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

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

## 一、主状态

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

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

### 入库单扣货门禁

- 扣货是 Firstleg 入库单的独立履约控制，不新增或改变 Order 六个主状态。统一订单列表与详情只透传 `holdFlag/currentHoldReason`；尚未生成入库单时两字段为 `null`，不得使用 `holdCargo/holdReason` 兼容别名。
- 平台人员只能在尚未发生实物拣货、装柜或出仓事实时扣货或解除扣货。两个动作都要求原因、`Idempotency-Key` 和当前入库单 `expectedVersion`；成功后入库版本递增，并在同一事务更新当前快照、写入不可变 `HOLD/RELEASE` 历史。
- 扣货状态为真时，服务端必须从智能排柜候选排除该入库单，并阻断人工分配或调整、同柜组分配、预装确认、PDA 任务创建或启动、PDA 拣货和工作托盘、装柜证据与完成、国内出仓。各入口直接读取 Firstleg 权威状态并失败关闭，前端不得自行推导资格。
- 查询扣货快照和历史使用 `platform:firstleg:inbound:list`；扣货与解除使用独立写权限 `platform:firstleg:inbound:hold`。查看权限不会自动获得写权限，默认只授予平台管理员。

## 四、客户确认和差异

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

- 客户未确认时，订单仍可继续执行分柜，并在全部服务端硬门禁满足后完成装柜；测量完成后主状态已经是 `WAIT_SPLIT`。
- 客户提出差异后，平台可以继续处理分柜和装柜子流程，但差异不能替代或绕过任何状态门禁；差异内容保留在订单时间线。
- 客户确认不是独立主状态，不改变六个主状态集合。

## 五、自定义节点

自定义节点只作为订单时间线和通知信息，不替代六个主状态，也不作为强制门禁。节点至少记录：名称、节点类型、排序、是否客户可见、计划时间、完成时间、操作人、备注和附件引用。

系统固定状态历史与自定义节点并存：固定状态历史记录主状态变更，自定义节点记录业务补充信息。自定义节点的新增、修改和完成不能直接改变主状态。

## 六、现有实现映射

统一订单 API 对外返回本契约的六个产品主状态：

| 现有内部状态 | 产品主状态映射 |
|---|---|
| 订单 `SUBMITTED` | `PENDING_REVIEW` |
| 入库 `WAIT_MEASURE`、`MEASURING`、`MEASURE_PENDING`、`MEASURE_REJECTED` | `WAIT_MEASURE` |
| 测量审核通过后的入库记录 | `WAIT_SPLIT` |
| 分柜、预装、装柜相关状态 | 分别映射 `WAIT_SPLIT`、`LOADING`、`LOADED` |
| 海外仓可信派送完成回传 | `DELIVERED`；国内内部状态或人工操作不得映射为该状态 |

`WAIT_PRICING`、`FEE_CONFIRMING`、`INBOUNDING` 等自动编排中间态不作为产品主状态展示；由统一订单查询层转换为当前产品阶段。

## 七、验收主链

### 客户订单列表的分页与待办读取

- 客户订单首页使用 `GET /api/merchant/v1/orders/workbench`，客户范围只取认证上下文，权限为 `merchant:order:list`。接口一次返回当前页、筛选后总数、全部/待费用确认/装柜完成/已报关/已清关/已排车/派送中/派送完成/待上传报关资料/草稿十项数量及该客户完整渠道名称选项；不能先取前 200 条再在浏览器分页或统计。
- Order 在数据库内应用入仓码或 SKU、收货仓、渠道、目的仓类型、快递单号、创建时间、当前状态及待办筛选。草稿排在前面，同组按创建时间和订单 ID 倒序稳定分页；默认每页 10 条，上限 200 条。`DRAFT/CANCELLED` 是订单交易状态在客户读模型中的直接展示，不新增履约推进节点；默认列表排除已取消单。
- Firstleg 通过受内部服务令牌保护的 `/internal/firstleg/v1/inbounds/unified-orders/workbench-filters` 提供当前客户匹配的履约和待办订单范围。费用待确认只取最新费用版本的未确认 `SENT`；报关待上传取最新已完成装柜计划、有效货柜及尚未上传齐当前客户退税入仓码资料的范围，不受同柜其他客户未上传影响。查询不创建报关记录、不更改船或柜、不跨 Schema 读表。
- 切换分类和刷新期间保留上次已确认的分类数量，最新响应完整校验后统一替换，避免数量先归零再恢复；请求失败明确报错并清除失效数量。重复点击当前分类不重发请求或重置页码，错误态允许点击重试。翻页、换每页数量和筛选均重新请求服务端；快速切换时旧响应不得覆盖新页。筛选数量随当前条件计算，资料或费用确认后重新读取。分页响应不完整或依赖服务失败时明确报错，不能回退旧查询或显示成功的空列表。

