baiyue-firstleg/scripts/admin-test-env-modules/README.md

# Admin 测试环境 HTTP 模块

总入口是 `../admin-test-env-acceptance.mjs`。每个业务模块使用独立的同名 `.mjs` 文件，避免多个对话同时修改总入口。

需要为人工联调批量准备同一客户、同一国内仓和同一渠道的 `WAIT_SPLIT` 数据时，使用[《批量待分柜数据生成指南》](批量待分柜数据生成指南.md)。该入口通过正式下单、入库、称重和测量接口生成数据，支持 FBA、海外仓、私人地址及一件代发等稳定随机组合；不得直接写库或用于生产环境。

固定“IT测试”客户与“义乌仓”、其余线路随机并尽力生成最多 8,000 票时，独立编排入口是 `../it-test-wait-split-bulk.mjs`。它仍复用本目录的 `orders.mjs` 与 `inbound-measurement.mjs`，但逐票保存日志且单票失败后继续。测量前置只随机复用既有 `TP-001`、`YW-TP-002`，不得调用托盘新增接口；库位由正式仓储接口分配，普通位不足时使用公共位 `A0`，不得调用库位新增接口。

订单造数中的 `GET /api/merchant/v1/partners/candidates?type=SHIPPER` 属于 Warehouse 正式客户候选能力。失败时订单脚本仍可使用 sender 快照继续收集后续链路证据，但 HTTP 503/`S0503` 必须保留为 deployment blocker，不能因订单、测量、分柜或装柜后续通过而降级为 coverage gap。

人工分柜采用两个可选模块，不进入默认全量入口：`manual-order-splitting-fixture.mjs` 基于本轮至少四票 `WAIT_SPLIT` 数据生成部分分配、整票拼柜和未分配对照清单；人工在 Admin 完成计划分配后，`manual-order-splitting-verify.mjs` 读取准备报告和 `loadingPlanId`，只读核对柜次范围、计划箱数及候选余量。完整命令见同一指南的“人工分柜验收”章节。

人工分柜通过后可继续执行 `manual-preload-push-fixture.mjs`：它读取分柜核验报告并冻结推送前计划版本、明细及无号模拟柜状态；人工点击“推送预装”后，再由 `manual-preload-push-verify.mjs` 只读核对 `EDITING` 预装清单、PENDING bridge、版本递增、明细零漂移和 PDA `A0404`。两个模块同样不进入默认全量入口。

预装推送通过后，`manual-pda-ready-fixture.mjs` 冻结无号、未关联订舱、不可确认且无 PDA 的基线；人工依次完成订舱 DRAFT、RELEASED 放舱、原模拟柜关联真实柜号和整份计划确认，再由 `manual-pda-ready-verify.mjs` 只读核对 RELEASED、allocation、稳定柜次/计划身份、CONFIRMED readiness 和唯一 `UNASSIGNED` PDA task。两个模块不领取任务，也不进入默认全量入口。

PDA 待领取通过后，`manual-pda-batch-fixture.mjs` 冻结任务明细、稳定箱码和库存快照基线；目标 PDA 作业员人工领取、逐箱扫码并一次提交原子 batch 后，`manual-pda-batch-verify.mjs` 只读核对作业员绑定、全量 PICKED、`AWAITING_REVIEW`、一次 CLAIM、一次 BATCH、pending/detail 一致和入库级数量收敛。HTTP 不记录逐次扫码轨迹，真机扫码仍需人工证据。

PDA 待复核通过后，`manual-loading-complete-fixture.mjs` 冻结无证据、未完成、RELEASED 订舱和 LOADING 计划基线；人工现场上传五类证据并执行一次最终完成后，`manual-loading-complete-verify.mjs` 只读核对五类真实图片、唯一 COMPLETE_LOADING、任务/计划 COMPLETED、来源入库单和统一订单 LOADED、实装分片数量守恒及货柜总览终态。

例如 `--modules system,inbound-weight-ocr` 会依次加载：

- `system.mjs`
- `inbound-weight-ocr.mjs`

`fee-items` 需要同一 marker 的客户订单和入库单。执行 `--modules fee-items` 时，入口自动扩展为 `merchant-qualification-fixture,orders,fee-items`，无需手工补齐前置模块。

模块只需导出：

```js
export async function run(context) {
  const response = await context.request('GET', '/api/platform/v1/example')
  const data = context.apiSuccess('example', '查询示例', response)
  context.assert('example', '示例结构正确', response, Array.isArray(data), `count=${data?.length ?? 'n/a'}`)
}
```

