work-order-lifecycle.md 7.8 KB
统一工单处置生命周期（七态共识）
状态：accepted（跨后端 pipe-ner-server、前端 city-life-line、UE 驾驶舱 Pipelines 的统一领域共识）
确立日期：2026-09-04（状态编码 2026-09-05 调整为从 1 开始）
决策依据：ADR-0008 工单生命周期收敛为七态
取代口径：旧“九态模型”（含“已驳回”终态、“延期审核/已延期”），以及 ADR-0004 中“驳回、延期日志语义”的旧表述。
本文只定义领域流程共识（状态、角色、迁移动作、证据与边界），不规定具体类、接口或 SQL。后端代码与存量数据当前仍是旧编码，编码迁移另开任务，在迁移完成前以本文状态名为唯一业务权威，编码以对照表换算。
1. 角色
- 管理员（派单/验收者）：派单下发、验收（审核通过 / 验收驳回 / 取消工单）。可在任意中间态取消工单。
- 接单责任人：接单确认、开始处置、多次追加处理流水、提交审核。一次派发指定唯一接单责任人。
- 运行系统/设备：产生设备预警、报警，是工单的来源之一，但不参与工单状态决策。
2. 进入流程的两条入口
- 报警转工单：由设备预警/报警创建工单，进入“待派单”，创建时不指定责任人。
- 直接下派：巡检工单、维修工单等可在创建时直接派给责任人，跳过“待派单”，直接进入“待接单”。
3. 七个状态（目标权威模型）
状态编码从 1 开始：
| 目标编码 | 状态 | 含义 | 是否终态 |
|---|---|---|---|
| 1 | 待派单 | 已创建、尚未指定接单责任人，等待管理员派单 | 否 |
| 2 | 待接单 | 已派给责任人，等待责任人接单确认 | 否 |
| 3 | 已接单 | 责任人已接单确认，尚未开始现场处置 | 否 |
| 4 | 处理中 | 责任人已开始处置；可多次追加处理流水 | 否 |
| 5 | 待验收 | 责任人已提交审核，等待管理员验收 | 否 |
| 6 | 已结案 | 管理员审核通过，处置闭环 | 是 |
| 7 | 已取消 | 管理员取消，强制终止；用于改派新责任人（另建新单） | 是 |
终态只有“已结案（6）”和“已取消（7）”。除两个终态外，其余均为中间态（1–5）。
4. 状态迁移（动作即事件）
| 动作 | 角色 | 前置态 | 目标态 | 必填信息 |
|---|---|---|---|---|
| 创建（报警转工单） | 系统/管理员 | — | 1 待派单 | 工单描述、来源报警/设备 |
| 直接下派（巡检/维修等） | 管理员 | — | 2 待接单 | 唯一责任人 |
| 派单/下发 | 管理员 | 1 | 2 待接单 | 唯一责任人 |
| 接单确认 | 责任人 | 2 | 3 已接单 | — |
| 开始处置 | 责任人 | 3 | 4 处理中 | 处理前照片 + 现场简述 |
| 追加处理流水 | 责任人 | 4 | 4 处理中（自循环，可多次） | 处理描述，可含图片 |
| 提交审核 | 责任人 | 4 | 5 待验收 | 处理后照片 + 处理描述 |
| 审核通过 | 管理员 | 5 | 6 已结案（终态） | 审核评价/建议 |
| 验收驳回 | 管理员 | 5 | 4 处理中（回退） | 驳回原因 |
| 取消工单 | 管理员 | 1/2/3/4/5 任一中间态 | 7 已取消（终态） | 建议填取消原因 |
约束：
- “已结案（6）”不可再取消、驳回或回退。
- “已取消（7）”是终态，不能复活；需要换责任人时，另建一张新工单重新派发。
- “验收驳回”只发生在“待验收（5）”，回到“处理中（4）”交同一责任人继续处理，可再次走“提交审核→待验收”。
状态机视图
stateDiagram-v2
[*] --> 待派单: 报警转工单创建
[*] --> 待接单: 巡检/维修直接下派
待派单 --> 待接单: 管理员派单
待接单 --> 已接单: 责任人接单确认
已接单 --> 处理中: 开始处置(处理前照片+简述)
处理中 --> 处理中: 追加处理流水(可多次)
处理中 --> 待验收: 提交审核(处理后照片+描述)
待验收 --> 处理中: 验收驳回(驳回原因)
待验收 --> 已结案: 审核通过(评价/建议)
待派单 --> 已取消: 管理员取消
待接单 --> 已取消: 管理员取消
已接单 --> 已取消: 管理员取消
处理中 --> 已取消: 管理员取消
待验收 --> 已取消: 管理员取消
已结案 --> [*]
已取消 --> [*]
5. “验收驳回”与“取消工单”的区别（重点，消除旧歧义）
- 验收驳回是一个动作而非状态：管理员对处置结果不满意时，把“待验收”工单退回“处理中”，由原责任人继续整改；工单不终止、不换单。
- 取消工单是一个迁到终态“已取消”的动作：用于不再继续本单（例如对该责任人处置不满、误报、停止处置）。取消后若仍需处置，应创建新工单并派给新责任人。
- 旧模型中“已驳回”是独立终态、且只允许在待派单/待接单驳回；该终态在七态模型中废止：未开始即终止的情形统一走“取消→已取消”，验收不通过统一走“驳回→回处理中”。
6. 处理流水与处置证据
处置证据按阶段区分，遵循 ADR-0006 工单附件存储（MinIO 对象 + KingbaseES 阶段化元数据，旧 URL 字段兼容）：
- 处理前证据：开始处置（3→4）时上传处理前照片与现场简述。
- 处理流水：处理中（4）可多次追加，每条可含图片与处理描述，并逐条写入工单操作日志，不改变状态。
- 处理后证据：提交审核（4→5）时上传处理后照片与处理描述。
- 验收意见：审核通过时记录评价/建议；验收驳回时记录驳回原因；取消时记录取消原因。
7. 与设备预警/报警的关系
- 工单来源于设备预警/报警，但工单状态独立于设备报警状态：工单结案/取消不直接清除报警；设备是否恢复由运行系统依据“有效报警原因”自动维护（见 ADR-0002）。
- 同一设备同一报警类型，同一时间只能存在一张未结束（非 6/7 终态）的同类工单；不同报警类型可分别建单。
- 一次维修同时消除其他异常属于“随同修复”，其他工单仍各自保留并完成验收，不静默结案。
8. 目标编码与现网接口编码（迁移期）
目标七态仍以 1–7 为权威。当前后端已出现两类并存契约：驾驶舱只读适配器输出目标 1–7；管理端 BusinessWorkOrderService 与供水设备详情仍读取数据库现网 0–7 编码，并保留 6-延期中 兼容分支。
| 状态名 | 目标编码（权威/驾驶舱只读） | 管理端现网编码 |
|---|---|---|
| 待派单 | 1 | 0 |
| 待接单 | 2 | 1 |
| 已接单 | 3 | 2 |
| 处理中 | 4 | 3 |
| 待验收 | 5 | 4 |
| 已结案 | 6 | 5 |
| 已取消 | 7 | 7 |
| — | 6（迁移期兼容） |
迁移期间调用方必须按接口契约解释编码并以状态名展示，不能跨接口复用裸数字。监测设备 GIS 只消费管理端关联工单摘要，不承担数据库状态迁移。后续迁移任务需把管理端状态编码对齐目标 1–7、删除延期兼容分支，并同步操作日志、前端和 UE 状态字典。
9. 本版明确删除/不纳入的内容
- 删除“已驳回”终态：驳回仅指“待验收→处理中”的回退动作。
- 删除延期相关状态：不再有“延期审核（旧 8）”“已延期（旧 9）”，工单主流程不含申请/审核延期环节；旧字段的下线随迁移任务处理。
- 不引入 Flowable 等外部工作流引擎，继续使用数据库状态机 + 事务服务（沿用 ADR-0004 中仍有效的部分）。