### 客户头程订单履约分类

- 分类不是新增订单主状态。当前分类优先级为装柜完成、已报关、已清关、已排车、派送中、派送完成，采用已确认的最高当前进度；费用确认、报关资料上传是并行待办，可以与履约分类重叠。分类数量随当前查询条件计算，不从当前页推算。
- Firstleg仅按客户实际装载片段读取有效货柜：装柜计划和实际拣货完成才算装柜；报关聚合`COMPLETED`才算已报关；目的港标准节点`PICKUP_READY`存在实际时间才算已清关。上传、回执确认、正式申报、预计时间和较晚船节点不能补造缺失清关事实。
- Lastleg通过`POST /internal/lastleg/v1/customer-order-progress`只读返回认证客户来源订单的尾程进度。Order使用内部服务令牌调用，公网Gateway不公开该接口，不跨Schema联查。该查询依赖Lastleg可用，失败明确报错，不返回假的零数量。
- 已排车取正式排车单`PENDING_DEPARTURE/PICKING/READY_TO_DEPART`的有效货物；预排草稿、取消排车不计。未收货托盘按计划分配来源，实收托盘按实际库存与本次拣货还原所有来源，混托不能用代表订单号归属整托。
- 派送中必须有`DEPARTED + departAt`、关联出库`OUTBOUNDED`及对应目的地派送单`WAIT_DELIVERY/DELIVERING`；生成派送单不表示开始派送。取消、拒收、待退回及退回分支不伪装为正常派送中，原运输事实留在详情。
- 分批履约返回`partial`，列表显示“部分装柜完成/部分已报关/部分已清关/部分已排车/部分派送中”。根订单合并自身及全部有效子单进度，子单继续独立展示；未同步尾程片段不能算整单完成。派送完成只认Order既有可信完成门禁，不凭某张派送单签收推定根订单完成。
- 工作台响应`progress`与当前页订单一一对应，未到装柜阶段返回`none`并显示“—”；列表及导出保留当前订单状态并单独展示履约进度。历史节点仍由详情中的真实运输片段承载。

本次列表交互以用户提供的分类栏截图为依据：横向可滚动分类、计费待办角标、履约分类括号数量和右侧工具栏。截图未覆盖的“派送完成、上传资料、草稿”沿当前入口追加，履约进度列用于区分主状态与客户进度。详情、编辑、计费确认、资料弹框的承载方式沿现有实现，本次不改变。

列表交互核对范围：

| 页面/操作 | 原型依据与承载 | 实现口径 |
|---|---|---|
| 头程订单列表分类 | 用户提供分类栏截图：列表内横向滚动，计费角标、履约括号数量 | 按截图次序展示七个入口，随后保留完成、资料和草稿；筛选重新请求服务端 |
| 列表状态展示 | 截图保留当前订单状态列；已确认方案补充履约进度 | 主状态不改义，新增可选履约进度列，部分事实明确标注“部分” |
| 订单信息导出 | 原列表工具栏按钮与CSV下载承载 | 同步导出主状态及履约进度，不新增弹框 |

### 履约主链

```text
客户提交订单
→ 平台审核
→ 仓库测量与客服确认
→ 测量完成并自动进入待分柜
→ 智能分柜并确认预装清单
→ 完成订舱、拖车、报关放行和 PDA 拣货
→ 五类有效照片及锁码文本通过门禁
→ 装柜完成（LOADED，国内国内货柜履约终点）
```

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