# 模块 3：工单状态流转规则实现

<div class="mt-6 text-sm">

工单状态不能靠临时 if else。必须先设计状态机，再实现接口和校验。

</div>

<div class="flex items-center justify-between mt-12 px-4 text-sm">
<div class="text-center flex-1">created<br/><span class="text-xs text-gray-400">已创建</span></div>
<div class="text-blue-400">→</div>
<div class="text-center flex-1">processing<br/><span class="text-xs text-gray-400">处理中</span></div>
<div class="text-blue-400">→</div>
<div class="text-center flex-1">pending_verify<br/><span class="text-xs text-gray-400">待验证</span></div>
<div class="text-blue-400">→</div>
<div class="text-center flex-1">closed<br/><span class="text-xs text-gray-400">已关闭</span></div>
</div>

<div class="mt-8 text-center text-sm text-red-400">pending_verify → rejected → processing</div>

<!--
状态流转是第四天的核心复杂业务。
状态值要稳定，中文名可以展示，但代码里要使用明确枚举或字典。
-->

---

# 状态流转表

<div class="mt-5 text-xs">

| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 失败提示 |
|---|---|---|---|---|---|
| created | 指派 | processing | 管理员/负责人 | 必须选择指派人 | 请选择指派人 |
| processing | 提交验证 | pending_verify | 研发/负责人 | 必须填写处理说明 | 请填写处理说明 |
| pending_verify | 关闭 | closed | 测试/负责人 | 验证通过 | 当前工单不可关闭 |
| pending_verify | 驳回 | rejected | 测试/负责人 | 必须填写驳回原因 | 请填写驳回原因 |
| rejected | 重新处理 | processing | 研发/负责人 | 必须填写处理说明 | 请填写重新处理说明 |

</div>

<!--
状态流转表要回答当前状态、动作、目标状态、角色、前置条件和失败提示。
这张表后续会转成 Service 校验逻辑和测试点。
-->

---

# 非法流转清单

<div class="mt-5 text-sm">

| 当前状态 | 尝试动作 | 系统响应 | 验收 |
|---|---|---|---|
| closed | 重新处理 | 返回非法状态流转 | 状态不变 |
| created | 关闭 | 返回非法状态流转 | 页面提示原因 |
| processing | 驳回 | 返回非法状态流转 | 状态不变 |
| pending_verify | 驳回但无原因 | 返回参数错误 | 提示填写原因 |
| 任意状态 | 无权限流转 | 返回权限拒绝 | 不完成操作 |

</div>

<!--
很多团队只测正常流，不测非法流。
第四天必须把非法流转当成设计产物，而不是测试时临时发现。
-->

---

# 状态流转接口契约

<div class="mt-5 text-sm">

```md
POST /workOrder/assign
字段：id、assignee、remark

POST /workOrder/transition
字段：id、action、targetStatus、remark、version

验收：
合法流转成功；非法流转失败；状态不被错误修改；审计日志可查。
```

</div>

<!--
状态流转不要散落在普通编辑接口里。
指派和状态流转建议有明确接口。
Service 层负责读取工单、校验权限、校验状态、更新状态、记录日志。
-->

---

# 可直接复制到 rules：状态流转

<div class="mt-5 text-xs">

```md
## 复杂业务状态必须先建模
- 级别：硬约束
- 适用场景：工单指派、处理、验证、驳回、关闭、重开。
- 必须：先产出状态流转表，列出当前状态、动作、目标状态、允许角色、前置条件、后置动作和验收方式。
- 禁止：直接在代码中堆状态判断而没有状态表。
- 验收方式：每个状态动作都有合法路径和非法路径验证。

## 非法状态流转必须拒绝且状态不变
- 必须：集中校验非法流转；失败时返回明确错误，业务状态不变，不写成功审计。
- 禁止：仅靠前端禁用按钮防止非法流转。
- 验收方式：构造非法状态动作，接口失败且数据库状态不变。
```

</div>

<!--
这页把 state-audit 里的状态规则放到状态机模块。
它的作用是提醒学员：状态表不是一次性课堂表格，而是后续开发和 Review 都要引用的团队规则。
尤其是“非法流转状态不变、不写成功审计”，这是复杂业务上线前必须验证的底线。
-->