优化

三期/货柜履约原型字段验收矩阵-2026-08-17.md

@@ -21,7 +21,7 @@
 | 装柜清单 | 操作、仓库、清单号、集装箱号、柜号、状态、总箱/毛重/净重/体积/数量、备注、创建人/时间 | 操作第一且左固定；字段与原型一致 | `ConfirmedSummary` 及 `ConfirmedDetail.items/histories` | 同一计划 PDA 完成后生成的 COMPLETED 清单 | `LANDED` |
 | 订舱 | 委托单位、主票号、放舱、MB/L 当事方、港口、箱量、船公司、截关、ETD/ATD/ATA、船名航次、订舱代理、退仓、单号、操作员、状态 | 操作第一且左固定；订舱号、客户、船公司、代理、船名航次、港口、ETD/ETA、状态、更新时间 | `OceanBookingDtos.Detail`：`oceanBooking/parties/containers/histories`，创建必填五项运输快照和逐柜 `containers[]` | `ocean-bookings` 本轮一单两真实柜，创建即 CONFIRMED，随后 RELEASED | `LANDED`；截关/ATD/ATA、退仓公司、操作员未进入当前列表，见 UNKNOWN |
 | 船期 | 原型订舱区域提供船名、航次、港口和关键时间 | 操作第一且左固定；船期号、来源、船名航次、港口、ETD/ETA、观测/更新时间、过期 | `ScheduleView.schedule+expired`，含来源、港口、ETD/ETA、截单/截关/截港、观测和过期时间 | `phase3-port-schedules` 本轮正式订舱关联观测 | `LANDED` |
-| 拖车 | 派车单号、运输公司、司机、车头号、门店、应付/应收、预计装箱、状态、附件、操作 | 操作第一且左固定；预约号、柜号、客户、运输公司、司机、车辆、门店、计划装货、状态、附件、更新时间 | `TruckAppointmentEntity` 及附件端点；订舱/柜次/计划/仓库/客户和供应商快照 | `truck-appointments` 复用同 marker 订舱详情身份并上传正式附件 | `LANDED`；附件列来自独立附件接口，不伪造实体字段 |
+| 拖车 | 派车单号、运输公司、司机、车头号、门店、应付/应收、预计装箱、状态、附件、操作 | 操作第一且左固定；预约号、柜号、客户、运输公司、司机、车辆、门店、计划装货、状态、附件、更新时间 | `TruckAppointmentEntity` 及附件端点；客户和 ACTIVE TRUCKING 承运商为必填快照，订舱/柜次/计划/仓库为可选关联 | `truck-appointments` 使用同 marker 客户独立开立，不借订舱；上传正式附件并完成自身状态机；另以本轮柜次执行计划不匹配负向 | `LANDED`；附件列来自独立附件接口，不伪造实体字段 |
 | 报关协同 | 模块 13 的传统报关/清关表包含订单、客户、状态、资料与时间等历史字段 | 操作第一且左固定；报关编号、订单/入库关联、资料清单及版本、状态、更新时间 | `CustomsCaseEntity` 与聚合详情的 documents/supplements/submissions/receipts/histories | `phase3-customs` 本轮实际订单、入库、柜次及不可变清单版本 | `LANDED_WITH_OVERRIDE`：当前“报关协同”模型覆盖历史原型；客户名和文件摘要见 UNKNOWN |
 | 国内出仓 | 模块 04 为海外末端派送原型，非当前国内出仓门禁模型 | 操作第一且左固定；入库单、客户、柜号、订舱/拖车/PDA 状态、出仓状态、门禁 | `OutboundDispatchDtos.Aggregate/Detail` 的订单、入库、客户、柜次、计划、PDA、订舱、拖车、状态、版本和 gate/timeline | `phase3-outbound-dispatch` 同 marker LOADED 柜次聚合 | `LANDED_WITH_OVERRIDE`：当前确认契约优先；Admin“柜号”列实际绑定 `containerNo`，建议文案校准 |
 

三期/货柜管理全链验收矩阵-2026-08-13.md

