baiyue-firstleg/scripts/README.md

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

`local-dispatch-transport-acceptance.mjs`：仅本机 LOCAL 的现有排车运输任务 HTTP 验收。显式 `node --env-file=<本机凭据文件>` 注入 `ADMIN_TEST_GATEWAY`、`ADMIN_TEST_USERNAME/PASSWORD`、`LOCAL_TRANSFER_PDA_PASSWORD`；拒绝远端网关。创建3张 TEST 仓储转运单、1张本土卡车原单、5张排车（完成/取消/重新安排），以及本轮专用调度/PDA账号、角色、车辆司机；缺失的正式排车权限仅补资源并授予专用角色，不修改既有角色。经正式网关验证原单审核、跨客户取货、资源冲突、凭证隔离、取消重排、发车完成回写、独立仓库清点和车辆司机释放。合成 PNG 只验文件链路，不代表实际运输或有效证照。默认报告 `reports/local-dispatch-transport.json`，可用 `TRANSPORT_ACCEPTANCE_OUTPUT` 指定；每步保留请求键、脱敏意图、错误码和关联标识，失败停止且保留数据。确认已知失败结果后显式 `TRANSPORT_ACCEPTANCE_RESUME=true` 复用同一报告继续；网络结果未知必须先核对，不自动清理或删除，不使用业务 SQL。已成功批次禁止重复运行；不能替代远端部署或人工截图验收。

`local-check.ps1`：Windows / PowerShell 7 本机重型检查统一入口，适用于前后端测试、类型检查、构建、安装依赖及 Maven。示例：`& ./scripts/local-check.ps1 -WorkingDirectory ../apps/admin-web -Label 'Admin typecheck' -Command @('pnpm', 'typecheck')`；`-Status` 查看占用。当前用户所有工作目录共用一个文件句柄锁，默认排队900秒、执行1200秒；超时分别退出75/124，其余透传命令退出码。Vitest workers=2，Node堆2048MB，Java堆1536MB/处理器2；直接 Maven 自动单线程/单fork，直接 Node 内置测试自动并发2。Windows Job Object 仅回收本次后代，不接管旧进程；嵌套调用拒绝，批次内部执行原始命令。无凭据、不主动联网或写业务数据；被包装命令的环境授权不变。状态和最近结果仅写 `%LOCALAPPDATA%/Chongchong/LocalChecks/`，不存命令参数或输出；不自动缓存成功结果。失败保留最近摘要，确认输入后重新排队；锁文件无需手工删除，状态不是验收报告。完整规则见 `../../docs/AI工程执行与协作约束.md` 的“本机重型检查与多对话限流”；离线行为测试为 `local-check.test.mjs`。

`local-transfer-pickup-acceptance.mjs`：仅本机 LOCAL 仓储转运取货造数与 HTTP 验收，拒绝非 localhost/127.0.0.1 Gateway。通过 `node --env-file=<本轮明确的本地配置> scripts/local-transfer-pickup-acceptance.mjs` 注入 `ADMIN_TEST_GATEWAY`、`ADMIN_TEST_USERNAME`、`ADMIN_TEST_PASSWORD`、`LOCAL_TRANSFER_PDA_PASSWORD`，不猜测或读取其他环境文件。创建16张明确 TEST 标记的业务单、专用PDA账号、司机车辆和多状态取货车次，含客户下单、跨客户共车、取消改派、资源占用、凭证隔离、送仓门禁与完整PDA测量。所有业务均走正式 Gateway HTTP，不用业务 SQL；文件是合成测试 PNG，不代表实际拍照或有效证照。报告默认 `reports/PICKUP-<新批次>.json`，可用 `PICKUP_ACCEPTANCE_OUTPUT` 指定；写入前保存脱敏意图与幂等键，逐阶段落盘。失败立即停止并保留已成功数据及报告，未知结果先核对原请求，不自动重发；重新执行会创建新批次，不自动续跑或清理旧记录。人工核实原请求结果后，可显式用 `PICKUP_ACCEPTANCE_RESUME=<本轮报告>` 沿已知单号继续验收；已成功批次禁止重复执行。脚本记录每次执行范围与结果，旧失败不删除；本机缺失的正式车次取消/结案/释放权限仅补权限资源并授权新建专用验收角色，不修改现有角色授权。账号和单据保留供本地页面验收，不能作为远端 TEST/生产或视觉验收结论。

`db/fleet-transfer-pickup-20261017.sql`：本功能 MySQL8 可重复执行结构增量，显式指向 `baiyue_lastleg`。为原车次增加 `trip_purpose`，新增取货计划摘要、原单任务、命令幂等、上传归属及历史五表；不写业务数据。结构同步于模块 `lastleg.sql` 和统一部署增量。需在已授权环境用运行者显式数据库凭据执行；失败保留诊断，修正后可重复执行，不删旧结构或业务数据。

`appointment-work-test-env.mjs`：预约事项与稳定批次 TEST 定向 HTTP 验收，默认 `--plan` 零网络；显式 `--execute --environment=TEST --run-id=<新批次> --mode=read|workflow --fixture=<本轮清单>` 才执行。运行者用 `node --env-file=<明确TEST配置>` 注入平台、客户及只读平台凭据，变量名和清单合同见 `--plan`。清单必须引用本轮正式业务生产者报告及 SHA256，不借用历史业务样本。read 只登录、查询、退出自身会话；workflow 还写一项跟进并验证原键重放、陈旧版本、异载荷和权限拒绝，可按清单登记客户仓无需预约要求，不代替排车/PDA/签收原域事实。报告写入独占的新 `reports/appointment-work-<run-id>/`；失败保留报告和业务记录，不自动重发未知结果、删除、重置或执行 SQL。离线合同为 `appointment-work-test-env.test.mjs`；只读或离线通过不代表完整运输履约、真实页面通过。

`../lastleg-service/scripts/selfoperated-test-env-acceptance.mjs`：自营统计 TEST Gateway 验收，默认仅输出计划；显式 `--execute --environment TEST --source-account <账号键> --warehouse <仓库编码> --other-warehouse <第二仓> --report <报告路径>` 才登录并查询。凭据由运行者通过脚本之前的 `node --env-file=<明确TEST文件>` 注入，需平台、只读平台、无权限平台及客户身份。`--probe-off-command` 仅在确认 OFF 后提交预期被拒绝的命令并核对无新增任务；不采集、发布、造数或写 SQL。`--synthetic-fixture <审核后的说明文件>` 验证合成样本，不能证明真实来源覆盖。报告脱敏记录各项结果及请求标识；失败保留报告，重跑使用新报告路径并重新登录，结束退出自身会话，不清理业务样本。离线合同为同目录 `selfoperated-test-env-acceptance.test.mjs`。

`db/cargo-discard-consolidated-incremental-20261014.sql`：废弃业务结构增量汇总，MySQL 8.0.16+，仅对 `baiyue_lastleg` 已有业务库执行。覆盖废弃基础表、PDA完工字段、照片关联、退货箱废弃状态、通用库存来源和部分选箱；表/列/索引按存在性判断，约束原子替换，可重复执行。不回填历史订单、不补造出库单、不修改库存数量，无业务 DML；File及仓储资源库无需本次SQL。实例和凭据由执行者指定，完整执行、遇错停止、不使用 `--force`；DDL隐式提交，修正错误后可重跑，末尾 `SHOW CREATE TABLE` 结果由执行者保存核对，不自动清理或连接环境。

`db/return-consolidated-incremental-20261012.sql`：10月10日/12日退货、签收、清点、换标与按件出库增量汇总，显式 `USE baiyue_lastleg`，MySQL 8.0.16+ 已有业务库可重复执行。本轮补齐签收原包装、尺寸重量来源及库存箱原包装三个字段；逐列判断存在性，不回填签收/清点事实，不改库存数量。连接实例及凭据由执行者明确指定，整份执行、遇错停止；保留执行错误，修复后可重跑，末尾输出字段、索引与约束供核对。托盘重量、体积汇总是应用逻辑，不新增资源库字段；不自动执行到测试或生产环境。

`procurement-sample-test-env.mjs` 是采购样品正常全链路 TEST 专项入口，默认或 `--plan` 零网络。真实执行使用 `node --env-file="<授权目录>/test-acceptance.env" scripts/procurement-sample-test-env.mjs --execute --environment TEST --run-id <唯一短批次> --warehouse-id <已核对有效海外收货仓>`。只允许当前 TEST 工作区及指定配置；由正式 API 创建独立客户并完成资质，人工充值10元，上传凭证/面单，调用内部 `procurement-sample-fulfillment.mjs` 完成两箱正常履约。充值、文件和采购请求前落盘，结果未知停写；报告独占 `reports/procurement-sample-<批次>/report.json`，不覆盖旧报告，不自动重跑，不执行 SQL/部署/删除。结束退出自身平台与客户会话，保留样本。通过只表示该正常路径，不替代异常、退款、权限、真实页面和请求量验收。离线入口合同为 `procurement-sample-test-env.test.mjs`；内部模块安全合同见模块索引。


`db/return-single-sku-quantity-incremental.sql`：MySQL 8已有尾程库的单SKU按件数出库增量，显式 `USE baiyue_lastleg`。新增明细件数快照，流水箱差允许0或1，同箱索引改为普通索引，保留拣货ID+SKU唯一防重和库存守恒约束；可重复执行，无凭据，不修改业务行。使用外部明确数据库连接，失败停止，保留DDL与错误，修复后重跑；执行后核对字段、CHECK和索引。

`db/overseas-business-acceptance-incremental-20261009.sql`：本轮海外业务本地验收已有库增量汇总，显式指向 `baiyue_lastleg` 和 `baiyue_iam`。合并四流程结构、退货合箱/合托、换标排车、箱内清点及会话、单SKU部分出库；来源文件列在每段头部，无SOURCE依赖，可重复执行。包含正式平台管理员作业权限补齐，以及条件限定的历史待清点和关联单号快照修正；不改库存件数、不强制推进履约、不删除业务数据、不生成测试资源。数据库实例和凭据由外部连接明确提供，MySQL8工具执行整份文件；遇错立即停止并保留DDL与原错误，核对后重跑，不使用--force。执行记录和结构回查为报告，未自动在TEST或生产执行。


`db/local-four-flows-schema-incremental-20261009.sql`：本地退货换标、仓储转运、贴标出库及退货出库结构比对所得的 MySQL 8 定向增量。显式 `USE baiyue_lastleg`，补齐预约结束时间/版本、转运换标来源绑定、分配 SKU 快照及转运收货幂等命令表；字段按存在性判断，表使用 `CREATE TABLE IF NOT EXISTS`，可重复执行，不删除或回填业务数据。使用操作者显式选择的本地数据库连接，无内置凭据；完整执行输出 `LOCAL_FLOW_SCHEMA_READY`。失败保留已完成的 DDL 与原错误，核对后重跑；不自动清理业务记录，不是全库迁移或生产验收入口。

`db/return-tail-order-number-incremental-20261009.sql` 将已验证关联的退货尾程单号及退货单尾程号快照统一为退货单号。显式 `USE baiyue_lastleg`，可重复执行，只更新同客户、关联订单 ID 和来源退货号均一致的 `RETURN_RELABEL` 单据；不改变业务 ID、库存或履约状态。执行前核对目标数据库，执行后核验查询应为空，异常关系保留供核实。已同步海外业务统一增量脚本。

`db/return-carton-count-session-incremental-20261009.sql` 为本地清点作业认领增量，明确指向 `baiyue_lastleg`，MySQL 8 可重复执行。新增按操作员唯一、签收批次唯一的持久会话表；开始清点后退出页面不释放，只有核平完成事务才释放，不修改库存数量。凭据取本机配置，执行输出作为迁移记录；失败保留错误，修复后重跑，不删除单据或清点会话。同表已同步尾程基线、海外统一增量及完整箱内清点增量脚本。

