# Ether 智慧物业管理平台 - 待开发功能完善规范 ## 📋 项目概述 本文档定义了待开发功能的详细实现规范，确保开发过程中不影响已完成的功能模块。 --- ## 🎯 开发目标 ### 总体目标 完善6个待开发功能模块，实现前后端完整对接，并通过E2E自动化测试验证。 ### 实际状态分析（更新后） | 模块 | 前端状态 | 后端状态 | API匹配 | 实际工作量 | |------|---------|---------|---------|-----------| | 设备管理 | ✅ 页面完整 | ⚠️ 占位接口 | ❌ 路径不匹配 | 中（需修复API路径+实现后端） | | 收费管理 | ✅ 页面完整 | ✅ 已完整实现 | ✅ 匹配 | 低（仅需启用前端API调用） | | 巡检管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | | 工单管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | | 访客管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | | 通知管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | --- ## 🚨 关键问题与解决方案 ### 问题1: 设备管理 API 路径不匹配 **现状**: - 前端 API: `/api/v1/asset/equipments` (api/asset/equipment.ts) - 后端 API: `/api/v1/mdm/equipments` (EquipmentController.java) **解决方案**: 在后端添加 `/api/v1/asset/equipments` 路径映射，保持前端不变。 ### 问题2: 设备表存在两个定义 **现状**: - `mdm_equipment` (V4迁移脚本) - `asset_equipment` (V9迁移脚本) **解决方案**: 统一使用 `mdm_equipment` 表，因为测试数据已使用该表。 ### 问题3: 收费管理前端显示"开发中" **现状**: - 后端 FeeController 已完整实现所有功能 - 前端代码注释显示"功能开发中"，API调用被禁用 **解决方案**: 移除前端"开发中"提示，启用API调用。 --- ## 📐 技术规范 ### 后端开发规范 #### 1. 服务端口分配 ``` ether-gateway: 8080 ether-auth: 8081 ether-mdm: 8082 ether-ops: 8083 ether-finance: 8085 ``` #### 2. API路径规范 ``` /api/v1/{module}/{resource} ``` - module: 模块名 (mdm, ops, finance, asset) - resource: 资源名 (复数形式) #### 3. 响应格式规范 ```json { "code": 200, "message": "success", "data": {} } ``` #### 4. 实体规范 - 所有实体使用UUID作为主键 - 必须包含 `createdAt` 和 `updatedAt` 字段 - 使用 `@PrePersist` 和 `@PreUpdate` 自动设置时间戳 #### 5. 数据库规范 - PostgreSQL 数据库 - 端口: 5432 - 用户名: ether - 密码: ether123 - 表名使用下划线命名法 (snake_case) ### 前端开发规范 #### 1. 组件命名 - 组件文件: kebab-case (如 `equipment-list.vue`) - 组件名称: PascalCase (如 `EquipmentList`) #### 2. API调用 - 统一使用 `@/api/` 目录下的API模块 - 使用 TypeScript 类型定义 #### 3. 状态管理 - 使用 Pinia 进行状态管理 - Store 文件放置在 `@/stores/` 目录 --- ## 🔧 功能模块详细规范 ### 1. 设备管理模块 (修复API路径 + 实现后端) #### 1.1 现有资源 **前端页面** (已存在): - `views/mdm/equipment/index.vue` - 设备列表页面（完整） - `views/asset/equipment-statistics/index.vue` - 设备统计页面 **数据库表** (已存在): - `mdm_equipment` - 设备主表 (V4迁移脚本已创建) **后端** (需完善): - `EquipmentController.java` - 仅有占位接口 #### 1.2 需要实现的内容 **后端实现**: 1. 创建设备实体类 - 文件: `ether-mdm/src/main/java/com/ether/mdm/entity/Equipment.java` - 映射表: `mdm_equipment` 2. 创建Repository - 文件: `ether-mdm/src/main/java/com/ether/mdm/repository/EquipmentRepository.java` 3. 创建Service - 文件: `ether-mdm/src/main/java/com/ether/mdm/service/EquipmentService.java` - 文件: `ether-mdm/src/main/java/com/ether/mdm/service/impl/EquipmentServiceImpl.java` 4. 完善Controller - 添加 `/api/v1/asset/equipments` 路径映射 - 实现完整CRUD接口 #### 1.3 API接口设计 **设备管理 API** (前端已定义，后端需实现): | 方法 | 前端调用路径 | 后端实现路径 | 描述 | |------|-------------|-------------|------| | GET | /api/v1/asset/equipments | 需映射 | 获取设备列表 | | GET | /api/v1/asset/equipments/{id} | 需映射 | 获取设备详情 | | POST | /api/v1/asset/equipments | 需映射 | 创建设备 | | PUT | /api/v1/asset/equipments/{id} | 需映射 | 更新设备 | | DELETE | /api/v1/asset/equipments/{id} | 需映射 | 删除设备 | | GET | /api/v1/asset/equipments/type/{type} | 需映射 | 按类型查询 | | GET | /api/v1/asset/equipments/status/{status} | 需映射 | 按状态查询 | | GET | /api/v1/asset/equipments/space-node/{spaceNodeId} | 需映射 | 按空间节点查询 | | GET | /api/v1/asset/equipments/search | 需映射 | 搜索设备 | | PATCH | /api/v1/asset/equipments/{id}/status | 需映射 | 更新设备状态 | | POST | /api/v1/asset/equipments/{id}/maintenance | 需映射 | 记录保养 | | GET | /api/v1/asset/equipments/generate-code | 需映射 | 生成设备编码 | | GET | /api/v1/asset/equipment/qrcode/{id} | 需映射 | 获取二维码 | | GET | /api/v1/asset/equipment/qrcode/info/{qrCode} | 需映射 | 扫码获取设备信息 | #### 1.4 数据库表结构 (已存在) ```sql -- mdm_equipment 表已存在于 V4 迁移脚本 CREATE TABLE mdm_equipment ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), project_id UUID NOT NULL, code VARCHAR(50) NOT NULL, name VARCHAR(100) NOT NULL, equipment_type VARCHAR(20) NOT NULL, status VARCHAR(20) NOT NULL DEFAULT 'NORMAL', brand VARCHAR(50), model VARCHAR(50), specifications VARCHAR(500), serial_number VARCHAR(100), manufacturer VARCHAR(100), supplier VARCHAR(100), space_node_id UUID, location_desc VARCHAR(200), purchase_date DATE, install_date DATE, warranty_date DATE, purchase_price NUMERIC(12, 2), service_life INTEGER, maintenance_cycle INTEGER, last_maintenance_date DATE, next_maintenance_date DATE, manager_id UUID, manager_name VARCHAR(50), contact_phone VARCHAR(20), images VARCHAR(1000), manual_url VARCHAR(255), remarks VARCHAR(500), attributes JSONB, created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, created_by UUID, updated_by UUID, CONSTRAINT uk_equipment_project_code UNIQUE (project_id, code) ); ``` --- ### 2. 收费管理模块 (启用前端API调用) #### 2.1 现有资源 **前端页面** (已存在): - `views/mdm/fee/index.vue` - 收费管理页面（完整） **后端** (已完整实现): - `FeeController.java` - 完整的CRUD接口 - `FeeService.java` - 完整的业务逻辑 #### 2.2 需要修改的内容 **前端修改**: 1. 移除"功能开发中"提示 - 文件: `views/mdm/fee/index.vue` - 删除 `showFeatureTip` 相关代码 2. 启用API调用 - 文件: `views/mdm/fee/index.vue` - 在 `fetchBills`、`fetchStatistics` 等方法中启用API调用 #### 2.3 后端已实现的API | 方法 | 路径 | 描述 | |------|------|------| | GET | /api/v1/finance/fee-items | 获取收费项目列表 | | POST | /api/v1/finance/fee-items | 创建收费项目 | | PUT | /api/v1/finance/fee-items/{id} | 更新收费项目 | | DELETE | /api/v1/finance/fee-items/{id} | 删除收费项目 | | GET | /api/v1/finance/bills | 获取账单列表 | | POST | /api/v1/finance/bills | 创建账单 | | PUT | /api/v1/finance/bills/{id} | 更新账单 | | DELETE | /api/v1/finance/bills/{id} | 删除账单 | | POST | /api/v1/finance/bills/{billId}/pay | 缴费 | | GET | /api/v1/finance/payments | 获取支付记录 | | GET | /api/v1/finance/statistics | 统计数据 | | GET | /api/v1/finance/statistics/today-receivable | 今日应收 | | GET | /api/v1/finance/statistics/today-received | 今日实收 | | GET | /api/v1/finance/statistics/pending-amount | 待收金额 | | GET | /api/v1/finance/statistics/overdue-amount | 逾期金额 | --- ### 3. 巡检管理模块 (联调测试) #### 3.1 现有资源 - 前端页面: ✅ 完整 - 后端API: ✅ 完整 - API匹配: ✅ 正确 #### 3.2 验证要点 - 巡检计划CRUD - 巡检点管理 - 巡检任务生成与执行 - 巡检记录提交 - 统计数据准确性 --- ### 4. 工单管理模块 (联调测试) #### 4.1 现有资源 - 前端页面: ✅ 完整（含组件和单元测试） - 后端API: ✅ 完整 - API匹配: ✅ 正确 #### 4.2 验证要点 - 工单创建流程 - 工单分配与接单 - 工单状态流转 - 工单完成与关闭 - 工单统计 --- ### 5. 访客管理模块 (联调测试) #### 5.1 现有资源 - 前端页面: ✅ 完整 - 后端API: ✅ 完整 - API匹配: ✅ 正确 #### 5.2 验证要点 - 访客预约流程 - 审批流程 - 入场/离场登记 - 黑名单管理 - 历史访客查询 --- ### 6. 通知管理模块 (联调测试) #### 6.1 现有资源 - 前端页面: ✅ 完整 - 后端API: ✅ 完整 - API匹配: ✅ 正确 #### 6.2 验证要点 - 通知渠道配置 - 通知模板管理 - 通知规则配置 - 通知发送与接收 - 通知状态管理 --- ## 🧪 测试规范 ### E2E测试策略 #### 测试工具 - Puppeteer 浏览器自动化 - 测试脚本目录: `tests/` #### 测试覆盖范围 1. 设备管理完整流程测试 2. 收费管理完整流程测试 3. 巡检管理流程测试 4. 工单管理流程测试 5. 访客管理流程测试 6. 通知管理流程测试 --- ## 🚀 部署规范 ### 服务启动顺序 1. PostgreSQL 数据库 2. ether-auth (8081) 3. ether-mdm (8082) 4. ether-ops (8083) 5. ether-finance (8085) 6. ether-gateway (8080) 7. ether-ui-admin (5175) --- ## 📝 开发注意事项 ### 不影响现有功能的措施 1. 所有新代码在独立分支开发 2. 新增数据库表使用新的命名空间 3. API版本控制，不修改现有API签名 4. 前端新增页面和组件，不修改现有页面 5. 完整的回归测试 ### 代码审查要点 1. 遵循项目代码规范 2. 添加必要的单元测试 3. 更新相关文档 4. 确保无安全漏洞 --- *最后更新: 2026-02-20*