baiyue-firstleg/scripts/README.md

# 后端脚本管理与全量 HTTP 验收索引

`event-delivery-fault-proxy.py` 是 TEST 环境定向事件 ACK 丢失工具，不创建或重放事件。运行者显式传入 `--upstream` 完整消费者地址、`--event-type`，并只选 `--event-id` 或 `--loading-plan-id`；`EVENT_FAULT_CONTROL_TOKEN` 从外部环境注入，保护固定本机监听的控制端口。默认 PASS；经鉴权切为 FAULT 后，仅在选定事件已真实转发且收到匹配的 APPLIED/DUPLICATE ACK 时向发送方返回 503，其他事件直通。日志只保留事件标识、摘要和结果，不保留正文或凭据。它会影响实际投递，仅限明确授权的测试环境；生产者配置、重试、DEAD 原事件人工恢复及最终恢复直连由运行者负责，工具退出不自动恢复服务配置。`--log` 可显式指定脱敏证据文件，失败保留原事件与日志，禁止改摘要或借其他事件重跑。`event-delivery-fault-proxy.test.mjs` 使用本机替身服务验证行为，不访问共享环境；工具离线通过不能替代真实重试验收。

`admin-test-env-acceptance.mjs` 与 `client-test-env-acceptance.mjs` 仅接受统一 TEST Gateway 和 Auth 会话；移除环境文件中的 `ADMIN_OVERSEAS_GATEWAY`，不再传 `--overseas-gateway` 或非 test 环境。平台、客户、PDA 身份仍分别登录并验证权限及客户隔离。海外资源接口使用 `/api/platform/v1/overseas-warehouse-resources/**`，仓库主档仍归 Warehouse。跨服务模块的重复 GET 不证明事件重放；真实重试/幂等证据缺失会报告部署阻断，详见模块 README 和下方事件人工重试入口。离线合同不会执行真实 HTTP；环境执行仍需本轮写入授权。

`db/local-return-relabel-multiple-applications.sql`：本地 `baiyue_lastleg.ll_relabel_application` 单次结构修复，将尾程订单关联的唯一索引替换为普通索引，允许同一退货单剩余货物分批换标；不修改业务行，单号与幂等键唯一索引保留。凭据及目标连接由操作者显式提供，只在已授权本地库执行；DDL失败停止，已执行后不要重复运行，回查SHOW INDEX。新库结构同步在Lastleg基线和海外区域SQL中。

`db/recent-schema-incremental-20260923.sql`：汇总 2026-09-21 至 2026-09-22 的近期结构变更，依次显式指向 `baiyue_iam`、`baiyue_firstleg`、`baiyue_lastleg`、`baiyue_lastlag_warehouse`；补齐国内 PDA 作业仓字段及索引、人工 FBA 报价可空字段、墨家 SKU 测量字段、换标申请普通索引和 A0 共享溢出位字段。所有字段和索引变更均经 `information_schema` 判断，可重复执行；不创建数据库、不含凭据、权限种子或业务状态修正，末尾输出逐库 `READY/CHECK_REQUIRED`。由操作者选择并确认目标连接后执行，任一 DDL 报错立即停止。

`db/customs-two-file-incremental-20260926.sql`：报关两文件流程增量结构，保留报关行回执与新增真实报关完税文件，补充“已发送给报关行执行”的操作人和时间；仅新增结构，可重复执行，不修改业务数据。

`local-return-relabel-acceptance.mjs` 的 `LOCAL_RETURN_VERIFY_REMAINING=true` 专项新建3件退货，先换1件并客户确认，再对同一退货单剩余2件中的1件新建第二申请，验证同键重放、第二轮完工后剩余1件；不执行出库，报告 scope 为 `REMAINING_RETURN_RELABEL`，不代表出库验收通过。仍保留单据、使用正式API和合成照片，默认单票模式不变。

`local-return-relabel-outbound.mjs`：仅本机网关，读取显式 `LOCAL_RETURN_SOURCE` 单票报告，为其中同客户、同仓、已完成换标的唯一一件可用库存执行平台创建出库、原键重放、PDA拣货及完成。沿用平台账号环境参数，报告默认 `reports/local-return-relabel-outbound-<marker>.json` 或 `--output`；创建临时PDA并finally停用，不改客户权限。平台库存核验不替代源报告的客户读权限失败。会推进库存与出库状态，保留单据及报告；失败后按已保存单号核查，不自动清理，不可对已出库库存盲目重跑。

`db/local-dev-iam-number-sequence.sql`：经明确授权在 local/dev 的 `baiyue_iam` 补齐客户编号序列表，与 IAM 表结构基线一致；连接凭据由外部传入，无固定主机。创建表并初始化 `CUSTOMER_CODE`，事务锁定序列后按已有五位数字客户编码确定下限，已有较大序列不回退，不更新客户业务行。执行后输出表结构及序列，重复执行安全；失败停止，不清库，不用于区域空库初始化或生产迁移。

`local-return-relabel-acceptance.mjs`：仅本机网关的单票退货换标独立编排器。显式传入 `ADMIN_TEST_GATEWAY`、`ADMIN_OVERSEAS_GATEWAY`、平台账号密码、`OVERSEAS_TEST_CUSTOMER_ID` 和 `INTERNAL_SERVICE_TOKEN`，可指定 `OVERSEAS_TEST_WAREHOUSE_ID`；先核对本地服务数据库连接。复用已有启用客户，经正式代登录接口，新建唯一SKU和一件退货，审核、PDA签收、Print生成验收PDF、转换标、组托、合成照片完工、客户确认及实际换标库存出库。复用内部模块的步骤函数，不借用历史业务库存，不运行客户建档或全量边界。会创建并最终停用临时PDA，业务记录保留；报告由 `--output` 指定，默认 `reports/local-return-relabel-single-<marker>.json`，阶段检查点保存单号，失败停止且重跑前必须核对报告，不自动清理或自动续跑，不代表现场作业或页面验收。

`db/test-return-relabel-checks.sql`：测试库退货转换标检查约束定向修复，显式目标 `baiyue_lastleg.ll_return_inventory_carton`。与 Lastleg 基线保持一致，允许正数量的 `RELABEL_PENDING`，保留可用/已出库正数量与已合箱零数量限制。一条原子 ALTER 同时替换两个既有 CHECK，不修改业务行、不删除数据、不关闭约束；重复执行得到相同约束，旧约束不存在则报错停止。凭据由外部测试数据库连接提供，执行前需测试库操作授权；末尾只读输出约束定义供回查。不是生产迁移入口，不能替代完整 HTTP 换标回归。


