优化

scripts/AGENTS.md

@@ -12,11 +12,13 @@
 |---|---|---|
 | 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 总入口按依赖运行，会写测试环境 |
 | 定向 HTTP/诊断 | 以 `README.md` 的“仓库级入口清单”为准 | 必须明确是只读诊断还是会补证据、创建资源或推进状态，不能用诊断成功冒充全量通过 |
 | 本地质量与静态合同 | `backend-full-regression.ps1`、`frontend-full-regression.ps1`、`mapper-scan-contract.mjs`、`script-documentation-contract.test.mjs` 等 | 默认不访问测试环境；数据库非 dry-run、Nacos 发布等有写入能力的入口必须按 README 单独识别 |
 | 部署与基础设施 | `../deploy/scripts/`、`../deploy/rocketmq/` | 靠近部署组件管理，不移动到根脚本目录；部署、初始化数据库或发布配置必须获得当前轮明确授权 |

scripts/admin-test-env-modules/README.md

@@ -60,7 +60,9 @@ export async function run(context) {
 |---|---|---|
 | 商户资质与下单身份 | `merchant-qualification-fixture.mjs` | `merchant-qualification-fixture-contract.test.mjs` |
 | 公共主数据与往来单位 | `master-data.mjs` | `master-data-partner-contract.test.mjs` |
+| 平台基础、客户、海外仓储费与下载 | `system.mjs`、`customers.mjs`、`overseas-storage-fees.mjs`、`downloads.mjs` | 由 Admin 总入口默认编排；分别覆盖系统能力、客户管理、海外仓阶梯费和下载中心基础能力 |
 | 订单创建、可计价主数据、幂等零漂移与审核异步收敛 | `orders.mjs` | `orders-pricing-fixture-contract.test.mjs`、`orders-lifecycle-idempotency-contract.test.mjs`、`orders-approval-convergence-contract.test.mjs` |
+| 费用项目、价格配置与基础 Finance | `fee-items.mjs`、`pricing.mjs`、`finance.mjs` | `fee-items-contract.test.mjs`、`pricing-contract.test.mjs`、`finance-contract.test.mjs` |
 | 入库测量、首次打印冻结箱码与墨家扫码 | `inbound-measurement.mjs` | `inbound-measurement-box-code-contract.test.mjs` |
 | 入仓自动头程费用、派生详情、人工发布与 MANUAL 其他费用版本 | `inbound-fees.mjs`（前置：`merchant-qualification-fixture,orders,inbound-measurement`） | `inbound-fees-contract.test.mjs` |
 | 三期模拟柜关联、柜次概览、渠道隔离、装柜模型桥接、PDA、动态增量、四类货柜资料、报关与证据/出仓门禁 | `phase3-container-loading.mjs`、`ocean-booking-fixture.mjs`、`phase3-container-overview.mjs`、`phase3-loading.mjs`、`phase3-loading-model-bridge.mjs`、`phase3-pda-convergence.mjs`、`phase3-evidence-gate.mjs`、`phase3-loading-finalize.mjs`、`phase3-container-documents.mjs`、`phase3-customs.mjs`、`phase3-outbound-dispatch.mjs` | `container-simulation-association-contract.test.mjs`、`container-specification-fixture-contract.test.mjs`、`ocean-booking-channel-contract.test.mjs`、`phase3-container-regression-contract.test.mjs`、`phase3-loading-model-bridge-contract.test.mjs`、`phase3-loading-dynamic-final-contract.test.mjs`、`phase3-container-documents-contract.test.mjs`、`phase3-phase4-departure-pickup-chain-contract.test.mjs`、`phase3-producer-chain-contract.test.mjs`、`manual-state-loading-pda-contract.test.mjs` |
@@ -74,14 +76,19 @@ export async function run(context) {
 | 五类装柜证据、PDA 最终完成与 LOADED 终态核验 | `manual-loading-complete-fixture.mjs`、`manual-loading-complete-verify.mjs`（可选，不进入默认全量） | `manual-loading-complete-contract.test.mjs` |
 | 订舱共享主数据前置与订舱验收 | `ocean-booking-fixture.mjs`、`ocean-bookings.mjs`、`phase3-port-schedules.mjs`、`phase3-carrier-schedule-queries.mjs`（DRAFT 可编辑；RELEASED 冻结；船司查询只创建并写当前 marker 登记任务） | `ocean-booking-prototype-contract.test.mjs`、`ocean-booking-fixture-contract.test.mjs`、`phase3-carrier-schedule-queries.test.mjs` |
 | 订舱级拖车预约完整生命周期 | `truck-appointments.mjs`（自包含创建并放舱，不创建或关联柜次；每订舱最多一张非终态拖车单；覆盖候选、附件、费用、幂等及 `SUBMIT → DISPATCH → PICKUP → ARRIVE → LOAD → DEPART → COMPLETE`） | `truck-appointments-contract.test.mjs` |
+| 订舱与拖车服务中心跨链路 | `service-center-flow.mjs`（依赖 `ocean-bookings,truck-appointments`；复用本轮 `RELEASED` 订舱创建订舱级拖车，验证派车单、完整状态链、历史、审计和关联零漂移） | 由入口依赖合同和拖车直接合同共同覆盖；真实 HTTP 缺本轮订舱或承运商时 fail-closed |
+| Admin 补充能力与保护边界 | `supplemental.mjs`、`supplemental-boundaries.mjs` | `supplemental-boundaries-contract.test.mjs`；只按本轮资源验证补充能力、负向和保护边界 |
 | 装柜清单三备注 | `orders.mjs`、`phase3-loading.mjs`（客户备注、最新内部备注、仓库备注；仓库备注 PATCH/清空/精确重放/旧版本零写） | `loading-list-remarks-contract.test.mjs` |
 | 消息中心管理 | `notifications.mjs` | `notifications-contract.test.mjs` |
 | Finance 真实前置、对账、结算与下载中心 | `finance-full-fixtures.mjs`、`finance-reconciliation-full.mjs`、`finance-settlement-full.mjs`、`finance-downloads.mjs` | `finance-full-fixtures-contract.test.mjs`、`finance-reconciliation-full-contract.test.mjs`、`finance-settlement-full-contract.test.mjs`、`finance-downloads-contract.test.mjs` |
 | Finance 扩展隔离与跨区费用 | `firstleg-container-fee-allocation.mjs`（柜次跨客户分摊）、`finance-direct-paid-isolation.mjs`（海外仓服务直接已付）、`phase4-overseas-finance-cross-region.mjs`（五类海外费用跨区进入 Finance） | 对应同名 `*-contract.test.mjs`；跨区事件持久化链在本轮获授权时另以只读数据库证据核对 |
 | 四期海外仓 HTTP 生命周期 | `phase4-overseas-warehouse.mjs` | `phase4-overseas-warehouse-contract.test.mjs` |
 | 四期海外 PDA 柜号收货与库内操作 HTTP 生命周期 | `phase4-overseas-pda.mjs`（按柜完成签收和实收，成功后仅以内存上下文交接操作员会话和已完成库存事实）、`phase4-overseas-pda-operations.mjs`（紧随收货执行 P2 盘点、P3 整托移库、P4 托盘拆装换绑、P5 换标复核；finally 停用双操作员并清空临时 Token；任何真实 fixture 缺失均 fail-closed） | `phase4-overseas-pda-contract.test.mjs`、`phase4-overseas-pda-operations-contract.test.mjs` |
+| 四期海外入仓扩展、客户服务与排车 | `phase4-overseas-inbound-operations.mjs`、`phase4-overseas-client-services.mjs`、`phase4-overseas-dispatch.mjs` | 对应同名 `*-contract.test.mjs`；只消费本轮四期前置资源，缺失时 fail-closed |
 | 三四期跨区事件与安全门禁 | `phase4-cross-region-events.mjs`（双 Token Audience 互斥、canonical 权限 403、国内装柜完成到 Lastleg 建单、海外柜完成到 Firstleg 回写、轮询重试/幂等/诊断证据；缺本轮 marker 前置时阻断） | `phase4-cross-region-events-contract.test.mjs` |
 | 国内离仓至海外 PDA 可见人工验收节点 | `phase3-customs.mjs`（四类柜资料与整柜照片）、`phase3-outbound-dispatch.mjs`（柜级离仓）、`phase3-carrier-schedule-queries.mjs`、`phase4-carrier-pickup-ready.mjs`、`phase4-overseas-pda.mjs`（同柜候选） | `phase3-phase4-departure-pickup-chain-contract.test.mjs` |
+| 三期出仓聚合、门禁、待装柜与仓库权限 | `phase3-outbound-aggregate.mjs`、`phase3-dispatch-gate.mjs`、`phase3-waiting-for-loading.mjs`、`phase3-warehouse-rbac.mjs` | 由三期容器回归、生产者链和出仓相关合同覆盖；只消费本轮主链资源 |
+| 三期人工状态矩阵 | `manual-state-matrix.mjs` | `manual-state-matrix-contract.test.mjs`；验证装柜完成、报关和订舱相关状态组合 |
 | 四期海外业务 HTTP 生命周期 | `phase4-overseas-business.mjs` | `phase4-overseas-business-contract.test.mjs` |
 | 四期海外主数据 HTTP 生命周期 | `phase4-overseas-master-data.mjs` | `phase4-overseas-master-data-contract.test.mjs` |
 | 四期船节点安全冒烟 | `phase4-carrier-nodes.mjs`（standalone 对历史任务只读；仅复用当前 marker 的 `phase3CarrierScheduleQuery` 时补录预计事实） | `phase4-carrier-nodes-contract.test.mjs` |

scripts/agents-index-contract.ps1

@@ -111,8 +111,12 @@ Assert-Contains $backendAgents 'Mapper 新增、移动、Bean 缺失与扫描遗
 Assert-Contains $backendAgents '脚本管理、全量验证、测试造数与诊断' '后端脚本管理快速路由'
 Assert-Contains $backendAgents 'scripts/it-test-wait-split-bulk.mjs' '后端批量待分柜造数入口'
 Assert-Contains $backendAgents 'scripts/create-pending-review-orders.mjs' '后端待审核订单造数入口'
+Assert-Contains $backendAgents 'scripts/client-quick-order-test-env-acceptance.mjs' '后端 Client 快速下单入口'
+Assert-Contains $backendAgents 'service-center-flow' '后端服务中心验收模块'
 Assert-Contains $scriptsAgents 'admin-test-env-acceptance.mjs' '脚本指引 Admin 全量入口'
 Assert-Contains $scriptsAgents 'client-test-env-acceptance.mjs' '脚本指引 Client 全量入口'
+Assert-Contains $scriptsAgents 'client-quick-order-test-env-acceptance.mjs' '脚本指引 Client 快速下单入口'
+Assert-Contains $scriptsAgents 'admin-test-env-modules/service-center-flow.mjs' '脚本指引服务中心验收模块'
 Assert-Contains $scriptsAgents 'script-documentation-contract.test.mjs' '脚本说明防漏门禁'
 Assert-Contains $scriptsAgents '不得散落到 `src/test/scripts/`' '服务局部脚本目录边界'
 Assert-Path 'baiyue-firstleg/scripts/AGENTS.md'

scripts/script-documentation-contract.test.mjs

@@ -6,6 +6,8 @@ import { fileURLToPath } from 'node:url'
 
 const repositoryRoot = path.resolve(fileURLToPath(new URL('..', import.meta.url)))
 const scriptsReadme = path.join(repositoryRoot, 'scripts', 'README.md')
+const adminModulesReadme = path.join(repositoryRoot, 'scripts', 'admin-test-env-modules', 'README.md')
+const adminAcceptanceEntry = path.join(repositoryRoot, 'scripts', 'admin-test-env-acceptance.mjs')
 const excludedDirectoryNames = new Set([
   '.git', '.logs', 'dist', 'node_modules', 'output', 'outputs', 'reports', 'target', 'uni_modules',
 ])
@@ -79,3 +81,19 @@ test('README explains internal modules and test scripts are not standalone entri
   assert.match(readme, /admin-test-env-modules\/\*\.mjs.*逐模块说明/)
   assert.match(readme, /warehouse\/scripts\/warehouse-public-master-data-contract\.test\.mjs/)
 })
+
+test('all Admin acceptance modules are documented in the module index', async () => {
+  const [entrySource, readme] = await Promise.all([
+    readFile(adminAcceptanceEntry, 'utf8'),
+    readFile(adminModulesReadme, 'utf8'),
+  ])
+  const registeredModules = []
+  for (const list of entrySource.matchAll(/const (?:CONFIGURED|OPTIONAL)_MODULES = \[([\s\S]*?)\]/g)) {
+    for (const moduleName of list[1].matchAll(/'([^']+)'/g)) registeredModules.push(moduleName[1])
+  }
+
+  assert.notEqual(registeredModules.length, 0, '未从 Admin 全量入口读取到模块注册表')
+  const undocumented = [...new Set(registeredModules)]
+    .filter((moduleName) => !readme.includes(`\`${moduleName}.mjs\``))
+  assert.deepEqual(undocumented, [], `以下 Admin 验收模块未登记用途与边界：\n${undocumented.join('\n')}`)
+})