@@ -1,6 +1,6 @@
# 货柜管理全链验收矩阵
> 更新时间：2026-08-13
> 更新时间：2026-08-14
> 当前任务：`019ff90b-a72d-7000-abdf-e5363357a564`
> 父任务：`019ff600-f9f1-78f1-a357-7c80c13e574e`
> 依赖任务：后端 `019ff90b-9b45-7191-b68f-c3b52567e3e4`、Admin `019ff90b-a037-79b0-b945-8f88bdbde9c5`
@@ -25,7 +25,7 @@
| 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-D08 | PDA 领取、拣货、复核、异常摘要 | CT-D04 | overview 分别返回 `taskStatus` 、 `workflowStatus` 、 任务 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` 全部历史 | 货柜详情入口待回传 | 服务端已冻结；人工入口待定 |
@@ -43,7 +43,7 @@
| 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-E08 | PDA 进度异常摘要 | `GET /api/platform/v1/containers/{id}/overview` 返回 PDA `taskStatus/workflowStatus` 、 任务身份、版本、计数、照片摘要、文件 ID 与鉴权下载路径；每个路径真实 GET 200 | 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 历史 | 服务端契约已冻结；版本来源阻断 |
@@ -72,7 +72,7 @@
| 能力标识 | 冻结路径与字段 | 权限/并发 | 状态 |
|---|---|---|---|
| `container-overview` | `GET /api/platform/v1/containers/{id}/overview` ；聚合 container、loadingPlanId、PDA 摘要、documents、exception/history、timeline | `platform:firstleg:container:list` ；旧 `container:view` 已移除 | 已冻结 |
| `pda-progress-exception-summary` | PDA 任务 ID/状态/ 版本、明细计数、`photoCounts` 、`photos` （含 fileId/status/downloadPath）及异常原因 | 随 overview 查看权限 | 已冻结 |
| `pda-progress-exception-summary` | PDA `taskStatus/workflowStatus` 、 任务 ID/版本、明细计数、`photoCounts` 、`photos` （含 fileId/status/downloadPath）及异常原因；照片下载为 `GET /api/platform/v1/containers/{id}/pda/photos/{fileId}/download` | 随 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` 和内容长度 | 查询/下载用 `platform:firstleg:container:list` ，上传用 `platform:firstleg:container:edit` ；旧 `container:view` 已移除；下载校验柜次、类型、文件 ID 及文件服务 tenant/business 归属 | 已冻结 |
| `do-pu` | `DELIVERY_ORDER` 、`PICKUP_ORDER` 通用查询/上传/下载 | 同 `container-documents` | 已冻结 |
@@ -104,3 +104,18 @@
| Admin 入口与动作承载尚未由 Admin 任务回传 | 无法固定人工点击路径与 UI 断言 | Admin 任务给出路由、状态动作和构建/测试结果 |
| 测试环境未获得部署授权且本任务禁止部署 | 无法验证环境是否已包含依赖实现 | 人工部署明确提交后，再执行获授权的验收轮次 |
| 未提供测试环境凭据和两组隔离身份 | 无法执行跨客户/跨仓库/下载鉴权负向用例 | 由总控提供临时验收身份或既有安全注入方式 |
## Marker 回归增量（ADMIN-API-20260814032734876）
| 回归项 | 当前冻结事实与自动化断言 | 当前结论 |
|---|---|---|
| Release 正式 DTO | `POST /api/platform/v1/ocean-bookings/{id}/release` 已冻结；`ReleaseRequest` 必填提单号、船名、航次、ETD、ETA，并保留 `expectedVersion` 。HTTP fixture 必须携带五字段；Admin 未填齐不得调用 release | `LANDED` ，不是路径阻断 |
| PDA overview 状态语义 | PDA 任务的 `taskStatus=LOADING` 与业务流转 `workflowStatus=AWAITING_REVIEW` 必须分字段返回；进度 100%、未解决数为 0 且任务仍为 `LOADING` 时必须明确为 `AWAITING_REVIEW` | 后端 DTO/OpenAPI/聚合已回传；`LANDED` ，待环境 HTTP 验收 |
| PDA overview 照片下载 | 对 `photos[]` 每个服务端 `downloadPath` 执行真实鉴权 GET；仅接受站内 `/api/` 路径、HTTP 200、非空二进制和非 JSON/HTML Content-Type | HTTP 回归已准备；待获授权环境验收 |
| 客户公开名称一致性 | `customerId` 筛选后的订舱、拖车和预装列表/详情必须显示 IAM `tenantName` ，不得优先 `legalName` ；列表、详情及关联名称一致 | 列表筛选与拖车预约新增表单已统一 `tenantName` ； `LANDED` ，待人工筛选回归 |
| 已有 `containerNo` 动作语义 | 已有真实柜号时补号动作不可伪装成首次补号；换号前后柜次 ID、PDA taskId、loadingPlanId 和证据归属必须稳定 | 后端 HTTP fixture 已有身份稳定断言；待 Admin 动作文案/禁用态回传 |
| 订舱/拖车详情关联名称 | 详情中的客户、柜次、订舱及关联资源名称必须来自正式详情响应，并与同 ID 列表显示一致 | 路径已存在；名称一致性待 Admin 回传，不误报后端路径阻断 |
| 拖车附件闭环 | `POST /truck-appointments/{id}/attachments` 引用与 `DELETE /truck-appointments/{id}/attachments/{attachmentId}` 已冻结，HTTP 已覆盖上传、列表、伪造拒绝和删除 | 后端路径 `LANDED` ；拖车附件新增入口缺失，`BLOCKED_CONTRACT` （待 Admin 弹框回传） |
| 中文状态、弹框与 390px 布局 | 列表/详情状态必须中文；release、附件、柜号动作使用正式弹框；390px 下字段、按钮、弹框不横向溢出或遮挡 | `BLOCKED_CONTRACT` （待 Admin 定向测试与 390px 截图证据） |
说明：`BLOCKED_CONTRACT` 仅标记明确缺失的 DTO 字段或 Admin 承载，不把已存在的 release、拖车附件 API 路径降级为未冻结能力。