`db/relabel-wait-status-incremental.sql`：存量换标主单状态修正，显式使用 `baiyue_lastleg`。由操作者选择已授权数据库连接执行，无内置凭据；修正未生成入库单、仍为待分配的 `RELABEL_APPLICATION` 主单，并将已客户确认且换标完成、仍停在待换标/待分配的仓储转运单按目的仓恢复为待排车或待确认目的仓，同步尾程主单和换标履约状态；不修改库存或删除单据。事务执行、可重复运行，执行后按换标号回查订单状态；无单独报告文件。

`db/warehouse-transfer-outbound-incremental.sql`：固定指向 `baiyue_lastleg`，一次补齐仓储转运审核、提货、PDA 测量打托、现场照片、换标、FBA/私人仓目的地、入库计划、智能排车和派送所需表、租户字段及索引，并将换标新 SKU 和转运托盘生命周期字段修正为本地要求的可空结构。无内置凭据；表使用 `CREATE TABLE IF NOT EXISTS`，字段和索引通过 `information_schema` 独立判断，可重复执行，不删除或改写业务单据。完整成功时返回 `WAREHOUSE_TRANSFER_LATEST_SCHEMA_READY`；若历史数据存在同客户重复托盘号，则返回 `WAREHOUSE_TRANSFER_SCHEMA_APPLIED_WITH_INDEX_BLOCKER`，且 `inbound_pallet_unique_index` 为 `BLOCKED_BY_DUPLICATE_CUSTOMER_PALLET_NO`。其余结构仍正常补齐，脚本不会擅自修改历史托盘号。

生产尾程数据库字段核对与增量补齐使用 `prod-database-schema-acceptance.mjs` 和 `deploy/sql/migrations/overseas/baiyue_lastleg/V1__align_lastleg_production_schema.sql`。脚本读取进程环境中的 `CHONGCHONG_ENV`、`CHONGCHONG_DB_HOST`、`CHONGCHONG_DB_PORT`、`CHONGCHONG_DB_USERNAME`、`CHONGCHONG_DB_PASSWORD`，默认只读比较统一海外 SQL 的 `ll_*` 表与生产 `information_schema`；仅在显式同时传入 `--apply --confirm-production-ddl` 时执行增量迁移。迁移只新增缺失字段、放宽生成后才确定字段的 `NOT NULL`、创建缺失的测量照片表，不执行 DML、删除或重建。运行前须确认外部生产 env 文件和数据库目标；脚本不会把凭据写入报告或仓库。

```powershell
node --env-file="<外部生产数据库.env>" scripts/prod-database-schema-acceptance.mjs
node --env-file="<外部生产数据库.env>" scripts/prod-database-schema-acceptance.mjs --apply --confirm-production-ddl
```

`mixed-container-outbound-test-env.mjs` 是经明确授权的测试环境留存混柜出库续跑入口：参数为 `source-report containerNo MIXED-FBA|MIXED-DROPSHIP output-report`，凭据由显式 `node --env-file` 注入。FBA 分支实时校验既有收货数据，创建排车、出库、派送及临时 PDA 账号，执行拣货、发车、测试签收文件保存和国内状态回查；一件代发分支只走专用候选、两托四箱出库、PDA 幂等拣货和完成回查，并明确记录派送未覆盖，不返回全流程成功退出码。finally 停用临时账号，不删除业务数据。输出报告作为检查点，失败后须先核对其中业务单号和实时状态，再用同一输出文件续跑；不得删除报告后盲目重试。它不代表普通海外仓目的地转换或所有分支签收验收通过。

全量验收只认测试环境 HTTP 脚本。它们通过 Gateway 调用已部署服务，按业务模块执行真实登录、权限、状态、幂等、跨服务和数据链路检查；脚本通过后，剩余工作是 Admin/Client 的真实接口调用与浏览器样式验收，以及 PDA 页面/设备验收。

进入本目录维护或运行脚本前先读 `scripts/AGENTS.md`；本文件是脚本入口、用途和副作用的唯一总索引，具体模块说明继续下沉到相邻 README。

## 验收环境变量文件

### 生产单票发布验收（独立入口）

称重计算内部模块 `prod-release-measurement-plan.mjs` 统一采用每箱含纸箱、不含托盘 7.5 kg、40×30×30 cm（0.036 m³）。`order-stage` 在载荷绑定及报价前自动按箱数统一申报箱规、货重及总体积；不推算商品净重，已填商品净重若超过含箱货重则阻断。改口径后的已有检查点载荷不一致会停止，不能以换批次方式盲目重跑。

只读计算命令：`node --env-file="<外部生产配置.env>" scripts/prod-release-acceptance.mjs measurement-plan 2`（箱数只允许 1 或 2；执行前仍需生产 HTTP 授权）。外部配置新增 `CHONGCHONG_ACCEPTANCE_PALLET_CODES`，逗号分隔明确允许复用的现有托盘编码；检查所有编码唯一存在于义乌仓，稳定选择列表第一个，读取其实际 `capacityCbm` 和 `weightKg`，不写死容量或皮重。托数按总体积/选中托盘容量向上取整，每托分配整数箱，称重毛重=该托箱数×7.5+皮重；容量不足以容纳完整箱或参数异常时阻断。不创建托盘/库位、不上传称重图片、不确认称重，只向终端输出 `MEASUREMENT_PLAN_ONLY` 计算结果。服务端库位槽数还依赖其默认托容量配置，与此处实际称重托数不是同一字段；后续由服务端分配并回查既有普通位或 A0，不在脚本伪造库位数。

离线验证：`node --test scripts/prod-release-measurement-plan.test.mjs`，覆盖小数容量边界、皮重、箱数/重量守恒、错误仓库和托盘白名单；不证明真实称重写入已实现。

`prod-release-acceptance.mjs` 目标固定为同一票从义乌 `CN-YIWU-01` 到洛杉矶 `US-LAX-01`，并在前置检查中同时核对东莞 `CN-DONGGUAN-01`；客户身份由外部配置精确限定，不调用开发/测试全量造数模块。订单阶段负责单票创建、提交和审核；`prod-release-delivery-stage.mjs` 负责既有本批次的派送中、签收文件、派送完成和国内签收事件回查，两个阶段分别使用独立检查点。签收脚本不会借用历史单据或删除数据。

- `node scripts/prod-release-acceptance.mjs plan`：不加载凭据，不访问 HTTP，列出主链阶段与不覆盖范围。
- `node --env-file="$env:USERPROFILE\.codex\env\chongchong-global\prod-acceptance.env" scripts/prod-release-acceptance.mjs preflight`：获得当次生产 HTTP 授权后运行；登录既有四个账号并查询客户、义乌/东莞/洛杉矶仓、PDA 绑定及义乌资源。不创建业务数据、主档或账号，不删除数据；登录本身会创建会话及审计记录。
- 必填 `CHONGCHONG_ENV=prod`；`CHONGCHONG_ADMIN_API_BASE_URL`、`CHONGCHONG_ADMIN_OVERSEAS_API_BASE_URL`、`CHONGCHONG_MERCHANT_API_BASE_URL` 分别为同一 HTTPS 前端代理的 `/api`、`/overseas-api`、`/api`。
- 客户锁定配置：`CHONGCHONG_ACCEPTANCE_CUSTOMER_ID`、`CHONGCHONG_ACCEPTANCE_CUSTOMER_CODE`、`CHONGCHONG_ACCEPTANCE_CUSTOMER_NAME`。四组账号分别使用 `CHONGCHONG_ADMIN_*`、`CHONGCHONG_MERCHANT_*`、`CHONGCHONG_CN_PDA_*`、`CHONGCHONG_OVERSEAS_LAX_PDA_*` 的 `USERNAME` / `PASSWORD`；另需 `CHONGCHONG_OVERSEAS_LAX_PDA_WAREHOUSE_CODE=US-LAX-01`。不修改环境文件，不读取其他环境作为回退。
- 报告位于 `reports/prod-release-preflight-<时间戳>.json`，不包含账号、Token、真实客户名称或原始响应。网络异常不自动重试；修正问题后可重新执行只读检查，产生新报告，不清理旧报告或业务数据。
- 单票入口 `order-stage <外部订单输入.json> <本批次检查点.json> --confirm-production-order [--resume]`：须另获当次生产写入授权。自动执行基本前置检查，额外校验指定客户可选的唯一渠道/包税维度与 1～2 箱实际重量、体积报价，然后创建一票、提交、审核；不创建图片、地址、托盘或库位。仅支持 AUTO 入仓码、普通海运 FBA 自送散货、单 SKU 非木制非危险品；目的 FBA 仓显式指定，洛杉矶是后续接柜仓，不是第二票。输入与检查点放仓库外，同一批次始终使用同一检查点文件，禁止并发另开路径或换批次重试。
- 尾程签收入口 `delivery-stage <尾程事实输入.json> <独立签收检查点.json> --confirm-production-delivery`：须另获当次生产写入授权。脚本只接受本批次已核对的排车、出库、派送和尾程订单身份；按状态版本推进 `DELIVERING`，上传验收用签收文件并保存资料，回查 `DELIVERED`、国内入仓 `DELIVERED` 和头程订单 `COMPLETED`。上传或状态写入结果不确定时停止；托盘明细或尾程子状态未同步会记录为阻断项。
- `prod-release-order-stage.mjs` 是上述入口使用的内部订单阶段与检查点实现，不可直接执行。先落盘并同步意图，再调用 HTTP；检查点绑定环境、客户、操作者、批次和载荷摘要，不保存密码/Token/完整申报。创建与提交仅在显式续跑时复用原幂等键；审核无幂等键，响应丢失后只回查，若仍不能确认已审核则停止并要求人工核对，不自动再次审核。崩溃残留 `.lock` 时先确认无运行进程、检查业务状态，再人工解除锁；不得删除业务检查点。
- 订单输入字段：`batch`（8～48 位字母数字/连字符）、`origin: {id, code: "CN-YIWU-01"}`、`destination: {id, code, type: "FBA"}`、`payload`（`order` 服务 `OrderRequests.SaveRequest` 完整请求）。客户、环境和操作者由外部 env 强制绑定；`payload.customerName` 必须匹配配置，`customerRemark` 必须为 `RELEASE-ACCEPTANCE:<batch>`。显式填 `fulfillmentType=STANDARD`、`transportMode=SEA`、`pickupMethod=SELF_EXPRESS`、`containerMode=LCL`，`cargoes` 一行 1～2 箱；已上传的产品图片 ID 和商品申报字段由本次验收资料提供，箱规/含箱总重/总体积由上述固定口径统一计算，不生成资质或物流签收证明。箱数×每箱数量必须等于总件数，箱规×箱数必须等于总体积。
- 待实现：供应商及海外资源门禁、测量至签收写入、后续阶段归属核验、跨区等待和检查点、所有阶段真实 HTTP 验证。全链 `execute` / `resume` 命令仍拒绝；订单续跑仅使用上述 `order-stage ... --resume`。不得改用测试全量脚本来代替。
- 离线验证：`node --test scripts/prod-release-acceptance.test.mjs`。一票主链不覆盖多客户混柜、退货异常、真实付款、外部下单、邮件发送或页面交互。

订单阶段与恢复验证：`node --test scripts/prod-release-order-stage.test.mjs`，包括断网响应丢失、原幂等键复用、未知审核结果停机、账号/客户/环境/载荷漂移、并发锁、损坏检查点与入口 HTTP mock。生产运行示例（只到已审核，执行前确认授权，不代表全链完成）：

```powershell
node --env-file="<外部生产配置.env>" scripts/prod-release-acceptance.mjs order-stage "<外部订单输入.json>" "<本批次检查点.json>" --confirm-production-order
# 中断后保持相同输入、账号和检查点；不要删除检查点或换批次。
node --env-file="<外部生产配置.env>" scripts/prod-release-acceptance.mjs order-stage "<外部订单输入.json>" "<本批次检查点.json>" --confirm-production-order --resume
```

统一 TEST 验收账号、密码和 Gateway 由仓库外配置文件显式提供，例如 `$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env`，不写入仓库。文件提供以下变量：

```text
ADMIN_TEST_GATEWAY
ADMIN_TEST_USERNAME
ADMIN_TEST_PASSWORD
MERCHANT_TEST_USERNAME
MERCHANT_TEST_PASSWORD
ADMIN_PDA_USERNAME
ADMIN_PDA_PASSWORD
```

Admin 默认全量及依赖国内装柜链的定向验收必须提供 `ADMIN_PDA_USERNAME/PASSWORD`。管理员用于计划确认，PDA 作业员用于领取与执行；缺少作业员凭据在启动前阻断，不能以管理员身份代替已分配的作业员。

脚本只读取当前 Node 进程的环境变量，不会自行查找或加载上述文件。运行时必须把 `--env-file` 放在脚本路径之前，明确选择环境：

```powershell
# 测试环境
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/admin-test-env-acceptance.mjs

# 测试环境批量待分柜造数
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/it-test-wait-split-bulk.mjs
```

Client 全量、Client 入库测量与计费、待审核订单和批量待分柜均复用这套变量，不再维护各自的 Gateway、管理员或客户账号变量。外部文件必须保留在仓库之外，不得复制到项目目录、报告或提交记录。

## 脚本目录归属

脚本按作用域放置，不要求全部集中到根 `scripts/`：

