4.7 KiB

Raw Blame History

前端开发规范

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 新增依赖流程

安装依赖: npm install package-name --save
重启开发服务器: 必须重启才能识别新安装的包
验证: 确保页面能正常加载

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 启动顺序

启动后端服务（任意顺序）
启动前端开发服务器
验证所有服务正常运行

5.3 检查命令

# 检查服务状态
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 解决: 修改导入路径

// 错误
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

// 错误
@RequestMapping("/mdm/visitors")

// 正确
@RequestMapping("/api/v1/mdm/visitors")

6.3 工单统计 echarts 错误

问题: Failed to resolve import "echarts" 原因: 项目未安装 echarts 依赖解决: 安装依赖并重启开发服务器

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. 最佳实践

前后端路径保持一致: 开发前确认 API 路径，避免路径不匹配
统一技术栈: 使用项目已安装的组件库和依赖
及时测试: 开发完成后立即测试，发现问题及时修复
记录问题: 将遇到的问题和解决方案记录到本文档
服务监控: 定期检查服务状态，确保所有服务正常运行

4.7 KiB Raw Blame History Unescape Escape