aiot-document/开发者文档/02-Ops领域/01-工单生命周期与状态机.md

01-工单生命周期与状态机

工单（WorkOrder）是 Ops 领域的核心实体。本项目中的 Ops 不是传统的“手机 App 抢单”模式，而是深度整合硬件（智能工牌 BADGE、感知信标 BEACON）的物联网级调度系统。

一、核心状态流转图 (WorkOrderStatusEnum)

根据 WorkOrderStatusEnum.java，工单的完整状态流转如下：

stateDiagram-v2
    [*] --> PENDING : 生成工单(待分配)
    
    PENDING --> QUEUED : 进入派单队列(保洁特有)
    PENDING --> DISPATCHED : 直接推送
    QUEUED --> DISPATCHED : 推送到智能工牌(已推送)
    
    DISPATCHED --> CONFIRMED : 员工按键确认(已确认)
    DISPATCHED --> CANCELLED : 调度超时/撤回
    
    CONFIRMED --> ARRIVED : 徽章感应到信标(已到岗)
    CONFIRMED --> PAUSED : 临时暂停
    
    ARRIVED --> COMPLETED : 作业完成或丢失信号(已完成)
    ARRIVED --> PAUSED : 临时暂停
    
    PAUSED --> ARRIVED : 恢复作业
    PAUSED --> CONFIRMED : 恢复作业(信标未感知)
    
    PENDING --> CANCELLED : 取消
    CONFIRMED --> CANCELLED : 取消
    
    COMPLETED --> [*]
    CANCELLED --> [*]

二、状态说明与底层硬件联动

在本项目中，工单状态的变化直接对应了物理硬件的事件 (EventDomainEnum)。

状态码 (status)	状态描述	触发源与硬件联动逻辑
PENDING	待分配	规则引擎(RULE)、客服等触发生成工单。
QUEUED	排队中	保洁特有：已推荐保洁员，在队列中等待推送。
DISPATCHED	已推送	调度器(DISPATCH)将指令下发到智能工牌(BADGE)。工牌可能震动或亮起。
CONFIRMED	已确认	保洁员在智能工牌上按下确认按钮。此时触发状态流转。
ARRIVED	已到岗	核心特性：员工到达现场，工牌扫描/感应到现场的感知信标(BEACON)，自动流转为作业中。
PAUSED	已暂停	员工临时离开信标区域或主动暂停。
COMPLETED	已完成	作业完成（可通过工牌按键或离开信标一定时间自动结算）。
CANCELLED	已取消	中途取消（可随时发起，除终态外）。

三、业务判断约束 (代码级)

所有状态跃迁受限于枚举类中的硬性校验：

1. isCleaningBusinessStatus()：QUEUED、DISPATCHED、CONFIRMED 属于保洁业务强相关的分发状态。
2. canConfirm()：只有处于 DISPATCHED（已推送）状态的工单，才允许保洁员进行硬件按键确认。
3. canStartWorking()：CONFIRMED 或 DISPATCHED 状态下，一旦感应到信标，都可以开始作业（兼容特殊直接到场场景）。
4. canComplete()：必须先达到 ARRIVED（已到岗）状态，才允许扭转为 COMPLETED。

这保证了员工**必须亲自到达物理现场（信标打卡）**才能完成工单，杜绝了远程虚假完工。