98 lines
7.2 KiB
Markdown
98 lines
7.2 KiB
Markdown
# 统一订单主状态与操作契约
|
|
|
|
> 当前产品基线：客户、平台运营、仓库和作业端围绕同一条订单主线工作。产品界面使用“订单列表”，不再把“头程订单”“入库单”作为用户可见的独立主线。
|
|
|
|
## 一、主状态
|
|
|
|
订单主状态固定为以下六个，不新增“待客户确认”“差异处理中”“派送中”等主状态：
|
|
|
|
| 编码 | 文案 | 说明 |
|
|
|---|---|---|
|
|
| `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` 等自动编排中间态不作为产品主状态展示；由统一订单查询层转换为当前产品阶段。
|
|
|
|
## 七、验收主链
|
|
|
|
```text
|
|
客户提交订单
|
|
→ 平台审核
|
|
→ 仓库测量与客服确认
|
|
→ 测量完成并自动进入待分柜
|
|
→ 智能分柜并确认预装清单
|
|
→ 完成订舱、拖车、报关放行和 PDA 拣货
|
|
→ 五类有效照片及锁码文本通过门禁
|
|
→ 装柜完成（LOADED，国内国内货柜履约终点）
|
|
```
|
|
|
|
后续由海外仓可信回传把 `LOADED` 推进为 `DELIVERED`，不属于国内国内货柜履约验收主链。每一段均需验证：满足门禁时可推进、重复操作幂等、操作有留痕、客户未确认不额外阻断，并且 Admin、Client、PDA 显示同一主状态。
|