仙剑奇侠传经

2026-08-17 15:41:47 +08:00
parent b78b493c9e
commit 2e77d0f1ce
3 changed files with 39 additions and 4 deletions
@@ -3,7 +3,7 @@
 > 更新时间：2026-08-15  
 > 当前任务：`019ff90b-a72d-7000-abdf-e5363357a564`  
 > 父任务：`019ff600-f9f1-78f1-a357-7c80c13e574e`  
-> 依赖任务：后端 `019ff90b-9b45-7191-b68f-c3b52567e3e4`、Admin `019ff90b-a037-79b0-b945-8f88bdbde9c5`  
+> 依赖任务：后端主链 `019ff90b-9b45-7191-b68f-c3b52567e3e4`、动态增量后端 `01a00e91-2124-7960-95d6-e0d0f81959f9`、Admin `019ff90b-a037-79b0-b945-8f88bdbde9c5`  
 > 边界：只维护根目录脚本、验收文档和测试矩阵；不修改 Admin 或 Java 业务源码，不部署、不触发 Jenkins、不写测试环境数据库。

 ## 验收口径
@@ -30,7 +30,8 @@
 | CT-D10 | DO/PU 未齐、部分完成、全部完成 | 柜次与运输协同已建立 | `DELIVERY_ORDER`、`PICKUP_ORDER` 可独立查询、上传和鉴权下载，版本与幂等有效 | 柜次详情入口待回传 | 服务端已冻结；人工入口待定 |
 | CT-D11 | 正常、异常、取消异常 | 任意有效柜次及显式货柜版本 | 标记/取消使用版本和必填原因；overview 保留 `MARK`/`CANCEL` 全部历史 | 货柜详情入口待回传 | 服务端已冻结；人工入口待定 |
 | CT-D12 | 多节点运输轨迹与操作日志 | CT-D10 | overview 时间线含运输更新、异常和 PDA 事件，按发生时间升序 | 详情时间线入口待回传 | 服务端聚合已冻结；人工入口待定 |
-| CT-D13 | 满足全部 `LOADED` 硬门禁 | 订舱、拖车、有效放行回执、PDA、五类证据完成 | 仅全部满足时进入 `LOADED`，重复完成幂等 | 订单/柜次详情显示完成且编辑锁定 | 待契约 |
+| CT-D13 | 满足全部 `LOADED` 硬门禁 | 订舱、拖车、有效放行回执、PDA 拣货、五类证据完成 | PDA `complete` 写前预检 inbound `LOADING`、bridge、订舱 `RELEASED`、同稳定 `containerBookingId` 的拖车 `COMPLETED` 和五类 ACTIVE 证据；缺项 A0409 且 task/plan/inbound 零写入，齐备后同一事务完成三者并推进 `LOADED` | 订单/柜次详情显示完成且编辑锁定 | `LANDED_STATIC`：OpenAPI 与 HTTP 脚本已接线；待部署后真实 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 复核 |

 ## 全链验收用例

