2026-09-28 16:01:16 +08:00
3 changed files with 152 additions and 2 deletions
@@ -0,0 +1,106 @@
+# 货柜管理全链验收矩阵
+
+> 更新时间：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 任务给出路由、状态动作和构建/测试结果 |
+| 测试环境未获得部署授权且本任务禁止部署 | 无法验证环境是否已包含依赖实现 | 人工部署明确提交后，再执行获授权的验收轮次 |
+| 未提供测试环境凭据和两组隔离身份 | 无法执行跨客户/跨仓库/下载鉴权负向用例 | 由总控提供临时验收身份或既有安全注入方式 |
@@ -9,6 +9,10 @@
 | task_id | display_name | responsibility |
 |---|---|---|
 | `019ff0da-7699-7532-ac64-703325c995fd` | 全量验收总控 | 统筹跨模块契约、专项实现、验证、人工部署准备及正式全量验收接入；当前覆盖 Finance 一期与三期智能装柜渠道柜链路 |
+| `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户管理与系统管理总控 | 统筹客户管理与系统管理的原型差异确认、缺失能力实现、跨模块契约接入、自动化验证与人工验收准备 |
+| `019ff600-f9f1-78f1-a357-7c80c13e574e` | 货柜管理全流程总控 | 统筹货柜管理未做与少做项的后端契约、Admin 页面收敛、全链验收和人工确认；柜态看板暂不进入开发范围 |
+| `019ff8dc-8700-7d93-a29b-3175b026a2ab` | 头程后台国内仓供应商通用总控 | 统筹头程后台国内仓、供应商管理和通用模块的产品差异确认、独立任务拆分、共享契约、集成装配与验证 |
+| `019ff8e7-aa4a-7ee0-b856-ee5db7ae525f` | 头程后台菜单与权限总控 | 统筹头程后台各模块菜单分组、页面列表与操作权限点的原型差异核对、人工确认、实现收敛及验证；统一集成 Admin 导航/路由权限和 IAM 菜单权限初始化，其他总控不得覆盖已确认权限语义 |

 总控创建、需要长期复用的用户独立任务：

@@ -17,11 +21,21 @@
 | `019ff5fa-b448-7713-a142-1af7f2c72d2d` | `019ff0da-7699-7532-ac64-703325c995fd` | 简化清关报关后端 | 按原型维护货柜清关资料与完成动作、装柜清单报关资料与完成动作的最小后端契约、文件归属、审计及数据库脚本 |
 | `019ff5fa-bdfc-7bf1-8cb2-18a25dccc67d` | `019ff0da-7699-7532-ac64-703325c995fd` | Admin原型流程与验收收敛 | 按原型收敛 Admin 导航与路由，在货柜和装柜清单承载清关/报关操作，并同步全量人工状态矩阵 |
 | `019ff5fe-dcc2-7481-8d8a-b0e1b39de145` | `019ff0da-7699-7532-ac64-703325c995fd` | File平台公共业务文件适配 | 维护内部服务令牌入口对平台公共业务文件 `tenantId=0` 的受控支持、清关报关文件类型白名单及上传校验下载契约 |
-| `019ff600-e924-7902-b00e-fa1ee1658e08` | `019ff0da-7699-7532-ac64-703325c995fd` | 平台基础原型只读审计 | 只读比对客户、平台用户、角色权限、仓库、库位、托盘及主数据的已确认范围、原型和当前实现 |
 | `019ff600-f15a-7be3-8f5d-8771115f9828` | `019ff0da-7699-7532-ac64-703325c995fd` | 订单入库审计与 WAIT_SPLIT 修复 | 先复用订单、测量、计费、统一订单及客户工作台审计证据，再修复 WAIT_SPLIT 主链并同步必要消费者与测试 |
-| `019ff600-f9f1-78f1-a357-7c80c13e574e` | `019ff0da-7699-7532-ac64-703325c995fd` | 货柜出仓审计与 PDA 门禁修复 | 先复用订舱、拖车、智能装柜、预装、装柜清单及 PDA 审计证据，再修复渠道约束和真实柜号现场门禁 |
 | `019ff601-029f-7801-851c-7c68e02804ca` | `019ff0da-7699-7532-ac64-703325c995fd` | 财务审计与正式结算契约修复 | 先复用财务审计证据，再统一正式结算模型、Client JSON 适配、权限和相关测试 |
 | `019ff607-87b3-70b3-b5c3-7bc9c528363c` | `019ff0da-7699-7532-ac64-703325c995fd` | 测试环境重建与人工验收数据矩阵 | 维护数据库重建后的基础初始化数据核验、全量验收脚本编排、各真实可达列表状态样本保留及人工点击验收报告 |
+| `019ff905-bd45-71a1-a5f5-b40b620fcc83` | `019ff8dc-8700-7d93-a29b-3175b026a2ab` | 头程后台｜国内仓测量｜独立列表与审核待办 | 实现国内仓订单测量独立筛选页与测量数据审核独立待办页，复用现有真实接口和权限 |
+| `019ff905-c186-78d2-bd44-e7eb08208459` | `019ff8dc-8700-7d93-a29b-3175b026a2ab` | 头程后台｜通用模块｜下载弹框与原型收敛 | 将下载任务详情收敛为原型居中弹框，并只读复核费用项目、仓库和船期价格表差异 |
+| `019ff905-c5e9-7631-a64e-79f7644ffce8` | `019ff8dc-8700-7d93-a29b-3175b026a2ab` | 头程后台｜供应商管理后端｜公共供应商契约 | 建设独立于往来单位的平台公共供应商后端模型、权限、接口、审计和 OpenAPI |
+| `019ff905-ca76-7123-af57-5825b5773d2b` | `019ff8dc-8700-7d93-a29b-3175b026a2ab` | 头程后台｜国内整柜后端｜入出库库存契约 | 建设国内整柜入库、出库、库存和详情交易记录的独立后端契约与状态流 |
+| `019ff91d-8d32-72b3-9f7d-abe918ad08ab` | `019ff8dc-8700-7d93-a29b-3175b026a2ab` | 头程后台｜供应商管理前端｜列表与独立编辑页 | 按真实供应商契约建设分类列表、详情、独立新增编辑页、营业执照查看和权限错误态 |
+| `019ff91d-91a4-79a1-8641-8ef0379619dd` | `019ff8dc-8700-7d93-a29b-3175b026a2ab` | 头程后台｜国内整柜前端｜入出库库存与详情 | 按真实整柜契约建设入库单、出库单、库存、交易详情及幂等并发交互 |
+| `019ff905-a055-7723-b05e-598399fc183e` | `019ff601-029f-7801-851c-7c68e02804ca` | 财务五页-客户账户与应收应付 | 按已确认财务一期契约和原型补齐客户账户、账户流水、费用来源列表与独立详情页功能 |
+| `019ff905-a477-7a03-b806-953ba598d305` | `019ff601-029f-7801-851c-7c68e02804ca` | 财务五页-客户对账单 | 按已确认财务一期契约和原型补齐客户对账单筛选、主表、明细与支付历史联动功能 |
+| `019ff905-a8d5-7802-bf31-29919070a312` | `019ff601-029f-7801-851c-7c68e02804ca` | 财务五页-应收应付结算单 | 按已确认财务一期契约和原型补齐应收、应付结算单汇总、筛选、详情、收付款及作废重开功能 |
+| `019ff90b-9b45-7191-b68f-c3b52567e3e4` | `019ff600-f9f1-78f1-a357-7c80c13e574e` | 货柜管理后端扩展契约 | 补齐清关报关与 DO/PU 文件查看下载、货柜异常及历史、运输轨迹日志和柜次 PDA 作业摘要的后端契约、权限、OpenAPI、SQL 与测试 |
+| `019ff90b-a037-79b0-b945-8f88bdbde9c5` | `019ff600-f9f1-78f1-a357-7c80c13e574e` | 货柜管理 Admin 功能补齐 | 补齐货柜与装柜清单的文件闭环、异常处理、更多操作、运输轨迹日志、PDA 摘要和必要列表字段，不含柜态看板 |
+| `019ff90b-a72d-7000-abdf-e5363357a564` | `019ff600-f9f1-78f1-a357-7c80c13e574e` | 货柜管理全链验收与状态数据 | 维护货柜管理全流程契约测试、真实验收脚本、各状态人工可点击数据矩阵和验收证据，不修改业务源码 |

 ## 规则

@@ -501,6 +501,28 @@ paths:
        '404': {$ref: '#/components/responses/BusinessError'}
        '409': {$ref: '#/components/responses/BusinessError'}
        '503': {$ref: '#/components/responses/BusinessError'}
+  /platform/finance/v1/settlements/{settlementId}/actions:
+    post:
+      operationId: actionSettlement
+      summary: 作废或重开未发生收付款的结算单
+      x-contract-status: FROZEN
+      x-idempotency: FULL_REQUEST_HASH_SAME_REPLAY_DIFFERENT_CONFLICT
+      x-state-machine: ISSUED -> VOIDED -> ISSUED；paidAmount 必须为 0
+      x-permission: platform:finance:settlement:void
+      parameters:
+        - $ref: '#/components/parameters/SettlementId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/SettlementActionRequest'}
+      responses:
+        '200': {$ref: '#/components/responses/SettlementDetailResponse'}
+        '400': {$ref: '#/components/responses/BusinessError'}
+        '403': {$ref: '#/components/responses/BusinessError'}
+        '404': {$ref: '#/components/responses/BusinessError'}
+        '409': {$ref: '#/components/responses/BusinessError'}
 components:
  parameters:
    InternalServiceToken:
@@ -1135,6 +1157,14 @@ components:
          items: {$ref: '#/components/schemas/Id'}
        expectedVersion: {type: integer, minimum: 0}
        remark: {type: string, maxLength: 500}
+    SettlementActionRequest:
+      type: object
+      additionalProperties: false
+      properties:
+        action: {type: string, enum: [VOID, REOPEN]}
+        reason: {type: string, minLength: 1, maxLength: 500}
+        expectedVersion: {type: integer, minimum: 0}
+      required: [action, reason, expectedVersion]
    ErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/TraceMeta'