baiyue-firstleg/scripts/AGENTS.md

后端脚本管理指引

适用范围与读取顺序

• 本文件适用于后端根 scripts/ 及其子目录；服务自己的 <service>/scripts/ 继续受对应服务 AGENTS.md 约束。
• 先用本文件判断脚本类别，再到 README.md 查询仓库级入口的用途、参数边界和副作用；Admin HTTP 模块继续读 admin-test-env-modules/README.md。
• 不扫描 target/、reports/、.logs/、node_modules/、.codex-*、output/ 或 outputs/ 寻找业务脚本和验收事实。

脚本分类与入口

类别	正式入口	管理边界
Admin 全量 HTTP 验证	admin-test-env-acceptance.mjs	通过显式环境文件运行开发或测试环境；默认模块覆盖平台全链路，定向验证使用 --modules，模块注册和依赖以总入口及 admin-test-env-modules/README.md 为准
Client 全量 HTTP 验证	client-test-env-acceptance.mjs	通过显式环境文件运行开发或测试环境；覆盖客户工作台完整链路，client-phase2-test-env-acceptance.mjs 只是入库测量与计费专项，不替代全量入口
Client 快速下单定向验证	client-quick-order-test-env-acceptance.mjs	使用既有测试客户通过批量草稿接口验证 FBA、海外仓、私人地址、逐行失败和幂等重放；只创建草稿，不提交或审核，不替代 Client 全量入口
待审核订单造数	create-pending-review-orders.mjs	使用已配置客户创建并提交订单，停在待审核；不审核、不推进后续履约
批量待分柜造数	it-test-wait-split-bulk.mjs	固定“IT测试”和“义乌仓”，随机客户可选真实线路并尽力推进到 WAIT_SPLIT；失败记录后继续，不自动删除成功数据；只复用 TP-001/YW-TP-002，不新增托盘或库位，普通位不足落 A0
Admin HTTP 内部模块	admin-test-env-modules/*.mjs	由 Admin 总入口动态加载，除文档明确的独立编排器外不得当作独立全量入口；*contract.test.mjs 只做离线合同
入仓测量与整票库位块专项	admin-test-env-modules/inbound-measurement.mjs、admin-test-env-modules/README.md	仍从 Admin 总入口按 orders,inbound-measurement 依赖链执行；开启 --verify-pallet-location-guide true 后逐张确认回查块扩容只能追加，既有槽身份不得漂移，并验证删除图片后空槽保留与替代图片复用；会写目标环境，必须有对应环境授权
Finance 扩展 HTTP 模块	admin-test-env-modules/firstleg-container-fee-allocation.mjs、finance-direct-paid-isolation.mjs、phase4-overseas-finance-cross-region.mjs	分别验证柜费跨客户分摊、海外仓服务直接已付隔离、五类海外费用跨区入池；必须由 Admin 总入口按已登记依赖运行，使用本轮资源且禁止借历史数据，真实 HTTP 仍须当前轮授权
订舱与拖车服务中心链路	admin-test-env-modules/service-center-flow.mjs	复用本轮 RELEASED 订舱，创建订舱级拖车并验证附件、完整状态链、历史和稳定关联；由 Admin 总入口按依赖运行，会写目标环境
尾程单控制与目的港码头拖车	admin-test-env-modules/phase4-tail-order-controls.mjs、admin-test-env-modules/phase5-terminal-drayage.mjs、admin-test-env-modules/phase4-carrier-nodes.mjs	PDA 前覆盖整柜接柜仓变更与恢复、单/批目的仓变更、单/批合托标记、CSV 导出、订单费用、单票暂扣/解除、八个人工节点和逐票人工计划；接柜仓仅复用公共主档且恢复原值。PDA 卸柜后经正式码头拖车接口完成选车队、预约、提柜、还柜，船节点模块只读核对最终回写，不直接伪造最后两个节点
定向 HTTP/诊断	以 README.md 的“仓库级入口清单”为准	必须明确是只读诊断还是会补证据、创建资源或推进状态，不能用诊断成功冒充全量通过
本地质量与静态合同	backend-full-regression.ps1、frontend-full-regression.ps1（含国内 PDA Node 全量测试）、mapper-scan-contract.mjs、script-documentation-contract.test.mjs 等	默认不访问开发或测试环境；数据库非 dry-run、Nacos 发布等有写入能力的入口必须按 README 单独识别
部署与基础设施	../deploy/scripts/、../deploy/rocketmq/	靠近部署组件管理，不移动到根脚本目录；部署、初始化数据库或发布配置必须获得当前轮明确授权
服务局部合同	../firstleg/scripts/、../lastleg-service/scripts/、../warehouse/scripts/	只服务所属模块，入口与命令登记在服务 AGENTS.md 或局部 README；不得散落到 src/test/scripts/

新增与修改规则

• 跨服务编排、全仓质量检查、开发/测试环境验收和通用诊断放在根 scripts/；只理解单一服务源码或数据的脚本放在 <service>/scripts/。
• 可直接运行的脚本必须在 README.md 登记：用途、目标环境、是否写数据、凭据来源、报告位置、失败/重跑语义和清理边界。内部模块必须登记到 admin-test-env-modules/README.md，并按需同步总入口模块注册及依赖展开。
• 文件命名使用稳定业务语义：离线 Node 合同以 .test.mjs 结尾；环境写入入口显式包含 test-env 或在 README 中标记目标环境；fixture/verify 必须区分准备写入和只读核验。
• 不在源码、AGENTS、README 或报告中写入密码、Token、私钥、真实客户数据和固定环境密钥；环境地址与账号从入口已支持的参数或本机环境配置读取。
• 开发与测试验收配置分别只维护在 $env:USERPROFILE\.codex\chongchong-global-dev-acceptance.env、$env:USERPROFILE\.codex\chongchong-global-test-acceptance.env。脚本不得自动猜测环境或读取另一份文件；运行者必须通过位于脚本路径之前的 node --env-file="<明确文件>" 选择环境。
• 开发目录只使用开发环境文件和开发域名，测试目录只使用测试环境文件和测试域名；不得跨目录复制报告、fixture 或未提交脚本来替代正常分支合并。
• 不直接写业务数据库伪造 HTTP 验收成功，不吞掉 deploymentBlocker、业务错误码、requestId 或 traceId。造数脚本的部分成功数据默认保留，清理、重置或删除必须另行授权。
• 不默认并发运行共享环境造数。只有用户明确要求并确认序号、报告目录和服务容量边界时，才允许拆分 worker；每个 worker 必须使用不重叠序号和独立报告目录。
• 修改公共参数、上下文或模块签名时，定向检查总入口、生产模块、fixture、合同测试、README 和调用命令，禁止保留旧参数兼容分支。
• 模块依赖必须由 normalizeModuleOrder() 和依赖注册统一展开；定向执行也必须获得与默认全量相同的生产者 fixture，缺少前置不得借历史数据或把 coverage gap 当成功。
• Finance 默认链固定为 finance-full-fixtures → finance-reconciliation-full → finance-settlement-full → finance-direct-paid-isolation → finance-downloads。直接已付隔离必须在结算模块产出本轮收付款成功结果后执行；后续动作必须回查实时详情，不得按 fixture 创建时的陈旧状态判断。
• 静态合同应锁定业务语义和稳定接口，不依赖无关排版或已改名文档路径；正式代码、文档目录、SQL 入口、Feign/HTTP 客户端或 Maven 拓扑变化时，同步更新相应枚举基线并核对新增项的访问范围、幂等和失败语义，不得仅放宽断言消除失败。

最低验证

• 修改单个 Node 脚本先运行 node --check <script>；PowerShell 使用解析检查或该脚本声明的 -DryRun，Shell/Groovy 使用现有离线合同，不为验证触发部署。
• 修改 Admin 模块时运行直接对应的 *contract.test.mjs；修改造数链时同时运行 admin-test-env-modules/it-test-wait-split-bulk-contract.test.mjs 等受影响合同。
• 宣称脚本“全量补齐”前，必须运行 scripts/ 根级离线合同与 admin-test-env-modules/*contract.test.mjs，并分别报告测试文件数、断言通过/失败数和精确失败文件；历史真实 HTTP 报告全绿不能覆盖当前离线合同失败。
• 新增、移动或删除脚本后运行 node --test scripts/script-documentation-contract.test.mjs，确认目录已登记且所有直接入口都有说明。
• 修改任一 AGENTS.md 后从后端根运行 ./scripts/agents-index-contract.ps1；真实 HTTP、数据库、Nacos、Jenkins 和部署验证仍须当前轮明确授权。