## 可用上下文

- `request(method, path, body?, token?, extraHeaders?)`：JSON HTTP 请求，自动使用平台 Token；幂等写操作通过 `extraHeaders` 传 `Idempotency-Key`。
- `requestBinary(method, path)`：文件下载，不把二进制写入报告。
- `apiSuccess(module, name, response, evidence?, options?)`：断言 HTTP 200 + body code `200`，成功时返回 data。
- `assert(module, name, response, condition, evidence, options?)`：业务断言。
- `expectConflict(module, name, response, scenario)`：断言并发冲突。
- `addStep(...)`：写入统一步骤报告。
- `marker`：本轮唯一测试标记。
- `createdResources`：登记测试资源 ID。
- `context`：模块间共享少量 ID；模块应尽量独立。

## 约束

- 不记录密码、Token、图片二进制或 OCR 原文全文。
- 测试数据必须带 `context.marker`；可删除的清理，不能删除的最终停用。
- 缺少已确认契约时记录失败或 `deploymentBlocker`，不得模拟成功。
- 一个模块只修改自己的 `.mjs`，不要修改其他模块文件。

## 近期业务模块与静态合同快速索引

| 业务链路 | HTTP 模块/共享前置 | 离线静态合同 |
|---|---|---|
| 商户资质与下单身份 | `merchant-qualification-fixture.mjs` | `merchant-qualification-fixture-contract.test.mjs` |
| 公共主数据与往来单位 | `master-data.mjs` | `master-data-partner-contract.test.mjs` |
| 平台基础、客户、海外仓储费与下载 | `system.mjs`、`customers.mjs`、`overseas-storage-fees.mjs`、`downloads.mjs` | 由 Admin 总入口默认编排；分别覆盖系统能力、客户管理、海外仓阶梯费和下载中心基础能力 |
| 订单创建、可计价主数据、幂等零漂移与审核异步收敛 | `orders.mjs` | `orders-pricing-fixture-contract.test.mjs`、`orders-lifecycle-idempotency-contract.test.mjs`、`orders-approval-convergence-contract.test.mjs` |
| 入库单手工扣货与解除 | `inbound-hold.mjs`（客户隔离、乐观锁、幂等重放/冲突、不可变历史、统一订单投影、智能装柜候选拦截与恢复） | `inbound-hold-contract.test.mjs`；默认全量已启用，定向入口自动展开已审核订单与入库单造数 |
| 费用项目、价格配置与基础 Finance | `fee-items.mjs`、`pricing.mjs`、`finance.mjs` | `fee-items-contract.test.mjs`、`pricing-contract.test.mjs`、`finance-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` |
| 头程整柜报关 | `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` |
| 人工计划分柜准备与只读核验 | `manual-order-splitting-fixture.mjs`、`manual-order-splitting-verify.mjs`（可选，不进入默认全量） | `manual-order-splitting-contract.test.mjs` |
| 人工推送预装前置与推送后只读核验 | `manual-preload-push-fixture.mjs`、`manual-preload-push-verify.mjs`（可选，不进入默认全量） | `manual-preload-push-contract.test.mjs` |
| 人工订舱关联、预装确认与 PDA 待领取核验 | `manual-pda-ready-fixture.mjs`、`manual-pda-ready-verify.mjs`（可选，不进入默认全量） | `manual-pda-ready-contract.test.mjs` |
| PDA 人工领取、逐箱扫码、原子批量提交与待复核核验 | `manual-pda-batch-fixture.mjs`、`manual-pda-batch-verify.mjs`（可选，不进入默认全量） | `manual-pda-batch-contract.test.mjs` |
| 五类装柜证据、PDA 最终完成与 LOADED 终态核验 | `manual-loading-complete-fixture.mjs`、`manual-loading-complete-verify.mjs`（可选，不进入默认全量） | `manual-loading-complete-contract.test.mjs` |
| 订舱共享主数据前置与订舱验收 | `ocean-booking-fixture.mjs`、`ocean-bookings.mjs`、`phase3-port-schedules.mjs`、`phase3-carrier-schedule-queries.mjs`（DRAFT 可编辑；RELEASED 冻结；船司查询只创建并写当前 marker 登记任务） | `ocean-booking-prototype-contract.test.mjs`、`ocean-booking-fixture-contract.test.mjs`、`phase3-carrier-schedule-queries.test.mjs` |
| 订舱级拖车预约完整生命周期 | `truck-appointments.mjs`（自包含创建并放舱，不创建或关联柜次；每订舱最多一张非终态拖车单；覆盖候选、附件、费用、幂等及 `SUBMIT → DISPATCH → PICKUP → ARRIVE → LOAD → DEPART → COMPLETE`） | `truck-appointments-contract.test.mjs` |
| 订舱与拖车服务中心跨链路 | `service-center-flow.mjs`（依赖 `ocean-bookings,truck-appointments`；复用本轮 `RELEASED` 订舱创建订舱级拖车，验证派车单、完整状态链、历史、审计和关联零漂移） | 由入口依赖合同和拖车直接合同共同覆盖；真实 HTTP 缺本轮订舱或承运商时 fail-closed |
| Admin 补充能力与保护边界 | `supplemental.mjs`、`supplemental-boundaries.mjs` | `supplemental-boundaries-contract.test.mjs`；只按本轮资源验证补充能力、负向和保护边界 |
| 装柜清单三备注 | `orders.mjs`、`phase3-loading.mjs`（客户备注、最新内部备注、仓库备注；仓库备注 PATCH/清空/精确重放/旧版本零写） | `loading-list-remarks-contract.test.mjs` |
| 消息中心管理 | `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`；跨区事件持久化链在本轮获授权时另以只读数据库证据核对 |
| 客户钱包与拆柜打托费自动闭环 | `phase4-overseas-wallet-and-pallet-cost.mjs`（授信初始化、平台充值、采购凭证/费用冻结结算、换标冻结结算/释放、Client 余额账本、国内/海外托盘汇总、按体积分摊及跨区金额守恒） | `phase4-overseas-wallet-and-pallet-cost-contract.test.mjs`；默认全量已启用，定向入口自动展开已审核客户与海外 PDA 实收链 |
| 海外仓 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-overseas-inbound-operations.mjs`、`phase4-overseas-client-services.mjs`、`phase4-overseas-dispatch.mjs` | 对应同名 `*-contract.test.mjs`；只消费本轮前置资源，缺失时 fail-closed |
| 海外仓业务跨区事件与安全门禁 | `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` |
| 国内出仓聚合、门禁、待装柜与仓库权限 | `phase3-outbound-aggregate.mjs`、`phase3-dispatch-gate.mjs`、`phase3-waiting-for-loading.mjs`、`phase3-warehouse-rbac.mjs` | 由容器回归、生产者链和出仓相关合同覆盖；只消费本轮主链资源 |
| 人工状态矩阵 | `manual-state-matrix.mjs` | `manual-state-matrix-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，不能按空场景通过；船节点禁止手工创建任务。