`db/return-carton-counting-incremental-20261009.sql` 为本地退货箱内清点增量，显式指向 `baiyue_lastleg`，适用于已执行退货合箱增量的 MySQL 8。增加清点状态、时间、操作人及索引；将整批仍可用且没有合箱追溯或换标占用的历史托盘签收箱转为待清点，不修改其数量。已履约或曾合箱的历史批次不自动回退，须单独核实。凭据由本机配置提供，不在脚本中保存；SQL 执行输出即为核验记录，可重复运行，已清点批次不会回退，失败保留错误和业务现场，不删除单据。同批结构同步到尾程基线与海外统一增量；服务须加载新代码后才能执行清点接口。

`db/return-relabel-truck-incremental-20261008.sql` 为本地退货换标排车增量，显式指向 `baiyue_iam` / `baiyue_lastleg`，适用于 MySQL 8。补齐管理员正式司机、车次与审核权限，以及车辆容量和正式车队表；不修改退货库存或业务单据。凭据从本机配置读取，可重复执行，失败保留原错误和业务现场；重新登录后核对权限快照。结构同步到基线及两个统一增量，权限由正式 IAM 权限种子维护。

`db/return-packing-incremental-20261008.sql` 为本地退货合箱增量，明确指向 `baiyue_iam` 和 `baiyue_lastleg`，适用于 MySQL 8，可重复执行。初始化平台管理员的库存管理权限，补齐精确预占、原退货单来源追溯、完成结果幂等快照和箱级库位字段，移除“一签收单只能一箱”的旧唯一索引；不修改退货、库存等业务数据。数据库凭据从本机环境配置读取；执行失败应保留原错误，修复后重跑，不清理验收业务单据。同批结构已同步到基线、海外统一增量与 `db/incremental.sql`。
`fleet-capacity-pool-ui-fixture-gray.mjs` 仅准备本轮授权的 GRAY 拼车角色页面、报价引用和 PDA H5 验收数据，复用 TEST UI producer/core，默认 `--plan` 零网络。执行使用 `node --env-file=<jenkins.env> --env-file=<gray-acceptance.env> scripts/fleet-capacity-pool-ui-fixture-gray.mjs --execute --environment GRAY --run-id <新批次> --warehouse-id <实际收货仓ID> --destination-warehouse-id <FBA目的仓ID> --private-credentials-file <私有env目录直接子级的独占JSON绝对路径>`。保留实际 `CHONGCHONG_ENV=prod|gray`，配置沿 GRAY 拼车专项的 CHONGCHONG_ADMIN 与 JENKINS_*；强制生产身份只读reader和品牌transport，不接受producer/reader覆盖。只建两客户真实来货、自有18/30计划、4完整草稿、两个销售及最小manage调度；销售A另含quote:list，销售B不含。准备窗口按同一时刻固定为8小时截止、9小时后计划发车、10小时后派送预计到站和12小时后司机结束；LocalDateTime到站与Instant车次时间分别处理。保留本批唯一仓绑定PDA为ACTIVE供H5，私有文件标记用途/仓库，不自动停用；脚本会话仍注销。凭据首次写入前wx独占并fsync，报告 `reports/fleet-capacity-pool-ui-gray-<批次>/` 全部脱敏，使用共享写锁，未知结果停写且不自动重试或覆盖；不创建池商业单、不发车签收、不写SQL或部署。原TEST UI入口仍24草稿且自动停用PDA。直接离线保护为 `fleet-capacity-pool-ui-fixture-gray.test.mjs`，凭据独占及脱敏复用 `fleet-capacity-pool-ui-fixture-test-env.test.mjs`。

`fleet-capacity-pool-gray.mjs` 是明确 GRAY 的拼车专项入口，复用既有池全流程矩阵与两客户实货前置，不执行旧 FBA 下单、报关或装柜链。默认 `--plan` 零网络、零文件写入；执行必须传 `--execute --environment GRAY --run-id <新批次> --warehouse-id <实际海外仓ID> --destination-warehouse-id <FBA目的仓ID>`。命令前使用 `node --env-file=<独立jenkins.env> --env-file=<明确gray-acceptance.env>`，要求 `CHONGCHONG_ENV=prod` 或 `gray`、`CHONGCHONG_ADMIN_API_BASE_URL`（统一 HTTPS 源站加 `/api`）、`CHONGCHONG_ADMIN_USERNAME/PASSWORD` 和 `JENKINS_URL/USER/API_TOKEN`；不改私有配置、不冒充 TEST、不使用 TEST agent。库存证据由 `createGrayEvidenceReaders` 校验生产容器、profile及数据库身份后只读取得。报告独占 `reports/fleet-pool-gray-<新批次>/`，沿共享 `.fleet-acceptance.lock` 串行执行；每次写入先持久记录原键与意图，结果未知停写，失败保留样本，不自动续跑或覆盖。结束停用本轮临时销售/调度/PDA账号、退出会话；合成客户、司机/车辆、报价、文件和业务样本留存，费用仍由唯一真实派送来源产生，不发起支付。Admin 通用 GRAY CLI 的 F40 白名单不变，专用 transport factory 只能创建空模块且无故障注入的灰度上下文。直接合同 `fleet-capacity-pool-gray.test.mjs` 验证环境隔离、品牌门禁和复用范围；原 TEST CLI 仍拒绝 GRAY。本入口不部署、不写业务 SQL，不将专项通过冒充全部页面验收。

拼车主入口 `fleet-capacity-pool-test-env.mjs` 除两笔真实履约订单外，还各创建一笔本土散板/卡车的“已确认、未登记来货”取消样本，核对商业单与预订同步取消、三维容量恢复和原键重放；增加来货后取消/实收超量拒绝、绑定后占位转计划不双扣、事实失效须重新核对并显式恢复，以及跨销售写入/跨客户商业单拒绝。正常链通过拼车专属 `save-and-confirm`、`fulfillment`、`incoming`、`receipt-confirmation` 和 `arrange-dispatch` 接口验证简化操作及原命令重放，不再以脚本手工建排车再绑定代替自动关联；另建精确履约权限账号，验证仅有拼车管理权限不能安排来货、确认实收或生成排车，销售仅能读取本人履约。拒绝动作须回查原事实与库存不变，不能仅按错误码判定通过；不注入业务数据库故障。

`fleet-capacity-pool-ui-fixture-test-env.mjs` 仅准备内部拼车池TEST页面验收数据，默认 `--plan` 零网络；实际命令沿 `--execute --environment TEST --run-id <新批次> --warehouse-id <实际海外仓ID> --destination-warehouse-id <目的仓ID>`，另必须显式传 `--private-credentials-file <用户.codex/env/chongchong-global目录直接子级的独占JSON绝对路径>`。通过明确TEST环境文件读取CHONGCHONG_ADMIN及Jenkins只读取证配置，创建两客户真实来货和计划车次、OPEN发布、两销售各12条不占位草稿及最小调度账号；停在可交互状态，不确认承运、不拣货发车、不声称全量验收。密码只在首次写入前独占创建的私有文件中保存，报告 `reports/fleet-capacity-pool-ui-<新批次>/` 不含密码/Token；失败保留现场和原请求，不自动重跑。退出脚本会话并停用自有fixture PDA，保留UI账号供浏览器验收；不部署、不写业务SQL、不删除业务样本。离线安全与作用域合同为 `fleet-capacity-pool-ui-fixture-test-env.test.mjs`。

`fleet-capacity-pool-test-env.mjs` 是内部拼车需求池 TEST 专项入口，默认 `--plan` 零网络；实际执行须显式 `--execute --environment TEST --run-id <新批次> --warehouse-id <实际海外仓ID> --destination-warehouse-id <目的仓ID>`，凭据由命令前的 `node --env-file=<明确TEST配置>` 提供，配置同时包含 Jenkins 只读取证凭据与 `FBA_CORE_JENKINS_AGENT`。创建隔离客户、销售、调度、预订及商业订单，验证容量争抢、销售隔离、命令重放、两类本土订单实际到仓/PDA收货/共享车次/出库签收和费用唯一；不部署、不写业务SQL。证据保存在 `reports/fleet-cross-<新批次>/`，包含 `pool-scope.json` 和写请求journal；未知结果停止，保留原样本与请求，不覆盖批次、不自动重造数据。结束退出独立会话并沿fixture清理其自有PDA访问，业务样本保留；页面及未覆盖矩阵单独报告，不将专项通过当成全量验收。离线保护由 `fleet-capacity-pool-test-env.test.mjs` 验证。

`inbound-plan-resource-fault-executor.mjs` 是单柜入仓计划资源确认故障的 TEST 环境执行入口，内部使用 `inbound-plan-resource-fault-runtime.py`。默认 `plan --plan <单柜计划.json>` 零网络；实际动作必须读取明确的TEST/Jenkins外部配置并传 `--confirm-test-runtime yes`。`preflight --routing <私有路由.json>` 只读校验Lastleg与Warehouse Overseas镜像/指纹、实际网络和Nacos common/lastleg配置摘要；`prepare`另要求 `--expected-image <已冻结镜像ID>` 及预检摘要。`activate`只临时改Lastleg的 `baiyue.warehouse.base-url`，配合 `mode --mode CONFIRM_ONCE --ttl 60` 精确注入一次confirm失败；业务转换和关闭重开页面由调用者独立操作，工具没有造数、SQL或业务写接口。`status/health/records`用于观测，结果未知先 `status/reconcile`，禁止因观察超时重复创建容器；`restore/verify-restored/finish`须按原镜像、完整配置/挂载/网络、Nacos及上游健康恢复后才停自有代理、清私有凭据。服务变更先记录意图，受限远端恢复状态目录为 `/tmp/chongchong-inbound-resource-<marker>`，由总控持独占Lastleg故障窗口；调用结果和业务证据另存本次独立 `reports/` 目录，失败保留、不覆盖，不与部署或其他共享业务写入并行。`inbound-plan-resource-fault-executor.test.mjs`、`inbound-plan-resource-fault-runtime.test.mjs` 为离线边界及恢复测试，不证明真实故障已跑通。

F33 分阶段助手的组合换标顺序为 `unit → unit-carton → bind`：只有完整逐箱作业事实后才可绑定实物托盘，不用默认数量补齐缺失事实。已明确拒绝的绑定仅允许当前已冻结原票、原批次、原命令摘要的 `F33_BIND_A0409_AFTER_UNIT` 恢复，必须同时核对不可变失败journal、完整回滚证明和新作业事实/原资源版本，恢复写入独立journal，不覆盖原失败。未知结果、其他拒绝和其他阶段仍禁止自动重试；响应message脱敏留存。该受限恢复只用于原TEST验收，不放宽生产接口或变更库存规则。

远端执行器仅通过标准输入传递有界UTF-8 JSON配置，不将包含源码的配置放入进程参数，避免Linux单参数长度限制；输入上限1MiB，运行代码参数小于64KiB。进程启动失败和stdin写入结果未知分别返回安全错误码；仅解析一条结构化结果，不输出完整配置、底层异常正文或凭据。stdin结果未知仍先按原marker核对状态，不能自动重试prepare或容器变更。