@@ -31,7 +31,7 @@
 | CT-D10 | DO/PU 未齐、部分完成、全部完成 | 柜次与运输协同已建立 | `DELIVERY_ORDER`、`PICKUP_ORDER` 可独立查询、上传和鉴权下载，版本与幂等有效 | 柜次详情入口待回传 | 服务端已冻结；人工入口待定 |
 | CT-D11 | 正常、异常、取消异常 | 任意有效柜次及显式货柜版本 | 标记/取消使用版本和必填原因；overview 保留 `MARK`/`CANCEL` 全部历史 | 货柜详情入口待回传 | 服务端已冻结；人工入口待定 |
 | CT-D12 | 多节点运输轨迹与操作日志 | CT-D10 | overview 时间线含运输更新、异常和 PDA 事件，按发生时间升序 | 详情时间线入口待回传 | 服务端聚合已冻结；人工入口待定 |
-| CT-D13 | PDA 确认装柜并推进 `LOADED` | inbound `LOADING`、bridge、订舱 `RELEASED`、PDA 全拣和五类 ACTIVE 证据齐备；拖车允许缺失或未完成 | PDA `complete` 不以拖车缺失/状态为阻断；若同稳定 `containerBookingId` 存在唯一有效拖车，则同一事务推进拖车 `COMPLETED`，并完成 task/plan/inbound `LOADED`；多拖车或真实并发返回 A0409 且零写入 | 订单/柜次详情显示完成且编辑锁定 | `LANDED_STATIC`：OpenAPI、Service 与结算后版本刷新回归已冻结；待部署后 HTTP 复核 |
+| CT-D13 | PDA 确认装柜并推进 `LOADED` | inbound `LOADING`、bridge、订舱 `RELEASED`、PDA 全拣和五类 ACTIVE 证据齐备；拖车允许缺失、未完成或存在多条 | PDA `complete` 的主事务不以拖车数量/状态为阻断；提交后才在独立事务 best-effort 同步唯一同柜有效拖车。零条直接跳过，一条可推进 `COMPLETED`，多条或拖车并发只隔离记录同步失败，task/plan/inbound 仍保持 `LOADED` | 订单/柜次详情显示完成且编辑锁定；拖车同步失败单独呈现 | `LANDED_STATIC`：OpenAPI、Service、提交后同步隔离与结算版本回归已冻结；待部署后 HTTP 复核 |
 | CT-D14 | PDA 未最终完成前向同一预装计划增加入库单 | 已有稳定 `loadingPlanId/taskId/containerBookingId`，任务尚未最终完成；新增票满足同客户、仓库、渠道、容量与柜型约束 | `EDITING/LOADING` 可增量；`LOADING` 不回退且复用同一 task；plan/task/item 版本递增，旧 inventory token A0409 后必须刷新；全拣后增项将 `AWAITING_REVIEW` 撤回 `IN_PROGRESS`，证据保留；未拣项可删，已拣数量形成 `minPackageCount` | Admin 预装增量入口与 PDA 同步显示新增项 | `LANDED_STATIC`：assign/adjust/delete 与 capability DTO 已冻结并接入脚本；待部署后真实 HTTP 复核 |
 
 ## 全链验收用例
@@ -50,7 +50,7 @@
 | CT-E10 | DO/PU | 通用查询、multipart 上传、鉴权下载；上传要求 `Idempotency-Key`、真实文件、`expectedVersion`，重放不得重复上传 | Admin 入口待回传 | 两类型响应、文件哈希/ID、二进制下载、幂等重放 | 服务端契约已冻结 |
 | CT-E11 | 货柜异常及取消历史 | `POST/DELETE /api/platform/v1/containers/{id}/exception` 要求 `expectedVersion` 和必填原因；冲突失败；overview 历史只追加不覆盖 | Admin 入口待回传 | 标记/取消响应、版本冲突、overview 历史 | 服务端契约已冻结；版本来源阻断 |
 | CT-E12 | 运输轨迹/日志 | overview `timeline` 聚合 `TRANSPORT_UPDATE`、`MARK/CANCEL`、`PDA_*`，时间升序且含详情、操作者和发生时间 | Admin 入口待回传 | overview 时间线响应 | 服务端契约已冻结 |