节点全链定向入口为 `--modules phase4-overseas-pda`。依赖展开固定经过本轮 `LOADED` 柜次的 `DESTINATION_CLEARANCE`、`CUSTOMS_DECLARATION`、`DELIVERY_ORDER`、`PICKUP_ORDER` 四类资料生命周期，再确认国内出仓、核对自动创建的 `OUTBOUND_CONFIRM` 船节点任务、人工补录至实际 `PICKUP_READY`，最后验证海外 PDA 候选可见。四类资料模块只写本轮 marker 柜次，覆盖上传/完成重放、同键异载荷 `A0409`、冲突后零漂移和聚合回读；任一 fixture 或 Trace 缺失均为 deployment blocker。

海外 PDA 收货统一扫描冻结箱码：`FBA` 与 `OVERSEAS` 都必须由 `POST /api/pda/v1/last-leg/receiving-containers/current/cartons/resolve` 返回 HTTP 200、业务码 `200` 和当前柜唯一 `inboundCode`，不展示、扫描或提交 SKU。仅实收阶段分流：FBA 使用不含 `skuCode` 的 `/current/receipts/bulk`，逐箱接口必须精确返回 `A0409 FBA destination must use bulk count`；OVERSEAS 使用 `/current/receipts/carton`，bulk 必须精确返回 `A0409 OVERSEAS destination must use carton-by-carton scanning; bulk count is forbidden`。实机旧行为反证为 requestId `5e925a3d-8184-41e1-b0d2-f4e1aae86639`、traceId `62fdf603b65fd7f43ec452bb8a6ca185`。跨区广播消费只保留观察证据，不再单独形成 deployment blocker；实际 `PICKUP_READY` 候选门禁仍必须通过。

