# 跨域业务流程 - 详细设计

**文档类型**: 详细设计文档
**生成日期**: 2026-05-18
**数据来源**: REVERSE-FINANCE.md + REVERSE-AUTH.md + 路由/API层源码 + 后端实体分析

---

## 一、业主报修全流程

### 1.1 流程概述

业主报修是Ether系统中最核心的跨域业务流程，涉及从业主发起报修到最终评价的完整生命周期：

**业主提交报修 -> 系统创建工单 -> 调度派单 -> 维保人员执行 -> 业主验收 -> 评价反馈**

### 1.2 涉及域和功能点

| 步骤 | 涉及域 | 功能点 | API端点 |
|------|--------|--------|---------|
| 1. 业主身份识别 | 认证域 | 业主登录、Token验证 | `POST /api/auth/login` |
| 2. 项目/空间定位 | 空间域 | 获取业主关联房产 | `GET /api/mdm/space-nodes/project/{projectId}/tree` |
| 3. 设备关联（可选） | 设备域 | 按空间查询设备 | `GET /api/asset/equipment/by-space/{spaceNodeId}` |
| 4. 创建工单 | 运营域 | 创建报修工单 | `POST /api/wo/work-orders` |
| 5. 工单派发 | 运营域 | 指派维保人员 | `POST /api/wo/work-orders/{id}/assign` |
| 6. 开始执行 | 运营域 | 维保人员接单 | `POST /api/wo/work-orders/{id}/start` |
| 7. 完成工单 | 运营域 | 填写处理结果 | `POST /api/wo/work-orders/{id}/complete` |
| 8. 业主验收 | 运营域 | 确认维修结果 | `POST /api/wo/work-orders/{id}/verify` |
| 9. 评价反馈 | 运营域 | 评分评价 | `POST /api/wo/work-orders/{id}/verify` (含rating) |
| 10. 备件消耗 | 备件域 | 出库记录 | `POST /api/ops/spare-parts/out-stock` |
| 11. 审计记录 | 认证域 | 操作日志 | 自动记录（AOP） |

### 1.3 数据流图

```mermaid
flowchart TD
    A[业主登录] -->|POST /api/auth/login| B[获取Token+角色]
    B --> C[选择项目/房产]
    C -->|GET /api/mdm/space-nodes/project/id/tree| D[加载空间树]
    D --> E{是否关联设备?}
    E -->|是| F[选择设备]
    F -->|GET /api/asset/equipment/by-space/spaceNodeId| G[设备列表]
    E -->|否| H[直接描述问题]
    G --> I[填写报修信息]
    H --> I
    I -->|POST /api/wo/work-orders| J[工单创建 PENDING]
    J -->|POST /api/wo/work-orders/id/assign| K[派发 ASSIGNED]
    K -->|POST /api/wo/work-orders/id/start| L[执行中 IN_PROGRESS]
    L --> M{是否需要备件?}
    M -->|是| N[备件出库]
    N -->|POST /api/ops/spare-parts/out-stock| O[更新库存]
    M -->|否| P[填写处理结果]
    O --> P
    P -->|POST /api/wo/work-orders/id/complete| Q[已完成 COMPLETED]
    Q -->|POST /api/wo/work-orders/id/verify| R[已验收 VERIFIED]
    R --> S[评价评分]

    style A fill:#e1f5fe
    style J fill:#fff3e0
    style K fill:#e3f2fd
    style L fill:#fff8e1
    style Q fill:#e8f5e9
    style R fill:#e0f7fa
```

### 1.4 状态流转图

```mermaid
stateDiagram-v2
    [*] --> PENDING: 业主提交报修
    PENDING --> ASSIGNED: 管理员派单
    PENDING --> CANCELLED: 业主取消
    ASSIGNED --> IN_PROGRESS: 维保人员开始执行
    ASSIGNED --> PENDING: 退回重派
    ASSIGNED --> CANCELLED: 管理员取消
    IN_PROGRESS --> SUSPENDED: 挂起（缺件/等审批）
    IN_PROGRESS --> RETURNED: 退回（无法处理）
    IN_PROGRESS --> COMPLETED: 填写处理结果
    SUSPENDED --> IN_PROGRESS: 恢复执行
    RETURNED --> ASSIGNED: 重新派单
    COMPLETED --> VERIFIED: 业主验收通过
    COMPLETED --> IN_PROGRESS: 验收不通过，返工
    VERIFIED --> [*]: 流程结束
    CANCELLED --> [*]: 流程结束
```

