373 lines
10 KiB
Markdown
373 lines
10 KiB
Markdown
# 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*
|