baiyue-firstleg/scripts

后端脚本管理与全量 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 报错立即停止。

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 换标回归。

../deploy/scripts/deploy-blue-green-service.sh：受控部署流程调用的单服务蓝绿发布与健康检查入口；只由部署/Jenkins 编排使用，不作为普通验收脚本直接运行。目标服务、环境、镜像和凭据均由外部参数提供，失败按部署脚本回滚规则处理。

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 文件和数据库目标；脚本不会把凭据写入报告或仓库。

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。生产运行示例（只到已审核，执行前确认授权，不代表全链完成）：

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

开发与测试环境的账号、密码和 Gateway 只维护在用户目录的两份外部文件中，不写入仓库：

环境	文件
开发环境	$env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env
测试环境	$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env

两份文件统一提供以下变量：

ADMIN_TEST_GATEWAY
ADMIN_OVERSEAS_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 放在脚本路径之前，明确选择环境：

# 开发环境
node --env-file="$env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env" scripts/admin-test-env-acceptance.mjs

# 测试环境
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	Mapper 门禁后执行受影响后端 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	使用本地 Maven 启动海外 Gateway，并将海外安全投影地址指向本机；会启动本地 Java 进程，不访问或修改共享环境
本地环境	publish-local-nacos-config.ps1	将 config/nacos/local/*.yml 发布到指定本地 Nacos，会修改 Nacos 配置
Nacos 环境选择	use-nacos-environment.ps1	按显式环境与区域设置当前 PowerShell 进程的 Nacos、Spring Profile 和运行区域变量；开发/测试密码必须由参数或环境变量提供，不发布配置
Nacos 配置发布	publish-nacos-config.ps1	将 `config/nacos/{local
密钥配置	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、海外仓和私人地址草稿，并验证无权限请求、单行失败隔离、详情客户归属与同幂等键重放。

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，最后额外验证跨票不串数据。

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。

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 根目录执行：

.\scripts\backend-full-regression.ps1

前端全量回归

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

.\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。

后端脚本固定运行：

mvn -f <仓库根>/pom.xml -pl order,firstleg,iam,gateway,file,warehouse -am test

这会先构建公共依赖，再运行 order、firstleg、iam、gateway、file 与 warehouse 的全部 Maven 测试。覆盖包括：

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

Dry-run

.\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，也不修改任何文件。

.\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 库完整性。

.\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。失败资源保留，续跑会复用同一报告中已创建的目的仓托盘，不自动清理。