`inbound-plan-resource-fault-proxy.py --config <权限0600的私有配置>` 是柜级入仓计划资源确认的 TEST 定向故障工具。导入不执行，运行才监听业务端口与回环控制端口；复用 `order-submit-dependency-fault-proxy.py` 的 HTTP 传输和服务，配置必须显式 `environment=TEST`，冻结柜ID、海外仓ID、按当前协调器JSON字符串算法计算的柜批次前缀、Lastleg来源IP和内部身份。默认直通；持有私有控制凭据的 `CONFIRM_ONCE` 最长60秒，只让该柜精确 `/internal/v1/warehouse-pallet-batches/confirm` POST 返回一次503，随后自动直通。其他柜、预留/查询、错身份及不匹配请求保留原请求响应。凭据只读私有配置，脱敏证据写同目录 `proxy-evidence.jsonl`，不保存正文或令牌。工具不修改SQL或Docker，不自行重试业务或恢复服务路由；运行者须先安排独占故障窗口、记录并恢复原Lastleg配置/镜像及健康、停止本代理，结果未知先核对，不盲目重启。`inbound-plan-resource-fault-proxy.test.mjs` 为离线范围、单次并发、TTL与脱敏测试；工具检查通过不等于已执行真实故障与页面恢复。

`partial-loading-actual-test-env.mjs` 是 F21/F22 两柜实装与部分装柜的 TEST 专项入口，默认无参数或 `--plan` 零网络。使用显式授权 TEST 环境文件，匹配 Firstleg/触发器就绪并开放独占样本窗口后，才可传 `--execute --environment=TEST --run-id=PARTIAL-ACTUAL-<新批次> --fixture=NEW`，或用 `--fixture=<manifest.json>` 提供本轮已核对来源。新准备只走客户资格、下单、测量、装柜正式接口；A 覆盖混合客户/税制、短拣和跳过，B 的全部实装行均为 PARTIAL、退税来源全部跳过。检查实际数量/指标、报关范围及同命令重放；合成图片只证明 HTTP，不是现场证据。报告保存至 `reports/partial-loading-actual-PARTIAL-ACTUAL-<批次>/`，先记录写入意图，拒绝覆盖；失败保留原样本和报告，未知结果不得自动重造或重试。仅在明确续跑授权和原快照核对后接续，退出自己的会话；不执行 SQL/部署、船节点或历史回填，不代替事件 ACK/下游库存、完整报关文件和页面/设备验收。直接测试 `partial-loading-actual-test-env.test.mjs`。

`fba-remaining-nodes-acceptance-transfer.mjs` 是 F33 原已有库存转运的内部验收助手，导入不执行。`freezeTransfer` 使用显式 TEST 配置建立独立会话，只读原票和来源库存后退出；`prepareOriginalTransferPlan` / `prepareTransferStage` 只准备本票真实关联换标的逐阶段命令，不能预设关联号。`runPreparedTransferStage` 默认零网络，只有总控明确 TEST、原票、客户、阶段和稳定批次并注入已核身份的单请求流 transport 后才执行；照片以原字节摘要校验，客户确认使用本票 MERCHANT 身份，不调用被禁止的 PDA 独立复核批准。报告与写入 journal 在 `reports/fba-remaining-nodes-20261004/transfer/`，写前持久化意图；只有已明确成功的原键原载荷可显式重放一次，上传不可重放，失败或结果未知先回查，不能新建替代票、解冻其他业务或重新收货。调用者须逐阶段独立核对库存、其他 HOLD、追加流水和主体归属，HTTP 成功不自动标记业务通过；退出自身会话，不执行 Firstleg 写入、SQL、部署或删除。直接测试 `fba-remaining-nodes-acceptance-transfer.test.mjs`。

`fba-remaining-nodes-acceptance.mjs` 是 FBA 剩余节点内部证据助手，显式调用 `auditRemainingNodes`，导入不运行；读取指定原报告并按 JSON pointer/SHA-256 保留证据。`live=true` 仅使用明确 TEST 配置的独立 Auth 会话和串行 GET，结束退出；不执行业务写命令、SQL、故障注入、部署或页面操作。报告位于 `reports/fba-remaining-nodes-20261004/`，拒绝覆盖既有报告，失败保留且不自动重试。对应离线测试为 `fba-remaining-nodes-acceptance.test.mjs`，只读核验不等于原业务已完成。

`fba-remaining-nodes-acceptance-pda-operator.mjs` 是 F33 海外 PDA 的一次性 TEST 账号准备助手，导入不运行。显式调用 `createF33PdaOperator({env, credentialFile, reportFile})`，凭据来自已授权 TEST 环境；仅通过正式 IAM API 创建独立洛杉矶仓作业员、授予已存在的海外 PDA 角色并验证登录/仓绑定，不改角色权限或旧账号，不操作库存。随机凭据仅写入调用方指定的仓库外环境文件，报告建议保存 `reports/fba-remaining-nodes-20261004/pda-operator/`，不包含密码或 Token；已有文件、请求未知结果或首次强制改密均停止，禁止自动重造。退出自有管理员/PDA会话，账号保留供页面验收，报告给出精确停用接口，清理由总控在验收结束后执行。

`fleet-same-route-cost-test-env.mjs` 是同路线自有/外接实运成本分摊的串行TEST入口，默认`--plan`零网络；执行参数为`--execute --environment TEST --run-id <新批次> --warehouse-id <实际海外仓ID> --destination-warehouse-id <FBA目的仓ID>`，凭据仅通过显式TEST/Jenkins环境文件及`FBA_CORE_JENKINS_AGENT`提供。两新客户普通来货/PDA实收/客户确认各一托一箱，共用一张原生排车；真实外接预订、来货和运营确认实收后加到原主单，三托统一目的站，零扫码退回后重新两审、按各客户实拣、实际装载、平台逐组安排，再以当前版本整车发车。登记USD1.00合成成本，以不可变DEPART实测托位核对两条业务分摊：OWN按本张排车单汇总两实托，EXTERNAL按真实booking业务号计外接实托，两行共用同一dispatchNo。实际容量2:1时为0.67/0.33，非单位容量按实际比例及业务号顺序分配最大余数，不按托盘个数或预设比例替代。保留每客户来源、库存/SHIP、原币分币守恒、成本创建重放与唯一历史，逐派送单去重签收、正式结案并分别释放车辆/司机。不写业务SQL、不部署、不操作财务付款。报告沿`reports/fleet-cross-<新批次>/`，增加`same-route-source.json`和`createdResources.fleetSameRouteCost`；显式SAME_ROUTE_COST校验域要求本轮marker、排车、车次及原proof一致，不能借跨客户或容量池结果结案。失败保留原请求/样本、停止且不自动重跑，缺实测先阻断，finally停用自有PDA并退出会话。`fleet-same-route-cost-test-env.test.mjs`验证错误来源/目的地/冻结依据/分币及零网络计划；真实HTTP与页面结论分别记录。

`fleet-booking-quotes-test-env.mjs` 是外接预订选用销售报价的独立 TEST HTTP 验收入口，使用显式 `node --env-file=<用户指定目录的test-acceptance.env>` 和 `--ready-commit=a6fd0ba3`，执行前须由总控核对实际部署版本与健康。只读公共仓城市/时区，创建自身全新隔离客户、销售报价及未分配资源的车次/询价草稿；验证候选日期/币种/计价、零价与缺价、手填价格、陈旧版本拒绝、刷新重选及来源快照，不创建库存、不发车、不证明承运成功或实收完成。请求前持久留证、敏感字段脱敏、未知结果停止且禁止自动重跑，独立登录并退出；保留自己的计划/报价/草稿，不删除资源。当前固定R2标识，独占报告 `reports/fleet-booking-quotes-live-20261003-r2/`。离线合同 `fleet-booking-quotes-test-env-contract.test.mjs`，运行前仍须总控放行对应健康版本。

`deploy/scripts/run-ci-maven.sh` 是 Linux Jenkins 的受限 Maven 构建入口，不部署、不访问业务数据库、不安装依赖。总控及单服务 Job 共用 `firstleg-test-maven` 锁；同一构建账号另用 `$HOME/.cache/chongchong-ci/maven.lock` 文件锁，已有本机持锁任务时失败退出，不删除锁文件或杀其他进程。入口禁止 `-T/--threads`，固定 Maven 堆768MiB、元空间256MiB、直接内存128MiB，启用根POM `ci-bounded`：单个测试JVM、堆1GiB、元空间384MiB、直接内存128MiB，保留JaCoCo迟绑定；OOM快速退出，父进程丢失检测、停止时kill、单测试JVM20分钟上限。独立于Jenkins连接的本机GNU timeout在45分钟后TERM、30秒后KILL进程组，流水线另设50分钟超时；缺少flock/timeout/mvn直接失败。构建输出及Surefire报告沿现有Jenkins归档；失败先确认原进程退出再重跑，不自动清理缓存。该预算不等于总RSS硬限额，代理本身和JVM原生内存仍需保留余量；节点执行器应设为1、保持systemd control-group清理，并在真实Linux节点验证峰值。`ci-maven-resource-contract.test.mjs` 检查双入口接线、参数拒绝/失败传播和子JVM配置，Shell替身检查不代替Linux实际锁与信号验收。

`client-address-isolation-test-env.mjs` 是客户地址提交隔离的 TEST 定向负向入口，默认 `--plan` 零网络；执行要求显式 TEST 配置及 `--execute --environment=TEST --run-id=<新批次> --customer-profile=<同目录test-ui-*.env>`。分别登录两个既有客户，从来源客户读取仍有效的取货/私人地址、从目标客户读取实际仓库和渠道；向目标客户发两次单单与两次单行批量 JSON 创建请求，必须精准返回“客户地址不存在或已停用”，普通必填错误不算通过。每个载荷只含一种外客户地址，成功返回订单或未知结果立即停止，报告保存幂等键/载荷摘要/意外订单标识供定位，不自动重试、删除或恢复；结束退出两个独立会话。独占报告 `reports/client-address-isolation-<run-id>/`，不记录凭据、地址明文或账号。该项不等于 XLSX 解析拒绝、数据库零漂移或真实页面验证；对应 `.test.mjs` 检查精准错误分类与探针载荷。

`client-xlsx-address-test-env.mjs` 补充真实 XLSX 地址隔离负向导入，默认计划零网络。执行用显式 TEST 配置，参数为 `--execute --environment=TEST --run-id=<新批次> --customer-profile=<同目录test-ui-*.env> --python=<bundled Python>`；内部 `client-xlsx-address-probe.py` 只在内存读取两个客户的真实模板，保留来源模板的隐藏选项/关系，仅填一行取货或私人地址后以对照客户上传。两次 PARTIAL 导入必须精准拒绝外客户地址，普通格式/必填错误不通过；导入源文件及错误报告会保留，意外成功/未知结果立即停止，不自动重试、删除或推进订单。凭据只经 stdin，报告 `reports/client-xlsx-address-<run-id>/report.json` 只保存摘要、响应码和返回资源标识，会话结束退出；不保存原工作簿/地址明文，不代表浏览器通过。可追加 `--database-profile=<同目录test-database.env>`：用现有 mysql CLI 的只读一致性事务，在导入前及每次拒绝后读取两客户 Order 的订单、货物、参与方、内部备注、状态历史、幂等和领域 Outbox 七表完整记录摘要（含逻辑删除），严格比较数量与完整摘要；不同、缺表、截断或查询失败即停止。DB 凭据只进入子进程环境，报告不含原始行；文件、审计及认证正常留存不属于这七表不变断言，不声称全环境零写入。未传此参数只验 HTTP。对应 Node/Python 测试检查零网络计划、环境边界、精准拒绝、模板其他部分不变及数据库快照完整性。

模板检查器可另传显式 `--customer-profile=<同一授权目录下test-ui-*.env>`，仅替换该次独立会话的测试客户凭据，Gateway 与 TEST 环境保持由 `test-acceptance.env` 决定；拒绝生产、数据库文件和目录外路径。报告只保存权威客户 ID 的 SHA256，以 `compareCustomerTemplates` 对照两个不同客户的匹配结果；读取地址/模板不串客户与“提交外客户地址被拒绝”分开记录。