@@ -48,11 +49,31 @@
 | 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-E13 | `LOADED` 正向与逐项负向 | 五项硬门禁分别缺失时 fail-closed；拖车按稳定 `containerBookingId` 归属，历史 `loadingPlanId` 为空不再构成错误门禁；正式拖车完成后才允许 PDA `complete` 迁移一次 | PDA 完成页、入库单和订单详情不得出现无解释的完成/`LOADING` 分裂 | 逐项负向 + 1 个正向 + 幂等重放；记录拖车 ID、柜次 ID、计划 ID、状态、业务码、`requestId/traceId` | `LANDED_STATIC`：失败零写入和最终同事务响应已锁定；待部署后真实 HTTP 复核 |
 | CT-E14 | 跨客户与跨仓库隔离 | 交叉资源 ID 不可读写下载，不泄露资源存在性 | 页面无越权入口 | 双身份交叉请求证据 | 待契约 |
 | CT-E15 | push 幂等、冲突与事务回滚 | 首次成功请求冻结 path/body/expectedVersion/key；同 key 原样重放只读且返回首次结果；同 key 异参、新 key 重复均冲突；各负向后计划、版本、历史、bridge、PDA 全快照零漂移；首次 push 在 bridge 中途失败时整事务零残留且不得触发 PDA | 冲突或失败后页面刷新仍只显示首次成功事实 | 原始请求、三次回查全快照、失败 `requestId/traceId`；中途失败由后端事务合同覆盖 | 新时序合同已冻结，待环境验收 |
 | CT-E16 | 默认 Admin HTTP 同 marker 完整链 | 默认入口按 `phase3-container-loading -> phase3-loading -> overview/PDA/evidence -> customs -> loading-finalize` 串行；下游只消费 `phase3Loading` 发布的 `taskId/inboundId/loadingPlanId/containerBookingId`，最终同一订单详情和列表均为 `LOADED` | 同一批次可从订单、柜次、预装、PDA、报关入口逐级回查 | 全新 marker、关键资源 ID、五类二进制证据、各请求 `requestId/traceId`、最终统一订单状态 | 静态合同已接入默认入口，待环境 HTTP |
 | CT-E17 | 订舱代理不区分国内/国外 | 供应商必须为正式 `supplierId` 对应的 `ACTIVE + BOOKING` 记录，名称使用服务端快照；查询、创建和内部快照校验不得携带或要求 `DOMESTIC/INTERNATIONAL scope`，但类别或启用状态不符仍 fail-closed | 订舱代理候选不显示国内/国外范围门禁 | fixture 请求、Warehouse 内部快照、Firstleg 类别/启用校验及 Admin 候选静态合同；部署后补真实 HTTP | Warehouse/Firstleg 共享改动已可见；Admin 与环境 HTTP 待收口 |
+| CT-E18 | PDA 进行中增量预装与最终完成竞态 | 领取后、最终完成前新增入库单必须复用同一 task；新项出现后撤回最终完成门禁，旧 token 返回 A0409“库存已变化，请刷新后重试”且零写入；未拣项可删除，已拣项删除或减量拒绝；Admin 增量与 PDA final complete 同锁 task 行，只允许一个事务成功；`COMPLETED` 后全部变更拒绝 | Admin 增量结果与 PDA 队列实时一致，失败提示不伪造完成 | 增删前后计划/task/items/evidence 投影、版本和操作历史；并发双方响应及最终唯一事实 | `LANDED_STATIC`：OpenAPI、HTTP 双请求 winner/loser 脚本及离线合同已接线；待部署后定向复核 |
+
+## PDA 完成后未进入 LOADED 的已登记回归
+
+- 真实测试样本：订单 `NYEXX2608170001`；PDA task、review、装柜计划与五类证据均已完成，但 inbound 仍为 `LOADING`。
+- 门禁只读证据：`ocean_ready=1`、`truck_ready=0`；同柜拖车预约 `TA2089239590749704194` 的 `loading_plan_id=NULL`、状态为 `LOADING`。
+- 当前冻结事实：`phase3-loading` 只完成 claim/batch/证据与动态增量，任务保持 `LOADING/AWAITING_REVIEW`；下游门禁齐备后，`phase3-loading-finalize` 调用 `POST /pda-loading/tasks/{taskId}/complete`。该调用在同一 Firstleg 事务完成 task/plan/projection/inbound 并推进 `LOADED`，不再调用旧 `/inbounds/{id}/loading/complete`。
+- 拖车归属统一使用稳定 `containerBookingId`，不要求历史 `loadingPlanId` 非空；新建/编辑由服务端解析并冻结计划。缺拖车、未完成或归属不匹配均 A0409，且 task/plan/inbound 零写入。
+- 部署后回归包：① PDA 完成响应与 task/inbound/order 回查一致；② 无拖车、拖车未完成、拖车归属不匹配分别返回明确业务证据并保持 `LOADING`；③ 正式关联拖车完成后 PDA `complete` 推进 `LOADED`；④ 历史空 `loadingPlanId` 按 `containerBookingId` 正式口径覆盖正反例；⑤ 失败分支保留 path、HTTP、业务码、message、`requestId/traceId`，且不得继续执行任何仅限 `LOADED` 的突变请求。
+
+## PDA 进行中增量预装冻结回归
+
+- 冻结来源仅跟踪动态增量后端任务 `01a00e91-2124-7960-95d6-e0d0f81959f9` 落盘的 SmartLoading assign/adjust/remove、capability DTO/OpenAPI 和版本并发契约；不再向后端主链任务重复询问动态字段。
+- 用户确认：预装清单在 PDA 尚未最终确认装柜完成前允许继续添加入库单，并由原有同一 PDA task 继续拣货；不得通过新建第二个 task 或替换稳定四元身份实现。
+- 必测时序：`EDITING` 添加；task 已领取且仍未完成时添加；新增项进入同一 `taskId + inboundId + loadingPlanId + containerBookingId` 工作集；计划/task/item 版本单调递增；旧 inventory token 返回正式版本冲突并零写入；刷新后可拣新增项并再次满足完成条件。
+- 门禁撤回：新增未拣项后，原先的 ready、完成度及五类证据完成投影不得继续允许 final complete；新增项全部拣完并重新满足正式证据/下游条件后才恢复。
+- 删除与减量：已拣项删除或减量必须拒绝且全链零漂移；未拣项删除成功后同步 task、计划、库存快照与 readiness。正式写端点为 plan assignments、item PATCH、item DELETE，分别使用 planVersion/itemVersion 与 operationId。
+- 并发与终态：Admin 增量与 PDA final complete 并发只允许一个事务成功，失败方必须取得明确业务冲突证据；task/计划进入 `COMPLETED` 后，添加、删除、减量全部拒绝。
+- 隔离基线不变：容量/限重、客户、仓库、物流渠道、柜型/规格和 ACTIVE 柜次归属继续 fail-closed；任何增量都不得借历史入库单、跨 marker 或创建第二个任务绕过。
+- 默认全量接入：`phase3-loading` 已在首次 batch 与 final complete 之间接入本轮 marker 的独立入库单、旧 token 负向、未拣删除、重新加入、调整、刷新补拣和已拣删除/减量零写入；`phase3-pda-convergence` 回查稳定四元和唯一任务，最后由 `phase3-loading-finalize` 并发提交同数量调整与 final complete，断言恰好一方成功、刷新胜方版本后唯一收敛 `LOADED`，并验证 `COMPLETED` 后全部写拒绝。真实 HTTP 待部署后定向执行。

 ## P3-Q14 文档同步待总控统一

