ether-docs/02-DESIGN/detail/DETAIL-CROSS-DOMAIN.md

跨域业务流程 - 详细设计

文档类型: 详细设计文档 生成日期: 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 数据流图

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 状态流转图

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 数据流图

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 状态流转图

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 数据流图

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 数据流图

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 数据流图

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:* 权限
• 业主端：仅查看自己的账单和支付记录