FBA 无 `ll_inbound_plan_carton` manifest 时，服务端只取完整扫描值的第一个 `#` 前缀，并在当前锁定柜中精确匹配唯一 `inboundCode`；不校验 SKU、`#` 后缀或箱序号，也不能要求前端拆分或自行决定归属。无 `#`、空前缀、未命中、跨柜或同柜多匹配必须拒绝。OVERSEAS 仍按完整箱码精确匹配真实 manifest 行。HTTP 合同使用任意 FBA 后缀验证前缀解析，覆盖上述负向与 OVERSEAS 缺 manifest，并在正负向 resolve 后回查 current 的状态、版本与收货数量零漂移。2026-08-26 最新已部署实机尚返回 `A0404 Carton mark was not found`，requestId `a716e2c2-dc10-4d07-8014-7438afb63090`、traceId `6ab8fcfcd812056ad6570d3b1652157b`；该证据保留为后端 FBA 入仓码前缀解析落盘及重新部署后的回归反证，不据此放宽成功合同。

```powershell
node scripts/admin-test-env-acceptance.mjs --gateway <development-gateway> --overseas-gateway <development-overseas-gateway> --modules phase4-overseas-warehouse,phase4-overseas-pda,phase4-overseas-pda-operations,phase4-cross-region-events,phase4-overseas-business,phase4-overseas-master-data,phase4-carrier-nodes,phase4-overseas-wallet-and-pallet-cost
```

只有已登记在 `../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 状态接口停用。

```powershell
node --env-file="$env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env" scripts/admin-test-env-acceptance.mjs --modules phase5-overseas-fulfillment
```

## WAIT_SPLIT 到 LOADED 冻结链

默认 Admin 全量入口已注册并按同一 `context.marker` 串行执行货柜主链。冻结时序为：

`WAIT_SPLIT -> SIMULATION/ACTIVE 内部模拟柜 -> 智能排货 -> 无集装箱号 push-preload -> exact replay/冲突零漂移 -> 订舱 DRAFT 完整登记 containerRequirements -> RELEASED -> 港口取得真实 containerNo -> 按 oceanBookingId + requirementId + containerNo + expectedVersion 原地关联并创建 allocation -> 计划级原子确认 -> 唯一 PDA task -> claim 后 LOADING -> 原子批量拣货 -> AWAITING_REVIEW -> 五类证据 -> LOADING 阶段增量入库单/旧 inventory token A0409/刷新后续拣 -> PDA task complete 先完成 task/plan/inbound -> LOADED -> 提交后独立尝试同步唯一同柜有效拖车`。

其中，无号 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`，不得回退历史资源。

动态增量还会读取计划明细中的服务端 `totalPackageCount/remainingPackageCount`，断言
`remaining = total - assigned`；随后尝试把箱数调整为权威总数加一，必须得到 `A0400`，并回查
plan/item 版本、分配箱数及总数投影全部零漂移。脚本不从当前已分配数量反推订单总箱数。

`phase3-pda-convergence` 同时回查 `/tasks/pending` 与稳定 task detail：两者的 `workflowStatus`、`itemCount`、`pendingItemCount` 必须来自同一任务明细事实。全拣任务必须在两处均为 `AWAITING_REVIEW`，可执行证据 GET，但派生 `actions=[]`，不得重复发送 batch；操作历史必须恰有一次有效 `BATCH`。若 pending 仍按 assignment 返回 `IN_PROGRESS`，该轮以真实 HTTP 失败阻断，不由脚本或前端改写状态。

部署后需要定向验证该完整链时，模块顺序固定为：

```powershell
node scripts/admin-test-env-acceptance.mjs --modules merchant-qualification-fixture,orders,inbound-measurement,phase3-container-loading,phase3-loading,phase3-container-overview,phase3-pda-convergence,phase3-evidence-gate,phase3-customs,phase3-loading-finalize
```

整票库位块专项可在只跑 `orders,inbound-measurement` 时追加
`--verify-pallet-location-guide true`。它在测量仍可编辑、正式提交前核对
`palletLocationGuide` 计数、每槽 `blockId/slotNo/reservationId/locationCode/slotStatus`、
称重结果按 `weightResultId` 显式绑定槽位；每确认一张称重图片都会回查一次，后续扩容只能追加槽位，
既有 `blockId/slotNo/reservationId/locationId/sharedOverflow` 不得漂移。脚本还会真实验证删除图片后原 reservation/location
保留且转为 `RESERVED_EMPTY`，再上传替代图片并确认复用原槽后继续提交与审核。脚本只观测自然出现的共享 A0；
不会为制造普通位不足批量停用库位。

