优化

scripts/README.md

@@ -0,0 +1,68 @@
+# 后端全量回归
+
+## 入口
+
+在 `baiyue-firstleg` 根目录执行：
+
+```powershell
+.\scripts\backend-full-regression.ps1
+```
+
+## 前端全量回归
+
+`frontend-full-regression.ps1` 只编排本地 Admin/Client 的 `pnpm test` 与 `pnpm typecheck`，不调用 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
+```
+
+脚本会检查 `pnpm` 和目标应用的 `package.json`；任一命令失败时立即透传退出码，不能同时跳过 Admin 和 Client。
+
+脚本固定运行：
+
+```text
+mvn -f <仓库根>/pom.xml -pl order,firstleg -am test
+```
+
+这会先构建公共依赖，再运行 `order` 与 `firstleg` 的全部 Maven 测试。覆盖包括：
+
+- 三期 Ocean Booking Controller/Service/Mapper/SQL 契约；
+- 三期 Truck Appointment Controller/Service/Mapper 契约、状态机、乐观锁和幂等操作；
+- 二期 `WAIT_SPLIT` 的 firstleg 查询、order 统一查询及筛选语义；
+- 拣货/预装/装柜模型映射与既有 Smart Loading/Split 契约。
+
+## Dry-run
+
+```powershell
+.\scripts\backend-full-regression.ps1 -DryRun
+```
+
+Dry-run 只检查根 `pom.xml` 和关键回归测试文件并打印 Maven 命令，不启动 Java 服务，不请求 Gateway，不连接或写入任何数据库。
+
+## 现有相关脚本与边界
+
+### 本地 MySQL 全量验收
+
+正式入口是 `local-db-full-acceptance.ps1`，只允许连接本机 `127.0.0.1` 或 `localhost`，默认端口 `3306`；测试库 `8.163.30.128` 会立即以退出码 2 拒绝。脚本固定校验统一 SQL SHA-256 `E86BB8DE105E9B59736FFCD180CBA902F2E3F5032C7EFF2E3DC3B24B289360A0` 和 7803 行。
+
+```powershell
+.\local-db-full-acceptance.ps1 -DryRun
+.\local-db-full-acceptance.ps1
+```
+
+Dry-run 只校验 SQL 输入并打印空库、复跑、两类 picking 旧结构、WAIT_SPLIT/IAM、海外仓旧结构、中断恢复和最终结构的执行顺序，不启动 MySQL、不写库。真实运行每阶段写入 `.codex-tmp/p23-04-acceptance/acceptance-run-*.log`，不使用 `--force`，任一 SQL 错误立即停止并透传退出码，最后执行 `verify-final.sql`。脚本不保存或传入数据库密码，使用本机默认认证环境。
+
+仓库中 `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、迁移、DDL、INSERT/UPDATE/DELETE，也不启动 Nacos、Gateway 或业务服务。需要数据库矩阵时必须单独运行受控验收流程。
+
+## 退出码
+
+- `0`：dry-run 检查通过或 Maven 全量测试通过；
+- `2`：仓库根 pom 或关键测试文件缺失，脚本未启动 Maven；
+- 其他非零值：原样透传 Maven 失败退出码。
+
+脚本不设置 `MAVEN_OPTS`、数据库 URL 或测试账号；环境参数仅为可选的 `$MavenCommand`（默认 `mvn`），用于指定本机 Maven 可执行文件。

scripts/admin-test-env-acceptance.mjs

@@ -11,7 +11,7 @@ import process from 'node:process'
 const DEFAULT_GATEWAY = 'http://8.163.30.128:9000'
 const DEFAULT_USERNAME = 'platform_admin'
 const DEFAULT_PASSWORD = 'ChangeMe123!'