### 1.5 异常场景处理

| 异常场景 | 触发条件 | 处理策略 | 涉及API |
|---------|---------|---------|---------|
| 设备不存在 | 业主选择的设备ID在数据库中不存在 | 返回404错误，提示设备不存在，允许不关联设备提交 | `GET /api/asset/equipment/{id}` |
| 派单失败 | 指定的维保人员不存在或不可用 | 返回错误提示，管理员重新选择人员 | `POST /api/wo/work-orders/{id}/assign` |
| 执行超时 | 工单超过SLA时间未完成 | 系统自动标记超时，通知项目经理 | 定时任务检查 |
| 验收不通过 | 业主对维修结果不满意 | 工单回退到IN_PROGRESS，维保人员返工 | `POST /api/wo/work-orders/{id}/complete` -> 重新执行 |
| 备件缺货 | 维修所需备件库存不足 | 工单挂起SUSPENDED，等待备件入库 | `GET /api/ops/spare-parts/low-stock` |
| 业主取消 | 业主在派单前取消 | 工单状态变为CANCELLED | `POST /api/wo/work-orders/{id}/cancel` |
| 重复提交 | 业主短时间内重复提交相同报修 | 前端防抖 + 后端幂等校验 | `POST /api/wo/work-orders` |
| 维保人员退回 | 维保人员无法处理该工单 | 工单退回RETURNED，管理员重新派单 | `POST /api/wo/work-orders/{id}/return` |
| 工单挂起 | 执行中遇到阻塞（等审批/等配件） | 工单挂起SUSPENDED，解除后恢复 | `POST /api/wo/work-orders/{id}/suspend` |
| 业主未验收 | 完成后业主长时间未验收 | 超过7天自动验收通过 | 定时任务检查 |

### 1.6 权限控制

| 角色 | 可执行操作 | 数据范围 |
|------|-----------|---------|
| 业主(OWNER) | 创建工单、查看自己的工单、验收、评价 | 仅自己创建的工单（SELF） |
| 项目管理员(PROJECT_ADMIN) | 查看项目所有工单、派单、取消 | 本项目工单（PROJECT） |
| 维保人员(MAINTENANCE) | 查看分配给自己的工单、开始、完成、退回 | 分配给自己的工单（SELF） |
| 系统管理员(SYS_ADMIN) | 所有操作 | 全部数据（ALL） |

**权限校验点**:

```
创建工单: 业主只能为关联房产创建工单
派单: 仅项目管理员/系统管理员可派单
执行: 仅被指派的维保人员可开始/完成
验收: 仅工单创建者（业主）可验收
评价: 仅工单创建者（业主）可评价
```

---

## 二、设备全生命周期管理

### 2.1 流程概述

设备全生命周期管理覆盖设备从采购入库到最终报废的完整过程：

**采购登记 -> 安装调试 -> 正常运行 -> 定期维保 -> 巡检监控 -> 故障维修 -> 报废处置**

### 2.2 涉及域和功能点