| 目录 | 归属 | 是否直接运行 |
|---|---|---|
| `scripts/` | 仓库级验收、回归、诊断、环境辅助和静态合同 | 本文“仓库级入口清单”列出的文件可以直接运行 |
| `scripts/admin-test-env-modules/` | `admin-test-env-acceptance.mjs` 动态加载的业务模块、fixture 和离线合同 | 业务 `.mjs` 原则上不直接运行；模块名、依赖和边界见该目录 `README.md` |
| `scripts/openapi-validation/` | 全仓 OpenAPI 发现、解析和引用校验 | 从该目录安装依赖后运行 `validate-openapi.mjs`；`validate-openapi.test.mjs` 是离线合同 |
| `firstleg/scripts/` | Firstleg 服务内部 Java 包依赖分析 | 只维护 Firstleg 内部模块化基线，与服务一起演进 |
| `lastleg-service/scripts/` | Lastleg 服务内部 Java 包依赖分析 | 只维护 Lastleg 内部模块化基线，与服务一起演进 |
| `warehouse/scripts/` | Warehouse 公共主数据等服务局部离线合同 | 从后端根用 Node test runner 执行，不连接数据库 |
| `deploy/scripts/` | Jenkins/部署主流程调用的镜像部署与测试库初始化脚本 | 只在受控部署或测试基础设施流程运行 |
| `deploy/rocketmq/` | RocketMQ 容器启动时渲染 broker 配置 | 由容器入口调用，不作为人工验收入口 |

因此 `firstleg/scripts/`、`lastleg-service/scripts/` 和 `deploy/**` 不是散落或放错目录；它们靠近所属部署单元或运行组件。仓库检索到的可执行脚本如果既不在上述目录，也没有在本表登记，应视为脚本归属缺失。

## 仓库级入口清单

下表覆盖 `scripts/` 下所有非 `*.test.mjs` 的可执行入口。`*.test.mjs` 统一为离线 Node 静态合同，不访问测试环境；`admin-test-env-modules/*.mjs` 的逐模块说明由该目录 `README.md` 和总入口注册表维护。

| 分类 | 入口 | 用途与副作用 |
|---|---|---|
| 测试环境 HTTP | `admin-test-env-acceptance.mjs` | Admin 全模块真实 HTTP 验收；按模块创建、更新、停用测试数据 |
| 测试环境 HTTP | `pallet-location-test-env-acceptance.mjs` | 订单测量与连续库位扩展矩阵；串行创建 5 票独立订单，覆盖 1/2/3 张称重图、体积跨档、删图释放、补传复用和跨票隔离，不主动停用库位制造 A0 |
| 测试环境 HTTP | `client-test-env-acceptance.mjs` | Client 完整真实 HTTP 链路；写入客户、订单、入库、权限和消息数据 |
| 测试环境 HTTP | `client-quick-order-test-env-acceptance.mjs` | Client 快速下单定向真实 HTTP 验收；使用既有测试客户创建 FBA、海外仓和私人地址草稿，验证逐行失败与幂等重放，不提交订单 |
| 测试环境 HTTP | `client-phase2-test-env-acceptance.mjs` | Client 入库、测量、费用和权限专项；写测试数据 |
| 测试环境 HTTP | `create-pending-review-orders.mjs` | 固定客户批量创建并提交待审核订单，不做平台审核和后续履约 |
| 测试环境 HTTP | `it-test-wait-split-bulk.mjs` | 固定“IT测试”与“义乌仓”，渠道等随机，逐票推进到 `WAIT_SPLIT`；失败继续并落报告。只复用 `TP-001`/`YW-TP-002`，不新增托盘或库位，库位不足使用公共位 `A0` |
| 本地真实 API | `relabel-closure-local-acceptance.mjs` | 仅调用本机海外 Gateway/Print/File/Lastleg，创建合成换标单并验证重复下单、三类 PDF、PDA 换标、拆托/合托、返工和换标出库；会写入本地业务数据，不代表现场照片或财务验收 |
| 测试环境 Excel 造数 | `real-order-xlsx-test-env.mjs` | 从外部源 XLSX 按入仓码归并，严格匹配客户可用渠道、税制、目的仓；`preflight` 只核对，`create` 创建草稿，`pending-review` 批量提交后停在待审核且不使用托盘/库位，`wait-split` 只供少量完整测量验收。参数、限制及重跑说明见 `real-order-xlsx-import.md` |
| 测试环境 HTTP | `dimension-ocr-pricing-test-env.ps1` | 尺寸、OCR 和渠道计价专项，上传本地图片并写测试业务数据；包含历史默认参数，只能显式传入当前目标参数后使用 |
| 测试环境 HTTP | `export-center-test-env-acceptance.ps1` | 导出中心测试环境验收，会创建导出任务和相关测试数据 |
| 测试环境 HTTP | `phase2-test-env-acceptance.ps1` | 入库测量与计费测试环境 API 验收，会写业务数据 |
| 场景组件 | `mojia-measurement-scenario.mjs` | 被 Admin 验收入口复用的墨家测量场景；不是独立 CLI，调用正式测量接口并上传图片 |
| 定向诊断 | `pda-final-complete-diagnostic.mjs` | 对指定 PDA task 回查最终完成门禁；传 `--seed-evidence` 时会补五类证据并产生写操作 |
| 本地真实 API | `order-warehouse-real-api-regression.ps1` | 本地 Order/Warehouse 往来单位真实 API 回归，并直接读写本机 MySQL；不得指向共享或测试数据库 |
| 订单与客户本地验收 | `phase1-acceptance.ps1` | 订单与客户本地服务/API 综合验收，会创建本地业务数据 |
| 订单与客户本地验收 | `phase1-business-maturity-regression.ps1` | 订单与客户业务成熟度回归，调用本地服务并生成报告 |
| 订单与客户本地验收 | `phase1-onboarding-order-e2e.ps1` | 注册、资质、审核到下单的本地 E2E，会创建客户、仓库、往来单位和订单 |
| 本地质量 | `backend-full-regression.ps1` | Gateway 路由与 Mapper 门禁后执行根 POM 全部有效模块 Maven 测试；`-DryRun` 只打印与校验 |
| 本地质量 | `frontend-full-regression.ps1` | 编排 Admin/Client 本地测试、类型检查及国内/海外 PDA Node 全量测试，不访问 Gateway |
| 本地质量 | `database-comment-audit.ps1` | 离线扫描数据库中文注释，不连接数据库 |
| Jenkins 只读数据库结构 | `database-schema-contract.mjs` | 只查询 `information_schema` 核对区域初始化 SQL 的表和字段；不执行 SQL、不造业务数据、不执行迁移 |
| 环境间只读数据库结构 | `database-schema-diff.mjs` | 通过显式 `--left-env`、`--right-env` 双向比较两套 MySQL 的 schema、表和字段契约；默认忽略字段顺序，只查询 `information_schema`，差异时退出码为 1，不生成或执行修复 SQL |
| 本地质量 | `local-db-full-acceptance.ps1` | 只允许本机 MySQL 的受控 SQL 验收；非 dry-run 会写本地测试库 |
| 本地质量 | `mapper-scan-contract.mjs` | 离线检查 Mapper 注解与扫描入口，不启动 Spring、不连接数据库 |
| 本地质量 | `java-quality-summary.mjs` | 聚合 Maven 拓扑、OpenAPI、JaCoCo 和 SpotBugs 已有报告，不启动服务 |
| 本地质量 | `agents-index-contract.ps1` | 离线检查 AGENTS 快速索引与关键入口一致性 |
| 契约数据 | `synchronous-dependency-baseline.mjs` | 同步服务依赖合同的数据源，只由相邻合同测试导入，不是 CLI |
| SQL 合同辅助 | `sql-baseline-contract-helpers.mjs` | 只供离线 Node 合同读取统一增量 SQL、拆分表定义和种子数据；不连接数据库，也不是 CLI |
| OpenAPI | `openapi-validation/validate-openapi.mjs` | 发现并解析各服务 OpenAPI，检查跨文件引用；只读源码 |
| 本地环境 | `local-env.ps1` | 本地开发环境公共参数/辅助函数，由其他 PowerShell 脚本加载 |
| 本地环境 | `start-gateway-overseas-local.ps1` | 退役海外 Gateway 的遗留启动脚本，不属于当前统一 TEST 启动或回归入口；不得据此恢复海外 Gateway 部署 |
| Nacos 环境选择 | `use-nacos-environment.ps1` | 仅设置当前进程 TEST 配置；显式提供地址、实际Namespace ID与凭据，不联网、不写运行环境 |
| Nacos 配置发布 | `publish-nacos-config.ps1` | 仅发布 `config/nacos/test/*.yml`；必须指定实际Namespace ID，凭据从环境取得。`-DryRun`离线列清单；正式运行会写Nacos，需授权；失败停止，重跑完整匹配配置，不自动清理 |
| 密钥配置 | `generate-overseas-jwk.mjs` | 生成 3072 位海外 JWT RSA JWK 并写入指定 `deploy/env/.env.*`；已有 JWK 时拒绝覆盖，密钥文件不得提交 |
| 迁移辅助 | `migrate-local-qualification-file.ps1` | 本地资质文件迁移辅助，会修改本地文件/数据；运行前核对脚本参数和备份策略 |
| Jenkins 管理 | `provision-development-service-jobs.groovy` | Jenkins Script Console 批量准备开发服务 Job；默认 `applyChanges=false` 仅预览，改为 true 会创建 Job |

