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

货柜管理全链验收矩阵

更新时间：2026-08-13
当前任务：019ff90b-a72d-7000-abdf-e5363357a564
父任务：019ff600-f9f1-78f1-a357-7c80c13e574e
依赖任务：后端 019ff90b-9b45-7191-b68f-c3b52567e3e4、Admin 019ff90b-a037-79b0-b945-8f88bdbde9c5
边界：只维护根目录脚本、验收文档和测试矩阵；不修改 Admin 或 Java 业务源码，不部署、不触发 Jenkins、不写测试环境数据库。

验收口径

• 本矩阵以当前对话、三期产品确认版开发规划和实际冻结契约为准。旧确认单中的待确认项不覆盖后续已冻结结论。
• 已冻结能力按事实来源落具体路径和断言；尚未冻结能力继续只保留能力级占位，不预设 HTTP 方法、路径、DTO 字段或业务错误码。
• 自动化必须通过业务 API 生成数据；人工验收必须能从 Admin/PDA 可见入口点击到对应状态。不得以数据库直写、mock、原型或前端本地假状态代替。
• 每次真实 HTTP 验收记录请求用途、响应状态、业务码、requestId、traceId、关键资源 ID 和清理/保留策略；敏感凭据不得写入报告。
• 柜态看板不纳入本轮。

状态数据目录

数据代号	必备状态/形态	生成前置	自动化断言	人工可点击入口	当前状态
CT-D01	已确认订单 CONFIRMED，尚无柜次	可创建并确认订单	确认后自动产生唯一柜次；重复事件不重复建柜	订单详情可进入关联柜次	待契约
CT-D02	不同渠道各一单	渠道主数据可用	柜次/清单/任务不得跨渠道混装或串查	排柜候选可按渠道辨识	待契约
CT-D03	已排柜但无真实柜号	临时柜身份可生成	不要求真实柜号即可排柜，内部身份稳定	预装清单可查看“待补号”柜次	待契约
CT-D04	已补真实柜号、PDA 可领取	CT-D03	补号后 PDA 入口开放且关联原内部柜身份	PDA 任务列表可进入	待契约
CT-D05	作业中更换真实柜号	CT-D04，PDA 已开始	柜号变化但柜次 ID、任务、清单、证据归属不漂移	详情与 PDA 同步显示新柜号	待契约
CT-D06	预装清单已生成/确认	CT-D03	清单版本、订单明细、数量及确认历史可追溯	预装清单列表/详情可点击	待契约
CT-D07	装柜清单进行中/已完成	CT-D04	装载明细、数量、状态与预装来源一致	装柜清单列表/详情可点击	待契约
CT-D08	PDA 领取、拣货、复核、异常摘要	CT-D04	overview 返回任务 ID、状态、版本、计数、photoCounts、photos、downloadPath 和异常原因	PDA 可完成主流程；Admin 入口待回传	服务端已冻结；人工入口待定
CT-D09	报关/清关资料及有效回执	CT-D06	目的港清关走货柜 /clearance；出口报关走 loading-list /customs；分别验证上传、完成和完成后替换锁定	报关协同入口待回传	服务端已冻结；人工入口待定
CT-D10	DO/PU 未齐、部分完成、全部完成	柜次与运输协同已建立	DELIVERY_ORDER、PICKUP_ORDER 可独立查询、上传和鉴权下载，版本与幂等有效	柜次详情入口待回传	服务端已冻结；人工入口待定
CT-D11	正常、异常、取消异常	任意有效柜次及显式货柜版本	标记/取消使用版本和必填原因；overview 保留 MARK/CANCEL 全部历史	货柜详情入口待回传	服务端已冻结；人工入口待定
CT-D12	多节点运输轨迹与操作日志	CT-D10	overview 时间线含运输更新、异常和 PDA 事件，按发生时间升序	详情时间线入口待回传	服务端聚合已冻结；人工入口待定
CT-D13	满足全部 LOADED 硬门禁	订舱、拖车、有效放行回执、PDA、五类证据完成	仅全部满足时进入 LOADED，重复完成幂等	订单/柜次详情显示完成且编辑锁定	待契约

全链验收用例

用例	场景	服务端/契约断言	UI/设备断言	证据要求	状态
CT-E01	CONFIRMED 自动建柜	状态事件自动建一个柜次；重放幂等；失败可观测	订单详情无需手工建柜即可看到柜次	前后资源 ID、事件/日志	待契约
CT-E02	渠道隔离	不同渠道不能进入同一排柜结果；交叉 ID 请求失败	候选、清单和详情不串渠道	双渠道正向及交叉负向响应	待契约
CT-E03	无真实柜号排柜	临时身份可完成排柜/预装；真实柜号字段可空	页面明确展示待补号，不伪造柜号	柜次 ID、预装版本	待契约
CT-E04	补号开放 PDA	合法补号后任务可领取；未补号时领取被稳定阻止	补号前后 PDA 入口状态同步	补号审计、领取响应	待契约
CT-E05	作业中换号身份不漂移	只变更展示柜号；柜次 ID、任务 ID、清单、证据关联不变	Admin/PDA 刷新后显示新号且进度不丢	换号前后关联快照	待契约
CT-E06	预装/装柜清单	生成、确认、版本、装载数量及来源关系完整	两类列表和详情均可人工点击	清单响应与页面截图	待契约
CT-E07	PDA 主链	领取、扫码、批量提交、复核、完成；幂等与版本冲突有效	真机/目标设备可完成，失败不假成功	请求链、设备记录	待契约
CT-E08	PDA 进度异常摘要	GET /api/platform/v1/containers/{id}/overview 返回 PDA 任务身份、版本、计数、照片摘要、文件 ID 与鉴权下载路径	Admin 入口待回传	overview 响应及字段完整性	服务端契约已冻结
CT-E09	清关/报关资料闭环	目的港清关：货柜 /clearance 查询/上传/完成；出口报关：loading-list /customs 查询/上传/完成；两者完成后均禁止替换	Admin 入口待回传	两条专用链路的版本、幂等、完成和锁定负向响应	服务端契约已冻结
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	LOADED 正向与逐项负向	五项硬门禁分别缺失时 fail-closed；全部满足后只迁移一次	完成后详情锁定，状态一致	5 个负向 + 1 个正向 + 幂等重放	待契约
CT-E14	跨客户与跨仓库隔离	交叉资源 ID 不可读写下载，不泄露资源存在性	页面无越权入口	双身份交叉请求证据	待契约

