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

> 当前产品基线：客户、平台运营、仓库和作业端围绕同一条订单主线工作。产品界面使用“订单列表”，不再把“头程订单”“入库单”作为用户可见的独立主线。

## 一、主状态

订单主状态固定为以下七个，不新增“待客户确认”“差异处理中”“派送中”等主状态：

| 编码 | 文案 | 说明 |
|---|---|---|
| `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` | 仅接受海外仓可信回传；国内 Admin/PDA 不提供该操作入口 |

`SMART_SPLIT` 不改变主状态，只改变预装清单子状态。预装清单子状态固定为：

```text
待确认 → 确认中 → 已确认
```

## 三、门禁与修改规则

- `WAIT_MEASURE -> WAIT_SPLIT` 必须满足二期测量、审核和费用确认契约；客户确认和差异沟通不单独增加主状态，也不替代服务端门禁。
- `LOADING -> LOADED` 必须由服务端校验订舱完成、拖车完成、有效放行回执、PDA 拣货完成、五类证据各至少一张有效照片及锁码文本；任何一项缺失都不得推进。
- 本版本不新增异常、驳回、阻塞、取消等主状态。异常说明、差异说明和补充资料作为子状态、备注、附件或自定义节点保存。
- `LOADED` 前的业务资料可在权限和状态规则内修改；修改资料不自动回退主状态。`LOADED` 后错误统一线下人工处理，国内系统不提供在线冲正。
- 主状态不提供任意下拉框修改，只通过明确的业务操作推进；服务端负责身份、权限、客户归属、幂等、版本和审计。
- 重复提交同一操作必须保持幂等，不能伪造新的状态历史或绕过前置门禁。
- `LOADED` 是国内出仓终点；本版本不增加“派送中”，也不允许国内运营人员手工推进 `DELIVERED`。

## 四、客户确认和差异

客户确认、差异沟通和客服补充说明均为非阻断操作：

- 客户未确认时，订单仍可继续执行分柜，并在全部服务端硬门禁满足后完成装柜；测量完成后主状态已经是 `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 拣货
→ 五类有效照片及锁码文本通过门禁
→ 装柜完成（LOADED，国内三期终点）
```

后续由海外仓可信回传把 `LOADED` 推进为 `DELIVERED`，不属于国内三期验收主链。每一段均需验证：满足门禁时可推进、重复操作幂等、操作有留痕、客户未确认不额外阻断，并且 Admin、Client、PDA 显示同一主状态。