`client-import-template-test-env.mjs` 为批量导入模板只读 TEST 检查，默认 `--plan` 零网络。执行参数沿用 `--execute --environment=TEST --run-id=<新批次>`，另传 `--python=<load_workspace_dependencies返回的Python路径>`；只使用显式 TEST 验收配置。内部 `client-import-template-inspect.py` 下载模板并在内存用 bundled openpyxl 读取，不写 Excel；与完整启用仓库分页、各国内仓渠道并集、当前客户取货/私人地址逐项对照，同时检查命名范围、隐藏选项和 50 行下拉。只登录/退出可用 POST，不导入或创建业务数据，不保存原始模板和客户地址；报告独占 `reports/client-template-<run-id>/`，失败保留。对应 `.test.py` 在内存构造最小 OOXML 检查缺项、额外项、错范围和重复名称；真实第二客户负向隔离及 Excel 桌面操作另验。

`client-workbench-test-env.mjs` 是客户订单工作台只读 TEST 分页验收入口，默认 `--plan` 零网络。Firstleg/Order 新工作台接口部署后，以显式 `node --env-file=<用户指定目录的test-acceptance.env> scripts/client-workbench-test-env.mjs --execute --environment=TEST --run-id=<新批次>` 执行；独立客户登录及退出是唯一 POST，不创建订单、不写 SQL、不调用会补建预入库记录的旧草稿列表。要求稳定样本超过 200 条，遍历完整工作台及独立统一订单集合，核对完整正式单集合、费用/草稿待办、报关队列分页数量、21页切片、渠道筛选和伪造客户参数。报关业务资格、第二客户负向权限、页面及写后刷新仍需另验。报告独占 `reports/client-workbench-<run-id>/`，请求前持久记录脱敏意图，失败保留且结束退出自己的会话；不保存凭据或原始客户明细。`client-workbench-test-env.test.mjs` 用故障响应验证拒绝截断、重复、错页和客户泄漏，不能替代真实 TEST 结果。

`fleet-operations-test-env.mjs` 是车次运营统计独立只读TEST入口。显式环境文件及`--ready-commit=a6fd0ba3`之外，必须提供`--fixture=reports/<C批次>/handover-fixture.json --fixture-sha256=<文件SHA256> --marker=<该轮marker> --run-id=<独立批次>`；校验本轮真实DEPART和已核平车次成本，不能借历史车次或从统计响应反推期望。独立登录，只读该车次/历史/运营统计及导出，禁止造数、业务写入和里程更正；登录/退出为唯一POST。报告`reports/fleet-operations-<run-id>/`独占且请求前落盘，原币成本CNY100.03与USD13.07分开；失败保留证据、禁止覆盖重跑，结束退出独立会话。来源断言和权限由正式入口及`fleet-operations-test-env-contract.test.mjs`共同约束，离线测试不证明真实统计已通过。

`fleet-quotes-test-env.mjs` 是独立报价TEST验收入口：显式使用 `node --env-file=<用户指定目录的test-acceptance.env> scripts/fleet-quotes-test-env.mjs --ready-commit=a6fd0ba3`，仅在总控确认匹配服务健康后执行。使用独立登录和本轮客户/供应商/报价，不借其他任务会话；固定marker为`FLEET-QUOTE-20261003`，报告目录`reports/fleet-quote-live-20261003`独占。登录、客户前置和业务请求均由脱敏持久化日志包裹，发送前fsync原请求/幂等键与文件样本引用；结果未知停止业务，保留原样本，拒绝自动重跑/续跑/覆盖。结束退出独立会话，不执行SQL、部署或库存操作。该入口只证明报价范围，运营统计仍须本轮真实DEPART及独立预期，见模块README。

`fleet-company-cost-test-env.mjs` 是公司车辆成本独立 TEST 验收入口，复用 Admin HTTP 客户端但不展开其他业务模块或复用其会话/样本。须在脚本前显式 `node --env-file=<用户指定目录的test-acceptance.env>`，并在总控确认服务就绪后传入 `--ready-commit=8700fc34238bc33339351c73c15f3af8de8ce517`。固定 marker 为 `FLEET-COST-20261003`，报告为 `reports/fleet-cost-live-20261003/api-report.json`；既有报告拒绝覆盖重跑。只创建本任务供应商、车辆、维修/救援、公司费用与合成付款凭证；不操作库存、不创建客户或客户费用、不修改共享汇率。客户费用池只读检查本 marker 来源未误入；不借用其他客户进行成本明细或账户查询，不保存其他客户数据。请求前落盘原内容及幂等键，失败保留证据；结束退出本任务会话、停用本任务车辆，不删除数据。真实执行仍须本轮 TEST 授权及服务就绪；离线检查见 `admin-test-env-modules/fleet-company-cost-acceptance-contract.test.mjs`。

`fee-void-recovery-test-env.mjs` 是费用作废确认响应丢失的 TEST 专项入口，默认 `--plan` 零网络。执行须显式传入 `--execute --environment TEST --run-id <新批次> --customer-id <测试客户ID> --control-customer-id <另一测试客户ID> --warehouse-id <海外仓ID>`，外部 TEST/Jenkins 配置及 `FBA_CORE_JENKINS_AGENT` 提供凭据与取证节点。创建一条新仓储服务应收，经提交审核和原发布确认后，对该来源版本的 VOIDED 事件注入 ACK 丢失；原事件 DEAD 后受保护重试，核对最终作废、同命令重放、另一客户费用与完整库存不变。不写业务SQL，不使用旧费用作废；故障窗口会临时重建同镜像 Lastleg，禁止并行发布或其他共享环境写入。报告在 `reports/fee-void-<新批次>/`，请求前保存意图，失败保留样本，不自动重跑或覆盖；finally 恢复原服务、停止代理并退出会话，恢复未证明则失败。`fee-void-recovery-test-env.test.mjs` 是离线编排与失败清理检查，不能代替真实环境结果。

`test-fee-void-fault-proof.mjs` 是上述流程的内部只读证据校验器，无独立 CLI；配合 `test-event-fault-executor.mjs` 与 `test-event-fault-runtime.py` 检查原费用发布确认、精确作废事件、Finance 消费及 Lastleg 确认状态。实际运行结论只以该批次证据为准。

费用作废代理使用 `event-delivery-fault-proxy.py --fee-source-id <来源ID> --source-version <版本>`，两参数必须成对且不能与其他选择器混用，事件类型固定 `BusinessFeeSourceChanged`，仅匹配正式 action `VOIDED`。指向正式费用消费路径时，同源 `/internal/finance/v1/wallet-command-events` 保留原请求与响应直通，不进入费用故障选择；其他未配置路径仍拒绝。此边界由代理离线测试覆盖。

`test-delivery-fault-proof.mjs` 是签收回写故障的内部证据校验器，无CLI、网络或写入。按精确客户/派送/来源入仓/来源订单/根订单核对原事件及载荷摘要、13次投递与代理记录、唯一收件箱和人工重试审计，并比较重试前后的Firstleg与Order事实。首片签收仍有有效余量时允许根单继续等待；不把根单必须立即COMPLETED当成成功条件。

F40 专项可用 `--signature-mode ROOT_FIRST|CHILD_FIRST|ROOT_SIGNED_REMAINDER_CANCELLED` 只运行显式指定的一种顺序，省略仍串行执行三种；报告和成功范围仅覆盖所列模式。`--verify-delivery-event-recovery` 必须同时显式指定一种顺序，且环境为TEST；仅在该模式第一张真实FBA派送签收前开启定向ACK丢失，不能使用普通海外转运的签收替代国内回写。故障窗口会重建同镜像Lastleg并临时调整事件目标和退避配置，禁止与其他部署或共享环境写入并行；原事件DEAD恢复后必须验证原镜像/配置/网络身份、健康及代理退出。入口事先留存精确故障scope，finally兜底恢复，缺恢复证据或恢复校验失败一律失败。完整库存取证接入既有只读器，报告保留于该批次 `evidence/`，不能把某一模式或事件通过解读为全部反向事件完成。

`fleet-cross-customer-test-env.mjs` 是最小两客户同一排车主单的串行 TEST 专项入口，默认 `--plan` 零网络。显式运行参数为 `--execute --environment TEST --run-id <新批次> --warehouse-id <实际海外收货仓ID> --destination-warehouse-id <FBA目的仓ID>`，凭据仅从显式 `node --env-file="<TEST配置>" --env-file="<Jenkins配置>"` 与 `FBA_CORE_JENKINS_AGENT` 提供。通过普通转运来货、PDA实收和客户确认创建两个新客户各一托一箱，真实来源一次Create到同一主单，自动唯一Fleet记录、配置资源并完成两审；一客户未核平时验证整车装车/发车拒绝及完整库存快照不变，全量实拣后按真实测量显式装车、平台逐客户目的地安排，再统一发车、原键重放、逐客户签收，最后正式结案并分别释放车辆/司机，核对结案前后库存零变化。完整库存由只读取证器获取，缺实测不补计划值，不写业务SQL，不部署或改共享配置。报告位于 `reports/fleet-cross-<新批次>/`，每次请求发送前记录意图；失败保留原现场，不自动重跑或续跑，已存在批次拒绝覆盖。finally停用本轮PDA并退出独立会话；业务样本保留。前置拒绝不代表事务中途回滚，后者另验。对应入口保护合同为 `fleet-cross-customer-test-env.test.mjs`；内部生成与验收函数见模块README。

头程订单提交使用首次原始详情的 `expectedVersion` 与原 `Idempotency-Key`。单票验收的 `SUBMIT_INTENT` 必须先持久化 `submitCommand` 再发送，显式续跑不得使用当前版本替换原命令，缺少原命令的提交意图及后续检查点停止并等待人工核对。源 Excel 造数同样在提交前保存订单条目的 `submitCommand`；中断或失败条目保留原检查点且不自动重跑，不重建订单或换版本继续。

## 验收证据校验

`fleet-trip-rollback-test-env.mjs` 是跨客户同一原生主单发车中途回滚的串行TEST入口，默认`--plan`零网络；实际参数沿用`--execute --environment TEST --run-id <新批次> --warehouse-id <实际海外仓ID> --destination-warehouse-id <FBA目的仓ID>`，凭据只通过显式TEST/Jenkins环境文件及`FBA_CORE_JENKINS_AGENT`提供。复用正式两客户一托一箱普通转仓来货/实收、同主单两审/实拣/实测装车及平台安排链；按Java客户字符串顺序，通过原业务号只读解析当前主单、客户子单及真实转仓来源，第二客户转仓行建立65秒SELECT FOR UPDATE租约，等待事务自身的50秒会话锁超时使原整车发车失败。不修改业务行、Schema、共享参数或镜像；GLOBAL超时或HTTP超时不能代替会话与事务证据。等待图须精确对应原发车事务、目标转仓主键及实际UPDATE，同时独立READ UNCOMMITTED观察已写的第一客户子单、来源计数及历史；此时主单仍AFTER_LOADING、Fleet为PLANNED、尚无DEPART命令结果，不能沿用旧DEPARTED/重放表断言。最终新已提交读按实际Schema全字段比较相关主/子单、来源历史、占用、命令账本及已提交扫码/SHIP事实，脏读仅作中途证明。租约自动ROLLBACK，核对原事务和等待均已消失，再用同一原发车键/载荷完成正式发车、重放、逐客户签收和资源释放。报告沿`reports/fleet-cross-<新批次>/`，额外`rollback.json`、源码SHA与镜像身份保留；权限、字段、会话超时或任一证据缺失明确阻断，失败保留原现场，不自动重造或续跑，finally仅清理自有PDA/会话。执行需要对应TEST数据库取证、持锁及真实HTTP的明确授权，共享窗口禁止并行发布或操作相同库存。对应`fleet-trip-rollback-test-env.test.mjs`验证证据反例和范围；通用跨客户入口不默认故障注入。