契约冻结清单

既有冻结基线

以下能力在本轮新增 overview 契约之前已经由三期产品确认版、既有 OpenAPI/Controller 和专项测试冻结。本轮不重定义其路径或状态机。

能力标识	冻结边界	事实来源	状态
confirmed-auto-container	CONFIRMED 自动建柜、幂等和唯一性	三期产品确认版及既有订单/货柜契约	既有冻结，待环境验收
channel-isolation	渠道隔离与禁止跨渠道混装	三期产品确认版及既有排柜契约	既有冻结，待环境验收
container-number-lifecycle	无真实柜号排柜、补号开放 PDA、作业中换号身份稳定	既有预装/货柜/PDA 契约	既有冻结，待环境验收
preload-and-loading-list	预装与装柜清单状态、版本、明细和历史	既有 Loading List OpenAPI/Controller/DTO	既有冻结，待环境验收
customs-documents-lock	清关/报关专用流程、完成态禁止替换	既有 LoadingListService、专用 Controller 与专项测试	既有冻结，待环境验收

本轮新增冻结契约

事实来源：baiyue-firstleg/firstleg/src/main/resources/openapi/phase3-container-overview-v1.yaml、PlatformContainerController、ContainerOverviewDtos、ContainerOverviewService、LoadingListService。

能力标识	冻结路径与字段	权限/并发	状态
container-overview	GET /api/platform/v1/containers/{id}/overview；聚合 container、loadingPlanId、PDA 摘要、documents、exception/history、timeline	platform:firstleg:container:view	已冻结
pda-progress-exception-summary	PDA 任务 ID/状态/版本、明细计数、photoCounts、photos（含 fileId/status/downloadPath）及异常原因	随 overview 查看权限	已冻结
container-abnormal-history	POST/DELETE /api/platform/v1/containers/{id}/exception；请求使用 overview 返回的 container.version、必填原因和幂等键	platform:firstleg:container:edit；版本冲突 fail-closed	已冻结
container-documents	通用查询、multipart 上传和受控文件下载仅支持 DO/PU；下载透传已校验 Content-Type，非法类型回退 application/octet-stream，并返回 UTF-8 文件名、no-store 和内容长度	查看/下载用 container list/view，上传用 edit；下载校验柜次、类型、文件 ID 及文件服务 tenant/business 归属	已冻结
do-pu	DELIVERY_ORDER、PICKUP_ORDER 通用查询/上传/下载	同 container-documents	已冻结
transport-trajectory-log	overview timeline 的事件类型、详情、操作者、发生时间；服务端升序	随 overview 查看权限	已冻结

最终安全分流

1. overview 与通用 documents 只覆盖 DELIVERY_ORDER、PICKUP_ORDER，不得向通用路径传清关或报关类型。
2. 目的港清关使用 /api/platform/v1/containers/{id}/clearance 及其专用上传、完成动作，权限为 platform:firstleg:customs:manage。
3. 出口报关使用 /api/platform/v1/first-leg/loading-lists/{planId}/customs 及其专用上传、完成动作；查询使用 loading-list list/view，写入使用 customs manage。
4. 清关和出口报关分别验证完成态禁止替换，不能用 DO/PU 通用上传替代。
5. 下载允许透传经校验的 Content-Type，非法值回退二进制类型；同时必须保留 UTF-8 文件名、no-store、内容长度及资源归属复核。

自动化落地门禁

真实环境脚本只有在对应能力“已冻结=是”后才能加入请求步骤，并必须满足：

1. 环境地址、账号和令牌只从环境变量读取。
2. 默认不执行；必须通过显式运行参数开启真实 HTTP。
3. 只通过业务 API 造数，不连接数据库，不调用 Jenkins。
4. 支持按本次运行标识检索资源，避免误用历史数据；清理动作仅在契约明确且安全时启用。
5. 输出脱敏 JSON 报告，逐请求记录 HTTP 状态、业务码、requestId、traceId 和资源 ID。
6. 对未冻结能力或冻结来源不一致输出 BLOCKED_CONTRACT，不得以跳过后仍报告全链通过。

当前阻断

阻断	影响	解除条件
Admin 入口与动作承载尚未由 Admin 任务回传	无法固定人工点击路径与 UI 断言	Admin 任务给出路由、状态动作和构建/测试结果
测试环境未获得部署授权且本任务禁止部署	无法验证环境是否已包含依赖实现	人工部署明确提交后，再执行获授权的验收轮次
未提供测试环境凭据和两组隔离身份	无法执行跨客户/跨仓库/下载鉴权负向用例	由总控提供临时验收身份或既有安全注入方式