579 lines
26 KiB
Markdown
579 lines
26 KiB
Markdown
# 跨域业务流程 - 详细设计
|
||
|
||
**文档类型**: 详细设计文档
|
||
**生成日期**: 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:* 权限
|
||
- 业主端：仅查看自己的账单和支付记录
|