| 步骤 | 涉及域 | 功能点 | API端点 |
|------|--------|--------|---------|
| 1. 设备采购登记 | 设备域 | 创建设备记录 | `POST /api/asset/equipment` |
| 2. 安装位置关联 | 空间域 | 关联空间节点 | `PUT /api/asset/equipment/{id}` (spaceNodeId) |
| 3. 扩展信息录入 | 设备域 | 电梯/暖通/消防等扩展 | `PUT /api/asset/equipment/{id}/elevator` 等 |
| 4. 照片/文档上传 | 设备域 | 照片和文档管理 | PhotoManager / DocumentManager |
| 5. 归属主体关联 | 设备域 | 设置归属类型和主体 | `GET /api/asset/ownership-entity` |
| 6. 正常运行监控 | 设备域 | 健康度计算 | `POST /api/asset/equipment-health/calculate` |
| 7. 定期维保 | 维保域 | 创建维保计划 | `POST /api/mdm/maintenance-plans` |
| 8. 维保执行 | 维保域 | 维保工单流转 | `POST /api/ops/maintenance-tasks/{id}/start` 等 |
| 9. 巡检监控 | 巡检域 | 巡检记录 | `POST /api/mdm/inspection-records` |
| 10. 故障维修 | 运营域 | 创建维修工单 | `POST /api/wo/work-orders` |
| 11. 健康度评估 | 设备域 | MTBF/MTTR分析 | `GET /api/asset/equipment-health/mtbf/{id}` |
| 12. 设备报废 | 设备域 | 更新设备状态 | `PUT /api/asset/equipment/{id}` (status=SCRAPPED) |

### 2.3 数据流图

```mermaid
flowchart TD
    A[设备采购] -->|POST /api/asset/equipment| B[设备登记]
    B --> C[安装调试]
    C -->|PUT /api/asset/equipment/id + spaceNodeId| D[关联空间位置]
    D -->|PUT /api/asset/equipment/id/elevator| E[录入扩展信息]
    E --> F[正常运行]
    F -->|POST /api/asset/equipment-health/calculate| G[健康度评估]
    G --> H{设备状态判断}
    H -->|健康| I[定期维保]
    H -->|预警| J[加强巡检]
    H -->|异常| K[故障维修]

    I -->|POST /api/mdm/maintenance-plans| L[创建维保计划]
    L -->|定时任务| M[生成维保工单]
    M -->|POST /api/ops/maintenance-tasks/id/start| N[执行维保]
    N -->|POST /api/ops/maintenance-tasks/id/complete| O[维保完成]
    O --> F

    J -->|POST /api/mdm/inspection-records| P[巡检记录]
    P --> Q{发现异常?}
    Q -->|是| K
    Q -->|否| F

    K -->|POST /api/wo/work-orders| R[创建维修工单]
    R -->|POST /api/wo/work-orders/id/complete| S[维修完成]
    S -->|POST /api/asset/equipment-health/calculate| T[重新评估健康度]
    T --> H

    F --> U{达到报废条件?}
    U -->|是| V[设备报废]
    U -->|否| I
    V -->|PUT /api/asset/equipment/id status=SCRAPPED| W[报废处置]

    style F fill:#e8f5e9
    style K fill:#ffebee
    style V fill:#f3e5f5
```

### 2.4 状态流转图

```mermaid
stateDiagram-v2
    [*] --> PURCHASED: 采购登记
    PURCHASED --> INSTALLING: 安装调试
    INSTALLING --> COMMISSIONING: 调试验收
    COMMISSIONING --> RUNNING: 验收通过
    COMMISSIONING --> INSTALLING: 验收不通过
    RUNNING --> MAINTENANCE: 定期维保
    RUNNING --> INSPECTION: 巡检监控
    RUNNING --> FAULT: 故障发生
    MAINTENANCE --> RUNNING: 维保完成
    INSPECTION --> RUNNING: 巡检正常
    INSPECTION --> FAULT: 巡检发现异常
    FAULT --> REPAIRING: 维修中
    REPAIRING --> RUNNING: 维修完成
    REPAIRING --> SCRAPPED: 无法修复
    RUNNING --> SCRAPPED: 达到使用年限
    RUNNING --> SCRAPPED: 经济性报废
    SCRAPPED --> [*]
```

### 2.5 异常场景处理

