优化

头程到尾程分阶段流程/README.md

@@ -0,0 +1,36 @@
+# 头程到尾程分阶段流程文档
+
+本目录把“头程下单 → 尾程出库”拆成六个可独立评审、以后也可独立优化的阶段。各阶段统一描述现状操作和数据流，不在流程确认前直接决定改版方案。
+
+当前六个阶段的现状基线均已完成。下一步按阶段组织业务、产品、运营、国内仓、海外仓和技术评审；每阶段确认后，再将评审结论转入易用性和数据流转优化方案。
+
+## 分阶段计划
+
+| 阶段 | 范围 | 对应全景流程 | 文档 |
+|---|---|---|---|
+| 阶段一 | 客户准入、基础资料、单票/批量下单、提交、审核、订单交接 | F01～F07 | [阶段一：客户准入与头程下单](阶段一-客户准入与头程下单.md) |
+| 阶段二 | 国内到仓、箱码、测量、称重、费用、扣货、一件代发组托 | F08～F13 | [阶段二：国内到仓、测量计费与组托](阶段二-国内到仓测量计费与组托.md) |
+| 阶段三 | 模拟柜、排柜、订舱、拖车、预装、国内 PDA、报关、出仓 | F14～F23 | [阶段三：国内货柜履约与出仓](阶段三-国内货柜履约与出仓.md) |
+| 阶段四 | 海运节点、目的港、跨区尾程建单、尾程入仓计划 | F24～F27 | [阶段四：海运、目的港与尾程入仓计划](阶段四-海运目的港与尾程计划.md) |
+| 阶段五 | 海外接柜、实收、库存、暂扣和库内服务 | F28～F33 | [阶段五：海外接柜、库存与库内服务](阶段五-海外接柜库存与库内服务.md) |
+| 阶段六 | 海外排车、转派送、PDA 出库、派送、异常和最终回写 | F34～F40 | [阶段六：海外排车、出库、派送与最终回写](阶段六-海外排车出库派送与回写.md) |
+
+## 每阶段统一模板
+
+1. 阶段目标、起点和终点；
+2. 角色、终端和权限边界；
+3. 前置主数据和检查项；
+4. 页面逐步操作；
+5. 字段与条件必填规则；
+6. 状态机、可用动作和不可逆节点；
+7. 单据、编号、快照和数据归属；
+8. 同步/异步调用和上下游交接；
+9. 正常流、条件分支和异常恢复；
+10. 阶段完成判定与评审清单。
+
+总览入口：
+
+- [现状流程全景清单](../头程下单到尾程出库现状流程全景清单.md)
+- [一票主链操作手册](../头程下单到尾程出库全流程操作手册.md)
+- [易用性与数据流转优化草案](../头程下单到尾程出库流程易用性与数据流转优化方案.md)
+- [AI 流程优化上下文包](../头程到尾程AI流程优化上下文包.md)

头程到尾程分阶段流程/阶段一-客户准入与头程下单.md

@@ -0,0 +1,464 @@
+# 阶段一：客户准入与头程下单
+
+> 对应全景流程：F01～F07。  
+> 阶段起点：企业已注册并可以登录。  
+> 阶段终点：平台审核通过，Order 为 `APPROVED`，Firstleg 已创建正式国内入库单并沿用固定入仓码，统一主状态进入 `WAIT_MEASURE`。  
+> 本文只记录现状流程；易用性问题先登记，不在本文直接改状态、接口或页面。
+
+## 1. 阶段目标和边界
+
+本阶段解决六件事：
+
+1. 确认“谁可以代表哪个客户下单”；
+2. 确认客户是否具备提交资格；
+3. 冻结订单的国内收货仓、目的仓、渠道、地址和货物申报；
+4. 生成客户可见的订单号和全局唯一入仓码；
+5. 由平台审核订单并建立正式国内入库单；
+6. 把权威订单和申报快照交给下一阶段的国内收货、测量和计费。
+
+本阶段不负责：货物是否已经到仓、实际尺寸重量、费用最终确认、分柜、装柜、出仓和海外履约。
+
+## 2. 角色、终端与权限
+
+| 角色 | 终端 | 可做操作 | 不可做操作 |
+|---|---|---|---|
+| 企业成员 | Client | 按权限查看本企业订单 | 查看其他客户、平台内部备注和成本 |
+| 企业订单操作员 | Client | 新建、编辑草稿、批量导入、提交、按规则取消 | 指定客户 ID、修改审核状态、维护公共仓库/渠道 |
+| 企业管理员 | Client | 管理本企业成员角色，并拥有获授权的订单操作 | 配置平台后台权限、跨企业授权 |
+| 平台订单运营 | Admin | 查询授权数据、审核、维护允许的申报字段 | 修改客户归属、订单号、入仓码或实测事实 |
+| 平台超级管理员 | Admin | 在平台权限范围内处理全部订单 | 绕过服务端状态机、直接指定任意目标状态 |
+| Order 服务 | 后端 | 保存订单、货物、快照、状态、入仓码、审计和 Outbox | 拥有测量、仓位、柜次或海外库存 |
+| Firstleg 服务 | 后端 | 审核后创建国内入库单，接收版本化申报更新 | 成为订单交易状态权威 |
+
+客户数据范围必须来自已认证身份。页面传入的 `tenantId/customerId` 不能单独形成授权。
+
+## 3. F02 基础资料准备
+
+### 3.1 企业和账号
+
+- 企业注册完成，可以用中文邮箱/手机号和密码登录；
+- 企业基本资料、联系信息和资质文件已填写；
+- 平台已经人工审核企业资料；
+- 当前成员拥有 `order:first-leg:create`、`order:first-leg:submit` 等对应权限；
+- 当前客户 Finance 资金账户存在且提交时可用。
+
+注册成功不等于具备提交资格。资料未审核通过时仍可登录、补资料和保存草稿，但提交订单必须失败关闭。
+
+### 3.2 下单主数据
+
+| 主数据 | 权威来源 | 下单使用方式 |
+|---|---|---|
+| 国内收货仓 | Warehouse | 只能选 `ACTIVE` 且具备对应收货能力的公共仓 |
+| FBA/海外目的仓 | Warehouse | 按目的类型返回匹配且启用的公共仓 |
+| 私人目的地址 | Order 客户地址簿 | 只能选择本客户 `PRIVATE_DESTINATION`，或保存本单临时快照 |
+| 平台提货地址 | Order 客户地址簿 | `PICKUP` 时选择本客户 `PICKUP` 地址 |
+| 运输渠道与价格 | Firstleg 价格/渠道目录 | 先选国内收货仓，再加载当前有效渠道 |
+| 企业资格 | IAM | 提交时实时校验 |
+| 资金账户 | Finance | 提交时校验实际余额不小于 0 |
+
+下拉列表只负责选择，提交时服务端必须重新查询权威主数据。Warehouse、IAM 或 Finance 无法返回可信结果时提交失败，不回退前端旧缓存。
+
+## 4. F01 企业资料与下单资格流程
+
+### 4.1 客户维护企业资料
+
+入口：Client → 公司信息。
+
+现状操作：
+
+1. 填写企业名称、统一社会信用代码、企业类型和注册地址等基本信息；
+2. 填写联系人、手机、邮箱、微信和联系地址；
+3. 上传营业执照；法人身份证为可选资料；
+4. 保存后等待平台审核。
+
+数据归属：企业和成员属于 IAM。公司联系电话/邮箱是企业资料，不等于成员登录标识；成员手机号修改走账号链路。
+
+### 4.2 平台审核企业资料
+
+入口：Admin → 客户管理/企业资料审核。
+
+1. 平台查看企业资料和资质；
+2. 资料正确时点击审核通过；
+3. 资料不正确时联系客户修改，不在头程订单流程伪造通过；
+4. 审核通过后，客户获得订单提交资格。
+
+### 4.3 提交资格实时检查
+
+客户打开订单页时可以看到企业资料审核提示，但页面提示不是最终门禁。点击提交时服务端重新检查：
+
+- 当前客户身份和成员权限；
+- 企业资料审核状态；
+- Finance 资金账户有效响应；
+- 实际余额是否小于 0；
+- 仓库、渠道、目的仓和地址是否仍有效。
+
+草稿保存不触发资金门禁，因此“能保存”不能解释成“能提交”。
+
+## 5. F03 客户单票下单详细操作
+
+入口：Client → 头程订单 → 创建订单。
+
+### 5.1 选择履约类型
+
+当前主要履约形态：
+
+| 履约形态 | 业务含义 | 关键限制 |
+|---|---|---|
+| 普通头程 | 普通 FBA、海外仓或私人仓货物 | 按箱码进入后续测量和装柜 |
+| `ONE_CLICK_DROPSHIP` 一件代发 | 国内清点 SKU、组托后跨境，海外按 SKU/箱唛出库 | 每个货物明细必须有 SKU；目的类型固定走海外仓能力，不允许靠货名推导 SKU |
+
+### 5.2 选择交货方式
+
+| 交货方式 | 页面值 | 必填数据 | 后续含义 |
+|---|---|---|---|
+| 快递自送 | `SELF_EXPRESS` | 国内收货仓；快递信息按页面当前要求维护 | 客户自行寄到国内仓 |
+| 平台上门提货 | `PICKUP` | 本企业提货地址、联系人、电话、城市、详细地址、预约提货时间 | 订单冻结客户要求的提货事实；不等于订舱级拖车 |
+| 卡车自送 | `SELF_TRUCK` | 国内收货仓和本单自送信息 | 客户自行送到国内仓 |
+
+`PICKUP` 地址可从地址簿选择，也可保存当前地址。停用地址不能用于新订单，但历史订单继续显示已冻结快照。
+
+### 5.3 选择国内收货仓和渠道
+
+1. 从平台有效国内收货仓单选；
+2. 选择仓库后加载该仓可用运输渠道；
+3. 选择渠道，保存稳定 `channelCode` 和服务端名称快照；
+4. 选择报价包税方式；
+5. 选择买单或退税；
+6. 选择整柜 `FCL` 或散货 `LCL`；
+7. 木制品货物要求商检时，页面和服务端必须校验。
+
+渠道编码是业务校验依据，不能从渠道中文名称反推。
+
+### 5.4 选择目的类型和目的地
+
+| 目的类型 | 页面操作 | 服务端规则 |
+|---|---|---|
+| `FBA` | 选择平台维护的有效 FBA 仓 | 仓库类型必须匹配；货物行要求货件编号和跟踪编号 |
+| `OVERSEAS` | 选择平台维护的有效海外目的仓 | 不允许用私人地址或国内仓冒充 |
+| `PRIVATE` | 选择/保存本企业私人地址，填写名称、联系人、电话、国家、城市、地址和邮编 | 地址属于本客户；不创建伪公共仓 |
+
+一件代发页面不开放 FBA/私人仓选择，使用海外仓路径承接后续海外库存。
+
+### 5.5 录入货物明细
+
+每张订单至少一条货物明细。当前页面覆盖：
+
+| 分类 | 字段 |
+|---|---|
+| 识别 | SKU、中文品名、英文品名、产品图片、混箱组合 |
+| 包装 | 包装类型（纸箱/托盘/木箱）、材质、箱数、每箱数量、总数量 |
+| 申报尺寸重量 | 长宽高、总毛重、总净重、总体积 |
+| 海关申报 | 报关 HS CODE、清关 HS CODE、申报单价、申报金额 |
+| FBA | 货件编号、跟踪编号、UPC |
+| 产品属性 | 用途、型号、品牌、产品规格、危险品、木制品 |
+| 辅助 | 备注 |
+
+关键计算和校验：
+
+- 总数量、总重量和总体积由明细汇总，不能另传一套冲突合计；
+- 箱数、件数、重量和体积必须满足正数/非负规则；
+- FBA 货物必须填写货件编号和跟踪编号；
+- 木制品必须满足商检选择；
+- 一件代发 SKU 强制存在，同一箱可通过混箱组合保存多个 SKU；
+- 图片只保存经 File 校验的文件引用，Order 不长期保存图片二进制。
+
+### 5.6 订单级其他信息
+
+- 期望出货日期：客户期望，不等于平台确认 ETD；
+- 客户备注：客户和平台可见；
+- 客户参考号/跟踪编号：用于客户内部定位，不替代平台订单号；
+- 费用预估：下单阶段只作当前规则下的估算，不能当成最终费用或客户确认版本。
+
+### 5.7 保存草稿
+
+客户点击“保存草稿”：
+
+- Order 保存主表、Party 快照和货物明细；
+- 状态保持 `DRAFT`；
+- 不生成入仓码；
+- 不创建 Firstleg 正式入库单；
+- 不触发资金账户校验；
+- 后续可继续编辑或取消。
+
+## 6. F04 客户批量导入详细流程
+
+入口：Client → 头程订单 → 批量导入订单。
+
+### 6.1 下载模板
+
+模板按当前登录客户动态生成：
+
+- 本客户有效提货地址和私人地址；
+- 全部有效国内收货仓；
+- 匹配目的类型的有效目的仓；
+- 当前有效渠道和中文下拉项；
+- 日期、数字和枚举校验。
+
+模板目录必须读取全部分页候选，不能只生成第一页选项。
+
+### 6.2 填写和上传
+
+- 文件只接受 `.xlsx`；
+- 最大 5MB；
+- 最多 50 行有效数据；
+- 直接选择中文下拉值，不填写内部 ID；
+- 平台上门提货必须填写预约时间和提货地址；
+- 木制品必须选择商检；
+- 一件代发必须填写 SKU。
+
+### 6.3 两种导入模式
+
+| 模式 | 行失败时行为 |
+|---|---|
+| `PARTIAL` | 成功行创建草稿，失败行返回行号、字段和原因 |
+| `ATOMIC` | 任一行失败时整批不创建订单 |
+
+导入时服务端重新加载仓库、渠道、地址和客户归属，不信任模板隐藏页。成功结果只创建 `DRAFT`，客户仍需检查并提交。
+
+## 7. F05 订单提交和入仓码
+
+### 7.1 提交前检查
+
+客户端进行表单校验后，服务端再次校验：
+
+1. 当前订单属于登录客户且版本一致；
+2. 状态允许提交；
+3. 当前成员有提交权限；
+4. 企业资料已审核通过；
+5. Finance 账户响应有效且实际余额不小于 0；
+6. 国内收货仓、目的仓和渠道仍启用并类型匹配；
+7. 地址属于本客户且类型正确；
+8. 货物字段、FBA 条件、木制品商检和一件代发 SKU 完整。
+
+### 7.2 提交事务结果
+
+成功后：
+
+- Order 状态 `DRAFT → SUBMITTED`；
+- 统一主状态展示为 `PENDING_REVIEW`；
+- 生成并固定全局唯一入仓码；
+- 写提交历史、操作者和服务端时间；
+- 发布后续协作所需的可靠消息/内部事实；
+- 同一幂等请求重放返回原结果，不产生第二个入仓码。
+
+入仓码是订单、国内入库、箱码、装柜和海外尾程之间的稳定业务关联码。页面不得用内部订单 ID 替代。
+
+### 7.3 F06 草稿编辑与取消
+
+- 草稿允许有权限的企业操作员继续修改并保存；
+- 已提交订单不得再通过草稿入口覆盖审核中的权威版本；
+- 只有服务端当前状态允许时才能取消，页面按钮不是最终授权；
+- 取消携带当前版本和幂等键，并记录操作人、时间和原因；
+- 已进入不可逆履约的订单不能取消，需进入后续阶段异常流程；
+- 请求超时后先查询当前状态，不换新幂等键盲目重试。
+
+## 8. F07 平台审核和申报修订
+
+入口：Admin → 统一订单 → 待审核。
+
+### 8.1 单票审核
+
+1. 按订单号、入仓码、客户、仓库、渠道或状态定位订单；
+2. 核对客户、交货方式、预约时间、国内收货仓、目的类型、目的仓、货物和申报；
+3. 查看平台可见内部信息和服务端返回的下一动作；
+4. 必要时修改允许的客户申报字段；
+5. 点击审核通过。
+
+### 8.2 批量审核
+
+1. 选择同一操作范围内的待审核订单；
+2. 一次调用批量审核预览，不逐票循环拉详情；
+3. 预览按请求顺序返回中文货物摘要、渠道、目的仓、入仓码、`canApprove` 和 `blockReason`；
+4. 操作员只提交可审核项；
+5. 服务端再次校验状态和版本后逐票处理。
+
+### 8.3 平台申报修订边界
+
+平台可在 `DRAFT/REJECTED/SUBMITTED/APPROVED` 范围内按版本修改客户原始申报，但：
+
+- 不得修改客户归属、国内收货仓、订单号、入仓码和状态；
+- 不得增删或重排货物行，使用稳定 `itemNo` 定位；
+- 不得覆盖设备/仓库实测、测量审核和计费事实；
+- 国内收货仓或中转仓要变化时必须重新下单；
+- 只有渠道变化时才检查 Firstleg 履约可逆性和重新计价门禁；
+- 内部校验不可用时失败关闭，不能只改 Order 留下跨服务不一致；
+- 成功后通过 `ORDER_DECLARATION_UPDATED_V1` 向 Firstleg 同步完整申报快照和字段变化。
+
+### 8.4 审核通过结果
+
+- Order 状态 `SUBMITTED → APPROVED`；
+- Firstleg 幂等创建正式国内入库单；
+- 正式入库单沿用提交时生成的入仓码；
+- 生成/补齐后续测量和 PDA 使用的稳定箱码映射；
+- 统一主状态进入 `WAIT_MEASURE`；
+- 审核动作和建单结果写入时间线。
+
+审核通过不代表货物到仓，也不代表测量、计费或入库完成。
+
+## 9. 客户订单列表和详情
+
+### 9.1 列表筛选
+
+当前客户可按订单号、国内收货仓、渠道、入仓码/SKU、创建时间、当前状态、目的仓类型和快递单号查询本企业订单。
+
+### 9.2 列表核心展示
+
+列表包含订单号、入仓码、状态、渠道、运输方式、交货方式、预约提货时间、国内收货仓、目的仓、目的类型、箱数、SKU、重量、体积、费用摘要、货件编号、跟踪编号、柜次和船期摘要等。
+
+数据可能来自 Order 申报和 Firstleg 履约聚合；Order 为 `SUBMITTED` 时必须优先展示待审核，不能因 Firstleg 预投影显示成待测量。
+
+### 9.3 详情和可用操作
+
+详情展示：
+
+- 订单主信息和客户/地址快照；
+- 货物明细和图片；
+- 入仓码业务关系；
+- 服务端时间线；
+- 当前履约摘要；
+- 当前允许的编辑、提交、费用确认、报关资料等动作。
+
+平台内部备注、成本、其他客户数据和内部事件字段不能进入客户响应。
+
+## 10. 状态机和动作
+
+### 10.1 Order 交易状态
+
+```text
+DRAFT --提交--> SUBMITTED --平台审核通过--> APPROVED
+  └--取消--> CANCELLED
+
+APPROVED --后续全部履约可信回写--> COMPLETED
+```
+
+当前产品不以“审核驳回”作为正常业务路径；历史 `REJECTED` 数据在客户侧仍按待补充/待审核兼容展示，不能据此新增一套驳回流程。
+
+### 10.2 统一订单主状态交接
+
+| Order/Firstleg 事实 | 统一显示 | 下一责任人 |
+|---|---|---|
+| Order `DRAFT` | 草稿 | 客户 |
+| Order `SUBMITTED` | `PENDING_REVIEW` | 平台订单运营 |
+| Order `APPROVED` + 正式入库单 | `WAIT_MEASURE` | 国内仓/测量人员 |
+
+交易状态和履约主状态是两个维度。平台审核后不应把 Order 交易状态继续当成仓库作业状态。
+
+## 11. 数据流转和权威归属
+
+```text
+Auth/IAM
+  ├─ 当前客户、成员、角色、企业审核资格
+  ↓
+Client 下单
+  ├─ Warehouse：实时校验国内仓、目的仓和仓库快照
+  ├─ Firstleg：读取有效渠道/价格目录
+  ├─ Finance：提交时校验资金账户
+  ↓
+Order 本地事务
+  ├─ 订单主表、Party快照、货物明细
+  ├─ 状态、版本、入仓码、时间线、幂等结果
+  └─ Outbox/内部调用事实
+  ↓ 审核通过
+Firstleg
+  ├─ 正式国内入库单
+  ├─ 稳定箱码/箱唛来源
+  └─ 下一阶段 WAIT_MEASURE
+```
+
+### 11.1 Order 权威数据
+
+- 客户归属、订单号、入仓码；
+- 客户原始申报和货物明细；
+- 下单时 Party/地址和仓库必要快照；
+- 订单交易状态、版本、幂等和时间线。
+
+### 11.2 Order 不拥有的数据
+
+- 实际尺寸、重量和测量审核；
+- 国内仓位、托盘和装柜事实；
+- 柜次、船节点、海外库存和出库；
+- Finance 钱包和结算主账。
+
+### 11.3 关键编号
+
+| 编号 | 生成时点 | 是否可改 | 用途 |
+|---|---|---|---|
+| `orderNo` | 创建/提交规则生成 | 否 | 客户订单定位 |
+| `inboundCode` | 首次成功提交 | 否 | 国内入库至海外尾程稳定关联 |
+| 客户参考号 | 客户填写 | 按状态 | 客户内部检索，不替代平台编号 |
+| 货物 `itemNo` | 订单明细创建 | 不重排 | 申报更新和箱码来源定位 |
+
+## 12. 正常流、分支和异常恢复
+
+| 场景 | 系统行为 | 操作员处理 |
+|---|---|---|
+| 企业资料未审核 | 可保存草稿，提交拒绝 | 补资料并等待平台审核 |
+| 资金余额小于 0 | 提交拒绝 | 充值或联系财务处理 |
+| Finance/IAM/Warehouse 不可用 | 提交失败关闭 | 保留草稿，服务恢复后原单重试 |
+| 仓库/渠道在草稿后停用 | 提交时拒绝 | 重新选择有效项 |
+| 私人地址归属不符 | 拒绝且不泄露其他客户数据 | 选择本企业地址或新建 |
+| 木制品未选商检 | 表单/服务端拒绝 | 补充商检选项 |
+| FBA 缺货件号/跟踪号 | 提交拒绝 | 补齐对应货物行 |
+| 一件代发缺 SKU | 保存/提交按当前门禁拒绝 | 为每个物理箱内货物补 SKU |
+| 版本冲突 | 当前写入失败且不覆盖新版本 | 刷新订单后重新编辑 |
+| 请求超时 | 不能换新幂等键盲重试 | 先查询订单/幂等结果，再用原操作处理 |
+| 批量导入部分失败 | `PARTIAL` 只建成功行；`ATOMIC` 整批不建 | 按行号和字段修正后重新导入 |
+| 审核时 Firstleg 建单失败 | 不能宣称阶段完成 | 查看服务端结果，受控重试或修复依赖 |
+| 渠道变更不允许 | Order 和 Firstleg 都不写 | 根据阻断原因新建订单或处理下游占用 |
+
+## 13. 阶段完成判定
+
+每张进入阶段二的订单必须同时满足：
+
+- [ ] Order 属于正确客户且状态为 `APPROVED`
+- [ ] 客户可见订单号存在
+- [ ] 全局唯一入仓码存在且未变化
+- [ ] 国内收货仓、渠道、目的类型和目的地快照完整
+- [ ] 货物明细行集合、箱数、SKU/申报字段符合订单类型
+- [ ] Firstleg 正式国内入库单已创建并沿用同一入仓码
+- [ ] 一件代发稳定箱码与 SKU 来源可用
+- [ ] 统一主状态为 `WAIT_MEASURE`
+- [ ] 审核和建单时间线可查
+- [ ] 重放提交/审核不会生成重复入仓码或重复入库单
+
+任何一项缺失都不能把订单交给国内仓作为正式测量任务。
+
+## 14. 本阶段评审问题
+
+这些问题不阻断现状记录，但需要业务评审确认后才能进入优化：
+
+1. 平台上门提货当前在订单中冻结地址和预约时间，但是否存在独立派车、接单、到仓回执流程？若没有，阶段二只能从“货物实际到仓”开始，不能假设提货已被系统履约。
+2. 客户是否仍需要平台代创建订单；若保留，代创建时客户授权、数据来源和通知方式需单列。
+3. 当前产品不设订单审核驳回，但代码兼容 `REJECTED` 历史状态；业务是否确认继续采用“平台修改或联系客户修改、保持待审核”。
+4. 旧系统入仓码模式是否仍会在任何环境启用；若不会，应从正式流程和页面移除。
+5. 下单页的费用预估对客户应如何命名，避免被理解成最终账单。
+6. 一件代发混箱 SKU 的实际填报责任人和现场纠错责任是否已明确。
+
+## 15. 阶段二交接包
+
+交给阶段二“国内到仓、测量、计费与组托”的输入应只有以下权威数据：
+
+- 客户和订单业务身份；
+- 订单号、入仓码、货物 `itemNo`；
+- 交货方式和预约提货事实；
+- 国内收货仓快照；
+- 渠道与目的仓/私人地址快照；
+- 客户申报箱数、SKU、尺寸、重量、体积和报关资料；
+- 一件代发箱内 SKU 关系；
+- 审核通过时间、版本和幂等历史。
+
+阶段二新增实测和计费事实，不反向覆盖本阶段客户原始申报。
+
+## 16. 事实来源
+
+- `docs/订单与客户/README.md`
+- `docs/订单与客户/订单与客户头程订单闭环设计.md`
+- `docs/统一订单主状态与操作契约.md`
+- `docs/业务快速索引.md`
+- `apps/client-web/AGENTS.md`
+- `apps/client-web/src/modules/first-leg/views/FirstLegOrdersView.vue`
+- `apps/client-web/src/modules/first-leg/api/firstLeg.ts`
+- `apps/admin-web/AGENTS.md`
+- `apps/admin-web/src/modules/unified-orders/pages/UnifiedOrdersView.vue`
+- `baiyue-firstleg/order/AGENTS.md`
+- `baiyue-firstleg/order/src/main/resources/openapi/order-v1.yaml`

