10 KiB

Raw Blame History

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. 响应格式规范

{
  "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 需要实现的内容

后端实现:

创建设备实体类
- 文件: ether-mdm/src/main/java/com/ether/mdm/entity/Equipment.java
- 映射表: mdm_equipment
创建Repository
- 文件: ether-mdm/src/main/java/com/ether/mdm/repository/EquipmentRepository.java
创建Service
- 文件: ether-mdm/src/main/java/com/ether/mdm/service/EquipmentService.java
- 文件: ether-mdm/src/main/java/com/ether/mdm/service/impl/EquipmentServiceImpl.java
完善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 数据库表结构 (已存在)

-- 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 需要修改的内容

前端修改:

移除"功能开发中"提示
- 文件: views/mdm/fee/index.vue
- 删除 showFeatureTip 相关代码
启用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/

测试覆盖范围

设备管理完整流程测试
收费管理完整流程测试
巡检管理流程测试
工单管理流程测试
访客管理流程测试
通知管理流程测试

🚀 部署规范

服务启动顺序

PostgreSQL 数据库
ether-auth (8081)
ether-mdm (8082)
ether-ops (8083)
ether-finance (8085)
ether-gateway (8080)
ether-ui-admin (5175)

📝 开发注意事项

不影响现有功能的措施

所有新代码在独立分支开发
新增数据库表使用新的命名空间
API版本控制，不修改现有API签名
前端新增页面和组件，不修改现有页面
完整的回归测试

代码审查要点

遵循项目代码规范
添加必要的单元测试
更新相关文档
确保无安全漏洞

最后更新: 2026-02-20

10 KiB Raw Blame History Unescape Escape