| 异常场景 | 触发条件 | 处理策略 |
|---------|---------|---------|
| 设备重复登记 | 相同序列号/资产编码已存在 | 后端校验唯一性，返回409冲突 |
| 安装位置冲突 | 同一空间节点已有同类型设备 | 允许同空间多设备，但给出提示 |
| 维保计划冲突 | 同一设备存在重叠的维保计划 | 校验计划周期不重叠 |
| 健康度计算失败 | 设备缺少历史数据 | 返回默认健康度，标记为"数据不足" |
| 维修无法修复 | 多次维修后仍故障 | 建议报废，升级审批流程 |
| 备件不兼容 | 维修使用的备件与设备不匹配 | 备件选择时按设备类型筛选 |
| 巡检数据异常 | 巡检结果与设备状态不符 | 标记为"需复核"，触发二次巡检 |
| 报废审批 | 高价值设备报废 | 需项目经理审批确认 |

### 2.6 权限控制

| 角色 | 可执行操作 | 数据范围 |
|------|-----------|---------|
| 系统管理员(SYS_ADMIN) | 设备全生命周期操作 | ALL |
| 项目管理员(PROJECT_ADMIN) | 本项目设备管理 | PROJECT |
| 工程人员(ENGINEERING) | 设备登记、维保、巡检 | PROJECT + DEPARTMENT |
| 维保人员(MAINTENANCE) | 执行维保工单 | SELF（分配给自己的） |
| 业主(OWNER) | 查看关联设备信息 | SELF（关联房产的设备） |

---

## 三、预防性维保调度流程

### 3.1 流程概述

预防性维保调度是基于维保计划自动生成维保工单的定时调度流程：

**创建维保计划 -> 定时调度检查 -> 自动生成维保工单 -> 派单执行 -> 验收 -> 更新设备记录**

### 3.2 涉及域和功能点

| 步骤 | 涉及域 | 功能点 | API端点 |
|------|--------|--------|---------|
| 1. 创建维保计划 | 维保域 | 设置设备、周期、维保内容 | `POST /api/mdm/maintenance-plans` |
| 2. 定时调度检查 | 维保域 | MaintenanceScheduler检查到期计划 | 定时任务（Cron） |
| 3. 自动生成工单 | 运营域 | 根据计划创建维保工单 | `POST /api/ops/maintenance-tasks` |
| 4. 自动派单 | 运营域 | 按计划指定维保人员/供应商 | `POST /api/ops/maintenance-tasks/{id}/assign` |
| 5. 执行维保 | 运营域 | 维保人员执行 | `POST /api/ops/maintenance-tasks/{id}/start` |
| 6. 记录备件消耗 | 备件域 | 出库记录 | `POST /api/ops/spare-parts/out-stock` |
| 7. 完成维保 | 运营域 | 填写维保结果 | `POST /api/ops/maintenance-tasks/{id}/complete-details` |
| 8. 验收 | 运营域 | 验收确认 | `POST /api/ops/maintenance-tasks/{id}/verify` |
| 9. 更新计划 | 维保域 | 更新lastDate和nextDate | `PUT /api/mdm/maintenance-plans/{id}` |
| 10. 更新设备 | 设备域 | 更新设备维保信息 | `PUT /api/asset/equipment/{id}` |

### 3.3 数据流图

```mermaid
flowchart TD
    A[管理员创建维保计划] -->|POST /api/mdm/maintenance-plans| B[计划存储 ACTIVE]
    B --> C{MaintenanceScheduler}
    C -->|每天凌晨检查| D{nextDate <= 今天?}
    D -->|是| E{计划状态=ACTIVE?}
    D -->|否| C
    E -->|是| F[自动生成维保工单]
    E -->|否| C
    F -->|POST /api/ops/maintenance-tasks| G[工单 PENDING]
    G -->|POST /api/ops/maintenance-tasks/id/assign| H[派发 ASSIGNED]
    H -->|POST /api/ops/maintenance-tasks/id/start| I[执行中 IN_PROGRESS]
    I --> J{需要备件?}
    J -->|是| K[备件出库]
    K -->|POST /api/ops/spare-parts/out-stock| L[更新库存]
    J -->|否| M[填写维保结果]
    L --> M
    M -->|POST /api/ops/maintenance-tasks/id/complete-details| N[已完成 COMPLETED]
    N -->|POST /api/ops/maintenance-tasks/id/verify| O[已验收 VERIFIED]
    O -->|PUT /api/mdm/maintenance-plans/id| P[更新计划lastDate/nextDate]
    P -->|PUT /api/asset/equipment/id| Q[更新设备维保信息]
    Q --> C

    style C fill:#fff3e0
    style F fill:#e3f2fd
    style O fill:#e0f7fa
```

