# 前端开发规范

## 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. **服务监控**: 定期检查服务状态，确保所有服务正常运行