151 lines
4.7 KiB
Markdown
151 lines
4.7 KiB
Markdown
# 前端开发规范
|
||
|
||
## 1. 组件库规范
|
||
|
||
### 1.1 统一使用 Ant Design Vue
|
||
- **强制要求**: 所有页面必须使用 Ant Design Vue 组件
|
||
- **禁止**: 不得使用 Element Plus 或其他 UI 组件库
|
||
- **原因**: 项目只安装了 ant-design-vue，使用其他组件库会导致页面加载失败
|
||
|
||
### 1.2 常用组件对照表
|
||
| Element Plus | Ant Design Vue |
|
||
|-------------|----------------|
|
||
| el-card | a-card |
|
||
| el-table | a-table |
|
||
| el-button | a-button |
|
||
| el-form | a-form |
|
||
| el-input | a-input |
|
||
| el-select | a-select |
|
||
| el-dialog | a-modal |
|
||
| el-tree | a-tree |
|
||
| el-tag | a-tag |
|
||
| el-switch | a-switch |
|
||
| el-icon | @ant-design/icons-vue |
|
||
|
||
## 2. API 路径规范
|
||
|
||
### 2.1 统一前缀
|
||
- 所有后端 API 必须以 `/api/v1` 开头
|
||
- 网关路由配置为 `/api/v1/**`
|
||
|
||
### 2.2 模块路径规范
|
||
| 模块 | 前端 API 路径 | 后端 Controller 路径 |
|
||
|-----|-------------|-------------------|
|
||
| 项目管理 | /api/v1/mdm/projects | @RequestMapping("/api/v1/mdm/projects") |
|
||
| 设备管理 | /api/v1/mdm/equipments | @RequestMapping("/api/v1/mdm/equipments") |
|
||
| 访客管理 | /api/v1/mdm/visitors | @RequestMapping("/api/v1/mdm/visitors") |
|
||
| 巡检管理 | /api/v1/mdm/inspections | @RequestMapping("/api/v1/mdm/inspections") |
|
||
| 工单管理 | /api/v1/ops/work-orders | @RequestMapping("/api/v1/ops/work-orders") |
|
||
| 消息通知 | /api/v1/ops/notifications | @RequestMapping("/api/v1/ops/notifications") |
|
||
|
||
### 2.3 常见问题
|
||
- **问题**: 前端调用 `/api/v1/asset/equipments`，后端只有 `/api/v1/mdm/equipments`
|
||
- **解决**: 统一使用 `/api/v1/mdm` 前缀，避免模块间混淆
|
||
|
||
## 3. 依赖管理规范
|
||
|
||
### 3.1 新增依赖流程
|
||
1. 安装依赖: `npm install package-name --save`
|
||
2. 重启开发服务器: 必须重启才能识别新安装的包
|
||
3. 验证: 确保页面能正常加载
|
||
|
||
### 3.2 常用依赖
|
||
- 图表库: `echarts` (工单统计页面使用)
|
||
- 日期处理: `dayjs`
|
||
- 图标: `@ant-design/icons-vue`
|
||
|
||
## 4. 页面开发检查清单
|
||
|
||
### 4.1 开发前检查
|
||
- [ ] 确认使用的组件库是 Ant Design Vue
|
||
- [ ] 确认 API 路径与后端一致
|
||
- [ ] 确认所需的依赖已安装
|
||
|
||
### 4.2 开发后检查
|
||
- [ ] 页面能正常加载无报错
|
||
- [ ] API 调用返回 200
|
||
- [ ] Console 无错误信息
|
||
- [ ] 所有服务正常运行
|
||
|
||
## 5. 服务启动检查
|
||
|
||
### 5.1 服务端口
|
||
| 服务 | 端口 | 说明 |
|
||
|-----|-----|-----|
|
||
| ether-gateway | 8080 | API 网关 |
|
||
| ether-auth | 8081 | 认证服务 |
|
||
| ether-mdm | 8082 | 主数据管理 |
|
||
| ether-ops | 8083 | 运维服务 |
|
||
| ether-ui-admin | 5173 | 前端开发服务器 |
|
||
|
||
### 5.2 启动顺序
|
||
1. 启动后端服务（任意顺序）
|
||
2. 启动前端开发服务器
|
||
3. 验证所有服务正常运行
|
||
|
||
### 5.3 检查命令
|
||
```bash
|
||
# 检查服务状态
|
||
for port in 8080 8081 8082 8083; do
|
||
pid=$(lsof -ti:$port 2>/dev/null)
|
||
if [ -n "$pid" ]; then
|
||
echo "Port $port: Running"
|
||
else
|
||
echo "Port $port: NOT RUNNING"
|
||
fi
|
||
done
|
||
```
|
||
|
||
## 6. 问题解决方案记录
|
||
|
||
### 6.1 设备管理 404 错误
|
||
**问题**: 前端调用 `/api/v1/asset/equipments` 返回 404
|
||
**原因**: 设备管理页面错误地导入了 `api/asset/equipment` 而不是 `api/mdm/equipment`
|
||
**解决**: 修改导入路径
|
||
```typescript
|
||
// 错误
|
||
import { equipmentApi } from '../../../api/asset/equipment';
|
||
|
||
// 正确
|
||
import { equipmentApi } from '../../../api/mdm/equipment';
|
||
```
|
||
|
||
### 6.2 访客管理 404 错误
|
||
**问题**: 前端调用 `/api/v1/mdm/visitors/*` 返回 404
|
||
**原因**: 后端 `VisitorController` 使用 `/mdm/visitors` 路径，缺少 `/api/v1` 前缀
|
||
**解决**: 修改后端 Controller
|
||
```java
|
||
// 错误
|
||
@RequestMapping("/mdm/visitors")
|
||
|
||
// 正确
|
||
@RequestMapping("/api/v1/mdm/visitors")
|
||
```
|
||
|
||
### 6.3 工单统计 echarts 错误
|
||
**问题**: `Failed to resolve import "echarts"`
|
||
**原因**: 项目未安装 echarts 依赖
|
||
**解决**: 安装依赖并重启开发服务器
|
||
```bash
|
||
npm install echarts --save
|
||
# 必须重启开发服务器
|
||
```
|
||
|
||
### 6.4 角色管理组件错误
|
||
**问题**: 页面使用 Element Plus 组件导致加载失败
|
||
**原因**: 项目只安装了 Ant Design Vue
|
||
**解决**: 将 Element Plus 组件替换为 Ant Design Vue 组件
|
||
|
||
### 6.5 巡检管理 404 错误
|
||
**问题**: 前端调用 `/api/v1/mdm/inspections/*` 返回 404
|
||
**原因**: 后端 `InspectionController` 缺少 `/api/v1` 前缀
|
||
**解决**: 修改后端 Controller 路径
|
||
|
||
## 7. 最佳实践
|
||
|
||
1. **前后端路径保持一致**: 开发前确认 API 路径，避免路径不匹配
|
||
2. **统一技术栈**: 使用项目已安装的组件库和依赖
|
||
3. **及时测试**: 开发完成后立即测试，发现问题及时修复
|
||
4. **记录问题**: 将遇到的问题和解决方案记录到本文档
|
||
5. **服务监控**: 定期检查服务状态，确保所有服务正常运行
|