### 3.4 定时调度设计（MaintenanceScheduler）

**调度器配置**:

| 配置项 | 值 | 说明 |
|--------|-----|------|
| Cron表达式 | `0 0 6 * * ?` | 每天凌晨6点执行 |
| 检查范围 | 所有ACTIVE状态的维保计划 | nextDate <= 当天 |
| 生成策略 | 每个到期计划生成一个维保工单 | triggerType = PLAN |
| 防重复 | 检查同一计划+同一天是否已生成工单 | 避免重复生成 |
| 通知 | 生成工单后通知项目管理员 | 待实现 |

**调度逻辑伪代码**:

```
MaintenanceScheduler.execute():
  1. 查询所有 ACTIVE 状态的维保计划
  2. 过滤 nextDate <= 今天 的计划
  3. 对每个到期计划:
     a. 检查是否已生成工单（planId + 当天日期）
     b. 若未生成，创建维保工单:
        - taskType = PREVENTIVE
        - triggerType = PLAN
        - equipmentId = plan.equipmentId
        - title = "预防性维护: " + plan.planName
        - assignedVendor = plan.assignedVendor
     c. 更新计划 lastDate = 今天, nextDate = 今天 + plan.cycleDays
  4. 发送通知给相关项目管理员
```

**nextDate计算规则**:

```
nextDate = lastDate + cycleDays
首次: nextDate = 创建日期 + cycleDays
完成后: nextDate = 实际完成日期 + cycleDays
```

### 3.5 异常场景处理

| 异常场景 | 触发条件 | 处理策略 |
|---------|---------|---------|
| 计划已暂停 | 计划状态为SUSPENDED | 跳过该计划，不生成工单 |
| 计划已停用 | 计划状态为INACTIVE | 跳过该计划，不生成工单 |
| 设备已报废 | 关联设备状态为SCRAPPED | 自动暂停计划，通知管理员 |
| 重复生成 | 同一计划同一天已生成工单 | 跳过，幂等处理 |
| 供应商不可用 | assignedVendor对应的供应商已失效 | 生成工单但不自动派单，通知管理员手动派单 |
| 备件不足 | 维保所需备件库存不足 | 工单挂起SUSPENDED，等待备件入库 |
| 维保超时 | 工单超过预估时间未完成 | 通知项目经理，标记超时 |
| 调度服务宕机 | 定时任务未执行 | 启动时补偿执行，检查遗漏的计划 |

### 3.6 权限控制

| 角色 | 可执行操作 | 数据范围 |
|------|-----------|---------|
| 系统管理员(SYS_ADMIN) | 创建/修改/删除维保计划 | ALL |
| 项目管理员(PROJECT_ADMIN) | 创建/修改本项目维保计划 | PROJECT |
| 工程人员(ENGINEERING) | 查看维保计划 | PROJECT |
| 维保人员(MAINTENANCE) | 执行分配的维保工单 | SELF |
| 外部供应商 | 执行指派的维保工单 | SELF（通过assignedVendor） |

---

## 四、巡检异常处理流程

### 4.1 流程概述

巡检异常处理流程描述巡检过程中发现异常后的上报和处理机制：

**巡检执行 -> 发现异常 -> 上报异常 -> 创建工单 -> 处理异常 -> 复检确认**

### 4.2 涉及域和功能点