-const DEFAULT_MODULES = ['customers', 'overseas-storage-fees', 'system', 'master-data', 'orders', 'pricing', 'downloads', 'inbound-weight-ocr', 'inbound-measurement', 'supplemental', 'supplemental-boundaries', 'ocean-bookings', 'truck-appointments']
+const DEFAULT_MODULES = ['customers', 'overseas-storage-fees', 'system', 'master-data', 'orders', 'pricing', 'downloads', 'inbound-weight-ocr', 'inbound-measurement', 'supplemental', 'supplemental-boundaries', 'ocean-bookings', 'truck-appointments', 'service-center-flow']
 const WEIGHT_IMAGE_PATH = 'C:/Users/BY-OY/Desktop/上传图片包/测量图片/测量图片/orig_1cf27695-b2c3-44b3-98e3-c0be8b80f79a.JPG'
 const CUSTOMER_FIELDS = [
   'id', 'tenantCode', 'tenantName', 'status', 'legalName', 'legalRepresentative',
@@ -92,6 +92,7 @@ class AcceptanceRun {
     this.scenarios = []
     this.createdResources = {}
     this.deploymentBlockers = []
+    this.coverageGaps = []
     this.context = {}
     this.token = ''
     this.fatal = null
@@ -158,6 +159,10 @@ class AcceptanceRun {
     return step.passed
   }
 
+  addCoverageGap(module, scenario, name, reason, category = 'not-implemented') {
+    this.coverageGaps.push({ module, scenario, name, reason, category })
+  }
+
   apiSuccess(module, name, response, evidence = '', options = {}) {
     const passed = response.http === 200 && String(response.body?.code) === '200'
     this.addStep(module, name, response, passed, evidence, options)
@@ -478,6 +483,7 @@ class AcceptanceRun {
       success: this.fatal === null && failed === 0, fatal: this.fatal,
       summary: { total: this.steps.length, passed: this.steps.length - failed, failed },
       modules: this.modules, scenarios: this.scenarios, deploymentBlockers: this.deploymentBlockers,
+      coverageGaps: this.coverageGaps,
       createdResources: this.createdResources,
       excluded: [
         { scope: 'dashboard', reason: '首页为静态演示数据，不调用后端 API' },

scripts/admin-test-env-modules/master-data.mjs

@@ -5,6 +5,21 @@ function xlsxOk(response) {
     && response.bytes[0] === 0x50 && response.bytes[1] === 0x4b
 }
 
+async function uploadTemplate(context, path, bytes, fileName) {
+  const form = new FormData()
+  form.append('file', new Blob([bytes], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }), fileName)
+  try {
+    const response = await fetch(`${context.options.gateway}${path}`, {
+      method: 'POST', headers: { Accept: 'application/json', Authorization: `Bearer ${context.token}` },
+      body: form, signal: AbortSignal.timeout(60_000),
+    })
+    const raw = await response.text(); let body = null
+    try { body = raw ? JSON.parse(raw) : null } catch { /* bounded evidence only */ }
+    return { method: 'POST', path, http: response.status, body, raw: body === null ? raw.slice(0, 500) : null,
+      requestId: body?.requestId || response.headers.get('x-request-id'), traceId: body?.traceId || response.headers.get('x-trace-id') }
+  } catch (error) { return { method: 'POST', path, http: 0, body: null, raw: String(error), requestId: null, traceId: null } }
+}
+
 export async function run(context) {
   const module = 'master-data'
   const suffix = context.marker.replace(/\D/g, '').slice(-12)
@@ -150,8 +165,30 @@ export async function run(context) {
     const response = await context.requestBinary('GET', path)
     context.addStep(module, `下载${name}导入模板`, response, xlsxOk(response),
       `bytes=${response.bytes?.length ?? 0}, contentType=${response.contentType || 'missing'}`)
+    if (xlsxOk(response)) {
+      const importPath = `${path.replace('/import-template', '/import')}?tenantId=0&dryRun=true`
+      const first = await uploadTemplate(context, importPath, response.bytes, `${context.marker}-${name}.xlsx`)
+      const firstData = first.body?.data
+      context.addStep(module, `${name}合法模板 dryRun 导入契约`, first,
+        first.http === 200 && String(first.body?.code) === '200',
+        `HTTP=${first.http}, code=${first.body?.code ?? 'missing'}, rows=${firstData?.totalRows ?? 'n/a'}, parserSuccess=${firstData?.success ?? 'n/a'}`,
+        { scenario: 'valid-import', deploymentBlocker: first.http === 404 || first.http === 405 || first.http === 503 })
+      const second = await uploadTemplate(context, importPath, response.bytes, `${context.marker}-${name}-replay.xlsx`)
+      context.addStep(module, `${name}合法模板重复 dryRun 幂等结果稳定`, second,
+        second.http === 200 && String(second.body?.code) === '200'
+          && second.body?.data?.totalRows === firstData?.totalRows && second.body?.data?.importedRows === firstData?.importedRows,
+        `firstRows=${firstData?.totalRows ?? 'n/a'}, replayRows=${second.body?.data?.totalRows ?? 'n/a'}`,
+        { scenario: 'valid-import', deploymentBlocker: second.http === 404 || second.http === 405 || second.http === 503 })
+      context.addCoverageGap(module, 'valid-import', `${name}带数据行的合法 XLSX 写入`,
+        '当前验收运行时无 XLSX 写入依赖；仅上传真实服务模板做解析/重复结果稳定性验证，未伪造数据行或写入主数据', 'runtime-dependency')
+    } else {
+      context.addCoverageGap(module, 'valid-import', `${name}合法 XLSX 导入`, '模板下载契约不可用，无法安全取得真实字段模板；未构造伪 XLSX', 'deployment')
+    }
   }
 
+  context.addCoverageGap(module, 'optimistic-lock', '仓库/托盘/快递/往来单位旧 version 冲突',
+    '真实 DTO 未声明 version/expectedVersion 字段，不能伪造并发冲突断言；库位版本已由 supplemental-boundaries 覆盖', 'contract-gap')
+
   const disableWarehouseResponse = await context.request('PATCH', `/api/platform/v1/warehouse-admin/${warehouseId}/status?tenantId=0&status=INACTIVE`)
   context.apiSuccess(module, '停用测试仓库', disableWarehouseResponse)
 }

scripts/admin-test-env-modules/service-center-flow.mjs

@@ -0,0 +1,45 @@
+const MODULE = 'service-center-flow'
+const OPTIONS = { scenario: 'service-center-cross-flow', deploymentBlocker: true }
+const OCEAN = '/api/platform/v1/ocean-bookings'
+const TRUCK = '/api/platform/v1/truck-appointments'
+
+function id(value) { return value == null ? '' : String(value) }
+function codeOf(response) { return response?.body?.code == null ? 'missing' : String(response.body.code) }
+
+export async function run(context) {
+  const ocean = context.createdResources?.oceanBooking
+  if (!ocean?.id || ocean.finalStatus !== 'RELEASED') {
+    context.addStep(MODULE, '跨服务链路前置订舱终态可用', null, false,
+      '本轮海运订舱模块未返回 RELEASED 隔离记录，未伪造关联拖车预约', OPTIONS)
+    return
+  }
+
+  const suffix = context.marker.replace(/\D/g, '').slice(-10)
+  const customerId = Number(context.context?.customerId || 10001)
+  const payload = {
+    outboundOrderId: null, oceanBookingId: Number(ocean.id), containerBookingId: null, loadingPlanId: null,
+    warehouseId: Number(context.createdResources?.warehouse?.id || context.context?.warehouseId || 193000000000000001),
+    customerId, customerName: `服务中心链路客户-${suffix}`, carrierId: null, carrierName: `链路承运商-${suffix}`,
+    fleetContact: '链路车队联系人', fleetPhone: '13800000007', driverName: '链路司机', driverPhone: '13800000008',
+    driverIdCard: null, vehicleNo: `粤D-${suffix.slice(-6)}`, storeName: `链路门店-${suffix}`, storeContact: '链路联系人',
+    storePhone: '13800000009', storeAddress: '深圳市南山区链路地址', storeCity: '深圳市', storeZipcode: '518000',
+    packageCount: 1, grossWeightKg: 1, volumeCbm: 0.1, palletCount: 0, poNo: `FLOW-PO-${suffix}`,
+    plannedLoadingAt: '2026-09-03T08:00:00', transitMinutes: 60, payableAmount: 1, receivableAmount: 2,
+    currency: 'RMB', remark: context.marker, expectedVersion: 0,
+  }
+  const response = await context.request('POST', TRUCK, payload)
+  const appointment = context.apiSuccess(MODULE, '创建关联海运订舱的拖车预约', response, `oceanBookingId=${ocean.id}`, OPTIONS)
+  const appointmentId = id(appointment?.id)
+  context.assert(MODULE, '拖车预约关联订舱 ID、版本和审计字段完整', response,
+    Boolean(appointmentId) && id(appointment?.oceanBookingId) === id(ocean.id) && Number.isFinite(Number(appointment?.version))
+      && Boolean(appointment?.createdAt || appointment?.createdBy || appointment?.operatorName),
+    `appointmentId=${appointmentId || 'missing'}, oceanBookingId=${appointment?.oceanBookingId || 'missing'}, version=${appointment?.version ?? 'missing'}`, OPTIONS)
+  if (!appointmentId) return
+  context.createdResources.serviceCenterFlow = { appointmentId, oceanBookingId: ocean.id, marker: context.marker, finalStatus: 'CANCELLED' }
+  const action = await context.request('POST', `${TRUCK}/${appointmentId}/cancel`, { expectedVersion: Number(appointment.version), reason: context.marker })
+  const cancelled = context.apiSuccess(MODULE, '取消跨服务链路拖车预约', action, '', OPTIONS)
+  context.assert(MODULE, '跨服务链路安全终态为 CANCELLED', action, cancelled?.status === 'CANCELLED', `status=${cancelled?.status || 'missing'}`, OPTIONS)
+  const detail = await context.request('GET', `${TRUCK}/${appointmentId}`)
+  const final = context.apiSuccess(MODULE, '回查跨服务链路审计历史', detail, '', OPTIONS)
+  context.assert(MODULE, '跨服务链路状态历史存在', detail, Array.isArray(final?.histories) && final.histories.length >= 1, `histories=${final?.histories?.length ?? 'n/a'}`, OPTIONS)
+}

scripts/admin-test-env-modules/supplemental-boundaries.mjs

@@ -89,8 +89,8 @@ export async function run(context) {
   // Public APIs do not expose a safe way to create a real occupied pallet/
   // location association without an inbound allocation fixture. Keep this as
   // an explicit automation gap instead of claiming a deletion-protection pass.
-  context.addStep(MODULE, '托盘/库位真实占用删除保护自动化缺口', null, false,
-    '当前公共验收 API 未提供可安全构造并释放占用关联的独立 fixture；未操作历史资源', OPTIONS)
+  context.addCoverageGap(MODULE, 'resource-occupancy', '托盘/库位真实占用删除保护',
+    '当前公共验收 API 未提供可安全构造并释放占用关联的独立 fixture；未操作历史资源', 'no-public-fixture-api')
 
   // Import boundary probes use only in-memory bytes and dry-run where supported.
   const bogusXlsx = new Uint8Array([0x50, 0x4b, 0x03, 0x04, 0x00, 0x00])

scripts/backend-full-regression.ps1

@@ -0,0 +1,54 @@
+[CmdletBinding()]
+param(
+    [switch]$DryRun,
+    [string]$MavenCommand = "mvn"
+)
+
+$ErrorActionPreference = "Stop"
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+$pom = Join-Path $repoRoot "pom.xml"
+$requiredTests = @(
+    "firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/controller/PlatformOceanBookingControllerContractTest.java",
+    "firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingServiceTest.java",
+    "firstleg/src/test/java/com/baiyue/firstleg/repository/TruckAppointmentMapperContractTest.java",
+    "firstleg/src/test/java/com/baiyue/firstleg/service/TruckAppointmentServiceTest.java",
+    "firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java",
+    "firstleg/src/test/java/com/baiyue/firstleg/service/UnifiedInboundQueryServiceTest.java",
+    "order/src/test/java/com/baiyue/order/service/UnifiedOrderQueryServiceTest.java"
+)
+$mavenArgs = @("-f", $pom, "-pl", "order,firstleg", "-am", "test")
+
+Write-Host "Backend regression root: $repoRoot"
+Write-Host "Scope: order + firstleg Maven reactor (includes all module tests)"
+Write-Host "Database/API access: none"
+
+if (-not (Test-Path -LiteralPath $pom)) {
+    Write-Error "Missing Maven pom: $pom"
+    exit 2
+}
+
+$missing = @($requiredTests | Where-Object { -not (Test-Path -LiteralPath (Join-Path $repoRoot $_)) })
+if ($missing.Count -gt 0) {
+    Write-Error ("Missing required regression coverage:`n" + ($missing -join "`n"))
+    exit 2
+}
+
+Write-Host ("Command: {0} {1}" -f $MavenCommand, ($mavenArgs -join " "))
+if ($DryRun) {
+    Write-Host "DRY-RUN PASS: prerequisites and coverage files are present; Maven was not started."
+    exit 0
+}
+
+Push-Location $repoRoot
+try {
+    & $MavenCommand @mavenArgs
+    $code = $LASTEXITCODE
+} finally {
+    Pop-Location
+}
+if ($code -ne 0) {
+    Write-Error "Maven regression failed with exit code $code"
+    exit $code
+}
+Write-Host "Backend regression PASS"
+exit 0

scripts/frontend-full-regression.ps1

@@ -0,0 +1,40 @@
+[CmdletBinding()]
+param(
+  [switch]$DryRun,
+  [switch]$SkipAdmin,
+  [switch]$SkipClient
+)
+
+$ErrorActionPreference = 'Stop'
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../..')).Path
+
+function Invoke-FrontendStep {
+  param([string]$Name, [string]$Directory, [string]$Task)
+  $display = "pnpm --dir `"$Directory`" $Task"
+  Write-Host "  [$Name] $display"
+  if ($DryRun) { return }
+  & pnpm --dir $Directory $Task
+  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
+if ($SkipAdmin -and $SkipClient) { Write-Error 'At least one of Admin or Client must be selected.'; exit 2 }
+if (-not (Get-Command pnpm -ErrorAction SilentlyContinue)) { Write-Error 'pnpm was not found on PATH.'; exit 2 }
+
+$targets = @()
+if (-not $SkipAdmin) { $targets += @{ Name = 'Admin'; Directory = Join-Path $repoRoot 'apps/admin-web' } }
+if (-not $SkipClient) { $targets += @{ Name = 'Client'; Directory = Join-Path $repoRoot 'apps/client-web' } }
+
+Write-Host 'Frontend full regression (local only)'
+Write-Host "Repository: $repoRoot"
+Write-Host "Mode: $(if ($DryRun) { 'DryRun' } else { 'Execute' })"
+Write-Host 'Gateway/database/deployment: not used'
+
+foreach ($target in $targets) {
+  $packageJson = Join-Path $target.Directory 'package.json'
+  if (-not (Test-Path -LiteralPath $packageJson)) { Write-Error "$($target.Name) package.json not found: $packageJson"; exit 2 }
+  Write-Host "[$($target.Name)]"
+  Invoke-FrontendStep 'test' $target.Directory 'test'
+  Invoke-FrontendStep 'typecheck' $target.Directory 'typecheck'
+}
+
+Write-Host 'Frontend regression completed.'

scripts/local-db-full-acceptance.ps1

@@ -0,0 +1,65 @@
+param(
+    [switch]$DryRun,
+    [Alias('Host')][string]$TargetHost = '127.0.0.1',
+    [int]$Port = 3306,
+    [string]$InputPath,
+    [string]$MysqlExe = 'C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe',
+    [string]$User = 'root'
+)
+
+$ErrorActionPreference = 'Stop'
+$Repo = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$Workspace = (Resolve-Path (Join-Path $Repo '..')).Path
+$Acceptance = Join-Path $Workspace '.codex-tmp\p23-04-acceptance'
+$ExpectedSha256 = 'E86BB8DE105E9B59736FFCD180CBA902F2E3F5032C7EFF2E3DC3B24B289360A0'
+$ExpectedLines = 7803
+
+if ($TargetHost -notin @('127.0.0.1', 'localhost')) {
+    [Console]::Error.WriteLine('Refusing non-local database; only 127.0.0.1 or localhost is allowed.')
+    exit 2
+}
+if ([string]::IsNullOrWhiteSpace($InputPath)) {
+    $InputPath = (Get-ChildItem (Join-Path $Repo 'deploy\sql') -Filter '*MySQL8.sql' -File |
+        Where-Object { $_.Length -gt 100000 } | Select-Object -First 1).FullName
+}
+if (-not (Test-Path -LiteralPath $InputPath)) {
+    [Console]::Error.WriteLine("InputPath does not exist: $InputPath")
+    exit 2
+}
+$actual = ((Get-FileHash -Algorithm SHA256 -LiteralPath $InputPath).Hash).Trim().ToUpperInvariant()
+$lines = [System.IO.File]::ReadAllLines($InputPath).Length
+if ($actual -ne $ExpectedSha256 -or $lines -ne $ExpectedLines) {
+    [Console]::Error.WriteLine("Unified SQL snapshot mismatch: $actual/$lines")
+    exit 2
+}
+
+$sequence = @(
+    'empty: base.sql', 'replay: base.sql + input.sql + input.sql',
+    'smart-old: fixture-smart-old.sql', 'inbound-old: fixture-inbound-old.sql',
+    'waitsplit-iam: fixture-test-shape.sql', 'overseas-old: fixture-overseas-old.sql',
+    'overseas-missing-objects: fixture-overseas-missing-objects.sql',
+    'interrupted-recovery: fixture-interrupted.sql', 'final-structure: verify-final.sql')
+Write-Output "SQL SHA-256: $actual / lines: $lines"
+Write-Output "Target: $TargetHost`:$Port"
+Write-Output 'Fixture order:'
+$sequence | ForEach-Object { Write-Output "  $_" }
+if ($DryRun) { Write-Output 'DRY-RUN PASS (mysql not started; no database writes)'; exit 0 }
+
+$run = 0
+function Invoke-Stage([string]$Name, [string]$File) {
+    $script = Join-Path $Acceptance $File
+    $log = Join-Path $Acceptance ("acceptance-run-{0:D2}-{1}.log" -f $script:run, $Name)
+    $script:run++
+    if (-not (Test-Path -LiteralPath $script)) { [Console]::Error.WriteLine("Script does not exist: $script"); return 2 }
+    & $MysqlExe '--protocol=TCP' "--host=$TargetHost" "--port=$Port" "--user=$User" '--database=mysql' '--batch' ("--execute=source " + $script.Replace('\','/')) *> $log
+    return $LASTEXITCODE
+}
+
+$calls = @(
+    @('empty','base.sql'), @('replay-reset','base.sql'), @('replay-1','input.sql'), @('replay-2','input.sql'),
+    @('smart-old','fixture-smart-old.sql'), @('inbound-old','fixture-inbound-old.sql'), @('waitsplit-iam','fixture-test-shape.sql'),
+    @('overseas-old','fixture-overseas-old.sql'), @('overseas-missing','fixture-overseas-missing-objects.sql'),
+    @('interrupted','fixture-interrupted.sql'), @('final-verify','verify-final.sql'))
+foreach ($call in $calls) { $code = Invoke-Stage $call[0] $call[1]; if ($code -ne 0) { exit $code } }
+Write-Output 'FULL LOCAL ACCEPTANCE PASS'
+exit 0