优化

AGENTS.md

@@ -95,6 +95,8 @@
 
 ## 契约、数据库与验证入口
 
+- 对外 Controller/API 新增、改名或删除时，同时核对调用端、区域 Gateway、OpenAPI 和权限；提交前运行 `node --test scripts/gateway-route-contract.test.mjs`，自动发现生产 Controller 并校验网关目标服务与内部路径隔离。失败不得提交或标记完成；网关配置变化必须列入部署清单，不以业务服务单测代替入口检查。
+
 - 跨服务修改先检查调用方 `client/`、被调用方 Controller/DTO、`src/main/resources/openapi/` 和双方契约测试；禁止共享领域 Entity。
 - 修改 Java 方法、构造器、Controller、Client、DTO 或 Mapper 参数签名时，先用 `rg` 定向查找符号及旧参数形态，并同步更新 `src/main/`、`src/test/`、Mock、Fixture、契约测试和脚本中的全部调用点。新增可选参数也必须补齐旧测试调用，不能因生产调用已更新就视为完成。
 - 所有生产 MyBatis Mapper 接口必须显式标记 `@Mapper`；每个持久化服务只允许在启动类使用一次服务根包 `@MapperScan(..., annotationClass = Mapper.class)`，不得新增子域包白名单或分散的 `*MapperConfiguration`。新增或移动 Mapper 后先运行 `node scripts/mapper-scan-contract.mjs`，全量后端回归也会在 Maven 前执行该门禁。

Jenkinsfile

@@ -316,6 +316,16 @@ pipeline {
             }
         }
 
