优化

2026-08-14 14:27:00 +08:00
parent a7390ae340
commit 272dcff57e
3 changed files with 24 additions and 6 deletions
@@ -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 路径降级为未冻结能力。
@@ -15,7 +15,7 @@

 - Admin 新增 6 个正式菜单页面：入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理、海外仓阶梯费用。
 - 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史，不再新增独立“接收审核”页面。
- 正常流程由“测量审核通过”触发后端自动计费、发布费用并完成入库；前端不把 `calculate → confirm → send` 串成常规人工流程。
+- 正常流程在“测量审核通过”后直接进入 `WAIT_SPLIT`；后端可尽力生成初算费用，但价格缺失或初算失败不得阻塞主流程。平台人员可独立修改计费量、单价和附加费，金额由服务端重算。
 - Client 不新增独立入库菜单或列表，只在现有头程订单详情中增加“入库与费用”只读区。
 - 到仓预报、预约、签到、分批收货、标签、冲正、差异通知、上架任务、位置历史和通用费用项目当前没有匹配的公开后端接口，暂不拆前端实现任务。

@@ -32,7 +32,7 @@

 | 主题 | 旧规划或 V2 描述 | 当前后端事实 | 前端处理 |
 |---|---|---|---|
-| 正常入库动作 | 人工试算、确认、发送费用后入库 | 测量审核通过后自动计费、发布费用并完成入库 | 审核成功后刷新详情和费用，不串行调用三个计费接口 |
+| 正常入库动作 | 人工试算、确认、发送费用后入库 | 测量审核通过后直接进入待分柜，费用仅作独立初算和人工维护 | 审核成功后刷新详情；初算失败展示非阻断提示，不影响待分柜操作 |
 | 托盘库位 | 操作员选择托盘和候选库位 | 测量提交/审核编排自动准备和占用，平台无人工分配公开接口 | 详情只读展示分配结果 |
 | 接收审核 | 独立页面 | 无独立节点 | 不建设；相关结果并入详情和审核区 |
 | Client 到仓预报 | 规划中存在 | 无商户公开接口 | 不建设 |
@@ -20,6 +20,7 @@

 | task_id | parent_task_id | display_name | responsibility |
 |---|---|---|---|
+| `019ffee2-50bd-7c30-aabd-bbe59a7dd16e` | `019ff8e7-aa4a-7ee0-b856-ee5db7ae525f` | Admin窄屏导航辅助状态修复 | 修复 Admin 全局布局在窄屏侧栏隐藏或展开时菜单按钮辅助名称与展开状态不一致，并维护对应响应式测试 |
 | `019ff9ad-9bd1-7393-a561-a2b2df6d4eec` | `019ff8e7-aa4a-7ee0-b856-ee5db7ae525f` | 全量测试门禁脚本修复 | 修复菜单/权限相关全量合同测试、后端回归覆盖及统一 SQL 快照门禁 |
 | `019ff5fa-b448-7713-a142-1af7f2c72d2d` | `019ff0da-7699-7532-ac64-703325c995fd` | 简化清关报关后端 | 按原型维护货柜清关资料与完成动作、装柜清单报关资料与完成动作的最小后端契约、文件归属、审计及数据库脚本 |
 | `019ff5fa-bdfc-7bf1-8cb2-18a25dccc67d` | `019ff0da-7699-7532-ac64-703325c995fd` | Admin原型流程与验收收敛 | 按原型收敛 Admin 导航与路由，在货柜和装柜清单承载清关/报关操作，并同步全量人工状态矩阵 |
@@ -43,6 +44,8 @@
 | `019ff947-0478-7690-998f-91b545353d06` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情统计-正式应收聚合 | 基于正式应收结算模型提供客户累计应收、已收、未结清及相关派生指标契约和测试 |
 | `019ff947-0c7b-7b60-9031-54201e8ca79f` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情统计-在途柜量TEU | 按实际开船未到仓口径提供客户在途柜数、TEU、未知柜型聚合契约和测试 |
 | `019ff947-1182-79e1-9054-ac11b70891d4` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情统计-Admin接入与全量验收 | 接入运单、应收和在途柜量三项统计，按原型实现客户详情卡片、权限状态、前端测试与全量验收脚本 |
+| `019ffedc-35d1-7cd1-b918-78be782d6553` | `019ffe52-81c7-74b2-9e8c-644428843584` | 国内仓订单-费用人工调整界面 | 按测量审核不阻塞待分柜、费用仅作初算的契约，维护 Admin 入库费用计费量、单价和附加费人工调整界面及测试，不修改后端、导航或权限初始化 |
+| `019ffedb-8e47-7262-84fa-13c4309864f4` | `019ff600-e924-7902-b00e-fa1ee1658e08` | 客户详情操作日志分页计数修复 | 修复客户详情操作日志实际记录与分页总数不一致，核对审计分页契约、Admin 适配和回归测试；不得部署或写测试环境 |

 ## 规则