@@ -27,6 +27,7 @@
 | `019ff905-a477-7a03-b806-953ba598d305` | `01a00e43-b4cb-72e1-ae21-ff30c427fce9` | 财务五页-客户对账单 | 按已确认财务一期契约和原型补齐客户对账单筛选、主表、明细与支付历史联动功能 |
 | `019ff905-a8d5-7802-bf31-29919070a312` | `01a00e43-b4cb-72e1-ae21-ff30c427fce9` | 财务五页-应收应付结算单 | 按已确认财务一期契约和原型补齐应收、应付结算单汇总、筛选、详情、收付款及作废重开功能 |
 | `019ff90b-9b45-7191-b68f-c3b52567e3e4` | `01a00e43-8fc7-7e30-8ae0-175d873a4cfd` | 货柜管理后端扩展契约 | 补齐清关报关与 DO/PU 文件查看下载、货柜异常及历史、运输轨迹日志和柜次 PDA 作业摘要的后端契约、权限、OpenAPI、SQL 与测试 |
+| `01a00e91-2124-7960-95d6-e0d0f81959f9` | `01a00e43-8fc7-7e30-8ae0-175d873a4cfd` | 预装清单动态增量后端契约 | 维护智能装柜与预装清单在 PDA 最终完成前的动态增量编排、计划与明细可编辑能力、PDA 同任务增量同步、版本并发及对应 OpenAPI 和后端测试；不接管 PDA 最终完成、拖车门禁或 LOADED 状态事务 |
 | `019ff90b-a037-79b0-b945-8f88bdbde9c5` | `01a00e43-8fc7-7e30-8ae0-175d873a4cfd` | 货柜管理 Admin 功能补齐 | 补齐货柜与装柜清单的文件闭环、异常处理、更多操作、运输轨迹日志、PDA 摘要和必要列表字段，不含柜态看板 |
 | `019ff90b-a72d-7000-abdf-e5363357a564` | `01a00e43-8fc7-7e30-8ae0-175d873a4cfd` | 货柜管理全链验收与状态数据 | 维护货柜管理全流程契约测试、真实验收脚本、各状态人工可点击数据矩阵和验收证据，不修改业务源码 |
 | `01a00037-08c8-7883-b76d-5c22b88e2329` | `01a00e43-8fc7-7e30-8ae0-175d873a4cfd` | PDA 拣货与装柜取证 | 维护 PDA 拣货、批量提交、任务恢复、装柜证据、状态提示及现场交互，并同步 PDA 本地契约测试；不修改 Admin、Client 或 Java 业务源码 |