只验证真实集装箱号晚补门禁时，使用正式可选参数 `LATE_CONTAINER_GATE_ONLY=1` 并仍从总入口执行 `phase3-loading`。该模式使用本轮 marker 独立造数，固定验证无号 push、订舱关联、整份预装确认、PDA claim/batch、无号 complete `A0409`、LOADING 阶段首次补号和补号后 complete 受理；随后允许后台命令停在 `CABINET_EVIDENCE/A0409`，以证明柜号门禁已经消失且下一门禁来自未上传的五类柜级证据。该模式不继续完整报关或 LOADED 链，也不得与完整链同时解释为同一终态验收。

```powershell
$env:LATE_CONTAINER_GATE_ONLY='1'
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/admin-test-env-acceptance.mjs --modules phase3-loading
Remove-Item Env:LATE_CONTAINER_GATE_ONLY
```

该命令会写测试环境，必须另行获得当前对话授权。离线入口合同为 `../full-regression-entry-contract.test.mjs`，生产者与状态合同为 `phase3-producer-chain-contract.test.mjs`。

## 消息中心模块

`notifications.mjs` 覆盖平台消息模板的查询、新增、编辑、版本冲突、激活与最终停用，以及未来定时消息任务的创建、幂等重放、列表查询、取消和非法重试。模块只创建未来定时任务并在结束前取消，不实际投递验收消息。定向 HTTP 验收需要当前对话明确授权：

```powershell
node scripts/admin-test-env-acceptance.mjs --modules notifications
```

离线静态合同可安全执行：

```powershell
node --test scripts/admin-test-env-modules/notifications-contract.test.mjs
```

## 供应商模块

`suppliers.mjs` 覆盖平台公共供应商的列表、统计、新增、详情、编辑、启停及主要错误边界。执行：

```powershell
node scripts/admin-test-env-acceptance.mjs --modules suppliers
```

该命令会调用测试环境写 API，只有当前对话明确授权后才允许执行。验收供应商最终停用但不删除；静态合同可安全离线运行：

```powershell
node --test scripts/admin-test-env-modules/suppliers-contract.test.mjs
```

## Finance 全链前置

`finance-full-fixtures` 会通过正式供应商 API 创建本轮隔离的 ACTIVE 供应商，并按费用项目类别校验后再生成 PAYABLE；不会使用历史供应商 ID。只请求 `finance-full-fixtures,finance-reconciliation-full,finance-settlement-full,finance-downloads` 时，总入口会自动补齐 `merchant-qualification-fixture -> orders -> inbound-measurement -> phase3-container-loading`，确保 Finance 能消费本轮真实已完成柜次，并在结算链完成后验证八类 XLSX 下载任务。若这些前置仍未产出同 marker 的完成柜次，Finance 会 fail-closed，不能把 finance-only 前置不足计为 Finance 业务成功。单独请求 `finance-downloads` 只执行最小部署能力探测，不借历史 Finance 数据。

## 国内整柜与客户运营统计

- `domestic-container.mjs`：整柜入库、出库、库存列表和详情，并覆盖字段边界、组合筛选与分页汇总、柜号标准化、同柜追加入库、货名冲突、完成出库强制库存版本、并发版本竞争和幂等重放；静态契约为 `domestic-container-contract.test.mjs`。
- `customer-operating-statistics.mjs`：客户详情在途柜量/TEU 运营指标，复用 `platform:firstleg:container:list` 权限。
- 两者由总入口 `admin-test-env-acceptance.mjs` 的默认模块列表编排；接口验收会写入测试数据，静态合同可离线执行。

```powershell
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 伪造。

离线合同：

```powershell
node --test scripts/admin-test-env-modules/fulfillment-prototype-field-matrix-contract.test.mjs
```

## 清库后的商户下单前置

`merchant-qualification-fixture.mjs` 是默认全量验收的首个模块。它通过平台正式接口创建本轮隔离客户，经 File 上传真实营业执照和法人身份证文件，再走 IAM 提交审核和平台审核通过；审核完成后把本轮动态加载模块使用的商户账号切换到该客户。

依赖商户下单资格的模块不要单独运行。定向排查时至少保留前置模块，例如：

```powershell
node scripts/admin-test-env-acceptance.mjs --modules merchant-qualification-fixture,orders
```

该前置不会向初始化 SQL 写入伪造资质，也不会绕过订单服务的企业资格校验。静态契约可离线执行：

```powershell
node --test scripts/admin-test-env-modules/merchant-qualification-fixture-contract.test.mjs
```