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

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

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

一、主状态

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

编码	文案	说明
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 不改变主状态，只改变预装清单子状态。预装清单子状态固定为：

待确认 → 确认中 → 已确认

三、门禁与修改规则

• 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下载承载	同步导出主状态及履约进度，不新增弹框

履约主链

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

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