@@ -824,7 +824,7 @@ components:
        expectedVersion: {type: integer, minimum: 0}
    ReconciliationSummary:
      type: object
-      required: [statementId, statementNo, customerId, customerName, periodStart, periodEnd, creditDays, currency, totalReceivable, receivedAmount, outstandingAmount, settled, status, version, createdAt, updatedAt]
+      required: [statementId, statementNo, customerId, customerName, periodStart, periodEnd, creditDays, currency, totalReceivable, receivedAmount, outstandingAmount, settled, status, version, createdBy, createdAt, updatedBy, updatedAt]
      properties:
        statementId: {$ref: '#/components/schemas/Id'}
        statementNo: {type: string}
@@ -841,7 +841,11 @@ components:
        settled: {type: boolean}
        status: {$ref: '#/components/schemas/ReconciliationStatus'}
        version: {type: integer, minimum: 0}
+        createdBy: {$ref: '#/components/schemas/Id'}
+        createdByName: {type: string, description: 创建时操作人名称快照；历史数据可能为空}
        createdAt: {type: string, format: date-time}
+        updatedBy: {$ref: '#/components/schemas/Id'}
+        updatedByName: {type: string, description: 最后修改时操作人名称快照；历史数据可能为空}
        updatedAt: {type: string, format: date-time}
    ReconciliationDetail:
      allOf:
@@ -884,6 +888,7 @@ components:
        afterAmount: {$ref: '#/components/schemas/Money'}
        reason: {type: string}
        operatorId: {$ref: '#/components/schemas/Id'}
+        operatorName: {type: string, description: 操作发生时的名称快照}
        occurredAt: {type: string, format: date-time}
    StatementRead:
      type: object
@@ -901,6 +906,12 @@ components:
        currency: {type: string, enum: [CNY]}
        status: {type: string, enum: [DRAFT, ISSUED, PARTIALLY_PAID, PAID, VOIDED]}
        version: {type: integer, minimum: 0}
+        createdBy: {$ref: '#/components/schemas/Id'}
+        createdByName: {type: string, description: 创建时操作人名称快照；历史数据可能为空}
+        createdAt: {type: string, format: date-time}
+        updatedBy: {$ref: '#/components/schemas/Id'}
+        updatedByName: {type: string, description: 最后修改时操作人名称快照；历史数据可能为空}
+        updatedAt: {type: string, format: date-time}
    StatementLineRead:
      type: object
      required: [id, sourceType, sourceId, sourceVersion, feeItemName, amount, currency]
@@ -1058,6 +1069,7 @@ components:
        afterAmount: {$ref: '#/components/schemas/Money'}
        reason: {type: string}
        operatorId: {$ref: '#/components/schemas/Id'}
+        operatorName: {type: string, description: 操作发生时的名称快照}
        occurredAt: {type: string, format: date-time}
    CreateReceivableSettlementRequest:
      type: object
@@ -1095,6 +1107,7 @@ components:
          type: array
          items: {$ref: '#/components/schemas/Id'}
        createdBy: {$ref: '#/components/schemas/Id'}
+        createdByName: {type: string, description: 登记时操作人名称快照；历史数据可能为空}
        createdAt: {type: string, format: date-time}
        remark: {type: string}
    ReceiptAllocationRequest: