# Admin 测试环境 HTTP 模块

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

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

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

模块只需导出：

```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`，不要修改其他模块文件。

## 供应商模块

`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
```

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

- `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
```

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

`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
```