-| CT-E13 | PDA complete 拖车联动正反例 | 有同柜 `LOADING` 拖车时 complete 后拖车 `COMPLETED` 且 inbound `LOADED`；无拖车仍成功；错柜拖车不修改；同键重放不新增拖车或 task 历史；并发/任一保留门禁失败时全部对象原子回滚 | PDA 完成页、入库单、订单详情及拖车详情显示同一最终事实 | 三条正反链 + 幂等重放 + 并发；记录 task/plan/inbound/truck 前后版本、历史数量、业务码和 `requestId/traceId` | `LANDED_STATIC`：关联有效拖车、状态推进、幂等和事务回滚已冻结；多 fixture HTTP 待跑 |
+| CT-E13 | PDA complete 与可选拖车隔离 | 同柜零/一/多条拖车均不阻断 complete：零条直接 `LOADED`；唯一有效拖车可在主事务提交后独立推进 `COMPLETED`；多条、错柜或拖车并发失败不得回滚 task/plan/inbound，且不得误改其他拖车；同键重放不新增历史 | PDA 完成页、入库单和订单详情先显示 `LOADED`；拖车详情显示独立同步结果 | 零/一/多条三条链 + 幂等重放；记录 task/plan/inbound/truck 前后版本、历史数量、业务码和 `requestId/traceId` | `LANDED_STATIC`：提交后独立同步、异常隔离及一对多保护已冻结；多 fixture HTTP 待跑 |
 | CT-E19 | PDA 结算导致版本递增后的最终完成 | final complete 前来源 inbound 为 `LOADING`；settle 可能将来源 version 递增并生成全量或部分实装分片 | complete 必须在 settle 后重新锁定实际完成行并使用当前 version，不得复用结算前快照；full/partial 均成功，真实并发仍 A0409，失败 task/plan/inbound/operation/history 零写入 | PDA、计划、入库单和统一订单显示唯一 `LOADED` 事实 | `LANDED_STATIC`：真实缺陷样本 task `2089254643058184193` 已转为 Node/Java 回归；待修复版本部署后 HTTP 复核 |
 | CT-E20 | PDA pending/detail 工作流一致性 | 同一 task 已有唯一 BATCH、明细全为 PICKED、`pendingItemCount=0` | pending 与 detail 均返回 `AWAITING_REVIEW`；允许证据 GET；派生 actions 为空且不再 POST batch | PDA 待办卡片与详情均显示“待人工复核”，进入取证而非重复拣货 | `LANDED_STATIC`：pending SQL 按明细未完成数投影，OpenAPI 已冻结；待部署后新 marker HTTP 复核 |
 | CT-E14 | 跨客户与跨仓库隔离 | 交叉资源 ID 不可读写下载，不泄露资源存在性 | 页面无越权入口 | 双身份交叉请求证据 | 待契约 |
@@ -62,10 +62,21 @@
 ## PDA 完成后未进入 LOADED 的已登记回归
 
 - 真实测试样本：订单 `NYEXX2608170001`；PDA task、review、装柜计划与五类证据均已完成，但 inbound 仍为 `LOADING`。