`fleet-test-env-acceptance.mjs` 是显式 TEST 车辆专项入口，默认 `--plan` 仅输出计划；使用显式外部 TEST 与 Jenkins 配置后，以 `--execute --environment TEST --run-id <新批次>` 串行创建本轮头程/海外来源并验证原费用全覆盖、取消重排后的部分覆盖、外接承运占位、PDA真实收货、外接排车计费、逐客户PDA拣货、整车发车、逐目的地签收及资源释放。报告在 `reports/fleet-<run-id>/`；目录和锁独占，失败保留原请求/资源，不自动续跑或重造。会通过正式HTTP写入测试资源和取消未执行单据；既有收货取证使用Jenkins只读查询，不执行业务SQL写入、部署或共享配置修改。Finance费用池消费事实与生产者ACK分开记录；UI及未实现车辆产品范围另验。对应离线入口合同为 `fleet-test-env-acceptance.test.mjs`，内部助手详见模块README。

整车回滚专项的完整快照覆盖当前23表，包括本批真实实托的`ll_physical_pallet_guard`永久串行行；按实际Schema全列及COUNT取证，中途和回滚后均核对原主键与首次创建时间不变，不把删除重建串行点视作成功回滚。此取证范围仅限该回滚专项，不扩展通用车辆入口的故障注入。

该入口用 `--scenario handover` 验证整车在途交接及经营成本；`--scenario return-redispatch` 验证实际退回入库后的重派和逐来源完成，默认要求全新批次；仅下述精确候选失败检查点允许显式恢复原样本。`--output reports/<新目录>` 指定独占报告目录，已有目录禁止覆盖。所有写请求发送前保存业务载荷、版本和幂等依据；网络失败、5xx、缺少关联信息或不符合正式响应契约时立即停止，保留原请求，不自动重发。

经审阅的已发车样本可显式提供 `--resume-report reports/<原目录>/report.json --resume-stage <阶段> --resume-sha256 <原报告SHA256>`，同时使用新的 `--run-id` 和输出目录。`DEPARTED_BEFORE_COSTS` 只接受尚未登记成本、交接和签收的已知只读成本断言失败；现场再次核对原车次版本、唯一 DEPART、实货及空成本/交接和未签收状态后，新建受限成本/PDA会话，继续成本、交接、签收与资源释放。`DEPARTED_AFTER_COSTS_BEFORE_HANDOVER` 只接受成本已验证、交接仍仅只读的已知断言失败；重新核对已登记成本完整原快照及原车次事实，只新建 PDA 会话，保留成本并从交接继续。两阶段均保留原 DEPART，不再拣货、发车或重复先前已确认的业务命令；未知结果和已发生交接/签收的报告不属于此恢复范围。多目的地不能使用同路线自动分摊时，整趟成本按原币核对，来源分摊明确记录为 `UNAVAILABLE`。恢复必须另获当前执行放行，不由脚本自动启动。

`return-redispatch` 在新重派签收前必须等待来源事件只读审计：原余货已签、B 已完成、A 的 2 箱尚未重派签收时，入口持久保存 `before-redispatch-signature.json` 并打印 `FLEET_SIGNATURE_AUDIT_WAITING`，最多等待 20 分钟。总控先核对现场 A 完成事件数为 0、B 为 1，再在同一报告目录提供 `approve-before-redispatch-signature.json`；文件必须含当前 checkpoint 的 `gateNonce`、`marker`、`newTripNo`、`sourceAEventCount:0`、`sourceBEventCount:1`、`auditEvidencePath` 和 `auditEvidenceSha256`，且证据文件须位于仓库 `reports/` 内、哈希相符。签收在此之前不会发送；缺失、超时或证据不符即停止，不自动续跑。新签收及同键重放后，另查 A/B 各一条来源完成事件及 Firstleg 精确 ACK，最终快照不能代替前签时点证据。

`RETURN_SOURCE_SELECTION_BEFORE_RETURN` 仅用于 `--scenario return-redispatch` 的明确候选选择失败：原样本已完成唯一 DEPART、交接和成本验证，三张原派送均已通过明确成功响应进入 `DELIVERING`，退回助手只执行了候选 GET 和这三次开始派送，尚未标记退回、建立异常、创建新出库或签收。必须提供原报告精确 `--resume-sha256`，现场复查完整原 DEPART、交接和成本快照、当前车辆/司机身份版本及占用、三单状态版本和修复后的完整 A/B 候选。预检通过后仅新建绑定原仓的 PDA 会话，从原车次退回复查继续，保留原成本/发车/交接，不再次开始派送。前签来源审计闸口仍必须由总控解除；任何先前写入结果不明或现场变化均拒绝恢复，不自动重造。

`DEPARTED_VEHICLE_CREATED` 是独立的显式恢复阶段：只接受已验证成本、唯一接替车辆创建 POST 明确成功、随后仅因车牌大小写断言停止的报告。执行前核对精确报告 SHA、原成功响应、车辆完整当前快照，并通过 Jenkins 一致性只读查询确认该车辆在 `ll_fleet_resource_assignment` 中没有占用；缺少证据、车辆变更或占用均停止。已创建车辆显式传给交接助手，跳过原车辆创建 POST，从新司机及证照继续；原成本和 DEPART 保留。该成功写入不能借用只读失败恢复阶段忽略，也不得自动重发。

`order-submit-dependency-fault-executor.mjs` 是显式 TEST 下单依赖故障入口，内部使用 `order-submit-dependency-fault-proxy.py`、`order-submit-dependency-fault-runtime.py`。`plan --plan <文件>` 只读校验；`preflight --plan <文件> --routing <文件> --confirm-test-runtime yes` 核对测试 Order 镜像、实际依赖和 Nacos v3 配置（固定v3登录与Admin配置读取、校验namespaceId/groupName/dataId后仅记录内容摘要，不回退v1）；`run` 另需 `--expected-image <镜像ID>`、全新 `--report <文件>`。凭据仅从明确指定的 TEST 与 Jenkins 环境文件读取，路由文件不得包含凭据。必须事先准备本轮两个独立合法草稿、原始版本与幂等键及完整快照；仅对本轮客户的 IAM 资格、Finance 钱包及两张草稿共同引用的公共收货仓 GET 注入短时故障；Warehouse 阶段还限定原请求 ID、Order 来源与内部身份，不影响其他客户对同仓的读取。验证三依赖、两端共六次提交失败后事实不变。运行会临时重建同镜像 Order 容器并在恢复后真实提交草稿，因此不得与部署或其他共享环境造数并行；不写业务 SQL。结束先恢复直通、原镜像配置、健康与依赖读取；业务恢复必须等实际唯一入库单的SUBMITTED投影收敛，不能以连续空结果认定完成，随后按原版本原键重放并核对完整快照，再停止代理；失败保留报告和受限恢复文件，不自动重跑或删除数据。结果未知时使用 `status`、`reconcile` 核对原操作，必要时显式 `restore --plan <文件> --report <新文件> --confirm-test-runtime yes`，不得因观察超时重复创建容器。离线合同为对应 proxy/executor `.test.mjs`，离线通过不代表真实故障注入已验收。

`fba-core-regression-test-env.mjs` 为显式 TEST 的 F40 三模式串行 HTTP 专项，默认 `--plan` 只显示计划；`--execute --environment TEST --run-id <新批次>` 执行根先签、子先签、根签收后余量取消。`--tax-mode` 只接受 `BUY_DECLARATION` 或 `TAX_REFUND`，省略时保持买单默认语义。显式 `--tax-mode TAX_REFUND` 将税制传给现有 `context.f40TaxMode`，三种签收顺序均复用正式 F40 依赖编排及退税内部模块，走资料上传、回执确认、正式申报与人工放行、完成文件、尾程签收，并在最终 `COMPLETED` 后验证客户报关资料读取和文件下载；不复制报关流程。计划、manifest、汇总、各模式报告和只读取证日志均标明税制及范围。会通过正式 API 创建客户、单据、文件并使用共享 PDA/托盘，临时 PDA 按原模块 finally 停用。`fba-core-regression-evidence.mjs` 是内部只读取证 helper，Jenkins scriptText 仅在明确 TEST 节点对 TEST 容器所用数据库执行一致性只读 SELECT，不触发部署、不写业务 SQL。凭据通过显式 `node --env-file="<TEST配置>" --env-file="<Jenkins配置>"` 提供，数据库凭据只在执行节点内存读取。

该入口必需 `CHONGCHONG_ADMIN_API_BASE_URL/USERNAME/PASSWORD`（账号实际键为 `CHONGCHONG_ADMIN_USERNAME` 与 `CHONGCHONG_ADMIN_PASSWORD`）、`ADMIN_PDA_USERNAME/PASSWORD`、`FBA_CORE_TEST_GATEWAY_ORIGIN`、`JENKINS_URL/USER/API_TOKEN` 和 `FBA_CORE_JENKINS_AGENT`；TEST origin 与取证节点必须由操作者显式核准。可选客户账号密码成对提供，仍由正式链生成本轮测试客户。报告保存在 `reports/fba-core-<run-id>/`，包括三模式报告、每次读取的独立证据及汇总；失败即停，不启动后续模式。文件和目录独占创建，不覆盖旧证据、不自动删数据或续跑；中断锁须核查原进程和现场后再处理。本专项不代表全部 F01–F40、页面或反向事件重复投递验收。

离线退税计划：`node scripts/fba-core-regression-test-env.mjs --plan --environment TEST --run-id <退税新批次> --tax-mode TAX_REFUND`；执行退税：`node --env-file="<TEST配置>" --env-file="<Jenkins配置>" scripts/fba-core-regression-test-env.mjs --execute --environment TEST --run-id <退税新批次> --tax-mode TAX_REFUND`。买单计划或执行省略 `--tax-mode`，或明确传 `BUY_DECLARATION`。不同税制使用各自新批次，目录防覆盖及失败即停规则相同。合同：`node --test scripts/fba-core-regression-test-env.test.mjs`。任何计划或离线合同通过均不代表三种退税顺序已在环境运行通过。

`acceptance-evidence-audit.mjs` 是本地只读证据检查入口，不连接环境、不需要凭据、不执行部署或数据库写入。`audit <manifest.json> <new-output.json>` 按经过评审的需求清单逐项核对报告文件 SHA-256、业务域、证据级别、部署版本、运行标记、精确检查名称和 requirementId；HTTP/浏览器证据还须关联 requestId。失败、跳过、缺证据或矛盾结论均不能判完成。输出文件必须不存在，重跑使用新路径；保留旧证据、不自动清理。文件路径相对 manifest 所在目录。

Manifest 使用 `version:1, scope, revision, requirements:[{id,domain,level,checks,evidence:{path,sha256}}]`；报告使用相同 `revision`、`domain`、`level`（unit/contract/http/browser/device）、`runId`、`success` 与 `steps:[{name,requirementId,passed,requestId,marker}]`。需求清单应来自当前文档，不能按已有绿灯缩小清单。此检查只验证证据完整性和声明的一致性，不能自动证明业务断言语义正确，也不允许把旧报告批量加标签后冒充新运行。传统报告用 `check-legacy <report.json> <new-output.json>` 检出相互冲突的完成字段；通过此模式仅代表无已识别字段矛盾，不代表业务验收通过。

离线回归：`node --test scripts/acceptance-evidence-audit.test.mjs`。命令失败返回1，参数/文件错误返回2；报告写入调用者指定的新路径。

