工单状态流转规则

适用于物业报修、维修服务、现场工单的状态机与权限控制场景。

规则文件内容

请复制以下内容，保存为 .cursor/rules/workorder-state-machine.mdc：

---
description: 工单状态机、角色权限与回退重派业务规则
globs: src/modules/workorders/**, src/modules/workflow/**, src/modules/notifications/**
---

# 工单状态流转业务规则

## 1. 核心原则
- **状态机约束**：工单必须按定义状态流转，不允许跳步。
- **角色可控**：每个状态变更都必须校验操作角色权限。
- **闭环可追踪**：每次状态变更写入日志并触发必要通知。

## 2. 状态定义
- `pending_accept`：待受理
- `pending_dispatch`：待派单
- `pending_pickup`：待接单
- `pending_arrival`：待到达
- `in_progress`：处理中
- `pending_confirm`：待确认
- `completed`：已完成
- `rejected`：已拒绝
- `cancelled`：已取消

## 3. 状态流转规则
- `pending_accept -> pending_dispatch`
- `pending_dispatch -> pending_pickup`
- `pending_pickup -> pending_arrival`
- `pending_arrival -> in_progress`
- `in_progress -> pending_confirm`
- `pending_confirm -> completed`
- `pending_confirm -> pending_dispatch`（不满意重派）
- 任意处理中状态可流转到 `cancelled`（具备权限时）

```ts
type WorkorderStatus =
  | 'pending_accept'
  | 'pending_dispatch'
  | 'pending_pickup'
  | 'pending_arrival'
  | 'in_progress'
  | 'pending_confirm'
  | 'completed'
  | 'rejected'
  | 'cancelled';

const ALLOWED_TRANSITIONS: Record<WorkorderStatus, WorkorderStatus[]> = {
  pending_accept: ['pending_dispatch', 'rejected', 'cancelled'],
  pending_dispatch: ['pending_pickup', 'cancelled'],
  pending_pickup: ['pending_arrival', 'cancelled'],
  pending_arrival: ['in_progress', 'cancelled'],
  in_progress: ['pending_confirm', 'cancelled'],
  pending_confirm: ['completed', 'pending_dispatch', 'cancelled'],
  completed: [],
  rejected: [],
  cancelled: []
};

4. 角色权限规则

• 客服：pending_accept, pending_dispatch, cancelled
• 维修人员：pending_pickup, pending_arrival, in_progress, pending_confirm
• 业主/报修人：completed（确认）或触发 pending_dispatch（不满意）
• 管理员：可执行任何合法流转

5. 超时与回退规则

• pending_pickup 超过 15 分钟未接单：自动回退 pending_dispatch
• pending_arrival 超过 SLA 未到场：标记超时并通知调度员
• pending_confirm 超过 24 小时未确认：自动完结或升级人工确认（按策略）

6. 通知规则

• 每次状态变更触发对应角色通知。
• 关键状态（重派、取消、完成）必须发送多渠道通知。

7. 数据模型约束

• workorders 必须包含：status, priority, assigned_worker_id, sla_deadline
• workorder_state_logs 必须包含：workorder_id, from_status, to_status, operator_id, changed_at
• workorder_permissions 必须包含：role, allowed_actions, status_scope

8. 实施注意事项

• 状态流转建议使用事务保证原子性。
• 需要防并发重复流转，建议使用版本号或乐观锁。
• 状态机规则建议配置化，便于不同项目复用。

## 适用场景

- 物业报修工单
- 维修服务工单
- 现场服务流程管理