| 步骤 | 涉及域 | 功能点 | API端点 |
|------|--------|--------|---------|
| 1. 加载巡检模板 | 巡检域 | 获取点检模板 | `GET /api/ops/inspection-templates?projectId=` |
| 2. 执行巡检 | 巡检域 | 创建巡检记录 | `POST /api/mdm/inspection-records` |
| 3. 记录巡检项 | 巡检域 | 逐项检查并记录 | InspectionRecordItem[] |
| 4. 发现异常 | 巡检域 | 标记异常项 + 问题描述 | problems[] + status=ABNORMAL |
| 5. 完成巡检 | 巡检域 | 提交巡检结果 | `POST /api/mdm/inspection-records/{id}/complete` |
| 6. 自动创建工单 | 运营域 | 根据异常自动创建工单 | `POST /api/wo/work-orders` |
| 7. 派单处理 | 运营域 | 指派维修人员 | `POST /api/wo/work-orders/{id}/assign` |
| 8. 维修执行 | 运营域 | 执行维修 | `POST /api/wo/work-orders/{id}/start` -> `complete` |
| 9. 复检 | 巡检域 | 对异常项进行复检 | `POST /api/mdm/inspection-records` (复检记录) |
| 10. 更新设备状态 | 设备域 | 更新设备运行状态 | `PUT /api/asset/equipment/{id}` |

### 4.3 数据流图

```mermaid
flowchart TD
    A[巡检人员选择设备] -->|GET /api/ops/inspection-templates| B[加载点检模板]
    B --> C[逐项检查]
    C --> D{检查结果}
    D -->|全部正常| E[标记NORMAL]
    D -->|部分预警| F[标记WARNING]
    D -->|发现异常| G[标记ABNORMAL]

    E -->|POST /api/mdm/inspection-records/id/complete| H[巡检完成]
    F --> H
    G --> I[记录异常详情]
    I -->|problems数组| J[提交巡检记录]
    J -->|POST /api/mdm/inspection-records/id/complete| K[巡检完成 ABNORMAL]

    K --> L{异常严重度}
    L -->|HIGH 严重| M[自动创建紧急工单]
    L -->|MEDIUM 中等| N[自动创建普通工单]
    L -->|LOW 轻微| O[记录待处理]

    M -->|POST /api/wo/work-orders priority=URGENT| P[工单 PENDING]
    N -->|POST /api/wo/work-orders priority=MEDIUM| P
    O --> Q[定期汇总处理]

    P -->|POST /api/wo/work-orders/id/assign| R[派发 ASSIGNED]
    R -->|POST /api/wo/work-orders/id/start| S[执行中 IN_PROGRESS]
    S -->|POST /api/wo/work-orders/id/complete| T[已完成 COMPLETED]
    T -->|POST /api/wo/work-orders/id/verify| U[已验收 VERIFIED]

    U --> V[复检]
    V -->|POST /api/mdm/inspection-records 复检记录| W{复检结果}
    W -->|通过| X[更新设备状态正常]
    W -->|不通过| Y[重新创建工单]
    X -->|PUT /api/asset/equipment/id| Z[流程结束]
    Y --> P

    style G fill:#ffebee
    style K fill:#fff3e0
    style M fill:#ffcdd2
    style X fill:#e8f5e9
```

### 4.4 异常场景处理

| 异常场景 | 触发条件 | 处理策略 |
|---------|---------|---------|
| 巡检模板缺失 | 设备类型无对应模板 | 允许自由录入巡检项，提示管理员创建模板 |
| 巡检中断 | 巡检过程中网络断开 | 本地暂存巡检数据，恢复后提交 |
| 异常误报 | 巡检人员误判为异常 | 复检时纠正，工单可取消 |
| 工单创建失败 | 自动创建工单时后端异常 | 巡检记录仍保存，手动创建工单 |
| 维修后复检不通过 | 异常未完全修复 | 重新创建工单，升级优先级 |
| 多次复检不通过 | 同一异常反复出现 | 标记为"顽固故障"，建议设备报废评估 |
| 巡检人员不足 | 无可用巡检人员 | 延迟巡检，通知项目经理 |
| 设备无法巡检 | 设备位置不可达或停机 | 记录原因，标记为"待巡检" |

### 4.5 权限控制

