feat: complete overseas customer and PDA workflows
This commit is contained in:
@@ -5,7 +5,7 @@
|
||||
| 对话 ID | 主题 | 负责文件 / 场景 |
|
||||
|---|---|---|
|
||||
| 当前总控对话 | Admin 全量脚本 | 总入口、`system.mjs`、`master-data.mjs`、`downloads.mjs`、最终集成与全量报告 |
|
||||
| `019ff0da-7699-7532-ac64-703325c995fd` | Finance 一期验收总控 | `finance.mjs`、Finance 正式全量接入与报告 |
|
||||
| `019ff0da-7699-7532-ac64-703325c995fd` | Finance 订单与客户验收总控 | `finance.mjs`、Finance 正式全量接入与报告 |
|
||||
| `019ff905-a477-7a03-b806-953ba598d305` | Finance 下载中心共享契约 | `finance-downloads.mjs`、直接契约测试与 Finance 完整链接入；不覆盖通用 `downloads.mjs` |
|
||||
| `019fdbd3-f24f-7903-9124-de79c3ba37d0` | 客户尺寸规则 | 总入口内 `customer-dimension-rules` 子场景；不得改其他 customers 流程 |
|
||||
| `019fdb7d-8e29-7c40-bda6-5a29dcb37971` | OCR 扫描 | `inbound-weight-ocr.mjs` |
|
||||
|
||||
@@ -63,7 +63,7 @@ export async function run(context) {
|
||||
| 订单创建、可计价主数据、幂等零漂移与审核异步收敛 | `orders.mjs` | `orders-pricing-fixture-contract.test.mjs`、`orders-lifecycle-idempotency-contract.test.mjs`、`orders-approval-convergence-contract.test.mjs` |
|
||||
| 入库测量、首次打印冻结箱码与墨家扫码 | `inbound-measurement.mjs` | `inbound-measurement-box-code-contract.test.mjs` |
|
||||
| 入仓自动头程费用、派生详情、人工发布与 MANUAL 其他费用版本 | `inbound-fees.mjs`（前置：`merchant-qualification-fixture,orders,inbound-measurement`） | `inbound-fees-contract.test.mjs` |
|
||||
| 三期模拟柜关联、柜次概览、渠道隔离、装柜模型桥接、PDA、动态增量、四类货柜资料、报关与证据/出仓门禁 | `phase3-container-loading.mjs`、`ocean-booking-fixture.mjs`、`phase3-container-overview.mjs`、`phase3-loading.mjs`、`phase3-loading-model-bridge.mjs`、`phase3-pda-convergence.mjs`、`phase3-evidence-gate.mjs`、`phase3-loading-finalize.mjs`、`phase3-container-documents.mjs`、`phase3-customs.mjs`、`phase3-outbound-dispatch.mjs` | `container-simulation-association-contract.test.mjs`、`container-specification-fixture-contract.test.mjs`、`ocean-booking-channel-contract.test.mjs`、`phase3-container-regression-contract.test.mjs`、`phase3-loading-model-bridge-contract.test.mjs`、`phase3-loading-dynamic-final-contract.test.mjs`、`phase3-container-documents-contract.test.mjs`、`phase3-phase4-departure-pickup-chain-contract.test.mjs`、`phase3-producer-chain-contract.test.mjs`、`manual-state-loading-pda-contract.test.mjs` |
|
||||
| 国内货柜履约模拟柜关联、柜次概览、渠道隔离、装柜模型桥接、PDA、动态增量、四类货柜资料、报关与证据/出仓门禁 | `phase3-container-loading.mjs`、`ocean-booking-fixture.mjs`、`phase3-container-overview.mjs`、`phase3-loading.mjs`、`phase3-loading-model-bridge.mjs`、`phase3-pda-convergence.mjs`、`phase3-evidence-gate.mjs`、`phase3-loading-finalize.mjs`、`phase3-container-documents.mjs`、`phase3-customs.mjs`、`phase3-outbound-dispatch.mjs` | `container-simulation-association-contract.test.mjs`、`container-specification-fixture-contract.test.mjs`、`ocean-booking-channel-contract.test.mjs`、`phase3-container-regression-contract.test.mjs`、`phase3-loading-model-bridge-contract.test.mjs`、`phase3-loading-dynamic-final-contract.test.mjs`、`phase3-container-documents-contract.test.mjs`、`phase3-phase4-departure-pickup-chain-contract.test.mjs`、`phase3-producer-chain-contract.test.mjs`、`manual-state-loading-pda-contract.test.mjs` |
|
||||
| 头程整柜报关 | `phase3-container-customs-fixture.mjs`、`phase3-container-customs.mjs`；定向入口通过正式订单、测量、同柜装载和最终完成 API 生成独立 `BUY_DECLARATION + TAX_REFUND` 混合柜，客户资料只覆盖退税票，买单行由下载中心 XLSX 验证；不复用历史柜、不执行 SQL | `container-customs-acceptance-contract.test.mjs`、`container-customs-acceptance-matrix.mjs` |
|
||||
| 分柜与父子入库单数量守恒 | `phase3-order-splitting.mjs` | `phase3-order-splitting-contract.test.mjs` |
|
||||
| 同柜且不可拆组 | `coload-groups.mjs`（可选；前置正式生成至少7票同线路 `WAIT_SPLIT`，另造不同线路反向票；覆盖创建/取消幂等、原子分配/移除、目标组隔离超容拒绝与零漂移、推送防绕过、PDA短拣完成拒绝且无余量子单、足量整组消费、普通单拆分不回归及已有父子单建组拒绝） | `coload-groups-contract.test.mjs` |
|
||||
@@ -78,19 +78,19 @@ export async function run(context) {
|
||||
| 消息中心管理 | `notifications.mjs` | `notifications-contract.test.mjs` |
|
||||
| Finance 真实前置、对账、结算与下载中心 | `finance-full-fixtures.mjs`、`finance-reconciliation-full.mjs`、`finance-settlement-full.mjs`、`finance-downloads.mjs` | `finance-full-fixtures-contract.test.mjs`、`finance-reconciliation-full-contract.test.mjs`、`finance-settlement-full-contract.test.mjs`、`finance-downloads-contract.test.mjs` |
|
||||
| Finance 扩展隔离与跨区费用 | `firstleg-container-fee-allocation.mjs`（柜次跨客户分摊）、`finance-direct-paid-isolation.mjs`（海外仓服务直接已付）、`phase4-overseas-finance-cross-region.mjs`（五类海外费用跨区进入 Finance） | 对应同名 `*-contract.test.mjs`；跨区事件持久化链在本轮获授权时另以只读数据库证据核对 |
|
||||
| 四期海外仓 HTTP 生命周期 | `phase4-overseas-warehouse.mjs` | `phase4-overseas-warehouse-contract.test.mjs` |
|
||||
| 四期海外 PDA 柜号收货与库内操作 HTTP 生命周期 | `phase4-overseas-pda.mjs`（按柜完成签收和实收，成功后仅以内存上下文交接操作员会话和已完成库存事实）、`phase4-overseas-pda-operations.mjs`（紧随收货执行 P2 盘点、P3 整托移库、P4 托盘拆装换绑、P5 换标复核；finally 停用双操作员并清空临时 Token；任何真实 fixture 缺失均 fail-closed） | `phase4-overseas-pda-contract.test.mjs`、`phase4-overseas-pda-operations-contract.test.mjs` |
|
||||
| 三四期跨区事件与安全门禁 | `phase4-cross-region-events.mjs`（双 Token Audience 互斥、canonical 权限 403、国内装柜完成到 Lastleg 建单、海外柜完成到 Firstleg 回写、轮询重试/幂等/诊断证据；缺本轮 marker 前置时阻断） | `phase4-cross-region-events-contract.test.mjs` |
|
||||
| 海外仓 HTTP 生命周期 | `phase4-overseas-warehouse.mjs` | `phase4-overseas-warehouse-contract.test.mjs` |
|
||||
| 海外 PDA 柜号收货与库内操作 HTTP 生命周期 | `phase4-overseas-pda.mjs`（按柜完成签收和实收，成功后仅以内存上下文交接操作员会话和已完成库存事实）、`phase4-overseas-pda-operations.mjs`（紧随收货执行盘点、整托移库、托盘拆装换绑和换标复核；finally 停用双操作员并清空临时 Token；任何真实 fixture 缺失均 fail-closed） | `phase4-overseas-pda-contract.test.mjs`、`phase4-overseas-pda-operations-contract.test.mjs` |
|
||||
| 三海外仓业务跨区事件与安全门禁 | `phase4-cross-region-events.mjs`（双 Token Audience 互斥、canonical 权限 403、国内装柜完成到 Lastleg 建单、海外柜完成到 Firstleg 回写、轮询重试/幂等/诊断证据；缺本轮 marker 前置时阻断） | `phase4-cross-region-events-contract.test.mjs` |
|
||||
| 国内离仓至海外 PDA 可见人工验收节点 | `phase3-customs.mjs`（四类柜资料与整柜照片）、`phase3-outbound-dispatch.mjs`（柜级离仓）、`phase3-carrier-schedule-queries.mjs`、`phase4-carrier-pickup-ready.mjs`、`phase4-overseas-pda.mjs`（同柜候选） | `phase3-phase4-departure-pickup-chain-contract.test.mjs` |
|
||||
| 四期海外业务 HTTP 生命周期 | `phase4-overseas-business.mjs` | `phase4-overseas-business-contract.test.mjs` |
|
||||
| 四期海外主数据 HTTP 生命周期 | `phase4-overseas-master-data.mjs` | `phase4-overseas-master-data-contract.test.mjs` |
|
||||
| 四期船节点安全冒烟 | `phase4-carrier-nodes.mjs`（standalone 对历史任务只读；仅复用当前 marker 的 `phase3CarrierScheduleQuery` 时补录预计事实） | `phase4-carrier-nodes-contract.test.mjs` |
|
||||
| 五期海外排车、出库、派送、异常与回访 HTTP 生命周期 | `phase5-overseas-fulfillment.mjs`（复用本轮四期已收货托盘和预排单，正式创建临时 PDA 操作员并在 `finally` 停用；覆盖排车编辑、转出库/派送、PDA 全量拣货/发车、派送完成、客户回访、人工异常及派送退回） | `phase5-overseas-fulfillment-contract.test.mjs` |
|
||||
| 海外业务 HTTP 生命周期 | `phase4-overseas-business.mjs` | `phase4-overseas-business-contract.test.mjs` |
|
||||
| 海外主数据 HTTP 生命周期 | `phase4-overseas-master-data.mjs` | `phase4-overseas-master-data-contract.test.mjs` |
|
||||
| 海外仓业务船节点安全冒烟 | `phase4-carrier-nodes.mjs`（standalone 对历史任务只读；仅复用当前 marker 的 `phase3CarrierScheduleQuery` 时补录预计事实） | `phase4-carrier-nodes-contract.test.mjs` |
|
||||
| 海外排车、出库、派送、异常与回访 HTTP 生命周期 | `phase5-overseas-fulfillment.mjs`（复用本轮海外仓已收货托盘和预排单，正式创建临时 PDA 操作员并在 `finally` 停用；覆盖排车编辑、转出库/派送、PDA 全量拣货/发车、派送完成、客户回访、人工异常及派送退回） | `phase5-overseas-fulfillment-contract.test.mjs` |
|
||||
| 初始化基线（仅离线） | — | `initialization-baseline-contract.test.mjs` |
|
||||
|
||||
表中的 `*-fixture.mjs` 是被业务模块复用的测试数据前置，不是新增的独立全量入口。执行 HTTP 时仍从 `../admin-test-env-acceptance.mjs` 进入；`*contract.test.mjs` 只做离线脚本结构和数据归属回归。
|
||||
|
||||
四期 HTTP 验收使用国内登录响应同时签发的短时海外 Token。总入口通过 `--gateway` 访问国内 Gateway，通过 `--overseas-gateway` 访问海外 Gateway。海外仓、海外业务和海外主数据模块只对带本轮 marker 的资源执行已确认的新增、编辑、状态与导出，并在结束前按契约停用；PDA 收货模块使用本轮临时 OVERSEAS_WAREHOUSE_PDA_OPERATOR 海外 Token，只调用 `/api/pda/v1/last-leg/receiving-containers/**` 柜号收货入口，不接受 `customerId`、`planNo` 或分配 ID。收货成功后由相邻的 `phase4-overseas-pda-operations` 消费仅存在于进程内存、不会进入 JSON 报告的 Token 与库存事实，执行盘点、整托移库、托盘操作和换标；新模块无论成功失败都在 finally 停用两个 picker 并清空临时凭据。两模块均不调用出库、退货出库、派送或内部接口；任何真实柜、箱唛、托盘、库存或换标前置缺失都必须形成 deployment blocker，不能按空场景通过；船节点禁止手工创建任务。
|
||||
海外仓业务 HTTP 验收使用国内登录响应同时签发的短时海外 Token。总入口通过 `--gateway` 访问国内 Gateway，通过 `--overseas-gateway` 访问海外 Gateway。海外仓、海外业务和海外主数据模块只对带本轮 marker 的资源执行已确认的新增、编辑、状态与导出，并在结束前按契约停用；PDA 收货模块使用本轮临时 OVERSEAS_WAREHOUSE_PDA_OPERATOR 海外 Token，只调用 `/api/pda/v1/last-leg/receiving-containers/**` 柜号收货入口，不接受 `customerId`、`planNo` 或分配 ID。收货成功后由相邻的 `phase4-overseas-pda-operations` 消费仅存在于进程内存、不会进入 JSON 报告的 Token 与库存事实，执行盘点、整托移库、托盘操作和换标；新模块无论成功失败都在 finally 停用两个 picker 并清空临时凭据。两模块均不调用出库、退货出库、派送或内部接口；任何真实柜、箱唛、托盘、库存或换标前置缺失都必须形成 deployment blocker，不能按空场景通过；船节点禁止手工创建任务。
|
||||
|
||||
节点全链定向入口为 `--modules phase4-overseas-pda`。依赖展开固定经过本轮 `LOADED` 柜次的 `DESTINATION_CLEARANCE`、`CUSTOMS_DECLARATION`、`DELIVERY_ORDER`、`PICKUP_ORDER` 四类资料生命周期，再确认国内出仓、核对自动创建的 `OUTBOUND_CONFIRM` 船节点任务、人工补录至实际 `PICKUP_READY`，最后验证海外 PDA 候选可见。四类资料模块只写本轮 marker 柜次，覆盖上传/完成重放、同键异载荷 `A0409`、冲突后零漂移和聚合回读；任一 fixture 或 Trace 缺失均为 deployment blocker。
|
||||
|
||||
@@ -104,7 +104,7 @@ node scripts/admin-test-env-acceptance.mjs --gateway <development-gateway> --ove
|
||||
|
||||
只有已登记在 `../admin-test-env-acceptance.mjs` 的 `CONFIGURED_MODULES` 中的名称才能用于 `--modules`；目录中存在同名 `.mjs` 不代表总入口已注册。新增或改名 HTTP 模块时必须同步总入口、依赖展开、离线入口合同和本表；尚未注册的实验脚本不得写成可执行验收入口。
|
||||
|
||||
五期履约链定向入口为 `--modules phase5-overseas-fulfillment`。依赖展开固定从本轮三期装柜完成、四期跨区接柜和海外 PDA 实收入库生成真实库存，再由四期智能预排创建 marker 专属 `PENDING_DEPARTURE` 排车。五期模块只消费该本轮排车，先补齐车辆与司机，原子转为 `WAIT_OUTBOUND + WAIT_DELIVERY`，随后使用绑定同一海外仓的临时 PDA 身份执行全量拣货和发车，使出库单进入 `OUTBOUNDED`；最后覆盖派送完成、回访、人工异常与退回海外仓。所有幂等重放都核对业务单号或数量不漂移，真实前置不足必须形成 deployment blocker，临时 PDA 身份无论成功失败都由正式 IAM 状态接口停用。
|
||||
海外仓出库与派送履约链定向入口为 `--modules phase5-overseas-fulfillment`。依赖展开固定从本轮国内货柜履约装柜完成、海外仓业务跨区接柜和海外 PDA 实收入库生成真实库存，再由海外仓业务智能预排创建 marker 专属 `PENDING_DEPARTURE` 排车。海外仓出库与派送模块只消费该本轮排车，先补齐车辆与司机，原子转为 `WAIT_OUTBOUND + WAIT_DELIVERY`，随后使用绑定同一海外仓的临时 PDA 身份执行全量拣货和发车，使出库单进入 `OUTBOUNDED`；最后覆盖派送完成、回访、人工异常与退回海外仓。所有幂等重放都核对业务单号或数量不漂移，真实前置不足必须形成 deployment blocker，临时 PDA 身份无论成功失败都由正式 IAM 状态接口停用。
|
||||
|
||||
```powershell
|
||||
node --env-file="$env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env" scripts/admin-test-env-acceptance.mjs --modules phase5-overseas-fulfillment
|
||||
@@ -118,7 +118,7 @@ node --env-file="$env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env" s
|
||||
|
||||
其中，无号 push 只冻结装柜计划、建立 bridge 并使预装可见，不得创建 PDA task；订舱放舱也不创建真实货柜或 allocation。港口取得真实柜号后，四字段 link 直接补全原模拟柜并创建 allocation，原 `containerBookingId/cabinetNo/loadingPlan/items` 不变；未关联、订舱未 `RELEASED` 或整份计划未确认时，PDA 查询必须返回业务码 `A0404`。唯一确认入口为 `POST /api/platform/v1/first-leg/loading-plans/{loadingPlanId}/confirm`，请求体只含当前计划 `expectedVersion` 并携带 `Idempotency-Key`；成功必须返回 `confirmationStatus=CONFIRMED`、`readiness.readyForPda=true` 和唯一 `readiness.pdaTaskId`。验收脚本禁止调用旧入库单级 `/preload/confirming`、`/preload/confirm`。
|
||||
|
||||
计划在 `EDITING/LOADING` 可通过正式 assignments/PATCH/DELETE 端点增量；计划、任务和明细版本必须递增，PDA 四元身份不变，旧 `inventorySnapshotToken` 必须返回 `A0409 库存已变化，请刷新后重试`。完整三期装柜 fixture 通过平台托盘 API 创建本轮专用称重托盘，再交给通用测量模块；当普通位不足时由 Warehouse 自然分配到 A0，随后仅使用公开 A0 换绑接口制造库存版本变化，不直连数据库或调用内部 Warehouse 接口。主三期链强制完成该专项，四期生产矩阵的附加柜只负责跨区生产，不重复要求 A0；附加柜若自然落入 A0 仍执行同一验证。批量待分柜入口仍只复用 `TP-001`/`YW-TP-002`，不创建托盘。已拣项不可删或减量，未拣项可删；增量会把全拣的 `AWAITING_REVIEW` 撤回为 `IN_PROGRESS`，刷新 task detail 与 inventory 后续拣才可再次等待最终确认。最终唯一完成入口仍为 `POST /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/complete`：保留同柜 `RELEASED` 订舱、bridge 与五类 ACTIVE 证据门禁；拖车状态和数量不是前置门禁。主事务提交后，零条有效拖车直接跳过，恰有一条时在独立事务尝试推进 `COMPLETED`，多条或并发冲突只记录拖车同步失败，不回滚已完成的 task/plan/inbound。PDA 结算可能先递增来源入库单版本或创建实装分片，完成动作必须在结算后重新锁定实际完成行并使用当前版本；HTTP finalizer 会回查 full/partial 履约分片，失败时保存 `requestId/traceId` 并断言 task/plan/inbound/operation 零漂移。后续模块必须复用 `phase3Loading` 发布的本轮 `taskId + inboundId + loadingPlanId + containerBookingId`，不得回退历史资源。
|
||||
计划在 `EDITING/LOADING` 可通过正式 assignments/PATCH/DELETE 端点增量；计划、任务和明细版本必须递增，PDA 四元身份不变，旧 `inventorySnapshotToken` 必须返回 `A0409 库存已变化，请刷新后重试`。完整国内货柜履约装柜 fixture 通过平台托盘 API 创建本轮专用称重托盘，再交给通用测量模块；当普通位不足时由 Warehouse 自然分配到 A0，随后仅使用公开 A0 换绑接口制造库存版本变化，不直连数据库或调用内部 Warehouse 接口。主国内货柜履约链强制完成该专项，海外仓业务生产矩阵的附加柜只负责跨区生产，不重复要求 A0；附加柜若自然落入 A0 仍执行同一验证。批量待分柜入口仍只复用 `TP-001`/`YW-TP-002`，不创建托盘。已拣项不可删或减量，未拣项可删；增量会把全拣的 `AWAITING_REVIEW` 撤回为 `IN_PROGRESS`，刷新 task detail 与 inventory 后续拣才可再次等待最终确认。最终唯一完成入口仍为 `POST /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/complete`：保留同柜 `RELEASED` 订舱、bridge 与五类 ACTIVE 证据门禁；拖车状态和数量不是前置门禁。主事务提交后，零条有效拖车直接跳过，恰有一条时在独立事务尝试推进 `COMPLETED`，多条或并发冲突只记录拖车同步失败，不回滚已完成的 task/plan/inbound。PDA 结算可能先递增来源入库单版本或创建实装分片，完成动作必须在结算后重新锁定实际完成行并使用当前版本；HTTP finalizer 会回查 full/partial 履约分片，失败时保存 `requestId/traceId` 并断言 task/plan/inbound/operation 零漂移。后续模块必须复用 `phase3Loading` 发布的本轮 `taskId + inboundId + loadingPlanId + containerBookingId`，不得回退历史资源。
|
||||
|
||||
`phase3-pda-convergence` 同时回查 `/tasks/pending` 与稳定 task detail：两者的 `workflowStatus`、`itemCount`、`pendingItemCount` 必须来自同一任务明细事实。全拣任务必须在两处均为 `AWAITING_REVIEW`，可执行证据 GET，但派生 `actions=[]`，不得重复发送 batch；操作历史必须恰有一次有效 `BATCH`。若 pending 仍按 assignment 返回 `IN_PROGRESS`，该轮以真实 HTTP 失败阻断，不由脚本或前端改写状态。
|
||||
|
||||
@@ -188,7 +188,7 @@ node --test scripts/admin-test-env-modules/domestic-container-contract.test.mjs
|
||||
|
||||
## 货柜履约列表字段合同
|
||||
|
||||
`fulfillment-list-field-contract.mjs` 统一校验货柜、预装/装柜清单、订舱、船期、拖车、报关协同和国内出仓正式响应中的稳定 ID、非空展示字段、非负数量/重量/体积及 ISO 时间格式。各生产模块在已取得的本轮 marker 响应上执行断言，不额外借用历史数据；未冻结的原型字段只登记在 `docs/三期/货柜履约原型字段验收矩阵-2026-08-17.md` 的 `UNKNOWN`，不得由 fixture 伪造。
|
||||
`fulfillment-list-field-contract.mjs` 统一校验货柜、预装/装柜清单、订舱、船期、拖车、报关协同和国内出仓正式响应中的稳定 ID、非空展示字段、非负数量/重量/体积及 ISO 时间格式。各生产模块在已取得的本轮 marker 响应上执行断言，不额外借用历史数据；未冻结的原型字段只登记在 `docs/国内货柜履约/货柜履约原型字段验收矩阵-2026-08-17.md` 的 `UNKNOWN`，不得由 fixture 伪造。
|
||||
|
||||
离线合同：
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ const containerList = read(`${adminRoot}container-loading/pages/ContainersView.v
|
||||
const containerOverviewPanel = read(`${adminRoot}container-loading/components/ContainerOverviewPanel.vue`)
|
||||
const containerLoadingAcceptance = read('phase3-container-loading.mjs')
|
||||
const truckAcceptance = read('truck-appointments.mjs')
|
||||
const matrix = read('../../../docs/三期/货柜管理全链验收矩阵-2026-08-13.md')
|
||||
const matrix = read('../../../docs/国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md')
|
||||
|
||||
test('DRAFT stores all five transport fields and release validates the persisted snapshot', () => {
|
||||
assert.match(oceanOpenApi, /ReleaseRequest: \{type: object, required: \[expectedVersion\]/)
|
||||
|
||||
Reference in New Issue
Block a user