部署目录的入口另有：`deploy/scripts/deploy-built-service.sh`（单服务健康检查与失败回滚）、`deploy/scripts/deploy-development-service.sh`（经 SSH 部署开发服务）、`deploy/scripts/deploy-services.sh`（按服务列表编排部署）、`deploy/scripts/initialize-test-databases.sh`（初始化测试基础设施数据库）、`deploy/scripts/check-lingxing-browser.sh`（只读检查 Lingxing 浏览器容器及健康状态）和 `deploy/rocketmq/render-broker-config.sh`（容器内渲染并启动 RocketMQ broker）。这些脚本都会改变运行环境或依赖受控部署上下文，不能作为普通本地检查执行。

数据库迁移离线入口为 `deploy/sql/scripts/db-migrations.mjs`：`new` 自动生成单 schema 的下一个版本草稿，`check` 做范围/文件/跨 schema 静态检查，`plan` 生成选定服务的不可变清单，`run --dry-run` 只输出执行计划。当前不连接数据库；真实 Flyway 执行须等迁移阶段完成并获得对应环境授权。用途、参数和边界见 `deploy/sql/README.md`。

服务局部分析入口为 `firstleg/scripts/analyze-firstleg-dependencies.mjs` 与 `lastleg-service/scripts/analyze-lastleg-dependencies.mjs`，相邻的 `*.test.mjs` 负责对基线和违规依赖做离线回归；`warehouse/scripts/warehouse-public-master-data-contract.test.mjs` 只读校验 Warehouse 公共主数据 CSV 与 SQL。SQL 辅助文件 `scripts/db/incremental.sql` 不是当前统一部署入口，正式数据库变更以 `deploy/sql/README.md` 指向的统一增量为准。

`scripts/db/test-lastleg-relabel-return-transfer-columns.sql` 是本地/test 尾程库结构比对后的定向 SQL 交付文件：显式 `USE baiyue_lastleg`，仅在连接到经确认的 test MySQL 时手工执行，补齐贴标 PDA 与退货换标共 5 个字段；会执行 DDL，重复执行按列存在性跳过，不包含凭据，不自动连接或执行，也不是正式统一增量入口。执行失败须停止并核对目标实例和现有结构。

新增可直接运行的脚本时，必须同时在本节登记用途、目标环境、是否写数据和密钥边界，并运行 `node --test scripts/script-documentation-contract.test.mjs`。仅新增 `*.test.mjs` 或 `admin-test-env-modules/` 内部模块时，分别更新对应合同范围或模块 README，不把内部文件误写成独立入口。

| 验收目标 | 唯一入口 | 数据副作用 | 覆盖范围 |
|---|---|---|---|
| 平台后台全模块 HTTP 验收 | `scripts/admin-test-env-acceptance.mjs` | 会创建、更新或最终停用测试数据 | `--modules` 默认列表中的平台客户、仓储、订单、入库、分柜、装柜、船期、拖车、报关、海外排车/出库/派送/异常/回访、财务、通知、统计等模块 |
| 客户工作台完整 HTTP 链路验收 | `scripts/client-test-env-acceptance.mjs` | 会创建测试企业、订单、权限和站内消息数据 | 注册/审核、企业与个人资料、客户隔离、订单、文件、客户侧权限、消息已读与账号安全；未完成注册的同凭据重放须复用账号/客户/成员身份，不同凭据重复用户名须冲突；测量/计费继续使用下列专项入口 |
| Client 快速下单定向 HTTP 验收 | `scripts/client-quick-order-test-env-acceptance.mjs` | 使用 `MERCHANT_TEST_USERNAME/PASSWORD` 对应客户创建快速下单草稿 | 真实调用 `/api/merchant/v1/orders/first-leg/batch`，覆盖 FBA、多产品、海外仓、多个私人地址、地址归属失败、渠道失败、重复行、逐行隔离、失败重试、详情归属、幂等重放与冲突；只创建草稿，不提交、不审核 |
| 固定客户批量创建待审核订单 | `scripts/create-pending-review-orders.mjs` | 只使用 `MERCHANT_TEST_USERNAME/PASSWORD` 配置的客户账号创建指定数量订单 | 使用 `ADMIN_TEST_GATEWAY`，选择真实可计价仓库/渠道，创建并提交订单，停在待审核，不创建客户、不审核订单 |
| Client 入库测量与计费专项 HTTP 验收 | `scripts/client-phase2-test-env-acceptance.mjs` | 会写入测试环境业务数据 | 入库测量与计费客户入库、测量、费用和权限专项场景；不是替代 Client 全量入口 |
| 人工分柜至 LOADED 分段验收 | `scripts/admin-test-env-acceptance.mjs` 的 `manual-*-fixture/verify` 可选模块；步骤和参数见 `scripts/admin-test-env-modules/README.md` | fixture 通过正式 HTTP 准备本轮数据，verify 只读核验；不进入默认全量 | `WAIT_SPLIT → 人工分柜 → 推送预装 → 订舱关联/计划确认 → PDA 领取与原子 batch → 五类证据/完成 → LOADED` |

