161 lines
15 KiB
Markdown
161 lines
15 KiB
Markdown
# Admin 测试环境 HTTP 模块
|
||
|
||
总入口是 `../admin-test-env-acceptance.mjs`。每个业务模块使用独立的同名 `.mjs` 文件，避免多个对话同时修改总入口。
|
||
|
||
例如 `--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` |
|
||
| 订单创建、可计价主数据与审核异步收敛 | `orders.mjs` | `orders-pricing-fixture-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-customs.mjs`、`phase3-loading-finalize.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-producer-chain-contract.test.mjs`、`manual-state-loading-pda-contract.test.mjs` |
|
||
| 分柜与父子入库单数量守恒 | `phase3-order-splitting.mjs` | `phase3-order-splitting-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`（同 marker 客户 + ACTIVE TRUCKING 承运商；订舱/柜次/计划可空；DISPATCH 前需提单号和有效 `BILL_OF_LADING` 文件） | `truck-appointments-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` |
|
||
| 四期海外仓 HTTP 生命周期 | `phase4-overseas-warehouse.mjs` | `phase4-overseas-warehouse-contract.test.mjs` |
|
||
| 四期海外 PDA 入仓 HTTP 生命周期 | `phase4-overseas-pda.mjs`（自动选择未转换尾程单、创建目标仓/库位/托盘并完成入库；完成事实保留审计） | `phase4-overseas-pda-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` |
|
||
| 初始化基线（仅离线） | — | `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 模块只调用 `/api/pda/v1/last-leg/inbound-plans/**` 完成入仓，不调用出库、派送或内部接口；船节点禁止手工创建任务。
|
||
|
||
```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-business,phase4-overseas-master-data,phase4-carrier-nodes
|
||
```
|
||
|
||
只有已登记在 `../admin-test-env-acceptance.mjs` 的 `CONFIGURED_MODULES` 中的名称才能用于 `--modules`；目录中存在同名 `.mjs` 不代表总入口已注册。新增或改名 HTTP 模块时必须同步总入口、依赖展开、离线入口合同和本表；尚未注册的实验脚本不得写成可执行验收入口。
|
||
|
||
## 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 库存已变化，请刷新后重试`。已拣项不可删或减量，未拣项可删；增量会把全拣的 `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 失败阻断，不由脚本或前端改写状态。
|
||
|
||
部署后需要定向验证该完整链时，模块顺序固定为：
|
||
|
||
```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
|
||
```
|
||
|
||
该命令会写测试环境，必须另行获得当前对话授权。离线入口合同为 `../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
|
||
```
|