-- 门禁只读证据：`ocean_ready=1`、`truck_ready=0`；同柜拖车预约 `TA2089239590749704194` 的 `loading_plan_id=NULL`、状态为 `LOADING`。
+- 历史只读证据：旧柜次曾因拖车 `loading_plan_id=NULL` 被误判 `truck_ready=0`；该门禁已被最新产品结论覆盖，不再作为 PDA 完成前置。
-- 最新用户覆盖：`phase3-loading` 仍只完成 claim/batch/证据与动态增量，任务保持 `LOADING/AWAITING_REVIEW`；最终入口仍为 `POST /pda-loading/tasks/{taskId}/complete`，但拖车缺失或尚未完成不再是阻断。
+- 最新冻结：最终入口仍为 `POST /pda-loading/tasks/{taskId}/complete`，保留订舱 `RELEASED`、bridge 和五类 ACTIVE 证据门禁；拖车缺失、未完成或多条均不得阻断。
-- 目标联动：若稳定 `containerBookingId` 有关联有效拖车，PDA complete 同一业务动作将其推进“已完成装柜”；若无拖车仍成功；错柜拖车不得修改。保留订舱 `RELEASED`、bridge 和五类 ACTIVE 证据门禁。
+- 同步边界：task/plan/inbound 主事务先提交为 `LOADED`；若同稳定 `containerBookingId` 恰有一条有效拖车，再以独立新事务尝试推进 `COMPLETED`。零条直接跳过；多条、错柜或并发冲突不得回滚主事实。
-- 已冻结回归包：① 有 `LOADING` 拖车 → PDA complete → 拖车 `COMPLETED` + inbound `LOADED`；② 无拖车仍成功；③ 错柜拖车零修改；④ 同键重放不新增历史；⑤ 增量/final complete 并发和任一保留门禁失败时 task/plan/inbound/truck 原子回滚。finalize 已恢复正式 complete 接线，不再执行旧“拖车必须预先 COMPLETED”门禁。
+- 已冻结回归包：① 唯一 `LOADING` 拖车 → PDA complete → inbound `LOADED`，拖车独立同步 `COMPLETED`；② 无拖车仍成功；③ 多拖车仍成功且各拖车零误改；④ 错柜拖车零修改；⑤ 同键重放不新增历史；⑥ 拖车同步异常只保留独立失败证据。
+
+## 拖车独立开立契约
+
+| 验收项 | 正式断言 | 当前结论 |
+|---|---|---|
+| 无履约关联创建 | `oceanBookingId/containerBookingId/loadingPlanId` 可同时为空；本轮客户、正式 ACTIVE `TRUCKING` 承运商、`plannedLoadingAt` 必填；创建后可查询、编辑并独立完成 `DRAFT -> ... -> COMPLETED` | `LANDED_STATIC`：DTO/OpenAPI/Admin 与 HTTP fixture 已接线 |
+| 客户和供应商事实 | `customerId` 必须指向 ACTIVE IAM 客户，名称由 IAM 冻结；`carrierId` 必须指向 ACTIVE TRUCKING 供应商，名称由 Warehouse 冻结；名称仅为一致性提示 | 静态及 HTTP 必填负向已接线 |
+| 可选订舱/柜次 | 任一关联存在时校验客户及仓库；订舱和柜次同时存在时必须有 allocation 关系 | Service/OpenAPI 静态合同已锁定；部署后补不同客户/仓库及 allocation HTTP 负向 |
+| 可选计划 | `loadingPlanId` 仅能与 `containerBookingId` 同时提供，且必须是该柜次当前计划 | 同 marker 柜次派生错误计划 ID 的 HTTP 负向已接线 |
+| PDA 隔离 | 未关联拖车不受 PDA 影响；同柜零/一/多条均不阻断 PDA 主事务；唯一拖车同步失败也只影响拖车自身 | 静态合同已锁定提交后同步与独立事务；部署后按零/一/多 fixture 验证 |
+| Admin 表单 | 客户、承运商、预计装箱时间必填；订舱和柜次明确标注可选，清空后不得残留派生计划/仓库/客户 | Admin 静态合同已接线 |
 - 结算版本缺陷证据：task `2089254643058184193`、inbound `2089181999189299202` 在 taskVersion=1/inboundVersion=6、PICKED 2/2 与五证据齐备时返回 A0409；requestId=`12a913ba-9845-45f6-91ec-bdba28e3eb9d`、traceId=`395d11b5c0da45eca948a39a08e29d3d`。回归锁定 settle 后重新读取 full/partial 实际完成分片版本；真实并发仍冲突，失败必须零写入。
 
 ## PDA 进行中增量预装冻结回归