`event-delivery-fault-proxy.py` 是 TEST 环境定向事件 ACK 丢失工具，不创建或重放事件。运行者显式传入 `--upstream` 完整消费者地址、`--event-type`，并只选 `--event-id`、`--loading-plan-id`、`--container-booking-id` 或 `--delivery-id`；派送选择器只读取正式 `payload.deliveryOrderId`，不接受 `deliveryId` 载荷别名；柜次选择精确匹配 payload.sourceContainerBookingId，用于海外卸柜回写，不接受混合选择条件。`EVENT_FAULT_CONTROL_TOKEN` 从外部环境注入，保护固定本机监听的控制端口。默认 PASS；经鉴权切为 FAULT 后，仅在选定事件已真实转发且收到匹配的 APPLIED/DUPLICATE ACK 时向发送方返回 503，其他事件直通。同一选择范围内锁定首个事件后不改选其他事件 ID，原 ID 改摘要或载荷直接拒绝。日志只保留事件标识、摘要和结果，不保留正文或凭据。它会影响实际投递，仅限明确授权的测试环境；生产者配置、重试、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-20261008.sql`：2026-09-21 至 2026-10-08 近期结构增量单文件汇总，显式指向 `baiyue_iam`、`baiyue_firstleg`、`baiyue_lastleg`、`baiyue_lastlag_warehouse`；包括 PDA 仓绑定、FBA 报价、墨家测量、换标普通索引、A0 标记、报关两文件、退货签收/箱级出库/箱唛总文件/合箱预占与追溯。用于已有基线业务库，MySQL 8.0.16+；逐列和逐索引判断，可重复执行，两个退货 CHECK 在单条 ALTER 中原子替换。无 SOURCE 依赖、凭据、业务 DML 或清理；操作者自行选择目标连接后将整个文件作为 SQL 脚本执行（不使用 --force），DDL 报错停止，核对末尾 READY/CHECK_REQUIRED 和各段结果。报告由 SQL 客户端日志保存，失败保留已成功 DDL，修复原因后可重跑；不自动连接或执行，不替代正式区域初始化入口。

`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` 是经明确授权的TEST留存混柜出库续跑入口，参数为`source-report containerNo MIXED-FBA|MIXED-DROPSHIP output-report`；显式环境文件使用统一Gateway/Auth，拒绝其他环境。FBA分支仅从本次报告中真实收货的客户、仓、来源和marker创建原生排车，顺序为两级审核、PDA实拣、真实测量装车、平台全车派送安排、当前主单版本发车、POD和资源结案。续跑须保留来源报告SHA、本轮marker、原Create载荷及原生CommandResult/Detail，旧报告或裸排车号不能证明来源；没有实测托位时明确阻断，不使用计划常量。一件代发仍为专用两托四箱出库及PDA幂等拣货/完成，明确派送未覆盖且不返回全流程成功退出码。写前原子落盘，结果未知停止，不换键或删除报告重跑；finally停用临时账号，保留业务资源。离线合同`native-retained-outbound-contract.test.mjs`覆盖两个留存入口，导入无网络；不能代替真实HTTP或PDA验收。

全量验收只认测试环境 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\chongchong-global-test-acceptance.env" scripts/prod-release-acceptance.mjs preflight`：获得当次目标环境 HTTP 授权后运行；登录既有四个账号并查询客户、义乌/东莞/洛杉矶仓、PDA 绑定及义乌资源。不创建业务数据、主档或账号，不删除数据；登录本身会创建会话及审计记录。
- 必填 `CHONGCHONG_ENV=test` 或 `gray`；`CHONGCHONG_ADMIN_API_BASE_URL` 与 `CHONGCHONG_MERCHANT_API_BASE_URL` 必须完全指向同一 HTTPS `/api` 统一入口。拒绝 `prod/dev` 及旧 `CHONGCHONG_ADMIN_OVERSEAS_API_BASE_URL`、`CHONGCHONG_MERCHANT_OVERSEAS_API_BASE_URL` 配置（即使值与统一入口相同也必须移除）。所有业务及文件上传只使用登录返回的 `accessToken`，不读取海外 Token。灰度由运行者显式选择外部灰度配置，不自动读取、修改或回退环境文件。
- 客户必须为 `ACTIVE` 且箱规初始化为 `READY`；`PROFILE_REQUIRED` 等状态阻断，不自动完善资料或审核客户。客户锁定配置：`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-single-order [--resume]`：须另获当次目标环境写入授权。自动执行基本前置检查，额外校验指定客户可选的唯一渠道/包税维度与 1～2 箱实际重量、体积报价，然后创建一票、提交、审核；不创建图片、地址、托盘或库位。仅支持 AUTO 入仓码、普通海运 FBA 自送散货、单 SKU 非木制非危险品；目的 FBA 仓显式指定，洛杉矶是后续接柜仓，不是第二票。输入与检查点放仓库外，同一批次始终使用同一检查点文件，禁止并发另开路径或换批次重试。
- 尾程签收入口 `delivery-stage <尾程事实输入.json> <独立签收检查点.json> --confirm-single-delivery`：须另获当次目标环境写入授权。脚本只接受本批次已核对的排车、出库、派送和尾程订单身份；按状态版本推进 `DELIVERING`，上传验收用签收文件并保存资料，回查 `DELIVERED`、国内入仓 `DELIVERED` 和头程订单 `COMPLETED`。上传或状态写入结果不确定时停止；托盘明细或尾程子状态未同步会记录为阻断项。
- `prod-release-order-stage.mjs` 是上述入口使用的内部订单阶段与检查点实现，不可直接执行。先落盘并同步意图，再调用 HTTP；检查点绑定环境模式及统一 API 地址、客户、操作者、批次和载荷摘要，不保存密码/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 和商品申报字段由本次验收资料提供，箱规/含箱总重/总体积由上述固定口径统一计算，不生成资质或物流签收证明。箱数×每箱数量必须等于总件数，箱规×箱数必须等于总体积。
- 完整正常链：`full-flow <外部订单输入.json> <独立全流程检查点.json> --confirm-single-full-flow [--resume]`。仅支持 `BUY_DECLARATION` 买单报关、单 SKU、1～2 箱、义乌起运及洛杉矶接柜的 FBA 正常链。先用现有客户下单审核，再测量/费用确认、订舱/分柜、国内 PDA 装柜、买单报关、人工船节点、目的港提柜预约、海外 PDA 收货/还空柜、排车/派送、车次调度/拣货/发车、签收回传及车次结案释放资源。任何HTTP或归属/数量门禁失败都停止，保留同票检查点，不新建订单代替失败。
- 全流程内部模块：`prod-release-full-flow.mjs` 负责单票阶段编排和独立子检查点；`prod-release-http.mjs` 负责统一 Gateway、写前请求摘要落盘、失败诊断、合成文件上传及独立登录会话退出；`prod-release-domestic-stage.mjs` 负责国内正常链；`prod-release-overseas-stage.mjs` 负责海外正常链和签收后车次结案。这些文件没有独立CLI，不运行全量fixture，不创建账号、客户、车辆、司机、供应商等主档。正常业务会创建本票货柜、订舱、作业托盘、排车、车次、派送及费用记录。
- 完整输入还需 `domestic: {palletId, assigneeId, bookingAgent:{id,name}, carrier:{id,name,carrierCode}, terminalFleet:{id,name}, estimatedSailingAt, estimatedArrivalAt}` 和 `resources:{vehicleId,driverId,carrierName}`，均引用既有启用且有资格的资源。订单级及货物行都必须明确提供 `shipmentId/referenceId`；不能只填货物行。报告/输入/检查点使用仓库外私有路径；公开交付仅保留脱敏结果、业务号及诊断编号。
- 实际装载缺少托位等实测值时，在首次输入中预先指定 `loadingMeasurementFile` 私有绝对路径；该路径随完整输入指纹冻结，文件可在本票扫码核平后补齐，再以同一输入和检查点 `--resume`。文件为 JSON：`{environment:"TEST"|"GRAY",batch,dispatchNo,pallets:[{warehousePalletId,palletSpaces,weightKg,volumeCbm,deliveryIndex,evidence:[{field,actual:true,sourceType,sourceBusinessNo,observedAt,value}]}]}`，环境须与本次入口一致，三项测量各有实际来源、时间和值，实托和路线须匹配当前装载预览。缺失、格式错误或归属不符停止装车，不从计划或计费常量补值。装车意图前保存原文件 SHA、回执和最终测量；成功命令恢复原请求，结果未知停写，不用修改文件触发重发。内部直接调用的 `loadingMeasurements` 与文件输入互斥。
- 全流程报告只有全部正常链及签收回传、资源释放核对成功才输出 `SINGLE_ORDER_HTTP_COMPLETED` 与 `fullFlowVerified:true`，其范围仅为 `ONE_ORDER_NORMAL_HTTP_PATH`。测量、资质、装柜、卸柜和签收文件均明确为合成验收材料，不代表真实物流证据；不覆盖退税报关、多客户/拆单/异常、故障注入、真实支付、第三方下单、邮件、浏览器及设备验收。阶段检查点已完成命令复用原结果，未知写入意图必须人工核对，不能自动重发。
- 离线验证：`node --test scripts/prod-release-acceptance.test.mjs scripts/prod-release-order-stage.test.mjs scripts/prod-release-delivery-stage.test.mjs scripts/prod-release-measurement-plan.test.mjs scripts/prod-release-http.test.mjs scripts/prod-release-domestic-stage.test.mjs scripts/prod-release-overseas-stage.test.mjs scripts/script-documentation-contract.test.mjs`。一票主链不覆盖多客户混柜、退货异常、真实付款、外部下单、邮件发送或页面交互。最终输出单独报告 `sessionCleanup`，会话退出不受业务请求次数上限影响。