执行前必须确认目标环境、账号和数据清理/停用策略，并获得当前对话的测试环境验收授权。`admin-test-env-modules/*contract.test.mjs` 只验证模块脚本结构，不能代替 HTTP 验收。

推荐顺序：部署服务 → Admin 全模块 HTTP 验收 → Client 完整 HTTP 链路验收 → 前端真实页面调用和样式验收 → PDA 页面/设备验收。任何本地单测通过都不能替代 HTTP 全量验收。

## Client 快速下单定向验收

快速下单页面使用独立批量草稿接口，不等同于 Excel 批量导入。脚本按 Client 页面当前真实请求构造最小草稿，包含页面只要求 SKU 和箱数、其余货物字段为空值或零值的行为，用于及时发现前后端契约漂移。它会使用测试客户创建 FBA、海外仓和私人地址草稿，并验证无权限请求、单行失败隔离、详情客户归属与同幂等键重放。

```powershell
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/client-quick-order-test-env-acceptance.mjs
```

需要额外随机创建多张草稿做压力回归时增加 `--random-count 20`。随机批次在三种目的仓类型间轮换，具体仓库/地址、每单产品数和箱数随机；逐张回查客户归属、草稿状态、目的类型和产品数量，并对整批执行幂等重放。取值范围 `1-50`，会在基础矩阵之外额外保留对应数量的草稿。

报告写入 `reports/client-quick-order-test-env-*.json`。脚本不提交、不审核、不取消订单，成功草稿保留为可丢弃测试数据；真实 HTTP 仅在当前轮明确授权测试环境验收后执行。

## 订单测量与连续库位扩展矩阵

部署完成后，可用独立入口串行执行订单创建、审核建入库单、称重确认、库位指引、删除释放、补传复用、测量提交/审核至 `WAIT_SPLIT`。默认固定“义乌仓”并执行 5 个确定性场景：单图单槽、单图两预留槽、实测体积跨档、两图逐次扩容、小体积订单三图 `1→2→3` 连续扩容。每票使用独立订单、入库单、库位块和 reservation，最后额外验证跨票不串数据。

```powershell
node --env-file="$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env" scripts/pallet-location-test-env-acceptance.mjs
```

只回归部分场景时使用 `--scenarios single-image-single-slot,measured-volume-growth`；仓库可用 `--origin-warehouse-name <名称>` 覆盖。汇总默认写入 `reports/pallet-location-http-matrix-*.json`，每票完整证据写入相邻的 `*-details/` 目录。任一场景失败后仍继续执行剩余场景，最终以非零退出码和汇总报告统一暴露失败。

该入口只复用正式 HTTP 验收模块，不执行 SQL、不部署服务，也不会为了制造容量不足而批量停用普通库位；普通库位自然不足时记录是否落到共享 `A0`。共享 Warehouse 故障不做停服注入，其“不回滚测量主流程”语义由服务单元测试覆盖。真实 HTTP 仅在当前轮明确授权测试环境验收后执行。

## 固定客户待审核订单

需要为人工审核准备固定数量的订单时，使用 `create-pending-review-orders.mjs`。Gateway 统一读取 `ADMIN_TEST_GATEWAY`，客户账号统一读取 `MERCHANT_TEST_USERNAME/PASSWORD`；数量可通过 `--count` 或 `PENDING_REVIEW_ORDER_COUNT` 设置，默认 50。脚本不会创建客户，也不会调用平台审核、入库或后续履约接口。数量支持 `1-100`，每张订单创建后立即提交并回查客户端状态为 `SUBMITTED`，报告统一记录为 `PENDING_REVIEW`。

```powershell
node scripts/create-pending-review-orders.mjs
```

## 本地质量检查（非全量验收）

合并后海外新增能力的覆盖清单、fixture 依赖和未实现/未覆盖项见
`admin-test-env-modules/README.md` 的“合并后的海外增量覆盖”。
转运审核、草稿柜及托盘移除、BOL 与后台转派送复用默认注册的
`phase4-overseas-client-services`、`phase4-overseas-dispatch`、`phase5-overseas-fulfillment`，
不是独立造数脚本；新增离线检查为 `admin-test-env-modules/merged-overseas-coverage-contract.test.mjs`。
这些模块真实运行会创建和推进本轮测试业务单据，只有取得对应环境授权后才执行；
空驳回原因当前后端未拒绝，必须保留失败，不以离线合同通过声称全量完成。

Gateway 路由防漏：`node --test scripts/gateway-route-contract.test.mjs`。只读 Maven 模块的 `src/main/java` Controller 与国内/海外源码路由，自动组合类/方法路径并校验目标服务、路由优先顺序和内部路径隔离；不需要凭据、不写数据或报告，失败返回非零，修复后原命令重跑。包含删除船节点路由、错误目标、内部暴露的反向用例。支持当前字面量/类内字符串常量、短格式 Path 配置；复杂映射需同步扩展解析器，不得忽略失败。它不验证 HTTP 方法、权限、外部 Nacos 实际值或运行时可达性。

`backend-full-regression.ps1` 在 Maven 前执行该合同；根 `Jenkinsfile` 在服务打包调度前独立执行，不受 `SKIP_TESTS` 跳过 Maven 的参数影响。CI 的 `java-builder` 必须提供支持 `node --test` 的 Node.js（建议 22）；缺失时门禁失败，不自动安装或静默跳过。直接单服务 Job、手工 Git 提交不会自动触发此脚本，仍须遵守提交前检查规则。

以下命令只用于代码质量和契约回归，不访问测试环境，不代表服务全量可用：

