# 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*