头程到尾程分阶段流程/阶段三-国内货柜履约与出仓.md

@@ -0,0 +1,424 @@
+# 阶段三：国内货柜履约与出仓
+
+> 对应全景流程：F14～F23。  
+> 阶段起点：入库单主状态为 `WAIT_SPLIT`，不存在有效 HOLD。  
+> 阶段终点：整柜满足国内出仓门禁，产生唯一实际 `DEPARTED_WAREHOUSE` 节点并开始出仓后的船节点查询。  
+> 本阶段复用订单、入库单、柜次和装柜计划，不新建独立“出仓单”。
+
+## 1. 阶段目标和边界
+
+本阶段把可分柜货物转化为可追溯的真实整柜离仓事实，覆盖：
+
+1. 模拟柜、智能推荐、人工分配和同柜不可拆组；
+2. 海运订舱草稿、资料补齐和放舱；
+3. 订舱级国内拖车预约；
+4. 模拟柜与订舱柜型需求、真实集装箱号关联；
+5. 预装确认、动态增减和普通散货托盘标签；
+6. 国内 PDA 拣货、整托装柜和异常闭环；
+7. 四步装柜照片、铅封照片与铅封号；
+8. 装柜完成、部分装载分片和跨区交接快照；
+9. 客户资料、整柜出口报关与放行；
+10. 国内出仓门禁、离仓确认和拖车费用归集。
+
+`LOADED` 表示货物已经完成实际装柜，不等于柜子已经离开国内仓。报关放行等条件在国内出仓环节统一校验；国内 Admin/PDA 不得把订单推进到海外派送完成 `DELIVERED`。
+
+## 2. 角色、终端和对象
+
+| 角色 | 终端 | 主要操作 |
+|---|---|---|
+| 排柜操作员 | Admin | 创建模拟柜、搜索候选、推荐/人工加入、调整预装 |
+| 订舱操作员 | Admin | 建订舱草稿、维护运输资料、上传文件、放舱 |
+| 国内调度 | Admin | 建订舱级拖车预约、选择供应商、维护时间和附件 |
+| 仓库主管 | Admin | 预装确认、真实柜号补录、任务和证据监督 |
+| PDA 拣货员 | 国内 PDA | 领取唯一柜次任务、扫码、异常、拍照、完成装柜 |
+| 报关操作员 | Admin | 汇总整柜资料、开始报关、上传完成文件、完成报关 |
+| 企业操作员 | Client | 上传本客户退税/报关资料、查看本企业进度和回执 |
+| 出仓操作员 | Admin | 查看组合门禁，必要时人工确认离仓 |
+
+核心对象：
+
+| 对象 | 业务作用 | 稳定标识 |
+|---|---|---|
+| 入库单 | 每票/分片货物履约主体 | `inboundId`、入仓码 |
+| 模拟柜/柜次 | 多票货物共享的装载容器 | `containerBookingId`、`cabinetNo` |
+| 装柜计划 | 柜次唯一预装/PDA 作业聚合 | `loadingPlanId` |
+| 海运订舱 | 船司运输和柜型需求聚合 | `oceanBookingId`、`OB-yyMMdd-####` |
+| 拖车预约 | 一个已放舱订舱的国内提柜/送柜任务 | `truckAppointmentId` |
+| PDA 任务 | 单柜次单作业员的现场任务 | `taskId`、任务版本 |
+| 整柜报关 | 柜次级资料冻结和回执 | 柜次及报关记录标识 |
+
+## 3. 前置检查
+
+- 候选入库单已完成阶段二，实际箱数、重量和体积可用；
+- 一件代发已按实际托盘封托；
+- 当前入库单无有效 HOLD；
+- 柜型规格、国内中转仓、有效渠道和供应商主档可用；
+- 操作员理解模拟柜、真实柜号、订舱和拖车是不同对象；
+- 同柜不可拆组、已占用数量和版本冲突均以服务端返回为准；
+- 费用仍可并行维护，但已经确认/发送或客户已确认版本不得被静默改写。
+
+## 4. F14 模拟柜与智能排柜
+
+### 4.1 创建模拟柜
+
+入口：Admin → 国内货柜/智能装柜。
+
+1. 选择正式装柜仓；
+2. 选择九类计划渠道组之一；
+3. 选择平台有效柜型，核对额定容量和限重；
+4. 填写计划日期和必要备注；
+5. 提交后系统原子创建稳定柜次、`cabinetNo` 和唯一装柜计划；
+6. 此时可以没有真实集装箱号，也不会因创建模拟柜自动产生订舱。
+
+容量和重量当前允许达到柜型额定值的 150%，超过时服务端拒绝。页面显示仅用于预判，最终以服务端重新计算为准。
+
+### 4.2 查询候选
+
+工作台可查询 `PENDING_REVIEW`、`WAIT_MEASURE`、`WAIT_SPLIT`、`LOADING` 等未完成候选。状态是展示维度，能否加入必须看响应中的 `canAssign` 和原因。
+
+- 待审核或待测量订单可提前占位；
+- 预装确认和启动 PDA 前，实际作业成员必须进入 `WAIT_SPLIT`；
+- 普通订单按剩余箱数分配；
+- 一件代发按每个未占用的已封托托盘独立返回和分配，禁止拆托；
+- 同柜不可拆组必须成员完整、满箱并原子加入；
+- 推荐顺序以入库时间先进先出为基础。
+
+### 4.3 智能推荐和人工加入
+
+智能推荐：设置筛选范围和装载目标，系统逐项校验渠道、仓库、剩余箱数、体积、重量、托盘完整性、组锁和占用，再返回推荐结果。
+
+人工加入：选择候选，填写普通货分配箱数或选择一件代发整托，携带计划版本提交。系统重新校验资格；页面旧结果不能作为写入依据。
+
+一件代发一票多托时逐托展示，其中一托已分配不得隐藏其他未分配托盘。容量不足时跳过整托，不能回退成按箱拆托。
+
+### 4.4 调整与费用影响
+
+- 未产生物理拣货的普通明细可增减或移除；
+- 已拣数量是可调整下限；
+- 同柜组只有全组都未拣时才能整组移除；
+- 单行一件代发只能按该行 `palletId` 整托移除；
+- 成员变化需要重算未冻结的柜级/客户级费用；
+- 已确认、已发送或客户已确认的费用版本不得直接改写，应按费用规则生成新版本或拒绝。
+
+## 5. F15 海运订舱与放舱
+
+### 5.1 创建草稿
+
+入口：Admin → 海运订舱。
+
+1. 选择启用的国内中转仓；
+2. 选择该仓当前有效渠道；
+3. 选择 `ACTIVE/BOOKING` 订舱供应商；
+4. 填写三类参与方和已知运输资料；
+5. 至少维护一项、最多二十项柜型需求，数量为正整数；
+6. 保存为 `DRAFT`，系统生成 `OB-yyMMdd-####` 订舱号。
+
+草稿允许资料不完整、替换文件和继续编辑。柜型需求只表达需要多少个什么柜型，不创建真实货柜行。
+
+### 5.2 补齐并放舱
+
+放舱前核对：
+
+- 提单号全局唯一；
+- 船名、航次、起运港、目的港、ETD、ETA 和运输条款完整；
+- 渠道仍有效；
+- 柜型需求与平台规格一致；
+- 存在有效 `BOOKING_CONFIRMATION` 或 `BILL_OF_LADING` 文件；
+- 订舱供应商仍为有效主档。
+
+点击放舱后状态从 `DRAFT` 进入 `RELEASED`，运输快照永久只读。放舱不要求真实柜号，不得为了通过校验伪造柜号。
+
+## 6. F16 订舱级国内拖车
+
+入口：Admin → 国内拖车预约。
+
+1. 从服务端候选中选择已 `RELEASED`、有提单号和有效订舱文件的订舱；
+2. 选择 `ACTIVE/TRUCKING/DOMESTIC` 供应商；
+3. 填写计划装柜时间、联系人和附件；
+4. 保存/提交预约；
+5. 重复创建时返回现有非终态预约，不生成第二张。
+
+拖车单只绑定订舱，不绑定客户、柜次、装柜计划或真实柜号。一个订舱最多一张非终态预约，已有有效完成单不能再次创建收费。
+
+PDA 装柜完成不推进拖车状态。只有订舱要求的全部柜型数量均已关联，并且所有柜均确认国内离仓后，拖车才自动完成。正金额应付拖车费按各柜最终实装体积守恒分摊并发送 Finance；缺供应商归属、有效体积或费用配置时失败关闭，不做伪造均分。
+
+## 7. F17 柜次关联和真实柜号
+
+入口：Admin → 柜次详情 → 关联订舱/补录柜号。
+
+1. 选择已放舱订舱的未满配柜型需求；
+2. 选择对应模拟柜；
+3. 校验仓库、渠道映射、柜型、容量、限重和需求剩余数量；
+4. 录入真实集装箱号；
+5. 提交后在原柜次上冻结订舱、需求和柜号快照。
+
+关联不会更换 `containerBookingId`、`cabinetNo`、装柜计划或明细。真实集装箱号在同一订舱内唯一，不同提单可按业务规则复用。
+
+订舱关联、预装确认和任务创建技术上可先于柜号，但正式操作应在 PDA 最终完成前补齐。已有柜号纠正仅限计划 `EDITING`、任务未领取且没有物理作业事实。
+
+## 8. F18 预装确认、动态增减与标签
+
+### 8.1 预装核对与确认
+
+入口：Admin → 预装清单。
+
+1. 打开柜次唯一预装计划；
+2. 核对每个入仓码、客户、目的仓、普通箱数或一件代发托盘；
+3. 查看容量、重量、已占用和异常提示；
+4. 确认所有现场成员已到 `WAIT_SPLIT` 且未 HOLD；
+5. 点击计划级确认，生成或开放唯一 PDA 任务；
+6. 记录确认快照、操作人和版本。
+
+预装进入 `CONFIRMING/CONFIRMED` 只冻结确认快照，不锁死尚未完成柜次。计划仍为 `EDITING/LOADING` 时可继续增加合法明细；未拣明细可调整，已拣明细保持锁定。
+
+新增或调整后计划和任务版本递增，PDA 旧版本必须刷新再作业。
+
+### 8.2 普通散货托盘标签
+
+普通、非一件代发 FBA 明细在计划 `LOADING/COMPLETED` 且真实柜号有效时生成正式托盘标签：
+
+1. 系统按平台柜次号、FBA 地址内部编号和三位序号生成冻结托盘码；新柜次号为全局连续且不按日期重置的 `D0001`、`D0002`，托盘码不依赖可跨提单复用的真实柜号；
+2. 地址内部编号从 Warehouse 启用主数据读取；
+3. 缺编号或同柜重复时拒绝生成；
+4. 重复生成必须与已有明细一致；
+5. Admin 全部打印或按仓指定张数打印；
+6. A4 横版每托一页，标签与海外补打复用同一编号。
+
+该标签与阶段二一件代发 `DP` 托盘不同：一件代发托盘在测量后已实际清点封托，装柜时按冻结整托分配。
+
+## 9. F19 国内 PDA 拣货装柜
+
+### 9.1 领取和开始
+
+入口：国内 PDA → 拣货装柜。
+
+1. 操作员选择当前作业仓；
+2. 打开或扫描柜次任务；
+3. 核对真实柜号、装柜计划和任务版本；
+4. 领取任务后绑定当前作业员、任务和柜次；
+5. 单柜次只允许一名作业员，不支持多人并行或无审计接管；
+6. 进入任务后计划/入库履约按规则进入 `LOADING`。
+
+正式作业当前只支持在线。设备本地草稿按作业员、任务和柜次隔离；批量提交是否具备完整原子事务仍需在优化/验收中持续核实。
+
+### 9.2 普通散货扫码
+
+- 扫描稳定箱码，一箱一码；
+- 不能用 SKU、件数、入仓码或自由文本代替箱码；
+- 系统核对箱码属于当前入库单、当前任务且尚未处理；
+- 连续扫描先进入当前任务草稿，操作员核对后批量提交；
+- 重复扫描不重复增加实装数量。
+
+### 9.3 一件代发整托装柜
+
+- 扫描 `DP` 托盘码，或扫描成员箱码定位所属已封托托盘；
+- 页面展示托盘、入仓码、箱数和 SKU 汇总；
+- 使用 `PICK_PALLET` 一次提交整托；
+- 禁止部分拣货、拆托或将同托不同订单成员分开提交；
+- 装柜完成按 `palletId` 精确冻结每托箱唛和 SKU，不能按整票模糊复制。
+
+### 9.4 部分拣货、跳拣和异常
+
+允许分批扫描和暂时跳过，但每个未完成项必须选择/填写异常原因。存在未解决异常、缺少处理单元、数量不平或版本冲突时不能完成任务。
+
+提交超时后先查询任务明细和操作结果，禁止更换幂等键盲目重复提交。版本冲突时刷新任务，保留未提交草稿并重新核对。
+
+## 10. F20 装柜证据与铅封
+
+PDA 按现场顺序拍摄：
+
+1. `PHOTO_STEP_1`：装柜初始/空柜；
+2. `PHOTO_STEP_2`：装载过程；
+3. `PHOTO_STEP_3`：接近完成；
+4. `PHOTO_STEP_4`：满柜/关门前；
+5. `SEAL`：带有效铅封号的封柜照片。
+
+每类至少一张有效照片，同类允许追加。PDA 仅允许现场相机拍摄；有权限的 Admin 操作员/理货员可人工补充，普通拣货员不开放后台上传。
+
+证据先上传 File 获得合法文件引用，再绑定柜次/任务。错误图片只能作废，不能硬删除；需保留上传、作废、操作者、时间、文件哈希和幂等记录。照片及铅封号当前不对客户展示。
+
+## 11. F21 装柜完成与分片
+
+PDA 点击“完成装柜”时，服务端重新校验：
+
+- 任务属于当前柜次和仓库且版本一致；
+- 真实集装箱号存在；
+- 所有普通箱码或一件代发整托均核平；
+- 没有未解决异常；
+- 四步照片和带铅封号的 `SEAL` 完整；
+- 计划明细、已拣数量和最终实装数量守恒。
+
+校验通过后：
+
+1. PDA 任务和装柜计划进入 `COMPLETED`；
+2. 实装来源入库单进入 `LOADED`；
+3. 生成最终实装箱码、托盘、SKU 和证据快照；
+4. 对部分装载执行一次分片；
+5. 生成跨区 Outbox，但后续消费必须保持幂等。
+
+部分装载时，已装数量形成当前柜次的 `LOADED` 子入库单，余量形成可继续 `WAIT_SPLIT` 的后续子单；只允许一层分片，所有子项总和必须等于来源数量。客户订单身份和入仓码关联不能丢失。
+
+## 12. F22 客户资料与整柜出口报关
+
+### 12.1 客户上传资料
+
+入口：Client → 头程订单 → 报关资料。
+
+客户只可对本企业订单上传退税/报关资料，选择资料类型并填写说明。文件归属、订单归属和客户身份由服务端校验，文件名不能代替合法文件 ID。
+
+### 12.2 平台整柜报关
+
+入口：Admin → 柜次详情 → 出口报关。
+
+1. 查看柜内所有入仓码及其资料覆盖情况；
+2. 对退税资料逐项核对，缺件时联系对应客户补充；
+3. 开始报关时冻结当前参与资料和版本；
+4. 线下向报关代理提交；首版不做外部系统直连；
+5. 完成后为每份退税资料上传一一对应的完成文件；
+6. 全买单柜由平台确认买单，并从导出中心获取最终实装买单明细；
+7. 点击完成整柜报关，写入放行结果和历史。
+
+报关完成后系统立即尝试国内出仓；若其他门禁尚未齐全，保留明确阻断项并由受控补偿重试，不能伪装为已离仓。
+
+## 13. F23 国内出仓
+
+### 13.1 出仓硬门禁
+
+整柜所有关联入库单逐项检查：
+
+- 无有效 HOLD；
+- 入库单为 `LOADED`；
+- 装柜计划为 `COMPLETED`；
+- PDA 柜次任务为 `COMPLETED`；
+- 订舱已 `RELEASED` 且分配当前柜次；
+- 四步照片与有效铅封完整；
+- 整柜报关已完成并放行。
+
+独立拖车状态和独立船期字段提供调度参考，但不是当前确认离仓的硬门禁。拖车在全部订舱柜次离仓后自动完成。
+
+### 13.2 自动与人工确认离仓
+
+报关完成或其他门禁变化时系统自动尝试收敛。未自动完成时，平台在柜次/国内出仓页面：
+
+1. 打开门禁清单；
+2. 逐项处理未通过原因；
+3. 全部通过后点击确认离仓；
+4. 携带当前版本和幂等键提交；
+5. 查看唯一离仓历史和第一条实际节点。
+
+成功后系统：
+
+- 写入整柜唯一国内离仓事实；
+- 创建 `CarrierScheduleQuery`；
+- 写入实际 `DEPARTED_WAREHOUSE` 节点；
+- 触发出仓后船节点查询；
+- 检查并尝试完成订舱级拖车；
+- 保持跨区交接事件可重试且不重复建单。
+
+实际离仓节点产生后禁止撤销。发现错误转入线下和后续阶段异常处理，不提供修改历史伪装未离仓的能力。
+
+## 14. 状态和动作总表
+
+| 对象 | 关键状态 | 推进动作 |
+|---|---|---|
+| 入库单 | `WAIT_SPLIT → LOADING → LOADED` | 分配/开始 PDA/完成装柜 |
+| 装柜计划 | `EDITING → LOADING → COMPLETED` | 预装调整/PDA 作业/最终完成 |
+| 订舱 | `DRAFT → RELEASED` | 补齐资料并放舱 |
+| 拖车 | 非终态 → `COMPLETED` | 所有要求柜次实际离仓后自动完成 |
+| 报关 | 资料收集 → 已冻结办理中 → 已完成/放行 | 客户上传、平台开始、上传回执并完成 |
+| 国内出仓 | 等待门禁 → 可出仓 → 已离仓 | 自动尝试或平台确认 |
+
+主状态只表达阶段结果。订舱、拖车、PDA、证据和报关保持关联子状态，页面应汇聚展示，但不能互相覆盖。
+
+## 15. 异常与恢复
+
+| 场景 | 处理方式 |
+|---|---|
+| 候选显示可用但提交失败 | 以服务端最新占用/版本为准，刷新后重排 |
+| 待测量订单已占位 | 可保留计划占位，确认预装前必须到 `WAIT_SPLIT` |
+| 一件代发整托容量不足 | 跳过整托或换柜，禁止拆托 |
+| 订舱资料不全 | 保持 `DRAFT`，补齐后再放舱 |
+| 放舱后资料错误 | 不原地篡改冻结快照，按业务异常处置 |
+| 真实柜号暂缺 | 可先关联/确认，但最终装柜前必须补齐 |
+| PDA 旧版本 | 刷新计划，不以旧版本覆盖新增明细 |
+| 扫描错箱/重复箱 | 拒绝或提示已处理，核对稳定箱码 |
+| 未完成项有异常 | 记录原因并解决，禁止完成任务 |
+| 照片错误 | 作废并重拍，不硬删除证据 |
+| 部分装载 | 一次分片，已装与余量数量守恒 |
+| 报关资料缺失 | 定位对应客户/入仓码补件，办理批次不伪造完成 |
+| 出仓门禁未齐 | 展示具体阻断项，条件变化后受控重试 |
+| 离仓请求超时 | 查询唯一离仓历史/节点后再处理，不重复写事实 |
+
+## 16. 数据流和阶段完成判定
+
+```text
+WAIT_SPLIT 入库单/已封托托盘
+  → 模拟柜与唯一装柜计划
+  → 已放舱订舱 + 真实柜号 + 订舱级拖车
+  → 预装确认/动态调整
+  → PDA 实装 + 五类证据
+  → COMPLETED / LOADED + 数量分片 + 跨区快照
+  → 整柜报关放行
+  → 国内离仓 + DEPARTED_WAREHOUSE + 船节点查询任务
+```
+
+阶段完成必须同时满足：
+
+- [ ] 最终柜次、装柜计划、订舱、真实柜号关联可追溯
+- [ ] 全部实装箱/托盘/SKU 与入库单数量守恒
+- [ ] PDA 任务完成且无未解决异常
+- [ ] 四步照片、铅封照片和铅封号完整有效
+- [ ] 装柜计划 `COMPLETED`，实装入库单 `LOADED`
+- [ ] 部分装载时已装子单和余量子单正确
+- [ ] 整柜报关已完成并放行
+- [ ] 所有入库单无 HOLD
+- [ ] 唯一国内离仓历史存在
+- [ ] 第一条实际 `DEPARTED_WAREHOUSE` 存在
+- [ ] 船节点查询任务和跨区事件可幂等重试
+
+## 17. 易用性与数据流评审问题
+
+1. 排柜工作台是否充分解释“可提前占位”和“可实际作业”的差别？
+2. 推荐结果是否应逐项展示未入选原因、容量影响和费用影响？
+3. 模拟柜、柜次编号、真实柜号、订舱号和提单号是否在页面上容易混淆？
+4. 订舱、拖车、预装、PDA、报关是否需要一个柜次级总控清单，而不是跨页面查找？
+5. 预装确认后仍可动态增减时，如何提示 PDA 版本已过期并保护未提交草稿？
+6. PDA 批量提交需要补齐怎样的原子性、离线/弱网和失败整批回滚验收？
+7. 五类证据是否要提供拍摄引导轮廓、清晰度检查和缺图计数？
+8. 部分装载分片在 Client 应如何展示，避免客户误以为整票已经全部装柜？
+9. 报关资料清单、补件责任人、截止时间和回执匹配是否需要结构化待办？
+10. 出仓门禁失败是否需要直接跳转到对应处理页面？
+11. 拖车不作为出仓硬门禁的现行口径，是否与现场调度责任一致？
+12. 实际离仓不可撤销后，错误柜号或错误时间的合规更正流程由谁负责？
+
+## 18. 阶段四交接包
+
+交给阶段四的权威数据包括：
+
+- 柜次、真实集装箱号、订舱号、提单号、船名和航次；
+- 起运港、目的港、ETD/ETA 和运输条款快照；
+- 最终实装订单、入仓单、箱码、托盘、SKU、重量和体积；
+- 装柜五类证据引用和报关完成事实；
+- 国内离仓时间和 `DEPARTED_WAREHOUSE` 实际节点；
+- 跨区事件版本、事件 ID 和有效载荷哈希；
+- `CarrierScheduleQuery` 及后续船节点查询上下文；
+- 未冻结费用和拖车应付等并行财务结果。
+
+## 19. 事实来源
+
+- `docs/国内货柜履约/README.md`
+- `docs/国内货柜履约/国内货柜履约页面与原型清单.md`
+- `docs/头程下单到尾程出库现状流程全景清单.md`
+- `docs/统一订单主状态与操作契约.md`
+- `apps/admin-web/src/modules/container-loading/`
+- `apps/admin-web/src/modules/loading-lists/`
+- `apps/pda-uniapp/AGENTS.md`
+- `apps/pda-uniapp/pages/picking/picking.vue`
+- `baiyue-firstleg/firstleg/AGENTS.md`
+- `baiyue-firstleg/firstleg/src/main/resources/openapi/loading-lists-v1.yaml`
+- `baiyue-firstleg/firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml`
+- `baiyue-firstleg/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml`
+- `baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/SmartLoadingService.java`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/LoadingPickService.java`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/outbound/dispatch/service/OutboundDispatchService.java`