| 检查 | 入口 |
|---|---|
| 后端 Maven 契约/单元测试 | `scripts/backend-full-regression.ps1` |
| Admin/Client/国内与海外 PDA 本地全量回归 | `scripts/frontend-full-regression.ps1` |
| PDA 本地页面和状态定向测试 | `../apps/pda-uniapp/tests/*.test.mjs` |
| 本地数据库 SQL 静态/受控验收 | `scripts/local-db-full-acceptance.ps1` |
| AGENTS 快速索引一致性 | `scripts/agents-index-contract.ps1`；只读核对根快速表唯一性、部署单元、业务模块、Client active 路由、海外仓业务范围漂移、仓库主档唯一权威、订舱候选与柜量语义、整柜出仓与船节点单调性、海外 Gateway 覆盖、PDA 页面/运行配置/独立更新/语言预留/能力开关、人工分段验收链、Maven 模块、Lastleg 海外安全投影、同步 Trace、关键入口与排除目录 |
| Mapper 注册静态合同 | `node scripts/mapper-scan-contract.mjs`、`node --test scripts/mapper-scan-contract.test.mjs`；自动核对全部持久化模块的 `@Mapper`、服务根包注解过滤扫描和唯一扫描入口，不启动 Spring、不连接数据库；`backend-full-regression.ps1` 在 Maven 前强制执行 |
| Java 质量聚合摘要 | `node --test scripts/java-quality-summary.test.mjs`、`node scripts/java-quality-summary.mjs --output target/java-quality-summary.json`；聚合 Maven/服务拓扑、OpenAPI 覆盖、JaCoCo 和 SpotBugs 报告，默认只报告存量缺口，CI 用显式 `--require-jacoco --require-spotbugs` 检查报告完整性且当前允许失败 |
| 单服务部署失败回滚合同 | `scripts/deploy-built-service-rollback.test.mjs`；模拟成功、健康失败和启动失败，确认仅恢复同服务先前健康镜像且部署任务仍失败 |
| 容器日志单写合同 | `scripts/container-logging-contract.test.mjs`；离线确认应用只写标准输出、Compose 默认使用宝塔可见的有界 `json-file` 驱动且不挂载应用日志目录 |

Admin/Client HTTP 脚本的离线合同只验证脚本结构、参数和模块边界，不访问测试环境：

| 合同范围 | 入口 |
|---|---|
| Admin 订单、箱码、国内货柜履约装柜/PDA、订舱、拖车、通知 | `scripts/admin-test-env-modules/*contract.test.mjs`；模块映射见 `scripts/admin-test-env-modules/README.md` |
| Client 消息中心调用 | `scripts/client-notifications-contract.test.mjs` |
| 验收入口与模块注册 | `scripts/full-regression-entry-contract.test.mjs`、`scripts/controller-pipeline-contract.test.mjs` |

## 后端全量回归

## 入口

在 `baiyue-firstleg` 根目录执行：

```powershell
.\scripts\backend-full-regression.ps1
```

## 前端全量回归

`frontend-full-regression.ps1` 编排本地 Admin/Client 的 `pnpm test`、`pnpm typecheck`，并默认执行国内与海外 PDA 的 `node --test tests/*.test.mjs`；不调用 Gateway、不部署、不连接数据库。

```powershell
.\scripts\frontend-full-regression.ps1 -DryRun
.\scripts\frontend-full-regression.ps1
.\scripts\frontend-full-regression.ps1 -SkipAdmin
.\scripts\frontend-full-regression.ps1 -SkipClient
.\scripts\frontend-full-regression.ps1 -SkipPda
```

脚本会检查 `pnpm` 和目标应用的 `package.json`；任一命令失败时立即透传退出码，不能同时跳过 Admin 和 Client。

后端脚本固定运行：

```text
mvn -f <仓库根>/pom.xml test
```

这会按根 POM 的 reactor 拓扑执行全部有效模块测试（当前 20 个模块，包括 Auth、Finance、Lastleg、海外仓资源、Print 及公共模块），不维护服务子集白名单；根 POM 后续新增模块自动纳入。既有 Gateway 路由与 Mapper Node 门禁仍在 Maven 前执行。关键覆盖包括：

- 国内货柜履约 Ocean Booking Controller/Service/Mapper/SQL 契约；
- 国内货柜履约 Truck Appointment Controller/Service/Mapper 契约、状态机、乐观锁和幂等操作；
- 入库测量与计费 `WAIT_SPLIT` 的 firstleg 查询、order 统一查询及筛选语义；
- Warehouse 海外仓阶梯费用 SQL 与 Controller 权限合同；
- 拣货/预装/装柜模型映射与既有 Smart Loading/Split 契约。

## Dry-run

```powershell
.\scripts\backend-full-regression.ps1 -DryRun
```

Dry-run 只检查根 `pom.xml` 和关键回归测试文件并打印 Maven 命令，不启动 Java 服务，不请求 Gateway，不连接或写入任何数据库。

## 现有相关脚本与边界

### 数据库中文注释审计

`database-comment-audit.ps1` 离线扫描各模块 `src/main/resources/db/*.sql` 中的 `CREATE TABLE` 定义，不连接数据库、不执行 SQL，也不修改任何文件。

```powershell
.\scripts\database-comment-audit.ps1
.\scripts\database-comment-audit.ps1 -Modules finance,order
.\scripts\database-comment-audit.ps1 -Modules finance -SummaryOnly
.\scripts\database-comment-audit.ps1 -Format Json
.\scripts\database-comment-audit.ps1 -FailOnIssues
.\scripts\database-comment-audit.ps1 -SelfTest
```

默认报告模式即使存在存量缺口也返回 `0`；CI 使用 `-FailOnIssues`，缺失或纯英文表/字段注释返回 `1`，模块或路径配置错误返回 `2`。规范和注释口径见 `../docs/数据库注释维护规范.md`。

### 本地 MySQL 全量验收

正式入口是 `local-db-full-acceptance.ps1`，只允许连接本机 `127.0.0.1` 或 `localhost`，默认端口 `3306`；任何非本机地址都会立即以退出码 2 拒绝。非 dry-run 默认连续执行两轮，每轮精确删除 12 个 `baiyue_*` 国内/海外业务库，再只执行 `deploy/sql/头程数据库统一增量-MySQL8.sql` 和 `deploy/sql/海外区域统一增量-MySQL8.sql`，最后核对两个文件的最终 `PASS` 与 12 库完整性。

```powershell
.\scripts\local-db-full-acceptance.ps1 -DryRun
.\scripts\local-db-full-acceptance.ps1
.\scripts\local-db-full-acceptance.ps1 -Rounds 1
```

Dry-run 只校验两个统一 SQL 的入口标记，打印当前 SHA-256、行数、清理范围和执行顺序，不连接 MySQL。真实运行会先把中文文件名按原始字节暂存为英文文件名，规避 Windows MySQL 客户端的 `source` 路径问题；每轮日志写入 `.codex-tmp/local-db-full-acceptance/round-*/`。脚本不保存数据库密码，认证由本机登录配置或当前进程的 `MYSQL_PWD` 等外部方式提供。成功后保留第二轮完整初始化结果；失败时可能留下半初始化库，下次运行会先清理精确范围再重建。

