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

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，无需手工补齐前置模块。

模块只需导出：

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
三期模拟柜关联、柜次概览、渠道隔离、装柜模型桥接、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-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	ocean-booking-prototype-contract.test.mjs、ocean-booking-fixture-contract.test.mjs、phase3-carrier-schedule-queries.test.mjs
拖车预约	truck-appointments.mjs	truck-appointments-contract.test.mjs
消息中心管理	notifications.mjs	notifications-contract.test.mjs
Finance 真实前置、对账与结算	finance-full-fixtures.mjs、finance-reconciliation-full.mjs、finance-settlement-full.mjs	finance-full-fixtures-contract.test.mjs、finance-reconciliation-full-contract.test.mjs、finance-settlement-full-contract.test.mjs
初始化基线（仅离线）	—	initialization-baseline-contract.test.mjs

表中的 *-fixture.mjs 是被业务模块复用的测试数据前置，不是新增的独立全量入口。执行 HTTP 时仍从 ../admin-test-env-acceptance.mjs 进入；*contract.test.mjs 只做离线脚本结构和数据归属回归。

只有已登记在 ../admin-test-env-acceptance.mjs 的 CONFIGURED_MODULES 中的名称才能用于 --modules；目录中存在同名 .mjs 不代表总入口已注册。新增或改名 HTTP 模块时必须同步总入口、依赖展开、离线入口合同和本表；尚未注册的实验脚本不得写成可执行验收入口。

WAIT_SPLIT 到 LOADED 冻结链

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

WAIT_SPLIT -> SIMULATION/ACTIVE 内部模拟柜 -> 智能排货 -> 无集装箱号 push-preload -> exact replay/冲突零漂移 -> 订舱逐柜登记 OCEAN_BOOKING/ACTIVE 真实柜 -> 按 realContainerBookingId 原地合并（来源 MERGED，模拟柜身份存活）-> RELEASED -> 计划级原子确认 -> 唯一 PDA task -> claim 后 LOADING -> 原子批量拣货/PDA complete -> 五类证据 -> 报关及下游门禁 -> loading complete -> LOADED。

其中，无号 push 只冻结装柜计划、建立 bridge 并使预装可见，不得创建 PDA task；真实柜号由合并动作从未消费的订舱真实柜带入，合并前、订舱未 RELEASED 或整份计划未确认时，PDA 查询必须返回业务码 A0404。合并后正常列表只保留模拟柜原地转成的一个 ACTIVE 操作身份，PDA 禁止使用 MERGED 来源 ID。唯一确认入口为 POST /api/platform/v1/first-leg/loading-plans/{loadingPlanId}/confirm，请求体只含当前计划 expectedVersion 并携带 Idempotency-Key；成功必须返回 confirmationStatus=CONFIRMED、readiness.readyForPda=true 和唯一 readiness.pdaTaskId。验收脚本禁止调用旧入库单级 /preload/confirming、/preload/confirm。后续模块必须复用 phase3Loading 发布的本轮 taskId + inboundId + loadingPlanId + containerBookingId，不得回退历史资源。

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

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 验收需要当前对话明确授权：

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

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

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

供应商模块

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

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

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

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 时，总入口会自动补齐 merchant-qualification-fixture -> orders -> inbound-measurement -> phase3-container-loading，确保 Finance 能消费本轮真实已完成柜次。若这些前置仍未产出同 marker 的完成柜次，Finance 会 fail-closed，不能把 finance-only 前置不足计为 Finance 业务成功。

国内整柜与客户运营统计

• domestic-container.mjs：整柜入库、出库、库存列表和详情；静态契约为 domestic-container-contract.test.mjs。
• customer-operating-statistics.mjs：客户详情在途柜量/TEU 运营指标，复用 platform:firstleg:container:list 权限。
• 两者由总入口 admin-test-env-acceptance.mjs 的默认模块列表编排；接口验收会写入测试数据，静态合同可离线执行。

node --test scripts/admin-test-env-modules/domestic-container-contract.test.mjs

清库后的商户下单前置

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

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

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

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

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