头程到尾程分阶段流程/阶段二-国内到仓测量计费与组托.md

@@ -0,0 +1,592 @@
+# 阶段二：国内到仓、测量计费与组托
+
+> 对应全景流程：F08～F13。  
+> 阶段起点：Order 已审核通过，Firstleg 正式国内入库单已创建，统一主状态为 `WAIT_MEASURE`。  
+> 普通订单终点：测量审核通过，主状态进入 `WAIT_SPLIT`。  
+> 一件代发终点：测量审核后进入 `WAIT_PALLETIZE`，完成清点、归托和封托后进入 `WAIT_SPLIT`。  
+> 本文记录当前可执行流程。费用是并行状态，不作为进入 `WAIT_SPLIT` 的前置条件。
+
+## 1. 阶段目标和边界
+
+本阶段要完成七件事：
+
+1. 用稳定入仓码、箱码识别实际到仓货物；
+2. 保存设备测量、人工测量、称重图片、OCR 原值和人工修正值；
+3. 核对实收箱数、实测尺寸、重量、预计托数和现场证据；
+4. 审核并冻结本次有效测量结果；
+5. 生成可独立维护、发布和确认的费用版本；
+6. 在需要时执行国内扣货或解除，并完整保留证据；
+7. 对一件代发订单完成逐箱 SKU 清点、归托和封托。
+
+本阶段不负责模拟柜、排柜、订舱、拖车、装柜、国内出仓、海外入库或尾程出库。普通订单进入 `WAIT_SPLIT` 仅表示已具备后续分柜条件，不表示已入柜、已离仓或已经生成海外库存。
+
+## 2. 角色、终端与权限
+
+| 角色 | 终端 | 主要操作 | 边界 |
+|---|---|---|---|
+| 国内仓收货/测量员 | Admin、测量设备 | 按入仓码定位、录入或接收尺寸、上传称重图片、确认重量、提交测量 | 不审核自己的权限外任务，不改订单客户归属和原始申报 |
+| 国内仓现场主管 | Admin | 复核箱数、尺寸、重量和证据，处理现场差异 | 不直接改费用价格簿和客户账务 |
+| 测量审核员 | Admin | 单票或批量审核、驳回；有专项权限时异常放行 | 不通过修改数据库绕过证据或状态门禁 |
+| 费用操作员 | Admin | 查看系统试算、调整允许字段、确认并发布费用版本 | 不修改测量原始证据，不越权跨客户操作 |
+| 企业费用确认人 | Client | 查看已发送的当前费用版本并确认 | 不能看到未发布版本、其他客户或内部成本 |
+| 扣货操作员 | Admin | 发起 HOLD、上传凭证、按规则解除 | 已拣货、装柜或出仓后不能手工扣货/解除 |
+| 国内 PDA 操作员 | PDA | 一件代发逐箱清点、扫码归托、封托、规则内解封 | 不创建临时箱码，不直接改测量和费用 |
+| Firstleg 服务 | 后端 | 拥有入库单、箱码、测量、审核、费用来源、组托和主流程状态 | 不拥有客户资金主账、公共仓储主档或订单交易主数据 |
+| Finance 服务 | 后端 | 接收不可变费用来源，维护后续账务 | 不成为测量、箱码或主流程状态权威 |
+
+页面按钮是否可见只能作为操作提示，服务端仍需校验身份、数据范围、权限、当前状态、版本和幂等键。
+
+## 3. 阶段输入与作业前检查
+
+### 3.1 从阶段一接收的权威数据
+
+| 数据 | 来源 | 本阶段用途 |
+|---|---|---|
+| 客户、订单号、入仓码 | Order/Firstleg | 识别货主和整票任务 |
+| 国内收货仓 | Order 冻结快照、Warehouse 主档 | 限定实际作业仓和资源范围 |
+| 渠道、目的类型、目的仓/地址 | Order 冻结快照 | 费用试算和后续分柜参考 |
+| 货物 `itemNo`、SKU、申报箱数 | Order 申报快照 | 箱数核对、一件代发清点 |
+| 申报尺寸、重量、体积 | Order 申报快照 | 差异对比，不覆盖实测值 |
+| 履约类型 | Order/Firstleg | 判断普通订单或 `ONE_CLICK_DROPSHIP` |
+| 稳定箱码及箱内 SKU | Firstleg | 测量、PDA 和装柜全过程复用 |
+
+### 3.2 现场开始前检查
+
+- 当前作业仓必须与入库单国内收货仓一致；
+- 入仓码必须可查询到唯一正式入库单；
+- 箱码必须来自系统已生成的稳定箱码池，不得用临时手写编号替代；
+- 订单处于允许采集测量的状态，已提交或已审核的测量批次不可继续修改；
+- 测量设备、秤、相机和网络可用；无法自动识别时必须保留图片并走人工确认；
+- 一件代发必须能够读取每个物理箱与完整 SKU 的冻结关系；
+- 操作员要先区分“申报箱数”和“实际确认箱数”，不得把客户申报直接当作实收事实。
+
+订单尚处于 `PENDING_REVIEW` 时，系统可允许提前采集测量数据，但不能完成测量审核、计价或进入分柜。正式交接仍以订单审核通过和入库单有效为准。
+
+## 4. F08 国内到仓与箱码识别
+
+### 4.1 按入仓码收货定位
+
+入口：Admin → 入库管理/统一入库工作台 → 货品与测量。
+
+操作步骤：
+
+1. 扫描或输入入仓码；
+2. 核对订单号、客户、国内仓、履约类型和申报箱数；
+3. 查看该票稳定箱码是否已经生成；
+4. 按实际到货逐箱核对外包装上的箱码；
+5. 对缺码、重码、无法识别或与本票不匹配的箱子先隔离，不直接进入测量；
+6. 确认现场货物与页面显示为同一客户、同一入仓码后再开始采集。
+
+系统中的“正式到仓”不是靠操作员另造一个新业务编号完成。入仓码负责整票定位，箱码负责物理箱身份，后续设备、人工测量、PDA 组托和装柜继续复用相同映射。
+
+### 4.2 普通订单箱码
+
+- 每个物理箱使用稳定 `boxCode`；
+- 箱码可以由客户或平台下载打印，但是否打印不影响系统中箱码的有效性；
+- 测量记录必须关联稳定箱码或明确的箱规数量，不能只写自由文本；
+- 后续装柜完成时按最终实装事实冻结并向下游传递箱码/箱数。
+
+### 4.3 一件代发箱码
+
+- `fl_inbound_carton_label` 表示物理箱；
+- 箱内一条或多条 SKU 关系在箱码生成时冻结；
+- 标签展示箱内 SKU，但二维码/条码仍只携带稳定箱码；
+- 缺少 SKU 的货物不能生成合格的一件代发箱唛；
+- PDA 清点时扫描这个箱码读取整箱 SKU，不重新手工创建商品明细。
+
+### 4.4 到仓差异登记
+
+| 差异 | 现场处理 | 系统处理原则 |
+|---|---|---|
+| 少箱/分批到货 | 标识未到箱，暂不虚增实收 | 测量总箱数必须基于实际确认结果 |
+| 多箱 | 隔离并查明所属 | 未建立合法箱码关系前不得并入本票 |
+| 箱码破损 | 用入仓码和订单信息核验后补打原箱码 | 不生成第二个物理身份 |
+| 箱码属于其他订单 | 隔离并通知主管 | 禁止强行绑定当前入仓单 |
+| 外包装异常 | 拍照、备注并按异常规则处理 | 证据与业务事实关联，不能只在线下沟通 |
+
+## 5. F09 尺寸测量与称重
+
+### 5.1 页面和数据组成
+
+入口：Admin → 入库管理 → 货品与测量。
+
+一次完整测量至少包含：
+
+- 测量批次：入库单、批次状态、采集来源、提交人和时间；
+- 测量明细：箱码/箱规、长、宽、高、箱数、体积、设备或人工来源；
+- 重量结果：称重图片、OCR 原值、采用值、毛重/净重、确认状态；
+- 辅助信息：预计托数、测量时间、设备号/事件号、备注和差异原因；
+- 审计字段：创建人、修改人、版本、提交与审核历史。
+
+客户申报值、设备原始值、OCR 原值、人工修正值和最终计费采用值必须并行保留，不能用最终值覆盖原始证据。
+
+### 5.2 设备自动测量
+
+第三方设备按接口提交入仓码或箱码、长宽高、数量、设备标识和事件号。
+
+操作要求：
+
+1. 先在设备端确认扫描的是当前物理箱；
+2. 设备上传后在 Admin 核对是否归入正确入仓单；
+3. 核对尺寸单位、箱数和设备时间；
+4. 重复回调使用同一事件号幂等处理，不生成重复测量；
+5. 设备数据异常时保留原值，另行人工修正，不删除原始记录。
+
+单次批量测量明细最多 500 条。超过时应按现场批次拆分，而不是截断数据。
+
+### 5.3 人工补录尺寸
+
+适用场景：设备不可用、个别箱复核、非标货或设备数据需要纠正。
+
+操作步骤：
+
+1. 点击新增/编辑测量明细；
+2. 选择稳定箱码或填写明确箱规及对应箱数；
+3. 填写长、宽、高，三项都必须大于 0；
+4. 填写测量时间；
+5. 上传必要的测量图片，单个文件不得超过页面限制（当前为 5 MB）；
+6. 写明人工补录或修正原因；
+7. 保存后重新核对明细箱数合计。
+
+人工补录可以替换可编辑批次中的业务测量项，但不得抹掉同一物理箱已经冻结的扫码身份、设备事件和原始取证。
+
+### 5.4 称重图片与 OCR
+
+操作步骤：
+
+1. 上传能够清晰看到秤面读数和货物关联的称重图片；
+2. 等待 OCR 返回识别值；
+3. 将 OCR 原值与图片读数比对；
+4. 正确时确认采用；不正确时填写人工修正值和原因；
+5. 确认单位统一换算为系统采用单位；
+6. 将每张有效图片设置为已确认；
+7. 确保最终总重量大于 0。
+
+即使整票只有 1 箱，也至少需要 1 张已确认重量图片。真实 OCR 凭证未配置或识别失败时，可以保留失败结果后人工确认；这是一条有证据的降级路径，不等于允许无图录重量。
+
+每张有效重量图片只能计重一次。重复上传、同图重复确认或同一重量被不同图片重复累计时，必须先消除重复再提交。
+
+### 5.5 保存前与提交前校验
+
+点击“保存测量数据”时保存当前可编辑批次；点击“提交审核”前至少检查：
+
+- 存在至少一条有效测量明细；
+- 所有长宽高、箱数、时间和必要附件合法；
+- 测量明细确认箱数合计等于整票实际确认总箱数；
+- 至少有一张已确认重量图片，全部有效图片均已处理；
+- 最终总重量大于 0；
+- 预计托数为合法正数或满足页面当前规则；
+- 页面没有尚未保存的修改；
+- 当前批次没有被其他人提交或审核；
+- 订单已经审核通过，具备提交审核资格。
+
+系统尝试依据已确认重量和提交动作建立整票连续库位占用/预留。资源不足等非致命问题应显示明确警告并由仓库处理；不得把警告伪装成已完成物理入库，也不得让位置建议覆盖测量事实。
+
+## 6. F10 测量审核与初始计价
+
+### 6.1 审核入口
+
+入口：Admin → 入库管理 → 测量审核。
+
+审核员按单票或批量打开待审任务，核对：
+
+- 客户、入仓码、订单号和国内仓；
+- 申报箱数与实际确认箱数差异；
+- 每组箱规的长宽高、数量和体积；
+- 称重图片、OCR 原值、人工采用值和修正原因；
+- 总重量、总体积和预计托数；
+- 客户尺寸规则或价格簿所需维度；
+- 是否存在重复图片、重复箱码、缺失证据或异常备注。
+
+### 6.2 审核通过
+
+点击审核通过后，服务端在同一受控流程中：
+
+1. 再次校验当前状态、批次版本和证据完整性；
+2. 冻结本次有效测量结果；
+3. 计算或准备初始费用版本；
+4. 普通订单主状态进入 `WAIT_SPLIT`；
+5. 一件代发主状态进入 `WAIT_PALLETIZE`；
+6. 写入审核人、审核时间和状态历史。
+
+初始计价失败或产生警告时，不应回滚已经合法完成的测量审核，也不能把普通订单从 `WAIT_SPLIT` 拉回旧的计费状态。页面需要明确展示“测量已通过、计价待处理”这两个独立结果。
+
+批量审核时，每票都必须返回独立结果。部分失败不能让操作员误以为整批全部成功；失败项按入仓码展示原因并保留在待处理列表。
+
+### 6.3 审核驳回
+
+发现数据或证据不合格时填写明确原因并驳回：
+
+- 驳回原因应说明需要修正的字段或证据；
+- 原测量批次和审核历史保留，不原地覆盖成新记录；
+- 操作员按原因修正允许编辑的数据后重新提交；
+- 历史 `MEASURE_REJECTED` 只作为事实和恢复入口，不代表可以绕过审核直接分柜。
+
+### 6.4 异常放行
+
+异常放行只适用于已驳回测量，且必须同时满足：
+
+- 环境已开启对应开关；
+- 当前用户具备专项权限；
+- 被放行批次确实处于已驳回状态；
+- 填写非空放行原因；
+- 完整记录操作人、时间、原驳回原因和放行原因。
+
+异常放行不能变成常规“跳过审核”按钮，也不能补造不存在的称重或测量证据。
+
+## 7. F11 费用生成、发布与客户确认
+
+### 7.1 费用与主流程的关系
+
+费用是与主状态并行的业务维度：
+
+```text
+测量审核通过 ──→ 主流程：WAIT_SPLIT（普通）/ WAIT_PALLETIZE（一件代发）
+       └──────→ 费用：初算 → 人工维护 → 确认/发布 → 客户确认 → 条件满足后冻结
+```
+
+因此：
+
+- 费用未发送不阻止普通订单进入 `WAIT_SPLIT`；
+- 客户未确认费用不把主流程回退；
+- 装柜完成也不能代替客户自动确认费用；
+- 费用的最终冻结需“客户已确认”和“本票已装柜完成”同时成立。
+
+### 7.2 系统初算
+
+入口：Admin → 入库管理 → 费用。
+
+系统基于已审核测量结果和有效价格簿生成版本化费用，操作员应检查：
+
+- 计费采用的是哪一组实测重量、体积和计费量；
+- 命中的渠道、目的地区域和价格簿版本；
+- 是否命中客户专属 ACTIVE 价格簿；未命中时才回退公共 ACTIVE 价格簿；
+- 计价模型是重量、体积、仓库费率、区域重量阶梯或其他当前有效模型；
+- 基础费用、附加费、币种、税费或调整项是否完整；
+- 系统警告是否说明缺价格、缺映射或数据不满足模型。
+
+同柜区域重量阶梯可能在阶段三根据同柜、同客户的最终有效成员聚合后重算；固定模型成员不参与阶梯聚合。此处初算是当前版本事实，不承诺后续永不变化。
+
+### 7.3 人工调整
+
+允许调整时：
+
+1. 选择当前费用版本；
+2. 查看系统基准量、基准单价和基准金额；
+3. 在服务端允许的范围内修改；当前规则以系统基准量为中心限制上下 10%，含边界；
+4. 填写调整原因；
+5. 完成二次确认；
+6. 保存为新版本，由服务端重新计算金额。
+
+页面不能只提交最终总额来绕开计费规则。版本、基准、调整值、原因、操作人和时间都要可追溯。
+
+### 7.4 平台确认与发送
+
+操作员确认费用明细无误后执行页面上的确认/发送操作：
+
+1. 复核客户、入仓码、币种和当前版本；
+2. 确认没有待处理计价警告；
+3. 发布当前费用明细；
+4. 将费用状态置为客户可见的 `SENT`；
+5. 记录发送人、发送时间和版本。
+
+“发送费用”表示发布当前费用版本供客户查看，不等于已经收款、核销或形成最终财务结算。
+
+### 7.5 客户查看和确认
+
+入口：Client → 头程订单/入库费用。
+
+客户只有在以下条件同时满足时才能看到费用：
+
+- 费用属于当前登录客户；
+- 测量已经审核通过；
+- `feeStatus=SENT`；
+- 存在已发布明细。
+
+客户确认时携带当前 `expectedFeeVersion` 和幂等键。成功后记录确认成员和时间。
+
+若装柜完成前平台生成并重新发送新版本，旧版本客户确认快照被清空，客户需要确认新版本。旧版本、未发送版本或同一幂等键携带不同参数都必须冲突失败，不能静默覆盖。
+
+## 8. F12 国内扣货与解除
+
+### 8.1 适用目的
+
+HOLD 用于在存在费用、资料、风控、货损或其他明确风险时阻断后续物理履约写入。它不是删除订单，也不修改客户和测量事实。
+
+### 8.2 发起扣货
+
+入口：Admin → 统一订单/入库详情 → 扣货。
+
+操作步骤：
+
+1. 确认当前入仓单尚未发生不允许回退的实物动作；
+2. 选择或填写扣货原因；
+3. 上传有效凭证；
+4. 核对入仓码、客户和当前版本；
+5. 二次确认后提交；
+6. 查看 HOLD 状态、操作人和时间线是否写入。
+
+扣货生效后，分柜、拣货、装柜、出仓等后续物理写操作必须由服务端阻断，不能只在前端隐藏按钮。
+
+### 8.3 解除扣货
+
+1. 打开当前有效 HOLD；
+2. 核对风险是否已经消除；
+3. 填写解除原因并补充凭证；
+4. 携带当前版本和幂等键提交；
+5. 系统关闭当前 HOLD，但保留发起与解除历史；
+6. 重新评估主状态允许的下一步动作。
+
+已经发生拣货、装柜或出仓时，禁止通过手工扣货/解除改变已发生的物理事实。此时应进入对应阶段的异常流程。
+
+## 9. F13 一件代发国内清点组托
+
+### 9.1 进入条件
+
+一件代发测量审核通过后不直接进入 `WAIT_SPLIT`，而是：
+
+- 主状态为 `WAIT_PALLETIZE`；
+- 按预计托数预生成 `DP` 托盘码；
+- 箱码与箱内 SKU 已冻结且可被 PDA 读取；
+- 不创建国内库存；
+- 组托完成后才交给分柜。
+
+预计托数与实际已生成托盘数不一致时禁止开始作业，应先修正任务或重新生成合法托盘，不允许 PDA 临时造托盘码。
+
+### 9.2 Admin 打印托盘信息单
+
+入口：Admin → 一件代发组托任务。
+
+1. 打开入仓码对应任务；
+2. 核对预计托数和已生成 `DP` 托盘列表；
+3. 逐托打印 A4 信息单，每托一页；
+4. 核对 Code 128 托盘码、入仓码、总箱数和 SKU 清单；
+5. 将标签贴到对应空托或托盘作业位。
+
+信息单用于识别和作业，不展示容易过期的实时作业状态。实际状态以 PDA/服务端为准。
+
+### 9.3 PDA 逐箱清点与归托
+
+入口：国内 PDA → 一件代发清点组托。
+
+允许两种顺序：
+
+```text
+先扫托盘 → 连续扫箱并清点 → 确认归托
+先扫箱并清点 → 扫目标托盘 → 确认归托
+```
+
+逐箱操作：
+
+1. 扫描稳定箱码；
+2. PDA 展示整箱 SKU、商品名称和应点数量；
+3. 按完整 SKU 清点实点数量；
+4. 有差异时填写原因并按现场异常规则处理，不能直接改冻结 SKU；
+5. 扫描目标 `DP` 托盘码；
+6. 确认该箱归托；
+7. 继续下一箱，直到本票全部箱处理完成。
+
+同仓多票在当前规则允许时可以共用一个开放托盘。共托不会改变箱子所属客户、订单、入仓码和 SKU；系统必须保存逐箱归属，不能只保存托盘总数量。
+
+### 9.4 封托与解封
+
+封托前检查：
+
+- 托盘上所有箱均已完成 SKU 清点；
+- 物理箱数与系统箱数一致；
+- 托盘标签清晰且与 PDA 当前托盘一致；
+- 没有未处理差异或重复归托；
+- 共托场景下各参与任务的数据均完整。
+
+操作员在 PDA 点击封托。封托后该托成为阶段三的整托候选。
+
+未进入装柜计划前可按权限和规则解封。共托解封时，所有参与任务和入仓单的相关状态必须同步恢复，不能只恢复其中一票。托盘进入有效装柜计划后不得在本阶段任意解封。
+
+### 9.5 组托完成判定
+
+系统只有在以下条件同时满足时将一件代发入仓单从 `WAIT_PALLETIZE` 推进到 `WAIT_SPLIT`：
+
+- 本票所有稳定箱码均已清点；
+- 每箱完整 SKU 均已核对；
+- 每箱恰好归属一个有效参与托盘；
+- 本票实际参与的所有托盘均已封托；
+- 没有开放托盘仍包含本票箱子；
+- 箱数、SKU 数量和托盘冻结快照核平。
+
+预计生成但实际未使用的空托盘不应伪造为已作业托盘；最终事实以实际参与且完成的托盘为准。
+
+## 10. 状态机与可用动作
+
+### 10.1 主流程状态
+
+| 当前状态 | 条件/操作 | 下一状态 | 说明 |
+|---|---|---|---|
+| `PENDING_REVIEW` | 可提前采集测量 | 不变 | 不能审核测量、计价或分柜 |
+| `WAIT_MEASURE` | 保存测量 | 不变 | 可反复保存未提交批次 |
+| `WAIT_MEASURE` | 提交测量审核 | 不变/待审维度变化 | 已提交批次冻结 |
+| `WAIT_MEASURE` | 审核驳回 | 驳回事实 | 修正后重新提交 |
+| `WAIT_MEASURE` | 普通订单审核通过 | `WAIT_SPLIT` | 费用并行处理 |
+| `WAIT_MEASURE` | 一件代发审核通过 | `WAIT_PALLETIZE` | 必须先完成清点组托 |
+| `WAIT_PALLETIZE` | 全部箱和实际托盘完成 | `WAIT_SPLIT` | 不创建国内库存 |
+| `WAIT_SPLIT` | 合法解封导致组托不再完整 | `WAIT_PALLETIZE` | 仅限未进入装柜计划等允许条件 |
+
+测量批次状态、审核状态、费用状态、HOLD 状态和托盘状态是独立维度，不能把它们拼成一条虚假的单状态流水线。
+
+### 10.2 费用状态关键约束
+
+| 费用事实 | 平台可修改 | 客户可见/确认 | 最终冻结 |
+|---|---|---|---|
+| 未生成/初算警告 | 是 | 否 | 否 |
+| 已生成、未发送 | 是 | 否 | 否 |
+| `SENT`、客户未确认 | 是，可生成新版本 | 可见、可确认 | 否 |
+| 客户已确认、尚未装柜完成 | 仍可按规则生成新版本并重新发送 | 新版本需重新确认 | 否 |
+| 客户已确认且装柜完成 | 否 | 已确认 | 是 |
+
+### 10.3 HOLD 的正交关系
+
+HOLD 不必改变主状态文字，但会阻断后续物理履约动作。解除后继续从原主状态判断下一步，不自动跳过测量、组托或分柜条件。
+
+## 11. 数据归属与流转
+
+### 11.1 关键数据所有者
+
+| 数据 | 权威系统 | 下游消费者 |
+|---|---|---|
+| 客户申报、订单交易状态 | Order | Firstleg、页面查询 |
+| 入库单、入仓码映射 | Firstleg | Admin、设备、PDA、后续装柜 |
+| 稳定箱码、箱内 SKU | Firstleg | 测量、PDA、装柜事件、尾程 |
+| 公共仓库、库位、托盘资源 | Warehouse | Firstleg 作业引用 |
+| 测量原始值、人工采用值、证据 | Firstleg | 计价、审核、后续审计 |
+| 费用来源和版本 | Firstleg | Client、Finance |
+| 应收应付、收付款、核销 | Finance | 财务终端与对账 |
+| 文件对象 | File | 各业务通过合法文件引用使用 |
+
+### 11.2 数据流
+
+```text
+Order 审核快照
+   ↓
+Firstleg 正式入库单 + 稳定箱码
+   ↓
+设备/人工尺寸 + 称重图片/OCR + 人工确认
+   ↓
+测量审核冻结 ──────────────→ 主流程 WAIT_SPLIT / WAIT_PALLETIZE
+   ├→ 初始费用版本 → 平台维护/发送 → 客户确认 → Finance 来源
+   ├→ 仓位连续占用/预留尝试 → Warehouse 资源
+   └→ 一件代发 PDA 逐箱清点 → DP 托盘冻结 → WAIT_SPLIT
+```
+
+### 11.3 必须保留的快照和历史
+
+- 原始客户申报与最终实测同时存在；
+- 设备事件号、设备原值、人工修正值和原因；
+- 原始称重图片、OCR 原值、采用值和确认人；
+- 每次测量提交、驳回、通过和异常放行；
+- 每个费用版本、价格簿来源、系统基准、人工调整和客户确认；
+- 每次 HOLD 发起、证据、解除和版本；
+- 一件代发每箱 SKU 实点、归托、封托和解封历史。
+
+## 12. 正常分支、异常与恢复
+
+| 场景 | 系统行为 | 操作员处理 |
+|---|---|---|
+| 订单未审核但货先到 | 允许按当前规则采集，禁止审核/计价/分柜 | 保留测量草稿，等待订单审核 |
+| 查不到入仓码 | 不创建临时正式入库单 | 隔离货物，核对订单提交/审核结果 |
+| 箱码破损 | 原身份仍有效 | 核验后补打相同箱码 |
+| 设备重复上报 | 按事件号幂等，不重复计量 | 核对已有记录，不换事件号盲重试 |
+| 设备值异常 | 原值保留 | 人工复测并写修正原因 |
+| OCR 失败 | 失败结果和图片保留 | 人工读取、录入并确认 |
+| 重量图片重复 | 禁止重复计重 | 删除/作废重复采用关系后重算 |
+| 明细箱数不等于实收总箱数 | 禁止提交 | 查找漏测、重复测量或到货差异 |
+| 预计托数无效 | 禁止提交或组托 | 仓库重新评估并保存 |
+| 页面有未保存修改 | 禁止提交审核 | 先保存再提交 |
+| 测量被并发提交 | 版本冲突 | 刷新后查看权威结果 |
+| 审核通过但计价失败 | 主状态按审核结果推进，费用显示待处理 | 修复价格簿/映射后重算，不回退测量 |
+| 费用版本过期 | 客户确认冲突 | 刷新并确认当前已发送版本 |
+| HOLD 生效 | 后续实物写入失败关闭 | 处理风险后按证据解除 |
+| 一件代发箱内 SKU 不符 | 不直接改冻结清单 | 记录差异并由有权流程纠正来源 |
+| 开放共托仍含本票箱子 | 本票不能完成组托 | 完成或按规则拆解参与托盘 |
+| 封托后需调整 | 仅未进入装柜计划时可解封 | 有权解封、修正、重新封托 |
+| PDA 请求超时 | 不确定是否成功 | 先查询箱/托当前状态，再用原幂等语义处理 |
+
+## 13. 阶段完成判定
+
+### 13.1 普通订单
+
+- [ ] 入仓码、订单、客户和国内仓对应正确
+- [ ] 稳定箱码和实收箱数可追溯
+- [ ] 测量明细箱数与实际确认总箱数一致
+- [ ] 尺寸、重量、图片和人工修正证据完整
+- [ ] 至少一张重量图片已确认且总重量大于 0
+- [ ] 测量批次已审核通过并冻结
+- [ ] 主状态为 `WAIT_SPLIT`
+- [ ] 初始费用已生成，或计价警告已作为独立待办暴露
+- [ ] 若存在 HOLD，下一阶段明确知道当前不可继续物理履约
+- [ ] 重复提交和重复审核不会产生重复事实
+
+### 13.2 一件代发订单
+
+除普通测量条件外，还必须满足：
+
+- [ ] 每个物理箱和完整 SKU 来源可追溯
+- [ ] 每箱均已完成 SKU 清点
+- [ ] 每箱恰好归属一个实际参与托盘
+- [ ] 所有实际参与托盘均已封托
+- [ ] 共托参与关系和逐箱归属完整
+- [ ] 最终托盘冻结快照存在
+- [ ] 主状态已从 `WAIT_PALLETIZE` 进入 `WAIT_SPLIT`
+- [ ] 未因组托创建国内库存
+
+费用是否已经发送、客户是否已经确认，不作为本阶段主流程交接到阶段三的硬门槛；但必须作为并行待办清晰展示和持续跟踪。
+
+## 14. 易用性与数据流评审问题
+
+以下问题先记录，后续优化阶段逐项决策：
+
+1. 到仓页是否需要独立的“实收登记”动作和时间戳，还是继续由首次合法测量/扫码体现到仓？
+2. 订单未审核时允许提前测量，页面应如何醒目标识“仅采集、不可审核”，避免仓库误判流程已放行？
+3. 箱数差异是否需要结构化的少箱、多箱、破损和错货原因，而不是仅填备注？
+4. 真实 OCR 供应商凭证、现场秤图片式样和识别准确率应由谁验收？
+5. 连续库位预留失败目前作为警告时，仓库如何看到并闭环处理，是否需要独立待办？
+6. “发送费用”是否应改名为“发布给客户”，以避免被误解为发送账单或已完成结算？
+7. 计价失败但主流程已进入 `WAIT_SPLIT` 时，是否需要跨页面的费用红点、责任人和超时提醒？
+8. HOLD 的发起责任、审批规则、证据类型和解除责任是否已经形成可审计 SOP？
+9. 一件代发允许跨订单共托时，业务是否确认允许跨客户；若允许，拆托、异常和费用责任如何分摊？
+10. PDA 清点发现 SKU 差异时，目前应走哪个权威纠错入口，谁能修改冻结来源并触发重新打印？
+11. 预计托数与实际托数变化时，是否需要保留预测偏差指标，为仓容和装柜优化提供数据？
+12. 客户费用确认与装柜完成共同冻结的规则，页面是否充分解释“已确认但尚未冻结”。
+
+## 15. 阶段三交接包
+
+交给阶段三“模拟柜、排柜、订舱、拖车、预装、装柜与出仓”的权威输入包括：
+
+- 入仓单、订单号、入仓码、客户和国内仓；
+- 渠道、目的类型、目的仓/地址快照；
+- 已审核的最终箱数、重量、体积和箱规；
+- 稳定箱码及必要的箱内 SKU 关系；
+- 普通订单预计托数和库位占用/预留结果；
+- 一件代发实际封托的 `DP` 托盘、逐箱归属和 SKU 冻结快照；
+- 当前主状态 `WAIT_SPLIT`；
+- 当前有效 HOLD 及阻断原因；
+- 费用当前版本、发布/客户确认状态和未处理计价警告。
+
+阶段三可以基于最终装柜成员重算尚未冻结的费用，但不得覆盖本阶段的原始测量、证据或一件代发逐箱组托事实。
+
+## 16. 事实来源
+
+- `docs/头程下单到尾程出库现状流程全景清单.md`
+- `docs/入库测量与计费/README.md`
+- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
+- `docs/统一订单主状态与操作契约.md`
+- `apps/admin-web/AGENTS.md`
+- `apps/admin-web/src/modules/inbounds/measurement/InboundMeasurementDialog.vue`
+- `apps/admin-web/src/modules/inbounds/measurement/InboundMeasurementPanel.vue`
+- `apps/admin-web/src/modules/inbounds/fee/InboundFeePanel.vue`
+- `apps/admin-web/src/modules/inbounds/components/InboundWorkflowWorkspace.vue`
+- `apps/admin-web/src/modules/inbounds/components/InboundTaskList.vue`
+- `baiyue-firstleg/firstleg/AGENTS.md`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/InboundMeasurementService.java`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/MeasurementReviewService.java`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/InitialInboundPricingService.java`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/DropshipPalletizationService.java`
+- `baiyue-firstleg/firstleg/src/main/resources/openapi/dropship-palletization-v1.yaml`

