first

docs/flow/state-machine.md

@@ -0,0 +1,126 @@
+# 安心验履约状态机
+
+## 1. 订单主状态
+
+### 用户提交前
+
+- `pending_payment`
+  说明：订单待支付，当前项目里基本不作为主流履约状态使用。
+- `pending_submission`
+  说明：待补充下单资料，尚未进入正式送检流转。
+
+### 用户寄送阶段
+
+- `pending_shipping`
+  说明：订单已创建，等待用户寄送商品到鉴定中心。
+  典型展示：
+  - 未填运单：`待寄送商品`
+  - 已填运单：`已提交运单`
+- `received`
+  说明：鉴定中心已签收商品，等待进入鉴定处理。
+
+### 鉴定阶段
+
+- `in_first_review`
+  说明：鉴定处理中。
+- `pending_supplement`
+  说明：鉴定师发起补料，等待用户补交资料。
+- `generating_report`
+  说明：已完成鉴定，正在生成报告。
+
+### 报告与寄回阶段
+
+- `report_published`
+  说明：报告已发布，等待平台安排寄回商品。
+  典型展示：`待寄回`
+- `completed`
+  说明：订单已完成。
+  注意：`completed` 下根据回寄物流再细分展示：
+  - 已登记回寄运单但用户未签收：`物品已寄回`
+  - 用户已签收回寄商品：`已完成`
+
+## 2. 鉴定任务状态
+
+### 任务阶段
+
+- `first_review`
+  说明：鉴定任务
+
+### 任务状态值
+
+- `pending`
+  对外文案：`待处理`
+- `processing`
+  对外文案：`处理中`
+- `returned`
+  对外文案：`待用户补料`
+  注意：这是任务被打回补料，不是货品寄回用户。
+- `submitted`
+  对外文案：`已提交`
+- `completed`
+  对外文案：`已完成`
+
+## 3. 物流状态
+
+### 物流类型
+
+- `send_to_center`
+  说明：用户寄送到鉴定中心
+- `return_to_user`
+  说明：平台回寄给用户
+
+### 物流节点状态
+
+#### 用户寄送物流
+
+- `submitted`
+  文案：`已提交运单`
+- `in_transit`
+  文案：`运输中`
+- `received`
+  文案：`已签收`
+
+#### 回寄物流
+
+- `submitted`
+  文案：`已登记回寄运单`
+- `in_transit`
+  文案：`回寄途中`
+- `received`
+  文案：`用户已签收`
+
+## 4. 关键状态迁移
+
+### 下单到鉴定
+
+1. 用户创建订单
+2. 订单进入 `pending_shipping`
+3. 用户提交寄送运单
+4. 后台标记鉴定中心签收
+5. 订单进入 `received`
+6. 鉴定任务进入 `processing`
+
+### 补料分支
+
+1. 鉴定师发起补料
+2. 当前任务状态改为 `returned`
+3. 订单状态改为 `pending_supplement`
+4. 用户补料完成后，订单重新进入 `in_first_review`
+
+### 出报告到寄回
+
+1. 后台发布报告
+2. 订单进入 `report_published`
+3. 用户确认寄回地址
+4. 后台登记回寄运单
+5. 订单进入 `completed`
+6. 若回寄物流未签收，对外显示 `物品已寄回`
+7. 后台标记用户签收后，对外显示 `已完成`
+
+## 5. 当前关键口径
+
+- “补料”只能表示资料补充，不得使用“退回”对外表达。
+- “待寄回”表示报告已出具但平台尚未登记回寄运单。
+- “物品已寄回”表示平台已登记回寄运单，但用户尚未签收。
+- “已完成”只用于回寄商品已签收，或无需回寄的最终完成态。
+- 订单报告未发布前，不允许登记回寄运单或安排物品寄回。