Merge pull request 'fix(lastleg): 修复取货车次导致出车记录 S0500' (#39) from hotfix-trip-operations into main

User-authorized fixed-source promotion; deployment and data preservation verified separately.

Jenkinsfile

@@ -67,6 +67,8 @@ def parseAutoBuildState(String description, List<String> allowedServices) {
     List<String> failedServices = []
     if (state.startsWith('RESULTS')) {
         String summary = state.substring('RESULTS'.length()).trim()
+        int metadataIndex = summary.indexOf(' | ')
+        if (metadataIndex >= 0) summary = summary.substring(0, metadataIndex).trim()
         summary.split(',').collect { it.trim() }.findAll { it }.each { item ->
             int separator = item.indexOf('=')
             if (separator > 0) {
@@ -103,6 +105,25 @@ def previousAutoBuildState(def previousBuild, List<String> allowedServices) {
     return null
 }
 
+// 测试范围必须相对成功门禁，而非失败/取消轮次；否则补跑可能遗漏前次未通过的变更。
+def previousSuccessfulTestCommit(def previousBuild, List<String> requiredServices) {
+    def candidate = previousBuild
+    int inspected = 0
+    while (candidate != null && inspected < 30) {
+        String description = candidate.description ?: ''
+        String marker = ' | TESTS=PASSED '
+        int markerIndex = description.lastIndexOf(marker)
+        if (candidate.result == 'SUCCESS' && markerIndex >= 0) {
+            List metadata = description.substring(markerIndex + marker.length()).trim().split(' ')
+            if (metadata.size() == 2 && metadata[0] ==~ /[0-9a-fA-F]{7,40}/ &&
+                requiredServices.every { metadata[1].split(',').contains(it) }) return metadata[0]
+        }
+        candidate = candidate.previousBuild
+        inspected++
+    }
+    return ''
+}
+
 def environmentChoicesForJob(String jobBaseName) {
     return [fixedEnvironmentForJob(jobBaseName) ?: 'test']
 }
@@ -161,6 +182,7 @@ pipeline {
         choice(name: 'ENVIRONMENT', choices: environmentChoicesForJob(env.JOB_BASE_NAME), description: '部署环境')
         booleanParam(name: 'DEPLOY', defaultValue: false, description: '各服务构建成功后是否独立部署')
         booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '是否跳过测试执行（仍编译测试源码）')
+        choice(name: 'TEST_SCOPE', choices: ['AUTO', 'MODULE'], description: 'AUTO 对已支持的局部变更执行关联测试；公共/未知变更自动完整模块回归；MODULE 显式完整模块回归')
         // 地址由当前 Job 配置提供；参数声明刷新时保留已配置值，不将环境地址写入源码。
         string(name: 'IMAGE_REPOSITORY', defaultValue: params.IMAGE_REPOSITORY ?: '', description: '沿用当前 Job 已配置的镜像仓库地址；首次配置或更换仓库时填写 host[:port]/owner/image')
         string(name: 'DOCKER_BASE_IMAGE', defaultValue: 'eclipse-temurin:17-jre-alpine', description: 'Java 17 基础镜像')
@@ -269,6 +291,7 @@ pipeline {
                     selected = selected.unique()
 
                     env.SELECTED_SERVICES = selected.join(',')
+                    env.TEST_BASE_COMMIT = previousSuccessfulTestCommit(currentBuild.previousBuild, selected)
                     env.NO_SERVICE_CHANGE = selected ? 'false' : 'true'
                     if (!selected) {
                         currentBuild.description = params.BUILD_MODE == 'AUTO'
@@ -335,16 +358,22 @@ pipeline {
                         .findAll { it }
                         .join(',')
                     echo "统一测试本次选中的服务及其公共依赖: ${selectedModules}"
+                    String testPlan = "${pwd(tmp: true)}/ci-test-plan.json"
                     lock(resource: 'firstleg-test-maven') {
                         timeout(time: 50, unit: 'MINUTES') {
                             sh """
                                 test \"\$(git rev-parse HEAD)\" = \"${env.SOURCE_COMMIT}\"
                                 find . -type f -path '*/target/surefire-reports/TEST-*.xml' -delete
-                                sh deploy/scripts/run-ci-maven.sh --settings deploy/maven/settings-ci.xml --batch-mode --errors -pl ${selectedModules} -am test
+                                node deploy/scripts/ci-test-scope.mjs plan --modules '${selectedModules}' --base '${env.TEST_BASE_COMMIT ?: ''}' --mode '${env.RESOLVED_ENVIRONMENT == 'test' ? (params.TEST_SCOPE ?: 'AUTO') : 'MODULE'}' --plan '${testPlan}'
+                                node deploy/scripts/ci-test-scope.mjs checks --plan '${testPlan}'
+                                test_arguments=\"\$(node deploy/scripts/ci-test-scope.mjs args --plan '${testPlan}')\"
+                                sh deploy/scripts/run-ci-maven.sh --settings deploy/maven/settings-ci.xml --batch-mode --errors -pl ${selectedModules} -am test \$test_arguments
+                                node deploy/scripts/ci-test-scope.mjs verify --plan '${testPlan}'
                             """
                         }
                     }
                     echo "统一测试门禁通过: ${env.SOURCE_COMMIT}；下游单服务任务不再重复执行测试"
+                    env.TEST_GATE_PASSED = 'true'
                 }
             }
             post {
@@ -401,6 +430,9 @@ pipeline {
                     currentBuild.description = params.BUILD_MODE == 'AUTO'
                         ? "AUTO ${env.IMAGE_TAG} | RESULTS ${summary}"
                         : "${env.IMAGE_TAG} | ${summary}"
+                    if (env.TEST_GATE_PASSED == 'true') {
+                        currentBuild.description += " | TESTS=PASSED ${env.SOURCE_COMMIT} ${env.SELECTED_SERVICES}"
+                    }
                     if (failed) {
                         unstable("部分服务执行失败，但其他服务已独立完成：${failed.join(', ')}")
                     }

common-event-contract/src/main/java/com/baiyue/common/event/ContainerNumbers.java

@@ -2,15 +2,11 @@ package com.baiyue.common.event;
 
 import java.util.Locale;
 
-/** Canonical physical container number used by cross-region business facts. */
+/** 跨服务业务事实使用的真实集装箱号，只规范化空白和大小写，不校验 ISO 格式。 */
 public final class ContainerNumbers {
-    private static final int[] LETTER_VALUES = {
-        10, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 23, 24,
-        25, 26, 27, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38
-    };
-
     private ContainerNumbers() { }
 
+    /** 柜号必须非空；统一移除格式空白并转大写，保留业务录入值。 */
     public static String normalizeRequired(String value) {
         if (value == null || value.isBlank()) {
             throw new IllegalArgumentException("containerNo is required");
@@ -19,21 +15,13 @@ public final class ContainerNumbers {
         value.codePoints().filter(codePoint -> !Character.isWhitespace(codePoint)
             && !Character.isSpaceChar(codePoint)).forEach(compact::appendCodePoint);
         String normalized = compact.toString().toUpperCase(Locale.ROOT);
-        if (!normalized.matches("[A-Z]{3}[UJZ][0-9]{7}")) {
-            throw new IllegalArgumentException("containerNo must comply with ISO 6346");
-        }
-        int sum = 0;
-        for (int index = 0; index < 10; index++) {
-            char current = normalized.charAt(index);
-            int number = Character.isDigit(current) ? current - '0' : LETTER_VALUES[current - 'A'];
-            sum += number * (1 << index);
-        }
-        if (normalized.charAt(10) - '0' != sum % 11 % 10) {
-            throw new IllegalArgumentException("containerNo must comply with ISO 6346 check digit");
+        if (normalized.isEmpty()) {
+            throw new IllegalArgumentException("containerNo is required");
         }
         return normalized;
     }
 
+    /** 冻结事实必须已规范化，避免生产与消费端的快照或哈希发生漂移。 */
     public static String requireCanonical(String value) {
         String normalized = normalizeRequired(value);
         if (!normalized.equals(value)) {

common-event-contract/src/test/java/com/baiyue/common/event/ContainerNumbersTest.java

@@ -1,20 +1,41 @@
 package com.baiyue.common.event;
 
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 class ContainerNumbersTest {
+    /** 规范化仍保持确定性，事件只能接受已冻结的规范值。 */
     @Test
-    void normalizesWhitespaceAndCaseButCanonicalFactsRequireExactIso6346Value() {
+    void normalizesWhitespaceAndCaseButCanonicalFactsRequireExactValue() {
         assertThat(ContainerNumbers.normalizeRequired(" zcsu 7881970 ")).isEqualTo("ZCSU7881970");
-        assertThat(ContainerNumbers.requireCanonical("ZCSU7881970")).isEqualTo("ZCSU7881970");
         assertThatThrownBy(() -> ContainerNumbers.requireCanonical("zcsu7881970"))
             .hasMessageContaining("normalized");
-        assertThatThrownBy(() -> ContainerNumbers.normalizeRequired("ZCSU7881971"))
-            .hasMessageContaining("check digit");
-        assertThatThrownBy(() -> ContainerNumbers.normalizeRequired("CAB-260831-0001"))
-            .hasMessageContaining("ISO 6346");
+        assertThatThrownBy(() -> ContainerNumbers.requireCanonical(" JZXH10231043 "))
+            .hasMessageContaining("normalized");
+    }
+
+    /** 非 ISO 柜号可以作为事件事实，不在下游重新阻断。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "ZCSU7881971", "MSCA6639870", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void acceptsNonIsoNumber(String containerNo) {
+        assertThat(ContainerNumbers.normalizeRequired(" " + containerNo.toLowerCase(java.util.Locale.ROOT) + " "))
+            .isEqualTo(containerNo);
+        assertThat(ContainerNumbers.requireCanonical(containerNo)).isEqualTo(containerNo);
+    }
+
+    /** 规范化前后均不得将空白柜号作为业务事实。 */
+    @ParameterizedTest
+    @NullAndEmptySource
+    @ValueSource(strings = {"   ", "\u00a0\u3000"})
+    void rejectsMissingNumber(String containerNo) {
+        assertThatThrownBy(() -> ContainerNumbers.normalizeRequired(containerNo))
+            .isInstanceOf(IllegalArgumentException.class).hasMessageContaining("required");
+        assertThatThrownBy(() -> ContainerNumbers.requireCanonical(containerNo))
+            .isInstanceOf(IllegalArgumentException.class).hasMessageContaining("required");
     }
 }

deploy/scripts/ci-test-scope.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, writeFileSync, statSync } from 'node:fs'
+import { resolve, relative, basename } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const moduleName = 'lastleg-service'
+const testClass = /(?:^Test.+|.+(?:Test|Tests|TestCase))\.java$/
+const words = source => new Set(source.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) || [])
+const tables = source => new Set(source.match(/\bll_[a-z0-9_]+\b/g) || [])
+const writtenTables = source => new Set([...source.matchAll(/\b(?:UPDATE|INSERT\s+(?:IGNORE\s+)?INTO|DELETE\s+FROM)\s+(ll_[a-z0-9_]+)/gi)].map(match => match[1]))
+
+// 按完整注解比较 SQL，避免只改 SELECT 时把同一 Mapper 内未改的全部写语句扩大为全域回归。
+function writeStatements(source) {
+  const result = []
+  for (const match of source.matchAll(/@(?:Insert|Update|Delete)\s*\(/g)) {
+    let depth = 1, quote = '', index = match.index + match[0].length
+    for (; index < source.length && depth; index++) {
+      if (quote) {
+        if (source.startsWith(quote, index)) { index += quote.length - 1; quote = '' }
+        else if (source[index] === '\\' && quote.length === 1) index++
+      } else if (source.startsWith('"""', index)) { quote = '"""'; index += 2 }
+      else if (source[index] === '"' || source[index] === "'") quote = source[index]
+      else if (source[index] === '(') depth++
+      else if (source[index] === ')') depth--
+    }
+    if (depth) throw new Error('Cannot parse SQL annotation; use MODULE test scope')
+    result.push(source.slice(match.index, index))
+  }
+  return result
+}
+
+function changedWrites(node) {
+  if (node.previousSource === undefined) return writtenTables(node.source)
+  const before = writeStatements(node.previousSource), after = writeStatements(node.source)
+  const changed = [...before.filter(sql => !after.includes(sql)), ...after.filter(sql => !before.includes(sql))]
+  const oldRest = before.reduce((text, sql) => text.replace(sql, ''), node.previousSource)
+  const newRest = after.reduce((text, sql) => text.replace(sql, ''), node.source)
+  if (oldRest !== newRest) changed.push(oldRest, newRest)
+  return writtenTables(changed.join('\n'))
+}
+
+/** 宁可扩大范围，不用文件名猜测唯一测试；未识别的输入保留完整模块门禁。 */
+export function planTests({ modules, mode = 'AUTO', changes = [], sources = [], baseline = '' }) {
+  const architectureScript = `${moduleName}/scripts/analyze-lastleg-dependencies`
+  const staticChecks = changes.some(path => path.startsWith(architectureScript))
+    ? [`${architectureScript}.test.mjs`] : []
+  const full = reason => ({ scope: 'MODULE', reason, modules, baseline, tests: [], staticChecks })
+  if (mode !== 'AUTO' && mode !== 'MODULE') throw new Error('TEST_SCOPE must be AUTO or MODULE')
+  if (mode === 'MODULE') return full('显式完整模块回归')
+  if (!baseline) return full('没有成功测试基线')
+  if (modules.length !== 1 || modules[0] !== moduleName) return full('多服务或尚未核对的服务采用完整模块回归')
+  const prefix = `${moduleName}/`
+  const relevant = changes.filter(path => path.startsWith(prefix))
+  const shared = changes.some(path => path !== 'scripts/agents-index-contract.ps1' && !path.startsWith(prefix)
+    && /^(?:common-[^/]+\/|platform-bom\/|pom\.xml$|Jenkinsfile|deploy\/|config\/|scripts\/.*\.(?:mjs|sh|ps1)$)/.test(path))
+  if (shared) return full('公共能力、发布或测试基础设施变更')
+  if (!relevant.length) return full('补跑服务没有可验证的业务差异')
+  const java = `${prefix}src/main/java/com/baiyue/lastleg/`
+  const supported = path => path.startsWith(`${prefix}src/test/java/`)
+    || path.startsWith(`${prefix}src/main/resources/openapi/`)
+    || path.startsWith(architectureScript)
+    || (path.startsWith(java) && path.slice(java.length).includes('/')
+      && !/^(?:config|security|entity|dto|model|mapper|repository|service|client)\//.test(path.slice(java.length)))
+    || /\.(?:md)$/.test(path)
+  if (relevant.some(path => !supported(path))) return full('共享模型、配置、SQL、资源或未识别路径变更')
+
+  const nodes = sources.map(({ path, source, previousSource }) => ({ path, source, previousSource,
+    symbol: basename(path, '.java'), tokens: words(source), tables: tables(source),
+    test: path.startsWith(`${prefix}src/test/java/`),
+    name: `${source.match(/\bpackage\s+([\w.]+)\s*;/)?.[1] || ''}.${basename(path, '.java')}` }))
+  const byPath = new Map(nodes.map(node => [node.path, node]))
+  const bySymbol = new Map()
+  for (const node of nodes) {
+    if (!bySymbol.has(node.symbol)) bySymbol.set(node.symbol, [])
+    bySymbol.get(node.symbol).push(node)
+  }
+  const reverse = new Map(nodes.map(node => [node.path, new Set()]))
+  for (const node of nodes) {
+    // 包含反射字符串、静态 import、同包引用及测试夹具；重名类全部纳入。
+    for (const token of node.tokens) for (const dependency of bySymbol.get(token) || []) {
+      if (dependency !== node) reverse.get(dependency.path).add(node.path)
+    }
+    // 实现变化也要覆盖只依赖接口/基类的调用者，不能仅沿显式 import 反查。
+    for (const match of node.source.matchAll(/\b(?:implements|extends)\s+([^{};]+)/g)) {
+      for (const token of words(match[1])) for (const contract of bySymbol.get(token) || []) {
+        if (contract !== node) reverse.get(node.path).add(contract.path)
+      }
+    }
+  }
+  const seeds = new Set()
+  const changedTables = new Set()
+  for (const path of relevant.filter(path => path.endsWith('.java'))) {
+    const node = byPath.get(path)
+    if (node) {
+      seeds.add(path)
+      // 读查询变化不改变其他查询的数据；潜在写入变化则纳入同表读写消费者。
+      if (!node.test) for (const table of changedWrites(node)) changedTables.add(table)
+    } else {
+      // 删除/移动旧类型时，仍按旧类名查现存消费者。
+      const symbol = basename(path, '.java')
+      const consumers = nodes.filter(consumer => consumer.tokens.has(symbol))
+      if (!consumers.length) return full('删除类型缺少可追踪的现存消费者')
+      for (const consumer of consumers) seeds.add(consumer.path)
+    }
+  }
+  if (!seeds.size) return full('没有可追踪的 Java 行为差异')
+  for (const node of nodes) if ([...node.tables].some(table => changedTables.has(table))) seeds.add(node.path)
+  const affected = new Set(seeds)
+  const queue = [...seeds]
+  for (let index = 0; index < queue.length; index++) {
+    for (const consumer of reverse.get(queue[index]) || []) if (!affected.has(consumer)) {
+      affected.add(consumer); queue.push(consumer)
+    }
+  }
+  const allTests = nodes.filter(node => node.test && testClass.test(basename(node.path))
+    && /@(?:Test|ParameterizedTest|RepeatedTest|TestFactory|TestTemplate)\b/.test(node.source))
+  const contractChange = relevant.some(path => path.startsWith(`${prefix}src/main/resources/openapi/`))
+  const candidates = allTests.filter(node => affected.has(node.path)
+    || /(?:Security|Isolation|MapperRegistrationArchitecture|QueryBinding)/.test(node.symbol)
+    || (contractChange && /(?:Contract|OpenApi|Schema|Architecture|Permission)/.test(node.symbol)))
+  // 显式依赖真实环境的类仍由 MODULE/专项授权入口负责，不能把它们默认跳过算作执行成功。
+  const optIn = node => /@(?:EnabledIf(?:SystemProperty|EnvironmentVariable)|Disabled(?:IfSystemProperty|IfEnvironmentVariable)?\b)/
+    .test(node.source.slice(0, node.source.indexOf(`class ${node.symbol}`)))
+  const tests = candidates.filter(node => !optIn(node))
+  if (!tests.some(node => affected.has(node.path))) return full('没有匹配到行为测试，拒绝零测试通过')
+  if (tests.some(node => !/^com\.[\w.$]+$/.test(node.name))) return full('测试类名无法安全传入 Maven')
+  return { scope: 'AFFECTED', reason: 'Java 反向引用、接口实现、测试夹具、共享 SQL 表和相关静态合同',
+    modules, baseline, tests: tests.map(node => node.name).sort(), totalTests: allTests.length, staticChecks,
+    optInTests: candidates.filter(optIn).map(node => node.name).sort() }
+}
+
+function walk(root) {
+  const files = []
+  for (const item of readdirSync(root, { withFileTypes: true })) {
+    const path = resolve(root, item.name)
+    if (item.isDirectory()) files.push(...walk(path))
+    else if (item.isFile() && item.name.endsWith('.java')) files.push(path)
+  }
+  return files
+}
+
+/** 每个所选类必须有本轮实际执行的报告；允许上游零匹配不能变成整个门禁零测试。 */
+export function verifyReports(plan, reports) {
+  if (plan.scope !== 'AFFECTED') return
+  for (const name of plan.tests) {
+    const matches = reports.filter(report => report.name === name || report.name.startsWith(`${name}$`))
+    if (!matches.length || matches.some(report => report.failures || report.errors
+      || ['tests', 'skipped', 'failures', 'errors'].some(key => !Number.isInteger(report[key]) || report[key] < 0)
+      || report.skipped > report.tests)
+      || matches.reduce((sum, report) => sum + report.tests - report.skipped, 0) <= 0) {
+      throw new Error(`Missing, skipped or failed fresh test report: ${name}`)
+    }
+  }
+}
+
+function main(args) {
+  const [action, ...options] = args
+  const values = {}
+  for (let i = 0; i < options.length; i += 2) {
+    if (!options[i].startsWith('--') || options[i + 1] === undefined) throw new Error('Expected --name value')
+    values[options[i].slice(2)] = options[i + 1]
+  }
+  const root = process.cwd()
+  const planFile = values.plan
+  if (!planFile) throw new Error('--plan is required')
+  if (action === 'plan') {
+    const modules = (values.modules || '').split(',')
+    if (modules.some(module => !/^[a-z][a-z0-9-]+$/.test(module))) throw new Error('Invalid modules')
+    let baseline = values.base || ''
+    let changes = []
+    if (baseline) {
+      if (!/^[0-9a-f]{7,40}$/i.test(baseline)) throw new Error('Invalid baseline commit')
+      try {
+        execFileSync('git', ['merge-base', '--is-ancestor', baseline, 'HEAD'], { stdio: 'pipe' })
+        changes = execFileSync('git', ['diff', '--name-only', '-z', baseline, 'HEAD'], { encoding: 'utf8' }).split('\0').filter(Boolean)
+      } catch { baseline = '' }
+    }
+    const sources = modules.length === 1 && modules[0] === moduleName
+      ? ['main', 'test'].flatMap(set => walk(resolve(root, moduleName, 'src', set, 'java')))
+        .map(path => {
+          const key = relative(root, path).replaceAll('\\', '/')
+          const entry = { path: key, source: readFileSync(path, 'utf8') }
+          if (baseline && changes.includes(key)) {
+            try { entry.previousSource = execFileSync('git', ['show', `${baseline}:${key}`], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }) }
+            catch { entry.previousSource = '' }
+          }
+          return entry
+        }) : []
+    const plan = { ...planTests({ modules, mode: values.mode || 'AUTO', baseline, changes, sources }), startedAt: Date.now() }
+    writeFileSync(planFile, JSON.stringify(plan))
+    console.log(`CI test scope: ${plan.scope}; ${plan.reason}`)
+    if (plan.scope === 'AFFECTED') console.log(`Selected ${plan.tests.length}/${plan.totalTests} test classes:\n${plan.tests.join('\n')}`)
+    if (plan.optInTests?.length) console.log(`Explicit environment tests remain opt-in (not counted as passed): ${plan.optInTests.join(',')}`)
+    return
+  }
+  const plan = JSON.parse(readFileSync(planFile, 'utf8'))
+  if (action === 'args') {
+    if (plan.scope === 'AFFECTED') process.stdout.write(`-Dtest=${plan.tests.join(',')} -Dsurefire.failIfNoSpecifiedTests=false -Dci.sql-semantic.skip=true`)
+  } else if (action === 'checks') {
+    for (const check of plan.staticChecks || []) {
+      if (check !== `${moduleName}/scripts/analyze-lastleg-dependencies.test.mjs`) throw new Error('Unsupported static check')
+      execFileSync(process.execPath, ['--test', '--test-concurrency=2', check], { stdio: 'inherit' })
+    }
+  } else if (action === 'verify') {
+    const reports = []
+    if (plan.scope === 'AFFECTED') for (const module of plan.modules) {
+      const directory = resolve(root, module, 'target/surefire-reports')
+      for (const filename of readdirSync(directory)) {
+        if (!/^TEST-.*\.xml$/.test(filename)) continue
+        const path = resolve(directory, filename)
+        if (statSync(path).mtimeMs < plan.startedAt - 2000) continue
+        const xml = readFileSync(path, 'utf8').match(/<testsuite\b([^>]+)>/)?.[1]
+        if (!xml) continue
+        const attrs = Object.fromEntries([...xml.matchAll(/([\w-]+)="([^"]*)"/g)].map(match => [match[1], match[2]]))
+        reports.push({ name: attrs.name || '', ...Object.fromEntries(['tests', 'failures', 'errors', 'skipped'].map(key => [key, Number(attrs[key] || 0)])) })
+      }
+    }
+    verifyReports(plan, reports)
+    console.log(`CI test reports verified: ${plan.scope}`)
+  } else throw new Error(`Unknown action: ${action}`)
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { main(process.argv.slice(2)) } catch (error) { console.error(error.message); process.exitCode = 1 }
+}

deploy/sql/README.md

@@ -1,5 +1,11 @@
 # 单测试环境数据库空库初始化
 
+车辆与司机档案照片复用：先执行 `lastleg-fleet-resource-photos.sql` 新增照片版本表，再配套发布 File、Lastleg 和 Admin。车辆详情／司机详情维护照片，排车保存时复制缺失照片为当趟证据；已有照片不被后续档案替换覆盖。驾驶证统一接受 PDF/JPG/PNG。源基线与海外空库基线已同步；本次未执行环境 SQL 或部署。
+
+放舱后预计到港窄维护需要配套更新 `trg_ocean_booking_before_update`：仅从冻结比较中移除 `estimated_arrival_at`，其余运输、预报、关系方及柜型冻结不变。定义已同步 `firstleg/src/main/resources/db/phase3-ocean-booking-schema.sql` 与国内统一基线；已有 TEST 需另行审阅并授权替换该触发器，不重放空库文件，不回填数据。本轮只准备定义，未执行 SQL 或部署。
+
+货柜关联已放舱订舱时不再限制 ISO 柜号格式，Firstleg 模块基线与国内统一空库基线已移除 `chk_container_booking_iso6346`，保留同订舱柜号唯一键。既有 TEST 发布前需核对并单独授权移除该约束：`ALTER TABLE baiyue_firstleg.fl_container_booking DROP CHECK chk_container_booking_iso6346;`。配套发布 Firstleg 与 Admin；不重放空库初始化、不修改业务数据。本次仅准备源码与 SQL 定义，未执行环境 SQL 或部署。
+
 仓储转运到仓取货、本土卡车接入现有排车的**可重复执行汇总SQL**为 `lastleg-dispatch-transport-tasks.sql`，文件内固定 `USE baiyue_lastleg`，对已存在字段、表安全跳过。新增 `ll_dispatch_order.task_type` 字段、`ll_dispatch_truck_task`、`ll_dispatch_transport_create`、`ll_dispatch_transport_command` 三张表，并确保既有正式排车单号日流水表存在；不回填或删除业务数据。前置是目标库已具备现有整车排车主表、FleetTrip、取货任务及本土卡车原单结构。按序先执行此 SQL，再配套发布 Lastleg 与 Admin；取消释放有效原单关联、完成保留关联。`migrations/overseas/baiyue_lastleg/V32__dispatch_transport_tasks.sql` 是迁移系统中的新增结构记录。本次仅在已授权本机执行并验收，不代表远端已部署。
 
 排车单号使用`PCyyyyMMdd0001`，日期取`Asia/Shanghai`，全平台跨客户/仓库共用独立日流水。`ll_dispatch_daily_sequence`同步Lastleg源基线与海外空库基线；已有结构的定向新增入口为`lastleg-dispatch-daily-sequence.sql`，只建序列表，不改已有业务号、不回填历史、不重放空库初始化。源码和DDL须配套发布；文件存在不表示已执行或部署。流水在独立短事务分配，回滚或取消不复用，四位范围每日0001至9999，准确单量以主单统计为准。
@@ -52,6 +58,10 @@
 
 换标直接出库的实物体积快照在 `ll_outbound_order.volume_cbm`、`ll_outbound_pallet_item.volume_cbm`、`ll_delivery_order.total_volume_cbm` 三列均允许 NULL，表示来源尚未确认；已有实盘尺寸按箱计算，不能用默认 0 代替未知，也不按 SKU 件数重复累计。两份初始化基线同步此定义，已有 TEST 只能在核对结构和授权后精确调整这三列，不重放空库文件或回填历史行。
 
+排车内部散板需求发布选项由 `lastleg-service/src/main/resources/db/dispatch-capacity-demand.sql` 提供精确结构变更：仅向 `ll_dispatch_order` 新增默认勾选的 `publish_looseboard_demand` 列，Lastleg与海外空库基线同步。该文件不是自动启动脚本；执行须单独授权，不能重放完整空库文件，不新增业务数据回填或清理。实际执行与部署状态仍归测试环境主契约。
+
+订舱委/实资料在 `firstleg/src/main/resources/db/phase3-ocean-booking-schema.sql` 与国内统一空库基线同步维护：订舱主表增加条款、包装、品名、唛头和委/实三项货量，关系方增加邮箱、税号；已放舱主表触发器仅允许实际货量及更新审计元数据变化，运输、预报和创建信息冻结。匹配发布单元为 Firstleg 与 Admin；Print 继续使用现有模板。本轮只准备初始化定义，不执行 SQL、不回填测试存量、不提供新旧兼容。已有测试库须另行审阅、授权结构更新，不能重放完整空库基线。
+
 ## 唯一入口与区域边界
 
 V13 收货覆盖由 `lastleg-service/src/main/resources/db/appointment-receiving.sql` 提供四表：独立收货预约、当前/历史客户成员、待确认变化和不可变覆盖版本；同步 Lastleg 与海外空库基线。有效外部约号唯一性归收货预约的目的仓与约号，批次头表不再独立占用约号。部署前必须核对四表及旧头表唯一索引；本批只准备基线，不提供测试存量回填或自动重置。旧 `reset-test-fba-appointments.sql` 已拒绝存在这些新表的环境，不能用于重放 V13 初始化。实际 SQL 与部署须逐项授权。

deploy/sql/lastleg-fleet-resource-photos.sql

@@ -0,0 +1,16 @@
+-- 仅新增车辆及司机档案照片版本表，可重复执行，不回填业务数据。
+USE baiyue_lastleg;
+
+CREATE TABLE IF NOT EXISTS ll_fleet_resource_photo (
+  resource_kind VARCHAR(16) NOT NULL COMMENT '档案类型：车辆或司机',
+  resource_id BIGINT NOT NULL COMMENT '车辆或司机档案标识',
+  record_version BIGINT NOT NULL COMMENT '照片版本，从一递增',
+  file_id BIGINT NOT NULL COMMENT '文件服务照片标识',
+  file_name VARCHAR(512) NOT NULL COMMENT '照片原始文件名',
+  content_type VARCHAR(64) NOT NULL COMMENT '照片媒体类型',
+  size_bytes BIGINT NOT NULL COMMENT '照片字节数',
+  created_by VARCHAR(64) NOT NULL COMMENT '上传操作人标识',
+  created_at DATETIME(3) NOT NULL COMMENT '上传时间（UTC）',
+  PRIMARY KEY (resource_kind, resource_id, record_version),
+  UNIQUE KEY uk_fleet_resource_photo_file (resource_kind, resource_id, file_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆及司机档案照片版本记录';

deploy/sql/migrations/overseas/baiyue_lastleg/V34__fleet_resource_photos.sql

@@ -0,0 +1,14 @@
+
+CREATE TABLE IF NOT EXISTS ll_fleet_resource_photo (
+  resource_kind VARCHAR(16) NOT NULL COMMENT '档案类型：车辆或司机',
+  resource_id BIGINT NOT NULL COMMENT '车辆或司机档案标识',
+  record_version BIGINT NOT NULL COMMENT '照片版本，从一递增',
+  file_id BIGINT NOT NULL COMMENT '文件服务照片标识',
+  file_name VARCHAR(512) NOT NULL COMMENT '照片原始文件名',
+  content_type VARCHAR(64) NOT NULL COMMENT '照片媒体类型',
+  size_bytes BIGINT NOT NULL COMMENT '照片字节数',
+  created_by VARCHAR(64) NOT NULL COMMENT '上传操作人标识',
+  created_at DATETIME(3) NOT NULL COMMENT '上传时间（UTC）',
+  PRIMARY KEY (resource_kind, resource_id, record_version),
+  UNIQUE KEY uk_fleet_resource_photo_file (resource_kind, resource_id, file_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆及司机档案照片版本记录';

deploy/sql/头程数据库统一增量-MySQL8.sql

@@ -1484,7 +1484,6 @@ CREATE TABLE fl_container_booking (
   KEY idx_container_booking_voyage (voyage_no,updated_at),
   KEY idx_container_booking_transit_summary (actual_sailing_at,actual_warehouse_arrival_at,ocean_booking_id,container_type),
   CONSTRAINT chk_container_booking_capacity CHECK (((capacity_cbm is null) or (capacity_cbm > 0))),
-  CONSTRAINT chk_container_booking_iso6346 CHECK (((container_no is null) or regexp_like(container_no,_utf8mb4'^[A-Z]{3}[UJZ][0-9]{7}$'))),
   CONSTRAINT chk_container_booking_pickup_code CHECK (((pickup_code is null) or regexp_like(pickup_code,_utf8mb4'^[0-9]{1,64}$'))),
   CONSTRAINT chk_container_booking_record_status CHECK ((record_status in (_utf8mb4'ACTIVE',_utf8mb4'MERGED'))),
   CONSTRAINT chk_container_booking_source CHECK ((source_type in (_utf8mb4'SIMULATION',_utf8mb4'OCEAN_BOOKING'))),
@@ -3442,7 +3441,7 @@ CREATE TABLE fl_mojia_measurement_receipt (
 CREATE TABLE fl_ocean_booking (
   id bigint unsigned NOT NULL COMMENT '海运订舱ID',
   booking_no varchar(40) NOT NULL COMMENT '平台海运订舱编号',
-  status varchar(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已发布且永久只读',
+  status varchar(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已放舱，运输快照冻结且实货量受控补录',
   customer_id bigint unsigned DEFAULT NULL COMMENT '客户ID和数据隔离键',
   customer_name varchar(128) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '客户名称快照',
   channel_code varchar(64) DEFAULT NULL COMMENT '订舱计划物流渠道组编码快照',
@@ -3465,6 +3464,17 @@ CREATE TABLE fl_ocean_booking (
   estimated_sailing_at datetime(3) DEFAULT NULL COMMENT '当前确认预计开船时间',
   estimated_arrival_at datetime(3) DEFAULT NULL COMMENT '当前确认预计到港时间',
   remark varchar(1000) DEFAULT NULL COMMENT '平台内部备注',
+  freight_term VARCHAR(64) NULL COMMENT '运费条款',
+  service_term VARCHAR(64) NULL COMMENT '运输条款',
+  package_unit VARCHAR(16) NULL COMMENT '包装单位：CARTONS、PCS或PALLETS',
+  cargo_description VARCHAR(1000) NULL COMMENT '货物品名及托运要求',
+  marks_and_nos VARCHAR(1000) NULL COMMENT '唛头和号码',
+  declared_package_count INT UNSIGNED NULL COMMENT '订舱预报件数（委）',
+  declared_gross_weight_kg DECIMAL(15,3) NULL COMMENT '订舱预报毛重kg（委）',
+  declared_volume_cbm DECIMAL(15,3) NULL COMMENT '订舱预报体积cbm（委）',
+  actual_package_count INT UNSIGNED NULL COMMENT '客服手工实货件数',
+  actual_gross_weight_kg DECIMAL(15,3) NULL COMMENT '客服手工实货毛重kg',
+  actual_volume_cbm DECIMAL(15,3) NULL COMMENT '客服手工实货体积cbm',
   created_by bigint unsigned NOT NULL COMMENT '创建操作人ID',
   created_by_name varchar(64) DEFAULT NULL COMMENT '创建操作人姓名快照',
   created_at datetime(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '订舱记录创建时间',
@@ -3479,6 +3489,14 @@ CREATE TABLE fl_ocean_booking (
   KEY idx_ocean_booking_voyage (vessel_name,voyage_no,updated_at),
   CONSTRAINT chk_ocean_booking_carrier_code CHECK (((carrier_code is null) or (carrier_code in (_utf8mb4'MATSON',_utf8mb4'SML',_utf8mb4'ZIM',_utf8mb4'COSCO',_utf8mb4'EMC',_utf8mb4'HEDE',_utf8mb4'OTHER')))),
   CONSTRAINT chk_ocean_booking_customer CHECK ((customer_id > 0)),
+  CONSTRAINT chk_ocean_booking_cargo CHECK (
+    (package_unit IS NULL OR package_unit IN ('CARTONS','PCS','PALLETS'))
+    AND (declared_package_count IS NULL OR declared_package_count BETWEEN 1 AND 999999999)
+    AND (actual_package_count IS NULL OR actual_package_count BETWEEN 1 AND 999999999)
+    AND (declared_gross_weight_kg IS NULL OR declared_gross_weight_kg > 0)
+    AND (actual_gross_weight_kg IS NULL OR actual_gross_weight_kg > 0)
+    AND (declared_volume_cbm IS NULL OR declared_volume_cbm > 0)
+    AND (actual_volume_cbm IS NULL OR actual_volume_cbm > 0)),
   CONSTRAINT chk_ocean_booking_schedule CHECK (((estimated_sailing_at is null) or (estimated_arrival_at is null) or (estimated_arrival_at >= estimated_sailing_at))),
   CONSTRAINT chk_ocean_booking_status CHECK ((status in (_utf8mb4'DRAFT',_utf8mb4'RELEASED')))
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='独立海运订舱聚合；柜次仍由fl_container_booking承载';
@@ -3565,6 +3583,8 @@ CREATE TABLE fl_ocean_booking_party (
   address varchar(1000) DEFAULT NULL COMMENT '关系方地址快照',
   contact_name varchar(128) DEFAULT NULL COMMENT '关系方联系人快照',
   contact_phone varchar(64) DEFAULT NULL COMMENT '关系方联系电话快照',
+  contact_email VARCHAR(255) NULL COMMENT '关系方联系邮箱',
+  tax_no VARCHAR(128) NULL COMMENT '关系方税号',
   PRIMARY KEY (id),
   UNIQUE KEY uk_ocean_booking_party (ocean_booking_id,party_type),
   CONSTRAINT fk_ocean_booking_party FOREIGN KEY (ocean_booking_id) REFERENCES fl_ocean_booking (id) ON DELETE CASCADE,
@@ -6026,9 +6046,48 @@ CREATE TRIGGER trg_ocean_allocation_before_insert BEFORE INSERT ON fl_ocean_book
   END IF;
 END$$
 
-CREATE TRIGGER trg_ocean_booking_before_update BEFORE UPDATE ON fl_ocean_booking FOR EACH ROW BEGIN
-  IF OLD.status = 'RELEASED' THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱订舱不可修改';
+CREATE TRIGGER trg_ocean_booking_before_update BEFORE UPDATE ON fl_ocean_booking FOR EACH ROW
+BEGIN
+  -- 已放舱只允许预计到港、实货量及审计元数据变化，其余运输和预报快照保持冻结。
+  IF OLD.status = 'RELEASED' AND NOT (
+    (NEW.id <=> OLD.id)
+    AND (NEW.booking_no <=> OLD.booking_no)
+    AND (NEW.status <=> OLD.status)
+    AND (NEW.customer_id <=> OLD.customer_id)
+    AND (NEW.customer_name <=> OLD.customer_name)
+    AND (NEW.channel_code <=> OLD.channel_code)
+    AND (NEW.channel_name <=> OLD.channel_name)
+    AND (NEW.warehouse_id <=> OLD.warehouse_id)
+    AND (NEW.warehouse_name <=> OLD.warehouse_name)
+    AND (NEW.bill_of_lading_no <=> OLD.bill_of_lading_no)
+    AND (NEW.shipping_company_id <=> OLD.shipping_company_id)
+    AND (NEW.shipping_company_name <=> OLD.shipping_company_name)
+    AND (NEW.carrier_code <=> OLD.carrier_code)
+    AND (NEW.booking_agent_id <=> OLD.booking_agent_id)
+    AND (NEW.booking_agent_name <=> OLD.booking_agent_name)
+    AND (NEW.vessel_name <=> OLD.vessel_name)
+    AND (NEW.voyage_no <=> OLD.voyage_no)
+    AND (NEW.departure_port_code <=> OLD.departure_port_code)
+    AND (NEW.departure_port_name <=> OLD.departure_port_name)
+    AND (NEW.destination_port_code <=> OLD.destination_port_code)
+    AND (NEW.destination_port_name <=> OLD.destination_port_name)
+    AND (NEW.place_of_delivery <=> OLD.place_of_delivery)
+    AND (NEW.estimated_sailing_at <=> OLD.estimated_sailing_at)
+    AND (NEW.remark <=> OLD.remark)
+    AND (NEW.freight_term <=> OLD.freight_term)
+    AND (NEW.service_term <=> OLD.service_term)
+    AND (NEW.package_unit <=> OLD.package_unit)
+    AND (NEW.cargo_description <=> OLD.cargo_description)
+    AND (NEW.marks_and_nos <=> OLD.marks_and_nos)
+    AND (NEW.declared_package_count <=> OLD.declared_package_count)
+    AND (NEW.declared_gross_weight_kg <=> OLD.declared_gross_weight_kg)
+    AND (NEW.declared_volume_cbm <=> OLD.declared_volume_cbm)
+    AND (NEW.created_by <=> OLD.created_by)
+    AND (NEW.created_by_name <=> OLD.created_by_name)
+    AND (NEW.created_at <=> OLD.created_at)
+    AND NEW.version = OLD.version + 1
+  ) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱仅允许维护预计到港及补录实货量';
   END IF;
   IF OLD.status <> NEW.status AND NOT (
        (OLD.status='DRAFT' AND NEW.status='RELEASED')) THEN

deploy/sql/海外区域统一增量-MySQL8.sql

@@ -417,6 +417,7 @@ CREATE TABLE ll_dispatch_order (
   id BIGINT NOT NULL COMMENT '整车排车主单内部主键',
   dispatch_no VARCHAR(64) NOT NULL COMMENT '真实排车业务号',
   task_type VARCHAR(32) NOT NULL DEFAULT 'DELIVERY' COMMENT '任务类型：仓库派送、到仓取货、本土卡车',
+  publish_looseboard_demand TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否向内部散板需求池发布余位',
   trip_id BIGINT NOT NULL COMMENT '本趟唯一车辆资源记录ID',
   overseas_warehouse_id VARCHAR(128) NOT NULL COMMENT '真实起运海外仓ID',
   overseas_warehouse_code VARCHAR(128) NULL COMMENT '起运海外仓编码快照',
@@ -4986,4 +4987,19 @@ CREATE TABLE ll_document_sequence (
   CONSTRAINT chk_ll_document_sequence_value CHECK (current_value > 0)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='业务单据每日独立原子流水';
 
-SELECT 'PASS' AS initialization_status, 'OVERSEAS' AS region, 234 AS initialized_tables;
+
+CREATE TABLE ll_fleet_resource_photo (
+  resource_kind VARCHAR(16) NOT NULL COMMENT '档案类型：车辆或司机',
+  resource_id BIGINT NOT NULL COMMENT '车辆或司机档案标识',
+  record_version BIGINT NOT NULL COMMENT '照片版本，从一递增',
+  file_id BIGINT NOT NULL COMMENT '文件服务照片标识',
+  file_name VARCHAR(512) NOT NULL COMMENT '照片原始文件名',
+  content_type VARCHAR(64) NOT NULL COMMENT '照片媒体类型',
+  size_bytes BIGINT NOT NULL COMMENT '照片字节数',
+  created_by VARCHAR(64) NOT NULL COMMENT '上传操作人标识',
+  created_at DATETIME(3) NOT NULL COMMENT '上传时间（UTC）',
+  PRIMARY KEY (resource_kind, resource_id, record_version),
+  UNIQUE KEY uk_fleet_resource_photo_file (resource_kind, resource_id, file_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆及司机档案照片版本记录';
+
+SELECT 'PASS' AS initialization_status, 'OVERSEAS' AS region, 235 AS initialized_tables;

file/src/main/java/com/baiyue/file/service/BusinessFileCategory.java

@@ -7,6 +7,8 @@ import java.util.Arrays;
 
 /** File-owned storage policy. Business visibility and lifecycle remain in the calling service. */
 enum BusinessFileCategory {
+    FLEET_VEHICLE_PHOTO(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
+    FLEET_DRIVER_PHOTO(false, FormatPolicy.IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     FLEET_DRIVER_LICENSE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     FLEET_TRIP_OPERATION_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
     OVERSEAS_DISPATCH_VEHICLE_EVIDENCE(false, FormatPolicy.PDF_IMAGE, Limits.STANDARD, BusinessIdPolicy.POSITIVE_LONG),
@@ -90,7 +92,7 @@ enum BusinessFileCategory {
         if (this == FINANCE_VEHICLE_VOUCHER && tenantId != 0) {
             throw new BizException(ResultCode.BAD_REQUEST, "公司车辆付款凭证必须归属平台");
         }
-        if (this == FLEET_VEHICLE_RECORD_PHOTO && tenantId != 0) {
+        if ((this == FLEET_VEHICLE_RECORD_PHOTO || this == FLEET_VEHICLE_PHOTO || this == FLEET_DRIVER_PHOTO) && tenantId != 0) {
             throw new BizException(ResultCode.BAD_REQUEST, "车辆运维照片必须归属平台");
         }
         if (this == FLEET_DRIVER_LICENSE && tenantId != 0) {

file/src/main/resources/openapi/fleet-resource-photo-v1.yaml

@@ -0,0 +1,88 @@
+openapi: 3.0.3
+info:
+  title: 车辆与司机档案照片内部文件契约
+  version: 1.0.0
+  description: >-
+    复用InternalBusinessFileController，固定平台tenantId=0、businessType=FLEET_VEHICLE_PHOTO或FLEET_DRIVER_PHOTO、
+    businessId=对应车辆或司机内部ID。Lastleg负责档案存在性、列表/维护权限、版本关联和历史可见性；
+    File校验内部服务令牌、平台复合归属、真实非空文件、MIME与签名。最大10MiB，仅JPG/PNG。
+    上传只生成不可变对象，不改变驾驶证审核结论，不生成公开URL，排车保存时复制为本趟证据，后续档案替换不改历史排车。
+security:
+  - InternalServiceToken: []
+paths:
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+    post:
+      summary: 上传车辆或司机档案照片
+      parameters:
+        - {name: X-Operator-Id, in: header, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file: {type: string, format: binary}
+      responses:
+        '200': {$ref: '#/components/responses/Metadata'}
+        '403': {description: 内部服务令牌无效}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+      - {$ref: '#/components/parameters/FileId'}
+    get:
+      summary: 校验归属并读取元数据
+      responses:
+        '200': {$ref: '#/components/responses/Metadata'}
+        '403': {description: 内部服务令牌无效}
+  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}/content:
+    parameters:
+      - {$ref: '#/components/parameters/TenantId'}
+      - {$ref: '#/components/parameters/BusinessType'}
+      - {$ref: '#/components/parameters/BusinessId'}
+      - {$ref: '#/components/parameters/FileId'}
+    get:
+      summary: 校验归属并下载真实文件
+      responses:
+        '200':
+          description: 文件内容，业务错误按JSON code识别
+          content:
+            image/jpeg: {schema: {type: string, format: binary}}
+            image/png: {schema: {type: string, format: binary}}
+        '403': {description: 内部服务令牌无效}
+components:
+  securitySchemes:
+    InternalServiceToken: {type: apiKey, in: header, name: X-Internal-Service-Token}
+  parameters:
+    TenantId: {name: tenantId, in: path, required: true, schema: {type: string, enum: ['0']}}
+    BusinessType: {name: businessType, in: path, required: true, schema: {type: string, enum: [FLEET_VEHICLE_PHOTO, FLEET_DRIVER_PHOTO]}}
+    BusinessId: {name: businessId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+    FileId: {name: fileId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+  responses:
+    Metadata:
+      description: 统一响应；业务成功code为200，复合归属不匹配按业务错误返回
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              code: {type: string}
+              message: {type: string, nullable: true}
+              data:
+                type: object
+                properties:
+                  fileId: {type: string}
+                  tenantId: {type: string, enum: ['0']}
+                  businessType: {type: string, enum: [FLEET_VEHICLE_PHOTO, FLEET_DRIVER_PHOTO]}
+                  businessId: {type: string}
+                  fileName: {type: string}
+                  sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+                  contentType: {type: string, enum: [image/jpeg, image/png]}
+                  sizeBytes: {type: integer, format: int64, minimum: 1, maximum: 10485760}

file/src/test/java/com/baiyue/file/service/FleetResourcePhotoCategoryTest.java

@@ -0,0 +1,16 @@
+package com.baiyue.file.service;
+
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.*;
+
+class FleetResourcePhotoCategoryTest {
+    @Test void profilePhotosOnlyAllowPlatformImagesAndPositiveResourceIdentities() {
+        for(var category : new BusinessFileCategory[]{BusinessFileCategory.FLEET_VEHICLE_PHOTO,BusinessFileCategory.FLEET_DRIVER_PHOTO}) {
+            category.validateOwner(0);
+            assertThatThrownBy(() -> category.validateOwner(1)).hasMessageContaining("平台");
+            assertThat(category.formatPolicy()).isEqualTo(BusinessFileCategory.FormatPolicy.IMAGE);
+            assertThat(category.maxSizeBytes()).isEqualTo(10L*1024*1024);
+            assertThatThrownBy(() -> category.storageBusinessId("not-a-resource")).isInstanceOf(RuntimeException.class);
+        }
+    }
+}

finance/src/main/java/com/baiyue/finance/mapper/FinanceFeeSourceReadMapper.java

@@ -0,0 +1,60 @@
+package com.baiyue.finance.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import java.util.List;
+import java.util.Map;
+
+/** 费用池按稳定来源读取当前版本，历史快照保留在同一费用的操作记录中。 */
+@Mapper
+public interface FinanceFeeSourceReadMapper {
+    String GENERATED = "(EXISTS(SELECT 1 FROM fin_bill_line bl WHERE bl.source_id=f.id AND bl.source_version=f.source_fee_version))";
+    String STATUS = "CASE WHEN f.status='AVAILABLE' AND " + GENERATED + " THEN 'BILLED' ELSE f.status END";
+    String BUSINESS_DATE = "CAST(JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.businessDate')) AS DATE)";
+    String FILTER = " FROM fin_fee_source f WHERE 1=1 " +
+        "<if test=\"status == null or status != 'SUPERSEDED'\">" +
+        " AND f.status&lt;&gt;'SUPERSEDED' AND NOT EXISTS(SELECT 1 FROM fin_fee_source newer" +
+        " WHERE newer.source_system=f.source_system AND newer.source_type=f.source_type" +
+        " AND newer.source_fee_id=f.source_fee_id AND newer.source_fee_version&gt;f.source_fee_version)" +
+        "</if>" +
+        "<if test='customerId != null'> AND f.customer_id=#{customerId}</if>" +
+        "<if test='direction != null'> AND f.direction=#{direction}</if>" +
+        "<if test='reviewStatus != null'> AND f.review_status=#{reviewStatus}</if>" +
+        "<if test='status != null'> AND " + STATUS + "=#{status}</if>" +
+        "<if test='statementGenerated != null'> AND " + GENERATED + "=#{statementGenerated}</if>" +
+        "<if test='dateFrom != null'> AND " + BUSINESS_DATE + "&gt;=#{dateFrom}</if>" +
+        "<if test='dateTo != null'> AND " + BUSINESS_DATE + "&lt;=#{dateTo}</if>" +
+        "<if test='keyword != null'> AND (f.source_no LIKE CONCAT('%',#{keyword},'%')" +
+        " OR f.fee_item_name LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.customerName')) LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.inboundCode')) LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.containerNo')) LIKE CONCAT('%',#{keyword},'%')" +
+        " OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.supplierName')) LIKE CONCAT('%',#{keyword},'%'))</if>";
+
+    /** 筛选和计数共用当前版本条件，不能先分页再去重。 */
+    @Select("<script>SELECT COUNT(*)" + FILTER + "</script>")
+    long count(Map<String, Object> filters);
+
+    /** 应收、应付分别展示当前快照；同名但来源费用号不同的费用不合并。 */
+    @Select("<script>SELECT f.*," + GENERATED + " statement_generated," + STATUS + " effective_status" + FILTER +
+        " ORDER BY " + BUSINESS_DATE + " DESC,f.id DESC LIMIT #{limit} OFFSET #{offset}</script>")
+    List<Map<String, Object>> list(Map<String, Object> filters);
+
+    String LINEAGE = " FROM fin_fee_source anchor JOIN fin_fee_source f ON f.source_system=anchor.source_system" +
+        " AND f.source_type=anchor.source_type AND f.source_fee_id=anchor.source_fee_id" +
+        " AND f.customer_id=anchor.customer_id AND f.direction=anchor.direction" +
+        " AND f.source_fee_version&lt;=anchor.source_fee_version";
+
+    /** 旧版本链接只读取当时及此前快照，不把后续调整倒灌到历史单据。 */
+    @Select("<script>SELECT f.id,f.source_fee_version,f.amount,f.currency_code,f.created_at" + LINEAGE +
+        " WHERE anchor.id=#{id} AND anchor.customer_id=#{customerId}" +
+        " AND f.source_system IN ('FIRSTLEG','LASTLEG') ORDER BY f.source_fee_version,f.id</script>")
+    List<Map<String, Object>> versions(@Param("customerId") long customerId, @Param("id") long id);
+
+    /** 按来源身份串起历次审核和操作，客户与方向边界不能被同名费用跨越。 */
+    @Select("<script>SELECT a.id,a.created_at,a.action,a.operator_name_snapshot,a.reason,a.before_data,a.after_data" + LINEAGE +
+        " JOIN fin_audit_log a ON a.tenant_id=f.customer_id AND a.resource_type='FIN_FEE_SOURCE' AND a.resource_id=f.id" +
+        " WHERE anchor.id=#{id} AND anchor.customer_id=#{customerId} ORDER BY a.created_at DESC,a.id DESC</script>")
+    List<Map<String, Object>> audits(@Param("customerId") long customerId, @Param("id") long id);
+}

finance/src/main/java/com/baiyue/finance/repository/FinanceFeeSourceReadRepository.java

@@ -0,0 +1,145 @@
+package com.baiyue.finance.repository;
+
+import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceSummary;
+import com.baiyue.finance.dto.FinancePhase1Dtos.OperationLog;
+import com.baiyue.finance.mapper.FinanceFeeSourceReadMapper;
+import com.baiyue.finance.service.FinanceEventException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.springframework.stereotype.Repository;
+import org.springframework.util.LinkedCaseInsensitiveMap;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.sql.Timestamp;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/** 费用当前投影及操作历史；版本记录只读，不覆盖账单引用的不可变快照。 */
+@Repository
+public class FinanceFeeSourceReadRepository {
+    private final FinanceFeeSourceReadMapper mapper;
+    private final ObjectMapper json;
+
+    /** 注入正式持久化入口与费用快照解析器。 */
+    public FinanceFeeSourceReadRepository(FinanceFeeSourceReadMapper mapper, ObjectMapper json) {
+        this.mapper = mapper;
+        this.json = json;
+    }
+
+    /** 组装统一查询参数，让计数和分页使用相同来源身份与筛选条件。 */
+    public Map<String, Object> filters(Long customerId, String direction, String status, String reviewStatus,
+                                      Boolean generated, LocalDate from, LocalDate to, String keyword, int page, int size) {
+        Map<String, Object> values = new HashMap<>();
+        values.put("customerId", customerId); values.put("direction", direction); values.put("status", status);
+        values.put("reviewStatus", reviewStatus); values.put("statementGenerated", generated);
+        values.put("dateFrom", from); values.put("dateTo", to); values.put("keyword", keyword);
+        values.put("limit", size); values.put("offset", (page - 1) * size);
+        return values;
+    }
+
+    /** 计数只包含所筛选的当前费用，历史状态专项查询除外。 */
+    public long count(Map<String, Object> filters) { return mapper.count(filters); }
+
+    /** 当前费用映射沿用原币、数量、客户等正式字段。 */
+    public List<FeeSourceSummary> list(Map<String, Object> filters) {
+        return mapper.list(filters).stream().map(this::summary).toList();
+    }
+
+    /** 由不可变版本追加同步历史，并串联同一费用所有既有审计记录。 */
+    public List<OperationLog> logs(long customerId, long id) {
+        List<OperationLog> result = new ArrayList<>();
+        Map<String, Object> previous = null;
+        for (Map<String, Object> raw : mapper.versions(customerId, id)) {
+            Map<String, Object> row = row(raw);
+            String version = "来源版本 " + row.get("source_fee_version");
+            String amount = amount(row) + " " + row.get("currency_code");
+            // 同步时间与原业务操作者不能混用，原业务审批仍以来源系统记录为准。
+            result.add(new OperationLog(time(row.get("created_at")),
+                previous == null ? "FEE_SOURCE_PUBLISHED" : "FEE_SOURCE_VERSION_ADJUST",
+                "系统同步", "SUCCESS", previous == null ? version + "；金额 " + amount
+                    : "来源版本 " + previous.get("source_fee_version") + " → " + row.get("source_fee_version")
+                        + "；金额 " + amount(previous) + " → " + amount));
+            previous = row;
+        }
+        // 金额差分仍按版本升序计算；展示先反转版本，同毫秒时稳定排序保留新版本在前。
+        java.util.Collections.reverse(result);
+        for (Map<String, Object> raw : mapper.audits(customerId, id)) {
+            Map<String, Object> row = row(raw);
+            String remark = text(row.get("reason"));
+            JsonNode before = parse(row.get("before_data"));
+            JsonNode after = parse(row.get("after_data"));
+            if (before.hasNonNull("amount") && after.hasNonNull("amount")
+                && before.path("amount").decimalValue().compareTo(after.path("amount").decimalValue()) != 0) {
+                remark = (remark == null ? "" : remark + "；") + "金额 " + before.path("amount").asText()
+                    + " → " + after.path("amount").asText() + " " + after.path("currency").asText("CNY");
+            }
+            result.add(new OperationLog(time(row.get("created_at")), text(row.get("action")),
+                text(row.get("operator_name_snapshot")), "SUCCESS", remark));
+        }
+        // 时间排序保持同毫秒版本的新到旧顺序，以及 Mapper 返回的审计 ID 倒序。
+        result.sort(Comparator.comparing(OperationLog::occurredAt, Comparator.nullsLast(Comparator.reverseOrder())));
+        return List.copyOf(result);
+    }
+
+    /** 将持久化快照转换为费用列表 DTO，不从其他客户或来源补齐业务事实。 */
+    private FeeSourceSummary summary(Map<String, Object> raw) {
+        Map<String, Object> row = row(raw);
+        JsonNode snapshot = parse(row.get("source_snapshot"));
+        BigDecimal amount = decimal(row.get("amount"));
+        BigDecimal originalAmount = first(decimal(text(snapshot, "originalAmount")), amount);
+        BigDecimal quantity = decimal(text(snapshot, "chargeableQuantity"));
+        BigDecimal unitPrice = first(decimal(text(snapshot, "unitPrice")), quantity != null && quantity.signum() > 0
+            ? originalAmount.divide(quantity, 6, RoundingMode.HALF_UP) : null);
+        return new FeeSourceSummary(number(row.get("id")), text(row.get("source_system")), text(row.get("source_type")),
+            first(text(row.get("source_no")), text(snapshot, "sourceBusinessId")), number(row.get("source_fee_id")),
+            ((Number) row.get("source_fee_version")).intValue(), text(row.get("direction")), number(row.get("customer_id")),
+            text(snapshot, "customerName"), positiveLong(text(snapshot, "supplierId")), text(snapshot, "supplierName"),
+            nullableLong(row.get("order_id")), nullableLong(row.get("inbound_id")), text(snapshot, "inboundCode"),
+            nullableLong(row.get("container_id")), text(snapshot, "containerNo"),
+            first(date(text(snapshot, "businessDate")), LocalDate.of(1970, 1, 1)), text(row.get("fee_item_name")),
+            quantity, text(snapshot, "quantityUnit"), unitPrice, date(text(snapshot, "periodStart")), date(text(snapshot, "periodEnd")),
+            amount, text(row.get("currency_code")), first(text(snapshot, "originalCurrency"), text(row.get("currency_code"))),
+            originalAmount, first(decimal(text(snapshot, "exchangeRate")), BigDecimal.ONE), text(snapshot, "exchangeRateMonth"),
+            first(text(row.get("review_status")), "DRAFT"), text(row.get("effective_status")),
+            Boolean.TRUE.equals(row.get("statement_generated")) || row.get("statement_generated") instanceof Number value && value.intValue() != 0);
+    }
+
+    /** 保留不同数据库驱动的列名大小写读取语义。 */
+    private static Map<String, Object> row(Map<String, Object> source) {
+        Map<String, Object> result = new LinkedCaseInsensitiveMap<>(); result.putAll(source); return result;
+    }
+    /** 解析不可变快照，损坏数据失败关闭。 */
+    private JsonNode parse(Object value) {
+        try { return value == null ? json.createObjectNode() : json.readTree(value.toString()); }
+        catch (Exception failure) { throw new FinanceEventException("FIN-DATA-500", "费用来源快照损坏"); }
+    }
+    /** 格式化记录金额，保留定点精度。 */
+    private static String amount(Map<String, Object> row) { return decimal(row.get("amount")).toPlainString(); }
+    /** 读取驱动返回的标准时间。 */
+    private static LocalDateTime time(Object value) { return value instanceof Timestamp time ? time.toLocalDateTime() : (LocalDateTime) value; }
+    /** 读取数字主键，仅用于数据引用。 */
+    private static long number(Object value) { return ((Number) value).longValue(); }
+    /** 保留未关联的可空引用。 */
+    private static Long nullableLong(Object value) { return value == null ? null : number(value); }
+    /** 只接受合法的正整型供应商引用。 */
+    private static Long positiveLong(String value) {
+        try { long parsed = Long.parseLong(value); return parsed > 0 ? parsed : null; }
+        catch (NumberFormatException failure) { return null; }
+    }
+    /** 读取可空金额，不经过浮点转换。 */
+    private static BigDecimal decimal(Object value) { return value == null ? null : new BigDecimal(value.toString()); }
+    /** 读取可空业务日期。 */
+    private static LocalDate date(String value) { return value == null ? null : LocalDate.parse(value); }
+    /** 保持空字段的缺失语义。 */
+    private static String text(Object value) { return value == null || value.toString().isBlank() ? null : value.toString(); }
+    /** 读取快照字段。 */
+    private static String text(JsonNode node, String field) { return node.path(field).isNull() || node.path(field).isMissingNode() ? null : text(node.path(field).asText()); }
+    /** 优先使用来源字段，其次使用已有正式默认值。 */
+    private static <T> T first(T value, T fallback) { return value == null ? fallback : value; }
+}

finance/src/main/java/com/baiyue/finance/service/FinancePhase1OperationService.java

@@ -1,10 +1,10 @@
 package com.baiyue.finance.service;
 
+import com.baiyue.finance.repository.FinanceFeeSourceReadRepository;
 import com.baiyue.finance.dto.FinancePhase1Dtos.AccountSummary;
 import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceDetail;
 import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceSummary;
 import com.baiyue.finance.dto.FinancePhase1Dtos.LedgerEntry;
-import com.baiyue.finance.dto.FinancePhase1Dtos.OperationLog;
 import com.baiyue.finance.dto.FinancePhase1Dtos.PageEnvelope;
 import com.baiyue.finance.dto.FinancePhase1Dtos.ReviewRequest;
 import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceActionRequest;
@@ -44,19 +44,19 @@ public class FinancePhase1OperationService {
     private final ObjectMapper objectMapper;
     private final FirstlegFeeSourceClient firstleg;
     private final String internalToken;
+    private final FinanceFeeSourceReadRepository feeSources;
 
+    /** 注入费用来源查询及现有业务依赖。 */
     @Autowired
     public FinancePhase1OperationService(JdbcTemplate jdbc, ObjectMapper objectMapper,
                                          FirstlegFeeSourceClient firstleg,
-                                         @Value("${baiyue.security.internal-service-token}") String internalToken) {
+                                         @Value("${baiyue.security.internal-service-token}") String internalToken,
+                                         FinanceFeeSourceReadRepository feeSources) {
         this.jdbc = jdbc;
         this.objectMapper = objectMapper;
         this.firstleg = firstleg;
         this.internalToken = internalToken;
-    }
-
-    public FinancePhase1OperationService(JdbcTemplate jdbc, ObjectMapper objectMapper) {
-        this(jdbc, objectMapper, null, "");
+        this.feeSources = feeSources;
     }
 
     public PageEnvelope<AccountSummary> listDerivedCustomerAccounts(int page, int pageSize, String customerName, String status) {
@@ -163,6 +163,7 @@ public class FinancePhase1OperationService {
         return PageEnvelope.success(List.copyOf(projected.subList(from, to)), page, pageSize, projected.size());
     }
 
+    /** 按同一来源费用的当前版本分页，调整历史不重复计入客户应收应付。 */
     public PageEnvelope<FeeSourceSummary> listFinanceFeeSources(int page, int pageSize, Long customerId,
                                                                  String direction, String sourceStatus,
                                                                  String reviewStatus,
@@ -178,34 +179,9 @@ public class FinancePhase1OperationService {
             List.of("DRAFT", "PENDING", "APPROVED", "REJECTED"), "审核状态无效");
         String normalizedSourceStatus = normalized(sourceStatus,
             List.of("AVAILABLE", "LOCKED", "BILLED", "SETTLED", "VOIDED", "SUPERSEDED"), "费用来源状态无效");
-        String generatedSql = "EXISTS(SELECT 1 FROM fin_bill_line bl WHERE bl.source_id=f.id AND bl.source_version=f.source_fee_version)";
-        String effectiveStatusSql = "CASE WHEN f.status='AVAILABLE' AND " + generatedSql + " THEN 'BILLED' ELSE f.status END";
-        String businessDateSql = "STR_TO_DATE(JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.businessDate')),'%Y-%m-%d')";
-        StringBuilder where = new StringBuilder(" FROM fin_fee_source f WHERE 1=1");
-        List<Object> args = new ArrayList<>();
-        if (customerId != null) { where.append(" AND f.customer_id=?"); args.add(customerId); }
-        if (normalizedDirection != null) { where.append(" AND f.direction=?"); args.add(normalizedDirection); }
-        if (normalizedReview != null) { where.append(" AND f.review_status=?"); args.add(normalizedReview); }
-        if (normalizedSourceStatus != null) { where.append(" AND ").append(effectiveStatusSql).append("=?"); args.add(normalizedSourceStatus); }
-        if (statementGenerated != null) { where.append(" AND ").append(generatedSql).append("=?"); args.add(statementGenerated); }
-        if (businessDateFrom != null) { where.append(" AND ").append(businessDateSql).append(">=?"); args.add(businessDateFrom); }
-        if (businessDateTo != null) { where.append(" AND ").append(businessDateSql).append("<=?"); args.add(businessDateTo); }
-        String normalizedKeyword = blankToNull(keyword);
-        if (normalizedKeyword != null) {
-            where.append(" AND (f.source_no LIKE CONCAT('%',?,'%') OR f.fee_item_name LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.customerName')) LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.inboundCode')) LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.containerNo')) LIKE CONCAT('%',?,'%')")
-                .append(" OR JSON_UNQUOTE(JSON_EXTRACT(f.source_snapshot,'$.supplierName')) LIKE CONCAT('%',?,'%'))");
-            for (int i = 0; i < 6; i++) args.add(normalizedKeyword);
-        }
-        Long total = jdbc.queryForObject("SELECT COUNT(*)" + where, Long.class, args.toArray());
-        List<Object> queryArgs = new ArrayList<>(args);
-        queryArgs.add(pageSize); queryArgs.add((page - 1) * pageSize);
-        String select = "SELECT f.*," + generatedSql + " statement_generated," + effectiveStatusSql + " effective_status" +
-            where + " ORDER BY " + businessDateSql + " DESC,f.id DESC LIMIT ? OFFSET ?";
-        List<FeeSourceSummary> rows = jdbc.query(select, (rs, n) -> summary(rs), queryArgs.toArray());
-        return PageEnvelope.success(rows, page, pageSize, total == null ? 0 : total);
+        Map<String, Object> filters = feeSources.filters(customerId, normalizedDirection, normalizedSourceStatus,
+            normalizedReview, statementGenerated, businessDateFrom, businessDateTo, blankToNull(keyword), page, pageSize);
+        return PageEnvelope.success(feeSources.list(filters), page, pageSize, feeSources.count(filters));
     }
 
     public FeeSourceDetail getFinanceFeeSource(long feeSourceId) {
@@ -339,6 +315,7 @@ public class FinancePhase1OperationService {
         return after;
     }
 
+    /** 读取指定不可变版本，并附带同客户同方向的费用调整历史。 */
     private FeeSourceDetail detail(ResultSet rs) throws SQLException {
         JsonNode snapshot = parse(rs.getString("source_snapshot"));
         long id = rs.getLong("id");
@@ -356,33 +333,7 @@ public class FinancePhase1OperationService {
             amount, rs.getString("currency_code"), firstText(text(snapshot, "originalCurrency"), rs.getString("currency_code")), originalAmount,
             firstDecimal(decimal(snapshot, "exchangeRate"), BigDecimal.ONE), text(snapshot, "exchangeRateMonth"),
             defaultString(rs.getString("review_status"), "DRAFT"), status, generated,
-            rs.getString("review_reason"), rs.getString("source_hash"), rs.getInt("operation_version"), logs(rs.getLong("customer_id"), id));
-    }
-
-    private FeeSourceSummary summary(ResultSet rs) throws SQLException {
-        JsonNode snapshot = parse(rs.getString("source_snapshot"));
-        boolean generated = rs.getBoolean("statement_generated");
-        BigDecimal quantity = decimal(snapshot, "chargeableQuantity");
-        BigDecimal amount = money(rs, "amount");
-        BigDecimal originalAmount = firstDecimal(decimal(snapshot, "originalAmount"), amount);
-        BigDecimal unitPrice = firstDecimal(decimal(snapshot, "unitPrice"), quantity != null && quantity.signum() > 0
-            ? originalAmount.divide(quantity, 6, java.math.RoundingMode.HALF_UP) : null);
-        return new FeeSourceSummary(rs.getLong("id"), rs.getString("source_system"), rs.getString("source_type"),
-            firstText(rs.getString("source_no"), text(snapshot, "sourceBusinessId")), rs.getLong("source_fee_id"), rs.getInt("source_fee_version"),
-            rs.getString("direction"), rs.getLong("customer_id"), text(snapshot, "customerName"),
-            jsonLong(snapshot, "supplierId"), text(snapshot, "supplierName"), nullableLong(rs, "order_id"),
-            nullableLong(rs, "inbound_id"), text(snapshot, "inboundCode"), nullableLong(rs, "container_id"),
-            text(snapshot, "containerNo"), date(snapshot, "businessDate"), rs.getString("fee_item_name"),
-            quantity, text(snapshot, "quantityUnit"), unitPrice, nullableDate(snapshot, "periodStart"), nullableDate(snapshot, "periodEnd"),
-            amount, rs.getString("currency_code"), firstText(text(snapshot, "originalCurrency"), rs.getString("currency_code")), originalAmount,
-            firstDecimal(decimal(snapshot, "exchangeRate"), BigDecimal.ONE), text(snapshot, "exchangeRateMonth"),
-            defaultString(rs.getString("review_status"), "DRAFT"),
-            rs.getString("effective_status"), generated);
-    }
-
-    private List<OperationLog> logs(long customerId, long id) {
-        return jdbc.query("SELECT created_at,action,operator_name_snapshot,reason FROM fin_audit_log WHERE tenant_id=? AND resource_type='FIN_FEE_SOURCE' AND resource_id=? ORDER BY created_at DESC,id DESC", (rs, n) ->
-            new OperationLog(time(rs, "created_at"), rs.getString("action"), rs.getString("operator_name_snapshot"), "SUCCESS", rs.getString("reason")), customerId, id);
+            rs.getString("review_reason"), rs.getString("source_hash"), rs.getInt("operation_version"), feeSources.logs(rs.getLong("customer_id"), id));
     }
 
     private Long reserve(long customerId, long operatorId, String operation, String key, String method, String path, Object body) {

finance/src/test/java/com/baiyue/finance/FinanceContractTest.java

@@ -17,6 +17,7 @@ class FinanceContractTest {
             .getAnnotation(org.springframework.scheduling.annotation.EnableScheduling.class));
     }
 
+    /** 固定财务访问域与账单关联键，查询迁入 Mapper 后仍核对真实来源记录。 */
     @Test
     void controllersUseFrozenFinancePaths() throws Exception {
         assertEquals("/api/platform/finance/v1", PlatformFinanceController.class.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class).value()[0]);
@@ -40,7 +41,8 @@ class FinanceContractTest {
         assertTrue(controller.contains("costSnapshotClient.loadingPlan") && controller.contains("createCost(request.customerId(), user.userId(), internal, volumes, key)"));
         assertTrue(service.contains("validateVoucherFiles(tenantId, request.voucherFileIds())"));
         String operations = Files.readString(Path.of("src/main/java/com/baiyue/finance/service/FinancePhase1OperationService.java"));
-        assertTrue(operations.contains("bl.source_id=f.id"));
+        String feeReads = Files.readString(Path.of("src/main/java/com/baiyue/finance/mapper/FinanceFeeSourceReadMapper.java"));
+        assertTrue(feeReads.contains("bl.source_id=f.id"));
         assertTrue(operations.contains("Boolean.class, id, rs.getInt(\"source_fee_version\")"));
         assertFalse(operations.contains("bl.source_id=f.source_fee_id"));
         String unified = Files.readString(Path.of("../deploy/sql/头程数据库统一增量-MySQL8.sql"));

finance/src/test/java/com/baiyue/finance/FinanceFeeSourceReadMapperTest.java

@@ -0,0 +1,141 @@
+package com.baiyue.finance;
+
+import com.baiyue.finance.mapper.FinanceFeeSourceReadMapper;
+import com.baiyue.finance.repository.FinanceFeeSourceReadRepository;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.session.Configuration;
+import org.apache.ibatis.session.SqlSessionFactoryBuilder;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.DriverManagerDataSource;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** 隔离数据库执行正式 Mapper，验证版本归并与历史不会改变金额和客户归属。 */
+public class FinanceFeeSourceReadMapperTest {
+    /** 应收和应付均以来源身份替换当前展示，同名费用、其他来源类型和系统保持独立。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"RECEIVABLE", "PAYABLE"})
+    void currentProjectionAndHistoryKeepStableFeeIdentity(String direction) {
+        var data = new DriverManagerDataSource("jdbc:h2:mem:fee-current-" + UUID.randomUUID() + ";MODE=MySQL", "sa", "");
+        var jdbc = new JdbcTemplate(data);
+        // 保持一个会话存活；Mapper 使用同一隔离数据库，绝不访问共享测试环境。
+        try (var connection = data.getConnection()) {
+            jdbc.execute("CREATE ALIAS JSON_EXTRACT FOR 'com.baiyue.finance.FinanceFeeSourceReadMapperTest.jsonExtract'");
+            jdbc.execute("CREATE ALIAS JSON_UNQUOTE FOR 'com.baiyue.finance.FinanceFeeSourceReadMapperTest.jsonUnquote'");
+            jdbc.execute("CREATE TABLE fin_fee_source(id BIGINT PRIMARY KEY,source_system VARCHAR(32),source_type VARCHAR(32),source_fee_id BIGINT,source_fee_version INT,customer_id BIGINT,direction VARCHAR(16),source_no VARCHAR(64),fee_item_name VARCHAR(100),amount DECIMAL(20,6),currency_code VARCHAR(3),review_status VARCHAR(16),status VARCHAR(16),source_snapshot VARCHAR(2000),order_id BIGINT,inbound_id BIGINT,container_id BIGINT,created_at TIMESTAMP)");
+            jdbc.execute("CREATE TABLE fin_bill_line(source_id BIGINT,source_version INT)");
+            jdbc.execute("CREATE TABLE fin_audit_log(id BIGINT PRIMARY KEY,tenant_id BIGINT,resource_type VARCHAR(32),resource_id BIGINT,action VARCHAR(64),operator_name_snapshot VARCHAR(64),reason VARCHAR(100),before_data VARCHAR(1000),after_data VARCHAR(1000),created_at TIMESTAMP)");
+            insert(jdbc, 1, "FIRSTLEG", "INBOUND_FEE", 700, 1, 9, direction, "SUPERSEDED", "100.00");
+            insert(jdbc, 2, "FIRSTLEG", "INBOUND_FEE", 700, 2, 9, direction, "AVAILABLE", "120.00");
+            insert(jdbc, 3, "FIRSTLEG", "INBOUND_FEE", 701, 1, 9, direction, "AVAILABLE", "80.00");
+            insert(jdbc, 4, "FIRSTLEG", "INBOUND_FEE", 702, 1, 9, direction, "AVAILABLE", "50.00");
+            insert(jdbc, 5, "FIRSTLEG", "INBOUND_FEE", 702, 2, 9, direction, "VOIDED", "70.00");
+            insert(jdbc, 6, "LASTLEG", "INBOUND_FEE", 700, 1, 9, direction, "AVAILABLE", "33.00");
+            insert(jdbc, 7, "FIRSTLEG", "CONTAINER_FEE", 700, 1, 9, direction, "AVAILABLE", "44.00");
+            insert(jdbc, 8, "FIRSTLEG", "INBOUND_FEE", 703, 1, 10, direction, "AVAILABLE", "55.00");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(1,9,'FIN_FEE_SOURCE',1,'FEE_SOURCE_REVIEW_APPROVE','审核员','原费用审核',NULL,NULL,'2026-10-21 10:01:30')");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(2,9,'FIN_FEE_SOURCE',2,'FEE_SOURCE_ADJUST','财务员','更正费用','{\"amount\":100}','{\"amount\":120,\"currency\":\"CNY\"}','2026-10-21 10:03:00')");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(3,9,'FIN_FEE_SOURCE',3,'FEE_SOURCE_ADJUST','其他费用','不能合并',NULL,NULL,'2026-10-21 10:04:00')");
+            jdbc.update("INSERT INTO fin_audit_log VALUES(4,10,'FIN_FEE_SOURCE',1,'FEE_SOURCE_ADJUST','其他客户','不能越界',NULL,NULL,'2026-10-21 10:04:00')");
+
+            var configuration = new Configuration(new Environment("test", new JdbcTransactionFactory(), data));
+            configuration.addMapper(FinanceFeeSourceReadMapper.class);
+            try (var session = new SqlSessionFactoryBuilder().build(configuration).openSession()) {
+                var repository = new FinanceFeeSourceReadRepository(session.getMapper(FinanceFeeSourceReadMapper.class), new ObjectMapper());
+                var filters = repository.filters(9L, direction, null, "APPROVED", false,
+                    LocalDate.of(2026, 10, 1), LocalDate.of(2026, 10, 31), "操作费", 1, 20);
+                assertThat(repository.count(filters)).isEqualTo(5);
+                var rows = repository.list(filters);
+                assertThat(rows).extracting(row -> row.feeSourceId()).containsExactly(7L, 6L, 5L, 3L, 2L);
+                assertThat(rows.stream().map(row -> row.amount()).reduce(BigDecimal.ZERO, BigDecimal::add))
+                    .isEqualByComparingTo("347.00");
+                assertThat(rows).allSatisfy(row -> {
+                    assertThat(row.direction()).isEqualTo(direction);
+                    assertThat(row.customerId()).isEqualTo(9);
+                    assertThat(row.supplierId()).isEqualTo(79);
+                    assertThat(row.inboundCode()).isEqualTo("IN-9");
+                    assertThat(row.businessDate()).isEqualTo(LocalDate.of(2026, 10, 21));
+                    assertThat(row.originalAmount()).isEqualByComparingTo("200");
+                    assertThat(row.unitPrice()).isEqualByComparingTo("20");
+                });
+                filters.put("limit", 2);
+                filters.put("offset", 2);
+                assertThat(repository.count(filters)).isEqualTo(5);
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).containsExactly(5L, 3L);
+                filters.put("limit", 20); filters.put("offset", 0); filters.put("status", "AVAILABLE");
+                assertThat(repository.count(filters)).isEqualTo(4);
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).doesNotContain(4L, 5L);
+                filters.put("status", "SUPERSEDED");
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).containsExactly(1L);
+
+                var logs = repository.logs(9, 2);
+                assertThat(logs).hasSize(4);
+                assertThat(logs).extracting(log -> log.action()).containsExactly(
+                    "FEE_SOURCE_ADJUST", "FEE_SOURCE_VERSION_ADJUST", "FEE_SOURCE_REVIEW_APPROVE", "FEE_SOURCE_PUBLISHED");
+                assertThat(logs.get(0).remark()).isEqualTo("更正费用；金额 100 → 120 CNY");
+                assertThat(logs.get(1).remark()).contains("来源版本 1 → 2", "100.000000 → 120.000000 CNY");
+                assertThat(logs).noneSatisfy(log -> assertThat(log.operatorName()).startsWith("其他"));
+                assertThat(repository.logs(9, 2)).isEqualTo(logs);
+                assertThat(repository.logs(9, 1)).hasSize(2);
+                assertThat(repository.logs(10, 2)).isEmpty();
+                // 同毫秒必须先展示新版本；审计仍按 ID 倒序，不能反转金额差分或突破旧版本锚点。
+                jdbc.update("UPDATE fin_fee_source SET created_at='2026-10-21 10:03:00.123' WHERE id IN (1,2)");
+                jdbc.update("UPDATE fin_audit_log SET created_at='2026-10-21 10:03:00.123' WHERE id IN (1,2)");
+                jdbc.update("INSERT INTO fin_audit_log VALUES(6,9,'FIN_FEE_SOURCE',2,'FEE_SOURCE_REVIEW_APPROVE','审核员','同毫秒后审计',NULL,NULL,'2026-10-21 10:03:00.123')");
+                session.clearCache();
+                var sameTimeLogs = repository.logs(9, 2);
+                assertThat(sameTimeLogs).extracting(log -> log.action()).containsExactly(
+                    "FEE_SOURCE_VERSION_ADJUST", "FEE_SOURCE_PUBLISHED", "FEE_SOURCE_REVIEW_APPROVE",
+                    "FEE_SOURCE_ADJUST", "FEE_SOURCE_REVIEW_APPROVE");
+                assertThat(sameTimeLogs.get(0).remark()).contains("来源版本 1 → 2", "100.000000 → 120.000000 CNY");
+                assertThat(sameTimeLogs.get(1).remark()).contains("来源版本 1；金额 100.000000 CNY");
+                assertThat(sameTimeLogs.subList(2, 5)).extracting(log -> log.remark()).containsExactly(
+                    "同毫秒后审计", "更正费用；金额 100 → 120 CNY", "原费用审核");
+                assertThat(repository.logs(9, 2)).isEqualTo(sameTimeLogs);
+                assertThat(repository.logs(9, 1)).extracting(log -> log.action()).containsExactly(
+                    "FEE_SOURCE_PUBLISHED", "FEE_SOURCE_REVIEW_APPROVE");
+                assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM fin_fee_source", Long.class)).isEqualTo(8);
+                jdbc.update("INSERT INTO fin_bill_line VALUES(2,2)");
+                filters.put("status", "BILLED"); filters.put("statementGenerated", true);
+                assertThat(repository.count(filters)).isEqualTo(1);
+                assertThat(repository.list(filters)).extracting(row -> row.feeSourceId()).containsExactly(2L);
+
+                // 财务内部费用原地改金额，其历史只取真实审计，不能伪造旧时间的同步金额。
+                insert(jdbc, 9, "FINANCE", "MANUAL", 700, 1, 9, direction, "AVAILABLE", "120.00");
+                jdbc.update("INSERT INTO fin_audit_log VALUES(5,9,'FIN_FEE_SOURCE',9,'FEE_SOURCE_ADJUST','财务员','更正人工费用','{\"amount\":100}','{\"amount\":120,\"currency\":\"CNY\"}','2026-10-21 10:05:00')");
+                assertThat(repository.logs(9, 9)).singleElement().satisfies(log -> {
+                    assertThat(log.action()).isEqualTo("FEE_SOURCE_ADJUST");
+                    assertThat(log.remark()).isEqualTo("更正人工费用；金额 100 → 120 CNY");
+                });
+            }
+        } catch (java.sql.SQLException failure) { throw new AssertionError(failure); }
+    }
+
+    /** 准备具有相同名称、不同稳定来源的隔离费用快照。 */
+    private static void insert(JdbcTemplate jdbc, long id, String system, String type, long fee, int version,
+                               long customer, String direction, String status, String amount) {
+        jdbc.update("INSERT INTO fin_fee_source(id,source_system,source_type,source_fee_id,source_fee_version,customer_id,direction,source_no,fee_item_name,amount,currency_code,review_status,status,source_snapshot,created_at) VALUES(?,?,?,?,?,?,?,'IN-9','操作费',?,'CNY','APPROVED',?,?,?)",
+            id, system, type, fee, version, customer, direction, new BigDecimal(amount), status,
+            "{\"businessDate\":\"2026-10-21\",\"supplierId\":79,\"inboundCode\":\"IN-9\",\"chargeableQuantity\":10,\"originalAmount\":200}",
+            java.sql.Timestamp.valueOf("2026-10-21 10:0" + version + ":00"));
+    }
+
+    /** H2 仅补足 MySQL JSON 读取函数，实际筛选、关联和分页仍执行正式 SQL。 */
+    public static String jsonExtract(String value, String path) throws Exception {
+        var node = new ObjectMapper().readTree(value).path(path.substring(2));
+        return node.isMissingNode() || node.isNull() ? null : node.toString();
+    }
+
+    /** 对测试 JSON 标量解引号，保持 MySQL 空值语义。 */
+    public static String jsonUnquote(String value) throws Exception {
+        return value == null ? null : new ObjectMapper().readTree(value).asText();
+    }
+}

finance/src/test/java/com/baiyue/finance/FinancePhase1OperationBehaviorTest.java

@@ -9,10 +9,13 @@ import com.baiyue.finance.dto.FinancePhase1Dtos.FeeSourceDetail;
 import com.baiyue.finance.dto.FinancePhase1Dtos.PageEnvelope;
 import com.baiyue.finance.service.FinanceEventException;
 import com.baiyue.finance.service.FinancePhase1OperationService;
+import com.baiyue.finance.repository.FinanceFeeSourceReadRepository;
 import com.baiyue.finance.service.FinanceCustomerAccountService;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.jdbc.core.JdbcTemplate;
@@ -40,6 +43,9 @@ import static org.mockito.Mockito.lenient;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.times;
 
 @ExtendWith(MockitoExtension.class)
 class FinancePhase1OperationBehaviorTest {
@@ -81,18 +87,20 @@ class FinancePhase1OperationBehaviorTest {
         assertThat(response.page().total()).isEqualTo(1);
     }
 
+    /** 无效客户在进入持久化查询前拒绝。 */
     @Test
     void ledgerRejectsInvalidCustomerBeforeAnyQuery() {
-        FinancePhase1OperationService service = new FinancePhase1OperationService(mock(JdbcTemplate.class), objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(mock(JdbcTemplate.class), objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
         assertThatThrownBy(() -> service.listDerivedCustomerAccountLedger(0, 1, 20, null, null, null))
             .isInstanceOf(FinanceEventException.class)
             .extracting(error -> ((FinanceEventException) error).code()).isEqualTo("FIN-REQ-400");
     }
 
+    /** 保留客户账户汇总的固定分页与金额口径。 */
     @Test
     void accountListReturnsFixedPagedDto() {
         AccountJdbc jdbc = new AccountJdbc();
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         PageEnvelope<FinancePhase1Dtos.AccountSummary> result =
             service.listDerivedCustomerAccounts(1, 20, "客户9", "ACTIVE");
@@ -112,10 +120,11 @@ class FinancePhase1OperationBehaviorTest {
         assertThat(jdbc.accountListSql).doesNotContain("CAST(c.customer_id AS CHAR)");
     }
 
+    /** 所有派生流水查询保留目标客户范围。 */
     @Test
     void ledgerQueriesEveryDerivedSourceWithinCustomerScope() {
         AccountJdbc jdbc = new AccountJdbc();
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         PageEnvelope<FinancePhase1Dtos.LedgerEntry> result =
             service.listDerivedCustomerAccountLedger(9L, 1, 20, null, null, null);
@@ -128,58 +137,24 @@ class FinancePhase1OperationBehaviorTest {
             .contains("fin_settlement_payment", "transaction_type='PAYMENT'", "s.direction='PAYABLE'"));
     }
 
+    /** 所有筛选在服务端进入同一版本投影，不在分页后按费用名称去重。 */
     @Test
-    void feeSourceListUsesFormalFieldsAndAllActiveFilters() throws Exception {
-        JdbcTemplate jdbc = mock(JdbcTemplate.class);
-        when(jdbc.queryForObject(startsWith("SELECT COUNT(*) FROM fin_fee_source"), eq(Long.class), any(Object[].class)))
-            .thenReturn(1L);
-        when(jdbc.query(startsWith("SELECT f.*"), any(RowMapper.class), any(Object[].class))).thenAnswer(invocation -> {
-            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
-            ResultSet rs = mock(ResultSet.class);
-            when(rs.getLong("id")).thenReturn(88L);
-            when(rs.getLong("source_fee_id")).thenReturn(9001L);
-            when(rs.getInt("source_fee_version")).thenReturn(3);
-            when(rs.getLong("customer_id")).thenReturn(9L);
-            when(rs.getLong("order_id")).thenReturn(19L);
-            when(rs.getLong("inbound_id")).thenReturn(29L);
-            when(rs.getLong("container_id")).thenReturn(39L);
-            when(rs.getString("source_system")).thenReturn("FIRSTLEG");
-            when(rs.getString("source_type")).thenReturn("INBOUND_FEE");
-            when(rs.getString("source_no")).thenReturn("IN-9");
-            when(rs.getString("direction")).thenReturn("RECEIVABLE");
-            when(rs.getString("fee_item_name")).thenReturn("入库操作费");
-            when(rs.getString("currency_code")).thenReturn("CNY");
-            when(rs.getString("review_status")).thenReturn("APPROVED");
-            when(rs.getString("effective_status")).thenReturn("AVAILABLE");
-            when(rs.getString("source_snapshot")).thenReturn("{\"customerName\":\"客户9\",\"supplierId\":\"79\",\"supplierName\":\"供应商A\",\"inboundCode\":\"IN-9\",\"containerNo\":\"CONT-9\",\"businessDate\":\"2026-08-11\",\"chargeableQuantity\":\"10\"}");
-            when(rs.getBigDecimal("amount")).thenReturn(new BigDecimal("120.00"));
-            when(rs.getBoolean("statement_generated")).thenReturn(false);
-            return List.of(mapper.mapRow(rs, 0));
-        });
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
-
+    void feeSourceListUsesFormalFieldsAndAllActiveFilters() {
+        var reads = mock(FinanceFeeSourceReadRepository.class);
+        var filters = java.util.Map.<String, Object>of("query", "current");
+        when(reads.filters(9L, "RECEIVABLE", "AVAILABLE", "APPROVED", false,
+            LocalDate.of(2026, 8, 1), LocalDate.of(2026, 8, 31), "IN-9", 2, 50)).thenReturn(filters);
+        when(reads.list(filters)).thenReturn(List.of());
+        when(reads.count(filters)).thenReturn(3L);
+        var service = new FinancePhase1OperationService(mock(JdbcTemplate.class), objectMapper(), null, "", reads);
         var result = service.listFinanceFeeSources(2, 50, 9L, "receivable", "available", "approved",
             false, LocalDate.of(2026, 8, 1), LocalDate.of(2026, 8, 31), "IN-9");
-
-        assertThat(result.page()).satisfies(meta -> {
-            assertThat(meta.page()).isEqualTo(2);
-            assertThat(meta.pageSize()).isEqualTo(50);
-            assertThat(meta.total()).isEqualTo(1);
-        });
-        assertThat(result.data()).singleElement().satisfies(source -> {
-            assertThat(source.sourceSystem()).isEqualTo("FIRSTLEG");
-            assertThat(source.sourceBusinessId()).isEqualTo("IN-9");
-            assertThat(source.inboundCode()).isEqualTo("IN-9");
-            assertThat(source.containerNo()).isEqualTo("CONT-9");
-            assertThat(source.supplierId()).isEqualTo(79L);
-            assertThat(source.supplierName()).isEqualTo("供应商A");
-            assertThat(source.reviewStatus()).isEqualTo("APPROVED");
-            assertThat(source.businessDate()).isEqualTo(LocalDate.of(2026, 8, 11));
-            assertThat(source.statementGenerated()).isFalse();
-        });
-        verify(jdbc).query(startsWith("SELECT f.*"), any(RowMapper.class), any(Object[].class));
+        assertThat(result.page().total()).isEqualTo(3);
+        assertThat(result.page().page()).isEqualTo(2);
+        verify(reads).list(filters);
     }
 
+    /** 流水返回业务单号和操作者快照。 */
     @Test
     void ledgerReturnsStableBusinessTypeDocumentAndOperatorNameSnapshot() throws Exception {
         JdbcTemplate jdbc = mock(JdbcTemplate.class);
@@ -197,7 +172,7 @@ class FinancePhase1OperationBehaviorTest {
         });
         when(jdbc.query(startsWith("SELECT id,receipt_no"), any(RowMapper.class), eq(9L))).thenReturn(List.of());
         when(jdbc.query(startsWith("SELECT id,cost_no"), any(RowMapper.class), eq(9L))).thenReturn(List.of());
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         PageEnvelope<FinancePhase1Dtos.LedgerEntry> result =
             service.listDerivedCustomerAccountLedger(9L, 1, 20, null, null, null);
@@ -211,18 +186,20 @@ class FinancePhase1OperationBehaviorTest {
         });
     }
 
+    /** 保留费用审核状态读取。 */
     @Test
     void approvedFeeCannotBeEditedAsDraft() throws Exception {
         JdbcTemplate jdbc = feeSourceJdbc("REJECTED", false, 2);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         assertThat(service.getFinanceFeeSource(88L).reviewStatus()).isEqualTo("REJECTED");
     }
 
+    /** 费用详情保持原客户与来源版本。 */
     @Test
     void feeSourceDetailUsesFixedDtoAndRealCustomerScope() throws Exception {
         FinancePhase1OperationService service = new FinancePhase1OperationService(
-            feeSourceJdbc("APPROVED", true, 2), objectMapper());
+            feeSourceJdbc("APPROVED", true, 2), objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         FeeSourceDetail detail = service.getFinanceFeeSource(88L);
 
@@ -232,10 +209,11 @@ class FinancePhase1OperationBehaviorTest {
         assertThat(detail.reviewStatus()).isEqualTo("APPROVED");
     }
 
+    /** 业务来源费用必须回到所属系统调整。 */
     @Test
     void firstlegFeeEditAndAdjustAreBlockedInsteadOfMutatingFinanceCopy() throws Exception {
         JdbcTemplate jdbc = feeSourceJdbc("REJECTED", false, 1);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         var request = new FinancePhase1Dtos.FeeSourceEditRequest(
             new BigDecimal("120.00"), "更正金额", 1);
@@ -247,6 +225,7 @@ class FinancePhase1OperationBehaviorTest {
             (Object[]) any());
     }
 
+    /** 头程作废等待权威来源事件，不能直接改财务副本。 */
     @Test
     void voidingNyexx2608180003DelegatesToFirstlegAndWaitsForEvent() throws Exception {
         JdbcTemplate jdbc = feeSourceJdbc("APPROVED", false, 2);
@@ -257,7 +236,7 @@ class FinancePhase1OperationBehaviorTest {
             .thenReturn(ApiResponse.success(new FirstlegFeeSourceClient.CommandResult(
                 "INBOUND_FEE", 700L, 3, "VOIDED", false)));
         FinancePhase1OperationService service = new FinancePhase1OperationService(
-            jdbc, objectMapper(), firstleg, "internal-token");
+            jdbc, objectMapper(), firstleg, "internal-token", mock(FinanceFeeSourceReadRepository.class));
 
         FeeSourceDetail result = service.voidFinanceFeeSource(88L, 71L, "finance",
             "void-key", new FinancePhase1Dtos.FeeSourceActionRequest("测试作废", 2));
@@ -278,6 +257,7 @@ class FinancePhase1OperationBehaviorTest {
             (Object[]) any());
     }
 
+    /** 审核以当前操作版本更新并追加同一记录的审计。 */
     @Test
     void reviewUsesExpectedVersionAndReturnsUpdatedDetail() throws Exception {
         JdbcTemplate jdbc = mock(JdbcTemplate.class);
@@ -289,7 +269,6 @@ class FinancePhase1OperationBehaviorTest {
             return List.of(mapper.mapRow(resultSet(review, false, version), 0));
         });
         when(jdbc.queryForObject(startsWith("SELECT COUNT(*)>0"), eq(Boolean.class), eq(88L), eq(3))).thenReturn(false);
-        when(jdbc.query(startsWith("SELECT created_at,action"), any(RowMapper.class), eq(9L), eq(88L))).thenReturn(List.of());
         when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L),
             eq("FEE_SOURCE_REVIEW"), eq("review-key"))).thenReturn(List.of());
         when(jdbc.update(startsWith("INSERT INTO fin_idempotency_record"), eq(9L), eq(71L),
@@ -301,7 +280,7 @@ class FinancePhase1OperationBehaviorTest {
             eq(71L), eq("操作人 71"), any(), any())).thenReturn(1);
         when(jdbc.update(startsWith("UPDATE fin_idempotency_record SET status='SUCCEEDED'"),
             eq(88L), eq(9L), eq(71L), eq("FEE_SOURCE_REVIEW"), eq("review-key"))).thenReturn(1);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class));
 
         FeeSourceDetail result = service.reviewFinanceFeeSource(88L, 71L, "review-key",
             new FinancePhase1Dtos.ReviewRequest("APPROVE", "核对无误", 0));
@@ -311,6 +290,51 @@ class FinancePhase1OperationBehaviorTest {
         verify(jdbc).update(startsWith("UPDATE fin_fee_source SET review_status="), eq("APPROVED"), eq("核对无误"), eq(88L), eq(0));
     }
 
+    /** 财务内部应收应付调整原费用记录，重复提交不能新增费用或重复记审计。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"RECEIVABLE", "PAYABLE"})
+    void manualAdjustmentUpdatesOriginalFeeOnceAndChecksVersionAndFrozenState(String direction) throws Exception {
+        var jdbc = mock(JdbcTemplate.class);
+        var service = spy(new FinancePhase1OperationService(jdbc, objectMapper(), null, "", mock(FinanceFeeSourceReadRepository.class)));
+        var beforeJson = objectMapper().createObjectNode().put("feeSourceId", 88).put("sourceSystem", "FINANCE")
+            .put("sourceType", "MANUAL").put("sourceFeeId", 700).put("sourceVersion", 1).put("customerId", 9)
+            .put("direction", direction).put("amount", 100).put("currency", "CNY").put("operationVersion", 2)
+            .put("reviewStatus", "APPROVED").put("sourceStatus", "AVAILABLE").put("statementGenerated", false);
+        var before = objectMapper().treeToValue(beforeJson, FeeSourceDetail.class);
+        var after = objectMapper().treeToValue(beforeJson.deepCopy().put("amount", 120)
+            .put("operationVersion", 3).put("reviewStatus", "DRAFT"), FeeSourceDetail.class);
+        doReturn(before, after).when(service).getFinanceFeeSource(88L);
+        lenient().when(jdbc.update(startsWith("UPDATE fin_fee_source SET amount="), eq(new BigDecimal("120.00")), eq(88L), eq(2), eq("APPROVED")))
+            .thenReturn(1, 0);
+        var request = new FinancePhase1Dtos.FeeSourceEditRequest(new BigDecimal("120.00"), "调整金额", 2);
+        var result = service.editFinanceFeeSource(88, 71, "adjust-once", request, true);
+        assertThat(result.feeSourceId()).isEqualTo(88);
+        assertThat(result.sourceFeeId()).isEqualTo(700);
+        assertThat(result.direction()).isEqualTo(direction);
+        assertThat(result.amount()).isEqualByComparingTo("120");
+        assertThat(result.operationVersion()).isEqualTo(3);
+        var hash = org.mockito.ArgumentCaptor.forClass(String.class);
+        verify(jdbc).update(startsWith("INSERT INTO fin_idempotency_record"), eq(9L), eq(71L),
+            eq("FEE_SOURCE_ADJUST"), eq("adjust-once"), hash.capture());
+        lenient().when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L), eq("FEE_SOURCE_ADJUST"), eq("adjust-once")))
+            .thenReturn(List.of(java.util.Map.of("request_hash", hash.getValue(), "status", "SUCCEEDED", "result_resource_id", 88L)));
+        assertThat(service.editFinanceFeeSource(88, 71, "adjust-once", request, true)).isEqualTo(after);
+        verify(jdbc, times(1)).update(startsWith("UPDATE fin_fee_source SET amount="), eq(new BigDecimal("120.00")), eq(88L), eq(2), eq("APPROVED"));
+        verify(jdbc, times(1)).update(startsWith("INSERT INTO fin_audit_log"), eq(9L), eq("FIN_FEE_SOURCE"), eq(88L),
+            eq("FEE_SOURCE_ADJUST"), eq("调整金额"), anyString(), anyString(), eq(71L), anyString(), any(), any());
+        verify(jdbc, never()).update(startsWith("INSERT INTO fin_fee_source"), any(Object[].class));
+        assertThatThrownBy(() -> service.editFinanceFeeSource(88, 71, "adjust-once",
+            new FinancePhase1Dtos.FeeSourceEditRequest(new BigDecimal("121.00"), "调整金额", 2), true))
+            .isInstanceOf(FinanceEventException.class).hasMessageContaining("Idempotency-Key已用于其他请求");
+        assertThatThrownBy(() -> service.editFinanceFeeSource(88, 71, "stale-version", request, true))
+            .isInstanceOf(FinanceEventException.class).hasMessageContaining("状态或版本");
+        doReturn(objectMapper().treeToValue(beforeJson.deepCopy().put("statementGenerated", true), FeeSourceDetail.class))
+            .when(service).getFinanceFeeSource(88L);
+        assertThatThrownBy(() -> service.editFinanceFeeSource(88, 71, "frozen", request, true))
+            .isInstanceOf(FinanceEventException.class).hasMessageContaining("已生成单据");
+    }
+
+    /** 准备指定来源版本的费用查询，不再模拟已迁入 Mapper 的审计查询。 */
     private static JdbcTemplate feeSourceJdbc(String reviewStatus, boolean included, int version) throws Exception {
         JdbcTemplate jdbc = mock(JdbcTemplate.class);
         when(jdbc.query(startsWith("SELECT * FROM fin_fee_source"), any(RowMapper.class), (Object[]) any())).thenAnswer(invocation -> {
@@ -318,7 +342,6 @@ class FinancePhase1OperationBehaviorTest {
             return List.of(mapper.mapRow(resultSet(reviewStatus, included, version), 0));
         });
         when(jdbc.queryForObject(startsWith("SELECT COUNT(*)>0"), eq(Boolean.class), eq(88L), eq(3))).thenReturn(false);
-        when(jdbc.query(startsWith("SELECT created_at,action"), any(RowMapper.class), eq(9L), eq(88L))).thenReturn(List.of());
         lenient().when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L),
             eq("FEE_SOURCE_SETTLEMENT"), eq("include-key"))).thenReturn(List.of());
         return jdbc;

firstleg/docs/business-index.md

@@ -42,7 +42,7 @@
 | 财务费用来源快照 | `controller/InternalFinanceFeeSourceController.java`；入库费用与柜次费用分别按来源 ID、版本向 Finance 提供不可变快照 |
 | 柜次费用明细与跨客户分摊组 | `controller/PlatformContainerFeeDetailController.java`、`service/ContainerFeeDetailService.java`、`dto/ContainerFeeDetailDtos.java`；跨客户公共柜费使用 `allocation-groups` 按柜内真实客户和订单原子分摊，入仓 ID/入仓码同时填写或同时留空；各行金额合计必须等于原始柜费，审核、驳回、调整、作废均整组处理，单行入口拒绝分摊组；契约 `src/main/resources/openapi/container-fees-v1.yaml`；Admin 消费端见 `../../apps/admin-web/src/modules/loading-lists/api/containerFees.ts` |
 | 财务整柜成本分摊快照 | `loading/controller/InternalFinanceCostSnapshotController.java`、`loading/service/FinanceCostSnapshotService.java` |
-| 分柜、预装、真实柜号后补与正式装柜清单生命周期 | `split/controller/PlatformSplitPreloadController.java`、`controller/PlatformLoadingListController.java`、`service/LoadingListService.java`；契约 `src/main/resources/openapi/loading-lists-v1.yaml`，详情阶段先查 `/loading-plans/{planId}/lifecycle`。创建柜次时原子生成唯一预装计划，加入入仓码明细时同步创建入库预装聚合与关联，不设推送步骤；同一 `planId` 在 `EDITING/LOADING` 返回 `PRELOAD`，`COMPLETED` 返回 `LOADING_LIST`。订单协作备注以 Order 为权威，`OrderRemarksSyncService` 负责订单列表与全部未冻结预装明细双向同步，完成装柜后保留冻结快照。订舱关联、预装确认和 PDA task 创建不依赖真实集装箱号；可在 `EDITING/LOADING` 首次补录，最终 PDA 完成前必须存在；已有值纠正仅限 `EDITING` 且任务未领取、无物理作业事实 |
+| 分柜、预装、真实柜号后补与正式装柜清单生命周期 | `split/controller/PlatformSplitPreloadController.java`、`controller/PlatformLoadingListController.java`、`service/LoadingListService.java`；契约 `src/main/resources/openapi/loading-lists-v1.yaml`，详情阶段先查 `/loading-plans/{planId}/lifecycle`。创建柜次时原子生成唯一预装计划，加入入仓码明细时同步创建入库预装聚合与关联，不设推送步骤；同一 `planId` 在 `EDITING/LOADING` 返回 `PRELOAD`，`COMPLETED` 返回 `LOADING_LIST`。订单协作备注以 Order 为权威，`OrderRemarksSyncService` 负责订单列表与全部未冻结预装明细双向同步，完成装柜后保留冻结快照。订舱关联允许真实集装箱号暂缺；确认预装和创建 PDA task 前必须补齐非空柜号，不按 ISO 格式阻断；可在 `EDITING/LOADING` 首次补录，PDA 完成前再次校验；已有值纠正仅限 `EDITING` 且任务未领取、无物理作业事实 |
 | 同柜不可拆组 | `loading/coload/controller/PlatformColoadGroupController.java`、`service/ColoadGroupService.java`、`persistence/ColoadGroupMapper.java`；契约 `src/main/resources/openapi/coload-groups-v1.yaml`。请求按订单 ID 建组，服务端允许待审核、待测量/测量中、待分柜及装柜中订单，冻结每票全部有效入仓片段与满箱数；成员全部未进柜时创建未锁定组，成员已满箱进入同一装柜计划时直接创建锁定组，部分占用或跨柜时拒绝；仅要求同国内仓、同渠道，允许跨客户及不同目的仓港；分配、移除、取消均保持整组原子 |
 | 货柜与全局智能排柜 | `controller/PlatformContainerController.java`、`PlatformSmartLoadingController.java`、`service/SmartLoadingService.java`、`repository/SmartLoadingRepository.java`、`client/PendingReviewOrderClient.java`、`loading/`；全局候选合并本服务履约投影与 Order `/internal/order/v1/pending-review-orders` 权威待审核页，工作台柜次从 `/inbound-candidates`、`/containers` 进入；普通箱数、待审核占位、同柜组和全部未拣移除分别走 `/inbound-assignments`、`/pending-review-assignments`、`/group-assignments`、`/unpicked-items`，明细规格拆分留在服务端 |
 | 货柜资料、PDA 证据与业务总览 | `controller/PlatformContainerController.java` 的 `/{id}/overview`、`/{id}/documents/{documentType}`，聚合 `mapper/ContainerOverviewMapper.java`；契约 `src/main/resources/openapi/phase3-container-overview-v1.yaml`，四类资料固定为目的港清关、国内出口报关、DO、PU 的当前唯一版本 |
@@ -58,7 +58,7 @@
 | 目的港码头拖车与还空预警 | `terminaldrayage/controller/PlatformTerminalDrayageController.java`、`service/TerminalDrayageService.java`、`mapper/TerminalDrayageMapper.java`；货柜实际到港后引用 Warehouse `ACTIVE/TRUCKING/OVERSEAS` 海外车队供应商，依次选择车队、预约提柜、确认实际提柜，海外仓卸柜或全部直送目的仓实际卸货完成后确认还柜；服务端按卸柜完成时间加 72 小时返回报空预警，实际提柜和还柜通过现有 `CarrierScheduleQueryService` 推进 `PICKED_UP/EMPTY_RETURNED`，不复制船节点或车队主档。契约 `src/main/resources/openapi/terminal-drayage-v1.yaml`，基线 `src/main/resources/db/phase3-terminal-drayage-schema.sql` 邮件由 `terminaldrayage/service/TerminalDrayageMailService.java` 入队，`TerminalDrayageMailDispatcher.java` 顺序投递，模板与 SMTP 配置见 `docs/terminal-drayage-mail.md`；首次选队不发信，换队事务内生成取消与请求两封邮件。 |
 | 船节点交接事件 | `portschedule/service/CarrierScheduleNodeOutboxService.java`；实际节点落库后按 `containerBookingId` 柜级发布 `FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED` V1，信封固定使用 `tenantId=0` 平台技术范围且 Payload 不携带客户，复用 `LoadingCompletedOutboxRepository`/Relay 直投 Lastleg `/internal/lastleg/events`；消费见 `../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java`，ACK/重试按 `../../docs/统一认证与服务通信契约.md` |
 | Firstleg 业务单据编号 | `service/FirstlegDocumentNumberGenerator.java`；前缀与生成规则见 `../../../docs/业务单据编号契约.md`，柜次及实物标签规则保持不变 |
-| 订舱级拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java` 的 `/candidates`、`service/TruckAppointmentService.java`、`repository/TruckAppointmentRepository.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；拖车契约 `src/main/resources/openapi/truck-appointments-v1.yaml`。预约只绑定 `RELEASED` 订舱，候选排除缺提单/有效订舱文件或已有非终态预约的订舱；API 不含客户、柜次、装柜计划或真实柜号，每订舱最多一张有效预约，已有完成单不得重建收费；PDA 完成不推进拖车状态，全部要求货柜确认国内离仓后由 `TruckAppointmentCompletionService` 自动完成并经 `TruckAppointmentFeeService` 发布应付 |
+| 订舱级拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java` 的 `/candidates`、`service/TruckAppointmentService.java`、`repository/TruckAppointmentRepository.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；拖车契约 `src/main/resources/openapi/truck-appointments-v1.yaml`。预约只绑定 `RELEASED` 订舱，候选排除缺提单号或已有非终态预约的订舱；创建及派车不要求订舱文件；API 不含客户、柜次、装柜计划或真实柜号，每订舱最多一张有效预约，已有完成单不得重建收费；PDA 完成不推进拖车状态，全部要求货柜确认国内离仓后由 `TruckAppointmentCompletionService` 自动完成并经 `TruckAppointmentFeeService` 发布应付 |
 | 整柜出口报关 | `customs/container/controller/PlatformContainerCustomsController.java`、`customs/container/controller/MerchantContainerCustomsController.java`、`customs/container/service/ContainerCustomsService.java`、`customs/container/mapper/ContainerCustomsMapper.java`；装柜完成后按柜收集退税资料，多对多覆盖入仓码，开始报关冻结，完成文件逐资料一对一回传，全买单柜由平台确认并通过导出中心取明细；正式申报批次与海关结果在同一模块独立记录，不改报关四态、PDA 或船期事实；契约 `src/main/resources/openapi/customs-v1.yaml`，基线 `src/main/resources/db/phase3-container-customs-schema.sql`；消费者为 Admin `../../apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue` 和 Client `../../apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue` |
 | 买单订单明细导出 Provider | `customs/container/controller/LoadingListBuyDeclarationExportController.java`、`service/LoadingListBuyDeclarationExportService.java`；只为 File 导出中心提供 `LOADING_LIST_BUY_DECLARATION_ITEMS` 的已完成装柜实际买单行，不在 Firstleg 生成文件 |
 | 跨模型桥接 | `loading/bridge/controller/PlatformLoadingModelBridgeController.java` |
@@ -79,8 +79,8 @@
 - 客户箱规配置必须恰好保持四档且默认算法在四行一致；`ADD` 以实测尺寸为基准对三个维度分别增加命中箱规的尺寸值，`MULTIPLY` 使用当前客户唯一默认计费规则，并由服务端按规则中的规格档位选择系数。测量行必须保存实际尺寸、选用规则和算法快照，页面不得自行重算后覆盖服务端结果；计价使用用户确认的重量/体积选择值并纳入幂等请求哈希。
 - 报关、订舱和拖车引用的供应商必须通过 `WarehouseSupplierSnapshotService` 按 ID 向 Warehouse 校验：报关使用 `CUSTOMS`，订舱使用 `BOOKING`（不区分国内/国外 scope），国内拖车使用 `TRUCKING + truckingScope=DOMESTIC`，清关提柜/目的港码头拖车使用 `TRUCKING + truckingScope=OVERSEAS`；供应商必须为 `ACTIVE`。请求中的名称只能作为一致性提示，持久化名称必须来自 Warehouse 快照，禁止用自由文本绕过 ID、类别或启用状态校验。修改任一供应商引用 DTO、OpenAPI 或内部客户端时，必须同步检查三条业务链、Warehouse `supplier-v1.yaml`、数据库快照字段和对应契约测试。
 - Order 渠道变更门禁必须检查装柜或后续状态、PDA task、预装、分柜及同柜组兼容性；任何不确定结果均失败关闭。`ORDER_DECLARATION_UPDATED_V1` 消费必须校验订单号/入仓码归属，永久保留 `eventId + payload hash` 幂等历史并按版本单调更新申报投影；不得覆盖仓库实测、箱码、测量审核或已确认费用。
-- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后永久只读。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
-- 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。
+- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合但不要求订舱附件，放舱后除预计到港外的运输、预报货量、三方和柜型需求只读；预计到港允许通过 `/estimated-arrival` 按编辑权限、版本与幂等键单独维护，保留前后审计快照且不得清空或早于预计开船，不改实际到港或计划到仓；三项实际货量允许通过 `OceanBookingService.updateActualCargo` 按编辑权限、版本、幂等键和原因补录并保存前后审计快照。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
+- 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。预计到港草稿可留空，放舱前必填且不得早于预计开船时间；关联柜次时带入柜级到港来源，供日历和默认到仓日期解析使用。
 - 订舱号遵循 `../../../docs/业务单据编号契约.md`；不得以实体 ID 拼接生成。提单号在订舱主表全局唯一，柜次表只保存快照；真实集装箱号只在同一订舱内唯一，不同提单允许复用。放舱不要求真实柜号，也不得为满足放舱校验伪造柜号。
 - 订舱列表 `containerCount` 固定为该订舱全部柜型需求 `quantity` 之和，与真实柜关联/解除无关；关联候选只返回 `RELEASED`、剩余数量大于 0 且 `warehouseId + channelCode + containerType` 精确匹配的需求，由服务端集合查询 ACTIVE 分配量。前端不得扇出详情计算或用已关联柜数覆盖该字段，最终关联命令仍须重验目标货柜可修改性。
 - 拖车预约是平台级订舱聚合，不是客户或柜次资源：请求、实体、查询、响应和附件不得恢复 `customerId/customerName`，公开 DTO 也不得出现 `containerBookingId/loadingPlanId/cabinetNo/containerNo`。创建候选只返回有提单号、ACTIVE `BOOKING_CONFIRMATION` 或 `BILL_OF_LADING` 且没有非终态拖车单的 `RELEASED` 订舱；创建或编辑只冻结订舱仓库/提单与 TRUCKING/DOMESTIC 国内拖车供应商快照。每订舱通过查询锁与唯一约束最多一张非终态预约，重复创建返回现有派车单号；PDA 装柜完成不得改变拖车状态；只有订舱全部柜型需求均已关联且每柜全部入仓绑定确认国内离仓，才自动完成（含草稿/晚提交）。离仓、拖车创建/编辑/操作统一先锁订舱，完成状态、`AUTO_COMPLETE` 历史、按实装体积守恒分摊的柜次应付及 Finance Outbox 同事务落库；取消/异常单不自动恢复，已有有效或完成单不得重复创建。应付拖车费仅人民币 RMB（财务快照为 CNY），固定使用 `FEE_TYPE_108`，关联 ACTIVE/TRUCKING/DOMESTIC 供应商，零金额不生成费用；正金额缺归属、有效体积或费用配置时失败关闭，不丢费、不伪造均分。手工 DEPART/COMPLETE 动作已移除。附件使用 `tenantId=0 + TRUCK_APPOINTMENT_ATTACHMENT + appointmentId`，提单文件继续归订舱。
@@ -94,7 +94,7 @@
 
 ## 国内货柜履约装柜与 PDA 资源结算
 
-- 新增模拟柜只保存智能装柜的 9 类计划渠道 channel_group_code；未关联已放舱订舱时 channel_code/channel_name 为空，关联后才冻结订舱的实际渠道。智能装柜全局工作台和订舱关联候选均按计划渠道组匹配；服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选支持按创建日期和预计到货日期闭区间筛选，状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、容量、组锁和版本等事实决定；人工加入允许订单国内仓及渠道与柜次不同，智能推荐允许跨国内仓但仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。计划明细通过 `totalPackageCount/remainingPackageCount` 返回可调总量和余量：测量前取 Order 原始申报箱数，进入 `WAIT_SPLIT/LOADING` 后取最新已审核测量箱数；只读补充失败时保守回退当前已分配数，调整写入仍重新查询并校验权威数量。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。真实集装箱号允许在关联已放舱订舱时暂缺，但确认预装及创建 PDA 任务前必须补齐；历史已建但缺号的 PDA 任务可在预装详情首次补录，补录后按柜次当前真实集装箱号恢复作业。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
+- 新增模拟柜只保存智能装柜的 9 类计划渠道 channel_group_code；未关联已放舱订舱时 channel_code/channel_name 为空，关联后才冻结订舱的实际渠道。智能装柜全局工作台和订舱关联候选均按计划渠道组匹配；服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选支持按创建日期和预计到货日期闭区间筛选，状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、容量、组锁和版本等事实决定；人工加入允许订单国内仓及渠道与柜次不同，智能推荐允许跨国内仓但仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。计划明细通过 `totalPackageCount/remainingPackageCount` 返回可调总量和余量：测量前取 Order 原始申报箱数，进入 `WAIT_SPLIT/LOADING` 后取最新已审核测量箱数；只读补充失败时保守回退当前已分配数，调整写入仍重新查询并校验权威数量。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。真实集装箱号允许在关联已放舱订舱时暂缺；关联、运输修改和提柜补录统一只规范化空白和大小写，不以 ISO 长度、结构、设备类别或校验位阻断，数据库不设置 ISO 格式 CHECK，仍遵守同订舱唯一及已有柜号一致性。确认预装、创建 PDA 任务和 PDA 完成只要求真实柜号非空，不再校验 ISO 格式；跨服务装柜、船节点和卸柜事件统一接受非 ISO 柜号，冻结事实仍要求柜号已规范化且与来源柜一致。运输纠错继续遵守原因、版本及 PDA 领取和物理作业冻结限制。确认预装及创建 PDA 任务前必须补齐；历史已建但缺号的 PDA 任务可在预装详情首次补录，补录后按柜次当前真实集装箱号恢复作业。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
 - 预装进入 `CONFIRMING/CONFIRMED` 只固化确认快照，不得锁死尚未完成柜次的智能装柜分配；装柜计划仍处于 `EDITING/LOADING` 时可继续新增，未产生实物拣货的明细可调整或移除，已拣明细保持锁定。一件代发智能装柜候选以每个未被有效柜次占用的已封托托盘为独立分页、展示和分配单位；同一入仓单有多托时必须逐托返回，其中一托已分配不得隐藏或禁用其余未分配托盘。智能推荐必须逐个调用整托分配，容量不足时跳过整托，不得回退按箱分配；全局工作台传入当前 `customerId/inboundCode` 筛选范围时，服务端只能推荐同时命中的候选，同一次推荐按受影响客户统一重算费用，不得逐托重复重算。单行删除必须按该行 `palletId` 整托移除。装柜完成事件必须按计划项 `palletId` 精确冻结每托箱唛与 SKU 清单，不得仅按入仓单或货物明细关联而造成多托交叉重复。
 - 客户入库费用只在登录客户范围、测量审核通过、`feeStatus=SENT` 且存在已发布明细时可见；确认必须具备 `merchant:order:edit`，携带当前 `expectedFeeVersion` 与幂等键。成功后记录确认成员和时间；客户未确认或该票尚未装柜完成时，平台仍可修改箱规规则、生成新费用版本并重新发送，新版本必须清空旧版客户确认快照。仅当“客户已确认且该票已装柜完成”同时成立时最终冻结；装柜完成不得代替客户自动确认。旧版本、未发送或重复异参确认均返回冲突，不做兼容覆盖。
 - PDA 普通散箱拣货以 `fl_inbound_carton_label.box_code` 对应的稳定箱唛箱码为扫描身份；审核建单、重复打印、手工测量和墨家测量复用同一映射，版本字段只用于并发控制，不进入扫码文本。一个有效且未重复的箱码扫描表示拣出一箱，不得以 SKU、商品件数、入库单号或页面展示字段替代箱码。一件代发已封托的 `SEALED_PALLET` 是不可拆整托单元，PDA 可扫描计划快照中的 `palletNo`、用该托任一成员 `boxCode` 反查所属整托，也可在明细卡片手工确认整托；三种入口最终都必须携带权威 `palletNo` 以 `PICK_PALLET` 一次性提交，不能按成员箱逐箱累计、部分拣货或跳拣。PDA 首页从 Warehouse 主档选择启用国内仓，一件代发与装柜待办列表必须按所选 `warehouseId` 服务端过滤；装柜任务内部仍允许跨国内仓，仓库与渠道限制统一由上游装柜编排负责，PDA 只按已生成任务读取各入仓单自身的 `CONFIRMED` 库位资源，不得再用柜次仓库过滤任务明细、库存快照或拣货写入。任务下发与提交契约见 `src/main/resources/openapi/phase3-pda-convergence-v1.yaml`。

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

@@ -211,6 +211,7 @@ public class ContainerCustomsService {
         return platformView(planId);
     }
 
+    /** 全部预录单经客户确认后发送报关行执行，保留版本与发送状态校验。 */
     @Transactional
     public ContainerView submitToBroker(long planId, long operatorId, String operatorName, String key, ActionRequest request) {
         String action = "SUBMIT_CUSTOMS_TO_BROKER_" + planId;
@@ -221,8 +222,8 @@ public class ContainerCustomsService {
         ContainerRow container = mapper.lockContainer(planId);
         if (container == null || !DECLARING.equals(container.status())) throw conflict("当前柜不在报关中");
         if (!Objects.equals(container.version(), request.expectedVersion())) throw concurrent();
-        if (mapper.taxRefundCount(container.loadingPlanId()) == 0) throw conflict("全买单柜无需发送客户回执给报关行");
-        if (mapper.unconfirmedReceiptCount(container.id()) != 0) throw conflict("仍有报关行回执未完成客户确认");
+        if (mapper.taxRefundCount(container.loadingPlanId()) == 0) throw conflict("全买单柜无需发送预录单确认结果给报关行");
+        if (mapper.unconfirmedReceiptCount(container.id()) != 0) throw conflict("仍有预录单未完成客户确认");
         if (mapper.brokerSubmission(container.id()) == null) throw conflict("当前柜尚未完成首次发送报关行资料");
         if (mapper.brokerSubmittedAt(container.id()) != null) throw conflict("当前柜已发送给报关行执行");
         if (mapper.submitToBroker(container.id(), container.version(), operatorId, operatorName) != 1) throw concurrent();
@@ -231,6 +232,7 @@ public class ContainerCustomsService {
         return platformView(planId);
     }
 
+    /** 上传预录单并保存文件版本，已发送报关行执行后仍禁止替换。 */
     @Transactional
     public DocumentView uploadCompletion(long documentId, long operatorId, String operatorName, String key,
                                          int expectedVersion, MultipartFile file) {
@@ -246,7 +248,7 @@ public class ContainerCustomsService {
             throw conflict("当前客户资料不在报关中冻结版本");
         }
         if (mapper.brokerSubmittedAt(container.id()) != null) {
-            throw conflict("客户确认回执已发送给报关行，不可再修改回执");
+            throw conflict("客户确认的预录单已发送给报关行，不可再修改预录单");
         }
         if (mapper.brokerSubmission(container.id()) == null) {
             throw conflict("当前柜尚未完成首次发送报关行资料");
@@ -300,6 +302,7 @@ public class ContainerCustomsService {
         return merchantViewForDocument(tenantId, source);
     }
 
+    /** 预录单确认并发送报关行执行后，接收真实报关完税文件。 */
     @Transactional
     public DocumentView uploadFinalDocument(long documentId, long operatorId, String operatorName, String key,
                                             int expectedVersion, MultipartFile file) {
@@ -316,7 +319,7 @@ public class ContainerCustomsService {
         }
         if (mapper.brokerSubmittedAt(container.id()) == null) throw conflict("客户确认结果尚未发送给报关行");
         CompletionRow receipt = mapper.lockCompletion(documentId);
-        if (receipt == null || !"CONFIRMED".equals(receipt.customerConfirmStatus())) throw conflict("该客户回执尚未确认");
+        if (receipt == null || !"CONFIRMED".equals(receipt.customerConfirmStatus())) throw conflict("该客户的预录单尚未确认");
         FinalRow existing = mapper.lockFinalDocument(documentId);
         CustomsFileClient.Metadata metadata = upload(source.tenantId(), RESULT_FILE_TYPE, Long.toString(container.loadingPlanId()), operatorId, file);
         long finalId;
@@ -371,7 +374,7 @@ public class ContainerCustomsService {
         if (container == null || !(DECLARING.equals(container.status()) || COMPLETED.equals(container.status()))) throw conflict("当前柜尚未进入报关行执行阶段，不能创建正式申报批次");
         if (mapper.taxRefundCount(planId) == 0) throw conflict("全买单柜不创建退税正式申报批次");
         if (mapper.unconfirmedReceiptCount(container.id()) != 0 || mapper.brokerSubmittedAt(container.id()) == null) {
-            throw conflict("当前柜尚未完成退税资料、回执确认和报关行执行");
+            throw conflict("当前柜尚未完成退税资料、预录单确认和报关行执行");
         }
         if (!Objects.equals(container.version(), request.expectedVersion())) throw concurrent();
         long batchId = IdWorker.getId();
@@ -536,14 +539,15 @@ public class ContainerCustomsService {
                 row.operatorName(), row.createdAt())).toList();
     }
 
+    /** 按既有客户范围与可见状态下载预录单，沿用文件真实名称。 */
     public Download downloadCompletion(long tenantId, long documentId, boolean platform) {
         DocumentRow source = requiredDocument(documentId);
         ContainerRow container = mapper.containerById(source.customsContainerId());
         if (!platform && (source.tenantId() != tenantId || container == null || !Set.of(DECLARING, COMPLETED).contains(container.status()))) {
-            throw notFound("报关行回执不存在");
+            throw notFound("预录单不存在");
         }
         CompletionRow completion = mapper.completion(documentId);
-        if (completion == null) throw notFound("报关行回执不存在");
+        if (completion == null) throw notFound("预录单不存在");
         return download(source.tenantId(), RECEIPT_FILE_TYPE, Long.toString(container.loadingPlanId()), completion.fileId(), completion.fileName());
     }
 

firstleg/src/main/java/com/baiyue/firstleg/domain/Iso6346ContainerNumber.java

@@ -1,49 +0,0 @@
-package com.baiyue.firstleg.domain;
-
-import com.baiyue.common.core.api.ResultCode;
-import com.baiyue.common.core.exception.BizException;
-
-import java.util.Locale;
-
-/** ISO 6346 真实集装箱号的唯一规范化与校验入口。 */
-public final class Iso6346ContainerNumber {
-    private static final int[] LETTER_VALUES = {
-        10, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 23, 24,
-        25, 26, 27, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38
-    };
-
-    private Iso6346ContainerNumber() {
-    }
-
-    public static String require(String raw) {
-        String value = normalizeWhitespace(raw);
-        if (value == null || !value.matches("[A-Z]{3}[UJZ][0-9]{7}")) {
-            throw invalid();
-        }
-        int sum = 0;
-        for (int index = 0; index < 10; index++) {
-            char current = value.charAt(index);
-            int number = Character.isDigit(current)
-                ? current - '0' : LETTER_VALUES[current - 'A'];
-            sum += number * (1 << index);
-        }
-        int expected = sum % 11 % 10;
-        if (value.charAt(10) - '0' != expected) throw invalid();
-        return value;
-    }
-
-    private static String normalizeWhitespace(String raw) {
-        if (raw == null) return null;
-        StringBuilder value = new StringBuilder(raw.length());
-        raw.codePoints().filter(codePoint -> !Character.isWhitespace(codePoint)
-                && !Character.isSpaceChar(codePoint))
-            .forEach(value::appendCodePoint);
-        String normalized = value.toString().toUpperCase(Locale.ROOT);
-        return normalized.isEmpty() ? null : normalized;
-    }
-
-    private static BizException invalid() {
-        return new BizException(ResultCode.BAD_REQUEST,
-            "真实集装箱号必须符合ISO 6346结构、设备类别和校验位");
-    }
-}

firstleg/src/main/java/com/baiyue/firstleg/domain/RealContainerNumber.java

@@ -0,0 +1,19 @@
+package com.baiyue.firstleg.domain;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.event.ContainerNumbers;
+
+/** 真实集装箱号录入与作业门禁，与跨服务事件使用同一规范化规则。 */
+public final class RealContainerNumber {
+    private RealContainerNumber() { }
+
+    /** 保留柜号必填要求，不再检查 ISO 长度、设备类别和校验位。 */
+    public static String require(String raw) {
+        try {
+            return ContainerNumbers.normalizeRequired(raw);
+        } catch (IllegalArgumentException exception) {
+            throw new BizException(ResultCode.BAD_REQUEST, "真实集装箱号不能为空");
+        }
+    }
+}

firstleg/src/main/java/com/baiyue/firstleg/dto/TruckAppointmentDtos.java

@@ -3,7 +3,8 @@ import jakarta.validation.constraints.*; import java.math.BigDecimal; import jav
 public final class TruckAppointmentDtos { private TruckAppointmentDtos(){}
  public record Query(@Size(max=64) String keyword, com.baiyue.firstleg.domain.TruckAppointmentStatus status, @Positive Long oceanBookingId, @Min(1) long page, @Min(1) @Max(200) long size){ public Query{if(page==0)page=1;if(size==0)size=20;} }
  public record CandidateQuery(@Size(max=64) String keyword,@Min(1) long page,@Min(1) @Max(200) long size){public CandidateQuery{if(page==0)page=1;if(size==0)size=20;}}
- public record Candidate(Long oceanBookingId,String oceanBookingNo,String billOfLadingNo,Long warehouseId,String warehouseName,String channelCode,String channelName,Boolean bookingDocumentReady){}
+ /** 已放舱订舱候选，预约不依赖订舱附件。 */
+ public record Candidate(Long oceanBookingId,String oceanBookingNo,String billOfLadingNo,Long warehouseId,String warehouseName,String channelCode,String channelName){}
  public record SaveRequest(@Positive Long outboundOrderId,@NotNull @Positive Long oceanBookingId,@Positive Long warehouseId,@NotNull @Positive Long carrierId,@Size(max=128) String carrierName,@Size(max=128) String billOfLadingNo,@Size(max=64) String fleetContact,@Size(max=32) String fleetPhone,@Size(max=64) String driverName,@Size(max=32) String driverPhone,@Size(max=32) String driverIdCard,@Size(max=32) String vehicleNo,@Size(max=128) String storeName,@Size(max=64) String storeContact,@Size(max=32) String storePhone,@Size(max=255) String storeAddress,@Size(max=64) String storeCity,@Size(max=16) String storeZipcode,@PositiveOrZero Integer packageCount,@DecimalMin("0") BigDecimal grossWeightKg,@DecimalMin("0") BigDecimal volumeCbm,@PositiveOrZero Integer palletCount,@Size(max=255) String poNo,@NotNull LocalDateTime plannedLoadingAt,@PositiveOrZero Integer transitMinutes,@DecimalMin("0") @Digits(integer=16,fraction=2) BigDecimal payableAmount,@Pattern(regexp="RMB") String currency,@Size(max=1000) String remark,@NotNull @PositiveOrZero Integer expectedVersion){}
  public record ActionRequest(@NotNull @PositiveOrZero Integer expectedVersion,@Size(max=500) String reason){}
  public record AttachmentRequest(@NotNull @Positive Long fileId,@NotBlank @Pattern(regexp="DISPATCH_ORDER|DRIVER_DOCUMENT|VEHICLE_DOCUMENT|OTHER") String attachmentType,@Size(max=255) String fileName,@Size(max=128) String fileHash){ }

firstleg/src/main/java/com/baiyue/firstleg/mapper/LoadingCompletionCommandMapper.java

@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.LoadingCompletionCommandEntity;
 import org.apache.ibatis.annotations.Insert;
 import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Options;
 import org.apache.ibatis.annotations.Param;
 import org.apache.ibatis.annotations.Select;
 import org.apache.ibatis.annotations.Update;
@@ -55,28 +56,34 @@ public interface LoadingCompletionCommandMapper extends BaseMapper<LoadingComple
     int claim(@Param("id") long id, @Param("worker") String worker,
               @Param("leaseUntil") LocalDateTime leaseUntil);
 
+    /** 只有尚未过期的当前所有者可以续租，过期执行者必须重新领取。 */
     @Update("""
         UPDATE fl_loading_completion_command SET lease_until=#{leaseUntil},updated_at=CURRENT_TIMESTAMP(3)
          WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
         """)
     int renew(@Param("id") long id, @Param("worker") String worker,
               @Param("leaseUntil") LocalDateTime leaseUntil);
 
+    /** 完成落库必须仍持有有效租约，拒绝过期或已易主的旧执行者。 */
     @Update("""
         UPDATE fl_loading_completion_command
            SET command_status='COMPLETED',completed_at=CURRENT_TIMESTAMP(3),updated_at=CURRENT_TIMESTAMP(3),
                lease_owner=NULL,lease_until=NULL,failure_stage=NULL,failure_code=NULL,
                failure_request_id=NULL,failure_trace_id=NULL
          WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
         """)
     int complete(@Param("id") long id, @Param("worker") String worker);
 
+    /** 失败回执也受当前有效租约保护，不能覆盖新执行者的状态。 */
     @Update("""
         UPDATE fl_loading_completion_command
            SET command_status=#{status},next_retry_at=#{nextRetryAt},updated_at=CURRENT_TIMESTAMP(3),
                lease_owner=NULL,lease_until=NULL,failure_stage=#{stage},failure_code=#{code},
                failure_request_id=#{requestId},failure_trace_id=#{traceId}
          WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
         """)
     int fail(@Param("id") long id, @Param("worker") String worker, @Param("status") String status,
              @Param("nextRetryAt") LocalDateTime nextRetryAt, @Param("stage") String stage,
@@ -97,13 +104,32 @@ public interface LoadingCompletionCommandMapper extends BaseMapper<LoadingComple
     String checkpoint(@Param("commandId") long commandId, @Param("tenantId") long tenantId,
                       @Param("inboundId") long inboundId);
 
+    /** 检查点事务锁住当前有效租约，与并发重新领取互斥。 */
+    @Options(useCache = false, flushCache = Options.FlushCachePolicy.TRUE)
+    @Select("""
+        SELECT id FROM fl_loading_completion_command
+         WHERE id=#{commandId} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
+         FOR UPDATE
+        """)
+    Long lockCheckpointLease(@Param("commandId") long commandId, @Param("worker") String worker);
+
+    /** 在已锁定的命令行上重验有效租约；检查点只能前进，不能被迟到写入降级。 */
     @Insert("""
         INSERT INTO fl_loading_completion_checkpoint
           (command_id,tenant_id,inbound_id,owner_sequence,checkpoint_stage)
-        VALUES (#{commandId},#{tenantId},#{inboundId},#{sequence},#{stage})
-        ON DUPLICATE KEY UPDATE checkpoint_stage=VALUES(checkpoint_stage),updated_at=CURRENT_TIMESTAMP(3)
+        SELECT id,#{tenantId},#{inboundId},#{sequence},#{stage}
+          FROM fl_loading_completion_command
+         WHERE id=#{commandId} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
+        ON DUPLICATE KEY UPDATE checkpoint_stage=CASE
+          WHEN checkpoint_stage='INBOUND_COMPLETED' OR #{stage}='INBOUND_COMPLETED'
+            THEN 'INBOUND_COMPLETED'
+          WHEN checkpoint_stage='SETTLED' OR #{stage}='SETTLED' THEN 'SETTLED'
+          ELSE 'READY' END,updated_at=CURRENT_TIMESTAMP(3)
         """)
-    int checkpointCompleted(@Param("commandId") long commandId, @Param("tenantId") long tenantId,
+    int checkpointCompleted(@Param("commandId") long commandId, @Param("worker") String worker,
+                            @Param("tenantId") long tenantId,
                             @Param("inboundId") long inboundId, @Param("sequence") int sequence,
                             @Param("stage") String stage);
 }

firstleg/src/main/java/com/baiyue/firstleg/mapper/TruckAppointmentMapper.java

@@ -1,15 +1,14 @@
 package com.baiyue.firstleg.mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baiyue.firstleg.dto.TruckAppointmentDtos.*; import com.baiyue.firstleg.entity.TruckAppointmentEntity; import org.apache.ibatis.annotations.*;
 @Mapper public interface TruckAppointmentMapper extends BaseMapper<TruckAppointmentEntity>{
+ /** 查询已放舱且有提单号的可预约订舱，不依赖附件。 */
  @Select("""
   <script>
   SELECT o.id oceanBookingId,o.booking_no oceanBookingNo,o.bill_of_lading_no billOfLadingNo,
          o.warehouse_id warehouseId,o.warehouse_name warehouseName,o.channel_code channelCode,
-         o.channel_name channelName,TRUE bookingDocumentReady
+         o.channel_name channelName
     FROM fl_ocean_booking o
-   WHERE EXISTS (SELECT 1 FROM fl_ocean_booking_document d WHERE d.ocean_booking_id=o.id
-                  AND d.valid=1 AND d.document_type IN ('BOOKING_CONFIRMATION','BILL_OF_LADING'))
-     AND o.status='RELEASED' AND o.bill_of_lading_no IS NOT NULL AND o.bill_of_lading_no&lt;&gt;''
+   WHERE o.status='RELEASED' AND o.bill_of_lading_no IS NOT NULL AND o.bill_of_lading_no&lt;&gt;''
      AND NOT EXISTS (SELECT 1 FROM fl_truck_appointment t WHERE t.ocean_booking_id=o.id
                       AND t.status NOT IN ('CANCELLED','EXCEPTION'))
      AND (#{q.keyword} IS NULL OR o.booking_no LIKE CONCAT('%',#{q.keyword},'%')

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/controller/PlatformOceanBookingController.java

@@ -126,6 +126,28 @@ public class PlatformOceanBookingController {
     @PutMapping("/{oceanBookingId}") @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:edit')")
     @BusinessAudit(event="OCEAN_BOOKING_UPDATE_DRAFT", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="编辑海运订舱草稿")
     public ApiResponse<Detail> updateDraft(@AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key, @Valid @RequestBody UpdateRequest request) { validateOptionalCustomer(user, request.data().customerId()); return ApiResponse.success(service.updateDraft(oceanBookingId, user.userId(), user.username(), key, request)); }
+    /** 放舱后单独维护预计到港，其他运输资料仍冻结。 */
+    @PutMapping("/{oceanBookingId}/estimated-arrival")
+    @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:edit')")
+    @BusinessAudit(event="OCEAN_BOOKING_UPDATE_ESTIMATED_ARRIVAL", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="维护订舱预计到港")
+    public ApiResponse<Detail> updateEstimatedArrival(@AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key,
+        @Valid @RequestBody EstimatedArrivalRequest request) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.updateEstimatedArrival(oceanBookingId, user.userId(), user.username(), key, request));
+    }
+
+    /** 客服在放舱后补录实货量，沿用订舱编辑权限并记录审计。 */
+    @PutMapping("/{oceanBookingId}/actual-cargo")
+    @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:edit')")
+    @BusinessAudit(event="OCEAN_BOOKING_UPDATE_ACTUAL_CARGO", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="补录订舱实际货量")
+    public ApiResponse<Detail> updateActualCargo(@AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key,
+        @Valid @RequestBody ActualCargoRequest request) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.updateActualCargo(oceanBookingId, user.userId(), user.username(), key, request));
+    }
+
     @DeleteMapping("/{oceanBookingId}") @PreAuthorize("hasAuthority('platform:firstleg:ocean-booking:delete')")
     @BusinessAudit(event="OCEAN_BOOKING_DELETE_DRAFT", resourceType="OCEAN_BOOKING", resourceId="#oceanBookingId", description="删除海运订舱草稿")
     public ApiResponse<Void> deleteDraft(@AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long oceanBookingId, @RequestHeader("Idempotency-Key") String key, @Valid @RequestBody ActionRequest request) { FirstlegScopeGuard.platform(user); service.deleteDraft(oceanBookingId, user.userId(), user.username(), key, request); return ApiResponse.success(null); }

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/dto/OceanBookingDtos.java

@@ -45,10 +45,12 @@ public final class OceanBookingDtos {
                                 String customerName, String warehouseName, String channelName) {}
 
     public record PartyRequest(@NotBlank @Size(max = 24) String partyType,
-                               @NotBlank @Size(max = 255) String partyName,
+                               @NotNull @Size(max = 255) String partyName,
                                @Size(max = 1000) String address,
                                @Size(max = 128) String contactName,
-                               @Size(max = 64) String contactPhone) {}
+                               @Size(max = 64) String contactPhone,
+                               @jakarta.validation.constraints.Email @Size(max = 255) String contactEmail,
+                               @Size(max = 128) String taxNo) {}
 
     public record ContainerRequirementRequest(@NotBlank @Size(max = 32) String containerType,
                                    @NotBlank @Size(max = 32) String containerKind,
@@ -76,7 +78,35 @@ public final class OceanBookingDtos {
                             LocalDateTime estimatedArrivalAt,
                             @Size(max = 1000) String remark,
                             @Valid @Size(max = 3) List<PartyRequest> parties,
-                            @Valid @Size(max = 20) List<ContainerRequirementRequest> containerRequirements) {}
+                            @Valid @Size(max = 20) List<ContainerRequirementRequest> containerRequirements,
+                            @Size(max = 64) String freightTerm,
+                            @Size(max = 64) String serviceTerm,
+                            @Pattern(regexp = "CARTONS|PCS|PALLETS") String packageUnit,
+                            @Size(max = 1000) String cargoDescription,
+                            @Size(max = 1000) String marksAndNos,
+                            @Min(1) @Max(999999999) Integer declaredPackageCount,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal declaredGrossWeightKg,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal declaredVolumeCbm,
+                            @Min(1) @Max(999999999) Integer actualPackageCount,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualGrossWeightKg,
+                            @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                            @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualVolumeCbm) {}
+
+    /** 放舱后仅维护预计到港，不接收其他运输资料。 */
+    public record EstimatedArrivalRequest(@NotNull @Min(0) Integer expectedVersion,
+                                         @NotNull LocalDateTime estimatedArrivalAt) {}
+
+    /** 放舱后的受控实货量补录，不接收运输资料。 */
+    public record ActualCargoRequest(@NotNull @Min(0) Integer expectedVersion,
+                                    @Min(1) @Max(999999999) Integer actualPackageCount,
+                                    @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                                    @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualGrossWeightKg,
+                                    @jakarta.validation.constraints.DecimalMin(value = "0", inclusive = false)
+                                    @jakarta.validation.constraints.Digits(integer = 12, fraction = 3) BigDecimal actualVolumeCbm,
+                                    @NotBlank @Size(max = 1000) String reason) {}
 
     public record CreateRequest(@NotNull @Min(0) Integer expectedVersion,
                                 @Valid @NotNull DraftData data) {}

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/entity/OceanBookingEntity.java

@@ -40,6 +40,17 @@ public class OceanBookingEntity {
     private LocalDateTime estimatedSailingAt;
     private LocalDateTime estimatedArrivalAt;
     private String remark;
+    private String freightTerm;
+    private String serviceTerm;
+    private String packageUnit;
+    private String cargoDescription;
+    private String marksAndNos;
+    private Integer declaredPackageCount;
+    private java.math.BigDecimal declaredGrossWeightKg;
+    private java.math.BigDecimal declaredVolumeCbm;
+    private Integer actualPackageCount;
+    private java.math.BigDecimal actualGrossWeightKg;
+    private java.math.BigDecimal actualVolumeCbm;
     private Long createdBy;
     private String createdByName;
     @TableField(fill = FieldFill.INSERT) private LocalDateTime createdAt;

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/entity/OceanBookingPartyEntity.java

@@ -17,4 +17,6 @@ public class OceanBookingPartyEntity {
     private String address;
     private String contactName;
     private String contactPhone;
+    private String contactEmail;
+    private String taxNo;
 }

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/mapper/OceanBookingMapper.java

@@ -25,8 +25,22 @@ public interface OceanBookingMapper extends BaseMapper<OceanBookingEntity> {
         """)
     int touchDraft(@Param("id") long id, @Param("expectedVersion") int expectedVersion,
                    @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
-    @Update("UPDATE fl_ocean_booking SET customer_id=#{value.customerId},customer_name=#{value.customerName},channel_code=#{value.channelCode},channel_name=#{value.channelName},warehouse_id=#{value.warehouseId},warehouse_name=#{value.warehouseName},bill_of_lading_no=#{value.billOfLadingNo},shipping_company_id=#{value.shippingCompanyId},shipping_company_name=#{value.shippingCompanyName},carrier_code=#{value.carrierCode},booking_agent_id=#{value.bookingAgentId},booking_agent_name=#{value.bookingAgentName},vessel_name=#{value.vesselName},voyage_no=#{value.voyageNo},departure_port_code=#{value.departurePortCode},departure_port_name=#{value.departurePortName},destination_port_code=#{value.destinationPortCode},destination_port_name=#{value.destinationPortName},place_of_delivery=#{value.placeOfDelivery},estimated_sailing_at=#{value.estimatedSailingAt},estimated_arrival_at=#{value.estimatedArrivalAt},remark=#{value.remark},updated_by=#{operatorId},updated_by_name=#{operatorName},version=version+1,updated_at=NOW() WHERE id=#{id} AND status='DRAFT' AND version=#{version}")
+    @Update("UPDATE fl_ocean_booking SET customer_id=#{value.customerId},customer_name=#{value.customerName},channel_code=#{value.channelCode},channel_name=#{value.channelName},warehouse_id=#{value.warehouseId},warehouse_name=#{value.warehouseName},bill_of_lading_no=#{value.billOfLadingNo},shipping_company_id=#{value.shippingCompanyId},shipping_company_name=#{value.shippingCompanyName},carrier_code=#{value.carrierCode},booking_agent_id=#{value.bookingAgentId},booking_agent_name=#{value.bookingAgentName},vessel_name=#{value.vesselName},voyage_no=#{value.voyageNo},departure_port_code=#{value.departurePortCode},departure_port_name=#{value.departurePortName},destination_port_code=#{value.destinationPortCode},destination_port_name=#{value.destinationPortName},place_of_delivery=#{value.placeOfDelivery},estimated_sailing_at=#{value.estimatedSailingAt},estimated_arrival_at=#{value.estimatedArrivalAt},remark=#{value.remark},freight_term=#{value.freightTerm},service_term=#{value.serviceTerm},package_unit=#{value.packageUnit},cargo_description=#{value.cargoDescription},marks_and_nos=#{value.marksAndNos},declared_package_count=#{value.declaredPackageCount},declared_gross_weight_kg=#{value.declaredGrossWeightKg},declared_volume_cbm=#{value.declaredVolumeCbm},actual_package_count=#{value.actualPackageCount},actual_gross_weight_kg=#{value.actualGrossWeightKg},actual_volume_cbm=#{value.actualVolumeCbm},updated_by=#{operatorId},updated_by_name=#{operatorName},version=version+1,updated_at=NOW() WHERE id=#{id} AND status='DRAFT' AND version=#{version}")
     int updateDraft(@Param("id") long id, @Param("value") OceanBookingEntity value, @Param("version") int version, @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
+    /** 已放舱预计到港窄更新，保留状态、版本和操作审计。 */
+    @Update("UPDATE fl_ocean_booking SET estimated_arrival_at=#{estimatedArrivalAt},updated_by=#{operatorId},updated_by_name=#{operatorName},updated_at=CURRENT_TIMESTAMP(3),version=version+1 WHERE id=#{id} AND status='RELEASED' AND version=#{version}")
+    int updateEstimatedArrival(@Param("id") long id, @Param("estimatedArrivalAt") java.time.LocalDateTime estimatedArrivalAt,
+        @Param("version") int version, @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
+
+    /** 已放舱补实只更新白名单字段，保留乐观锁及状态门禁。 */
+    @Update("""
+        UPDATE fl_ocean_booking SET actual_package_count=#{value.actualPackageCount},
+          actual_gross_weight_kg=#{value.actualGrossWeightKg},actual_volume_cbm=#{value.actualVolumeCbm},
+          updated_by=#{operatorId},updated_by_name=#{operatorName},updated_at=CURRENT_TIMESTAMP(3),version=version+1
+        WHERE id=#{value.id} AND status='RELEASED' AND version=#{version}
+        """)
+    int updateActualCargo(@Param("value") OceanBookingEntity value, @Param("version") int version,
+                          @Param("operatorId") long operatorId, @Param("operatorName") String operatorName);
     @Delete("DELETE FROM fl_ocean_booking WHERE id=#{id} AND status='DRAFT' AND version=#{version}")
     int deleteDraft(@Param("id") long id, @Param("version") int version);
     @Select("""

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/repository/OceanBookingRepository.java

@@ -54,6 +54,15 @@ public class OceanBookingRepository {
     public int touchDraft(long id, int version, long operatorId, String operatorName) {
         return bookings.touchDraft(id, version, operatorId, operatorName);
     }
+    /** 按订舱版本仅更新已放舱预计到港，不重写其他运输或货量资料。 */
+    public int updateEstimatedArrival(long id, java.time.LocalDateTime estimatedArrivalAt, int version, long operatorId, String operatorName) {
+        return bookings.updateEstimatedArrival(id, estimatedArrivalAt, version, operatorId, operatorName);
+    }
+
+    /** 只更新已放舱订舱的实际货量，运输快照保持冻结。 */
+    public int updateActualCargo(OceanBookingEntity value, int version, long operatorId, String operatorName) {
+        return bookings.updateActualCargo(value, version, operatorId, operatorName);
+    }
     public int deleteDraft(long id, int version) {
         return bookings.deleteDraft(id, version);
     }

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingPrintService.java

@@ -46,7 +46,7 @@ public class OceanBookingPrintService {
         String fileName = booking.getBookingNo() + "-" + suffix + ".pdf";
         PrintPdfClient.FreightA4PdfRequest request = new PrintPdfClient.FreightA4PdfRequest(
             template, A4, fileName, List.of(new PrintPdfClient.FreightDocument(
-                fields(template, detail), List.of(emptyCargo()))));
+                fields(template, detail), List.of(cargo(template, booking)))));
         try {
             ResponseEntity<byte[]> response = print.generateFreightA4Documents(internalToken, requestId, request);
             MediaType contentType = response.getHeaders().getContentType();
@@ -75,14 +75,21 @@ public class OceanBookingPrintService {
         fields.put("portOfLoading", first(booking.getDeparturePortName(), booking.getDeparturePortCode()));
         fields.put("portOfDischarge", first(booking.getDestinationPortName(), booking.getDestinationPortCode()));
         fields.put("placeOfDelivery", text(booking.getPlaceOfDelivery()));
-        fields.put("serviceTerm", "");
-        fields.put("freightTerm", "");
-        fields.put("totalPackagesInWords", "");
+        fields.put("serviceTerm", text(booking.getServiceTerm()));
+        fields.put("freightTerm", text(booking.getFreightTerm()));
+        Integer count = SHIPPING_INSTRUCTION.equals(template) ? booking.getDeclaredPackageCount() : booking.getActualPackageCount();
+        fields.put("totalPackagesInWords", packageWords(count, booking.getPackageUnit()));
         if (SHIPPING_INSTRUCTION.equals(template)) {
             fields.put("toCompany", text(booking.getBookingAgentName()));
             fields.put("jobNumber", text(booking.getBookingNo()));
             fields.put("etdDate", date(booking.getEstimatedSailingAt()));
-            fields.put("cargoQuantity", "");
+            fields.put("cargoQuantity", detail.containerRequirements().stream()
+                .map(value -> value.getQuantity() + "*" + value.getContainerType()).collect(Collectors.joining(" + ")));
+            OceanBookingPartyEntity shipper = parties.get("SHIPPER");
+            fields.put("picName", shipper == null ? "" : text(shipper.getContactName()));
+            fields.put("picTel", shipper == null ? "" : text(shipper.getContactPhone()));
+            fields.put("apName", text(booking.getBookingAgentName()));
+            fields.put("printDate", java.time.LocalDate.now(java.time.ZoneId.of("Asia/Shanghai")).toString());
             fields.put("carrier", text(booking.getShippingCompanyName()));
             fields.put("bookingAgent", text(booking.getBookingAgentName()));
             fields.put("remark", text(booking.getRemark()));
@@ -98,8 +105,43 @@ public class OceanBookingPrintService {
         return fields;
     }
 
-    private static PrintPdfClient.CargoRow emptyCargo() {
-        return new PrintPdfClient.CargoRow("—", "—", "—", "—", "—", "—");
+    /** 两类单据严格分别读取委、实数据，不以柜型容量或预报量代替实装量。 */
+    private static PrintPdfClient.CargoRow cargo(String template, OceanBookingEntity booking) {
+        boolean declared = SHIPPING_INSTRUCTION.equals(template);
+        Integer count = declared ? booking.getDeclaredPackageCount() : booking.getActualPackageCount();
+        BigDecimal weight = declared ? booking.getDeclaredGrossWeightKg() : booking.getActualGrossWeightKg();
+        BigDecimal volume = declared ? booking.getDeclaredVolumeCbm() : booking.getActualVolumeCbm();
+        return new PrintPdfClient.CargoRow(display(booking.getMarksAndNos()), count == null ? "—" : count.toString(),
+            display(booking.getPackageUnit()), display(booking.getCargoDescription()),
+            weight == null ? "—" : weight.setScale(3, java.math.RoundingMode.HALF_UP).toPlainString() + " KGS",
+            volume == null ? "—" : volume.setScale(3, java.math.RoundingMode.HALF_UP).toPlainString() + " CBM");
+    }
+
+    /** 打印空字段使用统一占位符。 */
+    private static String display(String value) { return text(value).isEmpty() ? "—" : text(value); }
+
+    /** 件数大写跟随所选数据和包装单位生成，未录入时明确留空。 */
+    private static String packageWords(Integer count, String unit) {
+        if (count == null || !org.springframework.util.StringUtils.hasText(unit)) return "";
+        String packaging = count == 1 ? switch (unit) {
+            case "CARTONS" -> "CARTON";
+            case "PALLETS" -> "PALLET";
+            case "PCS" -> "PIECE";
+            default -> unit;
+        } : ("PCS".equals(unit) ? "PIECES" : unit);
+        return "SAY " + words(count) + " " + packaging + " ONLY";
+    }
+
+    /** 将受件数范围约束的正整数转换为英文数量。 */
+    private static String words(int value) {
+        String[] small = {"ZERO", "ONE", "TWO", "THREE", "FOUR", "FIVE", "SIX", "SEVEN", "EIGHT", "NINE", "TEN",
+            "ELEVEN", "TWELVE", "THIRTEEN", "FOURTEEN", "FIFTEEN", "SIXTEEN", "SEVENTEEN", "EIGHTEEN", "NINETEEN"};
+        String[] tens = {"", "", "TWENTY", "THIRTY", "FORTY", "FIFTY", "SIXTY", "SEVENTY", "EIGHTY", "NINETY"};
+        if (value < 20) return small[value];
+        if (value < 100) return tens[value / 10] + (value % 10 == 0 ? "" : " " + words(value % 10));
+        int divisor = value >= 1000000 ? 1000000 : value >= 1000 ? 1000 : 100;
+        String scale = divisor == 1000000 ? "MILLION" : divisor == 1000 ? "THOUSAND" : "HUNDRED";
+        return words(value / divisor) + " " + scale + (value % divisor == 0 ? "" : " " + words(value % divisor));
     }
 
     private static String requirementSummary(List<OceanBookingContainerRequirementEntity> values) {
@@ -110,7 +152,8 @@ public class OceanBookingPrintService {
     private static String party(OceanBookingPartyEntity value) {
         if (value == null) return "";
         return List.of(text(value.getPartyName()), text(value.getAddress()),
-                join(value.getContactName(), value.getContactPhone())).stream()
+                join(value.getContactName(), value.getContactPhone()), text(value.getContactEmail()),
+                text(value.getTaxNo()).isEmpty() ? "" : "TAX NO: " + text(value.getTaxNo())).stream()
             .filter(part -> !part.isEmpty()).collect(Collectors.joining("\n"));
     }
 

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingService.java

@@ -51,7 +51,6 @@ public class OceanBookingService {
     @Resource private WarehouseMasterDataClient warehouses;
     @Resource private WarehousePartnerClient partners;
     @Resource private FirstlegDocumentNumberGenerator documentNumbers;
-    @Resource private OceanBookingDocumentService documents;
     @Resource private com.baiyue.firstleg.service.IamCustomerSnapshotService customers;
     @Value("${baiyue.security.internal-service-token:}") private String internalToken;
     @Value("${baiyue.warehouse.public-tenant-id:0}") private long publicWarehouseTenantId;
@@ -145,6 +144,44 @@ public class OceanBookingService {
         addHistory(id, OceanBookingStatus.DRAFT.name(), OceanBookingStatus.DRAFT.name(), action, null, before, after, operatorId, operatorName);
         return complete(id, operatorId, action, key, detail(after));
     }
+    /** 放舱后单独维护预计到港，按版本和幂等键保存并审计前后快照。 */
+    @Transactional
+    public Detail updateEstimatedArrival(long id, long operatorId, String name, String key, EstimatedArrivalRequest request) {
+        String action = "UPDATE_ESTIMATED_ARRIVAL";
+        Detail replay = claimOrReplay(id, operatorId, action, key, hash(action, id, request));
+        if (replay != null) return replay;
+        OceanBookingEntity before = requiredVersionForUpdate(id, request.expectedVersion());
+        requireStatus(before, OceanBookingStatus.RELEASED);
+        if (request.estimatedArrivalAt() == null) throw badRequest("预计到港时间不能为空");
+        if (before.getEstimatedSailingAt() != null && request.estimatedArrivalAt().isBefore(before.getEstimatedSailingAt())) {
+            throw badRequest("预计到港时间不能早于预计开船时间");
+        }
+        if (repository.updateEstimatedArrival(id, request.estimatedArrivalAt(), request.expectedVersion(), operatorId, name) != 1) throw concurrent();
+        OceanBookingEntity saved = required(id);
+        addHistory(id, before.getStatus(), saved.getStatus(), action, "维护预计到港", before, saved, operatorId, name);
+        return complete(id, operatorId, action, key, detail(saved));
+    }
+
+    /** 放舱后仅补录实货量，版本、幂等结果和修改前后快照在同一事务保存。 */
+    @Transactional
+    public Detail updateActualCargo(long id, long operatorId, String name, String key, ActualCargoRequest request) {
+        String action = "UPDATE_ACTUAL_CARGO";
+        Detail replay = claimOrReplay(id, operatorId, action, key, hash(action, id, request));
+        if (replay != null) return replay;
+        OceanBookingEntity before = requiredVersionForUpdate(id, request.expectedVersion());
+        requireStatus(before, OceanBookingStatus.RELEASED);
+        if (!StringUtils.hasText(request.reason())) throw badRequest("请填写实货量补录或修正原因");
+        validateCargo(request.actualPackageCount(), request.actualGrossWeightKg(), request.actualVolumeCbm());
+        OceanBookingEntity after = objectMapper.convertValue(before, OceanBookingEntity.class);
+        after.setActualPackageCount(request.actualPackageCount());
+        after.setActualGrossWeightKg(request.actualGrossWeightKg());
+        after.setActualVolumeCbm(request.actualVolumeCbm());
+        if (repository.updateActualCargo(after, request.expectedVersion(), operatorId, name) != 1) throw concurrent();
+        OceanBookingEntity saved = required(id);
+        addHistory(id, before.getStatus(), saved.getStatus(), action, request.reason(), before, saved, operatorId, name);
+        return complete(id, operatorId, action, key, detail(saved));
+    }
+
     @Transactional
     public void deleteDraft(long id, long operatorId, String operatorName, String key, ActionRequest request) {
         String action = "DELETE_DRAFT";
@@ -156,6 +193,7 @@ public class OceanBookingService {
         complete(null, operatorId, action, key, new Detail(before, List.of(), List.of(), List.of(), List.of()));
     }
 
+    /** 校验完整订舱资料后放舱，不以附件上传作为前置条件。 */
     @Transactional public Detail release(long id, long operatorId, String name, String key, ReleaseRequest request) {
         String action = "RELEASE";
         Detail replay = claimOrReplay(id, operatorId, action, key, hash(action, id, request));
@@ -164,7 +202,6 @@ public class OceanBookingService {
         requireStatus(before, OceanBookingStatus.DRAFT);
         validateRelease(before, repository.parties(id), repository.requirements(id));
         validateMasterData(before);
-        documents.requireActiveValidDocument(before);
         if (repository.transition(id, OceanBookingStatus.DRAFT.name(), OceanBookingStatus.RELEASED.name(),
             request.expectedVersion(), operatorId, name) != 1) throw concurrent();
         OceanBookingEntity after = required(id);
@@ -209,7 +246,18 @@ public class OceanBookingService {
     private OceanBookingEntity requiredVersionForUpdate(long id, int version) { OceanBookingEntity value = repository.findForUpdate(id); if (value == null) throw new BizException(ResultCode.NOT_FOUND, "订舱单不存在"); if (!Integer.valueOf(version).equals(value.getVersion())) throw concurrent(); return value; }
     private static void requireStatus(OceanBookingEntity value, OceanBookingStatus status) { if (!status.name().equals(value.getStatus())) throw conflict("订舱状态不允许当前操作"); }
 
+    /** 未采集使用空值；已填写的件数、重量和体积必须为正数且不超出存储精度。 */
+    private static void validateCargo(Integer count, java.math.BigDecimal weight, java.math.BigDecimal volume) {
+        if (count != null && (count < 1 || count > 999999999)) throw badRequest("货物件数必须为1到999999999的整数");
+        for (java.math.BigDecimal number : new java.math.BigDecimal[] {weight, volume}) {
+            if (number != null && (number.signum() <= 0 || number.scale() > 3
+                || number.precision() - number.scale() > 12)) throw badRequest("货物重量和体积必须为正数，最多12位整数和3位小数");
+        }
+    }
+
     private void validateDraftStructure(DraftData data) {
+        validateCargo(data.declaredPackageCount(), data.declaredGrossWeightKg(), data.declaredVolumeCbm());
+        validateCargo(data.actualPackageCount(), data.actualGrossWeightKg(), data.actualVolumeCbm());
         boolean hasCustomerId = data.customerId() != null;
         boolean hasCustomerName = StringUtils.hasText(data.customerName());
         if (!hasCustomerId && hasCustomerName) throw badRequest("客户名称不能脱离客户ID提交");
@@ -231,6 +279,7 @@ public class OceanBookingService {
         }
     }
     private static void validateRange(LocalDateTime from, LocalDateTime to) { if (from != null && to != null && to.isBefore(from)) throw badRequest("预计到港时间不能早于预计开船时间"); }
+    /** 放舱要求预计到港，供关联柜次的到港日历及默认到仓日期使用。 */
     private static void validateRelease(OceanBookingEntity booking, List<OceanBookingPartyEntity> parties,
                                         List<OceanBookingContainerRequirementEntity> requirements) {
         if (!StringUtils.hasText(booking.getChannelCode()) || booking.getWarehouseId() == null
@@ -242,6 +291,7 @@ public class OceanBookingService {
             || !StringUtils.hasText(booking.getPlaceOfDelivery())
             || !StringUtils.hasText(booking.getCarrierCode())
             || booking.getBookingAgentId() == null || parties == null || parties.size() != 3
+            || (parties != null && parties.stream().anyMatch(party -> !StringUtils.hasText(party.getPartyName())))
             || requirements == null || requirements.isEmpty()) throw badRequest("订舱资料尚未填写完整，无法发布");
         validateRange(booking.getEstimatedSailingAt(), booking.getEstimatedArrivalAt());
     }
@@ -298,6 +348,17 @@ public class OceanBookingService {
         v.setPlaceOfDelivery(trim(d.placeOfDelivery()));
         v.setEstimatedSailingAt(d.estimatedSailingAt()); v.setEstimatedArrivalAt(d.estimatedArrivalAt());
         v.setRemark(trim(d.remark()));
+        v.setFreightTerm(trim(d.freightTerm()));
+        v.setServiceTerm(trim(d.serviceTerm()));
+        v.setPackageUnit(trim(d.packageUnit()));
+        v.setCargoDescription(trim(d.cargoDescription()));
+        v.setMarksAndNos(trim(d.marksAndNos()));
+        v.setDeclaredPackageCount(d.declaredPackageCount());
+        v.setDeclaredGrossWeightKg(d.declaredGrossWeightKg());
+        v.setDeclaredVolumeCbm(d.declaredVolumeCbm());
+        v.setActualPackageCount(d.actualPackageCount());
+        v.setActualGrossWeightKg(d.actualGrossWeightKg());
+        v.setActualVolumeCbm(d.actualVolumeCbm());
     }
 
     private void requireUniqueBillOfLadingNo(String billOfLadingNo, Long excludedId) {
@@ -370,7 +431,7 @@ public class OceanBookingService {
         return normalized;
     }
 
-    private static List<OceanBookingPartyEntity> parties(long id, List<PartyRequest> requests) { if (requests == null) return List.of(); return requests.stream().map(r -> { OceanBookingPartyEntity v = new OceanBookingPartyEntity(); v.setId(IdWorker.getId()); v.setOceanBookingId(id); v.setPartyType(r.partyType().trim().toUpperCase()); v.setPartyName(r.partyName().trim()); v.setAddress(trim(r.address())); v.setContactName(trim(r.contactName())); v.setContactPhone(trim(r.contactPhone())); return v; }).toList(); }
+    private static List<OceanBookingPartyEntity> parties(long id, List<PartyRequest> requests) { if (requests == null) return List.of(); return requests.stream().map(r -> { OceanBookingPartyEntity v = new OceanBookingPartyEntity(); v.setId(IdWorker.getId()); v.setOceanBookingId(id); v.setPartyType(r.partyType().trim().toUpperCase()); v.setPartyName(r.partyName().trim()); v.setAddress(trim(r.address())); v.setContactName(trim(r.contactName())); v.setContactPhone(trim(r.contactPhone())); v.setContactEmail(trim(r.contactEmail())); v.setTaxNo(trim(r.taxNo())); return v; }).toList(); }
     private static List<OceanBookingContainerRequirementEntity> requirements(long id, List<ContainerRequirementRequest> requests) { if (requests == null) return List.of(); int[] sort = {0}; return requests.stream().map(r -> { var specification = ContainerSpecificationCatalog.requireMatch(r.containerType(), r.capacityCbm(), r.maxWeightKg()); OceanBookingContainerRequirementEntity v = new OceanBookingContainerRequirementEntity(); v.setId(IdWorker.getId()); v.setOceanBookingId(id); v.setContainerType(specification.containerType()); v.setContainerKind(r.containerKind().trim().toUpperCase()); v.setCapacityCbm(specification.capacityCbm()); v.setMaxWeightKg(specification.maxWeightKg()); v.setQuantity(r.quantity()); v.setSortNo(sort[0]++); return v; }).toList(); }
     private WarehouseMasterDataClient.Warehouse requireDomesticTransitWarehouse(long warehouseId) {
         try {

firstleg/src/main/java/com/baiyue/firstleg/portschedule/service/AppointmentForecastService.java

@@ -11,16 +11,27 @@ import java.util.stream.Collectors;
 @Service
 public class AppointmentForecastService {
     public record Forecast(Long containerBookingId,AppointmentForecastMapper.Fact latest,
-                           AppointmentForecastMapper.Fact previous,String timeBasis) { }
+                           AppointmentForecastMapper.Fact previous,String timeBasis,
+                           java.time.LocalDateTime portArrivalAt) { }
     private final AppointmentForecastMapper mapper;
-    public AppointmentForecastService(AppointmentForecastMapper mapper){this.mapper=mapper;}
+    private final com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository sources;
+    /** 读取船节点及日历权威到港来源，不从调用端接收推算日期。 */
+    public AppointmentForecastService(AppointmentForecastMapper mapper,
+        com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository sources) {
+        this.mapper=mapper; this.sources=sources;
+    }
+    /** 返回明确来源柜的到港事实，保留未知日期。 */
     public List<Forecast> batch(List<Long> ids) {
         if(ids==null || ids.isEmpty() || ids.size()>200 || ids.stream().anyMatch(id->id==null || id<=0)
             || new HashSet<>(ids).size()!=ids.size()) throw new ResponseStatusException(HttpStatus.BAD_REQUEST,"每批须提供1至200个不重复的柜次");
         var facts=mapper.latest(ids).stream().collect(Collectors.groupingBy(AppointmentForecastMapper.Fact::containerBookingId));
+        var arrivals=sources.byIds(ids).stream().collect(Collectors.toMap(
+            com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource::containerBookingId,
+            java.util.function.Function.identity()));
         return ids.stream().map(id->{
             var rows=facts.getOrDefault(id,List.of());
-            return new Forecast(id,rows.isEmpty()?null:rows.get(0),rows.size()<2?null:rows.get(1),"SOURCE_LOCAL_UNSPECIFIED");
+            return new Forecast(id,rows.isEmpty()?null:rows.get(0),rows.size()<2?null:rows.get(1),"SOURCE_LOCAL_UNSPECIFIED",
+                arrivals.containsKey(id)?arrivals.get(id).arrivalAt():null);
         }).toList();
     }
 }

firstleg/src/main/java/com/baiyue/firstleg/repository/FbaPricingRepository.java

@@ -383,11 +383,12 @@ public class FbaPricingRepository {
             .set(InboundFeeEntity::getConfirmedAt, now));
     }
 
+    /** 确认费用时保留物流主状态，一件代发待组托也允许确认。 */
     public int markInboundConfirmed(long tenantId, long inboundId) {
         return inbounds.update(null, new LambdaUpdateWrapper<InboundPricingEntity>()
             .eq(InboundPricingEntity::getTenantId, tenantId).eq(InboundPricingEntity::getId, inboundId)
             .in(InboundPricingEntity::getProcessStatus,
-                List.of("FEE_CONFIRMING", "WAIT_PALLET", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"))
+                List.of("FEE_CONFIRMING", "WAIT_PALLET", "WAIT_PALLETIZE", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"))
             .eq(InboundPricingEntity::getFeeStatus, "CALCULATED")
             .set(InboundPricingEntity::getFeeStatus, "CONFIRMED"));
     }

firstleg/src/main/java/com/baiyue/firstleg/repository/LoadingCompletionCommandRepository.java

@@ -4,6 +4,7 @@ import com.baiyue.firstleg.entity.LoadingCompletionCommandEntity;
 import com.baiyue.firstleg.mapper.LoadingCompletionCommandMapper;
 import jakarta.annotation.Resource;
 import org.springframework.stereotype.Repository;
+import org.springframework.transaction.annotation.Transactional;
 
 import java.time.LocalDateTime;
 import java.util.List;
@@ -12,6 +13,9 @@ import java.util.List;
 public class LoadingCompletionCommandRepository {
     @Resource private LoadingCompletionCommandMapper mapper;
 
+    /** 按事务提交后的命令标识读取唯一完成请求。 */
+    public LoadingCompletionCommandEntity command(long id) { return mapper.selectById(id); }
+
     public int insert(LoadingCompletionCommandEntity command) { return mapper.insertCommand(command); }
     public LoadingCompletionCommandEntity operation(String operationId) { return mapper.findByOperation(operationId); }
     public LoadingCompletionCommandEntity active(long taskId) { return mapper.findActiveByTask(taskId); }
@@ -28,7 +32,13 @@ public class LoadingCompletionCommandRepository {
     public String checkpoint(long commandId, long tenantId, long inboundId) {
         return mapper.checkpoint(commandId, tenantId, inboundId);
     }
-    public void checkpoint(long commandId, long tenantId, long inboundId, int sequence, String stage) {
-        mapper.checkpointCompleted(commandId, tenantId, inboundId, sequence, stage);
+    /** 命令行锁覆盖租约检查与检查点写入，旧执行者不能在租约易主后覆盖新结果。 */
+    @Transactional
+    public boolean checkpoint(long commandId, String worker, long tenantId, long inboundId,
+                              int sequence, String stage) {
+        if (mapper.lockCheckpointLease(commandId, worker) == null) return false;
+        int written = mapper.checkpointCompleted(commandId, worker, tenantId, inboundId, sequence, stage);
+        // 同阶段重放可能被驱动计为零行；命令行仍被本事务锁住，重验租约区分幂等与过期拒绝。
+        return written > 0 || mapper.lockCheckpointLease(commandId, worker) != null;
     }
 }

firstleg/src/main/java/com/baiyue/firstleg/service/ContainerService.java

@@ -12,7 +12,7 @@ import com.baiyue.firstleg.dto.ContainerDtos.FullUpdateRequest;
 import com.baiyue.firstleg.dto.ContainerDtos.SaveRequest;
 import com.baiyue.firstleg.dto.ContainerDtos.SimulationCreateRequest;
 import com.baiyue.firstleg.dto.ContainerDtos.OceanBookingLinkRequest;
-import com.baiyue.firstleg.domain.Iso6346ContainerNumber;
+import com.baiyue.firstleg.domain.RealContainerNumber;
 import com.baiyue.firstleg.entity.ContainerBookingEntity;
 import com.baiyue.firstleg.repository.ContainerRepository;
 import com.baiyue.firstleg.pricebookquery.application.model.PriceBookQueryRows.ChannelRow;
@@ -82,15 +82,19 @@ public class ContainerService {
         return value;
     }
 
+    /** 首次关联已放舱订舱，仅规范化柜号并保留关联资格与并发校验。 */
     @Transactional
     public ContainerBookingEntity linkOceanBooking(long id, long operatorId, String operatorName, OceanBookingLinkRequest request) {
         ContainerBookingEntity container = required(id); requireVersion(container, request.expectedVersion()); requireFirstLinkMutable(container);
         if (container.getOceanBookingId() != null) throw conflict("模拟柜已关联真实订舱柜");
         String existingContainerNo = trim(container.getContainerNo());
         String requestedContainerNo = trim(request.containerNo());
-        String containerNo = requestedContainerNo == null
-            ? existingContainerNo
-            : Iso6346ContainerNumber.require(requestedContainerNo);
+        // 本关联入口不按 ISO 长度、结构或校验位阻断，仍统一空白与大小写以核对唯一性。
+        if (requestedContainerNo != null) {
+            requestedContainerNo = trim(requestedContainerNo.replaceAll("[\\p{javaWhitespace}\\p{Z}]", "")
+                .toUpperCase(java.util.Locale.ROOT));
+        }
+        String containerNo = requestedContainerNo == null ? existingContainerNo : requestedContainerNo;
         if (existingContainerNo != null && !existingContainerNo.equals(containerNo)) {
             throw conflict("输入的真实集装箱号与当前柜次已录入柜号不一致，请先在预装运输信息中纠正");
         }
@@ -120,6 +124,7 @@ public class ContainerService {
         return required(id);
     }
 
+    /** 提柜后补录规范化真实柜号，保留同订舱唯一及作业冻结门禁。 */
     @Transactional
     public ContainerBookingEntity assignRealContainerNo(long id, String requestedContainerNo, int expectedVersion,
                                                          long operatorId, String operatorName) {
@@ -134,7 +139,7 @@ public class ContainerService {
             || repository.hasPickTask(id) || repository.hasEvidence(id) || repository.hasDocuments(id)) {
             throw conflict("已进入PDA、证据、单证或不可逆装柜阶段，不能补录真实柜号");
         }
-        String containerNo = Iso6346ContainerNumber.require(requestedContainerNo);
+        String containerNo = RealContainerNumber.require(requestedContainerNo);
         if (repository.containerNoExists(container.getOceanBookingId(), containerNo, id)) {
             throw conflict("当前提单下集装箱号已存在");
         }

firstleg/src/main/java/com/baiyue/firstleg/service/LoadingCompletionWorker.java

@@ -9,37 +9,77 @@ import jakarta.annotation.Resource;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.core.task.TaskExecutor;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.event.TransactionalEventListener;
 
 import java.time.LocalDateTime;
 import java.util.UUID;
+import java.util.concurrent.RejectedExecutionException;
 
-/** Lease-based recovery worker for PDA completion commands. */
+/** 事务提交后立即处理 PDA 完成命令，并按持久化租约定时恢复。 */
 @Service
 public class LoadingCompletionWorker {
     private static final Logger log = LoggerFactory.getLogger(LoadingCompletionWorker.class);
     private static final int MAX_ATTEMPTS = 5;
-    private final String workerId = "pda-completion-" + UUID.randomUUID();
 
     @Resource private LoadingCompletionCommandRepository commands;
     @Resource private LoadingPickRepository picks;
     @Resource private LoadingPickService loadingPicks;
+    @Resource(name = "applicationTaskExecutor") private TaskExecutor completionExecutor;
 
-    @Scheduled(fixedDelayString = "${baiyue.firstleg.pda-completion.fixed-delay-ms:2000}")
-    public void dispatch() {
-        for (LoadingCompletionCommandEntity candidate : commands.due(10)) {
-            if (!commands.claim(candidate.getId(), workerId, LocalDateTime.now().plusMinutes(10))) {
-                continue;
-            }
-            try {
-                loadingPicks.processCompletion(candidate, workerId);
-            } catch (RuntimeException exception) {
-                handleFailure(candidate, exception);
-            }
+    /** 唤醒只发生在受理事务提交后，异步执行不延长 HTTP 受理请求。 */
+    @TransactionalEventListener
+    public void accepted(LoadingPickService.CompletionAccepted accepted) {
+        try {
+            completionExecutor.execute(() -> dispatchAccepted(accepted));
+        } catch (RejectedExecutionException exception) {
+            // 执行器繁忙或关闭时保留持久化命令，仍由定时扫描领取，不能影响已提交回执。
+            log.warn("pda_completion_wakeup_deferred commandId={}", accepted.commandId(), exception);
         }
     }
 
-    private void handleFailure(LoadingCompletionCommandEntity command, RuntimeException exception) {
+    /** 唤醒与恢复共用原子领取；同一命令不会被两个执行入口重复结算。 */
+    private void dispatchAccepted(LoadingPickService.CompletionAccepted accepted) {
+        try {
+            LoadingCompletionCommandEntity command = commands.command(accepted.commandId());
+            if (command != null) process(command, "immediate", accepted.acceptedAtNanos());
+        } catch (RuntimeException exception) {
+            log.warn("pda_completion_wakeup_failed commandId={}", accepted.commandId(), exception);
+        }
+    }
+
+    /** 扫描到期或租约过期命令，覆盖唤醒丢失、进程重启及失败退避恢复。 */
+    @Scheduled(fixedDelayString = "${baiyue.firstleg.pda-completion.fixed-delay-ms:2000}")
+    public void dispatch() {
+        for (LoadingCompletionCommandEntity candidate : commands.due(10)) {
+            process(candidate, "scheduled", System.nanoTime());
+        }
+    }
+
+    /** 保留租约、检查点和失败恢复语义，记录领取及实际处理耗时。 */
+    private void process(LoadingCompletionCommandEntity command, String source, long queuedAt) {
+        // 每次领取使用独立所有者，避免旧执行线程在租约过期、同进程重新领取后继续写入。
+        String leaseOwner = "pda-completion-" + UUID.randomUUID();
+        if (!commands.claim(command.getId(), leaseOwner, LocalDateTime.now().plusMinutes(10))) return;
+        long started = System.nanoTime();
+        boolean succeeded = false;
+        log.info("pda_completion_started commandId={} taskId={} source={} wakeupMs={}",
+            command.getId(), command.getPickTaskId(), source, (started - queuedAt) / 1_000_000);
+        try {
+            loadingPicks.processCompletion(command, leaseOwner);
+            succeeded = true;
+        } catch (RuntimeException exception) {
+            handleFailure(command, leaseOwner, exception);
+        } finally {
+            log.info("pda_completion_finished commandId={} taskId={} source={} durationMs={} succeeded={}",
+                command.getId(), command.getPickTaskId(), source, (System.nanoTime() - started) / 1_000_000,
+                succeeded);
+        }
+    }
+
+    /** 确定性失败关闭任务，其余故障按原退避与最大次数恢复。 */
+    private void handleFailure(LoadingCompletionCommandEntity command, String leaseOwner, RuntimeException exception) {
         Throwable cause = exception instanceof LoadingPickService.CompletionProcessingException
             && exception.getCause() != null ? exception.getCause() : exception;
         String stage = exception instanceof LoadingPickService.CompletionProcessingException staged
@@ -53,7 +93,7 @@ public class LoadingCompletionWorker {
         int attempt = command.getAttemptCount() == null ? 1 : command.getAttemptCount() + 1;
         boolean terminal = isDeterministicLocalBusinessFailure(stage, cause) || attempt >= MAX_ATTEMPTS;
         LocalDateTime retryAt = LocalDateTime.now().plusSeconds(Math.min(300L, 15L << Math.min(attempt - 1, 4)));
-        boolean recorded = commands.fail(command.getId(), workerId, terminal ? "FAILED" : "RETRYABLE", retryAt,
+        boolean recorded = commands.fail(command.getId(), leaseOwner, terminal ? "FAILED" : "RETRYABLE", retryAt,
             stage, code, requestId, traceId);
         if (terminal && recorded) {
             picks.failCompletion(command.getPickTaskId());
@@ -63,6 +103,7 @@ public class LoadingCompletionWorker {
             command.getOperationId(), stage, code, requestId, traceId, attempt, terminal, cause);
     }
 
+    /** 仅将已明确不可重试的本地业务门禁判为终态。 */
     private static boolean isDeterministicLocalBusinessFailure(String stage, Throwable cause) {
         if (!(cause instanceof BizException business)) {
             return false;

firstleg/src/main/java/com/baiyue/firstleg/service/LoadingListService.java

@@ -26,7 +26,7 @@ import com.baiyue.firstleg.loading.bridge.dto.LoadingModelBridgeDtos.Link;
 import com.baiyue.firstleg.repository.LoadingListRepository;
 import com.baiyue.firstleg.repository.LoadingPickRepository;
 import com.baiyue.firstleg.repository.ContainerRepository;
-import com.baiyue.firstleg.domain.Iso6346ContainerNumber;
+import com.baiyue.firstleg.domain.RealContainerNumber;
 import com.baiyue.firstleg.domain.PriceBookChannelCatalog;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.JsonNode;
@@ -493,10 +493,10 @@ public class LoadingListService {
         return repository.preloadDetail(requirePlan(planId));
     }
 
+    /** 未提交柜号时保留原值，首次录入或纠错统一规范化并禁止清空。 */
     private static String targetContainerNo(AggregateRow before, String requested) {
-        if (requested != null) return Iso6346ContainerNumber.require(requested);
-        return StringUtils.hasText(before.getContainerNo())
-            ? Iso6346ContainerNumber.require(before.getContainerNo()) : null;
+        if (requested == null) return StringUtils.hasText(before.getContainerNo()) ? before.getContainerNo() : null;
+        return RealContainerNumber.require(requested);
     }
 
     private static String transportHash(long planId, int version, String containerNo,

firstleg/src/main/java/com/baiyue/firstleg/service/LoadingPickService.java

@@ -23,7 +23,7 @@ import com.baiyue.firstleg.dto.LoadingPickDtos.InboundInventory;
 import com.baiyue.firstleg.dto.LoadingPickDtos.InventorySnapshot;
 import com.baiyue.firstleg.dto.LoadingPickDtos.InventoryUnit;
 import com.baiyue.firstleg.dto.LoadingPickDtos.PendingTask;
-import com.baiyue.firstleg.domain.Iso6346ContainerNumber;
+import com.baiyue.firstleg.domain.RealContainerNumber;
 import com.baiyue.firstleg.client.DomesticPdaOperatorClient;
 import com.baiyue.firstleg.entity.LoadingPickAssignmentEntity;
 import com.baiyue.firstleg.entity.LoadingPickHistoryEntity;
@@ -56,6 +56,7 @@ import jakarta.annotation.Resource;
 import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.transaction.support.TransactionTemplate;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.util.StringUtils;
@@ -87,6 +88,8 @@ public class LoadingPickService {
     @Resource
     private LoadingCompletionCommandRepository completionCommands;
     @Resource
+    private ApplicationEventPublisher completionEvents;
+    @Resource
     private TransactionTemplate completionTransaction;
     @Resource
     private SmartLoadingRepository smartLoadingRepository;
@@ -137,6 +140,7 @@ public class LoadingPickService {
             smartLoadingRepository.items(plan.getId()));
     }
 
+    /** 确认预装前验证作业资格和真实柜号必填。 */
     public List<Link> requirePreloadConfirmationReady(long loadingPlanId) {
         inboundHoldGuard.requirePlanNotHeld(loadingPlanId);
         List<Link> links = loadingModelBridge.requireAllocatedLinksForConfirmation(loadingPlanId);
@@ -148,6 +152,7 @@ public class LoadingPickService {
             if (booking == null || !StringUtils.hasText(booking.getContainerNo())) {
                 throw conflict("确认预装前必须录入真实集装箱号");
             }
+            requireContainerNumberBeforeStarting(booking.getContainerNo());
             var allocation = oceanBookingRepository.allocationByContainer(link.containerBookingId());
             if (allocation == null) throw conflict("确认预装前必须关联真实订舱柜");
             var oceanBooking = oceanBookingRepository.find(allocation.getOceanBookingId());
@@ -161,12 +166,14 @@ public class LoadingPickService {
         return links;
     }
 
+    /** 仅在柜号已满足完成事件要求时创建 PDA 任务，已有任务的重复同步保持原语义。 */
     @Transactional
     public void begin(long planId, String containerNo, long operatorId, String operatorName,
                       List<LoadingPlanItemEntity> planItems) {
         inboundHoldGuard.requirePlanNotHeld(planId);
         LoadingPickTaskEntity task = repository.taskByPlan(planId);
         if (task == null) {
+            requireContainerNumberBeforeStarting(containerNo);
             task = new LoadingPickTaskEntity();
             task.setLoadingPlanId(planId);
             var booking = smartLoadingRepository.booking(smartLoadingRepository.plan(planId).getContainerBookingId());
@@ -552,6 +559,7 @@ public class LoadingPickService {
                     || !completionCommands.resume(replay.getId()) || repository.resumeCompletion(taskId) != 1) {
                     throw conflict("装柜完成命令状态已变化，请刷新后重试");
                 }
+                completionEvents.publishEvent(new CompletionAccepted(replay.getId(), System.nanoTime()));
             }
             return view(requiredTask(taskId), null);
         }
@@ -598,22 +606,37 @@ public class LoadingPickService {
         if (repository.acceptCompletion(taskId, task.getVersion()) != 1) {
             throw conflict("PDA任务版本已变化，请刷新后复核");
         }
+        // 提交后立即唤醒仍经持久化租约领取；回滚不得触发结算，定时扫描继续负责故障恢复。
+        completionEvents.publishEvent(new CompletionAccepted(command.getId(), System.nanoTime()));
         return view(requiredTask(taskId), null);
     }
 
+    /** 本进程事务提交后的唤醒信号，权威命令和恢复事实仍保存在数据库。 */
+    public record CompletionAccepted(long commandId, long acceptedAtNanos) {}
+
+    /** 确认预装和创建 PDA 任务前要求柜号非空，不以 ISO 格式阻断作业。 */
+    private static void requireContainerNumberBeforeStarting(String containerNo) {
+        try {
+            RealContainerNumber.require(containerNo);
+        } catch (BizException exception) {
+            throw conflict("请先在预装运输信息中录入真实集装箱号后再确认预装或启动PDA");
+        }
+    }
+
+    /** 完成前复核真实柜号，以生成一致的跨服务装柜完成事件。 */
     private void requireCompletionContainerNumber(long taskId) {
         ContainerBookingEntity booking = repository.activeBookingByTask(taskId);
         if (booking == null || !StringUtils.hasText(booking.getContainerNo())) {
             throw conflict("PDA确认装柜完成前必须录入真实集装箱号");
         }
         try {
-            Iso6346ContainerNumber.require(booking.getContainerNo());
+            RealContainerNumber.require(booking.getContainerNo());
         } catch (BizException exception) {
-            throw conflict("PDA确认装柜完成前必须录入符合ISO 6346的真实集装箱号");
+            throw conflict("PDA确认装柜完成前必须录入真实集装箱号");
         }
     }
 
-    /** Called only by the completion worker, after its durable lease has committed. */
+    /** 仅在持久化租约领取成功后执行，远程结算不占用受理事务。 */
     public void processCompletion(LoadingCompletionCommandEntity command, String worker) {
         long taskId = command.getPickTaskId();
         inboundHoldGuard.requireTaskNotHeld(taskId);
@@ -625,55 +648,55 @@ public class LoadingPickService {
             .toList();
         if (owners.isEmpty()) throw new CompletionProcessingException("OWNER_DISCOVERY", conflict("PDA任务未关联有效入库单"));
         List<GroupSnapshot> taskGroups = coloadGroups(owners);
-        runCompletionStage("CABINET_EVIDENCE", () ->
+        runCompletionStage(taskId, "CABINET_EVIDENCE", () ->
             cabinetEvidenceService.requireComplete(task.getContainerBookingId()));
-        runCompletionStage("COMPLETED_EVENT_READY", () ->
+        runCompletionStage(taskId, "COMPLETED_EVENT_READY", () ->
             loadingListService.requireCompletedEventReady(task.getLoadingPlanId()));
 
-        // Phase 1 is read-only: cabinet evidence is checked once, then every owner must pass its business gates
-        // before any warehouse resource or inbound status can be changed. This prevents a later customer gate from
-        // leaving earlier customers partially completed.
+        // 全柜所有客户先通过只读门禁，再开始资源结算，避免后续客户失败造成前序客户局部完成。
         for (int index = 0; index < owners.size(); index++) {
             requireCompletionLease(command.getId(), worker);
             LoadingPickItemMapper.InboundOwner owner = owners.get(index);
             String checkpoint = completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId());
             if (!checkpointAtLeast(checkpoint, "SETTLED")) {
-                runCompletionStage("OWNER_READY", () -> loadingDeliveryService.requirePdaCompletionReady(
+                runCompletionStage(taskId, "OWNER_READY", () -> loadingDeliveryService.requirePdaCompletionReady(
                     owner.tenantId(), owner.inboundId()));
                 if (!checkpointAtLeast(checkpoint, "READY")) {
-                    requireCompletionLease(command.getId(), worker);
-                    completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(),
+                    recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(),
                         index + 1, "READY");
                 }
             }
         }
 
-        // Phase 2 is recoverable by per-owner checkpoints and stable idempotency keys. It starts only after the
-        // complete cabinet passed phase 1, while prior deployments' completed checkpoints remain safely resumable.
+        // 全柜门禁通过后，按客户检查点和稳定幂等键逐步结算，已完成的检查点可安全续做。
         for (int index = 0; index < owners.size(); index++) {
             requireCompletionLease(command.getId(), worker);
             LoadingPickItemMapper.InboundOwner owner = owners.get(index);
             String checkpoint = completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId());
             if (!checkpointAtLeast(checkpoint, "SETTLED")) {
-                runCompletionStage("WAREHOUSE_SETTLEMENT", () -> settlementService.settleOwner(
+                runCompletionStage(taskId, "WAREHOUSE_SETTLEMENT", () -> settlementService.settleOwner(
                     taskId, owner.inboundId(), command.getOperatorId(), command.getOperatorName()));
-                requireCompletionLease(command.getId(), worker);
-                completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(), index + 1, "SETTLED");
+                recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(), index + 1, "SETTLED");
             }
             if (!checkpointAtLeast(checkpoint, "INBOUND_COMPLETED")) {
-                runCompletionStage("INBOUND_COMPLETE", () -> loadingDeliveryService.completeAfterPdaSettlement(
+                runCompletionStage(taskId, "INBOUND_COMPLETE", () -> loadingDeliveryService.completeAfterPdaSettlement(
                     owner.tenantId(), owner.inboundId(),
                     command.getOperatorId(), command.getOperatorName(),
                     "PDA-" + command.getOperationId() + '-' + owner.inboundId(), command.getRemark()));
-                requireCompletionLease(command.getId(), worker);
-                completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(), index + 1,
+                recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(), index + 1,
                     "INBOUND_COMPLETED");
             }
         }
-        completionTransaction.executeWithoutResult(ignored -> finalizeCompletion(command, worker, task, taskGroups));
+        long transactionStarted = System.nanoTime();
+        try {
+            completionTransaction.executeWithoutResult(ignored -> finalizeCompletion(command, worker, task, taskGroups));
+        } finally {
+            log.info("pda_completion_transaction taskId={} durationMs={}", taskId,
+                (System.nanoTime() - transactionStarted) / 1_000_000);
+        }
     }
 
-    /** Final Firstleg convergence only; all remote owner settlement calls have completed before this short transaction. */
+    /** 远程结算完成后，仅在短事务内收敛 Firstleg 本地完成事实。 */
     private void finalizeCompletion(LoadingCompletionCommandEntity command, String worker,
                                     LoadingPickTaskEntity task, List<GroupSnapshot> taskGroups) {
         long taskId = task.getId();
@@ -688,11 +711,11 @@ public class LoadingPickService {
             insertOperation(taskId, command.getOperationId(), command.getRequestHash(), "COMPLETE_LOADING",
                 command.getOperatorId(), command.getOperatorName());
         }
-        runCompletionStage("PLAN_COMPLETE", () -> loadingListService.finishFromPda(task.getLoadingPlanId(), taskId,
+        runCompletionStage(taskId, "PLAN_COMPLETE", () -> loadingListService.finishFromPda(task.getLoadingPlanId(), taskId,
             command.getOperatorId(), command.getOperatorName()));
-        runCompletionStage("COMPLETED_EVENT", () -> loadingListService.publishCompletedEvent(task.getLoadingPlanId()));
+        runCompletionStage(taskId, "COMPLETED_EVENT", () -> loadingListService.publishCompletedEvent(task.getLoadingPlanId()));
         for (GroupSnapshot group : taskGroups) {
-            runCompletionStage("COLOAD_CONSUME", () -> coloadGroups.consumeWholeGroup(group.groupId(),
+            runCompletionStage(taskId, "COLOAD_CONSUME", () -> coloadGroups.consumeWholeGroup(group.groupId(),
                 task.getLoadingPlanId(), "PDA-CONSUME-" + hash(command.getOperationId() + '|'
                     + group.groupId()).substring(0, 48), command.getOperatorId(), command.getOperatorName()));
         }
@@ -750,6 +773,14 @@ public class LoadingPickService {
         }
     }
 
+    /** 检查点失去当前有效租约时立即停止，不再推进后续客户或柜次。 */
+    private void recordCompletionCheckpoint(long commandId, String worker, long tenantId, long inboundId,
+                                            int sequence, String stage) {
+        if (!completionCommands.checkpoint(commandId, worker, tenantId, inboundId, sequence, stage)) {
+            throw new CompletionProcessingException("LEASE_LOST", conflict("装柜完成命令租约已变化"));
+        }
+    }
+
     private static void requireSameCompletionCommand(LoadingCompletionCommandEntity command, long taskId,
                                                      String requestHash, long operatorId) {
         if (command == null || !Long.valueOf(taskId).equals(command.getPickTaskId())
@@ -764,11 +795,18 @@ public class LoadingPickService {
         return checkpoint != null && stages.indexOf(checkpoint) >= stages.indexOf(target);
     }
 
-    private static void runCompletionStage(String stage, Runnable action) {
+    /** 记录实际阶段耗时，区分业务处理与调度、前端刷新等待。 */
+    private static void runCompletionStage(long taskId, String stage, Runnable action) {
+        long started = System.nanoTime();
+        boolean succeeded = false;
         try {
             action.run();
+            succeeded = true;
         } catch (RuntimeException exception) {
             throw new CompletionProcessingException(stage, exception);
+        } finally {
+            log.info("pda_completion_stage taskId={} stage={} durationMs={} succeeded={}",
+                taskId, stage, (System.nanoTime() - started) / 1_000_000, succeeded);
         }
     }
 

firstleg/src/main/java/com/baiyue/firstleg/service/TruckAppointmentService.java

@@ -9,7 +9,6 @@ import com.baiyue.firstleg.dto.TruckAppointmentDtos.*;
 import com.baiyue.firstleg.entity.*;
 import com.baiyue.firstleg.oceanbooking.entity.OceanBookingEntity;
 import com.baiyue.firstleg.oceanbooking.repository.OceanBookingRepository;
-import com.baiyue.firstleg.oceanbooking.service.OceanBookingDocumentService;
 import com.baiyue.firstleg.repository.TruckAppointmentRepository;
 import com.baiyue.firstleg.client.TruckAppointmentFileClient;
 import jakarta.annotation.Resource;
@@ -36,7 +35,6 @@ public class TruckAppointmentService {
  @Resource TruckAppointmentRepository repo;
  @Resource TruckAppointmentCompletionService completion;
  @Resource OceanBookingRepository oceanBookings;
- @Resource OceanBookingDocumentService oceanBookingDocuments;
  @Resource TruckAppointmentFileClient files;
  @Resource WarehouseSupplierSnapshotService suppliers;
  @Resource FirstlegDocumentNumberGenerator documentNumbers;
@@ -64,13 +62,13 @@ public class TruckAppointmentService {
   return completeOperation(id,action,idem,enrich(required(id)));
  }
  @Transactional public TruckAppointmentEntity reschedule(long id,LocalDateTime at,ActionRequest r,String idem,String clientHash,long uid,String name){String action="RESCHEDULE";String requestHash=hash(action,id,new ReschedulePayload(at,r));verifyClientHash(clientHash,requestHash);TruckAppointmentEntity replay=claimOrReplay(id,action,idem,requestHash);if(replay!=null)return replay;TruckAppointmentEntity e=required(id);completion.lockBooking(e.getOceanBookingId());checkVersion(e,r.expectedVersion()); if(e.getStatus()==TruckAppointmentStatus.COMPLETED||e.getStatus()==TruckAppointmentStatus.CANCELLED)throw conflict("当前状态不可改约"); TruckAppointmentEntity active=repo.firstActiveForUpdate(e.getOceanBookingId());if(active!=null&&!Objects.equals(active.getId(),e.getId()))throw existingAppointmentConflict(active);String from=e.getStatus().name(); if(repo.reschedule(id,at,r.reason(),e.getVersion())!=1)throw conflict("状态或版本已变化，请刷新后重试");TruckAppointmentEntity after=enrich(required(id));record(after,from,"RESCHEDULED",action,r.reason(),uid,name);completion.completeForBooking(e.getOceanBookingId());return completeOperation(id,action,idem,enrich(required(id)));}
+ /** 从已放舱订舱校验仓库和提单号，附件不作为预约条件。 */
  private AssociationContext validateAssociations(SaveRequest r){
   OceanBookingEntity booking=oceanBookings.find(r.oceanBookingId());
   if(booking==null)throw new BizException(ResultCode.NOT_FOUND,"关联订舱不存在");
   if(!"RELEASED".equals(booking.getStatus()))throw conflict("拖车预约只能选择已放舱订舱");
   Long warehouseId=mergeWarehouse(r.warehouseId(),booking.getWarehouseId(),"订舱");
   String billOfLadingNo=releasedBookingBill(booking,trim(r.billOfLadingNo()));
-  oceanBookingDocuments.requireActiveValidDocument(booking);
   return new AssociationContext(booking,warehouseId,billOfLadingNo);
  }
  private static void validateRequired(SaveRequest r){if(r.oceanBookingId()==null||r.oceanBookingId()<=0)throw bad("oceanBookingId不能为空");if(r.carrierId()==null||r.carrierId()<=0)throw bad("carrierId不能为空");if(r.plannedLoadingAt()==null)throw bad("plannedLoadingAt不能为空");if(r.expectedVersion()==null||r.expectedVersion()<0)throw bad("expectedVersion不合法");if(r.payableAmount()!=null&&(r.payableAmount().signum()<0||r.payableAmount().scale()>2))throw bad("拖车费必须为非负数且最多两位小数");}
@@ -85,13 +83,13 @@ public class TruckAppointmentService {
  private static void verifyClientHash(String clientHash,String serverHash){if(StringUtils.hasText(clientHash)&&!serverHash.equalsIgnoreCase(clientHash.trim()))throw bad("X-Request-Hash与请求内容不一致");}
  private static void validateKey(String key){if(!StringUtils.hasText(key)||key.trim().length()>128)throw bad("Idempotency-Key不能为空且不能超过128个字符");}
  private record ReschedulePayload(LocalDateTime plannedLoadingAt,ActionRequest request){}
+ /** 派车时复核订舱放舱状态及提单号，不要求订舱附件。 */
  private String requireDispatchReady(TruckAppointmentEntity appointment){
   if(appointment.getOceanBookingId()==null)throw conflict("拖车预约缺少订舱关联");
   OceanBookingEntity booking=oceanBookings.find(appointment.getOceanBookingId());
   if(booking==null)throw new BizException(ResultCode.NOT_FOUND,"关联订舱不存在");
   if(!"RELEASED".equals(booking.getStatus()))throw conflict("关联订舱尚未放舱");
   String bill=releasedBookingBill(booking,trim(appointment.getBillOfLadingNo()));
-  oceanBookingDocuments.requireActiveValidDocument(booking);
   return bill;
  }
  private static String releasedBookingBill(OceanBookingEntity booking,String requested){String authoritative=trim(booking.getBillOfLadingNo());if(!StringUtils.hasText(authoritative))throw conflict("关联已放舱订舱缺少提单号");if(StringUtils.hasText(requested)&&!authoritative.equals(requested))throw bad("billOfLadingNo与关联订舱不一致");return authoritative;}

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/mapper/ContainerCalendarSourceMapper.java

@@ -9,10 +9,31 @@ import java.util.List;
 
 @Mapper
 public interface ContainerCalendarSourceMapper {
-    /** 同时选出到港、缺日期和可能还柜的有效出仓柜，最终日期由业务服务复核。 */
+    /** 按明确来源柜读取到港事实；目的港优先显示名称，未填名称时显示已保存代码。 */
+    @Select("""
+        <script>
+        SELECT c.id containerBookingId,c.cabinet_no cabinetNo,c.container_no containerNo,
+          c.vessel_name vesselName,c.voyage_no voyageNo,
+          COALESCE(NULLIF(TRIM(c.destination_port_name),''),NULLIF(TRIM(c.destination_port_code),'')) destinationPortName,
+          c.destination_warehouse_code destinationWarehouseCode,
+          COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at) arrivalAt,
+          CASE WHEN COALESCE(n.actual_at,c.actual_port_arrival_at) IS NOT NULL THEN 'ACTUAL' ELSE 'ESTIMATED' END arrivalType
+        FROM fl_container_booking c
+        LEFT JOIN fl_carrier_schedule_node_fact n ON n.id=(
+          SELECT f.id FROM fl_carrier_schedule_node_fact f WHERE f.container_booking_id=c.id
+            AND f.standard_node='ARRIVED_DESTINATION_PORT' AND f.actual_at IS NOT NULL
+          ORDER BY f.observed_at DESC,f.id DESC LIMIT 1)
+        WHERE c.record_status='ACTIVE' AND c.id IN
+        <foreach collection='ids' item='id' open='(' separator=',' close=')'>#{id}</foreach>
+        </script>
+        """)
+    List<ContainerCalendarSource> byIds(@Param("ids") List<Long> ids);
+
+    /** 选出到港、缺日期和可能还柜的有效出仓柜；目的港名称为空时展示代码，最终日期由服务复核。 */
     @Select("""
         SELECT c.id containerBookingId,c.cabinet_no cabinetNo,c.container_no containerNo,
-          c.vessel_name vesselName,c.voyage_no voyageNo,c.destination_port_name destinationPortName,
+          c.vessel_name vesselName,c.voyage_no voyageNo,
+          COALESCE(NULLIF(TRIM(c.destination_port_name),''),NULLIF(TRIM(c.destination_port_code),'')) destinationPortName,
           c.destination_warehouse_code destinationWarehouseCode,
           COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at) arrivalAt,
           CASE WHEN COALESCE(n.actual_at,c.actual_port_arrival_at) IS NOT NULL THEN 'ACTUAL' ELSE 'ESTIMATED' END arrivalType

firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/repository/ContainerCalendarSourceRepository.java

@@ -11,6 +11,8 @@ public class ContainerCalendarSourceRepository {
     private final ContainerCalendarSourceMapper mapper;
     /** 使用本服务 Mapper 读取日历所需柜级来源。 */
     public ContainerCalendarSourceRepository(ContainerCalendarSourceMapper mapper) { this.mapper = mapper; }
+    /** 内部批量读取明确柜次，日期口径与平台日历一致。 */
+    public List<ContainerCalendarSource> byIds(List<Long> ids) { return mapper.byIds(ids); }
     /** 到港前移两天覆盖默认到仓，直送还柜候选额外留一天覆盖夏令时。 */
     public List<ContainerCalendarSource> sources(LocalDate from, LocalDate to) {
         return mapper.sources(from.atStartOfDay(), from.minusDays(2).atStartOfDay(),

firstleg/src/main/java/com/baiyue/firstleg/workflow/WorkflowTabService.java

@@ -27,7 +27,7 @@ public class WorkflowTabService {
  if(facts.stream().noneMatch(f->f.tenantId()==fee.tenantId() && f.orderId()==fee.orderId())) throw unavailable("费用确认事实不属于本批入仓来源");
  result.putIfAbsent(fee.orderId()+":"+fee.mainStatus(),fee);
  }
- var sources=facts.stream().filter(f->f.departed() || f.clearanceUploaded()).map(f->new WorkflowFacts.Source(f.tenantId(),f.inboundId())).distinct().toList();
+ var sources=facts.stream().filter(WorkflowFacts.Fact::departed).map(f->new WorkflowFacts.Source(f.tenantId(),f.inboundId())).distinct().toList();
  Map<String,WorkflowFacts.Overseas> overseas=new HashMap<>();
  if(!sources.isEmpty()) {
  try {
@@ -61,11 +61,11 @@ public class WorkflowTabService {
  Set<String> keys=new LinkedHashSet<>();
  if("MEASURE_PENDING".equals(process) && "PENDING".equals(f.reviewStatus())) keys.add("MEASUREMENT_REVIEW");
  boolean signed="DELIVERED".equals(process);
- // 报关完成即进入待清关；不再等待船期接口补齐实际离港节点。
- boolean clearanceStage=f.customsCompleted() || f.departed() || f.clearanceUploaded();
+ // 人工补录或船司查询的实际开船节点才推进阶段，报关完成和提前上传资料不能代替开船。
+ boolean clearanceStage=f.departed();
  if(!clearanceStage && !signed) {
  if(f.missingCustoms()) keys.add("WAIT_CUSTOMS_DOCS");
- if(f.exportCustomsReady()) keys.add("EXPORT_CUSTOMS");
+ if(f.exportCustomsReady() || f.customsCompleted()) keys.add("EXPORT_CUSTOMS");
  }
  if(signed) keys.add("SIGNED");
  if(clearanceStage && !signed) {

firstleg/src/main/resources/db/phase3-ocean-booking-schema.sql

@@ -4,7 +4,7 @@ USE baiyue_firstleg;
 CREATE TABLE IF NOT EXISTS fl_ocean_booking (
   id BIGINT UNSIGNED NOT NULL COMMENT '海运订舱ID',
   booking_no VARCHAR(40) NOT NULL COMMENT '平台海运订舱编号',
-  status VARCHAR(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已发布且永久只读',
+  status VARCHAR(24) NOT NULL DEFAULT 'DRAFT' COMMENT '订舱状态：DRAFT草稿、RELEASED已放舱，运输快照冻结且实货量受控补录',
   customer_id BIGINT UNSIGNED NULL COMMENT '可选客户ID快照',
   customer_name VARCHAR(128) NULL COMMENT '可选客户名称快照',
   channel_code VARCHAR(64) NULL COMMENT '订舱计划物流渠道组编码快照',
@@ -27,6 +27,17 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking (
   estimated_sailing_at DATETIME(3) NULL COMMENT '当前确认预计开船时间',
   estimated_arrival_at DATETIME(3) NULL COMMENT '当前确认预计到港时间',
   remark VARCHAR(1000) NULL COMMENT '平台内部备注',
+  freight_term VARCHAR(64) NULL COMMENT '运费条款',
+  service_term VARCHAR(64) NULL COMMENT '运输条款',
+  package_unit VARCHAR(16) NULL COMMENT '包装单位：CARTONS、PCS或PALLETS',
+  cargo_description VARCHAR(1000) NULL COMMENT '货物品名及托运要求',
+  marks_and_nos VARCHAR(1000) NULL COMMENT '唛头和号码',
+  declared_package_count INT UNSIGNED NULL COMMENT '订舱预报件数（委）',
+  declared_gross_weight_kg DECIMAL(15,3) NULL COMMENT '订舱预报毛重kg（委）',
+  declared_volume_cbm DECIMAL(15,3) NULL COMMENT '订舱预报体积cbm（委）',
+  actual_package_count INT UNSIGNED NULL COMMENT '客服手工实货件数',
+  actual_gross_weight_kg DECIMAL(15,3) NULL COMMENT '客服手工实货毛重kg',
+  actual_volume_cbm DECIMAL(15,3) NULL COMMENT '客服手工实货体积cbm',
   created_by BIGINT UNSIGNED NOT NULL COMMENT '创建操作人ID',
   created_by_name VARCHAR(64) NULL COMMENT '创建操作人姓名快照',
   created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '订舱记录创建时间',
@@ -44,6 +55,14 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking (
     ('DRAFT','RELEASED')),
   CONSTRAINT chk_ocean_booking_carrier_code CHECK
     (carrier_code IS NULL OR carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER')),
+  CONSTRAINT chk_ocean_booking_cargo CHECK (
+    (package_unit IS NULL OR package_unit IN ('CARTONS','PCS','PALLETS'))
+    AND (declared_package_count IS NULL OR declared_package_count BETWEEN 1 AND 999999999)
+    AND (actual_package_count IS NULL OR actual_package_count BETWEEN 1 AND 999999999)
+    AND (declared_gross_weight_kg IS NULL OR declared_gross_weight_kg > 0)
+    AND (actual_gross_weight_kg IS NULL OR actual_gross_weight_kg > 0)
+    AND (declared_volume_cbm IS NULL OR declared_volume_cbm > 0)
+    AND (actual_volume_cbm IS NULL OR actual_volume_cbm > 0)),
   CONSTRAINT chk_ocean_booking_schedule CHECK
     (estimated_sailing_at IS NULL OR estimated_arrival_at IS NULL OR estimated_arrival_at >= estimated_sailing_at)
 ) ENGINE=InnoDB COMMENT='独立海运订舱聚合；柜次仍由fl_container_booking承载';
@@ -110,6 +129,8 @@ CREATE TABLE IF NOT EXISTS fl_ocean_booking_party (
   address VARCHAR(1000) NULL COMMENT '关系方地址快照',
   contact_name VARCHAR(128) NULL COMMENT '关系方联系人快照',
   contact_phone VARCHAR(64) NULL COMMENT '关系方联系电话快照',
+  contact_email VARCHAR(255) NULL COMMENT '关系方联系邮箱',
+  tax_no VARCHAR(128) NULL COMMENT '关系方税号',
   PRIMARY KEY (id),
   UNIQUE KEY uk_ocean_booking_party (ocean_booking_id,party_type),
   CONSTRAINT fk_ocean_booking_party FOREIGN KEY (ocean_booking_id) REFERENCES fl_ocean_booking(id) ON DELETE CASCADE,
@@ -211,8 +232,46 @@ DROP TRIGGER IF EXISTS trg_ocean_booking_before_update;
 DELIMITER $$
 CREATE TRIGGER trg_ocean_booking_before_update BEFORE UPDATE ON fl_ocean_booking FOR EACH ROW
 BEGIN
-  IF OLD.status = 'RELEASED' THEN
-    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱订舱不可修改';
+  -- 已放舱只允许预计到港、实货量及审计元数据变化，其余运输和预报快照保持冻结。
+  IF OLD.status = 'RELEASED' AND NOT (
+    (NEW.id <=> OLD.id)
+    AND (NEW.booking_no <=> OLD.booking_no)
+    AND (NEW.status <=> OLD.status)
+    AND (NEW.customer_id <=> OLD.customer_id)
+    AND (NEW.customer_name <=> OLD.customer_name)
+    AND (NEW.channel_code <=> OLD.channel_code)
+    AND (NEW.channel_name <=> OLD.channel_name)
+    AND (NEW.warehouse_id <=> OLD.warehouse_id)
+    AND (NEW.warehouse_name <=> OLD.warehouse_name)
+    AND (NEW.bill_of_lading_no <=> OLD.bill_of_lading_no)
+    AND (NEW.shipping_company_id <=> OLD.shipping_company_id)
+    AND (NEW.shipping_company_name <=> OLD.shipping_company_name)
+    AND (NEW.carrier_code <=> OLD.carrier_code)
+    AND (NEW.booking_agent_id <=> OLD.booking_agent_id)
+    AND (NEW.booking_agent_name <=> OLD.booking_agent_name)
+    AND (NEW.vessel_name <=> OLD.vessel_name)
+    AND (NEW.voyage_no <=> OLD.voyage_no)
+    AND (NEW.departure_port_code <=> OLD.departure_port_code)
+    AND (NEW.departure_port_name <=> OLD.departure_port_name)
+    AND (NEW.destination_port_code <=> OLD.destination_port_code)
+    AND (NEW.destination_port_name <=> OLD.destination_port_name)
+    AND (NEW.place_of_delivery <=> OLD.place_of_delivery)
+    AND (NEW.estimated_sailing_at <=> OLD.estimated_sailing_at)
+    AND (NEW.remark <=> OLD.remark)
+    AND (NEW.freight_term <=> OLD.freight_term)
+    AND (NEW.service_term <=> OLD.service_term)
+    AND (NEW.package_unit <=> OLD.package_unit)
+    AND (NEW.cargo_description <=> OLD.cargo_description)
+    AND (NEW.marks_and_nos <=> OLD.marks_and_nos)
+    AND (NEW.declared_package_count <=> OLD.declared_package_count)
+    AND (NEW.declared_gross_weight_kg <=> OLD.declared_gross_weight_kg)
+    AND (NEW.declared_volume_cbm <=> OLD.declared_volume_cbm)
+    AND (NEW.created_by <=> OLD.created_by)
+    AND (NEW.created_by_name <=> OLD.created_by_name)
+    AND (NEW.created_at <=> OLD.created_at)
+    AND NEW.version = OLD.version + 1
+  ) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='已放舱仅允许维护预计到港及补录实货量';
   END IF;
   IF OLD.status <> NEW.status AND NOT (
        (OLD.status='DRAFT' AND NEW.status='RELEASED')) THEN

firstleg/src/main/resources/db/phase3-smart-loading-schema.sql

@@ -35,7 +35,7 @@ CREATE TABLE IF NOT EXISTS fl_document_sequence (
 
 CREATE TABLE IF NOT EXISTS fl_container_booking (
   id BIGINT UNSIGNED NOT NULL COMMENT '货柜预订ID（雪花ID）',
-  container_no VARCHAR(64) NULL COMMENT '国内柜次真实集装箱号权威快照；ISO 6346标准格式；同一订舱内唯一，不同提单允许复用；订舱关联可选写入、提柜后可原子补录、预装纠错命令可修改',
+  container_no VARCHAR(64) NULL COMMENT '国内柜次真实集装箱号权威快照；订舱关联不限制ISO格式；同一订舱内唯一，不同提单允许复用；订舱关联可选写入、提柜后可原子补录、预装纠错命令可修改',
   cabinet_no VARCHAR(64) NOT NULL COMMENT '平台唯一内部柜号',
   source_type VARCHAR(24) NOT NULL DEFAULT 'SIMULATION' COMMENT '记录来源：SIMULATION内部模拟柜、OCEAN_BOOKING订舱真实柜',
   record_status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT '记录状态：ACTIVE可操作、MERGED已合并历史',
@@ -100,9 +100,7 @@ CREATE TABLE IF NOT EXISTS fl_container_booking (
   CONSTRAINT chk_container_booking_record_status CHECK (record_status IN ('ACTIVE','MERGED')),
   CONSTRAINT chk_container_booking_capacity CHECK (capacity_cbm IS NULL OR capacity_cbm > 0),
   CONSTRAINT chk_container_booking_weight CHECK (max_weight_kg IS NULL OR max_weight_kg > 0),
-  CONSTRAINT chk_container_booking_pickup_code CHECK (pickup_code IS NULL OR pickup_code REGEXP '^[0-9]{1,64}$'),
-  CONSTRAINT chk_container_booking_iso6346 CHECK
-    (container_no IS NULL OR container_no REGEXP '^[A-Z]{3}[UJZ][0-9]{7}$')
+  CONSTRAINT chk_container_booking_pickup_code CHECK (pickup_code IS NULL OR pickup_code REGEXP '^[0-9]{1,64}$')
 ) ENGINE=InnoDB COMMENT='平台货柜预订资料；预装状态唯一来源为装柜计划';
 
 CREATE TABLE IF NOT EXISTS fl_container_event_inbox (
@@ -228,11 +226,6 @@ BEGIN
     ALTER TABLE fl_container_booking ADD CONSTRAINT chk_container_booking_record_status
       CHECK (record_status IN ('ACTIVE','MERGED'));
   END IF;
-  IF NOT EXISTS (SELECT 1 FROM information_schema.table_constraints WHERE constraint_schema=DATABASE()
-      AND table_name='fl_container_booking' AND constraint_name='chk_container_booking_iso6346') THEN
-    ALTER TABLE fl_container_booking ADD CONSTRAINT chk_container_booking_iso6346
-      CHECK (container_no IS NULL OR container_no REGEXP '^[A-Z]{3}[UJZ][0-9]{7}$');
-  END IF;
   IF NOT EXISTS (SELECT 1 FROM information_schema.table_constraints WHERE constraint_schema=DATABASE()
       AND table_name='fl_container_booking' AND constraint_name='chk_container_booking_pickup_code') THEN
     ALTER TABLE fl_container_booking ADD CONSTRAINT chk_container_booking_pickup_code

firstleg/src/main/resources/openapi/appointment-calendar-sources-v1.yaml

@@ -40,7 +40,7 @@ paths:
                             containerNo: {type: string, nullable: true}
                             vesselName: {type: string, nullable: true}
                             voyageNo: {type: string, nullable: true}
-                            destinationPortName: {type: string, nullable: true}
+                            destinationPortName: {type: string, nullable: true, description: 目的港展示值，优先名称，名称为空时使用已保存的港口代码，两者均为空时返回null}
                             destinationWarehouseCode: {type: string, nullable: true}
                             arrivalAt: {type: string, format: date-time, nullable: true}
                             arrivalType: {type: string, enum: [ACTUAL, ESTIMATED]}

firstleg/src/main/resources/openapi/appointment-forecasts-internal-v1.yaml

@@ -34,6 +34,7 @@ paths:
                       properties:
                         containerBookingId: {type: string}
                         timeBasis: {type: string, enum: [SOURCE_LOCAL_UNSPECIFIED]}
+                        portArrivalAt: {type: string, format: date-time, nullable: true, description: 与预约日历相同的权威到港当地时间，最新有效实际到港优先，其次柜资料实际到港及预计到港；未知保持空}
                         latest: {$ref: '#/components/schemas/Fact'}
                         previous: {$ref: '#/components/schemas/Fact'}
         '401': {description: 内部身份缺失、错误或服务端未配置}

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

@@ -118,9 +118,9 @@ paths:
       x-permission: platform:firstleg:customs:list
       parameters: [{$ref: '#/components/parameters/DocumentId'}]
       responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
-  /api/platform/v1/customs/loading-plans/documents/{documentId}/receipt/download:
+  /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/download:
     get:
-      summary: 平台下载报关行回执
+      summary: 平台下载预录单
       x-permission: platform:firstleg:customs:list
       parameters: [{$ref: '#/components/parameters/DocumentId'}]
       responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}

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

@@ -607,7 +607,7 @@ paths:
   /api/platform/v1/containers/{id}/ocean-booking-link:
     post:
       summary: 将内部模拟柜关联到已发布订舱需求
-      description: 需要 platform:firstleg:container:edit；请求指定 RELEASED oceanBookingId 和未满配 requirementId，containerNo 可空。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，原子写入订舱、运输和范围快照并创建 allocation；提柜后由拖车链调用柜次服务原子补录真实柜号。若关联请求已提供 containerNo，服务端仍规范化并校验 ISO 6346 结构、设备类别和校验位，并保证同一订舱内唯一；不同提单允许复用同一集装箱号。存在跨仓、跨渠道、柜型规格不一致、超量、同提单重复柜号、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
+      description: 需要 platform:firstleg:container:edit；请求指定 RELEASED oceanBookingId 和未满配 requirementId，containerNo 可空。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，原子写入订舱、运输和范围快照并创建 allocation；提柜后由拖车链调用柜次服务原子补录真实柜号。若关联请求已提供 containerNo，服务端仅移除空白并转大写，不校验 ISO 6346 长度、结构或校验位，并保证同一订舱内唯一；不同提单允许复用同一集装箱号。运输信息、提柜补录、确认预装、创建PDA任务、装柜完成及跨服务事件统一不校验ISO格式；确认预装及创建PDA任务前仍必须补齐真实柜号。存在跨仓、跨渠道、柜型规格不一致、超量、同提单重复柜号、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerOceanBookingLinkRequest'}}}}
       responses: {'200': {description: 关联后的同一模拟柜 containerBookingId/cabinetNo；列表仍只有这一条 ACTIVE 操作身份}}
@@ -2947,7 +2947,7 @@ components:
       properties:
         oceanBookingId: {type: integer, format: int64, minimum: 1, description: RELEASED订舱ID}
         requirementId: {type: integer, format: int64, minimum: 1, description: 未满配的订舱柜型需求ID}
-        containerNo: {type: string, nullable: true, maxLength: 64, description: 可选；港口提柜后可由拖车链另行原子补录。非空时服务端移除格式空白、转大写并校验ISO 6346结构、设备类别、校验位和同一订舱内唯一性}
+        containerNo: {type: string, nullable: true, maxLength: 64, description: 可选；港口提柜后可由拖车链另行原子补录。关联时移除格式空白并转大写，不校验ISO长度、结构或校验位，仍保证同一订舱内唯一；确认预装及创建PDA任务前必须补齐真实柜号，不校验ISO格式}
         expectedVersion: {type: integer, minimum: 0}
     ContainerFeeAdjustRequest:
       type: object

firstleg/src/main/resources/openapi/loading-lists-v1.yaml

@@ -50,7 +50,7 @@ paths:
       summary: 修改预装运输信息
       description: >-
         可在 EDITING 或 LOADING 阶段首次补录真实集装箱号；已有柜号的纠正仅限仍为 EDITING、PDA任务尚未领取且无任何物理作业事实时，并必须提供原因和当前版本；
-        containerNo 为 null 表示保持当前值，非空时服务端移除格式空白、转大写并校验ISO 6346结构、设备类别和校验位，空白字符串非法且禁止清空。
+        containerNo 为 null 时保留当前柜号；首次录入或纠正时服务端移除格式空白并转大写，不校验 ISO 6346 长度、结构、设备类别或校验位，空白字符串非法且禁止清空；同一订舱内柜号必须唯一。
       x-permission: platform:firstleg:preload:edit
       parameters:
         - {$ref: '#/components/parameters/PlanId'}

firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml

@@ -1,8 +1,8 @@
 openapi: 3.0.3
 info:
   title: Ocean Booking API
-  version: 2.1.0
-  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. Release requires at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Released bookings and their file links are permanently read-only.
+  version: 2.2.0
+  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. 放舱不要求上传订舱确认文件或提单文件。 Released transport and declared cargo snapshots and file links are read-only. Manual actual cargo may be supplemented with version, idempotency and audit reason.
 paths:
   /api/platform/v1/ocean-bookings:
     get:
@@ -29,10 +29,26 @@ paths:
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
       responses: {'200': {description: Deleted}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/estimated-arrival:
+    put:
+      summary: 放舱后维护预计到港
+      description: 仅允许RELEASED订舱按当前版本与幂等键维护estimatedArrivalAt，不得清空或早于预计开船时间；其他运输、预报、关系方、柜型与附件仍冻结，保存前后快照及操作人。不修改实际到港或计划到仓。
+      x-permission: platform:firstleg:ocean-booking:edit
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/EstimatedArrivalRequest'}}}}
+      responses: {'200': {description: 已保存的RELEASED订舱详情，包含当前版本和预计到港}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/actual-cargo:
+    put:
+      summary: Supplement manual actual cargo on a RELEASED booking
+      description: Only actual package count, gross weight and volume may change. Transport and declared cargo remain frozen. Requires expectedVersion, Idempotency-Key and a reason; saves before/after audit snapshots atomically. Null means not recorded, never zero or a fallback to declared cargo.
+      x-permission: platform:firstleg:ocean-booking:edit
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActualCargoRequest'}}}}
+      responses: {'200': {description: Updated RELEASED detail}, '409': {description: State or version conflict}}
   /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
     post:
       summary: Validate and permanently release a DRAFT
-      description: Release validates the persisted aggregate plus at least one active booking-owned BOOKING_CONFIRMATION or BILL_OF_LADING file. The customer is optional; a supplied customer must remain ACTIVE. Null denotes no single customer snapshot, never public access. It never requires or creates a real container number.
+      description: 放舱校验已保存的订舱业务资料，不以订舱确认文件或提单文件作为前置条件。 The customer is optional; a supplied customer must remain ACTIVE. Null denotes no single customer snapshot, never public access. It never requires or creates a real container number.
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
       responses: {'200': {description: RELEASED detail}}
@@ -89,7 +105,7 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/prints/shipping-instruction:
     get:
       summary: Render the current saved booking as an export shipping instruction PDF
-      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1 and synchronously proxies the generated PDF. Container requirements are not treated as actual cargo quantity, weight, volume, marks, packaging, or goods descriptions.
+      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1 and synchronously proxies the generated PDF. Cargo uses saved declared values; container requirements describe requested containers only. Count in words is generated from the declared count and packageUnit.
       x-permission: platform:firstleg:ocean-booking:list
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
       responses:
@@ -97,7 +113,7 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/prints/bill-of-lading-confirmation:
     get:
       summary: Render the current saved booking as a bill-of-lading confirmation PDF
-      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to BILL_OF_LADING_CONFIRMATION_A4_V1 and synchronously proxies the generated PDF. Container requirements remain a container summary and are not treated as actual cargo facts.
+      description: Firstleg maps the authoritative saved aggregate (DRAFT or RELEASED, with missing fields displayed as —) to BILL_OF_LADING_CONFIRMATION_A4_V1 and synchronously proxies the generated PDF. Cargo uses saved manually entered actual values only; missing actual data displays — and never falls back to declared values. This is a confirmation copy; the externally issued bill of lading remains an uploaded attachment.
       x-permission: platform:firstleg:ocean-booking:list
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
       responses:
@@ -192,12 +208,40 @@ components:
         destinationPortName: {type: string, nullable: true}
         placeOfDelivery: {type: string, nullable: true}
         estimatedSailingAt: {type: string, format: date-time, nullable: true}
-        estimatedArrivalAt: {type: string, format: date-time, nullable: true}
+        estimatedArrivalAt: {type: string, format: date-time, nullable: true, description: 草稿可留空，放舱前必填；不得早于预计开船时间，关联柜次后作为到港日历及默认到仓日期来源}
         remark: {type: string, nullable: true}
+        freightTerm: {type: string, maxLength: 64, nullable: true, description: 运费条款；新建页面默认FREIGHT PREPAID}
+        serviceTerm: {type: string, maxLength: 64, nullable: true, description: 运输条款；新建页面默认CY-CY}
+        packageUnit: {type: string, enum: [CARTONS, PCS, PALLETS], nullable: true}
+        cargoDescription: {type: string, maxLength: 1000, nullable: true}
+        marksAndNos: {type: string, maxLength: 1000, nullable: true}
+        declaredPackageCount: {type: integer, minimum: 1, maximum: 999999999, nullable: true}
+        declaredGrossWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        declaredVolumeCbm: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        actualPackageCount: {type: integer, minimum: 1, maximum: 999999999, nullable: true}
+        actualGrossWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        actualVolumeCbm: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
         parties: {type: array, nullable: true, items: {$ref: '#/components/schemas/PartyRequest'}}
         containerRequirements: {type: array, nullable: true, items: {$ref: '#/components/schemas/ContainerRequirementRequest'}}
-    PartyRequest: {type: object, required: [partyType, partyName], properties: {partyType: {type: string, enum: [SHIPPER, CONSIGNEE, NOTIFY_PARTY]}, partyName: {type: string}, address: {type: string, nullable: true}, contactName: {type: string, nullable: true}, contactPhone: {type: string, nullable: true}}}
+    PartyRequest: {type: object, required: [partyType, partyName], properties: {partyType: {type: string, enum: [SHIPPER, CONSIGNEE, NOTIFY_PARTY]}, partyName: {type: string}, address: {type: string, nullable: true}, contactName: {type: string, nullable: true}, contactPhone: {type: string, nullable: true}, contactEmail: {type: string, format: email, maxLength: 255, nullable: true}, taxNo: {type: string, maxLength: 128, nullable: true}}}
     ContainerRequirementRequest: {type: object, required: [containerType, containerKind, quantity, capacityCbm, maxWeightKg], properties: {containerType: {type: string, enum: [40GP, 40HQ, 45HQ], default: 40HQ}, containerKind: {type: string}, quantity: {type: integer, minimum: 1}, capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: 统一实装上限；40GP=58、40HQ=68、45HQ=86}, maxWeightKg: {type: number, enum: [19500], description: 统一货重上限}}}
+    EstimatedArrivalRequest:
+      type: object
+      additionalProperties: false
+      required: [expectedVersion, estimatedArrivalAt]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        estimatedArrivalAt: {type: string, format: date-time}
+    ActualCargoRequest:
+      type: object
+      additionalProperties: false
+      required: [expectedVersion, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, minLength: 1, maxLength: 1000}
+        actualPackageCount: {type: integer, minimum: 1, maximum: 999999999, nullable: true}
+        actualGrossWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
+        actualVolumeCbm: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 999999999999.999, multipleOf: 0.001, nullable: true}
     ReleaseRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
     ActionRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
     DocumentType: {type: string, enum: [BOOKING_CONFIRMATION, BILL_OF_LADING]}
@@ -311,6 +355,8 @@ components:
       required: [oceanBooking, parties, containerRequirements, containers, documents, histories]
       properties:
         oceanBooking:
+          allOf:
+            - {$ref: '#/components/schemas/DraftData'}
           type: object
           properties:
             bookingNo: {type: string, pattern: '^OB[0-9]{12}$', example: OB202608180001, description: 平台订舱号；按北京时间创建日逐日编号}

firstleg/src/main/resources/openapi/truck-appointments-v1.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Truck Appointment API
   version: 2.0.0
-  description: A truck appointment belongs to one RELEASED ocean booking, independently of when or how that booking's internal containers are linked. Each booking may have at most one non-terminal appointment. The bill-of-lading number and warehouse are frozen from the booking, which must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Container identities and real container numbers remain in the container/loading modules and are not part of this API. PDA loading completion alone does not complete the appointment. All required containers must be allocated and confirmed departed from the domestic warehouse. Completion atomically creates approved ON_ACCOUNT container payable fees allocated by loaded volume and publishes their immutable snapshots through the existing Finance Outbox. Create, edit, submit and reschedule also recheck departure facts, covering late appointments. Zero amounts create no fee. Cancelled and exception appointments are excluded. RMB is the only appointment currency and maps to CNY in Finance.
+  description: A truck appointment belongs to one RELEASED ocean booking, independently of when or how that booking's internal containers are linked. Each booking may have at most one non-terminal appointment. The bill-of-lading number and warehouse are frozen from the booking. 预约创建及派车不要求订舱附件。 Container identities and real container numbers remain in the container/loading modules and are not part of this API. PDA loading completion alone does not complete the appointment. All required containers must be allocated and confirmed departed from the domestic warehouse. Completion atomically creates approved ON_ACCOUNT container payable fees allocated by loaded volume and publishes their immutable snapshots through the existing Finance Outbox. Create, edit, submit and reschedule also recheck departure facts, covering late appointments. Zero amounts create no fee. Cancelled and exception appointments are excluded. RMB is the only appointment currency and maps to CNY in Finance.
 paths:
   /api/platform/v1/truck-appointments:
     get:
@@ -33,7 +33,7 @@ paths:
   /api/platform/v1/truck-appointments/candidates:
     get:
       summary: Query authoritative create-time ocean-booking candidates
-      description: Requires platform:firstleg:truck-appointment:list. Returns one row per RELEASED booking with a bill of lading and an active booking-owned confirmation or bill file, excluding bookings that already have an active or completed truck appointment. Container allocation and loading status do not affect eligibility. Edit pages display their current booking from appointment detail rather than injecting it into this create-only result.
+      description: Requires platform:firstleg:truck-appointment:list. Returns one row per RELEASED booking with a bill of lading number, excluding bookings that already have an active or completed truck appointment. Container allocation and loading status do not affect eligibility. Edit pages display their current booking from appointment detail rather than injecting it into this create-only result.
       parameters:
         - {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}, description: Matches booking number or bill of lading}
         - {name: page, in: query, required: false, schema: {type: integer, format: int64, minimum: 1, default: 1}}
@@ -168,7 +168,7 @@ components:
         timestamp: {type: string, format: date-time}
     Candidate:
       type: object
-      required: [oceanBookingId, oceanBookingNo, warehouseId, bookingDocumentReady]
+      required: [oceanBookingId, oceanBookingNo, warehouseId]
       properties:
         oceanBookingId: {type: integer, format: int64}
         oceanBookingNo: {type: string}
@@ -177,7 +177,7 @@ components:
         warehouseName: {type: string, nullable: true}
         channelCode: {type: string, nullable: true}
         channelName: {type: string, nullable: true}
-        bookingDocumentReady: {type: boolean, enum: [true]}
+
     DetailEnvelope:
       type: object
       required: [code, message, data, timestamp]
@@ -221,7 +221,7 @@ components:
       required: [oceanBookingId, carrierId, plannedLoadingAt, expectedVersion]
       properties:
         outboundOrderId: {type: integer, format: int64, minimum: 1, nullable: true}
-        oceanBookingId: {type: integer, format: int64, minimum: 1, description: Required RELEASED booking; must have a bill of lading and own an active BOOKING_CONFIRMATION or BILL_OF_LADING file.}
+        oceanBookingId: {type: integer, format: int64, minimum: 1, description: Required RELEASED booking; must have a bill of lading number. 订舱附件不作为前置条件。}
         warehouseId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional consistency hint. The persisted warehouse is frozen from the selected booking.}
         carrierId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE Warehouse supplier ID validated as TRUCKING with truckingScope DOMESTIC (国内拖车).}
         carrierName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot comes from Warehouse supplier master data.}

firstleg/src/test/java/com/baiyue/firstleg/controller/ContainerControllerContractTest.java

@@ -88,7 +88,7 @@ class ContainerControllerContractTest {
     }
 
     @Test
-    @DisplayName("OpenAPI声明平台级货柜路径和冻结规则")
+    @DisplayName("OpenAPI声明平台级货柜路径、关联柜号格式放行及冻结规则")
     void documentsContainerContract() throws Exception {
         String openapi = new ClassPathResource("openapi/firstleg-v1.yaml")
             .getContentAsString(StandardCharsets.UTF_8);
@@ -106,7 +106,8 @@ class ContainerControllerContractTest {
             .contains("未满配 requirementId")
             .contains("containerNo 可空")
             .contains("提柜后由拖车链调用柜次服务原子补录真实柜号")
-            .contains("校验 ISO 6346 结构、设备类别和校验位，并保证同一订舱内唯一")
+            .contains("不校验 ISO 6346 长度、结构或校验位，并保证同一订舱内唯一")
+            .contains("运输信息、提柜补录、确认预装、创建PDA任务、装柜完成及跨服务事件统一不校验ISO格式")
             .doesNotContain("/api/platform/v1/containers/{id}/transport:")
             .doesNotContain("ContainerOceanBookingUnlinkRequest")
             .doesNotContain("ContainerTransportUpdateRequest")

firstleg/src/test/java/com/baiyue/firstleg/controller/LoadingListControllerContractTest.java

@@ -73,7 +73,7 @@ class LoadingListControllerContractTest {
             .contains("containerNo")
             .contains("voyageNo")
             .contains("首次补录真实集装箱号")
-            .contains("校验ISO 6346结构、设备类别和校验位")
+            .contains("不校验 ISO 6346 长度、结构、设备类别或校验位")
             .contains("PDA任务尚未领取且无任何物理作业事实")
             .contains("/loading-plans/{planId}/confirm")
             .contains("/loading-plans/{planId}/lifecycle")

firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java

@@ -30,7 +30,7 @@ class TruckAppointmentControllerContractTest {
  }
  @Test void openApiDocumentsLifecycleIdempotencyAndActualTimes() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/{id}/{action}:","/api/platform/v1/truck-appointments/{id}/reschedule:","name: Idempotency-Key","required: true","actual event timestamps");}
  @Test void openApiDocumentsActionableDuplicateCreateConflict() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("A0409","existing appointment number","continue editing","database booking-level unique key");}
- @Test void openApiPublishesBookingLevelCandidateContract() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/candidates:","Paged booking candidates","bookingDocumentReady","Container allocation and loading status do not affect eligibility").doesNotContain("requirementId:","containerBookingId:","loadingPlanId:");}
+ @Test void openApiPublishesBookingLevelCandidateContract() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/candidates:","Paged booking candidates","Container allocation and loading status do not affect eligibility").doesNotContain("requirementId:","containerBookingId:","loadingPlanId:");}
  @Test void openApiRequiresReleasedBookingWithoutContainerWriteProtocol() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("required: [oceanBookingId, carrierId, plannedLoadingAt, expectedVersion]","RELEASED ocean booking","PICKUP does not accept or write a container number","schema: {$ref: '#/components/schemas/DetailEnvelope'}").doesNotContain("containerBookingId:","loadingPlanId:","containerNo:","customerId", "customerName");}
  @Test void openApiKeepsOnlyNonBookingTruckAttachments() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("AttachmentRequest:","required: [fileId, attachmentType]","required: [attachmentType, file]","TRUCK_APPOINTMENT_ATTACHMENT","Deletes the appointment reference only","DetailStableReferences:","oceanBookingNo:","shippingCompanyName:","bookingAgentName:","billOfLadingNo:").doesNotContain("enum: [BILL_OF_LADING, DISPATCH_ORDER");}
  @Test void openApiExposesOnlyPayableWithFixedCurrencies() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("payableAmount:","enum: [RMB]","default: RMB").doesNotContain("receivableAmount");}

firstleg/src/test/java/com/baiyue/firstleg/customs/container/ContainerCustomsControllerContractTest.java

@@ -4,6 +4,7 @@ import com.baiyue.firstleg.customs.container.controller.*;
 import org.junit.jupiter.api.Test;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.core.io.ClassPathResource;
 import org.yaml.snakeyaml.Yaml;
 
@@ -12,6 +13,22 @@ import java.lang.reflect.Method;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class ContainerCustomsControllerContractTest {
+    /** 下载契约必须跟随实际 Controller，避免前端和文档共同固化不存在的地址。 */
+    @Test void platformPreEntryDownloadMatchesActualControllerAndOpenApi() throws Exception {
+        Method download = java.util.Arrays.stream(PlatformContainerCustomsController.class.getDeclaredMethods())
+            .filter(method -> method.getName().equals("downloadCompletion")).findFirst().orElseThrow();
+        String root = PlatformContainerCustomsController.class.getAnnotation(RequestMapping.class).value()[0];
+        String path = root + download.getAnnotation(GetMapping.class).value()[0];
+        String source = new ClassPathResource("openapi/customs-v1.yaml").getContentAsString(java.nio.charset.StandardCharsets.UTF_8);
+        java.util.Map<?, ?> specification = new Yaml().load(source);
+        java.util.Map<?, ?> paths = (java.util.Map<?, ?>) specification.get("paths");
+
+        assertThat(path).isEqualTo("/api/platform/v1/customs/loading-plans/documents/{documentId}/completion/download");
+        assertThat(paths.containsKey(path)).isTrue();
+        assertThat(paths.containsKey(root + "/documents/{documentId}/receipt/download")).isFalse();
+        assertThat(download.getAnnotation(PreAuthorize.class).value()).contains("platform:firstleg:customs:list");
+    }
+
     @Test void platformUsesListForReadsAndManageForWrites() {
         assertThat(PlatformContainerCustomsController.class.getAnnotation(RequestMapping.class).value())
             .containsExactly("/api/platform/v1/customs/loading-plans");

firstleg/src/test/java/com/baiyue/firstleg/customs/container/ContainerCustomsServiceTest.java

@@ -442,6 +442,7 @@ class ContainerCustomsServiceTest {
         verifyNoInteractions(files);
     }
 
+    /** 上传被拒绝时使用预录单名称，并保留报关行执行后的替换门禁。 */
     @Test void receiptCannotBeReplacedAfterBrokerSubmission(){
         var source=document(1L);when(mapper.document(1L)).thenReturn(source);
         when(mapper.claimCommand(anyLong(),eq(5L),eq("UPLOAD_COMPLETION_1"),eq("broker-sent-key"),anyString())).thenReturn(1);
@@ -450,7 +451,10 @@ class ContainerCustomsServiceTest {
         when(mapper.brokerSubmittedAt(2L)).thenReturn(java.time.LocalDateTime.now());
         var file=new MockMultipartFile("file","result.bin","application/octet-stream",new byte[]{1});
         assertThatThrownBy(()->service.uploadCompletion(1L,5L,"admin","broker-sent-key",0,file))
-            .isInstanceOf(BizException.class).hasMessageContaining("不可再修改回执");
+            .isInstanceOfSatisfying(BizException.class, error -> {
+                assertThat(error.getResultCode()).isEqualTo(ResultCode.CONFLICT);
+                assertThat(error).hasMessage("客户确认的预录单已发送给报关行，不可再修改预录单");
+            });
         verifyNoInteractions(files);
     }
 
@@ -512,11 +516,43 @@ class ContainerCustomsServiceTest {
         verify(mapper,never()).complete(anyLong(),anyInt(),anyLong(),anyString());
     }
 
+    /** 下载不可见或缺失的预录单时使用正式名称，不改变客户范围校验。 */
     @Test void merchantCannotDownloadCompletionBeforeWholeContainerCompletes(){
         var source=document(1L);when(mapper.document(1L)).thenReturn(source);
         when(mapper.containerById(2L)).thenReturn(container(ContainerCustomsService.DECLARING,3));
         assertThatThrownBy(()->service.downloadCompletion(7L,1L,false)).isInstanceOf(BizException.class)
-            .hasMessageContaining("报关行回执不存在");
+            .hasMessageContaining("预录单不存在");
+        verifyNoInteractions(files);
+    }
+
+    /** 平台下载的当前预录单不存在时仍返回原业务错误码和正式名称。 */
+    @Test void platformMissingPreEntryDocumentUsesCurrentName() {
+        when(mapper.document(1L)).thenReturn(document(1L));
+        when(mapper.completion(1L)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.downloadCompletion(0L, 1L, true))
+            .isInstanceOfSatisfying(BizException.class, error -> {
+                assertThat(error.getResultCode()).isEqualTo(ResultCode.NOT_FOUND);
+                assertThat(error).hasMessage("预录单不存在");
+            });
+        verifyNoInteractions(files);
+    }
+
+    /** 发送前置校验仅调整用户可见名称，不改变全买单或客户确认门禁。 */
+    @ParameterizedTest
+    @CsvSource({"0,0,全买单柜无需发送预录单确认结果给报关行", "1,1,仍有预录单未完成客户确认"})
+    void brokerSubmissionErrorsUsePreEntryDocumentName(int taxRefundCount, int unconfirmedCount, String message) {
+        when(mapper.claimCommand(anyLong(), eq(5L), eq("SUBMIT_CUSTOMS_TO_BROKER_9"), eq("pre-entry-name"), anyString())).thenReturn(1);
+        when(mapper.lockContainer(9L)).thenReturn(container(ContainerCustomsService.DECLARING, 3));
+        when(mapper.taxRefundCount(9L)).thenReturn(taxRefundCount);
+        when(mapper.unconfirmedReceiptCount(2L)).thenReturn(unconfirmedCount);
+
+        assertThatThrownBy(() -> service.submitToBroker(9L, 5L, "admin", "pre-entry-name", new ActionRequest(3, true, null)))
+            .isInstanceOfSatisfying(BizException.class, error -> {
+                assertThat(error.getResultCode()).isEqualTo(ResultCode.CONFLICT);
+                assertThat(error).hasMessage(message);
+            });
+        verify(mapper, never()).submitToBroker(anyLong(), anyInt(), anyLong(), anyString());
         verifyNoInteractions(files);
     }
 

firstleg/src/test/java/com/baiyue/firstleg/domain/Iso6346ContainerNumberTest.java

@@ -1,23 +0,0 @@
-package com.baiyue.firstleg.domain;
-
-import com.baiyue.common.core.exception.BizException;
-import org.junit.jupiter.api.Test;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
-class Iso6346ContainerNumberTest {
-    @Test
-    void normalizesAllowedWhitespaceAndLowercase() {
-        assertThat(Iso6346ContainerNumber.require(" ms cu 663987 0 "))
-            .isEqualTo("MSCU6639870");
-    }
-
-    @Test
-    void rejectsWrongEquipmentCategoryAndCheckDigit() {
-        assertThatThrownBy(() -> Iso6346ContainerNumber.require("MSCA6639870"))
-            .isInstanceOf(BizException.class).hasMessageContaining("设备类别");
-        assertThatThrownBy(() -> Iso6346ContainerNumber.require("MSCU6639871"))
-            .isInstanceOf(BizException.class).hasMessageContaining("校验位");
-    }
-}

firstleg/src/test/java/com/baiyue/firstleg/domain/RealContainerNumberTest.java

@@ -0,0 +1,28 @@
+package com.baiyue.firstleg.domain;
+
+import com.baiyue.common.core.exception.BizException;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class RealContainerNumberTest {
+    /** 录入只去空白转大写，ISO 长度、设备类别与校验位不构成门禁。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCA6639870", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void normalizesWithoutIsoValidation(String containerNo) {
+        assertThat(RealContainerNumber.require(" \u00a0" + containerNo.toLowerCase(java.util.Locale.ROOT) + " "))
+            .isEqualTo(containerNo);
+    }
+
+    /** 空柜号不能进入实际作业，包含规范化后为空的 Unicode 空白。 */
+    @ParameterizedTest
+    @NullAndEmptySource
+    @ValueSource(strings = {"   ", "\u00a0\u3000"})
+    void rejectsMissingNumber(String containerNo) {
+        assertThatThrownBy(() -> RealContainerNumber.require(containerNo))
+            .isInstanceOf(BizException.class).hasMessageContaining("不能为空");
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/controller/PlatformOceanBookingControllerContractTest.java

@@ -14,6 +14,37 @@ import java.nio.file.Path;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class PlatformOceanBookingControllerContractTest {
+    /** 预计到港命令仅接收版本与时间，沿用编辑权限及独立审计。 */
+    @Test void estimatedArrivalCommandHasNarrowDtoAndEditPermission() throws Exception {
+        var endpoint = method("updateEstimatedArrival");
+        assertThat(endpoint.getAnnotation(org.springframework.web.bind.annotation.PutMapping.class).value()).containsExactly("/{oceanBookingId}/estimated-arrival");
+        assertThat(endpoint.getAnnotation(PreAuthorize.class).value()).isEqualTo("hasAuthority('platform:firstleg:ocean-booking:edit')");
+        assertThat(endpoint.getAnnotation(BusinessAudit.class)).isNotNull();
+        assertThat(Arrays.stream(com.baiyue.firstleg.oceanbooking.dto.OceanBookingDtos.EstimatedArrivalRequest.class.getRecordComponents())
+            .map(java.lang.reflect.RecordComponent::getName)).containsExactly("expectedVersion", "estimatedArrivalAt");
+        assertThat(Files.readString(Path.of("src/main/resources/openapi/ocean-bookings-v1.yaml")))
+            .contains("/api/platform/v1/ocean-bookings/{oceanBookingId}/estimated-arrival:", "#/components/schemas/EstimatedArrivalRequest");
+    }
+
+    /** 真实方法权限拦截器拒绝只有读取权限的账号，命令不会进入服务层。 */
+    @Test void estimatedArrivalRejectsReadOnlyAccountBeforeServiceCall() {
+        var service = org.mockito.Mockito.mock(com.baiyue.firstleg.oceanbooking.service.OceanBookingService.class);
+        var target = new PlatformOceanBookingController();
+        org.springframework.test.util.ReflectionTestUtils.setField(target, "service", service);
+        var factory = new org.springframework.aop.framework.ProxyFactory(target);
+        factory.setProxyTargetClass(true);
+        factory.addAdvisor(org.springframework.security.authorization.method.AuthorizationManagerBeforeMethodInterceptor.preAuthorize());
+        var secured = (PlatformOceanBookingController) factory.getProxy();
+        var context = org.springframework.security.core.context.SecurityContextHolder.getContext();
+        context.setAuthentication(new org.springframework.security.authentication.UsernamePasswordAuthenticationToken("reader", "",
+            java.util.List.of(new org.springframework.security.core.authority.SimpleGrantedAuthority("platform:firstleg:ocean-booking:list"))));
+        try {
+            org.assertj.core.api.Assertions.assertThatThrownBy(() -> secured.updateEstimatedArrival(null, 1L, "eta-denied",
+                new com.baiyue.firstleg.oceanbooking.dto.OceanBookingDtos.EstimatedArrivalRequest(3, java.time.LocalDateTime.now())))
+                .isInstanceOf(org.springframework.security.access.AccessDeniedException.class);
+            org.mockito.Mockito.verifyNoInteractions(service);
+        } finally { org.springframework.security.core.context.SecurityContextHolder.clearContext(); }
+    }
     @Test
     void usesDedicatedResourceAndPermissions() {
         assertThat(PlatformOceanBookingController.class.getAnnotation(RequestMapping.class).value())
@@ -32,6 +63,7 @@ class PlatformOceanBookingControllerContractTest {
             Map.entry("uploadDocument", "platform:firstleg:ocean-booking:edit"),
             Map.entry("invalidateDocument", "platform:firstleg:ocean-booking:edit"),
             Map.entry("create", "platform:firstleg:ocean-booking:create"),
+            Map.entry("updateActualCargo", "platform:firstleg:ocean-booking:edit"),
             Map.entry("updateDraft", "platform:firstleg:ocean-booking:edit"),
             Map.entry("deleteDraft", "platform:firstleg:ocean-booking:delete"),
             Map.entry("release", "platform:firstleg:ocean-booking:release"));
@@ -47,6 +79,24 @@ class PlatformOceanBookingControllerContractTest {
         });
     }
 
+    @Test
+    @SuppressWarnings("unchecked")
+    void actualCargoContractExposesOnlySupplementFieldsAndReusesEditPermission() throws Exception {
+        assertThat(method("updateActualCargo").getAnnotation(org.springframework.web.bind.annotation.PutMapping.class).value())
+            .containsExactly("/{oceanBookingId}/actual-cargo");
+        Map<String, Object> document = new org.yaml.snakeyaml.Yaml().load(
+            Files.readString(Path.of("src/main/resources/openapi/ocean-bookings-v1.yaml")));
+        var paths = (Map<String, Object>) document.get("paths");
+        var endpoint = (Map<String, Object>) paths.get("/api/platform/v1/ocean-bookings/{oceanBookingId}/actual-cargo");
+        var operation = (Map<String, Object>) endpoint.get("put");
+        assertThat(operation).containsEntry("x-permission", "platform:firstleg:ocean-booking:edit");
+        var schemas = (Map<String, Object>) ((Map<String, Object>) document.get("components")).get("schemas");
+        var request = (Map<String, Object>) schemas.get("ActualCargoRequest");
+        assertThat((Map<String, Object>) request.get("properties")).containsOnlyKeys(
+            "expectedVersion", "reason", "actualPackageCount", "actualGrossWeightKg", "actualVolumeCbm");
+        assertThat((java.util.List<String>) request.get("required")).contains("expectedVersion", "reason");
+    }
+
     @Test
     void pathVariablesUseExplicitAggregateNames() {
         assertThat(Arrays.stream(PlatformOceanBookingController.class.getDeclaredMethods())

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/repository/OceanBookingMapperContractTest.java

@@ -14,6 +14,13 @@ import java.util.Arrays;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class OceanBookingMapperContractTest {
+    /** 放舱后预计到港只更新该字段及版本审计，不允许带出其他冻结资料。 */
+    @Test void estimatedArrivalUpdateIsNarrowAndVersioned() throws Exception {
+        String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("updateEstimatedArrival", long.class,
+            java.time.LocalDateTime.class, int.class, long.class, String.class).getAnnotation(Update.class).value());
+        assertThat(sql).contains("estimated_arrival_at=#{estimatedArrivalAt}", "status='RELEASED'", "version=#{version}", "version=version+1")
+            .doesNotContain("vessel_name=", "voyage_no=", "estimated_sailing_at=", "actual_", "declared_", "warehouse_id=");
+    }
     @Test
     void listUsesPlatformAggregateFilters() throws Exception {
         String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("selectPage",
@@ -46,6 +53,16 @@ class OceanBookingMapperContractTest {
             .doesNotContain("CONFIRMED", "CHANGE_PENDING", "CANCELLED", "SUBMITTED", "FAILED");
     }
 
+    @Test
+    void releasedSupplementSqlCannotWriteTransportOrDeclaredCargo() throws Exception {
+        String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("updateActualCargo",
+            com.baiyue.firstleg.oceanbooking.entity.OceanBookingEntity.class, int.class, long.class, String.class)
+            .getAnnotation(Update.class).value());
+        assertThat(sql).contains("status='RELEASED' AND version=#{version}", "version=version+1",
+            "actual_package_count=#{value.actualPackageCount}", "actual_gross_weight_kg=#{value.actualGrossWeightKg}", "actual_volume_cbm=#{value.actualVolumeCbm}")
+            .doesNotContain("bill_of_lading_no=", "vessel_name=", "declared_", "warehouse_id=", "package_unit=");
+    }
+
     @Test
     void linkCandidatesUsesOneBoundedSetQueryAndExactRemainingSemantics() throws Exception {
         String sql = String.join("\n", OceanBookingMapper.class.getDeclaredMethod("selectLinkCandidates",

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/repository/OceanBookingSqlContractTest.java

@@ -10,6 +10,14 @@ import java.nio.file.Path;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class OceanBookingSqlContractTest {
+    /** 两份触发器基线只放开预计到港，继续冻结船名、开船、预报和其他运输资料。 */
+    @Test void releasedFreezeAllowsEstimatedArrivalOnly() throws Exception {
+        for (String source : new String[] {sql(), Files.readString(Path.of("../deploy/sql/头程数据库统一增量-MySQL8.sql"))}) {
+            assertThat(source).doesNotContain("NEW.estimated_arrival_at <=> OLD.estimated_arrival_at")
+                .contains("NEW.vessel_name <=> OLD.vessel_name", "NEW.estimated_sailing_at <=> OLD.estimated_sailing_at",
+                    "NEW.declared_package_count <=> OLD.declared_package_count", "NEW.version = OLD.version + 1");
+        }
+    }
     @Test
     void definesDedicatedAggregateWithoutChangingContainerSemantics() throws Exception {
         String sql = sql();
@@ -27,8 +35,8 @@ class OceanBookingSqlContractTest {
             .contains("MODIFY COLUMN customer_name VARCHAR(128) NULL COMMENT '可选客户名称快照'")
             .contains("UNIQUE KEY uk_ocean_booking_bill_of_lading (bill_of_lading_no)")
             .contains("ADD UNIQUE KEY uk_ocean_booking_bill_of_lading (bill_of_lading_no)")
-            .doesNotContain("service_term")
-            .doesNotContain("freight_term")
+            .contains("service_term", "declared_package_count", "actual_package_count")
+            .contains("freight_term", "contact_email", "tax_no")
             .contains("carrier_code VARCHAR(16) NULL COMMENT '船司标准编码")
             .contains("carrier_code IS NULL OR carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE','OTHER')")
             .contains("container_booking_id BIGINT UNSIGNED NOT NULL COMMENT '明确引用现有柜次ID'")
@@ -49,7 +57,7 @@ class OceanBookingSqlContractTest {
     void enforcesStateIdempotencyAndAuditContracts() throws Exception {
         assertThat(sql())
             .contains("OLD.status='DRAFT' AND NEW.status='RELEASED'")
-            .contains("OLD.status = 'RELEASED'")
+            .contains("OLD.status = 'RELEASED'", "NEW.declared_package_count <=> OLD.declared_package_count", "NEW.bill_of_lading_no <=> OLD.bill_of_lading_no", "NEW.version = OLD.version + 1")
             .contains("UNIQUE KEY uk_ocean_operation (operator_id,operation,idempotency_key)")
             .contains("request_hash CHAR(64) NOT NULL")
             .contains("<> 'RELEASED' THEN")

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingPrintServiceTest.java

@@ -49,7 +49,7 @@ class OceanBookingPrintServiceTest {
         assertThat(document.fields()).containsEntry("jobNumber", "OB-1")
             .containsEntry("shipper", "Shipper\nAddress")
             .containsEntry("oceanVesselVoyage", "Vessel / V001")
-            .containsEntry("cargoQuantity", "—")
+            .containsEntry("cargoQuantity", "2*40HQ")
             .containsEntry("totalPackagesInWords", "—")
             .containsKeys("toCompany", "consignee", "notifyParty", "cargoQuantity",
                 "portOfLoading", "portOfDischarge", "placeOfDelivery", "totalPackagesInWords");
@@ -95,6 +95,39 @@ class OceanBookingPrintServiceTest {
             .containsEntry("totalPackagesInWords", "—");
     }
 
+    @Test void routesDeclaredAndActualCargoSeparatelyAndGeneratesWords() {
+        Detail detail = detail("RELEASED");
+        var booking = detail.oceanBooking();
+        booking.setPackageUnit("CARTONS"); booking.setDeclaredPackageCount(500); booking.setActualPackageCount(480);
+        booking.setDeclaredGrossWeightKg(new BigDecimal("15000")); booking.setDeclaredVolumeCbm(new BigDecimal("68"));
+        booking.setActualGrossWeightKg(new BigDecimal("14320.125")); booking.setActualVolumeCbm(new BigDecimal("65.321"));
+        booking.setCargoDescription("HOUSEHOLD GOODS"); booking.setMarksAndNos("N/M");
+        booking.setServiceTerm("CY-CY"); booking.setFreightTerm("FREIGHT PREPAID");
+        detail.parties().get(0).setContactEmail("ops@example.test"); detail.parties().get(0).setTaxNo("TEST-TAX");
+        when(bookings.detail(10L)).thenReturn(detail);
+        when(print.generateFreightA4Documents(any(), any(), any()))
+            .thenReturn(ResponseEntity.ok().contentType(MediaType.APPLICATION_PDF).body(new byte[]{1}));
+        service.shippingInstruction(10L, "split"); service.billConfirmation(10L, "split");
+        var capture = ArgumentCaptor.forClass(PrintPdfClient.FreightA4PdfRequest.class);
+        verify(print, times(2)).generateFreightA4Documents(any(), any(), capture.capture());
+        var declared = capture.getAllValues().get(0).documents().get(0);
+        var actual = capture.getAllValues().get(1).documents().get(0);
+        assertThat(declared.cargoRows().get(0).quantity()).isEqualTo("500");
+        assertThat(declared.cargoRows().get(0).grossWeight()).isEqualTo("15000.000 KGS");
+        assertThat(declared.fields()).containsEntry("totalPackagesInWords", "SAY FIVE HUNDRED CARTONS ONLY")
+            .containsEntry("serviceTerm", "CY-CY").containsEntry("freightTerm", "FREIGHT PREPAID");
+        assertThat(declared.fields().get("shipper")).contains("ops@example.test", "TAX NO: TEST-TAX");
+        assertThat(actual.cargoRows().get(0).quantity()).isEqualTo("480");
+        assertThat(actual.cargoRows().get(0).grossWeight()).isEqualTo("14320.125 KGS");
+        assertThat(actual.cargoRows().get(0).measurement()).isEqualTo("65.321 CBM");
+        assertThat(actual.fields()).containsEntry("totalPackagesInWords", "SAY FOUR HUNDRED EIGHTY CARTONS ONLY");
+        booking.setActualPackageCount(null); booking.setActualGrossWeightKg(null); booking.setActualVolumeCbm(null);
+        service.billConfirmation(10L, "missing");
+        verify(print).generateFreightA4Documents(any(), eq("missing"), capture.capture());
+        assertThat(capture.getValue().documents().get(0).cargoRows().get(0).quantity()).isEqualTo("—");
+        assertThat(capture.getValue().documents().get(0).fields()).containsEntry("totalPackagesInWords", "—");
+    }
+
     private static Detail detail(String status) {
         OceanBookingEntity booking = new OceanBookingEntity();
         booking.setId(10L); booking.setBookingNo("OB-1"); booking.setStatus(status);

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingServiceTest.java

@@ -118,7 +118,7 @@ class OceanBookingServiceTest {
         assertThat(result.oceanBooking().getStatus()).isEqualTo("RELEASED");
         assertThat(result.oceanBooking().getCustomerId()).isNull();
         assertThat(result.oceanBooking().getCustomerName()).isNull();
-        verify(documents).requireActiveValidDocument(stored.get());
+        verifyNoInteractions(documents);
         verify(customers, times(initialCustomer ? 1 : 0)).active(anyLong(), any());
     }
 
@@ -188,21 +188,22 @@ class OceanBookingServiceTest {
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
     }
 
+    /** 无订舱附件时仍可按完整业务资料放舱。 */
     @Test
-    void rejectsReleaseWithoutActiveBookingOwnedFileWithoutStateDrift() {
+    void releasesWithoutBookingFiles() {
         stubMasterData();
         OceanBookingEntity draft = completeBooking("DRAFT", 3);
-        when(repository.find(1L)).thenReturn(draft);
+        when(repository.find(1L)).thenReturn(draft, completeBooking("RELEASED", 4));
         when(repository.parties(1L)).thenReturn(parties());
         when(repository.requirements(1L)).thenReturn(List.of(requirement()));
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
-            "订舱缺少有效订舱确认或提单文件"))
-            .when(documents).requireActiveValidDocument(draft);
+        when(repository.documents(1L)).thenReturn(List.of());
+        when(repository.transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin")).thenReturn(1);
 
-        assertThatThrownBy(() -> service.release(1L, 9L, "admin", "release-no-file",
-            new ReleaseRequest(3, "确认")))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
-        verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
+        Detail result = service.release(1L, 9L, "admin", "release-no-file", new ReleaseRequest(3, "确认"));
+        assertThat(result.oceanBooking().getStatus()).isEqualTo("RELEASED");
+        assertThat(result.documents()).isEmpty();
+        verifyNoInteractions(documents);
+        verify(repository).transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin");
     }
 
     @Test
@@ -231,6 +232,19 @@ class OceanBookingServiceTest {
         verify(repository, times(1)).transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin");
     }
 
+    /** 缺预计到港不能放舱，避免关联柜次后丢失日历及默认到仓日期来源。 */
+    @Test
+    void rejectsReleaseWithoutEstimatedArrival() {
+        OceanBookingEntity draft = completeBooking("DRAFT", 3);
+        draft.setEstimatedArrivalAt(null);
+        when(repository.find(1L)).thenReturn(draft);
+        when(repository.parties(1L)).thenReturn(parties());
+        when(repository.requirements(1L)).thenReturn(List.of(requirement()));
+        assertThatThrownBy(() -> service.release(1L, 9L, "admin", "release-no-arrival", new ReleaseRequest(3, "确认放舱")))
+            .isInstanceOf(BizException.class).hasMessageContaining("尚未填写完整");
+        verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
+    }
+
     @Test
     void rejectsCarrierSnapshotMismatchAndUnassociatedBookingAgent() {
         stubMasterData();
@@ -386,6 +400,142 @@ class OceanBookingServiceTest {
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
     }
 
+    /** 预计到港独立更新、回显并保留修改前后审计，不能触及其他冻结字段。 */
+    @Test void maintainsReleasedEstimatedArrivalWithVersionAndAudit() {
+        var before = completeBooking("RELEASED", 3);
+        var after = objectMapper.convertValue(before, OceanBookingEntity.class);
+        var arrival = before.getEstimatedSailingAt().plusDays(20);
+        after.setEstimatedArrivalAt(arrival); after.setVersion(4);
+        when(repository.find(1L)).thenReturn(before, after);
+        when(repository.updateEstimatedArrival(1L, arrival, 3, 9L, "admin")).thenReturn(1);
+
+        var result = service.updateEstimatedArrival(1L, 9L, "admin", "eta-save", new EstimatedArrivalRequest(3, arrival));
+
+        assertThat(result.oceanBooking().getEstimatedArrivalAt()).isEqualTo(arrival);
+        assertThat(result.oceanBooking().getVersion()).isEqualTo(4);
+        assertThat(result.oceanBooking().getVesselName()).isEqualTo(before.getVesselName());
+        var history = ArgumentCaptor.forClass(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class);
+        verify(repository).insert(history.capture());
+        assertThat(history.getValue().getAction()).isEqualTo("UPDATE_ESTIMATED_ARRIVAL");
+        assertThat(history.getValue().getBeforeSnapshot()).contains("estimatedArrivalAt");
+        assertThat(history.getValue().getAfterSnapshot()).contains("estimatedArrivalAt");
+        verify(repository, never()).updateDraft(any(), anyInt(), anyLong(), any());
+        verify(repository, never()).replaceRequirements(anyLong(), any());
+    }
+
+    /** 草稿、旧版本、空值及逆序时间均不能走放舱后的预计到港命令。 */
+    @Test void rejectsInvalidEstimatedArrivalCommands() {
+        var value = completeBooking("DRAFT", 3);
+        when(repository.find(1L)).thenReturn(value);
+        var arrival = value.getEstimatedSailingAt().plusDays(20);
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-draft", new EstimatedArrivalRequest(3, arrival))).isInstanceOf(BizException.class);
+        value.setStatus("RELEASED");
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-stale", new EstimatedArrivalRequest(2, arrival))).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-empty", new EstimatedArrivalRequest(3, null))).hasMessageContaining("不能为空");
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-early", new EstimatedArrivalRequest(3, value.getEstimatedSailingAt().minusSeconds(1)))).hasMessageContaining("不能早于");
+        when(repository.updateEstimatedArrival(anyLong(), any(), anyInt(), anyLong(), any())).thenReturn(0);
+        assertThatThrownBy(() -> service.updateEstimatedArrival(1L, 9L, "admin", "eta-conflict", new EstimatedArrivalRequest(3, arrival))).isInstanceOf(BizException.class);
+    }
+
+    /** 同一预计到港命令重放复用原结果，不重复保存或追加审计。 */
+    @Test void estimatedArrivalReplayDoesNotWriteAgain() throws Exception {
+        var request = new EstimatedArrivalRequest(3, LocalDateTime.of(2026, 10, 25, 10, 0));
+        var replay = new Detail(completeBooking("RELEASED", 4), List.of(), List.of(), List.of(), List.of(), List.of());
+        var operation = new OceanBookingOperationEntity();
+        operation.setRequestHash(hash("UPDATE_ESTIMATED_ARRIVAL", 1L, request));
+        operation.setStatus("SUCCESS"); operation.setResultJson(objectMapper.writeValueAsString(replay));
+        when(repository.claimOperation(1L, 9L, "UPDATE_ESTIMATED_ARRIVAL", "eta-replay", operation.getRequestHash())).thenReturn(false);
+        when(repository.operation(9L, "UPDATE_ESTIMATED_ARRIVAL", "eta-replay")).thenReturn(operation);
+        assertThat(service.updateEstimatedArrival(1L, 9L, "admin", "eta-replay", request).oceanBooking().getVersion()).isEqualTo(4);
+        verify(repository, never()).updateEstimatedArrival(anyLong(), any(), anyInt(), anyLong(), any());
+        verify(repository, never()).insert(any(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class));
+    }
+
+    @Test
+    void supplementsReleasedActualCargoWithVersionAndBeforeAfterAudit() {
+        OceanBookingEntity before = completeBooking("RELEASED", 3);
+        before.setDeclaredPackageCount(500);
+        before.setActualPackageCount(450);
+        AtomicReference<OceanBookingEntity> stored = new AtomicReference<>(before);
+        when(repository.find(1L)).thenAnswer(invocation -> stored.get());
+        when(repository.updateActualCargo(any(), eq(3), eq(9L), eq("admin"))).thenAnswer(invocation -> {
+            OceanBookingEntity after = invocation.getArgument(0);
+            after.setVersion(4); stored.set(after); return 1;
+        });
+        var request = new ActualCargoRequest(3, 480, new BigDecimal("14000.125"), new BigDecimal("65.321"), "修正实装货量");
+        var result = service.updateActualCargo(1L, 9L, "admin", "actual-save", request);
+        assertThat(result.oceanBooking().getActualPackageCount()).isEqualTo(480);
+        assertThat(result.oceanBooking().getDeclaredPackageCount()).isEqualTo(500);
+        assertThat(result.oceanBooking().getBillOfLadingNo()).isEqualTo("BL-001");
+        assertThat(before.getActualPackageCount()).isEqualTo(450);
+        var history = ArgumentCaptor.forClass(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class);
+        verify(repository).insert(history.capture());
+        assertThat(history.getValue().getAction()).isEqualTo("UPDATE_ACTUAL_CARGO");
+        assertThat(history.getValue().getBeforeSnapshot()).contains("\"actualPackageCount\":450");
+        assertThat(history.getValue().getAfterSnapshot()).contains("\"actualPackageCount\":480");
+        assertThat(history.getValue().getReason()).isEqualTo("修正实装货量");
+        verify(repository, never()).updateDraft(any(), anyInt(), anyLong(), any());
+        verify(repository, never()).replaceRequirements(anyLong(), any());
+        verifyNoInteractions(documents, priceBooks, suppliers, warehouses);
+    }
+
+    @Test
+    void rejectsActualCargoOnDraftOrStaleVersionAndRequiresReason() {
+        OceanBookingEntity value = completeBooking("DRAFT", 3);
+        when(repository.find(1L)).thenReturn(value);
+        var request = new ActualCargoRequest(3, 100, null, null, "补录");
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-draft", request)).isInstanceOf(BizException.class);
+        value.setStatus("RELEASED");
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-stale",
+            new ActualCargoRequest(2, 100, null, null, "补录"))).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-no-reason",
+            new ActualCargoRequest(3, 100, null, null, " "))).isInstanceOf(BizException.class).hasMessageContaining("原因");
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-negative",
+            new ActualCargoRequest(3, 100, new BigDecimal("-1"), null, "补录"))).isInstanceOf(BizException.class);
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-precision",
+            new ActualCargoRequest(3, 100, null, new BigDecimal("1.0001"), "补录"))).isInstanceOf(BizException.class);
+        when(repository.updateActualCargo(any(), anyInt(), anyLong(), any())).thenReturn(0);
+        assertThatThrownBy(() -> service.updateActualCargo(1L, 9L, "admin", "actual-concurrent", request)).isInstanceOf(BizException.class);
+        verify(repository, never()).insert(any(com.baiyue.firstleg.oceanbooking.entity.OceanBookingStatusHistoryEntity.class));
+    }
+
+    @Test
+    void replayedActualCargoDoesNotWriteAgain() throws Exception {
+        var request = new ActualCargoRequest(3, 100, null, null, "补录");
+        var replay = new Detail(completeBooking("RELEASED", 4), List.of(), List.of(), List.of(), List.of(), List.of());
+        var operation = new OceanBookingOperationEntity();
+        operation.setRequestHash(hash("UPDATE_ACTUAL_CARGO", 1L, request));
+        operation.setStatus("SUCCESS"); operation.setResultJson(objectMapper.writeValueAsString(replay));
+        when(repository.claimOperation(1L, 9L, "UPDATE_ACTUAL_CARGO", "actual-replay", operation.getRequestHash())).thenReturn(false);
+        when(repository.operation(9L, "UPDATE_ACTUAL_CARGO", "actual-replay")).thenReturn(operation);
+        assertThat(service.updateActualCargo(1L, 9L, "admin", "actual-replay", request).oceanBooking().getVersion()).isEqualTo(4);
+        verify(repository, never()).updateActualCargo(any(), anyInt(), anyLong(), any());
+    }
+
+    @Test
+    void savesUnnamedPartyContactDraftButRequiresNamesBeforeRelease() throws Exception {
+        var tree = (com.fasterxml.jackson.databind.node.ObjectNode) objectMapper.valueToTree(partialDraft(null));
+        tree.putArray("parties").addObject().put("partyType", "SHIPPER").put("partyName", "")
+            .put("contactEmail", "ops@example.test").put("taxNo", "TEST-TAX");
+        stubCreatedDraft();
+        service.create(9L, "admin", "partial-party", new CreateRequest(0, objectMapper.treeToValue(tree, DraftData.class)));
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<List<com.baiyue.firstleg.oceanbooking.entity.OceanBookingPartyEntity>> capture = ArgumentCaptor.forClass(List.class);
+        verify(repository).replaceParties(anyLong(), capture.capture());
+        assertThat(capture.getValue()).singleElement().satisfies(party -> {
+            assertThat(party.getContactEmail()).isEqualTo("ops@example.test");
+            assertThat(party.getTaxNo()).isEqualTo("TEST-TAX");
+        });
+        var draft = completeBooking("DRAFT", 3);
+        when(repository.find(1L)).thenReturn(draft);
+        var parties = parties(); parties.get(0).setPartyName("");
+        when(repository.parties(1L)).thenReturn(parties);
+        when(repository.requirements(1L)).thenReturn(List.of(requirement()));
+        assertThatThrownBy(() -> service.release(1L, 9L, "admin", "missing-party", new ReleaseRequest(3, null)))
+            .isInstanceOf(BizException.class).hasMessageContaining("尚未填写完整");
+        verify(repository, never()).transition(anyLong(), any(), any(), anyInt(), anyLong(), any());
+    }
+
     private AtomicReference<OceanBookingEntity> stubCreatedDraft() {
         AtomicReference<OceanBookingEntity> inserted = new AtomicReference<>();
         doAnswer(invocation -> { inserted.set(invocation.getArgument(0)); return null; })
@@ -412,7 +562,7 @@ class OceanBookingServiceTest {
 
     private static DraftData partialDraft(String remark) {
         return new DraftData(null, null, null, null, null, null, null, null, null, null,
-            null, null, null, null, null, null, null, null, null, remark, null, null);
+            null, null, null, null, null, null, null, null, null, remark, null, null, null, null, null, null, null, null, null, null, null, null, null);
     }
 
     private static DraftData completeDraft() {
@@ -420,11 +570,11 @@ class OceanBookingServiceTest {
             81L, null, "VESSEL", "V001", "CNSZX", "深圳", "USLAX", "洛杉矶",
             "LAX", LocalDateTime.of(2026, 9, 1, 0, 0),
             LocalDateTime.of(2026, 9, 20, 0, 0), null,
-            List.of(new PartyRequest("SHIPPER", "发货人", null, null, null),
-                new PartyRequest("CONSIGNEE", "收货人", null, null, null),
-                new PartyRequest("NOTIFY_PARTY", "通知人", null, null, null)),
+            List.of(new PartyRequest("SHIPPER", "发货人", null, null, null, null, null),
+                new PartyRequest("CONSIGNEE", "收货人", null, null, null, null, null),
+                new PartyRequest("NOTIFY_PARTY", "通知人", null, null, null, null, null)),
             List.of(new ContainerRequirementRequest("40HQ", "DRY", 2,
-                new BigDecimal("68"), new BigDecimal("19500"))));
+                new BigDecimal("68"), new BigDecimal("19500"))), null, null, null, null, null, null, null, null, null, null, null);
     }
 
     private static OceanBookingEntity completeBooking(String status, int version) {

firstleg/src/test/java/com/baiyue/firstleg/portschedule/service/AppointmentForecastServiceTest.java

@@ -9,8 +9,20 @@ import static org.assertj.core.api.Assertions.*;
 import static org.mockito.Mockito.*;
 
 class AppointmentForecastServiceTest {
+    /** 无船期预计观察时仍返回日历所用的柜级到港事实，供海外统一推算日期。 */
+    @Test void returnsTheCalendarArrivalEvenWhenLatestForecastIsAbsent() {
+        var mapper=mock(AppointmentForecastMapper.class);
+        var sources=mock(com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository.class);
+        var arrival=LocalDateTime.of(2026,10,30,23,30);
+        when(sources.byIds(List.of(1L))).thenReturn(List.of(
+            new com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource(1L,"D0001","CONT1",
+                null,null,null,null,arrival,"ACTUAL")));
+        var result=new AppointmentForecastService(mapper,sources).batch(List.of(1L));
+        assertThat(result.get(0).latest()).isNull();
+        assertThat(result.get(0).portArrivalAt()).isEqualTo(arrival);
+    }
     @Test void preservesMissingForecastAndSourceLocalTimesWithoutSynthesizingEta() {
-        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper);
+        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper,mock(com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository.class));
         var observed=LocalDateTime.of(2026,10,10,12,0);
         var latest=new AppointmentForecastMapper.Fact(1L,20L,"carrier","REF",observed,null,null);
         var previous=new AppointmentForecastMapper.Fact(1L,10L,"carrier","REF-OLD",observed.minusDays(1),observed.plusDays(5),null);
@@ -21,7 +33,7 @@ class AppointmentForecastServiceTest {
         verify(mapper).latest(List.of(1L,2L));verifyNoMoreInteractions(mapper);
     }
     @Test void rejectsInvalidBatchesAndMissingOrBlankInternalCredentials() {
-        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper);
+        var mapper=mock(AppointmentForecastMapper.class);var service=new AppointmentForecastService(mapper,mock(com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository.class));
         for(var ids:List.of(List.<Long>of(),List.of(1L,1L),List.of(-1L),Collections.nCopies(201,1L)))
             assertThatThrownBy(()->service.batch(ids)).isInstanceOf(org.springframework.web.server.ResponseStatusException.class);
         assertThatThrownBy(()->service.batch(null)).isInstanceOf(org.springframework.web.server.ResponseStatusException.class);

firstleg/src/test/java/com/baiyue/firstleg/repository/ContainerBookingMapperContractTest.java

@@ -8,12 +8,23 @@ import org.apache.ibatis.annotations.Param;
 import org.apache.ibatis.annotations.Update;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
+import com.baiyue.firstleg.oceanbooking.entity.OceanBookingEntity;
+import org.h2.jdbcx.JdbcDataSource;
+import org.mybatis.spring.SqlSessionTemplate;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.test.util.ReflectionTestUtils;
 
 import java.util.Arrays;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 @DisplayName("货柜数据库映射契约")
 class ContainerBookingMapperContractTest {
@@ -106,7 +117,7 @@ class ContainerBookingMapperContractTest {
     }
 
     @Test
-    @DisplayName("初始化与统一增量锁定真实柜号权威、订舱内唯一和ISO结构约束")
+    @DisplayName("初始化与统一增量保留柜号权威及订舱内唯一，不限制关联柜号ISO格式")
     void databaseContractsFreezeAuthoritativeContainerNumber() throws Exception {
         String module = Files.readString(Path.of("src/main/resources/db/phase3-smart-loading-schema.sql"));
         String unified = Files.readString(Path.of("../deploy/sql/头程数据库统一增量-MySQL8.sql"));
@@ -118,8 +129,41 @@ class ContainerBookingMapperContractTest {
             assertThat(source.toLowerCase())
                 .contains("unique key uk_container_booking_ocean_container (ocean_booking_id,container_no)")
                 .contains("key idx_container_booking_container_no (container_no,updated_at,id)")
-                .contains("constraint chk_container_booking_iso6346")
-                .contains("^[a-z]{3}[ujz][0-9]{7}$");
+                .doesNotContain("chk_container_booking_iso6346", "^[a-z]{3}[ujz][0-9]{7}$");
         }
     }
+
+    /** 从当前建表基线创建隔离数据库，真实执行关联 Mapper 并验证唯一键和版本。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void linksNonIsoContainerNumbersThroughActualSchemaAndMapper(String containerNo) throws Exception {
+        var dataSource = new JdbcDataSource();
+        dataSource.setURL("jdbc:h2:mem:container-link-" + java.util.UUID.randomUUID() + ";MODE=MySQL;DB_CLOSE_DELAY=-1");
+        var jdbc = new JdbcTemplate(dataSource);
+        String source = Files.readString(Path.of("src/main/resources/db/phase3-smart-loading-schema.sql"));
+        int start = source.indexOf("CREATE TABLE IF NOT EXISTS fl_container_booking (");
+        jdbc.execute(source.substring(start, source.indexOf(';', source.indexOf(") ENGINE=InnoDB", start)) + 1));
+        for (long id = 1; id <= 3; id++) {
+            jdbc.update("INSERT INTO fl_container_booking(id,cabinet_no,warehouse_id,warehouse_name,container_type,created_by,updated_by) VALUES(?,?,8,'测试仓','40HQ',9,9)",
+                id, "D" + id);
+        }
+        var configuration = new MybatisConfiguration();
+        configuration.setMapUnderscoreToCamelCase(true);
+        configuration.addMapper(ContainerBookingMapper.class);
+        var factory = new MybatisSqlSessionFactoryBean();
+        factory.setDataSource(dataSource);
+        factory.setConfiguration(configuration);
+        var session = new SqlSessionTemplate(factory.getObject());
+        var repository = new ContainerRepository();
+        ReflectionTestUtils.setField(repository, "mapper", session.getMapper(ContainerBookingMapper.class));
+        var booking = new OceanBookingEntity();
+
+        assertThat(repository.linkReleasedBooking(1L, 21L, 31L, containerNo, booking, 0, 9L, "操作员")).isEqualTo(1);
+        assertThat(jdbc.queryForObject("SELECT container_no FROM fl_container_booking WHERE id=1", String.class)).isEqualTo(containerNo);
+        assertThat(jdbc.queryForObject("SELECT version FROM fl_container_booking WHERE id=1", Integer.class)).isEqualTo(1);
+        assertThat(repository.linkReleasedBooking(1L, 21L, 31L, containerNo, booking, 0, 9L, "操作员")).isZero();
+        assertThatThrownBy(() -> repository.linkReleasedBooking(2L, 21L, 31L, containerNo, booking, 0, 9L, "操作员"))
+            .isInstanceOf(DuplicateKeyException.class);
+        assertThat(repository.linkReleasedBooking(3L, 22L, 32L, containerNo, booking, 0, 9L, "操作员")).isEqualTo(1);
+    }
 }

firstleg/src/test/java/com/baiyue/firstleg/repository/FbaPricingFeeTransitionTest.java

@@ -0,0 +1,107 @@
+package com.baiyue.firstleg.repository;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.MybatisSqlSessionFactoryBuilder;
+import com.baiyue.firstleg.mapper.InboundPricingMapper;
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.session.SqlSession;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** 通过真实 Mapper 执行费用状态更新，防止业务层放行但持久化条件遗漏作业状态。 */
+class FbaPricingFeeTransitionTest {
+    private SqlSession session;
+    private JdbcTemplate sql;
+    private FbaPricingRepository repository;
+
+    /** 每项测试使用独立内存表，保留真实的客户和逻辑删除条件。 */
+    @BeforeEach
+    void setUp() throws Exception {
+        var ds = new JdbcDataSource();
+        ds.setURL("jdbc:h2:mem:fee-transition-" + UUID.randomUUID() + ";MODE=MySQL");
+        var config = new MybatisConfiguration();
+        config.setEnvironment(new Environment("test", new JdbcTransactionFactory(), ds));
+        config.addMapper(InboundPricingMapper.class);
+        session = new MybatisSqlSessionFactoryBuilder().build(config).openSession(true);
+        session.getConnection();
+        sql = new JdbcTemplate(ds);
+        sql.execute("CREATE TABLE fl_inbound_order(id BIGINT PRIMARY KEY,tenant_id BIGINT," +
+            "process_status VARCHAR(32),fee_status VARCHAR(32),deleted BOOLEAN DEFAULT FALSE)");
+        repository = new FbaPricingRepository();
+        ReflectionTestUtils.setField(repository, "inbounds", session.getMapper(InboundPricingMapper.class));
+    }
+
+    /** 关闭最后一个连接后销毁本项测试的内存数据库。 */
+    @AfterEach
+    void tearDown() {
+        if (session != null) session.close();
+    }
+
+    /** 费用确认和发送不得提前完成一件代发组托或回退已有履约进度。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"FEE_CONFIRMING", "WAIT_PALLET", "WAIT_PALLETIZE", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"})
+    void confirmsAndSendsWithoutAdvancingPalletization(String processStatus) {
+        insertInbound(processStatus, "CALCULATED");
+
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isEqualTo(1);
+        assertState(processStatus, "CONFIRMED");
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        assertThat(repository.markInboundFeeSent(10001L, 88L, processStatus)).isEqualTo(1);
+        assertState("FEE_CONFIRMING".equals(processStatus) ? "WAIT_PALLET" : processStatus, "SENT");
+        assertThat(repository.markInboundFeeSent(10001L, 88L, processStatus)).isZero();
+    }
+
+    /** 待组托只补费用确认资格，不能绕过费用快照的前置状态。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"UNPRICED", "CONFIRMED", "SENT", "VOIDED"})
+    void rejectsConfirmationUnlessFeeIsCalculated(String feeStatus) {
+        insertInbound("WAIT_PALLETIZE", feeStatus);
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        assertState("WAIT_PALLETIZE", feeStatus);
+    }
+
+    /** 非确认阶段、其他客户和已删除入库单仍不可确认。 */
+    @Test
+    void preservesProcessCustomerAndDeletionGuards() {
+        insertInbound("WAIT_MEASURE", "CALCULATED");
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        sql.update("UPDATE fl_inbound_order SET process_status='WAIT_PALLETIZE' WHERE id=88");
+        assertThat(repository.markInboundConfirmed(20002L, 88L)).isZero();
+        sql.update("UPDATE fl_inbound_order SET deleted=TRUE WHERE id=88");
+        assertThat(repository.markInboundConfirmed(10001L, 88L)).isZero();
+        assertState("WAIT_PALLETIZE", "CALCULATED");
+    }
+
+    /** 模拟发送前作业状态发生变化，旧状态条件须拒绝写入。 */
+    @Test
+    void rejectsSendWithStaleProcessStatus() {
+        insertInbound("WAIT_SPLIT", "CONFIRMED");
+        assertThat(repository.markInboundFeeSent(10001L, 88L, "WAIT_PALLETIZE")).isZero();
+        assertState("WAIT_SPLIT", "CONFIRMED");
+    }
+
+    /** 准备单个客户的入库单，不调用共享环境。 */
+    private void insertInbound(String processStatus, String feeStatus) {
+        sql.update("INSERT INTO fl_inbound_order(id,tenant_id,process_status,fee_status) VALUES(88,10001,?,?)",
+            processStatus, feeStatus);
+    }
+
+    /** 同时核对物理作业状态与费用状态，防止用改主流程掩盖发送问题。 */
+    private void assertState(String processStatus, String feeStatus) {
+        assertThat(sql.queryForObject("SELECT process_status FROM fl_inbound_order WHERE id=88", String.class))
+            .isEqualTo(processStatus);
+        assertThat(sql.queryForObject("SELECT fee_status FROM fl_inbound_order WHERE id=88", String.class))
+            .isEqualTo(feeStatus);
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/repository/FbaPricingRepositoryRuleListTest.java

@@ -194,8 +194,9 @@ class FbaPricingRepositoryRuleListTest {
             .contains(10001L, 88L, "FEE_CONFIRMING", "CONFIRMED", "SENT", "WAIT_PALLET");
     }
 
+    /** 费用确认状态集覆盖待组托及后续履约阶段。 */
     @Test
-    void feeConfirmationAllowsPostLoadingInboundStatuses() {
+    void feeConfirmationAllowsPalletizationAndPostLoadingInboundStatuses() {
         String source;
         try {
             source = Files.readString(Path.of(
@@ -205,7 +206,7 @@ class FbaPricingRepositoryRuleListTest {
             throw new AssertionError(exception);
         }
         assertThat(source)
-            .contains("List.of(\"FEE_CONFIRMING\", \"WAIT_PALLET\", \"WAIT_SPLIT\", \"LOADING\", \"LOADED\", \"DELIVERED\")");
+            .contains("List.of(\"FEE_CONFIRMING\", \"WAIT_PALLET\", \"WAIT_PALLETIZE\", \"WAIT_SPLIT\", \"LOADING\", \"LOADED\", \"DELIVERED\")");
     }
 
     @Test

firstleg/src/test/java/com/baiyue/firstleg/repository/LoadingCompletionCheckpointLeaseTest.java

@@ -0,0 +1,190 @@
+package com.baiyue.firstleg.repository;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
+import com.baiyue.firstleg.mapper.LoadingCompletionCommandMapper;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mybatis.spring.SqlSessionTemplate;
+import org.springframework.aop.framework.ProxyFactory;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.DataSourceTransactionManager;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.transaction.annotation.AnnotationTransactionAttributeSource;
+import org.springframework.transaction.interceptor.TransactionInterceptor;
+
+import java.sql.SQLException;
+import java.time.LocalDateTime;
+import java.util.UUID;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.AdditionalAnswers.delegatesTo;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+
+/** 用真实 Mapper SQL、事务代理和独立连接验证完成检查点的租约隔离。 */
+class LoadingCompletionCheckpointLeaseTest {
+    private JdbcDataSource dataSource;
+    private JdbcTemplate jdbc;
+    private LoadingCompletionCommandMapper mapper;
+    private LoadingCompletionCommandRepository commands;
+
+    /** 每个用例使用独立内存数据库，不访问共享环境。 */
+    @BeforeEach
+    void setup() throws Exception {
+        dataSource = new JdbcDataSource();
+        dataSource.setURL("jdbc:h2:mem:completion-lease-" + UUID.randomUUID()
+            + ";MODE=MySQL;DB_CLOSE_DELAY=-1;LOCK_TIMEOUT=1000");
+        jdbc = new JdbcTemplate(dataSource);
+        jdbc.execute("""
+            CREATE TABLE fl_loading_completion_command(
+              id BIGINT PRIMARY KEY,command_status VARCHAR(16),lease_owner VARCHAR(128),lease_until TIMESTAMP,
+              attempt_count INT,next_retry_at TIMESTAMP,updated_at TIMESTAMP,completed_at TIMESTAMP,
+              failure_stage VARCHAR(40),failure_code VARCHAR(32),failure_request_id VARCHAR(64),failure_trace_id VARCHAR(64))
+            """);
+        jdbc.execute("""
+            CREATE TABLE fl_loading_completion_checkpoint(
+              command_id BIGINT,tenant_id BIGINT,inbound_id BIGINT,owner_sequence INT,checkpoint_stage VARCHAR(24),
+              updated_at TIMESTAMP,PRIMARY KEY(command_id,tenant_id,inbound_id))
+            """);
+        jdbc.update("""
+            INSERT INTO fl_loading_completion_command(id,command_status,lease_owner,lease_until,attempt_count,next_retry_at)
+            VALUES(900,'PROCESSING','old-owner',DATEADD('HOUR',1,CURRENT_TIMESTAMP),1,CURRENT_TIMESTAMP)
+            """);
+        var configuration = new MybatisConfiguration();
+        configuration.setMapUnderscoreToCamelCase(true);
+        configuration.addMapper(LoadingCompletionCommandMapper.class);
+        var factory = new MybatisSqlSessionFactoryBean();
+        factory.setDataSource(dataSource);
+        factory.setConfiguration(configuration);
+        mapper = new SqlSessionTemplate(factory.getObject()).getMapper(LoadingCompletionCommandMapper.class);
+        commands = repository(mapper);
+    }
+
+    /** 生产 Repository 的注解事务必须真实生效，覆盖锁定与写入两条 SQL。 */
+    private LoadingCompletionCommandRepository repository(LoadingCompletionCommandMapper targetMapper) {
+        var target = new LoadingCompletionCommandRepository();
+        ReflectionTestUtils.setField(target, "mapper", targetMapper);
+        var proxy = new ProxyFactory(target);
+        proxy.addAdvice(new TransactionInterceptor(new DataSourceTransactionManager(dataSource),
+            new AnnotationTransactionAttributeSource()));
+        return (LoadingCompletionCommandRepository) proxy.getProxy();
+    }
+
+    /** 模拟原执行者续租后暂停，租约过期并被新执行者领取推进，再恢复旧线程。 */
+    @Test
+    void pausedOldOwnerCannotDowngradeTheNewOwnersCompletedCheckpoint() throws Exception {
+        var renewed = new CountDownLatch(1);
+        var resumeOldOwner = new CountDownLatch(1);
+        var executor = Executors.newSingleThreadExecutor();
+        try {
+            var oldWrite = executor.submit(() -> {
+                assertThat(commands.renew(900, "old-owner", LocalDateTime.now().plusMinutes(10))).isTrue();
+                renewed.countDown();
+                assertThat(resumeOldOwner.await(10, TimeUnit.SECONDS)).isTrue();
+                return commands.checkpoint(900, "old-owner", 101, 50, 1, "READY");
+            });
+            assertThat(renewed.await(10, TimeUnit.SECONDS)).isTrue();
+            jdbc.update("UPDATE fl_loading_completion_command SET lease_until=DATEADD('SECOND',-1,CURRENT_TIMESTAMP) WHERE id=900");
+            assertThat(commands.claim(900, "new-owner", LocalDateTime.now().plusMinutes(10))).isTrue();
+            assertThat(commands.checkpoint(900, "new-owner", 101, 50, 1, "INBOUND_COMPLETED")).isTrue();
+            resumeOldOwner.countDown();
+            assertThat(oldWrite.get(10, TimeUnit.SECONDS)).isFalse();
+            assertThat(mapper.checkpointCompleted(900, "old-owner", 101, 50, 1, "SETTLED")).isZero();
+            assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("INBOUND_COMPLETED");
+            assertThat(jdbc.queryForObject("SELECT lease_owner FROM fl_loading_completion_command WHERE id=900", String.class))
+                .isEqualTo("new-owner");
+        } finally {
+            resumeOldOwner.countDown();
+            executor.shutdownNow();
+        }
+    }
+
+    /** 锁定后的实际写入前，独立数据库连接仍不能取得同一命令行的锁。 */
+    @Test
+    void commandRowRemainsLockedAcrossTheLeaseCheckAndCheckpointInsert() {
+        LoadingCompletionCommandMapper observed = mock(LoadingCompletionCommandMapper.class, delegatesTo(mapper));
+        doAnswer(call -> {
+            assertThatThrownBy(() -> {
+                try (var connection = dataSource.getConnection();
+                     var statement = connection.prepareStatement("SELECT id FROM fl_loading_completion_command WHERE id=900 FOR UPDATE NOWAIT")) {
+                    statement.executeQuery().close();
+                }
+            }).isInstanceOf(SQLException.class)
+                .satisfies(error -> assertThat(((SQLException) error).getErrorCode()).isEqualTo(50200));
+            return mapper.checkpointCompleted(call.getArgument(0), call.getArgument(1), call.getArgument(2),
+                call.getArgument(3), call.getArgument(4), call.getArgument(5));
+        }).when(observed).checkpointCompleted(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
+        assertThat(repository(observed).checkpoint(900, "old-owner", 101, 50, 1, "READY")).isTrue();
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("READY");
+    }
+
+    /** 初次锁定检查后若租约失效，实际 INSERT 也必须拒绝，不能仅依赖前一次检查。 */
+    @Test
+    void checkpointInsertRechecksLeaseValidityAfterTheInitialLock() {
+        LoadingCompletionCommandMapper observed = mock(LoadingCompletionCommandMapper.class, delegatesTo(mapper));
+        doAnswer(call -> {
+            jdbc.update("UPDATE fl_loading_completion_command SET lease_until=DATEADD('SECOND',-1,CURRENT_TIMESTAMP) WHERE id=900");
+            return mapper.checkpointCompleted(call.getArgument(0), call.getArgument(1), call.getArgument(2),
+                call.getArgument(3), call.getArgument(4), call.getArgument(5));
+        }).when(observed).checkpointCompleted(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
+        assertThat(repository(observed).checkpoint(900, "old-owner", 101, 50, 1, "READY")).isFalse();
+        assertThat(commands.checkpoint(900, 101, 50)).isNull();
+    }
+
+    /** 驱动将已持久化的幂等重放计为零行时，仍须以锁内当前有效租约确认。 */
+    @Test
+    void zeroAffectedRowsCanConfirmAnIdempotentCheckpointUnderTheSameValidLease() {
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "READY")).isTrue();
+        LoadingCompletionCommandMapper observed = mock(LoadingCompletionCommandMapper.class, delegatesTo(mapper));
+        doAnswer(call -> {
+            mapper.checkpointCompleted(call.getArgument(0), call.getArgument(1), call.getArgument(2),
+                call.getArgument(3), call.getArgument(4), call.getArgument(5));
+            return 0;
+        }).when(observed).checkpointCompleted(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
+        assertThat(repository(observed).checkpoint(900, "old-owner", 101, 50, 1, "READY")).isTrue();
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("READY");
+    }
+
+    /** 已过期但尚未被重新领取的所有者也不能写检查点、续租或写命令终态。 */
+    @Test
+    void expiredLeaseCannotWriteCheckpointRenewFailOrComplete() {
+        jdbc.update("UPDATE fl_loading_completion_command SET lease_until=DATEADD('SECOND',-1,CURRENT_TIMESTAMP) WHERE id=900");
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "READY")).isFalse();
+        assertThat(mapper.checkpointCompleted(900, "old-owner", 101, 50, 1, "READY")).isZero();
+        assertThat(commands.renew(900, "old-owner", LocalDateTime.now().plusMinutes(10))).isFalse();
+        assertThat(commands.fail(900, "old-owner", "FAILED", LocalDateTime.now(), "LEASE_LOST", "A0409", null, null)).isFalse();
+        assertThat(commands.complete(900, "old-owner")).isFalse();
+        assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM fl_loading_completion_checkpoint", Integer.class)).isZero();
+        assertThat(jdbc.queryForObject("SELECT command_status FROM fl_loading_completion_command WHERE id=900", String.class))
+            .isEqualTo("PROCESSING");
+    }
+
+    /** 同一当前所有者的重复或迟到阶段也只能保持或推进，不能降低完成检查点。 */
+    @Test
+    void validOwnerCheckpointStagesAreMonotonic() {
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "SETTLED")).isTrue();
+        commands.checkpoint(900, "old-owner", 101, 50, 1, "READY");
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("SETTLED");
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "INBOUND_COMPLETED")).isTrue();
+        commands.checkpoint(900, "old-owner", 101, 50, 1, "SETTLED");
+        commands.checkpoint(900, "old-owner", 101, 50, 1, "READY");
+        assertThat(commands.checkpoint(900, 101, 50)).isEqualTo("INBOUND_COMPLETED");
+    }
+
+    /** 完成或失败后的命令不允许追加检查点，即使所有者与租期字段仍有旧值。 */
+    @Test
+    void terminalCommandCannotAcceptAnotherCheckpoint() {
+        jdbc.update("UPDATE fl_loading_completion_command SET command_status='COMPLETED' WHERE id=900");
+        assertThat(commands.checkpoint(900, "old-owner", 101, 50, 1, "READY")).isFalse();
+        assertThat(mapper.checkpointCompleted(900, "old-owner", 101, 50, 1, "READY")).isZero();
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/repository/LoadingCompletionOwnerPersistenceTest.java

@@ -31,6 +31,8 @@ class LoadingCompletionOwnerPersistenceTest {
         jdbc.execute("CREATE TABLE fl_loading_plan_item(id BIGINT,loading_plan_id BIGINT,account_id BIGINT,inbound_id BIGINT,deleted INT,package_count INT)");
         jdbc.execute("CREATE TABLE fl_loading_pick_item(id BIGINT,pick_task_id BIGINT,loading_plan_item_id BIGINT,item_status VARCHAR,picked_package_count INT)");
         jdbc.execute("CREATE TABLE fl_loading_completion_checkpoint(command_id BIGINT,tenant_id BIGINT,inbound_id BIGINT,owner_sequence INT,checkpoint_stage VARCHAR(24),updated_at TIMESTAMP,PRIMARY KEY(command_id,tenant_id,inbound_id))");
+        jdbc.execute("CREATE TABLE fl_loading_completion_command(id BIGINT PRIMARY KEY,command_status VARCHAR(16),lease_owner VARCHAR(128),lease_until TIMESTAMP)");
+        jdbc.update("INSERT INTO fl_loading_completion_command VALUES(900,'PROCESSING','owner-test',DATEADD('HOUR',1,CURRENT_TIMESTAMP))");
         jdbc.update("INSERT INTO fl_loading_pick_task VALUES(20,10)");
         row(1, 101, 50, 3, "PARTIAL", 2, 10, 0);
         row(2, 101, 50, 1, "SKIPPED", 0, 10, 0); // same source SKU history
@@ -76,11 +78,11 @@ class LoadingCompletionOwnerPersistenceTest {
 
     @Test
     void completedActualCheckpointsAreReadBackUnchangedAndSkippedReadyCheckpointIsNotACompletionOwner() {
-        checkpoints.checkpointCompleted(900, 101, 50, 1, "READY");
-        checkpoints.checkpointCompleted(900, 101, 50, 1, "SETTLED");
-        checkpoints.checkpointCompleted(900, 101, 50, 1, "INBOUND_COMPLETED");
-        checkpoints.checkpointCompleted(900, 202, 60, 2, "INBOUND_COMPLETED");
-        checkpoints.checkpointCompleted(900, 303, 70, 3, "READY");
+        checkpoints.checkpointCompleted(900, "owner-test", 101, 50, 1, "READY");
+        checkpoints.checkpointCompleted(900, "owner-test", 101, 50, 1, "SETTLED");
+        checkpoints.checkpointCompleted(900, "owner-test", 101, 50, 1, "INBOUND_COMPLETED");
+        checkpoints.checkpointCompleted(900, "owner-test", 202, 60, 2, "INBOUND_COMPLETED");
+        checkpoints.checkpointCompleted(900, "owner-test", 303, 70, 3, "READY");
         assertThat(checkpoints.checkpoint(900, 101, 50)).isEqualTo("INBOUND_COMPLETED");
         assertThat(checkpoints.checkpoint(900, 202, 60)).isEqualTo("INBOUND_COMPLETED");
         assertThat(checkpoints.checkpoint(900, 303, 70)).isEqualTo("READY");

firstleg/src/test/java/com/baiyue/firstleg/repository/TruckAppointmentMapperContractTest.java

@@ -10,6 +10,7 @@ import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class TruckAppointmentMapperContractTest {
+    /** 候选不依赖附件，仍保留提单号、状态、唯一预约和乐观锁条件。 */
     @Test void mapsToPhase3TableAndUsesOptimisticGuards() throws Exception {
         assertThat(TruckAppointmentEntity.class.getAnnotation(TableName.class).value()).isEqualTo("fl_truck_appointment");
         String page = TruckAppointmentMapper.class.getMethod("page", com.baomidou.mybatisplus.extension.plugins.pagination.Page.class, com.baiyue.firstleg.dto.TruckAppointmentDtos.Query.class).getAnnotation(Select.class).value()[0];
@@ -18,9 +19,10 @@ class TruckAppointmentMapperContractTest {
             .doesNotContain("fl_container_booking", "cabinet_no", "container_no");
         assertThat(page).doesNotContain("customer_id", "customerId", "customer_name");
         String candidates = TruckAppointmentMapper.class.getMethod("candidates", com.baomidou.mybatisplus.extension.plugins.pagination.Page.class, com.baiyue.firstleg.dto.TruckAppointmentDtos.CandidateQuery.class).getAnnotation(Select.class).value()[0];
-        assertThat(candidates).contains("FROM fl_ocean_booking o", "o.status='RELEASED'", "d.valid=1",
-            "'BOOKING_CONFIRMATION','BILL_OF_LADING'", "t.ocean_booking_id=o.id",
-            "t.status NOT IN ('CANCELLED','EXCEPTION')", "bookingDocumentReady");
+        assertThat(candidates).contains("FROM fl_ocean_booking o", "o.status='RELEASED'",
+            "o.bill_of_lading_no IS NOT NULL", "o.bill_of_lading_no<>''", "t.ocean_booking_id=o.id",
+            "t.status NOT IN ('CANCELLED','EXCEPTION')");
+        assertThat(candidates).doesNotContain("fl_ocean_booking_document", "bookingDocumentReady");
         assertThat(candidates).doesNotContain("fl_ocean_booking_container_allocation", "fl_container_booking",
             "loadingPlanId", "containerBookingId", "cabinetNo", "containerNo");
         String transition = TruckAppointmentMapper.class.getMethod("transition", long.class, String.class, String.class, int.class).getAnnotation(Update.class).value()[0];

firstleg/src/test/java/com/baiyue/firstleg/service/ContainerServiceTest.java

@@ -297,21 +297,23 @@ class ContainerServiceTest {
         verifyNoInteractions(oceanBookings);
     }
 
-    @Test
+    /** 提柜补录使用相同的非 ISO 规则，并按版本原子保存。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "LOCAL-2026-001"})
     @DisplayName("提柜后按柜次版本原子补录真实柜号")
-    void assignsRealContainerNumberAfterPickup() {
+    void assignsRealContainerNumberAfterPickup(String containerNo) {
         ContainerBookingEntity linked = booking("EDITING", 3);
         linked.setContainerNo(null); linked.setOceanBookingId(21L); linked.setOceanBookingRequirementId(31L);
         ContainerBookingEntity assigned = booking("EDITING", 4);
-        assigned.setContainerNo("MSCU6639870"); assigned.setOceanBookingId(21L); assigned.setOceanBookingRequirementId(31L);
+        assigned.setContainerNo(containerNo); assigned.setOceanBookingId(21L); assigned.setOceanBookingRequirementId(31L);
         when(repository.find(11L)).thenReturn(linked, assigned);
-        when(repository.assignRealContainerNo(11L, "MSCU6639870", 3, 9L, "admin")).thenReturn(1);
+        when(repository.assignRealContainerNo(11L, containerNo, 3, 9L, "admin")).thenReturn(1);
 
         ContainerBookingEntity result = service.assignRealContainerNo(
-            11L, " ms cu 663987 0 ", 3, 9L, "admin");
+            11L, " " + containerNo.toLowerCase(java.util.Locale.ROOT) + " ", 3, 9L, "admin");
 
-        assertThat(result.getContainerNo()).isEqualTo("MSCU6639870");
-        verify(repository).assignRealContainerNo(11L, "MSCU6639870", 3, 9L, "admin");
+        assertThat(result.getContainerNo()).isEqualTo(containerNo);
+        verify(repository).assignRealContainerNo(11L, containerNo, 3, 9L, "admin");
     }
 
     @Test
@@ -329,17 +331,21 @@ class ContainerServiceTest {
         verify(repository, never()).assignRealContainerNo(anyLong(), anyString(), anyInt(), anyLong(), anyString());
     }
 
-    @Test
-    @DisplayName("首次关联拒绝错误ISO 6346校验位")
-    void rejectsInvalidContainerNumberCheckDigit() {
+    /** 关联入口允许非 ISO 柜号，继续按原版本和关联范围保存。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    @DisplayName("首次关联不因柜号长度结构或校验位阻断")
+    void linksWithoutIsoContainerNumberValidation(String containerNo) {
         stubLinkContext();
+        when(repository.linkReleasedBooking(eq(11L), eq(21L), eq(31L), eq(containerNo),
+            any(OceanBookingEntity.class), eq(2), eq(9L), eq("admin"))).thenReturn(1);
 
-        assertThatThrownBy(() -> service.linkOceanBooking(11L, 9L, "admin",
-            new OceanBookingLinkRequest(21L, 31L, "MSCU6639871", 2)))
-            .isInstanceOf(BizException.class).hasMessageContaining("校验位");
+        service.linkOceanBooking(11L, 9L, "admin", new OceanBookingLinkRequest(21L, 31L, containerNo, 2));
 
-        verify(repository, never()).linkReleasedBooking(anyLong(), anyLong(), anyLong(), anyString(),
-            any(), anyInt(), anyLong(), anyString());
+        verify(repository).containerNoExists(21L, containerNo, 11L);
+        verify(repository).linkReleasedBooking(eq(11L), eq(21L), eq(31L), eq(containerNo),
+            any(OceanBookingEntity.class), eq(2), eq(9L), eq("admin"));
+        verify(oceanBookings).insert(any(OceanBookingContainerAllocationEntity.class));
     }
 
     @Test

firstleg/src/test/java/com/baiyue/firstleg/service/FbaPricingServiceTest.java

@@ -22,6 +22,9 @@ import com.baiyue.firstleg.pricebookquery.application.model.PriceBookQueryRows.R
 import jakarta.annotation.Resource;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.ArgumentCaptor;
 import org.apache.ibatis.annotations.Select;
 import org.springframework.boot.test.mock.mockito.MockBean;
@@ -223,11 +226,13 @@ class FbaPricingServiceTest {
         verify(financeOutbox, never()).publishInbound(any(), anyLong(), anyLong(), anyLong(), anyInt(), any());
     }
 
-    @Test
-    @DisplayName("待分柜边界确认费用后仍保持主流程状态")
-    void confirmsAtWaitSplitWithoutRollingBackProcessStatus() {
+    /** 待组托、待分柜确认费用均不推进物流主流程。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"WAIT_PALLETIZE", "WAIT_SPLIT"})
+    @DisplayName("待组托或待分柜确认费用后仍保持主流程状态")
+    void confirmsWithoutRollingBackProcessStatus(String processStatus) {
         InboundPricingEntity inbound = inbound("10.000", "1.0000");
-        inbound.setProcessStatus("WAIT_SPLIT");
+        inbound.setProcessStatus(processStatus);
         inbound.setFeeStatus("CALCULATED");
         InboundFeeEntity fee = savedFee("CALCULATED");
         when(repository.findLatestFee(TENANT, INBOUND)).thenReturn(fee);
@@ -244,7 +249,7 @@ class FbaPricingServiceTest {
         FeeSnapshotResponse response = service.confirm(
             TENANT, OPERATOR, INBOUND, "confirm-wait-split");
 
-        assertThat(response.nextProcessStatus()).isEqualTo("WAIT_SPLIT");
+        assertThat(response.nextProcessStatus()).isEqualTo(processStatus);
         verify(repository).markInboundConfirmed(TENANT, INBOUND);
     }
 
@@ -436,11 +441,13 @@ class FbaPricingServiceTest {
         verify(repository, never()).insertFee(any());
     }
 
-    @Test
+    /** 待组托发送费用保留主状态，重复请求不重复生成费用事件。 */
+    @ParameterizedTest
+    @CsvSource({"FEE_CONFIRMING,WAIT_PALLET", "WAIT_PALLETIZE,WAIT_PALLETIZE"})
     @DisplayName("重复发送只返回首次结果且不会重复写Outbox")
-    void sendIsIdempotentAndDoesNotDuplicateOutbox() {
+    void sendIsIdempotentAndDoesNotDuplicateOutbox(String processStatus, String expectedStatus) {
         InboundPricingEntity inbound = inbound("10", "1");
-        inbound.setProcessStatus("FEE_CONFIRMING");
+        inbound.setProcessStatus(processStatus);
         inbound.setFeeStatus("CONFIRMED");
         InboundFeeEntity confirmed = savedFee("CONFIRMED");
         when(repository.findInbound(TENANT, INBOUND)).thenReturn(inbound);
@@ -448,7 +455,7 @@ class FbaPricingServiceTest {
         when(repository.findIdempotency(TENANT, OPERATOR, "FEE_SEND", "send-once"))
             .thenReturn(null, completed("FEE_SEND", 501L));
         when(repository.sendFee(TENANT, 501L, OPERATOR, NOW)).thenReturn(1);
-        when(repository.markInboundFeeSent(TENANT, INBOUND, "FEE_CONFIRMING")).thenReturn(1);
+        when(repository.markInboundFeeSent(TENANT, INBOUND, processStatus)).thenReturn(1);
         when(repository.completeIdempotency(any(), eq(501L), eq(NOW))).thenReturn(1);
         when(repository.findFee(TENANT, 501L)).thenReturn(confirmed);
         InboundFeeItemEntity item = new InboundFeeItemEntity(); item.setUnitPrice(new BigDecimal("2.00"));
@@ -459,8 +466,8 @@ class FbaPricingServiceTest {
         FeeSnapshotResponse first = service.send(TENANT, OPERATOR, INBOUND, "send-once");
         FeeSnapshotResponse repeated = service.send(TENANT, OPERATOR, INBOUND, "send-once");
 
-        assertThat(first.nextProcessStatus()).isEqualTo("WAIT_PALLET");
-        assertThat(repeated.nextProcessStatus()).isEqualTo("WAIT_PALLET");
+        assertThat(first.nextProcessStatus()).isEqualTo(expectedStatus);
+        assertThat(repeated.nextProcessStatus()).isEqualTo(expectedStatus);
         verify(financeOutbox, times(1)).publishInbound(
             eq(FinanceFeeSourceOutboxService.PUBLISHED), eq(TENANT), eq(INBOUND),
             eq(501L), eq(1), eq(NOW));

firstleg/src/test/java/com/baiyue/firstleg/service/LoadingCompletedOutboxServiceTest.java

@@ -101,6 +101,23 @@ class LoadingCompletedOutboxServiceTest {
         assertThat(first.eventVersion()).isEqualTo(3);
     }
 
+    /** 非 ISO 柜号能生成当前 V3 事件，并保持冻结柜号原值。 */
+    @org.junit.jupiter.params.ParameterizedTest
+    @org.junit.jupiter.params.provider.ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "LOCAL-2026-001"})
+    void publishesNonIsoContainerNumber(String containerNo) throws Exception {
+        Row value = row(11, 100, 101);
+        value.setContainerNo(containerNo);
+        when(snapshots.rows(90L)).thenReturn(List.of(value));
+
+        service.publish(90L);
+
+        ArgumentCaptor<InboundOutboxEntity> captured = ArgumentCaptor.forClass(InboundOutboxEntity.class);
+        verify(outbox).insert(captured.capture());
+        EventEnvelope event = mapper.readValue(captured.getValue().getPayloadJson(), EventEnvelope.class);
+        assertThat(event.eventVersion()).isEqualTo(3);
+        assertThat(event.payload().path("containerNo").asText()).isEqualTo(containerNo);
+    }
+
     @Test void requiresFrozenPhysicalContainerNumberBeforePublishing() {
         Row value = row(11, 100, 101); value.setContainerNo(" ");
         when(snapshots.rows(90L)).thenReturn(List.of(value));

firstleg/src/test/java/com/baiyue/firstleg/service/LoadingCompletionWorkerTest.java

@@ -8,22 +8,124 @@ import com.baiyue.firstleg.repository.LoadingPickRepository;
 import org.junit.jupiter.api.Test;
 import org.springframework.boot.test.mock.mockito.MockBean;
 import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.task.TaskExecutor;
+import org.springframework.transaction.TransactionDefinition;
+import org.springframework.transaction.annotation.EnableTransactionManagement;
+import org.springframework.transaction.support.AbstractPlatformTransactionManager;
+import org.springframework.transaction.support.DefaultTransactionStatus;
+import org.springframework.transaction.support.TransactionTemplate;
+import org.mockito.ArgumentCaptor;
 
 import java.time.LocalDateTime;
 import java.util.List;
+import java.util.concurrent.RejectedExecutionException;
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
-@SpringJUnitConfig(LoadingCompletionWorker.class)
+@SpringJUnitConfig({LoadingCompletionWorker.class, LoadingCompletionWorkerTest.TransactionEvents.class})
 class LoadingCompletionWorkerTest {
+    /** 与生产事务装配一致，注册事务事件工厂，避免普通事件工厂立即调用监听器。 */
+    @Configuration
+    @EnableTransactionManagement
+    static class TransactionEvents {}
+
     @MockBean private LoadingCompletionCommandRepository commands;
     @MockBean private LoadingPickRepository picks;
     @MockBean private LoadingPickService loadingPicks;
+    @MockBean(name = "applicationTaskExecutor") private TaskExecutor completionExecutor;
     @jakarta.annotation.Resource private LoadingCompletionWorker worker;
+    @jakarta.annotation.Resource private ApplicationEventPublisher events;
+
+    /** 真实事务同步回调必须在提交后才将完成工作交给执行器。 */
+    @Test
+    void committedAcceptanceStartsImmediatelyThroughTheDurableLease() {
+        LoadingCompletionCommandEntity command = command(0);
+        when(commands.command(900L)).thenReturn(command);
+        when(commands.claim(eq(900L), any(String.class), any(LocalDateTime.class))).thenReturn(true);
+        transactions().executeWithoutResult(status -> {
+            events.publishEvent(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+            verify(completionExecutor, never()).execute(any());
+            verify(loadingPicks, never()).processCompletion(any(), any());
+        });
+
+        ArgumentCaptor<Runnable> work = ArgumentCaptor.forClass(Runnable.class);
+        verify(completionExecutor).execute(work.capture());
+        verify(loadingPicks, never()).processCompletion(any(), any());
+        work.getValue().run();
+
+        verify(commands).claim(eq(900L), any(String.class), any(LocalDateTime.class));
+        verify(loadingPicks).processCompletion(eq(command), any(String.class));
+    }
+
+    /** 回滚后的命令没有权威落库事实，不允许唤醒或执行结算。 */
+    @Test
+    void rolledBackAcceptanceNeverSchedulesCompletion() {
+        transactions().executeWithoutResult(status -> {
+            events.publishEvent(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+            status.setRollbackOnly();
+        });
+        verify(completionExecutor, never()).execute(any());
+        verify(commands, never()).command(900L);
+    }
+
+    /** 即时唤醒不能绕过定时执行者已取得的租约。 */
+    @Test
+    void immediateWakeupDoesNotProcessAnAlreadyLeasedCommand() {
+        when(commands.command(900L)).thenReturn(command(0));
+        worker.accepted(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+        ArgumentCaptor<Runnable> work = ArgumentCaptor.forClass(Runnable.class);
+        verify(completionExecutor).execute(work.capture());
+        work.getValue().run();
+        verify(loadingPicks, never()).processCompletion(any(), any());
+    }
+
+    /** 执行器拒绝时受理不报错，定时扫描仍可从原命令恢复。 */
+    @Test
+    void rejectedWakeupLeavesScheduledRecoveryAvailable() {
+        doThrow(new RejectedExecutionException("busy")).when(completionExecutor).execute(any());
+        LoadingCompletionCommandEntity command = command(0);
+        when(commands.due(10)).thenReturn(List.of(command));
+        when(commands.claim(eq(900L), any(String.class), any(LocalDateTime.class))).thenReturn(true);
+        worker.accepted(new LoadingPickService.CompletionAccepted(900L, System.nanoTime()));
+        worker.dispatch();
+        verify(loadingPicks).processCompletion(eq(command), any(String.class));
+    }
+
+    /** 同进程重领已到期命令也必须更换所有者，旧线程不能续租或落库。 */
+    @Test
+    void everyClaimUsesAnIndependentLeaseOwner() {
+        LoadingCompletionCommandEntity command = command(0);
+        when(commands.due(10)).thenReturn(List.of(command));
+        when(commands.claim(eq(900L), any(String.class), any(LocalDateTime.class))).thenReturn(true);
+        worker.dispatch();
+        worker.dispatch();
+        ArgumentCaptor<String> owners = ArgumentCaptor.forClass(String.class);
+        verify(loadingPicks, times(2)).processCompletion(eq(command), owners.capture());
+        assertThat(owners.getAllValues()).doesNotHaveDuplicates();
+    }
+
+    /** 隔离数据库依赖，仅用 Spring 的真实事务同步机制核对提交、回滚边界。 */
+    private static TransactionTemplate transactions() {
+        return new TransactionTemplate(new AbstractPlatformTransactionManager() {
+            /** 为每次测试提供独立事务对象。 */
+            @Override protected Object doGetTransaction() { return new Object(); }
+            /** 测试事务不访问数据库。 */
+            @Override protected void doBegin(Object transaction, TransactionDefinition definition) {}
+            /** 让 Spring 正常触发提交同步回调。 */
+            @Override protected void doCommit(DefaultTransactionStatus status) {}
+            /** 让 Spring 正常触发回滚同步回调。 */
+            @Override protected void doRollback(DefaultTransactionStatus status) {}
+        });
+    }
 
     @Test
     void transientFailureIsReleasedForBackoffRetry() {

firstleg/src/test/java/com/baiyue/firstleg/service/LoadingListServiceTest.java

@@ -26,6 +26,9 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.annotation.Resource;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullSource;
+import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.ArgumentCaptor;
 import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.boot.test.mock.mockito.MockBean;
@@ -147,10 +150,45 @@ class LoadingListServiceTest {
         verifyNoInteractions(loadingPickService);
     }
 
+    /** 只更新航次时，关联已接受的非 ISO 柜号不应被重新校验或改写。 */
+    @ParameterizedTest
+    @NullSource
+    @ValueSource(strings = {"LOCAL-1", " local-1 "})
+    void preservesLinkedNonIsoNumberWhenOnlyVoyageChanges(String requested) {
+        AggregateRow before = row("EDITING", 3);
+        before.setContainerNo("LOCAL-1");
+        before.setVoyageNo("001E");
+        when(repository.aggregate(10L)).thenReturn(before);
+        when(repository.updateTransport(10L, 3, "LOCAL-1", "023E", 9L, "operator")).thenReturn(1);
+
+        service.updateTransport(10L, 100L, 9L, "operator", "preserve-linked-number",
+            new TransportUpdateRequest(requested, "023E", 3, null));
+
+        verify(repository).updateTransport(10L, 3, "LOCAL-1", "023E", 9L, "operator");
+        verify(loadingPickService).beginIfReady(30L, 9L, "operator");
+    }
+
+    /** 运输纠错与关联入口一致，只规范化柜号并保留纠错原因。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void acceptsNonIsoNumberInTransportCorrection(String containerNo) {
+        AggregateRow before = row("EDITING", 3);
+        before.setContainerNo("LOCAL-1");
+        when(repository.aggregate(10L)).thenReturn(before);
+        when(repository.updateTransport(10L, 3, containerNo, null, 9L, "operator")).thenReturn(1);
+
+        service.updateTransport(10L, 100L, 9L, "operator", "non-iso-correction",
+            new TransportUpdateRequest(" " + containerNo.toLowerCase(java.util.Locale.ROOT) + " ", null, 3, "纠错"));
+
+        verify(repository).updateTransport(10L, 3, containerNo, null, 9L, "operator");
+        verify(loadingPickService).beginIfReady(30L, 9L, "operator");
+    }
+
+    /** 关联入口接受的非 ISO 柜号，在 PDA 领取前仍可按版本和原因纠正为真实柜号。 */
     @Test
     void pushedEditingPreloadCanCorrectExistingContainerNumberBeforePdaClaim() {
         AggregateRow before = row("EDITING", 3);
-        before.setContainerNo("MSCU6639870");
+        before.setContainerNo("LOCAL-1");
         AggregateRow after = row("EDITING", 4);
         after.setContainerNo("CSQU3054383");
         when(repository.aggregate(10L)).thenReturn(before, after);
@@ -200,7 +238,7 @@ class LoadingListServiceTest {
 
         assertThatThrownBy(() -> service.updateTransport(10L, 100L, 9L, "operator", "key-1",
             new TransportUpdateRequest("   ", "023E", 3, "清空测试")))
-            .isInstanceOf(BizException.class).hasMessageContaining("ISO 6346");
+            .isInstanceOf(BizException.class).hasMessageContaining("不能为空");
         verify(repository, never()).updateTransport(eq(10L), eq(3),
             org.mockito.ArgumentMatchers.nullable(String.class),
             org.mockito.ArgumentMatchers.nullable(String.class), eq(9L),

firstleg/src/test/java/com/baiyue/firstleg/service/LoadingPickServiceTest.java

@@ -50,6 +50,9 @@ import org.mockito.InOrder;
 import org.mockito.ArgumentCaptor;
 import org.springframework.boot.test.mock.mockito.MockBean;
 import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.context.event.RecordApplicationEvents;
+import org.springframework.test.context.event.ApplicationEvents;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.transaction.TransactionStatus;
 import org.springframework.transaction.support.TransactionTemplate;
 
@@ -77,7 +80,9 @@ import static org.mockito.Mockito.clearInvocations;
 import static org.assertj.core.api.Assertions.assertThat;
 
 @SpringJUnitConfig(LoadingPickService.class)
+@RecordApplicationEvents
 class LoadingPickServiceTest {
+    @Autowired private ApplicationEvents completionEvents;
     @MockBean
     private LoadingPickRepository repository;
     @MockBean
@@ -154,6 +159,8 @@ class LoadingPickServiceTest {
         when(repository.activeBookingByTask(20L)).thenReturn(booking);
         when(completionCommands.insert(any())).thenReturn(1);
         when(completionCommands.renew(anyLong(), anyString(), any(java.time.LocalDateTime.class))).thenReturn(true);
+        when(completionCommands.checkpoint(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString()))
+            .thenReturn(true);
         when(repository.acceptCompletion(anyLong(), anyInt())).thenReturn(1);
         when(repository.inboundOwners(anyLong())).thenReturn(List.of(
             new LoadingPickItemMapper.InboundOwner(101L, 50L)));
@@ -220,7 +227,7 @@ class LoadingPickServiceTest {
         Link link = new Link(1L, 1L, 50L, 2L, "PENDING", 1,
             10L, 40L, "MSCU-001", "EDITING", 3, 2, null);
         var booking = new com.baiyue.firstleg.entity.ContainerBookingEntity();
-        booking.setId(40L); booking.setContainerNo("MSCU-001");
+        booking.setId(40L); booking.setContainerNo("MSCU6639870");
         var allocation = new OceanBookingContainerAllocationEntity();
         allocation.setOceanBookingId(90L);
         var ocean = new OceanBookingEntity();
@@ -931,6 +938,7 @@ class LoadingPickServiceTest {
         assertThat(replay.taskStatus()).isEqualTo("COMPLETING");
         verify(repository, never()).taskForUpdate(20L);
         verify(completionCommands, times(1)).insert(any());
+        assertThat(completionEvents.stream(LoadingPickService.CompletionAccepted.class).count()).isEqualTo(1);
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
     }
@@ -954,6 +962,82 @@ class LoadingPickServiceTest {
         verify(repository, never()).acceptCompletion(anyLong(), anyInt());
     }
 
+    /** 关联接受的非 ISO 柜号可直接确认预装，保留订舱放舱门禁。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void acceptsNonIsoNumberBeforeConfirmation(String containerNo) {
+        Link link = new Link(1L, 1L, 50L, 2L, "PENDING", 1,
+            10L, 40L, containerNo, "EDITING", 3, 2, null);
+        var booking = new ContainerBookingEntity();
+        booking.setId(40L);
+        booking.setContainerNo(containerNo);
+        when(loadingModelBridge.requireAllocatedLinksForConfirmation(10L)).thenReturn(List.of(link));
+        when(smartLoadingRepository.booking(40L)).thenReturn(booking);
+
+        var allocation = new OceanBookingContainerAllocationEntity();
+        allocation.setOceanBookingId(90L);
+        var ocean = new OceanBookingEntity();
+        ocean.setId(90L);
+        ocean.setStatus("RELEASED");
+        when(oceanBookingRepository.allocationByContainer(40L)).thenReturn(allocation);
+        when(oceanBookingRepository.find(90L)).thenReturn(ocean);
+        assertThat(service.requirePreloadConfirmationReady(10L)).containsExactly(link);
+    }
+
+    /** 非 ISO 柜号可以创建 PDA 任务，任务仍按柜次关联权威柜号。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void createsPdaTaskWithNonIsoNumber(String containerNo) {
+        var plan = new com.baiyue.firstleg.entity.LoadingPlanEntity();
+        plan.setId(10L); plan.setContainerBookingId(40L);
+        var booking = new ContainerBookingEntity();
+        booking.setId(40L); booking.setContainerNo(containerNo); booking.setCabinetNo("D2092");
+        when(smartLoadingRepository.plan(10L)).thenReturn(plan);
+        when(smartLoadingRepository.booking(40L)).thenReturn(booking);
+        doAnswer(invocation -> {
+            LoadingPickTaskEntity created = invocation.getArgument(0);
+            created.setId(20L);
+            return 1;
+        }).when(repository).insert(any(LoadingPickTaskEntity.class));
+
+        service.begin(10L, containerNo, 9L, "operator", List.of());
+
+        ArgumentCaptor<LoadingPickTaskEntity> captured = ArgumentCaptor.forClass(LoadingPickTaskEntity.class);
+        verify(repository).insert(captured.capture());
+        assertThat(captured.getValue().getContainerBookingId()).isEqualTo(40L);
+        assertThat(captured.getValue().getTaskStatus()).isEqualTo("LOADING");
+    }
+
+    /** 去除 ISO 校验不应放开缺号任务。 */
+    @ParameterizedTest
+    @org.junit.jupiter.params.provider.NullAndEmptySource
+    @ValueSource(strings = {"   ", "\u00a0\u3000"})
+    void rejectsMissingNumberBeforeCreatingPdaTask(String containerNo) {
+        assertThatThrownBy(() -> service.begin(10L, containerNo, 9L, "operator", List.of()))
+            .isInstanceOf(BizException.class).hasMessageContaining("录入真实集装箱号");
+        verify(repository, never()).insert(any(LoadingPickTaskEntity.class));
+    }
+
+    /** 非 ISO 柜号不会在完成阶段再次受阻，仍通过持久化命令结算。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"JZXH10231043", "MSCU6639871", "ABC", "ABCU123456789012", "LOCAL-2026-001"})
+    void completionAcceptsNonIsoNumberForCrossServiceFacts(String containerNo) {
+        repository.activeBookingByTask(20L).setContainerNo(containerNo);
+        when(repository.taskForUpdate(20L)).thenReturn(task());
+        LoadingPickTaskEntity completing = task();
+        completing.setTaskStatus("COMPLETING");
+        completing.setVersion(1);
+        when(repository.task(20L)).thenReturn(completing);
+        when(repository.allTaskItemsResolved(20L)).thenReturn(true);
+
+        Task result = service.complete(20L,
+            new CompleteLoadingRequest(0, "complete-non-iso", "checked"), 9L, "operator");
+
+        assertThat(result.taskStatus()).isEqualTo("COMPLETING");
+        verify(completionCommands).insert(any());
+        verify(repository).acceptCompletion(20L, 0);
+    }
+
     @Test
     void differentOperationIdIsRejectedImmediatelyWithConflict() {
         // different operationId is a canonical A0409 CONFLICT while the durable command is active.
@@ -997,6 +1081,8 @@ class LoadingPickServiceTest {
 
         assertThat(result.workflowStatus()).isEqualTo("PROCESSING");
         verify(completionCommands).resume(902L);
+        assertThat(completionEvents.stream(LoadingPickService.CompletionAccepted.class)
+            .map(LoadingPickService.CompletionAccepted::commandId)).containsExactly(902L);
         verify(repository).resumeCompletion(20L);
         verify(completionCommands, never()).insert(any());
     }
@@ -1089,7 +1175,7 @@ class LoadingPickServiceTest {
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(), anyString(), anyString(), anyString());
         verify(completionCommands, never()).checkpoint(eq(931L), eq(303L), eq(70L));
-        verify(completionCommands, never()).checkpoint(eq(931L), anyLong(), anyLong(), anyInt(), anyString());
+        verify(completionCommands, never()).checkpoint(eq(931L), anyString(), anyLong(), anyLong(), anyInt(), anyString());
         verify(loadingListService).publishCompletedEvent(10L);
         verify(completionCommands).complete(931L, "worker-completed-checkpoints");
     }
@@ -1109,6 +1195,31 @@ class LoadingPickServiceTest {
         verify(loadingListService, never()).publishCompletedEvent(anyLong());
     }
 
+    /** 任一检查点被租约拒绝后都不得继续下一业务步骤或最终完成柜次。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"READY", "SETTLED", "INBOUND_COMPLETED"})
+    void lostLeaseAtCheckpointStopsFurtherCompletion(String rejectedStage) {
+        LoadingPickTaskEntity completing = task();
+        completing.setTaskStatus("COMPLETING");
+        when(repository.task(20L)).thenReturn(completing);
+        when(completionCommands.checkpoint(eq(940L), eq("old-owner"), eq(101L), eq(50L), eq(1), eq(rejectedStage)))
+            .thenReturn(false);
+
+        assertThatThrownBy(() -> service.processCompletion(completionCommand(940L, "lost-checkpoint"), "old-owner"))
+            .isInstanceOf(LoadingPickService.CompletionProcessingException.class)
+            .satisfies(error -> assertThat(((LoadingPickService.CompletionProcessingException) error).stage())
+                .isEqualTo("LEASE_LOST"));
+        if ("READY".equals(rejectedStage)) {
+            verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
+        }
+        if (!"INBOUND_COMPLETED".equals(rejectedStage)) {
+            verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(),
+                anyString(), anyString(), anyString());
+        }
+        verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
+        verify(completionCommands, never()).complete(anyLong(), anyString());
+    }
+
     @Test
     void anEntirelySkippedTaskCannotCreateACompletionCommand() {
         when(repository.taskForUpdate(20L)).thenReturn(task());
@@ -1271,8 +1382,8 @@ class LoadingPickServiceTest {
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(),
             anyString(), anyString(), anyString());
-        verify(completionCommands).checkpoint(904L, 101L, 50L, 1, "READY");
-        verify(completionCommands, never()).checkpoint(eq(904L), anyLong(), anyLong(), anyInt(),
+        verify(completionCommands).checkpoint(904L, "worker-failure", 101L, 50L, 1, "READY");
+        verify(completionCommands, never()).checkpoint(eq(904L), anyString(), anyLong(), anyLong(), anyInt(),
             eq("SETTLED"));
         verify(repository, never()).insert(any(LoadingPickOperationEntity.class));
         verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
@@ -1300,7 +1411,7 @@ class LoadingPickServiceTest {
         verify(settlementService, never()).settleOwner(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingDeliveryService, never()).completeAfterPdaSettlement(anyLong(), anyLong(), anyLong(),
             anyString(), anyString(), anyString());
-        verify(completionCommands, never()).checkpoint(anyLong(), anyLong(), anyLong(), anyInt(), anyString());
+        verify(completionCommands, never()).checkpoint(anyLong(), anyString(), anyLong(), anyLong(), anyInt(), anyString());
         verify(repository, never()).insert(any(LoadingPickOperationEntity.class));
         verify(loadingListService, never()).finishFromPda(anyLong(), anyLong(), anyLong(), anyString());
         verify(loadingListService, never()).publishCompletedEvent(anyLong());

firstleg/src/test/java/com/baiyue/firstleg/service/MerchantInboundBillingServiceTest.java

@@ -36,8 +36,9 @@ class MerchantInboundBillingServiceTest {
     @MockBean private InboundFeeDetailService feeDetails;
     @Resource private MerchantInboundBillingService service;
 
+    /** 测量审核通过并发送费用后，待组托与后续履约阶段均可查看客户费用。 */
     @ParameterizedTest
-    @ValueSource(strings = {"WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"})
+    @ValueSource(strings = {"WAIT_PALLETIZE", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED"})
     void shouldKeepPublishedBillingVisibleAfterFulfillmentProgresses(String processStatus) {
         InboundOrderEntity inbound = inbound(processStatus, "APPROVED", "SENT");
         InboundOrderDetail detail = new InboundOrderDetail(mock(com.baiyue.firstleg.dto.InboundOrderSummary.class),
@@ -84,9 +85,11 @@ class MerchantInboundBillingServiceTest {
         verify(orders).findByOrderId(10001L, 77L);
     }
 
-    @Test
-    void shouldHandleCase02() {
-        InboundOrderEntity inbound = inbound("WAIT_SPLIT", "PENDING", "SENT");
+    /** 待组托不绕过客户费用可见性的测量审核条件。 */
+    @ParameterizedTest
+    @ValueSource(strings = {"WAIT_PALLETIZE", "WAIT_SPLIT"})
+    void shouldHandleCase02(String processStatus) {
+        InboundOrderEntity inbound = inbound(processStatus, "PENDING", "SENT");
         when(orders.findByOrderId(10001L, 77L)).thenReturn(inbound);
 
         assertThatThrownBy(() -> service.find(10001L, 77L))
@@ -105,6 +108,19 @@ class MerchantInboundBillingServiceTest {
         verify(pricing, never()).latest(20002L, 88L);
     }
 
+    /** 客户可在组托前确认已审核并发送的费用，继续使用当前费用版本和幂等键。 */
+    @Test
+    void confirmsPublishedFeeWhileWaitingForPalletization() {
+        when(orders.findByOrderId(10001L, 77L)).thenReturn(inbound("WAIT_PALLETIZE", "APPROVED", "SENT"));
+        FeeSnapshotResponse fee = mock(FeeSnapshotResponse.class);
+        when(pricing.confirmByCustomer(10001L, 7L, "客户成员", 88L, 3, "confirm-palletize"))
+            .thenReturn(fee);
+
+        assertThat(service.confirmFee(10001L, 7L, "客户成员", 77L, 3, "confirm-palletize"))
+            .isSameAs(fee);
+        verify(pricing).confirmByCustomer(10001L, 7L, "客户成员", 88L, 3, "confirm-palletize");
+    }
+
     @Test
     void shouldHandleCase04() {
         InboundOrderEntity inbound = inbound("WAIT_SPLIT", "APPROVED", "SENT");

firstleg/src/test/java/com/baiyue/firstleg/service/TruckAppointmentServiceTest.java

@@ -84,7 +84,7 @@ class TruckAppointmentServiceTest {
     }
 
     @Test void createCandidatesDelegateOneBoundedAuthoritativeQuery() {
-        Candidate candidate = new Candidate(99L, "OB-1", "BL-1", 18L, "义乌仓", "SEA-US", "美西", true);
+        Candidate candidate = new Candidate(99L, "OB-1", "BL-1", 18L, "义乌仓", "SEA-US", "美西");
         when(repository.candidates(any())).thenReturn(new PageResult<>(List.of(candidate), 1, 20, 1, 1));
 
         PageResult<Candidate> result = service.candidates(new CandidateQuery(" OB-1 ", 1, 20));
@@ -170,7 +170,8 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).insert(any());
     }
 
-    @Test void createFreezesBookingBillAndRequiresBookingOwnedDocument() {
+    /** 无附件订舱可创建预约，提单号仍取订舱冻结值。 */
+    @Test void createFreezesBookingBillWithoutRequiringBookingDocument() {
         SaveRequest request = validRequest();
 
         service.create(7L, "admin", request);
@@ -178,7 +179,7 @@ class TruckAppointmentServiceTest {
         ArgumentCaptor<TruckAppointmentEntity> entity = ArgumentCaptor.forClass(TruckAppointmentEntity.class);
         verify(repository).insert(entity.capture());
         assertThat(entity.getValue().getBillOfLadingNo()).isEqualTo("BL-BOOKING-1");
-        verify(oceanBookingDocuments).requireActiveValidDocument(any(OceanBookingEntity.class));
+        verifyNoInteractions(oceanBookingDocuments);
         verifyNoInteractions(files);
     }
 
@@ -307,14 +308,14 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).insert(any());
     }
 
-    @Test void createStillRequiresBookingDocumentWithoutAnyContainerAssociation() {
+    /** 没有附件或货柜关联时，完整已放舱订舱仍可预约。 */
+    @Test void createAllowsBookingWithoutDocumentsOrContainerAssociation() {
         SaveRequest request = validRequest();
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
-            "订舱缺少有效订舱确认或提单文件"))
-            .when(oceanBookingDocuments).requireActiveValidDocument(any());
-        assertThatThrownBy(() -> service.create(7L, "admin", request))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
-        verify(repository, never()).insert(any());
+        TruckAppointmentEntity result = service.create(7L, "admin", request);
+        assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.DRAFT);
+        assertThat(result.getContainerBookingId()).isNull();
+        verify(repository).insert(any());
+        verifyNoInteractions(oceanBookingDocuments);
     }
 
     @Test void editCanSwitchToAnotherUnoccupiedReleasedBooking() {
@@ -407,7 +408,8 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).history(any());
     }
 
-    @Test void dispatchRequiresBookingBillAndActiveBookingOwnedDocument() {
+    /** 取消附件要求后，派车仍必须具备提单号。 */
+    @Test void dispatchRequiresBookingBill() {
         TruckAppointmentEntity missingBill = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
         missingBill.setOceanBookingId(99L); missingBill.setContainerBookingId(88L);
         OceanBookingEntity bookingWithoutBill = releasedBooking(); bookingWithoutBill.setBillOfLadingNo(null);
@@ -419,21 +421,11 @@ class TruckAppointmentServiceTest {
             "dispatch-no-bill", null, 7L, "admin"))
             .isInstanceOf(BizException.class).hasMessageContaining("提单号");
 
-        TruckAppointmentEntity missingAttachment = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
-        missingAttachment.setOceanBookingId(99L); missingAttachment.setContainerBookingId(88L); missingAttachment.setBillOfLadingNo("BL-BOOKING-1");
-        when(oceanBookings.find(99L)).thenReturn(releasedBooking());
-        when(repository.claimOperation(anyLong(), eq(1L), eq("DISPATCH"), eq("dispatch-no-file"), anyString())).thenReturn(true);
-        when(repository.find(1L)).thenReturn(missingAttachment);
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,"订舱缺少有效订舱确认或提单文件"))
-            .when(oceanBookingDocuments).requireActiveValidDocument(any());
-
-        assertThatThrownBy(() -> service.action(1L, "DISPATCH", new ActionRequest(1, null),
-            "dispatch-no-file", null, 7L, "admin"))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
         verify(repository, never()).dispatch(anyLong(), anyString(), anyString(), anyInt());
     }
 
-    @Test void dispatchFreezesReleasedBookingBillWithoutRequiringRealContainerNumber() {
+    /** 无附件、无真实柜号时可派车，但仍冻结已放舱订舱的提单号并记历史。 */
+    @Test void dispatchFreezesReleasedBookingBillWithoutRequiringDocumentsOrRealContainerNumber() {
         TruckAppointmentEntity before = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
         before.setOceanBookingId(99L); before.setContainerBookingId(88L); before.setBillOfLadingNo(null);
         TruckAppointmentEntity after = entity(TruckAppointmentStatus.DISPATCHED, 2);
@@ -452,6 +444,7 @@ class TruckAppointmentServiceTest {
         assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.DISPATCHED);
         assertThat(result.getBillOfLadingNo()).isEqualTo("BL-BOOKING-1");
         verify(repository).dispatch(1L, "PENDING_DISPATCH", "BL-BOOKING-1", 1);
+        verifyNoInteractions(oceanBookingDocuments);
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt());
         verify(repository).history(any(TruckAppointmentHistoryEntity.class));
     }

firstleg/src/test/java/com/baiyue/firstleg/terminaldrayage/mapper/ContainerCalendarSourceMapperTest.java

@@ -11,6 +11,41 @@ import java.time.LocalDateTime;
 import static org.junit.jupiter.api.Assertions.*;
 
 class ContainerCalendarSourceMapperTest {
+    /** 两个日历来源入口均优先展示港口名称，仅填代码时仍可回显，缺失时保持空值。 */
+    @Test
+    void displaysDestinationNameOrSavedCodeAcrossBothEntrypoints() throws Exception {
+        var ds = new JdbcDataSource();
+        ds.setURL("jdbc:h2:mem:calendar-port-display;MODE=MySQL;DB_CLOSE_DELAY=-1");
+        try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
+            sql.execute("CREATE TABLE fl_container_booking(id BIGINT,cabinet_no VARCHAR,container_no VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_port_code VARCHAR,destination_warehouse_code VARCHAR," +
+                "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
+            sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_carrier_schedule_node_fact(id BIGINT,container_booking_id BIGINT,standard_node VARCHAR,actual_at TIMESTAMP,observed_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_direct_delivery_unloading(container_booking_id BIGINT,actual_at TIMESTAMP)");
+            sql.execute("CREATE TABLE fl_outbound_dispatch(container_booking_id BIGINT,confirmed_at TIMESTAMP,reversed_at TIMESTAMP,status VARCHAR)");
+            sql.execute("INSERT INTO fl_container_booking(id,destination_port_name,destination_port_code,record_status) VALUES " +
+                "(1,'洛杉矶','USLAX','ACTIVE'),(2,NULL,'USLAX','ACTIVE'),(3,'   ','USLAX','ACTIVE')," +
+                "(4,'洛杉矶',NULL,'ACTIVE'),(5,'','   ','ACTIVE')");
+            sql.execute("INSERT INTO fl_outbound_dispatch SELECT id,'2026-10-01 00:00:00',NULL,'WAITING_FOR_LOADING' FROM fl_container_booking");
+        }
+        var config = new MybatisConfiguration();
+        config.setEnvironment(new Environment("test", new JdbcTransactionFactory(), ds));
+        config.addMapper(ContainerCalendarSourceMapper.class);
+        try (var session = new MybatisSqlSessionFactoryBuilder().build(config).openSession()) {
+            var mapper = session.getMapper(ContainerCalendarSourceMapper.class);
+            var from = LocalDateTime.parse("2026-10-01T00:00:00");
+            var calendar = mapper.sources(from, from.minusDays(2), from.minusDays(4), from.plusMonths(1));
+            var explicit = mapper.byIds(java.util.List.of(1L, 2L, 3L, 4L, 5L));
+            var expected = java.util.Arrays.asList("洛杉矶", "USLAX", "USLAX", "洛杉矶", null);
+            assertEquals(expected, calendar.stream().map(row -> row.destinationPortName()).toList());
+            for (var row : explicit) {
+                assertEquals(expected.get(row.containerBookingId().intValue() - 1), row.destinationPortName());
+            }
+            assertEquals(5, explicit.size());
+        }
+    }
+
     /** 后续观测可将实际到港修正为更早日期，两入口须取同一条最新实际记录。 */
     @Test
     void usesLatestObservedArrivalIncludingSameObservationIdTieBreakAcrossBothEntrypoints() throws Exception {
@@ -18,7 +53,7 @@ class ContainerCalendarSourceMapperTest {
         ds.setURL("jdbc:h2:mem:arrival-source-correction;MODE=MySQL;DB_CLOSE_DELAY=-1");
         try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
             sql.execute("CREATE TABLE fl_container_booking(id BIGINT PRIMARY KEY,cabinet_no VARCHAR,container_no VARCHAR," +
-                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_warehouse_code VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_port_code VARCHAR,destination_warehouse_code VARCHAR," +
                 "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
             sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
             sql.execute("CREATE TABLE fl_carrier_schedule_query(id BIGINT,version INT,status VARCHAR)");
@@ -46,6 +81,8 @@ class ContainerCalendarSourceMapperTest {
             var calendar = session.getMapper(ContainerCalendarSourceMapper.class).sources(from, from.minusDays(2), from.minusDays(4), from.plusMonths(1));
             var workbench = session.getMapper(CarrierScheduleQueryMapper.class).selectContainerActualFacts(java.util.List.of(1L, 2L));
             assertEquals(2, calendar.size());
+            var explicit = session.getMapper(ContainerCalendarSourceMapper.class).byIds(java.util.List.of(1L,2L));
+            assertEquals(calendar,explicit);
             assertEquals(2, workbench.size());
             for (int index = 0; index < calendar.size(); index++) {
                 var expected = LocalDateTime.parse(index == 0 ? "2026-10-21T14:00:00" : "2026-10-22T14:00:00");
@@ -63,7 +100,7 @@ class ContainerCalendarSourceMapperTest {
         ds.setURL("jdbc:h2:mem:four-type-calendar;MODE=MySQL;DB_CLOSE_DELAY=-1");
         try (var connection = ds.getConnection(); var sql = connection.createStatement()) {
             sql.execute("CREATE TABLE fl_container_booking(id BIGINT,cabinet_no VARCHAR,container_no VARCHAR," +
-                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_warehouse_code VARCHAR," +
+                "vessel_name VARCHAR,voyage_no VARCHAR,destination_port_name VARCHAR,destination_port_code VARCHAR,destination_warehouse_code VARCHAR," +
                 "actual_port_arrival_at TIMESTAMP,estimated_port_arrival_at TIMESTAMP,unloading_completed_at TIMESTAMP,record_status VARCHAR)");
             sql.execute("CREATE TABLE fl_terminal_drayage(container_booking_id BIGINT,actual_empty_return_at TIMESTAMP)");
             sql.execute("CREATE TABLE fl_carrier_schedule_node_fact(id BIGINT,container_booking_id BIGINT,standard_node VARCHAR,actual_at TIMESTAMP,observed_at TIMESTAMP)");

firstleg/src/test/java/com/baiyue/firstleg/workflow/WorkflowBoundaryTest.java

@@ -36,8 +36,8 @@ class WorkflowBoundaryTest {
         assertThatThrownBy(()->service.rows(List.of(inbound))).isInstanceOf(BizException.class).hasCause(failure);
     }
 
-    /** 未记录离港时，报关完成即可待清关；上传清关资料后也必须查询精确海外来源。 */
-    @Test void completedCustomsAndClearanceUploadDoNotWaitForDeparture() {
+    /** 报关完成或提前上传资料仍留在出口报关，实际开船后才查询精确海外来源。 */
+    @Test void completedCustomsAndClearanceUploadWaitForActualDeparture() {
         var repository=mock(WorkflowFactRepository.class);
         var downstream=mock(LastlegWorkflowClient.class);
         var service=new WorkflowTabService(repository,downstream);
@@ -45,12 +45,21 @@ class WorkflowBoundaryTest {
         inbound.setOrderId(101L);inbound.setProcessStatus("LOADED");
         when(repository.facts(List.of(1L))).thenReturn(List.of(
             new WorkflowFacts.Fact(11,1,101,"APPROVED",false,false,false,true,true)));
-        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("SAILING_CLEARANCE");
+        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("EXPORT_CUSTOMS");
         verifyNoInteractions(downstream);
         when(repository.facts(List.of(1L))).thenReturn(List.of(
             new WorkflowFacts.Fact(11,1,101,"APPROVED",false,true,false,true,true)));
+        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("EXPORT_CUSTOMS");
+        verifyNoInteractions(downstream);
+        when(repository.facts(List.of(1L))).thenReturn(List.of(
+            new WorkflowFacts.Fact(11,1,101,"APPROVED",true,false,false,true,true)));
         when(downstream.read(any(),any())).thenReturn(ApiResponse.success(List.of(
             new WorkflowFacts.Overseas(11,1,false,false,false,false))));
+        assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("SAILING_CLEARANCE");
+        verify(downstream).read(any(),eq(new WorkflowFacts.Request(List.of(new WorkflowFacts.Source(11,1)))));
+        clearInvocations(downstream);
+        when(repository.facts(List.of(1L))).thenReturn(List.of(
+            new WorkflowFacts.Fact(11,1,101,"APPROVED",true,true,false,true,true)));
         assertThat(service.rows(List.of(inbound))).extracting(r->r.mainStatus()).containsExactly("WAIT_UNLOAD","WAIT_DISPATCH");
         verify(downstream).read(any(),eq(new WorkflowFacts.Request(List.of(new WorkflowFacts.Source(11,1)))));
     }

firstleg/src/test/java/com/baiyue/firstleg/workflow/WorkflowBusinessTest.java

@@ -3,7 +3,7 @@ import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.*;
 /** 取消回显、分柜隔离和资料页签回归。 */
 class WorkflowBusinessTest {
-    /** 报关完成进入待清关，清关资料保存后才进入拆柜与排车待办。 */
+    /** 实际开船前保留出口报关，实际开船后再按清关资料进入海外待办。 */
     @Test void customsDocumentsDepartureAndClearanceDriveTabs() {
         var missing=new WorkflowFacts.Fact(11,1,101,"APPROVED",false,false,true,false,false);
         var uploaded=new WorkflowFacts.Fact(11,1,101,"APPROVED",false,false,false,true,false);
@@ -18,9 +18,9 @@ class WorkflowBusinessTest {
         assertThat(WorkflowTabService.classify(uploaded,"LOADED",null))
             .contains("EXPORT_CUSTOMS").doesNotContain("WAIT_CUSTOMS_DOCS","SAILING_CLEARANCE","WAIT_UNLOAD");
         assertThat(WorkflowTabService.classify(completed,"LOADED",null))
-            .containsExactly("SAILING_CLEARANCE");
+            .containsExactly("EXPORT_CUSTOMS");
         assertThat(WorkflowTabService.classify(uploadedBeforeDeparture,"LOADED",pendingUnload))
-            .containsExactly("WAIT_UNLOAD","WAIT_DISPATCH");
+            .containsExactly("EXPORT_CUSTOMS");
         assertThat(WorkflowTabService.classify(departed,"LOADED",pendingUnload))
             .containsExactly("SAILING_CLEARANCE");
         assertThat(WorkflowTabService.classify(cleared,"LOADED",pendingUnload))

lastleg-service/AGENTS.md

@@ -56,6 +56,7 @@
 | 贴标申请、箱唛/SKU/组合换标与 PDA 完工 | `relabel/` |
 | PDA 仓内通用扫码与操作历史 | `pda/warehouse/controller/PdaWarehouseController.java` |
 | 船节点接收与海外 PDA 可收货门禁 | `shipping/service/ContainerShippingNodeConsumer.java` |
+| 内部散板需求只读来源 | `dispatch/service/DispatchCapacityDemandService.java`、`DispatchQueryController.java`的`/dispatches/capacity-demands`；发布字段仅随智能排车创建保存且缺省不发布，编辑命令不接收该字段；重发须按原门禁取消排车再重新创建，当前业务口径见拼车主契约，不恢复旧车次人工发布入口 |
 | 平台排车查询、整车四块详情、审核与实载 | `dispatch/controller/DispatchQueryController.java`、`DispatchAggregateController.java`；公开契约`dispatch/port/`，业务规则见`../../docs/海外仓业务/排车列表统一作业改造契约.md` |
 | 草稿、双端装车发运 | `dispatch/controller/SmartDispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`；平台维护`DispatchController.java`；自动发运编排`dispatch/service/DispatchLoadingDepartureService.java` |
 | 仓储资源调用 | `inboundplan/pda/gateway/WarehouseResourceGateway.java` |
@@ -77,7 +78,7 @@
 | 整车调度与理货审核 | `dispatch/controller/DispatchAggregateController.java` → `dispatch/service/DispatchAggregateService.java` 的提交及两级审核；同一排车先调度审核、再理货审核，通过后才允许真实扫码。资源、货物或路线关键变更使原依据失效；零扫码显式退回后重新审核，不复用旧客户子单审核状态 |
 | 外接询价、确认占位及取消 | `fleet/trip/PlatformFleetBookingController.java`、`FleetBookingService.java`、`FleetBookingReservations.java`；客户从`fleet/customer/`读取IAM有效主档与资格，询价不占位，确认后与自有货计划共同校验逐段容量。约定金额不代表应收/实收，`FleetBookingIncomingGateway`由`transfer/fleet/FleetIncomingAdapter`实现来货登记/实收确认，排车关联通过`FleetDispatchGateway.sourceCargo`核对实收来源 |
 | 拣货前计划容量与逐段余位 | `FleetTripExecutionService.capacityPlan/confirmCapacityPlan`、`/fleet/trips/{tripNo}/capacity-plan`；保存自有货的计划值，不检查拣货完成、不推进审核或扣库存；`planValid`校验当前货物hash，不把计划值当实测值，资源/计划/关联变更后须重新核对 |
-| 实物装载、逐段容量与双端整车发车 | 两端`dispatches/{dispatchNo}/loading-complete`统一调用`dispatch/service/DispatchLoadingDepartureService.java`，同一事务复用实载确认、派送单准备及发车，成功直接`DELIVERING`；请求携带唯一`recordVersion`，原键恢复最终结果。公开手工安排派送、`/depart`入口已移除；内部`AFTER_LOADING`和步骤命令只用于事务编排。真实PDA拣货须核平，不重复库存SHIP，Fleet容量和资源资格仍复核；未知费用不补零、不阻塞发运，真实已明确外接报价沿原费用来源防重 |
+| 实物装载、逐段容量与双端整车发车 | 两端`dispatches/{dispatchNo}/loading-complete`统一调用`dispatch/service/DispatchLoadingDepartureService.java`，实载确认成功进入`AFTER_LOADING`；请求携带唯一`recordVersion`，原键恢复原装车后结果。`dispatch/service/DispatchLoadingDocumentService.java`复用整车附加照片与账本，平台/PDA均经`loading-documents`保存；五框齐全的最后一次绑定与派送准备、发车同事务，成功`DELIVERING`。公开手工安排派送、`/depart`入口仍不开放。真实PDA拣货须核平，不重复库存SHIP，Fleet容量和资源资格仍复核；未知费用不补零、不阻塞发运，真实已明确外接报价沿原费用来源防重 |
 | 车次货物结案、车辆和司机分别释放 | `fleet/trip/FleetTripCompletionService.java`、`FleetCompletionModels.java`；平台 `/fleet/trips/{tripNo}/completion`、`/complete`、`/resources/release`，独立complete/release权限。结案核对所有派送终态与实发数量；实际任务结束时间/地点及车辆结束状态单独记录，不以结案或收款自动释放资源 |
 | 跨服务 HTTP 客户端装配 | `config/LastlegRestClientFactory.java` |
 | 数据库基线、表索引与中文注释契约 | `src/main/resources/db/lastleg.sql` |

lastleg-service/docs/business-index.md

@@ -7,8 +7,8 @@
 退货预报、签收、库存、合箱与退货出库：
 
 - 客户预报 `returnreceipt/controller/MerchantReturnOrderController.java` → `returnreceipt/service/ReturnReceiptService.java`，路径 `/api/merchant/v1/last-leg/return-orders`；客户范围取认证身份，预报按 SKU 保存期望数量。状态 `PENDING_RECEIPT → PARTIALLY_RECEIVED → COMPLETED` 表示签收进度，不等于换标或出库完成。
-- PDA 后端签收 `returnreceipt/controller/PdaReturnReceiptController.java`，前缀 `/api/pda/v1/last-leg/return-receipts`，依次 `start/sku-candidates/confirm`；按冻结仓和退货单校验实收，不允许未预报 SKU 或超量，幂等重放不得重复入账。确认同时生成签收箱与 SKU 库存；设备页面是否接通另查 PDA 工作台，不能以 Controller 存在代替前端接入。
-- 库存/箱号 `returnreceipt/controller/PlatformReturnInventoryController.java`、`MerchantReturnInventoryController.java` → `returnreceipt/service/ReturnInventoryService.java`，前缀分别为 `/api/platform/v1/last-leg/return-inventory`、`/api/merchant/v1/last-leg/return-inventory`；PDA 合箱入口 `PdaReturnInventoryController.java` 的 `/packing/orders`、`/cartons/merge`、`/cartons/{cartonMark}/label`。同仓同客户选取退货单及可用 SKU，合箱扣减来源箱数量并生成目标箱，空来源箱标为 `MERGED`，不得跨客户或超出可用量。
+- PDA 后端签收 `returnreceipt/controller/PdaReturnReceiptController.java`，前缀 `/api/pda/v1/last-leg/return-receipts`，依次 `start/sku-candidates/confirm`；按冻结仓和退货单校验实收，不允许未预报 SKU 或超量。确认必须传提交前全单累计实收量 `expectedReceivedQuantity`，在订单锁内校验；响应丢失后换新键重复提交旧快照返回冲突，刷新后重新操作，同键幂等请求不得重复入账。确认同时生成签收箱与 SKU 库存；设备页面是否接通另查 PDA 工作台，不能以 Controller 存在代替前端接入。
+- 库存/箱号 `returnreceipt/controller/PlatformReturnInventoryController.java`、`MerchantReturnInventoryController.java` → `returnreceipt/service/ReturnInventoryService.java`，前缀分别为 `/api/platform/v1/last-leg/return-inventory`、`/api/merchant/v1/last-leg/return-inventory`；PDA 合箱入口 `PdaReturnInventoryController.java` 的 `/packing/orders`、`/cartons/merge`、`/cartons/{cartonMark}/label`。同仓同客户选取退货单及可用 SKU，合箱扣减来源箱数量并生成目标箱，空来源箱标为 `MERGED`，不得跨客户或超出可用量。实物合箱 `/cartons/merge-boxes` 必须提交扫码时全部来源箱 SKU 数量 `expectedSourceQuantities`，来源行锁内核对完整快照；旧快照换新键也拒绝扣减，重新扫描后才能提交当前实物。内部退货换标调用从已锁定任务及来源库存生成快照。
 - 退货出库继续进入 `delivery/service/DeliveryTransferService.java` 的 `RETURN_OUTBOUND`，按退货库存可用箱唛创建与拣货；不能与 `exceptionorder/` 的派送退回恢复库存混用。契约见 `src/main/resources/openapi/overseas-business-v1.yaml`，表入口 `src/main/resources/db/lastleg.sql` 的 `ll_return_*`。
 - 客户箱号管理使用 `GET /api/merchant/v1/last-leg/return-inventory/cartons` 按实物箱分页，库存箱内 SKU 明细仍使用根查询；两者均按登录客户精确隔离。合箱 `sourceBatchNo/sourceReturnNo` 保存实际消耗来源的去重业务编号（多个以逗号分隔），不得写状态或包含未取货订单。`ReturnCartonBarcode` 按箱号生成 Code 128 SVG，打印内容不得使用内部客户/仓库 ID。
 
@@ -22,10 +22,10 @@
 |---|---|
 | 内部模块化基线与依赖分析 | `docs/lastleg-internal-modularization-baseline.md`、`scripts/analyze-lastleg-dependencies.mjs`、`scripts/analyze-lastleg-dependencies.test.mjs`、`src/test/resources/architecture/lastleg-slice-dependencies.json`；只约束本服务内部包依赖，不改变部署单元或数据库边界 |
 | 事件接收、平台订单列表/详情、柜级进度、目的仓调整 | `src/main/java/com/baiyue/lastleg/controller/LastlegOrderController.java`；`/api/platform/v1/last-leg/orders/container-summaries` 按 `sourceContainerBookingId` 服务端聚合全柜订单、入仓码、有效计划及托盘资源异常并分页返回全部稳定来源柜，已完成计划转换的柜仍保留用于接柜仓查询与修改；单票手工计划保存后，整柜最后一票齐全时自动生成并绑定全柜托盘码，一票柜立即生成，`resourcePendingPlanCount` 只作为失败重试事实；`/{sourceContainerBookingId}` 返回柜内全部订单/入仓码/计划状态且不受订单分页截断；`plannedArrivalAt` 只取装柜完成事件 `estimatedWarehouseArrivalAt` 冻结到 `ll_order.estimated_warehouse_at` 的正式事实，按其升序、null 最后、稳定柜 ID 排序；目的仓调整仅接受国内 Warehouse Service 平台公共 `ACTIVE + FBA` 主档，写入前由 `service/FbaWarehouseValidator.java` 经内部只读目录校验 ID/编码/名称一致 |
-| 尾程订单完整计划、柜级到仓时间、暂扣与人工节点 | `controller/LastlegOrderController.java`、`service/LastlegOrderCommandService.java`、`inboundplan/service/InboundPlanService.java`、`dto/LastlegOrderCommandDtos.java`；Admin 清关提柜列表通过 `/orders/container-arrival-times/query` 批量读取整柜预计/实际到仓，预计时间在任何入库计划生成前按柜级版本与幂等键人工维护并原子同步全柜 `ll_order.estimated_warehouse_at`，实际时间只取海外 PDA 会话首次 `receiving_at`。单票计划写入校验订单版本、客户范围、订单冻结入仓码、稳定接柜仓 ID、当前仓库主档与幂等键；预计到仓日期不接受计划请求输入，必须锁定来源柜全部订单的 `estimated_warehouse_at`，缺失或同柜不一致时阻断，人工与自动计划统一写其日期；一件代发人工计划必须逐托沿用不可变头程封托的 DP 托盘码和箱数，托数及各托箱数均不得重新分配，禁止保存无法绑定真实资源的半成品计划；接柜仓编码/名称以该 ID 当前目录快照为准，不要求订单残留旧展示快照。暂扣/解除写不可变历史并发布 `InboundOrderDetainedOutboxService`；新增暂扣只允许完成入库且尚未进入出库流程的订单，解除暂扣不受该状态限制；暂扣只阻断排车和出库，不阻断入库计划或入库作业。人工节点必须一次提交固定八行完整快照且至少一个时间，首次保存后永久使用 `MANUAL` 来源，不得回退柜级节点或反向修改头程船节点 |
+| 尾程订单完整计划、柜级到仓时间、暂扣与人工节点 | `controller/LastlegOrderController.java`、`service/LastlegOrderCommandService.java`、`inboundplan/service/InboundPlanService.java`、`dto/LastlegOrderCommandDtos.java`；Admin 清关提柜列表通过 `/orders/container-arrival-times/query` 批量读取整柜预计/实际到仓，预计时间在任何入库计划生成前按柜级版本与幂等键人工维护并原子同步全柜 `ll_order.estimated_warehouse_at`，实际时间只取海外 PDA 会话首次 `receiving_at`。单票计划写入校验订单版本、客户范围、订单冻结入仓码、稳定接柜仓 ID、当前仓库主档与幂等键；预计到仓日期不接受计划请求输入，必须锁定来源柜，并由 `ContainerWarehouseArrivalService` 统一解析：人工维护日期或已有计划冻结日期优先，未维护未建计划时读取 Firstleg 权威到港当地日期加两个自然日；缺失或同柜不一致时阻断，清关提柜、日历和人工/自动计划统一使用 `plannedDate`，默认日期不补零点，首个计划创建后按已有计划日期冻结；一件代发人工计划必须逐托沿用不可变头程封托的 DP 托盘码和箱数，托数及各托箱数均不得重新分配，禁止保存无法绑定真实资源的半成品计划；接柜仓编码/名称以该 ID 当前目录快照为准，不要求订单残留旧展示快照。暂扣/解除写不可变历史并发布 `InboundOrderDetainedOutboxService`；新增暂扣只允许完成入库且尚未进入出库流程的订单，解除暂扣不受该状态限制；暂扣只阻断排车和出库，不阻断入库计划或入库作业。人工节点必须一次提交固定八行完整快照且至少一个时间，首次保存后永久使用 `MANUAL` 来源，不得回退柜级节点或反向修改头程船节点 |
 | 客户尾程订单列表与详情 | `controller/MerchantLastlegOrderController.java`；客户范围只取认证身份，稳定类型/状态见 `model/LastlegOrderType.java`、`LastlegOrderStatus.java` |
 | 装柜完成事件消费 | `service/LoadingCompletedConsumer.java`；当前生产信封为 `FIRST_LEG_LOADING_PLAN_COMPLETED` V3，消费端除冻结 V2 货物事实外，按 `sourceContainerBookingId` 幂等投影物理柜五类国内装柜照片；FBA 可按箱数且不生成逐箱作业账，OVERSEAS 必须逐箱校验并生成箱级事实；V1/V2 仅用于历史事件读取 |
-| 尾程单号生成 | `service/LastlegOrderNoGenerator.java` |
+| 尾程单号生成 | `service/LastlegOrderNoGenerator.java`、`service/LastlegDocumentNumberGenerator.java`；头程来源使用14位 `WC + yyyyMMdd + 四位流水`，建单经 `service/LoadingCompletedConsumer.java` 在来源柜锁内复用已有号，正式格式见工作区 `docs/业务单据编号契约.md` |
 | 订单查询与更新 | `service/LastlegOrderService.java` |
 | 业务 Inbox | `entity/LastlegEventInbox.java`、`mapper/LastlegEventInboxMapper.java` |
 | 尾程订单、明细、状态历史 | `entity/LastlegOrder.java`、`LastlegOrderDetail.java`、`LastlegOrderStatusHistory.java` 及对应 Mapper |
@@ -36,6 +36,7 @@
 | 托盘分配算法 | `inboundplan/service/PalletAllocator.java` |
 | FBA 预约创建、详情与编辑 | `InboundPlanController.java` 的 `/fba-appointments/**`、`inboundplan/service/InboundFbaAppointmentService.java`、`BatchFbaAppointmentRequest.java`、`UpdateFbaAppointmentRequest.java` |
 | PDA 入仓、实收、上架与完成 | `inboundplan/pda/controller/ReceivingContainerController.java`、`inboundplan/pda/service/ReceivingContainerService.java`、内部编排 `InboundPdaWorkflowService.java`；公网入口固定为 `/api/pda/v1/last-leg/receiving-containers/**`，`/warehouse-profile` 只按 Token 绑定仓解析共享仓库中文名称与编码，旧 planNo/allocationId Controller 已移除。多计划同柜返回计划级 `assigned/mergeAllowed/urgent/mergeHint`；普通 FBA/OVERSEAS 分别使用 bulk/carton 收货，一件代发只允许 `/current/receipts/pallet` 按国内冻结来源托盘整托收货。合托只作现场可选提示；全部计划完整绑定真实 pallet/location/lock 前不得查看、准备或签收该柜，首扫只确认已预留绑定，不得重新分配计划资源 |
+| FBA收货短少确认 | `inboundplan/controller/InboundPlanController.java` 的 `/{planNo}/confirm-shortage` → `InboundPdaWorkflowService.confirmShortage`；仅平台入库编辑权限指定客户操作，要求待差异核对、原版本及应收/实收快照、原因和幂等键。仅同柜次同目的仓收货组单票且冻结申报单SKU可按总数确认，多SKU及跨票自动分摊拒绝；逐SKU实收不得超原申报，确认后保留应收与现场结束时间，按实收生成库存和原计租批次，计划/PDA任务进入 `PARTIAL_INBOUND`，尾程订单完成入库；同事务交接原预排，明确零实收的托盘同步移除预排明细、释放本车占用及预约分配并重算整车货量；缺少零实收证据或已有拣货拒绝。不重复发布卸柜事件。无实收、超收或逐SKU事实不一致拒绝；空预留托盘不能再次作为计划货源排车。 |
 | PDA 卸柜照片上传、归属校验与预览 | `ReceivingContainerController.java` 的 `/current/unload-photos/files`、`/current/unload-photos/files/{fileId}/download`，网关 `inboundplan/pda/gateway/UnloadPhotoFileGateway.java`、`HttpUnloadPhotoFileGateway.java`；File 类型固定 `OVERSEAS_UNLOAD_PHOTO`，下载只允许当前会话已签收的 fileId 并返回 `no-store` |
 | PDA 国内装柜照片对照 | `ReceivingContainerController.java` 的 `/current/domestic-loading-photos/{evidenceType}/content`、`ContainerLoadingEvidenceMapper.java`、`DomesticLoadingEvidenceGateway.java`；元数据按物理柜投影，不保存客户，下载必须经当前 PDA 会话鉴权并复用 `FILE_SERVICE_URL` 只读访问 File 服务，单图不可用不改变拆柜状态 |
 | 卸柜照片与海外卸柜完成 Outbox | `ReceivingContainerController.java`、`ReceivingContainerService.java`、`inboundplan/pda/service/InboundUnloadCompletedOutboxService.java`、`entity/LastlegEventOutbox.java`、`mapper/LastlegEventOutboxMapper.java`；多计划同柜只能在全柜完成后调用 `publishContainerCompleted`，按来源柜预订 ID 幂等发布一次，完成时刻与拍照时刻分离；事件模型见 `../common-event-contract/AGENTS.md` |
@@ -86,7 +87,7 @@
 - 车次成本：`fleet/trip/FleetTripCostService.java`、`fleet-trip-costs-v1.yaml`；按DEPART实测及外接实收分摊，不产生客户账单/付款。
 - 报价/统计：`fleet/quote/`、`fleet/reporting/`，合同`fleet-quotes-v1.yaml`、`fleet-operations-v1.yaml`；实测凭证按车次归属，仅当前/历史版本引用可下载。
 - 自有业务运营：`fleet/ownedbusiness/`、`fleet-owned-business-v1.yaml`，共同规则见`../../../docs/海外仓业务/自有业务首版开发契约.md`；原排车装车后三阶段按无实际拼车货物展示，车辆归属独立，仅补金额、逐目的地到达、里程、油耗与照片。原详情只经`dispatch.port.DispatchDetailReader`读取，原装车事务经`OwnedBusinessOwnershipCapture`捕获归属，不另建履约流程。
-- 外配业务运营：`fleet/outsourcedbusiness/`、`fleet-outsourced-business-v1.yaml`，共同规则见`../../../docs/海外仓业务/外配业务首版开发契约.md`；原排车装车后三阶段按实际接入需求池拼车货物展示，车辆归属独立，包含MASTER/EXTERNAL两种资源模式。只登记整车承运金额、逐目的仓到达和五装车照片，无里程/油耗或成本拆分。内部可信作用域复用四表，入口权限与自有严格分开，不引入第二履约模型。
+- 外配业务运营：`fleet/outsourcedbusiness/`、`fleet-outsourced-business-v1.yaml`，共同规则见`../../../docs/海外仓业务/外配业务首版开发契约.md`；原排车装车后三阶段按实际接入需求池拼车货物展示，车辆归属独立，包含MASTER/EXTERNAL两种资源模式。只登记整车承运金额、逐目的仓到达和五类装车照片（每类最多5张），无里程/油耗或成本拆分。内部可信作用域复用四表，入口权限与自有严格分开，不引入第二履约模型。
 - 外接选价合同：`fleet-quote-candidates-v1.yaml`、`fleet-trips-v1.yaml`；来源快照与成交价分开，确认承运复验。
 - 在途交接：`fleet/exception/`、`fleet-handovers-v1.yaml`；后台确认交接，旧资源分别结束任务，DEPART不重写。
 
@@ -97,7 +98,7 @@
 - 平台一件代发出库候选由 `/outbound-orders/one-click-dropship/candidates` 统一返回已完成入库且仍有可用箱唛、SKU 汇总和库存仓位绑定的托盘明细；查询不强制先传 `customerId`，未传时跨客户展示供页面分页筛选，创建时必须从所选候选解析为唯一客户和唯一海外仓，禁止一张出库单跨客户或跨仓。创建后出库单按 `WAIT_PICK → PICKING → PICKED → OUTBOUNDED` 推进；海外 PDA 扫描托盘码时通过整托命令原子拣取该托盘在当前任务内全部剩余箱件和 SKU，任一库存明细失败须整托回滚，逐箱拣货入口继续保留。
 - 排车主流程以工作区 `docs/海外仓业务/排车列表统一作业改造契约.md` 为正式入口：一张排车单代表一趟车；Admin/PDA确认`loading-complete`时，同一事务自动按客户与目的仓生成派送单并发车，成功直接进入`DELIVERING`。公开手工安排派送及`/depart`入口已删除；内部`AFTER_LOADING`仅是同事务中间态。`DispatchPdaWorkflowService` 按公开 `status`、`stage`、`recordVersion` 和 `actions` 返回作业事实与资格，Admin/PDA 共用服务端规则；BOL 与签收资料归拆分后的派送单，费用按其来源去重，不以旧转派送阶段或前端推算代替资格校验。
 - 排车主单允许同一起运仓的跨客户货物同车，每条来源保留客户、库存与费用归属；不再要求用户先建独立车次再关联多张客户排车。Fleet 的资源、司机证照、容量、历史与附加能力继续沿 `fleet/trip/` 定位；计划或资源变化对审核、实载确认的影响按正式契约及服务端结果核对，已拣货事实不能因改派或取消被直接抹除，实际发车后不得伪造资源释放。
-- 实物装载按仓库托盘去重计量，客户货量与物理占位分别保存；重量/体积必须来自实际确认，不用计费材积重回填。装车前真实拣货须核平，后台不能补录拣货数量绕过；装车发运编排不重复执行已完成的库存扣减；费用未明确时保持未计费，不要求理货员补费用，也不填零，真实已明确外接报价仍按原来源防重发布。来源、审核、实载与资源版本变化按正式契约重新校验，保留操作历史；双端使用同一版本与原请求键核对结果，任何失败均不得伪造完成事实。
+- 实物装载按仓库托盘去重计量，客户货量与物理占位分别保存；重量/体积由已有实测自动带出，未知保持空值且不阻塞装车，不要求逐托补填，不用计费材积重回填。装车前真实拣货须核平，后台不能补录拣货数量绕过；装车发运编排不重复执行已完成的库存扣减；费用未明确时保持未计费，不要求理货员补费用，也不填零，真实已明确外接报价仍按原来源防重发布。来源、审核、实载与资源版本变化按正式契约重新校验，保留操作历史；双端使用同一版本与原请求键核对结果，任何失败均不得伪造完成事实。
 - 车次结案只消费派送事实：实签须signedAt/signedPackages，实退须原来源入账流水/RETURN_COMPLETED；实签加本趟实退等于原实发且余量为零。拒收、待退回、取消不算完成，时间取最后实际终态。结案不改客户状态/费用、不释放占用；车/司机分别记录实际结束时间地点，车辆状态与释放同事务。过期证照不阻止旧任务结束、不恢复新任务资格；原键重放不影响后续车次。
 - 已签收后另发起退货保留原运输的签收事实，后续退货不重开原车次、不被车次结案改写；未签收货物仍按实际退回完成核对。`DeliveryDocumentService.save` 首次保存签收资料触发完成时要求关联出库已OUTBOUNDED，未出库可以准备BOL/装车资料但不能提前完成派送。
 - 排车执行与 `delivery/` Controller 一同注册；平台排车查询和智能预排入口分别沿 `lastleg.dispatch-query-api.enabled`、`lastleg.smart-dispatch-api.enabled` 配置定位，启用现状以配置和实际路由核对。平台查询按全局排车号及来源归属加载跨客户同车明细，客户接口保持本客户隔离；预排创建逐项校验同一起运仓及各来源客户，不能强制整张排车只含一个客户。草稿托盘锁仍按操作人与草稿标识持有，释放、失效及转正式锁由服务端原子处理。
@@ -112,7 +113,7 @@
 ## 事件建单规则
 
 - 只接受冻结契约支持的事件类型和版本；校验事件 ID、租户、区域、Payload 哈希及必要字段。
-- 同一实际集装箱 `containerNo` 生成一个共享业务尾程单号；`payload.orders` 每项按 `sourceInboundId` 独立落一条雪花 ID `ll_order`，并保存对应明细和初始状态历史。整柜操作不使用 `cabinetNo`。
+- 同一冻结来源柜 `sourceContainerBookingId` 共用一个14位 `WC + yyyyMMdd + 四位流水` 尾程单号；首个交接事件在来源柜行锁内取号，后续客户或跨日交接复用该柜已保存的编号，事件重放不取新号。不同来源柜复用真实集装箱号时仍分别编号；`payload.orders` 每项按 `sourceInboundId` 独立落一条雪花 ID `ll_order`，并保存对应明细和初始状态历史。真实 `containerNo` 继续保留作实箱快照，`cabinetNo` 仅为柜次展示，不替代稳定来源柜身份。
 - `ONE_CLICK_DROPSHIP` 每个来源入仓单必须携带一个或多个不可变来源托盘快照；每托按 SKU 携带箱数、数量和箱唛。校验订单汇总一致、托盘号/SKU/箱唛唯一后，按托建立档案及 SKU 库存，并建立箱唛和流水。仓库实物托盘由 Warehouse API 分配，不得覆盖来源托盘快照。
 - 其他订单类型建立入仓单维度的尾程订单与冻结明细，并保留头程推荐托数；尾程入仓计划至少按推荐托数生成计划托盘，PDA 再把箱级事实绑定到海外仓实物托盘。
 - 整个事件消费在一个事务内完成；任意订单失败时不得留下部分订单。
@@ -161,3 +162,5 @@
 - 事件契约变化同时检查 `common-event-contract`、直接生产者/消费者、Outbox/Inbox 和 DeliveryAck 的 eventId/payloadHash；按 `../../docs/统一认证与服务通信契约.md` 的逐事件表验证，不引入旧 Payload 兼容。
 - 定向验证：从后端根执行 `mvn -pl lastleg-service -am test`。
 - 事件链路变更至少覆盖重复事件、相同来源入仓单、事务回滚、并发单号、内部令牌和租户越权测试。
+
+- 2026-10-26 装车资料：五类依次为司机驾驶证、车牌照片、装车完成、封车照片、BOL司机签字；既有技术槽位与文件归属保持。每类1至5张，未传 `replaceFileId` 追加，指定当前同类文件ID则精确替换；油耗仍单张替换。五类至少各一张且装车确认后才自动派送，同类多张不能充当其他类别，附加行版本/幂等/历史及当前文件下载授权共同保留。无需新增数据库字段，PDA、Admin、Lastleg需配套发布。

lastleg-service/docs/lastleg-internal-modularization-baseline.md

@@ -28,6 +28,10 @@
 
 `fleet.ownedbusiness`只为原排车装车后的自有车辆组合运营资料。五条精确引用限`OwnedBusinessModels→DispatchViews`、`OwnedBusinessProjection→DispatchContracts`、`OwnedBusinessQueryService→DispatchContracts/DispatchTypes/DispatchDetailReader`，均为`dispatch.port`公开事实或只读应用端口；不增加`fleet→dispatch-delivery`通用许可，不共享原排车实体、Mapper或具体Service。原详情适配器在dispatch内部委托唯一提供者。`DispatchAggregateService→OwnedBusinessOwnershipCapture`仅在原装车事务捕获归属，不能反向调用运营查询；捕获失败随原确认回滚。反向合同拒绝具体持久化/Service引用、其他消费者借用端口许可及任何包循环。
 
+### 装车资料触发派送边界（2026-10-21）
+
+`DispatchLoadingDocumentService`、`DispatchLoadingDepartureService`及平台/PDA两个装车资料Controller只引用`fleet.ownedbusiness.port.DispatchLoadingPhotoPort`的公开照片、版本、绑定请求和结果。`DispatchLoadingPhotoAdapter`在车队内部复用原附加表、上传账本和文件校验，不反向调用排车服务。排车服务持整车父锁，在装车确认或资料保存后核对两项条件，同一事务推进派送并记录原结果。结构门禁仅开放上述四类到此端口的精确引用，不开放车队Service、Repository或Mapper，也不新增包循环。
+
 ### 外配业务原排车详情读取边界（2026-10-21）
 
 `OutsourcedBusinessModels → DispatchViews` 仅组合既有 `dispatch.port` 公开详情。依赖登记与已有外配反向合同同步，不开放 `fleet→dispatch-delivery` 通用许可；原排车实体、Mapper、具体 Service 及其他消费者仍由门禁拒绝。
@@ -260,3 +264,7 @@ node lastleg-service/scripts/analyze-lastleg-dependencies.mjs --source-set all -
 - 两条边均属于同一 `lastleg-service` 部署单元内的海外仓出库与派送正式链路；本次只冻结已存在的生产依赖，不扩大海外主数据或安全投影的允许方向。
 
 2026-10-03 外接来货使用`FleetBookingIncomingGateway`，仅`transfer.fleet.FleetIncomingAdapter`实现该端口并复用`FleetDispatchGateway`的目的键算法；这两个精确类引用进入reviewedClassDependencies，不放开整个转运切片读取fleet实现。fleet不导入转运DTO/Service/Mapper，转运仍维护实收与库存；车次只保存实收证据和确认的承运载荷。包无环及禁止其他消费者扩大依赖的反向测试继续生效。
+
+### 档案照片只读复用边界（2026-10-26）
+
+`DispatchMasterPhotoService`仅通过`fleet.photo.port.FleetResourcePhotoPort`及其照片DTO读取档案照片，再经排车文件网关生成当趟副本。`TransportTaskService`仅新增照片类别DTO引用，不读取照片Mapper或Repository。`fleet.photo`复用车辆`VehicleRepository`应用端口与司机应用服务校验身份，不反向依赖排车；精确边界纳入依赖合同。

lastleg-service/pom.xml

@@ -4,6 +4,10 @@
     <modelVersion>4.0.0</modelVersion>
     <parent><groupId>com.baiyue.firstleg</groupId><artifactId>baiyue-firstleg-platform</artifactId><version>1.0.0-SNAPSHOT</version><relativePath>../pom.xml</relativePath></parent>
     <artifactId>lastleg-service</artifactId>
+    <properties>
+        <!-- 定向 -Dtest 在 default-test 执行所选类，避免后置 SQL 执行再次运行同一列表。 -->
+        <ci.sql-semantic.skip>false</ci.sql-semantic.skip>
+    </properties>
     <dependencies>
         <dependency><groupId>com.google.zxing</groupId><artifactId>core</artifactId><version>3.5.3</version></dependency>
         <dependency><groupId>com.baiyue.shared</groupId><artifactId>common-event-contract</artifactId><version>${project.version}</version></dependency>
@@ -42,6 +46,7 @@
                         <phase>test</phase>
                         <goals><goal>test</goal></goals>
                         <configuration>
+                            <skip>${ci.sql-semantic.skip}</skip>
                             <includes><include>**/*SqlSemanticTest.java</include></includes>
                             <reuseForks>false</reuseForks>
                         </configuration>

lastleg-service/scripts/analyze-lastleg-dependencies.test.mjs

@@ -64,6 +64,8 @@ test('fleet stays a business slice and its policies have no infrastructure depen
     && edge.target.startsWith('com.baiyue.lastleg.fleet.'));
   assert.ok(dispatchEdges.length > 0);
   assert.ok(dispatchEdges.every(edge => /\.(FleetDispatchGateway|FleetDispatchBindingGuard|FleetTripExecutionService|FleetExecutionModels|FleetCompletionModels)$/.test(edge.target)
+    || edge.source === 'com.baiyue.lastleg.dispatch.service.DispatchMasterPhotoService'
+      && ['com.baiyue.lastleg.fleet.photo.port.FleetResourcePhotoPort', 'com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels'].includes(edge.target)
     || edge.source === 'com.baiyue.lastleg.dispatch.fleet.FleetDispatchPlanningAdapter'
       && /\.(FleetBookingIncomingGateway|FleetDispatchPlanningGateway)$/.test(edge.target)
     || edge.source === 'com.baiyue.lastleg.dispatch.fleet.FleetDispatchPlanningMapper'
@@ -72,11 +74,19 @@ test('fleet stays a business slice and its policies have no infrastructure depen
       && edge.target === 'com.baiyue.lastleg.fleet.exception.FleetHandoverPdaQuery'
     || edge.source === 'com.baiyue.lastleg.dispatch.service.DispatchAggregateService'
       && edge.target === 'com.baiyue.lastleg.fleet.ownedbusiness.port.OwnedBusinessOwnershipCapture'
+    || ['com.baiyue.lastleg.dispatch.service.DispatchLoadingDocumentService',
+      'com.baiyue.lastleg.dispatch.service.DispatchLoadingDepartureService',
+      'com.baiyue.lastleg.dispatch.controller.DispatchLoadingDocumentController',
+      'com.baiyue.lastleg.dispatch.pda.controller.PdaDispatchLoadingDocumentController'].includes(edge.source)
+      && edge.target === 'com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort'
     || [
       'TransportTaskModels->pickup.FleetPickupModels', 'TransportTaskModels->trip.FleetTripModels',
       'TransportTaskProjection->trip.FleetTripEntity', 'TransportTaskProjection->trip.TransportTripChanged',
       'TransportTaskService->business.FleetPoolOrderQueries', 'TransportTaskService->driver.DriverService',
       'TransportTaskService->reporting.TripOperationsEvidenceGateway',
+      'TransportTaskService->photo.FleetResourcePhotoModels',
+      // 取货照片沿既有运输边界读取车次身份/时间，并复用司机资格与证照授权；不开放 Mapper。
+      'TransportReviewPhotos->driver.DriverService', 'TransportReviewPhotos->trip.FleetTripEntity',
     ].some(reference => `${edge.source}->${edge.target}` === `com.baiyue.lastleg.dispatch.transport.${reference.replace('->', '->com.baiyue.lastleg.fleet.')}`)),
     'dispatch must use fleet ports and guards, not its persistence mappers');
   const incomingEdges = report.classDependencies.filter(edge => edge.source.startsWith('com.baiyue.lastleg.transfer.') && edge.target.startsWith('com.baiyue.lastleg.fleet.'));

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentplanning/AppointmentForecastClient.java

@@ -11,7 +11,7 @@ public interface AppointmentForecastClient {
     record Request(List<Long> containerBookingIds) { }
     record Fact(Long containerBookingId,Long factId,String providerCode,String sourceReference,
                 LocalDateTime observedAt,LocalDateTime estimatedAt,LocalDateTime actualAt) { }
-    record Forecast(Long containerBookingId,Fact latest,Fact previous,String timeBasis) { }
+    record Forecast(Long containerBookingId,Fact latest,Fact previous,String timeBasis,LocalDateTime portArrivalAt) { }
     @PostMapping("/internal/firstleg/appointment-forecasts/batch")
     ApiResponse<List<Forecast>> batch(@RequestHeader("X-Internal-Service-Token") String token,@RequestBody Request request);
 }

lastleg-service/src/main/java/com/baiyue/lastleg/appointmentwork/AppointmentWorkDispatchPort.java

@@ -16,6 +16,12 @@ public interface AppointmentWorkDispatchPort {
     record CandidateBatches(List<BatchReference> appointmentBatches,List<String> blockReasons,boolean occupied) { }
     /** 整页真实客户/计划托盘一次批读；occupied含有效草稿与正式实托占用，由调用方核对本草稿身份。 */
     Map<CandidatePhysical,CandidateBatches> candidateBatches(List<CandidatePhysical> candidates);
+    /** 只读取本车已选实物的逐票预约选项；本车原占用不扣减本车可重新分配量。 */
+    Map<CandidatePhysical,List<AllocationSource>> allocationOptions(long dispatchId,List<CandidatePhysical> items);
+    record AllocationOption(String batchKey,String batchNo,Long recordVersion,int availablePackages,
+                            String confirmationNo,String appointmentAt,String appointmentEndAt,String timezone) { }
+    record AllocationSource(String sourceKey,String orderNo,String inboundCode,String destinationKey,Integer packageCount,
+                            List<AllocationOption> options,List<String> blockReasons) { }
     /** Current original allocations, grouped for authorized dispatches; historical copies are read-only evidence. */
     java.util.Map<Long,List<BatchReference>> references(List<Long> dispatchIds);
     /** 在来源锁前按批次键一次性预锁并核对权威版本，版本零合法。 */
@@ -25,6 +31,11 @@ public interface AppointmentWorkDispatchPort {
     void requireDeparture(String dispatchNo);
     /** Read-only explanation; departure must repeat the same authority checks while holding batch locks. */
     String departureBlockReason(String dispatchNo);
+    record ReceivingWindow(String batchKey,String batchNo,String customerId,String destinationKey,String confirmationNo,
+                           java.time.Instant startAt,java.time.Instant endAt,String agreementKey,int version) { }
+    /** FBA选入前须已有正式时间确认；提交审核、审核通过和开始拣货继续复核运输安排。 */
+    String reviewBlockReason(String dispatchNo,java.time.Instant plannedDepartureAt,java.time.Instant estimatedArrivalAt);
+    List<ReceivingWindow> reviewEvidence(String dispatchNo);
     void removeItem(long dispatchId,long itemId);
     void requireTripBinding(String dispatchNo,long tripId);
 }

lastleg-service/src/main/java/com/baiyue/lastleg/calendar/WarehouseCalendarMapper.java

@@ -12,24 +12,31 @@ public interface WarehouseCalendarMapper {
     @Select("""
         <script>
         SELECT * FROM (
-          SELECT o.source_container_booking_id sourceContainerBookingId,MAX(o.container_no) containerNo,
+          SELECT o.source_container_booking_id sourceContainerBookingId,
+            MAX(NULLIF(JSON_UNQUOTE(JSON_EXTRACT(e.payload_json,'$.cabinetNo')),'null')) cabinetNo,
+            MAX(o.container_no) containerNo,
             CASE WHEN COUNT(DISTINCT o.overseas_warehouse_id)=1 THEN MAX(o.overseas_warehouse_name) END warehouseName,
             CASE WHEN COUNT(DISTINCT o.overseas_warehouse_id)=1 THEN MAX(o.overseas_warehouse_code) END warehouseCode,
             CASE WHEN COUNT(o.estimated_warehouse_at)=COUNT(*) AND COUNT(DISTINCT o.estimated_warehouse_at)=1
-              AND (MAX(o.arrival_time_version)>0 OR EXISTS(SELECT 1 FROM ll_inbound_plan p
-                JOIN ll_order po ON po.id=p.source_order_id AND po.customer_id=p.customer_id
-                WHERE po.source_container_booking_id=o.source_container_booking_id))
+              AND MAX(o.arrival_time_version)>0
               THEN MAX(o.estimated_warehouse_at) END plannedAt,
             (SELECT MIN(s.receiving_at) FROM ll_receiving_container_session s
               WHERE s.source_container_booking_id=o.source_container_booking_id) actualAt,
             CASE WHEN COUNT(DISTINCT o.arrival_time_version)=1 THEN MAX(o.arrival_time_version) ELSE -1 END version,
             (SELECT COUNT(*) FROM ll_inbound_plan p JOIN ll_order po ON po.id=p.source_order_id AND po.customer_id=p.customer_id
               WHERE po.source_container_booking_id=o.source_container_booking_id) planCount,
-            FALSE canEdit
-          FROM ll_order o WHERE o.source_container_booking_id IS NOT NULL
+            FALSE canEdit,
+            (SELECT CASE WHEN COUNT(p.planned_arrival_date)=COUNT(*) AND COUNT(DISTINCT p.planned_arrival_date)=1
+              THEN MAX(p.planned_arrival_date) END FROM ll_inbound_plan p
+              JOIN ll_order po ON po.id=p.source_order_id AND po.customer_id=p.customer_id
+              WHERE po.source_container_booking_id=o.source_container_booking_id) plannedDate,
+            FALSE isDefault
+          FROM ll_order o LEFT JOIN ll_loading_event_inbox e ON e.event_id=o.source_event_id
+          WHERE o.source_container_booking_id IS NOT NULL
           GROUP BY o.source_container_booking_id
         ) c WHERE
           (c.plannedAt &gt;= #{from} AND c.plannedAt &lt; #{to})
+          OR (c.plannedDate &gt;= DATE(#{from}) AND c.plannedDate &lt; DATE(#{to}))
           <if test="ids != null and !ids.isEmpty()">
             OR c.sourceContainerBookingId IN
             <foreach collection="ids" item="id" open="(" separator="," close=")">#{id}</foreach>

lastleg-service/src/main/java/com/baiyue/lastleg/calendar/WarehouseCalendarModels.java

@@ -14,7 +14,7 @@ public final class WarehouseCalendarModels {
     private WarehouseCalendarModels() { }
     public record Query(@NotNull LocalDate from, @NotNull LocalDate to,
         @NotNull @Size(max = 2000) List<@NotBlank @Pattern(regexp = "[1-9][0-9]*") String> sourceContainerBookingIds) { }
-    public record Entry(String sourceContainerBookingId, String containerNo, String warehouseName,
+    public record Entry(String sourceContainerBookingId, String cabinetNo, String containerNo, String warehouseName,
         String warehouseCode, LocalDateTime plannedAt, LocalDateTime actualAt, int version,
-        long planCount, boolean canEdit) { }
+        long planCount, boolean canEdit, LocalDate plannedDate, boolean isDefault) { }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/calendar/WarehouseCalendarService.java

@@ -10,8 +10,10 @@ import java.util.List;
 @Service
 public class WarehouseCalendarService {
     private final WarehouseCalendarRepository repository;
+    private final com.baiyue.lastleg.service.ContainerWarehouseArrivalService arrivals;
     /** 装配日历只读仓储查询。 */
-    public WarehouseCalendarService(WarehouseCalendarRepository repository) { this.repository = repository; }
+    public WarehouseCalendarService(WarehouseCalendarRepository repository,
+        com.baiyue.lastleg.service.ContainerWarehouseArrivalService arrivals) { this.repository = repository; this.arrivals=arrivals; }
     /** 明确权限、版本与计划冻结资格；不以默认计划改写真实到仓时间。 */
     public List<WarehouseCalendarModels.Entry> calendar(WarehouseCalendarModels.Query query, boolean canEdit) {
         if (query.from() == null || query.to() == null || !query.to().isAfter(query.from())
@@ -20,8 +22,16 @@ public class WarehouseCalendarService {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "日历范围须为1至42天，来源柜不能重复");
         var rows = repository.calendar(query);
         if (rows.size() > 2000) throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "到仓记录过多，请缩小日期范围");
-        return rows.stream().map(row -> new WarehouseCalendarModels.Entry(row.sourceContainerBookingId(), row.containerNo(),
-            row.warehouseName(), row.warehouseCode(), row.plannedAt(), row.actualAt(), row.version(), row.planCount(),
-            canEdit && row.version() >= 0 && row.planCount() == 0 && row.actualAt() == null)).toList();
+        var resolved=arrivals.resolve(rows.stream().map(WarehouseCalendarModels.Entry::sourceContainerBookingId).toList())
+            .stream().collect(java.util.stream.Collectors.toMap(
+                com.baiyue.lastleg.dto.ContainerArrivalTimeView::sourceContainerBookingId,java.util.function.Function.identity()));
+        return rows.stream().map(row -> {
+            var arrival=resolved.get(row.sourceContainerBookingId());
+            if(arrival==null) throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE,"来源柜到仓日期读取不完整");
+            return new WarehouseCalendarModels.Entry(row.sourceContainerBookingId(), row.cabinetNo(), row.containerNo(),
+                row.warehouseName(), row.warehouseCode(), row.plannedAt(), row.actualAt(), row.version(), row.planCount(),
+                canEdit && row.version() >= 0 && row.planCount() == 0 && row.actualAt() == null,
+                arrival.plannedDate(),arrival.isDefault());
+        }).toList();
     }
 }

lastleg-service/src/main/java/com/baiyue/lastleg/client/OrderPreDepartureClient.java

@@ -0,0 +1,24 @@
+package com.baiyue.lastleg.client;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+@FeignClient(name="order-service", contextId="lastlegOrderPreDepartureClient", path="/internal/order/v1/predeparture-orders")
+public interface OrderPreDepartureClient {
+    @GetMapping
+    ApiResponse<PageResult<Row>> page(@RequestHeader("X-Internal-Service-Token") String token,
+        @RequestParam(required=false) Long customerId, @RequestParam(required=false) String orderNo,
+        @RequestParam(required=false) String inboundCode, @RequestParam int page, @RequestParam int size);
+    record Row(Long orderId, Long customerId, String orderNo, String inboundCode, String mainStatus,
+        String customerName, String lxCode, String receivingWarehouseName, String destinationWarehouseName,
+        String destinationCode, Integer packageCount, BigDecimal volumeCbm, BigDecimal grossWeightKg,
+        BigDecimal netWeightKg, LocalDateTime expectedArrivalAt, String containerNo, String cabinetNo,
+        LocalDateTime estimatedSailingAt, LocalDateTime actualSailingAt, LocalDateTime createdAt, LocalDateTime updatedAt) {}
+}

lastleg-service/src/main/java/com/baiyue/lastleg/delivery/model/DeliveryCargoGroups.java

@@ -59,16 +59,26 @@ public class DeliveryCargoGroups {
             var rows=entry.getValue().stream().sorted(Comparator.comparing(CargoLine::dispatchItemId)
                 .thenComparing(CargoLine::attributionId)).toList();
             var first=rows.get(0);
-            if (rows.stream().anyMatch(row->!Objects.equals(row.destination(),first.destination())))
+            // FBA以真实仓码分组；外接来货可缺内部仓ID，只沿同组已知ID核对，不能覆盖冲突值。
+            var destination=rows.stream().map(CargoLine::destination)
+                .filter(value->!blank(value.warehouseId())).findFirst().orElse(first.destination());
+            if (rows.stream().anyMatch(row->!Objects.equals(withKnownFbaWarehouseId(row.destination(),destination.warehouseId()),destination)))
                 throw conflict("同组货物的目的地信息不一致，请核对后安排");
             long packages=rows.stream().mapToLong(CargoLine::packages).reduce(0,Math::addExact);
             long pallets=rows.stream().map(CargoLine::warehousePalletId).filter(Objects::nonNull).distinct().count();
-            result.add(new Group(entry.getKey(),first.customerId(),first.customerName(),first.destination(),
+            result.add(new Group(entry.getKey(),first.customerId(),first.customerName(),destination,
                 hash(rows),rows,packages,pallets));
         }
         return List.copyOf(result);
     }
 
+    /** 仅补同一分组FBA缺失的内部引用，其他目的地事实必须保持完全一致。 */
+    private Destination withKnownFbaWarehouseId(Destination value,String warehouseId) {
+        if (!"FBA".equals(value.type()) || !blank(value.warehouseId()) || blank(warehouseId)) return value;
+        return new Destination(value.key(),value.type(),warehouseId,value.warehouseCode(),value.warehouseName(),
+            value.address(),value.postalCode(),value.contactName(),value.contactPhone());
+    }
+
     /** 客户是组身份的一部分，同目的仓的其他客户永不合单。 */
     public String groupKey(String customerId,Destination destination) {
         return hash(List.of(customerId,destination.key()));

lastleg-service/src/main/java/com/baiyue/lastleg/delivery/service/DeliveryTransferService.java

@@ -78,7 +78,6 @@ import org.springframework.web.server.ResponseStatusException;
 
 import java.time.LocalDateTime;
 import java.time.LocalDate;
-import java.time.format.DateTimeFormatter;
 import com.baiyue.lastleg.service.LastlegOrderNoGenerator;
 import java.math.BigDecimal;
 import java.math.RoundingMode;
@@ -192,7 +191,7 @@ public class DeliveryTransferService {
         outbound.setVolumeCbm(sum(createdMetricItems, OutboundPalletItem::getVolumeCbm));
         outbound.setOverseasWarehouseId(selectedWarehouseId); outboundOrders.updateById(outbound);
         OutboundPdaTask task = new OutboundPdaTask(); task.setId(IdWorker.getId()); task.setCustomerId(customerId); task.setOutboundOrderId(outbound.getId());
-        task.setTaskNo("PDA" + now.format(DateTimeFormatter.BASIC_ISO_DATE) + task.getId()); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
+        task.setTaskNo(orderNoGenerator.next("OUTBOUND_TASK")); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
         return taskResult(outbound, task);
     }
 
@@ -307,7 +306,7 @@ public class DeliveryTransferService {
         delivery.setVersion(0L); delivery.setCreatedBy(operatorId); delivery.setCreatedAt(now); delivery.setUpdatedAt(now);
         deliveryOrders.insert(delivery);
         OutboundPdaTask task = new OutboundPdaTask(); task.setId(IdWorker.getId()); task.setCustomerId(customerId); task.setOutboundOrderId(outbound.getId());
-        task.setTaskNo("PDA" + now.format(DateTimeFormatter.BASIC_ISO_DATE) + task.getId()); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
+        task.setTaskNo(orderNoGenerator.next("OUTBOUND_TASK")); task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
         return taskResult(outbound, task);
     }
 
@@ -459,7 +458,7 @@ public class DeliveryTransferService {
         recordOperation(customerId, delivery.getId(), operatorId, "CREATE_DELIVERY", "仓储转运出库自动生成派送单", now);
 
         OutboundPdaTask task = new OutboundPdaTask(); task.setId(IdWorker.getId()); task.setCustomerId(customerId);
-        task.setOutboundOrderId(outbound.getId()); task.setTaskNo("PDA" + now.format(DateTimeFormatter.BASIC_ISO_DATE) + task.getId());
+        task.setOutboundOrderId(outbound.getId()); task.setTaskNo(orderNoGenerator.next("OUTBOUND_TASK"));
         task.setStatus("PENDING"); task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); pdaTasks.insert(task);
         transfer.setStatus("WAIT_OUTBOUND");
         if ("FBA".equals(destinationType)) transfer.setFbaWarehouseCode(request.destinationWarehouseCode().trim());

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchAggregateController.java

@@ -53,6 +53,18 @@ public class DispatchAggregateController {
     public ApiResponse<com.baiyue.lastleg.dispatch.port.DispatchWorkModels.Items> items(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
         return ApiResponse.success(service.items(DispatchActorFactory.platform(user),dispatchNo));
     }
+    /** 本车货物逐票读取正式预约选项及当前分配。 */
+    @GetMapping("/{dispatchNo}/appointment-allocations")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ApiResponse<com.baiyue.lastleg.dispatch.port.DispatchWorkModels.AppointmentAllocations> appointmentAllocations(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
+        return ApiResponse.success(service.appointmentAllocations(DispatchActorFactory.platform(user),dispatchNo));
+    }
+    /** 原车版本化关联正式预约，不新建排车或修改库存。 */
+    @PutMapping("/{dispatchNo}/appointment-allocations")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<CommandResult> appointmentAllocations(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@RequestBody com.baiyue.lastleg.dispatch.port.DispatchWorkModels.AppointmentAllocationCommand request) {
+        return ApiResponse.success(service.saveAppointmentAllocations(DispatchActorFactory.platform(user),dispatchNo,request));
+    }
     /** 读取实际起点和卸货顺序。 */
     @GetMapping("/{dispatchNo}/route")
     @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchLoadingDocumentController.java

@@ -0,0 +1,60 @@
+package com.baiyue.lastleg.dispatch.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.dispatch.controller.DispatchActorFactory;
+import com.baiyue.lastleg.fleet.ownedbusiness.port.DispatchLoadingPhotoPort.*;
+import com.baiyue.lastleg.dispatch.service.DispatchLoadingDocumentService;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.*;
+import org.springframework.http.*;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+/** 平台排车装车资料入口，与另一端共用五框和自动派送门禁。 */
+@RestController
+@Validated
+@RequestMapping("/api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents")
+public class DispatchLoadingDocumentController {
+    private final DispatchLoadingDocumentService service;
+    /** Controller只负责会话与输入映射，所有资料和状态规则归服务。 */
+    public DispatchLoadingDocumentController(DispatchLoadingDocumentService service){this.service=service;}
+    /** 读取本车已保存照片，不以设备缓存作为上传事实。 */
+    @GetMapping
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ApiResponse<Documents> get(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo) {
+        return ApiResponse.success(service.get(DispatchActorFactory.platform(user),dispatchNo));
+    }
+    /** 上传先记录原请求，成功回执后再保存本车槽位引用。 */
+    @PostMapping(value="/{slot}/uploads",consumes=MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Photo> upload(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable Slot slot,
+        @RequestParam @Size(min=8,max=128) String idempotencyKey,@RequestPart("file") MultipartFile file) {
+        return ApiResponse.success(service.upload(DispatchActorFactory.platform(user),dispatchNo,slot,idempotencyKey,file));
+    }
+    /** 最后一框保存成功时自动进入派送中，不新增人工发车按钮。 */
+    @PutMapping("/{slot}")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Documents> bind(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,
+        @PathVariable Slot slot,@Valid @RequestBody BindPhoto request) {
+        return ApiResponse.success(service.bind(DispatchActorFactory.platform(user),dispatchNo,slot,request));
+    }
+    /** 原上传仅允许当前有权限的原操作者恢复。 */
+    @GetMapping("/uploads/{idempotencyKey}")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:edit')")
+    public ApiResponse<Photo> recover(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable String idempotencyKey) {
+        return ApiResponse.success(service.recover(DispatchActorFactory.platform(user),dispatchNo,idempotencyKey));
+    }
+    /** 每次预览核对本车当前绑定，文件不得跨车跨仓读取。 */
+    @GetMapping("/{slot}/files/{fileId}/content")
+    @PreAuthorize("hasAuthority('platform:overseas-warehouse:dispatch:list')")
+    public ResponseEntity<byte[]> content(@AuthenticationPrincipal AuthenticatedUser user,@PathVariable String dispatchNo,@PathVariable Slot slot,@PathVariable @Positive long fileId) {
+        var value=service.content(DispatchActorFactory.platform(user),dispatchNo,slot,fileId);
+        return ResponseEntity.ok().cacheControl(CacheControl.noStore()).contentType(MediaType.parseMediaType(value.photo().contentType()))
+            .header("X-Content-Type-Options","nosniff").body(value.content());
+    }
+}
+

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchQueryController.java

@@ -36,6 +36,7 @@ import java.nio.charset.StandardCharsets;
 public class DispatchQueryController {
     @Resource private DispatchAggregateService aggregateService;
     @Resource private DispatchBolPrintService printService;
+    @Resource private com.baiyue.lastleg.dispatch.service.DispatchCapacityDemandService capacityDemands;
 
     @GetMapping
     @PreAuthorize("hasAuthority('" + OverseasPermissions.DISPATCH_LIST + "')")
@@ -47,6 +48,14 @@ public class DispatchQueryController {
         return ApiResponse.success(aggregateService.page(DispatchActorFactory.platform(user),query));
     }
 
+    /** 内部需求池沿独立只读权限，不授予销售整车客户及司机资料读取权限。 */
+    @GetMapping("/capacity-demands")
+    @PreAuthorize("hasAnyAuthority('platform:fleet:capacity-offer:list','platform:fleet:capacity-offer:manage')")
+    public ApiResponse<PageResult<com.baiyue.lastleg.dispatch.port.DispatchCapacityDemands.Demand>> capacityDemands(
+        @AuthenticationPrincipal AuthenticatedUser user, @Valid com.baiyue.lastleg.dispatch.port.DispatchCapacityDemands.Query query) {
+        requirePlatform(user); return ApiResponse.success(capacityDemands.page(query));
+    }
+
     @GetMapping("/{dispatchNo}")
     @PreAuthorize("hasAuthority('" + OverseasPermissions.DISPATCH_LIST + "')")
     @Operation(summary = "Get dispatch details and all pallet destinations")

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/entity/DispatchAggregate.java

@@ -9,6 +9,8 @@ public class DispatchAggregate {
     private Long id;
     private String dispatchNo;
     private String taskType;
+    /** 是否向内部散板需求池发布本车余位。 */
+    private Boolean publishLooseboardDemand = false;
     private Long tripId;
     private String overseasWarehouseId;
     private String overseasWarehouseCode;