订单阶段与恢复验证：`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-single-order
# 中断后保持相同输入、账号和检查点；不要删除检查点或换批次。
node --env-file="<明确目标环境配置.env>" scripts/prod-release-acceptance.mjs order-stage "<外部订单输入.json>" "<本批次检查点.json>" --confirm-single-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 作业员用于领取与执行；缺少作业员凭据在启动前阻断，不能以管理员身份代替已分配的作业员。

默认全量、海外收货及人工状态矩阵还需显式注入 `JENKINS_URL/JENKINS_USER/JENKINS_API_TOKEN/FBA_CORE_JENKINS_AGENT`。总入口使用 `fba-core-regression-evidence.mjs`，在业务写入前预检 TEST 节点上 Order/Lastleg 容器与只读数据库连接；将收货完整快照和根/子完成 Outbox 计数接入本轮上下文。凭据不写入报告，不执行业务 SQL 写入；连接或取证失败继续阻断，不能使用旧报告代替当前快照。

脚本只读取当前 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、管理员或客户账号变量。外部文件必须保留在仓库之外，不得复制到项目目录、报告或提交记录。

### 灰度环境 FBA 定向闭环

同一入口可显式添加 `--prepare-domestic-pda-h5 true`，仅允许单独指定 `phase5-root-fulfillment`：创建本轮客户和两箱根订单，经测量、分柜、订舱放舱和计划确认生成一箱待拣任务及箱唛后停止，不领取/拣货/完成任务、不进入海外链。报告标记 `fullAcceptance=false`、`PREPARED_NOT_VERIFIED`，`createdResources.phase5RootFulfillment.domesticPdaH5Fixture` 保存任务、柜次、计划、仓库、入仓来源及箱信息供 H5；成功只代表准备完成。样本保留，失败不自动重试或清理，默认不传该参数时继续完整链。


`admin-test-env-acceptance.mjs --environment gray` 显式支持临时灰度环境，当前仅开放 `--modules phase5-root-fulfillment` 及自动展开的本轮客户资质 fixture。该链会通过正式 HTTP 新建隔离客户、两箱根订单及分柜子来源，推进国内测量、装柜、报关、人工船节点、海外收货、排车、出库和签收；不是默认全量验收。默认全量中包含 TEST 专用故障注入和未经灰度副作用核对的模块，因此 gray 拒绝省略模块、附加模块、批量订单和卸柜故障开关，也不会创建 TEST fault executor。`--f40-tax-mode TAX_REFUND` 覆盖退税文件确认链；真实邮件和供应商自动查询不在此闭环的完成声明中。

明确的仓库外环境文件须配置 `ADMIN_GRAY_GATEWAY`（统一 HTTPS 源站，不带 `/api`）、`ADMIN_GRAY_USERNAME`、`ADMIN_GRAY_PASSWORD`、`ADMIN_GRAY_PDA_USERNAME`、`ADMIN_GRAY_PDA_PASSWORD`；可选 `ADMIN_GRAY_CUSTOMER_NAME`。gray 不读取 TEST Gateway、管理员或 PDA 凭据。F40 始终创建本轮客户，不需要传已有 merchant 账号。数据库只读取证使用 `JENKINS_URL`、`JENKINS_USER`、`JENKINS_API_TOKEN` 及 Jenkins 已登记的 production SSH/host/known-hosts/env 凭据，由 `gray-regression-evidence.mjs` 实现，不调用 TEST agent 或写业务 SQL。

运行前核对国内 PDA 绑定仓与 `--origin-warehouse-name` 一致，且目标环境已有有效渠道报价、订舱代理、库位/托盘及业务月份 ACTIVE 的 USD→CNY 月度汇率。汇率归 Lastleg `master-data/exchange-rates`，只读月份筛选为 `monthFrom`/`monthTo`；缺少时派送费用发布会被明确拒绝，脚本不自行沿用上月或修改共享汇率。海外 PDA 则从本轮两柜实际尾程来源解析唯一接柜仓，不按仓库列表顺序选择。

```powershell
node --env-file="<仓库外灰度验收环境文件>" scripts/admin-test-env-acceptance.mjs --environment gray --modules phase5-root-fulfillment --f40-tax-mode TAX_REFUND --origin-warehouse-name "<PDA实际绑定国内仓名>" --output "reports/<新批次>/gray-fba-flow.json"
```

运行前须具备该灰度环境写入授权、所选仓的 PDA 账号、正式主档和有效价格簿；只读取证预检失败时不进入业务写入。报告显式标注 gray、使用 `GRAY-API-` 资源标记，并列出未覆盖范围。失败保留本轮资源和原始报告，不自动重放未知结果、不删样本、不重置数据库；先核对失败阶段再决定续跑，新运行使用独立报告路径和新样本。本链通过不代表默认全量、页面视觉或外部供应商已验收。

## 脚本目录归属

脚本按作用域放置，不要求全部集中到根 `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/**` 不是散落或放错目录；它们靠近所属部署单元或运行组件。仓库检索到的可执行脚本如果既不在上述目录，也没有在本表登记，应视为脚本归属缺失。

## 仓库级入口清单

排车扩展入口还支持独立新批次 `--scenario reviews`，真实覆盖两级驳回重提、零扫码退回改货改车及旧版本/幂等冲突，再接完整履约。`--scenario review-terminal --resume-report <本扩展原失败报告> --resume-report-sha256 <原SHA>` 只接收已完成双签收、请求全部明确RESPONSE、审核包VERIFIED但顺序只读快照跨过异步完成版本的精确停点；新报告先只读核齐原单DELIVERED及全量库存，再仅结案释放本批资源，不重拣、重发、重签或覆盖旧失败。其他未知写和原人工单不接受此模式。

`dispatch-workflow-extensions-test-env.mjs` 是排车扩展 TEST HTTP 串行入口，默认 `--plan` 零网络。显式执行使用 `--execute --environment TEST --scenario dual-destination --run-id <新批次> --warehouse-id <实际海外仓> --destination-warehouse-id <首个FBA仓> --pda-env-file <现有海外PDA私有配置> --synthetic-pallet-spaces 1`；TEST及只读取证凭据由调用者在脚本前显式 `node --env-file=<TEST配置>` 加载。正式目录找到第二个同国有效FBA仓后才造新客户和货物，验证双目的仓、独立费用/单据/库存与完整履约。现有PDA只开新会话、不创建停用账号；托位、费用、附件标记TEST合成，重量体积必须来自正式测量证据，不代表现场或硬件。原人工单不参与新造数。报告 `reports/fleet-cross-<run-id>/` 与独占intent存在即拒绝重入；未知写保留原键载荷并停写。只复用受保护库存读者，不新增SQL、部署、改权限或清理数据；退出自有会话、保留业务样本。未就绪矩阵保持未执行；直接合同为 `admin-test-env-modules/dispatch-workflow-extension-contract.test.mjs`。

`--scenario competition` 同样仅使用本轮新样本，验证占用中的车辆/司机拒绝第二张空排车、装车后尚未安排派送的发车拒绝，以及已成功装车原键的两个 Admin/PDA 请求并发重放；原操作员恢复唯一结果，另一操作员被拒绝，完整库存与主单事实不变。该场景不宣称首次有效命令竞争或完整权限矩阵通过。第二次签收确定成功后增加最多30秒只读完结等待，再进入既有跨接口一致性快照；不重放签收写入，也不修改既有失败报告或共享验证器。

`--scenario first-competition` 在真实整车拣货核平后，以同一当前版本、两个不同请求键同时提交一次Admin/PDA首次装车命令；只允许一方成功、另一方版本冲突，整车只增加一个版本，完整库存不变。真实PDA回执原样返回；若Admin胜出，保留胜者回执及PDA拒绝，停止既有PDA正常链，不冒充PDA成功、不重复装车或发运。PDA胜出时继续正常履约、原键双端竞争重放与结案。

`--scenario relabel` 在本轮双客户正常履约后，另建独立客户并以正式仓储转运/PDA实收三箱；三份箱唛换标由客户确认，两份TRUCK合入同一新实托，一份PICKUP自动建独立出库。核验零扫码取消PICKUP出库保留原确认成果与完整库存；两TRUCK来源按服务器完整selectionGroup建同车，2箱只算1实托，零扫码撤销后重新正式建车，再撤销本轮未执行安排。PICKUP取消后保持待独立安排，缺公开再次安排入口时明确未验证，不改成TRUCK或重做完工确认。所有成功开出的客户会话在finally退出；若换标检查失败且没有未知写，已完成的正常车次仍正式结案释放资源，原失败证据保留。

`--scenario relabel-shared --resume-report <原报告> --resume-report-sha256 <冻结哈希>` 仅继续本轮三份均已确认、PICKUP取消VERIFIED、尚无任何共享建单请求且正常车次已结案的换标候选读取失败检查点。核对当前原始库存及三申请确认成果不变后，按精确换标业务号读取候选，仍要求完整selectionGroup闭包；只首次建共享运输安排，不重建客户/实收/换标，不重复取消PICKUP，不重复正常履约或资源释放。任何未知写阻断此入口；原报告保持失败。

`--scenario bol-empty|bol-same|bol-different --pdf-python <已安装pypdf的Python绝对路径>` 分别创建同目的仓无预约号、同号、不同号的两客户新样本。预约场景通过原有来源预约入口登记明确标记TEST的确认资料及1箱真实份额，再按返回的batchKey/version/来源归属关联原生排车；不借旧预约，不新增日历功能。实际BOL PDF、独立只读二进制请求账本和提取文字保存在该批 `evidence/`；核对跨客户合并/分组、各托只打印一次、总计2箱、打印前后完整库存不变，再继续正常履约结案。JSON请求计数不含独立二进制GET，二者分别留证；不把文字检查作为视觉验收。

BOL长托盘码按现行模板省略，自动核验使用完整入仓码与本轮一箱一托来源映射守恒，不声称PDF完整展示托盘码。若本轮在该显示断言处停止且尚未开始履约，可显式传原 `--resume-report` 和 `--resume-report-sha256` 到同一BOL场景、新runId；仅接受原READY夹具、精确已知错误、全部请求确定回执及无履约命令的冻结检查点。保留原失败，重新打印并核对当前状态后首次推进履约，不重建预约/排车，不允许未知写重试。

下表覆盖 `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 入库、测量、费用和权限专项；写测试数据 |

`client-phase2-measurement-evidence.mjs` 为该专项内部取证助手，核对平台已冻结的 calculatedOuter 尺寸、体积和客户发布的计费外尺寸及规则快照；不使用当前客户配置重算历史快照。对应 `client-phase2-measurement-evidence.test.mjs`，没有独立 CLI。新样本先沿 Admin `inbound-fees` 依赖链准备，再用专项的 `--order-id` 指定本轮订单；保留原失败报告。
| 测试环境 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` | 会创建测试企业、订单、权限和站内消息数据，并保留 Excel 源文件及错误报告 | 注册/审核、企业与个人资料、客户隔离、订单、文件、客户侧权限、消息已读与账号安全；Merchant 草稿编辑/取消使用冻结版本与幂等命令，拒绝及重放核对完整订单快照；实际中文 XLSX 验证 PARTIAL、ATOMIC 中途冲突回滚及原键恢复重试，JSON 批量草稿不能替代此项。未完成注册的同凭据重放须复用账号/客户/成员身份，不同凭据重复用户名须冲突；测量/计费继续使用下列专项入口 |
| 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`：仅显式 TEST 的统一 Gateway/Auth 换标生产者，会创建换标、库存及原生排车记录；平台/PDA及可选客户登录凭据由显式环境文件提供，缺客户凭据时通过正式临时登录票据，票据和 Token 只留内存。运行前必须指定 `OVERSEAS_TEST_CUSTOMER_ID`、`OVERSEAS_TEST_WAREHOUSE_ID`、`OVERSEAS_RELABEL_SOURCE_BALANCE_ID`、`OVERSEAS_RELABEL_SOURCE_POSITION_ID`，可用 `OVERSEAS_RELABEL_SOURCE_INBOUND_CODE` 进一步限定本轮来源；不任意借历史库存。`OVERSEAS_RELABEL_MARKER` 可固定批次，报告默认 `reports/overseas-relabel-real-acceptance.json`（`OVERSEAS_ACCEPTANCE_OUTPUT` 覆盖），已有报告禁止覆盖或重造 marker，失败保留原请求和资源，不自动清理、重跑或续跑，执行另需对应环境授权。保留四种换标作业、新旧箱唛、实物归属与扫码/打印重放；原生排车前一次读取本仓完整RELABEL候选，核对服务端selectionGroup、组成版本、全部逻辑来源与实托。NEW-PALLET和MERGE-EXISTING共托时共用一次Create及原键重放，并分别保留换标来源贡献；SPLIT-TWO-TARGETS仍按整申请闭包独立建单。未知成员、缺组、版本漂移或测量冲突必须在首个Create前阻断，不能退回只拒绝所有合托的旧行为。
- 可选 `OVERSEAS_RELABEL_LOADING_EVIDENCE` 指向按场景名索引的私有 JSON 回执，每项明确 `{environment:"TEST",marker,dispatchNo,pallets:[{warehousePalletId,palletSpaces,weightKg,volumeCbm,deliveryIndex,evidence:[{field,actual:true,sourceType,sourceBusinessNo,observedAt,value}]}]}`；当前排车、实托及三个实际测量来源须完全匹配，缺项标记装载证据阻断，不虚构托位。共享组各场景若同时提供回执，必须指向同一排车并具有相同实托测量；整托重量、体积及容量只计一次。`scripts/overseas-relabel-real-contract.test.mjs` 仅离线验证显式来源、四场景证据、完整组共车Create、原键重放、冲突前置阻断及未知写停写，不代表真实作业验收。该入口产出原生排车证明，既有留存消费者仍只继续SPLIT场景，不据此宣称共享组审核、扫码、装车、发车及签收全链已验收。
- 该脚本现按“扫码→组托→完工→客户确认”执行，`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`：显式TEST环境读取`OVERSEAS_ACCEPTANCE_SOURCE`中SPLIT-TWO-TARGETS的本轮原生Create命令、响应/详情及新旧箱唛证明，裸排车号或旧预排报告被拒绝。使用统一Gateway/Auth及与混柜相同的原生审核、扫码、真实装车、平台安排、发车、POD和资源链；缺物理测量不造值，未知写入保留原键停写。报告默认`reports/overseas-relabel-fulfillment-acceptance.json`（`OVERSEAS_FULFILLMENT_OUTPUT`覆盖），来源SHA和原命令必须保留，失败不自动清理。它不接管仅开发环境的current-session包装，亦不替代Admin全量验收。
- `scripts/native-retained-outbound-contract.test.mjs`：仅离线校验上述混柜/换标入口的来源身份、原生命令、写前落盘与未知停写、实载/PDA顺序、SHIP数量、POD和箱唛护栏；不读取环境凭据、不发HTTP、不执行SQL或部署。命令为`node --test scripts/native-retained-outbound-contract.test.mjs`。
- `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`。
# 事件人工重试运维入口

`fba-core-regression-evidence.mjs` 是 Admin/F40 共用的内部只读取证器，不是独立 CLI。只在明确的 TEST Jenkins 节点读取 `firstleg-test-order`、`firstleg-test-lastleg` 对应数据库的一致性只读快照，原始库存、位置、流水及事件身份严格按本轮客户/仓库/柜次过滤。连接凭据只在执行节点内存中处理，不执行 SQL 写入；调用者保存独立报告，失败不能用空结果代替。直接合同为 `fba-core-regression-evidence.test.mjs`，覆盖只读 SQL 边界、完整作用域、长 ID、零事件保留与敏感错误脱敏；离线合同不代替真实数据库取证。

`fleet-inventory-evidence.mjs` 是上述取证器的内部库存查询模块，通过 `createTestEvidenceReaders(...).readFleetInventory({ marker, customerId, warehouseId })` 调用，无独立命令、环境加载或写入能力。对明确客户和仓库读取全部原始余额、位置与所有类型流水，包含零数量、版本和时间；同一只读事务的逐表计数用于拒绝遗漏、截断和重复行，不使用非零汇总代替。每个字段保留为字符串或空值，避免长 ID 精度丢失。调用者保存报告及本轮来源证明，不能用历史客户的探针替代新场景验收。合同为 `fleet-inventory-evidence.test.mjs`。

海外卸柜反向故障验收从 Admin 总入口显式传 `--modules phase4-overseas-pda --verify-unload-event-recovery true`，按正式依赖准备新客户、新柜及实收，首个本轮柜完成前设置独立故障 hook；普通收货默认不启用。目标事件固定为 `OverseasContainerUnloaded`，生产者为 Lastleg，消费者为 Firstleg，事件平台作用域固定 0、库存仍按本轮实际客户隔离。按原事件验证 ACK 丢失、DEAD、人工 retry 与重复确认；在恢复服务配置后，用相同只读库存取证器采集 `AFTER_EVENT_RECOVERY`，核对原始库存、位置、托盘组成、收货完整键及流水零漂移。任一方向恢复失败保留任务恢复记录并判失败；不得与独立部署或共享环境造数并行，不修改业务 SQL。报告沿用显式新 `--output`，旧失败报告和业务样本保留，不自动清理。此项不覆盖签收完成回写、设备和车辆新版链路。

Admin 全量中的 `phase4-cross-region-events` 使用内部 `test-event-fault-executor.mjs` 和 `test-event-fault-runtime.py`，不是额外 CLI 入口。它们仅在显式 `CHONGCHONG_ENV=test` 和已授权环境中运行：在首个本轮计划完成前启动已有 ACK 丢失代理，短暂重建同镜像 Firstleg 容器，保留数据卷、端口和网络身份，只变更事件目标与本次故障退避参数。仅选定的装柜事件被抑制 ACK；其他事件直通。核对 12 次失败、DEAD、受保护原事件 retry、DUPLICATE 及业务订单零新增，结束或失败都恢复原镜像配置并检查健康，随后停止本任务代理。不修改业务 SQL、载荷、事件 ID 或 hash，不重放已发布事件。恢复失败必须保留阻断和任务元数据；独立后端发布或其他环境造数不得与此窗口并行。凭据仅在执行节点内存与权限600的临时恢复文件中使用，恢复完成后移除临时文件中的凭据。离线合同为 `test-event-fault-executor.test.mjs`。

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


`f32-pda-hold-race.mjs` 是显式 TEST 暂扣/PDA拣货并发验收入口，离线合同 `f32-pda-hold-race.test.mjs`。命令为 `node --env-file="<TEST配置>" --env-file="<Jenkins配置>" --env-file="<本轮自有PDA配置>" scripts/f32-pda-hold-race.mjs --plan <冻结计划> --report <全新报告> --confirm-test-runtime yes`；只消费已实际入仓、4箱可用、无占用、调度审核通过且同仓PDA canPick=true的本轮独立样本，不创建订单或车次。凭据只读明确TEST/Jenkins/自有PDA配置，不写报告；计划冻结客户、来源订单、仓、余额、位置、排车明细、车次、PDA成员和不可变Lastleg镜像ID。通过Jenkins在指定TEST Lastleg所用MySQL建立仅针对原订单的12秒行锁租约（SELECT FOR UPDATE、固定等待、ROLLBACK，无业务DML），用performance_schema实际锁等待证明两条正式HTTP命令同时竞争，再按暂扣先到/拣货先到两种顺序验证。会真实暂扣、解除本轮暂扣和拣货1箱，逐位置、库存流水、拣货及来源归属、原键重放分别核对；两个阶段顺序执行，不并发造数。结束恢复自有PDA停用状态并退出认证会话，测试单据、部分拣货和资源保留。命令结果未知或断言失败时保存原报告及逐步checkpoint，不自动重发命令、重建样本、删数据或回填SQL；租约自动释放后先核对原单和原命令，未证实的暂扣恢复必须单独按原事实处理。离线通过不代表实际MySQL/PDA或四端页面通过。

- `db/return-package-packing-boundary-incremental-20261010.sql`：退货包裹/箱出库及标签字段增量，显式选定 baiyue_lastleg 库后写结构；无凭据、无业务造数，可重复执行，失败停止并检查数据库错误。

废弃明细字段专项修复：db/cargo-discard-item-columns-repair-20261014.sql。仅对 MySQL 8.0.16+ 的 baiyue_lastleg 已有 ll_cargo_discard_item 表补齐 10 个新增字段，逐列判断，可重复执行，独立于退货约束。实例和凭据由执行者指定；不写业务数据，不修改库存，不自动访问环境。完整执行、遇错停止，DDL隐式提交，修正错误后可重跑；末尾只读查询应返回10行，由执行者保存结果，无自动清理。

废弃退货箱归零约束修复：db/cargo-discard-return-quantity-repair-20261014.sql。仅 baiyue_lastleg，MySQL 8.0.16+，将箱内SKU数量约束改为非负以支持整箱废弃。实例及凭据由执行者指定；可重复执行，原子替换约束，无业务DML，不连接环境自动执行。整份执行、遇错停止，DDL隐式提交，修正后可重跑；末尾输出表结构供保存核对，不清理业务数据。正式增量为 deploy/sql/migrations/overseas/baiyue_lastleg/V26__allow_zero_return_carton_item_quantity.sql，已纳入废弃汇总脚本。

客户废弃照片确认增量：db/cargo-discard-customer-confirmation-incremental-20261014.sql。MySQL 8.0.16+，目标明确为 baiyue_lastleg 和 baiyue_iam；连接实例与凭据由执行者指定。补齐客户确认时间和独立确认权限，默认客户管理员获得授权，自定义角色需手动分配；授权与受影响管理员的安全版本在同一事务提交，重跑安全版本仍单调递增。完整执行、遇错停止、修正后可重跑；不确认或回填历史单据，不修改库存，不自动访问环境或清理。执行结果由操作者保存，权限更新后需重新登录客户账号。对应正式迁移为 Lastleg V27 和 IAM V6；未执行时页面权限与服务字段尚不可用。

`db/warehouse-transfer-carton-counting-incremental.sql`：仓储转运逐箱测量与清点增量，显式 USE baiyue_lastleg；逐列检查并新增箱子尺寸、重量、实点件数、清点操作人、时间、幂等字段、箱所属转运托盘ID及独立SKU申报件数 declared_quantity，可重复执行，无业务DML、不回填历史事实。适用于明确授权的本地或开发MySQL8，凭据由操作者外部提供；失败保留原错误，修复后重跑，不清理单据。已同步尾程基线和海外统一增量。

`local-warehouse-transfer-carton-acceptance.mjs`：仅本机统一Gateway的仓储转运逐箱验收；命令前显式 `node --env-file=<本地配置文件>`，必须提供 ADMIN_TEST_GATEWAY、ADMIN_TEST_USERNAME/PASSWORD、LOCAL_TRANSFER_PDA_PASSWORD，可选 OVERSEAS_TEST_CUSTOMER_ID、TRANSFER_CARTON_OUTPUT、TRANSFER_KEEP_PDA。复用既有有效客户和海外仓，以业务HTTP创建4笔带批次标识的新单，覆盖单箱、多SKU分箱多托、短收及超收、SKU申报件数与预计箱数独立持久化且PDA实收不覆盖原申报、先生成多托盘再逐箱选择托盘、箱级测量清点及托盘体积重量自动汇总、错误SKU/零件数/缺少差异原因拒绝、幂等重放、箱标签、打托绑定、测试照片和入库完成回查。测试照片为合成PNG，不证明真机拍照或物理打印。创建本轮PDA账号，默认finally停用；仅显式 TRANSFER_KEEP_PDA=true 时保留供本轮页面验收后人工停用。不改主档、不写业务数据库、不删除单据；报告不保存凭据或Token，失败保留已创建单号，排查后用新批次重跑，不自动清库或续跑既有单。


`db/warehouse-transfer-consolidated-incremental-20261015.sql`：仓储转运近期本地增量汇总，固定 `USE baiyue_lastleg`，适用已有 Lastleg 基线的本地/开发 MySQL 8。依次合入 `warehouse-transfer-outbound-incremental.sql` 和 `warehouse-transfer-carton-counting-incremental.sql`，前者已覆盖旧 `dev-warehouse-transfer-pallet-lifecycle-incremental.sql`，无须重复跑旧生命周期补丁。包含审核、打托/照片、换标、目的地/出库/派送结构、实收箱数，以及逐箱尺寸、重量、实点件数、清点幂等、差异原因、箱所属托盘和独立 SKU 申报件数。只执行 DDL/元数据查询，无业务 DML；不回填单据或修改库存。实例和凭据由操作者在数据库客户端外部提供，无内置连接信息或报告文件。需支持 DELIMITER 和 CREATE ROUTINE/ALTER/INDEX 权限，整文件串行执行，遇错停止，不使用 --force；可按缺失结构检查重复执行，不修复任意同名异构旧表。末尾 `missing_carton_and_quantity_columns=0`、`inbound_pallet_unique_index=READY`、`migration_result=WAREHOUSE_TRANSFER_RECENT_SCHEMA_READY` 表示本轮列/索引核对通过；同客户重复托盘号会报告 INDEX_BLOCKED，不擅自更改旧托盘号。仅整理文件不表示目标库已经执行；连接必须由操作者明确选中，不重放 `deploy/sql/海外区域统一增量-MySQL8.sql` 空库基线。

`db/warehouse-transfer-carton-multi-sku-incremental.sql`：固定指向 `baiyue_lastleg`，按列存在性检查新增 `ll_warehouse_transfer_carton.sku_items_json`（JSON），保存同一实收箱的多个预报 SKU 及逐项件数。可重复执行，不更改或回填既有单据；需在启用新版转运清点后端前执行。