仓库中 `phase2-test-env-acceptance.ps1`、`admin-test-env-acceptance.mjs`、`client-test-env-acceptance.mjs`、`export-center-test-env-acceptance.ps1` 等属于测试环境/API 验收脚本；它们可能读取或写入测试环境数据，不由本入口调用。`migrate-local-qualification-file.ps1`、`local-env.ps1` 等是环境/迁移辅助脚本，也不由本入口调用。

本入口只操作明确指定的本机 MySQL，不访问开发或测试 HTTP 环境，不启动 Nacos、Gateway 或业务服务，也不会清理系统库或非 `baiyue_*` 数据库。

## 退出码

- `0`：dry-run 检查通过或 Maven 全量测试通过；
- `2`：仓库根 pom 或关键测试文件缺失，脚本未启动 Maven；
- 其他非零值：原样透传 Maven 失败退出码。

脚本不设置 `MAVEN_OPTS`、数据库 URL 或测试账号；环境参数仅为可选的 `$MavenCommand`（默认 `mvn`），用于指定本机 Maven 可执行文件。

## 海外换标定向验收补充

- `db/seed-local-relabel-ready-orders.sql`：仅供明确授权的本机测试库存准备。调用者在同一 MySQL 会话提供客户、共享海外仓、有效虚拟库位、FBA目的仓、唯一批次及ID基数；凭据由本机进程环境提供。以事务插入三单共54箱、六托及原入仓快照、计划、明细、余额、仓位和明确标记 LOCAL_TEST_FIXTURE 的库存流水；不伪造PDA照片、签收操作或HTTP验收通过，不修改原数据。重复批次失败并回滚，不用upsert重置已消耗库存；成功数据保留，结果表输出到调用者日志，不自动清理。

- `scripts/current-session-overseas-relabel-acceptance.mjs`：本地开发环境定向入口，从当前 Codex 内置浏览器本地存储读取最新平台/客户 refresh token，在内存中刷新双区域会话，自动选择当前客户具备足量库存的海外仓并临时创建海外 PDA 操作员；随后串行运行换标拆/合托、智能预排、PDA 出库与派送完成。报告写入 `reports/current-session-overseas-relabel/`，不记录 Token/密码；会消耗当前浏览器 refresh token 并保留业务验收单据，临时 PDA 在 `finally` 中停用。履约阶段中断后可显式设置 `OVERSEAS_RESUME_FULFILLMENT=true`，复用目录内已通过的 `relabel.json` 且只续跑出库派送。只允许本机开发环境且须有当前轮真实写入授权。
- `scripts/overseas-relabel-real-acceptance.mjs`：定向真实 HTTP 换标作业，会创建换标、库存及排车记录；从显式环境文件读取平台/PDA账号、网关及客户参数，输出脚本配置的报告，不自动清理。失败保留证据与已创建资源，重跑前核对报告，必须另获指定环境授权。
- 该脚本现按“扫码→组托→完工→客户确认”执行，`OVERSEAS_RELABEL_CHARGE_AMOUNT=0` 表示省略费用字段、只验仓库链路（不代表财务通过）；默认 0.01 验钱包冻结。照片为有效的合成测试 PNG，不是真实现场照片。
- `scripts/relabel-pdf-local-acceptance.mjs`：仅本机 Print→File 真实 HTTP 验收，显式提供 `INTERNAL_SERVICE_TOKEN`、`OVERSEAS_TEST_CUSTOMER_ID`，可配置 `PRINT_SERVICE_URL`、`FILE_SERVICE_URL`。创建三类测试 PDF 文件元数据，验证下载哈希及跨客户拒绝，报告 `reports/relabel-closure-20260916/pdf.json`；保留文件，不清理，失败非零退出，可重跑生成新 businessId。不代表换标下单/PDA全流程通过。
- `scripts/overseas-relabel-fulfillment-acceptance.mjs`：读取 `OVERSEAS_ACCEPTANCE_SOURCE` 或指定排车/换标编号，执行 PDA 拣货、出库、派送后续真实 HTTP，会推进业务状态；凭据来自显式环境文件，报告默认 `reports/overseas-relabel-fulfillment-acceptance.json`（`OVERSEAS_FULFILLMENT_OUTPUT` 可覆盖）。失败保留资源，重跑前核对业务状态，不自动清理。两个定向脚本不替代 Admin 全量入口，本次合并仅做离线合同。
- `scripts/warehouse-transfer-remaining-acceptance.mjs`：本地开发环境仓储转运真实 HTTP 验收入口，创建并推进转运、换标和库存业务数据，凭据来自环境变量或 `local-env.ps1`，报告写入 `reports/warehouse-transfer-remaining-acceptance.json`；失败数据保留，不自动清理。
- `scripts/warehouse-transfer-resume-acceptance.mjs`：续跑既有仓储转运排车、出库和派送流程，会推进真实业务状态；通过脚本内既有单据或环境变量定位待续跑数据，报告写入 `reports/warehouse-transfer-resume-acceptance.json`，不自动清理。
- `scripts/warehouse-transfer-receipt-acceptance.mjs`：本地开发环境目的仓收货真实 HTTP 验收，创建或通过 `WAREHOUSE_TRANSFER_RECEIPT_NO` 续跑库存转运并写入目的仓库存；凭据来自环境变量或 `local-env.ps1`，报告默认写入 `reports/warehouse-transfer-receipt-acceptance.json`。失败资源保留，续跑会复用同一报告中已创建的目的仓托盘，不自动清理。

部署离线合同：`overseas-deployment-contract.test.mjs` 现验证统一TEST拓扑，保留历史文件名便于调用；`deploy-built-service-rollback.test.mjs`以mock Docker验证失败与同契约回滚，无真实环境操作。唯一执行清单见 `../deploy/TEST单机部署执行清单.md`。
# 事件人工重试运维入口

`event-outbox-operations.mjs`：单测试环境的内部运维脚本。只连接显式指定的生产服务地址，不通过公网 Gateway，不自动重试或跟随重定向。凭据只从进程环境 `EVENT_OPERATIONS_TOKEN` 读取，另须 `CHONGCHONG_ENV=test`；不要把真实凭据放入参数或仓库。`--service firstleg|lastleg|finance --base <服务源地址> --entry <Outbox主键>` 只读查询状态和摘要，不返回业务负载。追加 `--retry --request-id <稳定UUID> --operator <操作人> --reason <原因> --hash <sha256摘要>` 会写入目标测试服务的 Outbox 与审计表，执行前须已有该环境操作授权。仅 DEAD 原事件可重试，事件身份、负载及摘要保持不变；重复提交使用同一个请求编号，参数变化会被拒绝。三个服务须先部署 `event_delivery_retry_audit` 表，未设置至少32字节的运维凭据时入口关闭。脚本将脱敏结果输出到标准输出，不持久化凭据；离线验证为 `node --test scripts/event-outbox-operations.test.mjs`。