| 角色 | 可执行操作 | 数据范围 |
|------|-----------|---------|
| 巡检人员(INSPECTOR) | 执行巡检、记录异常 | SELF（分配给自己的巡检任务） |
| 项目管理员(PROJECT_ADMIN) | 查看巡检结果、派单处理 | PROJECT |
| 维保人员(MAINTENANCE) | 处理异常工单 | SELF（分配给自己的工单） |
| 系统管理员(SYS_ADMIN) | 管理巡检模板 | ALL |

---

## 五、能耗计费流程

### 5.1 流程概述

能耗计费流程覆盖从抄表到最终支付的完整计费链路，部分环节已实现：

**抄表录入 -> 消耗量计算 -> 费用计算 -> 账单生成 -> 催缴提醒 -> 支付 -> 滞纳金计算 [部分实现]**

### 5.2 涉及域和功能点

| 步骤 | 涉及域 | 功能点 | 实现状态 | API端点 |
|------|--------|--------|---------|---------|
| 1. 计量点管理 | MDM域 | 创建/管理计量点 | 已实现 | `POST/GET/PUT/DELETE /api/ops/energy/meters` |
| 2. 抄表录入 | MDM域 | 录入能耗读数 | 已实现 | `POST /api/ops/energy/consumption` |
| 3. 消耗量计算 | MDM域 | currentReading - previousReading | 已实现 | 自动计算 |
| 4. 费用计算 | MDM域 | consumption * unitPrice | 已实现 | 自动计算 |
| 5. 按类型统计 | MDM域 | 按能源类型汇总 | 已实现(有缺陷) | `GET /api/ops/energy/statistics/by-type` |
| 6. 单方能耗 | MDM域 | 项目总消耗/总面积 | 已实现 | `GET /api/ops/energy/statistics/unit-consumption` |
| 7. 收费项目配置 | 财务域 | 创建按用量计费的收费项目 | 未实现 | `POST /api/finance/fee-items` |
| 8. 账单生成 | 财务域 | 根据能耗数据生成账单 | 未实现 | `POST /api/finance/bills/generate` |
| 9. 催缴提醒 | 财务域 | 到期/逾期提醒 | 未实现 | 定时任务 |
| 10. 滞纳金计算 | 财务域 | 逾期天数 * 日利率 | 未实现 | 定时任务 |
| 11. 线下收款 | 财务域 | 登记支付 | 未实现 | `POST /api/finance/payments` |
| 12. 线上支付 | 财务域 | 微信/支付宝 | 未实现 | `POST /api/finance/payments/online/prepare` |
| 13. 退款 | 财务域 | 退款申请/审批/执行 | 未实现 | `POST /api/finance/refunds` |

### 5.3 数据流图

```mermaid
flowchart TD
    subgraph 已实现
        A[创建计量点] -->|POST /api/ops/energy/meters| B[EnergyMeter]
        B --> C[抄表录入]
        C -->|POST /api/ops/energy/consumption| D[EnergyConsumption]
        D -->|自动计算| E[consumption = current - previous]
        E -->|自动计算| F[amount = consumption * unitPrice]
        F --> G[能耗统计]
        G -->|GET /api/ops/energy/statistics/by-type| H[按类型汇总]
        G -->|GET /api/ops/energy/statistics/unit-consumption| I[单方能耗]
    end

    subgraph 未实现
        F --> J[收费项目配置]
        J -->|POST /api/finance/fee-items type=ELECTRICITY/WATER/GAS billingMethod=USAGE| K[FeeItem]
        K --> L[账单自动生成]
        L -->|POST /api/finance/bills/generate sourceType=AUTO sourceId=EnergyConsumption.id| M[FeeBill UNPAID]
        M --> N{到期提醒}
        N -->|到期前3天| O[发送提醒]
        N -->|逾期| P[计算滞纳金]
        P -->|lateFee = 逾期天数 * payableAmount * lateFeeRate| Q[更新滞纳金]
        M --> R[支付]
        R -->|线下| S[登记收款 POST /api/finance/payments]
        R -->|线上| T[发起支付 POST /api/finance/payments/online/prepare]
        S --> U[FeePayment SUCCESS]
        T --> V[等待回调]
        V --> U
        U --> W[更新账单状态 PAID]
        U --> X{需要退款?}
        X -->|是| Y[申请退款 POST /api/finance/refunds]
        Y --> Z[审批]
        Z --> AA[执行退款]
        X -->|否| AB[流程结束]
    end

    style A fill:#e8f5e9
    style B fill:#e8f5e9
    style C fill:#e8f5e9
    style D fill:#e8f5e9
    style E fill:#e8f5e9
    style F fill:#e8f5e9
    style G fill:#e8f5e9
    style H fill:#e8f5e9
    style I fill:#e8f5e9
    style J fill:#fff3e0
    style K fill:#fff3e0
    style L fill:#fff3e0
    style M fill:#fff3e0
    style N fill:#fff3e0
    style O fill:#fff3e0
    style P fill:#fff3e0
    style Q fill:#fff3e0
    style R fill:#fff3e0
    style S fill:#fff3e0
    style T fill:#fff3e0
    style U fill:#fff3e0
    style V fill:#fff3e0
    style W fill:#fff3e0
    style X fill:#fff3e0
    style Y fill:#fff3e0
    style Z fill:#fff3e0
    style AA fill:#fff3e0
    style AB fill:#fff3e0
```

