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

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

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

一、主状态

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

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

待确认 → 确认中 → 已确认

三、宽松版本规则

• 本版本不做业务强制门禁，不因为测量缺项、客户未确认、差异未处理、照片或封签不完整而阻止操作员继续操作。
• 本版本不新增异常、驳回、阻塞、取消等主状态。异常说明、差异说明和补充资料作为备注、附件或自定义节点保存。
• 各主状态下的业务资料均允许修改。修改资料不自动回退主状态，也不自动触发新的异常状态。
• 主状态不提供任意下拉框修改，只通过明确的业务操作推进；服务端仍负责身份、权限、客户归属、幂等和审计。
• 重复点击同一操作应保持幂等；已经完成的操作可以重新打开资料编辑，但不能伪造新的状态历史。
• 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 等现有自动编排中间态不作为产品主状态展示；由统一订单查询层转换为当前产品阶段。

七、验收主链

客户提交订单
→ 平台审核
→ 仓库测量与客服确认
→ 测量完成并自动进入待分柜
→ 智能分柜并确认预装清单
→ PDA 拣货、拍照、封签
→ 装柜完成
→ 派送完成

每一段均需验证：可推进、可修改、可重复操作、操作有留痕、客户未确认不阻断，并且 Admin、Client、PDA 显示同一主状态。