docs: define inbound hold gate

2026-09-07 11:23:57 +08:00
parent 7c14f7039c
commit 7d64260209
1 changed files with 7 additions and 0 deletions
@@ -45,6 +45,13 @@
 - 重复提交同一操作必须保持幂等，不能伪造新的状态历史或绕过前置门禁。
 - `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`。查看权限不会自动获得写权限，默认只授予平台管理员。
+
 ## 四、客户确认和差异

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