### 5.4 异常场景处理

| 异常场景 | 触发条件 | 处理策略 | 实现状态 |
|---------|---------|---------|---------|
| 读数递减 | 当前读数小于上次读数 | 拒绝录入，返回错误码6103 | 已实现 |
| 仪表不存在 | meterId在数据库中不存在 | 拒绝录入，返回错误码6101 | 已实现 |
| 仪表已停用 | 仪表状态为INACTIVE | 拒绝录入，返回错误码6102 | 已实现 |
| 单价未设置 | meter.unitPrice为null | amount设为0 | 已实现 |
| 按类型统计错误 | 全部归入LIGHTING | 修复为按meter.energyType分项汇总 | 待修复 |
| 前后端枚举不一致 | 后端6种 vs 前端5种 | 统一枚举定义 | 待修复 |
| 能耗数据缺失 | 账期内无抄表记录 | 生成0元账单，标记"无抄表数据" | 未实现 |
| 业主无关联房产 | 生成账单时业主无房产 | 跳过该业主，记录日志 | 未实现 |
| 重复生成账单 | 同一收费项目+业主+账期 | 幂等校验，跳过已存在的账单 | 未实现 |
| 支付超时 | 线上支付未收到回调 | 对账任务检查，人工介入 | 未实现 |
| 滞纳金溢出 | 计算结果超过maxLateFee | 截断为maxLateFee上限 | 未实现 |
| 部分支付后退款 | 业主部分支付后申请退款 | 按支付记录逐笔退款 | 未实现 |

### 5.5 权限控制

| 角色 | 可执行操作 | 数据范围 |
|------|-----------|---------|
| 系统管理员(SYS_ADMIN) | 管理计量点、收费项目、账单 | ALL |
| 项目管理员(PROJECT_ADMIN) | 查看本项目能耗和账单 | PROJECT |
| 财务人员(FINANCE_STAFF) | 收费登记、账单管理 | PROJECT |
| 财务主管(FINANCE_SUPERVISOR) | 退款审批、财务报表 | PROJECT |
| 业主(OWNER) | 查看自己的账单、在线缴费 | SELF |
| 巡检/维保人员 | 抄表录入 | SELF（分配给自己的） |

**已实现的权限控制**:

- 计量点管理：无特定角色限制（仅要求已登录）
- 能耗录入：无特定角色限制（仅要求已登录）
- 能耗统计：无特定角色限制（仅要求已登录）

**待实现的权限控制**:

- 收费项目管理：finance:fee-item:* 权限
- 账单管理：finance:bill:* 权限
- 支付管理：finance:payment:* 权限
- 退款管理：finance:refund:* 权限
- 业主端：仅查看自己的账单和支付记录