统一订单主状态与操作契约.md

@@ -0,0 +1,88 @@
+# 统一订单主状态与操作契约
+
+> 当前产品基线：客户、平台运营、仓库和作业端围绕同一条订单主线工作。产品界面使用“订单列表”，不再把“头程订单”“入库单”作为用户可见的独立主线。
+
+## 一、主状态
+
+订单主状态固定为以下七个，不新增“待客户确认”“差异处理中”“派送中”等主状态：
+
+| 编码 | 文案 | 说明 |
+|---|---|---|
+| `PENDING_REVIEW` | 待审核 | 客户已提交订单，等待平台审核 |
+| `WAIT_MEASURE` | 待测量数据 | 审核通过后，测量数据尚未更新完成 |
+| `INBOUNDED` | 已入库 | 历史/内部兼容状态；本版本测量完成后不在此状态停留 |
+| `WAIT_SPLIT` | 待分柜 | 订单进入分柜处理，尚未完成有效分柜方案 |
+| `LOADING` | 装柜中 | 预装清单已确认，正在拣货、装柜和补充证据 |
+| `LOADED` | 装柜完成 | 装柜操作已完成，等待派送完成 |
+| `DELIVERED` | 派送完成 | 派送完成，订单进入终态 |
+
+主状态只表达订单当前所处的产品阶段。订单列表、订单详情、客户进度和 PDA 任务引用同一主状态，不再分别展示“头程订单状态”和“入库单状态”。
+
+## 二、主线操作流转
+
+| 操作编码 | 前置主状态 | 结果主状态 | 说明 |
+|---|---|---|---|
+| `SUBMIT_ORDER` | 草稿或新建 | `PENDING_REVIEW` | 客户提交订单 |
+| `APPROVE_ORDER` | `PENDING_REVIEW` | `WAIT_MEASURE` | 平台审核通过；审核和修改均需留痕 |
+| `CONFIRM_MEASUREMENT` | `WAIT_MEASURE` | `WAIT_SPLIT` | 测量数据点击完成后自动进入待分柜，不需要人工进入分柜 |
+| `SMART_SPLIT` | `WAIT_SPLIT` | `WAIT_SPLIT` | 智能分柜或人工调整，生成/更新预装清单 |
+| `CONFIRM_PRELOAD` | `WAIT_SPLIT` | `LOADING` | 预装清单确认后进入装柜中 |
+| `COMPLETE_LOADING` | `LOADING` | `LOADED` | PDA 拣货、拍照和封签操作完成后确认装柜完成 |
+| `COMPLETE_DELIVERY` | `LOADED` | `DELIVERED` | 运营人员确认派送完成 |
+
+`SMART_SPLIT` 不改变主状态，只改变预装清单子状态。预装清单子状态固定为：
+
+```text
+待确认 → 确认中 → 已确认
+```
+
+## 三、宽松版本规则
+
+- 本版本不做业务强制门禁，不因为测量缺项、客户未确认、差异未处理、照片或封签不完整而阻止操作员继续操作。
+- 本版本不新增异常、驳回、阻塞、取消等主状态。异常说明、差异说明和补充资料作为备注、附件或自定义节点保存。
+- 各主状态下的业务资料均允许修改。修改资料不自动回退主状态，也不自动触发新的异常状态。
+- 主状态不提供任意下拉框修改，只通过明确的业务操作推进；服务端仍负责身份、权限、客户归属、幂等和审计。
+- 重复点击同一操作应保持幂等；已经完成的操作可以重新打开资料编辑，但不能伪造新的状态历史。
+- `LOADED` 是派送完成前的稳定状态；本版本不增加“派送中”。
+
+## 四、客户确认和差异
+
+客户确认、差异沟通和客服补充说明均为非阻断操作：
+
+- 客户未确认时，订单仍可继续执行分柜、装柜和派送；测量完成后主状态已经是 `WAIT_SPLIT`。
+- 客户提出差异后，平台可以继续分柜、装柜和派送；差异内容保留在订单时间线。
+- 客户确认不是独立主状态，不改变七个主状态集合。
+
+## 五、自定义节点
+
+自定义节点只作为订单时间线和通知信息，不替代七个主状态，也不作为强制门禁。节点至少记录：名称、节点类型、排序、是否客户可见、计划时间、完成时间、操作人、备注和附件引用。
+
+系统固定状态历史与自定义节点并存：固定状态历史记录主状态变更，自定义节点记录业务补充信息。自定义节点的新增、修改和完成不能直接改变主状态。
+
+## 六、兼容现有实现
+
+现有 Order/Firstleg 内部状态暂作为技术兼容字段保留，统一订单 API 对外返回本契约的七个产品主状态：
+
+| 现有内部状态 | 产品主状态映射 |
+|---|---|
+| 订单 `SUBMITTED` | `PENDING_REVIEW` |
+| 入库 `WAIT_MEASURE`、`MEASURING`、`MEASURE_PENDING`、`MEASURE_REJECTED` | `WAIT_MEASURE` |
+| 入库 `INBOUNDED`、测量审核通过后的历史记录 | `WAIT_SPLIT`（当前主线）或保留为内部兼容值 |
+| 分柜、预装、装柜、派送相关新状态 | 分别映射 `WAIT_SPLIT`、`LOADING`、`LOADED`、`DELIVERED` |
+
+`WAIT_PRICING`、`FEE_CONFIRMING`、`INBOUNDING` 等现有自动编排中间态不作为产品主状态展示；由统一订单查询层转换为当前产品阶段。
+
+## 七、验收主链
+
+```text
+客户提交订单
+→ 平台审核
+→ 仓库测量与客服确认
+→ 测量完成并自动进入待分柜
+→ 智能分柜并确认预装清单
+→ PDA 拣货、拍照、封签
+→ 装柜完成
+→ 派送完成
+```
+
+每一段均需验证：可推进、可修改、可重复操作、操作有留痕、客户未确认不阻断，并且 Admin、Client、PDA 显示同一主状态。