头程到尾程分阶段流程/阶段五-海外接柜库存与库内服务.md

@@ -0,0 +1,405 @@
+# 阶段五：海外接柜、库存与库内服务
+
+> 对应全景流程：F28～F33。  
+> 阶段起点：实际船节点达到 `PICKUP_READY`，整柜尾程计划和海外托盘/库位资源已经就绪。  
+> 主链终点：整柜收货完成，库存同事务入账，尾程主状态为 `INBOUND_COMPLETED`。  
+> 并行范围：库存查询、托盘作业、暂扣、换标、仓储转运和货物废弃。
+
+## 1. 阶段目标和边界
+
+本阶段把海运在途货物转化为海外仓可核对库存：
+
+1. 海外 PDA 操作员按真实柜号认领待卸货柜；
+2. 核对国内装柜证据并拍摄海外签收三类照片；
+3. 按 FBA 散货、OVERSEAS 逐箱和一件代发整托三种模式实收；
+4. 整柜核平后一次完成计划、任务、库存和卸柜事件；
+5. 提供库存、位置、流水、托盘以及已开放的库内作业；
+6. 对单票执行暂扣/解除；
+7. 处理换标、仓储转运和一件代发货物废弃。
+
+本阶段不负责海外配送排车、出库发车和最终派送。入仓完成只是后续履约资格之一；有效暂扣、换标未完成或库存被其他子单锁定时仍不能出库。
+
+## 2. 角色、终端和权限
+
+| 角色 | 终端 | 主要操作 | 边界 |
+|---|---|---|---|
+| 海外仓 PDA 操作员 | 海外 PDA | 认领柜、拍照签收、实收、完成整柜、库内作业 | 需 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 和 `lastleg:pda:operate`，仓库由 Token 固定 |
+| 海外仓主管 | Admin | 查询入仓、库存、托盘、异常，处理授权的库存/暂扣操作 | 不用内部 ID 修改他仓资源 |
+| 企业操作员 | Client | 查看本企业库存，发起换标、转运、废弃等自助服务 | 不查看其他客户或直接改实物托盘 |
+| 换标作业员 | 海外 PDA | 认领、扫描旧/新标、拍照、提交复核 | 不自行批准复核或客户确认 |
+| 换标复核员 | Admin | 退回返工、核对作业事实 | 已由客户确认后不能退回 |
+| 废弃审核员 | Admin/PDA | 审批一件代发废弃并触发实际扣减 | 创建申请时不得直接扣库存 |
+| Lastleg | 后端 | 入仓作业、库存业务、子单、状态和事件权威 | 不拥有物理仓/托盘主档 |
+| Warehouse Overseas | 后端 | 海外库位、实物托盘、资源锁和物理状态 | 不拥有库存客户归属和尾程订单 |
+
+平台管理员和普通客户账号不能进入海外 PDA 柜号签收入口。PDA 请求不接收 `customerId` 或可切换的 `warehouseId`；客户和仓库范围由柜内计划、入仓码和登录 Token 解析。
+
+## 3. 作业前检查
+
+- 操作员账号已绑定唯一 `ACTIVE + OVERSEAS + RECEIVING` 海外仓；
+- 换仓或清空绑定后旧 Token 已失效；
+- 实际节点达到 `PICKUP_READY` 或更晚；
+- 柜内每票订单为 `INBOUND_PLANNED`；
+- 所有计划已经绑定真实托盘、库位和资源锁；
+- `resourcePendingPlanCount=0`；
+- 真实柜号、来源柜聚合键、预计到仓和入仓码完整；
+- 普通货计划箱数、一件代发来源托盘/SKU/箱唛快照可核对；
+- PDA 网络、相机和扫码能力正常。
+
+只要任一计划仍缺真实资源，就不能准备、签收或开始该柜。PDA 首次扫码只确认计划阶段已预留资源，不在现场重新分配托盘或库位。
+
+## 4. F28 海外 PDA 柜号签收
+
+### 4.1 查看待卸货柜
+
+入口：海外 PDA → 拆柜收货。
+
+候选按物理柜跨客户聚合，仅返回达到 `PICKUP_READY` 且计划资源完整的柜。列表使用真实集装箱号、预计到仓和接柜仓，不显示内部柜次 ID。
+
+操作员选择柜后：
+
+1. 系统按平台账号和柜号创建/恢复唯一未完成会话；
+2. 柜被原子认领到当前 Token 固定仓库；
+3. PDA 锁定当前柜，不允许随意切换；
+4. 展开查看柜内全部入仓码、客户隔离任务、目的仓、计划托数和箱数；
+5. 核对当前仓库与现场一致。
+
+柜级认领允许同柜多客户，但后续每票任务、扫码、库存和流水仍使用入仓码所属的真实客户。
+
+### 4.2 查看国内装柜照片
+
+签收前展开国内五类只读证据：空柜、装载过程、接近完成、满柜/关门前、带铅封号照片。
+
+- 证据仅用于现场对照，不允许 PDA 修改；
+- 单张图片加载失败时提供重试；
+- 单图失败不阻断拆柜，但应保留加载异常；
+- 现场发现柜号、铅封或外观明显不符时，应先走异常处理而不是盲目签收。
+
+### 4.3 拍摄三类签收照片
+
+依次现场拍摄并上传：
+
+1. `LICENSE_PLATE`：承运车辆车牌；
+2. `CONTAINER_SEAL`：开封前柜门和铅封；
+3. `DOOR_OPEN`：开柜现场。
+
+每类固定一张当前有效照片，允许在上传成功后更换。更换失败保留原照片；预览走鉴权下载，不持久化设备临时路径。三类照片全部齐全后才能确认签收。
+
+### 4.4 确认签收
+
+点击确认后，服务端复核柜号、仓库、会话、照片和版本，记录签收人和时间并进入收货。首次开始收货的 `receiving_at` 是整柜唯一实际到仓时间，回传 Admin 清关提柜列表；不能用预约或预计时间代替。
+
+## 5. F29 三类实收操作
+
+### 5.1 通用规则
+
+每次实收都必须：
+
+- 使用当前柜会话；
+- 由业务箱码、入仓码或来源托盘定位唯一计划；
+- 扫描计划已绑定的实物托盘码；
+- 使用稳定幂等键和当前版本；
+- 不超过该计划待收数量；
+- 写入当前客户、仓库、目的仓和库存来源；
+- 返回最新已收、待收和异常信息。
+
+`assigned/mergeAllowed/urgent/mergeHint` 只消费服务端结果。可合托只是现场选择，不改变收货资格，也不是整柜完成门禁。
+
+### 5.2 FBA 散货批量收货
+
+1. 在柜内选择目标入仓码/目的仓分组；
+2. 扫描冻结 SKU 或用于定位分组的业务码；
+3. 扫描计划绑定的实物托盘码；
+4. 输入本次放入托盘的箱数；
+5. 核对本次、累计和剩余箱数；
+6. 提交 bulk 收货；
+7. 继续下一托或下一入仓码。
+
+FBA bulk 不提交 `skuCode` 作为库存归属，服务端按计划明细分配。首次扫业务码只选择分组，不自动多收一箱。超收返回冲突且库存不变化。
+
+### 5.3 OVERSEAS 逐箱收货
+
+1. 扫描国内最终实装的稳定箱唛；
+2. 服务端自动解析唯一入仓码和计划；
+3. 扫描目标实物托盘；
+4. 核对箱码、目的模式和托盘兼容性；
+5. 确认单箱收货；
+6. 已收箱再次扫描必须冲突，不重复入账。
+
+OVERSEAS 必须使用跨区冻结的逐箱事实，禁止改为手工输入批量箱数。
+
+### 5.4 一件代发整托收货
+
+1. 选择柜内一件代发计划；
+2. 扫描国内冻结的来源 `DP` 托盘码；
+3. 查看该托盘所属入仓码、箱数、SKU 和箱唛；
+4. 扫描海外计划绑定的实物托盘；
+5. 使用 `/current/receipts/pallet` 整托确认；
+6. 服务端按来源托盘原子核平全部箱件和 SKU。
+
+禁止逐箱拆收、改写国内托盘成员或按商品名称猜配。一个国内来源托盘失败时整托不落账。
+
+### 5.5 独立收货与合托
+
+- 独立收货：扫描计划分配的新托盘；
+- 合托：仅在 `mergeAllowed=true` 时，扫描同目的仓已使用托盘；
+- 合托后同一实物托盘可以包含多张入仓单，但每票组成数量独立保存；
+- 单票全部收完不要求因“可合托”再执行一次合托动作。
+
+## 6. F30 整柜完成、库存入账与国内回写
+
+### 6.1 完成前检查
+
+点击完成整柜前核对：
+
+- 柜内所有计划 `pendingPackages=0`；
+- FBA 汇总数量、OVERSEAS 箱码和一件代发来源托盘均核平；
+- 每个库存组成已绑定真实托盘和库位；
+- 三类签收照片存在；
+- 通过 `/unload-photos` 保存了非空且不重复的卸柜照片文件 ID；
+- 没有结果不确定的在途命令或版本冲突。
+
+### 6.2 原子完成
+
+服务端在同一事务内：
+
+1. 完成每票 PDA 任务和入仓计划；
+2. 将尾程主状态推进为 `INBOUND_COMPLETED`；
+3. 将 `FIRST_LEG` 在途数量转为海外仓可用/对应状态库存；
+4. 写库存余额；
+5. 写按托盘和入仓单拆分的库存位置；
+6. 写进销存流水和实收快照；
+7. 更新托盘组成；
+8. 创建唯一 `OVERSEAS_CONTAINER_UNLOADED` V1 Outbox。
+
+任一步失败时不能只完成状态、不入库存，或只入库存、不完成任务。相同完成请求重放返回既有结果，不重复增加库存。
+
+### 6.3 国内回写
+
+事件绑定来源头程柜次身份，由服务端冻结，不接受 PDA 拼装。Firstleg 消费后：
+
+- 记录卸柜完成时间；
+- 记录照片上传/完成事实；
+- 计算预计还空时间；正式业务以卸柜完成后 72 小时为准；
+- 更新目的港码头拖车的还空预警；
+- 以事件 ID、哈希和聚合版本防重与防乱序。
+
+此事件不代表已经还柜；实际还柜另行推进 `EMPTY_RETURNED`。
+
+## 7. F31 库存、盘点、移库和托盘
+
+### 7.1 Admin 库存查询
+
+入口：Admin → 海外仓 → 库存管理。
+
+核对维度：客户、实际海外仓、目的仓、入仓单、可用/冻结/占用箱数、SKU 展示、实物托盘和库位。余额唯一业务维度不以托盘为归属；多 SKU 可显示 `MIXED`，完整 SKU 保存在箱唛、实收和流水快照。
+
+列表、详情、汇总和 CSV 必须使用同一权限范围，并默认排除所有数量桶均为零的维度。
+
+### 7.2 托盘与位置
+
+入口：Admin → 海外仓 → 托盘管理。
+
+- 实物托盘和库位是平台公共资源，`customer_id=0`；
+- 资源锁保存真实业务客户范围；
+- 同一托盘可包含多票，每票箱数保存在库存位置组成；
+- 托盘是 PDA 出库作业单位，不是库存所有权单位；
+- 普通入仓只证明某票有多少箱在该托盘，不证明每个箱唛精确位于哪个托盘；
+- 标签只按真实托盘编码补打，不重新生成编号。
+
+### 7.3 PDA 现场查询
+
+入口：海外 PDA → 库存/库位/托盘查询。
+
+扫描稳定业务码后查看服务端最新事实，只展示箱码、托盘码、库位码、仓库名称等业务标识，不以内建 ID 回退。
+
+### 7.4 商品移库
+
+入口：海外 PDA → 商品移库。
+
+1. 扫描来源托盘；
+2. 查看组成和当前版本；
+3. 扫描同仓目标库位；
+4. 核对目标可用；
+5. 提交整托移库；
+6. 服务端原子释放源真实库位并占用目标库位；
+7. 409 冲突后重新扫描，不能用旧版本重试覆盖。
+
+虚拟库位保持 `ACTIVE`；真实库位与托盘同步 `IDLE/OCCUPIED`。
+
+### 7.5 托盘组、拆、换、解绑
+
+PDA 扫描托盘后按服务端返回的 `palletVersion`、`positionVersion` 执行。每次操作必须核对库存组成并使用稳定幂等键；跨服务业务失败走显式补偿，Lastleg 不直接修改 Warehouse Overseas 的 `wh_` 表。
+
+### 7.6 库存盘点
+
+盘点底层支持创建、恢复、计数、提交、幂等和版本冲突处理；当前海外 PDA 工作台不开放入口，因此不能宣称已完成现场页面验收。需要盘点时以正式开放入口、权限 `lastleg:inventory:adjust` 和最终库存流水为准。
+
+## 8. F32 暂扣与解除
+
+### 8.1 新增暂扣
+
+只允许尾程订单已经 `INBOUND_COMPLETED` 且尚未进入出库流程时新增：
+
+1. Admin 打开尾程订单；
+2. 核对当前库存和后续占用；
+3. 填写暂扣原因和必要凭证；
+4. 携带订单版本和幂等键提交；
+5. 写不可变历史并发布暂扣事件。
+
+暂扣只作用于本票，阻断该票排车和出库；不影响同柜其他客户/订单，也不回退入仓计划、实收、库存或主状态。
+
+### 8.2 解除暂扣
+
+风险解除后填写原因并提交当前版本。解除不受“尚未进入出库”这一新增条件限制，但不能抹掉已发生的历史或释放其他子单仍合法持有的库存锁。
+
+## 9. F33 换标、仓储转运和废弃
+
+### 9.1 换标申请
+
+入口：Client → 海外仓服务 → 换标。
+
+1. 客户从本企业可用库存选择目标箱/数量；
+2. 选择换标类型：SKU、箱唛或混合；
+3. 填写旧标、新标和数量；
+4. 提交后系统冻结对应库存，防止重复申请和出库占用；
+5. 生成换标子单，精确状态保存在子单和 `sub_order_status`。
+
+普通入仓没有逐箱唛到托盘的精确快照时，客户填写的我方箱唛是换标作业主键；库存位置只是冻结记账锚点和现场大概位置，不能据此声称箱唛一定在某托。
+
+### 9.2 PDA 换标作业
+
+入口：海外 PDA → 换标收货/执行。
+
+1. 认领任务并进入处理中；
+2. SKU 类型逐条核对旧 SKU、新 SKU 和批准件数；
+3. 箱唛类型扫描仓库唛头和新 FBA 箱唛；
+4. 混合类型分别完成 `MIXED_CARTON`、`MIXED_SKU`，两项齐全才计一箱完成；
+5. 拍摄并上传作业照片；
+6. 必要时按实际来源拆托、换托并记录 `PALLET_BIND`；
+7. 提交后任务进入 `WAIT_REVIEW`，申请进入 `CUSTOMER_CONFIRM_PENDING`。
+
+换标移动只能移动本申请 `hold_packages`，不得解冻为普通可用库存。已生成出库单或开始拣货后禁止随意改绑。
+
+### 9.3 返工与客户确认
+
+平台复核发现问题时，使用专用返工接口携带任务版本、幂等键和必填备注退回。上一轮事实和照片归档，当前轮计数清零；客户已确认后不能退回。
+
+客户核对结果后确认，服务端原子完成复核并释放后续资格。换标主流程相关单据进入 `WAIT_OUTBOUND`；客户确认前不得出库。
+
+### 9.4 仓储转运
+
+入口：Client → 海外仓服务 → 仓储转运。
+
+1. 客户选择本企业可用库存和目标仓/运输要求；
+2. 提交转运申请；
+3. 平台审核通过或驳回；
+4. 通过后冻结对应库存并进入转运出库；
+5. 实际移出和目标收货按转运单、库存流水和资源操作闭环。
+
+转运状态保存在子单，不覆盖尾程主状态 `INBOUND_COMPLETED`。
+
+### 9.5 一件代发货物废弃
+
+废弃只使用能够核对 SKU 和箱唛的一件代发库存：
+
+1. 客户选择箱唛并创建申请；
+2. 箱从 `AVAILABLE` 锁定为 `DISCARD_PENDING`，此时不扣 SKU 箱数；
+3. 有 `lastleg:cargo-discard:approve` 权限的仓库/PDA 人员现场审核；
+4. 拒绝时只释放锁，不扣库存；
+5. 通过时在同一事务调用专用 discard adjustment；
+6. 箱进入 `DISCARDED`，写逐箱流水和唯一幂等键；
+7. 校验扣减前箱数减废弃箱数等于扣减后箱数，且逐箱合计等于申请总数；
+8. 任一失败整体回滚。
+
+## 10. 状态与数据归属
+
+| 维度 | 关键状态 | 说明 |
+|---|---|---|
+| 柜级收货会话 | 待签收/收货中/完成 | 绑定平台账号、柜和实际仓 |
+| 入仓计划/PDA 任务 | 已计划→作业中→完成 | 每票按真实客户隔离 |
+| 尾程主状态 | `INBOUND_PLANNED → INBOUND_COMPLETED` | 子单不能覆盖 |
+| 库存 | `FIRST_LEG` 在途→海外仓库存各数量桶 | 入账必须与状态同事务 |
+| 暂扣 | 有效/解除 | 正交阻断排车出库 |
+| 换标/转运/废弃 | 各自子状态 | 汇总到 `sub_order_status` |
+| 物理资源 | 托盘、库位、锁和版本 | Warehouse Overseas 权威 |
+
+## 11. 异常与恢复
+
+| 场景 | 处理方式 |
+|---|---|
+| `PICKUP_READY` 前看不到柜 | 等待真实节点，不手工绕过候选门禁 |
+| 操作员仓库绑定错误 | 重新绑定并重新登录，旧 Token 失效 |
+| 三类照片上传失败 | 保留旧图/现场重试，不伪造签收 |
+| FBA 超收 | 冲突且库存不变，核对累计/剩余数 |
+| OVERSEAS 重复箱码 | 冲突且不重复入账 |
+| 一件代发来源托盘不符 | 整托拒绝，核对国内冻结快照 |
+| 实收命令超时 | 查询当前实收记录，复用原幂等键 |
+| 任一计划未清零 | 禁止完成整柜，定位具体入仓码 |
+| 完成事务失败 | 状态和库存整体回滚后重试原命令 |
+| 移库/托盘版本冲突 | 重新扫描获取最新版本 |
+| 暂扣票参与排车 | 服务端拒绝，先按权限解除 |
+| 换标一项未完成 | 混合单不计整箱完成 |
+| 换标被退回 | 展示备注，清理设备草稿后按新轮返工 |
+| 废弃审批失败 | 锁定和扣减整体回滚，不产生半套流水 |
+
+## 12. 阶段完成判定
+
+主链完成必须满足：
+
+- [ ] 柜号由正确仓库操作员认领
+- [ ] 国内五类证据可对照，海外三类签收照片齐全
+- [ ] 实际到仓时间来自首次收货会话
+- [ ] FBA、OVERSEAS、一件代发均按对应模式实收
+- [ ] 每票 `pendingPackages=0`
+- [ ] 库存余额、位置、流水和托盘组成数量一致
+- [ ] 入仓计划和 PDA 任务完成
+- [ ] 尾程主状态为 `INBOUND_COMPLETED`
+- [ ] 卸柜 Outbox 唯一且国内幂等回写成功或可重试
+- [ ] 重放任何实收/完成命令不会重复库存
+
+库内服务完成以各子单独立判断；它们不改变已经成立的 `INBOUND_COMPLETED`，但未完成的冻结、暂扣或占用必须继续阻断阶段六相应库存。
+
+## 13. 易用性与数据流评审问题
+
+1. 柜级认领前是否需要把计划/资源缺口直接展示为可操作诊断？
+2. 国内五类照片与海外三类照片是否应提供左右对照和异常快捷登记？
+3. 三类收货模式是否需要在页面用颜色/图标强提示，防止操作员走错批量或逐箱入口？
+4. FBA 首次扫码只选分组、不计数的规则是否足够直观？
+5. 合托提示是否应同时展示托盘已有客户、入仓单组成和容量风险？
+6. 整柜完成前是否需要按入仓码显示“剩余几箱/哪几个来源托盘”？
+7. 卸柜完成后 72 小时还空预警应由谁接收、何时升级？
+8. 库存余额、库存位置、托盘组成和箱唛明细是否需要统一钻取入口？
+9. 当前盘点入口隐藏，正式业务发生账实差异时由哪个可见流程处理？
+10. 暂扣原因、换标冻结、转运占用和废弃锁箱是否应统一显示“不可用数量来源”？
+11. 换标混合任务双 Tab 的完成条件是否需要总进度和缺项提示？
+12. 废弃从“申请锁定”到“现场实际扣减”的状态文案是否足够清楚？
+
+## 14. 阶段六交接包
+
+交给阶段六“海外排车、出库、派送与回写”的输入包括：
+
+- `INBOUND_COMPLETED` 尾程订单和实际海外仓；
+- 客户、入仓单、目的仓和可用库存余额；
+- 每个实物托盘的多票组成、库位和版本；
+- 一件代发来源托盘、SKU 和箱唛可用状态；
+- 有效暂扣、换标、转运、废弃及其他库存锁；
+- 可出库数量、已占用数量和相应库存流水；
+- 客户/平台要求的派送地址、FBA 仓和服务属性。
+
+## 15. 事实来源
+
+- `docs/海外仓业务/README.md`
+- `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
+- `apps/pda-overseas-uniapp/AGENTS.md`
+- `apps/pda-overseas-uniapp/src/pages/operation/operation.vue`
+- `apps/pda-overseas-uniapp/src/pages/pallet/pallet.vue`
+- `apps/pda-overseas-uniapp/src/pages/move/move.vue`
+- `apps/pda-overseas-uniapp/src/pages/relabel/relabel.vue`
+- `baiyue-firstleg/lastleg-service/AGENTS.md`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/pda/`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/relabel/`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/transfer/`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/discard/`
+- `baiyue-firstleg/warehouse-overseas-service/AGENTS.md`

头程到尾程分阶段流程/阶段六-海外排车出库派送与回写.md

@@ -0,0 +1,310 @@
+# 阶段六：海外排车、出库、派送与最终回写
+
+> 对应全景流程：F34～F40。  
+> 阶段起点：尾程订单已经 `INBOUND_COMPLETED`，存在可用库存且没有阻断本次履约的暂扣或库存锁。  
+> 阶段终点：派送完成并带签收证据，跨区回写国内；对应国内入库单为 `DELIVERED`，同一 Order 全部有效入库单完成后 Order 为 `COMPLETED`。  
+> 出库、排车、派送和异常是独立子状态，不覆盖尾程主状态。
+
+## 1. 阶段目标和边界
+
+本阶段完成海外仓最后一段实物与数据闭环：
+
+1. 从真实库存生成智能预排和正式排车；
+2. 发车前将排车转换为车辆级出库单和按目的地拆分的派送单；
+3. PDA 按托盘拣货、扣减库存并在满足组合门禁后发车；
+4. 执行一件代发、换标、转运、退货等独立出库任务；
+5. 上传签收资料并自动完成派送；
+6. 对派送异常执行来源受控的退回入仓；
+7. 保存客户回访并将完成事实回写国内订单。
+
+“扫码拣货”“出库”“发车”“开始派送”“签收完成”是不同节点。库存只在成功的 PDA 拣货/出库事务按契约扣减，发车不能再次扣库存。
+
+## 2. 角色和终端
+
+| 角色 | 终端 | 主要操作 |
+|---|---|---|
+| 海外调度 | Admin | 智能预排、排车编辑/取消、转派送、维护车辆与预约 |
+| 海外仓 PDA 操作员 | 海外 PDA | 排车拣货、独立出库拣货、完成任务、发车 |
+| 派送运营 | Admin | 开始派送、维护允许状态、上传 BOL/签收资料 |
+| 企业成员 | Client | 查看本企业派送单、状态和允许下载的签收资料 |
+| 异常处理员 | Admin | 创建异常、选择原出库事实、处理退回入仓 |
+| 客服 | Admin | 客户回访、记录结果和附件 |
+| Lastleg | 后端 | 排车、出库、派送、异常、库存命令和完成 Outbox 权威 |
+| Firstleg/Order | 国内后端 | 幂等消费完成事件，推进 `DELIVERED/COMPLETED` |
+
+PDA 只调用 `/api/pda/**` 专用接口，客户和仓库由 Token、Gateway 和服务端解析；派送与客户回访由 Admin/Client 承载，不进入 PDA。
+
+## 3. 出库资格前置检查
+
+- 尾程订单已 `INBOUND_COMPLETED`；
+- 实际海外仓、目的仓和客户归属明确；
+- 库存余额、位置、托盘组成和可用箱数一致；
+- 无有效暂扣；
+- 换标需要客户确认的，已完成确认；
+- 转运、退货或废弃的库存锁与本次出库不冲突；
+- 一件代发箱唛/SKU 状态为可用；
+- 实物托盘和库位版本仍有效；
+- 车辆、车队和目的地使用有效主数据。
+
+任何不确定的库存、锁或归属查询都应失败关闭，不能通过前端勾选强行出库。
+
+## 4. F34 智能预排和排车维护
+
+### 4.1 候选和草稿锁
+
+入口：Admin → 海外仓 → 排车管理/智能预排。
+
+候选来自真实入仓计划、已收托盘或具备资格的换标库存。平台可跨客户查看候选，但创建时服务端从所选托盘解析并校验唯一客户范围和唯一海外仓。
+
+1. 创建随机草稿；
+2. 搜索并选择托盘；
+3. 托盘加入草稿时立即按操作人和草稿标识加锁；
+4. 移除托盘或关闭草稿时释放；
+5. 草稿超时后锁自动失效；
+6. 其他草稿/正式排车不能重复占用同一库存。
+
+### 4.2 预排创建
+
+1. 选择车型；
+2. 核对托位、箱数、重量、目的 FBA 仓或私人地址；
+3. 查看服务端汇总路线；
+4. 点击预排；
+5. 服务端重查托盘、库存、锁和客户范围；
+6. 草稿锁原子转换为正式排车锁；
+7. 生成排车单，初始为 `PENDING_DEPARTURE`。
+
+路线由已排托盘目的仓编码去重并稳定排序生成，预排和普通编辑都不接收人工路线文本。
+
+### 4.3 排车编辑和取消
+
+可维护：车牌、司机、电话、车队、预计发车/到达、FBA 预约和车辆预约。普通编辑不能修改排车状态。
+
+未执行、未产生不可逆拣货事实的排车可取消并释放正式锁。开始拣货后不能用取消恢复库存或抹掉作业历史。
+
+## 5. F35 排车转派送
+
+允许状态：`PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART`，且必须早于发车。
+
+入口：Admin → 排车详情 → 转派送。
+
+1. 填写预计派送时间；
+2. 选择派送方式、提货/装车类型；
+3. 选择车队/快递、车辆和预约；
+4. 维护费用来源和必要备注；
+5. 核对所有托盘都已经真实入仓且仍由本排车锁定；
+6. 二次确认后提交。
+
+服务端幂等生成：
+
+- 一张车辆级 `WAIT_OUTBOUND` 出库单；
+- 按目的 FBA 仓或私人地址拆分的一张或多张 `WAIT_DELIVERY` 派送单；
+- 派送费用只发布一次；
+- BOL 和签收资料绑定拆分后的单仓派送单。
+
+相同排车重放返回既有单据，不重复生成出库、派送或费用。
+
+## 6. F36 排车 PDA 拣货和发车
+
+### 6.1 打开任务
+
+入口：海外 PDA → 排车拣货。
+
+1. 查看当前 Token 仓库的任务；
+2. 打开排车单，核对排车号、车辆、目的地、托盘和计划箱数；
+3. 页面使用服务端返回的状态和版本，不按本地草稿推断可操作性。
+
+### 6.2 扫托盘拣货
+
+1. 扫描托盘业务码；
+2. 服务端校验托盘属于本排车、当前仓库和有效库存位置；
+3. 校验计划箱数和托盘组成；
+4. 在成功事务中完成库存分配、拣货和相应出库扣减；
+5. 写库存流水、任务进度和幂等记录；
+6. 重复同一命令返回原结果，不再次扣减。
+
+部分出库若不能整托核平，应先通过合法拆托或组成明细处理，不能按 FIFO 猜测某票来源。
+
+### 6.3 完成拣货
+
+全部托盘和箱数核平后，PDA 任务进入 `COMPLETED`，排车进入 `READY_TO_DEPART`。存在漏托、数量差异、暂扣或库存版本冲突时不能完成。
+
+### 6.4 发车门禁
+
+PDA 只使用详情返回的 `canDepart` 和 `departBlockReason`。服务端至少校验：
+
+- 车辆信息完整；
+- 拣货任务完成且箱数核平；
+- 排车为 `READY_TO_DEPART`；
+- 平台已经转派送；
+- 关联出库单仍为 `WAIT_OUTBOUND`。
+
+发车成功后排车进入 `DEPARTED`，出库单进入 `OUTBOUNDED`，释放相应托盘锁。发车只推进履约事实，不再次扣库存。
+
+## 7. F37 独立出库任务
+
+### 7.1 通用生命周期
+
+独立出库通常按 `WAIT_PICK → PICKING → PICKED → OUTBOUNDED` 推进。只有尚未开始的 `WAIT_PICK/WAIT_OUTBOUND` 可以取消；作业开始后不能通过取消自动恢复库存。
+
+PDA 操作：打开本仓任务 → 扫箱/托盘 → 核对来源 → 幂等提交 → 数量核平 → 完成出库。
+
+### 7.2 一件代发出库
+
+- 候选必须已完成入仓，仍有可用箱唛、SKU 和库存位置；
+- 创建时必须解析为唯一客户和唯一仓，禁止跨客户/跨仓一单；
+- 可逐箱扫描；
+- 扫 `DP` 托盘码时原子拣取当前任务内该托全部剩余箱件和 SKU；
+- 任一库存明细失败时整托回滚；
+- 完成后箱唛、SKU 汇总、库存位置和流水必须核平。
+
+### 7.3 换标、转运和退货出库
+
+| 类型 | 前置 | 作业依据 | 结果 |
+|---|---|---|---|
+| 换标出库 | 仓库作业完成且客户确认 | 换标后箱唛、托盘和改绑快照 | 换标单完成、出库 `OUTBOUNDED` |
+| 仓储转运 | 申请审核通过 | 冻结来源托盘和箱数 | 转运出库完成 |
+| 退货出库 | 退货箱/SKU 可用 | 冻结退货库存 | 退货库存扣减、出库完成 |
+
+退货出库不能与派送异常退回库存恢复混用；前者消费退货库存，后者恢复原出库来源库存。
+
+## 8. F38 派送和签收
+
+派送单状态：`WAIT_DELIVERY → DELIVERING → DELIVERED`，异常情况下可为 `REJECTED/CANCELLED/RETURNED`。
+
+### 8.1 查看和开始派送
+
+Admin/Client 按权限查看拆分后的单仓派送单、目的地、车辆/快递、预约、BOL 和状态历史。客户只能查看本企业。
+
+平台核对实际出库后开始派送，使单据进入 `DELIVERING`。不能仅因排车发车就把所有拆分派送单自动视为签收。
+
+### 8.2 上传签收资料并完成
+
+1. 打开具体派送单；
+2. 上传该目的仓对应的签收文件/照片；
+3. 核对文件归属、类型和有效性；
+4. 保存签收资料；
+5. 系统在同一业务流程自动将该派送单推进为 `DELIVERED`；
+6. 按关联 `sourceInboundId` 写 `OVERSEAS_DELIVERY_COMPLETED` Outbox。
+
+不提供脱离签收资料的人工“完成派送”按钮。同车不同 FBA 仓的派送单互不代完成。
+
+## 9. F39 派送异常退回
+
+入口：Admin → 异常订单。
+
+1. 从原派送单创建异常，状态为 `PENDING`；
+2. 退回明细只能从原出库拣货事实选择，不能自由填写 SKU 或数量；
+3. 开始处理后进入 `PROCESSING`；
+4. 选择服务端校验的真实退回仓、托盘和库位；
+5. 上传 `OVERSEAS_EXCEPTION_EVIDENCE`；
+6. 现场确认退回实收；
+7. 服务端按原出库来源恢复库存并写 `RETURN_STOCK_IN` 流水；
+8. 同事务完成异常并将派送置为 `RETURNED`。
+
+只有待处理异常可以取消。库存恢复、异常完成和派送退回任一步失败时整体回滚，不留下“派送已退回但库存未恢复”的半套结果。
+
+## 10. F40 客户回访和国内最终回写
+
+### 10.1 客户回访
+
+入口：Admin → 客户回访。
+
+客服选择已完成或需跟进的业务单，记录联系时间、方式、结果、问题、后续动作和附件。回访是服务闭环资料，不替代签收、异常或库存事实。
+
+### 10.2 跨区完成事件
+
+每张实际完成的派送单在业务事务内写 Outbox。Event Bridge 跨区投递后，Firstleg：
+
+1. 校验内部身份、事件版本、ID 和 Payload 哈希；
+2. 校验来源订单、来源入仓单、入仓码和 FBA 目的仓；
+3. 防止同车其他目的仓事件误完成本票；
+4. 将对应国内入库单从 `LOADED` 推进为 `DELIVERED`；
+5. 写状态历史和事件消费记录。
+
+### 10.3 Order 最终完成
+
+Firstleg 检查同一 Order 的全部有效入库单。只有全部都为 `DELIVERED` 时，才调用 Order 推进交易状态为 `COMPLETED`。
+
+部分装载形成的余量子单、另一柜或另一目的仓尚未完成时，Order 不能提前完成。重复事件不得重复推进、重复写历史或重复生成费用。
+
+## 11. 状态和数据流
+
+```text
+INBOUND_COMPLETED + 可用库存
+  → 草稿锁 → 正式排车锁 → PENDING_DEPARTURE
+  → 转派送：车辆级 WAIT_OUTBOUND + 目的地级 WAIT_DELIVERY
+  → PDA 扫托扣库存 → READY_TO_DEPART
+  → 发车：DEPARTED + OUTBOUNDED
+  → 派送：DELIVERING → 签收资料 → DELIVERED
+  → OVERSEAS_DELIVERY_COMPLETED
+  → 国内入库单 DELIVERED
+  → 同一 Order 全部完成后 COMPLETED
+```
+
+尾程主状态保持 `INBOUND_COMPLETED`，排车、出库、派送和异常精确状态分别保存在各自单据并汇总到 `sub_order_status`。
+
+## 12. 异常与恢复
+
+| 场景 | 处理方式 |
+|---|---|
+| 托盘被其他草稿锁定 | 不可选择，等待释放或超时 |
+| 预排时库存变化 | 服务端拒绝，刷新候选重排 |
+| 排车已开始仍取消 | 拒绝，走对应异常流程 |
+| 未转派送就发车 | `canDepart=false`，Admin 先完成转派送 |
+| PDA 扫错托盘 | 拒绝且库存不变 |
+| 扫码超时 | 保留幂等键，查询服务端任务后重试 |
+| 整托一项失败 | 整托回滚，不部分扣库存 |
+| 车辆资料缺失 | `departBlockReason` 明示缺项 |
+| 签收资料上传失败 | 派送保持未完成，重新上传 |
+| 一车多目的地仅一单签收 | 只完成对应派送单 |
+| 异常退回数量超原拣货 | 拒绝，不允许自由扩量 |
+| 退回库存事务失败 | 异常/派送状态同步回滚 |
+| 国内消费暂时失败 | 保留 Outbox/Inbox 受控重试，不手工完成国内单 |
+| 完成事件重复 | 返回既有结果，不重复历史或费用 |
+
+## 13. 全流程最终完成判定
+
+- [ ] 排车候选来自真实、可用且未被其他业务占用的库存
+- [ ] 草稿锁、正式锁和取消/完成释放均可追溯
+- [ ] 排车路线由实际目的地生成
+- [ ] 转派送只发生一次且早于发车
+- [ ] PDA 拣货数量、托盘组成、库存扣减和流水一致
+- [ ] 发车时服务端 `canDepart=true`
+- [ ] 发车没有重复扣库存
+- [ ] 每个目的地拥有独立派送单和签收资料
+- [ ] 派送完成只由有效签收资料触发
+- [ ] 异常退回时原出库来源、恢复库存和证据完整
+- [ ] 完成事件按来源入仓单跨区幂等回写
+- [ ] 国内入库单为 `DELIVERED`
+- [ ] 同一 Order 全部有效入库单完成后才为 `COMPLETED`
+- [ ] 客户可查询本企业最终状态和允许的签收资料
+
+## 14. 易用性与数据流评审问题
+
+1. 智能预排候选是否应直接显示不可选原因、锁定人和锁过期时间？
+2. 车型、托位、箱数、重量和目的仓能否提供装载风险提示？
+3. 转派送为何必须早于发车，页面是否在拣货阶段持续提示？
+4. 排车、出库、派送三个编号和状态是否需要统一时间线和相互跳转？
+5. PDA 扫码即扣库存的关键动作是否需要更强确认和撤销边界说明？
+6. `canDepart/departBlockReason` 能否直接跳转到车辆、拣货或转派送缺项？
+7. 一件代发逐箱与整托两种模式如何防止操作员重复选择？
+8. 一车多目的仓时，签收资料上传如何降低绑错派送单的风险？
+9. 派送异常是否需要标准原因、责任方、时限和赔付关联？
+10. 退回入仓是否需要 PDA 专用入口，而不是只依赖后台操作？
+11. 跨区回写延迟时，海外“已签收”和国内“未完成”如何向客服解释？
+12. Order `COMPLETED` 前是否需要展示仍未完成的具体子入库单/柜次/目的仓？
+
+## 15. 事实来源
+
+- `docs/海外仓业务/README.md`
+- `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
+- `apps/pda-overseas-uniapp/AGENTS.md`
+- `apps/pda-overseas-uniapp/src/pages/dispatch/dispatch.vue`
+- `apps/pda-overseas-uniapp/src/pages/outbound/outbound.vue`
+- `baiyue-firstleg/lastleg-service/AGENTS.md`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/delivery/`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/exceptionorder/`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/customervisit/`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/OverseasDeliveryCompletedConsumer.java`
+- `baiyue-firstleg/order/AGENTS.md`

头程到尾程分阶段流程/阶段四-海运目的港与尾程计划.md

@@ -0,0 +1,388 @@
+# 阶段四：海运、目的港与尾程入仓计划
+
+> 对应全景流程：F24～F27。  
+> 阶段起点：柜次已确认国内离仓，存在实际 `DEPARTED_WAREHOUSE` 节点和可查询的真实订舱/柜次。  
+> 阶段终点：跨区尾程订单完整生成，整柜每票入仓计划及托盘/库位资源已生成或有明确资源失败待办，订单进入 `INBOUND_PLANNED`。  
+> 本阶段同时维护船舶/货柜轨迹和尾程业务准备，但两类状态不得互相冒充。
+
+## 1. 阶段目标和边界
+
+本阶段完成四条相互关联但独立的链路：
+
+1. 从国内离仓开始查询并保存十个标准船节点；
+2. 管理目的港清关、海外码头车队、提柜、预计到仓和还空；
+3. 将国内最终实装快照可靠投递到海外区域并创建尾程订单；
+4. 按整柜维护每票计划并转换为可执行的海外入仓计划和资源。
+
+阶段四不执行海外仓实收、库存入账、库内服务、排车或出库。`PICKUP_READY` 只表示货柜已清关可提，并开放海外 PDA 待收柜候选；它不表示已经到仓或已经产生库存。
+
+## 2. 角色、终端和系统边界
+
+| 角色/系统 | 终端 | 主要职责 |
+|---|---|---|
+| 船期操作员 | Admin | 查看查询任务、标准节点、异常与查询历史，必要时人工补录 |
+| 目的港操作员 | Admin | 维护清关/DO/PU、选择海外车队、发提柜邮件、确认提柜和还柜 |
+| 海外仓计划员 | Admin | 维护整柜预计到仓、每票托数与作业属性、执行柜级转换 |
+| 企业成员 | Client | 查看本企业尾程订单和允许展示的船期/计划进度 |
+| Firstleg | 后端 | 拥有查询任务、标准节点、目的港码头拖车和装柜完成 Outbox |
+| Integration Service | 后端 | 调用船司/轨迹供应商，解析并返回标准化结果，不保存业务主数据 |
+| Event Bridge | 跨区通道 | 版本化、认证地投递业务事件 |
+| Lastleg | 海外后端 | Inbox 幂等消费、尾程订单、计划、在途库存和海外业务状态 |
+| Warehouse | 国内主数据 | 海外共享仓、FBA 目的仓和供应商主档权威 |
+| Warehouse Overseas | 海外资源 | 海外库位、实物托盘和资源锁 |
+
+所有浏览器海外接口经 `gateway-overseas/`。国内 Auth 仍是账号和 Token 签发方；跨区业务写入通过内部身份、Inbox/Outbox 和事件契约完成，不允许浏览器伪造跨区事件。
+
+## 3. 阶段前置检查
+
+- 柜次存在真实集装箱号、订舱、提单号和国内离仓事实；
+- 装柜完成事件包含最终实装订单、入仓单、目的类型、箱数及必要托盘/SKU/箱唛快照；
+- 国内四步照片和铅封证据已经冻结；
+- 接柜海外仓是 Warehouse 中 `ACTIVE + OVERSEAS + RECEIVING` 的平台共享物理仓；
+- FBA 目的仓是 Warehouse 有效公共主档，不能用接柜仓或国内仓代替；
+- 船司/轨迹查询标识足以唯一指向目标订舱和柜次；
+- 同柜订单的预计到仓事实必须能够收敛为一个柜级日期。
+
+## 4. F24 海运十节点
+
+### 4.1 查询任务创建
+
+国内出仓确认事务幂等创建 `CarrierScheduleQuery`。任务必须绑定真实订舱、柜次以及可用的船司、船名航次、提单号或柜号，不创建脱离业务单据的孤立轮询任务。
+
+首个实际节点由国内出仓写入：
+
+```text
+10 DEPARTED_WAREHOUSE       已离开国内仓
+20 AT_ORIGIN_PORT           已到起运港
+30 LOADED_ON_VESSEL         已装船
+40 DEPARTED_ORIGIN_PORT     已离开起运港
+50 IN_TRANSIT               海运途中
+60 ARRIVED_DESTINATION_PORT 已到目的港
+70 DISCHARGED_FROM_VESSEL   已卸船
+80 PICKUP_READY             已清关、可提柜
+90 PICKED_UP                已提柜
+100 EMPTY_RETURNED          已还空柜
+```
+
+### 4.2 自动查询操作与频率
+
+入口：Admin → 船期/货柜详情 → 船节点查询。
+
+平台查看：查询任务状态、当前最新实际节点、预计节点、最近成功时间、下次允许时间、供应商、失败原因、异常事实和每次尝试历史。
+
+正常查询槽位按北京时间每天 `09:00`、`12:30`、`16:00`。调度器每分钟只扫描已到期任务，不代表每分钟调用船司。
+
+- 成功、无变化、需人工或永久失败：进入下一固定槽位；
+- 技术性可重试失败：当前槽内按 15/30 分钟退避，含首次最多三次；
+- 重试不得跨越下一正常槽位；
+- 服务恢复后错过的槽位直接顺延，不集中补打供应商；
+- 实际 `EMPTY_RETURNED` 后任务停止。
+
+### 4.3 节点时间和推进规则
+
+| 时间 | 含义 | 推进最新实际节点 |
+|---|---|---|
+| `estimatedAt` | 预计发生时间 | 否 |
+| `actualAt` | 已确认实际时间 | 是 |
+| `observedAt` | 本次观测到事实的时间 | 否 |
+| `createdAt` | 平台写入时间 | 否 |
+
+只有带 `actualAt` 的标准节点可以推进。节点按序号单调前进；迟到的较早节点可作为历史保存，但不能回退当前节点。供应商缺少中间节点时保持缺失，不能自动补齐。
+
+同一供应商事件按稳定 `providerEventId` 幂等；无原生 ID 时用稳定字段组合生成哈希。每条事实保留原始节点编码、来源、地点、观测时间和原始响应哈希，但业务表不保存含密钥的完整网页。
+
+### 4.4 异常事实
+
+以下异常与正常节点并行保存：
+
+- `CUSTOMS_HOLD`：海关扣留；
+- `TERMINAL_HOLD`：码头/堆场扣留；
+- `DOCUMENT_HOLD`：单证问题；
+- `UNKNOWN_HOLD`：其他无法分类扣留。
+
+异常不能覆盖最近正常节点。解除时新增解除事实，不删除原异常。
+
+### 4.5 人工补录
+
+供应商缺节点、网页需要人工验证或业务已有可信凭证时，有权限人员可在查询详情补录：
+
+1. 选择标准节点；
+2. 填写实际时间，预计事实不能冒充实际时间；
+3. 填写地点、来源说明和必要凭证；
+4. 核对节点不会回退当前实际进度；
+5. 携带版本和幂等键提交；
+6. 查看历史中来源标识为人工。
+
+人工补录 `PICKUP_READY` 会通过跨区事实开放海外 PDA 柜号候选；人工补录 `EMPTY_RETURNED` 会停止任务，因此必须使用真实还柜事实。
+
+## 5. F25 目的港清关、车队、到仓和还空
+
+### 5.1 清关和文件
+
+入口：Admin → 清关提柜。
+
+1. 按柜号、提单号、目的港和节点筛选；
+2. 核对目的港清关资料、DO 和 PU 当前版本；
+3. 上传或替换合法文件引用；
+4. 将线下清关结果反映为可信业务事实；
+5. 清关完成、码头明确可提后，确保实际 `PICKUP_READY` 已进入标准节点链。
+
+清关资料状态和标准船节点有关联但不互相覆盖。只有明确可提事实才能推进 `PICKUP_READY`。
+
+### 5.2 选择海外码头车队
+
+1. 选择 Warehouse 中 `ACTIVE/TRUCKING/OVERSEAS` 供应商；
+2. 服务端读取供应商名称和邮箱快照，不能用自由文本绕过主档；
+3. 首次选择车队只保存选择，不自动发信；
+4. 操作员确认后发送提柜请求邮件；
+5. 邮件进入顺序发送队列，`SENT` 只表示 SMTP 接受，不代表车队已读或已执行；
+6. 失败邮件保留原因，人工确认后重试。
+
+更换车队时，事务内同时冻结旧车队取消邮件和新车队提柜邮件，并按顺序投递。同一车队重复选择不重复发信。
+
+### 5.3 实际提柜
+
+车队从码头取得重箱后，目的港操作员确认实际提柜时间。服务端推进实际 `PICKED_UP`，但不创建海外库存、不替代 PDA 到仓收货。
+
+### 5.4 预计到仓
+
+清关提柜列表中的“预计到仓”由平台维护：
+
+1. 输入整柜预计抵达接柜仓的日期/时间；
+2. 按 `sourceContainerBookingId` 锁定整柜；
+3. 原子同步柜内全部尾程订单的 `estimated_warehouse_at`；
+4. 记录版本、操作人和幂等历史；
+5. 任一入仓计划已生成后锁定，不再允许修改。
+
+预计到仓不能使用订单创建时间、预计到港时间或当前时间替代。同柜订单缺失或日期不一致时，阶段四的计划转换必须阻断。
+
+### 5.5 实际到仓与还空
+
+实际到仓不由 Admin 手填，也不取预约提柜时间；只取海外 PDA 首次开始收货会话的 `receiving_at`。因此本阶段只能展示“待实际到仓”，真实时间在阶段五产生。
+
+海外 PDA 完成卸柜后，跨区 `OVERSEAS_CONTAINER_UNLOADED` 事件回到 Firstleg。预计报空/还空截止按卸柜完成时间加 72 小时计算并产生预警。
+
+真实还柜可由供应商节点或有权限人员确认：
+
+- 时间不得早于卸柜完成时间；
+- 若已有实际提柜时间，也不得早于提柜；
+- 无需为了还柜补造车队、预约或提柜事实；
+- 首次命令可以版本 0 创建记录，车队字段允许为空；
+- 成功后推进实际 `EMPTY_RETURNED`、解除预警并停止查询任务。
+
+目的港码头拖车、国内订舱级拖车和海外配送排车是三张不同业务单，不得复用状态或费用。
+
+## 6. F26 跨区尾程建单
+
+### 6.1 国内生产事件
+
+Firstleg 在装柜完成后按最终实装生成 `FIRST_LEG_LOADING_PLAN_COMPLETED` V3：
+
+- 信封包含事件 ID、版本、来源区域、聚合版本和 Payload 哈希；
+- Payload 包含来源柜次/计划/真实柜号和每票最终实装；
+- FBA 可以按实装箱数冻结，不伪造逐箱作业账；
+- `OVERSEAS` 必须逐箱冻结箱码事实；
+- 一件代发必须携带一个或多个不可变来源托盘，以及每托 SKU、箱数、数量和箱唛；
+- 物理柜五类国内装柜照片引用一并冻结。
+
+Outbox 可重复投递，不能因网络失败直接丢事件或在事务外临时拼装 Payload。
+
+### 6.2 Event Bridge 投递
+
+Event Bridge 校验允许的事件类型、版本、来源/目标区域和内部服务身份后投递 Lastleg。IAM 安全事件使用独立入口，不能交给装柜完成消费者。
+
+### 6.3 Lastleg Inbox 消费
+
+Lastleg 消费步骤：
+
+1. 常量时间校验内部令牌；
+2. 校验事件 ID、版本、来源区域、客户和必要字段；
+3. 校验 Payload 哈希；
+4. 以事件 ID、哈希和来源入仓单唯一约束防重；
+5. 在一个事务内处理整柜全部订单；
+6. 任一票失败时整柜回滚，不留下半套订单；
+7. 重放相同事件返回既有结果。
+
+### 6.4 尾程订单和在途库存
+
+成功消费后：
+
+- 同一实际集装箱共享业务尾程单号；
+- 每个 `sourceInboundId` 独立生成一条 `ll_order`；
+- 保存来源订单、入仓码、客户、接柜仓、目的仓和货物冻结快照；
+- 主状态为 `PENDING_ASSIGNMENT`；
+- 生成 `FIRST_LEG` 在途库存；
+- 计划生成前以真实来源入仓码作为库存展示快照；
+- 事件只建订单，不自动生成入仓计划。
+
+一件代发额外生成来源托盘、SKU、箱唛档案和在途库存事实；海外实物托盘资源仍由 Warehouse Overseas 分配，不覆盖国内来源托盘快照。
+
+## 7. F27 尾程计划维护和整柜转换
+
+### 7.1 柜级工作台
+
+入口：Admin → 海外仓 → 尾程订单 → 柜级工作台。
+
+列表使用 `/container-summaries` 按稳定 `sourceContainerBookingId` 服务端聚合，不允许用当前订单分页在浏览器拼柜。列表至少展示：
+
+- 柜号、来源柜次和预计到仓；
+- 订单数、已建计划数、待建计划数；
+- `allPlansReady`；
+- `resourcePendingPlanCount`；
+- 接柜仓、目的仓分组和异常摘要。
+
+已完成转换的柜仍保留供查询和允许范围内维护。详情接口返回柜内全部订单和计划，不受列表分页截断。
+
+### 7.2 单票计划维护
+
+对柜内每票填写：
+
+- 计划托数；
+- 托盘类型；
+- 是否已分配；
+- 是否允许合托；
+- 是否加急；
+- 现场备注。
+
+入仓码、实际接柜仓和预计到仓只读。保存时校验订单版本、客户范围、Warehouse 当前仓库主档和幂等键。
+
+“可合托”只给阶段五现场提供选择，不是实收或完成门禁：合托时扫描同目的仓已使用托盘，独立收货扫描新托盘。
+
+### 7.3 普通货与一件代发托盘规则
+
+普通散货：
+
+- 保留头程已经冻结并跨区传入的托盘码；
+- 海外计划托数不得少于已有托盘码数量；
+- 海外装托密度不同导致托数增加时，在同柜、同 FBA 仓连续补码；
+- 预览分别展示头程已有数、海外补充数和最终托数。
+
+一件代发：
+
+- 必须逐托沿用国内封托的 `DP` 托盘码和每托箱数；
+- 不允许重算托数、重分配箱子或改写 SKU/箱唛；
+- 无法绑定真实资源时禁止保存半成品计划。
+
+### 7.4 自动触发与柜级预览
+
+单票柜保存完整计划后立即尝试生成资源；多票柜在最后一票计划齐全时自动触发整柜资源生成。
+
+转换前读取服务端预览，核对：
+
+- FBA、一件代发、私人地址等分组；
+- 每票来源托数、补充托数和最终托数；
+- 柜内计划是否全部就绪；
+- 接柜仓、预计到仓是否一致；
+- 阻断项；
+- `snapshotVersion` 和 `snapshotHash`。
+
+`pendingPlanCount` 表示尚未建立完整计划；`resourcePendingPlanCount` 只表示自动物化资源失败，需要按原柜级入口重试，不能把它当作正常人工步骤。
+
+### 7.5 确认转换
+
+系统执行柜级 Saga：
+
+1. 以 `sourceContainerBookingId` 锁柜；
+2. 用版本/哈希重新计算预览；
+3. 向 Warehouse Overseas 批量预留真实托盘、库位和资源锁；
+4. 为柜内每票独立生成入仓计划；
+5. 本地事务确认计划并绑定资源；
+6. 尾程订单进入 `INBOUND_PLANNED`；
+7. `FIRST_LEG` 在途库存展示编号从来源入仓码收口为各自 `planNo`。
+
+整批转换原子且幂等：相同命令重放不生成第二批计划或资源；本地失败只补偿尚未确认的远端资源；远端确认失败的重放只重试确认。
+
+## 8. 状态、编号与数据归属
+
+| 维度 | 关键状态/编号 | 权威系统 |
+|---|---|---|
+| 船节点任务 | ACTIVE/人工/失败/`STOPPED` | Firstleg |
+| 最新实际节点 | 十节点之一 | Firstleg |
+| 目的港码头拖车 | 车队、提柜、卸柜、还柜 | Firstleg |
+| 尾程主单 | `PENDING_ASSIGNMENT → INBOUND_PLANNED` | Lastleg |
+| 入仓计划 | `planNo`、计划属性、资源绑定 | Lastleg |
+| 在途库存 | `FIRST_LEG` | Lastleg |
+| 海外实物资源 | 托盘、库位、锁 | Warehouse Overseas |
+| 仓库/目的仓/供应商 | 业务主档 | Warehouse |
+
+`containerNo` 是真实集装箱号；`sourceContainerBookingId` 是跨区稳定柜聚合键；`inboundCode` 永远保存真实来源入仓码；`planNo` 只在尾程入仓计划生成后产生。任何页面不得以内建数据库 ID 回退展示业务编号。
+
+## 9. 异常与恢复
+
+| 场景 | 系统行为 | 操作处理 |
+|---|---|---|
+| 船司无变化 | 保存查询尝试，进入下一槽位 | 无需伪造节点 |
+| 船司技术失败 | 15/30 分钟受控重试 | 查看失败原因，必要时人工 |
+| 只有预计到港 | 保存预计事实，不推进实际节点 | 等待真实节点 |
+| 较早节点迟到 | 保存历史，不回退当前节点 | 无需修改最新进度 |
+| 清关/单证扣留 | 单独保存异常 | 处理后新增解除事实 |
+| 车队邮箱无效 | 阻断发信/换队 | 修正 Warehouse 供应商资料 |
+| 事件重复投递 | 返回既有消费结果 | 不人工删 Inbox |
+| 事件哈希不同 | 冲突失败 | 核对生产端版本和 Payload |
+| 柜内任一票事件失败 | 整柜消费回滚 | 修复数据后重放原事件 |
+| 预计到仓缺失/不一致 | 阻断计划生成 | 在计划前按柜统一维护 |
+| 计划版本过期 | 转换冲突 | 刷新预览，重新确认 |
+| 资源预留失败 | `resourcePendingPlanCount` 暴露 | 用原柜级入口定向重试 |
+| 重试结果不确定 | 查询计划和资源事实 | 复用原幂等键，不另建资源 |
+
+## 10. 阶段完成判定
+
+- [ ] 国内离仓产生的船节点任务绑定真实订舱和柜次
+- [ ] 节点预计/实际/观测时间没有混用
+- [ ] 异常事实与正常节点分开保存
+- [ ] 实际 `PICKUP_READY` 已到达或已有明确待处理状态
+- [ ] 装柜完成 V3 事件已被 Lastleg 幂等消费
+- [ ] 柜内每个来源入仓单只生成一张尾程订单
+- [ ] 尾程订单冻结客户、入仓码、接柜仓、目的仓和最终实装事实
+- [ ] `FIRST_LEG` 在途库存存在且归属正确
+- [ ] 整柜预计到仓完整且一致
+- [ ] 每票入仓计划属性完整
+- [ ] 柜级转换后每票独立 `planNo` 存在
+- [ ] 托盘、库位和资源锁已绑定，或存在可定位的资源失败待办
+- [ ] 尾程订单状态为 `INBOUND_PLANNED`
+- [ ] 重放事件/转换不会重复建单、建计划或占资源
+
+## 11. 易用性与数据流评审问题
+
+1. 船节点、目的港清关和尾程计划是否需要整合为一条柜级时间线，同时保留三个权威状态？
+2. 预计节点与实际节点的视觉差异是否足够明显？
+3. 船司失败、需人工、扣留异常分别由谁负责，是否需要责任人和 SLA？
+4. 发车队邮件后，页面是否明确区分“已入队、SMTP 已接受、车队已执行”？
+5. 预计到仓锁定前是否应显示会影响哪些订单和计划？
+6. 跨区事件失败是否需要业务友好的“缺哪一票/哪一字段”诊断，而不是只显示事件错误？
+7. 柜级工作台的 `pendingPlanCount` 与 `resourcePendingPlanCount` 是否容易混淆？
+8. 普通散货的“头程已有/海外补充/最终托数”是否需要图形化对比？
+9. 一件代发不可重排托盘的约束是否在编辑前就锁定控件？
+10. 转换前预览是否需要展示资源占用和预计库位，减少确认后人工调整？
+11. `PICKUP_READY` 开放 PDA 候选后，若预计到仓和资源计划尚未完成，现场应看到什么阻断提示？
+12. 还柜预警当前同时存在“两天展示”和“72 小时业务规则”的历史描述，正式页面应统一采用服务端 72 小时口径。
+
+## 12. 阶段五交接包
+
+交给阶段五“海外接柜、实收、库存和库内服务”的输入包括：
+
+- 来源柜次、真实柜号、订舱和最新实际船节点；
+- `PICKUP_READY` 及以后产生的 PDA 候选门禁；
+- 实际接柜海外仓和柜级预计到仓；
+- 柜内全部尾程订单、来源入仓码、目的类型和冻结货物；
+- 每票独立入仓计划及 `assigned/mergeAllowed/urgent/mergeHint`；
+- 已预留并确认的托盘、库位和资源锁；
+- 普通货头程托盘码与海外补码；
+- 一件代发不可变 `DP` 托盘、箱唛和 SKU；
+- 国内装柜五类照片引用及跨区事件审计历史。
+
+## 13. 事实来源
+
+- `docs/海外仓业务/README.md`
+- `docs/海外仓业务/船节点标准化契约.md`
+- `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
+- `docs/跨区域认证与服务通信契约.md`
+- `baiyue-firstleg/firstleg/AGENTS.md`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/portschedule/`
+- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/`
+- `baiyue-firstleg/common-event-contract/AGENTS.md`
+- `baiyue-firstleg/lastleg-service/AGENTS.md`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/service/LoadingCompletedConsumer.java`
+- `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/`
+- `apps/admin-web/src/modules/port-schedules/`
+- `apps/admin-web/src/modules/overseas-warehouse/`