feat(dispatch): unify whole vehicle scheduling, source ownership and staged execution

# Conflicts:
#	deploy/sql/README.md
#	deploy/sql/海外区域统一增量-MySQL8.sql

AGENTS.md

@@ -106,6 +106,19 @@
 - 装柜、船节点、卸柜、暂扣、派送、费用与资金按统一通信契约的逐事件表直接投递。保留本地 Outbox、消费幂等、重试与失败处置，不携带用户 JWT；旧 Bridge 源码已退出聚合和发布清单，退役待清理；实际停机仍须替代链验证与授权，不得据源码状态认定已部署。
 - `lastleg-service` 不读取头程数据库，`warehouse-overseas-service` 不读取尾程订单库。共用测试 MySQL 实例不改变服务数据归属。准确路由、ACK、撤销矩阵和切换门槛只维护在新的两份主契约中。
 
+## 数据库访问与中文代码注释（所有服务及公共模块强制）
+
+- 本节适用于全部后端服务和公共模块；新增、修改的方法必须执行，触及的存量代码同步整改。登记本约束不代表存量代码已全部完成迁移和注释补齐。
+- 生产代码的关系型数据库读写统一经 MyBatis/MyBatis-Plus Mapper 执行；Controller、Service、定时任务、消费者、编号生成器和公共基础组件不得直接使用 `JdbcTemplate`、`NamedParameterJdbcTemplate`、原生 JDBC/Connection/Statement 或其他通道执行 SQL。仅改成 Repository 包装 JDBC 不算整改，SQL 必须进入 Mapper；无数据库职责的模块不得为满足本条新增数据库访问。
+- 正常业务数据库访问路径统一为 `Controller → Service → Repository → Mapper`，四层职责明确，不得省略 Repository，也不得由 Controller 直接调用 Repository/Mapper，或由 Service 直接调用 Mapper。定时任务、消费者等非 HTTP 入口从 Service 进入，同样经 Repository → Mapper 完成持久化访问。
+- Controller 负责请求接收、参数校验、入口权限和响应转换；Service 负责业务规则、编排及业务事务；Repository 负责领域数据访问封装、查询组合与持久化模型转换，对 Service 提供有业务含义的数据操作；Mapper 负责 SQL 执行及数据库记录映射。Repository 不承载业务状态流转，不直接用 JDBC 执行 SQL；Service 不继承 MyBatis-Plus `ServiceImpl` 等方式绕过 Repository。
+- 复杂查询、批量处理、原子计数、锁定读取、Outbox 和数据库监控查询同样经 Repository → Mapper，不以 SQL 特殊或实现方便为由跳层。公共模块需要数据库能力时，按现有模块边界定义 Repository/持久化接口，由所属服务的 Repository → Mapper 实现，禁止借此跨服务读库。
+- 迁移数据库操作须保留客户隔离条件、事务传播、行锁、幂等和并发语义；`LAST_INSERT_ID()` 等连接级操作必须在同一事务连接完成，并明确关闭相关读取缓存，不能仅机械搬移 SQL。Mapper 注册及扫描仍遵守下文统一规范。
+- 测试代码可用 `JdbcTemplate` 创建隔离测试表、准备数据及核对结果；被测生产路径仍必须调用实际 Mapper，不得把测试造数做法带入生产。数据库基线和迁移脚本按现有部署契约管理。
+- 每个手写方法及构造器均须添加简短中文注释，通常 1—3 行说明业务用途；接口方法和 Mapper 方法优先使用中文 Javadoc。覆盖方法同样须有简短中文说明，实现中的关键规则仍须就地注释；自动生成的方法不手工逐个补注释。
+- 核心业务、复杂 SQL、状态流转、资金与库存变更、权限隔离、事务、锁、幂等、并发、重试和补偿逻辑，须在关键代码前增加适量中文注释，解释业务规则、处理原因、约束边界及失败影响；不逐行翻译代码，不添加无信息量或与实现不符的注释。
+- 新增和修改的代码说明注释统一使用中文；必要的技术标识、协议名、类名可保留原文，第三方许可证和生成标记保持原样。修改方法时同步更新相关存量英文或过期说明；审查时同时核对 Controller → Service → Repository → Mapper 分层及中文方法、核心逻辑注释。
+
 ## 契约、数据库与验证入口
 
 - 对外 Controller/API 新增、改名或删除时，同时核对调用端、统一 Gateway、OpenAPI 和权限；提交前运行 `node --test scripts/gateway-route-contract.test.mjs`，自动发现生产 Controller 并校验网关目标服务与内部路径隔离。失败不得提交或标记完成；网关配置变化必须列入部署清单，不以业务服务单测代替入口检查。

audit-service/AGENTS.md

@@ -1,5 +1,10 @@
 # Audit Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - Mapper 只由 `BaiyueAuditApplication.java` 对 `com.baiyue.audit` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。

auth/AGENTS.md

@@ -1,5 +1,10 @@
 # Auth Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责与边界
 
 - Mapper 只由 `BaiyueAuthApplication.java` 对 `com.baiyue.auth` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。

common-audit/AGENTS.md

@@ -1,5 +1,10 @@
 # Common Audit 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - 负责业务审计事件采集、注解切面、敏感字段脱敏以及日志/HTTP 输出。

common-core/AGENTS.md

@@ -1,5 +1,10 @@
 # Common Core 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - 提供不依赖具体业务域的返回模型、异常、基础实体和 MyBatis-Plus 通用配置。

common-event-contract/AGENTS.md

@@ -1,5 +1,10 @@
 # Common Event Contract 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - 维护 Firstleg、Lastleg、Finance 之间稳定、可版本化的业务事件契约。

common-openapi/AGENTS.md

@@ -1,5 +1,10 @@
 # Common OpenAPI 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - 为 Spring MVC 服务提供 SpringDoc/OpenAPI 自动配置和统一文档元数据。

common-security/AGENTS.md

@@ -1,5 +1,10 @@
 # Common Security 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - 提供业务服务通用的 JWT 解码、认证过滤、Redis Access Token 会话校验、认证用户上下文及 401/403 JSON 响应。

common-web/AGENTS.md

@@ -1,5 +1,10 @@
 # Common Web 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责边界
 
 - 提供 Servlet Web 通用能力：请求链路标识、上下文和统一异常响应。

deploy/docker-compose.yml

@@ -285,9 +285,14 @@ services:
     image: ${IMAGE_REPOSITORY}/lastleg-service:${IMAGE_TAG}
     container_name: firstleg-${DEPLOY_ENV:-test}-lastleg
     expose: ["9303"]
+    # 仅限制尾程服务，避免 JVM 异常时拖垮测试服务器.
+    mem_limit: 3g
+    memswap_limit: 3g
+    cpus: "2.0"
     environment:
       <<: *common-environment
       SERVER_PORT: 9303
+      JAVA_TOOL_OPTIONS: "-Xms512m -Xmx1536m -XX:+ExitOnOutOfMemoryError -Dfile.encoding=UTF-8"
       SELFOP_EXECUTION_ENABLED: ${SELFOP_EXECUTION_ENABLED:-false}
       SELFOP_COLLECTION_MODE: ${SELFOP_COLLECTION_MODE:-OFF}
       SELFOP_SOURCE_ACCOUNT: ${SELFOP_SOURCE_ACCOUNT:-lingxing-primary}
@@ -333,3 +338,5 @@ networks:
   infra-network:
     external: true
     name: ${INFRA_NETWORK:-firstleg-${DEPLOY_ENV:-test}-infra-network}
+
+

deploy/sql/20261016-数据库变更汇总.md

@@ -0,0 +1,63 @@
+# 2026-10-16 拉取合并数据库变更汇总
+
+范围：IDEA 更新前暂存基点 `cda5f3dc3` 到远程 `test` 的 `4e2ea8940`，加上本次恢复的本地改动。不是任意历史版本的一键全量升级脚本。没有连接或执行实际数据库。
+
+## 数据库对应关系
+
+| 服务 | 数据库 | 本次处理 |
+|---|---|---|
+| lastleg-service | `baiyue_lastleg` | 执行下列 V28 增量，新增表、字段、索引并放宽四个字段的可空性 |
+| warehouse-overseas-service | `baiyue_lastlag_warehouse` | 仅业务代码变化，无新增表或字段，无需 SQL；数据库名称保留正式的 lastlag 拼写 |
+| 其他服务 | 各服务原数据库 | 本次比较范围内无 SQL 结构新增，无需 SQL |
+
+已有尾程库使用：[V28 可重复执行 SQL](migrations/overseas/baiyue_lastleg/V28__merge_transfer_measurement_and_compact_numbers.sql)。文件显式指定 `USE baiyue_lastleg`，不访问其他服务数据库。
+
+## 新表与字段
+
+| 表 | 字段 | 定义/用途 |
+|---|---|---|
+| `ll_compact_number_clock`（新表） | `number_key` | VARCHAR(16)，主键，业务前缀及客户名称缩写 |
+| 同上 | `last_second` | BIGINT NOT NULL，短单号分配逻辑秒，防止同秒及多实例重号 |
+| `ll_warehouse_transfer_item` | `declared_quantity` | BIGINT NULL，SKU 申报件数，独立于箱数 |
+| `ll_warehouse_transfer_carton` | `length_cm`、`width_cm`、`height_cm`、`gross_weight_kg` | DECIMAL(12,2) NULL，逐箱实测尺寸、重量 |
+| 同上 | `counted_quantity` | BIGINT NULL，实点 SKU 件数 |
+| 同上 | `count_idempotency_key` | VARCHAR(255) NULL，清点幂等键 |
+| 同上 | `count_request_hash` | VARCHAR(64) NULL，清点请求摘要 |
+| 同上 | `counted_by` | VARCHAR(128) NULL，清点操作人 |
+| 同上 | `counted_at` | DATETIME(3) NULL，清点时间 |
+| 同上 | `discrepancy_reason` | VARCHAR(1000) NULL，实收差异原因 |
+| 同上 | `transfer_pallet_id` | BIGINT NULL，所属转运托盘事实 ID |
+| 同上 | `sku_items_json` | JSON NULL，一箱多 SKU 清点明细 |
+| 同上 | `customer_carton_mark` | VARCHAR(255) NULL，客户原箱唛及现场换标绑定 |
+
+合计：1 张新表（2 列）、既有表补齐 14 列。逐箱清点等字段在旧版独立增量中已有，本次合并统一纳入 V28，避免漏执行；已存在的列会跳过。
+
+## 索引及既有字段调整
+
+| 表 | 调整 |
+|---|---|
+| `ll_cargo_discard_item` | 缺失时增加普通索引 `idx_ll_cargo_discard_return_carton(customer_id,return_carton_id)` |
+| `ll_warehouse_transfer_order` | `estimated_arrival_at` 改为 DATETIME(3) NULL，库存转运无需填写预计入仓时间 |
+| `ll_delivery_order` | `total_volume_cbm` 改为 DECIMAL(18,4) NULL，未知体积保持空值 |
+| `ll_outbound_order`、`ll_outbound_pallet_item` | `volume_cbm` 改为 DECIMAL(18,4) NULL，未知体积保持空值 |
+
+远程同时完善了 `ll_relabel_application.delivery_method` 的业务说明及照片、预约表的中文注释，没有新增对应字段，不需要因此另建表。照片回显和箱子订单归属校验复用已有结构。
+
+## 执行与重跑
+
+1. 确认连接为需要升级的 MySQL 8 实例，已有 `baiyue_lastleg` 及之前版本的业务表。通过数据库客户端打开并完整执行 V28，失败时停止，不启用忽略错误继续执行。
+2. 新表采用 `CREATE TABLE IF NOT EXISTS`；每个新增字段和索引单独检查 `information_schema`，部分完成后可重跑。四个可空字段仅在当前为 NOT NULL 时调整。不会回填、删除或重算历史业务数据。
+3. DDL 在 MySQL 中会自动提交，不能整体事务回滚；脚本不会修复同名但定义不一致的已有列、索引或新表，执行前应核对这些对象的结构。脚本末尾提供字段结构查询。
+4. 此前 V1–V27 和其他已发布增量仍按原版本顺序管理，V28 不替代它们；缺失整个业务表的旧库应先完成对应历史升级。
+
+空库使用原有海外统一初始化入口，已同步最终建表结构与 209 张表计数。名称含“增量”的海外统一文件仍仅用于空库，不应向已有业务库执行。
+
+## 本地合并记录
+
+远程分支已拉取，当前本地 HEAD 与 `origin/test` 一致。本次异常来自 IDEA 恢复更新前暂存补丁不完整；48 个文件按当前文件、原始基点、暂存内容做三方合并。唯一文本冲突保留远程 `bindingGuard` 与本地 `compactNumbers` 两项测试依赖初始化。
+
+恢复前文件及三方版本保存在 `D:/project/.codex-temp/pull-resolution-20261016`；IDEA 原 shelf 保留。没有自动提交或推送代码。
+
+本地验证：相关业务 Maven 定向测试通过；初始化基线、入库费用/扣货及网关路由合同共 27 项通过；Git 无未解决索引、无残留冲突标记，差异格式检查通过。SQL 仅完成离线核对，未进行 MySQL 实库执行或二次重跑验证。
+
+指引索引检查 `scripts/agents-index-contract.ps1` 因工作区缺少 `D:/project/docs/业务快速索引.md` 而中止，此项未通过；未为消除检查错误而创建替代业务文档。

deploy/sql/README.md

@@ -1,5 +1,11 @@
 # 单测试环境数据库空库初始化
 
+排车整车作业结构同步于 Lastleg 源基线及海外统一空库基线：整车主单移除客户头部，真实客户归属保留在货物、出库、派送和费用；新增公共命令账本、主单历史、派送安排及签收待汇总信号。空排车的计划时间可暂缺，提交审核前由业务校验补齐；`ll_dispatch_physical_pallet_lock` 独立保存无代表客户的实托排他占用，`ll_dispatch_pallet_lock.physical_lock_id` 关联逐客户逻辑来源，同车可共享、跨主单或草稿容器仍排他。`ll_dispatch_item` 按主单和完整来源键唯一，`ll_dispatch_item_source` 冻结换标明细的实际位置、绑定箱数、真实件数（未知为空）及原货源事实；拣货归属新增 `dispatch_item_source_id`，与实收、退回实收、原生退货箱三类凭据四者互斥，不伪造普通收货凭据。智能草稿按拥有者、起运仓和版本维护，一容器转换一整车；独立草稿命令保存原请求和结果。必须与匹配的 Lastleg、IAM、File、Admin 和 PDA 一起核对，空库脚本不能向已有 TEST 重放。本条仅说明代码基线，不表示 SQL 已执行、已部署或全流程已验收；唯一业务规则见工作区 `docs/海外仓业务/排车列表统一作业改造契约.md`。
+
+`ll_physical_pallet_guard` 以真实全局实托ID和首次创建时间提供排车冻结与仓内改托的共同串行点，独立于运输占用，不保存客户、状态、有效期或第三种拥有者。`ll_dispatch_item_source.relabel_round_key`保存真实作业轮次，不能把扫码引起的库存和申请状态变化误当作换标轮次变化。排车、草稿和仓内调用必须使用匹配的公共锁实现；本条只说明空库基线结构，不表示已执行或已部署。
+
+本土散板简化下单的当前结构同步于 Lastleg 源基线及海外统一空库基线：移除散板柜型与旧要求日期，增加商品名称、申报预计托数及当地取货/送达时间，移除运输方式，增加起运地及目的地各自的联系人和联系电话；四项联系信息、取货及送货时间均必填；打盘与运输安排允许未知。预计托数不代表实收。字段语义唯一见工作区 `docs/海外仓业务/README.md`，不回填测试存量，不提供自动重置或启动时 SQL；需与匹配 Lastleg、Admin 和 Client 一起发布。本说明不表示 SQL 已执行。
+
 `migrations/overseas/baiyue_lastleg/V23__align_return_movement_collation.sql` 将退货进销存 UNION 涉及的八张表、22 个文本字段及表默认规则显式统一为 `utf8mb4_unicode_ci`，同步 Lastleg 两份源基线与海外统一空库基线。执行前核对字段长度、默认值、可空性及目标规则下唯一索引无冲突；只修改规则，不回填或删除数据，不重放空库基线。DDL 非事务，失败时停止并复查实际已完成项；可按最终定义重跑。脚本存在不表示测试库已执行，执行后用原始计数/分页查询验证，无需发布查询转换代码。
 
 `migrations/overseas/baiyue_lastleg/V22__selfop_warehouse_daily_sales.sql` 新增自营仓库每日汇总表及销量版本 `warehouse_daily_ready` 标记。与匹配 Lastleg 一起发布；汇总随 SKU 日事实批次原子构建，完整性验证后方可发布。已有未构建汇总的销量版本须重新构建发布，不回填旧版本、不回退旧查询；空版本同样必须有就绪证据。源基线与海外空库基线同步。
@@ -34,14 +40,19 @@
 
 预约工作事项新增结构由 `lastleg-service/src/main/resources/db/appointment-work.sql` 提供五张表：完整范围协调锁、工作关系、不可变历史、承诺影响版本与逐票批次实物分配，已同步 Lastleg 和海外空库初始化入口；对已有 TEST 仅审阅并授权这五表 CREATE 及协调锁初始行。直送目的仓实际卸货独立表由 `firstleg/src/main/resources/db/phase3-direct-delivery-schema.sql` 提供并同步国内空库入口，不产生海外库存。两项独立写权限见 `iam/src/main/resources/db/appointment-work-permissions.sql`，先校验精确权限身份再写入；默认只授权平台管理员。旧预约表的有损重建只允许单独审阅 `reset-test-fba-appointments.sql`；若历史、核实或工作/分配表已存在，前置检查会在 DROP 前拒绝，不能重放或擅自扩大重置范围。以上只维护脚本，不代表已执行或已部署。
 
+换标直接出库的实物体积快照在 `ll_outbound_order.volume_cbm`、`ll_outbound_pallet_item.volume_cbm`、`ll_delivery_order.total_volume_cbm` 三列均允许 NULL，表示来源尚未确认；已有实盘尺寸按箱计算，不能用默认 0 代替未知，也不按 SKU 件数重复累计。两份初始化基线同步此定义，已有 TEST 只能在核对结构和授权后精确调整这三列，不重放空库文件或回填历史行。
+
 ## 唯一入口与区域边界
 
+V13 收货覆盖由 `lastleg-service/src/main/resources/db/appointment-receiving.sql` 提供四表：独立收货预约、当前/历史客户成员、待确认变化和不可变覆盖版本；同步 Lastleg 与海外空库基线。有效外部约号唯一性归收货预约的目的仓与约号，批次头表不再独立占用约号。部署前必须核对四表及旧头表唯一索引；本批只准备基线，不提供测试存量回填或自动重置。旧 `reset-test-fba-appointments.sql` 已拒绝存在这些新表的环境，不能用于重放 V13 初始化。实际 SQL 与部署须逐项授权。
+
 两个统一 SQL 文件仍只用于空库初始化，名称中的“增量”不表示可向已有业务库重放。已有生产库的受控结构补齐单独放在 `migrations/`，只允许明确审阅过的增量变更；不提供存量数据回填、清理或兼容入口。
 
 | 区域 | 完整入口 | 服务 schema | 表数 |
 |---|---|---|---:|
-| 国内 | `头程数据库统一增量-MySQL8.sql` | `baiyue_auth`、`baiyue_iam`、`baiyue_order`、`baiyue_warehouse`、`baiyue_firstleg`、`baiyue_file`、`baiyue_audit`、`baiyue_finance` | 226 |
+| 国内 | `头程数据库统一增量-MySQL8.sql` | `baiyue_auth`、`baiyue_iam`、`baiyue_order`、`baiyue_warehouse`、`baiyue_firstleg`、`baiyue_file`、`baiyue_audit`、`baiyue_finance` | 227 |
-| 海外 | `海外区域统一增量-MySQL8.sql` | `baiyue_lastleg`、`baiyue_lastlag_warehouse` | 202 |
+| 海外 | `海外区域统一增量-MySQL8.sql` | `baiyue_lastleg`、`baiyue_lastlag_warehouse` | 228 |
+
 
 - 所有服务位于同一测试环境；两份文件只分组组织服务 schema，不代表两个部署区域。`baiyue_lastlag_warehouse` 保留当前正式的 `lastlag` 拼写。
 - 两份文件必须在同一测试数据库实例中完成初始化；业务服务仍只访问本服务 schema，经内部接口访问 IAM/Warehouse。已移除事件桥两个 schema 的创建，不对已有数据库执行 DROP。
@@ -50,7 +61,7 @@
 - 外接预订的`quote_source_json`保存可选销售报价来源版本快照，实际成交价仍在货物快照及`agreed_amount`中；手填成交价时无报价来源。该字段随Lastleg模块基线与海外统一入口维护，执行状态只见正式部署契约。
 - 异常退回的`return_context_json`保存取消时所需的原始业务状态；逐来源`received_packages`累计实际入仓量且不得超过批准退回量。同一派送可以保留多张已取消/已结束的历史退回单，活动退回仍由派送行锁内校验；普通`idx_ll_exception_delivery_return`替代跨全部历史的唯一索引。数量和状态不能通过回填旧单据伪造。
 - 派送`ll_delivery_order.signed_packages`保存签收资料确认时冻结的实际签收箱数；NULL表示未确认，不当作全量签收，数量须在0到本次实发箱数之间。后续退回保留原签收历史，不用当前退回量倒改实签。
-- `ll_return_stock_receipt`与真实退回库存入账同事务保存，按客户/入账流水唯一，保留原订单和出库位置以及实际入仓位置。重派候选、草稿锁及拣货显式引用该凭据；拣货`receipt_id`与`return_receipt_id`恰有一个非空。退回不增加原订单箱数，不回退历史出库流水；可重新发运量由实际退回及已消耗凭据核平。
+- `ll_return_stock_receipt`与真实退回库存入账同事务保存，按客户/入账流水唯一，保留原订单和出库位置以及实际入仓位置。重派候选、草稿锁及拣货显式引用该凭据；`receipt_id`、`return_receipt_id`、`return_carton_id`、`dispatch_item_source_id` 四类拣货归属凭据恰有一个非空。退回不增加原订单箱数，不回退历史出库流水；可重新发运量由实际退回及已消耗凭据核平。
 - 国内 Warehouse 管理包括海外仓在内的公共仓库主档；海外 Warehouse 只保存资源与主档 ID 引用。
 - Gateway、Print、Integration 不新增数据库。Compose 继续使用 `SPRING_SQL_INIT_MODE=never`，服务启动不执行这些文件。
 
@@ -63,7 +74,7 @@
 5. DDL 隐式提交，不可整体回滚。失败后停止并保留错误；经另行授权准备空库后从头执行，不针对半初始化库追加迁移或从失败行续跑。
 6. Firstleg 测量项与拆分项互为外键：建空表期间暂设会话 `foreign_key_checks=0`，随后立即恢复 `1`，再插入种子。失败时关闭连接。两边外键完整保留在 CREATE TABLE 内。
 
-成功时只在最末输出一行 `initialization_status=PASS`，并带 `region=CN/OVERSEAS`、`initialized_tables=226/199`。必须同时确认客户端退出码 0；忽略错误后出现的 PASS 不算成功。
+成功时只在最末输出一行 `initialization_status=PASS`，并带 `region=CN/OVERSEAS`、`initialized_tables=227/228`。必须同时确认客户端退出码 0；忽略错误后出现的 PASS 不算成功。
 
 ## 平台管理员密码
 
@@ -79,7 +90,7 @@
 
 | 所属库 | 保留内容 | 不包含 |
 |---|---|---|
-| Auth / IAM | 平台主体、唯一平台管理员、8 个系统角色及企业管理员模板、419 个权限、600 条角色权限、7 个数据范围、客户编号起点；无人工完成订单权限 | 测试客户、固定客户账号、额外扩权 |
+| Auth / IAM | 平台主体、唯一平台管理员、8 个系统角色及企业管理员模板、454 个权限、618 条角色权限、7 个数据范围、客户编号起点；无人工完成订单权限 | 测试客户、固定客户账号、额外扩权 |
 | Warehouse | 既有公共仓目录 318 条及地址；义乌、东莞、洛杉矶、纽约 4 个作业仓收货能力 | 示例供应商、快递、往来单位、托盘、库位、预占、库存 |
 | Firstleg | 112 个费用项目、15 个渠道目录、7 个始发地别名、4 个公共仓映射 | 客户报价、订单、入库、实测或履约记录 |
 | File / Finance | 导出互斥键 `GLOBAL_CREATE`、默认平台财务主体 | 文件任务、资金、账单或交易流水 |
@@ -157,3 +168,5 @@ node --test scripts/admin-test-env-modules/initialization-baseline-contract.test
 自营库存周转后端导出权限见 `selfop-turnover-export-permission.sql`，仅新增 `platform:self-operated-analytics:export` 并授予平台管理员；同步 IAM 自营权限源及国内统一基线。配套部署 Lastleg、File、Admin，File 注册 `SELFOP_INVENTORY_TURNOVER`（Nacos同名配置同步）；无业务建表及采集配置变更。执行前须逐项授权。
 
 货物废弃通用库存与散箱字段迁移：`migrations/overseas/baiyue_lastleg/V25__cargo_discard_generic_inventory.sql`。新增库存仓位关联及箱唛快照，须先迁移再部署 Lastleg；不回填历史废弃单。
+
+2026-10-16 拉取合并配套结构清单及执行边界见 [数据库变更汇总](20261016-数据库变更汇总.md)，已有尾程库使用 `migrations/overseas/baiyue_lastleg/V28__merge_transfer_measurement_and_compact_numbers.sql`；空库初始化海外表数同步为 209。该增量可重复执行，尚未执行到任何实际数据库。

deploy/sql/migrations/overseas/baiyue_lastleg/V28__merge_transfer_measurement_and_compact_numbers.sql

@@ -0,0 +1,70 @@
+-- 2026-10-16 拉取合并及本地恢复配套增量，MySQL 8。
+-- 目标：lastleg-service / baiyue_lastleg；前置：已有业务表及此前迁移。
+-- 只调整结构，不回填、删除或重算业务数据；执行失败应停止，修复后可重跑。
+SET NAMES utf8mb4;
+USE baiyue_lastleg;
+
+CREATE TABLE IF NOT EXISTS ll_compact_number_clock (
+  number_key VARCHAR(16) NOT NULL COMMENT '业务前缀和客户名称缩写',
+  last_second BIGINT NOT NULL COMMENT '最后分配的Unix逻辑秒',
+  PRIMARY KEY (number_key)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='海外业务短单号分配时钟';
+
+-- 仓储转运逐箱测量与清点；仅增加字段，不修改业务数据。
+USE baiyue_lastleg;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='length_cm'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN length_cm DECIMAL(12,2) NULL COMMENT ''箱子实测长度厘米'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='width_cm'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN width_cm DECIMAL(12,2) NULL COMMENT ''箱子实测宽度厘米'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='height_cm'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN height_cm DECIMAL(12,2) NULL COMMENT ''箱子实测高度厘米'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='gross_weight_kg'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN gross_weight_kg DECIMAL(12,2) NULL COMMENT ''箱子实测重量千克'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='counted_quantity'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN counted_quantity BIGINT NULL COMMENT ''箱内SKU实点件数'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='count_idempotency_key'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN count_idempotency_key VARCHAR(255) NULL COMMENT ''箱内清点幂等键'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='count_request_hash'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN count_request_hash VARCHAR(64) NULL COMMENT ''箱内清点请求摘要'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='counted_by'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN counted_by VARCHAR(128) NULL COMMENT ''箱内清点操作人'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='counted_at'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN counted_at DATETIME(3) NULL COMMENT ''箱内清点完成时间'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='discrepancy_reason'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN discrepancy_reason VARCHAR(1000) NULL COMMENT ''实收与预报箱数差异原因'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='transfer_pallet_id'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN transfer_pallet_id BIGINT NULL COMMENT ''签收箱所属转运托盘事实ID'''));
+PREPARE transfer_count_stmt FROM @ddl; EXECUTE transfer_count_stmt; DEALLOCATE PREPARE transfer_count_stmt;
+
+-- SKU 申报件数独立于预计箱数；历史未申报件数保持 NULL，实收以 PDA 清点为准。
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_item' AND column_name='declared_quantity'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_item ADD COLUMN declared_quantity BIGINT NULL COMMENT ''SKU申报件数，非预计或实收箱数'''));
+PREPARE transfer_quantity_stmt FROM @ddl; EXECUTE transfer_quantity_stmt; DEALLOCATE PREPARE transfer_quantity_stmt;
+
+-- 仓储转运一箱多SKU清点；仅增加结构，不回填历史业务数据。
+USE baiyue_lastleg;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='sku_items_json'), 'SELECT 1', 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN sku_items_json JSON NULL COMMENT ''实收箱内SKU及逐项件数明细'''));
+PREPARE transfer_sku_stmt FROM @ddl; EXECUTE transfer_sku_stmt; DEALLOCATE PREPARE transfer_sku_stmt;
+
+SET @ddl = IF(NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_carton' AND column_name='customer_carton_mark'), 'ALTER TABLE ll_warehouse_transfer_carton ADD COLUMN customer_carton_mark VARCHAR(255) NULL COMMENT ''客户原箱唛，用于换标现场绑定''', 'SELECT 1');
+PREPARE merge_schema_stmt FROM @ddl; EXECUTE merge_schema_stmt; DEALLOCATE PREPARE merge_schema_stmt;
+
+SET @ddl = IF(NOT EXISTS (SELECT 1 FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name='ll_cargo_discard_item' AND index_name='idx_ll_cargo_discard_return_carton'), 'ALTER TABLE ll_cargo_discard_item ADD KEY idx_ll_cargo_discard_return_carton(customer_id,return_carton_id)', 'SELECT 1');
+PREPARE merge_schema_stmt FROM @ddl; EXECUTE merge_schema_stmt; DEALLOCATE PREPARE merge_schema_stmt;
+
+SET @ddl = IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_warehouse_transfer_order' AND column_name='estimated_arrival_at' AND is_nullable='NO'), 'ALTER TABLE ll_warehouse_transfer_order MODIFY COLUMN estimated_arrival_at DATETIME(3) NULL COMMENT ''预计入仓时间，库存转运不填写''', 'SELECT 1');
+PREPARE merge_schema_stmt FROM @ddl; EXECUTE merge_schema_stmt; DEALLOCATE PREPARE merge_schema_stmt;
+
+SET @ddl = IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_delivery_order' AND column_name='total_volume_cbm' AND is_nullable='NO'), 'ALTER TABLE ll_delivery_order MODIFY COLUMN total_volume_cbm DECIMAL(18,4) NULL COMMENT ''体积（立方米），来源未确认时为空''', 'SELECT 1');
+PREPARE merge_schema_stmt FROM @ddl; EXECUTE merge_schema_stmt; DEALLOCATE PREPARE merge_schema_stmt;
+
+SET @ddl = IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_outbound_order' AND column_name='volume_cbm' AND is_nullable='NO'), 'ALTER TABLE ll_outbound_order MODIFY COLUMN volume_cbm DECIMAL(18,4) NULL COMMENT ''体积（立方米），来源未确认时为空''', 'SELECT 1');
+PREPARE merge_schema_stmt FROM @ddl; EXECUTE merge_schema_stmt; DEALLOCATE PREPARE merge_schema_stmt;
+
+SET @ddl = IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_outbound_pallet_item' AND column_name='volume_cbm' AND is_nullable='NO'), 'ALTER TABLE ll_outbound_pallet_item MODIFY COLUMN volume_cbm DECIMAL(18,4) NULL COMMENT ''体积（立方米），来源未确认时为空''', 'SELECT 1');
+PREPARE merge_schema_stmt FROM @ddl; EXECUTE merge_schema_stmt; DEALLOCATE PREPARE merge_schema_stmt;
+
+-- 执行后核对本次结构；这不是应用功能验收。
+SELECT table_name,column_name,column_type,is_nullable,column_comment FROM information_schema.columns
+WHERE table_schema=DATABASE() AND table_name IN ('ll_compact_number_clock','ll_warehouse_transfer_carton','ll_warehouse_transfer_item','ll_warehouse_transfer_order','ll_delivery_order','ll_outbound_order','ll_outbound_pallet_item')
+ORDER BY table_name,ordinal_position;

deploy/sql/migrations/overseas/baiyue_lastleg/V29__allow_unbound_transfer_forecast_cartons.sql

@@ -0,0 +1,2 @@
+-- 对应数据库：baiyue_lastleg；可重复执行，不修改原箱号、SKU预报件数和实测数据。
+ALTER TABLE ll_warehouse_transfer_carton MODIFY COLUMN transfer_item_id BIGINT NULL COMMENT '实际箱内首项SKU明细ID，预报补箱可为空';

deploy/sql/reset-test-fba-appointments.sql

@@ -10,7 +10,8 @@ CREATE PROCEDURE assert_test_appointment_reset_preconditions()
 BEGIN
   IF EXISTS(SELECT 1 FROM information_schema.tables WHERE table_schema=DATABASE()
       AND table_name IN ('ll_fba_appointment_command','ll_appointment_cargo_verification',
-        'll_appointment_work','ll_dispatch_appointment_allocation')) THEN
+        'll_appointment_work','ll_dispatch_appointment_allocation','ll_fba_receiving_agreement',
+        'll_fba_receiving_member','ll_fba_receiving_change','ll_fba_receiving_revision','ll_fba_receiving_plan')) THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Stop: appointment history or work/allocation schema already exists; inspect before any reset';
   END IF;
   IF (SELECT COUNT(*) FROM information_schema.tables WHERE table_schema=DATABASE()
@@ -49,7 +50,6 @@ CREATE TABLE ll_inbound_fba_appointment (
   updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '更新UTC时间',
   PRIMARY KEY (id),
   UNIQUE KEY uk_ll_fba_appointment_no (appointment_no),
-  UNIQUE KEY uk_ll_fba_external_confirmation (fba_warehouse_code,confirmation_no),
   KEY idx_ll_fba_appointment_list (appointment_at,appointment_status,fba_warehouse_code),
   KEY idx_ll_fba_appointment_planned (planned_at,appointment_status)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='FBA预约安排与正式确认唯一主记录';
@@ -66,7 +66,7 @@ CREATE TABLE ll_inbound_fba_appointment_item (
   package_count INT NULL COMMENT '本批分配箱数，未知保持空；同一原来源总量守恒',
   cargo_verification_version INT NULL COMMENT '采用的预约货物核实版本，未核实时为空',
   shipment_references_json LONGTEXT NULL COMMENT '本次采用的货件或追踪号核实快照',
-  active TINYINT(1) NOT NULL DEFAULT 1 COMMENT '取消或失败后释放货源占用',
+  active TINYINT(1) NOT NULL DEFAULT 1 COMMENT '当前批次数量分配有效；取消、未约成和完成均保留，仅替代时释放',
   created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建UTC时间',
   PRIMARY KEY (id),
   UNIQUE KEY uk_ll_fba_item_source (appointment_id,source_key),

deploy/sql/头程数据库统一增量-MySQL8.sql

@@ -6356,10 +6356,9 @@ INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id,
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107011,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:create','创建海外入仓计划',NULL,'POST',711,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107012,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:edit','编辑海外入仓计划',NULL,'POST',712,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107013,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:fba-appointment','FBA预约',NULL,'POST',713,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
-INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107014,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:smart-dispatch','智能排车',NULL,'POST',714,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107015,0,'PLATFORM','BUTTON',5107010,'lastleg:pda:operate','海外仓PDA入仓作业',NULL,'POST',715,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107016,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:edit','编辑海外排车',NULL,'PUT',716,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
-INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107017,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'DELETE',717,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
+INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107017,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'POST',717,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107018,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:transfer-delivery','排车转派送',NULL,'POST',718,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107020,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:relabel-order:list','海外换标单','/overseas-warehouse/relabel-orders','GET',720,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107021,0,'PLATFORM','BUTTON',5107020,'platform:overseas-warehouse:relabel-order:create','创建海外换标单',NULL,'POST',721,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
@@ -6381,6 +6380,9 @@ INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id,
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107062,0,'PLATFORM','BUTTON',5107060,'platform:overseas-warehouse:location:edit','编辑海外库位',NULL,'PUT',762,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107063,0,'PLATFORM','BUTTON',5107060,'platform:overseas-warehouse:location:delete','删除海外库位',NULL,'DELETE',763,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107064,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:dispatch:list','海外排车单','/overseas-warehouse/dispatches','GET',764,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
+INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107065,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:create','新增排车单',NULL,'POST',765,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
+INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107066,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:loading-complete','确认装车完成',NULL,'POST',766,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
+INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107067,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:depart','确认实际发车',NULL,'POST',767,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107070,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:exception-order:list','海外异常订单','/overseas-warehouse/exception-orders','GET',770,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107071,0,'PLATFORM','BUTTON',5107070,'platform:overseas-warehouse:exception-order:create','新增海外异常订单',NULL,'POST',771,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107072,0,'PLATFORM','BUTTON',5107092,'platform:overseas-warehouse:delivery:return','派送单标记退货',NULL,'POST',772,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
@@ -6458,7 +6460,6 @@ INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id,
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5305020,0,'MERCHANT','MENU',5300000,'merchant:finance:account:view','资金账户','/finance/account','GET',50,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5305021,0,'MERCHANT','BUTTON',5305020,'merchant:finance:recharge:create','提交充值申请',NULL,'POST',10,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5306000,0,'MERCHANT','MENU',0,'merchant:warehouse:delivery:list','海外仓派送单','/orders/delivery','GET',60,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
-INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5306001,0,'MERCHANT','BUTTON',5306000,'merchant:warehouse:delivery:create','创建海外仓派送单',NULL,'POST',10,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5306100,0,'MERCHANT','MENU',0,'merchant:cross-border:procurement:list','海外采购','/cross-border/procurement','GET',70,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5306101,0,'MERCHANT','BUTTON',5306100,'merchant:cross-border:procurement:create','创建海外采购单',NULL,'POST',10,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5306110,0,'MERCHANT','MENU',0,'merchant:cross-border:domestic-trucking:list','美国本土卡','/cross-border/domestic-trucking','GET',80,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
@@ -6737,7 +6738,6 @@ INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at)
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107011,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107012,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107013,0,CURRENT_TIMESTAMP(3));
-INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107014,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107016,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107017,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107018,0,CURRENT_TIMESTAMP(3));
@@ -6761,6 +6761,9 @@ INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at)
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107062,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107063,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107064,0,CURRENT_TIMESTAMP(3));
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107065,0,CURRENT_TIMESTAMP(3));
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107066,0,CURRENT_TIMESTAMP(3));
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107067,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107070,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107071,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107072,0,CURRENT_TIMESTAMP(3));
@@ -7038,6 +7041,9 @@ INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at)
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107050,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107060,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107064,0,CURRENT_TIMESTAMP(3));
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107065,0,CURRENT_TIMESTAMP(3));
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107066,0,CURRENT_TIMESTAMP(3));
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107067,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107070,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107071,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000004,5107072,0,CURRENT_TIMESTAMP(3));
@@ -7121,7 +7127,6 @@ INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at)
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000100,5305020,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000100,5305021,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000100,5306000,0,CURRENT_TIMESTAMP(3));
-INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000100,5306001,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000100,5306100,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000100,5306101,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000100,5306110,0,CURRENT_TIMESTAMP(3));

docs/overseas-inventory-mutation-flow.svg

@@ -0,0 +1,90 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1800" height="1280" viewBox="0 0 1800 1280">
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto"><path d="M0,0 L10,3 L0,6 Z" fill="#335c81"/></marker>
+    <marker id="greenArrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto"><path d="M0,0 L10,3 L0,6 Z" fill="#18865b"/></marker>
+    <marker id="redArrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto"><path d="M0,0 L10,3 L0,6 Z" fill="#c94d4d"/></marker>
+    <style>
+      .title{font:700 34px 'Microsoft YaHei','Noto Sans SC',sans-serif;fill:#17324d}
+      .sub{font:400 17px 'Microsoft YaHei','Noto Sans SC',sans-serif;fill:#547086}
+      .lane{font:700 20px 'Microsoft YaHei','Noto Sans SC',sans-serif;fill:#17324d}
+      .boxTitle{font:700 19px 'Microsoft YaHei','Noto Sans SC',sans-serif;fill:#17324d}
+      .boxText{font:400 16px 'Microsoft YaHei','Noto Sans SC',sans-serif;fill:#36566d}
+      .small{font:400 14px 'Microsoft YaHei','Noto Sans SC',sans-serif;fill:#547086}
+      .assert{font:500 16px 'Microsoft YaHei','Noto Sans SC',sans-serif;fill:#23445a}
+      .line{stroke:#335c81;stroke-width:3;fill:none;marker-end:url(#arrow)}
+      .gline{stroke:#18865b;stroke-width:3;fill:none;marker-end:url(#greenArrow)}
+      .rline{stroke:#c94d4d;stroke-width:3;fill:none;marker-end:url(#redArrow)}
+    </style>
+  </defs>
+  <rect width="1800" height="1280" fill="#f6f9fc"/>
+  <text x="70" y="62" class="title">海外业务｜库存变动测试总流程图</text>
+  <text x="70" y="94" class="sub">测试看库存：先看库存状态，再看数量、位置、流水和幂等；灰色节点只改状态/资源，不直接改可用库存。</text>
+
+  <g transform="translate(70,125)">
+    <rect width="1660" height="58" rx="12" fill="#e9f1f8"/>
+    <circle cx="28" cy="29" r="10" fill="#18865b"/><text x="50" y="35" class="small">绿色：库存增加/恢复</text>
+    <circle cx="250" cy="29" r="10" fill="#c94d4d"/><text x="272" y="35" class="small">红色：库存扣减</text>
+    <circle cx="450" cy="29" r="10" fill="#e19a28"/><text x="472" y="35" class="small">橙色：冻结/释放</text>
+    <circle cx="690" cy="29" r="10" fill="#7657a8"/><text x="712" y="35" class="small">紫色：SKU/箱唛变化</text>
+    <circle cx="960" cy="29" r="10" fill="#78909c"/><text x="982" y="35" class="small">灰色：状态/资源变化</text>
+    <text x="1260" y="35" class="small">所有写操作：租户隔离 + 版本/锁 + 幂等键</text>
+  </g>
+
+  <g transform="translate(70,220)">
+    <rect width="1660" height="196" rx="16" fill="#edf5ee" stroke="#b7d9c2" stroke-width="2"/>
+    <text x="24" y="34" class="lane">A. 库存来源与入仓</text>
+    <rect x="24" y="58" width="240" height="96" rx="12" fill="#fff" stroke="#6ea984" stroke-width="2"/>
+    <text x="44" y="88" class="boxTitle">头程装柜完成事件</text><text x="44" y="116" class="boxText">生成尾程单 / 冻结明细</text><text x="44" y="140" class="small">在途：不可用库存</text>
+    <path d="M264 106 H330" class="line"/>
+    <rect x="330" y="58" width="250" height="96" rx="12" fill="#fff" stroke="#6ea984" stroke-width="2"/>
+    <text x="350" y="88" class="boxTitle">平台转换入仓计划</text><text x="350" y="116" class="boxText">按入仓单 / 推荐托数建计划</text><text x="350" y="140" class="small">仍未形成可用库存</text>
+    <path d="M580 106 H646" class="line"/>
+    <rect x="646" y="58" width="290" height="96" rx="12" fill="#fff" stroke="#18865b" stroke-width="3"/>
+    <text x="666" y="88" class="boxTitle">PDA 签收 → 实收 → 上架</text><text x="666" y="116" class="boxText">完成后入仓库存入账</text><text x="666" y="140" class="small">AVAILABLE + 位置 + 库存流水</text>
+    <path d="M936 106 H1002" class="gline"/>
+    <rect x="1002" y="58" width="280" height="96" rx="12" fill="#e6f6ed" stroke="#18865b" stroke-width="2"/>
+    <text x="1022" y="88" class="boxTitle">可用库存池</text><text x="1022" y="116" class="boxText">客户 × 海外仓 × 目的仓</text><text x="1022" y="140" class="small">入仓单汇总；托盘只做作业维度</text>
+    <rect x="1316" y="58" width="310" height="96" rx="12" fill="#f0f2f4" stroke="#9baab4" stroke-width="2"/>
+    <text x="1336" y="88" class="boxTitle">门禁与失败</text><text x="1336" y="116" class="boxText">照片、仓绑定、客户/柜号</text><text x="1336" y="140" class="small">任一失败：库存与状态整体回滚</text>
+  </g>
+
+  <g transform="translate(70,450)">
+    <rect width="1660" height="222" rx="16" fill="#fff8ec" stroke="#efd39a" stroke-width="2"/>
+    <text x="24" y="34" class="lane">B. 从可用库存出发的四类作业</text>
+    <rect x="24" y="60" width="360" height="126" rx="12" fill="#fff" stroke="#dfa43c" stroke-width="2"/>
+    <text x="44" y="88" class="boxTitle">排车 / 一件代发拣货</text><text x="44" y="116" class="boxText">AVAILABLE → 冻结 → PICKED</text><text x="44" y="144" class="boxText">发车/出库 → 扣减</text><text x="44" y="170" class="small">整托扫描也按入仓单组成核平</text>
+    <rect x="430" y="60" width="360" height="126" rx="12" fill="#fff" stroke="#7657a8" stroke-width="2"/>
+    <text x="450" y="88" class="boxTitle">换标</text><text x="450" y="116" class="boxText">冻结 hold_packages</text><text x="450" y="144" class="boxText">旧 SKU 转出 → 新 SKU 转入</text><text x="450" y="170" class="small">箱唛/托盘绑定变化，箱数守恒</text>
+    <rect x="836" y="60" width="360" height="126" rx="12" fill="#fff" stroke="#dfa43c" stroke-width="2"/>
+    <text x="856" y="88" class="boxTitle">仓储转运</text><text x="856" y="116" class="boxText">来源仓冻结/扣减</text><text x="856" y="144" class="boxText">目标仓收货 → 增加</text><text x="856" y="170" class="small">可联动换标；来源/目标核对</text>
+    <rect x="1242" y="60" width="384" height="126" rx="12" fill="#fff" stroke="#c94d4d" stroke-width="2"/>
+    <text x="1262" y="88" class="boxTitle">废弃</text><text x="1262" y="116" class="boxText">申请仅锁箱：DISCARD_PENDING</text><text x="1262" y="144" class="boxText">PDA 实际确认 → 扣减 → DISCARDED</text><text x="1262" y="170" class="small">驳回释放；平台结案不再扣一次</text>
+  </g>
+
+  <g transform="translate(70,706)">
+    <rect width="1660" height="222" rx="16" fill="#eef3fa" stroke="#b7cae2" stroke-width="2"/>
+    <text x="24" y="34" class="lane">C. 出库后的结果与恢复</text>
+    <rect x="24" y="60" width="350" height="126" rx="12" fill="#fff" stroke="#c94d4d" stroke-width="2"/>
+    <text x="44" y="88" class="boxTitle">OUTBOUNDED / 派送中</text><text x="44" y="116" class="boxText">库存已扣减，保留出库事实</text><text x="44" y="144" class="boxText">签收：不再二次扣库存</text><text x="44" y="170" class="small">派送费用与库存动作分开核对</text>
+    <path d="M374 123 H446" class="line"/>
+    <rect x="446" y="60" width="380" height="126" rx="12" fill="#fff" stroke="#18865b" stroke-width="3"/>
+    <text x="466" y="88" class="boxTitle">异常退回入仓</text><text x="466" y="116" class="boxText">只能选原出库拣货事实</text><text x="466" y="144" class="boxText">RETURN_STOCK_IN → 目标托盘/库位</text><text x="466" y="170" class="small">库存恢复 + 异常完成 + 派送 RETURNED</text>
+    <rect x="900" y="60" width="330" height="126" rx="12" fill="#fff" stroke="#78909c" stroke-width="2"/>
+    <text x="920" y="88" class="boxTitle">盘点调整</text><text x="920" y="116" class="boxText">实盘数量 − 账面数量 = 差异</text><text x="920" y="144" class="boxText">按正/负生成调整流水</text><text x="920" y="170" class="small">无差异不造流水；需 adjust 权限</text>
+    <rect x="1270" y="60" width="356" height="126" rx="12" fill="#fff" stroke="#78909c" stroke-width="2"/>
+    <text x="1290" y="88" class="boxTitle">移库 / 拆合托 / 换绑</text><text x="1290" y="116" class="boxText">同仓位置或托盘组成变化</text><text x="1290" y="144" class="boxText">数量净额 = 0</text><text x="1290" y="170" class="small">记录位置流水；资源锁防并发</text>
+  </g>
+
+  <path d="M1142 416 V450" class="gline"/><path d="M120 638 V706" class="rline"/><path d="M610 638 V706" class="gline"/>
+  <path d="M1020 638 V706" class="line"/><path d="M1435 638 V706" class="rline"/>
+
+  <g transform="translate(70,965)">
+    <rect width="1660" height="250" rx="16" fill="#ffffff" stroke="#d5e0e8" stroke-width="2"/>
+    <text x="24" y="36" class="lane">D. 测试统一断言（每个库存场景都要检查）</text>
+    <text x="42" y="78" class="assert">① 数量守恒：客户 / 海外仓 / 目的仓 / 入仓单 / 托盘组成逐层核平</text>
+    <text x="42" y="114" class="assert">② 三账一致：库存余额 = 位置明细汇总 = 库存流水结果</text>
+    <text x="42" y="150" class="assert">③ 幂等并发：重复事件、重复请求、并发锁定不得产生第二笔变动</text>
+    <text x="42" y="186" class="assert">④ 原子回滚：权限、门禁、资源锁、跨服务失败时，库存/单据/流水一起回滚</text>
+    <text x="42" y="222" class="assert">⑤ 隔离校验：客户、仓、来源入仓单、原出库事实不可伪造或串用</text>
+  </g>
+</svg>

docs/overseas-inventory-mutation-test-map.md

@@ -0,0 +1,40 @@
+# 海外业务库存变动测试整理
+
+范围依据：`lastleg-service/AGENTS.md`、`docs/backend-business-index.md` 及当前海外仓库存、入仓、出库、换标、转运、废弃、异常退回和 PDA 作业入口。
+
+## 先统一库存口径
+
+- **可用库存**：按客户、海外仓、目的仓、入仓单汇总箱数；SKU、箱唛和托盘是明细快照/作业维度。
+- **冻结库存**：拣货、换标、废弃、转运等处理中暂时不可重复使用；冻结不等于已经扣减。
+- **库存流水**：每一次入账、冻结、释放、扣减、恢复、SKU 转换和位置变化都应能按业务单号、幂等键追溯。
+- **托盘不是库存归属**：合托后一个物理托盘可以包含多个入仓单，出库、换标和退回必须按托盘组成明细核平。
+
+## 测试场景矩阵
+
+| 场景 | 触发与前置 | 库存变动 | 测试重点 |
+|---|---|---|---|
+| 头程接柜/海外入仓 | 装柜完成事件 → 生成尾程单/入仓计划；PDA 签收、实收、上架、完成 | 在途冻结 → 入仓后 `AVAILABLE` 增加；写库存位置和流水 | 柜号/客户/入仓单隔离；卸柜照片门禁；重复事件不重复入账；失败整事务回滚 |
+| 普通排车出库/派送 | 计划已入仓；排车审核、拣货、箱数核平、发车 | `AVAILABLE` → 冻结/已拣；原子出库后可用库存扣减 | 整托/部分托按组成明细核平；未审核、数量不平、车辆门禁时不得出库；同键重放幂等 |
+| 一件代发 | 已完成入库且有可用箱唛/SKU；创建 `WAIT_PICK` 出库单 | SKU/箱唛库存冻结 → PDA 拣货 → `OUTBOUNDED` 扣减 | 候选只能来自真实可用库存；一单不得跨客户/跨仓；整托扫描任一明细失败必须整体回滚 |
+| 客户换标 | 历史入仓库存可用；客户申请、PDA 扫旧 SKU/箱唛、完工、客户确认 | 旧 SKU/箱唛冻结；换标完成后旧库存转出、新 SKU/箱唛转入；库存总箱数守恒 | 同箱多 SKU 不重复冻结；只移动本单 `hold_packages`；已生成出库单禁止再次拆托；照片/复核/客户确认门禁 |
+| 仓储转运 | 来源库存可用；创建转运、测量、换标（可选）、出库、目标仓收货 | 来源仓冻结/扣减 → 目标仓入账；换标时 SKU 转换 | 来源客户、入仓单和箱数核对；部分转运数量守恒；目标仓与来源仓不能串；重复完成不重复入账 |
+| 货物废弃 | 一件代发/库存货物申请废弃；审批后由绑定海外 PDA 实际确认 | `AVAILABLE` → `DISCARD_PENDING`；实际确认后 SKU、余额、位置扣减并记 `DISCARDED` | 申请阶段只锁箱不扣库存；驳回释放；批准不是实际扣减；实际数量与逐箱流水一致；失败整批回滚 |
+| 异常退回入仓 | 只能选择原出库拣货事实；异常单受理并完成退回 | 原出库来源核验 → `RETURN_STOCK_IN` 恢复到真实目标托盘/库位 | 不能伪造出库来源、借用其他客户主单；退回数量与原实发核平；异常单完成与派送 `RETURNED` 同事务 |
+| PDA 盘点调整 | 绑定海外仓；盘点锁定库存位置并提交实盘数量 | 按差异产生增加/减少调整流水；无差异不产生虚假变动 | 需要 `inventory:adjust`；并发版本校验；差异正负方向正确；盘点重复提交幂等 |
+| PDA 移库/托盘拆合/换绑 | 同仓有效托盘/库位；资源锁成功 | 数量净额不变，仅位置/托盘组成变化，写位置流水 | 不跨仓；托盘组成明细保留；资源锁释放；出库/换标占用时禁止绕过协调单独移动 |
+
+## 不应误判为库存变动
+
+- 目的仓修改、暂扣/解除、报价、排车预排、外接预约、车辆/司机资料：只改变状态、资格、资源占用或费用快照。
+- 海外采购样品履约：按当前契约走 Admin 台账，**不接入 PDA，也不写 WMS 可用库存**。
+- 退货申请/废弃申请/转派送建单：申请或建单阶段只形成冻结/候选/出库单，必须到实际收货、实际扣减或实际出库节点才确认数量变化。
+
+## 每条库存用例的统一断言
+
+1. 变动前后按客户、海外仓、目的仓、入仓单、托盘组成核对数量守恒。
+2. 查询余额、位置明细和库存流水三处结果一致，且业务单号/幂等键可追溯。
+3. 重复请求、重复事件、并发操作不得新增第二笔库存变动。
+4. 任一校验、权限、资源锁或跨服务依赖失败时，库存、单据状态和流水一起回滚。
+5. 客户越权、跨仓、跨客户、伪造来源入仓单/出库单均应拒绝。
+
+流程图：`overseas-inventory-mutation-flow.svg` / `overseas-inventory-mutation-flow.png`

file/AGENTS.md

@@ -1,5 +1,10 @@
 # File Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责与边界
 
 - Mapper 只由 `FileServiceApplication.java` 对 `com.baiyue.file` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。

file/src/main/java/com/baiyue/file/service/BusinessFileCategory.java

@@ -9,6 +9,8 @@ import java.util.Arrays;
 enum BusinessFileCategory {
     FLEET_DRIVER_LICENSE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     FLEET_TRIP_OPERATION_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
+    OVERSEAS_DISPATCH_VEHICLE_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
+    OVERSEAS_DISPATCH_DRIVER_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     FLEET_VEHICLE_RECORD_PHOTO(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     DELIVERY_LOADING_PHOTO(true, FormatPolicy.ARBITRARY, Limits.CUSTOMS, BusinessIdPolicy.POSITIVE_LONG),
     DELIVERY_BOL(true, FormatPolicy.ARBITRARY, Limits.CUSTOMS, BusinessIdPolicy.POSITIVE_LONG),
@@ -67,7 +69,12 @@ enum BusinessFileCategory {
             .orElseThrow(() -> new BizException(ResultCode.BAD_REQUEST, "不支持的附件业务类型"));
     }
 
+    /** 校验文件归属；跨客户排车证据固定为平台所有，不随货物客户变化。 */
     void validateOwner(long tenantId) {
+        if ((this == OVERSEAS_DISPATCH_VEHICLE_EVIDENCE || this == OVERSEAS_DISPATCH_DRIVER_EVIDENCE)
+                && tenantId != 0) {
+            throw new BizException(ResultCode.BAD_REQUEST, "排车车辆及司机证据必须归属平台");
+        }
         if (this == FLEET_TRIP_OPERATION_EVIDENCE && tenantId != 0) {
             throw new BizException(ResultCode.BAD_REQUEST, "出车实测凭证必须归属平台");
         }

file/src/main/resources/openapi/dispatch-evidence-v1.yaml

@@ -0,0 +1,167 @@
+openapi: 3.0.3
+info:
+  title: 平台排车车辆与司机证据内部文件契约
+  version: 1.0.0
+  description: >-
+    复用 InternalBusinessFileController 的现有通用内部入口，不新增公开文件路由。
+    两类证据均固定平台 tenantId=0，businessId 为排车内部正数 Long ID 的十进制表示，
+    不使用车辆 ID、司机 ID、车牌或客户 ID。车辆与司机证据分别使用
+    OVERSEAS_DISPATCH_VEHICLE_EVIDENCE、OVERSEAS_DISPATCH_DRIVER_EVIDENCE，不可互换。
+    File 校验内部服务令牌、平台归属、正数业务 ID、文件非空、最大 10MiB（10485760 字节，包含边界）、
+    PDF/JPG/PNG MIME 及对应内容签名。元数据和下载按 tenantId、businessType、businessId、fileId
+    联合查询 ACTIVE 且未删除文件，错车或错类别均视为归属不匹配，下载前完成归属校验。
+    上传生成不可变文件和真实元数据，不自动绑定证据或通过审核，不返回公开 URL 或存储路径。
+    Lastleg 负责排车存在性、仓库与角色权限、当前及历史附件引用和审核状态；File 不查询 Lastleg 业务表。
+    本文只描述排车网关实际消费的上传、元数据和内容三个操作，不改变通用文件接口的其他用途。
+    统一异常处理使用 HTTP 200 JSON 业务错误，调用方必须检查 code；内容接口错误也返回 JSON，不能当作文件。
+security:
+  - InternalServiceToken: []
+paths:
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+    post:
+      operationId: uploadDispatchEvidence
+      summary: 上传本排车的车辆或司机证据
+      parameters:
+        - name: X-Operator-Id
+          in: header
+          required: true
+          description: Lastleg 已认证操作者的正数 Long ID
+          schema: {$ref: '#/components/schemas/PositiveLongString'}
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: 非空且不超过10485760字节；application/pdf、image/jpeg或image/png，并校验对应内容签名
+      responses:
+        '200': {$ref: '#/components/responses/MetadataOrError'}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+      - {$ref: '#/components/parameters/FileId'}
+    get:
+      operationId: readDispatchEvidenceMetadata
+      summary: 按本排车与证据类别联合校验并读取元数据
+      responses:
+        '200': {$ref: '#/components/responses/MetadataOrError'}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}/content:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+      - {$ref: '#/components/parameters/FileId'}
+    get:
+      operationId: downloadDispatchEvidence
+      summary: 按完整复合归属读取文件内容
+      responses:
+        '200':
+          description: >-
+            成功返回真实文件；错误返回 application/json 统一业务错误。
+            A0400 表示作用域、ID或文件格式无效，A0403 表示内部令牌无效，
+            A0404 表示文件不存在、非有效文件或复合归属不匹配。
+          headers:
+            Cache-Control: {schema: {type: string, enum: [no-store]}}
+            Content-Disposition: {schema: {type: string}, description: 成功时为attachment及UTF-8文件名}
+            Content-Length: {schema: {type: integer, format: int64}, description: 成功时为真实文件字节数}
+          content:
+            application/pdf: {schema: {type: string, format: binary}}
+            image/jpeg: {schema: {type: string, format: binary}}
+            image/png: {schema: {type: string, format: binary}}
+            application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}
+components:
+  securitySchemes:
+    InternalServiceToken: {type: apiKey, in: header, name: X-Internal-Service-Token}
+  parameters:
+    TenantId:
+      name: tenantId
+      in: path
+      required: true
+      description: 两类排车证据只属于平台，客户作用域一律拒绝
+      schema: {type: string, enum: ['0']}
+    BusinessType:
+      name: businessType
+      in: path
+      required: true
+      schema: {$ref: '#/components/schemas/DispatchEvidenceType'}
+    BusinessId:
+      name: businessId
+      in: path
+      required: true
+      description: 排车内部正数Long ID，上限9223372036854775807；Lastleg以标准十进制字符串传入
+      schema: {$ref: '#/components/schemas/PositiveLongString'}
+    FileId:
+      name: fileId
+      in: path
+      required: true
+      schema: {$ref: '#/components/schemas/PositiveLongString'}
+  responses:
+    MetadataOrError:
+      description: >-
+        统一JSON响应，业务成功code为200。A0400为无效平台作用域、ID、操作者或文件；
+        A0403为内部服务令牌无效；A0404为文件不存在、非ACTIVE、已删除或复合归属不匹配；
+        S0503为存储不可用，S0500为元数据保存失败等内部异常。
+      content:
+        application/json:
+          schema:
+            oneOf:
+              - {$ref: '#/components/schemas/MetadataEnvelope'}
+              - {$ref: '#/components/schemas/ErrorEnvelope'}
+  schemas:
+    PositiveLongString:
+      type: string
+      pattern: '^[1-9][0-9]*$'
+      maxLength: 19
+      description: 正数Long的十进制字符串，值不得超过9223372036854775807
+    DispatchEvidenceType:
+      type: string
+      enum: [OVERSEAS_DISPATCH_VEHICLE_EVIDENCE, OVERSEAS_DISPATCH_DRIVER_EVIDENCE]
+    MetadataEnvelope:
+      type: object
+      required: [code, data]
+      properties:
+        code: {type: string, enum: ['200']}
+        message: {type: string}
+        data: {$ref: '#/components/schemas/Metadata'}
+        requestId: {type: string, nullable: true}
+        traceId: {type: string, nullable: true}
+        timestamp: {type: string, format: date-time}
+    Metadata:
+      type: object
+      required: [fileId, ownerScope, tenantId, businessType, businessId, fileName, sha256, contentType, sizeBytes, createdAt]
+      properties:
+        fileId: {$ref: '#/components/schemas/PositiveLongString'}
+        ownerScope: {type: string, enum: [PLATFORM]}
+        tenantId: {type: string, enum: ['0']}
+        businessType: {$ref: '#/components/schemas/DispatchEvidenceType'}
+        businessId: {$ref: '#/components/schemas/PositiveLongString'}
+        fileName: {type: string, minLength: 1, description: 清理路径和控制字符后的原始文件名}
+        sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        contentType: {type: string, enum: [application/pdf, image/jpeg, image/png]}
+        sizeBytes:
+          type: string
+          pattern: '^[1-9][0-9]*$'
+          description: 实际字节数，范围1到10485760；公共Jackson配置将Long输出为字符串
+          example: '1024'
+        createdAt: {type: string, description: File真实上传时间，LocalDateTime的ISO本地时间表示，无时区偏移}
+    ErrorEnvelope:
+      type: object
+      required: [code, data]
+      properties:
+        code: {type: string, enum: [A0400, A0403, A0404, A0422, S0500, S0503]}
+        message: {type: string}
+        data: {type: object, nullable: true, description: 业务错误为null；参数校验错误可携带字段信息}
+        requestId: {type: string, nullable: true}
+        traceId: {type: string, nullable: true}
+        timestamp: {type: string, format: date-time}

file/src/test/java/com/baiyue/file/service/DispatchEvidenceFileTest.java

@@ -0,0 +1,245 @@
+package com.baiyue.file.service;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.file.controller.InternalBusinessFileController;
+import com.baiyue.file.entity.FileObjectEntity;
+import com.baiyue.file.mapper.FileObjectMapper;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.mock.web.MockMultipartFile;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.ByteArrayOutputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Arrays;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.regex.Pattern;
+
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+class DispatchEvidenceFileTest {
+    private static final String VEHICLE = "OVERSEAS_DISPATCH_VEHICLE_EVIDENCE";
+    private static final String DRIVER = "OVERSEAS_DISPATCH_DRIVER_EVIDENCE";
+    private static final int MAX_BYTES = 10 * 1024 * 1024;
+    @TempDir Path root;
+
+    /** 初始化真实 Lambda 查询列映射，使测试能逐列核对复合归属条件。 */
+    @BeforeAll static void metadata() {
+        TableInfoHelper.initTableInfo(new MapperBuilderAssistant(new MybatisConfiguration(), "dispatch-evidence"),
+            FileObjectEntity.class);
+    }
+
+    /** 两类证据只接受平台与有效排车内部 ID，非法输入不得访问数据库或磁盘。 */
+    @ParameterizedTest
+    @ValueSource(strings = {VEHICLE, DRIVER})
+    void requiresPlatformAndPositiveDispatchIdBeforeAccess(String type) {
+        var files = mock(FileObjectMapper.class);
+        var storage = mock(BusinessFileStorage.class);
+        var service = service(files, storage);
+        var upload = pdf();
+        for (long customer : new long[]{-1, 1, 900}) {
+            assertThatThrownBy(() -> service.upload(customer, type, "71", 7, upload)).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> service.metadata(customer, type, "71", 501)).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> service.download(customer, type, "71", 501)).isInstanceOf(BizException.class);
+        }
+        for (String id : new String[]{"0", "-1", "DISPATCH-71", "../71", "9223372036854775808"}) {
+            assertThatThrownBy(() -> service.upload(0, type, id, 7, upload)).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> service.metadata(0, type, id, 501)).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> service.download(0, type, id, 501)).isInstanceOf(BizException.class);
+        }
+        assertThatThrownBy(() -> service.upload(0, type, "71", 0, upload)).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.metadata(0, type, "71", 0)).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.download(0, type, "71", 0)).isInstanceOf(BizException.class);
+        verifyNoInteractions(files, storage);
+    }
+
+    /** 真实 PDF、JPG、PNG 均可写入并保持内容；上传不以扩展名代替 MIME 和签名。 */
+    @ParameterizedTest
+    @ValueSource(strings = {VEHICLE, DRIVER})
+    void storesPdfJpegPngAndRejectsEmptyUnsupportedAndSpoofedContent(String type) throws Exception {
+        var storage = storage();
+        var category = BusinessFileCategory.require(type);
+        for (var file : new MockMultipartFile[]{pdf(),
+                new MockMultipartFile("file", "vehicle.jpg", "image/jpeg", image("jpeg")),
+                new MockMultipartFile("file", "driver.png", "image/png", image("png"))}) {
+            var saved = storage.store(0, "71", file, category);
+            assertThat(storage.read(saved.objectKey())).isEqualTo(file.getBytes());
+            assertThat(saved.contentType()).isEqualTo(file.getContentType());
+            assertThat(saved.size()).isEqualTo(file.getSize());
+            assertThat(saved.sha256()).matches("[0-9a-f]{64}");
+        }
+        for (var file : new MockMultipartFile[]{
+                new MockMultipartFile("file", "empty.pdf", "application/pdf", new byte[0]),
+                new MockMultipartFile("file", "fake.pdf", "application/pdf", "plain text".getBytes(StandardCharsets.UTF_8)),
+                new MockMultipartFile("file", "fake.jpg", "image/jpeg", image("png")),
+                new MockMultipartFile("file", "fake.png", "image/png", image("jpeg")),
+                new MockMultipartFile("file", "fake.pdf", "text/plain", pdf().getBytes()),
+                new MockMultipartFile("file", "fake.pdf", "application/octet-stream", pdf().getBytes()),
+                new MockMultipartFile("file", "missing.pdf", null, pdf().getBytes())}) {
+            assertThatThrownBy(() -> storage.store(0, "71", file, category)).isInstanceOf(BizException.class);
+        }
+        assertThatThrownBy(() -> storage.store(0, "71", null, category)).isInstanceOf(BizException.class);
+    }
+
+    /** 10MiB 为包含边界，超限在读取内容或落盘前拒绝。 */
+    @ParameterizedTest
+    @ValueSource(strings = {VEHICLE, DRIVER})
+    void acceptsExactlyTenMibAndRejectsOneByteOverBeforeReading(String type) throws Exception {
+        var storage = storage();
+        var category = BusinessFileCategory.require(type);
+        byte[] content = Arrays.copyOf(pdf().getBytes(), MAX_BYTES);
+        var boundary = new MockMultipartFile("file", "boundary.pdf", "application/pdf", content);
+        var stored = storage.store(0, "71", boundary, category);
+        assertThat(Files.size(root.resolve(stored.objectKey()))).isEqualTo(MAX_BYTES);
+        var oversized = mock(MultipartFile.class);
+        when(oversized.isEmpty()).thenReturn(false);
+        when(oversized.getSize()).thenReturn((long) MAX_BYTES + 1);
+        assertThatThrownBy(() -> storage.store(0, "71", oversized, category))
+            .isInstanceOf(BizException.class).hasMessageContaining("10MB");
+        verify(oversized, never()).getInputStream();
+        verify(oversized, never()).transferTo(any(Path.class));
+    }
+
+    /** 上传生成独立不可变对象和真实元数据；替换引用不覆盖原文件。 */
+    @ParameterizedTest
+    @ValueSource(strings = {VEHICLE, DRIVER})
+    void uploadsKeepPlatformDispatchScopeAndImmutableObjects(String type) throws Exception {
+        var files = mock(FileObjectMapper.class);
+        var storage = storage();
+        var service = service(files, storage);
+        var ids = new AtomicLong(500);
+        when(files.insert(any(FileObjectEntity.class))).thenAnswer(call -> {
+            FileObjectEntity row = call.getArgument(0);
+            row.setId(ids.incrementAndGet());
+            return 1;
+        });
+        var first = service.upload(0, type, "71", 7, pdf());
+        var secondFile = new MockMultipartFile("file", "updated.pdf", "application/pdf",
+            "%PDF-1.7\nupdated".getBytes(StandardCharsets.US_ASCII));
+        var second = service.upload(0, type, "71", 7, secondFile);
+        var rows = org.mockito.ArgumentCaptor.forClass(FileObjectEntity.class);
+        verify(files, times(2)).insert(rows.capture());
+        assertThat(first.ownerScope()).isEqualTo("PLATFORM");
+        assertThat(first.tenantId()).isZero();
+        assertThat(first.businessType()).isEqualTo(type);
+        assertThat(first.businessId()).isEqualTo("71");
+        assertThat(first.fileId()).isEqualTo(501L);
+        assertThat(second.fileId()).isEqualTo(502L);
+        assertThat(first.fileName()).isEqualTo("evidence.pdf");
+        assertThat(first.contentType()).isEqualTo("application/pdf");
+        assertThat(first.sizeBytes()).isEqualTo(pdf().getSize());
+        assertThat(first.sha256()).matches("[0-9a-f]{64}");
+        assertThat(first.createdAt()).isNotNull().isEqualTo(rows.getAllValues().get(0).getCreatedAt());
+        assertThat(rows.getAllValues().get(0).getObjectKey()).isNotEqualTo(rows.getAllValues().get(1).getObjectKey());
+        assertThat(storage.read(rows.getAllValues().get(0).getObjectKey())).isEqualTo(pdf().getBytes());
+        assertThat(storage.read(rows.getAllValues().get(1).getObjectKey())).isEqualTo(secondFile.getBytes());
+        verify(files, never()).updateById(any(FileObjectEntity.class));
+    }
+
+    /** 元数据和下载均逐列带全复合键；错车、错类别、错文件不得读取存储内容。 */
+    @ParameterizedTest
+    @ValueSource(strings = {VEHICLE, DRIVER})
+    void metadataAndDownloadEnforceEveryScopeKeyBeforeReading(String type) throws Exception {
+        var files = mock(FileObjectMapper.class);
+        var storage = mock(BusinessFileStorage.class);
+        var service = service(files, storage);
+        var row = new FileObjectEntity();
+        row.setId(501L); row.setTenantId(0L); row.setBusinessType(type); row.setBusinessId("71");
+        row.setOriginalName("evidence.pdf"); row.setContentType("application/pdf");
+        row.setObjectKey("business-files/0/71/evidence.pdf"); row.setSizeBytes(pdf().getSize());
+        row.setSha256("a".repeat(64)); row.setCreatedAt(java.time.LocalDateTime.now());
+        when(files.selectOne(any())).thenAnswer(call -> {
+            LambdaQueryWrapper<FileObjectEntity> query = call.getArgument(0);
+            assertThat(boundValue(query, "status")).isEqualTo("ACTIVE");
+            assertThat(boundValue(query, "deleted")).isEqualTo(false);
+            return Long.valueOf(0).equals(boundValue(query, "tenant_id"))
+                && type.equals(boundValue(query, "business_type"))
+                && "71".equals(boundValue(query, "business_id"))
+                && Long.valueOf(501).equals(boundValue(query, "id")) ? row : null;
+        });
+        when(storage.read(row.getObjectKey())).thenReturn(pdf().getBytes());
+        var metadata = service.metadata(0, type, "71", 501);
+        assertThat(metadata.fileId()).isEqualTo(501L);
+        assertThat(metadata.ownerScope()).isEqualTo("PLATFORM");
+        assertThat(service.download(0, type, "71", 501).content()).isEqualTo(pdf().getBytes());
+        verify(storage).read(row.getObjectKey());
+        clearInvocations(storage);
+        String otherType = VEHICLE.equals(type) ? DRIVER : VEHICLE;
+        for (String candidate : new String[]{otherType, "FLEET_DRIVER_LICENSE", "FLEET_TRIP_OPERATION_EVIDENCE"}) {
+            assertThatThrownBy(() -> service.metadata(0, candidate, "71", 501))
+                .isInstanceOf(BizException.class).hasMessageContaining("归属不匹配");
+            assertThatThrownBy(() -> service.download(0, candidate, "71", 501))
+                .isInstanceOf(BizException.class).hasMessageContaining("归属不匹配");
+        }
+        assertThatThrownBy(() -> service.metadata(0, type, "72", 501)).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.download(0, type, "72", 501)).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.metadata(0, type, "71", 502)).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.download(0, type, "71", 502)).isInstanceOf(BizException.class);
+        verifyNoInteractions(storage);
+    }
+
+    /** 内部服务令牌在业务访问前校验，不对未授权请求暴露元数据或文件。 */
+    @ParameterizedTest
+    @ValueSource(strings = {VEHICLE, DRIVER})
+    void invalidInternalTokenCannotUploadReadMetadataOrDownload(String type) {
+        var service = mock(InternalBusinessFileService.class);
+        var controller = new InternalBusinessFileController();
+        ReflectionTestUtils.setField(controller, "expected", "dispatch-test-token");
+        ReflectionTestUtils.setField(controller, "service", service);
+        for (String token : new String[]{null, "", "wrong-token"}) {
+            assertThatThrownBy(() -> controller.upload(token, 7, 0, type, "71", pdf())).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> controller.metadata(token, 0, type, "71", 501)).isInstanceOf(BizException.class);
+            assertThatThrownBy(() -> controller.download(token, 0, type, "71", 501)).isInstanceOf(BizException.class);
+        }
+        verifyNoInteractions(service);
+    }
+
+    /** 从实际 SQL 绑定中取指定列的等值条件，缺少任一隔离条件直接失败。 */
+    private static Object boundValue(LambdaQueryWrapper<FileObjectEntity> query, String column) {
+        var matcher = Pattern.compile("(?<![A-Za-z0-9_])" + column
+            + " = #\\{ew\\.paramNameValuePairs\\.([^}]+)}").matcher(query.getSqlSegment());
+        assertThat(matcher.find()).as("复合归属条件 %s", column).isTrue();
+        return query.getParamNameValuePairs().get(matcher.group(1));
+    }
+
+    /** 创建隔离临时目录中的真实存储，不访问运行环境。 */
+    private BusinessFileStorage storage() {
+        var storage = new BusinessFileStorage();
+        ReflectionTestUtils.setField(storage, "configuredRoot", root);
+        storage.initializeRoot();
+        return storage;
+    }
+
+    /** 复用生产服务，数据库边界由 Mapper 替身记录实际查询。 */
+    private InternalBusinessFileService service(FileObjectMapper files, BusinessFileStorage storage) {
+        var service = new InternalBusinessFileService();
+        ReflectionTestUtils.setField(service, "files", files);
+        ReflectionTestUtils.setField(service, "storage", storage);
+        return service;
+    }
+
+    /** 提供具有真实 PDF 文件头的最小上传内容。 */
+    private static MockMultipartFile pdf() {
+        return new MockMultipartFile("file", "evidence.pdf", "application/pdf",
+            "%PDF-1.7\nevidence".getBytes(StandardCharsets.US_ASCII));
+    }
+
+    /** 使用图像编码器生成真实 JPG、PNG，避免测试只验证扩展名。 */
+    private static byte[] image(String format) throws java.io.IOException {
+        var output = new ByteArrayOutputStream();
+        var image = new java.awt.image.BufferedImage(2, 2, java.awt.image.BufferedImage.TYPE_INT_RGB);
+        assertThat(javax.imageio.ImageIO.write(image, format, output)).isTrue();
+        return output.toByteArray();
+    }
+}

finance/AGENTS.md

@@ -1,5 +1,10 @@
 # Finance Service Instructions
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 模块定位
 
 - 本模块是独立财务服务，拥有客户结算条款、财务费用来源、CNY 账单与明细、客户资金账户及充值申请、应收款月度统计、客户对账确认、收款及分配、成本及分摊、账单修订、单据编号、幂等记录和财务审计状态。

firstleg/AGENTS.md

@@ -1,5 +1,10 @@
 # Firstleg Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责与边界
 
 - Mapper 统一显式使用 `@Mapper`，仅由 `BaiyueFirstlegApplication.java` 对 `com.baiyue.firstleg` 根包按 `annotationClass = Mapper.class` 扫描；禁止恢复业务子域 Mapper 包白名单。静态门禁见根 `scripts/mapper-scan-contract.mjs`，模块内编译门禁见 `MapperRegistrationArchitectureTest.java`、`BaiyueFirstlegApplicationContractTest.java`。

firstleg/src/main/java/com/baiyue/firstleg/controller/PlatformDropshipPalletizationController.java

@@ -35,6 +35,28 @@ public class PlatformDropshipPalletizationController {
     @Resource private DropshipPalletizationService service;
     @Resource private InboundCartonLabelPrintService printService;
 
+    /** 跨票识别箱码只读预览，清点仍按原任务领取并提交。 */
+    @GetMapping("/cartons/resolve")
+    @PreAuthorize("hasAuthority('platform:firstleg:pda:view')")
+    public ApiResponse<DropshipPalletizationDtos.ScanContext> resolveWorkspaceCarton(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam @Positive long warehouseId,
+        @RequestParam @jakarta.validation.constraints.NotBlank @Size(max = 80) String boxCode) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.resolveWorkspaceCarton(warehouseId, boxCode, user.userId()));
+    }
+
+    /** 获取当前实物托盘及客户组成，不要求托盘已与当前票绑定。 */
+    @GetMapping("/pallets/resolve")
+    @PreAuthorize("hasAuthority('platform:firstleg:pda:view')")
+    public ApiResponse<DropshipPalletizationDtos.PalletWorkspace> workspacePallet(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam @Positive long warehouseId,
+        @RequestParam @jakarta.validation.constraints.Pattern(regexp = "DP-[0-9]{6}-[0-9]{4}") String palletNo) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.workspacePallet(warehouseId, palletNo));
+    }
+
     @GetMapping("/tasks/pending")
     @PreAuthorize("hasAuthority('platform:firstleg:pda:view')")
     public ApiResponse<List<DropshipPalletizationDtos.PendingTask>> pending(

firstleg/src/main/java/com/baiyue/firstleg/dto/DropshipPalletizationDtos.java

@@ -18,6 +18,15 @@ public final class DropshipPalletizationDtos {
 
     public record ClaimRequest(@Positive long warehouseId) {}
 
+    /** 跨票只读识别结果；确认清点前仍须领取对应任务。 */
+    public record ScanContext(Task task, Carton carton) {}
+
+    /** 当前实物托盘及逐客户、逐票组成。 */
+    public record PalletWorkspace(Pallet pallet, List<PalletMember> members) {}
+
+    public record PalletMember(Long taskId, Long inboundId, String inboundCode,
+                               Long customerId, String customerName, Integer cartonCount) {}
+
     public enum DiscrepancyAction { MATCH, ACCEPT_VARIANCE }
 
     public record CountCartonRequest(@Positive long warehouseId,

firstleg/src/main/java/com/baiyue/firstleg/dto/MerchantWorkbenchFilters.java

@@ -10,7 +10,8 @@ public final class MerchantWorkbenchFilters {
     private MerchantWorkbenchFilters() {}
 
     public record Request(@NotNull @Positive Long tenantId,
-        @Pattern(regexp = "WAIT_MEASURE|WAIT_PALLETIZE|WAIT_SPLIT|LOADING|LOADED|DELIVERED") String mainStatus) {}
+        @Pattern(regexp = "WAIT_MEASURE|WAIT_PALLETIZE|WAIT_SPLIT|LOADING|LOADED|DELIVERED") String mainStatus,
+        @jakarta.validation.constraints.Size(min=1,max=200) List<@NotNull @Positive Long> orderIds) {}
 
     public record Response(List<Long> matchingStatusOrderIds, List<Long> feeOrderIds,
                            List<Long> customsOrderIds, List<Progress> progress) {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/DropshipPalletizationMapper.java

@@ -15,6 +15,45 @@ import java.util.List;
 /** 一件代发逐箱清点、待绑托与封托事实。 */
 @Mapper
 public interface DropshipPalletizationMapper {
+ /** 在指定仓库按稳定箱码识别任务，多个匹配由业务层拒绝。 */
+ @Select("""
+  SELECT DISTINCT t.id FROM fl_dropship_pallet_task t
+  JOIN fl_inbound_order o ON o.id=t.inbound_id AND o.tenant_id=t.tenant_id AND o.deleted=0
+  JOIN fl_inbound_carton_label l ON l.inbound_id=t.inbound_id AND l.tenant_id=t.tenant_id
+  WHERE t.warehouse_id=#{warehouseId} AND l.box_code=#{boxCode} AND l.batch_status='ACTIVE'
+    AND o.fulfillment_type='ONE_CLICK_DROPSHIP'
+  """)
+ List<Long> workspaceTaskIds(@Param("warehouseId") long warehouseId,@Param("boxCode") String boxCode);
+
+ /** 扫码预览为只读查询，不能把未知或已封托托盘默认成开放。 */
+ @Select("SELECT * FROM fl_dropship_pallet WHERE warehouse_id=#{warehouseId} AND pallet_no=#{palletNo}")
+ PalletRow workspacePallet(@Param("warehouseId") long warehouseId,@Param("palletNo") String palletNo);
+
+ /** 按实际成员汇总客户与票，空的预生成托盘不虚构成员。 */
+ @Select("""
+  SELECT c.task_id,c.inbound_id,o.inbound_code,c.tenant_id customer_id,o.customer_name,COUNT(*) carton_count
+  FROM fl_dropship_pallet_carton c
+  JOIN fl_inbound_order o ON o.id=c.inbound_id AND o.tenant_id=c.tenant_id
+  WHERE c.pallet_id=#{palletId}
+  GROUP BY c.task_id,c.inbound_id,o.inbound_code,c.tenant_id,o.customer_name
+  ORDER BY o.inbound_code,c.task_id
+  """)
+ List<com.baiyue.firstleg.dto.DropshipPalletizationDtos.PalletMember> workspaceMembers(@Param("palletId") long palletId);
+
+ /** 混托成员必须与当前票同渠道、同目的仓，客户可以不同。 */
+ @Select("""
+  SELECT COUNT(*) FROM fl_dropship_pallet_carton c
+  JOIN fl_inbound_order o ON o.id=c.inbound_id AND o.tenant_id=c.tenant_id
+  JOIN fl_dropship_pallet_task t ON t.id=#{taskId}
+  JOIN fl_inbound_order target ON target.id=t.inbound_id AND target.tenant_id=t.tenant_id
+  WHERE c.pallet_id=#{palletId} AND (
+    NOT (o.channel_code <=> target.channel_code)
+    OR NOT (o.destination_type <=> target.destination_type)
+    OR NOT (o.destination_warehouse_id <=> target.destination_warehouse_id)
+    OR NOT (o.destination_code <=> target.destination_code))
+  """)
+ int workspaceIncompatibleMembers(@Param("taskId") long taskId,@Param("palletId") long palletId);
+
  @Insert("""
   INSERT IGNORE INTO fl_dropship_pallet_task
   (id,tenant_id,inbound_id,warehouse_id,task_status,total_cartons,counted_cartons,allocated_cartons,discrepancy_cartons,version,created_at,updated_at)

firstleg/src/main/java/com/baiyue/firstleg/mapper/MerchantWorkbenchFilterMapper.java

@@ -65,6 +65,7 @@ public interface MerchantWorkbenchFilterMapper {
     List<Long> pendingCustoms(@Param("tenantId") long tenantId);
     /** Only physically loaded fragments can expose container milestones to the customer. */
     @Select("""
+        <script>
         SELECT o.order_id, CASE WHEN owned.container_booking_id IS NULL THEN 0
                WHEN EXISTS (SELECT 1 FROM fl_carrier_schedule_node_fact n
                  WHERE n.container_booking_id=owned.container_booking_id
@@ -76,6 +77,11 @@ public interface MerchantWorkbenchFilterMapper {
         LEFT JOIN (
           SELECT DISTINCT i.inbound_id, i.account_id, p.id AS loading_plan_id, p.container_booking_id
           FROM fl_loading_plan_item i
+          <if test="orderIds != null">
+          JOIN fl_inbound_order selected ON selected.id=i.inbound_id AND selected.tenant_id=i.account_id
+            AND selected.deleted=0 AND selected.order_id IN
+            <foreach collection="orderIds" item="id" open="(" separator="," close=")">#{id}</foreach>
+          </if>
           JOIN fl_loading_plan p ON p.id=i.loading_plan_id AND p.plan_status='COMPLETED'
           JOIN fl_loading_pick_task t ON t.loading_plan_id=p.id AND t.task_status='COMPLETED'
           JOIN fl_loading_pick_item picked ON picked.pick_task_id=t.id AND picked.loading_plan_item_id=i.id
@@ -84,8 +90,12 @@ public interface MerchantWorkbenchFilterMapper {
             AND picked.item_status IN ('PICKED','PARTIAL') AND picked.picked_package_count>0
         ) owned ON owned.inbound_id=o.id AND owned.account_id=o.tenant_id
         WHERE o.tenant_id=#{tenantId} AND o.deleted=0 AND o.order_id IS NOT NULL
-          AND o.process_status <> 'CANCELLED'
+          AND o.process_status &lt;&gt; 'CANCELLED'
+          <if test="orderIds != null">
+            AND o.order_id IN <foreach collection="orderIds" item="id" open="(" separator="," close=")">#{id}</foreach>
+          </if>
         ORDER BY o.order_id
+        </script>
         """)
-    List<com.baiyue.firstleg.dto.MerchantWorkbenchFilters.Fragment> progressFragments(@Param("tenantId") long tenantId);
+    List<com.baiyue.firstleg.dto.MerchantWorkbenchFilters.Fragment> progressFragments(@Param("tenantId") long tenantId, @Param("orderIds") List<Long> orderIds);
 }

firstleg/src/main/java/com/baiyue/firstleg/portschedule/mapper/AppointmentWorkSourceMapper.java

@@ -10,8 +10,12 @@ public interface AppointmentWorkSourceMapper {
         String destinationWarehouseName, LocalDateTime departedLocalAt, LocalDateTime sailedEvidenceLocalAt, int version, long factVersion, long deliveryVersion) { }
     record Cargo(long inboundId, long customerId, long orderId, String orderNo, String inboundCode,
         String destinationKind, String destinationCode, String destinationName, int packageCount) { }
+    record ContainerCargo(long containerBookingId,long inboundId,long customerId,long orderId,String orderNo,String inboundCode,
+        String destinationKind,String destinationCode,String destinationName,int packageCount) {
+        public Cargo cargo() { return new Cargo(inboundId,customerId,orderId,orderNo,inboundCode,destinationKind,destinationCode,destinationName,packageCount); }
+    }
 
-    String SOURCES = """
+    String SOURCE_ROWS = """
         SELECT b.id,b.cabinet_no,b.container_no,b.departure_port_name,b.destination_warehouse_name,
           MIN(CASE WHEN f.standard_node='DEPARTED_ORIGIN_PORT' THEN f.actual_at END) departed_local_at,
           MIN(f.actual_at) sailed_evidence_local_at,
@@ -21,23 +25,40 @@ public interface AppointmentWorkSourceMapper {
         WHERE b.record_status='ACTIVE' AND f.actual_at IS NOT NULL
           AND f.standard_node IN ('DEPARTED_ORIGIN_PORT','IN_TRANSIT','ARRIVED_DESTINATION_PORT',
             'DISCHARGED_FROM_VESSEL','PICKUP_READY','PICKED_UP','EMPTY_RETURNED')
+        """;
+    String SOURCE_ORDER = """
         GROUP BY b.id,b.cabinet_no,b.container_no,b.departure_port_name,b.destination_warehouse_name,b.version
         ORDER BY b.id
         """;
     // A complete identity/version manifest also detects deletions or edits between cursor pages.
-    @Select(SOURCES)
+    @Select(SOURCE_ROWS + SOURCE_ORDER)
     List<Source> sources();
 
+    /** Same live eligibility and aggregate facts as the manifest, restricted before aggregation. */
+    @Select("<script>" + SOURCE_ROWS + """
+        <choose>
+          <when test="ids != null and !ids.isEmpty()">
+            AND b.id IN <foreach collection='ids' item='id' open='(' separator=',' close=')'>#{id}</foreach>
+          </when>
+          <otherwise>AND 1=0</otherwise>
+        </choose>
+        """ + SOURCE_ORDER + "</script>")
+    List<Source> sourcesByIds(@Param("ids") List<Long> ids);
+
     @Select("""
-        SELECT i.inbound_id, i.account_id customer_id, i.order_id, i.order_no,i.inbound_code,
+        <script>
+        SELECT p.container_booking_id,i.inbound_id, i.account_id customer_id, i.order_id, i.order_no,i.inbound_code,
           o.destination_type destination_kind,i.destination_warehouse_code destination_code,
           i.destination_warehouse_name destination_name,SUM(i.package_count) package_count
         FROM fl_loading_plan p JOIN fl_loading_plan_item i ON i.loading_plan_id=p.id AND i.deleted=0
           JOIN fl_inbound_order o ON o.id=i.inbound_id
-        WHERE p.container_booking_id=#{id} AND p.plan_status='COMPLETED'
+        WHERE p.container_booking_id IN
-        GROUP BY i.inbound_id,i.account_id,i.order_id,i.order_no,i.inbound_code,o.destination_type,
+          <foreach collection='ids' item='id' open='(' separator=',' close=')'>#{id}</foreach>
+          AND p.plan_status='COMPLETED'
+        GROUP BY p.container_booking_id,i.inbound_id,i.account_id,i.order_id,i.order_no,i.inbound_code,o.destination_type,
           i.destination_warehouse_code,i.destination_warehouse_name
-        ORDER BY i.inbound_id
+        ORDER BY p.container_booking_id,i.inbound_id
+        </script>
         """)
-    List<Cargo> cargo(@Param("id") long id);
+    List<ContainerCargo> cargo(@Param("ids") List<Long> ids);
 }

firstleg/src/main/java/com/baiyue/firstleg/portschedule/service/AppointmentWorkSourceService.java

@@ -13,8 +13,8 @@ import java.util.*;
 @Service
 public class AppointmentWorkSourceService {
     public interface OriginalFacts {
-        String establishedFlow(long containerBookingId);
+        Map<Long,String> establishedFlows(List<Long> containerBookingIds);
-        Fact read(FactRequest request, ContainerSource source);
+        List<Fact> read(List<FactRequest> requests, Map<Long,ContainerSource> sources);
     }
     private final AppointmentWorkSourceMapper mapper;
     private final OriginalFacts original;
@@ -37,14 +37,23 @@ public class AppointmentWorkSourceService {
         var page=rows.stream().filter(row->row.id()>cursor).limit(size+1L).toList();
         boolean complete=page.size()<=size;
         var selected=page.stream().limit(size).toList();
-        return new SourcePage(selected.stream().map(this::source).toList(),complete?null:scope+":"+selected.get(selected.size()-1).id(),complete,scope);
+        return new SourcePage(sources(selected),complete?null:scope+":"+selected.get(selected.size()-1).id(),complete,scope);
     }
     public ContainerSource container(long id) {
-        return mapper.sources().stream().filter(row->row.id()==id).findFirst().map(this::source)
+        var row=mapper.sources().stream().filter(candidate->candidate.id()==id).findFirst()
             .orElseThrow(()->new ResponseStatusException(HttpStatus.NOT_FOUND,"未找到有效已开船柜次"));
+        return sources(List.of(row)).get(0);
     }
-    private ContainerSource source(AppointmentWorkSourceMapper.Source row) {
+    private List<ContainerSource> sources(List<AppointmentWorkSourceMapper.Source> rows) {
-        var cargo=mapper.cargo(row.id());
+        if(rows.isEmpty()) return List.of();
+        var ids=rows.stream().map(AppointmentWorkSourceMapper.Source::id).toList();
+        var cargo=new HashMap<Long,List<AppointmentWorkSourceMapper.Cargo>>();
+        for(var item:mapper.cargo(ids)) cargo.computeIfAbsent(item.containerBookingId(),ignored->new ArrayList<>()).add(item.cargo());
+        var flows=original.establishedFlows(ids);
+        return rows.stream().map(row->source(row,cargo.getOrDefault(row.id(),List.of()),flows.get(row.id()))).toList();
+    }
+    private ContainerSource source(AppointmentWorkSourceMapper.Source row,List<AppointmentWorkSourceMapper.Cargo> cargo,String flow) {
+        if(flow==null) throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE,"柜次路线事实读取不完整");
         var requirements=cargo.stream().map(c->new Requirement("INBOUND:"+c.inboundId(),null,null,
             c.destinationKind(),row.departurePortName(),c.destinationName(),null,
             List.of(new Reference("CUSTOMER",Long.toString(c.customerId()),null,"所属客户"),
@@ -52,18 +61,22 @@ public class AppointmentWorkSourceService {
                 new Reference("INBOUND",Long.toString(c.inboundId()),c.inboundCode(),"入仓单"),
                 new Reference("CONTAINER",Long.toString(row.id()),row.cabinetNo(),"柜次")),List.of(),List.of())).toList();
         return new ContainerSource(Long.toString(row.id()),row.containerNo(),null,row.departedLocalAt(),row.sailedEvidenceLocalAt(),
-            hash(List.of(row,cargo)),original.establishedFlow(row.id()),null,requirements);
+            hash(List.of(row,cargo)),flow,null,requirements);
     }
     public List<Fact> facts(List<FactRequest> requests) {
         if(requests==null || requests.isEmpty() || requests.size()>200) throw bad("事实请求须包含1至200项");
-        Set<String> keys=new HashSet<>(); Map<Long,ContainerSource> sources=new HashMap<>();
+        Set<String> keys=new HashSet<>(); var ids=new LinkedHashSet<Long>();
-        return requests.stream().map(request->{
+        for(var request:requests) {
             if(request==null || request.workItemKey()==null || request.workItemKey().isBlank() || !keys.add(request.workItemKey())
                 || !("PICKUP".equals(request.type()) || "EMPTY_RETURN".equals(request.type()) || "DELIVERY".equals(request.type()) && "DIRECT".equals(request.flow())))
                 throw bad("事项身份或事实类型无效");
-            long id=id(request.containerBookingId());
+            ids.add(id(request.containerBookingId()));
-            return original.read(request,sources.computeIfAbsent(id,this::container));
+        }
-        }).toList();
+        var selected=mapper.sourcesByIds(List.copyOf(ids));
+        if(selected.size()!=ids.size()) throw new ResponseStatusException(HttpStatus.NOT_FOUND,"未找到有效已开船柜次");
+        var sources=new LinkedHashMap<Long,ContainerSource>();
+        sources(selected).forEach(source->sources.put(Long.parseLong(source.containerBookingId()),source));
+        return original.read(requests,sources);
     }
     public String hash(Object value) {
         try {return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(json.writeValueAsBytes(value)));}

firstleg/src/main/java/com/baiyue/firstleg/repository/DropshipWorkspaceRepository.java

@@ -0,0 +1,39 @@
+package com.baiyue.firstleg.repository;
+
+import com.baiyue.firstleg.dto.DropshipPalletizationDtos.PalletMember;
+import com.baiyue.firstleg.mapper.DropshipPalletizationMapper;
+import com.baiyue.firstleg.mapper.DropshipPalletizationMapper.PalletRow;
+import jakarta.annotation.Resource;
+import org.springframework.stereotype.Repository;
+import java.util.List;
+
+/** 仓内跨票扫码与实物托盘组成查询，客户归属始终从箱唛事实取得。 */
+@Repository
+public class DropshipWorkspaceRepository {
+    @Resource private DropshipPalletizationMapper mapper;
+
+    /** 按仓库和稳定箱码查找作业任务，不接受客户端指定客户归属。 */
+    public List<Long> taskIdsForBox(long warehouseId, String boxCode) {
+        return mapper.workspaceTaskIds(warehouseId, boxCode);
+    }
+
+    /** 只读查询托盘，不因扫描托盘产生绑定或状态变化。 */
+    public PalletRow pallet(long warehouseId, String palletNo) {
+        return mapper.workspacePallet(warehouseId, palletNo);
+    }
+
+    /** 保留每票客户与任务身份，供混托核对和按原任务移箱。 */
+    public List<PalletMember> members(long palletId) {
+        return mapper.workspaceMembers(palletId);
+    }
+
+    /** 归托前锁定实物托盘，与封托互斥。 */
+    public PalletRow lockPallet(String palletNo) {
+        return mapper.palletByNo(palletNo);
+    }
+
+    /** 按原始入仓快照检查运输兼容性，不接受客户端声明。 */
+    public boolean compatible(long taskId, long palletId) {
+        return mapper.workspaceIncompatibleMembers(taskId, palletId) == 0;
+    }
+}

firstleg/src/main/java/com/baiyue/firstleg/service/DropshipPalletizationService.java

@@ -21,6 +21,34 @@ import java.util.*;
 public class DropshipPalletizationService {
  @Resource private DropshipPalletizationMapper mapper;
  @Resource private FirstlegDocumentNumberGenerator documentNumbers;
+ @Resource private com.baiyue.firstleg.repository.DropshipWorkspaceRepository workspaceRepository;
+
+ /** 只读识别其他客户的箱码；不自动领取、清点或绑定托盘。 */
+ public ScanContext resolveWorkspaceCarton(long warehouseId,String boxCode,long operatorId){
+  String code=normalize(boxCode);
+  if(code==null) throw invalid("箱码不能为空");
+  List<Long> ids=workspaceRepository.taskIdsForBox(warehouseId,code);
+  if(ids.isEmpty()) throw new BizException(ResultCode.NOT_FOUND,"当前仓库未找到该一件代发箱码");
+  if(ids.size()!=1) throw conflict("箱码匹配多个任务，请联系后台核对");
+  Task target=task(ids.get(0),warehouseId,operatorId);
+  Carton carton=resolveCarton(target.taskId(),warehouseId,code,operatorId);
+  // 未领取任务仅允许预览，员工确认后由正式领取与清点接口再次检查权限和状态。
+  if("PENDING".equals(target.taskStatus()) && Boolean.TRUE.equals(target.palletSetupReady())
+     && "请先领取任务".equals(carton.blockReason())){
+   carton=new Carton(carton.cartonId(),carton.boxCode(),carton.inboundId(),carton.inboundCode(),
+    carton.skuLines(),carton.countStatus(),carton.palletId(),carton.palletNo(),true,null);
+  }
+  return new ScanContext(target,carton);
+ }
+
+ /** 按仓库返回真实托盘状态及全部成员，跨客户不改变每箱的原归属。 */
+ public PalletWorkspace workspacePallet(long warehouseId,String palletNo){
+  String code=normalize(palletNo);
+  if(code==null) throw invalid("托盘码不能为空");
+  PalletRow row=workspaceRepository.pallet(warehouseId,code);
+  if(row==null) throw new BizException(ResultCode.NOT_FOUND,"当前仓库未找到该托盘码");
+  return new PalletWorkspace(palletView(row,null),workspaceRepository.members(row.getId()));
+ }
 
  @Transactional
  public void createTask(InboundOrderEntity inbound,long operatorId,String operatorName) {
@@ -195,11 +223,13 @@ public class DropshipPalletizationService {
    .map(p->palletView(p,task.getInboundCode())).toList();
  }
 
+ /** 跨客户归托仍须同仓、同渠道、同目的仓，并锁定开放托盘。 */
  private PalletRow requireAssignablePallet(TaskRow task,String palletNo){
-  PalletRow existing=mapper.palletByNo(palletNo);
+  PalletRow existing=workspaceRepository.lockPallet(palletNo);
   if(existing==null) throw new BizException(ResultCode.NOT_FOUND,"托盘码不存在，请扫描测量审核后生成的 DP 托盘码");
   if(!Objects.equals(existing.getWarehouseId(),task.getWarehouseId())) throw conflict("托盘码不属于当前作业仓库");
   if(!"OPEN".equals(existing.getPalletStatus())) throw conflict("托盘已封托，不能继续绑定箱");
+  if(!workspaceRepository.compatible(task.getId(),existing.getId())) throw conflict("托内货物与当前票的渠道或目的仓不同，不能混托");
   return existing;
  }
 

firstleg/src/main/java/com/baiyue/firstleg/service/MerchantWorkbenchFilterService.java

@@ -12,11 +12,15 @@ public class MerchantWorkbenchFilterService {
 
     @org.springframework.transaction.annotation.Transactional(readOnly=true)
     public MerchantWorkbenchFilters.Response read(MerchantWorkbenchFilters.Request request) {
+        if (request.orderIds() != null) {
+            return new MerchantWorkbenchFilters.Response(null, java.util.List.of(), java.util.List.of(),
+                progress(mapper.progressFragments(request.tenantId(), request.orderIds())));
+        }
         return new MerchantWorkbenchFilters.Response(
             request.mainStatus() == null ? null : mapper.byProcessStatuses(request.tenantId(),
                 unified.internalStatuses(request.mainStatus())),
             mapper.pendingFees(request.tenantId()), mapper.pendingCustoms(request.tenantId()),
-            progress(mapper.progressFragments(request.tenantId())));
+            progress(mapper.progressFragments(request.tenantId(), null)));
     }
 
     static java.util.List<MerchantWorkbenchFilters.Progress> progress(java.util.List<MerchantWorkbenchFilters.Fragment> facts) {

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/controller/ContainerCalendarSourceController.java

@@ -0,0 +1,28 @@
+package com.baiyue.firstleg.terminaldrayage.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.firstleg.service.FirstlegScopeGuard;
+import com.baiyue.firstleg.terminaldrayage.service.ContainerCalendarSourceService;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.*;
+import java.time.LocalDate;
+
+@RestController
+@RequestMapping("/api/platform/v1/terminal-drayages")
+public class ContainerCalendarSourceController {
+    private final ContainerCalendarSourceService service;
+    /** 装配只读日历业务服务。 */
+    public ContainerCalendarSourceController(ContainerCalendarSourceService service) { this.service = service; }
+    /** 预约列表可读基础柜信息，还柜事实继续核验原业务读取权限。 */
+    @GetMapping("/calendar-sources")
+    @PreAuthorize("hasAuthority('platform:appointment:list')")
+    public ApiResponse<ContainerCalendarSourceService.Result> calendar(@AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate from,
+        @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate to) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.calendar(from, to, user.permissions()));
+    }
+}

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/dto/ContainerCalendarSource.java

@@ -0,0 +1,8 @@
+package com.baiyue.firstleg.terminaldrayage.dto;
+
+import java.time.LocalDateTime;
+
+/** 四类日历使用的柜级来源，日期均保留原业务当地值。 */
+public record ContainerCalendarSource(Long containerBookingId, String cabinetNo, String containerNo,
+    String vesselName, String voyageNo, String destinationPortName, String destinationWarehouseCode,
+    LocalDateTime arrivalAt, String arrivalType) { }

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/mapper/ContainerCalendarSourceMapper.java

@@ -0,0 +1,44 @@
+package com.baiyue.firstleg.terminaldrayage.mapper;
+
+import com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import java.time.LocalDateTime;
+import java.util.List;
+
+@Mapper
+public interface ContainerCalendarSourceMapper {
+    /** 同时选出到港、缺日期和可能还柜的有效出仓柜，最终日期由业务服务复核。 */
+    @Select("""
+        SELECT c.id containerBookingId,c.cabinet_no cabinetNo,c.container_no containerNo,
+          c.vessel_name vesselName,c.voyage_no voyageNo,c.destination_port_name destinationPortName,
+          c.destination_warehouse_code destinationWarehouseCode,
+          COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at) arrivalAt,
+          CASE WHEN COALESCE(n.actual_at,c.actual_port_arrival_at) IS NOT NULL THEN 'ACTUAL' ELSE 'ESTIMATED' END arrivalType
+        FROM fl_container_booking c
+        LEFT JOIN fl_terminal_drayage t ON t.container_booking_id=c.id
+        LEFT JOIN fl_carrier_schedule_node_fact n ON n.id=(
+          SELECT f.id FROM fl_carrier_schedule_node_fact f WHERE f.container_booking_id=c.id
+            AND f.standard_node='ARRIVED_DESTINATION_PORT' AND f.actual_at IS NOT NULL
+          ORDER BY f.observed_at DESC,f.id DESC LIMIT 1)
+        WHERE c.record_status='ACTIVE'
+          AND EXISTS(SELECT 1 FROM fl_outbound_dispatch d WHERE d.container_booking_id=c.id
+            AND d.confirmed_at IS NOT NULL AND d.reversed_at IS NULL AND d.status='WAITING_FOR_LOADING')
+          AND (
+            COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at) IS NULL
+            OR (COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at)>=#{arrivalFrom}
+              AND COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at)<#{to})
+            OR (t.actual_empty_return_at>=#{from} AND t.actual_empty_return_at<#{to})
+            OR (c.unloading_completed_at>=#{returnFrom} AND c.unloading_completed_at<#{to})
+            OR EXISTS(SELECT 1 FROM fl_carrier_schedule_node_fact r WHERE r.container_booking_id=c.id
+              AND r.standard_node='EMPTY_RETURNED' AND r.actual_at>=#{from} AND r.actual_at<#{to})
+            OR EXISTS(SELECT 1 FROM fl_direct_delivery_unloading u WHERE u.container_booking_id=c.id
+              AND u.actual_at>=#{returnFrom} AND u.actual_at<#{to})
+          )
+        ORDER BY c.id LIMIT 2001
+        """)
+    List<ContainerCalendarSource> sources(@Param("from") LocalDateTime from,
+        @Param("arrivalFrom") LocalDateTime arrivalFrom, @Param("returnFrom") LocalDateTime returnFrom,
+        @Param("to") LocalDateTime to);
+}

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/mapper/DirectDeliveryMapper.java

@@ -10,6 +10,41 @@ public interface DirectDeliveryMapper {
         int version,LocalDateTime actualAt,String timezone,String receivedBy,String evidenceNo,String remark,
         String idempotencyKey,String requestHash) { }
     record Container(long id,String recordStatus,LocalDateTime warehouseUnloadedAt) { }
+    record FlowEvidence(long id,LocalDateTime warehouseUnloadedAt,long evidenceCount) { }
+    record ContainerDelivery(long containerBookingId,long inboundId,String inboundCode,String orderNo,String destinationName,int packageCount,
+        int version,LocalDateTime actualAt,String timezone,String receivedBy,String evidenceNo,String remark,
+        String idempotencyKey,String requestHash) {
+        public Delivery delivery(){return new Delivery(inboundId,inboundCode,orderNo,destinationName,packageCount,version,
+            actualAt,timezone,receivedBy,evidenceNo,remark,idempotencyKey,requestHash);}
+    }
+    @Select("""
+        <script>
+        SELECT c.id,c.unloading_completed_at warehouse_unloaded_at,COUNT(d.inbound_id) evidence_count
+        FROM fl_container_booking c LEFT JOIN fl_direct_delivery_unloading d ON d.container_booking_id=c.id
+        WHERE c.id IN <foreach collection="ids" item="id" open="(" separator="," close=")">#{id}</foreach>
+        GROUP BY c.id,c.unloading_completed_at
+        </script>
+        """)
+    List<FlowEvidence> flowEvidence(@Param("ids") List<Long> ids);
+    @Select("""
+        <script>SELECT id,record_status,unloading_completed_at warehouse_unloaded_at FROM fl_container_booking
+        WHERE id IN <foreach collection="ids" item="id" open="(" separator="," close=")">#{id}</foreach></script>
+        """)
+    List<Container> containers(@Param("ids") List<Long> ids);
+    @Select("""
+        <script>
+        SELECT p.container_booking_id,i.inbound_id,MAX(i.inbound_code) inbound_code,MAX(i.order_no) order_no,
+          MAX(i.destination_warehouse_name) destination_name,SUM(i.package_count) package_count,
+          COALESCE(d.version,0) version,d.actual_at,d.timezone,d.received_by,d.evidence_no,d.remark,d.idempotency_key,d.request_hash
+        FROM fl_loading_plan p JOIN fl_loading_plan_item i ON i.loading_plan_id=p.id AND i.deleted=0
+        LEFT JOIN fl_direct_delivery_unloading d ON d.container_booking_id=p.container_booking_id AND d.inbound_id=i.inbound_id
+        WHERE p.container_booking_id IN <foreach collection="ids" item="id" open="(" separator="," close=")">#{id}</foreach>
+          AND p.plan_status='COMPLETED'
+        GROUP BY p.container_booking_id,i.inbound_id,d.version,d.actual_at,d.timezone,d.received_by,d.evidence_no,d.remark,d.idempotency_key,d.request_hash
+        ORDER BY p.container_booking_id,i.inbound_id
+        </script>
+        """)
+    List<ContainerDelivery> deliveriesBatch(@Param("ids") List<Long> ids);
     @Select("SELECT id,record_status,unloading_completed_at warehouse_unloaded_at FROM fl_container_booking WHERE id=#{id} FOR UPDATE")
     @Options(flushCache=Options.FlushCachePolicy.TRUE,useCache=false)
     Container lockContainer(@Param("id") long id);

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/mapper/TerminalDrayageMapper.java

@@ -114,6 +114,16 @@ public interface TerminalDrayageMapper extends BaseMapper<TerminalDrayageEntity>
          ORDER BY created_at DESC,id DESC
         """)
     List<History> histories(@Param("containerBookingId") long containerBookingId);
+    record PickupChanges(long containerBookingId,long schedules,long fleets) { }
+    @Select("""
+        <script>SELECT container_booking_id,
+          SUM(CASE WHEN action='SCHEDULE_PICKUP' THEN 1 ELSE 0 END) schedules,
+          SUM(CASE WHEN action='SELECT_FLEET' THEN 1 ELSE 0 END) fleets
+        FROM fl_terminal_drayage_history WHERE container_booking_id IN
+        <foreach collection="ids" item="id" open="(" separator="," close=")">#{id}</foreach>
+        GROUP BY container_booking_id</script>
+        """)
+    List<PickupChanges> pickupChanges(@Param("ids") List<Long> ids);
 
     @Insert("""
         INSERT INTO fl_terminal_drayage_history(id,drayage_id,container_booking_id,action,from_status,to_status,

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/repository/ContainerCalendarSourceRepository.java

@@ -0,0 +1,19 @@
+package com.baiyue.firstleg.terminaldrayage.repository;
+
+import com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource;
+import com.baiyue.firstleg.terminaldrayage.mapper.ContainerCalendarSourceMapper;
+import org.springframework.stereotype.Repository;
+import java.time.LocalDate;
+import java.util.List;
+
+@Repository
+public class ContainerCalendarSourceRepository {
+    private final ContainerCalendarSourceMapper mapper;
+    /** 使用本服务 Mapper 读取日历所需柜级来源。 */
+    public ContainerCalendarSourceRepository(ContainerCalendarSourceMapper mapper) { this.mapper = mapper; }
+    /** 到港前移两天覆盖默认到仓，直送还柜候选额外留一天覆盖夏令时。 */
+    public List<ContainerCalendarSource> sources(LocalDate from, LocalDate to) {
+        return mapper.sources(from.atStartOfDay(), from.minusDays(2).atStartOfDay(),
+            from.minusDays(4).atStartOfDay(), to.atStartOfDay());
+    }
+}

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/service/AppointmentWorkTerminalFacts.java

@@ -3,6 +3,8 @@ package com.baiyue.firstleg.terminaldrayage.service;
 import com.baiyue.firstleg.portschedule.dto.AppointmentWorkSourceDtos.*;
 import com.baiyue.firstleg.portschedule.service.AppointmentWorkSourceService.OriginalFacts;
 import com.baiyue.firstleg.portschedule.service.CarrierScheduleQueryService;
+import com.baiyue.firstleg.portschedule.dto.CarrierScheduleQueryDtos.ContainerActualFacts;
+import com.baiyue.firstleg.terminaldrayage.entity.TerminalDrayageEntity;
 import com.baiyue.firstleg.terminaldrayage.mapper.DirectDeliveryMapper;
 import com.baiyue.firstleg.terminaldrayage.mapper.TerminalDrayageMapper;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -26,17 +28,43 @@ public class AppointmentWorkTerminalFacts implements OriginalFacts {
         CarrierScheduleQueryService nodes,UnloadingEvidenceGuard unloading,ObjectMapper json) {
         this.terminal=terminal;this.direct=direct;this.nodes=nodes;this.unloading=unloading;this.json=json;
     }
-    public String establishedFlow(long id) {
+    public Map<Long,String> establishedFlows(List<Long> ids) {
-        var container=direct.container(id);
+        var result=new HashMap<Long,String>();
-        boolean transfer=container!=null && container.warehouseUnloadedAt()!=null;
+        if(ids.isEmpty()) return result;
-        boolean delivery=direct.evidenceCount(id)>0;
+        for(var row:direct.flowEvidence(ids)) {
-        if(transfer && delivery) throw new ResponseStatusException(HttpStatus.CONFLICT,"货柜存在冲突的中转和直送执行事实");
+            boolean transfer=row.warehouseUnloadedAt()!=null;
-        return transfer?"TRANSFER":delivery?"DIRECT":"UNKNOWN";
+            boolean delivery=row.evidenceCount()>0;
+            if(transfer && delivery) throw new ResponseStatusException(HttpStatus.CONFLICT,"货柜存在冲突的中转和直送执行事实");
+            result.put(row.id(),transfer?"TRANSFER":delivery?"DIRECT":"UNKNOWN");
+        }
+        return result;
     }
-    public Fact read(FactRequest request,ContainerSource source) {
+    public List<Fact> read(List<FactRequest> requests,Map<Long,ContainerSource> sources) {
-        long id=Long.parseLong(request.containerBookingId());
+        var ids=requests.stream().map(r->Long.parseLong(r.containerBookingId())).distinct().toList();
-        var node=nodes.containerActualFacts(List.of(id)).stream().findFirst().orElse(null);
+        if(ids.isEmpty()) return List.of();
-        var plan=terminal.find(id);
+        var actuals=new HashMap<Long,ContainerActualFacts>();
+        for(var row:nodes.containerActualFacts(ids)) actuals.put(row.containerBookingId(),row);
+        var plans=new HashMap<Long,TerminalDrayageEntity>();
+        for(var row:terminal.findAll(ids)) plans.put(row.getContainerBookingId(),row);
+        var pickupIds=requests.stream().filter(r->"PICKUP".equals(r.type())).map(r->Long.parseLong(r.containerBookingId())).distinct().toList();
+        var changes=new HashMap<Long,TerminalDrayageMapper.PickupChanges>();
+        if(!pickupIds.isEmpty()) for(var row:terminal.pickupChanges(pickupIds)) changes.put(row.containerBookingId(),row);
+        var deliveryIds=requests.stream().filter(r->"DELIVERY".equals(r.type())).map(r->Long.parseLong(r.containerBookingId())).distinct().toList();
+        var deliveries=new HashMap<Long,List<DirectDeliveryMapper.Delivery>>();
+        if(!deliveryIds.isEmpty()) for(var row:direct.deliveriesBatch(deliveryIds))
+            deliveries.computeIfAbsent(row.containerBookingId(),ignored->new ArrayList<>()).add(row.delivery());
+        var returnIds=requests.stream().filter(r->"EMPTY_RETURN".equals(r.type())).map(r->Long.parseLong(r.containerBookingId())).distinct()
+            .filter(id->(actuals.get(id)==null || actuals.get(id).emptyReturnedAt()==null)
+                && (plans.get(id)==null || plans.get(id).getActualEmptyReturnAt()==null)).toList();
+        var completed=returnIds.isEmpty()?Map.<Long,LocalDateTime>of():unloading.completedUnloading(returnIds);
+        return requests.stream().map(request->{
+            long id=Long.parseLong(request.containerBookingId());
+            return read(request,sources.get(id),actuals.get(id),plans.get(id),changes.get(id),
+                deliveries.getOrDefault(id,List.of()),completed.get(id));
+        }).toList();
+    }
+    private Fact read(FactRequest request,ContainerSource source,ContainerActualFacts node,TerminalDrayageEntity plan,
+        TerminalDrayageMapper.PickupChanges changes,List<DirectDeliveryMapper.Delivery> deliveries,LocalDateTime completedUnloading) {
         var references=new ArrayList<Reference>();
         source.requirements().forEach(r->r.references().forEach(ref->{if(!references.contains(ref))references.add(ref);}));
         var blocks=new ArrayList<String>(); var missing=new ArrayList<String>();
@@ -53,9 +81,8 @@ public class AppointmentWorkTerminalFacts implements OriginalFacts {
                 if(plan!=null && plan.getFleetSupplierId()!=null)
                     responsibility=new Responsibility("SUPPLIER",plan.getFleetSupplierId().toString(),plan.getFleetSupplierName());
                 // The initial arrangement/assignment establishes a baseline. Only later changes invalidate dependants.
-                var history=terminal.histories(id);
+                long reschedules=Math.max(0,(changes==null?0:changes.schedules())-1);
-                long reschedules=Math.max(0,history.stream().filter(h->"SCHEDULE_PICKUP".equals(h.action())).count()-1);
+                long reassignments=Math.max(0,(changes==null?0:changes.fleets())-1);
-                long reassignments=Math.max(0,history.stream().filter(h->"SELECT_FLEET".equals(h.action())).count()-1);
                 impact=reschedules+":"+reassignments;
                 if(at==null) {
                     if(node==null || node.arrivedDestinationPortAt()==null) blocks.add("实际到港后才能安排提柜");
@@ -67,7 +94,7 @@ public class AppointmentWorkTerminalFacts implements OriginalFacts {
             case "EMPTY_RETURN" -> {
                 at=node==null?null:node.emptyReturnedAt();
                 if(at==null && plan!=null) at=plan.getActualEmptyReturnAt();
-                if(at==null && unloading.completedUnloading(id)==null) blocks.add("海外仓卸柜或全部直送目的仓实际卸货后才能还空");
+                if(at==null && completedUnloading==null) blocks.add("海外仓卸柜或全部直送目的仓实际卸货后才能还空");
                 else if(at==null) {code="RECORD_EXECUTION";label="确认实际还空";permission="platform:firstleg:terminal-drayage:empty-return:confirm";}
                 // Return responsibility belongs to the work handoff, not the historical pickup carrier.
             }
@@ -75,7 +102,7 @@ public class AppointmentWorkTerminalFacts implements OriginalFacts {
                 var requirement=source.requirements().stream().filter(r->Objects.equals(r.requirementKey(),request.requirementKey())).findFirst()
                     .orElseThrow(()->new ResponseStatusException(HttpStatus.CONFLICT,"直送需求与原柜来源不一致"));
                 references.clear(); references.addAll(requirement.references());
-                var row=direct.deliveries(id).stream().filter(d->("INBOUND:"+d.inboundId()).equals(request.requirementKey())).findFirst()
+                var row=deliveries.stream().filter(d->("INBOUND:"+d.inboundId()).equals(request.requirementKey())).findFirst()
                     .orElseThrow(()->new ResponseStatusException(HttpStatus.CONFLICT,"直送需求与实际装柜来源不一致"));
                 at=row.actualAt();zone=row.timezone();businessNo=row.inboundCode();
                 if(at==null && (node==null || node.pickedUpAt()==null)) blocks.add("实际提柜后才能记录直送卸货");

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/service/ContainerCalendarSourceService.java

@@ -0,0 +1,46 @@
+package com.baiyue.firstleg.terminaldrayage.service;
+
+import com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource;
+import com.baiyue.firstleg.terminaldrayage.dto.TerminalDrayageDtos.View;
+import com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import java.time.LocalDate;
+import java.time.temporal.ChronoUnit;
+import java.util.*;
+import org.springframework.web.server.ResponseStatusException;
+
+@Service
+public class ContainerCalendarSourceService {
+    public record Result(List<ContainerCalendarSource> containers, List<View> emptyReturns,
+                         boolean emptyReturnsReadable) { }
+    private final ContainerCalendarSourceRepository repository;
+    private final TerminalDrayageService drayages;
+    /** 复用真实还柜业务的截止时间和完成事实，不在日历另算还柜状态。 */
+    public ContainerCalendarSourceService(ContainerCalendarSourceRepository repository, TerminalDrayageService drayages) {
+        this.repository = repository; this.drayages = drayages;
+    }
+    /** 按日期范围读取到港、默认到仓来源及可见的还柜记录。 */
+    public Result calendar(LocalDate from, LocalDate to, Set<String> permissions) {
+        if (from == null || to == null || !to.isAfter(from) || ChronoUnit.DAYS.between(from, to) > 42)
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "日历查询范围必须为1至42天");
+        var sources = repository.sources(from, to);
+        if (sources.size() > 2000)
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "日历来源超过2000柜，请缩小范围或补齐未定日期");
+        boolean readable = permissions != null && permissions.contains("platform:firstleg:terminal-drayage:list");
+        var returns = new ArrayList<View>();
+        if (readable) {
+            var ids = sources.stream().map(ContainerCalendarSource::containerBookingId).toList();
+            for (int start = 0; start < ids.size(); start += 200) {
+                for (var row : drayages.authorize(drayages.views(ids.subList(start, Math.min(start + 200, ids.size()))), permissions)) {
+                    var at = row.actualEmptyReturnAt() != null ? row.actualEmptyReturnAt() : row.emptyReturnWarning().deadlineAt();
+                    if (at != null && !at.toLocalDate().isBefore(from) && at.toLocalDate().isBefore(to)) returns.add(row);
+                }
+            }
+        }
+        // 未授权还柜读取时，也不能通过仅因还柜日期命中的旧柜候选推断受保护事实。
+        var visibleSources = readable ? sources : sources.stream().filter(row -> row.arrivalAt() == null
+            || !row.arrivalAt().toLocalDate().isBefore(from.minusDays(2)) && row.arrivalAt().toLocalDate().isBefore(to)).toList();
+        return new Result(List.copyOf(visibleSources), List.copyOf(returns), readable);
+    }
+}

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/service/UnloadingEvidenceGuard.java

@@ -6,6 +6,7 @@ import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import org.springframework.stereotype.Service;
 import java.time.*;
+import java.util.*;
 
 @Service
 public class UnloadingEvidenceGuard implements EmptyReturnPrerequisite {
@@ -16,11 +17,32 @@ public class UnloadingEvidenceGuard implements EmptyReturnPrerequisite {
         public LocalDateTime deadline(int hours){return instant().plus(Duration.ofHours(hours)).atZone(ZoneId.of(timezone)).toLocalDateTime();}
     }
     public DirectCompletion directCompletion(long id) {
-        var rows=mapper.deliveries(id);
+        return directCompletion(mapper.deliveries(id));
+    }
+    private DirectCompletion directCompletion(List<DirectDeliveryMapper.Delivery> rows) {
         if(rows.isEmpty() || rows.stream().anyMatch(row->row.actualAt()==null)) return null;
         return rows.stream().map(row->new DirectCompletion(row.actualAt(),row.timezone()))
             .max(java.util.Comparator.comparing(DirectCompletion::instant)).orElse(null);
     }
+    public Map<Long,LocalDateTime> completedUnloading(List<Long> ids) {
+        var result=new HashMap<Long,LocalDateTime>();
+        if(ids.isEmpty()) return result;
+        var pending=new ArrayList<Long>();
+        for(var container:mapper.containers(ids)) {
+            if(!"ACTIVE".equals(container.recordStatus())) continue;
+            if(container.warehouseUnloadedAt()!=null) result.put(container.id(),container.warehouseUnloadedAt());
+            else pending.add(container.id());
+        }
+        if(!pending.isEmpty()) {
+            var deliveries=new HashMap<Long,List<DirectDeliveryMapper.Delivery>>();
+            for(var row:mapper.deliveriesBatch(pending)) deliveries.computeIfAbsent(row.containerBookingId(),ignored->new ArrayList<>()).add(row.delivery());
+            for(long id:pending) {
+                var completed=directCompletion(deliveries.getOrDefault(id,List.of()));
+                if(completed!=null) result.put(id,completed.localAt());
+            }
+        }
+        return result;
+    }
     public LocalDateTime completedUnloading(long id) {
         var container=mapper.container(id);
         if(container==null || !"ACTIVE".equals(container.recordStatus())) return null;

firstleg/src/main/resources/openapi/appointment-calendar-sources-v1.yaml

@@ -0,0 +1,55 @@
+openapi: 3.0.3
+info: {title: 四类日历柜级来源, version: 1.0.0}
+security: [{bearerAuth: []}]
+paths:
+  /api/platform/v1/terminal-drayages/calendar-sources:
+    get:
+      summary: 查询日历到港、默认到仓来源和还柜事实
+      description: >-
+        仅平台，platform:appointment:list。返回已确认国内出仓、未撤销且有效的柜次。
+        到港取最新已观测实际到港节点、柜次实际到港、预计到港，按此顺序选一个日期。
+        到港候选前移两天覆盖计划到仓默认日期；缺到港日期的柜次同时返回，不能伪造日期。
+        还柜候选含原截止日期与真实完成日期，最终由原码头拖车业务复核，完成后只按实际还柜日期归日历。
+        没有platform:firstleg:terminal-drayage:list时emptyReturns为空且emptyReturnsReadable=false；不把缺权限当没有安排。
+        最多2000个候选，超出返回400；来源读取失败返回错误，不以空列表代替。
+      x-permissions: [platform:appointment:list]
+      parameters:
+        - {name: from, in: query, required: true, schema: {type: string, format: date}, description: 包含的原业务当地日期}
+        - {name: to, in: query, required: true, schema: {type: string, format: date}, description: 不包含的原业务当地日期，范围最多42天}
+      responses:
+        '200':
+          description: 成功业务响应，code为字符串200
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: object
+                    required: [containers, emptyReturns, emptyReturnsReadable]
+                    properties:
+                      emptyReturnsReadable: {type: boolean}
+                      containers:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            containerBookingId: {type: string}
+                            cabinetNo: {type: string, nullable: true}
+                            containerNo: {type: string, nullable: true}
+                            vesselName: {type: string, nullable: true}
+                            voyageNo: {type: string, nullable: true}
+                            destinationPortName: {type: string, nullable: true}
+                            destinationWarehouseCode: {type: string, nullable: true}
+                            arrivalAt: {type: string, format: date-time, nullable: true}
+                            arrivalType: {type: string, enum: [ACTUAL, ESTIMATED]}
+                      emptyReturns:
+                        type: array
+                        description: 沿terminal-drayage-v1的View结构，allowedActions按当前权限过滤；含actualEmptyReturnAt及emptyReturnWarning.deadlineAt
+                        items: {$ref: './terminal-drayage-v1.yaml#/components/schemas/TerminalDrayageView'}
+        '400': {description: 范围无效或候选过多}
+        '403': {description: 非平台或没有预约读取权限}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}

firstleg/src/main/resources/openapi/dropship-palletization-v1.yaml

@@ -4,6 +4,26 @@ info:
   version: 3.0.0
   description: 测量环节录入预计托数，审核通过后预生成全部 DP 托盘码并可合并打印。PDA 支持先扫箱或先扫托，同一国内作业仓可跨票共用开放托盘，实物装满后再封托。
 paths:
+  /api/platform/v1/first-leg/pda-dropship/cartons/resolve:
+    get:
+      summary: 同仓跨客户识别箱码并预览原任务
+      description: 只读，不领取或清点；返回 task 与 carton，确认时仍须领取原任务后按原 taskId 清点。拒绝其他作业员已领取任务及箱码歧义。
+      x-required-authority: platform:firstleg:pda:view
+      parameters:
+        - {$ref: '#/components/parameters/WarehouseId'}
+        - {name: boxCode, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 80}}
+      responses:
+        '200': {description: 原任务和箱内 SKU 预览}
+  /api/platform/v1/first-leg/pda-dropship/pallets/resolve:
+    get:
+      summary: 查询当前仓库真实托盘状态与逐客户逐票组成
+      description: 扫描不产生归托；返回 pallet 与 members，成员保留 taskId、inboundId、inboundCode、customerId、customerName、cartonCount。不存在或跨仓的托盘拒绝，已封托返回真实状态。
+      x-required-authority: platform:firstleg:pda:view
+      parameters:
+        - {$ref: '#/components/parameters/WarehouseId'}
+        - {name: palletNo, in: query, required: true, schema: {type: string, pattern: 'DP-[0-9]{6}-[0-9]{4}'}}
+      responses:
+        '200': {description: 实物托盘状态和成员汇总}
   /api/platform/v1/first-leg/pda-dropship/tasks/pending:
     get:
       summary: 查询待领取或本人已领取任务

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -355,7 +355,7 @@ paths:
   /internal/firstleg/v1/inbounds/unified-orders/workbench-filters:
     post:
       summary: 查询单一客户工作台履约筛选标识（Order内部）
-      description: 只读返回命中状态、最新待确认费用及待上传资料的订单标识。客户必须明确且为正数；不创建报关聚合，不跨Schema读取。
+      description: 只读返回命中状态、最新待确认费用及待上传资料的订单标识。客户必须明确且为正数；不创建报关聚合，不跨Schema读取。传入orderIds为精确进度模式，仅计算progress，matchingStatusOrderIds为null，feeOrderIds和customsOrderIds为空；mainStatus在该模式不参与查询。
       security: [{internalServiceToken: []}]
       requestBody:
         required: true
@@ -367,6 +367,13 @@ paths:
               properties:
                 tenantId: {type: integer, format: int64, minimum: 1}
                 mainStatus: {type: string, nullable: true, enum: [WAIT_MEASURE, WAIT_PALLETIZE, WAIT_SPLIT, LOADING, LOADED, DELIVERED]}
+                orderIds:
+                  type: array
+                  nullable: true
+                  minItems: 1
+                  maxItems: 200
+                  items: {type: integer, format: int64, minimum: 1}
+                  description: 省略或null查询当前客户全部进度；传入时仅在SQL内查询这些来源Order订单，空数组拒绝，不允许扩大到全客户。
       responses:
         '200':
           description: 按响应code判断，标识只供Order在自身客户范围内过滤、计数和分页

firstleg/src/test/java/com/baiyue/firstleg/controller/InternalInboundOrderReferenceControllerTest.java

@@ -45,7 +45,7 @@ class InternalInboundOrderReferenceControllerTest {
     private InternalInboundOrderController controller;
 
     @Test void workbenchFiltersRejectMissingAndWrongInternalIdentity() {
-        var request = new com.baiyue.firstleg.dto.MerchantWorkbenchFilters.Request(11L, "LOADED");
+        var request = new com.baiyue.firstleg.dto.MerchantWorkbenchFilters.Request(11L, "LOADED", null);
         assertThatThrownBy(() -> controller.workbenchFilters(null, request)).isInstanceOf(BizException.class);
         assertThatThrownBy(() -> controller.workbenchFilters("wrong", request)).isInstanceOf(BizException.class);
         org.mockito.Mockito.verifyNoInteractions(workbenchFilters);
@@ -143,4 +143,18 @@ class InternalInboundOrderReferenceControllerTest {
             carrierId == null ? null : "承运商", null, null, null, null,
             null, null, null, null, null, null);
     }
+
+    @Test void optionalExactScopeRejectsEmptyOversizeNullOrNonPositiveItems() {
+        try(var factory=jakarta.validation.Validation.buildDefaultValidatorFactory()) {
+            var validator=factory.getValidator();
+            for(java.util.List<Long> ids: java.util.List.of(java.util.List.<Long>of(),java.util.List.of(0L),
+                java.util.Arrays.asList(1L,null),java.util.stream.LongStream.rangeClosed(1,201).boxed().toList())) {
+                assertThat(validator.validate(new com.baiyue.firstleg.dto.MerchantWorkbenchFilters.Request(11L,null,ids))).isNotEmpty();
+            }
+            for(java.util.List<Long> ids: java.util.Arrays.asList(null,java.util.List.of(1L),java.util.stream.LongStream.rangeClosed(1,200).boxed().toList())) {
+                assertThat(validator.validate(new com.baiyue.firstleg.dto.MerchantWorkbenchFilters.Request(11L,null,ids))).isEmpty();
+            }
+        }
+    }
+
 }

firstleg/src/test/java/com/baiyue/firstleg/controller/UnifiedInboundOpenApiContractTest.java

@@ -74,4 +74,16 @@ class UnifiedInboundOpenApiContractTest {
             .containsOnlyKeys("standardNode","nodeSequence","providerCode","estimatedAt","actualAt","locationCode","locationName");
     }
 
+
+    @Test @SuppressWarnings("unchecked") void documentsBoundedOptionalExactOrderScope() throws Exception {
+        var document=(java.util.Map<String,Object>)new org.yaml.snakeyaml.Yaml().load(
+            new org.springframework.core.io.ClassPathResource("openapi/firstleg-v1.yaml").getContentAsString(java.nio.charset.StandardCharsets.UTF_8));
+        var paths=(java.util.Map<String,Object>)document.get("paths");
+        var operation=(java.util.Map<String,Object>)((java.util.Map<String,Object>)paths.get("/internal/firstleg/v1/inbounds/unified-orders/workbench-filters")).get("post");
+        var content=(java.util.Map<String,Object>)((java.util.Map<String,Object>)operation.get("requestBody")).get("content");
+        var schema=(java.util.Map<String,Object>)((java.util.Map<String,Object>)content.get("application/json")).get("schema");
+        var ids=(java.util.Map<String,Object>)((java.util.Map<String,Object>)schema.get("properties")).get("orderIds");
+        assertThat(ids).containsEntry("minItems",1).containsEntry("maxItems",200).containsEntry("nullable",true);
+        assertThat((java.util.List<String>)schema.get("required")).doesNotContain("orderIds");
+    }
 }

firstleg/src/test/java/com/baiyue/firstleg/portschedule/mapper/AppointmentWorkSourceMapperTest.java

@@ -18,15 +18,25 @@ class AppointmentWorkSourceMapperTest {
             s.execute("CREATE TABLE fl_direct_delivery_unloading(container_booking_id BIGINT)");
             s.execute("INSERT INTO fl_container_booking VALUES(1,'D1',NULL,'上海',NULL,1,'ACTIVE'),(2,'D2','C2','上海','私人仓',1,'ACTIVE'),(3,'D3','C3','上海',NULL,1,'ACTIVE'),(4,'D4','C4','上海',NULL,1,'MERGED')");
             s.execute("INSERT INTO fl_carrier_schedule_node_fact VALUES(10,1,'DEPARTED_ORIGIN_PORT','2026-10-01'),(20,2,'EMPTY_RETURNED','2026-10-03'),(30,3,'LOADED_ON_VESSEL','2026-10-04'),(40,4,'DEPARTED_ORIGIN_PORT','2026-10-01'),(50,3,'DEPARTED_ORIGIN_PORT',NULL)");
-            s.execute("INSERT INTO fl_direct_delivery_unloading VALUES(2)");
+            s.execute("INSERT INTO fl_direct_delivery_unloading VALUES(2),(2)");
+            s.execute("INSERT INTO fl_carrier_schedule_node_fact VALUES(60,1,'IN_TRANSIT','2026-10-02'),(70,1,'ARRIVED_DESTINATION_PORT','2026-10-03'),(80,2,'EMPTY_RETURNED',NULL)");
         }
         var config=new MybatisConfiguration();config.setMapUnderscoreToCamelCase(true);
         config.setEnvironment(new Environment("test",new JdbcTransactionFactory(),ds));config.addMapper(AppointmentWorkSourceMapper.class);
         try(var session=new MybatisSqlSessionFactoryBuilder().build(config).openSession()) {
-            var rows=session.getMapper(AppointmentWorkSourceMapper.class).sources();
+            var mapper=session.getMapper(AppointmentWorkSourceMapper.class);
+            var rows=mapper.sources();
             assertEquals(2,rows.size());assertEquals(1,rows.get(0).id());assertEquals(2,rows.get(1).id());
-            assertNull(rows.get(0).destinationWarehouseName());assertEquals(1,rows.get(1).deliveryVersion());
+            assertNull(rows.get(0).destinationWarehouseName());assertEquals(2,rows.get(1).deliveryVersion());
             assertNull(rows.get(1).departedLocalAt());assertNotNull(rows.get(1).sailedEvidenceLocalAt());
+            assertEquals(70,rows.get(0).factVersion());assertEquals(20,rows.get(1).factVersion());
+            // The optimized path must equal the former full-manifest + Java filter, including
+            // dates, versions, null names, unloading counts, duplicate IDs and ineligible sources.
+            for(var ids:java.util.List.of(java.util.List.of(2L,1L),java.util.List.of(1L,1L),
+                java.util.List.of(2L,3L,4L,999L),java.util.List.of(3L,4L),java.util.List.<Long>of())) {
+                assertEquals(rows.stream().filter(row->ids.contains(row.id())).toList(),mapper.sourcesByIds(ids));
+            }
+            assertTrue(mapper.sourcesByIds(null).isEmpty());
         }
     }
 }

firstleg/src/test/java/com/baiyue/firstleg/portschedule/service/AppointmentWorkSourceServiceTest.java

@@ -7,6 +7,10 @@ import org.junit.jupiter.api.Test;
 import org.springframework.web.server.ResponseStatusException;
 import java.time.LocalDateTime;
 import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
+import com.baiyue.firstleg.portschedule.dto.AppointmentWorkSourceDtos.*;
 import static org.mockito.Mockito.*;
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -19,7 +23,7 @@ class AppointmentWorkSourceServiceTest {
     }
     @Test void completeCursorManifestIncludesUnboundSourcesAndRejectsScopeDrift() {
         when(mapper.sources()).thenReturn(List.of(source(1,1),source(2,1)));
-        when(mapper.cargo(anyLong())).thenReturn(List.of()); when(facts.establishedFlow(anyLong())).thenReturn("UNKNOWN");
+        when(mapper.cargo(anyList())).thenReturn(List.of()); stubFlows("UNKNOWN");
         var first=service.discover(null,1);
         assertFalse(first.complete()); assertNotNull(first.nextCursor());
         assertNull(first.containers().get(0).departedAt());
@@ -31,9 +35,11 @@ class AppointmentWorkSourceServiceTest {
     }
     @Test void sourceKeepsCustomerAndPhysicalInboundLineageWithoutDisplayingIdsAsNumbers() {
         when(mapper.sources()).thenReturn(List.of(source(1,1)));
-        when(mapper.cargo(1)).thenReturn(List.of(new AppointmentWorkSourceMapper.Cargo(8,9,10,"ORDER-10","IN-8","PRIVATE","P","客户仓",12)));
+        when(mapper.cargo(List.of(1L))).thenReturn(List.of(new AppointmentWorkSourceMapper.ContainerCargo(1,8,9,10,"ORDER-10","IN-8","PRIVATE","P","客户仓",12)));
-        when(facts.establishedFlow(1)).thenReturn("DIRECT");
+        stubFlows("DIRECT");
         var source=service.container(1);var requirement=source.requirements().get(0);
+        assertEquals(service.hash(List.of(source(1,1),List.of(new AppointmentWorkSourceMapper.Cargo(8,9,10,"ORDER-10","IN-8","PRIVATE","P","客户仓",12)))),source.sourceVersion());
+        assertEquals(source,service.discover(null,200).containers().get(0));
         assertEquals("INBOUND:8",requirement.requirementKey());assertEquals("PRIVATE",requirement.destinationKind());
         assertTrue(requirement.references().stream().anyMatch(r->r.kind().equals("CUSTOMER") && r.key().equals("9") && r.businessNo()==null));
     }
@@ -42,4 +48,45 @@ class AppointmentWorkSourceServiceTest {
         assertEquals(401,assertThrows(ResponseStatusException.class,()->guarded.discover(null,null,20)).getStatusCode().value());
         verifyNoInteractions(mapper);
     }
+    @Test void missingFlowEvidenceIsNotSilentlyPresentedAsUnknown() {
+        when(mapper.sources()).thenReturn(List.of(source(1,1)));
+        assertEquals(503,assertThrows(ResponseStatusException.class,()->service.container(1)).getStatusCode().value());
+    }
+    @Test void factBatchReadsOnlyRequestedSourcesAndPreservesEachContainerIdentity() {
+        when(mapper.sourcesByIds(anyList())).thenReturn(IntStream.rangeClosed(1,100).mapToObj(id->source(id,1)).toList());
+        when(mapper.cargo(anyList())).thenReturn(List.of());
+        stubFlows("UNKNOWN");
+        var fact=mock(Fact.class);
+        when(facts.read(any(),any())).thenAnswer(invocation->{
+            List<FactRequest> requests=invocation.getArgument(0); Map<Long,ContainerSource> sources=invocation.getArgument(1);
+            assertEquals(100,sources.size());
+            requests.forEach(request->assertEquals(request.containerBookingId(),sources.get(Long.parseLong(request.containerBookingId())).containerBookingId()));
+            return requests.stream().map(request->fact).toList();
+        });
+        var requests=IntStream.rangeClosed(1,100).boxed().flatMap(id->List.of(
+            request("PICKUP-"+id,"PICKUP",id),request("RETURN-"+id,"EMPTY_RETURN",id)).stream()).toList();
+        assertEquals(200,service.facts(requests).size());
+        verify(mapper,times(1)).sourcesByIds(IntStream.rangeClosed(1,100).mapToObj(Long::valueOf).toList());
+        verify(mapper,never()).sources();
+        verify(mapper,times(1)).cargo(IntStream.rangeClosed(1,100).mapToObj(Long::valueOf).toList());
+        verify(facts,times(1)).establishedFlows(anyList());
+        verify(facts,times(1)).read(any(),any());
+    }
+    @Test void nextFactBatchReadsFreshSourcesAndRejectsRemovedContainer() {
+        when(mapper.sourcesByIds(List.of(1L))).thenReturn(List.of(source(1,1)),List.of());
+        when(mapper.cargo(List.of(1L))).thenReturn(List.of());
+        stubFlows("UNKNOWN");
+        var request=request("PICKUP-1","PICKUP",1);
+        service.facts(List.of(request));
+        assertEquals(404,assertThrows(ResponseStatusException.class,()->service.facts(List.of(request))).getStatusCode().value());
+        verify(mapper,times(2)).sourcesByIds(List.of(1L));
+        verify(mapper,never()).sources();
+        verify(facts,times(1)).read(any(),any());
+    }
+    private void stubFlows(String flow) {
+        when(facts.establishedFlows(anyList())).thenAnswer(invocation->((List<Long>)invocation.getArgument(0)).stream().collect(Collectors.toMap(id->id,id->flow)));
+    }
+    private FactRequest request(String key,String type,long id) {
+        return new FactRequest(key,type,"TRANSIT",Long.toString(id),null,null,null,List.of(),List.of(),List.of());
+    }
 }

firstleg/src/test/java/com/baiyue/firstleg/repository/MerchantWorkbenchFilterMapperTest.java

@@ -83,19 +83,28 @@ class MerchantWorkbenchFilterMapperTest {
     }
 
     @Test void onlyActualLoadedOwnedFragmentsAndActualClearanceAdvanceProgress() {
-        assertThat(mapper.progressFragments(11)).allMatch(f->f.stage()==0);
+        assertThat(mapper.progressFragments(11, null)).allMatch(f->f.stage()==0);
         jdbc.update("INSERT INTO fl_loading_pick_task VALUES(900,100,'COMPLETED')");
         jdbc.update("INSERT INTO fl_loading_pick_item SELECT 900,id,'PICKED',2 FROM fl_loading_plan_item");
-        assertThat(mapper.progressFragments(11)).allMatch(f->f.stage()==1).noneMatch(f->f.orderId()==103||f.orderId()==104);
+        assertThat(mapper.progressFragments(11, null)).allMatch(f->f.stage()==1).noneMatch(f->f.orderId()==103||f.orderId()==104);
         jdbc.update("INSERT INTO fl_customs_container VALUES(200,100,'DECLARING')");
-        assertThat(mapper.progressFragments(11)).allMatch(f->f.stage()==1);
+        assertThat(mapper.progressFragments(11, null)).allMatch(f->f.stage()==1);
         jdbc.update("UPDATE fl_customs_container SET status='COMPLETED'");
-        assertThat(mapper.progressFragments(11)).allMatch(f->f.stage()==2);
+        assertThat(mapper.progressFragments(11, null)).allMatch(f->f.stage()==2);
         jdbc.update("INSERT INTO fl_carrier_schedule_node_fact VALUES(100,'PICKUP_READY',NULL)");
-        assertThat(mapper.progressFragments(11)).allMatch(f->f.stage()==2);
+        assertThat(mapper.progressFragments(11, null)).allMatch(f->f.stage()==2);
         jdbc.update("UPDATE fl_carrier_schedule_node_fact SET actual_at=CURRENT_TIMESTAMP");
-        assertThat(mapper.progressFragments(11)).allMatch(f->f.stage()==3);
+        assertThat(mapper.progressFragments(11, null)).allMatch(f->f.stage()==3);
+        assertThat(mapper.progressFragments(11,List.of(101L))).singleElement().satisfies(f->{assertThat(f.orderId()).isEqualTo(101);assertThat(f.stage()).isEqualTo(3);});
         jdbc.update("UPDATE fl_container_booking SET record_status='CANCELLED'");
-        assertThat(mapper.progressFragments(11)).allMatch(f->f.stage()==0);
+        assertThat(mapper.progressFragments(11, null)).allMatch(f->f.stage()==0);
     }
+
+    @Test void exactOrderScopeKeepsAllItsFragmentsAndCannotReadForeignOrDeletedOrders() {
+        jdbc.update("INSERT INTO fl_inbound_order(id,tenant_id,order_id,deleted,tax_mode,process_status) VALUES(50,11,101,0,'TAX_REFUND','LOADED')");
+        assertThat(mapper.progressFragments(11,List.of(101L,103L,104L))).extracting(f->f.orderId()).containsExactly(101L,101L);
+        assertThat(mapper.progressFragments(11,List.of(999L))).isEmpty();
+        assertThat(mapper.progressFragments(22,List.of(101L))).isEmpty();
+    }
+
 }

firstleg/src/test/java/com/baiyue/firstleg/service/DropshipPalletizationServiceTest.java

@@ -24,7 +24,56 @@ class DropshipPalletizationServiceTest {
  private final FirstlegDocumentNumberGenerator numbers=mock(FirstlegDocumentNumberGenerator.class);
  private final DropshipPalletizationMapper mapper=mock(DropshipPalletizationMapper.class);
  private final DropshipPalletizationService service=new DropshipPalletizationService();
- DropshipPalletizationServiceTest(){ ReflectionTestUtils.setField(service,"mapper",mapper); ReflectionTestUtils.setField(service,"documentNumbers",numbers); when(mapper.labelSkus(anyLong(),anyLong())).thenAnswer(call -> java.util.List.of(labelSku())); when(mapper.cartonSkus(anyLong())).thenAnswer(call -> java.util.List.of(cartonSku())); }
+ private final com.baiyue.firstleg.repository.DropshipWorkspaceRepository workspace=mock(com.baiyue.firstleg.repository.DropshipWorkspaceRepository.class);
+ /** 使用正式仓储入口的等价锁定查询，保留既有扫码测试的事实准备。 */
+ DropshipPalletizationServiceTest(){ ReflectionTestUtils.setField(service,"mapper",mapper); ReflectionTestUtils.setField(service,"documentNumbers",numbers); ReflectionTestUtils.setField(service,"workspaceRepository",workspace); when(workspace.lockPallet(anyString())).thenAnswer(call -> mapper.palletByNo(call.getArgument(0))); when(workspace.compatible(anyLong(),anyLong())).thenReturn(true); when(mapper.labelSkus(anyLong(),anyLong())).thenAnswer(call -> java.util.List.of(labelSku())); when(mapper.cartonSkus(anyLong())).thenAnswer(call -> java.util.List.of(cartonSku())); }
+
+ /** 跨客户预览不领取任务，不写入清点事实。 */
+ @Test void workspaceResolvesPendingCustomerWithoutMutating(){
+  ReflectionTestUtils.setField(service,"workspaceRepository",workspace);
+  TaskRow other=task(); other.setTenantId(2L); other.setTaskStatus("PENDING"); other.setAssigneeId(null);
+  when(workspace.taskIdsForBox(100L,"BOX-1")).thenReturn(java.util.List.of(10L));
+  when(mapper.task(10L,100L)).thenReturn(other);
+  when(mapper.label(10L,"BOX-1")).thenReturn(label());
+  when(mapper.palletCountByInbound(2L,30L)).thenReturn(other.getExpectedPalletCount());
+  var result=service.resolveWorkspaceCarton(100L," BOX-1 ",7L);
+  assertThat(result.task().tenantId()).isEqualTo(2L);
+  assertThat(result.carton().canCount()).isTrue();
+  verify(mapper,never()).claim(anyLong(),anyLong(),anyLong(),anyString());
+  verify(mapper,never()).addCounted(anyLong(),anyLong(),anyInt(),anyInt());
+ }
+
+ /** 不允许从跨票扫码接管其他作业员的任务。 */
+ @Test void workspaceRejectsOtherOperatorsTaskAndAmbiguousBox(){
+  ReflectionTestUtils.setField(service,"workspaceRepository",workspace);
+  when(workspace.taskIdsForBox(100L,"BOX-1")).thenReturn(java.util.List.of(10L));
+  TaskRow other=task(); other.setAssigneeId(9L); when(mapper.task(10L,100L)).thenReturn(other);
+  assertThatThrownBy(()->service.resolveWorkspaceCarton(100L,"BOX-1",7L)).isInstanceOf(BizException.class).hasMessageContaining("其他人员");
+  when(workspace.taskIdsForBox(100L,"BOX-1")).thenReturn(java.util.List.of(10L,11L));
+  assertThatThrownBy(()->service.resolveWorkspaceCarton(100L,"BOX-1",7L)).isInstanceOf(BizException.class).hasMessageContaining("多个任务");
+ }
+
+ /** 托盘预览必须返回已封托的真实状态，跨仓不存在时拒绝。 */
+ @Test void workspacePalletNeverInventsOpenState(){
+  ReflectionTestUtils.setField(service,"workspaceRepository",workspace);
+  when(workspace.pallet(100L,"DP-260911-0001")).thenReturn(sealedPallet());
+  when(workspace.members(20L)).thenReturn(java.util.List.of());
+  when(mapper.cartons(20L)).thenReturn(java.util.List.of());
+  assertThat(service.workspacePallet(100L,"DP-260911-0001").pallet().status()).isEqualTo("SEALED");
+  assertThatThrownBy(()->service.workspacePallet(101L,"DP-260911-0001")).isInstanceOf(BizException.class).hasMessageContaining("未找到");
+ }
+
+ /** 即使不同客户允许混托，运输渠道或目的仓不同仍须拒绝。 */
+ @Test void incompatibleDestinationCannotBeMixed(){
+  when(mapper.task(10L,100L)).thenReturn(task());
+  when(mapper.palletCountByInbound(1L,30L)).thenReturn(2);
+  when(mapper.label(10L,"BOX-1")).thenReturn(label());
+  when(mapper.palletByNo("DP-260911-0001")).thenReturn(pallet());
+  when(workspace.compatible(10L,20L)).thenReturn(false);
+  assertThatThrownBy(()->service.countCarton(10L,new CountCartonRequest(100L,"BOX-1",java.util.List.of(new CountSkuLine(40L,"SKU-1",12,DiscrepancyAction.MATCH,null)),"DP-260911-0001","wrong-destination"),7L,"张三"))
+   .isInstanceOf(BizException.class).hasMessageContaining("渠道或目的仓不同");
+  verify(mapper,never()).addCounted(anyLong(),anyLong(),anyInt(),anyInt());
+ }
 
  @Test void sharedPalletCountsDistinctSkuCodesWithoutMergingInboundDetails(){
   when(mapper.inboundCode(1L,30L)).thenReturn("IN-1");

firstleg/src/test/java/com/baiyue/firstleg/service/MerchantWorkbenchFilterServiceTest.java

@@ -0,0 +1,26 @@
+package com.baiyue.firstleg.service;
+
+import com.baiyue.firstleg.dto.MerchantWorkbenchFilters;
+import com.baiyue.firstleg.mapper.MerchantWorkbenchFilterMapper;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.util.ReflectionTestUtils;
+import java.util.List;
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+class MerchantWorkbenchFilterServiceTest {
+    @Test void exactDetailProgressSkipsUnrelatedCustomerQueues() {
+        var mapper=mock(MerchantWorkbenchFilterMapper.class);
+        var unified=mock(UnifiedInboundQueryService.class);
+        var service=new MerchantWorkbenchFilterService();
+        ReflectionTestUtils.setField(service,"mapper",mapper);
+        ReflectionTestUtils.setField(service,"unified",unified);
+        when(mapper.progressFragments(11,List.of(101L))).thenReturn(List.of(
+            new MerchantWorkbenchFilters.Fragment(101,3),new MerchantWorkbenchFilters.Fragment(101,1)));
+        var response=service.read(new MerchantWorkbenchFilters.Request(11L,null,List.of(101L)));
+        assertThat(response.progress()).containsExactly(new MerchantWorkbenchFilters.Progress(101,"cleared",true));
+        assertThat(response.feeOrderIds()).isEmpty();assertThat(response.customsOrderIds()).isEmpty();
+        assertThat(response.matchingStatusOrderIds()).isNull();
+        verify(mapper).progressFragments(11,List.of(101L));verifyNoMoreInteractions(mapper);verifyNoInteractions(unified);
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/mapper/ContainerCalendarSourceMapperTest.java

@@ -0,0 +1,44 @@
+package com.baiyue.firstleg.terminaldrayage.mapper;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.MybatisSqlSessionFactoryBuilder;
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.Test;
+import java.time.LocalDateTime;
+import static org.junit.jupiter.api.Assertions.*;
+
+class ContainerCalendarSourceMapperTest {
+    /** 使用实际 Mapper 核对跨月默认日期候选、缺日期与真实出仓边界。 */
+    @Test
+    void selectsShiftedArrivalUndatedAndOlderReturnCandidatesWithoutInactiveOrUndepartedContainers() throws Exception {
+        var ds = new JdbcDataSource();
+        ds.setURL("jdbc:h2:mem:four-type-calendar;MODE=MySQL;DB_CLOSE_DELAY=-1");
+        try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
+            sql.execute("CREATE TABLE fl_container_booking(id BIGINT,cabinet_no VARCHAR,container_no VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_warehouse_code VARCHAR," +
+                "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
+            sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_carrier_schedule_node_fact(id BIGINT,container_booking_id BIGINT,standard_node VARCHAR,actual_at TIMESTAMP,observed_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_direct_delivery_unloading(container_booking_id BIGINT,actual_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_outbound_dispatch(container_booking_id BIGINT,confirmed_at TIMESTAMP,reversed_at TIMESTAMP,status VARCHAR)");
+            sql.execute("INSERT INTO fl_container_booking(id,cabinet_no,estimated_port_arrival_at,record_status) VALUES " +
+                "(1,'D1','2026-10-30 12:00:00','ACTIVE'),(2,'D2','2026-11-10 12:00:00','ACTIVE')," +
+                "(3,'D3',NULL,'ACTIVE'),(4,'D4','2026-01-01 12:00:00','ACTIVE')," +
+                "(5,'D5','2026-11-10 12:00:00','CANCELLED'),(6,'D6','2026-11-10 12:00:00','ACTIVE')");
+            sql.execute("INSERT INTO fl_outbound_dispatch SELECT id,'2026-01-01 00:00:00',NULL,'WAITING_FOR_LOADING' FROM fl_container_booking WHERE id<>6");
+            sql.execute("INSERT INTO fl_terminal_drayage VALUES(4,'2026-11-05 12:00:00')");
+            sql.execute("INSERT INTO fl_carrier_schedule_node_fact VALUES(1,2,'ARRIVED_DESTINATION_PORT','2026-10-25 12:00:00','2026-10-26 12:00:00')");
+        }
+        var config = new MybatisConfiguration();
+        config.setEnvironment(new Environment("test", new JdbcTransactionFactory(), ds)); config.addMapper(ContainerCalendarSourceMapper.class);
+        try (var session = new MybatisSqlSessionFactoryBuilder().build(config).openSession()) {
+            var from = LocalDateTime.parse("2026-11-01T00:00:00");
+            var rows = session.getMapper(ContainerCalendarSourceMapper.class).sources(from, from.minusDays(2), from.minusDays(4), from.plusDays(30));
+            assertEquals(java.util.List.of(1L, 3L, 4L), rows.stream().map(row -> row.containerBookingId()).toList());
+            assertEquals("2026-10-30T12:00", rows.get(0).arrivalAt().toString());
+            assertNull(rows.get(1).arrivalAt());
+        }
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/mapper/DirectDeliveryMapperTest.java

@@ -8,6 +8,8 @@ import org.h2.jdbcx.JdbcDataSource;
 import org.junit.jupiter.api.Test;
 import java.time.LocalDateTime;
 import java.util.UUID;
+import java.util.List;
+import com.baiyue.firstleg.portschedule.mapper.AppointmentWorkSourceMapper;
 import static org.junit.jupiter.api.Assertions.*;
 
 class DirectDeliveryMapperTest {
@@ -20,8 +22,19 @@ class DirectDeliveryMapperTest {
             s.execute("CREATE TABLE fl_direct_delivery_unloading(container_booking_id BIGINT,inbound_id BIGINT,actual_at TIMESTAMP,timezone VARCHAR,received_by VARCHAR,evidence_no VARCHAR,remark VARCHAR,version INT,idempotency_key VARCHAR,request_hash VARCHAR,created_by BIGINT,created_by_name VARCHAR,PRIMARY KEY(container_booking_id,inbound_id),UNIQUE(container_booking_id,idempotency_key))");
             s.execute("INSERT INTO fl_container_booking VALUES(1,'ACTIVE',NULL)");s.execute("INSERT INTO fl_loading_plan VALUES(10,1,'COMPLETED')");
             s.execute("INSERT INTO fl_loading_plan_item VALUES(10,20,'I20','O20','D',3,0),(10,20,'I20','O20','D',4,0),(10,21,'I21','O21','D',5,0),(10,22,'I22','O22','D',100,1)");
+            s.execute("INSERT INTO fl_container_booking VALUES(2,'ACTIVE','2026-01-02 12:00:00'),(3,'ACTIVE',NULL)");
+            s.execute("INSERT INTO fl_loading_plan VALUES(11,2,'COMPLETED'),(12,3,'DRAFT')");
+            s.execute("INSERT INTO fl_loading_plan_item VALUES(11,20,'I20','O20','D',2,0),(12,20,'I20','O20','D',100,0)");
+            s.execute("ALTER TABLE fl_loading_plan_item ADD account_id BIGINT DEFAULT 7");
+            s.execute("ALTER TABLE fl_loading_plan_item ADD order_id BIGINT DEFAULT 8");
+            s.execute("ALTER TABLE fl_loading_plan_item ADD destination_warehouse_code VARCHAR DEFAULT 'D'");
+            s.execute("CREATE TABLE fl_inbound_order(id BIGINT,destination_type VARCHAR)");
+            s.execute("INSERT INTO fl_inbound_order VALUES(20,'PRIVATE'),(21,'AMAZON'),(22,'PRIVATE')");
+            s.execute("CREATE TABLE fl_terminal_drayage_history(container_booking_id BIGINT,action VARCHAR)");
+            s.execute("INSERT INTO fl_terminal_drayage_history VALUES(1,'SELECT_FLEET'),(1,'SCHEDULE_PICKUP'),(1,'SCHEDULE_PICKUP'),(1,'OTHER'),(2,'SELECT_FLEET')");
         }
         var config=new MybatisConfiguration();config.setMapUnderscoreToCamelCase(true);config.setEnvironment(new Environment("test",new JdbcTransactionFactory(),ds));config.addMapper(DirectDeliveryMapper.class);
+        config.addMapper(AppointmentWorkSourceMapper.class);config.addMapper(TerminalDrayageMapper.class);
         try(var session=new MybatisSqlSessionFactoryBuilder().build(config).openSession()) {
             var mapper=session.getMapper(DirectDeliveryMapper.class);assertEquals(1,mapper.lockContainer(1).id());
             assertEquals(2,mapper.deliveries(1).size());assertEquals(7,mapper.deliveries(1).get(0).packageCount());
@@ -29,6 +42,18 @@ class DirectDeliveryMapperTest {
             mapper.insert(1,20,at,"America/Los_Angeles","签收人","POD20",null,"key","hash",7,"admin");
             assertEquals(1,mapper.evidenceCount(1));assertEquals(1,mapper.keyCount(1,"key"));
             assertEquals(at,mapper.deliveries(1).get(0).actualAt());assertNull(mapper.deliveries(1).get(1).actualAt());
+            var batch=mapper.deliveriesBatch(List.of(1L,2L,3L));
+            assertEquals(3,batch.size());assertEquals(mapper.deliveries(1),batch.stream().filter(r->r.containerBookingId()==1).map(DirectDeliveryMapper.ContainerDelivery::delivery).toList());
+            assertEquals(2,batch.get(2).packageCount());assertNull(batch.get(2).actualAt());
+            assertEquals(3,mapper.containers(List.of(1L,2L,3L)).size());
+            var flows=mapper.flowEvidence(List.of(1L,2L,3L));
+            assertEquals(1,flows.stream().filter(r->r.id()==1).findFirst().orElseThrow().evidenceCount());
+            assertNotNull(flows.stream().filter(r->r.id()==2).findFirst().orElseThrow().warehouseUnloadedAt());
+            var cargo=session.getMapper(AppointmentWorkSourceMapper.class).cargo(List.of(1L,2L,3L));
+            assertEquals(3,cargo.size());assertEquals(7,cargo.get(0).packageCount());assertEquals(1,cargo.get(0).containerBookingId());
+            assertEquals(2,cargo.get(2).containerBookingId());assertEquals(2,cargo.get(2).packageCount());
+            var changes=session.getMapper(TerminalDrayageMapper.class).pickupChanges(List.of(1L,2L,3L));
+            assertEquals(new TerminalDrayageMapper.PickupChanges(1,2,1),changes.stream().filter(r->r.containerBookingId()==1).findFirst().orElseThrow());
             assertThrows(RuntimeException.class,()->mapper.insert(1,20,at,"America/Los_Angeles","签收人","POD20",null,"another","hash",7,"admin"));
             session.rollback();
         }

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/service/AppointmentWorkTerminalFactsTest.java

@@ -5,11 +5,11 @@ import com.baiyue.firstleg.portschedule.dto.CarrierScheduleQueryDtos.ContainerAc
 import com.baiyue.firstleg.portschedule.service.CarrierScheduleQueryService;
 import com.baiyue.firstleg.terminaldrayage.mapper.*;
 import com.baiyue.firstleg.terminaldrayage.entity.TerminalDrayageEntity;
-import com.baiyue.firstleg.terminaldrayage.dto.TerminalDrayageDtos.History;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.Test;
 import java.time.LocalDateTime;
 import java.util.List;
+import java.util.Map;
 import static org.mockito.Mockito.*;
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -22,22 +22,43 @@ class AppointmentWorkTerminalFactsTest {
     private final LocalDateTime at=LocalDateTime.parse("2026-01-01T12:30:00");
     private ContainerSource source(){return new ContainerSource("1","C1",null,at,at,"v","UNKNOWN",null,List.of());}
     private FactRequest request(String type){return new FactRequest("W1",type,"DIRECT","1",null,null,null,List.of(),List.of(),List.of());}
-    private History history(String action){return new History(action,"A","B",1,2,null,7L,"admin",at);}
+    private Fact read(FactRequest request,ContainerSource source) {return adapter.read(List.of(request),Map.of(1L,source)).get(0);}
+    @Test void twoHundredRequestsReadEachFactSetOnceAndKeepMissingFactsVisible() {
+        var ids=java.util.stream.LongStream.rangeClosed(1,100).boxed().toList();
+        var sources=new java.util.HashMap<Long,ContainerSource>();
+        var requests=new java.util.ArrayList<FactRequest>();
+        for(long id:ids) {
+            sources.put(id,new ContainerSource(Long.toString(id),"C"+id,null,at,at,"v","UNKNOWN",null,List.of()));
+            requests.add(new FactRequest("P"+id,"PICKUP","TRANSIT",Long.toString(id),null,null,null,List.of(),List.of(),List.of()));
+            requests.add(new FactRequest("R"+id,"EMPTY_RETURN","TRANSIT",Long.toString(id),null,null,null,List.of(),List.of(),List.of()));
+        }
+        var results=adapter.read(requests,sources);
+        assertEquals(200,results.size());
+        for(int i=0;i<results.size();i++) {assertEquals(requests.get(i).workItemKey(),results.get(i).workItemKey());assertFalse(results.get(i).blockReasons().isEmpty());}
+        verify(nodes).containerActualFacts(ids);verify(terminal).findAll(ids);verify(terminal).pickupChanges(ids);
+        verify(guard).completedUnloading(ids);verifyNoMoreInteractions(nodes,terminal,guard);verifyNoInteractions(direct);
+    }
+    @Test void batchedFlowConflictsStillFailClosed() {
+        when(direct.flowEvidence(List.of(1L,2L))).thenReturn(List.of(new DirectDeliveryMapper.FlowEvidence(1,null,1),new DirectDeliveryMapper.FlowEvidence(2,at,1)));
+        assertEquals(409,assertThrows(org.springframework.web.server.ResponseStatusException.class,()->adapter.establishedFlows(List.of(1L,2L))).getStatusCode().value());
+    }
     @Test void initialPickupPlanRetainsLocalDateAndDoesNotInventZoneOrReview() {
-        var plan=new TerminalDrayageEntity();plan.setPickupAppointmentAt(at);plan.setFleetSupplierId(4L);plan.setFleetSupplierName("车队");
+        var plan=new TerminalDrayageEntity();plan.setContainerBookingId(1L);plan.setPickupAppointmentAt(at);plan.setFleetSupplierId(4L);plan.setFleetSupplierName("车队");
-        when(terminal.find(1)).thenReturn(plan);
+        when(terminal.findAll(List.of(1L))).thenReturn(List.of(plan));
-        when(terminal.histories(1)).thenReturn(List.of(history("SELECT_FLEET"),history("SCHEDULE_PICKUP")));
+        when(terminal.pickupChanges(List.of(1L))).thenReturn(List.of(new TerminalDrayageMapper.PickupChanges(1,1,1)));
-        var fact=adapter.read(request("PICKUP"),source());
+        var fact=read(request("PICKUP"),source());
         assertEquals("0:0",fact.impactToken());assertEquals(at.toLocalDate(),fact.confirmed().date());
         assertNull(fact.timezone());assertTrue(fact.missingFields().contains("SOURCE_TIMEZONE"));
-        when(terminal.histories(1)).thenReturn(List.of(history("SELECT_FLEET"),history("SCHEDULE_PICKUP"),history("SCHEDULE_PICKUP")));
+        var returnRequest=new FactRequest("W2","EMPTY_RETURN","DIRECT","1",null,null,null,List.of(),List.of(),List.of());
-        assertEquals("1:0",adapter.read(request("PICKUP"),source()).impactToken());
+        assertEquals(fact,adapter.read(List.of(request("PICKUP"),returnRequest),Map.of(1L,source())).get(0));
+        when(terminal.pickupChanges(List.of(1L))).thenReturn(List.of(new TerminalDrayageMapper.PickupChanges(1,2,1)));
+        assertEquals("1:0",read(request("PICKUP"),source()).impactToken());
     }
     @Test void emptyReturnActualIsCompleteEvenWhenOriginalTimezoneIsUnknownAndDoesNotCopyPickupResponsibility() {
-        var plan=new TerminalDrayageEntity();plan.setFleetSupplierId(4L);plan.setFleetSupplierName("提柜承运人");
+        var plan=new TerminalDrayageEntity();plan.setContainerBookingId(1L);plan.setFleetSupplierId(4L);plan.setFleetSupplierName("提柜承运人");
-        when(terminal.find(1)).thenReturn(plan);
+        when(terminal.findAll(List.of(1L))).thenReturn(List.of(plan));
         when(nodes.containerActualFacts(List.of(1L))).thenReturn(List.of(new ContainerActualFacts(1L,2L,3,"STOPPED","EMPTY_RETURNED",at,null,null,null,null,at.minusDays(1),at)));
-        var fact=adapter.read(request("EMPTY_RETURN"),source());
+        var fact=read(request("EMPTY_RETURN"),source());
         assertEquals("COMPLETED",fact.executionStatus());assertNull(fact.actual().occurredAt());assertEquals(at,fact.actual().localOccurredAt());
         assertNull(fact.responsibility());assertNull(fact.action());assertNull(fact.businessNo());
     }
@@ -47,9 +68,10 @@ class AppointmentWorkTerminalFactsTest {
         var source=new ContainerSource("1","C1",null,at,at,"v","DIRECT",null,List.of(
             new Requirement("INBOUND:2",null,null,"PRIVATE","港","A",null,own,List.of(),List.of()),
             new Requirement("INBOUND:3",null,null,"PRIVATE","港","B",null,other,List.of(),List.of())));
-        when(direct.deliveries(1)).thenReturn(List.of(new DirectDeliveryMapper.Delivery(2,"IN2","O2","A",4,1,at,"America/Los_Angeles","a","P2",null,"k","h")));
+        when(direct.deliveriesBatch(List.of(1L))).thenReturn(List.of(new DirectDeliveryMapper.ContainerDelivery(1,2,"IN2","O2","A",4,1,at,"America/Los_Angeles","a","P2",null,"k","h")));
         var request=new FactRequest("W1","DELIVERY","DIRECT","1","INBOUND:2",null,null,List.of(),List.of(),List.of());
-        var fact=adapter.read(request,source);
+        var fact=read(request,source);
         assertEquals(own,fact.references());assertEquals("IN2",fact.businessNo());assertEquals("COMPLETED",fact.executionStatus());
+        assertEquals(fact,adapter.read(List.of(request,new FactRequest("W2","PICKUP","DIRECT","1",null,null,null,List.of(),List.of(),List.of())),Map.of(1L,source)).get(0));
     }
 }

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/service/ContainerCalendarSourceServiceTest.java

@@ -0,0 +1,45 @@
+package com.baiyue.firstleg.terminaldrayage.service;
+
+import com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource;
+import com.baiyue.firstleg.terminaldrayage.dto.TerminalDrayageDtos.*;
+import com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.server.ResponseStatusException;
+import java.time.*;
+import java.util.*;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+class ContainerCalendarSourceServiceTest {
+    private final ContainerCalendarSourceRepository repository = mock(ContainerCalendarSourceRepository.class);
+    private final TerminalDrayageService drayages = mock(TerminalDrayageService.class);
+    private final ContainerCalendarSourceService service = new ContainerCalendarSourceService(repository, drayages);
+    private final LocalDate from = LocalDate.of(2026, 11, 1), to = from.plusDays(30);
+    /** 缺还柜读取权限时保留范围说明，不读取受保护事实。 */
+    @Test void keepsMissingReturnPermissionExplicitWithoutReadingProtectedFacts() {
+        when(repository.sources(from, to)).thenReturn(List.of(
+            new ContainerCalendarSource(1L,"D1",null,null,null,null,null,null,"ESTIMATED"),
+            new ContainerCalendarSource(2L,"D2",null,null,null,null,null,from.minusMonths(2).atStartOfDay(),"ACTUAL")));
+        var result = service.calendar(from, to, Set.of("platform:appointment:list"));
+        assertEquals(1, result.containers().size()); assertFalse(result.emptyReturnsReadable());
+        verifyNoInteractions(drayages);
+    }
+    /** 实际还柜日期优先于截止日期，范围外完成事实不回落到原提醒日。 */
+    @Test void usesOriginalDeadlineButActualReturnSupersedesTheDeadlineDate() {
+        when(repository.sources(from, to)).thenReturn(List.of(new ContainerCalendarSource(1L,"D1",null,null,null,null,null,null,"ESTIMATED")));
+        var row = mock(View.class);
+        when(row.actualEmptyReturnAt()).thenReturn(to.atStartOfDay());
+        when(row.emptyReturnWarning()).thenReturn(new Warning("RESOLVED", from.atStartOfDay(),0,0));
+        when(drayages.views(List.of(1L))).thenReturn(List.of(row));
+        when(drayages.authorize(anyList(), anySet())).thenAnswer(call -> call.getArgument(0));
+        assertTrue(service.calendar(from,to,Set.of("platform:firstleg:terminal-drayage:list")).emptyReturns().isEmpty());
+        when(row.actualEmptyReturnAt()).thenReturn(null);
+        assertEquals(List.of(row), service.calendar(from,to,Set.of("platform:firstleg:terminal-drayage:list")).emptyReturns());
+    }
+    /** 非法日期范围在访问持久化层前拒绝。 */
+    @Test void rejectsInvalidRangesBeforeDatabaseAccess() {
+        assertThrows(ResponseStatusException.class, () -> service.calendar(from,from,Set.of()));
+        assertThrows(ResponseStatusException.class, () -> service.calendar(from,from.plusDays(43),Set.of()));
+        verifyNoInteractions(repository);
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/service/UnloadingEvidenceGuardTest.java

@@ -9,6 +9,21 @@ import static org.mockito.Mockito.*;
 import static org.junit.jupiter.api.Assertions.*;
 
 class UnloadingEvidenceGuardTest {
+    @Test void batchRetainsInactiveMissingPartialAndZonedCompletionRules() {
+        var mapper=mock(DirectDeliveryMapper.class);var guard=new UnloadingEvidenceGuard(mapper);
+        var at=LocalDateTime.parse("2026-10-10T12:00:00");
+        var ids=List.of(1L,2L,3L,4L,5L,6L);
+        when(mapper.containers(ids)).thenReturn(List.of(new DirectDeliveryMapper.Container(1,"ACTIVE",at),
+            new DirectDeliveryMapper.Container(2,"ACTIVE",null),new DirectDeliveryMapper.Container(3,"ACTIVE",null),
+            new DirectDeliveryMapper.Container(4,"CANCELLED",at),new DirectDeliveryMapper.Container(5,"ACTIVE",null)));
+        when(mapper.deliveriesBatch(List.of(2L,3L,5L))).thenReturn(List.of(
+            new DirectDeliveryMapper.ContainerDelivery(2,20,"I20","O20","D",1,1,at,"America/New_York",null,null,null,null,null),
+            new DirectDeliveryMapper.ContainerDelivery(2,21,"I21","O21","D",1,1,at.minusHours(2),"America/Los_Angeles",null,null,null,null,null),
+            new DirectDeliveryMapper.ContainerDelivery(3,30,"I30","O30","D",1,1,at,"America/New_York",null,null,null,null,null),
+            new DirectDeliveryMapper.ContainerDelivery(3,31,"I31","O31","D",1,0,null,null,null,null,null,null,null)));
+        assertEquals(java.util.Map.of(1L,at,2L,at.minusHours(2)),guard.completedUnloading(ids));
+        verify(mapper).containers(ids);verify(mapper).deliveriesBatch(List.of(2L,3L,5L));verifyNoMoreInteractions(mapper);
+    }
     @Test void requiresEveryPhysicalInboundSourceAndAcceptsLatestActualEvidence() {
         var mapper=mock(DirectDeliveryMapper.class);var guard=new UnloadingEvidenceGuard(mapper);
         var container=new DirectDeliveryMapper.Container(1,"ACTIVE",null);

gateway/AGENTS.md

@@ -1,5 +1,10 @@
 # Gateway 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责与边界
 
 - 负责路由、CORS、JWT/Redis 会话校验、平台/客户访问域隔离、请求标识和 Swagger 聚合。

iam/AGENTS.md

@@ -1,5 +1,10 @@
 # IAM Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责与边界
 
 - Mapper 只由 `BaiyueIamApplication.java` 对 `com.baiyue.iam` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。

iam/src/main/resources/db/lastleg-permissions.sql

@@ -31,7 +31,6 @@ VALUES
   (5107011,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:create','创建海外入仓计划',NULL,'POST',711,'ACTIVE',1,0),
   (5107012,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:edit','编辑海外入仓计划',NULL,'POST',712,'ACTIVE',1,0),
   (5107013,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:fba-appointment','FBA预约',NULL,'POST',713,'ACTIVE',1,0),
-  (5107014,0,'PLATFORM','BUTTON',5107010,'platform:overseas-warehouse:inbound-order:smart-dispatch','智能排车',NULL,'POST',714,'ACTIVE',1,0),
   (5107015,0,'PLATFORM','BUTTON',5107010,'lastleg:pda:operate','海外仓PDA入仓作业',NULL,'POST',715,'ACTIVE',1,0),
   (5107020,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:relabel-order:list','海外换标单','/overseas-warehouse/relabel-orders','GET',720,'ACTIVE',1,0),
   (5107021,0,'PLATFORM','BUTTON',5107020,'platform:overseas-warehouse:relabel-order:create','创建海外换标单',NULL,'POST',721,'ACTIVE',1,0),
@@ -283,8 +282,7 @@ SELECT 0, role.id, permission.id, NOW(3)
 FROM iam_role role
 JOIN iam_permission permission ON permission.tenant_id=0 AND permission.app_code='PLATFORM'
   AND permission.permission_code IN (
-    'platform:overseas-warehouse:inbound-order:fba-appointment',
+    'platform:overseas-warehouse:inbound-order:fba-appointment'
-    'platform:overseas-warehouse:inbound-order:smart-dispatch'
   )
 WHERE role.tenant_id=0 AND role.app_code='PLATFORM'
   AND UPPER(role.role_code)='PLATFORM_CUSTOM_ADMIN'

iam/src/main/resources/db/phase5-delivery-permissions.sql

@@ -9,6 +9,9 @@ BEGIN
   IF EXISTS (
     SELECT 1 FROM iam_permission
      WHERE (id = 5107064 AND permission_code <> 'platform:overseas-warehouse:dispatch:list')
+        OR (id = 5107065 AND permission_code <> 'platform:overseas-warehouse:dispatch:create')
+        OR (id = 5107066 AND permission_code <> 'platform:overseas-warehouse:dispatch:loading-complete')
+        OR (id = 5107067 AND permission_code <> 'platform:overseas-warehouse:dispatch:depart')
         OR (id = 5107016 AND permission_code <> 'platform:overseas-warehouse:dispatch:edit')
         OR (id = 5107017 AND permission_code <> 'platform:overseas-warehouse:dispatch:cancel')
         OR (id = 5107018 AND permission_code <> 'platform:overseas-warehouse:dispatch:transfer-delivery')
@@ -25,10 +28,12 @@ BEGIN
         OR (id = 5107081 AND permission_code <> 'platform:overseas-warehouse:customer-visit:edit')
         OR (id = 5107082 AND permission_code <> 'platform:overseas-warehouse:delivery:status')
         OR (id = 5306000 AND permission_code <> 'merchant:warehouse:delivery:list')
-        OR (id = 5306001 AND permission_code <> 'merchant:warehouse:delivery:create')
   ) OR EXISTS (
     SELECT 1 FROM iam_permission
      WHERE (permission_code = 'platform:overseas-warehouse:dispatch:list' AND id <> 5107064)
+        OR (permission_code = 'platform:overseas-warehouse:dispatch:create' AND id <> 5107065)
+        OR (permission_code = 'platform:overseas-warehouse:dispatch:loading-complete' AND id <> 5107066)
+        OR (permission_code = 'platform:overseas-warehouse:dispatch:depart' AND id <> 5107067)
         OR (permission_code = 'platform:overseas-warehouse:dispatch:edit' AND id <> 5107016)
         OR (permission_code = 'platform:overseas-warehouse:dispatch:cancel' AND id <> 5107017)
         OR (permission_code = 'platform:overseas-warehouse:dispatch:transfer-delivery' AND id <> 5107018)
@@ -45,7 +50,6 @@ BEGIN
         OR (permission_code = 'platform:overseas-warehouse:customer-visit:edit' AND id <> 5107081)
         OR (permission_code = 'platform:overseas-warehouse:delivery:status' AND id <> 5107082)
         OR (permission_code = 'merchant:warehouse:delivery:list' AND id <> 5306000)
-        OR (permission_code = 'merchant:warehouse:delivery:create' AND id <> 5306001)
   ) THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='五期海外派送权限初始化失败：权限ID或编码冲突';
   END IF;
@@ -59,8 +63,11 @@ INSERT INTO iam_permission
    permission_name, route_path, http_method, sort_no, status, built_in, deleted)
 VALUES
   (5107064,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:dispatch:list','海外排车单','/overseas-warehouse/dispatches','GET',764,'ACTIVE',1,0),
+  (5107065,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:create','新增排车单',NULL,'POST',765,'ACTIVE',1,0),
+  (5107066,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:loading-complete','确认装车完成',NULL,'POST',766,'ACTIVE',1,0),
+  (5107067,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:depart','确认实际发车',NULL,'POST',767,'ACTIVE',1,0),
   (5107016,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:edit','编辑海外排车',NULL,'PUT',716,'ACTIVE',1,0),
-  (5107017,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'DELETE',717,'ACTIVE',1,0),
+  (5107017,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'POST',717,'ACTIVE',1,0),
   (5107018,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:transfer-delivery','排车转派送',NULL,'POST',718,'ACTIVE',1,0),
   (5107070,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:exception-order:list','海外异常订单','/overseas-warehouse/exception-orders','GET',770,'ACTIVE',1,0),
   (5107071,0,'PLATFORM','BUTTON',5107070,'platform:overseas-warehouse:exception-order:create','新增海外异常订单',NULL,'POST',771,'ACTIVE',1,0),
@@ -74,8 +81,7 @@ VALUES
   (5107092,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:delivery:list','海外派送单','/overseas-warehouse/delivery-orders','GET',767,'ACTIVE',1,0),
   (5107094,0,'PLATFORM','BUTTON',5107092,'platform:overseas-warehouse:delivery:documents','管理派送资料',NULL,'POST',769,'ACTIVE',1,0),
   (5107093,0,'PLATFORM','BUTTON',5107090,'platform:overseas-warehouse:outbound:cancel','取消海外出库单',NULL,'POST',768,'ACTIVE',1,0),
-  (5306000,0,'MERCHANT','MENU',0,'merchant:warehouse:delivery:list','海外仓派送单','/orders/delivery','GET',60,'ACTIVE',1,0),
+  (5306000,0,'MERCHANT','MENU',0,'merchant:warehouse:delivery:list','海外仓派送单','/orders/delivery','GET',60,'ACTIVE',1,0)
-  (5306001,0,'MERCHANT','BUTTON',5306000,'merchant:warehouse:delivery:create','创建海外仓派送单',NULL,'POST',10,'ACTIVE',1,0)
 ON DUPLICATE KEY UPDATE
   permission_type=VALUES(permission_type), parent_id=VALUES(parent_id),
   permission_name=VALUES(permission_name), route_path=VALUES(route_path),
@@ -92,6 +98,9 @@ SELECT 0, role.id, permission.id, CURRENT_TIMESTAMP(3)
    AND role.status='ACTIVE' AND role.deleted=0
    AND permission.permission_code IN (
      'platform:overseas-warehouse:dispatch:list',
+     'platform:overseas-warehouse:dispatch:create',
+     'platform:overseas-warehouse:dispatch:loading-complete',
+     'platform:overseas-warehouse:dispatch:depart',
      'platform:overseas-warehouse:dispatch:edit',
      'platform:overseas-warehouse:dispatch:cancel',
      'platform:overseas-warehouse:dispatch:transfer-delivery',
@@ -117,8 +126,7 @@ SELECT role.tenant_id, role.id, permission.id, CURRENT_TIMESTAMP(3)
  WHERE role.tenant_id>0 AND role.app_code='MERCHANT' AND role.role_code='MERCHANT_OWNER'
    AND role.status='ACTIVE' AND role.deleted=0
    AND permission.permission_code IN (
-     'merchant:warehouse:delivery:list',
+     'merchant:warehouse:delivery:list')
-     'merchant:warehouse:delivery:create')
    AND permission.status='ACTIVE' AND permission.deleted=0;
 
 -- 仓库后台岗位按最小职责授权；PDA 岗位不得获得后台排车、出库或派送权限。
@@ -130,6 +138,9 @@ CREATE TEMPORARY TABLE tmp_phase5_delivery_role_permission (
 ) ENGINE=MEMORY;
 INSERT INTO tmp_phase5_delivery_role_permission (role_code, permission_code) VALUES
   ('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:list'),
+  ('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:create'),
+  ('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:loading-complete'),
+  ('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:depart'),
   ('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:edit'),
   ('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:cancel'),
   ('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:transfer-delivery'),
@@ -160,6 +171,9 @@ WHERE role.tenant_id=0 AND role.app_code='PLATFORM'
   AND role.role_code IN ('WAREHOUSE_OPERATOR','WAREHOUSE_TALLY','OVERSEAS_WAREHOUSE_PDA_OPERATOR','CN_FIRSTLEG_PDA_OPERATOR')
   AND permission.permission_code IN (
     'platform:overseas-warehouse:dispatch:list',
+     'platform:overseas-warehouse:dispatch:create',
+     'platform:overseas-warehouse:dispatch:loading-complete',
+     'platform:overseas-warehouse:dispatch:depart',
     'platform:overseas-warehouse:dispatch:edit',
     'platform:overseas-warehouse:dispatch:cancel',
     'platform:overseas-warehouse:dispatch:transfer-delivery',
@@ -186,7 +200,7 @@ SELECT 0, role.id, permission.id, CURRENT_TIMESTAMP(3)
     AND permission.permission_code=expected.permission_code
     AND permission.status='ACTIVE' AND permission.deleted=0;
 
--- 客户默认管理员获得派送列表/详情只读及独立创建；其他客户角色不自动扩权。
+-- 客户默认管理员只获得派送列表和详情读取；整车派送由平台统一安排。
 INSERT IGNORE INTO iam_role_permission (tenant_id, role_id, permission_id, created_at)
 SELECT 0, role.id, permission.id, CURRENT_TIMESTAMP(3)
   FROM iam_role role
@@ -194,8 +208,7 @@ SELECT 0, role.id, permission.id, CURRENT_TIMESTAMP(3)
  WHERE role.tenant_id=0 AND role.app_code='MERCHANT' AND role.role_code='MERCHANT_OWNER'
    AND role.status='ACTIVE' AND role.deleted=0
    AND permission.permission_code IN (
-     'merchant:warehouse:delivery:list',
+     'merchant:warehouse:delivery:list')
-     'merchant:warehouse:delivery:create')
    AND permission.status='ACTIVE' AND permission.deleted=0;
 
 DROP PROCEDURE IF EXISTS assert_phase5_delivery_permissions;
@@ -209,6 +222,9 @@ BEGIN
        WHERE tenant_id=0 AND status='ACTIVE' AND deleted=0
          AND permission_code IN (
            'platform:overseas-warehouse:dispatch:list',
+     'platform:overseas-warehouse:dispatch:create',
+     'platform:overseas-warehouse:dispatch:loading-complete',
+     'platform:overseas-warehouse:dispatch:depart',
            'platform:overseas-warehouse:dispatch:edit',
            'platform:overseas-warehouse:dispatch:cancel',
            'platform:overseas-warehouse:dispatch:transfer-delivery',
@@ -224,8 +240,7 @@ BEGIN
            'platform:overseas-warehouse:delivery:documents',
            'platform:overseas-warehouse:customer-visit:list',
            'platform:overseas-warehouse:customer-visit:edit',
-           'merchant:warehouse:delivery:list',
+           'merchant:warehouse:delivery:list')) <> 20 THEN
-           'merchant:warehouse:delivery:create')) <> 18 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='五期海外派送权限初始化失败：权限目录不完整';
   END IF;
   IF (SELECT COUNT(*) FROM iam_role_permission grant_row
@@ -234,6 +249,9 @@ BEGIN
        WHERE role.role_code='PLATFORM_ADMIN'
          AND permission.permission_code IN (
            'platform:overseas-warehouse:dispatch:list',
+     'platform:overseas-warehouse:dispatch:create',
+     'platform:overseas-warehouse:dispatch:loading-complete',
+     'platform:overseas-warehouse:dispatch:depart',
            'platform:overseas-warehouse:dispatch:edit',
            'platform:overseas-warehouse:dispatch:cancel',
            'platform:overseas-warehouse:dispatch:transfer-delivery',
@@ -248,7 +266,7 @@ BEGIN
            'platform:overseas-warehouse:delivery:status',
            'platform:overseas-warehouse:delivery:documents',
            'platform:overseas-warehouse:customer-visit:list',
-           'platform:overseas-warehouse:customer-visit:edit')) <> 16 THEN
+           'platform:overseas-warehouse:customer-visit:edit')) <> 19 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='五期海外派送权限初始化失败：平台管理员授权不完整';
   END IF;
   IF EXISTS (SELECT 1 FROM iam_role role
@@ -260,6 +278,9 @@ BEGIN
               WHERE grant_row.role_id=role.id AND grant_row.tenant_id=role.tenant_id
                 AND permission.permission_code IN (
            'platform:overseas-warehouse:dispatch:list',
+     'platform:overseas-warehouse:dispatch:create',
+     'platform:overseas-warehouse:dispatch:loading-complete',
+     'platform:overseas-warehouse:dispatch:depart',
            'platform:overseas-warehouse:dispatch:edit',
            'platform:overseas-warehouse:dispatch:cancel',
            'platform:overseas-warehouse:dispatch:transfer-delivery',
@@ -274,14 +295,14 @@ BEGIN
            'platform:overseas-warehouse:delivery:status',
            'platform:overseas-warehouse:delivery:documents',
            'platform:overseas-warehouse:customer-visit:list',
-           'platform:overseas-warehouse:customer-visit:edit')) <> 16) THEN
+           'platform:overseas-warehouse:customer-visit:edit')) <> 19) THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='五期海外派送权限初始化失败：平台自定义管理员授权不完整';
   END IF;
   SELECT COALESCE(SUM(role_code='WAREHOUSE_OPERATOR'),0),
          COALESCE(SUM(role_code='WAREHOUSE_TALLY'),0)
     INTO v_warehouse_operator_permission_count, v_warehouse_tally_permission_count
     FROM tmp_phase5_delivery_role_permission;
-  IF v_warehouse_operator_permission_count <> 16
+  IF v_warehouse_operator_permission_count <> 19
      OR v_warehouse_tally_permission_count <> 5 THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='五期海外派送权限初始化失败：仓库岗位最小权限矩阵异常';
   END IF;
@@ -291,6 +312,9 @@ BEGIN
        WHERE role.role_code IN ('OVERSEAS_WAREHOUSE_PDA_OPERATOR','CN_FIRSTLEG_PDA_OPERATOR')
          AND permission.permission_code IN (
            'platform:overseas-warehouse:dispatch:list',
+     'platform:overseas-warehouse:dispatch:create',
+     'platform:overseas-warehouse:dispatch:loading-complete',
+     'platform:overseas-warehouse:dispatch:depart',
            'platform:overseas-warehouse:dispatch:edit',
            'platform:overseas-warehouse:dispatch:cancel',
            'platform:overseas-warehouse:dispatch:transfer-delivery',
@@ -313,11 +337,10 @@ BEGIN
          ON grant_row.role_id=role.id AND grant_row.tenant_id=role.tenant_id
        LEFT JOIN iam_permission permission ON permission.id=grant_row.permission_id
          AND permission.permission_code IN (
-           'merchant:warehouse:delivery:list',
+           'merchant:warehouse:delivery:list')
-           'merchant:warehouse:delivery:create')
        WHERE role.role_code='MERCHANT_OWNER' AND role.app_code='MERCHANT'
          AND role.status='ACTIVE' AND role.deleted=0
-       GROUP BY role.id HAVING COUNT(DISTINCT permission.permission_code) <> 2) THEN
+       GROUP BY role.id HAVING COUNT(DISTINCT permission.permission_code) <> 1) THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='五期海外派送权限初始化失败：客户默认管理员授权不完整';
   END IF;
 END$$

iam/src/main/resources/openapi/iam-v1.yaml

@@ -146,7 +146,7 @@ paths:
     get:
       tags: [IAM Resources / IAM 资源]
       summary: 查询当前用户有效权限
-      description: 返回当前有效平台成员权限编码；只要求有效 PLATFORM JWT，不依赖 `platform:role:list`。入库单扣货与解除扣货返回独立写权限 `platform:firstleg:inbound:hold`，不会由 `platform:firstleg:inbound:list` 查看权限自动获得。资金账户充值审核与手工调账分别返回 `platform:finance:recharge:review`、`platform:finance:customer-account:adjust`，并与 `platform:finance:customer-account:list` 只读权限分离。海外仓返回 `platform:overseas-warehouse:dispatch:list`、`platform:overseas-warehouse:dispatch:edit`、`platform:overseas-warehouse:dispatch:cancel`、`platform:overseas-warehouse:dispatch:transfer-delivery`、`platform:overseas-warehouse:outbound:list`、`platform:overseas-warehouse:outbound:create`、`platform:overseas-warehouse:outbound:cancel`、`platform:overseas-warehouse:delivery:list`、`platform:overseas-warehouse:delivery:return`、`platform:overseas-warehouse:delivery:status`、`platform:overseas-warehouse:delivery:documents`、`platform:overseas-warehouse:exception-order:list`、`platform:overseas-warehouse:exception-order:create`、`platform:overseas-warehouse:exception-order:process`、`platform:overseas-warehouse:customer-visit:list`、`platform:overseas-warehouse:customer-visit:edit`；海外 PDA 盘点、移库、换标和现场查询统一返回 `lastleg:pda:operate`，且仅限 `OVERSEAS_WAREHOUSE_PDA_OPERATOR`。货柜双工作台以 `platform:firstleg:container:list/create/edit` 维护国内送柜报关，国外清关提柜独立返回 `platform:firstleg:terminal-drayage:list`、`platform:firstleg:terminal-drayage:document:edit`、`platform:firstleg:terminal-drayage:fleet:edit`、`platform:firstleg:terminal-drayage:pickup-appointment:edit`、`platform:firstleg:terminal-drayage:empty-return:confirm`，不以 `container:list/edit` 兼容放行国外操作。派送三类资料管理使用独立写权限 `platform:overseas-warehouse:delivery:documents`；读取和下载仍使用 `platform:overseas-warehouse:delivery:list`。列表权限包含详情和只读辅助接口，写操作独立授权。
+      description: 返回当前有效平台成员权限编码；只要求有效 PLATFORM JWT，不依赖 `platform:role:list`。入库单扣货与解除扣货返回独立写权限 `platform:firstleg:inbound:hold`，不会由 `platform:firstleg:inbound:list` 查看权限自动获得。资金账户充值审核与手工调账分别返回 `platform:finance:recharge:review`、`platform:finance:customer-account:adjust`，并与 `platform:finance:customer-account:list` 只读权限分离。海外仓返回 `platform:overseas-warehouse:dispatch:list`、`platform:overseas-warehouse:dispatch:create`、`platform:overseas-warehouse:dispatch:loading-complete`、`platform:overseas-warehouse:dispatch:depart`、`platform:overseas-warehouse:dispatch:edit`、`platform:overseas-warehouse:dispatch:cancel`、`platform:overseas-warehouse:dispatch:transfer-delivery`、`platform:overseas-warehouse:outbound:list`、`platform:overseas-warehouse:outbound:create`、`platform:overseas-warehouse:outbound:cancel`、`platform:overseas-warehouse:delivery:list`、`platform:overseas-warehouse:delivery:return`、`platform:overseas-warehouse:delivery:status`、`platform:overseas-warehouse:delivery:documents`、`platform:overseas-warehouse:exception-order:list`、`platform:overseas-warehouse:exception-order:create`、`platform:overseas-warehouse:exception-order:process`、`platform:overseas-warehouse:customer-visit:list`、`platform:overseas-warehouse:customer-visit:edit`；海外 PDA 盘点、移库、换标和现场查询统一返回 `lastleg:pda:operate`，且仅限 `OVERSEAS_WAREHOUSE_PDA_OPERATOR`。货柜双工作台以 `platform:firstleg:container:list/create/edit` 维护国内送柜报关，国外清关提柜独立返回 `platform:firstleg:terminal-drayage:list`、`platform:firstleg:terminal-drayage:document:edit`、`platform:firstleg:terminal-drayage:fleet:edit`、`platform:firstleg:terminal-drayage:pickup-appointment:edit`、`platform:firstleg:terminal-drayage:empty-return:confirm`，不以 `container:list/edit` 兼容放行国外操作。派送三类资料管理使用独立写权限 `platform:overseas-warehouse:delivery:documents`；读取和下载仍使用 `platform:overseas-warehouse:delivery:list`。列表权限包含详情和只读辅助接口，写操作独立授权。
       responses:
         '200':
           description: 当前平台成员权限查询成功
@@ -364,7 +364,7 @@ paths:
     get:
       tags: [IAM Resources / IAM 资源]
       summary: 查询当前用户有效权限
-      description: 返回当前有效客户成员权限编码。资金账户和流水只读返回 `merchant:finance:account:view`，提交充值申请返回 `merchant:finance:recharge:create`，两者独立授权。海外采购、本土卡、本土散板的列表入口分别返回 `merchant:cross-border:procurement:list`、`merchant:cross-border:domestic-trucking:list`、`merchant:cross-border:pallet-shipping:list`，创建和编辑另行授权；海外仓入库返回 `merchant:warehouse:inbound:list`，尾程订单、换标、转运、废弃、退货预报和退货库存均返回各自 `merchant:overseas-warehouse:*` 权限。客户派送返回 `merchant:warehouse:delivery:list` 和 `merchant:warehouse:delivery:create`。列表权限包含详情只读，创建、文件、确认、取消和转换操作独立授权。
+      description: 返回当前有效客户成员权限编码。资金账户和流水只读返回 `merchant:finance:account:view`，提交充值申请返回 `merchant:finance:recharge:create`，两者独立授权。海外采购、本土卡、本土散板的列表入口分别返回 `merchant:cross-border:procurement:list`、`merchant:cross-border:domestic-trucking:list`、`merchant:cross-border:pallet-shipping:list`，创建和编辑另行授权；海外仓入库返回 `merchant:warehouse:inbound:list`，尾程订单、换标、转运、废弃、退货预报和退货库存均返回各自 `merchant:overseas-warehouse:*` 权限。客户派送仅返回 `merchant:warehouse:delivery:list`，整车派送由平台统一安排。列表权限包含详情只读，创建、文件、确认、取消和转换操作独立授权。
       responses:
         '200':
           description: 当前商户成员权限查询成功

iam/src/test/java/com/baiyue/iam/controller/IamOpenApiContractTest.java

@@ -10,6 +10,7 @@ import java.util.Map;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class IamOpenApiContractTest {
+    /** 核对当前授权接口公开说明，整车写权限独立且客户派送只读。 */
     @Test
     void shouldHandleCase01() throws IOException {
         String document;
@@ -21,6 +22,9 @@ class IamOpenApiContractTest {
         assertThat(document).contains("/api/platform/v1/iam/authorization/permissions:")
                 .contains("/api/merchant/v1/iam/authorization/permissions:")
                 .contains("platform:overseas-warehouse:dispatch:list")
+                .contains("platform:overseas-warehouse:dispatch:create")
+                .contains("platform:overseas-warehouse:dispatch:loading-complete")
+                .contains("platform:overseas-warehouse:dispatch:depart")
                 .contains("platform:overseas-warehouse:dispatch:edit")
                 .contains("platform:overseas-warehouse:dispatch:cancel")
                 .contains("platform:overseas-warehouse:dispatch:transfer-delivery")
@@ -45,7 +49,7 @@ class IamOpenApiContractTest {
                 .contains("platform:firstleg:terminal-drayage:empty-return:confirm")
                 .contains("不以 `container:list/edit` 兼容放行国外操作")
                 .contains("merchant:warehouse:delivery:list")
-                .contains("merchant:warehouse:delivery:create")
+                .doesNotContain("merchant:warehouse:delivery:create")
                 .contains("merchant:cross-border:procurement:list")
                 .contains("merchant:cross-border:domestic-trucking:list")
                 .contains("merchant:cross-border:pallet-shipping:list")

iam/src/test/java/com/baiyue/iam/repository/OverseasPhase4PermissionSqlContractTest.java

@@ -39,8 +39,7 @@ class OverseasPhase4PermissionSqlContractTest {
 
     private static final Pattern CANONICAL = Pattern.compile("platform:overseas-[a-z0-9:-]+");
     private static final Set<String> CUSTOM_ADMIN_PERMISSIONS = Set.of(
-        "platform:overseas-warehouse:inbound-order:fba-appointment",
+        "platform:overseas-warehouse:inbound-order:fba-appointment");
-        "platform:overseas-warehouse:inbound-order:smart-dispatch");
     private static final List<String> REQUIRED = List.of(
         "platform:overseas-warehouse:last-mile-order:list",
         "platform:overseas-warehouse:discard:list",
@@ -48,7 +47,6 @@ class OverseasPhase4PermissionSqlContractTest {
         "platform:overseas-warehouse:warehouse-transfer:approve",
         "platform:overseas-warehouse:inbound-order:list",
         "platform:overseas-warehouse:inbound-order:fba-appointment",
-        "platform:overseas-warehouse:inbound-order:smart-dispatch",
         "platform:overseas-warehouse:relabel-order:status",
         "platform:overseas-warehouse:pallet:list",
         "platform:overseas-warehouse:inventory:adjust",
@@ -77,7 +75,7 @@ class OverseasPhase4PermissionSqlContractTest {
         assertThat(sql).contains(REQUIRED.toArray(String[]::new));
         assertThat(sql).contains("'lastleg:pda:operate'");
         assertPdaPickerGrant(sql);
-        assertThat(catalog).hasSize(71).noneMatch(code -> code.endsWith(":view"));
+        assertThat(catalog).hasSize(70).noneMatch(code -> code.endsWith(":view"));
         assertThat(sql).contains(
             "(5107003,0,'PLATFORM','BUTTON',5107000,'platform:overseas-warehouse:warehouse-transfer:approve'");
         assertThat(sql).contains("CALL assert_warehouse_transfer_approval_permission()",
@@ -85,7 +83,8 @@ class OverseasPhase4PermissionSqlContractTest {
         assertThat(sql).doesNotContain(
             "'platform:overseas-warehouse:warehouse-transfer:list','仓储转运审核'");
         assertThat(sql).contains("permission_code LIKE 'platform:lastleg:%'", "status='INACTIVE'", "deleted=1");
-        assertThat(sql).doesNotContain(":carton:", ":product:");
+        assertThat(sql).doesNotContain(":carton:", ":product:",
+            "platform:overseas-warehouse:inbound-order:smart-dispatch");
         assertThat(catalog).contains("platform:overseas-warehouse:delivery:list");
         assertCustomAdminGrant(sql);
         assertCustomAdminNavigationGrant(sql);

iam/src/test/java/com/baiyue/iam/repository/Phase5DeliveryPermissionSqlContractTest.java

@@ -16,6 +16,9 @@ class Phase5DeliveryPermissionSqlContractTest {
     private static final Pattern CODE = Pattern.compile("(?:platform:overseas-warehouse|merchant:warehouse):[a-z0-9:-]+");
     private static final Set<String> REQUIRED = Set.of(
         "platform:overseas-warehouse:dispatch:list",
+        "platform:overseas-warehouse:dispatch:create",
+        "platform:overseas-warehouse:dispatch:loading-complete",
+        "platform:overseas-warehouse:dispatch:depart",
         "platform:overseas-warehouse:dispatch:edit",
         "platform:overseas-warehouse:dispatch:cancel",
         "platform:overseas-warehouse:dispatch:transfer-delivery",
@@ -31,15 +34,16 @@ class Phase5DeliveryPermissionSqlContractTest {
         "platform:overseas-warehouse:delivery:documents",
         "platform:overseas-warehouse:customer-visit:list",
         "platform:overseas-warehouse:customer-visit:edit",
-        "merchant:warehouse:delivery:list",
+        "merchant:warehouse:delivery:list");
-        "merchant:warehouse:delivery:create");
 
+    /** 核对整车权限目录只包含当前正式编码。 */
     @Test
     void definesOnlyTheFrozenPhase5DeliveryCatalogWithoutAliases() throws Exception {
         String sql = sql();
 
         assertThat(codes(sql)).containsExactlyInAnyOrderElementsOf(REQUIRED);
         assertThat(codes(sql)).noneMatch(code -> code.endsWith(":view"));
+        assertThat(sql).doesNotContain("merchant:warehouse:delivery:create");
         assertThat(sql).contains(
             "guard_phase5_delivery_permission_ids",
             "权限ID或编码冲突",
@@ -47,27 +51,32 @@ class Phase5DeliveryPermissionSqlContractTest {
             "列表权限同时覆盖列表和详情只读");
     }
 
+    /** 核对菜单、动作方法及独立装车发车权限。 */
     @Test
     void keepsMenuRoutesAndHttpMethodsAlignedWithTheFrozenAdminAndClientContracts() throws Exception {
         String sql = sql();
 
         assertThat(sql).contains(
             "'platform:overseas-warehouse:dispatch:list','海外排车单','/overseas-warehouse/dispatches','GET'",
-            "'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'DELETE'",
+            "'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'POST'",
             "'platform:overseas-warehouse:exception-order:list','海外异常订单','/overseas-warehouse/exception-orders','GET'",
             "'platform:overseas-warehouse:exception-order:create','新增海外异常订单',NULL,'POST'",
             "'platform:overseas-warehouse:exception-order:process','处理海外异常订单',NULL,'POST'",
             "'platform:overseas-warehouse:delivery:return','派送单标记退货',NULL,'POST'",
             "'platform:overseas-warehouse:delivery:status','编辑派送单状态',NULL,'PUT'",
+            "(5107065,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:create'",
+            "(5107066,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:loading-complete'",
+            "(5107067,0,'PLATFORM','BUTTON',5107064,'platform:overseas-warehouse:dispatch:depart'",
             "(5107094,0,'PLATFORM','BUTTON',5107092,'platform:overseas-warehouse:delivery:documents','管理派送资料',NULL,'POST'",
             "'platform:overseas-warehouse:customer-visit:list','客户回访','/overseas-warehouse/customer-visits','GET'",
             "'platform:overseas-warehouse:customer-visit:edit','保存客户回访',NULL,'PUT'",
             "'merchant:warehouse:delivery:list','海外仓派送单','/orders/delivery','GET'");
         assertThat(sql).doesNotContain(
-            "'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'POST'",
+            "'platform:overseas-warehouse:dispatch:cancel','取消海外排车',NULL,'DELETE'",
             "'merchant:warehouse:delivery:list','海外仓派送单','/overseas-warehouse/delivery-orders'");
     }
 
+    /** 核对后台操作岗位、理货只读岗位与PDA之间的最小授权边界。 */
     @Test
     void grantsAdministratorsAndWarehouseRolesByTheFrozenMinimumMatrix() throws Exception {
         String sql = sql();
@@ -76,6 +85,9 @@ class Phase5DeliveryPermissionSqlContractTest {
             "UPPER(role.role_code) IN ('PLATFORM_ADMIN','PLATFORM_CUSTOM_ADMIN')",
             "tmp_phase5_delivery_role_permission",
             "('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:list')",
+            "('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:create')",
+            "('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:loading-complete')",
+            "('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:depart')",
             "('WAREHOUSE_OPERATOR','platform:overseas-warehouse:dispatch:edit')",
             "('WAREHOUSE_OPERATOR','platform:overseas-warehouse:outbound:create')",
             "('WAREHOUSE_OPERATOR','platform:overseas-warehouse:exception-order:create')",
@@ -92,6 +104,9 @@ class Phase5DeliveryPermissionSqlContractTest {
             "role.role_code IN ('OVERSEAS_WAREHOUSE_PDA_OPERATOR','CN_FIRSTLEG_PDA_OPERATOR')",
             "PDA岗位错误获得后台权限");
         assertThat(sql).doesNotContain(
+            "('WAREHOUSE_TALLY','platform:overseas-warehouse:dispatch:create')",
+            "('WAREHOUSE_TALLY','platform:overseas-warehouse:dispatch:loading-complete')",
+            "('WAREHOUSE_TALLY','platform:overseas-warehouse:dispatch:depart')",
             "('WAREHOUSE_TALLY','platform:overseas-warehouse:dispatch:edit')",
             "('WAREHOUSE_TALLY','platform:overseas-warehouse:outbound:create')",
             "('WAREHOUSE_TALLY','platform:overseas-warehouse:exception-order:create')",
@@ -104,6 +119,7 @@ class Phase5DeliveryPermissionSqlContractTest {
             "('CN_FIRSTLEG_PDA_OPERATOR','platform:overseas-warehouse:");
     }
 
+    /** 核对临时角色矩阵一次读取及完整性判断。 */
     @Test
     void validatesTheWarehouseRoleMatrixWithOneTemporaryTableReadPerStatement() throws Exception {
         String sql = sql();
@@ -114,7 +130,7 @@ class Phase5DeliveryPermissionSqlContractTest {
             "SELECT COALESCE(SUM(role_code='WAREHOUSE_OPERATOR'),0)",
             "COALESCE(SUM(role_code='WAREHOUSE_TALLY'),0)",
             "INTO v_warehouse_operator_permission_count, v_warehouse_tally_permission_count",
-            "IF v_warehouse_operator_permission_count <> 16",
+            "IF v_warehouse_operator_permission_count <> 19",
             "OR v_warehouse_tally_permission_count <> 5 THEN",
             "IF EXISTS (SELECT 1 FROM iam_role role",
             "AND UPPER(role.role_code)='PLATFORM_CUSTOM_ADMIN'",
@@ -126,10 +142,11 @@ class Phase5DeliveryPermissionSqlContractTest {
             "OR (SELECT COUNT(*) FROM tmp_phase5_delivery_role_permission");
     }
 
+    /** 客户默认管理员只获得本客户派送读取权限。 */
     @Test
     void grantsOnlyTheDefaultCustomerAdministratorAutomatically() throws Exception {
         String sql = sql();
-        int marker = sql.indexOf("-- 客户默认管理员获得派送列表/详情只读及独立创建");
+        int marker = sql.indexOf("-- 客户默认管理员只获得派送列表和详情读取");
         int assertion = sql.indexOf("DROP PROCEDURE IF EXISTS assert_phase5_delivery_permissions", marker);
         assertThat(marker).isGreaterThanOrEqualTo(0);
         assertThat(assertion).isGreaterThan(marker);
@@ -137,11 +154,11 @@ class Phase5DeliveryPermissionSqlContractTest {
         String grant = sql.substring(marker, assertion);
         assertThat(grant).contains(
             "role.role_code='MERCHANT_OWNER'",
-            "merchant:warehouse:delivery:list",
+            "merchant:warehouse:delivery:list");
-            "merchant:warehouse:delivery:create");
+        assertThat(grant).doesNotContain("MERCHANT_OPERATOR", "ORDER_VIEWER", "role.role_code IN", "merchant:warehouse:delivery:create");
-        assertThat(grant).doesNotContain("MERCHANT_OPERATOR", "ORDER_VIEWER", "role.role_code IN");
     }
 
+    /** 国内空库基线必须同步当前权限与默认角色关联。 */
     @Test
     void domesticCleanInitializationContainsTheCompletePermissionCatalog() throws Exception {
         String unifiedSql = repositoryFile("deploy/sql/头程数据库统一增量-MySQL8.sql");
@@ -151,7 +168,10 @@ class Phase5DeliveryPermissionSqlContractTest {
             .contains("(4000004,5107064,0,CURRENT_TIMESTAMP(3))")
             .contains("(4000004,5107094,0,CURRENT_TIMESTAMP(3))")
             .contains("(4000100,5306000,0,CURRENT_TIMESTAMP(3))")
-            .contains("(4000100,5306001,0,CURRENT_TIMESTAMP(3))")
+            .contains("(4000004,5107065,0,CURRENT_TIMESTAMP(3))")
+            .contains("(4000004,5107066,0,CURRENT_TIMESTAMP(3))")
+            .contains("(4000004,5107067,0,CURRENT_TIMESTAMP(3))")
+            .doesNotContain("merchant:warehouse:delivery:create", "(4000100,5306001,0,CURRENT_TIMESTAMP(3))")
             .doesNotContain("guard_phase5_delivery_permission_ids", "tmp_phase5_delivery_role_permission");
     }
 

iam/src/test/java/com/baiyue/iam/repository/Phase5DeliveryPermissionSqlExecutionTest.java

@@ -20,6 +20,7 @@ class Phase5DeliveryPermissionSqlExecutionTest {
     private static final Pattern PLATFORM_CODE =
         Pattern.compile("platform:overseas-warehouse:[a-z0-9:-]+");
 
+    /** 没有自定义管理员时不产生虚假的缺权错误。 */
     @Test
     void noCustomAdministratorDoesNotCreateAnAssertionViolation() throws Exception {
         try (Connection connection = database()) {
@@ -29,6 +30,7 @@ class Phase5DeliveryPermissionSqlExecutionTest {
         }
     }
 
+    /** 按当前完整目录补齐管理员授权，重复执行不增加关联。 */
     @Test
     void onePartiallyGrantedCustomAdministratorIsCompletedIdempotently() throws Exception {
         try (Connection connection = database()) {
@@ -37,50 +39,53 @@ class Phase5DeliveryPermissionSqlExecutionTest {
             assertThat(customAdministratorViolations(connection)).isEqualTo(1);
 
             executeGrant(connection);
-            assertThat(grantCount(connection, 11L)).isEqualTo(16);
+            assertThat(grantCount(connection, 11L)).isEqualTo(19);
             assertThat(customAdministratorViolations(connection)).isZero();
 
             executeGrant(connection);
-            assertThat(grantCount(connection, 11L)).isEqualTo(16);
+            assertThat(grantCount(connection, 11L)).isEqualTo(19);
-            assertThat(totalGrantCount(connection)).isEqualTo(16);
+            assertThat(totalGrantCount(connection)).isEqualTo(19);
         }
     }
 
+    /** 分别核对每个管理员，缺少任一权限不能被其他角色抵消。 */
     @Test
     void multipleCustomAdministratorsExposeTheSingleIncompleteRole() throws Exception {
         try (Connection connection = database()) {
             insertRole(connection, 21L, "PLATFORM_CUSTOM_ADMIN");
             insertRole(connection, 22L, "Platform_Custom_Admin");
-            grantFirstPermissions(connection, 21L, 16);
+            grantFirstPermissions(connection, 21L, 19);
-            grantFirstPermissions(connection, 22L, 15);
+            grantFirstPermissions(connection, 22L, 18);
 
             assertThat(customAdministratorViolations(connection)).isEqualTo(1);
 
             executeGrant(connection);
-            assertThat(grantCount(connection, 21L)).isEqualTo(16);
+            assertThat(grantCount(connection, 21L)).isEqualTo(19);
-            assertThat(grantCount(connection, 22L)).isEqualTo(16);
+            assertThat(grantCount(connection, 22L)).isEqualTo(19);
             assertThat(customAdministratorViolations(connection)).isZero();
         }
     }
 
+    /** 完整管理员重复授权保持各自权限集合稳定。 */
     @Test
     void multipleCompleteCustomAdministratorsRemainCompleteAfterReplay() throws Exception {
         try (Connection connection = database()) {
             insertRole(connection, 31L, "PLATFORM_CUSTOM_ADMIN");
             insertRole(connection, 32L, "platform_custom_admin");
-            grantFirstPermissions(connection, 31L, 16);
+            grantFirstPermissions(connection, 31L, 19);
-            grantFirstPermissions(connection, 32L, 16);
+            grantFirstPermissions(connection, 32L, 19);
 
             assertThat(customAdministratorViolations(connection)).isZero();
             executeGrant(connection);
             executeGrant(connection);
 
-            assertThat(grantCount(connection, 31L)).isEqualTo(16);
+            assertThat(grantCount(connection, 31L)).isEqualTo(19);
-            assertThat(grantCount(connection, 32L)).isEqualTo(16);
+            assertThat(grantCount(connection, 32L)).isEqualTo(19);
-            assertThat(totalGrantCount(connection)).isEqualTo(32);
+            assertThat(totalGrantCount(connection)).isEqualTo(38);
         }
     }
 
+    /** 管理员授权不得扩散到理货只读岗位或停用账号。 */
     @Test
     void administratorGrantDoesNotEscalateAReadOnlyRoleOrDisabledAdministrator() throws Exception {
         try (Connection connection = database()) {
@@ -99,7 +104,7 @@ class Phase5DeliveryPermissionSqlExecutionTest {
             executeGrant(connection);
             executeGrant(connection);
 
-            assertThat(grantCount(connection, 41L)).isEqualTo(16);
+            assertThat(grantCount(connection, 41L)).isEqualTo(19);
             assertThat(grantCount(connection, 42L)).isEqualTo(1);
             assertThat(grantCount(connection, 43L)).isZero();
             try (Statement statement = connection.createStatement();
@@ -206,6 +211,7 @@ class Phase5DeliveryPermissionSqlExecutionTest {
         }
     }
 
+    /** 逐角色核对当前后台权限全集，避免跨角色合并计数。 */
     private static int customAdministratorViolations(Connection connection) throws Exception {
         String placeholders = String.join(",", platformPermissions().stream().map(code -> "?").toList());
         String sql = """
@@ -216,7 +222,7 @@ class Phase5DeliveryPermissionSqlExecutionTest {
                AND (SELECT COUNT(*) FROM iam_role_permission grant_row
                     JOIN iam_permission permission ON permission.id=grant_row.permission_id
                     WHERE grant_row.role_id=role.id AND grant_row.tenant_id=role.tenant_id
-                      AND permission.permission_code IN (%s)) <> 16
+                      AND permission.permission_code IN (%s)) <> 19
             """.formatted(placeholders);
         try (PreparedStatement query = connection.prepareStatement(sql)) {
             int index = 1;
@@ -239,11 +245,12 @@ class Phase5DeliveryPermissionSqlExecutionTest {
         return sql.substring(start, end);
     }
 
+    /** 从实际管理员授予语句提取当前后台权限全集。 */
     private static Set<String> platformPermissions() throws Exception {
         LinkedHashSet<String> codes = new LinkedHashSet<>();
         String grant = administratorGrantSql();
         PLATFORM_CODE.matcher(grant).results().map(result -> result.group()).forEach(codes::add);
-        assertThat(codes).hasSize(16);
+        assertThat(codes).hasSize(19);
         return codes;
     }
 

iam/src/test/java/com/baiyue/iam/service/AuthorizationSnapshotServiceTest.java

@@ -64,18 +64,16 @@ class AuthorizationSnapshotServiceTest {
         verify(mapper).findSnapshot(42L, 0L, 9L, "PLATFORM");
     }
 
+    /** 按当前有效角色返回客户派送读取权限。 */
     @Test
-    void exposesPhase5DeliveryPermissionsFromCurrentRoleAssignments() {
+    void exposesCustomerDeliveryReadPermissionFromCurrentRoleAssignments() {
         when(mapper.findSnapshot(42L, 7L, 9L, "MERCHANT")).thenReturn(rows(List.of("MERCHANT_OWNER"), List.of(
-                "merchant:warehouse:delivery:list",
+                "merchant:warehouse:delivery:list")));
-                "merchant:warehouse:delivery:create")));
 
         var result = service.currentPermissions(new AuthenticatedUser(42L, 7L, 7L, 9L,
                 "owner", "MERCHANT", "MERCHANT", java.util.Set.of()), "MERCHANT");
 
-        assertThat(result).containsExactlyInAnyOrder(
+        assertThat(result).containsExactly("merchant:warehouse:delivery:list");
-                "merchant:warehouse:delivery:create",
-                "merchant:warehouse:delivery:list");
     }
 
     @Test

integration-service/AGENTS.md

@@ -1,5 +1,10 @@
 # Integration Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责与边界
 
 - 负责百度 OCR、Amazon Logistics/SP-API、海外仓业务船司/船舶轨迹查询等第三方适配和能力开关；不保存业务主数据。

lastleg-service/AGENTS.md

@@ -1,5 +1,10 @@
 # Lastleg Service 模块指引
 
+## 数据库访问与中文注释约束
+
+- 强制遵守根 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 `Controller → Service → Repository → Mapper`，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
+- 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。
+
 ## 职责与边界
 
 - Mapper 必须标注 `@Mapper`，仅由 `BaiyueLastlegApplication.java` 对 `com.baiyue.lastleg` 根包按 `annotationClass = Mapper.class` 扫描；禁止局部 `*MapperConfiguration` 和包白名单。验证：`scripts/mapper-scan-contract.mjs`、`MapperRegistrationArchitectureTest.java`。
@@ -11,7 +16,7 @@
 
 业务包相对 `src/main/java/com/baiyue/lastleg/`；`src/`、`docs/`、`scripts/`、`../` 相对服务目录。裸类名在指定包内检索。
 
-拼车接货与车次准备：`fleet/trip/`、`fleet/business/`；合同`fleet-preparation-v1.yaml`，流程见 `../../docs/海外仓业务/内部拼车需求池首版开发契约.md`。
+拼车余位发布查 `fleet/trip/FleetCapacityOfferService.java`；整车建单与准备查 `dispatch/controller/DispatchAggregateController.java` 和 `dispatch/service/DispatchAggregateService.java`，本土业务接线查 `fleet/business/`；既有外接登记衔接合同为 `fleet-preparation-v1.yaml`，排车流程按 `../../docs/海外仓业务/排车列表统一作业改造契约.md`。
 
 事件重试：`controller/EventOperationsController.java`，内部 `/internal/lastleg/event-operations/{entryId}` 查询、`/retry` 写入；仅卸柜、派送、暂扣、资金及费用事件，以 `EVENT_OPERATIONS_TOKEN` 保护。原事件不可改，DEAD→PENDING 与 `event_delivery_retry_audit` 同事务；脚本 `scripts/event-outbox-operations.mjs`。
 
@@ -50,8 +55,8 @@
 | 贴标申请、箱唛/SKU/组合换标与 PDA 完工 | `relabel/` |
 | PDA 仓内通用扫码与操作历史 | `pda/warehouse/controller/PdaWarehouseController.java` |
 | 船节点接收与海外 PDA 可收货门禁 | `shipping/service/ContainerShippingNodeConsumer.java` |
-| 平台排车列表/详情与智能预排 | `dispatch/controller/DispatchQueryController.java` |
+| 平台排车查询、整车四块详情、审核与实载 | `dispatch/controller/DispatchQueryController.java`、`DispatchAggregateController.java`；公开契约`dispatch/port/`，业务规则见`../../docs/海外仓业务/排车列表统一作业改造契约.md` |
-| 排车编辑、PDA 出库、派送与交接 | `dispatch/controller/DispatchController.java` |
+| 草稿、双端装发与派送安排 | `dispatch/controller/SmartDispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`；平台维护`DispatchController.java`，派送组合`delivery/controller/DeliveryTransferController.java` |
 | 仓储资源调用 | `inboundplan/pda/gateway/WarehouseResourceGateway.java` |
 | 仓储转运、历史订单/入仓绑定、可选换标联动 | `transfer/controller/WarehouseTransferController.java` |
 | 一件代发接收、SKU/箱唛库存 | `dropship/controller/DropshipOrderController.java` |
@@ -68,10 +73,10 @@
 | 司机档案、证照上传/审核、资格预览与历史 | `fleet/driver/PlatformDriverController.java`、`DriverService.java`；OpenAPI `fleet-drivers-v1.yaml`，表 `ll_fleet_driver` / `ll_fleet_driver_history`；资格规则 `fleet/domain/DriverQualificationPolicy.java` |
 | 车辆运维：保养、加油、维修、故障、救援、异常 | `fleet/maintenance/PlatformVehicleCareController.java`、`VehicleCareService.java`；合同`fleet-vehicle-records-v1.yaml`。按车/类型隔离，单位/币种明确，处理不等付款；创建/附件幂等，更正留版本历史，不改主档里程/状态。维修救援经`financefee/fleet/VehicleCareFinanceAdapter`入公司成本，Finance为付款权威，未关联UNLINKED，不生成客户应收 |
 | 车次计划、车/司机分配与占用、客户排车关联 | `fleet/trip/PlatformFleetTripController.java`、`FleetTripService.java`；OpenAPI `fleet-trips-v1.yaml`；`FleetDispatchGateway` 由 `dispatch/fleet/DispatchFleetAdapter.java` 实现，`FleetDispatchBindingGuard` 控制子单独立修改/发车；车辆通过 `VehicleRepository` 和 `VehicleAssignmentGuard` 协作，fleet不直读车辆持久化适配器 |
-| 调度与理货审核 | `FleetTripService.reviewDispatch`、`FleetTripExecutionService.reviewLoading`；每张客户排车单先调度通过，整车确认实载后理货通过。`FleetDispatchBindingGuard.requirePickingApproved` 在新拣货/完成前核对当前单审核；已成功操作的同键重放保留原结果 |
+| 整车调度与理货审核 | `dispatch/controller/DispatchAggregateController.java` → `dispatch/service/DispatchAggregateService.java` 的提交及两级审核；同一排车先调度审核、再理货审核，通过后才允许真实扫码。资源、货物或路线关键变更使原依据失效；零扫码显式退回后重新审核，不复用旧客户子单审核状态 |
 | 外接询价、确认占位及取消 | `fleet/trip/PlatformFleetBookingController.java`、`FleetBookingService.java`、`FleetBookingReservations.java`；客户从`fleet/customer/`读取IAM有效主档与资格，询价不占位，确认后与自有货计划共同校验逐段容量。约定金额不代表应收/实收，`FleetBookingIncomingGateway`由`transfer/fleet/FleetIncomingAdapter`实现来货登记/实收确认，排车关联通过`FleetDispatchGateway.sourceCargo`核对实收来源 |
 | 拣货前计划容量与逐段余位 | `FleetTripExecutionService.capacityPlan/confirmCapacityPlan`、`/fleet/trips/{tripNo}/capacity-plan`；保存自有货的计划值，不检查拣货完成、不推进审核或扣库存；`planValid`校验当前货物hash，不把计划值当实测值，资源/计划/关联变更后须重新核对 |
-| 实物装载、逐段容量与整车PDA发车 | `fleet/trip/FleetTripExecutionService.java`、`FleetExecutionModels.java`；平台 `/fleet/trips/{tripNo}/loading`，PDA沿用 `/dispatches/{dispatchNo}/depart` 但提交车次版本并返回整车结果；`DispatchPdaWorkflowService.depart` 为车次事务内子操作，不独立对外调用 |
+| 实物装载、逐段容量与双端整车发车 | `dispatch/pda/controller/DispatchPdaController.java` → `dispatch/service/DispatchAggregateService.java`（装车）、`DispatchDepartureService.java`（发车）；平台与PDA均使用本端`dispatches/{dispatchNo}/loading-complete`及`/depart`，公共DTO在`dispatch/port/`，已有单写入唯一`recordVersion`。装车前须真实PDA拣货核平，发车前须全车派送安排完整；装车及发车不重复执行扫码已完成的库存SHIP，Fleet容量和资源资格继续由真实提供者复核 |
 | 车次货物结案、车辆和司机分别释放 | `fleet/trip/FleetTripCompletionService.java`、`FleetCompletionModels.java`；平台 `/fleet/trips/{tripNo}/completion`、`/complete`、`/resources/release`，独立complete/release权限。结案核对所有派送终态与实发数量；实际任务结束时间/地点及车辆结束状态单独记录，不以结案或收款自动释放资源 |
 | 跨服务 HTTP 客户端装配 | `config/LastlegRestClientFactory.java` |
 | 数据库基线、表索引与中文注释契约 | `src/main/resources/db/lastleg.sql` |
@@ -90,12 +95,12 @@
 - 海外仓全流程连续覆盖尾程订单、入仓计划/PDA 入仓、换标、产品与箱唛快照、库存、转运、废弃、采购、本土卡车、本土散板、排车查询/智能预排、排车编辑/取消/发车、PDA 拣货与出库、一件代发、转派送、客户派送单、异常退回和客户回访。
 - 服务端正式入口包括 `dispatch/controller/DispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`、`delivery/controller/DeliveryTransferController.java`、`delivery/controller/OutboundPdaController.java`、`delivery/controller/MerchantDeliveryController.java`、`exceptionorder/` 与 `customervisit/`；设备页面是否可用以海外 PDA 正式路由和能力开关为准，未由 PDA 承载的操作由 Admin/Client 完成。
 - 平台一件代发出库候选由 `/outbound-orders/one-click-dropship/candidates` 统一返回已完成入库且仍有可用箱唛、SKU 汇总和库存仓位绑定的托盘明细；查询不强制先传 `customerId`，未传时跨客户展示供页面分页筛选，创建时必须从所选候选解析为唯一客户和唯一海外仓，禁止一张出库单跨客户或跨仓。创建后出库单按 `WAIT_PICK → PICKING → PICKED → OUTBOUNDED` 推进；海外 PDA 扫描托盘码时通过整托命令原子拣取该托盘在当前任务内全部剩余箱件和 SKU，任一库存明细失败须整托回滚，逐箱拣货入口继续保留。
-- 排车转派送允许在 `PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART` 阶段幂等生成一张 `WAIT_OUTBOUND` 出库单，并按目的FBA仓生成多张派送单，但必须早于发车；BOL和签收资料均绑定拆分后的单仓派送单，派送费用仍只发布一次。PDA 排车详情由 `DispatchPdaWorkflowService` 返回 `canDepart`、`departBlockReason`，只有车辆信息完整、拣货任务完成且箱数核平、排车为 `READY_TO_DEPART`、关联出库单仍为 `WAIT_OUTBOUND` 时才允许发车，PDA 不得自行推导该门禁。
+- 排车主流程以工作区 `docs/海外仓业务/排车列表统一作业改造契约.md` 为正式入口：一张排车单代表一趟车，装车完成后、实际发车前由后台安排派送，按客户与目的仓拆分派送单。`DispatchPdaWorkflowService` 按公开 `status`、`stage`、`recordVersion` 和 `actions` 返回作业事实与资格，Admin/PDA 共用服务端规则；BOL 与签收资料归拆分后的派送单，费用按其来源去重，不以旧转派送阶段或前端推算代替资格校验。
-- 共享车次关联取排车单自身客户与起运仓；排车有效关联唯一，多客户不合并库存归属。`FleetDispatchBindingGuard` 在子单行锁内阻止独立编辑/移托/取消及绕过车次协调单独发车；转派送的新建请求不能覆盖车次车辆司机，已成功转换的重放继续返回既有单据。PDA详情同步返回车次统一发车阻断原因；关联与改派通过 `FleetDispatchGateway` 同事务同步尚未执行的派送快照。已拣货禁止直接解除关联或变更路线；发车前可统一换车/司机或保持路线调整时间，保留拣货事实与到达时间，重验司机任务覆盖及替换车辆对已确认装载的容量，成功后调度审核、理货审核及原装载确认失效；仅修改备注保留审核与装载。已出库/发车不允许此类修改。
+- 排车主单允许同一起运仓的跨客户货物同车，每条来源保留客户、库存与费用归属；不再要求用户先建独立车次再关联多张客户排车。Fleet 的资源、司机证照、容量、历史与附加能力继续沿 `fleet/trip/` 定位；计划或资源变化对审核、实载确认的影响按正式契约及服务端结果核对，已拣货事实不能因改派或取消被直接抹除，实际发车后不得伪造资源释放。
-- 实物装载按仓库托盘ID去重计量，客户货量与物理占位分别保存；重量/体积为明确确认的实际值，不读取计费材积重回填。路线卸货站的 `destinationKey` 必须匹配原货物目的地，同实托不同目的地先拆托。装载确认保存来源hash、版本、操作人和历史；改计划/改派/关联变化使确认失效。整车发车在同一Lastleg事务中复核所有子单、车辆占用及司机证照，调用原子单出库命令后统一提交 `IN_TRANSIT` 和幂等结果；任一失败全车回滚，`DEPARTING`只在事务内部使用。PDA列表按车次复用发车门禁查询，再按当前客户排车单审核返回canPick/pickBlockReason；客户A通过不能代替客户B通过。重新确认装载或重新调度审核使理货审核待审，审核历史不删除；过期前30天提醒与阻断分别返回。
+- 实物装载按仓库托盘去重计量，客户货量与物理占位分别保存；重量/体积必须来自实际确认，不用计费材积重回填。装车前真实拣货须核平，后台不能补录拣货数量绕过；装车、安排派送和发车不重复执行已完成的库存扣减。来源、审核、实载与资源版本变化按正式契约重新校验，保留操作历史；双端使用同一版本与原请求键核对结果，任何失败均不得伪造完成事实。
 - 车次结案只消费派送事实：实签须signedAt/signedPackages，实退须原来源入账流水/RETURN_COMPLETED；实签加本趟实退等于原实发且余量为零。拒收、待退回、取消不算完成，时间取最后实际终态。结案不改客户状态/费用、不释放占用；车/司机分别记录实际结束时间地点，车辆状态与释放同事务。过期证照不阻止旧任务结束、不恢复新任务资格；原键重放不影响后续车次。
 - 已签收后另发起退货保留原运输的签收事实，后续退货不重开原车次、不被车次结案改写；未签收货物仍按实际退回完成核对。`DeliveryDocumentService.save` 首次保存签收资料触发完成时要求关联出库已OUTBOUNDED，未出库可以准备BOL/装车资料但不能提前完成派送。
-- 排车执行与 `delivery/` Controller 和其他尾程业务接口一同注册，不受功能开关控制。平台排车列表与详情仍由 `lastleg.dispatch-query-api.enabled=true` 独立启用；入库单智能排车候选、草稿锁定/解锁/释放和预排创建仍由 `lastleg.smart-dispatch-api.enabled=true` 独立启用。这些排车平台入口均不接收 `customerId`：排车列表跨客户分页，详情按全局排车单号定位后使用记录自身客户范围加载明细；智能排车候选未传计划 ID 时跨客户查询，传入时根据计划 ID 解析范围；托盘移入草稿时立即以操作人和随机草稿标识锁定，移除或关闭时释放，草稿锁超时失效；预排创建根据所选托盘 ID 在服务端解析并校验唯一客户范围，并将当前操作人的草稿锁原子转换为正式排车锁。
+- 排车执行与 `delivery/` Controller 一同注册；平台排车查询和智能预排入口分别沿 `lastleg.dispatch-query-api.enabled`、`lastleg.smart-dispatch-api.enabled` 配置定位，启用现状以配置和实际路由核对。平台查询按全局排车号及来源归属加载跨客户同车明细，客户接口保持本客户隔离；预排创建逐项校验同一起运仓及各来源客户，不能强制整张排车只含一个客户。草稿托盘锁仍按操作人与草稿标识持有，释放、失效及转正式锁由服务端原子处理。
 - 仓库 ID、类型、状态、地址和能力唯一权威归国内 `warehouse-service`；海外库位、实物托盘和资源锁归 `warehouse-overseas-service/` 且只引用同一国内 `warehouseId`。Lastleg PDA 通过 Warehouse Overseas 内部资源入口校验该国内共享收货仓，不得要求海外数据库重复建仓；浏览器 API 统一经 `gateway/`。
 
 - 外接预订以父车次行锁串行确认容量；DRAFT不占位，CONFIRMED占位，CANCELLED释放，创建/确认/取消保留请求键与内容摘要。报价与记录快照进入既有车次历史。重新核对自有货计划不得占用已确认外接容量，换小车须能容纳两者；同车只换司机不额外要求先重新核对容量。CONFIRMED和RECEIVED尚未绑定实际发运时阻止整车发车；通过真实来货实测、运费确认及来源核对后转为BOUND，解除未开工排车关联回RECEIVED。报价或登记来货不冒充库存/已出库；取消未执行预订仅释放承运容量，来货及已入库货物保留。

lastleg-service/docs/business-index.md

@@ -44,7 +44,7 @@
 | 派送完成回传 | `delivery/service/DeliveryCompletedOutboxService.java`；签收资料保存并自动完成时在业务事务内按关联 `sourceInboundId` 分别写 `OVERSEAS_DELIVERY_COMPLETED` Outbox，同车不同 FBA 派送单互不代完成；不保留人工完成入口 |
 | 入仓后 SKU 库存余额、库位和流水 | `inventory/`；平台只读查询与非出库库存命令分别从 `inventory/query/controller/InventoryQueryController.java`、`inventory/command/controller/InventoryCommandController.java` 进入 |
 | 海外PDA盘点、同仓整托移库、托盘组拆换绑与换标现场作业 | `pda/stocktake/`、`pda/move/`、`palletops/`、`relabel/pda/`；版本化契约 `src/main/resources/openapi/overseas-pda-operations-v1.yaml`；全部范围取自PDA Token，排车和出库使用独立 PDA Controller |
-| 贴标申请、箱唛/SKU/组合换标与 PDA 完工 | `relabel/`、`relabel/pda/`；一条 `ll_relabel_item` 对应一个客户填写的我方箱唛任务，`CARTON_LABEL`、`SKU_LABEL`、`CARTON_AND_SKU` 分别保存箱唛、SKU 或组合需求，SKU 子项 JSON 数量按件；涉及箱唛换标时整张申请只能有一个 FBA 目的仓，服务端拒绝明细目的仓不一致的请求。普通尾程入库没有箱唛到实物托盘的精确快照，历史入仓库存仓位只能作为冻结记账锚点和现场大概位置，禁止把该仓位解释为箱唛已绑定具体托盘。库存只按箱任务冻结一次。涉及箱唛换标时申请必须选择 `TRUCK/EXPRESS/TRUCK_PICKUP/EXPRESS_PICKUP`，两种快递方式可要求打印并上传面单；PDA 扫我方箱唛完成逐箱事实和照片，仓库复核后等待客户查看照片确认。对外换标状态只投影为 `PENDING_PROCESSING/COMPLETED`（待处理/换标完成），`PROCESSING`、`CUSTOMER_CONFIRM_PENDING`、`READY_FOR_OUTBOUND` 只属于内部作业节点且不得直接出现在业务列表；客户确认后仅卡车派送进入 `WAIT_PRE_DISPATCH`，快递派送和两种自提直接创建换标出库单。客户确认前不得进入出库 |
+| 贴标申请、箱唛/SKU/组合换标与 PDA 完工 | `relabel/`、`relabel/pda/`；一条 `ll_relabel_item` 对应一个客户填写的我方箱唛任务，`CARTON_LABEL`、`SKU_LABEL`、`CARTON_AND_SKU` 分别保存箱唛、SKU 或组合需求，SKU 子项 JSON 数量按件；涉及箱唛换标时整张申请只能有一个 FBA 目的仓，服务端拒绝明细目的仓不一致的请求。普通尾程入库没有箱唛到实物托盘的精确快照，历史入仓库存仓位只能作为冻结记账锚点和现场大概位置，禁止把该仓位解释为箱唛已绑定具体托盘。库存只按箱任务冻结一次。涉及箱唛换标时申请必须选择 `TRUCK/EXPRESS/PICKUP/AMAZON_PICKUP/CUSTOMER_PICKUP`，仅快递方式可要求打印并上传面单；PDA 扫我方箱唛完成逐箱事实和照片，仓库复核后等待客户查看照片确认。对外换标状态只投影为 `PENDING_PROCESSING/COMPLETED`（待处理/换标完成），`PROCESSING`、`CUSTOMER_CONFIRM_PENDING`、`READY_FOR_OUTBOUND` 只属于内部作业节点且不得直接出现在业务列表；客户确认后仅平台卡车 `TRUCK` 进入 `WAIT_PRE_DISPATCH`；快递及普通自提、亚马逊自提、客户自提均直接创建换标出库单，普通库存仍复验实际托盘绑定，已分配仓储转运保留原转运出库链。客户确认前不得进入出库 |
 | PDA 仓内通用扫码与操作历史 | `pda/warehouse/controller/PdaWarehouseController.java`、`pda/warehouse/service/PdaWarehouseService.java`；解析库存、库位和托盘码并查询操作历史，固定要求 `lastleg:pda:operate` 与 `ROLE_WAREHOUSE_PICKER`，仓库范围只能取自 PDA Token |
 | 船节点接收与海外 PDA 可收货门禁 | `shipping/service/ContainerShippingNodeConsumer.java`、`shipping/entity/ContainerShippingGate.java`、`shipping/mapper/ContainerShippingGateMapper.java`；按 `containerBookingId` 柜级接收，信封使用 `tenantId=0` 且门禁不存客户；只单调接受实际标准节点，`PICKUP_READY` 及以后才允许对应柜进入 PDA 收货候选 |
 | 平台排车列表/详情与智能预排 | `dispatch/controller/DispatchQueryController.java`、`SmartDispatchController.java`、`dispatch/mapper/DispatchCandidateMapper.java`、`dispatch/service/DispatchService.java`；草稿柜 `entity/DispatchDraftContainer.java`、`mapper/DispatchDraftContainerMapper.java`，托盘锁 `DispatchPalletLock.java`；入口 `/api/platform/v1/last-leg/dispatches`，路线由当前已排托盘的 FBA 仓编码去重后按稳定顺序以英文逗号连接，预排与普通编辑请求均不接收路线；查询、预排与执行边界见“海外仓全流程开发路由” |
@@ -80,3 +80,82 @@
 | 一件代发与废弃 | `ll_dropship_*`、`ll_cargo_discard_*` | 托盘/箱唛库存、流水和废弃审批 |
 | 采购、卡车与本土散板 | `ll_overseas_procurement_*`、`ll_us_truck_*`、`ll_local_looseboard_*` | 海外采购、美国卡车运输及本土散板订单 |
 | 通用资料 | `ll_overseas_quote*`、`ll_monthly_exchange_rate*`、`ll_vehicle` | 海外仓报价、月度汇率及车辆档案；不保存车辆派送履约历史 |
+
+## 海外仓全流程开发路由
+
+- 车次成本：`fleet/trip/FleetTripCostService.java`、`fleet-trip-costs-v1.yaml`；按DEPART实测及外接实收分摊，不产生客户账单/付款。
+- 报价/统计：`fleet/quote/`、`fleet/reporting/`，合同`fleet-quotes-v1.yaml`、`fleet-operations-v1.yaml`；实测凭证按车次归属，仅当前/历史版本引用可下载。
+- 外接选价合同：`fleet-quote-candidates-v1.yaml`、`fleet-trips-v1.yaml`；来源快照与成交价分开，确认承运复验。
+- 在途交接：`fleet/exception/`、`fleet-handovers-v1.yaml`；后台确认交接，旧资源分别结束任务，DEPART不重写。
+
+- 车辆履约投影：`fleet/trip/PlatformVehicleFulfillmentController.java` → `VehicleFulfillmentService` / `VehicleFulfillmentMapper`，合同`fleet-vehicle-fulfillment-v1.yaml`。派送同时要求vehicle:list与delivery:list，更换历史要求vehicle:list与trip:list；客户与排车双键关联，不跨库。按不可变DEPART/ASSIGN关联车辆，首次分配不算更换，不按当前车牌猜历史。只读重复读事务分页；不返回内部ID或整份客户快照。
+
+- 海外仓全流程连续覆盖尾程订单、入仓计划/PDA 入仓、换标、产品与箱唛快照、库存、转运、废弃、采购、本土卡车、本土散板、排车查询/智能预排、排车编辑/取消/发车、PDA 拣货与出库、一件代发、转派送、客户派送单、异常退回和客户回访。
+- 服务端正式入口包括 `dispatch/controller/DispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`、`delivery/controller/DeliveryTransferController.java`、`delivery/controller/OutboundPdaController.java`、`delivery/controller/MerchantDeliveryController.java`、`exceptionorder/` 与 `customervisit/`；设备页面是否可用以海外 PDA 正式路由和能力开关为准，未由 PDA 承载的操作由 Admin/Client 完成。
+- 平台一件代发出库候选由 `/outbound-orders/one-click-dropship/candidates` 统一返回已完成入库且仍有可用箱唛、SKU 汇总和库存仓位绑定的托盘明细；查询不强制先传 `customerId`，未传时跨客户展示供页面分页筛选，创建时必须从所选候选解析为唯一客户和唯一海外仓，禁止一张出库单跨客户或跨仓。创建后出库单按 `WAIT_PICK → PICKING → PICKED → OUTBOUNDED` 推进；海外 PDA 扫描托盘码时通过整托命令原子拣取该托盘在当前任务内全部剩余箱件和 SKU，任一库存明细失败须整托回滚，逐箱拣货入口继续保留。
+- 排车主流程以工作区 `docs/海外仓业务/排车列表统一作业改造契约.md` 为正式入口：一张排车单代表一趟车，装车完成后、实际发车前由后台安排派送，按客户与目的仓拆分派送单。`DispatchPdaWorkflowService` 按公开 `status`、`stage`、`recordVersion` 和 `actions` 返回作业事实与资格，Admin/PDA 共用服务端规则；BOL 与签收资料归拆分后的派送单，费用按其来源去重，不以旧转派送阶段或前端推算代替资格校验。
+- 排车主单允许同一起运仓的跨客户货物同车，每条来源保留客户、库存与费用归属；不再要求用户先建独立车次再关联多张客户排车。Fleet 的资源、司机证照、容量、历史与附加能力继续沿 `fleet/trip/` 定位；计划或资源变化对审核、实载确认的影响按正式契约及服务端结果核对，已拣货事实不能因改派或取消被直接抹除，实际发车后不得伪造资源释放。
+- 实物装载按仓库托盘去重计量，客户货量与物理占位分别保存；重量/体积必须来自实际确认，不用计费材积重回填。装车前真实拣货须核平，后台不能补录拣货数量绕过；装车、安排派送和发车不重复执行已完成的库存扣减。来源、审核、实载与资源版本变化按正式契约重新校验，保留操作历史；双端使用同一版本与原请求键核对结果，任何失败均不得伪造完成事实。
+- 车次结案只消费派送事实：实签须signedAt/signedPackages，实退须原来源入账流水/RETURN_COMPLETED；实签加本趟实退等于原实发且余量为零。拒收、待退回、取消不算完成，时间取最后实际终态。结案不改客户状态/费用、不释放占用；车/司机分别记录实际结束时间地点，车辆状态与释放同事务。过期证照不阻止旧任务结束、不恢复新任务资格；原键重放不影响后续车次。
+- 已签收后另发起退货保留原运输的签收事实，后续退货不重开原车次、不被车次结案改写；未签收货物仍按实际退回完成核对。`DeliveryDocumentService.save` 首次保存签收资料触发完成时要求关联出库已OUTBOUNDED，未出库可以准备BOL/装车资料但不能提前完成派送。
+- 排车执行与 `delivery/` Controller 一同注册；平台排车查询和智能预排入口分别沿 `lastleg.dispatch-query-api.enabled`、`lastleg.smart-dispatch-api.enabled` 配置定位，启用现状以配置和实际路由核对。平台查询按全局排车号及来源归属加载跨客户同车明细，客户接口保持本客户隔离；预排创建逐项校验同一起运仓及各来源客户，不能强制整张排车只含一个客户。草稿托盘锁仍按操作人与草稿标识持有，释放、失效及转正式锁由服务端原子处理。
+- 仓库 ID、类型、状态、地址和能力唯一权威归国内 `warehouse-service`；海外库位、实物托盘和资源锁归 `warehouse-overseas-service/` 且只引用同一国内 `warehouseId`。Lastleg PDA 通过 Warehouse Overseas 内部资源入口校验该国内共享收货仓，不得要求海外数据库重复建仓；浏览器 API 统一经 `gateway/`。
+
+- 外接预订以父车次行锁串行确认容量；DRAFT不占位，CONFIRMED占位，CANCELLED释放，创建/确认/取消保留请求键与内容摘要。报价与记录快照进入既有车次历史。重新核对自有货计划不得占用已确认外接容量，换小车须能容纳两者；同车只换司机不额外要求先重新核对容量。CONFIRMED和RECEIVED尚未绑定实际发运时阻止整车发车；通过真实来货实测、运费确认及来源核对后转为BOUND，解除未开工排车关联回RECEIVED。报价或登记来货不冒充库存/已出库；取消未执行预订仅释放承运容量，来货及已入库货物保留。
+- 外接约定运费由`fleet/trip/FleetBookingFreight`按排车来源、绑定车次、目的地和完整实收量复核；`DeliveryTransferService`在原转派送事务内发布到对应目的地派送单的`OVERSEAS_DELIVERY_FEE`，通过既有费用Outbox进入Finance。预览只读且使用dispatch:list；确认原货物/报价摘要后写入，全部外接货禁止再填派送应收，额外装车/买约仍独立。明确零约定留操作事实不发布虚构零费用。首版确认承运币种限现行费用支持的CNY/USD，原头程费用覆盖按下条处理。
+- 原运费覆盖由`delivery/service/DeliveryFeeCoverageService`与`DispatchFeeCargoMapper`按实际库存组成及本次已拣数量还原，核平每条排车箱数；不可用MIN展示入仓码替代整托全部来源。`FinanceFeeCoverageClient`批量只读Finance，平台转派送按费用ID/版本/hash和当前货物/目的地摘要复核，只有全部相关货物已覆盖的服务才免新增应收，供应商应付独立。客户接口禁止自行声明覆盖。确认快照保存到`ll_outbound_order.fee_coverage_json`，原费用不复制、不抵扣金额、不生成伪零费用；详情按本派送货物过滤只读快照，之后财务更正不自动改写旧发运。普通无引用请求保持原新增收费要求。
+- 派送出库取消按dispatch→outbound加锁，核对排车未拣货/发车并先解除车次关联；取消出库不代替取消排车占用。来源订单按本次转派送历史的原状态恢复，显式清空出库/派送关联并增加版本，不统一写RECEIVED。只对本派送当前已审核有效的DELIVERY_FEE应收申请作废，其他费用保留核对，完整取消原因分段保存在派送操作记录。
+- `financefee/state/OverseasFeeCancellation`从不可变费用Outbox批量读取voidStatus；请求/拒绝/未知结果保留ACTIVE，只有Finance匹配APPLIED/DUPLICATE后，在投递审计同事务中落VOIDED。撤销候选必须等待原发布成功，未满足前置的PENDING撤销在LIMIT前排除，避免堵住后续投递；过期PROCESSING仍按租约恢复。费用调整使用READ_COMMITTED并在来源行锁后检查未决撤销，禁止旧快照漏检。前端与API区分待财务确认、待财务处理和确认作废，不能以物流取消或HTTP请求发出认定账务已撤销。
+
+## 事件建单规则
+
+- 只接受冻结契约支持的事件类型和版本；校验事件 ID、租户、区域、Payload 哈希及必要字段。
+- 同一实际集装箱 `containerNo` 生成一个共享业务尾程单号；`payload.orders` 每项按 `sourceInboundId` 独立落一条雪花 ID `ll_order`，并保存对应明细和初始状态历史。整柜操作不使用 `cabinetNo`。
+- `ONE_CLICK_DROPSHIP` 每个来源入仓单必须携带一个或多个不可变来源托盘快照；每托按 SKU 携带箱数、数量和箱唛。校验订单汇总一致、托盘号/SKU/箱唛唯一后，按托建立档案及 SKU 库存，并建立箱唛和流水。仓库实物托盘由 Warehouse API 分配，不得覆盖来源托盘快照。
+- 其他订单类型建立入仓单维度的尾程订单与冻结明细，并保留头程推荐托数；尾程入仓计划至少按推荐托数生成计划托盘，PDA 再把箱级事实绑定到海外仓实物托盘。
+- 整个事件消费在一个事务内完成；任意订单失败时不得留下部分订单。
+- 相同事件重复投递返回既有结果，不重新生成单号或插入明细。来源入仓单唯一约束是最终防线。
+- 装柜完成事件只把尾程订单建立为 `PENDING_ASSIGNMENT`。`FIRST_LEG` 在途库存使用不可变来源入仓码作为计划生成前的 `inbound_order_no` 展示快照；平台人工转换成功后，同一事务将订单推进为 `INBOUND_PLANNED`，并把对应库存余额的该快照收口为新 `planNo`。
+- 内部接口先执行常量时间令牌校验；缺失或错误令牌不得进入消费事务。
+- 通用 `/internal/lastleg/events` 只白名单接收装柜完成、实际船节点与资金结果事件；未知或IAM安全事件必须拒绝。
+- PDA 入仓任务完成前必须先通过 `/unload-photos` 保存非空且不重复的卸柜照片文件 ID；照片上传时间由服务端记录，预计报空时间固定为照片上传时间加两天。完成入仓时，库存入账、计划/任务状态推进与 `OVERSEAS_CONTAINER_UNLOADED` V1 Outbox 必须处于同一事务；事件绑定来源头程货柜身份，不得从前端请求拼装或回查头程数据库。
+- 海外 PDA 柜号签收只允许平台 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 使用 `lastleg:pda:operate`；国内头程 PDA 角色不得进入。PDA 不接收 `customerId`，候选按来源柜跨客户聚合，同柜允许多个客户；选柜会话、三类照片及整柜完成事实只绑定 `sourceContainerBookingId + containerNo`，文件与柜级跨区事件使用 `tenantId=0` 平台技术范围。签收后按每个入仓计划自身客户生成任务，扫码、SKU 实收、托盘和库存始终使用入仓码所属票的真实客户。未完成会话按平台操作账号和柜号分别全局唯一；平台管理员和客户账号不得进入该作业入口。
+
+## 查询与租户约束
+
+- 平台查询范围由可信身份/平台权限决定；商户查询只能使用认证身份中的客户 ID。
+- 尾程平台只读查询接口的 `customerId` 为可选筛选条件：平台身份省略时查询全部客户数据，传入时按指定客户过滤；商户身份忽略客户端传入值并始终按 Token 中的自身客户隔离。创建、编辑、审核等需要明确目标客户的写接口仍必须传入 `customerId`。
+- 常规入仓库存余额以客户、海外仓、目的仓和入仓单为唯一业务维度并汇总箱数；SKU 继续保存在箱唛、实收和流水快照中，余额 SKU 仅作单 SKU 展示或以 `MIXED` 标识多 SKU，不参与当前唯一维度。
+- 托盘是 PDA 出库的作业单位，但不是库存归属单位：`ll_inventory_position` 通过余额和托盘保存“托盘包含哪些入仓单、各多少箱”的组成明细。合托后的同一实物托盘允许对应多个入仓单，换标冻结和后续出库核算必须按这些明细分别记账；整托出库可扫描托盘一次完成，部分出库先拆托或按明细核平，不得用 FIFO 猜测来源入仓单。普通尾程入库只确认某入仓单在托盘上的箱数，没有逐箱唛到托盘的快照；贴标下单由客户填写我方箱唛，库存仓位只作为冻结记账锚点和现场大概位置，不能据此声称箱唛位于某个具体托盘。贴标任务以我方箱唛为主键，同箱多 SKU 只存为子明细且不重复冻结。
+- 换标箱唛经现场确认后执行 `pallet-operations/relabel-disassemble`：允许仅移动该换标单对应的 `hold_packages`，不得解冻为普通可用库存；事务内同步更新 `ll_relabel_item.source_inventory_position_id`。若客户确认后已生成换标出库单，还必须在拣货开始前同步拆分或改写 `ll_outbound_pallet_item` 的托盘、箱唛、箱数与来源仓位快照，使 PDA 后续按新旧托盘分别扫描且每个指定箱唛只出库一次。
+- `FIRST_LEG` 在途、计划转换与 PDA 入账统一使用尾程订单冻结的实际接柜海外仓 ID/编码/名称，禁止使用国内来源仓或 FBA 目的仓冒充；接柜仓变更必须在同一事务内修订尚未形成实物仓位的在途余额并写零差额审计流水。余额分页、汇总和 CSV 默认排除所有数量桶均为零的维度，跨仓入账清空的无仓位来源余额必须原子删除。
+- 列表、详情、导出和更新必须使用同一租户边界，不能仅在列表过滤而让详情或更新越权。
+- 目的仓变更必须写状态/操作历史或审计证据，并使用版本控制防止并发覆盖。
+- 一件代发废弃：申请只锁箱 `AVAILABLE→DISCARD_PENDING`；平台批准（`lastleg:cargo-discard:approve`）只授权。绑定仓的海外 PDA（`lastleg:pda:operate`）实际确认时，同事务调用 discard adjustment，扣 SKU 件数及库存余额/位置，实际箱转 `DISCARDED` 并写唯一逐箱流水，数量须守恒；未废弃预留箱释放，失败整体回滚。按实际数量汇总费用，平台结案不再扣减。终态同完整载荷重放不新增流水/历史，异数量拒绝；驳回只释放锁箱。完整流程见 `../../docs/头程到尾程分阶段流程/阶段五-海外接柜库存与库内服务.md` 第9.5节。
+- 海外采购样品履约按 `../../docs/海外仓业务/采购订单样品履约流程变更需求.md` 执行：通用编辑仅限内部备注，实收、装箱、面单、两段交寄和资金走独立节点。采购使用 Admin 履约台账，不接入 PDA、不写 WMS 可用库存。
+- 派车状态只允许 PDA 拣货、完成和出库动作推进，普通派车编辑接口不得修改状态。PDA 写操作要求 `lastleg:pda:operate`；后台库存表单操作要求 `lastleg:inventory:manage`，盘点调整另要求 `lastleg:inventory:adjust`，转仓库存操作要求 `lastleg:warehouse-transfer:manage`。
+- `ll_order.current_status` 只保存尾程主流程状态；换标、转仓、出库和派送等子单精确状态保存到各自单据并汇总到 `sub_order_status`，不得再用子单状态覆盖主流程状态。PDA 入仓及库存落账完成后，主流程状态固定推进为 `INBOUND_COMPLETED`。
+
+## 修改与验证
+
+- `RelabelBindingGuard` 校验已保存组托历史与当前库存托盘一致，箱唛/混合换标正常完工、客户确认与排车提交均复验；纯 SKU 不要求移托，异常手动完工仍须在客户确认前补齐绑定。创建申请按库存余额串行检查箱唛既有申请，拒绝重复申请；历史扫码全局唯一约束尚未改为多轮复用。
+
+- 已确认箱唛改绑复用 `PdaPalletOperationService.relabelDisassemble` 不带 `actualSource` 的精确来源分支，按现有绑定移动 HOLD 库存，不重新分配冻结锚点；成功同样记录 `PALLET_BIND` 以展示最新目标。`requireUnallocatedRelabel` 在入口与事务锁单后限制排车/出库占用，已创建出库单也不可直接改绑。回归 `PdaPalletOperationServiceTest`。
+
+- PDA旧SKU单扫：`PdaRelabelService.scanSku` 和 `/relabel-tasks/{relabelNo}/skus/scan`，按箱itemId+skuIndex核对旧SKU，服务端取新SKU/数量，逐条记录现有 `SKU_SCAN` 历史，版本、幂等、认领和仓库校验不变；同箱全部SKU完成再推进SKU阶段，混合单需两阶段才生成一条箱事实。无新增字段；前端按历史当前轮次隐藏已完成子项，重复旧SKU须由操作员选实际箱。
+
+- 数量拆托成功在现有 `ll_relabel_pda_history` 写 `PALLET_BIND`，保存本轮、箱唛和目标托盘；同轮已组托箱从候选排除并在事务内防重复，返工使用新的 reviewedAt 轮次。PDA 通过详情 history 展示组托记录；不需要新增库存表字段。
+
+- 换标按数量拆合托：`palletops/PdaPalletOperationService.relabelSources` 返回原入仓库存池的托盘组成，不能视为箱唛定位；`relabel-disassemble` 的 `actualSource` 携带仓位版本及现场箱数，`cartonMarks` 为本批目标绑定确认。实际托盘与冻结锚点不同时，在同余额/批次内仅重新分配本单冻结桶后合托，库存余额及原入仓单归属不变，保留逐仓位流水、物理资源补偿及幂等。每次一条实际来源仓位，可分批多托；已生成出库单禁止此重分配。认领人处理中即可新增托盘，不需客户确认；此能力不等于已具备真机打印或整单强制组托门禁。
+
+- 换标申请生成的 `RELABEL_APPLICATION` 尾程主单使用 `WAIT_RELABEL`（待换标），不进入普通入库计划池；子状态仍区分处理中/待客户确认。客户确认后统一为 `WAIT_OUTBOUND`（待出库），卡车分支按换标申请的 `WAIT_PRE_DISPATCH` 资格参与排车，不重复入库。存量修正脚本 `../scripts/db/relabel-wait-status-incremental.sql` 仅调整尚未生成入库单的遗留待分配换标主单。
+
+- 混合换标 `CARTON_AND_SKU` 使用现有 PDA 历史保存 `MIXED_CARTON/MIXED_SKU` 分项事实（itemId + 退回轮次）；同一项防重复，两项全部完成才写一条箱事实并增加整箱计数。详情返回 `cartonProcessedPackages/skuProcessedPackages`；不得将单项完成当作整箱完成，返工后旧轮次不计入当前分项进度。
+
+- 换标复核闭环：`PdaRelabelService.complete` 直接提交待客户确认，`RelabelApplicationService.confirmCompletion` 原子完成 PDA 复核；平台 `RelabelApplicationController` 的 `/review-task`、`/rework` 按状态权限提供带版本的退回。退回备注必填，上一轮事实及照片引用写入 `REWORK_ARCHIVE` 历史，原事实标记 `REWORK_ARCHIVED` 并释放扫描唯一键，当前计数归零；客户已确认不可退回。PDA 不再自行批准复核。
+
+- 移动包、拆分端口/适配器或引入新的跨子域依赖时，先核对内部模块化基线并运行 `node --test scripts/analyze-lastleg-dependencies.test.mjs`；确需更新依赖基线时必须说明稳定边界变化，不能把临时循环依赖登记为长期豁免。
+- 表字段、注释和索引同步维护基线 SQL 与统一增量 SQL；生产/存量库只执行增量脚本。
+- 事件契约变化同时检查 `common-event-contract`、直接生产者/消费者、Outbox/Inbox 和 DeliveryAck 的 eventId/payloadHash；按 `../../docs/统一认证与服务通信契约.md` 的逐事件表验证，不引入旧 Payload 兼容。
+- 定向验证：从后端根执行 `mvn -pl lastleg-service -am test`。
+- 事件链路变更至少覆盖重复事件、相同来源入仓单、事务回滚、并发单号、内部令牌和租户越权测试。

lastleg-service/docs/lastleg-internal-modularization-baseline.md

@@ -20,6 +20,10 @@
 - 平台导出作为组合入口，仅登记 `LastlegExportProviderService` 对 12 个公开查询服务与 DTO/投影的引用，不开放整个切片；车辆仍限应用层。排车规划适配器只使用车队公开规划和收货端口。采购对海外主数据的旧依赖已不存在，移除该旧许可及入向断言。
 - 反向检查继续拒绝新消费者、导出直连持久化、车辆应用层外向依赖和任何主源码包循环。分析器继续按既有显式 import、静态 import 及同包类型引用规则检查；本次不改变其识别范围。
 
+### 整车排车的既有预约接线边界（2026-10-19）
+
+既有预约执行与改量只经 `dispatch.port.DispatchAppointmentAmendmentPort` 进入整车事务边界。`FbaAppointmentExecutionAdapter` 对该端口、`DispatchContracts`、`DispatchTypes`，以及 `FbaAppointmentTransportAdapter` 对该端口、`DispatchCommands`、`DispatchContracts`、`DispatchTypes` 的七条精确类引用进入 `reviewedClassDependencies`；不增加 `inbound-pda→dispatch-delivery` 的切片通用许可。适配器不得直连整车 Service、Repository 或 Mapper，其他消费者不继承本项许可，反向合同同时核对这两类越界。此边界只覆盖原预约与现行整车的关联、执行和同事务变更，不授权新增日历预约权威或流程。
+
 ### 平台自营统计边界
 
 `selfoperated/analytics/` 在依赖分析器中作为独立 `selfoperated-analytics` 切片优先匹配，其 `outbound`、`inventory` 和 `model` 子包不归入客户出库、客户库存或尾程交接切片。该子域通过内部 HTTP 使用 Integration，持久化十张独立 `ll_selfop_*` 表，不引用现有客户履约实体或 Mapper。唯一基础能力引用为 `SelfopEgressController → security.InternalServiceTokenGuard`，复用内部令牌校验；基线仅登记此精确类边，不增加共享技术切片通配许可，包循环仍按同一门禁拒绝。

lastleg-service/docs/warehouse-transfer-pickup.md

@@ -0,0 +1,15 @@
+# 仓储转运上门取货与车辆排车
+
+客户选择仓库上门取货并提交，平台审核通过后，原转运单进入车辆排车的“待取货”。一个取货车次可取多名客户的多票货，目的海外仓必须相同。客户自送、未审核、库存转运和测量已完成的订单不进入候选。
+
+业务入口为 `fleet/pickup/PlatformFleetPickupController`，按 Controller → Service → Repository → Mapper 持久化，复用原车次编号、车辆司机分配和资源占用。`tripPurpose=PICKUP` 区别于原 `DELIVERY`，取货车次不关联出库排车、不发布拼车余位、不执行原出库装载和扣库存。
+
+车次按 `PLANNED → IN_TRANSIT → COMPLETED` 执行。逐票取货任务为 `ASSIGNED → PICKED → ARRIVED`：发车复验车辆司机资格和实际占用；取货必须填写实提箱数并上传本票凭证；到仓后才开放原 PDA 清点测量。实提箱数独立保存，不覆盖客户预报箱数、SKU件数和箱唛。全车送仓可结束运输，车辆与司机任务分别沿原入口释放，不需要等仓内测量。
+
+计划阶段取消车次会保留操作历史、释放资源和原单关联，使原单重新可安排；发车后禁止取消。原车次分配入口支持发车前改派。所有取货命令在车次行锁、版本校验和持久幂等摘要下执行；来源安排同时锁原单，避免一单多车。前端遇到结果未知保留原请求和请求键，阻止刷新卸载或改派后重新生成命令。
+
+平台待取货使用服务端分页；客户详情、平台尾程详情按原转运单查询同一运输进度。凭证只允许当前单已确认引用，本车其他客户文件不能借用或下载。文件数据归 File 服务，Lastleg仅持有文件归属和引用。
+
+公开接口与请求字段见 `src/main/resources/openapi/fleet-transfer-pickup-v1.yaml`。数据库增量为 `../../scripts/db/fleet-transfer-pickup-20261017.sql`，目标 `baiyue_lastleg`，可重复执行，无业务 DML。
+
+本机验收入口 `../../scripts/local-transfer-pickup-acceptance.mjs` 创建带 TEST 标记的新业务记录并保存报告。覆盖待取货、未审核、自送、异仓拒绝、共车、取消改派、资源冲突、同键重放与异载荷拒绝、跨客户文件隔离、未送仓禁止PDA和送仓后完整测量。合成图片仅验证上传与文件归属，不证明物理取货。本机构建、单测和HTTP验收与远端部署、真实页面视觉验收分别记录。

lastleg-service/pom.xml

@@ -25,4 +25,29 @@
         <dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><scope>test</scope></dependency>
     </dependencies>
     <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
+    <profiles>
+        <profile>
+            <id>ci-bounded</id>
+            <build><plugins><plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>default-test</id>
+                        <configuration><excludes><exclude>**/*SqlSemanticTest.java</exclude></excludes></configuration>
+                    </execution>
+                    <!-- H2复杂查询规划与普通单测分进程，仍沿用父级1GB上限并执行全部断言。 -->
+                    <execution>
+                        <id>sql-semantic-tests</id>
+                        <phase>test</phase>
+                        <goals><goal>test</goal></goals>
+                        <configuration>
+                            <includes><include>**/*SqlSemanticTest.java</include></includes>
+                            <reuseForks>false</reuseForks>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin></plugins></build>
+        </profile>
+    </profiles>
 </project>

lastleg-service/scripts/analyze-lastleg-dependencies.test.mjs

@@ -73,6 +73,40 @@ function analyze(sourceSet = 'main') {
   }));
 }
 
+test('original appointment adapters use only the reviewed dispatch port types', () => {
+  const report = analyze();
+  const baseline = JSON.parse(readFileSync(contract, 'utf8'));
+  const prefix = 'com.baiyue.lastleg.inboundplan.work.';
+  const port = 'com.baiyue.lastleg.dispatch.port.';
+  const expected = [
+    ['FbaAppointmentExecutionAdapter', 'DispatchAppointmentAmendmentPort'],
+    ['FbaAppointmentExecutionAdapter', 'DispatchContracts'],
+    ['FbaAppointmentExecutionAdapter', 'DispatchTypes'],
+    ['FbaAppointmentTransportAdapter', 'DispatchAppointmentAmendmentPort'],
+    ['FbaAppointmentTransportAdapter', 'DispatchCommands'],
+    ['FbaAppointmentTransportAdapter', 'DispatchContracts'],
+    ['FbaAppointmentTransportAdapter', 'DispatchTypes'],
+  ].map(([source, target]) => `${prefix}${source}->${port}${target}`).sort();
+  const reviewed = baseline.reviewedClassDependencies.filter(edge => edge.source.startsWith(prefix)
+    && edge.target.startsWith('com.baiyue.lastleg.dispatch.'));
+  assert.deepEqual(reviewed.map(edge => `${edge.source}->${edge.target}`).sort(), expected);
+  assert.equal(baseline.allowedSliceEdges.includes('inbound-pda->dispatch-delivery'), false);
+  const violations = contractViolations(report, baseline);
+  for (const edge of expected) assert.equal(violations.some(message => message.includes(edge)), false);
+
+  // 精确端口边不允许原适配器直连整车实现，也不授权其他预约消费者借用此许可。
+  const forbidden = [
+    { source: prefix + 'FbaAppointmentExecutionAdapter', target: 'com.baiyue.lastleg.dispatch.service.DispatchAggregateService' },
+    { source: prefix + 'AppointmentWorkDispatchBinding', target: port + 'DispatchAppointmentAmendmentPort' },
+  ];
+  for (const edge of forbidden) {
+    assert.ok(report.classes.some(entry => entry.fqcn === edge.source));
+    assert.ok(report.classes.some(entry => entry.fqcn === edge.target));
+    report.classDependencies.push(edge);
+    assert.ok(contractViolations(report, baseline).some(message => message.includes(`${edge.source}->${edge.target}`)));
+  }
+});
+
 test('current source does not add slice dependencies beyond the Lastleg baseline', () => {
   execFileSync(process.execPath, [analyzer, '--source-set', 'main', '--format', 'dot', '--check', contract], {
     cwd: moduleRoot,

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentplanning/AppointmentCargoVerificationMapper.java

@@ -16,6 +16,17 @@ public interface AppointmentCargoVerificationMapper extends BaseMapper<Appointme
     @Select("SELECT * FROM ll_appointment_cargo_verification WHERE customer_id=#{customerId} AND source_key=#{sourceKey} ORDER BY version DESC LIMIT 1")
     AppointmentCargoVerification latest(@Param("customerId") String customerId,@Param("sourceKey") String sourceKey);
 
+    @Select("""
+        <script>
+        SELECT ranked.* FROM (
+          SELECT v.*,ROW_NUMBER() OVER(PARTITION BY customer_id,source_key ORDER BY version DESC) work_row
+          FROM ll_appointment_cargo_verification v WHERE
+          <foreach collection='refs' item='ref' separator=' OR '>(customer_id=#{ref.customerId} AND source_key=#{ref.sourceKey})</foreach>
+        ) ranked WHERE work_row=1
+        </script>
+        """)
+    java.util.List<AppointmentCargoVerification> latestBatch(@Param("refs") java.util.List<AppointmentCoverageService.SourceRef> refs);
+
     @Select("SELECT * FROM ll_appointment_cargo_verification WHERE customer_id=#{customerId} AND source_key=#{sourceKey} AND command_key=#{key}")
     AppointmentCargoVerification command(@Param("customerId") String customerId,@Param("sourceKey") String sourceKey,@Param("key") String key);
 
@@ -27,4 +38,15 @@ public interface AppointmentCargoVerificationMapper extends BaseMapper<Appointme
         WHERE customer_id=#{customerId} AND source_key=#{sourceKey} AND active=1
         """)
     Allocation allocated(@Param("customerId") String customerId,@Param("sourceKey") String sourceKey);
+
+    record SourceAllocation(String customerId,String sourceKey,long packages,long unknownItems) { }
+    @Select("""
+        <script>
+        SELECT customer_id,source_key,COALESCE(SUM(package_count),0) packages,COUNT(*)-COUNT(package_count) unknown_items
+        FROM ll_inbound_fba_appointment_item WHERE active=1 AND (
+          <foreach collection='refs' item='ref' separator=' OR '>(customer_id=#{ref.customerId} AND source_key=#{ref.sourceKey})</foreach>
+        ) GROUP BY customer_id,source_key
+        </script>
+        """)
+    java.util.List<SourceAllocation> allocatedBatch(@Param("refs") java.util.List<AppointmentCoverageService.SourceRef> refs);
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentplanning/AppointmentCargoVerificationService.java

@@ -40,13 +40,43 @@ public class AppointmentCargoVerificationService {
 
     @Transactional(readOnly=true)
     public Context get(String sourceKey,String customerId,String destinationKey) {
+        return inspect(sourceKey,customerId,destinationKey);
+    }
+    /** Caller-owned transaction: a handled read prerequisite must not mark the whole work scan rollback-only. */
+    public Context inspect(String sourceKey,String customerId,String destinationKey) {
         var source=sources.resolve(sourceKey,customerId,destinationKey);
         return inspect(source);
     }
+    public record Inspection(AppointmentCoverageService.SourceRef reference,Context context,ResponseStatusException error) {
+        public Context requireContext() { if(error!=null) throw error; return context; }
+    }
+    /** Shares source and warehouse reads within this call only; never caches mutable business facts across requests. */
+    public List<Inspection> inspectBatch(List<AppointmentCoverageService.SourceRef> refs) {
+        var result=new ArrayList<Inspection>();
+        for(int start=0;start<refs.size();start+=100) {
+            var batch=refs.subList(start,Math.min(start+100,refs.size()));
+            var resolved=sources.inspectBatch(batch);
+            var valid=resolved.stream().filter(r->r.error()==null).map(AppointmentSourceService.Resolution::reference).toList();
+            var latest=new HashMap<List<String>,AppointmentCargoVerification>();
+            var allocations=new HashMap<List<String>,AppointmentCargoVerificationMapper.Allocation>();
+            if(!valid.isEmpty()) {
+                mapper.latestBatch(valid).forEach(r->latest.put(List.of(r.getCustomerId(),r.getSourceKey()),r));
+                mapper.allocatedBatch(valid).forEach(r->allocations.put(List.of(r.customerId(),r.sourceKey()),new AppointmentCargoVerificationMapper.Allocation(r.packages(),r.unknownItems())));
+            }
+            for(var resolution:resolved) {
+                var key=List.of(resolution.reference().customerId(),resolution.reference().sourceKey());
+                result.add(new Inspection(resolution.reference(),resolution.error()==null?inspect(resolution.source(),latest.get(key),allocations.getOrDefault(key,new AppointmentCargoVerificationMapper.Allocation(0,0))):null,resolution.error()));
+            }
+        }
+        return List.copyOf(result);
+    }
     /** Uses an already-authorized batched source resolution; never repeats warehouse HTTP lookups per row. */
     public Context inspect(AppointmentSourceService.Source source) {
         var row=mapper.latest(source.customerId(),source.sourceKey());
         var allocation=mapper.allocated(source.customerId(),source.sourceKey());
+        return inspect(source,row,allocation);
+    }
+    private Context inspect(AppointmentSourceService.Source source,AppointmentCargoVerification row,AppointmentCargoVerificationMapper.Allocation allocation) {
         boolean changed=row!=null && changed(row,source);
         Integer total=row==null?source.packages():row.getPackageCount();
         var reasons=new ArrayList<>(source.blockReasons());

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentplanning/AppointmentImpactRelationMapper.java

@@ -19,11 +19,11 @@ public interface AppointmentImpactRelationMapper {
         """)
     List<Appointment> appointments(String id);
     @Select("""
-        SELECT DISTINCT d.customer_id,d.dispatch_no FROM ll_order o
+        SELECT DISTINCT i.customer_id,d.dispatch_no FROM ll_order o
         JOIN ll_dispatch_item i ON i.order_id=o.id AND i.customer_id=o.customer_id
-        JOIN ll_dispatch_order d ON d.id=i.dispatch_order_id AND d.customer_id=i.customer_id
+        JOIN ll_dispatch_order d ON d.id=i.dispatch_order_id
         WHERE o.source_container_booking_id=#{id} AND o.order_type='FIRST_LEG' AND o.current_status NOT IN ('CANCELLED','COMPLETED')
-          AND d.status NOT IN ('CANCELLED','COMPLETED') ORDER BY d.dispatch_no LIMIT 1001
+          AND d.status='ACTIVE' AND d.stage<>'DELIVERED' ORDER BY d.dispatch_no LIMIT 1001
         """)
     List<AppointmentImpactTransportGateway.Dispatch> dispatches(String id);
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentplanning/AppointmentSourceService.java

@@ -58,14 +58,42 @@ public class AppointmentSourceService {
             return response.data().warehouse().timezone();
         } catch(RuntimeException error) { throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE,"目的仓时区读取失败，请稍后核对",error); }
     }
-    /** One catalog request and batched source reads, including mixed first-leg and external bookings. */
+    /** 普通批量读取创建独立目录作用域，同时读取头程和外接登记来源。 */
     public List<Source> resolveBatch(List<AppointmentCoverageService.SourceRef> requested) {
+        return openReadScope().resolveBatch(requested);
+    }
+    /** 创建显式单次读取作用域；仅成功的目录结果可在本次生成中复用。 */
+    public ReadScope openReadScope() { return new ReadScope(); }
+    public final class ReadScope {
+        private List<AppointmentWarehouseClient.Warehouse> directory;
+        /** 只能由所属来源服务创建，不允许传入未经校验的目录。 */
+        private ReadScope() { }
+        /** 每次仍读取原订单和权限事实，仅目录共享；不保存来源解析结果。 */
+        public List<Source> resolveBatch(List<AppointmentCoverageService.SourceRef> requested) {
+            return AppointmentSourceService.this.resolveBatch(requested,true,this).stream().map(Resolution::requireSource).toList();
+        }
+        /** 读取失败不赋值，下次显式调用仍按原目录接口重读。 */
+        private List<AppointmentWarehouseClient.Warehouse> catalog() {
+            if(directory==null) directory=AppointmentSourceService.this.catalog();
+            return directory;
+        }
+    }
+    /** Read-only inspection keeps each source's prerequisite failure separate; infrastructure errors still escape. */
+    public record Resolution(AppointmentCoverageService.SourceRef reference,Source source,ResponseStatusException error) {
+        public Source requireSource() { if(error!=null) throw error; return source; }
+    }
+    /** 每次检查独立读取目录，保留逐来源前置条件失败与基础设施异常边界。 */
+    public List<Resolution> inspectBatch(List<AppointmentCoverageService.SourceRef> requested) {
+        return resolveBatch(requested,false,openReadScope());
+    }
+    /** 保留原批量校验与错误边界，目录只从调用方的局部作用域读取。 */
+    private List<Resolution> resolveBatch(List<AppointmentCoverageService.SourceRef> requested,boolean strict,ReadScope scope) {
         if(requested==null || requested.isEmpty() || requested.size()>100) throw bad("每批请选择1至100票真实货源");
         var keys=new LinkedHashSet<String>(); var orderIds=new LinkedHashSet<Long>();
         var bookingRefs=new java.util.ArrayList<AppointmentExternalSourceGateway.SourceRef>();
         for(var ref:requested) {
             if(ref==null || blank(ref.sourceKey()) || ref.sourceKey().length()>160 || blank(ref.customerId()) || ref.customerId().length()>128) throw bad("请选择完整的真实货源");
-            if(!keys.add(ref.sourceKey())) throw bad("同一来源货物不能重复选择");
+            if(!keys.add(ref.sourceKey()) && strict) throw bad("同一来源货物不能重复选择");
             if(ref.sourceKey().startsWith("ORDER:")) orderIds.add(orderId(ref.sourceKey()));
             else if(ref.sourceKey().startsWith("BOOKING:") && !blank(ref.sourceKey().substring(8))) bookingRefs.add(new AppointmentExternalSourceGateway.SourceRef(ref.customerId(),ref.sourceKey().substring(8)));
             else throw bad("不支持的货源类型");
@@ -77,17 +105,28 @@ public class AppointmentSourceService {
             if(booking.orderId()!=null) orderIds.add(booking.orderId());
         }
         var orderRows=orderIds.isEmpty()?List.<com.baiyue.lastleg.entity.LastlegOrder>of():orders.selectBatchIds(orderIds);
-        var directOrders=requested.stream().filter(ref->ref.sourceKey().startsWith("ORDER:")).map(ref->new AppointmentExternalSourceGateway.OrderRef(ref.customerId(),orderId(ref.sourceKey()))).toList();
+        var directOrders=requested.stream().filter(ref->ref.sourceKey().startsWith("ORDER:")).map(ref->new AppointmentExternalSourceGateway.OrderRef(ref.customerId(),orderId(ref.sourceKey()))).distinct().toList();
-        if(!directOrders.isEmpty() && !external.resolveOrders(directOrders).isEmpty()) throw bad("该货物来自外接登记，请使用原登记来源继续预约");
+        var externalOrders=directOrders.isEmpty()?Set.<AppointmentExternalSourceGateway.OrderRef>of():external.resolveOrders(directOrders).stream()
+            .map(s->new AppointmentExternalSourceGateway.OrderRef(s.customerId(),s.orderId())).collect(Collectors.toSet());
+        if(strict && !externalOrders.isEmpty()) throw bad("该货物来自外接登记，请使用原登记来源继续预约");
         var orderMap=orderRows.stream().collect(Collectors.toMap(com.baiyue.lastleg.entity.LastlegOrder::getId,Function.identity()));
         var transferRefs=orderRows.stream().filter(o->"WAREHOUSE_TRANSFER".equals(o.getOrderType())).map(o->new AppointmentCoverageMapper.OrderRef(o.getCustomerId(),o.getId())).toList();
         var destinations=transferRefs.isEmpty()?Map.<Long,AppointmentCoverageMapper.Source>of():destinationFacts.sources(transferRefs).stream().collect(Collectors.toMap(AppointmentCoverageMapper.Source::orderId,Function.identity()));
         var containerIds=orderRows.stream().filter(o->"FIRST_LEG".equals(o.getOrderType())).map(com.baiyue.lastleg.entity.LastlegOrder::getSourceContainerBookingId).filter(Objects::nonNull).distinct().toList();
         var gates=containerIds.isEmpty()?Map.<String,Boolean>of():shipping.selectBatchIds(containerIds).stream().collect(Collectors.toMap(g->g.getContainerBookingId(),g->g.getNodeSequence()!=null && g.getNodeSequence()>=40));
-        var catalog=catalog();
+        var catalog=scope.catalog();
-        var result=requested.stream().map(ref->resolve(ref.sourceKey(),ref.customerId(),ref.destinationKey(),orderMap,bookingMap,gates,catalog,destinations)).toList();
+        var result=requested.stream().map(ref->{
+            try {
+                if(ref.sourceKey().startsWith("ORDER:") && externalOrders.contains(new AppointmentExternalSourceGateway.OrderRef(ref.customerId(),orderId(ref.sourceKey()))))
+                    throw bad("该货物来自外接登记，请使用原登记来源继续预约");
+                return new Resolution(ref,resolve(ref.sourceKey(),ref.customerId(),ref.destinationKey(),orderMap,bookingMap,gates,catalog,destinations),null);
+            } catch(ResponseStatusException error) {
+                if(strict || error.getStatusCode().value()>=500) throw error;
+                return new Resolution(ref,null,error);
+            }
+        }).toList();
         var materialized=new java.util.HashSet<Long>();
-        for(var source:result) if(source.orderId()!=null && !materialized.add(source.orderId())) throw bad("同一货物存在重复来源，请保留原登记来源");
+        if(strict) for(var resolution:result) { var source=resolution.requireSource(); if(source.orderId()!=null && !materialized.add(source.orderId())) throw bad("同一货物存在重复来源，请保留原登记来源"); }
         return result;
     }
     private Source resolve(String sourceKey,String customerId,String destinationKey,

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkChanges.java

@@ -4,13 +4,15 @@ import org.springframework.stereotype.Component;
 import org.springframework.transaction.annotation.Propagation;
 import org.springframework.transaction.annotation.Transactional;
 
-/** Original business commands invalidate the manifest atomically with their business write. */
+/** 原业务写入与工作清单失效保持在同一事务，不延后或绕过版本门禁。 */
 @Component
 public class AppointmentWorkChanges {
-    private final AppointmentWorkMapper mapper;
+    private final AppointmentWorkStore store;
-    public AppointmentWorkChanges(AppointmentWorkMapper mapper) { this.mapper=mapper; }
+    /** 复用工作事项持久层，统一记录守卫更新耗时。 */
+    public AppointmentWorkChanges(AppointmentWorkStore store) { this.store=store; }
+    /** 只标记需求变化，保留调用方原事务和异常语义。 */
     @Transactional(propagation=Propagation.MANDATORY)
     public void requirementsChanged() {
-        if(mapper.invalidateRequirements()!=1) throw AppointmentWorkPolicy.unavailable("工作事项同步守卫未初始化");
+        store.invalidateRequirements();
     }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkCommandService.java

@@ -63,7 +63,9 @@ public class AppointmentWorkCommandService {
                 fields(payload,Set.of("reviewVersion","note"),Set.of("reviewVersion","note"));
                 int version=integer(payload,"reviewVersion");
                 if(!state.isReviewRequired() || state.getReviewVersion()!=version) throw conflict("影响版本已变化，请重新核对");
-                if(changed(state,fact)) throw conflict("原业务已有更新，须先同步最新影响");
+                if(changed(state,fact) || fact!=null && state.getObservedImpactToken()!=null
+                    && !Objects.equals(state.getObservedImpactToken(),fact.impactToken())) throw conflict("原业务已有更新，须先同步最新影响");
+                requireCurrentImpacts(state);
                 if(fact!=null && !fact.blockReasons().isEmpty()) throw conflict("原业务仍有阻断，请先处理原安排");
                 summary=text(payload,"note",true,1000); state.setReviewRequired(false); state.setReviewReason(null);
             }
@@ -114,6 +116,20 @@ public class AppointmentWorkCommandService {
         store.history(state,actor,request.command().name(),summary,request.idempotencyKey(),hash,result);
         return result;
     }
+    private void requireCurrentImpacts(AppointmentWorkState state) {
+        store.requireInitialized();
+        var prerequisites=AppointmentWorkSyncService.impactPrerequisites(state,store.all());
+        if(prerequisites.isEmpty()) return;
+        var current=gateway.facts(prerequisites);
+        for(var prior:prerequisites) {
+            if(prior.getType()==Type.ROUTE) continue;
+            var fact=current.get(prior.getWorkItemKey());
+            if(fact==null) throw unavailable("关联安排权威事实缺失，不能完成复核");
+            if(prior.isObservedArranged() && prior.getObservedDependentImpactToken()!=null
+                && !Objects.equals(prior.getObservedDependentImpactToken(),fact.dependentImpactToken()))
+                throw conflict("关联安排已有新变化，须先同步最新影响再复核");
+        }
+    }
     private List<String> markDownstream(AppointmentWorkState source,String reason,Actor actor) {
         var states=store.all(); var keys=new LinkedHashSet<String>(); AppointmentWorkSyncService.expandDependents(source.getWorkItemKey(),states,keys); keys.remove(source.getWorkItemKey());
         var candidates=states.stream().filter(s->keys.contains(s.getWorkItemKey()) && !s.isRetired()).toList(); var facts=gateway.facts(candidates); var affected=new ArrayList<String>();

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkCommitmentService.java

@@ -29,6 +29,12 @@ public class AppointmentWorkCommitmentService {
         var row=mapper.commitment(key);
         return key+":"+(row==null?0:row.getImpactVersion());
     }
+    public java.util.Map<String,String> impactTokens(java.util.List<String> keys) {
+        var tokens=new java.util.HashMap<String,String>();
+        keys.forEach(key->tokens.put(key,key+":0"));
+        if(!keys.isEmpty()) mapper.commitments(keys).forEach(row->tokens.put(row.getEntityKey(),row.getEntityKey()+":"+row.getImpactVersion()));
+        return tokens;
+    }
     public static boolean impacts(Commitment old,Commitment now) {
         if(old.cancelled()!=now.cancelled()) return true;
         boolean firstSameDayConfirmation=old.confirmed()==null && now.confirmed()!=null && old.target()!=null && old.target().date().equals(now.confirmed().date());

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkController.java

@@ -33,6 +33,10 @@ public class AppointmentWorkController {
         @RequestParam(required=false) String containerBookingId,@RequestParam(required=false) Bucket bucket,@RequestParam(required=false) String keyword) {
         return ApiResponse.success(queries.items(view,page,size,date,flow,types,containerBookingId,bucket,keyword,actor(user)));
     }
+    @GetMapping("/items/resolve")
+    public ApiResponse<BatchWorkResolution> resolve(@AuthenticationPrincipal AuthenticatedUser user,@RequestParam String batchKey,@RequestParam(required=false) String customerId) {
+        return ApiResponse.success(queries.resolveBatch(batchKey,customerId,actor(user)));
+    }
     @GetMapping("/items/{workItemKey}")
     public ApiResponse<WorkDetail> detail(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String workItemKey) {
         return ApiResponse.success(queries.detail(workItemKey,actor(user)));

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkDirectTransportProvider.java

@@ -36,7 +36,7 @@ public class AppointmentWorkDirectTransportProvider implements BusinessProvider
                 done?ExecutionStatus.COMPLETED:carrier.executionStatus()==ExecutionStatus.COMPLETED?ExecutionStatus.IN_PROGRESS:ExecutionStatus.PENDING,
                 carrier.target(),carrier.confirmed(),done?delivery.actual():null,done?delivery.timezone():carrier.timezone(),delivery.businessNo(),null,
                 List.copyOf(read),action==null?List.of():carrier.executionStatus()==ExecutionStatus.COMPLETED?delivery.actionPermissions():carrier.actionPermissions(),action,
-                done?List.of():carrier.executionStatus()==ExecutionStatus.COMPLETED?delivery.blockReasons():carrier.blockReasons(),List.copyOf(missing),List.copyOf(refs),carrier.responsibility());
+                done?List.of():carrier.executionStatus()==ExecutionStatus.COMPLETED?delivery.blockReasons():carrier.blockReasons(),List.copyOf(missing),List.copyOf(refs),carrier.responsibility(),null);
         }).toList();
     }
     private FactRequest request(FactRequest r,Type type,String suffix) { return new FactRequest(r.workItemKey()+suffix,type,r.flow(),r.containerBookingId(),r.requirementKey(),r.batchKey(),null,r.batchKeys(),r.containers(),r.sources()); }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkDispatchPort.java

@@ -2,15 +2,29 @@ package com.baiyue.lastleg.appointmentwork;
 
 import jakarta.validation.constraints.*;
 import java.util.List;
+import java.util.Map;
 
 /** Real dispatch allocation boundary, implemented by the original appointment domain. */
 public interface AppointmentWorkDispatchPort {
-    record Allocation(@NotNull Long planPalletId,@NotBlank String batchKey,@NotBlank String customerId,
+    record Allocation(@NotNull Long planPalletId,@NotBlank String batchKey,@NotNull @PositiveOrZero Long recordVersion,@NotBlank String customerId,
                       @NotBlank String sourceKey,@NotBlank String destinationKey,@Positive int packageCount) { }
-    record PhysicalItem(Long itemId,Long planPalletId,String sourceStage,Integer packages) { }
+    record PhysicalItem(Long itemId,String customerId,Long planPalletId,String sourceStage,Integer packages) { }
-    void bind(String customerId,long dispatchId,List<PhysicalItem> items,List<Allocation> allocations);
+    record BatchSource(String sourceKey,String destinationKey,int packageCount) { }
-    void requireReplay(String customerId,long dispatchId,List<Allocation> allocations);
+    record BatchReference(String batchKey,String batchNo,Long recordVersion,String customerId,List<BatchSource> sources) { }
+    record CandidatePhysical(String customerId,Long planPalletId) { }
+    /** sources数量由本托真实逐票量和原批次剩余量共同限定；不包含零余量的伪可选项。 */
+    record CandidateBatches(List<BatchReference> appointmentBatches,List<String> blockReasons,boolean occupied) { }
+    /** 整页真实客户/计划托盘一次批读；occupied含有效草稿与正式实托占用，由调用方核对本草稿身份。 */
+    Map<CandidatePhysical,CandidateBatches> candidateBatches(List<CandidatePhysical> candidates);
+    /** Current original allocations, grouped for authorized dispatches; historical copies are read-only evidence. */
+    java.util.Map<Long,List<BatchReference>> references(List<Long> dispatchIds);
+    /** 在来源锁前按批次键一次性预锁并核对权威版本，版本零合法。 */
+    void lockBatches(Map<String,Long> expectedBatchVersions);
+    /** 仅替换已核实的受影响实物分配，保留同车其他客户及其他实物。 */
+    void bindItems(long dispatchId,List<PhysicalItem> touchedItems,List<Allocation> allocations);
     void requireDeparture(String dispatchNo);
+    /** Read-only explanation; departure must repeat the same authority checks while holding batch locks. */
+    String departureBlockReason(String dispatchNo);
     void removeItem(long dispatchId,long itemId);
     void requireTripBinding(String dispatchNo,long tripId);
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkFactAdapter.java

@@ -4,12 +4,14 @@ import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
 import java.util.*;
+import static com.baiyue.lastleg.appointmentwork.diagnostics.AppointmentWorkDiagnostics.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkModels.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkFactGateway.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkPolicy.*;
 
 @Component
 public class AppointmentWorkFactAdapter implements AppointmentWorkFactGateway {
+    private static final org.slf4j.Logger LOG=org.slf4j.LoggerFactory.getLogger(AppointmentWorkFactAdapter.class);
     private final AppointmentWorkFirstlegClient firstleg;
     private final List<BusinessProvider> providers;
     private final ObjectProvider<OwnerDirectory> directory;
@@ -38,7 +40,10 @@ public class AppointmentWorkFactAdapter implements AppointmentWorkFactGateway {
             return response.data();
         } catch(RuntimeException error) { throw unavailable("柜次权威事实不可用",error); }
     }
+    /** 原顺序读取全部事实；慢调用和失败仅附加无业务内容的局部统计。 */
     public Map<String,Fact> facts(List<AppointmentWorkState> states) {
+        var timing=new FactTiming();boolean success=false;
+        try {
         var result=new LinkedHashMap<String,Fact>();
         var remote=new ArrayList<FactRequest>();
         var groups=new LinkedHashMap<BusinessProvider,List<FactRequest>>();
@@ -53,36 +58,99 @@ public class AppointmentWorkFactAdapter implements AppointmentWorkFactGateway {
             }
         }
         for(int start=0; start<remote.size(); start+=200) {
-            var requests=remote.subList(start,Math.min(start+200,remote.size())); requireToken();
+            var requests=remote.subList(start,Math.min(start+200,remote.size())); timing.stage="FIRSTLEG"; requireToken();
-            try { var response=firstleg.facts(token,requests);
+            try { var response=timing.measure(timing.firstleg,requests.size(),()->firstleg.facts(token,requests));
                 if(response==null || !response.successful()) throw unavailable("提柜及还空事实读取失败");
-                append(result,requests,response.data());
+                run(Stage.FACTS_VALIDATE,()->append(result,requests,response.data()));
             } catch(RuntimeException error) { throw unavailable("Firstleg工作事实不可用",error); }
         }
         groups.forEach((provider,requests)->{
             for(int start=0; start<requests.size(); start+=200) {
                 var batch=requests.subList(start,Math.min(start+200,requests.size()));
-                try { append(result,batch,provider.read(batch)); }
+                var statistics=timing.provider(provider);
+                try { var response=timing.measure(statistics,batch.size(),()->provider.read(batch));run(Stage.FACTS_VALIDATE,()->append(result,batch,response)); }
                 catch(RuntimeException error) { throw unavailable("预约/收货/运输事实不可用",error); }
             }
         });
-        return result;
+        success=true;return result;
+        } finally { timing.finish(success); }
     }
-    public List<Requirement> requirements(ContainerSource source,Flow effectiveFlow) {
+    /** 一次 facts 调用的计时，不保存原来源或返回值，不跨调用缓存。 */
-        var provider=requirements.getIfAvailable();
+    private static final class FactTiming {
-        if(provider==null) throw unavailable("原预约需求与批次清单适配尚未接入，不能生成不完整工作清单");
+        private final Span prepare=span(Stage.FACTS_PREPARE);
-        var result=provider.requirements(source,effectiveFlow);
+        private final long started=System.nanoTime();
-        if(result==null || result.isEmpty()) throw unavailable("原预约需求清单缺失，不能以空清单完成路线生成");
+        private final CallStatistics firstleg=new CallStatistics();
-        return List.copyOf(result);
+        private final Map<String,CallStatistics> providers=new LinkedHashMap<>();
+        private String stage="PREPARE";
+        /** 固定诊断桶不使用代理名、业务参数或异常文本。 */
+        private CallStatistics provider(BusinessProvider provider) {
+            String name=org.springframework.util.ClassUtils.getUserClass(provider).getSimpleName();
+            name=switch(name) {
+                case "AppointmentWorkReceivingProvider","AppointmentWorkDeliveryProvider","AppointmentWorkTransportProvider","AppointmentWorkDirectTransportProvider" -> name;
+                default -> "OTHER";
+            };
+            stage=name;
+            return providers.computeIfAbsent(name,ignored->new CallStatistics());
+        }
+        /** 只统计真正尝试的提供端调用；校验及组装耗时保留在 totalMs 中。 */
+        private <T> T measure(CallStatistics statistics,int requests,java.util.function.Supplier<T> operation) {
+            prepare.close();statistics.calls++;statistics.requests+=requests;long begin=System.nanoTime();
+            try(var span=span(switch(stage){case "FIRSTLEG"->Stage.FACTS_FIRSTLEG;case "AppointmentWorkReceivingProvider"->Stage.FACTS_RECEIVING;
+                case "AppointmentWorkDeliveryProvider"->Stage.FACTS_DELIVERY;case "AppointmentWorkTransportProvider"->Stage.FACTS_TRANSPORT;
+                case "AppointmentWorkDirectTransportProvider"->Stage.FACTS_DIRECT_TRANSPORT;default->Stage.FACTS_OTHER;})){
+                try{return operation.get();}catch(RuntimeException|Error error){span.failed();throw error;}
+            }finally{statistics.elapsed+=System.nanoTime()-begin;}
+        }
+        /** 成功慢调用或任意失败只输出一次汇总，日志故障不得遮蔽原异常。 */
+        private void finish(boolean success) {
+            if(!success)prepare.failed();prepare.close();
+            long totalMs=java.util.concurrent.TimeUnit.NANOSECONDS.toMillis(System.nanoTime()-started);
+            if(success && totalMs<250) return;
+            try {
+                var summaries=new LinkedHashMap<String,String>();
+                providers.forEach((name,value)->summaries.put(name,value.summary()));
+                LOG.warn("Appointment work facts diagnostic: totalMs={}, firstlegCalls={}, firstlegRequests={}, firstlegMs={}, providers={}, failedStage={}, requestId={}, traceId={}, scopeId={}",
+                    totalMs,firstleg.calls,firstleg.requests,firstleg.millis(),summaries,success?"NONE":stage,org.slf4j.MDC.get("requestId"),org.slf4j.MDC.get("traceId"),currentScopeId());
+            } catch(Throwable diagnosticFailure) { /* 仅忽略诊断故障，原事实错误仍沿原路径抛出。 */ }
+        }
+    }
+    /** 仅包含数量和单调时钟耗时的累加器。 */
+    private static final class CallStatistics {
+        private int calls,requests;private long elapsed;
+        /** 输出整毫秒，未计入网络之后的事实完整性校验。 */
+        private long millis() { return java.util.concurrent.TimeUnit.NANOSECONDS.toMillis(elapsed); }
+        /** 固定字段格式便于日志汇总，不包含任何请求或响应内容。 */
+        private String summary() { return "calls="+calls+",requests="+requests+",ms="+millis(); }
+    }
+    /** 每次生成建立独立读取器；没有实际需求读取时不引入原业务依赖。 */
+    public RequirementReader openRequirements() {
+        return new RequirementReader() {
+            private RequirementReader reader;
+            /** 首次实际读取才取得原域作用域，保留每份需求的完整性校验。 */
+            public List<Requirement> read(ContainerSource source,Flow effectiveFlow) {
+                if(reader==null) {
+                    var provider=requirements.getIfAvailable();
+                    if(provider==null) throw unavailable("原预约需求与批次清单适配尚未接入，不能生成不完整工作清单");
+                    reader=provider.openRequirements();
+                }
+                var result=reader.read(source,effectiveFlow);
+                if(result==null || result.isEmpty()) throw unavailable("原预约需求清单缺失，不能以空清单完成路线生成");
+                return List.copyOf(result);
+            }
+        };
     }
     static void append(Map<String,Fact> target,List<FactRequest> requests,List<Fact> facts) {
         if(facts==null || facts.size()!=requests.size()) throw unavailable("工作事实响应不完整");
-        var expected=new HashSet<>(requests.stream().map(FactRequest::workItemKey).toList());
+        var requestByKey=new HashMap<String,FactRequest>();requests.forEach(r->requestByKey.put(r.workItemKey(),r));
+        var expected=new HashSet<>(requestByKey.keySet());
         for(var fact:facts) {
             if(fact==null || !expected.remove(fact.workItemKey()) || fact.fingerprint()==null || fact.fingerprint().isBlank() || fact.impactToken()==null || fact.impactToken().isBlank() || fact.planStatus()==null || fact.executionStatus()==null
                 || fact.readPermissions()==null || fact.readPermissions().isEmpty() || fact.actionPermissions()==null || fact.blockReasons()==null || fact.missingFields()==null || fact.references()==null)
                 throw unavailable("工作事实缺少身份、版本或资格");
             if(fact.executionStatus()==ExecutionStatus.COMPLETED && fact.actual()==null) throw unavailable("完成事实缺少实际时间");
+            var request=requestByKey.get(fact.workItemKey());
+            if(request.type()==Type.TRANSPORT && request.flow()==Flow.TRANSFER && (fact.transportPlanImpactToken()==null || fact.transportPlanImpactToken().isBlank()))
+                throw unavailable("共享车次事实缺少独立计划影响版本");
             if(fact.actual()!=null) validateActual(fact.actual());
             if(!fact.planExists() && (fact.target()!=null || fact.confirmed()!=null || fact.planStatus()==PlanStatus.CONFIRMED)) throw unavailable("原计划存在性与计划结果冲突");
             validateSourceSlot(fact.target()); validateSourceSlot(fact.confirmed());

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkFactGateway.java

@@ -20,13 +20,15 @@ public interface AppointmentWorkFactGateway {
         ExecutionStatus executionStatus, Slot target, Slot confirmed, Actual actual, String timezone,
         String businessNo, String tripKey, List<String> readPermissions, List<String> actionPermissions,
         Action action, List<String> blockReasons, List<String> missingFields, List<BusinessReference> references,
-        Responsibility responsibility) {
+        Responsibility responsibility, String transportPlanImpactToken) {
-        public boolean arranged() { return planStatus == PlanStatus.CONFIRMED || planStatus == PlanStatus.NOT_REQUIRED || target != null; }
+        /** Shared fleet transport separates its own cargo impact from changes affecting receiving appointments. */
+        public String dependentImpactToken() { return transportPlanImpactToken==null?impactToken:transportPlanImpactToken; }
+        public boolean arranged() { return planStatus == PlanStatus.CONFIRMED || planStatus == PlanStatus.NOT_REQUIRED || target != null || confirmed != null; }
     }
     SourcePage discover(String after, int size);
     ContainerSource container(String containerBookingId);
-    /** Original appointment core supplies the complete current obligation/batch manifest, including explicit replacement keys. */
+    /** 建立本次原预约需求读取作用域，保持完整批次及明确替代关系。 */
-    List<Requirement> requirements(ContainerSource source,Flow effectiveFlow);
+    RequirementReader openRequirements();
     Map<String, Fact> facts(List<AppointmentWorkState> states);
     Owner owner(String id, Actor actor);
     Responsibility supplier(String id);
@@ -39,5 +41,7 @@ public interface AppointmentWorkFactGateway {
     /** IAM-backed active platform operators; display names supplied by callers are never trusted. */
     interface OwnerDirectory { Owner activePlatformOwner(String id); }
     interface SupplierDirectory { Responsibility activeSupplier(String id); }
-    interface RequirementProvider { List<Requirement> requirements(ContainerSource source,Flow effectiveFlow); }
+    /** 单次生成显式复用目录，不跨请求保存来源事实。 */
+    interface RequirementReader { List<Requirement> read(ContainerSource source,Flow effectiveFlow); }
+    interface RequirementProvider { RequirementReader openRequirements(); }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkFollowupInheritance.java

@@ -0,0 +1,72 @@
+package com.baiyue.lastleg.appointmentwork;
+
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+import java.time.LocalDate;
+import java.util.*;
+import static com.baiyue.lastleg.appointmentwork.AppointmentWorkModels.*;
+import static com.baiyue.lastleg.appointmentwork.AppointmentWorkPolicy.*;
+
+/** A future work key may receive an audited follow-up seed before source discovery creates its work row. */
+@Component
+public class AppointmentWorkFollowupInheritance {
+    public record Member(String batchKey,String customerId) { }
+    private final AppointmentWorkStore store;
+    private final AppointmentWorkFactGateway.OwnerDirectory directory;
+    public AppointmentWorkFollowupInheritance(AppointmentWorkStore store,AppointmentWorkFactGateway.OwnerDirectory directory) {
+        this.store=store;this.directory=directory;
+    }
+    public AppointmentWorkStore.Followup resolve(String ownerId,LocalDate nextFollowupDate) {
+        if(ownerId==null || ownerId.isBlank()) throw bad("请选择有效平台负责人");
+        var owner=directory.activePlatformOwner(ownerId);
+        if(owner==null || !ownerId.equals(owner.id()) || owner.name()==null || owner.name().isBlank()) throw bad("负责人不是有效平台操作人员");
+        return new AppointmentWorkStore.Followup(owner,nextFollowupDate);
+    }
+    @Transactional(propagation=Propagation.MANDATORY)
+    public void seed(Member original,Member later,AppointmentWorkStore.Followup followup,String operatorId) {
+        key(original);key(later);
+        if(!original.customerId().equals(later.customerId()) || original.batchKey().equals(later.batchKey())) throw bad("跟进继承必须来自同一客户的原批次和新批次");
+        if(followup==null || followup.owner()==null || followup.owner().id()==null || followup.owner().id().isBlank() || followup.owner().name()==null || followup.owner().name().isBlank()) throw bad("后送跟进缺少真实负责人");
+        store.lock();write(later,followup,operatorId);
+    }
+    @Transactional(propagation=Propagation.MANDATORY)
+    public void inherit(List<Member> originals,List<Member> successors,String operatorId) {
+        validate(originals);validate(successors);store.lock();
+        var values=new HashMap<String,Set<AppointmentWorkStore.Followup>>();
+        for(var original:originals) {
+            var key=key(original);var state=store.find(key);
+            var current=state==null?store.inheritedFollowup(key):new AppointmentWorkStore.Followup(state.getOwner(),state.getFollowupDate());
+            if(current!=null) values.computeIfAbsent(original.customerId(),ignored->new HashSet<>()).add(current);
+        }
+        // Validate every target before writing; caller transaction still supplies rollback for all original-domain writes.
+        for(var successor:successors) if(values.getOrDefault(successor.customerId(),Set.of()).size()>1)
+            throw conflict("合批来源的负责人或跟进日期不同，请先在原工作事项统一后再合批");
+        for(var successor:successors) {
+            var current=values.getOrDefault(successor.customerId(),Set.of());
+            if(!current.isEmpty()) write(successor,current.iterator().next(),operatorId);
+        }
+    }
+    private void write(Member target,AppointmentWorkStore.Followup followup,String operatorId) {
+        if(operatorId==null || operatorId.isBlank()) throw bad("跟进继承缺少真实操作人");
+        var key=key(target);var state=store.find(key);var previous=store.inheritedFollowup(key);
+        if(state!=null) {
+            if(Objects.equals(state.getOwner(),followup.owner()) && Objects.equals(state.getFollowupDate(),followup.nextFollowupDate())) return;
+            throw conflict("目标工作已存在独立跟进，不能用继承覆盖");
+        }
+        if(previous!=null) {
+            if(previous.equals(followup)) return;
+            throw conflict("目标批次已有不同的跟进继承记录");
+        }
+        var future=new AppointmentWorkState();future.setWorkItemKey(key);
+        store.history(future,new Actor(operatorId,null,Set.of()),"FOLLOWUP_INHERITED","继承原送仓事项的负责人及跟进日期",null,null,followup);
+    }
+    private static String key(Member member) {
+        if(member==null || member.batchKey()==null || !member.batchKey().matches("FBA_APPOINTMENT:[1-9][0-9]*") || member.customerId()==null || member.customerId().isBlank()) throw bad("跟进继承缺少真实批次客户范围");
+        return AppointmentWorkPolicy.key("BATCH:"+member.batchKey(),Type.DELIVERY,customerRequirement(member.batchKey(),member.customerId()));
+    }
+    private static void validate(List<Member> members) {
+        if(members==null || members.isEmpty() || members.size()>2000 || new HashSet<>(members).size()!=members.size()) throw bad("跟进继承范围须为1至2000个不重复客户批次");
+        members.forEach(AppointmentWorkFollowupInheritance::key);
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkMapper.java

@@ -44,6 +44,8 @@ public interface AppointmentWorkMapper {
     }
     @Select("SELECT * FROM ll_appointment_work_commitment WHERE entity_key=#{key} FOR UPDATE") CommitmentRow lockCommitment(String key);
     @Select("SELECT * FROM ll_appointment_work_commitment WHERE entity_key=#{key}") CommitmentRow commitment(String key);
+    @Select("<script>SELECT * FROM ll_appointment_work_commitment WHERE entity_key IN <foreach collection='keys' item='key' open='(' separator=',' close=')'>#{key}</foreach></script>")
+    List<CommitmentRow> commitments(@Param("keys") List<String> keys);
     @Insert("INSERT INTO ll_appointment_work_commitment(entity_key,state_json,impact_version) VALUES(#{key},#{json},0)")
     int insertCommitment(@Param("key") String key,@Param("json") String json);
     @Update("UPDATE ll_appointment_work_commitment SET state_json=#{json},impact_version=#{version} WHERE entity_key=#{key}")
@@ -64,4 +66,6 @@ public interface AppointmentWorkMapper {
         VALUES(#{id},#{workItemKey},#{operatorId},#{operatorName},#{action},#{summary},#{commandKey},#{requestHash},#{responseJson},#{occurredAt})
         """) int insertHistory(History row);
     @Select("SELECT * FROM ll_appointment_work_history WHERE work_item_key=#{key} ORDER BY occurred_at DESC,id DESC LIMIT 1001") List<History> selectHistory(@Param("key") String key);
+    @Select("SELECT * FROM ll_appointment_work_history WHERE work_item_key=#{key} AND action='FOLLOWUP_INHERITED' ORDER BY occurred_at DESC,id DESC LIMIT 1")
+    History inheritedFollowup(String key);
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkModels.java

@@ -51,6 +51,8 @@ public final class AppointmentWorkModels {
     public record HistoryEntry(Instant occurredAt, String operatorName, String action, String summary) { }
     public record WorkDetail(WorkItem item, List<WorkItem> relatedItems,
         List<BusinessReference> references, List<HistoryEntry> history, Review review, RequirementDetails requirement, ReturnHandoff returnHandoff) { }
+    public record BatchWorkCandidate(String customerId,String workItemKey,String batchNo) { }
+    public record BatchWorkResolution(String batchKey,String customerId,WorkDetail detail,List<BatchWorkCandidate> candidates) { }
     public record Review(int version,List<String> reasons) { }
     public record RequirementDetails(boolean bookingRequired,String receivingRequirements,String reason) { }
     public enum ResponsibilityKind { USER, SUPPLIER, EXTERNAL }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkPolicy.java

@@ -14,6 +14,15 @@ public final class AppointmentWorkPolicy {
     public static final ZoneId REMINDER_ZONE=ZoneId.of("America/Los_Angeles");
     public static final String ORDER_READ="platform:overseas-warehouse:last-mile-order:list";
     private AppointmentWorkPolicy() { }
+    public static String customerRequirement(String batchKey,String customerId) {
+        if(batchKey==null || customerId==null || customerId.isBlank()) throw unavailable("送仓需求缺少批次或客户身份");
+        return batchKey+"|CUSTOMER:"+customerId;
+    }
+    public static String deliveryCustomer(List<SourceReference> sources) {
+        var customers=sources.stream().map(SourceReference::customerId).distinct().toList();
+        if(customers.size()!=1 || customers.get(0)==null || customers.get(0).isBlank()) throw unavailable("送仓事项须明确唯一客户货物范围");
+        return customers.get(0);
+    }
     public static String key(String containerId,Type type,String requirementKey) {
         return "AW-"+type.name()+"-"+digest(containerId+"\n"+Objects.toString(requirementKey,"")).substring(0,32);
     }
@@ -89,6 +98,7 @@ public final class AppointmentWorkPolicy {
         var today=LocalDate.now(clock.withZone(timezone==null?REMINDER_ZONE:zone(timezone)));
         if(timezone==null) missing.add("跟进日期按业务默认时区America/Los_Angeles判断；作业时区待核实");
         if(state.getOwner()==null && execution!=ExecutionStatus.COMPLETED) missing.add("负责人待分配");
+        if(state.getFollowupDate()==null && execution!=ExecutionStatus.COMPLETED && !state.isRetired()) missing.add("下次跟进日期待安排");
         var overdue=new ArrayList<String>();
         if(execution!=ExecutionStatus.COMPLETED && !state.isRetired()) {
             if(state.getFollowupDate()!=null && state.getFollowupDate().isBefore(today)) overdue.add("跟进日期已过");

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkQueryService.java

@@ -7,7 +7,9 @@ import java.time.*;
 import java.time.temporal.ChronoUnit;
 import java.util.*;
 import java.util.function.Function;
+import java.util.function.Predicate;
 import java.util.stream.Collectors;
+import static com.baiyue.lastleg.appointmentwork.diagnostics.AppointmentWorkDiagnostics.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkModels.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkFactGateway.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkPolicy.*;
@@ -23,19 +25,56 @@ public class AppointmentWorkQueryService {
     AppointmentWorkQueryService(AppointmentWorkStore store,AppointmentWorkFactGateway facts,Clock clock) { this.store=store; this.facts=facts; this.clock=clock; }
     record Snapshot(List<AppointmentWorkState> states,Map<String,Fact> facts,List<WorkItem> items) { }
     Snapshot snapshot(Actor actor) {
+        return snapshot(actor,s->true,true);
+    }
+    /** 按原顺序构造完整快照，计时只分离读取、筛选、事实及投影。 */
+    private Snapshot snapshot(Actor actor,Predicate<AppointmentWorkState> selected,boolean includeNext) {
+        observeTransaction();var timing=span(Stage.QUERY_GUARD);
+        try {
         String scopeVersion=store.requireInitialized();
+        timing.close();timing=span(Stage.QUERY_DISCOVER);
         if(!Objects.equals(scopeVersion,facts.discover(null,1).scopeVersion())) throw conflict("已开船工作范围变化，请先完成服务端同步");
+        timing.close();timing=span(Stage.QUERY_STORE);
         var all=store.all();
-        var states=all.stream().filter(s->!s.isRetired()).toList();
+        timing.close();timing=span(Stage.QUERY_SELECT);
+        var stateByKey=all.stream().collect(Collectors.toMap(AppointmentWorkState::getWorkItemKey,Function.identity()));
+        var selectedKeys=all.stream().filter(s->!s.isRetired() && selected.test(s)).map(AppointmentWorkState::getWorkItemKey).collect(Collectors.toSet());
+        var needed=new HashSet<>(selectedKeys);
+        if(includeNext) {
+            var pending=new ArrayDeque<>(selectedKeys);
+            while(!pending.isEmpty()) {
+                var state=stateByKey.get(pending.remove());
+                for(var key:effectiveKeys(state.getPrerequisites(),stateByKey)) if(stateByKey.containsKey(key) && needed.add(key)) pending.add(key);
+            }
+        }
+        var states=all.stream().filter(s->!s.isRetired() && needed.contains(s.getWorkItemKey())).toList();
+        timing.close();timing=span(Stage.QUERY_FACTS);
         var current=facts.facts(states);
+        timing.close();timing=span(Stage.QUERY_PROJECT);
         var visible=states.stream().filter(s->canRead(s,current.get(s.getWorkItemKey()),actor)).toList();
         var items=visible.stream().map(s->project(s,current.get(s.getWorkItemKey()),actor,clock)).toList();
         var byKey=items.stream().collect(Collectors.toMap(WorkItem::workItemKey,Function.identity()));
-        var stateByKey=all.stream().collect(Collectors.toMap(AppointmentWorkState::getWorkItemKey,Function.identity()));
+        timing.close();timing=span(Stage.QUERY_NEXT);
-        return new Snapshot(all,current,items.stream().map(i->withNext(i,next(i,byKey,stateByKey,new HashSet<>()))).toList());
+        return new Snapshot(all,current,items.stream().filter(i->selectedKeys.contains(i.workItemKey()))
+            .map(i->includeNext?withNext(i,next(i,byKey,stateByKey,new HashSet<>())):i).toList());
+        } catch(RuntimeException|Error error){timing.failed();throw error;} finally{timing.close();}
     }
     private Action next(WorkItem item,Map<String,WorkItem> items,Map<String,AppointmentWorkState> states,Set<String> visited) {
-        if(!visited.add(item.workItemKey()) || item.blockReasons().isEmpty() || item.reviewRequired()) return item.nextAction();
+        if(!visited.add(item.workItemKey()) || item.reviewRequired()) return item.nextAction();
+        if(item.type()==Type.DELIVERY && item.executionStatus()!=ExecutionStatus.COMPLETED && item.blockReasons().isEmpty()
+            && (item.planStatus()==PlanStatus.CONFIRMED || item.planStatus()==PlanStatus.NOT_REQUIRED)) {
+            for(var key:effectiveKeys(states.get(item.workItemKey()).getPrerequisites(),states)) {
+                var transport=items.get(key);
+                if(transport==null || transport.type()!=Type.TRANSPORT || transport.executionStatus()==ExecutionStatus.COMPLETED) continue;
+                var action=transport.nextAction();
+                if(action==null) continue;
+                if(action.code()==ActionCode.RESOLVE_REVIEW)
+                    return new Action(action.code(),"先复核车辆安排",transport.workItemKey(),action.target());
+                if(action.code()==ActionCode.ARRANGE_TRANSPORT && action.target() instanceof TripTarget target)
+                    return new Action(action.code(),target.tripId()==null?"继续安排本批车辆":"核对本车发车安排",transport.workItemKey(),target);
+            }
+        }
+        if(item.blockReasons().isEmpty()) return item.nextAction();
         for(var key:effectiveKeys(states.get(item.workItemKey()).getPrerequisites(),states)) {
             var prior=items.get(key);
             if(prior!=null && prior.executionStatus()!=ExecutionStatus.COMPLETED && (prior.reviewRequired() || prior.planStatus()==PlanStatus.UNPLANNED || prior.planStatus()==PlanStatus.AWAITING_REPLY)) {
@@ -45,23 +84,34 @@ public class AppointmentWorkQueryService {
         }
         return item.nextAction();
     }
+    /** 完整快照之后单独统计汇总耗时，不改变待办筛选语义。 */
     public Summary summary(Actor actor) {
-        var items=snapshot(actor).items().stream().filter(i->i.executionStatus()!=ExecutionStatus.COMPLETED).toList();
+        var snapshotItems=snapshot(actor,s->true,false).items();
+        return measure(Stage.QUERY_FINAL,()->{
+        var items=snapshotItems.stream().filter(i->i.executionStatus()!=ExecutionStatus.COMPLETED).toList();
         return new Summary(items.size(),items.stream().filter(i->followToday(i,clock)).count(),items.stream().filter(i->!i.overdueReasons().isEmpty()).count(),items.stream().filter(i->i.calendarDate()==null).count(),items.stream().filter(WorkItem::reviewRequired).count());
+        });
     }
+    /** 日历最终分组保持原顺序，单独记录快照后处理。 */
     public CalendarResult calendar(LocalDate from,LocalDate to,Flow flow,Set<Type> types,Actor actor) {
         if(from==null || to==null || to.isBefore(from) || ChronoUnit.DAYS.between(from,to)>=62) throw bad("日历范围须为1至62天");
         if(types!=null && types.contains(Type.ROUTE)) throw bad("路线待确认需求请从全局待办查看");
-        var items=snapshot(actor).items().stream().filter(i->i.type()!=Type.ROUTE && i.calendarDate()!=null && !i.calendarDate().isBefore(from) && !i.calendarDate().isAfter(to))
+        var snapshotItems=snapshot(actor,s->s.getType()!=Type.ROUTE && matches(s,flow,types,null),false).items();
+        return measure(Stage.QUERY_FINAL,()->{
+        var items=snapshotItems.stream().filter(i->i.type()!=Type.ROUTE && i.calendarDate()!=null && !i.calendarDate().isBefore(from) && !i.calendarDate().isAfter(to))
             .filter(i->flow==null || i.flow()==flow).filter(i->types==null || types.contains(i.type())).toList();
         var groups=items.stream().collect(Collectors.groupingBy(WorkItem::calendarDate,TreeMap::new,Collectors.toList()));
         var days=groups.entrySet().stream().map(e->new DayAggregate(e.getKey(),e.getValue().size(),e.getValue().stream().collect(Collectors.groupingBy(WorkItem::type,()->new EnumMap<>(Type.class),Collectors.counting())),counts(e.getValue()))).toList();
         return new CalendarResult(from,to,items.size(),counts(items),days);
+        });
     }
+    /** 保留事实核对之后的最终过滤排序分页，仅拆出其耗时。 */
     public PageResult<WorkItem> items(View view,int page,int size,LocalDate date,Flow flow,Set<Type> types,String containerId,Bucket bucket,String keyword,Actor actor) {
         if(page<1 || size<1 || size>100 || keyword!=null && keyword.length()>128) throw bad("分页或搜索条件无效");
         var word=keyword==null?"":keyword.trim().toLowerCase(Locale.ROOT);
-        var items=snapshot(actor).items().stream()
+        var snapshotItems=snapshot(actor,s->matches(s,flow,types,containerId) && candidate(s,view),true).items();
+        return measure(Stage.QUERY_FINAL,()->{
+        var items=snapshotItems.stream()
             .filter(i->date!=null || i.executionStatus()!=ExecutionStatus.COMPLETED)
             .filter(i->date==null || date.equals(i.calendarDate()))
             .filter(i->flow==null || flow==i.flow()).filter(i->types==null || types.contains(i.type()))
@@ -72,11 +122,30 @@ public class AppointmentWorkQueryService {
             .sorted(Comparator.comparing(WorkItem::followupDate,Comparator.nullsLast(Comparator.naturalOrder())).thenComparing(WorkItem::workItemKey)).toList();
         long offset=(long)(page-1)*size; int start=(int)Math.min(offset,items.size());
         return new PageResult<>(items.subList(start,Math.min(start+size,items.size())),page,size,items.size(),(items.size()+size-1L)/size);
+        });
     }
+    public BatchWorkResolution resolveBatch(String batchKey,String customerId,Actor actor) {
+        if(batchKey==null || !batchKey.matches("(?:FBA_APPOINTMENT|DISPATCH):[1-9][0-9]*")) throw bad("请提供原业务返回的完整批次键");
+        if(customerId!=null && customerId.isBlank()) throw bad("客户身份不能为空");
+        if(!Objects.equals(store.requireInitialized(),facts.discover(null,1).scopeVersion())) throw conflict("已开船工作范围变化，请先完成服务端同步");
+        var matches=store.all().stream().filter(s->!s.isRetired() && s.getType()==Type.DELIVERY && batchKey.equals(s.getBatchKey()))
+            .filter(s->customerId==null || customerId.equals(deliveryCustomer(s.getSources()))).toList();
+        if(matches.isEmpty()) throw missing("当前批次的送仓事项尚不存在，请先同步当前批次");
+        var current=facts.facts(matches);
+        var visible=matches.stream().filter(s->canRead(s,current.get(s.getWorkItemKey()),actor)).toList();
+        if(visible.isEmpty()) throw forbidden("无权读取关联来源");
+        var candidates=visible.stream().map(s->new BatchWorkCandidate(deliveryCustomer(s.getSources()),s.getWorkItemKey(),s.getBatchNo())).sorted(Comparator.comparing(BatchWorkCandidate::customerId)).toList();
+        if(candidates.stream().map(BatchWorkCandidate::customerId).distinct().count()!=candidates.size()) throw conflict("同一批次客户存在重复送仓事项");
+        if(candidates.size()>1) return new BatchWorkResolution(batchKey,null,null,candidates);
+        var selected=candidates.get(0);
+        return new BatchWorkResolution(batchKey,selected.customerId(),detail(selected.workItemKey(),actor),candidates);
+    }
+    /** 保留详情完整快照与退休事实读取，历史查询单独观察。 */
     public WorkDetail detail(String key,Actor actor) {
-        var snapshot=snapshot(actor); var state=store.get(key);
+        var snapshot=snapshot(actor); var state=measure(Stage.DETAIL_STORE,()->store.get(key));
         var fact=snapshot.facts().get(key);
-        if(state.isRetired() && state.getType()!=Type.ROUTE) fact=facts.facts(List.of(state)).get(key);
+        if(state.isRetired() && state.getType()!=Type.ROUTE) fact=measure(Stage.DETAIL_FACTS,()->facts.facts(List.of(state))).get(key);
+        try(var timing=span(Stage.DETAIL_PROJECT)) {
         if(!canRead(state,fact,actor)) throw forbidden("无权读取关联来源");
         var item=state.isRetired()?project(state,fact,actor,clock):snapshot.items().stream().filter(i->i.workItemKey().equals(key)).findFirst().orElseThrow(()->missing("事项不存在"));
         var relatedKeys=new HashSet<>(state.getPrerequisites()); relatedKeys.addAll(state.getReplacementKeys());
@@ -84,11 +153,27 @@ public class AppointmentWorkQueryService {
         relatedKeys.addAll(effectiveKeys(relatedKeys,statesByKey));
         snapshot.states().stream().filter(s->effectiveKeys(s.getPrerequisites(),statesByKey).contains(key)).map(AppointmentWorkState::getWorkItemKey).forEach(relatedKeys::add);
         var refs=new ArrayList<>(state.getReferences()); if(fact!=null) refs.addAll(fact.references());
-        return new WorkDetail(item,snapshot.items().stream().filter(i->relatedKeys.contains(i.workItemKey())).toList(),refs.stream().distinct().toList(),store.history(key),
+        return new WorkDetail(item,snapshot.items().stream().filter(i->relatedKeys.contains(i.workItemKey())).toList(),refs.stream().distinct().toList(),measure(Stage.DETAIL_HISTORY,()->store.history(key)),
             state.isReviewRequired()?new Review(state.getReviewVersion(),List.of(Objects.toString(state.getReviewReason(),"关联安排变化"))):null,
             requirementOwned(state,fact)?new RequirementDetails(state.isBookingRequired(),Objects.toString(state.getReceivingRequirements(),""),state.getRequirementReason()):null,state.getReturnHandoff());
+        }
     }
     WorkItem current(AppointmentWorkState state,Fact fact,Actor actor) { return project(state,fact,actor,clock); }
+    private boolean matches(AppointmentWorkState state,Flow flow,Set<Type> types,String containerId) {
+        return (flow==null || state.getFlow()==flow) && (types==null || types.contains(state.getType()))
+            && (containerId==null || (state.getContainers().isEmpty()?containerId.equals(state.getContainerBookingId()):state.getContainers().stream().anyMatch(c->containerId.equals(c.containerBookingId()))));
+    }
+    private boolean candidate(AppointmentWorkState state,View view) {
+        // Follow-up dates and handoffs belong to the work state. Use the latest possible local day,
+        // not its stored timezone: the authoritative fact can supply a different current zone.
+        // Exact local-day, completion and permission checks still run after the live fact read.
+        return switch(view) {
+            case FOLLOW_TODAY -> pendingHandoff(state) || state.getFollowupDate()!=null
+                && !state.getFollowupDate().isAfter(LocalDate.now(clock.withZone(ZoneOffset.MAX)));
+            case REVIEW -> state.isReviewRequired();
+            default -> true;
+        };
+    }
     private String searchable(WorkItem i) {
         return String.join(" ",Objects.toString(i.businessNo(),""),Objects.toString(i.batchNo(),""),Objects.toString(i.originName(),""),Objects.toString(i.destinationName(),""),i.containers().stream().map(c->Objects.toString(c.containerNo(),"")+" "+Objects.toString(c.bookingNo(),"")).collect(Collectors.joining(" "))).toLowerCase(Locale.ROOT);
     }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkState.java

@@ -36,6 +36,7 @@ public class AppointmentWorkState {
     private String reviewReason;
     private String observedFingerprint;
     private String observedImpactToken;
+    private String observedDependentImpactToken;
     private boolean observedArranged;
     private Responsibility responsibility;
     private ReturnHandoff returnHandoff;

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkStore.java

@@ -1,23 +1,59 @@
 package com.baiyue.lastleg.appointmentwork;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.slf4j.MDC;
 import org.springframework.stereotype.Component;
 import java.time.*;
 import java.util.*;
+import static com.baiyue.lastleg.appointmentwork.diagnostics.AppointmentWorkDiagnostics.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkModels.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkPolicy.*;
 
 @Component
 public class AppointmentWorkStore {
+    private static final Logger LOG = LoggerFactory.getLogger(AppointmentWorkStore.class);
     public static final int MAX_ITEMS=10000;
     private final AppointmentWorkMapper mapper;
     private final ObjectMapper json;
     public AppointmentWorkStore(AppointmentWorkMapper mapper,ObjectMapper json) { this.mapper=mapper; this.json=json; }
-    public AppointmentWorkMapper.Guard lock() {
+    /** 只测量守卫更新语句，不改变锁、事务或版本，用于区分慢写是否卡在该语句。 */
-        var guard=mapper.lockGuard(); if(guard==null) throw unavailable("工作事项DDL尚未集成"); return guard;
+    public void invalidateRequirements() {
+        long started = System.nanoTime();
+        try {
+            if (measure(Stage.GUARD_UPDATE,mapper::invalidateRequirements) != 1) throw unavailable("工作事项同步守卫未初始化");
+        } finally {
+            long elapsedMs = java.util.concurrent.TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - started);
+            if (elapsedMs >= 250) {
+                // 语句耗时可能包含等锁或连接等待，不能仅凭日志认定具体锁根因；不记录请求业务载荷。
+                try { LOG.warn("Appointment work guard update slow: elapsedMs={}, requestId={}, traceId={}, scopeId={}",
+                    elapsedMs, MDC.get("requestId"), MDC.get("traceId"), currentScopeId());
+                } catch(Throwable ignored) { /* 诊断输出失败不得覆盖原守卫结果或异常。 */ }
+            }
+        }
     }
+    /** 测量守卫读取加锁耗时，保留原有锁和失败行为，覆盖尚未进入更新语句的慢命令。 */
+    public AppointmentWorkMapper.Guard lock() {
+        long started = System.nanoTime();
+        try {
+            observeTransaction();
+            var guard = measure(Stage.GUARD_LOCK,mapper::lockGuard);
+            if (guard == null) throw unavailable("工作事项DDL尚未集成");
+            return guard;
+        } finally {
+            long elapsedMs = java.util.concurrent.TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - started);
+            if (elapsedMs >= 250) {
+                // 耗时包含连接及语句执行，单条日志不能区分具体等待原因，不记录业务载荷。
+                try { LOG.warn("Appointment work guard lock slow: elapsedMs={}, requestId={}, traceId={}, scopeId={}",
+                    elapsedMs, MDC.get("requestId"), MDC.get("traceId"), currentScopeId());
+                } catch(Throwable ignored) { /* 诊断输出失败不得覆盖原守卫结果或异常。 */ }
+            }
+        }
+    }
+    /** 完整性守卫保持原语义，读取耗时与事务完成只作诊断。 */
     public String requireInitialized() {
-        var guard=mapper.guard();
+        observeTransaction();var guard=measure(Stage.GUARD_READ,mapper::guard);
         if(guard==null || !guard.isInitialized()) throw unavailable("完整工作范围尚未完成同步，不能显示零项");
         if(guard.getRequirementVersion()!=guard.getSynchronizedRequirementVersion()) throw conflict("预约批次或运输关联已变化，服务端正在协调完整工作清单");
         return guard.getScopeVersion();
@@ -32,6 +68,11 @@ public class AppointmentWorkStore {
     public AppointmentWorkState get(String key) {
         var row=mapper.get(key); if(row==null) throw missing("事项不存在"); return decode(row);
     }
+    public AppointmentWorkState find(String key) { var row=mapper.get(key);return row==null?null:decode(row); }
+    public record Followup(Owner owner,LocalDate nextFollowupDate) { }
+    public Followup inheritedFollowup(String key) {
+        var row=mapper.inheritedFollowup(key);return row==null?null:read(row.getResponseJson(),Followup.class);
+    }
     public void insert(AppointmentWorkState state) { mapper.insert(row(state)); }
     public void save(AppointmentWorkState state) {
         state.setVersion(state.getVersion()+1);

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkSyncService.java

@@ -2,45 +2,58 @@ package com.baiyue.lastleg.appointmentwork;
 
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import java.time.*;
 import java.util.*;
 import java.util.function.Function;
 import java.util.stream.Collectors;
+import static com.baiyue.lastleg.appointmentwork.diagnostics.AppointmentWorkDiagnostics.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkModels.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkFactGateway.*;
 import static com.baiyue.lastleg.appointmentwork.AppointmentWorkPolicy.*;
 
 @Service
 public class AppointmentWorkSyncService {
+    private static final Logger LOG=LoggerFactory.getLogger(AppointmentWorkSyncService.class);
     private static final Actor SYSTEM=new Actor("appointment-work-sync","服务端工作范围同步",Set.of(LIST,ORDER_READ));
     private final AppointmentWorkStore store;
     private final AppointmentWorkFactGateway gateway;
     public AppointmentWorkSyncService(AppointmentWorkStore store,AppointmentWorkFactGateway gateway) { this.store=store; this.gateway=gateway; }
-    /** Called by trusted server orchestration, never by GET or by opening a particular container. */
+    /** 服务端按完整范围同步；同一守卫事务内复用工作集，GET 不触发写入。 */
     @Transactional
     public SyncResult synchronize(SyncRequest request) {
         if(request==null || request.size()<1 || request.size()>100) throw bad("同步批次须为1至100柜");
+        observeTransaction();var timing=new SyncTiming();boolean success=false;
+        try {
         var guard=store.lock();
         if(request.afterContainerBookingId()!=null && !Objects.equals(guard.getScanCursor(),request.afterContainerBookingId())) throw conflict("来源同步游标已变化，请从首批重新核对");
+        timing.next(SyncPhase.DISCOVER);
         var page=gateway.discover(request.afterContainerBookingId(),request.size());
+        timing.pageContainers=page.containers().size();timing.complete=page.complete();
         if(request.afterContainerBookingId()==null) { guard.setScanScopeVersion(page.scopeVersion()); guard.setScanRequirementVersion(guard.getRequirementVersion()); }
         else if(!Objects.equals(guard.getScanScopeVersion(),page.scopeVersion())) throw conflict("来源范围扫描中变化，请从首批重试");
         else if(guard.getScanRequirementVersion()!=guard.getRequirementVersion()) throw conflict("预约需求扫描中变化，请从首批重试");
+        timing.next(SyncPhase.GENERATE);
+        // 保留全部历史与稳定键顺序；逐柜更新立即进入本次工作集，不跨事务缓存。
+        var known=workingSet();
+        var requirementReader=gateway.openRequirements();
         int created=0; var ids=new HashSet<String>();
         for(var source:page.containers()) {
             validateSource(source);
             if(!ids.add(source.containerBookingId())) throw unavailable("来源响应重复柜次");
-            var existing=store.container(source.containerBookingId());
+            var existing=known.values().stream().filter(s->source.containerBookingId().equals(s.getContainerBookingId())
+                || s.getContainers().stream().anyMatch(c->source.containerBookingId().equals(c.containerBookingId()))).toList();
             if(existing.isEmpty()) {
                 if(source.establishedFlow()==Flow.UNKNOWN) {
-                    var route=create(source,Type.ROUTE,null,Flow.UNKNOWN); route.setFollowupDate(LocalDate.now(route.getTimezone()==null?REMINDER_ZONE:zone(route.getTimezone()))); store.insert(route); created++;
+                    var route=create(source,Type.ROUTE,null,Flow.UNKNOWN); route.setFollowupDate(LocalDate.now(route.getTimezone()==null?REMINDER_ZONE:zone(route.getTimezone()))); store.insert(route); known.put(route.getWorkItemKey(),route); created++;
-                } else created+=generate(source,source.establishedFlow(),existing,SYSTEM).size();
+                } else created+=generate(source,source.establishedFlow(),existing,SYSTEM,known,requirementReader).size();
             } else {
                 var activeFlow=existing.stream().filter(s->s.getType()!=Type.ROUTE && !s.isRetired()).map(AppointmentWorkState::getFlow).findFirst().orElse(null);
-                if(activeFlow!=null) created+=generate(source,activeFlow,existing,SYSTEM).size();
+                if(activeFlow!=null) created+=generate(source,activeFlow,existing,SYSTEM,known,requirementReader).size();
                 else for(var route:existing) if(route.getType()==Type.ROUTE && !route.isRetired()) {
                     if(source.establishedFlow()!=Flow.UNKNOWN) {
-                        var generated=generate(source,source.establishedFlow(),existing,SYSTEM); created+=generated.size();
+                        var generated=generate(source,source.establishedFlow(),existing,SYSTEM,known,requirementReader); created+=generated.size();
                         route.setFlow(source.establishedFlow()); route.setRetired(true); route.setRetirementReason("ROUTE_CONFIRMED"); route.setReplacementKeys(generated); store.save(route);
                     } else if(!Objects.equals(route.getSourceVersion(),source.sourceVersion())) {
                         route.setSourceVersion(source.sourceVersion()); route.setContainerNo(source.containerNo()); route.setTimezone(source.timezone()); store.save(route);
@@ -48,18 +61,66 @@ public class AppointmentWorkSyncService {
                 }
             }
         }
-        // An existing row is never deleted because an order left the active source page.
+        // 原来源离开当前页也保留历史事项，未完成工作仍在第二轮按原业务完整核对。
-        // Empty return and other unfinished work continue to read their original authority.
+        timing.next(SyncPhase.TRANSPORT_FACTS);
         var all=new ArrayList<>(store.all());
-        var facts=gateway.facts(all.stream().filter(s->s.getType()!=Type.ROUTE && s.getTripKey()==null && !"BATCH_REPLACED".equals(s.getRetirementReason())).toList());
+        // 首轮仅归并运输关系；保留已关联车次的退役成员，才能发现解绑并恢复原运输事项。
+        var transportItems=all.stream().filter(s->s.getType()==Type.TRANSPORT && s.getTripKey()==null && !"BATCH_REPLACED".equals(s.getRetirementReason())).toList();
+        timing.transportFactsCount=transportItems.size();
+        var facts=gateway.facts(transportItems);
+        timing.next(SyncPhase.RECONCILE);
         reconcileTransport(all,facts);
+        timing.next(SyncPhase.ACTIVE_STORE);
         all=new ArrayList<>(store.all());
-        facts=gateway.facts(all.stream().filter(s->!s.isRetired()).toList());
+        var activeItems=all.stream().filter(s->!s.isRetired()).toList();
+        timing.activeFactsCount=activeItems.size();
+        timing.next(SyncPhase.ACTIVE_FACTS);
+        facts=gateway.facts(activeItems);
+        timing.next(SyncPhase.OBSERVE_CHECKPOINT);
         observe(all,facts,SYSTEM);
         guard.setScanCursor(page.complete()?null:page.nextCursor());
         if(page.complete()) { guard.setInitialized(true); guard.setScopeVersion(page.scopeVersion()); guard.setSynchronizedRequirementVersion(guard.getRequirementVersion()); guard.setCompletedAt(LocalDateTime.now(ZoneOffset.UTC)); }
         store.checkpoint(guard);
+        success=true;
         return new SyncResult(page.containers().size(),created,page.nextCursor(),page.complete());
+        } finally { timing.finish(success); }
+    }
+    /** 固定阶段名用于慢同步定位，不包含来源、游标或异常业务内容。 */
+    private enum SyncPhase { GUARD, DISCOVER, GENERATE, TRANSPORT_FACTS, RECONCILE, ACTIVE_STORE, ACTIVE_FACTS, OBSERVE_CHECKPOINT }
+    /** 仅统计本次方法执行，不含事务代理提交，不能当作精确锁持有时间。 */
+    private static final class SyncTiming {
+        private final Span body=span(Stage.SYNC_BODY);
+        private Span diagnosticPhase=span(Stage.SYNC_GUARD);
+        private final long started=System.nanoTime();
+        private final long[] elapsed=new long[SyncPhase.values().length];
+        private long phaseStarted=started;
+        private SyncPhase phase=SyncPhase.GUARD;
+        private int pageContainers=-1,transportFactsCount=-1,activeFactsCount=-1;
+        private boolean complete;
+        /** 完成前一阶段后开始下一阶段；事实阶段包含紧邻的数据库回读。 */
+        private void next(SyncPhase next) {
+            long now=System.nanoTime();elapsed[phase.ordinal()]+=now-phaseStarted;phaseStarted=now;phase=next;
+            diagnosticPhase.close();diagnosticPhase=span(switch(next){
+                case GUARD->Stage.SYNC_GUARD;case DISCOVER->Stage.SYNC_DISCOVER;case GENERATE->Stage.SYNC_GENERATE;
+                case TRANSPORT_FACTS->Stage.SYNC_TRANSPORT_FACTS;case RECONCILE->Stage.SYNC_RECONCILE;
+                case ACTIVE_STORE->Stage.SYNC_ACTIVE_STORE;case ACTIVE_FACTS->Stage.SYNC_ACTIVE_FACTS;case OBSERVE_CHECKPOINT->Stage.SYNC_CHECKPOINT;});
+        }
+        /** 成功和失败共用一条慢调用摘要，未到达的计数保持为负一。 */
+        private void finish(boolean success) {
+            long now=System.nanoTime();elapsed[phase.ordinal()]+=now-phaseStarted;
+            if(!success){diagnosticPhase.failed();body.failed();}diagnosticPhase.close();body.close();
+            long totalMs=java.util.concurrent.TimeUnit.NANOSECONDS.toMillis(now-started);
+            if(totalMs<250) return;
+            try {
+                // 旧 activeFactsMs 仍包含工作表读取、解析及适配；新增明细不能改变旧指标口径。
+                long activeMs=java.util.concurrent.TimeUnit.NANOSECONDS.toMillis(elapsed[SyncPhase.ACTIVE_STORE.ordinal()]+elapsed[SyncPhase.ACTIVE_FACTS.ordinal()]);
+                LOG.warn("Appointment work sync slow: totalMs={}, guardMs={}, discoverMs={}, generateMs={}, transportFactsMs={}, reconcileMs={}, activeFactsMs={}, activeStoreMs={}, activeAdapterMs={}, observeCheckpointMs={}, pageContainers={}, transportFactsCount={}, activeFactsCount={}, complete={}, failedStage={}, requestId={}, traceId={}, scopeId={}",
+                    totalMs,millis(SyncPhase.GUARD),millis(SyncPhase.DISCOVER),millis(SyncPhase.GENERATE),millis(SyncPhase.TRANSPORT_FACTS),millis(SyncPhase.RECONCILE),activeMs,millis(SyncPhase.ACTIVE_STORE),millis(SyncPhase.ACTIVE_FACTS),millis(SyncPhase.OBSERVE_CHECKPOINT),
+                    pageContainers,transportFactsCount,activeFactsCount,complete,success?"NONE":phase.name(),org.slf4j.MDC.get("requestId"),org.slf4j.MDC.get("traceId"),currentScopeId());
+            } catch(Throwable diagnosticFailure) { /* 诊断失败不能替换原业务异常或阻断提交。 */ }
+        }
+        /** 阶段仅输出整数毫秒，不携带业务标识。 */
+        private long millis(SyncPhase value) { return java.util.concurrent.TimeUnit.NANOSECONDS.toMillis(elapsed[value.ordinal()]); }
     }
     static void validateSource(ContainerSource source) {
         if(source==null || source.containerBookingId()==null || source.containerBookingId().isBlank() || source.departedAt()==null && source.departedLocalAt()==null && source.sailedEvidenceLocalAt()==null || source.sourceVersion()==null || source.establishedFlow()==null || source.requirements()==null)
@@ -69,19 +130,32 @@ public class AppointmentWorkSyncService {
         for(var requirement:source.requirements()) {
             if(requirement==null || requirement.requirementKey()==null || requirement.requirementKey().isBlank() || !seen.add(requirement.requirementKey()) || requirement.references()==null || requirement.replacesRequirementKeys()==null || requirement.sources()==null)
                 throw unavailable("送货需求缺少稳定身份或重复");
-            if(requirement.batchKey()!=null && !batches.add(requirement.batchKey())) throw unavailable("同柜批次需求重复，必须由原域归并来源");
+            if(requirement.batchKey()!=null) {
+                var identity=requirement.batchKey().startsWith("FBA_APPOINTMENT:")?customerRequirement(requirement.batchKey(),deliveryCustomer(requirement.sources())):requirement.batchKey();
+                if(!batches.add(identity)) throw unavailable("同柜批次客户需求重复，必须由原域归并来源");
+            }
             if(requirement.timezone()!=null) zone(requirement.timezone());
         }
     }
-    /** Caller holds work guard and validates the route against current original facts. */
+    /** 命令入口仍在调用方守卫事务中即时加载工作集。 */
     List<String> generate(ContainerSource source,Flow flow,List<AppointmentWorkState> existing,Actor actor) {
+        return generate(source,flow,existing,actor,workingSet(),gateway.openRequirements());
+    }
+    /** 与持久层全量读取保持稳定键顺序，并保留退役事项及原读取上限。 */
+    private Map<String,AppointmentWorkState> workingSet() {
+        var known=new TreeMap<String,AppointmentWorkState>();
+        store.all().forEach(state->known.put(state.getWorkItemKey(),state));
+        return known;
+    }
+    /** 同页各柜共享最新状态，新增、跨柜关联和退役仍逐项持久化。 */
+    private List<String> generate(ContainerSource source,Flow flow,List<AppointmentWorkState> existing,Actor actor,
+                                  Map<String,AppointmentWorkState> known,RequirementReader requirementReader) {
         validateSource(source);
         if(flow==Flow.UNKNOWN) throw conflict("真实送货路线尚未明确");
-        var requirements=gateway.requirements(source,flow);
+        var requirements=requirementReader.read(source,flow);
         source=new ContainerSource(source.containerBookingId(),source.containerNo(),source.departedAt(),source.departedLocalAt(),source.sailedEvidenceLocalAt(),source.sourceVersion(),source.establishedFlow(),source.timezone(),requirements);
         validateSource(source);
         if(requirements.isEmpty()) throw conflict("真实送货需求尚未明确，不能生成空清单");
-        var known=store.all().stream().collect(Collectors.toMap(AppointmentWorkState::getWorkItemKey,Function.identity(),(a,b)->a));
         var created=new ArrayList<AppointmentWorkState>();
         for(var type:flow==Flow.TRANSFER?List.of(Type.PICKUP,Type.WAREHOUSE_RECEIPT,Type.EMPTY_RETURN):List.of(Type.PICKUP,Type.EMPTY_RETURN)) add(source,type,null,flow,known,created);
         for(var requirement:source.requirements()) {
@@ -91,10 +165,17 @@ public class AppointmentWorkSyncService {
         for(var state:created) {
             state.setOwner(actor.id().equals(SYSTEM.id())?null:new Owner(actor.id(),actor.name()));
             state.setFollowupDate(LocalDate.now(state.getTimezone()==null?REMINDER_ZONE:zone(state.getTimezone())));
+            var inherited=store.inheritedFollowup(state.getWorkItemKey());
+            if(inherited!=null) { state.setOwner(inherited.owner());state.setFollowupDate(inherited.nextFollowupDate()); }
             String pickup=key(source.containerBookingId(),Type.PICKUP,null),receipt=key(source.containerBookingId(),Type.WAREHOUSE_RECEIPT,null);
             if(state.getType()==Type.WAREHOUSE_RECEIPT) state.setPrerequisites(List.of(pickup));
             if(state.getType()==Type.DELIVERY) state.setPrerequisites(List.of(flow==Flow.TRANSFER?receipt:pickup,requirementKey(source.containerBookingId(),Type.TRANSPORT,state.getRequirementKey(),state.getBatchKey())));
-            if(state.getType()==Type.TRANSPORT) state.setPrerequisites(List.of(flow==Flow.TRANSFER?receipt:pickup,requirementKey(source.containerBookingId(),Type.DELIVERY,state.getRequirementKey(),state.getBatchKey())));
+            if(state.getType()==Type.TRANSPORT) {
+                var prerequisites=new LinkedHashSet<String>();prerequisites.add(flow==Flow.TRANSFER?receipt:pickup);
+                for(var r:requirements) if(Objects.equals(state.getBatchKey(),r.batchKey()) && (r.batchKey()!=null || Objects.equals(state.getRequirementKey(),r.requirementKey())))
+                    prerequisites.add(requirementKey(source.containerBookingId(),Type.DELIVERY,r.requirementKey(),r.batchKey()));
+                state.setPrerequisites(List.copyOf(prerequisites));
+            }
             if(state.getType()==Type.EMPTY_RETURN) {
                 String containerId=source.containerBookingId();
                 state.setPrerequisites(flow==Flow.TRANSFER?List.of(receipt):source.requirements().stream().map(r->requirementKey(containerId,Type.DELIVERY,r.requirementKey(),r.batchKey())).toList());
@@ -102,6 +183,18 @@ public class AppointmentWorkSyncService {
             store.insert(state); store.history(state,actor,"GENERATED","根据已确认路线建立工作需求",null,null,null);
         }
         String generationContainerId=source.containerBookingId();
+        // Rebuild each batch vehicle's customer edges from the complete current manifest.
+        // A shared vehicle retains every customer delivery; no last customer wins the edge.
+        for(var batch:requirements.stream().map(Requirement::batchKey).filter(Objects::nonNull).distinct().toList()) {
+            var vehicle=known.get(requirementKey(generationContainerId,Type.TRANSPORT,null,batch));
+            var dependencies=new LinkedHashSet<>(vehicle.getPrerequisites());
+            dependencies.removeIf(k->{var s=known.get(k);return s!=null && s.getType()==Type.DELIVERY && batch.equals(s.getBatchKey());});
+            requirements.stream().filter(r->batch.equals(r.batchKey())).map(r->requirementKey(generationContainerId,Type.DELIVERY,r.requirementKey(),batch)).forEach(dependencies::add);
+            var sources=requirements.stream().filter(r->batch.equals(r.batchKey())).flatMap(r->r.sources().stream()).distinct().toList();
+            if(!vehicle.getPrerequisites().equals(List.copyOf(dependencies)) || !vehicle.getSources().equals(sources)) {
+                vehicle.setPrerequisites(List.copyOf(dependencies));vehicle.setSources(sources);store.save(vehicle);
+            }
+        }
         var activeKeys=new HashSet<String>(); requirements.forEach(r->{ activeKeys.add(requirementKey(generationContainerId,Type.DELIVERY,r.requirementKey(),r.batchKey())); activeKeys.add(requirementKey(generationContainerId,Type.TRANSPORT,r.requirementKey(),r.batchKey())); });
         for(var old:existing) if(old.getRequirementKey()!=null && !"BATCH_REPLACED".equals(old.getRetirementReason()) && !activeKeys.contains(old.getWorkItemKey())) {
             String containerId=source.containerBookingId();
@@ -116,6 +209,7 @@ public class AppointmentWorkSyncService {
                 store.save(old);store.history(old,actor,"SOURCE_REMOVED","原排车已移除该柜实物，保留其他柜的当前关联",null,null,null);continue;
             }
             var replacements=requirements.stream().filter(r->r.replacesRequirementKeys().contains(old.getRequirementKey()))
+                .filter(r->old.getType()!=Type.DELIVERY || old.getSources().isEmpty() || r.sources().isEmpty() || r.sources().stream().anyMatch(s->old.getSources().stream().anyMatch(o->Objects.equals(o.customerId(),s.customerId()))))
                 .map(r->requirementKey(containerId,old.getType(),r.requirementKey(),r.batchKey())).distinct().toList();
             // Removed dispatch items no longer exist in the original allocation table. Its full current
             // container manifest restores the unallocated demand or names the newly assigned dispatch.
@@ -126,7 +220,9 @@ public class AppointmentWorkSyncService {
         }
         return created.stream().map(AppointmentWorkState::getWorkItemKey).toList();
     }
-    private static String requirementKey(String container,Type type,String requirement,String batch) { return batch==null?key(container,type,requirement):key("BATCH:"+batch,type,null); }
+    private static String requirementKey(String container,Type type,String requirement,String batch) {
+        return batch==null?key(container,type,requirement):key("BATCH:"+batch,type,type==Type.DELIVERY && batch.startsWith("FBA_APPOINTMENT:")?requirement:null);
+    }
     private void add(ContainerSource source,Type type,Requirement requirement,Flow flow,Map<String,AppointmentWorkState> known,List<AppointmentWorkState> created) {
         var state=create(source,type,requirement,flow); var old=known.get(state.getWorkItemKey());
         if(old==null) { created.add(state); known.put(state.getWorkItemKey(),state); }
@@ -147,14 +243,14 @@ public class AppointmentWorkSyncService {
             }
             old.setBatchNo(requirement.batchNo()); old.setOriginName(requirement.originName()); old.setDestinationName(requirement.destinationName()); old.setDestinationKind(requirement.destinationKind()); old.setReferences(requirement.references()); old.setSources(requirement.sources());
             if(type==Type.DELIVERY) old.setTimezone(requirement.timezone());
-            if(update) store.save(old);
+            if(update && !created.contains(old)) store.save(old);
         }
     }
     private AppointmentWorkState create(ContainerSource source,Type type,Requirement requirement,Flow flow) {
         var state=new AppointmentWorkState(); state.setWorkItemKey(requirement==null?key(source.containerBookingId(),type,null):requirementKey(source.containerBookingId(),type,requirement.requirementKey(),requirement.batchKey()));
         state.setType(type); state.setFlow(flow); state.setContainerBookingId(source.containerBookingId()); state.setContainerNo(source.containerNo()); state.setSourceVersion(source.sourceVersion());
         state.setTimezone(type==Type.ROUTE?source.timezone():null); state.setContainers(List.of(new ContainerReference(source.containerBookingId(),null,source.containerNo())));
-        if(requirement!=null) { state.setRequirementKey(requirement.requirementKey()); state.setBatchKey(requirement.batchKey()); state.setBatchNo(requirement.batchNo()); state.setDestinationKind(requirement.destinationKind());
+        if(requirement!=null) { state.setRequirementKey(type==Type.TRANSPORT && requirement.batchKey()!=null?requirement.batchKey():requirement.requirementKey()); state.setBatchKey(requirement.batchKey()); state.setBatchNo(requirement.batchNo()); state.setDestinationKind(requirement.destinationKind());
             state.setOriginName(requirement.originName()); state.setDestinationName(requirement.destinationName()); state.setTimezone(type==Type.DELIVERY?requirement.timezone():null); state.setReferences(requirement.references()); state.setSources(requirement.sources());
             if(requirement.batchKey()!=null) state.setBatchKeys(List.of(requirement.batchKey())); }
         return state;
@@ -166,17 +262,18 @@ public class AppointmentWorkSyncService {
             var fact=facts.get(state.getWorkItemKey()); if(fact==null) continue;
             if(fact!=null && state.getObservedImpactToken()!=null && !Objects.equals(state.getObservedImpactToken(),fact.impactToken()) && state.isObservedArranged()) {
                 affected.add(state.getWorkItemKey());
-                expandDependents(state.getWorkItemKey(),states,affected);
+                if(state.getObservedDependentImpactToken()!=null && !Objects.equals(state.getObservedDependentImpactToken(),fact.dependentImpactToken()))
+                    expandDependents(state.getWorkItemKey(),states,affected);
             }
         }
         for(var state:states) {
             if(state.isRetired()) continue;
             var fact=facts.get(state.getWorkItemKey()); if(fact==null) continue;
-            boolean changed=changed(state,fact) || !Objects.equals(state.getObservedImpactToken(),fact.impactToken()) || state.isObservedArranged()!=fact.arranged() || !state.getReadPermissions().equals(fact.readPermissions()),baseline=state.getObservedFingerprint()==null;
+            boolean changed=changed(state,fact) || !Objects.equals(state.getObservedImpactToken(),fact.impactToken()) || !Objects.equals(state.getObservedDependentImpactToken(),fact.dependentImpactToken()) || state.isObservedArranged()!=fact.arranged() || !state.getReadPermissions().equals(fact.readPermissions()),baseline=state.getObservedFingerprint()==null;
             boolean review=affected.contains(state.getWorkItemKey()) && arranged(state,fact) && !completed(fact);
             if(review) { state.setReviewRequired(true); state.setReviewVersion(state.getReviewVersion()+1); state.setReviewReason("原业务时间、货量或执行关联发生变化，请核对已有安排"); }
             if(changed || baseline || review) {
-                state.setObservedFingerprint(fact.fingerprint()); state.setObservedImpactToken(fact.impactToken()); state.setObservedArranged(fact.arranged()); state.setReadPermissions(List.copyOf(fact.readPermissions())); store.save(state);
+                state.setObservedFingerprint(fact.fingerprint()); state.setObservedImpactToken(fact.impactToken()); state.setObservedDependentImpactToken(fact.dependentImpactToken()); state.setObservedArranged(fact.arranged()); state.setReadPermissions(List.copyOf(fact.readPermissions())); store.save(state);
                 store.history(state,actor,review?"IMPACT_OBSERVED":"BASELINE_OBSERVED",review?state.getReviewReason():"记录当前原业务基线，不生成执行事实",null,null,null);
             }
         }
@@ -185,9 +282,29 @@ public class AppointmentWorkSyncService {
         var queue=new ArrayDeque<String>(); queue.add(key); var seen=new HashSet<String>();
         var byKey=states.stream().collect(Collectors.toMap(AppointmentWorkState::getWorkItemKey,Function.identity()));
         while(!queue.isEmpty()) { var current=queue.remove(); if(!seen.add(current)) continue;
+            // A changed customer batch requires its shared vehicle to be checked. That does not
+            // make the vehicle's other customers' appointments change. A change originating in
+            // the vehicle itself still reaches all of its current dependent appointments.
+            var currentState=byKey.get(current);
+            if(!current.equals(key) && currentState!=null && currentState.getType()==Type.TRANSPORT) continue;
             for(var candidate:states) if(!candidate.isRetired() && effectiveKeys(candidate.getPrerequisites(),byKey).contains(current) && affected.add(candidate.getWorkItemKey())) queue.add(candidate.getWorkItemKey());
         }
     }
+    /** Reverse of the impact traversal: a shared vehicle is an authority, not a sibling bridge. */
+    static List<AppointmentWorkState> impactPrerequisites(AppointmentWorkState target,List<AppointmentWorkState> states) {
+        var byKey=states.stream().collect(Collectors.toMap(AppointmentWorkState::getWorkItemKey,Function.identity()));
+        var pending=new ArrayDeque<>(effectiveKeys(target.getPrerequisites(),byKey));
+        var seen=new HashSet<String>(); seen.add(target.getWorkItemKey());
+        var result=new ArrayList<AppointmentWorkState>();
+        while(!pending.isEmpty()) {
+            var key=pending.remove(); if(!seen.add(key)) continue;
+            var state=byKey.get(key);
+            if(state==null || state.isRetired()) throw conflict("关联安排已变化，须先同步当前工作关系");
+            result.add(state);
+            if(state.getType()!=Type.TRANSPORT) pending.addAll(effectiveKeys(state.getPrerequisites(),byKey));
+        }
+        return List.copyOf(result);
+    }
     private void reconcileTransport(List<AppointmentWorkState> all,Map<String,Fact> facts) {
         var members=all.stream().filter(s->s.getType()==Type.TRANSPORT && s.getTripKey()==null && facts.containsKey(s.getWorkItemKey()) && facts.get(s.getWorkItemKey()).tripKey()!=null)
             .collect(Collectors.groupingBy(s->facts.get(s.getWorkItemKey()).tripKey()));

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkSynchronizationJob.java

@@ -21,7 +21,20 @@ public class AppointmentWorkSynchronizationJob {
             cursor=result.complete()?null:result.nextCursor();
         } catch(RuntimeException error) {
             cursor=null;
-            log.warn("Appointment work synchronization incomplete; next scan restarts from first page: {}",error.getClass().getSimpleName());
+            log.warn("Appointment work synchronization incomplete; next scan restarts from first page: {}",failureDiagnostic(error));
         }
     }
+    /** Keep causes and code locations, never exception messages that may contain remote payloads or credentials. */
+    static String failureDiagnostic(Throwable error) {
+        var causes=new java.util.ArrayList<String>();
+        var seen=java.util.Collections.newSetFromMap(new java.util.IdentityHashMap<Throwable,Boolean>());
+        for(var current=error;current!=null && causes.size()<6 && seen.add(current);current=current.getCause()) {
+            String status=current instanceof org.springframework.web.server.ResponseStatusException response?"["+response.getStatusCode().value()+"]":"";
+            String location=java.util.Arrays.stream(current.getStackTrace())
+                .filter(frame->frame.getClassName().startsWith("com.baiyue.") && !frame.getClassName().equals(AppointmentWorkPolicy.class.getName()))
+                .findFirst().map(frame->"@"+frame.getClassName()+":"+frame.getLineNumber()).orElse("");
+            causes.add(current.getClass().getSimpleName()+status+location);
+        }
+        return String.join(" <- ",causes);
+    }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/diagnostics/AppointmentWorkDataSourcePostProcessor.java

@@ -0,0 +1,35 @@
+package com.baiyue.lastleg.appointmentwork.diagnostics;
+
+import com.zaxxer.hikari.HikariDataSource;
+import org.aopalliance.intercept.MethodInterceptor;
+import org.springframework.aop.framework.ProxyFactory;
+import org.springframework.aop.support.AopUtils;
+import org.springframework.beans.factory.config.BeanPostProcessor;
+import javax.sql.DataSource;
+import static com.baiyue.lastleg.appointmentwork.diagnostics.AppointmentWorkDiagnostics.*;
+
+/** 仅观察原Hikari getConnection；同池同连接，unwrap保持容器bean self契约而非隐藏target身份。 */
+final class AppointmentWorkDataSourcePostProcessor implements BeanPostProcessor {
+    /** 不识别或已有代理的数据源保持原对象，明确记录未覆盖而不主动探测连接。 */
+    @Override public Object postProcessAfterInitialization(Object bean,String name) {
+        if(!(bean instanceof DataSource))return bean;
+        if(!(bean instanceof HikariDataSource) || AopUtils.isAopProxy(bean)) {
+            warnUnavailable();return bean;
+        }
+        try {
+            var factory=new ProxyFactory(bean);factory.setProxyTargetClass(true);
+            factory.addAdvice((MethodInterceptor)invocation->{
+                if(!invocation.getMethod().getName().equals("getConnection") || !active())return invocation.proceed();
+                try(var span=span(Stage.CONNECTION_ACQUIRE)) {
+                    try{return invocation.proceed();}catch(Throwable error){span.failed();throw error;}
+                }
+            });
+            return factory.getProxy(bean.getClass().getClassLoader());
+        } catch(RuntimeException failure) { warnUnavailable();return bean; }
+    }
+    /** 不输出 Bean 名、数据源属性或异常内容。 */
+    private static void warnUnavailable() {
+        try{org.slf4j.LoggerFactory.getLogger(AppointmentWorkDataSourcePostProcessor.class).warn("Appointment connection diagnostic unavailable: unsupported or already proxied datasource");}
+        catch(Throwable ignored){ /* 日志故障不改变 Bean 注册。 */ }
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/diagnostics/AppointmentWorkDiagnosticFilter.java

@@ -0,0 +1,39 @@
+package com.baiyue.lastleg.appointmentwork.diagnostics;
+
+import jakarta.servlet.*;
+import jakarta.servlet.http.*;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+import java.io.IOException;
+import static com.baiyue.lastleg.appointmentwork.diagnostics.AppointmentWorkDiagnostics.*;
+
+/** 仅测量服务端同步 filter dispatch，不代表客户端总耗时或异步响应完成时间。 */
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE+10)
+public class AppointmentWorkDiagnosticFilter extends OncePerRequestFilter {
+    private static final String BASE="/api/platform/v1/last-leg/appointment-work";
+    /** 仅识别固定模板；路径参数、query string和载荷不进入上下文。 */
+    static Route route(String method,String path){
+        if("GET".equals(method)){
+            if((BASE+"/summary").equals(path))return Route.SUMMARY;
+            if((BASE+"/calendar").equals(path))return Route.CALENDAR;
+            if((BASE+"/items").equals(path))return Route.ITEMS;
+            if((BASE+"/items/resolve").equals(path))return Route.RESOLVE;
+            if(path!=null && path.matches(BASE+"/items/[^/]+"))return Route.DETAIL;
+        }
+        if("POST".equals(method) && path!=null && path.matches(BASE+"/items/[^/]+/commands"))return Route.COMMAND;
+        return null;
+    }
+    /** 不采集其他端点，也不为诊断增加权限判断。 */
+    @Override protected boolean shouldNotFilter(HttpServletRequest request){return route(request.getMethod(),request.getRequestURI())==null;}
+    /** 创建及清理线程作用域；不覆写上游相关标识、状态、响应或异常。 */
+    @Override protected void doFilterInternal(HttpServletRequest request,HttpServletResponse response,FilterChain chain)throws ServletException,IOException{
+        Scope scope=null;
+        try{scope=open(Origin.HTTP,route(request.getMethod(),request.getRequestURI()));}catch(RuntimeException ignored){ /* 无诊断仍执行原请求。 */ }
+        try{chain.doFilter(request,response);}
+        catch(ServletException|IOException|RuntimeException|Error error){if(scope!=null)scope.failed();throw error;}
+        finally{if(scope!=null){try{scope.status(response.getStatus());}catch(Throwable ignored){ /* 响应诊断读取失败不替换原异常。 */ }finally{scope.close();}}}
+    }
+}