+        stage('Gateway 路由静态门禁') {
+            when {
+                expression { env.NO_SERVICE_CHANGE != 'true' }
+            }
+            agent { label 'java-builder' }
+            steps {
+                sh 'node --test scripts/gateway-route-contract.test.mjs'
+            }
+        }
+
         stage('统一 Maven 测试门禁') {
             when {
                 expression { env.NO_SERVICE_CHANGE != 'true' && !params.SKIP_TESTS }

firstleg/src/main/java/com/baiyue/firstleg/customs/container/service/ContainerCustomsService.java

@@ -44,6 +44,9 @@ public class ContainerCustomsService {
 
     @Transactional
     public ContainerView platformView(long planId) {
+        List<InboundRow> rows = actualPlanRows(planId);
+        PlanRow plan = rows.isEmpty() ? requiredPlan(planId) : plan(rows.get(0));
+        if (!"COMPLETED".equals(plan.loadingPlanStatus())) return null;
         ContainerRow container = ensure(planId);
         return view(container, null, false);
     }

firstleg/src/main/resources/openapi/customs-v1.yaml

@@ -123,7 +123,7 @@ components:
   schemas:
     LongId: {type: string, pattern: '^[1-9][0-9]*$', description: Long ID序列化为字符串}
     ApiEnvelope: {type: object, required: [code, message, timestamp], properties: {code: {type: string}, message: {type: string}, requestId: {type: string, nullable: true}, traceId: {type: string, nullable: true}, timestamp: {type: string, format: date-time}}}
-    ContainerEnvelope: {allOf: [{$ref: '#/components/schemas/ApiEnvelope'}, {type: object, properties: {data: {$ref: '#/components/schemas/ContainerView'}}}]}
+    ContainerEnvelope: {allOf: [{$ref: '#/components/schemas/ApiEnvelope'}, {type: object, properties: {data: {allOf: [{$ref: '#/components/schemas/ContainerView'}], nullable: true, description: 装柜计划尚未完成时返回null，表示报关流程尚未生成}}}]}
     DocumentEnvelope: {allOf: [{$ref: '#/components/schemas/ApiEnvelope'}, {type: object, properties: {data: {$ref: '#/components/schemas/DocumentView'}}}]}
     ActionRequest: {type: object, required: [expectedVersion, confirm], additionalProperties: false, properties: {expectedVersion: {type: integer, minimum: 0}, confirm: {type: boolean}, remark: {type: string, maxLength: 500, nullable: true}}}
     ScopeRequest: {type: object, required: [inboundIds, expectedVersion], additionalProperties: false, properties: {inboundIds: {type: array, minItems: 1, maxItems: 200, items: {$ref: '#/components/schemas/LongId'}}, expectedVersion: {type: integer, minimum: 1}}}

scripts/README.md

@@ -149,6 +149,10 @@ node scripts/create-pending-review-orders.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 提交不会自动触发此脚本，仍须遵守提交前检查规则。
+
 以下命令只用于代码质量和契约回归，不访问测试环境，不代表服务全量可用：
 
 | 检查 | 入口 |

scripts/backend-full-regression.ps1

@@ -9,6 +9,7 @@ $repoRoot = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
 $pom = Join-Path $repoRoot "pom.xml"
 $mapperScanContract = Join-Path $repoRoot "scripts/mapper-scan-contract.mjs"
 $requiredTests = @(
+    "scripts/gateway-route-contract.test.mjs",
     "scripts/mapper-scan-contract.test.mjs",
     "firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/controller/PlatformOceanBookingControllerContractTest.java",
     "firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingServiceTest.java",
@@ -66,6 +67,8 @@ if ($DryRun) {
 
 Push-Location $repoRoot
 try {
+    & node --test (Join-Path $repoRoot "scripts/gateway-route-contract.test.mjs")
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
     & node $mapperScanContract
     if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
     & $MavenCommand @mavenArgs

scripts/gateway-route-contract.test.mjs

@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import test from 'node:test'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const read = path => readFileSync(resolve(root, path), 'utf8')
+
+// Deliberately limited to the repository's explicit short-form Path routes.
+// Unsupported route syntax fails instead of silently skipping coverage.
+function routes(source) {
+  return [...source.matchAll(/^\s*- id:\s*([^\r\n]+)([\s\S]*?)(?=^\s*- id:|^\S|$(?![\s\S]))/gm)].map(([, id, body]) => {
+    const uri = body.match(/uri:\s*lb:\/\/([\w-]+)/)?.[1]
+    const paths = body.match(/Path=([^\r\n"\]]+)/)?.[1]?.trim().split(',')
+    assert.ok(uri && paths?.length, `Unsupported route: ${id}`)
+    assert.ok(!/\b(?:Method|Host|RewritePath|SetPath|PrefixPath)=/.test(body), `Extend checker for conditional/rewrite route: ${id}`)
+    assert.ok(!/\border\s*:/.test(body), `Extend checker for explicit route order: ${id}`)
+    return { id: id.trim(), uri, paths }
+  })
+}
+
+function matches(pattern, path) {
+  const parts = pattern.split('/')
+  const actual = path.split('/')
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '**') return true
+    if (actual[i] === undefined) return false
+    if (parts[i] === '*' || /^\{[^}]+\}$/.test(parts[i])) continue
+    if (parts[i] !== actual[i]) return false
+  }
+  return parts.length === actual.length
+}
+
+function javaFiles(dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+    const path = resolve(dir, entry.name)
+    return entry.isDirectory() ? javaFiles(path) : entry.name.endsWith('.java') ? [path] : []
+  })
+}
+
+function controllerPaths(source, file) {
+  const clean = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
+  if (!/@(?:RestController|Controller)\b/.test(clean)) return []
+  const header = clean.split(/\bclass\s+/)[0]
+  const mapping = header.match(/@RequestMapping\s*\(([^)]*)\)/)
+  const extract = args => {
+    for (const [, name, value] of clean.matchAll(/static\s+final\s+String\s+(\w+)\s*=\s*"([^"\r\n]*)"\s*;/g)) {
+      args = args.replace(new RegExp(`\\b${name}\\b`, 'g'), `"${value}"`)
+    }
+    while (/"[^"\r\n]*"\s*\+\s*"[^"\r\n]*"/.test(args)) {
+      args = args.replace(/"([^"\r\n]*)"\s*\+\s*"([^"\r\n]*)"/g, '"$1$2"')
+    }
+    const paths = [...args.matchAll(/"(\/[^"\r\n]*)"/g)].map(m => m[1])
+    assert.ok(paths.length || !args.trim() || /^(?:produces|consumes|method)\s*=/.test(args.trim()), `Non-literal mapping requires checker support: ${file}`)
+    assert.ok(!args.replace(/"[^"\r\n]*"/g, '').includes('+'), `Concatenated mapping requires checker support: ${file}`)
+    return paths.length ? paths : ['']
+  }
+  const bases = mapping ? extract(mapping[1]) : ['']
+  const body = clean.slice(header.length)
+  const methods = [...body.matchAll(/@(?:Get|Post|Put|Delete|Patch|Request)Mapping\b(?:\s*\(([^)]*)\))?/g)]
+  if (!methods.length) return bases
+  return methods.flatMap(([, args = '']) => extract(args).flatMap(path => bases.map(base => `${base}${path}`)))
+}
+
+function verify(path, service, table, file) {
+  if (path.includes('{app}')) {
+    for (const app of ['platform', 'merchant']) verify(path.replace('{app}', app), service, table, file)
+    return
+  }
+  // Internal service-token endpoints must never be forwarded, regardless of owner.
+  const hit = table.find(route => route.paths.some(pattern => matches(pattern, path)))
+  if (path.startsWith('/internal/')) {
+    assert.equal(hit, undefined, `Internal endpoint exposed: ${file} ${path}`)
+  } else if (path.startsWith('/api/') || path.startsWith('/openapi/')) {
+    assert.ok(hit, `Missing Gateway route: ${file} ${path}`)
+    assert.equal(hit.uri, service, `Wrong destination: ${file} ${path} via ${hit.id}`)
+  }
+}
+
+const domestic = routes(read('gateway/src/main/resources/application.yml'))
+const overseas = routes(read('gateway-overseas/src/main/resources/application-overseas.yml'))
+const modules = [...read('pom.xml').matchAll(/<module>([^<]+)<\/module>/g)].map(m => m[1])
+
+test('local regression and root CI require route checks before Maven/dispatch', () => {
+  const local = read('scripts/backend-full-regression.ps1')
+  assert.ok(local.indexOf('& node --test') < local.indexOf('& $MavenCommand'))
+  assert.match(local, /gateway-route-contract\.test\.mjs/)
+  const pipeline = read('Jenkinsfile')
+  const gate = pipeline.slice(pipeline.indexOf("stage('Gateway 路由静态门禁')"), pipeline.indexOf("stage('统一 Maven 测试门禁')"))
+  assert.match(gate, /node --test scripts\/gateway-route-contract\.test\.mjs/)
+  assert.doesNotMatch(gate, /SKIP_TESTS|catchError|returnStatus|\|\| true/)
+})
+
+test('Controller prefixes route to their owning service; internal prefixes stay private', () => {
+  let count = 0
+  for (const module of modules) {
+    if (module.startsWith('common-') || module.startsWith('gateway') || module === 'platform-bom') continue
+    const app = `${module}/src/main/resources/application.yml`
+    if (!existsSync(resolve(root, app))) continue
+    const service = read(app).match(/application:\s*\r?\n\s+name:\s*([\w-]+)/)?.[1]
+    assert.ok(service, `Missing application name: ${module}`)
+    const tables = ['lastleg-service', 'warehouse-overseas-service'].includes(module)
+      ? [overseas] : ['file', 'print'].includes(module) ? [domestic, overseas] : [domestic]
+    for (const file of javaFiles(resolve(root, module, 'src/main/java'))) {
+      for (const path of controllerPaths(readFileSync(file, 'utf8'), file)) {
+        for (const table of tables) verify(path, service, table, file)
+        count++
+      }
+    }
+  }
+  assert.ok(count > 100, `Unexpectedly small Controller inventory: ${count}`)
+})
+
+test('removing container shipping nodes route reproduces the missing registration', () => {
+  const broken = domestic.map(route => ({ ...route, paths: route.paths.filter(p => p !== '/api/platform/v1/container-shipping-nodes/**') }))
+  assert.throws(() => verify('/api/platform/v1/container-shipping-nodes', 'firstleg-service', broken, 'fixture'), /Missing Gateway route/)
+})
+
+test('wrong target and internal exposure are rejected', () => {
+  assert.throws(() => verify('/api/new', 'firstleg-service', [{ id: 'wrong', uri: 'order-service', paths: ['/api/**'] }], 'fixture'), /Wrong destination/)
+  assert.throws(() => verify('/internal/private', 'firstleg-service', [{ id: 'broad', uri: 'firstleg-service', paths: ['/**'] }], 'fixture'), /Internal endpoint exposed/)
+})
+
+test('path variables, exact paths and segment boundaries are respected', () => {
+  assert.ok(matches('/api/items/{id}/**', '/api/items/123/action'))
+  assert.ok(matches('/api/items/**', '/api/items'))
+  assert.ok(!matches('/api/items/**', '/api/items-other'))
+  assert.ok(!matches('/api/items', '/api/items/action'))
+  assert.deepEqual(controllerPaths('@RestController @RequestMapping(value = {"/api/a", "/api/b"}) public class Example {}', 'fixture'), ['/api/a', '/api/b'])
+  assert.throws(() => controllerPaths('@RestController @RequestMapping(API_PATH) public class Example {}', 'fixture'), /Non-literal/)
+  assert.deepEqual(controllerPaths('@RestController @RequestMapping("/api") public class Example { @GetMapping("/items") void list() {} }', 'fixture'), ['/api/items'])
+  assert.deepEqual(controllerPaths('@RestController public class Example { static final String PATH = "/api/items"; @GetMapping(PATH) void list() {} }', 'fixture'), ['/api/items'])
+  assert.throws(() => verify('/api/item', 'firstleg-service', [{ id: 'shadow', uri: 'order-service', paths: ['/api/**'] }, { id: 'correct', uri: 'firstleg-service', paths: ['/api/item'] }], 'fixture'), /Wrong destination/)
+})