Merge pull request 'Test' (#1) from test into main

Reviewed-on: https://git.buggoglobal.com/html/docs/pulls/1
2026-09-28 16:01:15 +08:00
parent b7e02f0782 df6f434550
commit e579ca2d3a
1486 changed files with 1942252 additions and 14801 deletions
@@ -1,2 +1,6 @@
 .DS_Store
 **/.DS_Store
 .playwright-cli
 .superpowers
 output
 docs
@@ -0,0 +1,8 @@
 # 默认忽略的文件
 /shelf/
 /workspace.xml
 # 基于编辑器的 HTTP 客户端请求
 /httpRequests/
 # Datasource local storage ignored files
 /dataSources/
 /dataSources.local.xml
@@ -0,0 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <module type="JAVA_MODULE" version="4">
  <component name="NewModuleRootManager" inherit-compiler-output="true">
    <exclude-output />
    <content url="file://$MODULE_DIR$" />
    <orderEntry type="inheritedJdk" />
    <orderEntry type="sourceFolder" forTests="false" />
  </component>
 </module>
@@ -0,0 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="ProjectRootManager" version="2" languageLevel="JDK_17" default="true" project-jdk-name="temurin-17" project-jdk-type="JavaSDK">
    <output url="file://$PROJECT_DIR$/out" />
  </component>
 </project>
@@ -0,0 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="ProjectModuleManager">
    <modules>
      <module fileurl="file://$PROJECT_DIR$/.idea/docs.iml" filepath="$PROJECT_DIR$/.idea/docs.iml" />
    </modules>
  </component>
 </project>
@@ -0,0 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="VcsDirectoryMappings">
    <mapping directory="" vcs="Git" />
  </component>
 </project>
@@ -0,0 +1,68 @@
 # AI 工程执行与协作约束
 ## 读取条件
 - 运行、构建、依赖、临时目录、工作树、部署、数据库、跨模块改动或独立任务协作时读取本文件。
 - 普通代码定位仍先按根 `AGENTS.md` 的项目和业务路由进入最近的项目/模块指引；本文件不替代业务索引。
 ## 根目录、临时目录与依赖复用
 - 根目录只保留 `apps/` 前端应用、`baiyue-firstleg/` 后端独立仓库、`docs/` 产品与契约文档三类业务事实来源；新增业务源码或服务不得直接放在根目录。
 - `.vscode/`、`.impeccable/`、`.superpowers/` 和根 `.codex-temp/` 属于本地工具或缓存，不作为业务入口；根 `.codex-temp/` 不得存放项目副本。
 - `output/`、`outputs/`、`dist/`、`target/`、日志和临时文件属于生成物，不纳入索引；空的临时产物目录应及时清理。
 - 启动服务、测试、类型检查和构建默认直接在目标项目目录执行，并复用现有 `node_modules/`、Maven 本地仓库及其他依赖缓存；不得仅为运行或验证创建 `.codex-temp/<task>`、`.codex-tmp/<task>` 或完整项目副本。
 - 不得复制、移动或手工链接现有 `node_modules/` 到临时目录。依赖缺失或锁文件变化时，在目标项目执行其声明的安装命令。
 - 当前开发阶段不得因小功能、缺陷修复、联调、测试、构建、端口冲突、未提交修改或希望获得“干净目录”而创建 `wk`/Git worktree、临时分支或项目副本；统一直接在当前工作区、当前分支修改和验证，不得自行创建或切换分支。
 - 只有用户在当前轮明确要求隔离分支或 worktree 时才可例外。例外时必须先说明原因、精确位置和清理条件，放在目标项目之外；任务结束且无进程占用后立即清理。
 - 禁止在 `apps/*/`、`baiyue-firstleg/` 及业务模块内部新增 `.codex-temp/`、`.codex-tmp/`、`worktree/` 或类似项目副本。遗留目录须先确认没有运行进程和唯一证据，再按精确路径清理。
 - 端口冲突通过停止已知旧进程或指定其他端口解决，不得复制项目。普通验证应直接覆盖当前未提交修改，不为获得“干净目录”绕开真实变更。
 ## 当前开发阶段
 - 项目尚未上线，没有需要兼容的生产存量数据、线上客户端或已发布接口版本；所有代码与契约直接收敛到当前确认目标，用户确认上线或存在不可变外部契约后才重新建立版本兼容和升级规则。
 - 收敛范围包括源码结构、接口与 DTO、字段、状态机、权限、配置键、OpenAPI、数据库结构与初始化 SQL、事件、路由、页面、前端消费者、Mock/Fixture、测试和脚本；旧实现冲突时同步修改全部生产者与消费者并直接删除旧实现。
 - 禁止为旧代码、旧调用或开发环境存量保留旧接口/旧字段别名、兼容分支、双协议、双写、灰度、回滚版本、降级解析、旧行为回退、临时适配层、迁移脚本、回填脚本、清理补偿或新旧版本并行；不得以“稳妥”“兼容历史数据”或“先保留以后删除”为由延迟收敛。
 - 开发环境数据库记录、上传文件、缓存、会话、消息、搜索索引和其他运行状态均可丢弃；正常验证方式是更新最新初始化基线、重新造数或上传，并直接运行受影响回归，不模拟生产迁移。已有历史 SQL 只用于开发追溯，不构成兼容依据。
 - 后端位于独立 Git 仓库 `../baiyue-firstleg/`，执行 Git 命令前确认当前工作目录。“无需兼容、直接修复”不授权自动重置数据库、删除数据/文件、执行 SQL、部署或修改环境。测试环境授权只读 `独立任务协作登记.md`，开发全流程授权只读 `开发环境独立任务协作登记.md`；未登记任务和生产环境仍需用户在当前轮明确授权。
 ## 联调、部署与数据库
 - 默认只准备代码、验证结果和人工部署步骤，不触发 Jenkins、不启动本地 Java/Nacos/数据库。开发全流程总控可按 `开发环境独立任务协作登记.md` 的授权操作开发数据库、部署开发环境并执行开发环境真实 HTTP；登记专项可按 `独立任务协作登记.md` 的持续授权查询和修改用户指定的测试数据库。两类授权不得跨环境复用，也不得自动扩大到 Jenkins 或生产环境。
 - 只有用户在当前轮明确授权指定环境、服务和提交时，才可部署或执行 HTTP 验收；同一环境和服务的非破坏性写入可复用本轮授权，删除、重置、执行 SQL、部署或发布仍逐项授权。测试数据库的读写例外仅适用于登记表中已持续授权的总控与专项，并遵守其中的职责和破坏性操作门禁。
 - 环境地址、凭据和 Token 不写入源码或 `AGENTS.md`。接口不可用或契约不一致时记录路径、状态、错误码、`requestId`/`traceId` 和阻断原因，不回退到模拟成功。
 - 测试环境联调、部署和验收命令读取 `测试环境Jenkins部署指南.md`；开发全流程只按 `开发环境独立任务协作登记.md` 的授权与目标项目指引执行，不把测试 Jenkins 流程当作开发部署入口。
 ## 通用工程与质量门禁
 - 对外 API 新增、改名、删除或访问域变化，以“调用端实际路径（含 API Base）→ 对应区域 Gateway → Controller → OpenAPI → 权限”作为一个交付单元；不能只在修改网关文件时才检查注册。已被正确通配路由覆盖时无需重复添加路由，内部服务令牌接口不得为通过检查而公开。
 - 提交前运行 `node --test scripts/gateway-route-contract.test.mjs` 及受影响服务/调用端的定向测试；路由合同失败不得提交或声称完成。该离线合同检查源码映射、目标服务及内部路径隔离，不代替权限、HTTP 方法、运行时 Nacos 或真实 HTTP 验收；前端 Mock 测试、类型检查及服务单测通过也不证明网关可达。
 - 交付列明变更接口、路由是否复用或新增、验证结果及部署单元；Gateway 配置变化必须包含对应网关，Nacos 配置变化单独说明发布项。没有环境授权时只交付代码和待验收说明，不自动部署、发布配置或调用真实 HTTP。
 - 保持变更小而聚焦，遵循目标项目现有命名、分层和格式，不顺手重构无关代码。
 - 优先复用现有依赖和公共能力；新增或升级依赖前说明必要性、影响范围和替代方案。
 - 不提交依赖目录、构建产物、运行日志、编辑器缓存或本地临时文件；不写入密钥、令牌、真实客户数据或环境特定地址。
 - 用户可见文案保持清晰一致；代码标识符使用英文，业务说明和文档可使用中文。
 - 仅运行目标项目实际声明的安装、检查、测试和构建命令。每次变更至少验证直接受影响的项目，跨项目变更还要验证对应消费者。
 - 修改方法、构造器、组件 Props、函数、接口、DTO 或请求/响应参数时，定向检索全部生产调用、测试调用、Mock、Fixture、契约测试和脚本引用，并同步修改。
 - 参数或类型签名变化必须运行会编译测试源码的最小检查；无法验证时明确列出未验证范围。
 - 修复缺陷优先增加复现测试；没有现成测试设施时不为小改动引入整套框架，应记录验证步骤和剩余风险。
 - UI 变更按受影响范围检查加载、空态、错误态、权限、目标视口和可访问性；Admin/Client 视觉细则查 `Admin-Client前端原型还原验收规则.md` 和目标应用指引。
 - 需求、技术栈或接口未确认时停在可逆设计阶段，不自行作出高成本平台决策。
 ## 独立任务与多任务协作
 - 跨环境调度必须先核对保存项目 projectId、任务 cwd 与环境登记表三项一致；任一不一致不得下发或执行。禁止把测试环境任务通过绝对路径提示临时改作开发环境任务，反向同样禁止。
 - 开发环境全流程任务只使用 `开发环境独立任务协作登记.md`；测试环境任务只使用 `独立任务协作登记.md`。两套任务不互相复用，不在两个目录之间复制未提交文件、生成补丁、自动合并或 cherry-pick。
 - 普通任务不读取协作登记。只有用户明确指定当前对话为总控，或要求检索历史任务、独立任务或跨对话通信时，才按当前保存项目与 cwd 读取唯一匹配的登记表：开发全流程读 `开发环境独立任务协作登记.md`，测试环境读 `独立任务协作登记.md`；不得同时加载两表后混合选取任务。
 - 总控在接收任务时必须先做时长评估；预计单一执行链超过 15 分钟时，不得继续由一个任务从定位包办到验收，必须立即拆成可并行的“根因/契约核对、实现修复、回归验收”等独立工作包，并明确每包文件写权限和交付物。优先复用登记表中的长期专项；一次性工作使用内部子代理。该规则不自动授权创建新的用户可见任务。
 - 实际执行超过 15 分钟仍未形成可验证交付时，总控必须主动重新拆分或缩小范围，向用户报告当前阻断与并行安排，不得静默等待、继续扩展设计或把非必要兼容、迁移、补偿工作并入主修复链。
 - 用户按业务流程逐节点进行人工验收时，总控必须以“当前验收节点”为调度和完成单位，而不是以代码模块或单个 Bug 为单位。收到该节点首个问题后，应立即并行检查前端交互、后端状态与契约、数据/权限前置和自动化验收覆盖；同一节点后续问题统一并入该批次，不得连续串行追加给一个长期专项。
 - 节点开发批次至少包含一个唯一实现写入者；跨端时分别下发前端、后端工作包，日常不默认下发节点全链验收专项。只有用户当轮明确通知开始验收、准备部署或执行验收时，才启动验收脚本工作包。能够提前发现的问题由各实现专项在自身定向测试中收口，尽量减少“部署一次、人工发现一个、再部署一次”的循环。
 - 当前节点只有在代码门禁通过、相关自动化场景补齐、部署清单明确，并由用户完成真实环境人工验收后才关闭；关闭后再进入下一业务节点。总控需持续维护当前节点的阻断项、已修项和待部署项，不把其他节点的优化混入当前发布批次。
 - 检索历史任务只使用本机 `~/.codex/session_index.jsonl`、`~/.codex/state_5.sqlite`、`~/.codex/sessions/` 和已知本地任务，不依赖聚合本地、远程主机或云端对话的列表接口。
 - 被指定为总控只授权规划、拆解、协调和复用已登记任务，不授权创建新的用户可见独立任务；临时并行默认使用当前对话或内部子代理。
 - 创建用户可见独立任务必须由用户在当前轮明确要求，并确认精确数量、稳定职责和所属总控；历史授权以及“继续处理”“拆分”“安排”“并行”等表述不构成创建授权。
 - 创建前必须查询登记表并优先复用职责匹配的 `task_id`；一次性缺陷、排障、部署、临时验收和只为提速的并行工作不得登记为长期任务。
 - 创建成功后先登记稳定 `task_id`、所属总控和唯一长期职责，再下发工作；不自动创建替代任务或归档、解档、恢复、迁移任务。
 - 并行前明确文件归属和共享契约。共享导航、根路由、权限初始化和统一 SQL 由已登记的对应总控统一集成；发生重叠时保留现有改动并跨任务协调。
@@ -0,0 +1,69 @@
 # Admin / Client 前端原型还原验收规则
 ## 目标
 Admin 与 Client 已向客户讲解或确认过的页面，必须以对应原型为直接事实来源逐页还原。不得先统一套用现有设计系统、抽屉、弹框、详情页或图标规范，再局部调整。
 ## 修改门禁
 每个页面修改前必须先形成以下矩阵，并给出原型文件及行号、元素 ID、函数名或截图证据：
 | 页面 | 操作 | 原型承载方式 | 原型尺寸/布局 | 当前实现 | 结论 |
 |---|---|---|---|---|---|
 | 示例 | 详情 | 独立页面 | 页面级头部、返回列表 | 右侧抽屉 | 改为正式路由页面 |
 操作至少分别核对：详情、新增、编辑、审核/确认、文件预览、删除/停用确认。不得以其中一个操作的结论推断其他操作。
 ## 承载方式
 - 原型使用独立页面：必须使用正式路由、页面级布局和明确返回入口；不得改成抽屉或弹框。
 - 原型使用居中弹框：必须使用居中模态框，并按原型宽度、标题、正文、底部按钮和关闭方式还原；不得改成右侧抽屉。
 - 原型使用侧滑面板：仅该操作允许使用抽屉，并按原型方向、宽度和内部布局还原。
 - 原型未定义：先停在矩阵中标记待确认，不得因为公共组件方便而自行选择。
 - 同一列表的详情、新增、编辑、审核可以采用不同承载方式，必须逐操作判断。
 ## 视觉与排版
 - 字段顺序、分组、摆放、列宽、控件宽高、换行、对齐、外边距、内边距、间隙和留白按原型逐项核对。
 - 顶部背景色、页面背景、区块背景、边框、圆角、阴影、字号、字重和文字颜色直接取原型值。
 - 按钮位置、顺序、尺寸、颜色、危险语义、悬停态、禁用态按原型还原；不得自行增加“更多”菜单或纯文字替代。
 - 原型已提供图标、字符图标、图片或 SVG 时直接复用原型资源；不得自行绘制或替换。
 - 表格按原型核对外边框、单元格边框、表头背景、斑马纹、行悬停背景、行高和横向滚动。
 - 原型没有的公司名称图标、下划线、卡片装饰、悬停上浮、缩放和渐变效果不得添加。
 ### Admin 已确认布局基线
 - 订单样板及国内仓样式统一采用 [Admin 高密度界面规范](Admin高密度界面规范.md)。其已确认的密度、容器和页签图标规则优先于历史原型中的对应视觉；字段、业务分组、权限、操作语义与页面/弹框/抽屉承载方式继续逐操作核对。该规范不表示其他页面已完成验收。
 - Admin 是高信息密度业务系统。保留原型字段、顺序、业务分组和交互语义，但普通短字段优先使用连续白底、多列键值网格、描述表或紧凑列表，不把“一个标签 + 一个值”做成独立卡片。
 - 详情页顶部尽量合并返回、标题、核心状态和主要操作；路由壳层已显示标题时正文不重复。状态或流程结论只保留一个主要视觉落点，除真实错误、阻断或危险外不叠加大面积彩色横幅。
 - 在 `1920×1080` 下短字段通常并排 `4–6` 组；长文本、地址、备注和异常原因可以跨列或换行。长编号集中省略说明列宽设计失败，应调整列数、宽度或跨列，不继续缩小字号。
 - 同一详情页使用一致的内容底色和容器语言；连续白底区域用分隔线和间距分区，同级独立卡片的背景、圆角、边框和外间距保持一致。
 - 高信息密度不授权缩小可点击区域、删除标签、强制截断关键值或牺牲可访问性。使用真实长编号、空值、状态徽标和多字段数据核对首屏。
 - 原型明确的承载方式和视觉细节优先；历史原型仅因大量字段卡片、重复状态块或过度留白与当前密度基线冲突时，收敛承载方式但不改变字段、分组和交互语义。
 ## 响应式与可访问性
 - Admin、Client 当前只按 `1920×1080`、浏览器缩放 `100%` 验收；不检查或整改 `720px`、`320px` 等窄屏，也不删除已有响应式能力。用户恢复多视口验收后再统一调整。
 - 弹框正文超过视口时只滚动正文，标题和操作区保持可见；独立详情页按正常页面滚动。
 - 字段数量较多、两列会导致弹框明显过高时，在 `1920×1080`验收视口下改用宽版三列表单；短字段单列占位，地址、长文本、备注、文件和表格按内容跨列或整行。小型确认类弹框不因此扩宽。
 - 保留键盘操作、焦点、表单标签、图标按钮名称和足够对比度。可访问性调整不得改变原型的主要布局与视觉语义。
 ## 执行与验收
 1. 先提交逐页矩阵，不直接批量替换公共组件。
 2. 总控冻结该页结论后，任务只修改职责内模块，不触碰其他任务在途文件。
 3. 修改后由人工在 `1920×1080`、`100%` 缩放下操作并提供截图，标注与原型仍存在的差异；缺少截图时记录“待人工截图确认”，AI 不自行批量取证。
 4. 运行直接测试与类型检查；共享组件变更必须检查全部消费者。
 5. 不触发 Jenkins、不部署、不提交，除非当前对话另有明确授权。
 ## 已确认示例
 Admin 客户管理原型：
 - 客户详情：独立页面（`page-tenant-detail`）。
 - 新增客户：居中宽版弹框（`modal-tenant-add`，宽度约 1120px），基础资料和联系与商务使用三列，地址、备注和资质表格整行。
 - 编辑客户：复用新增客户的居中宽版三列弹框（`modal-tenant-edit`，宽度约 1120px）。
 - 重置密码：居中弹框（`modal-tenant-reset-password`，宽度约 520px）。
 - 入驻审核：居中弹框（`modal-tenant-audit`，宽度约 900px）。
 这些结论只适用于上述操作，不自动推广到其他页面。
@@ -0,0 +1,65 @@
 # Admin 全模块样式核对记录
 范围为 `apps/admin-web/src/core/navigation/adminNavigation.ts` 当前可见的 48 个菜单、顶部消息中心的 3 个正式页面，以及它们通过实际路由和组件可达的新增、编辑、详情、审核、文件、删除确认等操作。隐藏原型不恢复；某操作没有正式入口时记录现状，不凭原型补建业务能力。目标不缩减为已改模块。
 统一依据为本轮用户确认、国内订单/客户详情样板及 [高密度界面规范](Admin高密度界面规范.md)。操作不超过 3 个时全部显示，超过 3 个才折叠；折叠按钮只显示省略号图标，保留提示和可访问名称。
 | 导航组 | 可见菜单数 | 当前记录及下一步 |
 |---|---:|---|
 | 顶部消息中心（侧栏外） | 3 个页面 | 已补入三个列表、两处详情抽屉、两处编辑弹框及状态确认，见 [消息中心记录](Admin消息中心样式核对记录.md)；1981 项全量测试、类型与构建通过，待人工截图 |
 | 首页数据看板 | 1 | 四项真实指标、刷新与全屏已接入；代码检查通过，待人工截图，见 [首页与系统记录](Admin首页与系统管理样式核对记录.md) |
 | 客户管理 | 2 | 已有 [客户管理记录](Admin客户管理样式核对记录.md)，最终按截图复核 |
 | 国内仓 | 7 | 已有 [国内仓记录](Admin国内仓样式核对记录.md)，最终按截图复核 |
 | 货柜管理 | 4 | 已有 [货柜管理记录](Admin货柜管理样式核对记录.md)，最终按截图复核 |
 | 海外业务 | 3 | 代码已修正，代码门禁通过，待人工截图，见 [海外业务记录](Admin海外业务样式核对记录.md) |
 | 海外仓 | 10 | 已有 [海外仓记录](Admin海外仓样式核对记录.md)，尾程截图差异及省略号按钮已修正，仍需修正后截图 |
 | 客户服务 | 2 | 代码已修正，覆盖异常新增/详情、回访/再次回访及资料，见 [客户服务记录](Admin客户服务样式核对记录.md)；代码门禁通过，待人工截图 |
 | 财务管理 | 6 | 代码已修正，覆盖 11 路由、7 个页面文件及 11 处弹框声明；1950 项全量测试、类型与构建通过，待人工截图，见 [财务管理记录](Admin财务管理样式核对记录.md) |
 | 通用 | 10 | 10 菜单、14 页面代码样式已核对，1957 项全量测试、类型与构建通过，待人工截图，见 [通用资料记录](Admin通用资料样式核对记录.md) |
 | 系统管理 | 3 | 三页及新增/编辑/配置/启停/删除已核对；菜单权限恢复 720px 居中框，1961 项全量测试、类型与构建通过，待人工截图，见 [首页与系统记录](Admin首页与系统管理样式核对记录.md) |
 “已有记录”不是视觉验收通过。每组必须保留逐操作矩阵、受影响测试/类型/构建证据，以及人工在 1920×1080、100% 缩放下提供的截图结论；缺少截图标记待确认。
 ## 共享子弹框复核
 2026-09-14，已补齐订单费用新增/编辑/调整、费用驳回、订单申报编辑和货品申报编辑四处弹框的显式密度入口。保留原尺寸、表单、权限和提交行为，费用行操作按实际权限计数，不超过三个直接显示，超过三个使用纯省略号图标。
 从密度合同声明的 93 个页面/组件入口沿实际 Vue import 检查到 118 个组件，未再发现缺少显式密度入口的弹框；引用检查已纳入维护合同，覆盖静态导入及字面量动态导入。当前左侧生产导航 48 个菜单均对应已登记的页面或组件入口。后续复核发现顶部消息中心未被侧栏清单覆盖，已另行补入三个正式页面及两个组件；原 93 / 118 计数仅为该次补查范围。此项为代码覆盖检查，不代表全部页面的视觉验收。
 四处弹框相关 61 项定向测试、1971 项全量测试、类型检查、构建及 git diff --check 通过。本地 Vite 返回的排车列表、尾程订单列表均已采用纯省略号操作按钮。仍待人工在 1920×1080、100% 缩放下核对修正后的页面及弹框截图。
 ## 应用外层确认框
 沿正式路由检查后，顶部消息中心已补齐。登录、首页入口重定向与 403 属于应用外层；不机械套用业务表格密度。应用外层的退出登录、权限变化、关闭页签、离开未保存页面和新版本恢复五处确认均已显式接入公共样式，51 项定向检查通过；取消、权限和草稿保护逻辑未改变。
 | 应用外层操作 | 当前承载与依据 | 调整结论 |
 |---|---|---|
 | 退出登录 | AppLayout 现有消息确认框；原型无具体确认容器 | 保留原提示、取消与登出流程，只接入公共确认框样式 |
 | 权限变化 | AppLayout 现有警告框 | 保留未保存条目说明与关闭失权页签逻辑 |
 | 关闭页签 | WorkspaceTabs 现有未保存确认框 | 保留继续编辑、放弃并关闭以及后续焦点行为 |
 | 离开未保存页面 | router/index.ts 的现有路由守卫确认框 | 保留守卫与版本缓存失效逻辑 |
 | 新版本资源恢复 | main.ts 的现有刷新确认框 | 保留确认后刷新与放弃草稿边界，不触发真实刷新 |
 以上五处仅统一消息框密度，不改变承载方式或内容。原型未定义的保护行为沿用当前实现，人工截图待确认。
 ## 人工证据待补
 代码与离线测试不能证明最终 CSS 优先级、溢出、遮挡、缩放或长内容效果。人工按 1920×1080、100% 缩放逐项截图：
 1. 国内订单与尾程订单详情（同一页签）、排车列表（少于/等于三个与超过三个可用操作的记录），复核此前反馈。
 2. 顶部消息中心的三个列表、消息和模板新增/编辑、任务/消息详情抽屉，确认字段换行、滚动及底部按钮。
 3. 各模块记录中尚未取得的新增、编辑、审核/确认、文件预览、删除/停用、未保存保护等状态截图，逐操作闭环，不以一张列表图代替详情或弹框。
 在上述证据补齐前，全模块视觉目标保持未完成。不得把已登记组件检查与全量测试通过写成已完成所有页面视觉验收。
 ## 本轮最终代码门禁
 最终 253 个文件 / 1982 项全量测试、类型检查、构建和 git diff --check 通过。消息中心 42 项、应用外层 51 项、国内仓确认框 184 项定向检查通过（这些集合存在共享合同重叠，不将其简单相加）。实际引用链覆盖 123 个 Vue 组件的 56 处业务消息框调用，以及应用外层五处确认。原有业务脚本在排除样式导入、customClass 与此前已确认的费用按钮计数函数后保持一致。
 未部署，未向真实账号发送消息，未操作数据库或业务记录。不将代码门禁视为全模块视觉验收通过。
 ## 2026-09-15 浏览器截图验收
 用户已明确授权内置浏览器在测试环境截图，后续不再以缺少人工截图授权作为阻塞原因。本批按 1920×1080、100% 缩放取得 10 张截图，见 [测试环境截图验收记录](Admin测试环境截图验收记录-20260915.md)。国内与尾程订单详情基本信息、排车按钮和编辑弹框已取得实际页面证据。
 测试首页和消息模板仍未呈现本地最新样式；需获得单独的 Admin 测试部署授权并确认版本，再继续完整验收。其余页面和状态仍待逐项核对，本批不代表全模块通过。
@@ -0,0 +1,153 @@
 # Admin 国内仓样式核对记录
 ## 与客户管理共用样式的维护收敛
 本次按用户确认，仅整理国内仓与客户管理已接入范围的样式归属；不新增页面、业务操作或环境写入。此前界面验收截图不作为本次收敛后的截图证据，本次仍待人工截图确认。
 | 国内仓入口/消费者 | 公共层收敛 | 业务例外与边界 |
 |---|---|---|
 | 订单列表及详情 | 公共描边按钮、详情页签、连续信息表、表格基础密度 | 操作资格、详情字段跨列与业务数据排列保留 |
 | 订单测量与审核、称重图片 | 字号、间距、行高使用公共变量，弹框标题/正文/底部由公共层管理 | 1560px / 92vh 作业宽高、图片/画布尺寸、测量对照列保留 |
 | 预装列表与详情、模拟柜与托盘码弹框 | 字号、间距、表格及弹框使用公共规则 | `isPreload` / `dense` 继续显式控制，共用组件未接入入口使用原布局；PDF 标签尺寸不变 |
 | 库位、托盘 | 删除重复弹框框架，统一控件/字号/间距变量 | 560px 编辑宽度、双列表单和业务字段保留 |
 | 整柜业务与库存详情 | 摘要引用公共变量，库存详情使用公共信息表 | 出入库分组、库存事实和交易表结构保留 |
 默认值唯一入口为 `src/styles/adminDensityTokens.css`，公共外观唯一入口为 `src/styles/adminDensity.css`；业务 CSS 不重新定义按钮配色或密度默认值。维护合同与后续接入规则见《Admin 高密度界面规范》的“国内仓、客户管理的样式维护边界”。
 ## 订单共享子弹框补查矩阵（2026-09-14）
 从订单页实际 import 追踪到以下两个组件，当前仅由 `UnifiedOrdersView.vue` 调用。原有订单页密度根不能覆盖其 Teleport 弹框。依据本轮统一要求补齐显式入口，保持当前业务合同和以下承载，不恢复原型旧字段。矩阵对应实际组件模板及页面调用，而非仅凭原型推断。
 | 组件与操作 | 当前承载 / 尺寸 | 核对结论 |
 |---|---|---|
 | `InboundFeeDetailManager.vue` 新增、编辑、已审核费用调整 | 680px 居中框、两列表单 | 保留应收/应付、结算方式、已付字段、凭证、金额及版本；显式接入弹框和表单密度，长备注/凭证整行。 |
 | 同组件审核、驳回、删除、作废 | 审核为原行内动作；驳回为 AppDialog 默认 560px；删除/作废独立确认框 | 保留权限和状态。待审核最多四个可用操作，超过三个才将删除收起；三项以内全部直显；已审核的调整/作废两项直显。 |
 | `OrderDeclarationEditorDialog.vue` 订单申报、渠道修改 | 1180px 居中框；渠道变更另有确认框 | 保留四项只读信息、订单级五项表单、原货品表及渠道确认内容；只让弹框正文滚动，去掉内部重复滚动容器。 |
 | 同组件货品申报编辑 | 980px 居中框、四列 22 项字段 | 保留“应用本项”、字段顺序、长备注跨列及原校验，行内编辑使用共享描边按钮。 |
 上述四处弹框已补齐公共密度入口，61 项定向测试、1971 项全量测试、类型检查、构建和 git diff --check 通过；仍待人工截图确认。保留计费、凭证上传、审核资格、货品项序号、仓库实测和订单版本请求。
 ## 2026-09-14 接手复核：订单列表与详情样式失效
 用户在本地订单列表发现按钮回退，并提供详情截图：页签呈浏览器默认按钮，基本信息退回逐项竖排。复核发现 `UnifiedOrdersView.vue` 的列表与详情共用外层缺少 `admin-density`；子项虽已改为公共类，公共选择器和变量却无法生效。已在两种路由共用的页面外层补回入口。
 维护合同新增模板祖先检查，覆盖订单与客户页面中的公共操作按钮、页签、信息表；避免仅凭 CSS 导入和子项类名存在就判为通过。用户截图确认的是修复前问题，修复后仍待 1920×1080、100% 缩放人工截图确认。
 本次验证：订单页面与公共密度定向测试 48/48、`pnpm typecheck`、`pnpm build` 和差异空白检查通过；AGENTS 索引合同 1050 项通过。当前工作区全量测试 1910/1911 通过，唯一失败为费用项目页面的 5000ms 超时，该文件单独复跑 5/5 通过；不将这次全量运行记录为全部通过。验证覆盖工作区现有在途代码，未提交或部署。
 ## 国内仓 7 个菜单统一复核与返回入口调整（2026-09-14）
 用户要求按全部 7 个菜单继续收敛，并提供整柜库存详情返回按钮独立于信息区的截图。本次取消“只有订单列表采用描边行内按钮”的旧范围例外；列表权限、操作资格、加载/禁用状态、确认与保存事件不变。
 | 菜单 | 本次核对和调整 | 详情与弹框范围 |
 |---|---|---|
 | 订单列表 | 保留修复后的页面密度根与公共描边按钮 | 详情七个页签、测量/审核及页面内弹框；返回接入公共轻量导航 |
 | 订单测量 | 行内测量为紫色、查看为灰色，移除装饰图标 | 共用测量作业、手动录入、图片预览和称重确认 |
 | 测量数据审核 | 行内审核为橙色、查看为灰色，移除装饰图标 | 共用审核工作区、测量图片和确认窗口 |
 | 预装清单 | 查看接入灰色描边；通过 `isPreload` 隔离共用组件 | 详情行内备注、返回、运输信息/备注/确认弹框、模拟柜和托盘打印；已确认清单模式不变 |
 | 库位管理 | 编辑灰色、启用绿色、停用/删除红色；按钮组间距使用公共规则 | 560px 编辑弹框、确认消息保持显式密度入口 |
 | 托盘管理 | 编辑灰色、删除红色；按钮组间距使用公共规则 | 560px 编辑弹框及删除确认 |
 | 整柜业务 | 查看库存接入灰色描边 | 新建入库/出库弹框；库存详情返回、编号、状态与基本信息合并为一个白底区，交易记录保留独立分区 |
 维护检查覆盖导航中的精确 7 个入口、测量/审核/预装入口的实际共享组件模式、独立打开页面所需的 CSS 导入、公共样式的模板祖先，以及弹框自身的接入类。不能把进入过订单页后其他页面“看起来正常”当作独立入口通过。用户截图属于调整前证据，全部修改后的视觉状态仍待 1920×1080、100% 缩放人工截图确认。
 本次同时消除公共按钮组 6px 间距与 `DataTable` 默认 8px 左边距叠加的问题；未接入按钮仍使用原默认值。验证结果：7 页及详情定向测试 142/142、全量测试 249 个文件与 1913 项测试通过；最终表格间距合同及 DataTable 回归 28/28 通过，类型检查、构建与 AGENTS 索引合同 1050 项通过。未执行部署或业务数据写入。
 ## 向后续模块复用前的规则核对（2026-09-14）
 复核发现“父子订单关联”抽屉遗漏 `admin-density-drawer`，已补回并增加抽屉独立入口检查。公共斑马纹、描述表标签背景和按钮悬停色现统一由变量消费。完整发现、验证结果和后续接入结论见 [客户管理核对记录](Admin客户管理样式核对记录.md) 的“向后续模块复用前的规则核对”；货柜管理入口与共享边界见 [货柜管理核对记录](Admin货柜管理样式核对记录.md)。这次复核不将历史截图视为新效果验收证据。
 ## 首轮国内仓验收依据（历史记录）
 依据：已确认订单样板与 [Admin 高密度界面规范](Admin高密度界面规范.md)。首轮覆盖第 1、2、3 组。当时用户明确要求由 AI 在 1920×1080、100% 缩放下进行界面验收；该授权只用于当轮界面检查。
 ## 改造前逐操作矩阵
 原型路径前缀为 `docs/悦/货代SAAS平台后台/prototype-src/`。保留实际业务入口、权限、提交与关闭语义，仅收敛密度。
 | 页面 | 操作及当前承载 | 原型/代码依据 | 实施结论 |
 |---|---|---|---|
 | 订单测量 | 列表、详情跳转订单页 | `modules/02-domestic-warehouse.html:1465`；InboundTaskList | 紧凑表格，复用已确认订单详情 |
 | 订单测量 | 测量作业居中弹框、全屏 | `overlays.html:720`；InboundMeasurementDialog | 1560px、92vh，固定标题和底部操作 |
 | 订单测量 | 手动录入、测量原图、称重确认居中弹框 | InboundMeasurementPanel、WeightOcrPanel | 原有宽度与字段，统一边距及正文滚动；原图保留可读尺寸 |
 | 测量审核 | 列表、审核居中弹框 | `overlays.html:811`；InboundTaskList、MeasurementReviewPanel | 1560px 审核工作区，操作栏可见，紧凑对比与明细 |
 | 测量审核 | 审核通过二次确认、称重修正与原图 | MeasurementReviewPanel.confirmApprove、WeightOcrPanel | 保留确认、原因及权限；当前没有驳回按钮，不恢复历史操作 |
 | 预装清单 | 列表、详情独立路由 | `modules/06-containers.html:1105,1118`；PreloadPlanDetailView | 使用可用页面宽度，摘要与历史表格 |
 | 预装清单 | 新增模拟柜居中弹框 | ContainerSimulationCreate | 仅预装入口显式接入密度，保留当前业务流程 |
 | 预装详情 | 补录/纠正运输信息、编辑仓库备注、确认预装居中弹框 | PreloadPlanDetailView 的三个 AppDialog | 统一标题、正文、操作区；尺寸随内容保留 |
 | 预装详情 | 打印托盘码居中弹框与 PDF 输出 | PalletLabelPrintDialog；`overlays.html:1902` 为历史标签预览 | 保留当前 PDF 下载流程和标签尺寸，只调整选项容器 |
 | 库位管理 | 列表、新增/编辑居中弹框 | `modules/02-domestic-warehouse.html:1807,1827` | 紧凑列表与双列表单，保留 560px 宽度 |
 | 库位管理 | 启用/停用、删除二次确认 | LocationsView.toggleStatus/removeLocation | 保留业务文案、禁用、危险语义 |
 | 托盘管理 | 列表、新增/编辑居中弹框、删除确认 | `modules/02-domestic-warehouse.html` 的 modal-pallet；PalletsView | 大统计卡改摘要行；当前路由没有托盘独立详情，不新增历史页面 |
 | 整柜业务 | 入库/出库/库存页签与列表 | `modules/02-domestic-warehouse.html:1897` | 38px 彩色图标页签，库存统计改摘要行 |
 | 整柜业务 | 新增入库、新增出库居中弹框 | `modules/02-domestic-warehouse.html:1931` 及相邻出库弹框 | 720px 双列表单，固定操作区 |
 | 整柜库存 | 库存详情独立路由、交易记录 | `modules/02-domestic-warehouse.html:1923` | 四列连续描述表，长文本换行，紧凑流水表 |
 预装完成后的跳转进入货柜管理既有详情，不扩大到全部货柜菜单。共享组件须显式接入，其他入口默认不受影响。
 ## 验收结果
 2026-09-14 完成第 1、2、3 组实现和首轮浏览器界面验收。视口为 **1920×1080，缩放 100%**，使用当前本地 Admin 页面与现有测试数据。下表只表示实际检查到的界面，不代表写入流程或全部权限状态通过。
 | 范围 | 实际检查 | 结论与本轮修正 | 截图证据 |
 |---|---|---|---|
 | 订单测量 | 列表、测量作业、手动录入、全屏/退出全屏、取消与重开；另从订单列表进入共用测量工作区 | 1560px 作业框及固定底部可用；修正样式优先级，使五项实测摘要保持一行；缩小表单组间距 | [测量工作区](../.codex-temp/admin-density-acceptance/order-measurement.png) |
 | 测量审核 | 9 条待办；单票审核、测量原图、含托盘毛重修改、审核通过二次确认；勾选后批量审核确认并取消 | 审核框按内容自然收高；修正箱规、时间列宽，避免尺寸和时间截断；称重图与数据紧凑并列，原图窗口保留查看面积 | [审核工作区](../.codex-temp/admin-density-acceptance/measurement-review.png)、[称重修正](../.codex-temp/admin-density-acceptance/review-weight.png)、[批量确认](../.codex-temp/admin-density-acceptance/review-batch-confirm.png) |
 | 预装清单 | 列表、新增模拟柜、两票明细详情、长船名、仓库备注、补录运输信息、打印托盘码选项 | 摘要四列、客户跨列、历史改紧凑表格；修正长表头单位换行及订单/SKU/客户列宽；缺少订舱或 PDA 已开始时，原禁用与只读提示保持可见 | [列表](../.codex-temp/admin-density-acceptance/preload-list.png)、[详情](../.codex-temp/admin-density-acceptance/preload-detail.png)、[备注](../.codex-temp/admin-density-acceptance/preload-remark.png)、[运输信息](../.codex-temp/admin-density-acceptance/preload-transport.png)、[打印选项](../.codex-temp/admin-density-acceptance/preload-print.png) |
 | 库位管理 | 96 条记录列表、新增双列表单、状态筛选空态、查询重置、加载失败后重试 | 560px 表单完整显示；系统库位/占用库位操作限制保留；仓库名称与编码为两行，允许行高自然增长 | [列表](../.codex-temp/admin-density-acceptance/locations-list.png)、[表单](../.codex-temp/admin-density-acceptance/location-editor.png)、[空态](../.codex-temp/admin-density-acceptance/locations-empty.png) |
 | 托盘管理 | 7 条记录列表、新增、已有托盘编辑后取消 | 统计改摘要行；560px 双列表单完整显示，容积、重量、颜色和备注保持原字段 | [列表](../.codex-temp/admin-density-acceptance/pallets-list.png)、[新增](../.codex-temp/admin-density-acceptance/pallet-create.png)、[编辑](../.codex-temp/admin-density-acceptance/pallet-edit.png) |
 | 整柜业务 | 入库、出库、库存三个页签；新建入库/出库弹框；部分出库库存详情及 3 条交易记录 | 彩色页签、摘要行、720px 双列表单、四列描述表正常；长单号列表省略，详情交易表显示完整编号；底部操作可见 | [入库](../.codex-temp/admin-density-acceptance/container-inbound.png)、[出库](../.codex-temp/admin-density-acceptance/container-outbound.png)、[库存](../.codex-temp/admin-density-acceptance/container-inventory.png)、[入库表单](../.codex-temp/admin-density-acceptance/container-inbound-editor.png)、[出库表单](../.codex-temp/admin-density-acceptance/container-outbound-editor.png)、[库存详情](../.codex-temp/admin-density-acceptance/container-detail.png) |
 | 已确认订单样板回归 | 订单列表测量入口、详情基本信息、状态历史 | 共用样式提取后测量正常；补齐订单页通用弹框样式导入；彩色页签、连续描述表与历史表保持 | [基本信息](../.codex-temp/admin-density-acceptance/order-detail.png)、[状态历史](../.codex-temp/admin-density-acceptance/order-history.png) |
 截图位于当前工作区临时验收目录，不作为应用资源或构建产物提交；需要长期归档时应另行保存这些证据。
 ### 自动检查
 - `pnpm typecheck`：通过。
 - `pnpm test`：247 个测试文件、1899 项测试通过。此前一次并行负载下费用项目页面测试超时，单独复跑 5/5 通过，随后完整重跑也全部通过。
 - `pnpm build`：通过。
 - `git diff --check`：通过。
 - 后端根 `./scripts/agents-index-contract.ps1`：1050 项离线索引检查通过，不访问业务服务或数据库。
 ### 覆盖边界与发现
 1. 所有新增、保存、提交审核、确认预装和删除等业务写入均未执行；打印只检查选项窗口，未生成 PDF。本轮检查的是样式与可达交互，提交成功、服务端校验失败、处理中关闭等业务结果不列为实页通过。
 2. 已访问的预装记录处于未关联订舱、PDA 作业中或已确认状态，未进入可提交的“确认整份预装计划”窗口。该窗口已接入统一样式并通过代码测试，实际可确认状态仍待补充截图。库位现有可用记录为系统 A0，其余样本为占用状态，编辑、启停及删除确认未取得实页证据；保留原权限与限制，不为截图改动测试数据。
 3. 未切换账号验证全部无权限状态，也未穷举大批量照片、多页长表、所有业务状态。本轮称重原图样本为红色测试占位图片，只能验证图片承载与窗口布局，不能代表真实照片清晰度验收。
 4. 测量草稿的客户名称显示“客户未命名”，而相同订单的列表/详情有客户名称，作为既有数据展示问题记录；本轮未修改客户映射与业务接口。
 5. 库位首次加载曾失败，重试后正常。后续审核页客户筛选出现“服务暂时不可用”，待办数据仍显示；错误提示没有遮挡列表，见 [筛选加载失败](../.codex-temp/admin-density-acceptance/review-filter-error.png)。不将环境服务可用性计入视觉通过。
 6. `LoadingListDetailDrawer` 同时供预装和已确认清单使用：历史记录的表格结构会影响这两个消费者，既有筛选和排序保持不变；其余紧凑间距仅预装入口启用。模拟柜创建、托盘码打印通过可选 `dense` 参数接入，其他入口未改变默认密度。
 本轮未部署、未修改数据库或测试业务数据。规则与实现可以作为国内仓后续样式维护基线；上列未覆盖状态补齐后再作完整业务验收结论。
 ## 人工验收调整：订单列表行内按钮
 用户提供参考图 `codex-clipboard-3cab512c-3b1a-412c-9a6d-1cbf796bf020.png`，要求订单列表采用该按钮风格。
 | 页面/操作 | 参考依据 | 当前承载与调整 | 验收状态 |
 |---|---|---|---|
 | 订单列表：详情 | 参考图深灰纯文字、白底细边框 | 保留独立详情页跳转；移除按钮前图标，采用深灰文字 | 待人工截图确认 |
 | 订单列表：通过 | 参考图橙色审核按钮 | 保留订单审核弹框与确认流程；改橙色文字及浅橙边框 | 待人工截图确认 |
 | 订单列表：测量 | 参考图紫色业务操作按钮 | 保留测量作业弹框；改紫色文字及浅紫边框 | 待人工截图确认 |
 | 订单列表：备注、更多 | 参考图普通描边按钮 | 备注用深灰纯文字；更多保留省略号及原下拉操作，不改变权限和排列顺序 | 待人工截图确认 |
 所有行内按钮保持 28px 高度，按钮间距 6px；白底无阴影、细边框、6px 圆角。悬停、键盘焦点、处理中和禁用反馈保留。未调整顶部工具栏及弹框操作，未增加参考图中的客户管理功能。通用说明同步到《Admin 高密度界面规范》的“订单列表行内按钮”。
 本次 `pnpm typecheck`、`pnpm test`（247 个文件、1899 项测试）、`pnpm build` 和 `git diff --check` 均通过。未部署；待用户在 1920×1080、100% 缩放下提供本次按钮截图。之前首轮验收截图不作为本次按钮效果通过的证据。
 ## 脚本确认框补查（2026-09-14）
 沿已登记组件的实际引用检查发现八处 ElMessageBox 确认未显式接入密度。以下均保留当前确认框承载、原提示和操作逻辑；本次仅补充 customClass。
 | 页面 / 操作 | 当前承载与结论 |
 |---|---|
 | 国内托盘删除 | 原有删除确认框；保留危险按钮和占用门禁提示 |
 | 国内库位启用/停用 | 原有状态确认框；保留不同状态的标题、提示与版本 |
 | 删除称重图片 | 原有确认框；保留本票库位不会释放说明 |
 | 测量加载最新版本 | 原有放弃草稿确认框；保留继续编辑 |
 | 提交测量数据 | 原有提交确认框；不改变校验及提交顺序 |
 | 关闭未保存测量窗口 | 原有放弃修改确认框；保留取消后停留 |
 | 订单解除同柜组 | 原有解除确认框；保留原有资格、提示和接口 |
 | 入库费用作废 | 原有作废确认框；保留费用版本与原因校验 |
 184 项定向检查通过；最终 253 个文件 / 1982 项全量测试、类型检查、构建和 git diff --check 通过。八处确认框均仅补充显式密度入口，提示、权限、版本和提交逻辑未变。人工截图待确认。
@@ -0,0 +1,24 @@
 # Admin 客户服务样式核对记录
 范围为导航“客户服务”的异常订单、客户回访两页及其实际可达弹框，源码位于 `apps/admin-web/src/modules/overseas-warehouse/pages/`。与海外仓 10 菜单分开记录。
 | 页面/操作 | 原型证据 | 当前承载 | 本轮修正 |
 |---|---|---|---|
 | 异常订单查询/查看 | `prototype-src/modules/04a-customer-service.html` 第 1 行 | `ExceptionOrdersView` 列表与 760px 只读详情框 | 查看采用纯文字描边按钮；详情保留双组描述表与长原因/处理动作，接入弹框密度 |
 | 新增异常订单 | `prototype-src/overlays.html` 第 1572 行 `modal-dispatch-exception-create`，620px | 760px 居中框，比历史原型增加箱数和 SKU 字段 | 保留现宽度与双列表单，原因跨行，保留关联解析、冲突提示和保存状态 |
 | 异常处理/删除 | 第 1586 行历史处理框 | 当前列表只有查看，未开放处理/删除入口 | 不恢复历史操作，不将不存在的操作记作通过 |
 | 客户回访列表与统计 | `04a-customer-service.html` 第 21 行起 | `CustomerVisitsView`，3 个统计卡与单个回访/再次回访按钮 | 统计改紧凑摘要；按权限保留单个纯文字操作，无省略号菜单 |
 | 回访/再次回访 | `overlays.html` 第 4 行 `modal-customer-followup`，720px | 920px 居中框，增加实际入仓单选择，允许较长反馈和附件 | 保留现宽度；订单上下文改连续描述表，压缩可选入仓单布局，保留选择状态、反馈、备注、保存校验 |
 | 资料上传/移除 | 同上，原型文件选择与文件列表 | 系统文件选择，回访保存前可移除附件 | 使用可聚焦的原生按钮触发文件选择，附件移除使用纯文字危险按钮，保留文件类型/大小限制与客户作用域 |
 当前模板未提供独立回访详情路由或文件预览入口，不增加新业务能力。业务返回字段、状态机和权限保持现有契约。
 代码修正已完成；修正后所有页面和弹框待人工在 1920×1080、100% 缩放截图确认。
 ## 本轮检查结果
 - 全量 251 个测试文件、1,942 项通过；类型检查、生产构建及差异空白检查通过。
 - 密度合同已纳入本组全部页面和真实 Teleport 弹框，覆盖公共样式独立导入、实际祖先、行内按钮、标签与字号规则。
 - 本组视觉仍待人工截图确认；代码和组件测试不代表页面视觉验收。
 - 回归覆盖异常新建权限、订单关联与冲突、只读详情、处理人 ID 隐藏、回访必填/客户范围、文件选择按钮和附件上传；入仓单选择及附件语义保持原样。
@@ -0,0 +1,104 @@
 # Admin 客户管理样式核对记录
 ## 范围与依据
 按当前客户管理导航的两个入口：客户列表、海外仓阶梯费用；客户详情及两个入口实际调用的编辑、审核、预览一并收敛。用户要求按钮使用纯文字，避免图标占位；详情页签保留已确认的彩色 Emoji。沿用《Admin 高密度界面规范》，验收视口为 1920×1080、100% 缩放。
 本轮开始时客户编辑已有 1120px、三列表单，详情联系信息已有三列调整；保留这些在途改动并在其基础上处理密度，不回退业务逻辑。
 ## 逐操作矩阵
 原型入口：`docs/悦/货代SAAS平台后台/prototype-src/modules/01-customers.html` 的 `page-tenant-list`、`page-warehouse-tier-fee`、`page-tenant-detail`。当前用户确认的密度及按钮要求优先于历史装饰。
 | 页面/操作 | 当前承载 | 调整目标 |
 |---|---|---|
 | 客户列表、筛选、行内操作 | 标准列表 | 13px 正文、36px 基准行高，28px 白底描边纯文字操作，保留直接操作数量与更多菜单 |
 | 新增/编辑客户 | 1120px 居中弹框、三列表单 | 保留字段、联络信息说明与资质上传，紧凑分区、正文滚动、底部操作可见 |
 | 客户入驻审核 | 1040px 居中弹框 | 企业资料连续描述表、资质表，保留同意/驳回与理由 |
 | 创建/审核结果、重置密码、跳转登录、删除 | 各自居中弹框 | 统一密度与纯文字按钮；凭证、复制、确认和失败行为保留 |
 | 资质文件预览 | 居中弹框 | 保留原图/PDF 查看面积与加载反馈 |
 | 客户详情基本信息 | 独立页面 | 紧凑头部、38px 彩色页签，企业和联络信息用连续键值表，资质和企业成员用紧凑列表 |
 | 客户详情计费规则 | 箱规表、权重系数表及编辑弹框 | 收紧标题与行距，保留公式、默认规则、权限与保存语义 |
 | 客户详情海外仓费用 | 阶梯表及编辑弹框 | 紧凑分组表，保留币种、档位、单位与未保存确认 |
 | 客户详情操作日志 | 标准列表及详情抽屉 | 紧凑表格、描述表，保留既有抽屉承载、快照、错误诊断 |
 | 海外仓阶梯费用 | 标准列表及 1120px 编辑弹框 | “天数：单价”连续排列并整组换行、币种单列，两类费用并排编辑，保留原增删档位校验 |
 ## 验证
 ### 人工截图反馈：更多入口与阶梯费用
 依据本轮用户提供的海外仓阶梯费用单行截图（`codex-clipboard-60f898d1-3c3c-49ba-8eda-b741e40bbd6d.png`）及“请同步”的确认：
 | 页面/操作 | 当前截图或实现 | 本轮处理 |
 |---|---|---|
 | 客户列表更多操作 | 文字“更多”，与订单列表省略号不一致 | 统一 `MoreHorizontal` 三点入口，保留悬停提示和可访问名称；菜单项纯文字 |
 | 订单列表更多菜单 | 三点入口，菜单项带图标 | 保留三点入口，菜单项改为纯文字 |
 | 海外仓阶梯费用列表 | 档位分成两列白底块，每档重复币种、行高较大 | 改为“天数：单价”连续排列，按原档位顺序整组换行；币种只在独立列出现，计费单位在表头；空档位显示“—” |
 | 海外仓阶梯费用编辑 | 原 1120px 双费用分组弹框 | 保留当前承载、字段与增删校验；后续按钮反馈补齐新增/删除白底描边样式 |
 本轮修改后的截图待人工确认，原截图只作为问题证据。三点入口与连续阶梯展示完成后重新执行类型检查、全量测试、构建及差异检查，结果如下。
 后续按钮反馈补充：源码中列表“编辑”已经接入 `customer-action-button`，本次增强其选择器和 Element Plus 状态变量，明确灰字白底细描边及焦点反馈；阶梯编辑弹框的“新增阶梯、删除”此前仍使用默认按钮，本次补齐蓝/红语义描边，并同步客户详情同类费用编辑。没有将源码检查等同于用户当前环境已经生效，最终外观仍待人工截图确认。
 按钮补齐后再次验证：`pnpm typecheck`、`pnpm test`（247 个文件、1901 项）、`pnpm build` 和客户模块差异检查均通过；未部署。
 2026-09-14，本轮样式实现及代码验证完成：
 - `pnpm typecheck`：通过。
 - `pnpm test`：247 个测试文件、1901 项测试全部通过，包含客户模块、客户操作日志及订单列表的直接影响测试。原有图标和弹框类名断言按本轮确认更新，保留 API、权限、保存与错误处理断言。
 - `pnpm build`：通过。
 - 本轮客户模块、客户操作日志与订单列表的 `git diff --check`：通过。
 视觉状态为 **待人工截图确认**。没有用代码检查代替截图验收，没有沿用国内仓截图作证据；未部署、未进行业务写入。测试输出包含已有的其他页面 `query` 常量绑定编译提示，不影响本轮检查通过。
 ## 实现入口与影响边界
 - 页面显式接入 `admin-density customer-density`，相关居中弹框显式接入 `admin-density-dialog customer-density-dialog`，Teleport 后仍应用密度规则。
 - 客户专用样式位于 `apps/admin-web/src/modules/customers/customerDensity.css`；基础密度复用 `src/styles/adminDensity.css`。本轮没有修改全局默认样式或共享组件接口。
 - `CustomerAuditLogsPanel.vue` 当前由客户详情消费，本轮调整其详情按钮和日志抽屉间距、描述表。保留原抽屉、快照和诊断信息。
 - 纯文字规则覆盖业务操作与带文案的查询、重置、复制；分页箭头、列设置、筛选布局、关闭、全屏及加载反馈继续可见，避免出现空按钮。
 - 客户列表白底描边按钮按既有操作权限和直接操作数量显示，更多入口统一三点 `…`，不显示“更多”文字；菜单项纯文字。未修改状态、权限、API 或计费口径。
 ## 样式维护收敛（国内仓、客户管理）
 按用户确认，将两模块共用的默认值和通用外观合并到公共层：
 | 范围 | 接入内容 | 保留的业务配置 |
 |---|---|---|
 | 客户列表、阶梯费用列表及编辑弹框 | `density-action` + `data-tone`，按钮交互状态只维护一份 | 操作权限、配色语义、直接操作数量、三点更多 |
 | 客户详情、订单详情 | `density-tabs` / `density-tab-icon`；信息表接入 `density-fields` | 页签标签和事件，四列/三列、字段跨列 |
 | 客户审核 | 公共弹框框架及 `density-fields` | 1040px 宽度、审核资料分组、96px 标签宽度 |
 | 客户规则与费用 | 公共字号/间距/行高变量 | 规则公式、阶梯顺序、两类费用分组与编辑宽度 |
 | 客户操作日志 | 公共密度变量、`admin-density-drawer` | 日志详情抽屉、结果与快照布局 |
 `customerDensity.css` 中重复的按钮、页签、信息表基础规则已上移；客户 Vue 文件中被模块样式覆盖的旧声明已清除，不再保留旧卡片尺寸后用更强选择器覆盖。此前记录提到的 `customer-action-button` 已由公共 `density-action` 替换，属于样式归属调整。
 维护规则见《Admin 高密度界面规范》的“国内仓、客户管理的样式维护边界”。`src/styles/adminDensity.test.ts` 检查 21 个明确消费者及其模块 CSS：禁止业务选择器进入公共层、禁止页面重复实现按钮、禁止在页面重定义密度默认值、检查所有变量引用已定义。此次代码收敛后的视觉状态仍为待人工截图确认。
 ## 向后续模块复用前的规则核对（2026-09-14）
 本次按实际代码核对国内仓和客户管理样板、公共 CSS、变量、维护合同与应用指引，并以货柜管理的真实菜单/路由检查规范能否复用。
 | 检查项 | 发现与处理 | 证据范围 |
 |---|---|---|
 | 客户详情返回 | 原按钮尚未接入公共返回样式，现使用 `link` + `density-back`；保留纯文字及返回客户列表的事件 | 页面代码及返回入口合同；新视觉待截图 |
 | 客户日志行内按钮 | 仍使用独立链接按钮，现接入灰色 `density-action`；日志面板自身导入公共 CSS 并显式接入密度根 | 独立组件入口、权限与详情查询测试 |
 | 公共颜色变量 | 斑马纹和描述表标签底色绕过了已定义变量，已接回；各语义按钮悬停浅底改由公共变量提供 | 变量定义、消费与状态规则合同 |
 | 浮层覆盖 | 国内仓父子订单关联抽屉缺少独立密度类，已补齐；合同新增抽屉检查 | 弹框/抽屉显式入口，不依赖页面祖先 |
 | 后续接入说明 | 增加完整页面/弹框示例、共享模式边界、检查清单扩展与代码/视觉证据界限 | 《Admin 高密度界面规范》“新模块接入规则”及 Admin 指引 |
 结论：公共基线和接入规则可用于后续 Admin 页面；新增页面仍须逐操作接入和验收，不能只导入 CSS 就称为完成。货柜管理 4 个菜单及 DOMESTIC/OVERSEAS 共享边界已登记在 [货柜管理核对记录](Admin货柜管理样式核对记录.md)，尚未实施其页面改造。
 本次定向测试 85/85、全量测试 249 个文件与 1915 项测试、类型检查、构建、AGENTS 索引合同 1050 项及文档链接检查通过。未执行部署或业务数据写入；修复后的页面视觉仍待人工截图确认。
 ## 人工验收步骤
 统一采用 1920×1080、浏览器缩放 100%。每项包含空态、长内容、禁用及加载反馈；涉及真实业务提交时按人工验收数据操作。
 1. 客户列表：筛选、查询/重置、列设置、分页，以及按钮最多的行；核对按钮间距和颜色、更多菜单、权限变化后的操作列。
 2. 新增/编辑客户：三列表单、校验提示、长公司名称、资质上传与有效期；检查滚动、底部按钮、全屏和重开。
 3. 客户审核与凭证相关弹框：企业资料、资质预览、审核理由、密码显示/复制、跳转登录理由及删除确认；核对信息完整和处理中锁定。
 4. 客户详情：基本信息四组字段、联系信息三组字段、长地址/邮箱/文件名、资质预览及企业成员表；核对彩色页签与返回/编辑按钮。
 5. 计费规则及海外仓费用：只读分组、默认规则入口、规则编辑、币种与多档阶梯、取消和未保存提示；核对单位、公式与底部操作。
 6. 操作日志：筛选、详情抽屉、成功/失败记录及快照长内容。
 7. 海外仓阶梯费用列表：多档位行、横向空间、编辑弹框两类费用并排、档位增删后的表格及校验。
@@ -0,0 +1,139 @@
 # Admin 按钮与订单状态颜色清单
 核对日期：2026-09-15。以下为当前工作区源码事实，不代表测试环境已部署。范围为公共按钮样式、公共状态徽标、国内订单列表/详情/审核状态、海外尾程订单列表与详情；不是所有业务模块的完整状态机盘点。清单先按源码盘点；后续已补齐的预装清单颜色映射单列记录。业务状态与状态文案未调整。
 ## 统一情况与修改入口
 | 对象 | 当前统一程度 | 修改入口 |
 |---|---|---|
 | 接入 `density-action` 的行内按钮 | 色值、边框、悬停/禁用/焦点、尺寸集中；页面通过 `data-tone` 选择语义 | `apps/admin-web/src/styles/adminDensityTokens.css`、`adminDensity.css` |
 | 顶部查询/新增/提交等 Element 按钮 | 使用基础主题，与行内按钮是两套色板 | `apps/admin-web/src/styles/foundation.css`，Element 主题 |
 | `StatusBadge` 订单状态徽标 | 公共外观已集中；颜色仍直接写在 CSS 中；按中文文案判断类型 | `apps/admin-web/src/shared/components/StatusBadge.vue`、`src/styles/index.css` |
 | 国内订单状态文案 | 状态码到文案集中；文案到颜色在另一处 | `apps/admin-web/src/modules/unified-orders/status.ts` |
 | 尾程订单详情 | `OverseasDetailShell` 的 `dense` 分支复用 `StatusBadge` | `apps/admin-web/src/modules/overseas-warehouse/components/OverseasDetailShell.vue` |
 | 尾程订单列表 | “当前状态”直接输出文本，没有状态徽标插槽 | `apps/admin-web/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue` |
 | 扣货状态等 `el-tag` | 独立走 Element 标签主题，不等同于 `StatusBadge` | 对应页面 `type/effect` + 基础主题 |
 结论：有公共入口，但尚未形成全应用唯一色板、唯一状态映射和唯一状态展示组件。修改按钮色不会同步修改订单状态徽标。
 ## 行内按钮色板
 普通背景均为白色 `#fff`；文字与边框分别配置。默认蓝色已经按用户确认改为 `#1777ff`。
 | 语义 / `data-tone` | 文字颜色 | 普通边框 | 悬停背景 | 现有用途示例 |
 |---|---|---|---|---|
 | 默认 / 省略或 `neutral` | `#1777ff` | `#dfe3ee` | `#f8fafc` | 详情、编辑、备注、省略号 |
 | 主要 / `primary` | `#1677cf` | `#bfdbfe` | `#eff6ff` | 指定为主要操作的行内按钮 |
 | 成功 / `success` | `#15803d` | `#bbf7d0` | `#f0fdf4` | 启用 |
 | 警告 / `warning` | `#c76500` | `#fed7aa` | `#fff7ed` | 审核、暂扣等需注意的操作 |
 | 危险 / `danger` | `#dc2626` | `#fecaca` | `#fef2f2` | 停用、删除、驳回 |
 | 紫色 / `purple` | `#7c3aed` | `#ddd6fe` | `#f5f3ff` | 测量、重置密码 |
 `warning`/`danger` 是按钮操作的语义，不会根据“异常”“成功”“失败”等按钮文字自动识别。页面需要显式选择类型。
 | 交互状态 | 公共规则 |
 |---|---|
 | 普通 | 高 28px、圆角 6px、白底、1px 描边，13px / 600 字重，padding 4px 10px |
 | 悬停 | 文字保持语义色，边框变为文字同色，背景使用上表悬停色 |
 | 按下 | Element active 色变量使用相同语义色和悬停背景 |
 | 键盘焦点 | 2px 同语义色轮廓，外偏移 2px |
 | 禁用 | 文字 `#a1a1aa`、边框 `#e5e7eb`、白底；文字颜色目前直接写在 `adminDensity.css` |
 | 加载中 | 沿用所属按钮的语义色与 Element loading 行为，无独立 loading 色板 |
 ## 顶部按钮基础主题
 | 主题 | 基础色变量 | 当前值 |
 |---|---|---|
 | 主要 | `--cc-primary` → `--el-color-primary` | `#667eea` |
 | 主要悬停 | `--cc-primary-hover` | `#764ba2` |
 | 成功 | `--cc-success` → `--el-color-success` | `#067647` |
 | 警告 | `--cc-warning` → `--el-color-warning` | `#b54708` |
 | 危险 | `--cc-danger` → `--el-color-danger` | `#b42318` |
 | 信息 | `--cc-info` → `--el-color-info` | `#175cd3` |
 这些是基础语义值；实际按钮的实心/描边、禁用和悬停颜色还取决于 `type`、`plain` 和 Element 主题变量。不能把此表视为每个按钮最终计算样式。修改 `--cc-primary` 还可能影响导航、页签等，不能只为按钮颜色直接整体替换。
 ## 订单状态徽标色板
 统一外观：胶囊形、最小高度 24px、padding 2px 8px、圆点 6px、间距 6px、字重 650，字号读取 `--cc-list-status-font-size`（基础默认 11px）。圆点使用文字色。
 | 类型 | 文字 / 圆点 | 背景 | `StatusBadge` 当前精确匹配的中文文案 |
 |---|---|---|---|
 | 默认 `neutral` | `#475467` | `#f2f4f7` | 所有未匹配下面映射的文案 |
 | 成功 `success` | `#067647` | `#ecfdf3` | 正常、启用、已完成、已审核、审核通过、已入库、已出库、装柜完成、派送完成、已确认、已放舱 |
 | 警告 `warning` | `#b54708` | `#fffaeb` | 待审核、草稿、待处理、待分配、未提交、未录入、待测量数据、待分柜、待装柜、预装柜中、待出库、已拣货、变更中 |
 | 危险 `danger` | `#b42318` | `#fef3f2` | 停用、已取消、已驳回、审核驳回、失败、订舱失败 |
 | 信息 `info` | `#3538cd` | `#eff4ff` | 已受理、已订舱、已提交、运输中、处理中、拣货中、装柜中 |
 注意：`异常`、`成功` 这两个字面文案本身不在映射中，直接传给 `StatusBadge` 会显示默认灰色；`失败` 在危险映射中。`info` 徽标的颜色与基础主题的 `--cc-info` 不相同。成功/警告/危险虽然当前数值与基础主题一致，但 CSS 直接写死，因此改基础变量不会同步修改徽标。
 ## 国内订单当前实际映射
 由 `unified-orders/status.ts` 翻译后传给 `StatusBadge`，列表主状态和详情沿用这条链路。
 | 状态码 | 文案 | 当前徽标类型 |
 |---|---|---|
 | DRAFT | 草稿 | warning |
 | SUBMITTED / PENDING_REVIEW | 待审核 | warning |
 | APPROVED | 已审核 | success |
 | ACCEPTED | 已受理 | info |
 | REJECTED | 已驳回 | danger |
 | PROCESSING | 处理中 | info |
 | COMPLETED | 已完成 | success |
 | CANCELLED | 已取消 | danger |
 | WAIT_MEASURE | 待测量数据 | warning |
 | WAIT_PALLETIZE | 待一件代发组托 | **neutral：没有专门映射** |
 | WAIT_SPLIT | 待分柜 | warning |
 | LOADING | 装柜中 | info |
 | LOADED | 装柜完成 | success |
 | DELIVERED | 派送完成 | success |
 审核状态：`NOT_SUBMITTED` 未提交、`UNRECORDED` 未录入、`PENDING` 待审核为 warning；`APPROVED` 审核通过和 `CONFIRMED` 已确认为 success；`REJECTED` 审核驳回为 danger。
 ## 尾程订单当前实际映射
 文案来自 `overseas-warehouse/lastMilePresentation.ts`。下表颜色用于已接入 `dense` 的尾程详情；尾程列表当前状态列仍为普通文本。
 | 状态码 | 文案 | 详情当前徽标类型 |
 |---|---|---|
 | PENDING_ASSIGNMENT | 待分配 | warning |
 | DESTINATION_ASSIGNED | 已分配目的仓 | **neutral：没有专门映射** |
 | INBOUND_PLANNED | 已生成入库计划 | **neutral：没有专门映射** |
 | PENDING_PROCESSING | 待处理 | warning |
 | PROCESSING | 处理中 | info |
 | COMPLETED | 已完成 | success |
 | CANCELLED | 已取消 | danger |
 ## 预装清单状态
 2026-09-15 根据用户截图补齐公共徽标映射；预装列表与使用同一徽标的详情同步生效，不改变业务状态、文案、权限和操作。其他入口传入相同状态文案时也使用公共语义色。
 | 状态码 | 文案 | 语义 | 文字色 / 背景色 |
 |---|---|---|---|
 | WAIT_LOADING | 待装柜 | 等待，warning | `#b54708` / `#fffaeb` |
 | EDITING | 预装柜中 | 计划准备，warning | `#b54708` / `#fffaeb` |
 | LOADING | 拣货中 | 进行中，info | `#3538cd` / `#eff4ff` |
 | COMPLETED | 装柜完成 | 完成，success | `#067647` / `#ecfdf3` |
 | 未知状态 / 空值 | 未知状态 / — | neutral | `#475467` / `#f2f4f7` |
 当前预装列表主要显示预装柜中和拣货中，需要直接用颜色区分：预装柜中采用橙色文字与浅橙背景，拣货中采用蓝紫文字与浅蓝背景。两者仍复用公共语义色，不新增页面私有色值。
 ## 出库单状态
 列表与详情使用公共状态徽标；已出库从缺失映射的灰色改为完成绿色。列表明确识别待出库，不再将待出库或未知状态统一显示为拣货中。
 | 状态码 | 文案 | 语义 | 文字色 / 背景色 |
 |---|---|---|---|
 | WAIT_OUTBOUND | 待出库 | warning | `#b54708` / `#fffaeb` |
 | PICKING | 拣货中 | info | `#3538cd` / `#eff4ff` |
 | PICKED | 已拣货 | warning（待完成出库） | `#b54708` / `#fffaeb` |
 | OUTBOUNDED | 已出库 | success | `#067647` / `#ecfdf3` |
 | CANCELLED | 已取消 | danger | `#b42318` / `#fef3f2` |
 ## 后续统一时需要确定的范围
 1. 默认蓝 `#1777ff` 已确认；是否将行内主要蓝 `#1677cf` 也统一为该值，尚未修改。
 2. 按钮、徽标可共享成功/警告/危险等语义，但文字、背景、边框分别使用变量，避免把徽标改成按钮外观。
 3. 状态样式统一放在公共徽标中，颜色提取到公共变量；业务模块按状态码显式提供文案和语义，避免改中文文案导致颜色变化。
 4. 补齐待组托、已分配目的仓、已生成入库计划及异常等映射，并统一尾程列表与详情的状态呈现。以上为待调整项，本次未改实现。
 5. 对未接入 `density-action`、使用 `el-tag` 或非 dense 详情分支的入口另行定向接入，不能宣称改一处已覆盖全应用。
@@ -0,0 +1,36 @@
 # Admin 测试环境截图验收记录（2026-09-15）
 用户本轮明确授权使用内置浏览器在测试环境截图验收。本次采用 1920×1080 视口、100% 浏览器缩放。该授权替代此前默认等待人工截图的方式；不包含提交业务表单、发送消息或部署授权。
 本批取得 10 张截图。测试页面已呈现国内订单/尾程订单详情和排车省略号的修改，但首页、消息模板仍与当前本地实现不同。因此仅记录已观察到的页面状态，不将全模块视觉验收标记完成。
 截图保存在本机目录：`C:/Users/BY-OY/.codex/visualizations/2026/09/14/01a09f47-4fd9-79a2-ab11-907fafb01423/qa-test-20260915/`。以下文件名均相对于该目录。
 | 截图 | 页面或操作 | 本批结论 |
 |---|---|---|
 | 01-dashboard.png | 首页 | 仍为四张独立指标卡；当前本地已改成连续指标信息表，暂不能验收本地修改 |
 | 02-domestic-orders.png | 国内订单列表 | 已留首屏证据；不替代全部状态及操作验收 |
 | 03-domestic-order-detail.png | 国内订单详情基本信息 | 返回、业务单号、状态同行；摘要、页签、紧凑信息表可见，未再出现此前原生按钮和无布局字段现象 |
 | 04-lastmile-orders.png | 尾程订单列表 | 可见查看、入库计划及纯省略号入口；没有可见“更多”文字 |
 | 05-lastmile-order-detail.png | 尾程订单详情基本信息 | 与国内订单详情采用一致的标题行、摘要、页签及信息表样式；其余页签仍需复核 |
 | 06-dispatches.png | 排车列表 | 已出发样本只有查看、打印 BOL 两个按钮，没有折叠入口；待发车样本为三个直接操作加省略号 |
 | 07-dispatch-more.png | 排车省略号菜单 | 待发车样本菜单包含转派送、取消，共五个操作；入口只有省略号图标 |
 | 08-dispatch-edit.png | 排车编辑 | 弹框居中、三列表单，底部取消和保存可见，截图中未见遮挡；未修改字段，已取消 |
 | 09-message-templates.png | 模板管理列表 | 仍为旧样式，页面缺少本地的 admin-density 入口；长列表及按钮暂不能验收为当前版本 |
 | 10-template-create.png | 新增消息模板 | 已记录旧版弹框外观；未填写或保存，已取消，部署后需重新截图 |
 ## 测试页面与本地实现差异
 - 首页本地 `apps/admin-web/src/modules/dashboard/pages/DashboardView.vue` 使用密度入口及连续指标表；实际测试截图仍显示四张卡片。
 - 模板管理本地 `apps/admin-web/src/modules/notifications/pages/MessageTemplatesView.vue` 使用 `admin-density` 与 `density-action`；测试 DOM 的页面根未包含该入口，已观察到的禁用按钮仍为 `el-button--primary is-link`，高度约 21px。
 - 本地 `TemplateEditorDialog.vue` 已显式接入 `admin-density-dialog`。测试截图不作为这部分新样式的通过证据。
 以上证据表明当前测试页面未呈现全部本地修改；本批未核实测试部署的精确提交号，不能将差异归因到某一次部署。
 ## 后续验收范围
 1. 获得单独的 Admin 测试部署授权后，按部署指南发布本次相关修改并确认版本，再复核上述差异。
 2. 继续按各模块记录覆盖列表、新增、编辑、详情及各页签、确认框和操作菜单；样本未覆盖的权限、状态、长内容保留待验收。
 3. 本批未提交业务表单、未发送消息、未变更业务数据，也未部署。消息详情可能自动标记已读，需在后续操作前纳入授权范围判断。
 本地既有门禁为 253 个文件 / 1982 项测试、类型检查、构建及差异检查通过；本批只新增截图记录，不将离线检查替代浏览器视觉验收。
@@ -0,0 +1,32 @@
 # Admin 海外业务样式核对记录
 ## 范围与修改前逐操作核对
 当前三菜单映射到 `apps/admin-web/src/modules/overseas-business/routes.ts` 的 9 个路由、5 个页面文件。原型入口为 `悦/货代SAAS平台后台/prototype-src/modules/07-overseas-business.html`。通用样式按本轮国内订单样板，字段/权限/业务承载以已实现契约和当前用户要求为准。
 | 页面/操作 | 原型证据 | 当前实现 | 本轮修正 |
 |---|---|---|---|
 | 采购列表查询、详情、编辑 | `page-overseas-purchase` 第 2 行 | `PurchaseOrdersView`，详情/编辑两个操作 | 公共密度、纯文字描边按钮、左侧操作列，保留查询和分页 |
 | 采购新增 | 第 14 行明确历史新增模板不可达 | 后台无新增路由/API | 不补建新增能力 |
 | 采购详情 | `page-overseas-purchase-detail` 第 204 行，商品/库存/订单/快递/操作记录 | `PurchaseOrderDetailView` 独立页面，四组信息与四组业务表 | 返回、编号和状态合并；实际事实摘要；按原顺序连续键值表；取消独立字段卡片式排版 |
 | 采购审核通过/拒绝 | 原型详情为动态内容；当前已接入服务端审核 | 520px 居中 `reviewDialogOpen`，备注、版本和幂等键 | 保留承载与请求，显式接入弹框密度并展示审核业务对象 |
 | 签收文件、凭证上传、登记费用 | 当前详情实际上传入口，原型未完整定义 | 系统文件选择、560px 费用弹框 | 保留现有文件生命周期与冻结说明，统一弹框和表单；无预览/删除入口不虚构操作 |
 | 采购编辑、出库明细添加/删除、保存/取消 | `page-overseas-purchase-edit` 第 143 行，独立页面 | `PurchaseOrderEditView` 三列表单、出库明细行、未保存保护 | 同行返回、业务编号；紧凑分组及表单；保留入库资格、全部字段、三态 PATCH 与未保存保护 |
 | 本土卡车列表、新增、编辑 | 第 58/83/332 行 | `TransportOrdersView domain=truck`、`TransportOrderFormView` 独立页面；原型 760px，现实现 900px 表单 | 保留新增/编辑承载；同一白底表单区域、统一控件和行内编辑按钮，按字段组保留两/四/五列布局 |
 | 本土散板列表、新增、编辑 | 第 222/247/390 行 | 上述共享页的 `domain=looseboard` 模式 | 同上，同时保留散板方式、是否打盘与权限状态差异 |
 | 卡车/散板详情、资料、删除 | 卡车原型第 313 行存在详情，当前正式路由与列表只开放新增/编辑 | 无对应只读详情/资料上传/删除入口 | 记录当前可达范围，不恢复历史功能，不将其标记为已验收 |
 共同问题：5 页均未显式接入公共密度样式；详情/表单头部返回靠右、重复标题/编号标签，编号缺失时回退路由参数；旧局部字号/大间距与公共规则冲突。本轮按实际字段重排，业务请求与权限不改。
 ## 验证
 代码修正已完成；所有页面及弹框的修正后视觉效果待人工截图确认。
 ## 本轮检查结果
 - 全量 251 个测试文件、1,942 项通过；类型检查、生产构建及差异空白检查通过。
 - 密度合同已纳入本组全部页面和真实 Teleport 弹框，覆盖公共样式独立导入、实际祖先、行内按钮、标签与字号规则。
 - 本组视觉仍待人工截图确认；代码和组件测试不代表页面视觉验收。
 - 采购/卡车/散板编辑区域均限制在 1120px 连续白底区域，标题和表单同宽；采购出库明细保留独立行、完整输入和删除操作。该宽度属于本组业务布局，不改变全局页面宽度。
 - 组件回归覆盖采购 23 个信息字段/4 个业务分组/4 个长字段跨列，以及凭证选择、上传、登记费用、审核后按钮隐藏；原有分页、409 输入保留、幂等重试和卡车/散板状态限制全部通过。
@@ -0,0 +1,92 @@
 # Admin 海外仓样式核对记录
 ## 范围与依据
 本轮用户确认继续“海外仓”模块。范围以 `adminNavigation.ts` 的 `overseas-inventory` 分组为准，包含 10 个菜单、对应独立详情和实际调用的作业弹框。客户服务、海外业务、隐藏产品库和旧箱号页面不在范围内。
 视觉采用 [Admin 高密度界面规范](Admin高密度界面规范.md)，保留当前路由、字段、权限、服务端状态资格及操作承载方式。原型入口为 `悦/货代SAAS平台后台/prototype-src/modules/03-overseas-warehouse.html`；入库、出库、换标、托盘详情分别见 706、714、720、726 行，尾程列表/详情见 894/927 行，库存详情/流水见 974/1022 行。当前真实业务契约优先于历史原型占位。
 ## 修改前逐操作矩阵
 页面文件均相对 `apps/admin-web/src/modules/overseas-warehouse/`。原型未覆盖的新操作保留现有承载方式，不新增业务流程。
 | 菜单/入口 | 操作及源码证据 | 当前承载与尺寸 | 本轮结论 |
 |---|---|---|---|
 | 尾程订单 | `LastMileOrdersView` 查询、导出、查看、更多；`LastMileOrderDetailView` | 独立详情；基本/货物/计划/费用/日志页签 | 纯文字行内按钮、彩色页签、连续信息表、同行返回 |
 | 尾程订单 | `transferOpen`、`inboundPlanOpen` | 转仓默认宽度、入库计划 720px 居中框 | 保留确认、候选、版本，接入弹框密度 |
 | 尾程订单 | `containerConvertOpen`、`containerDetailOpen`、`receivingWarehouseOpen` | 预览 1240px、柜详情 1120px、接柜仓 600px | 保留逐柜预览/阻断及当前隐藏入口，不恢复隐藏菜单 |
 | 尾程订单 | `holdOpen`、`manualNodesOpen` | 暂扣 620px、节点 700px | 保留原因、计费、节点原子提交，紧凑表单 |
 | 尾程订单 | `WarehouseTransferReviewDialog` | 转运审核 920px | 保留审核/驳回、货物与打托实测、按钮资格 |
 | 尾程详情 | `feeDialogOpen` | 新增费用 720px | 保留金额/币种/保存流程 |
 | 入库单 | `InboundOrdersView` 查看、编辑计划、预约；`InboundOrderDetailView` | 独立详情；预约 1080px；计划编辑默认框 | 保留只读费用空态、预约模式，统一按钮与描述表 |
 | 入库单 | `SmartDispatchDialog` | 1800px 三栏作业框；车型选择 360px | 保留拖拽、锁定、容量、超重与预排车；只压缩普通控件 |
 | 排车列表 | `DispatchesView` 查看、BOL、更多、取消；`DispatchDetailView` | 独立详情；PDF 原打印流程；取消确认框 | 保留返回目标、直接操作及危险确认 |
 | 排车列表 | `transferOpen`、`editOpen`、`removePallet` | 转派送 1120px；编辑 900px；移除确认框 | 保留费用/箱唛/托盘事实，描边行内操作 |
 | 出库单 | `OutboundsView` 新建、查看、取消；`OutboundDetailView` | 新建 1320px；独立详情；取消原因框 | 保留一件代发/退货两模式、选择表、PDA 提交 |
 | 派送单列表 | `DeliveryOrdersView` 查看、编辑状态、标记退货 | 独立详情；状态 520px；退货 720px | 保留原出库明细可退数量与去向；统一按钮 |
 | 派送详情 | `DeliveryOrderDetailView` 四页签 | 订单/SKU/费用/操作，内容在页签内 | 彩色页签且所有正文保持可见，去重复正文标题 |
 | 派送单资料 | `DeliveryDocumentsDialog` 上传、替换、删除、下载、保存、重新加载确认 | 1040px；关闭放弃未保存修改 | 保留文件生命周期，正文单一滚动区 |
 | 换标单 | `RelabelOrdersView` 新增、审核、查看 | 760px 表单；独立详情 | 保留创建与审核模式、状态候选与必填字段 |
 | 换标详情 | `RelabelOrderDetailView` 完工证据、总 PDF、明细 PDF 上传/预览 | 连续详情、预览 900px | 保留 PDF 物理预览尺寸与绑定数据，紧凑文件行 |
 | 托盘管理 | `PalletsView` 汇总、新增、编辑、查看；`PalletDetailView` | 760px 表单；独立详情 | 汇总改紧凑行；保留仓库编辑限制 |
 | 库存管理 | `InventoryView` 汇总、查看、导出；`InventoryDetailView` | 独立详情，库位/托盘箱号/流水表 | 连续汇总、信息表；不改变库存口径 |
 | 库存流水 | `InventoryTransactionsView` 导出、返回、关联数据 | 列表深链；共享关联框 1060px | 只为本轮调用显式接入共享框，保留分区域只读权限 |
 | 退货库存管理 | `ReturnInventoryManagementView mode=inventory` | 库存/流水页签、查询、分页 | 两页签保留各自数据和查询模式 |
 | 退货箱号管理 | `ReturnInventoryManagementView mode=cartons` 查看、箱唛打印 | 详情 1080px；现有 HTML 打印 | 统一详情按钮/信息表，不修改打印内容或尺寸 |
 ## 共享边界和验收
 - `OverseasDetailShell`、`OverseasReadOnlyDetail`、`InboundCodeRelationshipDialog` 显式 `dense` 接入；默认调用保持原样。
 - 公共字号、间距、按钮、页签和键值表只使用公共密度变量与类；模块仅保留业务布局与作业区尺寸。
 - 最终全量 `pnpm test --maxWorkers=4`：1,927 项通过；`pnpm typecheck`、`pnpm build` 通过；索引合同 1,050 项通过。新增合同核对 10 个导航入口、两种退货模式、详情祖先样式、Teleport 接入和共享组件关闭状态。
 - 尾程与派送详情的 `density-contained-tabs` 保留所有页签正文；智能排车将原操作按钮移入固定 footer 插槽，保留预排车事件与原三栏作业区。
 - 页面事件、请求和状态门禁保持原有业务逻辑；本轮没有部署或修改环境数据。复核修正托盘标题的内部 ID 回退，出库仓库名称仅采用同仓关联派送返回的名称；缺失或关联不一致时显示“—”。托盘 DTO 目前未返回库位编码，详情保留空值，不展示 `locationId`。
 - 托盘汇总移除与页面 `gap` 叠加的底部间距；删除已被公共按钮组接管的局部间距及空样式规则。
 - 默认高并发全量回归出现分散用例的偶发失败；失败项定向复跑通过，随后在不修改断言或超时的情况下限制为 4 并发，全量通过。托盘加载/失败时不展示内部 ID、出库仓库名称匹配/缺失/不一致均有组件回归证据。
 - 本地 5173 端口的 Vite 服务进程指向当前 `chongchong-global/apps/admin-web` 工作区；这只证明服务路径，不代替页面视觉证据。
 - 全部 10 个菜单及详情/弹框均 **待人工截图确认**，验收为 1920×1080、浏览器缩放 100%。
 ## 用户截图复核修正
 用户提供尾程详情与国内订单详情截图后，确认上一轮仅接入密度变量不足以达到样板一致：尾程存在重复页头标签、缺少业务摘要、自定义绿色状态边框、页签首项贴边且选中底色缺失、基本信息被两个标题拆断。截图证据为本轮附件 f76bcf5f（尾程）与 151a1d06（国内样板）。
 | 操作 | 样板及现状 | 本次修正 |
 |---|---|---|
 | 尾程详情页头 | 国内为返回列表、业务编号、状态；尾程额外展示页面标题和编号标签 | 共用页头排版，仅保留业务编号；复制功能缩为轻量图标 |
 | 状态 | 国内使用带圆点的 StatusBadge；尾程将全部已接入状态画成绿色 | 使用同一状态徽标，待分配按待办语义展示 |
 | 概览 | 国内摘要位于标题和页签之间；尾程没有 | 展示客户、海外仓、箱数、托数、体积和最近更新，均取当前订单事实 |
 | 页签 | 原生与 Element 两套样式存在实际差异 | 共用选中底色、字号、内边距、下划线，保留 Element 键盘切换及五页签正文 |
 | 基本信息 | 国内连续键值表；尾程两个标题与两个表 | 保留全部字段顺序，合并为连续表；长备注按两组字段宽度展示 |
 上述截图证明原版本存在差异，不作为修正后视觉通过的证据。
 - 按本轮补充要求复核操作按钮：尾程订单、排车按当前行权限和状态统计实际显示操作，3 个及以下全部直显，超过 3 个才出现“更多”；直接操作优先保留查看、编辑/计划、打印。其余海外仓菜单操作列最多 3 个，继续直接显示。
 ### 本次截图修正的验证结果
 - 新增尾程详情组件回归：单一业务标题、待分配状态语义、紧凑复制、实际摘要（含零箱数）、19 个基本字段、长备注、返回路由与 5 个页签可达。
 - 新增尾程/排车权限组合回归：1—3 个操作直接显示，4—5 个操作才显示“更多”，并保留高频操作。公共样式合同校验国内原生与海外 Element 页签共用同一组外观规则。
 - 全量执行 251 个测试文件、1,940 项：1,938 项首轮通过；另两项是旧的 230px 列宽及单一标题类名断言，按新规则更新后，其所属两个测试文件定向复跑全部通过。类型检查、生产构建及差异空白检查通过。
 - 修正后仍待人工页面截图核对；本次代码与组件验证不作为浏览器视觉验收通过的依据。
 ### 折叠按钮文字修正
 - 用户截图 f21098e6 确认折叠入口只展示省略号图标。尾程订单、排车列表移除可见“更多”文字，保留悬停提示和无障碍名称；超过 3 个操作才折叠的判断保持不变。
 - 本次折叠按钮修正：全量 1,940 项测试、类型检查与生产构建通过。
 ### 新建出库单搜索、批量选择与分页（2026-09-15）
 依据用户截图 `codex-clipboard-6a1295e8-ae69-44de-86bd-a0dd22446396.png`，仅调整 `OutboundsView` 的新建弹窗：
 | 操作 | 截图现状 | 修正 |
 |---|---|---|
 | 仓库选择 | 下拉框的搜索能力不明显 | 保留可搜索下拉，提示输入名称/编码；选项同时展示名称与编码，可清空重选 |
 | 订单搜索 | 已有关键词查询 | 保留订单号、入库单号、客户、托盘号、SKU、品名查询，增加搜索图标和无障碍名称；输入后查询或回车生效 |
 | 批量选择 | 只有逐行复选框 | 表头全选本页；取消本页仅影响本页，翻页保留选择。按用户后续截图要求移除独立“全选筛选结果/清空选择”按钮行，已选总数并入分页左侧 |
 | 客户/仓库限制 | 提示仅提及同一仓库，但接口还要求单一客户 | 保留同一客户、同一仓库提交限制；跨客户勾选后明确提示，用户可取消勾选并按客户查询 |
 | 分页 | 每页条数文字不可见；内容过长时分页靠近弹窗底部 | 收窄表单全宽选择器范围，分页条数下拉固定 128px；增加每页 50 条、当前/总页数、跳页；条数变化回到第一页 |
 | 长列表 | 增加每页条数会拉长整个弹窗 | 候选表格内部滚动，最大高度 360px；分页可换行，退货分支的分页条数宽度同步修正 |
 后续截图 `codex-clipboard-1adadeb3-9d55-4c41-81c1-d6dafba87293.png` 确认搜索与批量按钮占行过多：海外仓搜索（280px）和一件代发订单搜索及查询/重置（640px）同排，移除独立批量按钮行，已选数并入分页左侧。普通说明收为单行文字，跨客户警告仍保留，备注默认一行并按输入自动增高至三行。
 已增加真实组件回归覆盖分页选择、筛选后跨页勾选、半选状态、每页条数切换、仓库变更清空选择、提交明细数量以及多客户提交门禁。仅使用测试 Mock 验证提交，无真实出库单创建或 PDA 推送。修正后视觉仍待 1920×1080、100% 截图确认。
@@ -0,0 +1,18 @@
 # Admin 消息中心样式核对记录
 范围为顶部消息中心实际注册的三个页面及其现有操作。入口由 `apps/admin-web/src/app/layouts/AppLayout.vue:181` 和 `src/modules/notifications/routes.ts` 证明，不计入左侧 48 个菜单。采用当前用户确认的国内订单样板与公共密度规范。
 | 页面 | 操作 | 原型依据 / 承载 | 当前实现与调整结论 |
 |---|---|---|---|
 | 我的消息 | 查询、查看、标为已读、全部已读 | `prototype-src/modules/11-system-messages.html:283` 的 `page-msg-my`；详情容器未定义 | 保留正式列表及 680px 详情抽屉；列表按钮、抽屉字号和正文间距接入公共密度，不改变打开未读消息时的标记逻辑 |
 | 消息管理 | 列表、查看 | 同文件 260 行 `page-msg-manage`；原型仅给详情按钮 | 保留正式列表及现有 820px 任务详情抽屉；六项摘要改连续两列键值表，保留收件人表和失败原因 |
 | 消息管理 | 新建、立即/定时发送 | `prototype-src/overlays.html:354` 的 `modal-msg-create`，680px 居中弹框 | 保留宽度、两列表单、整行模板变量及定时选项；独立浮层显式接入密度 |
 | 消息管理 | 取消、重试 | 原型未定义；现有确认框及权限、状态限定 | 保留确认和 API；取消为危险色、重试为普通描边，不增加操作入口 |
 | 模板管理 | 列表、激活、禁用 | `prototype-src/modules/11-system-messages.html:272` 的 `page-msg-template`；状态确认原型未定义 | 保留现有状态门禁及确认；激活为成功色、禁用为危险色 |
 | 模板管理 | 新增、编辑、变量插入、预览 | `prototype-src/overlays.html:367` 的 `modal-msg-template-create`，760px 居中弹框；编辑复用现有容器 | 保留两列基本字段和整行正文、变量、预览；统一表单间距与浮层密度 |
 现有 `notifications/PROTOTYPE_MATRIX.md` 中“我的消息未注册”和“无任务详情”与当前正式路由、顶部入口及 `getTask` 实现不符。本次按实际入口核对样式，不移除已存在功能，不新增发送渠道、草稿或导出能力。各行最多两个可用操作，全部直接展示，不引入更多菜单。
 本次只调整样式，消息发送、标记已读、模板写入、取消与重试均仅使用离线 Mock 验证，不向真实账号发送消息。42 项定向检查、253 个文件 / 1981 项全量测试、类型检查、构建和 git diff --check 均通过；本地 Vite 五个组件资源均返回 200。三个列表、两处抽屉、两处编辑弹框及状态确认均待人工在 1920×1080、100% 缩放下截图确认。
 对五个组件的脚本 AST 与修改前比较，排除样式导入和确认框 customClass 后相同。新增原生 Element Plus 挂载用例核对了按权限查看/已读、任务与模板状态操作、两处详情抽屉、模板不可变编码/变量预览/版本及定时发送表单。实际字段校验、消息发送及服务端结果仍由人工业务验收补充。
@@ -0,0 +1,43 @@
 # Admin 财务管理样式核对记录
 范围为当前财务导航 6 个菜单、11 个正式路由及其实际可达操作。入口为 `apps/admin-web/src/modules/finance/routes.ts`，5 个主体页面与应收/应付两个路由封装。依据本轮全模块统一样式要求、国内订单样板和财务最近指引；历史原型的旧钱包/台账边界不覆盖当前已接入业务。
 ## 修改前逐操作矩阵
 原型目录为 `docs/悦/货代SAAS平台后台/prototype-src/`；页面在 `modules/08-finance.html`，浮层在 `overlays.html`。尺寸列记录当前实现；本轮保留业务弹框宽度及版本、权限、幂等和金额口径。
 | 页面/操作 | 原型或当前事实 | 当前承载/本轮调整 |
 |---|---|---|
 | 客户账户列表、详情、账期 | `page-customer-account` 637 行、详情 645 行；`FinanceCustomerAccountsView` | 列表/独立详情/详情内账期编辑；返回与客户同行，账户实际余额、冻结、授信等全部口径保留为紧凑摘要 |
 | 手工充值、手工扣款 | 当前 `adjustmentOpen`，与最近 Finance 指引一致 | 720px 弹框；保留类型、金额、付款方式、流水号、原因、账户版本及幂等键 |
 | 授信维护 | 当前 `creditLimitOpen` | 560px 弹框；保留到期日、额度下限与校验 |
 | 充值申请审核/驳回 | `modal-customer-recharge-review` 1807 行，当前 `reviewOpen` | 620px 弹框；保留申请描述表、凭证和审核原因 |
 | 充值凭证预览 | 当前 `voucherPreviewOpen` | 920px 图片预览，保留图片尺寸和清理，不压成普通表单 |
 | 账户流水查询/导出 | 当前详情 `ledger-query` 和 `exportLedger` | 独立筛选与服务端流水表保留，统一行高和工具栏 |
 | 客户应收应付列表/费用详情 | `page-customer-arap` 661 行、详情 798 行；`FinanceCustomerArapView` | 独立详情、来源金额摘要、单据与结算信息；统一标题、描述表和日志 |
 | 来源编辑、提交、审核/驳回、调整、作废 | 当前 `mutationOpen` 与 `reviewOpen` | 默认居中框；上游来源只读、整组分摊、状态及权限条件不变，按实际可见操作数量折叠 |
 | 应收款统计查询/打印/导出 | `page-finance-ar-detail-report` 761 行；`FinanceReceivableStatisticsView` | 真实按月 CNY 汇总；摘要压缩，打印保持既有规则和异步 Excel 导出 |
 | 对账单列表/详情 | `page-customer-recon-stmt` 822 行；`FinanceCustomerStatementsView` | 独立详情；去重复页头，保留客户/期间与 20 项概要、两个页签及全部版本记录 |
 | 生成对账单 | 当前 `createOpen` | 680px 弹框，保留费用候选、已选总额与账期 |
 | 提交、通过、驳回、出账、作废、重开 | 当前 `performAction` | 保留权限/状态条件和原因确认，操作不超过 3 个全部直显；超过 3 个才显示省略号 |
 | 对账单调整 | 当前 `adjustOpen` | 900px 弹框，保留来源明细及金额计算 |
 | 应收/应付列表与详情 | `page-settlement-ar` 940 行、`page-settlement-ap` 995 行、详情 1073 行；`FinanceFormalSettlementPage` 两模式 | 返回、结算单号和状态同行，删除路由 ID 文案回退；四项金额/日期摘要与描述表保留全部字段 |
 | 生成应收/应付结算单 | 当前 `createOpen` | 600px 弹框，保留各自候选和方向约束 |
 | 部分收款、部分付款 | 当前 `receiptOpen`/`paymentOpen` | 各 760px 弹框；保留部分核销摘要、凭证上传、剩余金额预览及保存限制 |
 | 结算单作废/重开、导出 | 当前 `performAction`/`exportDetail` | 原因确认与导出沿用原流程，接入公共确认框样式 |
 `CustomerStatementsPanel` 虽作为 Finance 公开组件存在，但当前六菜单路由没有引用；不能凭文件存在恢复旧抽屉入口。若后续模块沿实际引用命中，另行纳入其操作范围。
 ## 检查
 本轮代码核对覆盖上述 6 菜单 / 11 路由。5 个主体页面显式接入公共密度样式，财务局部布局位于 `src/modules/finance/financeDensity.css`；应收/应付两个路由封装移除旧的 `tbody` 网格覆盖，由共享详情描述表统一排版。
 - 客户账户、费用来源、对账单、应收/应付详情统一返回、业务标题与状态；金额摘要使用公共紧凑布局，对账单保留 20 个概要字段与两个页签。
 - 11 处弹框声明及各自版本、权限、金额、凭证处理保留；操作原因框和导出提示框显式接入样式。导出公共辅助函数增加可选 `dense` 参数，未接入消费者保持原样。
 - 账户仅有详情/账期时直接显示两个按钮；有充扣及授信权限时才折叠。费用来源草稿有 4 个动作时折叠作废，3 个及以下全部显示；通过真实组件测试验证省略号无文字且菜单里的作废仍能打开原确认流程。
 - 收款/付款由结算方向与权限互斥，最多 3 个行内操作；应收款统计打印/导出归入表格工具栏，打印时隐藏工具栏。
 - 清除页面内重复密度外观及空 CSS 选择器；公共维护合同纳入财务 5 个页面和模块 CSS，并增加空选择器检查。
 2026-09-14 检查结果：财务、公共密度和导出提示定向测试 183 项通过；全量 `pnpm test --maxWorkers=4` 为 251 个文件、1950 项通过；`pnpm typecheck`、`pnpm build`、`git diff --check` 通过。新增/编辑、审核、上传、部分核销、金额守恒及导出行为沿用原有财务测试，未删除这些业务断言。
 代码检查与财务行为测试不等同于视觉验收；所有本轮修改后的页面和弹框仍待人工在 1920×1080、100% 缩放下截图确认。
@@ -0,0 +1,79 @@
 # Admin 货柜管理样式核对记录
 ## 本次范围与状态
 用户确认继续优化货柜管理的 4 个菜单。本轮按下表实现列表、独立新建/详情页、智能装柜工作台及关联弹框的密度统一。代码检查结果在文末记录；未进行本轮浏览器视觉验收，所有修改后效果均待人工截图确认。
 统一使用 [Admin 高密度界面规范](Admin高密度界面规范.md)，以国内仓与客户管理为样板。普通列表、行内描边按钮、详情返回与页签、连续信息表、表单和浮层框架复用公共能力；业务状态、权限、接口、字段顺序、独立页面/弹框/抽屉承载方式保持现有契约。
 ## 4 个菜单与实际入口
 范围依据：[Admin 导航](../apps/admin-web/src/core/navigation/adminNavigation.ts) 的 `container-management` 分组。下表源码路径相对 `apps/admin-web/src/modules/`。
 | 菜单 | 页面与路由 | 新建、详情及相关组件 | 改造前继续核对 |
 |---|---|---|---|
 | 订舱列表 | `ocean-bookings/pages/OceanBookingsView.vue`，`/ocean-bookings` | `/ocean-bookings/new` 与 `/:bookingId` 共用 `OceanBookingDetailView.vue`；`OceanBookingDocumentsPanel`、`OceanBookingPrintDialog`、`CarrierScheduleQueryPanel` 和确认放舱弹框 | 新建与详情分别核对；资料、打印、船期、放舱资格及处理中状态不能丢失 |
 | 拖车列表 | `trucking/pages/TruckAppointmentsView.vue`，`/trucking` | `TruckAppointmentCreateView.vue`（`/trucking/new`）、`TruckAppointmentDetailView.vue`（`/trucking/:id`）；共用 `TruckAppointmentForm`、`TruckAttachmentDialog` | 新建是独立页面，编辑经详情页 `edit=1`；表单、附件、返回目标和状态资格分别核对 |
 | 送柜报关 | `container-loading/pages/DomesticContainersView.vue`，`/container-loading/domestic` | 列表共用 `ContainersView.vue`；详情经 `DomesticContainerDetailView.vue` 到 `ContainerDetailView.vue`，均传 `workbench="DOMESTIC"`；另有 `SmartLoadingWorkbenchView.vue` 深链 | 模拟柜、关联订舱、装柜/预装关联、报关、费用、出仓及智能装柜入口按实际权限展开 |
 | 清关提柜 | `container-loading/pages/OverseasContainersView.vue`，`/container-loading/overseas` | 列表共用 `ContainersView.vue`；详情经 `OverseasContainerDetailView.vue` 到 `ContainerDetailView.vue`，均传 `workbench="OVERSEAS"` | 船节点、清关资料、码头车队、提柜/还柜、异常、文件和尾程费用按实际权限展开 |
 路由事实：[订舱](../apps/admin-web/src/modules/ocean-bookings/routes.ts)、[拖车](../apps/admin-web/src/modules/trucking/routes.ts)、[货柜工作台](../apps/admin-web/src/modules/container-loading/routes.ts)。不将“国内仓”的整柜业务 `/domestic-containers` 当作这里的送柜报关页面。
 ## 共享边界与例外
 1. `ContainersView.vue` 和 `ContainerDetailView.vue` 同时服务国内、海外。可以复用样式，但两个模式分别保留字段、操作权限和业务资格；不能只验国内模式就声称覆盖清关提柜。
 2. `ContainerSimulationCreate.vue`、`PalletLabelPrintDialog.vue` 已被国内仓预装入口以 `dense` 接入。货柜管理接入时优先沿用该参数，并回归原国内仓调用；不复制组件或撤销已有密度。
 3. 货柜详情实际引用 `ContainerOverviewPanel`、`CarrierScheduleQueryPanel`、`ContainerCustomsPanel`、`LoadingListDetailDrawer`、`ContainerFeesPanel`、`ContainerLastLegFeesPanel` 和 `OceanBookingLinkDialog`。沿这些组件继续盘点实际页签、弹框与消息确认；不要因为父详情接入了公共类就把全部子页面记为完成。
 4. `LoadingListDetailDrawer` 当前是嵌入内容组件，名称不决定承载方式。它同时服务预装和已确认清单；为货柜详情的已确认模式接入密度时，要同步修改原“未接入模式保持默认”的合同与两个实际消费者用例，不能只放开样式后删检查。
 5. 智能装柜的模型/画布、船期轨迹、打印标签与 PDF 保留必要面积；只压缩周边表单、说明和装饰留白。航运业务编号、实际柜号、长文件名应有完整展示方式。
 ## 原型与逐操作矩阵
 原型先读 [局部指引](悦/货代SAAS平台后台/AGENTS.md)，目标模块为 `prototype-src/modules/06-containers.html`：订舱 `page-booking-list` / `page-booking-detail`，拖车 `page-truck-list` / `page-truck-add` / `page-truck-edit`，历史货柜与装柜入口 `page-ct-list` / `page-ct-manifest` / `page-ct-board`。
 历史原型没有完整表达当前国内/海外双工作台，不能照其页面数量恢复旧菜单。本轮以用户确认的密度规则和当前实际组件、事件为依据，保留如下承载方式：
 | 页面/模式 | 操作与承载方式 | 当前组件与依据 | 采用公共规则/业务例外 | 验证与截图 |
 |---|---|---|---|---|
 | 订舱 | 列表查看/编辑，跳转独立页面 | `page-booking-list`；`OceanBookingsView.open` | 灰色纯文字描边；草稿编辑、已放舱查看资格保留 | 待人工截图确认 |
 | 订舱 | 新建草稿、保存及详情 | `page-booking-detail`；`OceanBookingDetailView` 的 `booking-groups` | 轻量返回与标题同区；原业务分组与字段顺序保留，去除内层卡片；柜型操作列保留在首列 | 待人工截图确认 |
 | 订舱 | 删除草稿、确认放舱 | `removeDraft` / `releaseDialogOpen` 与 `submitRelease` | 删除消息独立接入；放舱保留 560px 居中确认与只读、处理中门禁 | 待人工截图确认 |
 | 订舱 | 上传/替换、下载、作废资料与作废历史 | `OceanBookingDocumentsPanel.selectFile/download/remove` | 类型分组改连续资料行，长文件名换行；替换与作废仍需原消息确认 | 待人工截图确认 |
 | 订舱 | 选择打印类型、PDF 预览/下载 | `OceanBookingPrintDialog.preview/backToSelection/download` | 保留 1120px 弹框、预览视口及 PDF 输出尺寸；选择项减小留白 | 待人工截图确认 |
 | 订舱 | 船期与状态历史 | `CarrierScheduleQueryPanel`；`OceanBookingDetailView` 的 `detail.histories` | 船期显式 `dense`；状态历史表保留时间、状态变化、操作人、原因与原排序 | 待人工截图确认 |
 | 拖车 | 列表详情/编辑，独立新建页 | `page-truck-list` / `page-truck-add`；`TruckAppointmentsView.openDetail`、`TruckAppointmentCreateView` | 行内纯文字描边；新建页返回和标题同区，不再放进表单说明末尾 | 待人工截图确认 |
 | 拖车 | 编辑、只读详情及保存 | `page-truck-edit`；`TruckAppointmentDetailView`、`TruckAppointmentForm` | 返回/编号/状态同区；桌面四列表单、关联与长地址跨列保留，公共表单字号间距 | 待人工截图确认 |
 | 拖车 | 状态变更确认与历史 | `changeStatus`、`history` | 原资格和确认消息；历史连续表格保留全部记录及操作人/原因 | 待人工截图确认 |
 | 拖车 | 附件查看、上传/关联、删除 | `TruckAttachmentDialog` | 保留 640px 居中弹框；连续附件行，删除红色描边，消息独立接入 | 待人工截图确认 |
 | 送柜报关 DOMESTIC | 列表、编辑基础资料 | `DomesticContainersView → ContainersView`；`openEdit/save` | 未完结/已完结页签 38px；查看、编辑、装柜、清单保持原排列；820px 双列表单使用公共弹框 | 待人工截图确认 |
 | 送柜报关 DOMESTIC | 新增模拟柜、关联订舱 | `ContainerSimulationCreate`；`OceanBookingLinkDialog.save` | 模拟柜沿用 `dense`；关联保留 680px 弹框和候选资格 | 待人工截图确认 |
 | 送柜报关 DOMESTIC | 智能装柜、分配/移除、调整箱数 | `SmartLoadingWorkbenchView.recommend/openAssign/assign/remove/startQuantityEdit` | 独立深链；保留容量进度、同柜组与封托说明、列表和分配弹框；普通行内操作接入描边 | 待人工截图确认 |
 | 双工作台详情 | 返回、概要、业务页签 | `ContainerDetailView` 的 `workbench-tabs` | Element 页签保留键盘行为，改 38px 彩色图标；概要为紧凑摘要，字段为四组连续描述表 | 待人工截图确认 |
 | 送柜报关 DOMESTIC | 异常标记/取消与历史 | `ContainerOverviewPanel` 的 `exception`；`ContainerDetailView.exceptionOpen` | 历史原因自然换行；520px 原因弹框独立接入 | 待人工截图确认 |
 | 送柜报关 DOMESTIC | PDA 进度与照片、国内出仓门禁 | `ContainerOverviewPanel` 的 `pda`；`confirmDeparture` | 去除内层卡片、数字改小摘要；保留进度、照片原图入口、全部门禁展开及离仓确认 | 待人工截图确认 |
 | 送柜报关 DOMESTIC | 报关资料、下载、上传完成文件、开始/完成报关 | `ContainerCustomsPanel` | 连续原生资料表，操作首列；纯文字描边，不改变全买单/退税分流或完成条件 | 待人工截图确认 |
 | 送柜报关 DOMESTIC | 装柜清单页签、打印清单/托盘码 | `LoadingListDetailDrawer`；`printLoadingList`；`PalletLabelPrintDialog` | 预装/已确认模式均由调用者显式接入；保持嵌入内容及打印载体，PDF 尺寸不变 | 待人工截图确认 |
 | 清关提柜 OVERSEAS | 列表、车队选择、发送/重试邮件与记录 | `ContainersView.selectRowFleet/sendPickupEmail/retryEmail/openEmailHistory` | 原列表控件与业务资格；邮件记录 1100px 弹框、重试确认独立接入，邮件正文保留换行 | 待人工截图确认 |
 | 清关提柜 OVERSEAS | 预约/实际提柜、还柜及拖车历史 | `drayageActionOpen`、`drayageHistoryOpen`；详情 `emptyReturnOpen` | 520px 时间与原因表单、980px 历史；超时状态和服务端时间事实原样保留 | 待人工截图确认 |
 | 清关提柜 OVERSEAS | 清关/DO 文件上传下载、PU 保存、完成清关 | `ContainerOverviewPanel` 的 `documents`；`documentOpen/clearanceOpen` | 操作首列描边；文件与 PU 保持不同流程，520px 弹框；无资料/只读/失败状态保留 | 待人工截图确认 |
 | 订舱/双工作台 | 履约轨迹、任务历史、人工船节点补录 | `CarrierScheduleQueryPanel` | 原轨迹分组和时间顺序保留；长摘要换行，展开查询事实为连续信息表；620px 补录弹框仅在 `dense` 模式接入 | 待人工截图确认 |
 | 双工作台费用页签 | 头程新增、调整、通过/驳回/作废、凭证、财务分摊 | `ContainerFeesPanel` | 行内纯文字描边，页内工具栏复用公共尺寸；编辑/驳回弹框和消息独立接入，客户归属与金额口径不变 | 待人工截图确认 |
 | 双工作台费用页签 | 尾程新增/调整、提交/审核/作废、付款凭证预览 | `ContainerLastLegFeesPanel` | 620px 双列表单、900px 预览及消息独立接入；保留图片 65vh 与全部权限条件 | 待人工截图确认 |
 交付按菜单逐个覆盖完整工作区；两种货柜模式共享代码时同时回归。代码检查和人工截图分别记录，不将入口盘点或公共规范可复用等同于本模块已优化。
 ## 公共实现与范围控制
 - `adminDensity.css` 增补 `density-element-tabs`、`density-table` 和 `density-form`，分别供现有 Element 页签、原生资料/历史表和分组表单显式使用；样式仍限定在密度入口内。原生表保留业务列宽和固定操作列。
 - `LoadingListDetailDrawer` 增加可选 `dense`；预装默认接入规则保留，货柜已确认清单显式开启，其他未开启消费者仍保持原布局。其局部密度类统一命名为 `loading-density`。
 - `CarrierScheduleQueryPanel` 增加可选 `dense`；订舱和货柜详情开启，独立船期入口未开启；原有无密度模式用原尺寸兜底。
 - 修改仅涉及样式、布局、图标及可选密度参数；不修改 API、业务权限、字段、提交资格或状态推导。图片原图、标签和 PDF 输出保持原功能。
 - 密度合同显式登记 4 个菜单、独立新建/详情和实际子组件，分别检查 DOMESTIC/OVERSEAS 入口、共享组件开启/关闭及预装/已确认模式。原有国内仓与客户管理清单保留。
 ## 2026-09-14 代码验证结果
 - 货柜、订舱、拖车、船期、清单与公共密度定向回归：53 个文件、485 项通过；补充的原生表、共享入口检查及智能装柜/双工作台回归 50 项通过。
 - 最终全量 `pnpm test`：249 个文件、1918 项全部通过。首次全量运行中仅跨模块状态合同仍锁定拖车旧图标，更新外观断言后完整复跑通过；原权限、状态、路由和业务提交断言保留。
 - `pnpm typecheck`、`pnpm build` 与 `git diff --check` 通过；AGENTS 索引合同 1050 项通过。
 - 本轮业务脚本与修改前版本对比，仅增加样式导入、确认浮层类和可选密度参数，没有修改业务处理逻辑。实际浏览器加载、长数据布局、浮层普通/全屏/重开及各权限状态仍待 1920×1080、100% 缩放人工截图确认。
 - 本轮未部署、未启动后端或修改业务数据。代码验证不替代实际业务写入及视觉验收。
@@ -0,0 +1,58 @@
 # Admin 通用资料样式核对记录
 范围为 `adminNavigation.ts` 的通用组 10 个可见菜单，沿正式路由定位到 14 个页面。10 个菜单的 14 个页面已完成代码样式核对；全部修改后页面尚待人工截图确认。隐藏产品信息、税率和旧库位页面不恢复。
 原型目录为 `docs/悦/货代SAAS平台后台/prototype-src/`。列表操作依据当前用户确认：不超过 3 个全部显示，超过 3 个才折叠，折叠入口只显示省略号。新增、编辑、详情、文件和确认逐项检查，不能从某一弹框推断其他操作。
 | 菜单 | 正式页面入口（`apps/admin-web/src/modules/` 下） | 原型入口 | 已定位操作 / 下一步 |
 |---|---|---|---|
 | 供应商列表 | `suppliers/pages/SuppliersView.vue`、`SupplierDetailView.vue`、`SupplierFormView.vue` | `05-suppliers.html`：列表 34 行、编辑 108 行 | 独立新增/编辑/详情；实际引用 `components/SupplierLicenseDialog.vue` 560px；核对返回、资质信息与操作权限 |
 | 快递公司 | `master-data/express-companies/pages/ExpressCompaniesView.vue` | `05-suppliers.html`：2 行 | 批量导入、580px 编辑抽屉；原型静态列表仅列出新增/导入/导出，具体表单原型未定义，保留当前承载 |
 | 往来单位 | `master-data/counterparties/pages/PartnersView.vue` | `05-suppliers.html`：8 行 | 680px 编辑/详情抽屉、批量导入；详情、编辑、启停均已显式接入，保留真实权限 |
 | 费用项目 | `fee-items/pages/FeeItemsView.vue` | `10-general.html`：8 行 | 620px 编辑抽屉；启停与删除分别使用确认框；核对表单分组和危险操作 |
 | 汇率管理 | `overseas-master-data/pages/ExchangeRatesView.vue` | `10-general.html`：21 行 | 560px 月度汇率新增/编辑框，保留月份和汇率校验 |
 | 仓库管理 | `warehouses/pages/WarehousesView.vue` | `10-general.html`：44、51、58、65 行 | 多类仓库列表；650px 新增/编辑框、760px 导入框，无独立详情入口；保留仓库类型、版本、导入文件和状态操作 |
 | 海外仓报价 | `overseas-master-data/pages/OverseasQuotesView.vue` | `10-general.html`：167 行 | 980px 详情、1180px 新增/编辑框；保留报价与计费字段 |
 | 船期价格表 | `fba-pricing/carrier-rates/pages/CarrierRatesView.vue`、`CarrierRateDetailView.vue` | `10-general.html`：273 行；当前价格簿接口与应用指引优先 | 560px 上传框、独立版本详情、仓库映射/确认；价格行只读，不恢复旧原型手工计价能力 |
 | 车辆列表 | `overseas-master-data/pages/VehiclesView.vue`、`VehicleDetailView.vue` | `10-general.html`：314、442 行 | 760px 新增/编辑、480px 状态变更、独立详情；核对关联派送及更换记录 |
 | 下载中心 | `downloads/pages/DownloadCenterView.vue` | `10-general.html`：228 行 | 720px 任务详情框、下载与重试；保留任务状态/退避/文件权限 |
 共享批量导入组件与供应商资质组件须沿实际调用逐项检查是否能显式接入密度样式。不能仅在父页面增加类名就声称 Teleport 弹框已覆盖。
 本轮先实施供应商、汇率、海外仓报价、车辆四个菜单（7 个页面及供应商资质组件）。供应商新增/编辑/详情继续独立路由；资质 560px、汇率 560px、报价详情 980px/编辑 1180px、车辆编辑 760px/状态 480px 保留承载和宽度，车辆详情继续独立页面。海外资料操作证据补充见应用内 `overseas-master-data/PROTOTYPE_MATRIX.md`：`modal-gen-overseas-quote-detail`、`modal-gen-overseas-quote`、`modal-exchange-rate-edit`、`modal-vehicle-edit`。供应商资质来自 `overlays.html:660`，保留其证照版式。供应商分类数量合并到同一组彩色页签，保留四类数量与筛选事件；连续详情使用公共页头与字段网格，列表行内操作均不超过三个，全部直显。状态和停用确认只接入外观，保留原权限、版本与请求。
 所有修改后页面仍需人工在 1920×1080、100% 缩放下提供截图核对。
 ## 其余六菜单逐操作核对
 - 快递公司：编辑、启停最多两项直显；580px 编辑抽屉和共享批量导入 720px。原型未定义的具体编辑承载按当前实现保留，不擅自改为独立页。
 - 往来单位：详情、编辑、启停最多三项直显；680px 详情/编辑抽屉和共享批量导入 720px。
 - 费用项目：编辑、启停、删除最多三项直显；620px 编辑抽屉，启停和删除各有确认框。
 - 仓库管理：编辑、启停最多两项直显；650px 编辑和 760px 导入框。不要把 `AppDialog` 内表单误认为独立页面。
 - 船期价格表：列表详情、原文件、待确认版本作废最多三项直显；560px 上传框；独立详情页头保留下载与确认生效操作，不按列表行内按钮压缩。
 - 下载中心：详情、成功后下载、符合条件时重试；详情 720px 弹框，按状态保留后端重试资格。
 共享 `BatchImportDialog.vue` 保持单一 `el-dialog` 为根；挂载测试已验证父传 class 实际到达 Teleport 根。组件直接引用密度变量并保留未接入时的默认值，无需新增参数。
 ## 已实施四菜单的检查结果
 2026-09-14：7 个页面和供应商资质组件显式接入公共密度。供应商分类数量并入彩色页签；汇率四项摘要保留为紧凑一行；三个独立详情/表单页使用公共 `density-detail-layout`、同行返回与业务标题，供应商路由关闭重复页头。报价详情采用两组连续键值表，供应商及车辆长字段跨列；车辆标题不再回退内部 ID，筛选、列表、表单与详情统一使用原中文状态名称。
 - 原字段及作业入口保留：供应商表单 14 项、报价表单 8 项及两组 10 个表格列、车辆表单 10 项、汇率表单 3 项；供应商详情 12 项、车辆详情 11 项。已有资质版式和六个弹框的宽度、关闭与提交逻辑保留。
 - 定向测试 60 项通过，包含长供应商名称/地址、返回目标、车辆详情失败不展示内部 ID、最多三个操作直接显示；原有版本冲突、长 ID、汇率精度和失败保留表单测试继续通过。
 - 全量测试 251 个文件、1956 项通过。随后仅统一车辆状态中文名称，再次运行上述 60 项定向检查和 `pnpm build`（含类型检查），均通过；`git diff --check` 通过。
 - 本地 5173 开发服务返回这 7 个页面的已编译密度代码，HTTP 均为 200。该检查证明正在提供新代码，不代替真实页面视觉验收。
 四菜单均待人工在 1920×1080、100% 缩放下核对修改后截图。
 ## 其余六菜单的检查结果
 2026-09-14：七个页面和共享批量导入组件完成显式密度接入。列表操作使用白底描边纯文字，最多三项全部直显；抽屉根同时接入页面密度和抽屉密度，弹框根显式接入对话框密度。公共 FormSection 样式覆盖独立浮层，修正只依赖父页面造成的样式遗漏。仓库新增菜单的浮层间距限定在自身，不再覆盖其他菜单。
 - 维持前表逐操作承载与尺寸。往来单位详情和下载详情采用两组连续键值网格，长地址、备注与文件跨列；船期价格详情使用同行返回、版本号、状态及主要操作，摘要保留报价范围和上传时间，正文为连续白底。渠道页签使用公共彩色图标，预览表保留在页签正文外，价格行继续只读。
 - 七页脚本语法树比对（排除样式导入、已移除装饰图标与确认框外观参数）及所有表单绑定比对均一致，原业务处理、权限、版本、仓库映射、导入预检与下载重试逻辑保留。
 - 定向检查 94 项通过，包含排车六组权限下的操作数量、往来单位详情浮层、下载详情 11 个字段、批量导入普通/密度模式及成功提交；类型检查通过。
 - 全量测试 251 个文件、1957 项通过；构建（含类型检查）和差异空白检查通过。
 - 本地 5173 返回这七页及排车列表的新密度代码，HTTP 均为 200。排车列表已是纯省略号入口；代码与开发服务验证不能代替页面截图。
 通用 10 菜单代码检查完成，全部待人工在 1920×1080、100% 缩放下核对修改后截图。首页、系统管理另行继续。
@@ -0,0 +1,28 @@
 # Admin 首页与系统管理样式核对记录
 范围为导航首页 1 个菜单及系统管理 3 个菜单，沿正式路由进入四个页面。依据当前确认的高密度样板，保留权限、状态、请求和真实字段。四页代码样式及直接交互检查已完成；全部页面待人工在 1920×1080、100% 缩放下提供修改后截图。
 原型目录：`docs/悦/货代SAAS平台后台/prototype-src/`。页面入口相对 `apps/admin-web/src/modules/`。
 | 页面 | 操作 | 原型证据 | 当前实现与结论 |
 |---|---|---|---|
 | `dashboard/pages/DashboardView.vue` | 指标、刷新、全屏 | `modules/00-dashboard.html:2`，全屏按钮 7 行、指标 10 行起 | 保留当前四项真实指标、统计口径、部分失败和更新时间；合并为连续信息区，保留原生全屏。无新增、编辑、详情、删除入口，不恢复静态图表、营收和待办演示。 |
 | `iam/pages/InternalUsersView.vue` | 新增、编辑、密码重置 | `modules/11-system-messages.html:2`；`overlays.html:545` 新增 650px，682 行编辑 650px | 保留 650px 居中框及两列表单；密码重置仍在编辑框内，保留独立权限、校验、受保护账号和海外 PDA 仓库绑定。 |
 | 用户管理 | 启停 | 当前列表 `toggleStatus` | 两项以内全部直显；保留独立确认框、当前登录用户及系统管理员禁用限制。无独立详情或文件入口。 |
 | `iam/pages/RolesView.vue` | 新增、配置角色及权限 | `modules/11-system-messages.html:7`；`app.js:5035` 的 `showRoleEdit` 打开模态框 | 保留当前 860px 居中框及左右基础信息/权限树；半选、恢复已选、菜单分组和授予权限独立控制。原型旧数据范围和字段授权不恢复。 |
 | 角色权限 | 启停、删除 | 当前 `toggleStatus`、`removeRole` | 三项以内全部直显；启停和删除分别保留确认，内置角色、已关联用户及加载门禁不变。无独立详情、文件入口。 |
 | `iam/pages/PermissionsView.vue` | 新增、添加下级、编辑 | `modules/11-system-messages.html:62` 的 `modal-sys-menu-permission`，720px 居中框；`app.js:5235` | 已由 600px 非模态抽屉修正为 720px 居中框，保留当前资源字段与可编辑性、上级候选、保存和未保存登记。 |
 | 菜单权限 | 启停、删除、展开/收起 | 原型同文件 54 行树操作；当前 `permissionActionCount` / `showDeleteMore` | 保留树展开/收起与层级；按实际权限超过三项才折叠，省略号图标独显、下拉项纯文字；受保护资源不可修改，删除资格和确认保留。无独立详情或文件入口。 |
 公共密度样式通过四页显式导入，所有模态框及消息确认框在自身浮层根接入；不向未声明页面扩散。此处矩阵记录实现范围，不代表视觉验收通过。
 ## 代码检查结果
 2026-09-14：四个页面及 IAM 局部布局样式完成接入，列表按钮沿用公共纯文字描边与语义色；菜单权限最多三项直显、第四项进纯省略号菜单，保留原权限及内置资源门禁。角色权限树保持半选与已保存授权恢复，长名称及权限编码可换行，无授权配置权限时基础表单使用完整宽度。首页四项指标使用连续键值信息区，刷新及全屏使用普通工具栏按钮；不增加未接通的演示数据。
 - 93 项定向检查通过，覆盖用户/PDA 仓库绑定、角色权限树、菜单权限数量及保护、居中框真实挂载、新增/编辑保存失败保留表单、首页部分失败刷新和进出全屏。菜单权限弹框测试明确模拟表单校验成功/失败结果，避免 Vitest 外部加载 Element Plus 时的 CJS 校验库互操作差异；不声称该测试替代真实浏览器校验。
 - 四页脚本语法树及表单绑定与修改前一致（排除样式/组件导入、确认框外观参数及已移除的首页装饰色字段），权限、保存、校验规则和统计口径未变。
 - 全量测试 252 个文件、1961 项通过；类型检查、构建与差异空白检查通过。
 - 本地 5173 的四页源码编译请求均为 200，并返回密度样式入口；该证据只证明开发服务提供了当前代码。
 此批无剩余代码检查失败；修改后视觉仍待人工截图。全模块沿组件引用继续复核，不能由四页通过推断其他共享子弹框全部通过。
@@ -0,0 +1,269 @@
 # Admin 高密度界面规范
 ## 确认依据与适用范围
 2026-09-14，用户在 Admin 样式优化对话中确认订单列表样板，并要求以此推进国内仓样式统一。样板包括订单列表、测量与订单审核弹框、订单详情的基本信息、货品信息、费用信息、状态历史、测量数据、其他、拆分履约。详情页签使用与客户管理一致的彩色 Emoji 图标。
 本规范固定该样板的视觉与密度规则。验收视口为 **1920×1080，浏览器缩放 100%**。其他页面采用本规范不等于其功能或视觉已验收。
 这是一套后续 Admin 页面可复用的基线。新增菜单按“新模块接入规则”实施，不复制订单或客户模块 CSS；货柜管理的入口与共享组件边界见 [货柜管理核对记录](Admin货柜管理样式核对记录.md)。海外仓的 10 个菜单及共享详情边界见 [海外仓核对记录](Admin海外仓样式核对记录.md)。列入下一批入口不代表页面已完成改造或验收。
 当前推广范围包括 Admin 导航中的“国内仓”，以及本轮确认的“客户管理”两个入口：客户列表、海外仓阶梯费用，包含各入口实际使用的详情、页签、新增、编辑、审核、确认、图片/文件预览和其他业务弹框。客户管理下的海外仓阶梯费用属于客户费用配置，不扩大到海外仓作业菜单。跨菜单跳转应记录目标入口和共享组件影响；不因此把另一个菜单的全部页面自动加入改造范围。Client、PDA 与其他菜单采用规范时另行明确范围。
 样板实现入口：
 - [公共密度样式](../apps/admin-web/src/styles/adminDensity.css)：页面显式使用 `admin-density`，Teleport 弹框显式使用 `admin-density-dialog`；默认不改变其他菜单。
 - [公共密度变量](../apps/admin-web/src/styles/adminDensityTokens.css)：两模块的字号、间距、控件/行/按钮/页签高度、圆角、底色和按钮语义色的唯一默认值入口。
 - [维护合同检查](../apps/admin-web/src/styles/adminDensity.test.ts)：限定已接入消费者，检查变量归属、公共样式作用域及页面重复实现。
 - [测量作业密度](../apps/admin-web/src/modules/inbounds/measurement/measurementDensity.css)：测量与审核共享作业布局，宽度由测量弹框自身提供。
 - [国内仓逐操作核对记录](Admin国内仓样式核对记录.md)：三组页面的承载方式、例外和验收证据。
 - [客户管理局部密度样式](../apps/admin-web/src/modules/customers/customerDensity.css)：客户列表、详情、计费与相关弹框的显式密度入口。
 - [客户管理逐操作核对记录](Admin客户管理样式核对记录.md)：两个菜单入口及关联详情、审核、编辑与预览的范围和人工验收项。
 - [订单列表与详情](../apps/admin-web/src/modules/unified-orders/pages/UnifiedOrdersView.vue)：列表、顶部摘要、描述表、页签、日志表及订单弹框。
 - [订单局部密度样式](../apps/admin-web/src/modules/unified-orders/styles/orderDensity.css)：费用、履约与测量弹框的局部样式。
 - [国内仓导航](../apps/admin-web/src/core/navigation/adminNavigation.ts)：`domestic-warehouse` 分组是菜单范围来源。
 本规范与 [Admin/Client 前端原型还原验收规则](Admin-Client前端原型还原验收规则.md) 配合使用。在本规范适用范围内，已确认的密度、容器和页签图标规则优先于历史原型中的大卡片、大留白和单色页签图标；字段、业务分组、权限、操作语义及页面/弹框/抽屉承载方式仍按当前业务契约和逐操作矩阵核对。样板中某个字段的专属宽度不能直接当作其他页面的固定宽度。
 ## 基本原则
 表格顶部操作栏的桌面尺寸统一由 `DataTable.vue` 维护：`padding: 6px 12px`、`min-height: 44px`。普通栏与 `.is-compact` 共用尺寸，后者只改变对齐；不再按 1920px 断点切换尺寸。公共密度样式和业务页面不得重复声明这部分 padding / height；组件现有移动端排列规则保留。
 1. 普通业务内容采用连续白底、细边框、描述表与数据表格。短字段以“标签 + 值”连续排列，不制作独立指标卡片。
 2. 先压缩重复标题、重复汇总、容器层数和无意义留白，再调整列宽与行高。正文保持可读，不通过缩小整页、浏览器缩放或截断关键值提高密度。
 3. 长编号、地址、邮箱、文件名与备注允许跨列、换行或按已确认方式查看完整值。空值显示“—”或明确的未关联状态，不显示内部数据库 ID。
 4. 业务状态使用现有语义色和文字。只有真实阻断、错误、风险才使用明显的警示区域。
 5. 密度改造不改变计算口径、API、保存触发方式、权限资格、状态机或字段含义。遇到功能问题单独记录，不能用样式隐藏。
 ## 尺寸与颜色
 下表是普通桌面业务布局基线；图片、长内容、错误反馈和可编辑表格可以自然增高，不能强制裁切。
 | 项目 | 基线 |
 |---|---|
 | 正文、表格、输入文字 | 13px |
 | 标签、辅助说明 | 12px；不进一步缩小 |
 | 分区标题 | 14px，适度加粗 |
 | 页面业务编号、弹框标题 | 16px |
 | 普通页签 | 高 38px，左右内边距 16px，图文间距 6px |
 | 页签图标 | 17px，固定 18px 占位，独立彩色显示 |
 | 普通表格行 | 基准 36px，单元格上下内边距 4px；按内容自然增高 |
 | 普通输入框与工具栏按钮 | 通常 32px |
 | 表格内操作按钮 | 28px，保留文字、焦点和禁用反馈 |
 | 区块间距 | 通常 12px；标准列表遵守现有 ListPageLayout 的单一间距，不叠加页级空白 |
 | 普通内容内边距 | 12px；弹框正文 12px 16px |
 | 容器圆角 | 0–4px；普通数据区无装饰阴影、渐变或上浮效果 |
 | 内容底色 | 白色 |
 | 表头、描述表标签底色 | 浅灰，参考 #f8fafc / #f9fafb |
 | 边框 | 现有 `--cc-border`；表格参考 #e5e7eb |
 | 悬停、斑马纹 | 轻量区分，参考 #f3f7fb / #fcfcfd |
 颜色优先复用当前 `--cc-*` 与 Element Plus 语义变量。金额和测量数字可使用等宽数字排版，只有总计或关键结论适度加粗，不将每个值都加粗。
 ## 各类页面规则
 ### 列表
 - 继续使用 `ListPageLayout + QueryToolbar + DataTable`。查询、批量操作、表格、分页构成连续工作区，不重复放置正文大标题或统计卡片。
 - “操作”列始终第一列，需要固定时固定在左侧。最多三个高频操作直接显示，更多操作使用已有菜单约定；保留页面已确认的直接操作数量。国内仓全部 7 个菜单及客户管理的行内业务操作采用下述纯文字描边按钮。危险动作保留明确文字与确认。
 - 列宽按实际编号、状态和按钮数量决定；不能把样板的 260px 操作列套给所有列表。核对最多按钮、加载中和权限变化后的布局。
 - 数值列右对齐，单位优先放表头；编号按业务需要设置宽度。保留横向滚动、列偏好、分页和已有行内编辑能力。
 #### 国内仓行内按钮（以订单列表样板统一）
 依据用户提供的白底描边按钮参考图，订单列表行内操作采用纯文字、白底、1px 细边框，无阴影，圆角 6px；保持 28px 高、13px 字号、600 字重、左右内边距 10px、按钮间距 6px。该按钮圆角为明确例外，普通内容容器仍为 0–4px。
 - 默认行内操作（详情、编辑、备注、更多）：蓝色文字 `#1777ff` 与浅灰边框，由 `--admin-action-neutral` 统一维护。
 - 审核“通过”：橙色文字与浅橙边框，保留原确认流程。
 - 测量：紫色文字与浅紫边框。
 - 悬停使用对应浅色底，键盘焦点保持可见；禁用、处理中状态保留。更多入口统一为 `…`（Lucide `MoreHorizontal`），保留包含业务对象的“更多操作”悬停提示和可访问名称；下拉项纯文字。
 该规则覆盖订单列表、订单测量、测量数据审核、预装清单、库位管理、托盘管理、整柜业务以及其详情中的行内操作。查看/编辑/备注为默认蓝色 `#1777ff`，测量为紫色，审核为橙色，启用为绿色，停用/删除为红色。预装共用组件只在 `preload` 模式接入，已确认装柜清单模式保持原规则。顶部查询/新增/批量操作和弹框提交仍使用 32px 主次按钮，不机械改成行内按钮，也不增加样板中不存在的业务操作。
 #### 客户管理按钮与详情
 - 客户列表、海外仓阶梯费用及关联详情、编辑、审核、预览的业务操作按钮采用纯文字；查询、重置、复制也去掉装饰图标。分页箭头、列设置、筛选布局、关闭与全屏等独立图标控件保留，处理中旋转图标保留。
 - 客户列表行内按钮沿用 28px 白底描边、6px 圆角、6px 间距：详情/编辑/更多为默认蓝色 `#1777ff`，审核为橙色，重置密码为紫色，跳转登录为蓝色，启用为绿色，停用/删除为红色。更多入口与订单列表统一显示 `…`，不显示“更多”文字；悬停提示及可访问名称保留，菜单项纯文字，保留原权限与操作分配。
 - 海外仓阶梯费用列表按原档位顺序显示“天数：单价”，在费用单元格中连续排列、整组自然换行；不制作每档独立白块，不强制左右两列，不隐藏后续档位。币种只在独立列展示，计费单位保留在表头；零单价照常显示 `0`，没有档位显示“—”。编辑按钮沿用默认蓝色 `#1777ff` 文字、白底描边。
 - 阶梯费用编辑弹框中的“新增阶梯”为蓝字浅蓝边、“删除”为红字浅红边，均使用 28px 高、6px 圆角的白底纯文字按钮；客户详情的海外仓费用编辑同步执行。底部保存/取消沿用 32px 主次按钮。按钮规则同时覆盖页面与 Teleport 弹框，并显式设置普通、悬停、焦点及禁用状态，避免默认主题色覆盖。
 - 客户详情保留彩色页签；企业信息用连续四组键值表，联系与合作信息保留三组键值表，长地址整行。资质文件采用连续行，企业成员使用表格。
 - 客户新增/编辑保留 1120px 三列表单，入驻审核保留 1040px，箱规规则编辑保留 1200px，海外仓阶梯编辑保留 1120px。宽度属于当前内容的适配值，不推广为全局默认。
 ### 详情与基本信息
 - 第一行集中放返回、业务编号、核心状态及主要操作。下一行用可换行摘要展示关键上下文，不使用大数字概览卡。
 - 返回使用 `density-back` 轻量导航，与业务编号和状态排在同一行，保留箭头、文字、键盘焦点及原返回目标。该行并入连续白底详情区域，不为返回单独增加卡片或空白行；整柜库存的标题行与基本信息共用一个信息区。
 - 页签紧接摘要。页签已表达的标题不再在正文重复占用一大行；数量、更新时间与相关操作可放紧凑工具栏。
 - 短字段通常每行四组，长内容跨两组或整行。描述表标签浅灰、数值白底，边线连续；标签宽度以 112px 为样板参考，按字段实际长度调整。
 - 保留字段顺序和业务分组，不使用会改变阅读顺序的自动密集填空布局。
 - 同一个订单或实体内部的内容连续分区，不再层层套卡片。
 ### 费用、汇总与测量
 - 汇总使用单行摘要或紧凑描述表。自动费用与其他费用保持各自业务口径，金额、单价、计费量、附加费和版本完整展示。
 - 保留公式、计费依据和价格来源入口，不能为了减少行数合并不同口径的金额或重量。
 - 测量各来源保留独立分组；展开时在表尾显示合计，折叠时在标题显示摘要，同一口径不在上下重复占位。
 - 同一计算策略只保留一个明确操作入口，保存中、无权限、冻结与失败信息照常显示。
 - 称重图片可用缩略图加紧凑事实行；保留查看原图、托盘/库位信息和人工修正入口。可视化、图纸、标签预览、库位示意等按业务用途保留合适尺寸。
 ### 历史、备注与空态
 - 大量状态历史与操作日志优先使用表格：时间、事件、状态、操作人、备注。保留全部记录和原有排序，不合并或删除相似事件。
 - 长备注自然换行；简短备注也可使用连续列表。空态使用简短文字，不用大型插画或为无数据区设置大最小高度。
 - 真实流程进度图可以保留，不能因日志样板是表格就删除业务需要的阶段关系。
 ### 弹框与表单
 - 保留各操作已确认的独立页面、居中弹框或抽屉承载方式。审核确认不自动变为完整详情；简单备注不套用大型作业弹框。
 - 标题和底部操作保持可见，长内容只滚动正文。优先使用 `AppDialog` 的原生标题栏和已有全屏能力。
 - 宽度按内容选择：简单确认/备注参考 560–600px，普通双列表单参考 680–920px，批量预览参考 1100px；订单测量作业样板为 1560px、92vh。以上是类型参考，不是所有弹框的统一固定尺寸。
 - 普通弹框参考上边距 6vh、最大高度 88vh；大型测量作业参考上边距 4vh、最大高度 92vh。全屏时使用组件的完整视口规则。
 - 表单控件、单位、必填标识、校验错误和原因说明完整保留。长表单按业务分组排两至四列，文本域按需跨列。
 - 审核确认清楚展示业务对象；批量审核保留逐票预览、选中数量和不可操作原因。保留处理中锁定、关闭未保存确认与失败上下文。
 ## 彩色图标
 导航性质的详情页签采用与客户管理一致的彩色 Emoji，同一语义尽量复用同一图标：
 | 语义 | 图标 |
 |---|---|
 | 基本信息 | 📋 |
 | 货品、货物明细 | 📦 |
 | 费用 | 💰 |
 | 历史、日志 | 📝 |
 | 测量、尺寸 | 📐 |
 | 其他资料 | 🗂️ |
 | 拆分履约 | 🧩 |
 | 计费规则（客户管理已有） | ⚖️ |
 图标只作辅助，保留文字标签；装饰图标设置 `aria-hidden="true"`。选中态通过文字色和底部横线表示，不把 Emoji 强制染成单色。采用系统彩色 Emoji 字体，不引入图片生成或外部图标下载依赖。
 彩色图标用于详情页签。国内仓 7 个菜单的行内按钮与客户管理业务操作使用纯文字；返回箭头、顶部与弹框的既有功能图标可保留。不要给操作按钮、表头或字段添加 Emoji。
 ## 国内仓推广清单与顺序
 此表是实施入口，不是完成状态。每个入口必须继续沿实际组件引用盘点可达弹框与详情，不把父页面验收等同于所有子界面通过。
 | 顺序 | 菜单 | 主入口（相对 apps/admin-web/src） | 本组应覆盖 |
 |---|---|---|---|
 | 样板 | 订单列表 | `modules/unified-orders/pages/UnifiedOrdersView.vue` | 列表、详情全部页签、测量、单票/批量审核及实际可达弹框 |
 | 1 | 订单测量 | `modules/inbounds/pages/InboundMeasurementsView.vue` | 列表、测量作业、称重图片与相关编辑/预览 |
 | 1 | 测量数据审核 | `modules/inbounds/pages/MeasurementReviewsView.vue` | 列表、审核工作区、明细、确认及当前实际存在的修正操作 |
 | 2 | 预装清单 | `modules/loading-lists/pages/PreloadPlansView.vue`、`PreloadPlanDetailView.vue` | 列表、详情各页签、相关确认及打印/预览容器 |
 | 3 | 库位管理 | `modules/warehouse-resources/locations/pages/LocationsView.vue` | 列表、详情、新增/编辑及实际存在的批量操作 |
 | 3 | 托盘管理 | `modules/warehouse-resources/pallets/pages/PalletsView.vue` | 列表、详情、新增/编辑及实际存在的关联操作 |
 | 3 | 整柜业务 | `modules/domestic-containers/pages/DomesticContainersView.vue`、`DomesticContainerInventoryDetailView.vue` | 入库/出库/库存工作区、库存详情与实际可达弹框 |
 每组先统一列表，再处理详情与弹框；同一业务工作区一起交付人工查看。未注册、已重定向或只存在于历史原型的页面不能只凭文件存在就恢复或加入本轮。
 ## 实现与验收
 1. 改造前读取最近指引，沿菜单、路由、组件与事件定位实际页面；填写逐操作矩阵。原型已有承载方式不因密度统一而替换，明确的样式改造可在已授权范围内推进。
 2. 多个真实消费者使用同类密度时，将稳定尺寸与布局能力收敛到本应用的样式变量或现有共享组件的可选能力。先明确接入范围，不让全局默认变化影响尚未改造的菜单。
 3. `adminDensityTokens.css` 定义默认值，`adminDensity.css` 承载通用组件规则；`orderDensity.css`、`measurementDensity.css`、`customerDensity.css` 只保留各自业务布局与引用公共变量的局部规则。按钮外观不得在模块中另写一套。跨菜单共用组件（如模拟柜创建、托盘码打印）通过可选 `dense` 参数接入；未传参数的调用保持原布局。
 4. 弹框经 Teleport 后必须仍能获得对应样式。检查普通、全屏、关闭、重开以及多个入口使用同一组件时的表现；避免无边界的全局 `.el-dialog`、`.el-table` 或 `!important` 覆盖。
 5. 每页检查长编号、长地址、多条数据、空态、失败态、无权限、禁用态及处理中状态；所有字段、单位、排序、权限与操作资格应保留。测试不得继续锁定已废弃的卡片结构，也不能删除业务断言以换取通过。
 6. 按 Admin 指引运行直接影响测试、类型检查、全量测试与构建；公共组件检查实际消费者。视觉默认由用户在指定视口操作并截图，缺少证据标记“待人工截图确认”；用户明确要求 AI 界面验收时，按本轮授权操作并记录实际证据，不将代码测试当作视觉通过。
 7. 每组交付说明修改页面、公共影响、检查结果、剩余视觉差异。任何尺寸或布局例外记录在逐页矩阵中，避免把一次性例外写成新的全局默认。
 逐页核对记录模板：
 | 页面/路由 | 操作及承载方式 | 原型或确认依据 | 采用规则/业务例外 | 检查与截图结论 |
 |---|---|---|---|---|
 | 填写具体页面 | 分别填写详情、编辑、审核、预览等 | 原型 ID、代码入口或用户确认 | 列表/描述表/日志/作业弹框等 | 代码检查结果；待人工截图确认或实际结论 |
 规范只记录稳定规则和入口。各组进度、临时问题与验收结果写入对应核对记录，不写入 `AGENTS.md`。
 ## 国内仓、客户管理的样式维护边界
 本节适用于已接入的两个菜单及其实际子组件，不改变其他菜单默认样式。此次收敛以保留业务字段、权限、计算与承载方式为前提。
 | 要修改什么 | 唯一维护位置 | 页面需要做什么 |
 |---|---|---|
 | 正文/辅助/分区/页头字号 | `adminDensityTokens.css` 的 `--admin-font-*` | 引用变量，不重新写 13px 等普通字号 |
 | 表格行高、输入高度、操作按钮高度、页签高度 | `--admin-row-height`、`--admin-control-height`、`--admin-action-height`、`--admin-tab-height` | 使用已有公共组件和公共类 |
 | 常用间距、圆角、普通数据区底色 | `--admin-space-*`、`--admin-radius`、`--admin-surface` 等 | 业务布局引用变量；不可在页面重定义变量默认值 |
 | 描边按钮外观、悬停/禁用/焦点状态 | `adminDensity.css` 的 `.density-action` | 只选择 `data-tone` 与业务事件 |
 | 详情返回导航 | `.density-back` | 使用 `link`，保留返回事件和可访问名称；客户管理按纯文字约定保留返回文字 |
 | 详情页头与业务摘要 | `.density-detail-header` / `.density-detail-heading` / `.density-detail-title` / `.density-detail-overview` | 与国内订单样板共用排版；页面提供实际业务编号、状态及摘要，不复制标题字号和摘要间距 |
 | 连续白底独立详情容器 | `DetailPageLayout` 上的 `.density-detail-layout` | 显式接入统一页头分隔线、正文间距与零区块间隙；正文去掉重复面板，业务仅保留列数和长字段跨列 |
 | 详情页签及彩色图标 | `.density-tabs`、`.density-tab-icon` | 保留标签、键盘事件和激活态；只配置业务内容 |
 | 现有 Element 详情页签 | `.density-element-tabs` | 保留 `el-tabs` 的键盘处理、权限条件与切换事件，标签复用彩色图标 |
 | 现有原生资料表、状态历史表 | `.density-table` | 保留字段、记录排序、业务列宽和固定操作列；不另写行高、边线和表头底色 |
 | 分组页面与弹框表单 | `.density-form` | 显式接入统一标签字号和字段间距，模块只维护列数、跨列及字段顺序 |
 | 既有 FormSection 分组 | `.density-form-section` | 在 `FormSection` 上显式添加，复用公共标题字号和分组间距，保留业务标题与分组顺序 |
 | Element 描述表 | `.density-descriptions` | 页面显式接入统一标签/内容字号与行高；保留原字段及列数 |
 | 连续信息表边框、标签底色、文字与内边距 | `.density-fields` | 只配置列数、跨列、字段顺序；特殊标签宽度使用局部 `--admin-field-label-width` |
 | 弹框/抽屉标题、正文滚动、底部间距 | `.admin-density-dialog` / `.admin-density-drawer` | 容器显式接入，保留该业务已确认宽度与作业高度 |
 | 客户资质列、测量对照列、预装信息布局 | 对应模块 CSS 或页面 `scoped` | 只保留业务列宽、列数、图片尺寸、定位与排列 |
 ### 使用约定
 ```html
 <!-- 业务按钮只选择语义，不复制尺寸、颜色及交互状态规则 -->
 <el-button class="density-action" @click="edit">编辑</el-button>
 <el-button class="density-action" data-tone="warning" @click="review">审核</el-button>
 <el-button class="density-action" data-tone="danger" @click="remove">删除</el-button>
 <!-- 更多入口仍是三点，必须保留可访问名称与悬停提示 -->
 <el-button class="density-action" aria-label="更多操作" title="更多操作">
  <MoreHorizontal :size="17" aria-hidden="true" />
 </el-button>
 ```
 `data-tone` 可用 `neutral`（默认）、`warning`、`purple`、`primary`、`success`、`danger`。每个页面仍按已确认的动作配色表选择；纯文字与图标策略不由 CSS 猜测。按钮组使用 `density-actions` 统一间距，业务布局可决定是否换行。
 `density-actions` 使用 `gap` 管理间距，并将 `--cc-list-action-sibling-margin` 设为 0；`DataTable` 通过该变量保留未接入按钮的默认 8px 左边距。不得将两份间距叠加，也不以更强选择器在页面逐个覆盖。
 ### 防止维护退化
 1. **同一通用外观只有一个实现。** 已由公共类接管的按钮配色、页签高度、信息表边框或弹框内边距，删除原页面声明，不能保留两套后再增加优先级或 `!important`。
 2. **新增通用尺寸先改变量。** 模块与页面只引用 `--admin-*`；禁止在页面重定义公共默认值。局部标签宽度是明确的业务参数，不改变全局标签宽度。
 3. **不要把代码搬到模块 CSS 就称为公共化。** 多个业务共用的按钮、页签、信息表与弹框规则留在公共层；模块 CSS 不能依赖另一个业务模块的类名，也不引入第二套按钮颜色变量。
 4. **保留显式接入边界。** 公共样式不能使用无范围的 `.el-button`、`.el-table`、`.el-dialog` 选择器。Teleport 的弹框、抽屉必须自己携带密度类；不能仅依赖页面父级。
 5. **共用组件保留未接入消费者。** CSS 变量的兜底值用于独立渲染和未接入入口；两个已接入模块始终由公共变量决定实际值，兜底值不是第二份密度配置。打印标签、PDF 尺寸、原图、画布和既有窄屏规则不能机械替换。
 6. **公共调整按消费者回归。** `adminDensity.test.ts` 维护明确的页面/组件清单，不扫描全部后台。检查模板中公共按钮、页签和信息表的真实祖先是否带有密度入口，不能仅断言文件导入了 CSS 或出现过密度类；页面弹框带有 `admin-density-dialog` 不代表列表与详情已接入。新增接入时同步清单及逐操作矩阵，运行合同、受影响测试、类型检查、全量测试和构建。
 7. **视觉与代码分开记录。** 本轮默认人工截图；代码通过不等于视觉验收通过。已确认业务宽度和工作区高度可以保留为例外，例外写入核对记录。
 ## 新模块接入规则
 ### 先确定范围，再选择公共能力
 1. 用导航与实际路由列出全部菜单入口，以及新建、详情、编辑和深链页面；不能把文件夹数量当作页面覆盖数。为每个页面沿实际组件引用列出弹框、抽屉、消息确认、预览与打印入口，按逐操作矩阵记录承载方式。
 2. 默认复用普通表格 36px 行高、正文 13px、辅助文字 12px、行内描边按钮 28px、页签 38px、轻量返回和连续信息表。新模块的行内业务操作默认纯文字；顶部/提交保留 32px 主次按钮。动作语义色沿用本规范，不通过按钮文字自动猜测。
 3. 模块只保留业务列宽、字段跨列、布局与图纸尺寸等参数。`density-fields` 的四列是默认值，不是固定业务要求；返回位置与大弹框尺寸也不能从订单整页复制。
 4. 编辑表格、流程图、装柜模型、数据看板、图片、标签和 PDF 保留业务所需面积；指标卡和图表不得套用 `.density-fields`或其他详情表格样式，模型画布和打印尺寸不套普通行高。空态、错误、长内容、处理中、只读和无权限仍要可用。
 ### 完整接入示例
 下面展示已有页面的接入结构，`rows`、`columns`、事件与表单仍使用该页面原实现。页面脚本直接导入 `@/styles/adminDensity.css`，不依赖先进入其他菜单后残留的样式，也不把这份 CSS 放入 `scoped` 样式块。
 ```vue
 <AdminPage class="admin-density">
  <ListPageLayout>
    <DataTable :data="rows" :columns="columns">
      <template #actions="{ row }">
        <div class="density-actions">
          <el-button class="density-action" @click="openDetail(row)">详情</el-button>
          <el-button class="density-action" data-tone="warning" @click="review(row)">审核</el-button>
        </div>
      </template>
    </DataTable>
  </ListPageLayout>
  <AppDialog class="admin-density-dialog" v-model="editorOpen" title="编辑资料">
    <!-- 原有业务表单 -->
  </AppDialog>
 </AdminPage>
 ```
 此结构只说明样式接入，不授权新增审核等业务动作。详情复用页面根节点的 `admin-density`；原生详情页签用 `density-tabs` / `density-tab-icon`，连续信息表用 `density-fields`。既有 Element 页签使用 `density-element-tabs`；页签栏与正文分离时隐藏空内容容器。在 `el-tab-pane` 内承载正文的页面必须同时使用 `density-contained-tabs`，保留正文并由公共样式设置内容间距。不得依赖页面 CSS 覆盖隐藏规则。既有原生资料/历史表用 `density-table`，分组表单用 `density-form`。返回按钮使用 `link class="density-back"`，跟编号、状态排在同一行。
 Teleport 弹框用 `admin-density-dialog`，抽屉框架用 `admin-density-drawer`，`ElMessageBox` 用 `customClass: 'admin-density-confirm'`；这些浮层必须各自声明，页面祖先不能替代。抽屉当前公共框架负责字号、标题和正文边距；其正文若复用页面级表格、信息表或按钮原语，在正文业务根节点显式接入 `admin-density`。不要把名为 Drawer 的嵌入组件当作实际抽屉，承载方式以模板和调用端为准。
 ### 共享组件与检查的扩展
 - 对每个共享组件列出真实调用方及模式。现有 `dense` 参数由调用入口显式传递；`mode` / `workbench` 属于业务范围，不能为了样式变更其含义。新增消费者后，对开启和关闭密度、国内和海外等实际模式分别回归。
 - `adminDensity.test.ts` 中菜单清单、`densityPages`、`consumers`、`moduleCss` 分别覆盖导航、独立入口、子组件和模块 CSS。接入时补充受影响清单，不移除国内仓和客户管理基线，也不通过递归扫描全后台推导范围。
 - 动态类检查显式执行预装/已确认、`dense` 开/关，以及 DOMESTIC/OVERSEAS 入口；货柜已确认清单与船期浮层有独立开关断言。接入其他条件时补充真实上下文和对应开关用例，不能一律传 `preload`、强行把所有条件置真，或只断言出现过类名。
 - 检查必须同时覆盖 CSS 独立导入、公共原语的实际祖先、Teleport 容器自己的类、变量定义与消费、按钮间距、普通/悬停/焦点/禁用，以及原有业务行为。源码合同只防止已知结构退化，不能证明最终 CSS 优先级或布局视觉正确。
 - 发布前的代码门禁为密度合同、受影响业务测试、类型检查、全量测试和构建；维护指引后运行 AGENTS 索引合同。人工按 1920×1080、100% 缩放检查独立打开/刷新、列表到详情、浮层普通/全屏/重开、长数据和权限状态。缺少对应截图时保留“待人工截图确认”。
@@ -0,0 +1,97 @@
 # Client 界面样式规范
 ## 范围与验收状态
 - 本规范由客户端样式对话确认建立，首个验收样板为“头程物流 → 订单列表”（`/orders/first-leg`）。当前为首版实现，待人工截图确认；通过后再逐模块推广。
 - 只维护 `apps/client-web/` 内的样式和公共组件，不与 Admin 跨应用链接依赖。
 - 左侧菜单背景保持现状，不修改 `shell.css` 中的导航背景，也不通过全局品牌变量间接改变导航。
 - 标准通过正文容器 `.client-ui` 接入；首批覆盖订单列表。创建、详情与其他模块需分别核对承载方式和字段，不以列表通过代替整模块验收。
 - 按 1920×1080、浏览器缩放 100% 验收，保留现有窄屏能力。
 ## 公共入口与职责
 | 入口（相对 apps/client-web） | 职责 |
 |---|---|
 | `src/styles/client-ui.css` | `--client-*` 颜色、尺寸、间距；正文按钮和状态外观 |
 | `src/components/common/QueryToolbar.vue` | 搜索栏；`layout="grid"` 为四列筛选布局 |
 | `src/components/common/DataTable.vue` | 表格、工具栏、行操作、分页；工具栏内容用插槽提供 |
 | `src/components/common/tableActions.ts` | 三个操作以内全部展示，超过三个折叠；禁用和加载状态执行保护 |
 | `src/modules/first-leg/utils/firstLegOrder.ts` | 头程状态码 → 语义色，不在公共样式中判断业务状态码 |
 页面只提供字段、操作、业务状态与权限，不再覆盖公共工具栏 padding、表格行高及分页 padding。确有业务差异时增加明确的组件能力，避免重复页面 CSS。
 ## 尺寸与布局
 | 项目 | 标准 |
 |---|---|
 | 正文、表格、按钮字号 | 13px |
 | 次要说明、状态字号 | 12px |
 | 普通按钮、输入框 | 高 32px |
 | 表格行操作按钮 | 高 28px，左右 padding 8px |
 | 按钮间距 | 8px |
 | 搜索栏 | padding 16px；四列；字段间距纵向 12px、横向 16px |
 | 搜索操作区 | 顶部 margin 12px、padding 12px，分隔线与字段区区分 |
 | 表格工具栏 | 最小高 48px；padding 8px 16px；实际高度随操作换行增长 |
 | 表头 | 高 44px，浅灰底，600 字重 |
 | 数据行 | 高 48px；白底与浅灰交替，悬停浅蓝 |
 | 单元格 | 左右 padding 12px，行高 20px |
 | 分页 | 最小高 58px；padding 12px 16px；页码按钮 32px |
 | 内容分区间距、圆角 | 16px、6px |
 长编号保持可辨认，普通长文本省略并提供完整内容提示；金额右对齐，状态居中。操作列在业务列最左侧并固定，批量选择框在其前方。列设置、排序与选择行为保持原有业务逻辑。
 ## 颜色与按钮
 | 用途 | 文字色 | 背景色 |
 |---|---|---|
 | 默认操作 | `#1777ff` | 白色 |
 | 主要操作 | 白色 | `#1777ff` |
 | 处理中 | `#175cd3` | `#eff8ff` |
 | 成功 | `#067647` | `#ecfdf3` |
 | 待处理、提醒 | `#b54708` | `#fffaeb` |
 | 失败、危险 | `#b42318` | `#fef3f2` |
 | 草稿、中性 | `#475467` | `#f2f4f7` |
 | 禁用按钮 | `#98a2b3` | `#f9fafb` |
 - 查询、创建等主要操作使用实心蓝色；行内详情、编辑等使用白底描边蓝字，统一使用纯文字，不显示装饰图标。加载中的进度指示保留。
 - 行操作先按权限及业务条件过滤，再计算数量；1–3 个全部展示，4 个及以上显示前两个和 `…`。入口保留“更多操作”的可访问名称。
 - 禁用操作不被隐藏，不因禁用改变位置；加载中不可重复执行。
 - 表格顶部批量操作不套用行操作的三个阈值，保留明确的批量入口和创建入口。
 - 危险操作仍需原有业务确认；样式不改变权限和提交条件。
 ## 头程状态映射
 | 状态码 | 文案 | 语义色 |
 |---|---|---|
 | DRAFT | 草稿 | 中性灰 |
 | PENDING_REVIEW | 待审核 | 提醒橙 |
 | WAIT_MEASURE | 待测量数据 | 处理中蓝 |
 | WAIT_PALLETIZE | 待组托 | 处理中蓝 |
 | WAIT_SPLIT | 待分柜 | 处理中蓝 |
 | LOADING | 装柜中 | 处理中蓝 |
 | LOADED | 装柜完成 | 成功绿 |
 | DELIVERED | 派送完成 | 成功绿 |
 | COMPLETED | 已完成 | 成功绿 |
 测试环境复验补充：服务端统一订单已正式返回 `COMPLETED`，列表、筛选和详情沿用该状态，不能再显示英文或映射成“装柜完成”。订单号列宽 240px，入仓码列宽 230px，状态默认紧随入仓码，保证首屏可识别。
 标签包含状态文字，颜色为辅助识别。其他模块需按业务阶段单独列出状态映射，不以中文模糊匹配统一推断；未知状态不得伪装为处理中或完成。
 ## 样板逐操作验收矩阵
 | 检查对象 | 首版目标 | 验收方式 |
 |---|---|---|
 | 左侧菜单 | 背景与修改前一致 | 同视口截图对照 |
 | 列表首屏 | 筛选、工具栏、表格、分页层次一致 | 有数据的完整页面截图 |
 | 搜索 | 查询和重置有效；输入框不遮挡、字段标签完整 | 查询前后、重置后 |
 | 工具栏 | 列设置、下载、导出、批量提交、批量导入、创建入口保留 | 未选择/已选择/无写权限 |
 | 行操作 | 1、2、3 个不折叠；4 个时前两个加省略入口 | 按权限与业务条件验证，不修改真实订单来凑状态 |
 | 状态 | 草稿、待审核、处理中、装柜完成的语义颜色不同 | 对照多状态列表 |
 | 表格 | 横向滚动时选择、操作、订单号可用；完整值可查看 | 长编号、长渠道、空值、列重排 |
 | 分页 | 条数和页码完整；更换条数回到第 1 页 | 10/20/50 条、首尾页 |
 | 加载/失败/空态 | 失败保留重试和工具栏；不把失败显示为无订单 | 加载、失败重试、空结果 |
 | 关联操作 | 详情、费用、编辑、报关入口保持原有行为 | 只读打开核对；写入另按授权执行 |
 自动化检查不代替真实页面截图。列表样板确认前，不将其他 21 个菜单标记为已统一或已验收。
 2026-09-15 经用户明确授权完成内置浏览器验收：测试部署 `client-web-test #282`、提交 `7068f49` 成功；1920×1080、100% 缩放下检查首屏、筛选重置、全选、列设置、10/20/50 分页、横向固定列、详情入口以及灰/橙/蓝/绿状态。实测工具栏 padding 为 8px 16px，分页为 12px 16px，表头/行高为 44px/48px，行按钮 28px、#1777ff；菜单背景与部署前一致。四操作折叠分支仅自动化覆盖，缺少真实四操作数据；用户对视觉标准的最终确认待完成。
@@ -1,21 +1,69 @@
 # 虫虫出海文档索引
-项目交付文档按阶段归档，跨阶段原型、调研和过程设计保留在原专题目录。
+项目交付文档按业务域组织。当前开发环境以端到端全流程为统一范围；历史规划、确认和验收记录保留在对应业务域目录，仅用于追溯决策，不构成功能边界。
-## 阶段文档
+## 业务域文档
- [一期文档](一期/README.md)：一期范围、开发进度和头程订单最小闭环。
+- [业务快速索引](业务快速索引.md)：按关键词检索跨端代码入口与业务边界；先查根 AGENTS.md 短路由，按需读取命中行。
 - [二期文档](二期/README.md)：预约取货、到仓收货、实测差异和指定库位闭环。
 - [三期文档](三期/README.md)：智能排柜、订舱、拖车、PDA 拣货、报关协同和国内出仓闭环。
-## 跨阶段参考
+- [订单与客户](订单与客户/README.md)：登录认证、客户与企业、权限、头程订单和客户工作台。
 - [入库测量与计费](入库测量与计费/README.md)：预约取货、到仓收货、箱码与箱唛、测量、尺寸策略、计价和入库费用。
 - [国内货柜履约](国内货柜履约/README.md)：分柜与同柜、智能排柜、订舱、拖车、PDA 拣货、装柜、报关和国内出仓。
  - [船期日历功能规划](国内货柜履约/船期日历功能规划.md)：渠道、周模板、单次船期、收货截止时间和按渠道货量统计的独立日历规划。
 - [海外仓业务](海外仓业务/README.md)：船节点、海外接柜、入仓、库存、托盘、换标、转运、废弃、退货、排车、PDA 出库、派送、异常退回、客户回访、一件代发及海外本土业务。
  - [船节点标准化契约](海外仓业务/船节点标准化契约.md)：统一船司原始状态、标准节点、预计/实际时间、异常事实、还柜停止规则和新增船司接入门禁。
 - [财务管理](财务管理/README.md)：应收、应付、费用池、账单、收款、成本、核销、凭证以及国内外业务费用来源。
 - [打印标签维护](打印标签维护/README.md)：箱唛、各类托盘标、HOLD、BOL 与其他单据的现状盘点、参考样张和逐项改版记录。
- `悦/`：产品原型、流程图、历史架构资料和调研数据，仅作为需求参考，不直接等同于已确认范围。
+## 全流程公共契约
- `superpowers/`：具体功能的设计与实施记录，按日期和主题维护。
+
 ### 当前流程入口（收尾变更只看这里）
 - [头程到尾程当前维护入口](头程到尾程/README.md)：集中进入总览、六个阶段、货柜入口、报关专题，以及页面和需求参考。
 ### 历史与参考（保留，不作为日常流程入口）
 - [头程到尾程历史文档](归档/头程到尾程/README.md)：全流程操作手册、旧现状全景、AI 上下文和易用性方案。
 - [国内货柜履约历史记录](国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收矩阵、审计和旧确认材料。
 以上文件继续保留，分别用于历史现状、操作说明和方案追溯；开发规划、进度、门禁和验收记录也按业务域保留，不再与当前节点总表同步改写。
 - [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。
 - [双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。
 - [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。
 - [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单状态、操作编码、内部状态映射和可信履约回传边界。
 - [Admin/Client 前端原型还原验收规则](Admin-Client前端原型还原验收规则.md)：页面操作承载方式、视觉还原、响应式检查和验收证据要求。
 - [Admin 高密度界面规范](Admin高密度界面规范.md)：已确认订单样板的字号、间距、表格、描述表、弹框和彩色页签规则，以及国内仓、客户管理推广入口。
 - [Admin 客户管理样式核对记录](Admin客户管理样式核对记录.md)：客户列表、海外仓阶梯费用及关联详情和弹框的样式与人工验收项。
 - [Admin 国内仓样式核对记录](Admin国内仓样式核对记录.md)：7 个菜单、关联详情与浮层的范围、样式复核和验收证据。
 - [Admin 货柜管理样式核对记录](Admin货柜管理样式核对记录.md)：订舱、拖车、送柜报关、清关提柜入口及共享组件边界。
 - [Admin 海外仓样式核对记录](Admin海外仓样式核对记录.md)：海外仓 10 个菜单、独立详情、作业弹框和共享组件显式接入边界。
 - [AI 工程执行与协作约束](AI工程执行与协作约束.md)：工作区、依赖、Git、部署、数据库、质量门禁和独立任务协作规则。
 - [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
 - [数据库版本迁移与 Jenkins 自动发布方案](数据库版本迁移与Jenkins自动发布方案.md)：两人团队自动迁移规划；统一工具入口、自动编号、开发/测试/生产执行分工、单服务迁移范围、漏写迁移检查、Flyway 校验、失败候选修订、发布证据保留、带数据升级演练及实施顺序。
 - [数据库迁移操作手册](../baiyue-firstleg/deploy/sql/数据库迁移操作手册.md)：开发者和发布执行人日常使用说明；包含新建、检查、生成清单、测试执行、生产晋级、失败处理和维护规则。
 - [生产服务监控告警与无停机发布方案](生产服务监控告警与无停机发布方案.md)：容器与外部可用性监控、部署期告警处理、自动恢复、发布通知及滚动/蓝绿发布演进方案。
 - [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、健康检查与失败处理。
 - [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：ECS/ALB、RDS MySQL、Redis、OSS、Nacos、RocketMQ、压测、高可用、监控、备份与上线清单。
 - [阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)：Admin、Client、国内/海外 PDA 文件接入 OSS 的区域拓扑、存储适配、权限、一致性、实施拆分、验收门禁和方案评审。
 - [首页数据看板真实化与统计策略规划](首页数据看板真实化与统计策略规划.md)：首页指标、实时与缓存边界、统计口径和实施顺序。
 - [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：测量设备经 Gateway 上传箱码、尺寸、重量和图片的接口契约。
 ## 环境协作
 - [开发环境独立任务协作登记](开发环境独立任务协作登记.md)：开发环境全流程总控与长期专项的稳定任务、职责及开发数据库/部署/HTTP 授权。
 - [测试环境独立任务协作登记](独立任务协作登记.md)：登记已清空，任务由用户手动管理。
 - [测试任务盘点与需求台账](测试任务盘点与需求台账.md)：历史任务快照、未闭环需求、提交线索和待核实证据，不作为当前调度依据。
 ## 参考资料
 - `悦/`：产品原型、流程图、历史架构资料和调研数据，只作为需求参考，不直接定义当前范围。
 - `superpowers/`：按日期和主题保留的具体功能设计与实施记录。
 ## 维护规则
- 只影响单个阶段的范围、进度和验收文档放入对应阶段目录。
+- 新文档按业务域归档，不新增以开发批次编号命名的目录、文件、标题、任务或范围标签。
- 公共架构、跨阶段契约和长期产品资料保留在 `docs/` 根目录或独立专题目录。
+- 已完成开发阶段的流程手册、规划、进度和验收资料统一放入 `归档/`；后续流程变更只从[头程到尾程当前维护入口](头程到尾程/README.md)进入。
- 阶段范围变化时同步更新该阶段的规划、进度表及受影响的公共契约。
+- 当前交付范围始终按端到端全流程理解；业务域目录只用于检索和职责归属，不用于排除上下游流程。
- 原型中出现的功能不自动进入开发范围，必须在阶段规划中明确优先级、依赖和验收标准。
+- 范围、字段或流程冲突时，按“当前对话确认 > 正式契约与确认记录 > 项目指引与代码 > 原型 > 历史记录”判断。
 - 新增或修改业务能力时，同步更新业务域 README、跨端契约、接口、权限、SQL、测试和验收入口。
 - 原型中出现的功能不自动成为有效实现；必须由正式契约、代码和验收证据共同确认。
@@ -59,7 +59,7 @@
 - 退出操作先调用权限预览 Store 的重置动作，清除内存状态与持久化演示角色 ID，再调用 `auth.logout()`；认证 Store 不承担预览状态职责。
 - 登录成功后由登录流程调用权限预览 Store 的初始化动作，默认选择启用的超级管理员；超级管理员不可用时选择第一个启用角色。未登录阶段不自动初始化或重新持久化默认角色。
 - 顶栏固定区分两个来源：`登录身份：{auth.user.name}（{auth.user.account}）` 与 `权限预览：{previewRole.name}`。认证角色 `auth.user.roles` 不作为无标签副标题展示，也不被预览状态读取或改写。
- `localStorage` 在同源标签页之间共享，但本期不监听 `storage` 事件做实时跨标签同步；其他标签页刷新后读取最新持久化角色。
+- `localStorage` 在同源标签页之间共享，但当前不监听 `storage` 事件做实时跨标签同步；其他标签页刷新后读取最新持久化角色。
 ### 权限数据流
@@ -1,23 +0,0 @@
 # 一期文档
 一期目标是完成平台后台与企业客户端的真实业务基础，以及头程订单最小闭环。
 ## 文档
 - [一期开发进度表](一期开发进度表.md)
 - [一期头程订单闭环设计](一期头程订单闭环设计.md)
 - `虫虫出海一期开发进度表.xlsx`：面向团队日常维护的 Excel 进度表。
 ## 原型来源
 - 产品原型统一位于 `docs/悦/`。
 - 企业登录与注册分别参考 `docs/悦/合并/login.html`、`docs/悦/合并/register.html`；一期只默认包含中文账号密码登录和基础企业注册闭环。
 - 快递公司和往来单位参考 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` 中“通用”菜单下的对应页面。
 - 原型用于确认信息架构、字段和视觉方向；是否已进入当前 Vue 应用、是否具备完整交互与数据持久化，以一期开发进度表为准。
 ## 当前边界
 - 平台后台：内部账号登录、客户及企业资料审核、内部用户、角色权限、平台收货仓、快递公司、往来单位和头程订单；工作台不作为一期交付项。
 - 企业客户端：中文邮箱/手机号加密码登录、免审核企业注册、企业资料、成员角色权限、头程下单、订单列表和详情；企业资料经平台人工审核通过后才允许提交订单，一期不接短信/邮箱验证码及微信、企业微信登录。
 - 服务端：认证、租户隔离、权限、文件、基础资料、订单状态机、幂等和审计。
 - 不包含工作台、部门/组织架构、完整 WMS、FBA/海外目的仓服务、在线报价、财务结算、完整报关清关、外部物流接口、多语言及微信/企业微信登录；快递公司和往来单位一期支持批量导入，不提供导出。
@@ -1,16 +0,0 @@
 # 三期文档
 三期以头程物流“03 出仓”为范围，完成从排柜、订舱、拖车和仓内拣货，到封柜、报关、国内出仓并等待装船的业务闭环。
 ## 文档
 - [三期开发规划：国内出仓](三期开发规划.md)
 - [三期开发进度表](三期开发进度表.md)：参考一期采用“大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”结构维护。
 - [虫虫出海三期开发进度表（Excel）](虫虫出海三期开发进度表.xlsx)：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。
 - [三期需求确认表](三期需求确认表.md)：集中跟踪 P3-Q1～P3-Q13、负责人和最终结论。
 - [三期页面与原型清单](三期页面与原型清单.md)：按管理后台、企业客户端和 PDA 维护页面范围及原型状态。
 - `参考资料/出仓流程.png`：本期 9 个核心动作及业务终点的原始参考图。
 ## 当前状态
 三期处于范围规划阶段，当前开工结论为 `NO-GO`。当前以原型图片中的“完成国内出仓，等待装船”为阶段终点。动作依赖与并行关系、排柜规则、PDA 设备、拖车协作、柜封照片清单、报关回执及放行门禁、港务/船期信息范围和来源仍需在启动前确认。产品和业务完成确认后先进入契约与任务准备，六项开工准入全部通过后再进入全面功能开发。
@@ -1,310 +0,0 @@
 # 虫虫出海三期开发规划：国内出仓
 > 创建日期：2026-07-28  
 > 状态：范围规划中  
 > 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；当前以图片中的“完成国内出仓，等待装船”为阶段终点  
 > 前置阶段：[一期文档](../一期/README.md) · [二期文档](../二期/README.md)
 ## 一、三期目标
 三期承接二期“货物完成到仓、实测、差异处理和指定库位”的结果，将已受理货物转化为可执行、可追踪、可审计的国内出仓任务。
 流程覆盖九个动作：
 ```text
 智能排柜 → 订舱 → 预约拖车
    ↓
 PDA 拣货 → 装柜并上传货柜/铅封照片
    ↓
 客户上传报关资料 → 平台整理提交报关代理 → 上传回执供客户下载
    ↓
 查询或维护预计开船、到港等港务/船期信息
    ↓
 完成国内出仓，等待装船
 ```
 三期完成标准不是“订单改成已出仓”，而是每个柜次能够回答：装了哪些订单和货物、依据什么方案排柜、订了什么舱、谁承运拖车、仓库实际拣装了什么、柜号与铅封是什么、报关资料和回执在哪里、实际何时出仓、当前等待哪一班船。
 ### 原型动作覆盖
 | 原型动作 | 规划模块 | 开发任务 | 覆盖结果 |
 |---|---|---|---|
 | 1. 智能排柜 | 智能排柜 | P3-PLAN-01、P3-PLAN-02 | 已覆盖，规则待 P3-Q1 确认 |
 | 2. 订舱 | 订舱与港务/船期信息 | P3-BOOK-01 | 已覆盖 |
 | 3. 预约托车 | 预约拖车 | P3-TRUCK-01 | 已覆盖，用词待 P3-Q3 确认 |
 | 4. PDA 拣货 | PDA 拣货与复核 | P3-PICK-01、P3-PDA-01、P3-PDA-02 | 已覆盖 |
 | 5. 拍货柜及铅封照上传 | 装柜及柜封证据 | P3-LOAD-01、P3-LOAD-02 | 已补充现场拍照上传任务，清单待 P3-Q6 确认 |
 | 6. 客户上传报关资料 | 报关资料协同 | P3-CUS-01 | 已覆盖 |
 | 7. 整理给到报关代理报关 | 报关资料协同 | P3-CLEAR-01 | 已覆盖 |
 | 8. 回执上传到系统供客户下载 | 报关回执与客户下载 | P3-CLEAR-01、P3-CUS-02 | 已覆盖，回执类型待 P3-Q12 确认 |
 | 9. 查港务信息（预计开船、到港等） | 订舱与港务/船期信息 | P3-PORT-01、P3-CUS-02 | 已补充独立查询任务，范围和数据源待 P3-Q9 确认 |
 ## 二、阶段边界
 ### 纳入三期
 - 出仓单、柜次、智能排柜建议、人工调整和版本确认。
 - 订舱申请、舱位结果，以及原型所述预计开船、到港等港务/船期信息；具体字段和数据源待确认。
 - 预约拖车、车辆司机、到仓装柜和离仓记录。
 - PDA 任务领取、扫码拣货、部分拣货、异常、复核和幂等提交。
 - 装柜、柜号、铅封号及货柜/铅封照片证据。
 - 客户上传报关资料、平台审核补件、整理并提交报关代理。
 - 报关回执上传、版本、客户可见范围和授权下载。
 - 国内出仓门禁、确认、冲正、时间线和站内通知。
 ### 明确不纳入三期
 - 入库、上架、实时库存、移库、盘点、冻结、补货和完整 WMS。
 - 港区闸口、车队、船公司、海关单一窗口的正式自动化接口。
 - GPS 实时跟车、电子铅封、称重设备、摄像头 OCR 和 IoT 自动采集。
 - 自动报关、关税计算、退税、完整清关业务和自动单证识别。
 - 海上运输、海外清关、目的港提柜、海外仓入库和末端派送。
 - 无人工确认的全自动排柜、自动订舱和不可逆业务操作。
 ## 三、参与角色与数据边界
 | 角色 | 数据范围 | 主要操作 |
 |---|---|---|
 | 企业订单操作员 | 当前企业订单与出仓单 | 上传/补充报关资料、查看出仓和港务/船期进度、下载回执 |
 | 平台运营 | 授权客户、订单和出仓单 | 创建出仓单、确认排柜、订舱、维护港务/船期信息和协调异常 |
 | 仓库主管 | 被授权的平台收货仓 | 分配拣货任务、复核差异、确认装柜和出仓条件 |
 | 仓库作业员 | 分配给本人或本仓的任务 | PDA 扫码、数量确认、异常上报和任务提交 |
 | 拖车调度员 | 授权出仓单与车辆范围 | 预约车辆、维护司机/车牌、到仓和离仓节点 |
 | 报关专员 | 授权客户、订单和报关批次 | 审核、退回、整理、提交资料并上传回执 |
 | 平台管理员 | 平台授权范围 | 维护权限、规则、服务商和高风险冲正 |
 服务端必须依据登录身份确定企业、仓库、客户和数据范围。前端传入的订单 ID、出仓单 ID、仓库 ID、客户 ID、作业员 ID 或报关批次 ID 不能单独作为授权依据。
 ## 四、流程与状态设计
 原型以 1 至 9 编号表达动作顺序，但尚未说明哪些是强制前置、哪些允许并行。当前按原型顺序规划业务节点，同时使用主状态和子流程状态保留后续调整空间；在 P3-Q11 确认前，不把并行关系写成固定业务规则。
 ### 1. 出仓单主状态
 | 稳定编码 | 中文名称 | 含义 |
 |---|---|---|
 | `DRAFT` | 草稿 | 出仓单已创建，排柜方案尚未确认 |
 | `PLANNING` | 排柜中 | 系统生成建议或人工调整方案 |
 | `PREPARING` | 出仓准备中 | 按已确认的依赖关系处理订舱、拖车、拣货和报关 |
 | `READY_TO_DISPATCH` | 待出仓 | 必要子流程和证据已满足 |
 | `DISPATCHED` | 已出仓 | 货柜已离开国内仓库 |
 | `WAITING_FOR_LOADING` | 等待装船 | 国内出仓已完成，等待对应船班装船 |
 | `CANCELLED` | 已取消 | 按规则取消并保留原因与历史 |
 | `BLOCKED` | 已阻塞 | 存在必须人工解除的关键异常 |
 ### 2. 子流程状态
 - 订舱：待订舱、订舱中、已订舱、订舱失败、已取消。
 - 拖车：待预约、已预约、车辆已到仓、装柜中、已离仓、改约、已取消。
 - 拣货：待分配、待拣货、拣货中、待复核、已完成、异常挂起、已取消。
 - 报关：资料待上传、资料待审核、待补件、待提交、已提交代理、回执待上传、回执已上传、已退回、已取消。海关放行如需管理，作为待确认的回执类型或后续状态，不默认作为三期出仓门禁。
 - 港务/船期：待维护、已确认、信息变更、已开船；“已开船”属于三期之后的运输阶段，不是当前三期完成条件。
 主状态由服务端根据已确认的必要子流程推进。客户端不得通过传任意目标状态跳过拣货复核、柜封证据或已配置的出仓门禁。
 ## 五、业务模块
 ### 1. 出仓单
 - 从已上架且允许出仓的头程订单创建一张或多张出仓单。
 - 支持一张订单分多个柜次，也支持多个订单拼柜，具体开放范围由产品确认。
 - 保存订单、客户、仓库、货物、往来单位和计量数据快照。
 - 维护计划出仓时间、优先级、负责人、异常和整体时间线。
 - 重复创建和确认使用幂等键，并通过版本字段防止并发覆盖。
 ### 2. 智能排柜
 - 原型仅明确“智能排柜”，具体硬约束、软偏好、输入数据和输出结果以 P3-Q1 的业务规则表为准。
 - 柜型容量、重量、体积、箱数、同票/混票、不可混装、装载顺序和利用率暂列为候选能力，不作为未经确认的固定验收项。
 - 当前建议首版采用“系统建议、人工确认”；是否允许调整、是否强制填写原因由排柜规则确认。
 - 建议排柜方案保留版本、规则版本、输入快照、操作者和前后差异，以支持追溯。
 - 未确认方案不得生成正式拣货任务或执行不可逆状态变化。
 ### 3. 订舱与港务/船期信息
 - 原型明确需要查询预计开船、到港等港务信息；“港务信息”的准确业务含义、字段范围和归属以 P3-Q9 为准。
 - 船公司/订舱代理、航线、订舱号、船名航次、起运港、目的港、截单、截关、截港、ETD 和 ETA 暂列为候选字段。
 - 订舱失败、改船、甩柜、船期延误和取消暂列为候选异常场景，按业务确认结果实现。
 - 港务信息查询与人工维护分开设计：三期至少支持查询系统内已维护的信息，并记录查询条件、数据来源和更新时间；如后续确认可靠外部数据源，再通过预留适配边界接入，不在三期默认承诺正式接口。
 - 客户查看预计开船、到港等信息时展示数据来源和最近更新时间，避免把过期结果显示为实时信息。
 - 当前建议首版由平台人工维护，外部港务或船期接口只预留适配边界。
 - 建议关键信息变更保留旧值、新值、原因，并向授权用户发送站内提醒。
 ### 4. 预约拖车
 - 从往来单位选择已启用拖车服务商，维护车牌、司机、电话和预约时间窗。
 - 记录提柜、到仓、装柜、离仓、还柜节点和交接说明。
 - 支持改约、取消、迟到、未到、车辆更换和柜号变更。
 - 司机手机号等个人信息按最小权限展示，不进入不必要的客户响应。
 - 图片原文“预约托车”建议统一为行业常用的“预约拖车”，需产品最终确认。
 ### 5. PDA 拣货与复核
 - 按已确认排柜方案生成仓库、柜次、订单和货物明细级任务。
 - PDA 支持登录、领取、箱号选择、扫码、数量确认、部分拣货、跳拣、撤销和异常上报。
 - 服务端校验任务归属、状态、重复扫码、超量、错货和重复提交。
 - 拣货完成后必须复核；差异未处理前不得进入待出仓。
 - 扫描器、声音、震动、网络和缓存通过设备适配层实现，不直接绑定单一厂商 SDK。
 ### 6. 装柜及柜封证据
 - 维护柜号、铅封号、装柜开始/完成时间、操作人和异常说明。
 - 支持按可配置清单上传货柜及铅封照片；柜体、开门空柜、装柜过程、满柜、关门和铅封照仅为候选类型，必传类型、角度和数量以 P3-Q6 为准。
 - 现场执行端支持直接拍照或从相册选择后上传，上传前显示柜次、柜号、铅封号和照片类型，防止证据关联错误。
 - 支持上传进度、失败重试、重复照片提示和提交前预览；弱网下不得因重复点击产生多份有效证据。
 - 照片记录文件哈希、上传人、上传时间、关联柜次和客户可见范围。
 - 铅封号重复、已确认的必传照片缺失或复核未通过时禁止确认出仓。
 - 修改柜号或铅封号需要二次确认、原因和完整审计。
 ### 7. 报关资料协同
 - 客户按资料清单上传发票、箱单、合同、委托书和申报要素等文件。
 - 资料清单可按国家/地区、渠道和货物类型配置，并保存订单使用的清单版本。
 - 平台报关专员审核完整性，可退回具体文件并记录补件原因和时限。
 - 提交报关代理时生成提交批次，冻结该批次关联的文件版本。
 - 首版采用系统内整理加线下提交，不直接对接海关单一窗口。
 ### 8. 报关回执与客户下载
 - 上传代理回传的报关回执并关联提交批次；回执类型可区分接收、申报、退单、查验或放行等，实际类型及出仓门禁以 P3-Q12 为准。
 - 替换文件产生新版本，不覆盖原记录；退单或补件形成明确任务。
 - 客户只能下载本企业且标记为客户可见的回执。
 - 文件下载使用授权地址并记录审计，不暴露内部存储路径。
 ### 9. 国内出仓确认
 - 服务端校验排柜已确认、拣货复核完成、已确认的柜封证据齐全、车辆已离仓，以及已配置的报关回执和港务/船期信息门禁。
 - 当前不默认要求“海关已放行”后才能确认国内出仓；是否需要放行或其他特定回执作为门禁，以 P3-Q12 的业务结论为准。
 - 授权人员执行确认出仓，记录实际出仓时间、车辆、柜号、铅封号和说明。
 - 确认操作具备幂等、权限、版本和并发校验，重复请求只产生一次有效事件。
 - 完成后进入“等待装船”，企业客户可查看允许公开的节点、港务/船期信息和回执。
 - 出仓后发现错误不得直接回退数据库状态，必须使用授权冲正动作和反向审计事件。
 ## 六、核心数据对象
 | 数据对象 | 关键内容 |
 |---|---|
 | 出仓单 | 订单、企业、仓库、计划/实际时间、主状态、负责人和版本 |
 | 排柜方案 | 经确认的规则版本、输入快照、柜次、货物分配、规则计算结果和确认记录 |
 | 柜次 | 柜型、柜号、铅封号、装载顺序、重量、体积和关联订单 |
 | 订舱记录 | 船公司/代理、订舱号、船名航次、港口、舱位和异常 |
 | 港务/船期节点 | 经确认的信息字段、变更历史和来源；候选字段包括截单、截关、截港、ETD 和 ETA |
 | 拖车预约 | 服务商、车辆、司机、预约时间窗、到离仓节点和异常 |
 | 拣货任务 | 柜次、货物明细、分配人、作业员、扫描、数量、差异和复核 |
 | 装柜证据 | 柜号、铅封号、照片类型、文件、上传人、时间和可见范围 |
 | 报关批次 | 资料清单版本、文件版本、补件、提交代理和回执 |
 | 出仓时间线 | 事件、前后状态、操作者、发生时间、说明和请求关联 ID |
 基础资料引用必须同时保存稳定 ID 和必要快照。订单、客户、仓库、往来单位、港务/船期信息或文件后续修改时，不得改变历史出仓记录。
 ## 七、应用范围
 ### 管理后台 `apps/admin-web`
 - 出仓单列表、筛选、详情、异常和状态操作。
 - 按已确认的排柜规则提供建议、冲突展示、人工调整、版本对比和确认。
 - 订舱、船期、拖车预约、装柜、柜号、铅封和照片。
 - 报关资料审核、补件、提交批次、回执上传和客户可见控制。
 - 权限至少拆分为查看、排柜、订舱、拖车、仓内复核、报关、确认出仓和冲正。
 ### 企业客户端 `apps/client-web`
 - 查看本企业出仓单、柜次和允许公开的进度时间线。
 - 上传、补充和查看报关资料及处理结果。
 - 下载客户可见的报关回执。
 - 查看预计开船、到港和船期变更，不暴露内部成本、供应商敏感信息和内部备注。
 ### PDA `apps/pda-uniapp`
 - 仓库人员登录、任务领取、箱号选择、扫码拣货和数量确认。
 - 部分拣货、跳拣、撤销、异常上报、待复核和完成提交。
 - 按授权柜次拍摄或选择货柜、铅封照片，确认关联信息后上传，并处理进度、失败重试和重复提交。
 - 弱网、断网、前后台切换、重复提交和换班清理。
 - 真实设备、扫描头和发布方式确认前，不绑定厂商 SDK。
 ### 服务端 `services/api`
 - 最终保证身份、租户、仓库数据范围、权限、状态、门禁、幂等、并发和审计。
 - 管理出仓、排柜、订舱、拖车、拣货、装柜、报关和时间线的事务边界。
 - 文件上传校验类型、大小、内容和权限；使用不可预测标识和授权下载。
 - 为船期、车队、海关等外部接口预留适配层，但三期不承诺正式对接。
 ## 八、建议里程碑
 | 里程碑 | 交付目标 | 进入条件 |
 |---|---|---|
 | P3-M0 规则与设备锁定 | 流程、角色、状态、排柜规则、PDA、文件和验收确认 | 二期到仓契约稳定 |
 | P3-M1 出仓单与排柜 | 出仓单可创建，并按确认范围提供排柜建议、人工确认与追溯 | 排柜规则确认 |
 | P3-M2 订舱与拖车 | 订舱、船期、拖车预约和异常处理可用 | 服务商与权限可用 |
 | P3-M3 PDA 拣货 | 任务生成、扫码、差异、复核和幂等提交可用 | 目标设备与仓库流程确认 |
 | P3-M4 装柜封柜 | 柜号、铅封和照片证据完整，门禁生效 | 文件能力与必传清单确认 |
 | P3-M5 报关协同 | 客户上传、平台审核、补件、提交和回执下载闭环 | 报关资料清单确认 |
 | P3-M6 国内出仓 | 必要子流程满足后可确认出仓并进入等待装船 | 出仓门禁和冲正规则确认 |
 | P3-M7 联调验收 | 跨端、设备、安全、弱网、性能、迁移和发布完成 | P3-M1 至 P3-M6 验收通过 |
 ## 九、建议开发任务
 | ID | 端 | 模块 | 交付内容 | 优先级 | 依赖 |
 |---|---|---|---|---|---|
 | P3-BASE-01 | 公共 | 出仓契约 | 主/子状态、权限、事件、错误码、门禁和快照模型 | P0 | 二期到仓契约 |
 | P3-BASE-02 | 公共 | 数据模型 | 出仓单、排柜、柜次、订舱、拖车、拣货、装柜、报关和时间线 | P0 | P3-BASE-01 |
 | P3-DSP-01 | 后台 | 出仓单 | 列表、筛选、创建、详情、异常和取消 | P0 | P3-BASE-02 |
 | P3-PLAN-01 | 公共 | 排柜规则 | 按已确认规则实现输入、约束、偏好和冲突判断 | P0 | P3-BASE-02、P3-Q1 |
 | P3-PLAN-02 | 后台 | 智能排柜 | 按已确认范围实现建议、人工确认和追溯 | P0 | P3-PLAN-01 |
 | P3-BOOK-01 | 后台 | 订舱 | 订舱和经确认的船名航次、港口、变更及异常 | P0 | P3-DSP-01、P3-Q9 |
 | P3-PORT-01 | 后台/服务端 | 港务信息查询 | 查询系统内预计开船、到港等信息，记录来源和更新时间，并提供授权人工维护兜底 | P0 | P3-BOOK-01、P3-Q9 |
 | P3-TRUCK-01 | 后台 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常 | P0 | P3-DSP-01 |
 | P3-PICK-01 | 公共 | 拣货任务 | 按排柜方案生成任务、明细、差异和复核规则 | P0 | P3-PLAN-02 |
 | P3-PDA-01 | PDA | 扫码拣货 | 领取、扫描、部分拣货、跳拣、撤销和异常 | P0 | P3-PICK-01 |
 | P3-PDA-02 | PDA/服务端 | 弱网幂等 | 重试、去重、冲突、换班和设备缓存清理 | P0 | P3-PDA-01 |
 | P3-LOAD-01 | 后台 | 装柜封柜 | 柜号、铅封号、装柜节点、可配置照片清单和复核 | P0 | P3-PICK-01、P3-Q6 |
 | P3-LOAD-02 | PDA/服务端 | 柜封拍照上传 | 现场拍照/相册选择、关联确认、进度、预览、失败重试、去重和提交 | P0 | P3-LOAD-01、文件能力可用 |
 | P3-CUS-01 | 客户端 | 报关资料 | 清单、上传、补件、版本和进度查看 | P0 | 文件能力可用 |
 | P3-CLEAR-01 | 后台 | 报关协同 | 审核、退回、提交代理、批次、回执和可见范围 | P0 | P3-CUS-01 |
 | P3-CUS-02 | 客户端 | 回执及港务信息 | 回执下载、预计开船/到港信息、数据来源、更新时间和变更时间线 | P0 | P3-PORT-01、P3-CLEAR-01 |
 | P3-GATE-01 | 服务端 | 出仓门禁 | 按确认规则校验必要子流程、确认出仓、等待装船和冲正 | P0 | P3-PORT-01、P3-TRUCK-01、P3-LOAD-01、P3-LOAD-02、P3-CLEAR-01、P3-Q11、P3-Q12 |
 | P3-NOTIFY-01 | 公共 | 通知异常 | 站内通知、阻塞、责任人、时限和失败补偿 | P1 | 核心流程完成 |
 | P3-TEST-01 | 公共 | 自动化测试 | 权限、排柜、幂等、并发、文件、门禁和状态测试 | P0 | 所有 P0 模块 |
 | P3-DEVICE-01 | PDA | 真机验收 | 扫描头、弱网、性能、电量、前后台和发布验证 | P0 | 目标设备确认 |
 | P3-REL-01 | 公共 | 发布验收 | 初始化规则、迁移、联调、演练、灰度和生产发布 | P0 | P3-TEST-01、P3-DEVICE-01 |
 ## 十、测试与验收重点
 - 系统排柜符合已确认的业务规则；如启用建议解释、人工调整、版本或原因记录，对应结果可追溯。
 - 多订单拼柜和一单多柜的件数、重量、体积能与二期实测版本对账。
 - PDA 重复扫码、超量、错货、断网重试和重复提交不产生重复扣减或完成事件。
 - 柜封照片能够在现场完成拍摄、关联确认和上传；失败重试或重复提交不产生多份有效证据。
 - 未完成复核、缺少已确认的必传柜封证据或存在关键阻塞时不能确认出仓。
 - 企业 A 无法查看、上传或下载企业 B 的报关资料和回执。
 - 报关资料替换、退回、补件、提交和回执均能追溯到明确版本。
 - 港务/船期查询结果展示来源和更新时间；变更保留历史并通知授权用户，旧信息不被无痕覆盖。
 - 确认出仓的并发请求只产生一次状态变化和一次有效审计事件。
 - 管理后台覆盖加载、空态、失败、无权限和数据冲突；PDA 覆盖弱网、前后台切换和硬件扫描。
 - 当前三期验收基线为“完成国内出仓，等待装船”，不以海上运输或海外签收作为完成条件；最终以 P3-Q13 确认结果为准。
 ## 十一、启动前待确认事项
 | 编号 | 待确认问题 | 当前建议 |
 |---|---|---|
 | P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务先提供可执行规则表；建议必须可解释且人工确认 |
 | P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 数据模型全部支持，页面按实际高频场景逐步开放 |
 | P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 建议统一使用行业常用的“拖车”，并确认业务实际含义 |
 | P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 设备确认前保持适配层，不绑定厂商 SDK |
 | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 若需要，完整 WMS 前置范围会显著扩大，必须单独评估 |
 | P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 启动前由仓库、业务和合规共同锁定 |
 | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 建议配置化，并保留下单使用的清单版本 |
 | P3-Q8 | 报关代理如何接收资料和返回回执？ | 首版系统内整理加线下提交，正式接口后续评估 |
 | P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认业务词义和字段；首版建议平台人工维护并审计，外部接口仅预留适配层 |
 | P3-Q10 | 确认出仓后发现错误如何处理？ | 不直接回退状态，使用授权冲正动作和反向审计事件 |
 | P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 确认前按原型编号顺序规划，不承诺固定并行关系 |
 | P3-Q12 | “报关回执”具体包含哪些类型，海关放行是否为国内出仓硬门禁？ | 当前不默认以放行为门禁；由业务明确接收、申报、退单、查验和放行的含义及门禁 |
 | P3-Q13 | 三期终点以“等待装船”还是“装船发运”为准？ | 当前以本期出仓图片的“完成国内出仓，等待装船”为基线，完整流程 SVG 的不同表述待产品确认 |
 ## 十二、建议实施顺序
 1. 锁定待确认事项、业务规则、目标设备和协作责任人。
 2. 统一出仓单、柜次、订舱、拖车、拣货、报关和港务/船期信息的稳定编码。
 3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。
 4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。
 5. 使用脱敏数据演练拼柜、一单多柜、错拣、补件、改船和冲正。
 6. 在真实 PDA 和代表性仓库网络环境中完成联调、验收和灰度发布。
@@ -1,152 +0,0 @@
 # 虫虫出海三期开发进度表
 > 创建日期：2026-07-28  
 > 当前阶段：范围规划与大任务拆分  
 > 总体状态：待确认  
 > 规划依据：`三期开发规划.md`  
 > 维护方式：参考一期进度表，采用“总体大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”的结构。
 ## 一、三期目标
 三期承接二期到仓、实测、差异处理、处理单元编码和当前位置记录，完成智能排柜、订舱、拖车预约、PDA 拣货、柜封拍照、报关协同、港务信息查询和国内出仓闭环。
 当前验收基线为“完成国内出仓，等待装船”。在 P3-Q13 最终确认前，不把装船发运纳入三期完成条件。
 ## 二、总体进度（大任务）
 | 大任务 ID | 大任务 | 范围 | 状态 | 进度 | 计划开始 | 计划完成 | 负责人 | 关键依赖/备注 |
 |---|---|---|---|---:|---|---|---|---|
 | T01 | 需求确认与原型 | 锁定阶段边界、流程依赖、排柜规则、设备、文件、报关和港务信息；完成页面原型 | 进行中 | 40% | 2026-07-28 | 待排期 | 待分配 | 已盘点 `docs/悦` 三期相关原型；后台有较完整参考，客户端三期页面和 PDA 柜封拍照仍待补 |
 | T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、出仓单、柜次、任务、证据、报关和审计模型 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T01、二期输出契约 |
 | T03 | 出仓单与柜次 | 出仓单创建、列表、详情、订单拆分/拼柜、柜次和时间线 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T02、P3-Q2、P3-Q11 |
 | T04 | 智能排柜 | 排柜规则、系统建议、冲突、人工确认和追溯 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T03、P3-Q1、P3-Q2 |
 | T05 | 订舱与港务信息 | 订舱、变更异常、预计开船/到港信息、来源和更新时间 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T03、P3-Q9、P3-Q11 |
 | T06 | 拖车预约 | 服务商、车辆司机、预约时间窗、到离仓节点和异常 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T03、一期往来单位、P3-Q3 |
 | T07 | PDA 拣货与复核 | 任务生成、领取、扫码、部分拣货、异常、弱网幂等和后台复核 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T04、二期处理单元/位置、P3-Q4、P3-Q5 |
 | T08 | 装柜及柜封证据 | 装柜节点、柜号、铅封号、PDA 拍照上传、照片清单和复核 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T07、文件能力、P3-Q6 |
 | T09 | 报关资料与回执 | 客户上传、后台审核补件、提交代理、回执上传和客户下载 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖文件能力、P3-Q7、P3-Q8、P3-Q12 |
 | T10 | 国内出仓门禁 | 必要条件校验、确认出仓、阻塞、通知、冲正和审计 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T05～T09、P3-Q10～P3-Q13 |
 | T11 | 客户端出仓协同 | 出仓进度、柜次、回执、预计开船/到港和变更时间线 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T05、T09、T10；客户可见范围 |
 | T12 | 联调测试与发布 | 跨端联调、自动化测试、PDA 真机、安全、弱网、迁移、验收和发布 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T02～T11 完成 |
 ## 三、详细任务表
 详细任务按大任务逐项拆分。当前先建立任务骨架；每次拆分一个大任务，确认交付内容、优先级和依赖后再进入开发。
 | ID | 大任务 | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 依赖 | 负责人 | 备注 |
 |---|---|---|---|---|---|---|---:|---|---|---|
 | P3-T01-00 | T01 | 公共 | 需求确认与原型 | 完成需求确认表、页面清单和原型评审，锁定开工阻断项 | P0 | 进行中 | 40% | - | 待分配 | 已建立文档骨架并完成 `docs/悦` 原型初审，后续逐项确认和裁剪 |
 | P3-T02-00 | T02 | 公共 | 公共契约与数据模型 | 待 T01 确认后拆分 | P0 | 待确认 | 0% | P3-T01-00 | 待分配 | 下一层将拆状态、权限、数据模型、接口和审计 |
 | P3-T03-00 | T03 | 后台/服务端 | 出仓单与柜次 | 待 T02 契约明确后拆分 | P0 | 待确认 | 0% | P3-T02-00 | 待分配 | - |
 | P3-T04-00 | T04 | 后台/服务端 | 智能排柜 | 待排柜规则确认后拆分 | P0 | 待确认 | 0% | P3-T03-00、P3-Q1 | 待分配 | - |
 | P3-T05-00 | T05 | 后台/服务端 | 订舱与港务信息 | 待港务范围和字段确认后拆分 | P0 | 待确认 | 0% | P3-T03-00、P3-Q9 | 待分配 | - |
 | P3-T06-00 | T06 | 后台/服务端 | 拖车预约 | 待流程依赖确认后拆分 | P0 | 待确认 | 0% | P3-T03-00、P3-Q11 | 待分配 | - |
 | P3-T07-00 | T07 | PDA/后台/服务端 | PDA 拣货与复核 | 待拣货输入和设备确认后拆分 | P0 | 待确认 | 0% | P3-T04-00、P3-Q4、P3-Q5 | 待分配 | 已有静态 PDA 原型可复用 |
 | P3-T08-00 | T08 | PDA/后台/服务端 | 装柜及柜封证据 | 待照片清单确认后拆分 | P0 | 待确认 | 0% | P3-T07-00、P3-Q6 | 待分配 | 需新增柜封拍照原型 |
 | P3-T09-00 | T09 | 客户端/后台/服务端 | 报关资料与回执 | 待资料和回执规则确认后拆分 | P0 | 待确认 | 0% | P3-Q7、P3-Q8、P3-Q12 | 待分配 | - |
 | P3-T10-00 | T10 | 后台/服务端 | 国内出仓门禁 | 待流程、回执和终点确认后拆分 | P0 | 待确认 | 0% | P3-T05-00～P3-T09-00 | 待分配 | 高风险状态操作 |
 | P3-T11-00 | T11 | 客户端/服务端 | 客户端出仓协同 | 待客户可见字段确认后拆分 | P0 | 待确认 | 0% | P3-T05-00、P3-T09-00、P3-T10-00 | 待分配 | - |
 | P3-T12-00 | T12 | 公共 | 联调测试与发布 | 待各模块拆分完成后细化测试与发布任务 | P0 | 待开始 | 0% | P3-T02-00～P3-T11-00 | 待分配 | - |
 | P3-T01-PROTO-01 | T01 | 公共 | 原型盘点 | 盘点流程图、后台、企业客户端和 PDA 中与三期相关的页面及交互 | P0 | 已完成 | 100% | - | 待分配 | 2026-07-28 已完成首次盘点，来源为 `docs/悦` |
 | P3-T03-PROTO-01 | T03 | 后台 | 出仓单原型核验 | 对照通用 WMS 出库单、货柜和装柜清单，确定三期出仓单可复用字段与需重做部分 | P0 | 进行中 | 50% | P3-T01-PROTO-01、P3-Q11 | 待分配 | 通用“出库”不能直接等同三期“国内出仓” |
 | P3-T04-PROTO-01 | T04 | 后台 | 智能排柜原型核验 | 映射智能装柜的线路页签、筛选、智能锁定、订单分柜、拖放调整和集装箱详情 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 原型叫“智能装柜”，与“智能排柜”的业务边界待 P3-Q1 确认 |
 | P3-T05-PROTO-01 | T05 | 后台 | 订舱港务原型核验 | 映射订舱列表、新增/详情、放舱、船名航次、港口和 ETD/ATD/ETA/ATA 字段 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 港务信息是否独立模块仍待 P3-Q9 确认 |
 | P3-T06-PROTO-01 | T06 | 后台 | 拖车原型核验 | 映射拖车列表、新增表单、运输公司、司机、车头号、装箱日期、费用和附件 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 预约时间窗和到离仓节点仍需按三期流程补充 |
 | P3-T07-PROTO-01 | T07 | 后台/PDA | 拣货原型核验 | 对照通用 WMS 出库拣货和现有 PDA 集装箱拣货，锁定可复用交互与真实接口缺口 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | PDA 静态交互已有，任务、鉴权、持久化和弱网仍待开发 |
 | P3-T08-PROTO-01 | T08 | 后台 | 装柜证据原型核验 | 映射货柜列表、预装清单、装柜清单、柜号、单证、船期和装柜明细 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 后台参考较完整，但现场拍照上传原型缺失 |
 | P3-T08-PROTO-02 | T08 | PDA | 柜封拍照原型 | 新增柜次确认、货柜/铅封拍照、照片类型、预览、重试和提交页面原型 | P0 | 待开始 | 0% | P3-Q4、P3-Q6 | 待分配 | `docs/悦` 暂无对应原型 |
 | P3-T09-PROTO-01 | T09 | 后台 | 报关单证原型核验 | 映射报关单列表、单证管理、报关/清关/放行资料及装柜清单附件 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 客户上传和回执下载页面仍需新建 |
 | P3-T10-PROTO-01 | T10 | 后台 | 出仓门禁原型 | 设计统一门禁检查、阻塞原因、确认出仓和冲正页面 | P0 | 进行中 | 30% | P3-Q10～P3-Q13 | 待分配 | 现有原型只有分散状态和放行字段，无统一出仓门禁页 |
 | P3-T11-PROTO-01 | T11 | 客户端 | 客户端三期原型 | 新增出仓进度、报关资料上传/补件、回执下载和港务/船期页面原型 | P0 | 待开始 | 0% | P3-Q7～P3-Q9、P3-Q12、P3-Q13 | 待分配 | 现有客户端原型未覆盖三期专用页面 |
 ## 四、原型对照与开发影响
 | 大任务 | `docs/悦` 现有原型 | 覆盖判断 | 开发处理 |
 |---|---|---|---|
 | T03 出仓单与柜次 | 通用 WMS 出库单、货柜列表、装柜清单 | 部分参考 | 保留列表、状态和明细交互，按国内出仓业务重新定义对象和门禁 |
 | T04 智能排柜 | 入库单列表中的“智能装柜”弹窗 | 已有参考 | 复用线路、筛选、锁定、分柜和拖放交互，按 P3-Q1 裁剪规则 |
 | T05 订舱与港务信息 | 订舱列表、新增/详情、放舱、货柜船期字段 | 已有参考 | 复用订舱字段和页面结构，确认港务信息范围及来源后裁剪 |
 | T06 拖车预约 | 拖车列表、新增拖车 | 已有参考 | 复用车辆司机和费用字段，补预约时间窗、到仓及离仓节点 |
 | T07 PDA 拣货与复核 | 通用 WMS 出库、PDA 集装箱拣货 | 已有参考 | 保留 PDA 交互，重做真实任务、权限、幂等、弱网和后台复核 |
 | T08 装柜及柜封证据 | 货柜列表、预装清单、装柜清单 | 部分参考 | 后台页面裁剪复用；PDA 货柜/铅封拍照页面新建 |
 | T09 报关资料与回执 | 报关单列表、单证管理、装柜清单附件 | 部分参考 | 后台裁剪复用；客户上传、补件和回执下载页面新建 |
 | T10 国内出仓门禁 | 分散的出库状态、国内报关成功和放行资料 | 部分参考 | 新建统一门禁检查和确认出仓页面，避免直接照搬“已放行”规则 |
 | T11 客户端出仓协同 | 头程下单客户端只有船期字段和出仓时间展示 | 覆盖不足 | 新建三期客户端出仓进度、报关和港务信息页面 |
 > `货代SaaS平台原型.html` 是全量平台参考原型，其中海外仓、完整 WMS、费用和清关能力不自动纳入三期；所有复用项仍需经过三期范围裁剪。
 ## 五、建议拆分模板
 每个大任务按照同一顺序拆成可开发、可验收的小任务：
 1. `RULE`：业务规则、状态、权限和异常。
 2. `DATA`：数据表、字段、快照、版本和审计。
 3. `API`：接口、鉴权、幂等、并发和错误码。
 4. `ADM` / `CLI` / `PDA`：各端页面与交互。
 5. `TEST`：单元、接口、端到端、权限和边界测试。
 6. `ACCEPT`：业务验收、证据和遗留问题。
 例如 T04 智能排柜后续可使用 `P3-T04-RULE-01`、`P3-T04-DATA-01`、`P3-T04-API-01`、`P3-T04-ADM-01`、`P3-T04-TEST-01` 编号。
 ## 六、建议里程碑
 | 里程碑 | 交付目标 | 状态 | 计划完成 |
 |---|---|---|---|
 | P3-M0 需求与原型锁定 | 阶段边界、流程、规则、设备、文件和页面原型确认 | 待确认 | 待排期 |
 | P3-M1 公共契约 | 二三期输入、状态、权限、数据模型和接口契约稳定 | 待排期 | 待排期 |
 | P3-M2 出仓编排 | 出仓单、排柜、订舱、港务和拖车可用 | 待排期 | 待排期 |
 | P3-M3 仓内出仓 | PDA 拣货、复核、装柜和柜封证据闭环 | 待排期 | 待排期 |
 | P3-M4 报关协同 | 客户资料、后台审核、提交代理、回执上传下载闭环 | 待排期 | 待排期 |
 | P3-M5 国内出仓 | 门禁满足后可确认出仓并进入当前约定终点 | 待排期 | 待排期 |
 | P3-M6 三期上线 | 联调、真机、安全、测试、验收和生产发布完成 | 待排期 | 待排期 |
 ## 七、未确认事项（需求确认进度）
 当前共 13 项待确认事项，其中 7 项为开工阻断、5 项为模块阻断、1 项为非阻断。完整建议、负责人、计划确认日期和最终结论统一维护在 [三期需求确认表](三期需求确认表.md)；开工阻断项未确认前，受影响的大任务保持“待确认”。
 | 编号 | 阻断级别 | 待确认事项 | 状态 | 主要影响 |
 |---|---|---|---|---|
 | P3-Q1 | 开工阻断 | 智能排柜的硬约束和软偏好 | 待确认 | T04 智能排柜、T07 拣货任务 |
 | P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批出仓 | 待确认 | T03 出仓单与柜次、T04 智能排柜 |
 | P3-Q3 | 非阻断 | “预约托车”是否统一为“预约拖车” | 待确认 | T06 拖车预约、页面与接口文案 |
 | P3-Q4 | 模块阻断 | PDA 型号、系统和扫描头接入方式 | 待确认 | T07 PDA 拣货、T08 柜封拍照、真机验收 |
 | P3-Q5 | 开工阻断 | 拣货是否依赖实时库存和库位可用量 | 待确认 | T02 二三期契约、T07 PDA 拣货 |
 | P3-Q6 | 模块阻断 | 柜封照片必传类型、角度、数量和留存期限 | 待确认 | T08 装柜证据、T10 出仓门禁 |
 | P3-Q7 | 模块阻断 | 报关资料清单是否按国家、渠道和货物类型变化 | 待确认 | T09 报关资料、文件版本 |
 | P3-Q8 | 模块阻断 | 报关代理接收资料和返回回执的方式 | 待确认 | T09 报关协同、回执上传 |
 | P3-Q9 | 开工阻断 | 港务信息的业务含义、字段和维护方 | 待确认 | T05 订舱港务、T11 客户端展示 |
 | P3-Q10 | 模块阻断 | 确认出仓后的错误处理和冲正方式 | 待确认 | T10 出仓门禁、权限和审计 |
 | P3-Q11 | 开工阻断 | 九个动作的强制前置和并行关系 | 待确认 | T03～T10 全流程和状态机 |
 | P3-Q12 | 开工阻断 | 报关回执类型及海关放行是否为出仓硬门禁 | 待确认 | T09 报关状态、T10 出仓门禁 |
 | P3-Q13 | 开工阻断 | 三期终点是等待装船还是装船发运 | 待确认 | 阶段边界、状态、里程碑和验收 |
 ## 八、开工准入清单
 产品和业务完成需求确认后，先进入“开工准备”；以下准入项全部通过后，三期才能从范围规划正式切换到全面开发。
 | 准入编号 | 准入条件 | 当前状态 | 责任方 | 完成证据 |
 |---|---|---|---|---|
 | P3-GO-01 | P3-Q1～P3-Q13 均形成明确结论，7 项开工阻断全部解除 | 进行中 | 产品、业务 | `三期需求确认表.md` 状态均为已确认并填写最终结论 |
 | P3-GO-02 | 确认结论已同步开发规划、进度表、页面清单和验收范围 | 待开始 | 产品、项目负责人 | 四份文档口径一致，无未标注的候选规则 |
 | P3-GO-03 | 关键缺失原型已补齐并评审，包括出仓门禁、客户端三期页面和 PDA 柜封拍照 | 进行中 | 产品、设计、业务 | 页面清单中的关键页面达到已确认状态 |
 | P3-GO-04 | T02 公共契约完成，二期输入、状态机、权限、数据模型、接口、错误码和审计口径稳定 | 待开始 | 前后端、架构/技术负责人 | 契约评审记录及稳定的数据/API 定义 |
 | P3-GO-05 | T03～T12 已拆成 RULE、DATA、API、ADM/CLI/PDA、TEST、ACCEPT 任务，并填写负责人和计划 | 待开始 | 项目负责人、研发、测试 | 详细任务可独立开发、联调和验收 |
 | P3-GO-06 | 产品、业务、研发和测试完成开工评审，确认范围、依赖、风险和首批任务 | 待开始 | 项目负责人 | 开工评审纪要及明确的 GO 结论 |
 准入口径：`P3-GO-01` 完成后可以进入 T02 契约设计和详细任务拆分；`P3-GO-01～P3-GO-06` 全部通过后，才进入全面功能开发。
 ## 九、状态维护规则
 - 状态统一使用：待确认、待开始、进行中、联调中、测试中、已完成、已阻塞。
 - 进度填写 `0%～100%`；只有开发、测试和业务验收均完成后才能填写 `100%`。
 - 开始开发时填写负责人、计划开始和计划完成日期。
 - 出现阻塞时在备注中填写阻塞原因、责任人和预计解除时间。
 - 大任务进度应由其详细任务加权汇总；当前骨架阶段先人工维护，拆分完成后再确定权重。
 ## 十、下一步拆分顺序
 1. 先处理 T01，逐项确认 P3-Q1～P3-Q13，并补齐关键页面原型。
 2. 拆 T02 公共契约与数据模型，固定二期输入和三期核心对象。
 3. 按业务顺序拆 T03～T10，每个模块补齐规则、数据、接口、页面和测试。
 4. 拆 T11 客户端可视范围和交互。
 5. 最后拆 T12 联调、真机、验收和发布任务。
@@ -1,69 +0,0 @@
 # 虫虫出海三期需求确认表
 > 创建日期：2026-07-28  
 > 当前状态：确认中  
 > 用途：记录会影响三期范围、流程、数据模型、页面和验收的产品决策。
 ## 一、维护规则
 - 状态统一使用：待确认、确认中、已确认、已取消。
 - 阻断级别统一使用：开工阻断、模块阻断、非阻断。
 - 结论确认后同步更新 `三期开发规划.md`、`三期开发进度表.md` 和受影响的页面原型。
 - 未确认事项只能作为候选方案，不能直接写成固定开发或验收承诺。
 ## 二、确认事项
 | 编号 | 决策/问题 | 当前建议 | 阻断级别 | 状态 | 负责人 | 计划确认 | 最终结论 | 影响模块 |
 |---|---|---|---|---|---|---|---|---|
 | P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务提供可执行规则表，建议可解释并由人工确认 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 智能排柜、拣货任务 |
 | P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 数据模型预留能力，页面按高频场景逐步开放 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 出仓单、柜次、排柜、拣货 |
 | P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 待确认 | 待分配 | 待排期 | - | 页面文案、接口字段说明 |
 | P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 确认前保持设备适配层，不绑定厂商 SDK | 模块阻断 | 待确认 | 待分配 | 待排期 | - | PDA 拣货、真机验收 |
 | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用二期处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 二三期契约、拣货、库存边界 |
 | P3-Q6 | 柜封照片有哪些必传类型、角度、数量和留存期限？ | 使用可配置清单，由仓库、业务和合规共同确认 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 装柜、PDA 拍照、文件存储、出仓门禁 |
 | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 客户资料、报关审核、文件版本 |
 | P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 报关协同、回执上传 |
 | P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认词义和字段；首版平台人工维护并审计 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 订舱、港务查询、客户展示 |
 | P3-Q10 | 确认出仓后发现错误如何处理？ | 不直接回退状态，使用授权冲正和反向审计事件 | 模块阻断 | 待确认 | 待分配 | 待排期 | - | 出仓门禁、权限、审计 |
 | P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 确认前按原型编号顺序规划 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 全流程、状态机、页面进度 |
 | P3-Q12 | 报关回执包含哪些类型，海关放行是否为国内出仓硬门禁？ | 当前不默认以放行为门禁，业务明确各类回执含义 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 报关状态、出仓门禁、客户回执 |
 | P3-Q13 | 三期终点以“等待装船”还是“装船发运”为准？ | 当前以“完成国内出仓，等待装船”为基线 | 开工阻断 | 待确认 | 待分配 | 待排期 | - | 阶段边界、状态、里程碑、验收 |
 ## 三、建议确认顺序
 1. 先确认 P3-Q13、P3-Q11，锁定阶段终点和流程依赖。
 2. 再确认 P3-Q1、P3-Q2、P3-Q5，锁定排柜、柜次和拣货输入。
 3. 然后确认 P3-Q12、P3-Q7、P3-Q8，锁定报关和出仓门禁。
 4. 最后确认设备、照片、港务信息、冲正和文案事项。
 ## 四、产品与业务确认会议
 ### 4.1 参会角色
 - 产品负责人：逐项说明问题、候选方案和影响范围，维护最终结论。
 - 业务负责人：确认流程、规则、例外、责任边界和客户可见范围。
 - 仓库/运营代表：确认现场作业、PDA、照片、拖车、装柜和冲正可执行性。
 - 研发与测试代表：识别数据、接口、设备、权限和验收风险，不代替业务作决定。
 ### 4.2 会议输入
 - 本确认表中的 P3-Q1～P3-Q13。
 - `三期开发规划.md` 的流程、状态、里程碑和任务骨架。
 - `三期页面与原型清单.md` 中已有参考原型和待补页面。
 - 二期输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。
 ### 4.3 每项确认要求
 1. 必须填写负责人、计划确认日期和可执行的最终结论，不能只记录“按建议处理”。
 2. 最终结论需明确正常流程、异常/冲正、权限责任和验收口径。
 3. 暂缓事项必须写明本期是否排除、临时方案、影响模块和再次确认日期。
 4. 开工阻断项未解除时，不得将受影响模块标记为可开发。
 5. 会议结束后，将结论同步到开发规划、开发进度表、页面原型和后续验收任务。
 ### 4.4 会议输出
 - 13 项确认事项的状态和最终结论。
 - 需要新增或调整的原型清单。
 - 三期范围内/范围外清单及跨期依赖。
 - 仍有风险的事项、责任人和完成日期。
 - 是否允许进入 T02 契约设计与任务拆分的明确结论。
@@ -1,55 +0,0 @@
 # 虫虫出海三期页面与原型清单
 > 创建日期：2026-07-28  
 > 当前状态：页面盘点中  
 > 原型依据：`参考资料/出仓流程.png`、现有 PDA 拣货原型
 ## 一、维护规则
 - 页面状态统一使用：待确认、待原型、原型中、待评审、已确认、开发中、已完成。
 - 页面只有在业务流程、角色权限和关键字段确认后才能标记“已确认”。
 - 页面原型至少覆盖正常态、空态、加载态、失败态、无权限态和关键冲突态。
 - 当前先列页面级大项，后续按开发进度表的大任务逐项拆交互、字段和验收。
 ## 二、管理后台
 | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 |
 |---|---|---|---|---|---|---|
 | P3-ADM-01 | 出仓单列表 | 查询、筛选、创建、异常和状态展示 | T03 出仓单与柜次 | 部分参考原型 | P3-Q2、P3-Q11 | 可参考通用 WMS 出库单，但需重定义国内出仓对象 |
 | P3-ADM-02 | 出仓单详情 | 柜次、任务、证据、报关和时间线 | T03 出仓单与柜次 | 部分参考原型 | P3-Q11、P3-Q13 | 可组合参考货柜列表和装柜清单，缺统一详情页 |
 | P3-ADM-03 | 智能排柜 | 生成建议、冲突、调整和确认 | T04 智能排柜 | 已有参考原型 | P3-Q1、P3-Q2 | 参考“智能装柜”弹窗，需确认名称和规则边界 |
 | P3-ADM-04 | 订舱管理 | 订舱申请、结果、变更和异常 | T05 订舱与港务信息 | 已有参考原型 | P3-Q9、P3-Q11 | 已有订舱列表、新增和详情 |
 | P3-ADM-05 | 港务/船期信息 | 查询系统信息、人工维护、来源和更新时间 | T05 订舱与港务信息 | 部分参考原型 | P3-Q9 | 订舱详情和货柜列表已有船期字段，缺独立查询口径 |
 | P3-ADM-06 | 拖车预约 | 服务商、车辆司机、时间窗和节点 | T06 拖车预约 | 已有参考原型 | P3-Q3、P3-Q11 | 已有拖车列表和新增表单，需补预约及到离仓节点 |
 | P3-ADM-07 | 拣货任务与复核 | 分配、进度、差异、复核和异常 | T07 PDA 拣货与复核 | 部分参考原型 | P3-Q4、P3-Q5 | 可参考通用 WMS 出库和 PDA 原型，缺三期真实任务页 |
 | P3-ADM-08 | 装柜封柜 | 柜号、铅封号、照片清单和复核 | T08 装柜及柜封证据 | 部分参考原型 | P3-Q6 | 已有货柜/预装/装柜清单，缺现场照片复核闭环 |
 | P3-ADM-09 | 报关协同 | 资料审核、补件、提交批次和回执上传 | T09 报关资料与回执 | 部分参考原型 | P3-Q7、P3-Q8、P3-Q12 | 已有报关单和单证管理，缺客户补件协同闭环 |
 | P3-ADM-10 | 国内出仓确认 | 门禁检查、确认、阻塞和冲正 | T10 国内出仓门禁 | 待原型 | P3-Q10、P3-Q11、P3-Q12、P3-Q13 | 现有状态分散，无统一门禁确认页 |
 ## 三、企业客户端
 | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 |
 |---|---|---|---|---|---|---|
 | P3-CLI-01 | 出仓进度列表 | 查看本企业出仓单、柜次和当前节点 | T11 客户端出仓协同 | 待原型 | P3-Q11、P3-Q13 | 现有客户端未覆盖三期专用页面 |
 | P3-CLI-02 | 出仓进度详情 | 时间线、柜号、船期和允许公开的证据 | T11 客户端出仓协同 | 待原型 | P3-Q6、P3-Q9 | 现有客户端只有零散船期/出仓时间字段，需新建详情页 |
 | P3-CLI-03 | 报关资料上传 | 清单、上传、补件、版本和处理进度 | T09 报关资料与回执 | 待原型 | P3-Q7 | 文件规则确认后细化 |
 | P3-CLI-04 | 报关回执下载 | 回执列表、类型、版本和授权下载 | T09 报关资料与回执 | 待原型 | P3-Q8、P3-Q12 | 区分客户可见回执 |
 | P3-CLI-05 | 港务/船期信息 | 预计开船、到港、来源、更新时间和变更 | T11 客户端出仓协同 | 待原型 | P3-Q9 | 不将过期信息展示为实时信息 |
 ## 四、PDA
 | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 |
 |---|---|---|---|---|---|---|
 | P3-PDA-01 | 登录 | 人员登录和快捷登录 | T07 PDA 拣货与复核 | 已有静态原型 | P3-Q4 | 真实鉴权待服务端接入 |
 | P3-PDA-02 | 箱号与任务选择 | 领取任务、选择箱号和查看进度 | T07 PDA 拣货与复核 | 已有静态原型 | P3-Q4、P3-Q5 | 需对接真实任务和处理单元 |
 | P3-PDA-03 | 扫码拣货 | 扫码、整拣、部分拣货、跳拣和撤销 | T07 PDA 拣货与复核 | 已有静态原型 | P3-Q4、P3-Q5 | 已有本地交互，缺服务端 |
 | P3-PDA-04 | 拣货提交 | 汇总、异常、提交和完成统计 | T07 PDA 拣货与复核 | 已有静态原型 | P3-Q5 | 需补幂等和冲突处理 |
 | P3-PDA-05 | 柜封拍照上传 | 柜次确认、拍照/相册、类型、预览和重试 | T08 装柜及柜封证据 | 待原型 | P3-Q4、P3-Q6 | `docs/悦` 中暂无对应页面，属于明确原型缺口 |
 ## 五、下一步拆分顺序
 1. 先补 P3-ADM-01、P3-ADM-02，确定三期后台信息架构。
 2. 根据 P3-Q1 结论补 P3-ADM-03 智能排柜原型。
 3. 根据 P3-Q5 复核现有 PDA 拣货原型并补真实状态。
 4. 根据 P3-Q6 优先补 P3-PDA-05 柜封拍照上传原型。
 5. 报关和港务规则确认后，再补客户端及对应后台页面。
@@ -0,0 +1,102 @@
 # 业务快速索引
 本文件按需检索，不作为启动必读文档。以下路径均按工作区根目录或表内注明的应用源码根目录起算，不相对于 docs/。
 ## 常用说法与歧义分流
 仓储转运审核、转运驳回：Admin 尾程订单 `apps/admin-web/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue` → `apps/admin-web/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue`；权限、状态及 API 见该模块 `AGENTS.md` 的“仓储转运审核、通过与驳回”。不要把该入口当作头程订单审单，也不要按“转运”误入排车转派送。
 先从任务中取“终端 + 业务对象 + 动作”，如“海外 PDA + 柜号 + 收货”。下面是检索提示，不替代业务契约；代码路径均从工作区根起算。用短词检索，不拿整句自然语言做精确匹配。
 ### 高频任务最小读取集
 - 订单审核：根 `AGENTS.md` → `docs/业务快速索引.md` 本节 → `apps/admin-web/src/modules/unified-orders/` → `baiyue-firstleg/order/AGENTS.md`；只有审核门禁跨到履约时才增加 `firstleg/AGENTS.md`。不读海外仓审核或全量权限 SQL。
 - PDA 出库：根 `AGENTS.md` → `apps/pda-overseas-uniapp/AGENTS.md` → `src/pages/dispatch/` 和 `src/api/fulfillment.js` → `lastleg-service/AGENTS.md`；只有网关路径或 Token 失败才增加 `gateway-overseas/AGENTS.md`。不读 Admin 排车配置，除非问题涉及平台转派送资格。
 - 客户账单：根 `AGENTS.md` → Client `apps/client-web/AGENTS.md` → `src/modules/finance/` → `baiyue-firstleg/finance/AGENTS.md`；平台账单才切换 Admin Finance。不要因“账单”自动加载柜费分摊或海外费用契约。
 - 退货、异常、拖车：先用终端、阶段和动作分流；无法确定时只读取本节对应行，不全文加载海外仓 README 或 Lastleg 全部业务索引。
 每个入口同时标出排除范围，避免把相邻生命周期当作同一业务。普通任务默认最多读取根指引、一个终端/模块指引和目标代码命中段；跨服务时再增加直接消费者或提供者。
 | 常用说法 | 区分依据 | 首个定位范围 |
 |---|---|---|
 | 没有报价、价格未命中、人工定价、手工报价 | FBA 单票费用的显式人工报价，不是价格簿上传或静默回退 | Admin `apps/admin-web/src/modules/inbounds/fee/api.ts` 的 `createManualInboundQuote`；Backend `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/FbaPricingService.java` 的 `manualQuote`，联查 `PlatformFbaPricingController`、`fba-pricing-v1.yaml`；Client 快照类型 `apps/client-web/src/modules/first-leg/types/inboundBilling.ts` |
 | 退货换标候选、退货单创建换标 | 客户退货库存进入换标申请，区别于平台审核与 PDA 签收 | `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/returnreceipt/controller/MerchantReturnOrderController.java` 的 `GET /{returnNo}/relabel-candidates`、`POST /{returnNo}/relabel` → `ReturnReceiptService.relabelCandidates/createRelabel`；公共前缀 `/api/merchant/v1/last-leg/return-orders`，客户范围取认证身份 |
 | 退货审核、退货驳回、换标审核 | 先区分退货预报准入与换标申请审核，均不是仓储转运审核 | 退货预报 `apps/admin-web/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue`；换标申请 `apps/admin-web/src/modules/overseas-warehouse/pages/RelabelOrdersView.vue`；条件与 API 见该模块 `AGENTS.md` |
 | PDA版本、安装包下载、热更新、发布版本、停发 | 平台管理版本与设备检查更新分开定位，先区分国内/海外 PDA | 管理页 `apps/admin-web/src/modules/pda-releases/pages/PdaReleasesView.vue`；设备更新为国内 `apps/pda-uniapp/utils/app-update.js`、海外 `apps/pda-overseas-uniapp/src/utils/app-update.js`；后端查 `baiyue-firstleg/file/AGENTS.md` |
 | 收货、入库、测量、称重 | 国内到仓称重或测量弹框 | `apps/admin-web/src/modules/inbounds/`；业务路由查“到仓测量” |
 | 仓储转运测量、转运打托、转运托盘标签 | 海外 PDA 逐托实测、生成新托盘号与扫码绑定，不是 Admin 转运审核或排车转派送 | `apps/pda-overseas-uniapp/src/pages/warehouse-transfer/warehouse-transfer.vue` → `apps/pda-overseas-uniapp/src/api/warehouse-transfers.js`；约束与回归见该应用 `AGENTS.md` |
 | 接柜、卸柜、收货、签收 | 海外 PDA 柜号认领、照片、实收 | `apps/pda-overseas-uniapp/src/pages/operation/operation.vue`；后端查 `ReceivingContainerService` |
 | 入仓计划、生成计划、按柜生成 | 平台尾程订单预览与确认，不是现场实收 | `apps/admin-web/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue`；后端查 `ContainerInboundPlanConversionCoordinator` |
 | 审核、审单、批量审核 | 客户头程订单待审核 | `apps/admin-web/src/modules/unified-orders/`；后端查 `BatchOrderReviewPreviewService` |
 | 订单审核、头程订单审核、批量审单 | 平台审核客户头程订单，状态以 Order `SUBMITTED` 和服务端 `canApprove/blockReason` 为准；不要按仓储转运审核定位 | Admin `apps/admin-web/src/modules/unified-orders/`；Client 只读订单状态查 `apps/client-web/src/modules/first-leg/`；Backend `baiyue-firstleg/order/` 的 `BatchOrderReviewPreviewService`、`PlatformFirstLegOrderController` |
 | 审核、测量审核、实测审核 | 仓库测量结果审核 | `baiyue-firstleg/firstleg/AGENTS.md` 中“审核与初始计价”；页面先查 Admin 入库模块 |
 | 费用、运费、报价、计费、船期价格表、价格簿 | 单票入仓计价、客户专属报价或调价 | `apps/admin-web/src/modules/inbounds/fee/`、`apps/admin-web/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue`（列表/上传）、`apps/admin-web/src/modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue`（版本详情/映射确认）；后端查 `FbaPricingService` |
 | 柜费、公共费用、分摊 | 国内柜费来源归 Firstleg；海外柜费来源归 Lastleg；账单与结算结果归 Finance | 业务路由查“财务管理与柜级公共费用分摊”或“海外业务费用来源与客户财务”，按实际请求区分 |
 | 充值、余额、授信、账单、核销 | 客户自助与平台管理先按终端区分 | Client `apps/client-web/src/modules/finance/`；Admin `apps/admin-web/src/modules/finance/` |
 | 客户账单、客户对账单、账单确认 | 客户查看和确认本企业账单，不是平台柜费分摊或充值审核 | Client `apps/client-web/src/modules/finance/views/FinanceBillsView.vue`；Admin 平台账单查 `apps/admin-web/src/modules/finance/`；Backend `baiyue-firstleg/finance/` 的 Client Finance Controller |
 | 自动生成托盘、托盘码没生成、计划齐全、重试生成托盘码 | 海外入库计划保存后资源生成，不是国内托盘标签打印 | Admin `apps/admin-web/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue`；Backend `baiyue-firstleg/lastleg-service/docs/business-index.md` 的“人工计划自动生成托盘与资源重试”，执行规则先读该服务 `AGENTS.md` |
 | 托盘码、托盘标签、补打 | 先区分散货装柜、一件代发和海外实体托盘 | 散货 `apps/admin-web/src/modules/loading-lists/components/PalletLabelPrintDialog.vue`；一件代发 `apps/admin-web/src/modules/inbounds/core/DropshipPalletPrintPanel.vue`，从订单“托盘打印”页签进入；海外单张打印 `apps/admin-web/src/modules/overseas-warehouse/pages/PalletsView.vue`，详见各应用/模块指引 |
 | 箱码、箱唛、箱标、单箱扫码 | 单箱身份与测量，不是托盘或库位 | 业务路由查“箱唛、箱码与单箱测量”；后端查 `InboundCartonLabelService` |
 | 库位、托盘、占位、释放 | 国内称重整票块归 Warehouse；海外实物托盘资源归 Warehouse Overseas；业务任务归 Lastleg | 业务路由查“称重确认”或“海外仓库与通用资料”；用国内/海外和业务阶段继续限定 |
 | 拖车、派车、提柜、还柜 | 国内订舱拖车与目的港码头车队是不同业务；海外配送排车另属 Lastleg | 国内 `apps/admin-web/src/modules/trucking/`；目的港 `apps/admin-web/src/modules/container-loading/api/terminalDrayages.ts`；配送查“海外出库、排车” |
 | 报关资料、退税资料、完成文件 | 平台整柜操作与客户订单上传先按终端区分 | Admin `apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue`；Client `apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue` |
 | 退货、退货预报、退货换标、退货签收、退货合箱 | 客户退货预报及签收库存，区别于派送异常退回 | Client `apps/client-web/src/modules/overseas-warehouse/views/ReturnOrdersView.vue`；Admin `apps/admin-web/src/modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；PDA `apps/pda-overseas-uniapp/AGENTS.md`；Lastleg `returnreceipt/`，见下文“退货预报、签收、库存与合箱” |
 | PDA 出库、PDA 发车、扫码出库、整托出库 | 海外 PDA 执行排车和出库，不是平台排车配置或客户派送查询 | 海外 PDA `apps/pda-overseas-uniapp/src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js`；Backend `baiyue-firstleg/lastleg-service/dispatch/pda/`；统一经 `gateway-overseas/` |
 | 异常、退回、退仓、回访 | 派送异常退回与库存退货业务不可混用 | 派送查 `apps/admin-web/src/modules/overseas-warehouse/pages/ExceptionOrdersView.vue`；退货预报/库存查 Lastleg `returnreceipt/` |
 ## 定位步骤与反馈
 - 已知文件、组件或请求路径：读取适用指引后直接进入该文件或限定服务搜索路由，无需经过词表。
 - 页面问题：终端指引 → 命中页面 → 实际 import/API → 对应 Controller/Service。纯展示问题定位到相关组件即可；遇到后端业务判断再追踪调用链。
 - 状态或权限问题：已知请求时先定位 Controller 的权限与 Service 的状态门禁，再核对前端消费；尚不知请求时从触发动作找到 API。不要先扫所有权限初始化 SQL。
 - 无精确命中：从用户原话提取短词查本表；仍有歧义时利用页面标题、业务编号类型和国内/海外范围缩小。每次只扩展相邻业务范围。
 - 实际任务若发生入口误导、路径失效或重复扩大搜索，在当次交付中简记“原说法 → 最终入口 → 绕路原因”，并修正命中的索引行；进度与临时结果不写回本文件。
 - 评价检索质量看首次入口是否正确、扩大范围次数、找到目标前额外读取的无关文件数；文件存在或离线合同通过只能证明部分有效性，不能代替真实任务耗时。普通任务不额外建立计时脚本或登记台账。
 ## 业务快速路由表
 退货预报、签收、库存与合箱：Client `modules/overseas-warehouse/views/ReturnOrdersView.vue`、`ReturnInventoryView.vue`；Admin `modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；海外 PDA `src/pages/return-receipt/return-receipt.vue`、`src/pages/return-packing/return-packing.vue`，API 与检查入口见 `apps/pda-overseas-uniapp/AGENTS.md`；Backend `lastleg-service/returnreceipt/`，执行规则先读 `baiyue-firstleg/lastleg-service/AGENTS.md`，详细接口与状态按需查 `baiyue-firstleg/lastleg-service/docs/business-index.md` 的退货入口，OpenAPI 为 `overseas-business-v1.yaml`。客户预报 → 平台审核 → PDA 签收 → 退货箱/SKU 库存 → 同客户合箱 → `delivery/` 退货出库；两个 PDA 页面均在 `src/pages.json` 注册，由 `src/data/overseas-workbench.js` 提供入口，真机验收另取证。派送异常退回仍归 `exceptionorder/`。
 本表只路由到范围依据和首个代码入口；Admin/Client 路径从对应应用的 `src/` 起算，国内 PDA 路径从 `apps/pda-uniapp/` 起算，海外 PDA 路径从 `apps/pda-overseas-uniapp/src/` 起算，Backend 路径从 `baiyue-firstleg/` 起算。进入目标后继续读最近的 `AGENTS.md`，不要把根表当作模块细节清单。
 | 业务 | 范围依据 | 首个代码入口 |
 |---|---|---|
 | 登录认证 | `docs/订单与客户/README.md` | Admin `modules/auth/`、`core/auth/`；Client `modules/auth/`；Backend `auth/`、`iam/`。海外 Token 不携带角色或权限集，Admin/Client/海外 PDA 从 Auth 登录与刷新响应的顶层授权快照读取，海外 Gateway 再按 IAM 安全投影校验 |
 | 客户与企业 | `docs/订单与客户/README.md`、`docs/订单与客户/订单与客户头程订单闭环设计.md` | Admin `modules/customers/`；Client `modules/tenant-management/`、`modules/account/`；Backend `iam/`、`auth/`、`file/`。公司联系电话/邮箱是企业资料，不作为成员登录标识且不要求跨企业唯一；成员登录手机号归账号链路，修改时同步 Auth 并撤销该账号会话。审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可在已有营业执照后单独补传或替换，营业执照仍须与统一社会信用代码整包提交；默认尺寸配置由 IAM 持久任务异步调用 `firstleg/`，未就绪不得审核通过 |
 | 供应商与国内整柜 | `docs/国内货柜履约/国内货柜履约需求确认表.md` | Admin `modules/suppliers/`、`modules/domestic-containers/`；Backend `warehouse/`；OpenAPI `supplier-v1.yaml`、`domestic-container-v1.yaml` |
 | 平台收货仓 | `docs/订单与客户/订单与客户头程订单闭环设计.md` | Admin `modules/warehouses/`；Client `modules/first-leg/`；Backend `warehouse/` |
 | 头程订单、批量审核预览与入仓码关系 | `docs/订单与客户/README.md`、头程订单闭环设计 | Admin `modules/first-leg-orders/`、`modules/unified-orders/`；Client `modules/first-leg/api/inboundCodeAssociations.ts`、`modules/first-leg/`；Backend `order/` 的 `InboundCodeAssociationService`、`UnifiedOrderQueryService`、`BatchOrderReviewPreviewService` 与 `firstleg/`。Order 为 `SUBMITTED` 时，即使 Firstleg 已存在准备中入库投影，统一列表仍固定显示 `PENDING_REVIEW` 并提供审核动作；批量审核弹框只调用 `/orders/first-leg/batch-review-preview` 一次获取按请求顺序返回的快照，不逐票查询详情，主要展示入仓码而非内部订单 ID |
 | 客户头程订单批量导入 | 当前 Order 契约 | Client `modules/first-leg/views/FirstLegOrdersView.vue`、`api/firstLeg.ts`；Backend `order/` 的 `MerchantBatchImportService`、`MerchantWarehouseCatalogClient`、`MerchantPricingCatalogClient` 与 `order-v1.yaml`。中文 XLSX 模板按当前客户动态生成地址、全部有效仓库和渠道下拉；导入时重新校验动态选项与客户归属，最多 50 行，只创建草稿，支持部分成功或整批原子模式 |
 | 平台旧系统订单导入 | 当前 Order 契约 | Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `PlatformLegacyOrderImportService` 与 `/api/platform/v1/orders/first-leg/legacy-import`。固定归属启用客户“IT测试公司”，保留旧入仓码，按当前公共仓库和客户价格簿逐行校验，成功行进入待审核 |
 | 平台修改客户原始申报与履约渠道 | 当前 Order/Firstleg 契约 | Admin `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `OrderDeclarationUpdateService` 与 `order-v1.yaml`，通过 `ORDER_DECLARATION_UPDATED_V1` 同步 `firstleg/` 的 `OrderDeclarationSyncService`。只修改申报快照，不覆盖仓库/PDA 实测、测量审核、箱码或已确认费用；渠道变化额外校验分柜、同柜、装柜可逆性与重新计价，国内收货仓或中转仓变化必须重新下单 |
 | 脚本管理、全量验证与测试造数 | `baiyue-firstleg/scripts/AGENTS.md`、`baiyue-firstleg/scripts/README.md` | Backend `scripts/` 为仓库级入口，`scripts/admin-test-env-modules/` 为 Admin HTTP 内部模块；服务局部脚本留在 `<service>/scripts/`，不得散落到 `src/test/scripts/`；真实 HTTP、部署或环境写入仍须当前轮明确授权 |
 | 平台/企业 RBAC | 订单与客户契约；公共语义见 `docs/平台客户层级与权限契约.md` | Admin `modules/iam/`、`core/access/`；Client `modules/tenant-management/`；Backend `iam/`、`auth/` |
 | 消息中心与站内通知 | 触发业务的阶段/专题契约，收件箱以 IAM OpenAPI 为准 | Admin/Client `modules/notifications/`；Backend `iam/.../notification/`；生产者留在所属服务 |
 | PDA 拣货与柜级装柜证据 | 国内 PDA README、拣货原型、国内货柜履约需求确认 | PDA `pages/picking/`、`stores/picking.js`、`api/pda-loading.js`；证据以 `taskId + warehouseId` 进入任务专用 API，业务所有权固定真实 `containerBookingId`，不得按入仓单或客户拆分；上传以幂等键绑定包含文件内容的请求哈希，完全重放直接返回已有结果且不得重复上传 File；Backend `firstleg/`、`warehouse/`、`file/` |
 | 到仓测量、测量库位、箱规策略与头程计费 | `docs/入库测量与计费/README.md`、测量计费入库主流程 | Admin 测量 `modules/inbounds/measurement/InboundMeasurementDialog.vue`、`InboundMeasurementPanel.vue`，称重 `modules/inbounds/weight/components/WeightOcrPanel.vue`，以及 `warehouse-resources/`、`fba-pricing/`、`dimension-config/`、`fee-items/`；Backend `firstleg/` 的 `InboundMeasurementService`、`MeasurementLocationOccupationService`、`MeasurementSubmissionService`、`CustomerDimensionConfigService`、`CustomerDimensionWeightingService`、`FbaPricingService`，并联查 `warehouse/`、`file/`、`integration-service/`。整票库位按确认图片数与有效体积容量需求的较大值尽力预留，扩容只追加且删除图片保留空槽；库位指引失败不阻断称重确认或测量提交。客户固定四档箱规可选择 `ADD/MULTIPLY`，计价和费用确认以服务端及当前实际测量明细为准 |
 | 客户专属报价、柜级阶梯运费与费用调整 | 当前 Firstleg 计价契约、`docs/入库测量与计费/README.md` | Admin `modules/fba-pricing/carrier-rates/`、`modules/inbounds/fee/`、`modules/unified-orders/components/InboundFeeDetailManager.vue`；Backend `firstleg/` 的 `PlatformPriceBookService`、`ActivePriceBookEstimator`、`FbaPricingService`、`ContainerTierAmountAllocator`、`InboundFeeDetailService` 与 `fba-pricing-v1.yaml`。公共报价使用 `customerId=0`，客户专属报价按客户独立版本化并优先于公共 ACTIVE 版本；柜级区域重量阶梯只聚合同柜同客户中费用快照同为 `REGION_WEIGHT_TIER` 的成员并守恒分摊，混柜的固定仓价等其他模型不参与阶梯且保持原费用，装柜成员变化只重算未锁定的区域阶梯费用。人工调整计费量限系统基准上下 10% 且必须带版本、原因和二次确认；`PRIVATE_LAST_MILE_DELIVERY` 只允许私人目的仓；一件代发在预装确认前完成计价，`WAIT_PALLETIZE` 试算不得回退托盘化状态 |
 | 箱唛、箱码与单箱测量 | `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`、`docs/墨家设备测量上传接口说明-V3.md` | Admin `modules/inbounds/measurement/`；Client `modules/first-leg/`；Backend 按 `firstleg/AGENTS.md` 的箱唛与测量入口 |
 | 称重确认、整票库位块与部分拣货资源结算 | 入库测量与计费主流程、国内货柜履约 PDA 契约 | Admin `modules/inbounds/weight/components/WeightOcrPanel.vue`；Backend `firstleg/` 的 `MeasurementLocationOccupationService`、`InboundMeasurementService`、`MeasurementSubmissionService` 与 `warehouse/` 的 `LocationBlockService`。测量提交审核前至少上传并确认一张称重图片，单箱也不得免称重；称重确认尽力建立整票块，提交时再次补齐，库位指引失败不阻断称重确认或测量提交。容量按确认图片数与有效体积折算的较大值，最新测量批次内实测/冻结申报体积取有效较大值；删除图片只清空绑定不释放槽位。部分拣货有余量时整段转移给子单，整票拣完才一次性释放全部普通位与共享 A0，资源身份以 `reservationId` 为准 |
 | 入库扣货、解除与凭证 | 入库测量与计费、国内货柜履约契约 | Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/api.ts`；Backend `firstleg/` 的 `InboundHoldService`、`InboundHoldGuard`、`InboundHoldEvidenceService`，文件归 `file/` 的 `INBOUND_HOLD_EVIDENCE`。扣货状态必须阻断后续物理履约写入；已发生拣货、装柜或出仓时禁止手工扣货/解除，命令携带版本与幂等键，只有进入不可变历史的凭证可下载 |
 | 财务管理与柜级公共费用分摊 | `docs/财务管理/` 产品确认、五页验收契约、Firstleg-Finance 跨服务契约 | Admin `modules/finance/`、`modules/loading-lists/components/ContainerFeesPanel.vue`；Client `modules/finance/views/FinanceBillsView.vue`，账单行按 `inboundCode` 复用头程入仓关系详情；Backend `finance/`、`firstleg/`，契约 `container-fees-v1.yaml`；导出与凭证归 `file/`。跨客户公共柜费按柜内真实客户与订单归属原子建组，金额合计等于柜费总额，审核、驳回、调整和作废整组处理，单行入口不得破坏组一致性 |
 | 客户资金账户、充值、授信与业务扣费 | `docs/财务管理/README.md`、跨区域认证与服务通信契约 | Admin `modules/finance/pages/FinanceCustomerAccountsView.vue`；Client `modules/finance/views/FinanceAccountView.vue`；Backend `finance/` 的 `FinanceWalletService` 与三类 Wallet Controller。充值申请经 File 保存凭证，平台审核或手工充扣；余额、授信、冻结、结算和释放以 Finance 主账为准。海外业务经 `WALLET_COMMAND_REQUESTED/COMPLETED` Outbox/Event Bridge 往返，不跨区同步调用钱包 |
 | 订单编排、分柜、同柜不可拆组与柜次 | `docs/国内货柜履约/README.md`、`docs/国内货柜履约/国内货柜履约需求确认表.md`、`docs/统一订单主状态与操作契约.md` | Admin `modules/unified-orders/api/coLoadGroups.ts`、`modules/unified-orders/`、`container-loading/`；Client `modules/first-leg/`；Backend `firstleg/loading/coload/`、`firstleg/split/`、`firstleg/loading/`、`order/`；同柜组按订单创建，由服务端冻结每票全部可用入仓片段，仅要求同国内仓、同渠道，允许跨客户及不同目的仓港 |
 | 全局智能排柜、预装与真实集装箱号后补 | 同上 | Admin `modules/container-loading/components/SmartLoadingDialog.vue` 内嵌 `pages/GlobalSmartLoadingView.vue`，柜次页 `SmartLoadingWorkbenchView.vue`，预装详情 `loading-lists/pages/PreloadPlanDetailView.vue`；PDA `pages/picking/`；Backend `firstleg/` 的 `PlatformSmartLoadingController`、`SmartLoadingService`、`PendingReviewOrderClient`、`loading/`，待审核事实来自 Order `PendingReviewOrderQueryService`。全局候选覆盖 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING`，状态只用于筛选展示，能否加入以服务端 `canAssign` 为准；待审核/待测量可提前占位，但确认预装或启动 PDA 前必须进入 `WAIT_SPLIT`。暂估明细的 `totalPackageCount/remainingPackageCount` 在测量前取 Order 原始申报箱数，测量完成后取最新已审核测量箱数，读取补充失败只回退当前已分配数，写入调整仍重新校验权威数量。同柜不可拆组仅在全员命中状态集合时作为一个分页与分配单元；人工加入允许跨渠道，智能推荐仍按柜次渠道。计划可一次性移除全部未拣明细，但任一成员已拣的同柜组必须整组保留。创建柜次时原子生成唯一预装计划，加入入仓码即建立关联；真实集装箱号不阻塞订舱关联，但确认预装和创建 PDA 任务前必须补齐。历史缺号任务允许在预装详情首次补录，保存后恢复 PDA 可进入状态 |
 | 客户入库结果与头程费用确认 | 入库测量与计费主流程、当前 Firstleg 契约 | Client `modules/first-leg/components/InboundBillingPanel.vue`、`api/inboundBilling.ts`；Backend `firstleg/` 的 `MerchantInboundBillingController`、`MerchantInboundBillingService`、`FbaPricingService` 与 `firstleg-v1.yaml`。客户仅能确认本客户 `SENT` 的最新费用版本，提交 `expectedFeeVersion` 与幂等键；确认记录当前成员和时间并永久锁定该版本，平台不得再修改 |
 | 订舱资料、放舱、出仓前船期与订舱级拖车 | 国内货柜履约 README、需求确认和实施边界 | Admin `modules/ocean-bookings/`、`port-schedules/`、`trucking/`；Backend `firstleg/oceanbooking/`、`firstleg/portschedule/`、`TruckAppointmentService`。拖车预约由 `RELEASED` 订舱拥有，不按客户、柜次、装柜计划或真实柜号归属；每个订舱最多一张非终态拖车单，创建候选由服务端排除缺提单/有效订舱文件或已有有效拖车单的订舱；PDA 装柜完成不推进拖车状态；全部要求货柜确认国内离仓后自动完成，人民币拖车费按实装体积分摊为柜次应付并经 Finance Outbox 入池 |
 | 目的港码头拖车与还空预警 | `docs/海外仓业务/README.md` | 与订舱级拖车预约是不同生命周期。Admin 海外清关提柜列表/详情 `modules/container-loading/pages/OverseasContainersView.vue`、`modules/container-loading/pages/OverseasContainerDetailView.vue`；Firstleg 拖车 API `api/terminalDrayages.ts`，柜级到仓 API `api/containerArrivalTimes.ts`。原预约/实际提柜列改为预计/实际到仓：预计时间由平台在列表快捷选择并同步 Lastleg 整柜尾程订单，实际时间取海外 PDA 首次开始收货；车队、邮件、还柜与 `unloadingCompletedAt + 72h` 预警仍归 `firstleg/terminaldrayage/`。 |
 | 整柜报关资料与完成文件 | 国内货柜履约契约 | 装柜完成后由 Admin `modules/container-loading/components/ContainerCustomsPanel.vue` 管理整柜报关，Client `modules/first-leg/components/CustomsDocumentsDialog.vue`、`api/customs.ts` 按订单处理本客户退税资料；Backend `firstleg/customs/container/`、`customs-v1.yaml`，文件归 `file/`。客户资料可覆盖同柜多个退税入仓码，开始报关后冻结；平台逐资料回传完成文件，全买单柜走平台确认与明细导出 |
 | 国内出仓确认 | 国内货柜履约契约 | Admin `modules/outbound-dispatch/`；Backend `firstleg/outbound/dispatch/` |
 | 客户统计与平台日志 | 当前统计/审计契约 | Admin `modules/customers/`、`modules/audit/`；Backend `firstleg/customerstatistics/`、`audit-service/` |
 | 客户工作台账户与设置 | 订单与客户契约 | Client `modules/account/`、`system/`、`tenant-management/`；Backend `iam/`、`auth/` |
 | 企业订单与跨境业务 | 订单与客户、国内货柜履约契约 | Client `modules/order-management/`、`cross-border/`；Backend `order/`、`firstleg/`、`integration-service/` |
 | 海外接柜、入库与库内库存 | `docs/海外仓业务/README.md` | Admin 按 `apps/admin-web/AGENTS.md` 海外模块入口；海外入口 `gateway-overseas/`；尾程/入仓/换标/库存 `lastleg-service/`；仓库主档归国内 `warehouse/`，库位/托盘/锁归 `warehouse-overseas-service/` 并只引用国内 warehouseId；与排车、出库、派送共同组成海外仓全流程 |
 | 尾程订单控制与柜级入仓计划转换 | `docs/海外仓业务/README.md` | Admin `modules/overseas-warehouse/pages/LastMileOrdersView.vue`、`LastMileOrderDetailView.vue`、`api/lastMileOrders.ts`；Backend `lastleg-service/` 的 `LastlegOrderController`、`LastlegOrderCommandService`、`InboundPlanService`、`ContainerInboundPlanConversionCoordinator`，资源归 `warehouse-overseas-service/` 的 `WarehousePalletBatchService`。`orders/container-summaries` 按 `sourceContainerBookingId` 跨客户聚合并分页返回全部稳定来源柜，已完成计划转换的柜仍保留用于接柜仓查询与修改；生成动作只消费 `allPlansReady/pendingPlanCount/resourcePendingPlanCount`，详情不受列表分页截断。确认前从 `/inbound-plans/container-preview` 读取服务端分组、托数、阻断项与 `snapshotVersion/snapshotHash`；`convert-container` 锁柜重算后先批量预留真实托盘，再本地原子生成剩余独立计划并确认资源，失败仅补偿未确认资源，同柜重放不得产生第二批资源。单票手工计划保存后，全柜计划齐全且预览就绪时自动生成并绑定托盘资源，一票柜立即触发；`resourcePendingPlanCount` 表示自动生成异常后的重试入口，资源未齐不得进入 PDA 接柜。自动入口见 Lastleg `ContainerInboundPlanConversionCoordinator.convertManualAndAutoMaterialize`。单票可维护完整入库计划、暂扣/解除及八行人工节点快照；命令提交订单版本与幂等键，新增暂扣只允许完成入库后执行并仅阻断该票后续排车/出库，不阻断入库计划或入库作业；人工节点首次保存后固定 `MANUAL` 来源且不得回退柜级节点 |
 | 海外仓 PDA | `docs/海外仓业务/README.md` | Overseas PDA 入仓 `api/inbound.js`、`api/receiving-adapter.js`、`pages/operation/`，库内/换标按工作台入口，排车与出库 `pages/dispatch/`、`pages/outbound/`；Backend `lastleg-service/inboundplan/pda/`、`pda/`、`dispatch/pda/`、`delivery/`；统一经 `gateway-overseas/`。接柜候选、会话、照片和整柜完成按 `sourceContainerBookingId + containerNo` 聚合且不绑定客户，允许同柜多客户；各入仓码的计划、任务、SKU、托盘与库存仍按自身客户隔离。多计划同柜按服务端返回的 `assigned/mergeAllowed/urgent` 展示，合托只是现场可选提示；扫码实收确认计划生成时预留的真实托盘与库位，不重新分配资源；派送与回访由 Admin/Client 承载 |
 | 海外采购、本土卡车与散板 | `docs/海外仓业务/README.md` | Admin `modules/overseas-business/`；Client `modules/cross-border/`；Backend `lastleg-service/` 的 `procurement/`、`trucking/`、`looseboard/`；统一经 `gateway-overseas/` |
 | 海外仓库与通用资料 | `docs/海外仓业务/README.md` | 全部仓库主档进入 Admin `modules/warehouses/` 与国内 `warehouse/`；海外库位/托盘/锁进入 `warehouse-overseas-service/` 并引用国内 warehouseId；报价、汇率、车辆按海外服务实际契约 |
 | 国内出仓后船节点 | `docs/海外仓业务/README.md` | Admin `modules/port-schedules/`、`ocean-bookings/`、货柜详情；Backend `firstleg/portschedule/`、`integration-service/`；从确认国内出仓查询至目的港到达、提柜和还柜。节点按 `containerBookingId` 柜级聚合，跨区事件使用 `tenantId=0` 平台技术范围，不携带或校验客户 |
 | 海外出库、排车、派送、异常与回访 | 当前海外履约契约 | Admin `modules/overseas-warehouse/pages/OutboundsView.vue`、`DeliveryOrdersView.vue`、`ExceptionOrdersView.vue`、`CustomerVisitsView.vue`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`、`exceptionorder/`、`customervisit/`；统一经 `gateway-overseas/`。异常单按 `PENDING → PROCESSING → COMPLETED` 流转，处理完成必须引用归属为 `OVERSEAS_EXCEPTION_EVIDENCE` 的证据；派送退回只从原出库拣货事实选择可退明细，退回海外仓时先把实收恢复到指定真实托盘/库位，再原子完成异常单并将派送置为 `RETURNED` |
 | 海外业务费用来源与客户财务 | 当前实现查财务契约与跨区域通信契约；阶段 0A—0E 开发再读 `docs/财务管理/海外仓费用统一接入阶段0技术契约.md` | 当前 V1 由 `lastleg-service/financefee/` 校验海外入仓、采购、美国卡车、本土散板和海外仓服务费，通过完整快照、Event Bridge 和 Finance 内部入口入池；阶段 0 目标改为收费身份/候选版本、Finance 接受或拒绝结果事件及版本化资金计划。必须沿代码确认落地范围，不把技术契约当成已实现状态；Client 仍只读取获准客户财务 |
 散货托盘码生成、打印与跨区传递：Admin `modules/loading-lists/components/PalletLabelPrintDialog.vue`；Firstleg `LoadingPalletLabelService`、`LoadingCompletedOutboxService`；Lastleg `LastlegSourcePalletMapper`、`InboundPlanService`。从各项目最近指引继续定位；散货 FBA 标签与一件代发实装托盘分别取各自冻结事实。
@@ -1,20 +0,0 @@
 # 二期文档
 二期以头程物流“02 到仓”为作业主线，完成预约取货、送货上门、入库测量、差异记录和指定库位闭环，并增加头程费用项目、计费规则、费用试算和费用明细。产品已确认二期不建设应收应付、对账、收付款、核销、发票和利润模块。
 ## 文档
 - [二期开发规划：头程到仓](二期开发规划.md)
 - [二期头程计费模块规划](二期计费财务模块规划.md)
 - [二期头程计费需求确认表](二期计费财务需求确认表.md)
 - [二期头程计费需求确认表（Excel，保留历史文件名）](二期计费财务需求确认表.xlsx)
 - [二期产品待确认事项（发产品填写）](二期产品待确认事项.md)
 - [二期开发进度表](二期开发进度表.md)
 - [二期开发进度表（Excel）](虫虫出海二期开发进度表.xlsx)
 - [二期需求确认清单：产品与业务确认](二期需求确认清单.md)
 - [二期需求确认清单（会议填写 Excel）](二期需求确认清单.xlsx)
 - [规划依据：头程物流流程图](参考资料/头程物流流程图.svg)
 ## 当前状态
 二期已经启动，采用“需求确认与开发并行”的推进方式。2026-07-31 已合并产品确认结果：到仓作业结论已补齐，二期财务范围收缩为“仅头程计费”。当前只剩 P2-Q14、P2-Q15、P2-Q16 三项计费细节待确认；应收应付、对账、收付款、核销、发票、汇率结算和利润不纳入二期。具体任务状态和实际进度由开发负责人回填，当前文档不代表已承诺完成日期。
@@ -0,0 +1,86 @@
 # 入库测量与计费文档
 入库测量与计费当前范围止于头程下单、商户提交、平台审核、到仓测量与称重、费用试算和费用确认。测量审核后主状态停在 `WAIT_SPLIT`，费用可独立维护且不得回退主流程状态；分柜、托盘/库位、预装、PDA 拣货、装柜和派送统一归入国内货柜履约。入库测量与计费不建设应收应付、对账、收付款、核销、发票和利润模块。
 ## 当前主体模型
 - 入库测量与计费继续按“平台—客户”两级开发。`tenant_id > 0` / `tenantId` 当前表示客户 ID，用于客户隔离；`tenant_id=0` 是平台技术作用域。
 - 不新增真实租户、租户选择器或租户级 RBAC，也不把兼容字段重定义为上级租户。历史路径、字段与配置名继续保留。
 - 平台公共仓库、快递公司、托盘、库位和费用项目统一归属平台技术作用域 `tenant_id=0`，不绑定客户；客户往来单位、订单、文件和费用明细仍按所属客户 `tenant_id>0` 严格隔离，费用明细引用公共 `fee_item_id`。`10001` 是客户 ID，不得用于公共资源归属。
 ## 文档
 - [入库测量与计费 V2 需求确认清单（当前会议填写）](入库测量与计费V2需求确认清单.md)
 - [入库测量与计费需求优化版 V2：测量、计费、托盘入库主流程](入库测量与计费需求优化版-v2-测量计费入库主流程.md)
 - [入库测量与计费需求优化版：原型对照（上一版优化稿）](入库测量与计费需求优化版-原型对照.md)
 - [入库测量与计费开发规划：头程到仓](入库测量与计费开发规划.md)
 - [入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md)
 - [入库测量与计费头程计费需求确认表](入库测量与计费计费财务需求确认表.md)
 - [入库测量与计费费用项目数据归属决策记录](入库测量与计费费用项目数据归属决策记录.md)
 - [入库测量与计费头程计费需求确认表（Excel，保留历史文件名）](入库测量与计费计费财务需求确认表.xlsx)
 - [入库测量与计费产品待确认事项（发产品填写）](入库测量与计费产品待确认事项.md)
 - [入库测量与计费开发进度表](入库测量与计费开发进度表.md)
 - [入库测量与计费开发进度表（Excel）](虫虫出海入库测量与计费开发进度表.xlsx)
 - [入库测量与计费前端页面清单与多对话并行任务表](入库测量与计费前端页面清单与多对话并行任务表.md)
 - [海外仓阶梯费用前端联调说明（2026-08-05）](海外仓阶梯费用前端联调说明-2026-08-05.md)
 - [入库测量与计费需求确认清单：产品与业务确认](入库测量与计费需求确认清单.md)
 - [入库测量与计费需求确认清单（会议填写 Excel）](入库测量与计费需求确认清单.xlsx)
 - [规划依据：头程物流流程图](参考资料/头程物流流程图.svg)
 ## 当前状态
 截至 2026-08-06，当前阶段边界已重新确认为 `WAIT_SPLIT + APPROVED + CONFIRMED`：`WAIT_SPLIT` 只表示入库测量与计费已完成、等待未来国内货柜履约分柜，不代表国内货柜履约已启动。2026-08-04 的 `INBOUNDED + APPROVED + SENT` 是旧范围下的历史回归结果，不再作为当前入库测量与计费验收终点。
 - 订单：`2084549604719718402`
 - 入库单：`2084549769916538881`
 - 入仓码：`RK-2084549604719718402`
 - 测量批次：`2084556854154715137`
 - 费用单：`FBAF-2084549769916538881-1`
 - 计费结果：实重 `20kg`，体积 `0.24m³`，计费量 `40.08kg`，费用 `440.68 CNY`
 - 自动化测试：Firstleg 77 项、Warehouse 68 项、公共仓储技术归属专项（历史测试名含“资源租户”）3 项全部通过
 - 在线验证：7 个隔离服务健康状态均为 `UP`
 本地 OCR 未配置真实供应商凭证，因此本轮验证的是“图片上传成功、OCR 返回失败、人工修正并确认、继续完成计费入库”的可用降级链路。真实 OCR 识别准确率仍需在测试环境使用现场秤图验证。
 产品确认与技术验收是两类状态。V2 的 C1-C8 产品结论仍由产品/业务负责人填写；已经实现和测试通过的技术能力记录在验收报告及确认清单的技术状态章节中。
 ## 核心文档
 - [入库测量与计费前端联调报告（2026-08-04）](入库测量与计费前端联调报告-2026-08-04.md)
 - [第三方入仓测量接口联调说明](第三方入仓测量接口联调说明-2026-08-04.md)
 - [入库测量与计费需求优化版 V2：测量、计费、托盘入库主流程](入库测量与计费需求优化版-v2-测量计费入库主流程.md)
 - [入库测量与计费 V2 需求确认清单](入库测量与计费V2需求确认清单.md)
 ## 规划与历史文档
 - [入库测量与计费需求优化版：原型对照](入库测量与计费需求优化版-原型对照.md)
 - [入库测量与计费开发规划：头程到仓](入库测量与计费开发规划.md)
 - [入库测量与计费开发进度表](入库测量与计费开发进度表.md)
 - [入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md)
 - [入库测量与计费头程计费需求确认表](入库测量与计费计费财务需求确认表.md)
 - [入库测量与计费费用项目数据归属决策记录](入库测量与计费费用项目数据归属决策记录.md)
 - [入库测量与计费产品待确认事项](入库测量与计费产品待确认事项.md)
 - [入库测量与计费需求确认清单：产品与业务确认](入库测量与计费需求确认清单.md)
 ## 数据库增量
 可重复执行的测试库增量脚本位于：
 ```text
 D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql
 ```
 该文件是头程数据库唯一增量入口，后续数据库变更只追加到此文件。当前已包含订单与客户、入库测量与计费以及海外仓阶梯费用基础资料所需结构、索引和权限。历史日期脚本不再作为部署入口。
 其中海外仓阶梯费用新增：
 - `wh_overseas_storage_fee_rule`
 - `wh_overseas_storage_fee_tier`
 - 5 个查询、唯一性和关联索引
 - 4 项平台端按钮权限及平台系统管理员默认授权
 原入库测量与计费回归字段仍包含：
 - `fl_inbound_weight_result.created_by`
 - `fl_inbound_weight_result.updated_by`
 - `fl_inbound_pallet_allocation.warehouse_resource_tenant_id`
@@ -1,11 +1,11 @@
-# 2026-07-28 二期产品确认回传审核记录
+# 2026-07-28 入库测量与计费产品确认回传审核记录
-> 回传原件：[2026-07-28-二期需求确认-产品回传.xlsx](2026-07-28-二期需求确认-产品回传.xlsx)  
+> 回传原件：[2026-07-28-入库测量与计费需求确认-产品回传.xlsx](2026-07-28-入库测量与计费需求确认-产品回传.xlsx)
 > 审核结论：暂不直接合并为正式需求基线
 ## 一、确认口径
-二期由单一产品负责人统一确认，不要求填写产品跟进人、业务确认人和确认日期。回传文件中状态为“已确认”且已填写最终结论，即视为产品确认结果；状态为“暂缓”的项目需要明确二期临时处理方式。
+入库测量与计费由单一产品负责人统一确认，不要求填写产品跟进人、业务确认人和确认日期。回传文件中状态为“已确认”且已填写最终结论，即视为产品确认结果；状态为“暂缓”的项目需要明确入库测量与计费临时处理方式。
 ## 二、需要产品补充澄清
@@ -17,17 +17,17 @@
 | P2-Q4 | 重量体积（毛重/363）；总材积重（长×宽×高/6000）×箱数 | 单位、公式中 `/363` 的业务含义、计费重是否取毛重和材积重较大值、精度和舍入规则 |
 | P2-Q5 | 差异需客户确认 | 是否所有差异都确认；客户拒绝、超时未确认以及确认前货物能否上架/计费 |
 | P2-Q6 | 没有隔离单独的区域 | 差异未关闭时货物放哪里、系统是否使用“业务暂停”而不使用隔离库位、谁可以解除暂停 |
-| P2-Q7 | 当前没有库位容量 | 二期是否完全不做容量校验；库位停用、占用和货物类型不匹配是否仍需拦截 |
+| P2-Q7 | 当前没有库位容量 | 入库测量与计费是否完全不做容量校验；库位停用、占用和货物类型不匹配是否仍需拦截 |
 | P2-Q8 | 称重照片、测量照片上传 | 是否必传、每个箱件还是每个收货批次上传、允许的文件数量/大小和补传规则 |
-| P2-Q9 | 暂缓 | 明确二期不接 PDA，并确定使用后台网页或响应式作业页 |
+| P2-Q9 | 暂缓 | 明确入库测量与计费不接 PDA，并确定使用后台网页或响应式作业页 |
 | P2-Q10 | 暂缓 | 暂缓期间无预报货物是否拒收；如允许收货，需要临时认领和超期规则 |
-| P2-Q11 | 保存 12 个月 | 从哪个时间点起算、到期删除还是归档、各类照片/联系方式/凭证是否采用同一期限 |
+| P2-Q11 | 保存 12 个月 | 从哪个时间点起算、到期删除还是归档、各类照片/联系方式/凭证是否采用同订单与客户限 |
 ## 三、当前可保留的结论
 - `P2-Q12`：标签打印设备为佳博 1324D 热敏标签打印机；标签纸、连接、驱动和指令协议仍需实机核验。
 - `P2-Q8` 已明确需要称重照片和测量照片，可作为规则方向保留，必传粒度和附件限制补齐后再锁定。
- `P2-Q9、P2-Q10` 可以保持“暂缓”，但必须给出二期临时处理规则，否则仍会阻塞对应开发任务。
+- `P2-Q9、P2-Q10` 可以保持“暂缓”，但必须给出入库测量与计费临时处理规则，否则仍会阻塞对应开发任务。
 ## 四、下一步
@@ -1,26 +1,26 @@
-# 2026-07-31 二期产品确认合并记录
+# 2026-07-31 入库测量与计费产品确认合并记录
-> 原始回传：[2026-07-31-二期需求确认-产品回传-v1.xlsx](2026-07-31-二期需求确认-产品回传-v1.xlsx)  
+> 原始回传：[2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx](2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx)
-> 回传来源：WXWork 文件 `二期需求确认清单.xlsx`  
+> 回传来源：WXWork 文件 `入库测量与计费需求确认清单.xlsx`
 > 原始文件 SHA-256：`841F976133F772BD52E085785C57D8BA90687CA07CC57B8009C71138F78C8563`
-## 一、已合并到二期到仓基线
+## 一、已合并到入库测量与计费到仓基线
 | 编号 | 产品结论 | 合并后的开发口径 |
 |---|---|---|
 | P2-Q1 | 以实际货物重量、体积为准 | 收货实测结果作为后续作业和头程计费输入；少货关闭规则按现有临时基线保留 |
 | P2-Q4 | 小数点三位向上取整 | 测量和计费中间结果保留原始值，展示/业务结果按三位向上取整；公式版本可追溯 |
 | P2-Q5 | 差异同步给客户，无需客户确认，只做记录 | 差异不再阻塞后续作业，不建设客户确认动作；保留差异记录、通知和审计 |
-| P2-Q6 | 不考虑 | 二期不建设独立隔离区和隔离释放流程 |
+| P2-Q6 | 不考虑 | 入库测量与计费不建设独立隔离区和隔离释放流程 |
 | P2-Q8 | 照片必传，大小不限制 | 称重照片、测量照片必传；产品未设置业务大小上限，系统仍保留可配置的技术安全上限和文件类型校验 |
-| P2-Q10 | 不考虑，无此场景 | 二期不建设无预报货物认领流程；不预留正式订单绑定和计费入口 |
+| P2-Q10 | 不考虑，无此场景 | 入库测量与计费不建设无预报货物认领流程；不预留正式订单绑定和计费入口 |
 | P2-Q11 | 永久保存 | 业务上不自动删除照片、凭证和测量记录；具体存储成本、合规删除和备份策略由运维另行制定 |
 ## 二、财务范围合并结论
-产品在本轮确认中明确：二期财务只做“头程计费”，不做后续财务闭环。
+产品在本轮确认中明确：入库测量与计费财务只做“头程计费”，不做后续财务闭环。
-### 二期纳入
+### 入库测量与计费纳入
 - 头程费用项目维护。
 - 头程计费规则、计费单位、价格版本和生效区间。
@@ -28,7 +28,7 @@
 - 费用结果的人工补录、调整、审核、作废和审计留痕。
 - 头程费用明细查询、订单关联、计算过程和规则快照。
-### 二期明确不纳入
+### 入库测量与计费明确不纳入
 - 应收应付台账。
 - 客户或供应商对账单、结算周期和账单确认。
@@ -37,7 +37,7 @@
 - 汇率结算、利润、利润率和财务报表。
 - 总账、会计凭证、在线支付和银企直连。
-这些模块的原型页面只作为后续阶段参考，不再进入二期开发任务、验收标准或进度统计。
+这些模块的原型页面只作为后续阶段参考，不再进入入库测量与计费开发任务、验收标准或进度统计。
 ## 三、未合并内容
@@ -49,7 +49,7 @@
 ## 四、合并后处理
- 更新二期开发规划、计费规划、需求确认清单和开发进度表。
+- 更新入库测量与计费开发规划、计费规划、需求确认清单和开发进度表。
- 从二期财务任务中移除应收应付、对账、付款、核销、发票和利润任务。
+- 从入库测量与计费财务任务中移除应收应付、对账、付款、核销、发票和利润任务。
 - 将 P2-Q13 标记为“已确认：仅头程计费”，P2-Q14 至 P2-Q16 保持待确认。
 - 产品原始回传只读归档，不覆盖；后续回传使用新版本文件名。
@@ -1,11 +1,11 @@
-# 二期产品确认回传管理
+# 入库测量与计费产品确认回传管理
-本目录只保存产品原始回传文件，不直接作为正式开发进度表使用，也不覆盖 `docs/二期/虫虫出海二期开发进度表.xlsx`。
+本目录只保存产品原始回传文件，不直接作为正式开发进度表使用，也不覆盖 `docs/入库测量与计费/虫虫出海入库测量与计费开发进度表.xlsx`。
 ## 文件命名
 ```text
-YYYY-MM-DD-二期需求确认-产品回传-vN.xlsx
+YYYY-MM-DD-入库测量与计费需求确认-产品回传-vN.xlsx
 ```
 ## 合并条件
@@ -16,13 +16,13 @@ YYYY-MM-DD-二期需求确认-产品回传-vN.xlsx
 - 例外情况、暂缓范围和临时处理规则明确。
 - 与其他确认项不存在冲突。
-二期由单一产品负责人统一确认，不要求填写确认人、产品跟进人和确认日期。产品将状态设置为“已确认”即代表结论生效。
+入库测量与计费由单一产品负责人统一确认，不要求填写确认人、产品跟进人和确认日期。产品将状态设置为“已确认”即代表结论生效。
 ## 合并流程
 1. 原样保存产品回传文件，不在原件上二次修改。
 2. 对比正式确认清单，形成回传审核记录。
 3. 产品补充不完整或冲突的结论，并将状态设置为“已确认”或“暂缓”。
-4. 按 `P2-Qxx` 合并到 `二期需求确认清单.md`。
+4. 按 `P2-Qxx` 合并到 `入库测量与计费需求确认清单.md`。
 5. 同步更新开发规划、开发任务、依赖、验收标准和 Excel 进度表。
-6. 合并前后的正式版本分别保存到 `docs/二期/版本归档/`。
+6. 合并前后的正式版本分别保存到 `docs/入库测量与计费/版本归档/`。
@@ -0,0 +1,143 @@
 # 虫虫出海入库测量与计费 V2 需求确认清单
 > 创建日期：2026-08-03
 > 当前状态：待产品与业务确认
 > 确认对象：[入库测量与计费需求优化版 V2：测量、计费、托盘入库闭环](入库测量与计费需求优化版-v2-测量计费入库主流程.md)
 > 适用范围：头程订单审核通过后的测量、计费、托盘分配、库位占用和入库闭环
 > 技术状态（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发和真实 API 回归。以下“产品确认状态”仍由产品/业务负责人填写，技术完成不自动等同于产品确认。
 > 订单衔接规则更新（2026-09-09，当前对话确认）：客户草稿不生成入仓码；客户提交进入待审核时立即生成并固定唯一入仓码，同时准备同号预入库单。货物已到国内仓时可在订单审核前先收货、称重、保存箱规并提交测量数据，但订单仍保持待审核，测量审核通过、计费、分柜和装柜必须等待订单审核通过；审核后沿用同一入仓单和已采集数据。承运商可在后续履约或计费前补充。
 > 主体模型：入库测量与计费只实现“平台—客户”两级；业务数据的 `tenant_id>0` 是客户隔离兼容字段，平台公共仓储资源归属 `tenant_id=0`。下表历史“资源租户”均指公共主数据技术归属，不代表真实租户。
 ## 一、使用说明
 - 本清单是入库测量与计费 V2 的唯一会议确认入口。
 - 产品只有一人，不填写确认人和确认时间，只填写“最终结论”和“状态”。
 - 状态统一使用：`待确认`、`已确认`、`暂缓`。
 - 认可当前建议时，可将当前建议直接复制为最终结论，并把状态改为“已确认”。
 - 修改当前建议时，必须写清可直接转成页面、接口、状态、计算或验收规则的最终结论。
 - 暂时无法确定时，状态改为“暂缓”，同时填写入库测量与计费临时处理方式。
 - C1 至 C8 全部形成可开发结论后，V2 才能替换现有 24 项开发计划。
 ## 二、产品与业务必须确认的 8 项
 | 编号 | 需要确认的事项 | 当前建议 | 最终结论 | 状态 |
 |---|---|---|---|---|
 | C1 | 是否正式采用 V2 作为入库测量与计费唯一开发基线 | 采用“测量数据采集 → 测量审核 → 自动试算 → 人工确认 → 发送费用 → 托盘与库位占用 → 入库成功”主流程；确认后旧 24 项计划和第一份优化稿停止作为开发依据 | 待填写 | 待确认 |
 | C2 | 长宽高和重量分别从哪里取得 | 长宽高由第三方测量设备按入仓码回传；重量由称重图片 OCR 识别，允许人工校正并保留 OCR 原值、修正值和修正原因 | 待填写 | 待确认 |
 | C3 | 测量审核失败是否允许继续计费和入库 | 默认禁止；仅在 Nacos 异常放行开关开启、操作人有专属权限且填写放行原因时允许继续；作废单、缺少费用快照或无可用库位始终禁止放行 | 待填写 | 待确认 |
 | C4 | 入库测量与计费计费结果的业务边界 | 入库测量与计费只生成发送给客户的头程费用；船司价格只作为计价基础，不生成船司应付、成本、对账、收付款、核销、发票或利润数据 | 待填写 | 待确认 |
 | C5 | KG/CBM 计费公式、换算系数和价格匹配维度 | 包税按 `体积 × 167` 转换为 KG 后与实重取大；不包税按 `重量 ÷ 363` 转换为 CBM 后与实测体积取大；`167`、`363` 按客户规则版本配置，不硬编码；价格按起运仓、渠道/计费类型、船司、FBA 目的仓和有效期唯一匹配 | 待填写 | 待确认 |
 | C6 | 入库测量与计费首批头程费用项目白名单 | 只纳入实际使用的基础运费和明确附加费；每项费用必须确认编码、名称、计费单位、币种、自动/人工、触发条件及是否允许人工调整 | 待填写 | 待确认 |
 | C7 | 发送费用、入库成功及复核节点 | “发送费用给客户”作为入库测量与计费完成节点：锁定费用快照、生成托盘分配、占用库位并将入库单改为已入库；默认不再增加独立接收审核或第二人复核 | 待填写 | 待确认 |
 | C8 | 托盘拆分和库位占用规则 | 按实际总体积除以单托盘可用容积向上取整；入库测量与计费默认一托一库位；托盘只分配体积和箱数汇总，不拆到 SKU；入库后换位作为 P1 独立功能 | 待填写 | 待确认 |
 ## 三、C6 首批费用项目填写表
 没有实际业务的费用不要为了匹配原型而纳入入库测量与计费。白名单之外的费用默认不能自动生成。
 | 费用编码 | 费用名称 | 计费单位 | 默认币种 | 自动/人工 | 单价来源 | 触发条件 | 是否允许调整 | 备注 |
 |---|---|---|---|---|---|---|---|---|
 | 待填写 | 待填写 | KG/CBM/票/固定金额 | CNY/USD/待确认 | 待填写 | 客户规则/船司价格/人工 | 待填写 | 待填写 | 待填写 |
 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
 ## 四、技术、仓库与供应商确认的 3 项
 以下事项不要求产品单独决定，但必须在对应任务开工前形成书面技术结论。
 | 编号 | 需要确认的事项 | 当前建议 | 最终结论 | 状态 |
 |---|---|---|---|---|
 | T1 | 第三方长宽高设备接入参数 | 确认供应商、测试环境、入仓码格式、设备编码、事件号、HMAC 签名、时间戳容差、幂等期限、超时和重试规则；第三方不得直接传内部数据库主键 | 待填写 | 待确认 |
 | T2 | OCR 接入参数 | 确认 OCR 服务商、图片格式、单图技术上限、单批数量、识别时限、置信度阈值、公斤/磅识别、失败重试和人工校正规则；业务服务通过 `fileId` 调用，不传服务器目录 | 待填写 | 待确认 |
 | T3 | 托盘和库位基础资料 | 确认托盘编码规则、标准可用容积、仓库现有托盘数量、库位编码、可用状态及初始化数据；并发占位由数据库唯一约束或乐观锁保证 | 待填写 | 待确认 |
 ## 五、确认后形成的入库测量与计费主流程
 ```text
 订单与客户头程订单提交待审核
  → 生成并固定唯一入仓码
  → 平台审核通过（承运商不是审核前置条件）
  → 创建正式入库单并沿用该入仓码
  → 第三方回传长宽高
  → 上传称重图片并进行 OCR
  → 人工校正和确认重量
  → 测量审核
  → 客户规则与船司 FBA 价格自动试算
  → 人工确认费用
  → 发送费用给客户
  → 拆分托盘并分配库位
  → 占用库位并完成入库
  → 客户只读查看费用和入库结果
  → 异步发送客户通知
 ```
 ## 六、明确不纳入入库测量与计费
 - 船司应付、供应商应付和应付审核。
 - 客户或供应商对账单、结算周期和账单争议。
 - 收款、付款、退款、核销、反核销和银行流水。
 - 发票、开票接口、会计凭证和总账。
 - 单票利润、利润率和完整财务报表。
 - 头程/FBA 阶梯计费、组合优惠和通用计费表达式平台。
 - 完整 SKU 库存、盘点、拣货、复核和出库。
 - 入库后的常规移库、拆托、并托和库存成本。
 - PDA 作业端。
 ### 6.1 海外仓阶梯费用的范围例外
 - 已纳入“海外仓客户级天数阶梯仓储费”的基础资料 CRUD，归属 Warehouse 服务，不新增独立服务或数据库。
 - 一名客户只允许一份有效配置，维护币种及连续的天数区间、仓储费单价。
 - 该配置当前只供平台端维护和查询，暂不接入本期头程/FBA 自动计费、费用发送、账单或结算流程。
 - 后续接入海外仓实际计费时，需要另行确认计费单位、入库/出库日边界、免租期、尾段处理、币种换算和规则生效版本。
 ## 七、与原确认问题的对应关系
 | 原编号 | 原问题 | V2 对应项 | 处理方式 |
 |---|---|---|---|
 | P2-Q14 | 首批费用项目 | C6 | 由 C6 费用白名单替代 |
 | P2-Q15 | 计费规则复杂度 | C4、C5 | 由计费边界、公式和匹配维度替代 |
 | P2-Q16 | 费用生成节点 | C7 | 由费用确认、发送和入库成功节点替代 |
 C1 至 C8 确认后，原 P2-Q14 至 P2-Q16 不再单独维护，避免形成两套需求编号。
 ## 八、确认完成后的文档处理
 1. 将本文件状态改为“已确认”。
 2. 将 [入库测量与计费需求优化版 V2](入库测量与计费需求优化版-v2-测量计费入库主流程.md) 标记为正式开发基线。
 3. 将 [入库测量与计费需求优化版：原型对照](入库测量与计费需求优化版-原型对照.md) 标记为历史版本，不再用于开发。
 4. 用 V2 的 13 项任务替换现有 24 项开发计划，并同步 Markdown 和 Excel 进度表。
 5. 将 C1 至 C8 的结论转换为状态、接口、数据表、权限、异常和验收规则。
 6. 将 T1 至 T3 分配给技术、仓库和供应商负责人，在对应开发任务开始前补齐。
 7. 后续新增应收应付、对账、收付款、发票或利润时，必须另行立项，不得直接扩入入库测量与计费。
 ## 九、进入开发排期的完成标准
 - C1 至 C8 均为“已确认”，或“暂缓”但已写明入库测量与计费可执行的临时处理方式。
 - C6 至少形成一版可初始化的费用项目白名单。
 - 计费公式、换算系数、唯一匹配维度和费用发送节点可以转为自动化测试。
 - 托盘数量、库位占用和并发冲突规则可以转为数据库约束和接口验收。
 - T1 至 T3 已明确责任方和最晚完成节点。
 - V2 的 13 项任务已经同步到正式开发进度表，旧任务不再继续认领。
 ## 十、技术实现状态（2026-08-04）
 | 对应项 | 技术状态 | 验证说明 |
 |---|---|---|
 | C1 主链路 | 已完成正常链路 | 下单、审核、测量、称重、计费、费用发送、托盘库位、入库已通过真实 API |
 | C2 测量与重量来源 | 已实现 | 第三方/平台箱规明细、图片证据、OCR 失败人工修正与确认已验证 |
 | C3 审核失败放行 | 已实现配置和权限边界 | Nacos 开关默认关闭；正常审核通过链路已验证 |
 | C4 计费边界 | 已按入库测量与计费范围实现 | 仅生成客户头程费用，不扩展应付、对账、核销、发票和利润 |
 | C5 KG/CBM 规则 | 已实现并验证样本 | 实重 `20kg`、体积重 `40.08kg`，取 `40.08kg` 计费 |
 | C6 费用项目白名单 | 技术能力已具备，业务内容待确认 | 本轮使用测试价格 `11 CNY/kg`，不能代替正式费用白名单 |
 | C7 费用发送与入库节点 | 已实现 | 审核通过后自动生成费用 `440.68 CNY`，最终 `SENT + INBOUNDED` |
 | C8 托盘与库位 | 已实现 | 托盘、库位、预占、确认占用及公共主数据技术归属快照已验证 |
 | T1 第三方测量参数 | 接口能力已实现，供应商参数待定 | 正式签名密钥、设备编码和供应商联调环境仍需确认 |
 | T2 OCR 参数 | 降级链路已验证，真实供应商待接入 | 本地 OCR 未配置，已验证失败后人工修正继续入库 |
 | T3 托盘库位基础资料 | 已实现并通过 API 创建 | 当前公共主数据技术归属规则为 `tenant_id=0`，分配状态 `CONFIRMED`；`10001` 不再作为公共资源归属 |
 完整接口与回归证据见 [入库测量与计费前端联调报告（2026-08-04）](入库测量与计费前端联调报告-2026-08-04.md)。
@@ -1,15 +1,15 @@
-# 虫虫出海二期产品待确认事项
+# 虫虫出海入库测量与计费产品待确认事项
-> 更新日期：2026-07-31  
+> 更新日期：2026-07-31
-> 适用范围：头程物流“02 到仓”及头程计费  
+> 适用范围：头程物流“02 到仓”及头程计费
-> 正式状态以 [二期需求确认清单](二期需求确认清单.md) 为准。  
+> 正式状态以 [入库测量与计费需求确认清单](入库测量与计费需求确认清单.md) 为准。
 > 产品只有一人，不需要填写确认人和确认时间；会议只填写最终结论和状态。
 ## 一、会议结论摘要
- 产品已确认到仓作业规则及二期“只做头程计费”的范围。
+- 产品已确认到仓作业规则及入库测量与计费“只做头程计费”的范围。
 - 当前只需确认 P2-Q14、P2-Q15、P2-Q16，共 3 项。
- P2-Q17 至 P2-Q24 对应应收应付、对账、收付款、核销、发票、汇率结算和利润能力，均不纳入二期。
+- P2-Q17 至 P2-Q24 对应应收应付、对账、收付款、核销、发票、汇率结算和利润能力，均不纳入入库测量与计费。
 - 产品回传中 Q14 至 Q16 的“63”没有业务含义，本次会议需要重新填写。
 ## 二、本次会议需要确认的 3 项
@@ -22,7 +22,7 @@
 ## 三、P2-Q14 首批费用项目填写模板
-没有实际业务的费用不要为了匹配原型而纳入二期。
+没有实际业务的费用不要为了匹配原型而纳入入库测量与计费。
 | 费用编码 | 费用名称 | 费用性质 | 计费对象 | 计费单位 | 默认币种 | 默认税率 | 自动/人工 | 触发节点 |
 |---|---|---|---|---|---|---|---|---|
@@ -30,7 +30,7 @@
 ## 四、已确认，无需再次询问
-| 编号 | 产品结论 | 二期开发口径 |
+| 编号 | 产品结论 | 入库测量与计费开发口径 |
 |---|---|---|
 | P2-Q1 | 以实际货物重量、体积为准 | 实测结果作为后续作业和头程计费输入 |
 | P2-Q2 | 不做系统服务商调度 | 线下安排取货，系统记录结果 |
@@ -43,14 +43,14 @@
 | P2-Q10 | 不考虑无预报货物 | 不建设无预报认领和正式订单绑定流程 |
 | P2-Q11 | 永久保存 | 业务记录不自动删除；运维补充备份和合规策略 |
 | P2-Q12 | 使用佳博 1324D 热敏标签打印机 | 开发前核验纸张、连接、驱动和指令协议 |
-| P2-Q13 | 二期只做头程计费 | 不生成应收、应付、账单、付款、核销、发票或利润数据 |
+| P2-Q13 | 入库测量与计费只做头程计费 | 不生成应收、应付、账单、付款、核销、发票或利润数据 |
-P2-Q9 暂缓：二期不接 PDA，使用后台或响应式作业页。
+P2-Q9 暂缓：入库测量与计费不接 PDA，使用后台或响应式作业页。
 ## 五、确认后的处理
 1. 将 Q14 至 Q16 的最终结论和状态回写正式需求确认清单。
 2. 技术审核结论是否足以转为字段、状态、计算、权限、异常和验收规则。
-3. 同步更新二期开发规划、头程计费规划、开发进度表和 Excel。
+3. 同步更新入库测量与计费开发规划、头程计费规划、开发进度表和 Excel。
 4. 保留产品原始回传和本次会议版本；后续修改用新版本，不覆盖历史文件。
@@ -0,0 +1,627 @@
 # 入库测量、计费与入库前端联调报告
 > 版本日期：2026-08-04  
 > 后端仓库：`D:\baiyue-firstleg`  
 > 代码基线：`test-01` 分支，提交 `25d2a13`  
 > 使用对象：平台后台前端、商户端前端、第三方测量系统联调人员
 > 术语与现行规则校正：当前产品只有“平台—客户”两级。客户业务中的 `tenantId` / `tenant_id` 表示客户 ID 兼容字段；“资源租户”历史术语表示公共主数据技术归属。平台公共仓库、快递公司、托盘和库位现归属 `tenant_id=0`，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`；报告中的 `10001` 是已失效的历史联调样本，不得继续作为公共资源归属。
 ## 一、联调结论
 入库测量与计费后端主流程、平台测量、OCR 重量、客服审核、FBA 计费、费用发布、入库完成、库位和托盘维护、客户只读查询、第三方测量回传接口均已形成代码闭环。
 最终正常业务流程是：
 ```text
 订单生成入库单
  → 第三方或平台录入长宽高、箱规和件数
  → 上传称重图片并执行 OCR
  → 人工修正并确认 OCR 重量
  → 保存测量草稿
  → 提交测量
  → 系统按托盘容量拆分托盘并立即占用库位
  → 客服审核测量数据
  → 审核通过后自动按 FBA 规则计费
  → 自动发布费用给客户
  → 自动完成入库
  → 客户只读查看费用和入库结果
 ```
 联调时必须遵守以下口径：
 - 客户不确认费用，前端不得设计或调用“客户确认费用”操作。
 - 测量提交后必须由客服审核；第三方回传测量数据不能直接审核、计费或完成入库。
 - 提交测量时已经完成托盘拆分和库位占用。客服驳回只退回测量修改，已占库位不释放。
 - 客服审核通过后，后端自动完成计费、内部确认、费用发布和入库，不需要前端依次点击计费、确认、发送。
 - 已发布费用可以调整；调整会生成新费用版本，但不会回退 `INBOUNDED` 入库状态。
 - 测量审核失败默认不允许异常放行。Nacos 配置 `firstleg.workflow.allow-rejected-measurement=false`，仅开启配置且有专门权限时才能放行。
 - 当前只实现 FBA 目的仓计费，不包含应收应付、对账、核销、发票、利润、PDA 和完整 WMS。
 ## 二、服务依赖、入口与文档
 ### 2.1 前端统一入口
 本地默认网关：
 ```text
 http://127.0.0.1:9000
 ```
 聚合 Swagger：
 ```text
 http://127.0.0.1:9000/webjars/swagger-ui/index.html
 ```
 Swagger 分组：
 - `firstleg-platform`：平台入库、测量、审核、计费及客户只读接口。
 - `firstleg-measurement-openapi`：第三方测量回传接口。
 - `warehouse-platform`：库位、托盘等仓储基础资料。
 - `file-platform`：测量图片上传、识别和读取。
 - `integration`：OCR 内部能力，前端一般不直接调用。
 ### 2.2 联调相关服务及默认端口
 | 顺序 | 服务 | 默认端口 | 用途 |
 |---:|---|---:|---|
 | 1 | Nacos、MySQL、Redis | 环境配置 | 注册配置、数据和会话 |
 | 2 | `iam-service` | 9201 | 用户、角色、按钮权限 |
 | 3 | `auth-service` | 9100 | 登录、Token 刷新和退出 |
 | 4 | `warehouse-service` | 9205 | 仓库、库位、托盘及占用 |
 | 5 | `integration-service` | 9210 | OCR 识别能力 |
 | 6 | `file-service` | 9206 | 图片上传、持久化和 OCR 聚合 |
 | 7 | `firstleg-service` | 9202 | 入库、测量、审核和计费主流程 |
 | 8 | `gateway` | 9000 | 前端统一入口和聚合文档 |
 若登录或订单前置流程依赖其他订单与客户服务，应在 Firstleg 前启动。前端业务请求统一走网关，不要将各服务端口写死到页面。
 ## 三、全局请求与响应约定
 ### 3.1 平台和商户请求头
 ```http
 Authorization: Bearer <accessToken>
 Content-Type: application/json
 ```
 平台代目标企业操作的接口还必须传代表目标客户的 `tenantId` 查询参数。后端同时校验登录应用类型、操作者数据范围、目标客户、仓库和资源归属；不能只依靠前端隐藏按钮实现隔离。
 所有有副作用且要求幂等的接口必须传：
 ```http
 Idempotency-Key: <每次业务操作唯一且重试保持不变的字符串>
 ```
 网络超时重试时复用原键；用户重新发起一笔新操作时生成新键。
 ### 3.2 统一响应
 ```json
 {
  "code": "00000",
  "message": "成功",
  "data": {},
  "requestId": "...",
  "traceId": "...",
  "timestamp": "2026-08-04T02:38:31Z"
 }
 ```
 - 前端必须以业务 `code` 判断成功，不能只判断 HTTP 200。
 - 分页数据结构为 `data.records`、`data.page`、`data.size`、`data.total`、`data.pages`。
 - Long 类型 ID 已统一序列化为 JSON 字符串，前端必须按字符串保存和传递，不要转换成 JavaScript `Number`。
 - 401 统一跳转登录或触发刷新 Token；403 显示无权限；409 通常表示重复、状态冲突、乐观锁过期或资源已被占用，页面应刷新详情后再操作。
 - 提交按钮在请求完成前禁用，配合 `Idempotency-Key` 防止重复提交。
 ## 四、状态、页签和按钮规则
 ### 4.1 入库流程状态 `processStatus`
 | 状态 | 中文含义 | 页面主要操作 |
 |---|---|---|
 | `WAIT_MEASURE` | 待测量 | 进入测量、录入草稿 |
 | `MEASURING` | 测量中 | 编辑草稿、OCR、人工修正、提交 |
 | `MEASURE_PENDING` | 待客服审核 | 客服审核通过或驳回 |
 | `MEASURE_REJECTED` | 测量驳回 | 修改并重新提交；特殊情况下异常放行 |
 | `WAIT_PRICING` | 待计费 | 正常流程由后台自动推进 |
 | `FEE_CONFIRMING` | 费用处理中 | 正常流程由后台自动推进 |
 | `INBOUNDING` | 入库处理中 | 正常流程由后台自动推进 |
 | `INBOUNDED` | 已入库 | 查看费用、库位、文件；有权限时调整费用 |
 | `VOIDED` | 已作废 | 只读 |
 页面不要根据中文文案判断状态，必须使用状态码。
 ### 4.2 列表页签 `tab`
 | 页签参数 | 后端包含状态 |
 |---|---|
 | `WAIT_MEASURE` | `WAIT_MEASURE`、`MEASURING`、`MEASURE_REJECTED` |
 | `WAIT_REVIEW` | `MEASURE_PENDING` |
 | `WAIT_FEE_SEND` | `WAIT_PRICING`、`FEE_CONFIRMING`、`INBOUNDING` |
 | `INBOUNDED` | `INBOUNDED` |
 ### 4.3 主流程状态变化
 | 业务动作 | 结果状态 | 库位事实 |
 |---|---|---|
 | 保存测量草稿 | `MEASURING` | 未占用 |
 | 提交测量 | `MEASURE_PENDING` | 已拆托并确认 `OCCUPIED` |
 | 客服驳回 | `MEASURE_REJECTED` | 保持占用 |
 | 客服通过 | 自动经过计费和入库中间态 | 保持占用 |
 | 自动闭环完成 | `INBOUNDED`，费用 `SENT` | 保持占用 |
 | 调整已发布费用 | 仍为 `INBOUNDED`；新费用 `SENT`，旧费用 `SUPERSEDED` | 保持占用 |
 ## 五、平台入库单列表与详情
 | 方法 | 路径 | 权限 |
 |---|---|---|
 | GET | `/api/platform/inbounds` | `platform:firstleg:inbound:list` |
 | GET | `/api/platform/inbounds/{inboundId}` | `platform:firstleg:inbound:view` |
 共同参数：`tenantId`。列表支持：
 ```text
 inboundCode, orderNo, processStatus, orderStatus, measureReviewStatus,
 feeStatus, feeReviewStatus, tab, expectedArrivalFrom, expectedArrivalTo,
 customerId, customerName, companyId, warehouseId, deliveryWarehouseId,
 destinationCode, holdFlag, page, size
 ```
 列表已覆盖前端主要展示字段：入仓码、订单号、订单/流程/测量审核/费用状态、客户、公司、仓库、交货仓、FBA 目的仓、扣货、箱数、实重、净重、实测体积、材积重、计费重量、计费体积、托盘数、`locationCodes`、测量和入库完成时间、快递公司和快递单号、配载、集装箱、柜号、船名、航次、开船和到港时间、创建和更新时间。
 详情在此基础上还返回：`publicRemark`、`palletLocations`、`files`、`internalNotes`、`statusHistory`。
 ## 六、平台测量与 OCR
 接口前缀：
 ```text
 /api/platform/v1/first-leg/inbounds/{inboundId}
 ```
 | 方法 | 子路径 | 权限 | 说明 |
 |---|---|---|---|
 | GET | `/measurement` | `platform:firstleg:inbound:measure:view` | 获取测量、明细和 OCR 结果 |
 | PUT | `/measurement/draft` | `platform:firstleg:inbound:measure:edit` | 保存或更新草稿 |
 | POST | `/measurement/submit` | `platform:firstleg:inbound:measure:submit` | 提交并拆托、占库位 |
 | POST | `/weight-results` | `platform:firstleg:inbound:weight:edit` | 新增 OCR 结果 |
 | PUT | `/weight-results/{resultId}` | `platform:firstleg:inbound:weight:edit` | 人工修正重量 |
 | POST | `/weight-results/{resultId}/confirm` | `platform:firstleg:inbound:weight:confirm` | 确认最终重量 |
 以上接口均带 `tenantId`；写接口按 Swagger 要求携带 `Idempotency-Key`。
 ### 6.1 保存测量草稿
 ```json
 {
  "measurementId": "已有草稿时传，首次可为空",
  "version": 0,
  "originalDocumentNo": "原单据号",
  "originalGrossWeightKg": 100.000,
  "originalVolumeCbm": 2.5000,
  "actualGoodsName": "实际品名",
  "items": [
    {
      "itemNo": "ITEM-001",
      "boxSpecification": "60*40*50cm",
      "packageCount": 10,
      "lengthCm": 60.000,
      "widthCm": 40.000,
      "heightCm": 50.000,
      "unitWeightKg": 12.500,
      "intelligentImageFileId": "图片文件ID",
      "overLimitWarning": "",
      "outerLengthCm": 61.000,
      "outerWidthCm": 41.000,
      "outerHeightCm": 51.000,
      "remark": ""
    }
  ]
 }
 ```
 注意：汇总体积、材积重等计算字段由后端计算，前端不要传入或自行覆盖。`items` 至少一条，尺寸和单件重量必须大于 0，`boxSpecification` 必填。
 提交测量请求：
 ```json
 {
  "measurementId": "190000000000000001",
  "version": 1
 }
 ```
 `version` 是乐观锁版本。每次保存、修正或确认成功后都应使用响应中的新版本；409 后重新拉取详情，不能用旧版本强行重试。
 ### 6.2 OCR 重量
 图片接口：
 | 方法 | 路径 | 权限 |
 |---|---|---|
 | POST | `/api/platform/v1/files/measurements/{tenantId}/{inboundId}` | `platform:firstleg:inbound:weight:edit` |
 | POST | `/api/platform/v1/files/measurements/{tenantId}/{inboundId}/{fileId}/recognize` | `platform:firstleg:inbound:weight:edit` |
 | GET | `/api/platform/v1/files/measurements/{tenantId}/{inboundId}/{fileId}` | `platform:firstleg:inbound:measure:view` |
 支持 JPG、PNG、BMP，单文件最大 5 MB。建议交互顺序：上传图片 → 调用识别 → 展示 OCR 原值、单位、置信度 → 用户按需修正 → 确认重量。
 人工修正请求：
 ```json
 {
  "version": 0,
  "adjustedWeightValue": 12.500,
  "adjustedWeightUnit": "KG",
  "adjustmentReason": "OCR 小数点识别错误"
 }
 ```
 确认请求：
 ```json
 {
  "version": 1
 }
 ```
 测量详情会返回 OCR 原文、原重量和单位、置信度、人工修正值和原因、最终 KG、识别状态、修正/确认人员与时间、版本。多张秤图的最终重量由业务服务汇总，前端只负责展示和人工确认，不自行写汇总重量。
 ## 七、客服测量审核
 | 方法 | 路径 | 权限 |
 |---|---|---|
 | POST | `/api/platform/v1/inbounds/{inboundId}/measurements/approve` | `firstleg:inbound:measurement-review` |
 | POST | `/api/platform/v1/inbounds/{inboundId}/measurements/reject` | `firstleg:inbound:measurement-review` |
 | POST | `/api/platform/v1/inbounds/{inboundId}/measurements/exception-release` | `firstleg:inbound:exception-release` |
 | GET | `/api/platform/v1/inbounds/{inboundId}/measurement-review-history` | `firstleg:inbound:measurement-review-history` |
 写接口必须传 `tenantId` 和 `Idempotency-Key`。通过/驳回请求：
 ```json
 {
  "measurementId": "190000000000000001",
  "expectedVersion": 2,
  "reason": "审核意见，通过时可为空，驳回时按业务填写"
 }
 ```
 异常放行请求的 `reason` 必填：
 ```json
 {
  "measurementId": "190000000000000001",
  "expectedVersion": 3,
  "reason": "负责人审批后的异常放行原因"
 }
 ```
 审核通过请求成功即表示后端自动闭环已执行完成或可幂等续跑。前端应重新查询入库详情和最新费用，不要再自动串行调用 `/calculate`、`/confirm`、`/send`。
 ## 八、FBA 计费与费用调整
 接口前缀：
 ```text
 /api/platform/v1/inbounds/{inboundId}/fees
 ```
 | 方法 | 子路径 | 权限 | 前端用途 |
 |---|---|---|---|
 | GET | `/latest` | `firstleg:fba-pricing:view` | 查询最新费用快照 |
 | PUT | `/published` | `firstleg:fba-pricing:adjust` | 调整已发布费用 |
 | POST | `/calculate` | `firstleg:fba-pricing:calculate` | 异常恢复/人工补偿，不是正常主流程按钮 |
 | POST | `/confirm` | `firstleg:fba-pricing:confirm` | 异常恢复/人工补偿 |
 | POST | `/send` | `firstleg:inbound:send-fee` | 异常恢复/人工补偿 |
 调整已发布费用：
 ```json
 {
  "subtotalAmount": 1000.00,
  "additionalAmount": 50.00,
  "reason": "经审批调整附加费"
 }
 ```
 计费规则：
 - 包税、按 KG：`计费数量 = max(实重, 实测 CBM × 换算系数)`。
 - 不包税、按 CBM：`计费数量 = max(实测 CBM, 实重 ÷ 换算系数)`。
 - 换算系数、精度、舍入方式、币种和价格均来自客户规则及船司费率版本，前端不能写死。
 FBA 基础资料：
 ```text
 GET    /api/platform/v1/fba-pricing/customer-rules
 GET    /api/platform/v1/fba-pricing/customer-rules/{id}
 POST   /api/platform/v1/fba-pricing/customer-rules/versions
 DELETE /api/platform/v1/fba-pricing/customer-rules/{id}
 GET    /api/platform/v1/fba-pricing/carrier-rates
 GET    /api/platform/v1/fba-pricing/carrier-rates/{id}
 POST   /api/platform/v1/fba-pricing/carrier-rates/versions
 DELETE /api/platform/v1/fba-pricing/carrier-rates/{id}
 ```
 规则采用版本化新增，历史订单费用使用当时快照，不应被新版本覆盖。
 ## 九、库位管理
 | 方法 | 路径 | 权限 |
 |---|---|---|
 | GET | `/api/platform/v1/locations` | `platform:location:list` |
 | GET | `/api/platform/v1/locations/{id}` | `platform:location:list` |
 | GET | `/api/platform/v1/locations/available` | `platform:location:list` |
 | POST | `/api/platform/v1/locations` | `platform:location:create` |
 | PUT | `/api/platform/v1/locations/{id}` | `platform:location:edit` |
 | PATCH | `/api/platform/v1/locations/{id}/status` | `platform:location:status` |
 | DELETE | `/api/platform/v1/locations/{id}` | `platform:location:delete` |
 分页条件：`tenantId`、`warehouseId`（必填）、`zoneCode`、`locationCode`、`locationType`、`status`、`page`、`size`。
 库位类型：`SHELF`、`PALLET`、`FLOOR`、`FLOW_RACK`。查询状态：`AVAILABLE`、`RESERVED`、`OCCUPIED`、`DISABLED`。
 新增/编辑请求：
 ```json
 {
  "warehouseId": "190000000000000002",
  "zoneCode": "A",
  "zoneName": "A库区",
  "locationCode": "A-001",
  "locationName": "A区001库位",
  "locationType": "PALLET",
  "maxWeightKg": 1000.000,
  "status": "AVAILABLE",
  "remark": "",
  "version": 0
 }
 ```
 启停仅允许 `AVAILABLE` 或 `DISABLED`，请求为：
 ```json
 {
  "status": "DISABLED",
  "version": 1
 }
 ```
 活动预占或已占用库位不能停用；删除要求库位已停用、无活动预占/占用，并在查询参数传 `warehouseId`、`version`。无普通空闲库位时，系统可使用本租户、本仓库的共享溢出位 `A0`，前端只展示后端结果。
 ## 十、托盘管理
 | 方法 | 路径 | 权限 |
 |---|---|---|
 | GET | `/api/platform/v1/pallets` | `platform:pallet:list` |
 | GET | `/api/platform/v1/pallets/{id}` | `platform:pallet:list` |
 | POST | `/api/platform/v1/pallets` | `platform:pallet:create` |
 | PUT | `/api/platform/v1/pallets/{id}` | `platform:pallet:edit` |
 | DELETE | `/api/platform/v1/pallets/{id}` | `platform:pallet:delete` |
 分页条件：`tenantId`、`warehouseId`、`palletCode`、`palletType`、`page`、`size`。新增/编辑请求：
 ```json
 {
  "warehouseId": "190000000000000002",
  "palletCode": "TP-001",
  "palletType": "木托盘",
  "capacityCbm": 2.000000,
  "remark": "标准托盘"
 }
 ```
 当前平台托盘 DTO 只返回主数据，不暴露内部 `AVAILABLE / RESERVED / OCCUPIED` 状态；也没有单独的托盘启停或状态筛选 API。页面当前只实现查询、新增、编辑、删除。已预占或占用托盘删除会被后端拒绝。这是当前明确的接口边界，不要自行猜测状态路径。
 ## 十一、商户端只读接口
 ```http
 GET /api/merchant/v1/first-leg/orders/{orderId}/inbound-billing
 ```
 权限：`merchant:order:view`。
 返回 `inbound` 和 `latestFee`。仅允许商户身份查询本租户订单，且只有客服审核通过并已发布的费用可见。商户端只展示：入库结果、测量汇总、托盘/库位结果和最新费用，不提供费用确认、测量审核、费用修改操作。
 ## 十二、第三方测量开放接口
 | 方法 | 路径 | 说明 |
 |---|---|---|
 | POST | `/openapi/v1/inbound-measurements` | 一次提交一条箱规明细和一张对应图片 |
 | GET | `/openapi/v1/inbound-measurements/events/{eventNo}` | 查询事件处理结果 |
 请求头：
 ```http
 X-App-Key: <调用方应用键>
 X-Timestamp: <时间戳>
 X-Nonce: <随机串>
 X-Signature: <签名>
 Idempotency-Key: <幂等键>
 ```
 POST 使用 `multipart/form-data`，包含：
 ```text
 data：原始 UTF-8 JSON 文本
 image：该条箱规唯一对应的 JPG/PNG/BMP 图片，最大 5 MB
 ```
 `data` 示例：
 ```json
 {
  "eventNo": "M202608010001",
  "externalDetailNo": "BOX-20260801-0001",
  "warehouseCode": "CN-YW-01",
  "inboundCode": "RK202608010001",
  "inboundDetailId": "190000000000000001",
  "deviceCode": "DEVICE-01",
  "measuredAt": "2026-08-01T10:30:00+08:00",
  "boxSpecification": "60*40*50cm",
  "packageCount": 10,
  "lengthCm": 60.000,
  "widthCm": 40.000,
  "heightCm": 50.000,
  "unitWeightKg": 12.500,
  "remark": ""
 }
 ```
 绑定和签名规则：
 - 后端先按 `inboundCode` 匹配入库单，再使用 `inboundDetailId` 通过 Order 内部接口校验该货物明细确实属于入库单关联订单；第三方不能自由创建来源不明的明细。
 - 一次请求只生成一个测量批次、一条测量明细和一个文件中心图片引用。
 - `externalDetailNo` 标识第三方物理测量明细；同一订单明细和相同第三方明细号不能重复绑定。
 - `eventNo` 在同一 `appKey` 下唯一；相同事件号或幂等键重试时，测量 JSON 和图片内容必须完全一致。
 - 签名 body 为：`data原文 + LF + image文件内容SHA-256小写十六进制`；再按既有六行 HMAC 规则计算 `X-Signature`。
 - `measuredAt` 必须带时区；长宽高大于 0；`packageCount` 为 1 至 1,000,000；`boxSpecification` 必填。
 - 图片由 File 服务验证真实格式并持久化；尺寸测量图片不触发重量 OCR。测量落库失败时会调用文件中心补偿清理。
 - 接口只接收测量数据，不推进客服审核、计费、库位或入库状态。
 成功响应的 `data` 返回：`eventNo`、`inboundCode`、`inboundDetailId`、`measurementId`、`measurementItemId`、`imageFileId`、`accepted`、`status`、`receivedAt`。所有 ID 按字符串处理。
 ## 十三、推荐前端联调顺序
 1. 验证平台登录、刷新 Token、退出、过期会话、401 和 403。
 2. 给测试角色同步入库测量与计费权限，确认按钮显示与后端权限码一致。
 3. 初始化启用仓库、至少一个托盘、足量可用库位、客户计费规则和船司 FBA 费率。
 4. 创建或准备一条已进入待测量状态的真实入库单。
 5. 调用入库列表和详情，核对 Long ID 均按字符串处理。
 6. 上传秤图、调用 OCR、人工修正和确认重量。
 7. 保存测量草稿，刷新页面后核对草稿和版本回显。
 8. 提交测量，验证状态变为 `MEASURE_PENDING`，托盘和库位结果已生成。
 9. 先走一次驳回 → 修改 → 重新提交，验证旧页面版本提交被拒绝。
 10. 客服审核通过，随后重新查询详情和 `/fees/latest`，验证自动变为 `INBOUNDED / SENT`。
 11. 商户账号查询 `inbound-billing`，验证只读数据、跨客户 403/404 和未发布费用不可见。
 12. 调整一次已发布费用，验证新版本可见、旧版本被替代且入库状态不回退。
 13. 验证重复点击使用同一幂等键不会重复计费、重复托盘或重复占位。
 14. 验证无权限按钮、直接构造越权请求、空态、加载态、异常提示和移动端展示。
 ## 十四、测试数据准备清单
 - 平台管理员账号：具备入库查看、测量、OCR、审核、计费查看/调整、库位和托盘权限。
 - 客服账号：具备测量审核权限，但不授予异常放行权限，用于验证按钮隔离。
 - 商户账号：绑定独立租户，只具备本企业订单查看权限。
 - 两个不同租户及各自仓库，用于跨企业越权验证。
 - 一个启用仓库、至少 2 个容量明确的托盘、至少 2 个 `AVAILABLE` 库位。
 - 一套生效中的客户 FBA 计费规则和匹配的船司费率，币种、渠道、目的仓、有效期完整。
 - 一条待测量入库单、一条已发布费用入库单。
 - JPG/PNG/BMP 各一张有效秤图，以及超 5 MB、伪造扩展名和无法识别图片各一张。
 - 第三方测量应用的 AppKey、签名密钥、绑定租户和仓库编码。
 ## 十五、本次回归测试结果
 2026-08-04 11:42（Asia/Shanghai）在最终代码上重新执行：
 ```powershell
 D:\apache-maven-3.8.8\bin\mvn.cmd clean test -pl order,firstleg,warehouse,file,integration-service,gateway,iam -am
 ```
 结果：13 个 Reactor 模块全部 `SUCCESS`，`BUILD SUCCESS`，耗时约 1 分 5 秒。
 | 模块 | 测试数 | Failures | Errors | Skipped |
 |---|---:|---:|---:|---:|
 | common-core | 3 | 0 | 0 | 0 |
 | common-web | 10 | 0 | 0 | 0 |
 | common-security | 6 | 0 | 0 | 0 |
 | common-openapi | 1 | 0 | 0 | 0 |
 | common-audit | 0 | 0 | 0 | 0 |
 | gateway | 10 | 0 | 0 | 0 |
 | iam | 79 | 0 | 0 | 0 |
 | order | 30 | 0 | 0 | 0 |
 | firstleg | 74 | 0 | 0 | 0 |
 | warehouse | 68 | 0 | 0 | 0 |
 | file | 23 | 0 | 0 | 0 |
 | integration-service | 8 | 0 | 0 | 0 |
 | **合计** | **312** | **0** | **0** | **0** |
 重点自动化覆盖：
 - 统一响应、异常映射、Long ID 字符串序列化和权限认证。
 - 测量草稿、OCR 修正/确认、提交及乐观锁。
 - 测量提交时托盘拆分、库位预占/确认、失败回滚、幂等重试。
 - 客服驳回、通过后自动计费/发布/入库、中断续跑。
 - FBA 计费规则选择、已发布费用调整和状态不回退。
 - 客户只见本客户已发布费用，平台/商户身份及跨客户隔离。
 - 第三方签名、防重放、事件幂等、仓库范围及不越权推进状态。
 - 第三方一条箱规对应一条订单货物明细和一张图片、重复绑定拦截、图片补偿清理。
 - 库位/托盘主数据约束、A0 共享溢出及活动占用唯一性契约。
 - 图片上传类型、大小、真实图片校验、下载三字段隔离和 OCR 聚合。
 - Gateway 路由以及 OpenAPI、Application、Nacos YAML 解析。
 测试日志中的模拟数据库不可用、文件写入失败等异常堆栈，是异常映射测试主动构造的场景；对应测试均通过，不是构建失败。
 ## 十六、尚需在线环境验证与当前遗留
 本次回归没有启动服务、没有占用 `9000/9100/920x` 默认端口，也没有连接或修改 MySQL。以下内容必须在测试环境由后端与前端共同验证后，才能判定上线验收通过：
 1. 入库测量与计费 SQL 在真实 MySQL 的建表/迁移执行，以及历史数据与唯一约束冲突检查。
 2. Gateway、Nacos、Redis、MySQL、服务间令牌和各微服务的真实 HTTP 联通。
 3. OCR 引擎对现场秤图的识别准确率、超时和失败重试。
 4. 并发提交、并发抢托盘/库位、A0 多托盘共享在真实数据库事务下的压力验证。
 5. 浏览器端完整登录、刷新 Token、权限按钮、403、跨客户拒绝、空态、加载态和重复提交体验。
 6. 当前托盘管理没有独立启停和状态筛选接口；页面只做查询、新增、编辑、删除。
 上述内容是本报告初版时的阶段结论。2026-08-04 已继续完成真实数据库迁移和隔离端口在线 HTTP 回归，最终结论以第十七章为准。
 ## 十七、最终在线回归结果（任务 019fc6f9）
 ### 17.1 验收结论
 2026-08-04 已连接本地测试 MySQL，并使用独立 Nacos 分组和隔离端口完成真实 API 全链路回归。下单、订单审核生成入库单、测量草稿、图片绑定、称重图片、OCR 失败人工修正、重量确认、托盘库位占用、测量审核、FBA 自动计费、费用发送和入库完成全部通过。
 最终状态：
 | 项目 | 结果 |
 |---|---|
 | 订单 ID | `2084549604719718402` |
 | 入库单 ID | `2084549769916538881` |
 | 入仓码 | `RK-2084549604719718402` |
 | 测量批次 | `2084556854154715137` |
 | 入库状态 | `INBOUNDED` |
 | 测量审核状态 | `APPROVED` |
 | 费用状态 | `SENT` |
 | 费用单号 | `FBAF-2084549769916538881-1` |
 | 实重 / 体积 | `20kg` / `0.24m³` |
 | 体积重 / 计费量 | `40.08kg` / `40.08kg` |
 | 最终费用 | `440.68 CNY` |
 | 托盘 | `2084561214309851137` |
 | 库位 | `2084561214452457473` |
 | 库位预占单 | `LR2084562525306675202` |
 | 分配状态 | `CONFIRMED` |
 ### 17.2 环境与自动化结果
 - Nacos 隔离组：`BAIYUE_PHASE2_E2E_20260804`。
 - 隔离端口：`19100`、`19201`、`19202`、`19204`、`19205`、`19206`、`19207`，未占用默认 `9000/9100/920x` 端口。
 - 7 个隔离服务健康检查均为 `UP`。
 - Firstleg 自动化测试 77 项通过。
 - Warehouse 自动化测试 68 项通过。
 - 公共仓储技术归属专项（历史测试名含“资源租户”）3 项通过。
 ### 17.3 前端需要采用的最终契约
 - 入库详情已经返回 `version`，测量审核、驳回等乐观锁请求必须使用服务端最新版本。
 - Long 类型 ID 继续按字符串处理。
 - 客服审核通过后由后端自动完成计费、费用发送和入库，前端成功后刷新详情与最新费用，不串行调用补偿接口。
 - 平台操作公共收货仓时，订单客户归属与公共主数据技术归属由后端分别校验，前端不自行改写技术归属字段。
 - OCR 未配置时会返回明确失败状态，页面必须允许人工修正识别重量并确认，不能把 OCR 失败等同于整条业务失败。
 ### 17.4 本轮修复
 1. 补齐 `fl_inbound_weight_result.created_by`、`updated_by`，修复称重结果登记 SQL 失败。
 2. 增加历史兼容配置 `firstleg.inbound.warehouse-resource-tenant-id`，支持商户订单使用公共主数据技术归属下的仓库、托盘和库位；2026-08-04 本轮曾使用 `10001` 验证，但该样本已失效，现行公共资源归属必须为平台技术作用域 `0`。
 3. 仓储确认结果回传并保留 `reservationNo`，避免分配快照写入空预占单号。
 4. 入库详情 `InboundOrderSummary` 增加 `version`。
 5. `fl_inbound_pallet_allocation` 增加 `warehouse_resource_tenant_id`，保留历史资源归属快照。
 ### 17.5 当前边界
 - 本轮已验证 OCR 不可用时的人工修正降级闭环；未验证真实 OCR 供应商对现场秤图的准确率、时延和失败重试。
 - 浏览器端视觉、移动端适配和真实用户操作体验仍由前端按本报告接口完成联调验收。
 - 数据库唯一增量入口：`D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql`。后续变更只追加到该文件，历史日期脚本不再作为部署入口。
 最终结论：**入库测量与计费核心正常主链路已经完成真实 MySQL、真实 HTTP 和自动化回归，后端达到前端联调条件；真实 OCR 供应商识别和浏览器端体验属于后续环境验收项。**
@@ -0,0 +1,237 @@
 # 入库测量与计费前端页面清单与多对话并行任务表
 > 盘点日期：2026-08-05  
 > 适用项目：`apps/admin-web/`、`apps/client-web/`  
 > 后端范围：只读核对 `baiyue-firstleg/`，本任务不修改后端  
 > 当前基线：以后端现有 Controller、DTO、权限和状态机为可联调事实；V2 待确认项不擅自补成前端规则
 > 主体模型：前端只呈现“平台—客户”两级；接口 `tenantId` 当前表示客户 ID。任务中的“租户切换”统一理解为客户切换，不新增租户选择器或租户级权限。
 本轮不存在“等待后端提供接口文档”的前置任务。每个前端对话直接只读当前工作区 `baiyue-firstleg/` 中的 Controller、DTO、Service、Repository、OpenAPI 和权限 SQL；发现契约问题只登记，不修改后端。
 ## 一、结论
 入库测量与计费前端应围绕已经落地的“入库测量、OCR、测量审核、FBA 计费、托盘库位、客户只读结果”建设，不继续沿用旧 24 项计划直接开工。
 - Admin 新增 6 个正式菜单页面：入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理、海外仓阶梯费用。
 - 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史，不再新增独立“接收审核”页面。
 - 正常流程在“测量审核通过”后直接进入 `WAIT_SPLIT`；后端可尽力生成初算费用，但价格缺失或初算失败不得阻塞主流程。平台人员可独立修改计费量、单价和附加费，金额由服务端重算。
 - Client 不新增独立入库菜单或列表，只在现有头程订单详情中增加“入库与费用”只读区。
 - 到仓预报、预约、签到、分批收货、标签、冲正、差异通知、上架任务、位置历史和通用费用项目当前没有匹配的公开后端接口，暂不拆前端实现任务。
 ## 二、事实来源和冲突处理
 当前 V2 确认清单的 C1-C8、T1-T3 仍是待确认状态，但后端已经形成一套更收敛的可联调实现。因此本轮按以下顺序执行：
 1. 用户本轮要求：只整理和开发前端，不修改后端，可以直接只读后端代码。
 2. 后端真实 Controller、DTO、权限 SQL、状态枚举和服务编排。
 3. `入库测量与计费需求优化版-v2-测量计费入库主流程.md` 的范围边界。
 4. Admin 原型仅用于布局、字段和交互参考，不补造后端没有的业务能力。
 已确认的实现差异：
 | 主题 | 旧规划或 V2 描述 | 当前后端事实 | 前端处理 |
 |---|---|---|---|
 | 正常入库动作 | 人工试算、确认、发送费用后入库 | 测量审核通过后直接进入待分柜，费用仅作独立初算和人工维护 | 审核成功后刷新详情；初算失败展示非阻断提示，不影响待分柜操作 |
 | 托盘库位 | 操作员选择托盘和候选库位 | 测量提交/审核编排自动准备和占用，平台无人工分配公开接口 | 详情只读展示分配结果 |
 | 接收审核 | 独立页面 | 无独立节点 | 不建设；相关结果并入详情和审核区 |
 | Client 到仓预报 | 规划中存在 | 无商户公开接口 | 不建设 |
 | 通用费用项目 | V2 C6 白名单待确认 | 无独立费用项目 Controller | 不建设费用项目页 |
 | 入库列表路径 | V2 示例使用 `/api/platform/inbounds` | Controller 确实无 `v1`，其他入库接口多为 `/api/platform/v1/...` | API 封装保留真实多前缀，不自行统一 |
 | 海外仓阶梯费用 | 旧文档排除全部阶梯价 | Warehouse 已提供客户级天数阶梯费用基础资料 CRUD | 新增平台端维护页；当前不接入自动计费 |
 ## 三、Admin 页面和变更清单
 ### 3.1 正式菜单页面
 | 页面 | 建议路由 | 主要内容 | 主要权限 | 优先级 |
 |---|---|---|---|---|
 | 入库单 | `/inbounds` | 企业选择、四个后端页签、多条件筛选、服务端分页、详情入口 | `platform:firstleg:inbound:list` | P0 |
 | 入库详情 | `/inbounds/:inboundId` | 概览、运输快照、内部备注、文件、状态历史、测量、审核、费用、托盘库位 | `platform:firstleg:inbound:view` 及各操作权限 | P0 |
 | 客户计费规则 | `/first-leg-pricing/customer-rules` | 规则查询、详情、新版本、停用；KG/CBM、换算系数、舍入和有效期 | `firstleg:fba-pricing:rule:view/edit` | P0 |
 | 船司 FBA 价格 | `/first-leg-pricing/carrier-rates` | 价格查询、详情、新版本、停用；起运仓、渠道、船司、FBA 仓、单价和附加费 | `firstleg:fba-pricing:rate:view/edit` | P0 |
 | 库位管理 | `/master-data/locations` | 企业和仓库联动、筛选、分页、新增、编辑、启停、删除、可用库位状态 | `platform:location:*` | P0 |
 | 托盘管理 | `/master-data/pallets` | 企业和仓库联动、筛选、分页、新增、编辑、删除 | `platform:pallet:*` | P0 |
 | 海外仓阶梯费用 | `/customers/overseas-storage-fees` | 按客户分页查询，维护币种、连续天数区间和仓储费单价，支持乐观锁编辑与删除 | `platform:overseas-storage-fee:*` | P1 |
 所有业务表格的“操作”列放在第一列，并检查窄屏退化。
 ### 3.2 入库详情内部功能
 入库详情建议作为一个路由页，以页签或分区承载以下能力，不为每一步增加侧边栏菜单：
 | 分区 | 能力 | 交互边界 |
 |---|---|---|
 | 概览与历史 | 入仓码、订单/客户/仓库快照、申报与实测汇总、文件、内部备注、状态历史 | 切换企业后清空全部上下文 |
 | 测量与 OCR | 第三方箱规、测量草稿、称重图片上传/预览/OCR 重试、OCR 原值、置信度、人工修正、确认、提交审核 | 汇总重量和体积以服务端结果为准；不覆盖 OCR 原值 |
 | 测量审核 | 原单、第三方测量、OCR 三组数据对比；通过、驳回、审核历史、异常放行 | 通过/驳回/放行携带幂等键；放行必须有专属权限和原因 |
 | 费用快照 | 最新费用、规则版本、价格版本、实际量、折算量、计费量、单价、附加费、总额、发送状态 | 正常流程只读；已发布费用可按权限调整且必须填写原因 |
 | 托盘库位 | 托盘号、分配体积/箱数、库位编码和占用结果 | 只读，不让前端拼托盘号、选择或占用库位 |
 ### 3.3 全局装配变更
 - `src/app/router/index.ts`：装配入库测量与计费模块路由。
 - `src/core/navigation/adminNavigation.ts`：在“国内仓”下增加入库单、库位、托盘；新增“头程计费”分组；在客户或海外仓基础资料分组增加“海外仓阶梯费用”。
 - 路由和导航测试同步更新。
 - IAM 权限页面无需业务改造；后端返回入库测量与计费权限资源后沿用现有展示和授权能力。
 - 不恢复“接收审核”“费用项目”“完整财务管理”等原型菜单。
 ## 四、Client 页面变更清单
 Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增“入库与费用”只读区，不改路由、导航或模块注册。
 展示内容：
 - 入库结果：入仓码、入库状态、完成时间、平台收货仓。
 - 实测汇总：实际箱数、实重、净重、实测体积、材积重、计费重量/体积。
 - 托盘库位：托盘数、托盘号、分配体积、箱数和库位编码。
 - 费用结果：计费模式、换算系数、实际量、折算量、最终计费量、单价、小计、附加费、总额、币种、规则/价格版本和发送时间。
 - 只展示公开备注；不展示内部备注、原始操作历史、内部原因和操作人 ID。
 状态处理：
 - 草稿订单不请求入库费用接口，显示“订单提交后可查看入库结果”。
 - 后端业务码 `A0404` 作为中性待处理态，显示“入库及费用结果尚未发布”。
 - 其他失败只影响此区块，保留订单详情并提供区块级重试。
 - 快速切换订单时使用请求序号或 `orderId` 校验，旧响应不得覆盖新订单。
 - 不增加客户确认、调整、审核、发送费用或照片下载动作。
 ## 五、真实接口域
 前端实现直接读取相邻 Controller/DTO，不需要另行准备后端接口文档。首批任务按以下接口域联调：
 | 接口域 | Controller 入口 | 前端用途 |
 |---|---|---|
 | 入库查询 | `firstleg/.../PlatformInboundOrderController.java` | Admin 入库列表和聚合详情 |
 | 测量/OCR | `firstleg/.../PlatformInboundMeasurementController.java` | 测量草稿、提交、OCR 登记/修正/确认 |
 | 测量审核 | `firstleg/.../PlatformInboundMeasurementReviewController.java` | 通过、驳回、异常放行、审核历史 |
 | FBA 基础资料 | `firstleg/.../PlatformFbaMasterDataController.java` | 客户规则和船司价格版本维护 |
 | FBA 费用 | `firstleg/.../PlatformFbaPricingController.java` | 最新费用、异常恢复接口、已发布费用调整 |
 | 称重图片 | `file/.../PlatformMeasurementImageController.java` | 上传、OCR 重试和鉴权查看 |
 | 托盘 | `warehouse/.../PlatformPalletController.java` | 托盘 CRUD |
 | 库位 | `warehouse/.../PlatformLocationController.java` | 库位 CRUD、状态和可用库位查询 |
 | 海外仓阶梯费用 | `warehouse/.../PlatformOverseasStorageFeeController.java` | 平台端客户级天数阶梯仓储费 CRUD |
 | 商户结果 | `firstleg/.../MerchantInboundBillingController.java` | Client 订单入库与费用只读展示 |
 共同约定：
 - 浏览器代码使用现有 `/api` 基地址，不硬编码 Gateway 地址。
 - 普通业务 HTTP 200 后仍需判断响应体 `code === "200"`。
 - Java Long 在 JSON 中按字符串处理，前端不得转为 `Number`。
 - Admin 当前接口显式需要代表目标客户的 `tenantId`；切换企业必须清空仓库、详情、编辑、上传和幂等上下文。
 - 409 表示版本或并发冲突，页面应刷新最新详情，不静默覆盖。
 - 审核通过、驳回、异常放行和费用写操作按 Controller 要求携带 `Idempotency-Key`。
 ## 六、多对话并行任务表
 ### 6.0 实施状态（2026-08-04）
 - `P2-ADM-01` 至 `P2-ADM-11`、`P2-CLI-01`、`P2-QA-01`、`P2-QA-02` 均已完成。
 - 新增 `P2-ADM-12` 海外仓阶梯费用前端任务：后端接口、权限和 SQL 已完成，前端页面待实现与联调。
 - Admin 已通过 `pnpm test`（58 个文件、262 个测试）、`pnpm typecheck` 和 `pnpm build`。
 - Client 已通过 `pnpm test`（135 个测试）、`pnpm typecheck` 和 `pnpm build`。
 - Admin 入库测量与计费新增模块的 Impeccable detector 结果为 `[]`，模块依赖边界测试已通过。
 - Admin 入库测量与计费页面已再次按平台后台原型校正搜索条件、表格字段、字段顺序和详情分区；视觉组件统一复用现有 `QueryToolbar`、`DataTable`、`AppDrawer` 及状态组件。
 - 原型字段只在当前后端 Controller/DTO 支持时落地；未恢复接收审核、客户确认、报关、智能装柜、托盘状态/启停、尺寸/承重及无接口的导入导出。
 - Client 入库费用区沿用既有订单详情视觉，补充换算系数、舍入精度和规则/价格版本，保持只读并继续使用“入仓码”业务术语。
 - 本轮未修改 `baiyue-firstleg/`；8.1 节的 Client 服务端响应数据暴露风险仍是上线阻断，不影响本轮前端任务完成状态。
 ### 6.1 任务定义
 下表中未写应用前缀的 Admin 路径均相对 `apps/admin-web/src/`。
 | ID | 对话任务 | 负责范围和文件所有权 | 交付与验收 | 依赖 | 波次 |
 |---|---|---|---|---|---|
 | `P2-ADM-01` | 入库列表与聚合查询 | 独占 `modules/inbounds/core/**`、`pages/InboundOrdersView.vue` 及测试 | 本域 types/API；企业选择、四页签、筛选、分页、操作列第一列、概览/历史只读组件、加载/空/错/权限态 | 只读入库查询 Controller/DTO | W1 |
 | `P2-ADM-02` | 测量草稿与箱规 | 独占 `modules/inbounds/measurement/**` 及测试 | 本域 types/API/组件；第三方箱规、测量草稿、保存、提交审核、版本冲突和未保存保护 | 只读测量 Controller/DTO | W1 |
 | `P2-ADM-03` | 称重图片与 OCR | 独占 `modules/inbounds/weight/**` 及测试 | 本域 types/API/组件；上传、预览、OCR 重试、原值/置信度、人工修正和确认 | 只读 File、测量 Controller/DTO | W1 |
 | `P2-ADM-04` | 测量审核 | 独占 `modules/inbounds/review/**` 及测试 | 本域 types/API/组件；三组数据对比、历史、通过、驳回、异常放行、幂等和权限 | 只读审核 Controller/DTO/Service | W1 |
 | `P2-ADM-05` | 入库费用快照 | 独占 `modules/inbounds/fee/**` 及测试 | 本域 types/API/组件；最新费用、完整计价过程、状态和已发布费用调整；不串常规 calculate/confirm/send | 只读 FBA 费用 Controller/DTO/Service | W1 |
 | `P2-ADM-06` | 客户计费规则 | 独占 `modules/fba-pricing/customer-rules/**` 及测试 | 查询、详情、新版本、停用、权限和未保存保护 | 只读 `PlatformFbaMasterDataController` 客户规则契约 | W1 |
 | `P2-ADM-07` | 船司 FBA 价格 | 独占 `modules/fba-pricing/carrier-rates/**` 及测试 | 查询、详情、新版本、停用、起运仓/渠道/船司/FBA 仓/价格和有效期 | 只读 `PlatformFbaMasterDataController` 价格契约 | W1 |
 | `P2-ADM-08` | 库位管理 | 独占 `modules/warehouse-resources/locations/**` 及测试 | 企业/仓库级联、筛选分页、CRUD、启停、乐观锁、状态限制、响应式 | 现有企业选择器和仓库 API | W1 |
 | `P2-ADM-09` | 托盘管理 | 独占 `modules/warehouse-resources/pallets/**` 及测试 | 企业/仓库级联、筛选分页、CRUD；不虚构状态或启停 | 现有企业选择器和仓库 API | W1 |
 | `P2-ADM-10` | 入库详情工作台组装 | 独占 `modules/inbounds/pages/InboundOrderDetailView.vue`、`components/InboundWorkflowWorkspace.vue` 及测试 | 将 ADM-01 至 ADM-05 组件组装为详情页；统一刷新、客户切换清理、操作成功回读和托盘库位只读结果 | ADM-01 至 ADM-05 | W2 |
 | `P2-ADM-11` | Admin 全局装配 | 独占各模块 `routes.ts`、`app/router/index.ts`、`core/navigation/adminNavigation.ts` 及对应测试 | 接入全部 Admin 页面、菜单和权限；首个可访问路由正确；不恢复接收审核/费用项目原型菜单 | ADM-06 至 ADM-10 | W3 |
 | `P2-ADM-12` | 海外仓阶梯费用 | 建议独占 `modules/overseas-storage-fees/**` 及测试；路由和菜单在集成时统一修改 | 分页、详情、新增、编辑、删除；客户唯一性、连续阶梯校验、乐观锁冲突、权限态和未保存保护 | `PlatformOverseasStorageFeeController` | W1 |
 | `P2-CLI-01` | 商户订单入库费用只读展示 | `apps/client-web/src/modules/first-leg/api/inboundBilling.ts`、`types/inboundBilling.ts`、`components/InboundBillingPanel.vue`、`views/FirstLegOrdersView.vue` 及测试 | 成功/待发布/失败/重试、快速切单、320/720/桌面；无写动作，不消费内部字段 | 只读 `MerchantInboundBillingController` 及 DTO/Service | W1 |
 | `P2-QA-01` | Admin 跨模块回归 | 以新增集成测试和联调记录为主，不重构业务实现 | 客户切换、401/403、业务码、409、幂等、重复提交、图片异常、空/加载/失败、权限按钮、窄屏；运行 test/typecheck/build | `P2-ADM-11` | W4 |
 | `P2-QA-02` | Client 安全与展示验收 | 只读审查和补测试，避免与 CLI-01 同时改订单页 | 不展示内部备注/历史；A0404 中性态；响应隔离；test/typecheck/build | `P2-CLI-01` | W2 |
 ### 6.2 推荐并行波次
 ```text
 W1（新增任务可独立开发）:
 ADM-01 + ADM-02 + ADM-03 + ADM-04 + ADM-05
 ADM-06 + ADM-07 + ADM-08 + ADM-09 + ADM-12 + CLI-01
                    ↓
 W2（2 个并行对话）: ADM-10 + QA-02
                    ↓
 W3（1 个集成对话）: ADM-11
                    ↓
 W4: QA-01 跨模块联调、构建和回归
 ```
 `ADM-12` 没有入库主链路依赖，可独立实现；完成后需要把其路由、菜单和权限态纳入 Admin 集成回归。原关键路径仍是 `ADM-01 至 ADM-05 → ADM-10 → ADM-11 → QA-01`。
 ### 6.3 多对话协作规则
 - 每个对话只修改任务表声明的文件边界；发现需要改公共文件时留给 `P2-ADM-11`。
 - `router/index.ts`、`adminNavigation.ts` 和对应测试只能由集成任务修改。
 - 库位和托盘任务不得各自创建或修改同一个 `warehouse-resources/routes.ts`。
 - 入库各业务域分别维护本域 `types.ts` 和 API，不创建共享巨型 DTO 文件；跨域只传 `tenantId: string`、`inboundId: string`、`readonly` 数据和 `changed` 事件。
 - `ADM-01` 至 `ADM-05` 不创建或修改 `InboundOrderDetailView.vue`；详情页面只由 `ADM-10` 组装。
 - `ADM-06`、`ADM-07` 不创建共同的 `fba-pricing/routes.ts`；路由只由 `ADM-11` 创建。
 - `ADM-12` 不修改入库或 FBA 自动计费模块；海外仓阶梯配置当前仅作为基础资料 CRUD。
 - Client 任务保持单对话实现，因为现有订单页超过一千行，拆成多个写任务会集中冲突。
 - 每个任务完成后运行直接相关的测试和 typecheck；最终集成任务再运行全项目测试和构建。
 - 后端契约疑问直接只读 Controller、DTO、Service、Repository/OpenAPI；本轮不得修改 `baiyue-firstleg/`。
 ## 七、当前后端源码未落地、暂不开发的范围
 | 能力 | 本轮处理 | 原因 |
 |---|---|---|
 | 到仓预报和线下预约结果 | 暂不开发 | 无商户/平台公开接口 |
 | 签到、分批收货、处理单元 | 暂不开发 | 无匹配 Controller |
 | 标签打印和换标 | 暂不开发 | Print 服务仍是骨架，无业务公开接口 |
 | 收货冲正 | 暂不开发 | 无匹配 Controller |
 | 申报实测差异通知 | 暂不开发 | 无匹配 Controller |
 | 上架任务和位置历史 | 暂不开发 | 当前只有托盘/库位和自动占用，无平台作业接口 |
 | 通用费用项目白名单 | 暂不开发 | C6 未确认且无独立 Controller |
 | 通知失败人工重试 | P1 候选 | 当前无明确平台公开接口 |
 | 入库后换位 | P1 候选 | 当前无平台公开接口 |
 | 测量视频、单票导出 | P1 候选 | 当前无明确契约 |
 | 客户照片查看 | 暂不开发 | 当前无商户文件下载接口 |
 ## 八、上线阻断和风险
 ### 8.1 Client 数据暴露风险（上线阻断）
 当前 `MerchantInboundBillingService` 直接返回平台侧 `InboundOrderDetail`，其中可能包含全部 `internalNotes` 和未按商户可见性过滤的 `files`。即使 Client 页面不渲染，这些字段仍会下发到浏览器。
 前端必须做到：
 - 商户 DTO 不声明、不读取、不渲染内部备注和原始内部历史。
 - 不记录或展示原始响应对象。
 但前端无法消除网络响应中的数据暴露，因此正式上线前仍需后端改为商户专用 DTO 或服务端字段过滤。该项不在本轮后端修改授权范围内，只登记为上线阻断。
 ### 8.2 需求和实现风险
 - V2 C1-C8 尚未正式确认；若产品推翻当前自动计费入库流程，需要重新评估页面动作和任务边界。
 - Admin 多个接口仍要求前端显式传目标 `tenantId`，与 V2“不相信前端 tenantId”的文字描述不同；前端按现有 Controller 调用，最终数据范围仍由服务端校验。
 - 正常审核通过会自动完成后续动作，属于高影响写操作；页面确认文案必须明确结果，并防止重复点击。
 - 计费规则和船司价格接口当前返回列表而非分页对象；页面不要先假设服务端分页。
 - 托盘接口没有状态和启停能力；库位才有 `AVAILABLE/RESERVED/OCCUPIED/DISABLED` 状态。
 - 海外仓阶梯费用当前没有启停、计费单位和生效日期字段；前端不得自行补造，也不得将该配置接入现有 FBA 自动计费。
 ## 九、每个任务的统一完成标准
 - 严格按真实权限控制路由、菜单和按钮；前端权限只控制展示，服务端继续最终授权。
 - 覆盖加载、空态、失败、无权限、业务冲突、重复操作和数据过期。
 - 所有业务表格操作列在第一列，桌面端可固定左侧；窄屏不依赖表格末端操作。
 - 所有 ID 保持字符串，金额、体积、重量和换算系数不硬编码、不自行推导为业务事实。
 - 写操作成功后刷新服务端状态；409 或版本冲突提示用户并重载，不静默覆盖。
 - Admin 运行 `pnpm test`、`pnpm typecheck`、`pnpm build`。
 - Client 运行 `pnpm test`、`pnpm typecheck`、`pnpm build`。
 - 不修改后端、不启动本地 Java/Nacos/数据库；联调默认通过测试 Gateway 的 `/api` 代理。
@@ -1,15 +1,17 @@
-# 虫虫出海二期开发规划：头程到仓与头程计费
+# 虫虫出海入库测量与计费开发规划：头程到仓与头程计费
 > 创建日期：2026-07-28  
 > 更新日期：2026-07-31  
 > 状态：开发已启动，3 项计费细节确认中  
 > 流程依据：[头程物流流程图](参考资料/头程物流流程图.svg)中的头程物流“02 到仓”  
 > 产品确认：[2026-07-31 产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)  
-> 前置阶段：[一期文档](../一期/README.md)
+> 前置阶段：[订单与客户文档](../订单与客户/README.md)
-## 一、二期目标
+> 主体模型：入库测量与计费只实现“平台—客户”两级。`tenant_id > 0` / `tenantId` 是客户 ID 兼容字段，`tenant_id=0` 是平台技术作用域；不得新增真实租户、租户选择器、租户级 RBAC 或重定义现有隔离字段。
-二期承接一期“客户下单并选择平台收货仓”的结果，完成货物从待到仓、实际收货、测量、差异记录到指定库位的作业闭环，并在实测数据之上完成头程费用计算。
+## 一、入库测量与计费目标
 入库测量与计费承接订单与客户“客户下单并选择平台收货仓”的结果，完成货物从待到仓、实际收货、测量、差异记录到指定库位的作业闭环，并在实测数据之上完成头程费用计算。
 ```text
 线下预约 / 送货预报
@@ -25,11 +27,11 @@
 头程费用试算与费用明细确认
 ```
-二期不建设应收应付、对账、收付款、核销、发票、利润或总账。完成标准是每票货能够回答：何时到仓、实际收到什么、实测结果是什么、与申报差多少、差异是否已通知、最终放在哪个库位，以及产生了哪些头程费用和计算依据。
+入库测量与计费不建设应收应付、对账、收付款、核销、发票、利润或总账。完成标准是每票货能够回答：何时到仓、实际收到什么、实测结果是什么、与申报差多少、差异是否已通知、最终放在哪个库位，以及产生了哪些头程费用和计算依据。
 ## 二、阶段边界
-### 纳入二期
+### 纳入入库测量与计费
 - 客户取货或送货预报，以及线下预约结果、改期和取消记录。
 - 平台收货仓到仓签到、分批收货、处理单元标签和收货冲正。
@@ -37,9 +39,9 @@
 - 申报数据与实测数据对比、差异记录、客户通知和审计。
 - 最小库位档案、上架任务、指定库位和位置历史。
 - 头程费用项目、计费规则版本、费用试算、人工费用、调整、确认和费用明细。
- 服务端权限、租户隔离、状态、幂等、并发、文件鉴权、审计和历史快照。
+- 服务端权限、基于兼容字段 `tenant_id` 的客户隔离、状态、幂等、并发、文件鉴权、审计和历史快照。
-### 明确不纳入二期
+### 明确不纳入入库测量与计费
 - 应收应付台账、客户/供应商对账、账单确认和争议。
 - 收款、付款、退款、核销、反核销、银行流水和在线支付。
@@ -47,7 +49,7 @@
 - 会计科目、会计凭证和总账。
 - 流程图头程“03 出仓”：智能排柜、订舱、拖车、PDA 拣货、装柜、报关和港务信息。
 - 完整 WMS：可用库存、库存成本、常规移库、盘点、冻结、拣货、复核和出库。
- PDA 硬件或厂商 SDK；二期使用后台或响应式作业页。
+- PDA 硬件或厂商 SDK；入库测量与计费使用后台或响应式作业页。
 - 独立隔离区、差异等待客户确认、无预报货物认领和待认领区。
 - 时间窗容量调度、自动服务商分配、地图、GPS 和外部承运商接口。
 - FBA/海外目的仓及尾程到港、到仓、出仓和签收流程。
@@ -64,11 +66,11 @@
 | P2-Q6 | 不考虑隔离区 | 不建设隔离库位、隔离上架和释放流程 |
 | P2-Q7 | 不做库位容量校验 | 仅校验库位启停、仓库归属和权限合法性 |
 | P2-Q8 | 称重、测量照片必传，大小不限制 | 产品不设业务大小上限；系统保留文件类型校验和可配置技术安全上限 |
-| P2-Q9 | PDA 暂缓 | 二期使用后台或响应式作业页 |
+| P2-Q9 | PDA 暂缓 | 入库测量与计费使用后台或响应式作业页 |
 | P2-Q10 | 不考虑无预报货物 | 不建设无预报认领和正式订单绑定流程 |
 | P2-Q11 | 永久保存 | 业务记录不自动删除；访问审计、备份和合规策略由运维补充 |
 | P2-Q12 | 佳博 1324D 热敏标签打印机 | 开发前实机核验纸张、连接、驱动和指令协议 |
-| P2-Q13 | 二期只做头程计费 | 费用结果不自动形成应收、应付、账单或收付款数据 |
+| P2-Q13 | 入库测量与计费只做头程计费 | 费用结果不自动形成应收、应付、账单或收付款数据 |
 ## 四、角色与数据边界
@@ -123,7 +125,7 @@
 ### 6. 库位与上架
 - 维护仓库、库区、库位编码、名称、状态和权限范围。
- 二期不做承重、箱数或体积容量校验，也不建设隔离区和待认领区。
+- 入库测量与计费不做承重、箱数或体积容量校验，也不建设隔离区和待认领区。
 - 上架任务关联收货批次、目标库位、执行人、状态和完成时间。
 - 上架完成后写入处理单元当前位置和历史位置，为后续出仓提供输入。
@@ -134,7 +136,7 @@
 - 头程订单、到仓实测或已确认业务事件触发费用试算，重复事件不得重复计费。
 - 支持自动费用、人工补录、调整、确认、作废、查询和导出。
 - 已确认费用不直接覆盖，变更通过调整记录留痕。
- 详细规则见 [二期头程计费模块规划](二期计费财务模块规划.md)。
+- 详细规则见 [入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md)。
 ## 六、状态模型
@@ -201,11 +203,11 @@
 - 创建取货或送货预报。
 - 查看预约结果、到仓时间线、实测、公开照片、差异通知和上架结果。
- 如二期客户端展示头程费用，只显示本企业公开费用，不显示内部备注和其他企业数据。
+- 如入库测量与计费客户端展示头程费用，只显示本企业公开费用，不显示内部备注和其他企业数据。
 ### 国内头程后端 `baiyue-firstleg/`
- 最终保证身份、租户、仓库数据范围、状态转换、幂等、并发和审计。
+- 最终保证身份、客户归属、仓库数据范围、状态转换、幂等、并发和审计。
 - 管理到仓单、收货批次、处理单元、标签、测量、差异通知、库位、上架、位置和冲正事务边界。
 - 管理计费规则版本、费用生成幂等、三位向上取整、费用调整和历史复算。
 - 文件访问使用不可预测标识和授权下载，不信任客户端文件名与 MIME 类型。
@@ -214,7 +216,7 @@
 | 里程碑 | 交付目标 | 进入条件 |
 |---|---|---|
-| P2-M0 规则锁定 | 到仓契约、测量口径、头程计费边界和权限基线确认 | 一期订单及基础资料契约稳定 |
+| P2-M0 规则锁定 | 到仓契约、测量口径、头程计费边界和权限基线确认 | 客户订单及基础资料契约稳定 |
 | P2-M1 到仓预报 | 取货/送货预报及线下预约结果可记录 | 收货仓 API 可用 |
 | P2-M2 到仓收货 | 签到、分批收货、标签、照片和冲正可追溯 | 文件服务和仓库权限可用 |
 | P2-M3 测量差异 | 原始测量、三位向上取整、差异记录和通知可用 | 测量公式可用 |
@@ -226,7 +228,7 @@
 | ID | 端 | 模块 | 交付内容 | 优先级 | 依赖 |
 |---|---|---|---|---|---|
-| P2-BASE-01 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 一期订单契约 |
+| P2-BASE-01 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 客户订单契约 |
 | P2-BASE-02 | 公共 | 数据模型 | 到仓单、批次、处理单元、标签、测量、差异、库位、位置、费用和审计 | P0 | P2-BASE-01 |
 | P2-ADM-01 | 后台 | 到仓列表 | 查询、筛选、分页、详情、空态和异常态 | P0 | P2-BASE-01 |
 | P2-ADM-02 | 后台 | 预约结果 | 记录、调整和取消线下预约结果 | P0 | P2-ADM-01 |
@@ -251,7 +253,7 @@
 | P2-TEST-01 | 公共 | 自动化测试 | 越权、幂等、测量舍入、计费复算、标签、差异、位置、文件和审计 | P0 | 所有 P0 模块 |
 | P2-REL-01 | 公共 | 发布验收 | 初始化仓库、库位、测量规则、标签和费用基础数据，联调、验收和发布 | P0 | P2-TEST-01 |
-二期开发任务共 24 项。应收应付、对账、账单中心、收付款核销、发票和利润六项任务已根据产品确认从二期移除。
+入库测量与计费开发任务共 24 项。应收应付、对账、账单中心、收付款核销、发票和利润六项任务已根据产品确认从入库测量与计费移除。
 ## 十一、测试与验收重点
@@ -276,7 +278,7 @@
 | P2-Q15 | 计费维度、阶梯价、最低收费、封顶、组合价和优先级 | 先支持客户、往来单位、仓库、服务和生效区间 |
 | P2-Q16 | 费用试算、生成、确认、调整和作废节点 | 实测完成试算，其他费用按已确认业务事件生成 |
-回传中的“63”不作为业务结论。P2-Q13 已确认仅做头程计费；P2-Q17 至 P2-Q24 不纳入二期。
+回传中的“63”不作为业务结论。P2-Q13 已确认仅做头程计费；P2-Q17 至 P2-Q24 不纳入入库测量与计费。
 ## 十三、建议实施顺序
@@ -287,5 +289,5 @@
 5. 实现库位、上架任务和位置历史，不建设隔离和容量校验。
 6. 确认 P2-Q14 至 Q16，建立头程费用项目和计费规则版本。
 7. 接入实测和业务事件，完成费用试算、人工补录、调整和费用明细。
-8. 完成租户隔离、幂等、计费复算、文件安全、审计和回归测试。
+8. 完成跨客户隔离、幂等、计费复算、文件安全、审计和回归测试。
 9. 使用脱敏初始化数据联调、验收和发布。
@@ -1,25 +1,34 @@
-# 虫虫出海二期开发进度表：到仓与头程计费
+# 虫虫出海入库测量与计费开发进度表：到仓与头程计费
 > 创建日期：2026-07-28  
 > 更新日期：2026-07-31  
 > 当前阶段：开发已启动，需求确认并行  
 > 总体状态：到仓规则和范围已确认，3 项计费细节待补充；实际开发进度待负责人回填
-二期严格以头程物流“02 到仓”和头程计费为范围。范围依据见 [二期开发规划](二期开发规划.md)，确认结论见 [二期需求确认清单](二期需求确认清单.md)。原型只用于页面、字段和流程参考，不自动扩大二期范围。
+入库测量与计费严格以头程物流“02 到仓”和头程计费为范围。范围依据见 [入库测量与计费开发规划](入库测量与计费开发规划.md)，确认结论见 [入库测量与计费需求确认清单](入库测量与计费需求确认清单.md)。原型只用于页面、字段和流程参考，不自动扩大入库测量与计费范围。
 ## 零、2026-08-05 增量状态
 | 任务 | 范围 | 后端 | 前端 | 验证 | 备注 |
 |---|---|---|---|---|---|
 | `P2-WH-OSF-01` | 海外仓客户级天数阶梯仓储费基础资料 CRUD | 已完成 | 不适用 | Warehouse 全量 91 项、CRUD 定向 6 项通过 | 复用 Warehouse 服务和数据库，不参与当前自动计费 |
 | `P2-ADM-12` | 海外仓阶梯费用平台端页面 | 接口、权限和 Gateway 路由已完成 | 待实现与联调 | 待前端 test、typecheck、build 和浏览器验收 | 契约见《海外仓阶梯费用前端联调说明-2026-08-05》 |
 数据库变更只追加到 `D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql`，不再创建日期增量脚本。
 ## 一、进度口径
 - 开发任务共 24 项；未收到具体完成量、负责人和日期前，不虚填开发进度。
- 需求问题共 24 项：已确认 12 项、暂缓 1 项、待确认 3 项、不纳入二期 8 项。
+- 需求问题共 24 项：已确认 12 项、暂缓 1 项、待确认 3 项、不纳入入库测量与计费 8 项。
 - 当前会议只需处理 P2-Q14、P2-Q15、P2-Q16。
- P2-Q9 暂缓，二期不接 PDA；P2-Q17 至 P2-Q24 不纳入二期。
+- P2-Q9 暂缓，入库测量与计费不接 PDA；P2-Q17 至 P2-Q24 不纳入入库测量与计费。
 - 应收应付、对账、收付款、核销、发票、汇率结算、利润和总账不进入任务、排期和验收。
 ## 二、总体进度
 | 工作流 | 范围 | 状态 | 开发进度 | 需求状态 | 负责人 | 备注 |
 |---|---|---|---:|---|---|---|
-| 规则与数据 | 到仓契约、数据模型、权限、文件和审计 | 待开始 | 0% | 到仓规则已确认 | 待分配 | 一期订单及基础资料契约是前置依赖 |
+| 规则与数据 | 到仓契约、数据模型、权限、文件和审计 | 待开始 | 0% | 到仓规则已确认 | 待分配 | 客户订单及基础资料契约是前置依赖 |
 | 到仓预报 | 取货/送货预报和线下预约结果记录 | 待开始 | 0% | Q2、Q3 已确认 | 待分配 | 不做容量调度和系统服务商分配 |
 | 到仓收货 | 签到、分批收货、标签、照片、异常和冲正 | 待开始 | 0% | Q1、Q8、Q10、Q12 已确认 | 待分配 | 不建设无预报认领流程 |
 | 测量差异 | 实测、三位向上取整、差异记录和客户通知 | 待开始 | 0% | Q4、Q5、Q6 已确认 | 待分配 | 差异无需客户确认，不阻塞上架或计费 |
@@ -31,7 +40,7 @@
 | ID | 里程碑 | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 原型覆盖 | 需求阻塞 | 依赖 | 负责人 | 计划开始 | 计划完成 | 备注 |
 |---|---|---|---|---|---|---|---:|---|---|---|---|---|---|---|
-| P2-BASE-01 | P2-M0 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 待开始 | 0% | 部分 | - | 一期订单契约 | 待分配 | 待排期 | 待排期 | 按已确认到仓规则建设 |
+| P2-BASE-01 | P2-M0 | 公共 | 到仓契约 | 状态、枚举、权限、事件、错误码和快照模型 | P0 | 待开始 | 0% | 部分 | - | 客户订单契约 | 待分配 | 待排期 | 待排期 | 按已确认到仓规则建设 |
 | P2-BASE-02 | P2-M0 | 公共 | 数据模型 | 到仓单、批次、处理单元、标签、测量、差异、库位、位置、费用和审计 | P0 | 待开始 | 0% | 部分 | - | P2-BASE-01 | 待分配 | 待排期 | 待排期 | 不包含后续财务对象 |
 | P2-ADM-01 | P2-M1 | 后台 | 到仓列表 | 查询、筛选、分页、详情、空态和异常态 | P0 | 待开始 | 0% | 较完整 | - | P2-BASE-01 | 待分配 | 待排期 | 待排期 | 后台原型可参考 |
 | P2-ADM-02 | P2-M1 | 后台 | 预约结果 | 记录、调整和取消线下预约结果 | P0 | 待开始 | 0% | 部分 | - | P2-ADM-01 | 待分配 | 待排期 | 待排期 | 不建设容量调度和自动分配 |
@@ -46,7 +55,7 @@
 | P2-HOLD-01 | P2-M3 | 公共 | 异常记录 | 非差异类异常、责任人、证据、处理结果和审计 | P1 | 待开始 | 0% | 部分 | - | P2-BASE-02 | 待分配 | 待排期 | 待排期 | 不建设隔离区或差异暂停 |
 | P2-LOC-01 | P2-M4 | 后台 | 库位维护 | 库区、库位编码、状态和权限范围 | P0 | 待开始 | 0% | 较完整 | - | P2-BASE-02 | 待分配 | 待排期 | 待排期 | 不做容量校验 |
 | P2-PUT-01 | P2-M4 | 后台 | 上架任务 | 创建、分配、拆分、异常和完成 | P0 | 待开始 | 0% | 较完整 | - | P2-LOC-01、P2-WH-02 | 待分配 | 待排期 | 待排期 | 不做隔离上架 |
-| P2-POS-01 | P2-M4 | 公共 | 位置记录 | 处理单元当前位置和进入/移出历史 | P0 | 待开始 | 0% | 部分 | - | P2-PUT-01 | 待分配 | 待排期 | 待排期 | 二期不建设完整库存系统 |
+| P2-POS-01 | P2-M4 | 公共 | 位置记录 | 处理单元当前位置和进入/移出历史 | P0 | 待开始 | 0% | 部分 | - | P2-PUT-01 | 待分配 | 待排期 | 待排期 | 入库测量与计费不建设完整库存系统 |
 | P2-SEC-01 | P2-M0 | 公共 | 文件与保留 | 文件鉴权、类型/安全校验、访问审计、永久保存和备份边界 | P0 | 待开始 | 0% | 无 | - | P2-WH-01 | 待分配 | 待排期 | 待排期 | 产品不设业务大小上限 |
 | P2-TIME-01 | P2-M6 | 公共 | 时间线通知 | 对客事件、差异通知和失败补偿记录 | P1 | 待开始 | 0% | 部分 | - | 核心流程完成 | 待分配 | 待排期 | 待排期 | 外部通知渠道另行配置 |
 | P2-FEE-01 | P2-M5 | 后台 | 费用项目 | 头程费用项目、单位、币种、税务属性和启停 | P0 | 需求确认中 | 0% | 较完整 | Q14 | P2-BASE-01 | 待分配 | 待排期 | 待排期 | 仅头程费用白名单 |
@@ -60,7 +69,7 @@
 | 里程碑 | 交付目标 | 状态 | 开发进度 | 进入条件 | 计划完成 |
 |---|---|---|---:|---|---|
-| P2-M0 规则锁定 | 到仓契约、数据关系、权限和文件基线 | 待开始 | 0% | 一期订单及基础资料契约稳定 | 待排期 |
+| P2-M0 规则锁定 | 到仓契约、数据关系、权限和文件基线 | 待开始 | 0% | 客户订单及基础资料契约稳定 | 待排期 |
 | P2-M1 到仓预报 | 取货/送货预报和线下预约结果可记录 | 待开始 | 0% | 收货仓 API 可用 | 待排期 |
 | P2-M2 到仓收货 | 签到、分批收货、标签、照片和冲正可追溯 | 待开始 | 0% | 文件服务、仓库权限及标签设备可用 | 待排期 |
 | P2-M3 测量差异 | 原始测量、三位向上取整、差异记录和通知可用 | 待开始 | 0% | 测量规则可用 | 待排期 |
@@ -70,7 +79,7 @@
 ## 五、原型映射与范围边界
-| 流程/能力 | 原型覆盖 | 二期任务 | 二期处理 |
+| 流程/能力 | 原型覆盖 | 入库测量与计费任务 | 入库测量与计费处理 |
 |---|---|---|---|
 | 取货/送货预报 | 部分 | P2-ADM-02、P2-CLI-01 | 记录线下预约结果，不做容量调度 |
 | 到仓收货 | 部分 | P2-WH-01、P2-REV-01 | 分批收货和冲正；不建设无预报认领 |
@@ -79,19 +88,19 @@
 | 指定库位 | 较完整 | P2-LOC-01、P2-PUT-01、P2-POS-01 | 不做容量校验和隔离区 |
 | 标签打印 | 部分 | P2-LABEL-01 | 使用佳博 1324D 实机适配 |
 | 头程费用 | 部分 | P2-FEE-01、P2-RATE-01、P2-CALC-01、P2-FEE-02 | 只做费用项目、规则、试算、调整和明细 |
-| 应收应付、对账、收付款、核销 | 原型存在 | - | 不纳入二期 |
+| 应收应付、对账、收付款、核销 | 原型存在 | - | 不纳入入库测量与计费 |
-| 发票、汇率结算、利润和财务报表 | 原型存在 | - | 不纳入二期 |
+| 发票、汇率结算、利润和财务报表 | 原型存在 | - | 不纳入入库测量与计费 |
-| PDA | 有“03 出仓”原型 | - | Q9 暂缓，二期不接 PDA |
+| PDA | 有“03 出仓”原型 | - | Q9 暂缓，入库测量与计费不接 PDA |
-| 完整库存/WMS | 原型存在 | - | 二期只维护处理单元位置记录 |
+| 完整库存/WMS | 原型存在 | - | 入库测量与计费只维护处理单元位置记录 |
 ## 六、需求确认进度
 | 状态 | 数量 | 编号 | 说明 |
 |---|---:|---|---|
 | 已确认 | 12 | Q1-Q8、Q10-Q13 | 到仓规则和“仅头程计费”已进入基线 |
-| 暂缓 | 1 | Q9 | 二期不接 PDA |
+| 暂缓 | 1 | Q9 | 入库测量与计费不接 PDA |
 | 待确认 | 3 | Q14-Q16 | 费用白名单、计费复杂度、费用生成节点 |
-| 不纳入二期 | 8 | Q17-Q24 | 后续财务与结算能力 |
+| 不纳入入库测量与计费 | 8 | Q17-Q24 | 后续财务与结算能力 |
 ## 七、测试与验收重点
@@ -112,4 +121,4 @@
 - 原型覆盖统一使用：较完整、部分、无、不适用；原型覆盖不得换算为开发进度。
 - 负责人、计划开始和计划完成由排期会议填写；未获得实际数据时保持“待分配/待排期”。
 - 开始编码后才能填写大于 0% 的开发进度；开发、测试和验收完成后才能标记“已完成”。
- 需求结论先回写 [二期需求确认清单](二期需求确认清单.md)，再同步本表、开发规划、任务依赖和验收标准。
+- 需求结论先回写 [入库测量与计费需求确认清单](入库测量与计费需求确认清单.md)，再同步本表、开发规划、任务依赖和验收标准。
@@ -1,15 +1,15 @@
-# 虫虫出海二期头程计费模块规划
+# 虫虫出海入库测量与计费头程计费模块规划
-> 创建日期：2026-07-28  
+> 创建日期：2026-07-28
-> 更新日期：2026-07-31  
+> 更新日期：2026-07-31
-> 状态：产品已确认范围，计费规则细节确认中  
+> 状态：产品已确认范围，计费规则细节确认中
-> 历史文件名保留：`二期计费财务模块规划.md`  
+> 历史文件名保留：`入库测量与计费计费财务模块规划.md`
-> 关联规划：[二期开发规划](二期开发规划.md)  
+> 关联规划：[入库测量与计费开发规划](入库测量与计费开发规划.md)
-> 产品确认记录：[2026-07-31 二期产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
+> 产品确认记录：[2026-07-31 入库测量与计费产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
 ## 一、产品确认的范围结论
-二期只做头程业务的费用计算，不建设后续财务闭环。计费结果是头程订单的业务费用明细，不自动形成应收、应付、账单、付款、核销、发票或利润数据。
+入库测量与计费只做头程业务的费用计算，不建设后续财务闭环。计费结果是头程订单的业务费用明细，不自动形成应收、应付、账单、付款、核销、发票或利润数据。
 ```text
 头程订单 / 到仓实测 / 业务事件
@@ -23,7 +23,7 @@
 头程费用明细确认
 ```
-## 二、二期纳入范围
+## 二、入库测量与计费纳入范围
 ### 1. 头程费用项目
@@ -63,7 +63,7 @@
 费用项目、规则发布、试算、人工补录、调整、确认、作废和导出均需记录审计日志。
-## 三、二期明确不纳入
+## 三、入库测量与计费明确不纳入
 - 应收、应付台账及账龄。
 - 客户或供应商对账单、结算周期、账单确认和争议处理。
@@ -73,7 +73,7 @@
 - 在线支付、银企直连、银行流水自动认领。
 - 会计科目、会计凭证、总账和法定财务报表。
-原型中的上述页面仅作为后续阶段参考，不进入二期任务、排期或验收。
+原型中的上述页面仅作为后续阶段参考，不进入入库测量与计费任务、排期或验收。
 ## 四、核心数据对象
@@ -104,7 +104,7 @@
 | P2-Q15 | 计费规则维度，以及是否支持阶梯价、最低收费、封顶、组合价和冲突优先级 | 回传中的“63”无业务含义，未合并 |
 | P2-Q16 | 各类费用在哪个节点试算、生成、确认和作废，人工费用何时生效 | 回传中的“63”无业务含义，未合并 |
-P2-Q13 已确认：二期只做到头程费用计算。P2-Q17 至 P2-Q24 对应的应收应付、对账、收付款、发票、汇率结算和利润能力不适用于二期。
+P2-Q13 已确认：入库测量与计费只做到头程费用计算。P2-Q17 至 P2-Q24 对应的应收应付、对账、收付款、发票、汇率结算和利润能力不适用于入库测量与计费。
 ## 七、验收重点
@@ -1,15 +1,15 @@
-# 二期头程计费需求确认表
+# 入库测量与计费头程计费需求确认表
-> 更新日期：2026-07-31  
+> 更新日期：2026-07-31
-> 状态：产品已确认二期只做头程计费，当前仅剩 3 项计费细节待确认  
+> 状态：产品已确认入库测量与计费只做头程计费，当前仅剩 3 项计费细节待确认
-> 历史文件名保留：`二期计费财务需求确认表.md`  
+> 历史文件名保留：`入库测量与计费计费财务需求确认表.md`
-> 关联文档：[二期头程计费模块规划](二期计费财务模块规划.md)、[产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
+> 关联文档：[入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md)、[产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
 ## 一、已确认的范围
-| 编号 | 产品结论 | 二期开发口径 | 状态 |
+| 编号 | 产品结论 | 入库测量与计费开发口径 | 状态 |
 |---|---|---|---|
-| P2-Q13 | 二期只做头程计费 | 建设头程费用项目、计费规则、费用试算、人工补录、调整、确认、作废和费用明细 | 已确认 |
+| P2-Q13 | 入库测量与计费只做头程计费 | 建设头程费用项目、计费规则、费用试算、人工补录、调整、确认、作废和费用明细 | 已确认 |
 头程费用结果不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账数据。
@@ -29,24 +29,24 @@
 |---|---|---|---|---|---|---|---|---|
 | 待填写 | 待填写 | 待填写 | 待填写 | CNY | 待填写 | 待填写 | 待填写 | 待填写 |
-## 三、明确不纳入二期
+## 三、明确不纳入入库测量与计费
-| 编号 | 主题 | 二期处理 |
+| 编号 | 主题 | 入库测量与计费处理 |
 |---|---|---|
-| P2-Q17 | 汇率结算和本位币折算 | 不纳入二期 |
+| P2-Q17 | 汇率结算和本位币折算 | 不纳入入库测量与计费 |
-| P2-Q18 | 财务税务结算口径 | 不纳入二期；费用项目如需税率字段，按 Q14 配置 |
+| P2-Q18 | 财务税务结算口径 | 不纳入入库测量与计费；费用项目如需税率字段，按 Q14 配置 |
-| P2-Q19 | 财务费用审批、应收应付审批 | 不纳入二期；仅保留头程费用调整审计 |
+| P2-Q19 | 财务费用审批、应收应付审批 | 不纳入入库测量与计费；仅保留头程费用调整审计 |
-| P2-Q20 | 客户/供应商对账和结算周期 | 不纳入二期 |
+| P2-Q20 | 客户/供应商对账和结算周期 | 不纳入入库测量与计费 |
-| P2-Q21 | 账单确认、争议和关闭 | 不纳入二期 |
+| P2-Q21 | 账单确认、争议和关闭 | 不纳入入库测量与计费 |
-| P2-Q22 | 收付款、核销、反核销和银行流水 | 不纳入二期 |
+| P2-Q22 | 收付款、核销、反核销和银行流水 | 不纳入入库测量与计费 |
-| P2-Q23 | 发票登记和外部开票平台 | 不纳入二期 |
+| P2-Q23 | 发票登记和外部开票平台 | 不纳入入库测量与计费 |
-| P2-Q24 | 利润、利润率和财务报表 | 不纳入二期 |
+| P2-Q24 | 利润、利润率和财务报表 | 不纳入入库测量与计费 |
 ## 四、会议填写规则
 - 认可当前建议：将建议复制到“最终结论”，状态改为“已确认”。
 - 修改当前建议：填写会议确定的可开发口径，状态改为“已确认”。
- 暂时无法确定：状态改为“暂缓”，并写清二期临时处理方式。
+- 暂时无法确定：状态改为“暂缓”，并写清入库测量与计费临时处理方式。
 - 不需要填写确认人和确认时间。
 - 确认后保留本次会议文件，不覆盖产品原始回传；新一轮确认使用新版本文件名。
@@ -0,0 +1,122 @@
 # 入库测量与计费费用项目数据归属决策记录
 > 形成日期：2026-08-10  
 > 状态：已确认  
 > 决策范围：`费用类型.xls` 中 110 条费用类型的数据归属、初始化和存量迁移  
 > 关联确认项：[入库测量与计费 V2 需求确认清单](入库测量与计费V2需求确认清单.md) C6、[入库测量与计费头程计费需求确认表](入库测量与计费计费财务需求确认表.md) P2-Q14
 ## 一、最终结论
 - 费用项目是平台公共主数据，`fl_fee_item.tenant_id` 固定为 `0`，全平台使用同一套费用编码和项目定义。
 - 客户费用明细仍是客户隔离数据，`fl_inbound_fee_detail.tenant_id > 0`；其 `fee_item_id` 直接引用 `tenant_id = 0` 的公共费用项目。
 - 不再按客户复制费用项目，不建立“客户 ID + 模板版本”的初始化副本，也不允许用客户级费用项目承接公共定义。
 - `tenant_id = 0` 只是平台技术作用域，不增加用户可见的租户层级、租户选择器或租户级运营流程。
 - 本结论只确定费用项目主数据归属。计费单位、币种、税率、自动/人工、触发节点、价格规则和结算范围仍按 C6/P2-Q14 单独确认；110 条公共项目处于 `ACTIVE` 不等于 110 条都自动参与入库测量与计费计费。
 ## 二、源文件核对
 受控源文件：`费用类型.xls`。
 | 核对项 | 结果 |
 |---|---|
 | SHA-256 | `395C9CA71816E79C7745E224E63CF79A4AB782140364F63C8374B396DF38CDB4` |
 | 工作表 | `费用类型` |
 | 数据范围 | 1 行表头 + 110 条数据，共 111 行、13 列 |
 | 国内/国际 | 国内 84 条、国际 26 条 |
 | 真实表头 | 分类、国内国际、费用类型名称、货柜应付、货柜应收、仓储应付、仓储应收、平摊费用、说明、创建人、创建日期、更新人、更新日期 |
 | 源编码 | 源表没有费用编码列 |
 | 语义重复 | `国内国际 + 费用类型名称` 无重复 |
 源表不包含计费单位、币种、税率、价格、公式或触发节点，不能从费用名称推断这些配置。
 ## 三、初始化口径
 ### 3.1 稳定标识
 - 按受控源表数据行序生成固定编码 `FEE_TYPE_001` 至 `FEE_TYPE_110`。编码一经发布不得因排序、展示名称或分类调整重新生成。
 - 固定主键为 `193000000001000001` 至 `193000000001000110`，编码序号与主键末三位一一对应。
 - 110 条记录全部写入 `tenant_id = 0`、`status = ACTIVE`、`deleted = 0`。
 - `fee_code` 使用平台全局唯一索引，不再使用 `(tenant_id, fee_code)` 客户内唯一索引。
 - 财务自动计费另使用固定系统项目 `FBA_HEAD_FREIGHT`（`INTERNATIONAL`、仓储应收），它不属于 Excel 110 条受控种子；完整正式目录因此为 111 条。该系统项目由初始化 SQL 创建，业务请求不得运行期补建。
 ### 3.2 字段映射
 | Excel 字段 | 数据库字段 | 规则 |
 |---|---|---|
 | 分类 | `category` | 去除首尾空白，保留源值 |
 | 国内国际 | `trade_scope` | 国内映射 `DOMESTIC`，国际映射 `INTERNATIONAL` |
 | 费用类型名称 | `fee_type_name` | 去除首尾空白，保留业务名称 |
 | 货柜应付/货柜应收 | `pickup_payable` / `pickup_receivable` | “参与”映射 `1`，其他值映射 `0` |
 | 仓储应付/仓储应收 | `warehouse_payable` / `warehouse_receivable` | “参与”映射 `1`，其他值映射 `0` |
 | 平摊费用 | `allocation_fee` | “参与”映射 `1`，其他值映射 `0` |
 | 说明 | `description` | 空值写 `NULL`，非空保留源值 |
 | 创建人/创建日期 | `created_by`、`created_by_name`、`created_at` | 纯数字创建人可写入 ID；原文本始终保存在名称字段；日期按源日期零时刻写入 |
 | 更新人/更新日期 | `updated_by`、`updated_by_name`、`updated_at` | 有源值时保留；缺失时沿用创建信息，避免用迁移执行时间覆盖历史 |
 若目标固定主键或固定编码已有完全一致的公共记录，重复执行保持原记录及其历史字段不变；若已有记录状态、删除标记或业务语义不同，按冲突处理，不自动覆盖。
 ## 四、存量迁移
 迁移采用“先预检、后写入”的安全顺序，不对客户级费用项目直接执行批量 `UPDATE tenant_id = 0`。
 1. 建立 110 条临时种子并校验总数、国内/国际数量、固定编码和语义键唯一性。
 2. 预检固定主键占用、平台同码异义、平台同义异码、平台空编码和客户存量映射完整性。
 3. 客户级项目只在完整业务语义一致时允许映射。空编码和历史兼容编码 `MANUAL_<原ID>` 可按 `trade_scope + fee_type_name` 映射；其他异码、字段差异或无法匹配项均中止。
 4. 预检费用明细归属：明细必须属于客户；迁移前若明细引用客户级项目，该项目必须属于同一客户。任何跨客户引用均中止。
 5. 幂等插入缺失的公共费用项目，建立“旧客户项目 ID -> 固定公共项目 ID”临时映射。
 6. 先更新 `fl_inbound_fee_detail.fee_item_id`，再删除已完成映射的客户级主数据，保持外键始终有效。
 7. 将 `uk_fee_item_code` 重建为全局单列唯一索引，并将 `fee_code` 收紧为非空。
 冲突时脚本先返回冲突行再 `SIGNAL SQLSTATE '45000'`。结果集使用以下 `conflict_type`：
 - `FIXED_ID_CONFLICT`
 - `PUBLIC_CODE_CONFLICT`
 - `PUBLIC_SEMANTIC_CONFLICT`
 - `PUBLIC_EMPTY_CODE`
 - `UNMAPPED_CUSTOMER_ITEM`
 - `CUSTOMER_CODE_CONFLICT`
 - `CUSTOMER_SEMANTIC_CONFLICT`
 - `CROSS_CUSTOMER_DETAIL_REFERENCE`
 不得绕过冲突预检继续执行，也不得通过名称模糊匹配、临时改码或忽略历史引用来强行合并。冲突应先导出、由业务确认唯一映射，再调整受控迁移脚本。
 ## 五、幂等与强校验
 同一版本脚本重复执行必须满足：
 - 110 条固定 ID 和固定编码已存在时不重复插入，不覆盖可保留的创建、更新历史。
 - 不再存在 `tenant_id > 0` 的 `fl_fee_item`。
 - 110 条固定公共项目全部为 `tenant_id = 0`、`ACTIVE`、`deleted = 0`。
 - 系统项目 `FBA_HEAD_FREIGHT` 唯一存在且为 `tenant_id = 0`、`ACTIVE`、`deleted = 0`，正式目录合计 111 条（国内 84、国际 27）。
 - `uk_fee_item_code` 恰好是 `fee_code` 单列全局唯一索引，`fee_code` 非空。
 - 所有费用明细 `tenant_id > 0`，且引用的费用项目 `tenant_id = 0`。
 - 固定编码、固定主键、国内 84 条、国际 26 条和合计 110 条保持一致。
 模块迁移位于 `firstleg/src/main/resources/db/phase2-published-freight-detail-migration.sql`；测试和存量环境仍只通过 `deploy/sql/头程数据库统一增量-MySQL8.sql` 执行。两个入口必须保持相同种子和迁移断言。
 ## 六、范围边界
 本决策不扩展以下能力：
 - 应收应付、账龄、授信、账单、对账、收付款、核销、发票和税务申报。
 - 汇率结算、本位币折算、会计科目、凭证、总账、利润和法定财务报表。
 - 仅为覆盖 110 条费用而建设的通用计费表达式、复杂审批或客户自定义费用平台。
 - 在初始化脚本中补造计费单位、默认币种、税率、价格、公式、触发节点或自动计费规则。
 ## 七、验证记录
 - 已只读核对受控 Excel 的工作表、13 个表头、110 条记录、84/26 范围和 SHA-256。
 - 已对模块迁移和统一增量做静态 SQL 审查，并核对两处 110 条种子完全一致。
 - 本地未启动 Java、Nacos 或 MySQL，也未连接测试环境执行数据库变更；因此尚无真实存量数据冲突结果、外键重映射结果或重复执行数据库证据。
 - 上线前先用只读查询核对存量规模并完成备份；实际冲突预检由统一增量在任何费用数据改写前执行。出现冲突结果和 `SIGNAL` 时必须停止，预检无冲突后脚本才进入外键重映射与初始化，最终以末尾强校验和唯一 `PASS` 为准。
 ## 八、确认记录
 | 决策项 | 最终结论 | 状态 |
 |---|---|---|
 | 数据归属 | `fl_fee_item.tenant_id = 0`，平台公共主数据 | 已确认 |
 | 客户费用明细 | `tenant_id > 0`，引用公共 `fee_item_id` | 已确认 |
 | 初始化范围 | Excel 110 条全部初始化为 `ACTIVE` 公共项目 | 已确认 |
 | 编码策略 | `FEE_TYPE_001` 至 `FEE_TYPE_110`，固定主键一一对应 | 已确认 |
 | 客户级存量处理 | 完整预检、外键重映射、删除已映射副本；冲突中止 | 已确认 |
 | 计费字段与规则 | 继续由 C6/P2-Q14 单独确认，不从 Excel 推断 | 未被本决策扩大 |
@@ -0,0 +1,446 @@
 # 虫虫出海入库测量与计费需求优化版 V2：测量、计费、托盘入库闭环
 > 形成日期：2026-08-01
 > 文档状态：待业务审核
 > 依据：入库测量与计费原型、现有入库测量与计费需求优化稿及 2026-08-01 新增流程说明
 > 本文只定义入库测量与计费范围和业务契约，不代表功能已经开发完成。
 > 主体模型：本文业务数据中的“租户”历史术语与 `tenantId` / `tenant_id` 字段，当前均按客户归属兼容语义理解；产品只有“平台—客户”两级。`tenant_id=0` 是平台身份、RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用使用所属客户 `tenant_id>0`。入库测量与计费不引入真实租户层。
 > 技术实现状态更新（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发，并通过本地测试 MySQL 和隔离端口真实 API 回归。产品/业务待确认项仍以第九章和《入库测量与计费 V2 需求确认清单》为准。
 > 订单衔接规则更新（2026-08-07，已确认）：草稿不生成入仓码；订单提交进入待审核时立即生成并固定唯一入仓码。平台审核无需先选择承运商；审核通过后才创建正式入库单并沿用该码，承运商可在后续履约或计费前补充。
 ## 一、结论
 入库测量与计费主流程应从原来的“人工测量—测量审核—接收审核—人工计费—填写一个库位”调整为：
 ```text
 订单与客户头程订单提交待审核
  → 生成并固定唯一入仓码
  → 平台审核通过（承运商不是审核前置条件）
  → 创建正式入库单并沿用该入仓码
  → 第三方测量设备按入仓码回传长宽高
  → 上传称重图片并由 OCR 识别重量
  → 人工校正 OCR 结果并汇总实际重量
  → 测量数据审核
  → 按客户规则、船司和 FBA 目的仓自动试算
  → 人工确认费用
  → 点击“发送费用给客户”
  → 拆分托盘并分配库位
  → 占用库位、入库成功、费用对客户可见
  → 异步通知客户
 ```
 “发送费用给客户”是入库测量与计费业务完成节点，也是入库成功节点。原方案中的独立“接收审核”不再作为入库前置节点；如页面需要保留，可改名为“入库确认”，其核心动作就是确认费用并完成托盘、库位占用。
 入库测量与计费不新增微服务：
 - 入库单、测量数据、审核、计费试算和费用快照放在头程服务。
 - 托盘基础资料、库位及库位占用放在仓库服务。
 - 测量图、称重图继续使用文件服务。
 - 客户通知通过现有事件桥接服务发送，不在入库事务中同步调用外部消息渠道。
 - 权限继续复用 IAM，所有后台按钮做到客户归属、企业、仓库数据范围校验。
 ## 二、核心业务规则
 ### 2.1 测量审核失败是否允许入库
 保留 Nacos 动态开关，默认关闭：
 ```yaml
 firstleg:
  inbound:
    allow-rejected-measurement: false
 ```
 建议配置归属：
 - Data ID：`firstleg-${spring.profiles.active}.yaml`
 - Group：`BAIYUE`
 - 默认值：代码和 Nacos 均为 `false`，避免 Nacos 配置缺失时意外放行。
 开关语义：
 | 配置值 | 规则 |
 |---|---|
 | `false` | 只有测量审核通过，才能确认费用、发送费用和入库；审核失败必须修正后重新提交。 |
 | `true` | 测量审核失败的入库单允许由有“异常放行”权限的人员继续；必须填写放行原因。 |
 即使开关开启，也不能让所有失败单自动入库。后端还必须同时校验按钮权限 `firstleg:inbound:exception-release`，记录操作人、原因、审核失败原因、开关当时值和时间。作废单、缺少费用快照或没有可用库位的单据始终不得放行。
 ### 2.2 第三方长宽高测量
 第三方设备只通过入仓码绑定入库单，不接受第三方直接传内部数据库主键。一个入仓码可回传多条箱规测量明细，每条回传必须带第三方事件号以保证幂等。
 建议开放接口：
 ```http
 POST /openapi/v1/inbound-measurements
 ```
 请求头：
 ```text
 X-App-Key: 分配给测量服务商的应用标识
 X-Timestamp: Unix 毫秒时间戳
 X-Nonce: 随机串
 X-Signature: HMAC-SHA256 签名
 Idempotency-Key: 第三方事件号
 ```
 请求示例：
 ```json
 {
  "eventNo": "M202608010001",
  "warehouseCode": "CN-YW-01",
  "inboundCode": "RK202608010001",
  "deviceCode": "DEVICE-01",
  "measuredAt": "2026-08-01T10:30:00+08:00",
  "items": [
    {
      "itemNo": "001",
      "lengthCm": 50.20,
      "widthCm": 40.10,
      "heightCm": 30.00,
      "quantity": 5,
      "sourceImageUrl": null
    }
  ]
 }
 ```
 统一响应示例：
 ```json
 {
  "code": "0",
  "message": "成功",
  "data": {
    "eventNo": "M202608010001",
    "inboundCode": "RK202608010001",
    "accepted": true
  },
  "requestId": "...",
  "timestamp": 1785541800000
 }
 ```
 接口校验：
 - 入仓码必须存在，且属于请求中的仓库和客户归属关系。
 - 入库单必须处于待测量或测量被驳回状态；已入库、已作废、费用已发送的数据不得覆盖。
 - 长宽高必须大于 0，单位统一为厘米；数量必须为正整数。
 - 同一个 `appKey + eventNo` 重复请求返回第一次结果，不重复新增明细。
 - 第三方原始报文、签名主体、处理结果和请求时间单独留档，业务表保存标准化后的数据。
 - 回调接口只接收测量结果，不直接审核、计费、占用库位或改变入库状态。
 建议同时提供查询接口，供设备确认处理结果：
 ```http
 GET /openapi/v1/inbound-measurements/events/{eventNo}
 ```
 ### 2.3 OCR 重量识别与人工校正
 重量数据来自称重图片，而不是长宽高设备。前端先把图片上传文件中心，再把 `fileId` 提交给头程服务识别，避免业务服务接收和长期保存大文件。
 建议接口：
 ```http
 POST /api/platform/inbounds/{inboundId}/weight-images/recognize
 PUT  /api/platform/inbounds/{inboundId}/weight-results/{resultId}
 POST /api/platform/inbounds/{inboundId}/weight-results/confirm
 ```
 识别请求只传文件标识：
 ```json
 {
  "fileIds": ["file-001", "file-002"]
 }
 ```
 每张图片形成一条结果，至少保存：图片、OCR 原始文本、OCR 原始重量、置信度、修正后重量、修正人、修正原因、确认状态。总实际重量由所有“已确认且有效”的修正后重量累加，禁止前端直接传一个不可追溯的总重量。
 规则：
 - OCR 结果允许人工修改，但不得覆盖原始识别值。
 - 无法识别、置信度过低或单位不明时标记为“待人工确认”。
 - 支持公斤和磅，服务端统一换算成 KG，原单位和原值必须保留。
 - 同一图片不得重复计重；替换、删除图片必须留下操作记录。
 - 测量提交审核前，至少上传并确认一张称重图片；即使整票只有一箱也不得免称重。所有称重图片必须已确认，且总重量大于 0。
 ### 2.4 FBA 计费范围
 入库测量与计费只支持 FBA 目的仓计费，不做完整财务、账单、收付款、核销和利润模块。
 计费匹配顺序：
 1. 根据客户归属、业务客户和生效时间选择客户计费规则版本；两类客户含义必须按字段契约区分。
 2. 根据起运仓、渠道/计费类型、船司、FBA 目的仓和生效时间匹配船司价格。
 3. 计算实测体积、实重和折算量。
 4. 按客户规则确定 KG 或 CBM 计费口径，并取实际量与折算量中的较大值。
 5. 生成费用试算明细，人工确认后形成不可变费用快照。
 包税、按 KG 计费：
 ```text
 体积重(kg) = 实测体积(CBM) × 167
 计费重量(kg) = max(实际重量(kg), 体积重(kg))
 基础费用 = 计费重量 × KG 单价
 ```
 不包税、按 CBM 计费：
 ```text
 重量折算体积(CBM) = 实际重量(kg) ÷ 363
 计费体积(CBM) = max(实测体积(CBM), 重量折算体积(CBM))
 基础费用 = 计费体积 × CBM 单价
 ```
 其中 `167`、`363` 只是当前业务给出的默认示例，必须配置在客户规则版本中，不得硬编码。金额还可叠加船司价格表中明确配置的附加费；入库测量与计费头程/FBA 计费不支持阶梯价、组合优惠和复杂表达式。Warehouse 服务中的海外仓客户级天数阶梯仓储费仅为基础资料 CRUD，当前不参与本流程自动计费。
 费用单必须保存以下快照，避免基础资料后续修改影响历史订单：
 - 客户规则 ID、版本、计费类型、换算系数和舍入规则。
 - 船司价格 ID、版本、船司、起运仓、FBA 目的仓、有效期和币种。
 - 实测体积、实际重量、折算量、最终计费量、单价、附加费和总金额。
 - 试算人、确认人、确认时间，以及是否异常放行。
 无法唯一匹配客户规则或船司价格时，不允许发送费用和入库；返回明确错误，交由运营补充配置。
 ### 2.5 发送费用与入库成功
 后台按钮：`发送费用给客户`。建议权限码：`firstleg:inbound:send-fee`。
 点击前必须满足：
 - 入库单未作废、未入库、费用未发送。
 - 长宽高测量数据完整，重量图片均已确认。
 - 测量审核通过；或异常放行开关开启、操作人有权限且填写原因。
 - 费用已按当前有效规则重新试算并由操作人确认。
 - 已选择足够数量的可用托盘和库位。
 成功后一次业务操作应产生以下结果：
 1. 锁定费用快照，不再允许原地覆盖。
 2. 生成托盘分配明细。
 3. 在仓库服务预占并确认库位占用。
 4. 入库单状态变为 `INBOUNDED`，记录入库人和入库时间。
 5. 费用状态变为 `SENT`，客户侧可只读查看。
 6. 写入“费用已发送”领域事件，由事件桥接服务异步通知客户。
 客户消息发送失败不能回滚已经完成的实物入库和库位占用。事件通过 Outbox 重试，并在后台显示“通知失败/待重试”；禁止因用户重复点击产生重复费用、重复托盘或重复占位。
 ### 2.6 托盘拆分与库位占用
 托盘数量按总体积和选定托盘可用容积向上取整：
 ```text
 托盘数量 = ceil(入库单实际总体积 ÷ 单托盘可用容积)
 ```
 示例：总体积 `20 CBM`，托盘可用容积 `2 CBM`，需要 `10` 个托盘；默认一个托盘绑定一个库位，因此需要占用 `10` 个库位。若总体积为 `20.1 CBM`，则需要 `11` 个托盘，最后一个托盘保存剩余分配体积。
 注意：业务含义应是“10 个托盘分别绑定 10 个库位”，不是“一个托盘同时绑定 10 个库位”。如果实际仓库允许同一库位存多个托盘，后续再增加库位容量模型；入库测量与计费默认一托一位，以避免占用口径不清。
 拆分规则：
 - 托盘容积取托盘基础资料快照，历史分配不随托盘资料修改。
 - 托盘编号由仓库服务生成，禁止前端自行拼接。
 - 后端校验库位属于当前仓库、启用且未占用。
 - 多人同时选同一库位时，以数据库唯一约束或乐观锁保证只有一个请求成功。
 - 已入库后的换位、释放和重新上架不属于本次主流程；如确有需要，应作为 P1 的库位调整功能单独验收。
 ## 三、状态模型
 建议把“流程状态”“审核状态”“费用状态”“通知状态”分开保存，避免一个状态字段组合爆炸。
 ### 3.1 入库单流程状态
 | 状态 | 说明 |
 |---|---|
 | `WAIT_MEASURE` | 等待第三方长宽高和称重图片。 |
 | `MEASURING` | 已接收部分测量或 OCR 数据，尚未确认完整。 |
 | `MEASURE_PENDING` | 测量已提交，等待审核。 |
 | `MEASURE_REJECTED` | 审核失败，等待修正；默认不能继续入库。 |
 | `WAIT_PRICING` | 测量审核通过，等待计费试算。 |
 | `FEE_CONFIRMING` | 已试算，等待人工确认并发送。 |
 | `INBOUNDING` | 正在预占托盘和库位，防止重复操作。 |
 | `INBOUNDED` | 费用已确认并发送，托盘和库位已占用，入库成功。 |
 | `VOIDED` | 已作废。 |
 ### 3.2 子状态
 - 测量审核：`PENDING / APPROVED / REJECTED`。
 - 费用：`UNPRICED / CALCULATED / CONFIRMED / SENT / VOIDED`。
 - 客户通知：`NOT_CREATED / PENDING / SUCCESS / FAILED`。
 ## 四、服务与数据边界
 | 服务 | 入库测量与计费职责 | 主要新增数据 |
 |---|---|---|
 | 头程服务 | 入库单、第三方测量接入、OCR 结果业务管理、测量审核、计费匹配、费用快照、入库编排 | 入库单、测量批次/明细、OCR 重量结果、审核记录、客户规则、船司价格、费用快照、托盘分配引用 |
 | 仓库服务 | 托盘资料、库位资料、可用库位查询、预占/确认/释放 | 托盘、库位、库位占用、预占记录 |
 | 文件服务 | 称重图片、测量图片和附件 | 文件元数据和对象存储引用 |
 | 事件桥接服务 | 客户通知的可靠投递 | Outbox 消费记录、通知结果 |
 | IAM | 客户归属、企业、仓库范围和按钮权限 | 新增入库测量与计费权限资源，不新增业务数据 |
 头程与仓库分库，不能依赖跨库事务。采用“仓库库位预占 → 头程确认入库 → 仓库确认占用”的幂等 Saga；补偿只释放仍处于预占状态的库位，已经完成实物入库的记录不得被通知失败反向释放。
 ## 五、建议新增的核心接口
 ### 5.1 平台后台接口
 ```text
 GET  /api/platform/inbounds
 GET  /api/platform/inbounds/{id}
 POST /api/platform/inbounds/{id}/measurements/submit
 POST /api/platform/inbounds/{id}/measurements/approve
 POST /api/platform/inbounds/{id}/measurements/reject
 POST /api/platform/inbounds/{id}/weight-images/recognize
 PUT  /api/platform/inbounds/{id}/weight-results/{resultId}
 POST /api/platform/inbounds/{id}/weight-results/confirm
 POST /api/platform/inbounds/{id}/fees/calculate
 POST /api/platform/inbounds/{id}/fees/confirm
 POST /api/platform/inbounds/{id}/send-fee-and-inbound
 GET  /api/platform/inbounds/{id}/pallet-allocations
 GET  /api/platform/inbounds/{id}/operation-logs
 ```
 ### 5.2 仓库内部接口
 ```text
 GET  /internal/warehouses/{warehouseId}/locations/available
 POST /internal/location-reservations
 POST /internal/location-reservations/{reservationNo}/confirm
 POST /internal/location-reservations/{reservationNo}/release
 ```
 所有写接口必须支持幂等键；所有查询由后端基于登录上下文注入客户归属和企业范围，禁止单独相信前端传入的 `tenantId`；该参数当前表示目标客户 ID。
 ## 六、页面范围
 ### P0 页面
 - 入库单列表和详情。
 - 入库单测量：第三方数据展示、称重图片、OCR 原值/修正值和总重量。
 - 测量数据审核：客户下单、第三方长宽高、OCR 重量三组信息和驳回原因。
 - 费用试算与确认：客户规则、船司价格、FBA 目的仓、计费过程和费用快照预览。
 - 托盘/库位分配：托盘数量、每托盘体积、候选库位、占用结果。
 - 客户订单详情：只读显示已发送费用和入库结果。
 - 客户计费规则、船司价格表、托盘管理和库位管理。
 ### P1 页面/功能
 - 通知失败人工重试。
 - 入库后库位调整。
 - 测量视频。
 - 单票导出。
 ## 七、入库测量与计费开发任务重排
 | ID | 模块 | 交付内容 | 优先级 |
 |---|---|---|---|
 | P2-01 | 契约、状态与权限 | 状态机、错误码、按钮权限、客户/企业/仓库数据范围 | P0 |
 | P2-02 | 入库单 | 列表、详情、入仓码和操作历史 | P0 |
 | P2-03 | 第三方测量 | 签名、幂等、长宽高回传、原始报文留档和查询 | P0 |
 | P2-04 | OCR 称重 | 图片关联、OCR、人工校正、单位换算、确认和重量汇总 | P0 |
 | P2-05 | 测量审核 | 原单/设备/OCR 对比、通过、驳回和异常放行开关 | P0 |
 | P2-06 | 客户计费规则 | KG/CBM 类型、换算系数、舍入、生效期和版本 | P0 |
 | P2-07 | 船司 FBA 价格 | 起运仓、船司、FBA 目的仓、单价、币种、附加费和有效期 | P0 |
 | P2-08 | 自动试算与费用快照 | 规则匹配、取大计算、人工确认、费用发送和历史快照 | P0 |
 | P2-09 | 托盘与库位 | 托盘资料、向上拆分、库位可用查询、预占和确认占用 | P0 |
 | P2-10 | 入库编排 | 发送费用、入库成功、跨服务 Saga、幂等和失败补偿 | P0 |
 | P2-11 | 客户通知与展示 | Outbox 通知、失败重试、客户侧费用和入库结果只读展示 | P0 |
 | P2-12 | 文件与审计 | 称重/测量图片鉴权、第三方调用日志和全操作审计 | P0 |
 | P2-13 | 回归与发布 | 正常、驳回、放行、并发占位、重复提交、越权和异常恢复 | P0 |
 ## 八、验收主流程
 ### 8.1 正常流程
 1. 客户订单提交待审核时生成唯一入仓码，审核通过后创建正式入库单并沿用该码。
 2. 第三方用入仓码回传多条长宽高，同一事件重复回传不产生重复数据。
 3. 操作员上传多张称重图片，OCR 识别后可逐条修正，系统正确累加 KG。
 4. 审核员通过测量，系统按客户规则、船司、FBA 目的仓匹配唯一有效价格。
 5. 系统按 KG 或 CBM 口径取大计算，页面展示完整计算过程。
 6. 操作员确认后点击发送费用，系统生成正确托盘数并占用相同数量的可用库位。
 7. 入库单变为已入库，客户能看到已发送费用；通知异步成功。
 ### 8.2 必须覆盖的异常流程
 - 默认开关关闭时，测量审核失败不能计费发送和入库。
 - 开关开启但无异常放行权限，仍不能入库；有权限且填写原因时才可放行。
 - 无客户规则、无船司价格、价格过期或匹配多条时禁止发送费用。
 - OCR 图片重复、单位不明、未确认或总重为零时禁止提交审核。
 - 库位数量不足、被并发抢占或已停用时，入库失败且不能留下半完成费用/占用。
 - 重复点击发送费用只产生一份费用快照、一组托盘和一次入库结果。
 - 客户通知失败时入库状态不回滚，系统自动重试并可查失败原因。
 - 跨客户、跨企业、跨仓库查询和操作全部拒绝，并记录安全审计；具体使用 HTTP 状态还是业务码以接口统一响应契约为准。
 ## 九、仍需业务最终确认的事项
 1. 包税是否固定采用 `CBM × 167` 转 KG，不包税是否固定采用 `KG ÷ 363` 转 CBM；不同客户能否配置不同系数。
 2. “根据客户规则然后根据船司计算”是只生成客户应收费用，还是同时保存船司成本。本文默认入库测量与计费只向客户发送应收费用，船司价格作为计价基础，不进入应付和利润闭环。
 3. 船司价格唯一匹配所需维度是否就是：起运仓、渠道/类型、船司、FBA 目的仓和有效期。
 4. 托盘是否始终一托一库位。本文按一托一位设计；若一个库位可放多个托盘，需要补充库位容积、承重和剩余容量规则。
 5. 托盘分配是只按体积平均拆分，还是还要拆到具体 SKU/箱数。本文入库测量与计费只分配体积和箱数汇总，不做完整 SKU 库存。
 6. 点击发送费用前是否还需要第二人复核。本文默认测量审核完成后由有发送权限的操作员确认，不再增加独立接收审核。
 7. OCR 服务商、图片格式、单图大小、识别时限和失败重试次数需要在技术接入前确定。
 ## 十、本次相对上一版的变更
 - 第三方长宽高测量从“不纳入”改为入库测量与计费 P0，并定义按入仓码接入的开放接口。
 - OCR 称重从“不纳入”改为入库测量与计费 P0，支持多图累加和人工修正。
 - 人工简单计费改为客户规则加船司 FBA 目的仓自动试算。
 - 新增 KG/CBM 换算取大和费用规则/价格快照。
 - 新增 Nacos 审核失败异常放行开关，默认关闭。
 - 原“接收审核通过即入库”改为“发送费用给客户即入库成功”。
 - 原“只填一个库位”改为按托盘容积向上拆分，并一托一位占用库位。
 - 托盘管理从“不纳入”改为入库测量与计费必要基础能力，但不扩展为完整 WMS。
 ## 十一、实现与验收状态（2026-08-04）
 ### 11.1 已实现并通过真实 API 验证
 - 订单提交待审核时生成唯一入仓码；审核通过后创建正式入库单并沿用该码，审核不强制选择承运商。
 - 平台测量草稿、箱规明细、尺寸证据图片绑定。
 - 称重图片上传、OCR 失败状态、人工修正、重量确认和多重量汇总。
 - 测量提交、托盘拆分、库位预占及确认占用。
 - 客服测量审核通过后自动计费、发送费用并完成入库。
 - FBA 目的仓计费按实重和体积重取大，本轮 `20kg` 与 `40.08kg` 取 `40.08kg`。
 - 入库详情、费用快照、托盘和库位分配结果查询。
 - 公共收货仓的公共主数据技术归属与商户订单的客户归属分别校验；这只是当前兼容实现，不形成真实租户层。
 ### 11.2 最终验证数据
 | 项目 | 结果 |
 |---|---|
 | 入库单 | `2084549769916538881` |
 | 入仓码 | `RK-2084549604719718402` |
 | 测量批次 | `2084556854154715137` |
 | 最终状态 | `INBOUNDED / APPROVED / SENT` |
 | 计费 | `40.08kg × 11 CNY/kg = 440.68 CNY` |
 | 托盘 / 库位 | `2084561214309851137` / `2084561214452457473` |
 | 预占单 | `LR2084562525306675202`，状态 `CONFIRMED` |
 ### 11.3 已落地配置与数据快照
 公共仓主数据技术归属配置（配置名保留历史 `tenant` 命名）：
 ```yaml
 firstleg:
  inbound:
    warehouse-resource-tenant-id: ${WAREHOUSE_RESOURCE_TENANT_ID:0}
 ```
 公共仓库、快递公司、托盘和库位当前统一使用平台技术作用域 `tenant_id=0`，不得绑定客户 `10001` 或其他客户 ID。客户往来单位、订单、文件和费用仍使用所属客户 `tenant_id>0`。托盘分配快照继续保存历史字段 `warehouse_resource_tenant_id` 和 `reservation_no`，其中公共资源归属值应为 `0`，避免配置变化后无法追溯历史资源归属。
 ### 11.4 尚未关闭的环境验收项
 - 接入真实 OCR 供应商凭证后，以现场秤图验证识别准确率、超时和重试。
 - 前端浏览器完成登录、权限按钮、403、跨客户拒绝、重复提交、空态和移动端体验验收。
 - C1-C8 产品结论仍需产品/业务负责人正式填写，技术实现通过不等于代替产品确认。
@@ -0,0 +1,182 @@
 # 虫虫出海入库测量与计费需求优化版：头程入库测量闭环
 > 形成日期：2026-08-01
 > 需求依据：`D:\docs\悦` 原型、WMS 文档、头程物流流程图及现有入库测量与计费文档
 > 优化原则：以实际原型可见流程为主，优先复用客户订单与现有微服务，不建设当前业务不需要的完整 WMS 和计费平台。
 ## 一、优化结论
 入库测量与计费主目标收缩为：订单与客户头程订单提交后，后台能够完成入库单查看、实际测量、测量审核、接收审核，并记录简单库位和头程费用。
 ```text
 订单与客户头程订单
  → 入库单列表/详情
  → 录入实际测量数据与图片
  → 测量审核
  → 接收审核
  → 填写库位
  → 人工录入并审核头程费用
 ```
 不再单独建设到仓预约单、分批收货、处理单元、上架任务、位置历史和自动计费引擎。
 ## 二、入库测量与计费纳入范围
 ### 1. 入库单列表和详情
 - 直接复用订单与客户头程订单生成或展示入库单，不新增“订单—到仓单 1:N”模型。
 - 支持按入仓码、订单状态、测量审核状态、费用审核状态、客户、仓库和预计到达时间查询。
 - 详情展示基本信息、货物明细、测量数据、费用信息、状态历史和其他信息。
 - 其他信息包括快递公司、快递单号、关联文件、备注和客服内部备注。
 - 支持作废操作，作废必须填写原因并保留操作记录。
 ### 2. 入库测量
 - 录入实际箱数、总毛重、总体积和实际品名。
 - 按箱规录入长、宽、高、箱数、每箱重量、体积、周长和备注。
 - 保存客户下单数据、外箱规数据和实际测量数据，便于审核对比。
 - 体积、材积重和汇总值由服务端计算，小数点三位向上取整。
 - 测量图片必传；测量视频作为 P1 可选附件，不作为提交必填项。
 - 修改已提交测量数据需要退回后重新提交，不建设多版本复测系统。
 ### 3. 测量审核
 - 独立的待审核列表和审核详情。
 - 对比原单总箱数、毛重、体积、材积与实测结果。
 - 审核结果：审核通过、审核不通过。
 - 审核不通过必须填写原因，并退回测量人员修改。
 - 审核通过后进入接收审核。
 ### 4. 接收审核
 - 独立的待接收审核列表。
 - 展示入仓码、仓库、客户、业务类型、渠道、箱数、重量和测量审核结果。
 - 只有测量审核通过的数据才能接收。
 - 接收结果：接收通过、接收不通过。
 - 接收不通过必须填写原因；接收通过后入库单状态变为已入库。
 ### 5. 差异展示
 - 差异不再建设独立差异单、客户确认、通知补偿和关闭流程。
 - 在测量审核页面直接展示原单与实测箱数、重量、体积和材积差值。
 - 差异仅用于审核参考和历史记录，不阻塞审核人员主动通过。
 - 原型中的“待客户确认”页签不纳入入库测量与计费，应删除或改为“测量待审核”。
 ### 6. 库位
 - 复用仓库服务中的库位基础资料。
 - 入库接收时人工选择或填写一个库位。
 - 只校验库位属于当前仓库且未停用。
 - 不建设库区容量、承重校验、上架任务、任务分配、拆分和位置流水。
 ### 7. 头程费用
 - 只维护入库测量与计费实际使用的头程费用项目白名单。
 - 在入库单详情人工新增费用项目、数量、单价、币种、金额和备注。
 - 金额由服务端按“数量 × 单价”计算，也允许固定金额。
 - 费用状态：草稿、待审核、审核通过、审核不通过、作废。
 - 审核通过的费用不能直接覆盖，只能作废后重新录入。
 - 不建设头程/FBA 计费维度匹配、阶梯价、最低收费、封顶、组合价、规则版本和事件计费引擎。
 - 不生成应收、应付、对账单、收付款、核销、发票和利润数据。
 ### 8. 文件、打印和导出
 - 测量图片和关联文件使用现有文件服务，下载时校验租户和订单权限。
 - 打印唛头复用现有打印服务；入库测量与计费只要求按入库单打印，不建设处理单元标签生命周期。
 - 单票入库清单导出列为 P1；FBA 流转单、批量 ZIP 和自定义列暂不纳入。
 ## 三、状态模型
 | 状态 | 说明 |
 |---|---|
 | `WAIT_MEASURE` | 等待录入测量数据 |
 | `MEASURE_PENDING` | 测量数据已提交，等待审核 |
 | `MEASURE_REJECTED` | 测量审核不通过，等待修改 |
 | `RECEIVE_PENDING` | 测量审核通过，等待接收审核 |
 | `RECEIVE_REJECTED` | 接收审核不通过 |
 | `RECEIVED` | 接收审核通过，完成入库 |
 | `VOIDED` | 入库单已作废 |
 不使用“待客户确认、差异关闭、上架中、上架完成”等入库测量与计费无实际操作页面的状态。
 ## 四、角色与按钮权限
 | 角色 | 主要按钮 |
 |---|---|
 | 仓库测量员 | 查看入库单、录入/修改测量、上传图片、提交审核 |
 | 仓库审核员 | 测量审核通过/不通过、接收审核通过/不通过 |
 | 运营/客服 | 查看详情、维护快递信息、关联文件、备注、作废 |
 | 计费操作员 | 新增、编辑、提交头程费用 |
 | 计费审核员 | 费用审核、驳回和作废 |
 | 平台管理员 | 费用项目、库位及权限配置 |
 所有查询和操作必须按租户、企业和仓库进行服务端数据隔离。
 ## 五、精简后的开发任务
 | ID | 模块 | 交付内容 | 优先级 |
 |---|---|---|---|
 | P2-01 | 契约与权限 | 状态、错误码、按钮权限、租户/仓库数据范围 | P0 |
 | P2-02 | 入库单列表 | 查询、分页、筛选和状态页签 | P0 |
 | P2-03 | 入库单详情 | 基本信息、货物、测量、费用、历史和其他信息 | P0 |
 | P2-04 | 入库测量 | 箱规明细、汇总计算、图片上传和提交 | P0 |
 | P2-05 | 测量审核 | 原单实测对比、通过、驳回和原因 | P0 |
 | P2-06 | 接收审核 | 待接收列表、通过、驳回和完成入库 | P0 |
 | P2-07 | 库位记录 | 库位查询、选择、停用校验和入库单库位字段 | P0 |
 | P2-08 | 费用项目 | 头程费用项目白名单和启停 | P0 |
 | P2-09 | 入库费用 | 人工录入、计算、提交、审核、驳回和作废 | P0 |
 | P2-10 | 文件与打印 | 测量图片、关联文件、鉴权下载和打印唛头 | P0 |
 | P2-11 | 客户端展示 | 在客户订单详情只读展示实测、入库状态和公开费用 | P1 |
 | P2-12 | 测试发布 | 权限、越权、状态、重复提交、金额计算、文件和回归测试 | P0 |
 原 24 项任务收缩为 12 项，不新增微服务：入库和审核放在头程服务，库位/快递公司继续使用仓库服务，文件与打印复用现有服务。
 ## 六、从原型发现但原入库测量与计费文档覆盖不足
 | 原型内容 | 当前覆盖情况 | 优化处理 |
 |---|---|---|
 | 测量数据审核独立页面 | 有提及，但任务粒度不清 | 明确为独立 P0 功能 |
 | 接收审核独立页面 | 原计划被分批收货、上架流程稀释 | 明确为完成入库的最后审核节点 |
 | 客户下单/外箱规/实际测量三组对比 | 未完整描述 | 纳入测量详情和审核页 |
 | 审核不通过及失败原因 | 未完整描述 | 测量和接收审核均必须支持驳回原因 |
 | 测量视频 | 原文只写照片 | 改为 P1 可选附件 |
 | 快递公司、快递单号 | 有订单与客户字段，但未进入入库详情 | 纳入“其他信息” |
 | 关联文件、备注、客服内部备注 | 覆盖不足 | 纳入详情，内部备注不对客户展示 |
 | 作废、打印唛头、单票导出 | 覆盖不完整 | 作废和打印 P0，单票导出 P1 |
 | 费用审核状态 | 计费方案过度复杂 | 改为人工费用提交与审核 |
 | 状态历史 | 有数据对象但没有明确页面 | 详情页只读展示操作时间线 |
 ## 七、原型存在但入库测量与计费不纳入
 - 智能装柜、合关报关、配载、船期和 FIST 推送。
 - 到仓预约容量、自动服务商分配和多批次收货。
 - 托盘管理、处理单元、标签换标/补打/作废生命周期。
 - 独立差异单、客户确认、隔离区、上架任务和位置历史。
 - OCR 智能识别和自动测量设备接入。
 - 海外仓库存、退货、换标、派送、PDA 和完整 WMS；仅纳入客户级天数阶梯仓储费基础资料 CRUD。
 - 头程/FBA 阶梯计费、规则引擎、应收应付、对账和完整财务模块。
 - 批量导入导出、自定义列、批量 ZIP 和复杂报表。
 ### 7.1 海外仓阶梯费用补充边界（2026-08-05）
 Warehouse 服务已提供海外仓客户级天数阶梯仓储费的分页、详情、新增、编辑和删除接口。该功能属于基础资料配置，不代表海外仓 WMS 或自动计费已经纳入入库测量与计费。当前配置不参与入库/FBA 费用计算、费用发送、账单或结算。
 ## 八、仍需产品确认的最少事项
 1. 测量审核和接收审核是否必须由不同账号完成。
 2. 接收审核不通过后退回到测量环节，还是直接作废入库单。
 3. 入库测量与计费首批费用项目清单，以及哪些费用允许人工录入。
 4. 客户端是否展示费用；如果展示，只展示审核通过的费用。
 5. “是否扣货/扣货理由”只作为备注字段，还是需要真实业务状态。
 6. 测量视频是否保留；建议非必填并放入 P1。
 ## 九、验收主流程
 1. 订单与客户审核通过的头程订单出现在后台入库单列表。
 2. 测量员录入箱规、重量和体积，上传测量图片并提交。
 3. 审核员查看原单与实测对比，驳回时必须填写原因。
 4. 测量通过后进入接收审核，接收通过后状态变为已入库。
 5. 入库单能够保存库位、快递信息、关联文件和备注。
 6. 计费人员录入头程费用并提交审核，审核通过后客户按权限只读查看。
 7. 重复提交不产生重复记录，跨企业和跨仓库访问被拒绝。
 8. 作废、驳回、审核、文件访问和费用操作均有审计记录。
@@ -1,18 +1,18 @@
-# 虫虫出海二期需求确认清单：头程到仓与头程计费
+# 虫虫出海入库测量与计费需求确认清单：头程到仓与头程计费
-> 创建日期：2026-07-28  
+> 创建日期：2026-07-28
-> 更新日期：2026-07-31  
+> 更新日期：2026-07-31
-> 当前状态：产品已确认二期只做头程计费，3 项计费细节待补充  
+> 当前状态：产品已确认入库测量与计费只做头程计费，3 项计费细节待补充
-> 确认范围：头程物流“02 到仓”及头程费用计算  
+> 确认范围：头程物流“02 到仓”及头程费用计算
-> 关联规划：[二期开发规划](二期开发规划.md)  
+> 关联规划：[入库测量与计费开发规划](入库测量与计费开发规划.md)
-> 原型依据：[头程物流流程图](参考资料/头程物流流程图.svg)  
+> 原型依据：[头程物流流程图](参考资料/头程物流流程图.svg)
 > 产品回传：[2026-07-31 产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
 ## 一、文档用途
-本清单记录二期产品确认结果和仍需补齐的开发规则。产品已确认的结论直接进入基线；仍待确认的事项不得写成不可变的业务默认值，应保持配置化或可替换。二期由单一产品负责人统一确认，不记录确认人和确认时间；项目负责人组织业务、仓库、计费和技术共同补齐可开发结论。
+本清单记录入库测量与计费产品确认结果和仍需补齐的开发规则。产品已确认的结论直接进入基线；仍待确认的事项不得写成不可变的业务默认值，应保持配置化或可替换。入库测量与计费由单一产品负责人统一确认，不记录确认人和确认时间；项目负责人组织业务、仓库、计费和技术共同补齐可开发结论。
-二期财务边界已经确定：只做头程费用项目、计费规则、费用试算和头程费用明细，不做应收应付、对账、付款、核销、发票、汇率结算、利润或总账。
+入库测量与计费财务边界已经确定：只做头程费用项目、计费规则、费用试算和头程费用明细，不做应收应付、对账、付款、核销、发票、汇率结算、利润或总账。
 ## 二、确认参与人
@@ -29,7 +29,7 @@
 | 编号 | 原型/回传情况 | 本次需要确定 | 当前建议 | 临时结论 | 状态 |
 |---|---|---|---|---|---|
-| P2-Q14 | 费用白名单位置出现“63”占位值，不能作为业务结论 | “02 到仓”首批费用项目、计费单位、币种、税率/税务属性和触发节点 | 只纳入二期实际使用的头程费用；白名单外允许人工补录但必须留痕 | 待填写 | 待确认 |
+| P2-Q14 | 费用白名单位置出现“63”占位值，不能作为业务结论 | “02 到仓”首批费用项目、计费单位、币种、税率/税务属性和触发节点 | 只纳入入库测量与计费实际使用的头程费用；白名单外允许人工补录但必须留痕 | 待填写 | 待确认 |
 | P2-Q15 | 计费规则复杂度位置出现“63”占位值，不能作为业务结论 | 计费维度，以及是否支持阶梯价、最低收费、封顶、组合价和冲突优先级 | 先支持客户、往来单位、仓库、服务类型和生效区间；复杂结构按业务需要裁剪 | 待填写 | 待确认 |
 | P2-Q16 | 费用生成节点位置出现“63”占位值，不能作为业务结论 | 实测、差异、上架和人工费用分别在哪个节点试算、生成、确认和作废 | 实测完成生成试算；其他费用按已确认头程业务事件生成；来源键保证幂等 | 待填写 | 待确认 |
@@ -41,7 +41,7 @@
 ## 四、已确认的到仓作业结论
-| 编号 | 产品结论 | 二期开发口径 | 状态 |
+| 编号 | 产品结论 | 入库测量与计费开发口径 | 状态 |
 |---|---|---|---|
 | P2-Q1 | 以实际货物重量、体积为准 | 收货实测结果作为后续作业和头程计费输入 | 已确认 |
 | P2-Q2 | 不走系统服务商调度，取货安排线下完成 | 系统记录到仓结果，不建设服务商调度闭环 | 已确认 |
@@ -51,26 +51,26 @@
 | P2-Q6 | 不考虑隔离区 | 不建设独立隔离区和隔离释放流程 | 已确认 |
 | P2-Q7 | 当前不做库位容量校验 | 不做容量强校验，但校验库位停用和状态合法性 | 已确认 |
 | P2-Q8 | 称重、测量照片必传，大小不限制 | 必传照片；保留可配置技术安全上限、类型校验和访问审计 | 已确认 |
-| P2-Q9 | 暂缓 PDA | 二期使用后台或响应式作业页，不接 PDA | 暂缓 |
+| P2-Q9 | 暂缓 PDA | 入库测量与计费使用后台或响应式作业页，不接 PDA | 暂缓 |
 | P2-Q10 | 不考虑无预报货物场景 | 不建设无预报货物认领和正式订单绑定流程 | 已确认 |
 | P2-Q11 | 永久保存 | 业务记录不自动删除；运维另行制定存储、备份和合规处理策略 | 已确认 |
 | P2-Q12 | 使用佳博 1324D 热敏标签打印机 | 纸张、连接、驱动和指令协议在开发前实机核验 | 已确认 |
 ## 五、已确认的头程计费范围
-| 编号 | 产品结论 | 二期处理 |
+| 编号 | 产品结论 | 入库测量与计费处理 |
 |---|---|---|
-| P2-Q13 | 二期只做头程计费 | 只建设费用项目、计费规则、费用试算、调整、确认和头程费用明细 |
+| P2-Q13 | 入库测量与计费只做头程计费 | 只建设费用项目、计费规则、费用试算、调整、确认和头程费用明细 |
-| P2-Q17 | 不进入二期 | 不建设汇率结算和本位币折算 |
+| P2-Q17 | 不进入入库测量与计费 | 不建设汇率结算和本位币折算 |
-| P2-Q18 | 不进入二期 | 不建设财务税务结算口径；费用项目如需税率字段，按 Q14 配置即可 |
+| P2-Q18 | 不进入入库测量与计费 | 不建设财务税务结算口径；费用项目如需税率字段，按 Q14 配置即可 |
-| P2-Q19 | 不进入二期 | 不建设财务费用审核、应收应付审核或会计审计链；保留头程费用调整审计 |
+| P2-Q19 | 不进入入库测量与计费 | 不建设财务费用审核、应收应付审核或会计审计链；保留头程费用调整审计 |
-| P2-Q20 | 不进入二期 | 不建设客户/供应商对账和结算周期 |
+| P2-Q20 | 不进入入库测量与计费 | 不建设客户/供应商对账和结算周期 |
-| P2-Q21 | 不进入二期 | 不建设账单确认、争议和关闭流程 |
+| P2-Q21 | 不进入入库测量与计费 | 不建设账单确认、争议和关闭流程 |
-| P2-Q22 | 不进入二期 | 不建设收付款、核销、反核销和银行自动认领 |
+| P2-Q22 | 不进入入库测量与计费 | 不建设收付款、核销、反核销和银行自动认领 |
-| P2-Q23 | 不进入二期 | 不建设发票登记和外部开票平台 |
+| P2-Q23 | 不进入入库测量与计费 | 不建设发票登记和外部开票平台 |
-| P2-Q24 | 不进入二期 | 不建设利润、利润率和财务报表 |
+| P2-Q24 | 不进入入库测量与计费 | 不建设利润、利润率和财务报表 |
-原型中对应的完整财务页面不自动进入二期，后续阶段如需建设，另行立项确认。
+原型中对应的完整财务页面不自动进入入库测量与计费，后续阶段如需建设，另行立项确认。
 ## 六、全量状态跟踪
@@ -88,26 +88,26 @@
 | P2-Q10 | P0 | 无预报货物 | 已确认 |
 | P2-Q11 | P0 | 数据保存 | 已确认 |
 | P2-Q12 | P0 | 标签设备 | 已确认 |
-| P2-Q13 | P0 | 二期财务范围 | 已确认 |
+| P2-Q13 | P0 | 入库测量与计费财务范围 | 已确认 |
 | P2-Q14 | P0 | 首批费用项目 | 待确认 |
 | P2-Q15 | P0 | 计费规则复杂度 | 待确认 |
 | P2-Q16 | P0 | 费用生成节点 | 待确认 |
-| P2-Q17 | P0 | 汇率结算 | 不纳入二期 |
+| P2-Q17 | P0 | 汇率结算 | 不纳入入库测量与计费 |
-| P2-Q18 | P0 | 财务税务结算 | 不纳入二期 |
+| P2-Q18 | P0 | 财务税务结算 | 不纳入入库测量与计费 |
-| P2-Q19 | P0 | 财务费用审批 | 不纳入二期 |
+| P2-Q19 | P0 | 财务费用审批 | 不纳入入库测量与计费 |
-| P2-Q20 | P0 | 对账周期 | 不纳入二期 |
+| P2-Q20 | P0 | 对账周期 | 不纳入入库测量与计费 |
-| P2-Q21 | P0 | 账单确认争议 | 不纳入二期 |
+| P2-Q21 | P0 | 账单确认争议 | 不纳入入库测量与计费 |
-| P2-Q22 | P0 | 收付款核销 | 不纳入二期 |
+| P2-Q22 | P0 | 收付款核销 | 不纳入入库测量与计费 |
-| P2-Q23 | P1 | 发票管理 | 不纳入二期 |
+| P2-Q23 | P1 | 发票管理 | 不纳入入库测量与计费 |
-| P2-Q24 | P1 | 利润报表 | 不纳入二期 |
+| P2-Q24 | P1 | 利润报表 | 不纳入入库测量与计费 |
 ## 七、确认完成标准
-P2-Q14 至 P2-Q16 形成可开发结论后，头程计费模块可以进入正式任务拆分和开发验收。后续需求变化按变更流程处理，不得将应收应付、对账、付款、核销、发票或利润功能默认带入二期。
+P2-Q14 至 P2-Q16 形成可开发结论后，头程计费模块可以进入正式任务拆分和开发验收。后续需求变化按变更流程处理，不得将应收应付、对账、付款、核销、发票或利润功能默认带入入库测量与计费。
 确认完成后需要同步：
- 二期头程计费模块规划。
+- 入库测量与计费头程计费模块规划。
- 二期开发规划和开发进度表。
+- 入库测量与计费开发规划和开发进度表。
 - 头程计费任务依赖、数据对象和验收标准。
- 二期会议确认 Excel 及产品回传归档记录。
+- 入库测量与计费会议确认 Excel 及产品回传归档记录。
@@ -47,6 +47,8 @@
    </style>
  </defs>
  <rect width="1600" height="1100" fill="url(#pageBg)"/>
  <circle cx="1490" cy="50" r="180" fill="#D9F1ED" opacity=".42"/>
  <circle cx="90" cy="1080" r="220" fill="#DFEBFF" opacity=".48"/>
@@ -0,0 +1,171 @@
 # 海外仓阶梯费用前端联调说明
 > 更新日期：2026-08-05  
 > 后端服务：Warehouse Service  
 > 当前状态：后端 CRUD、Gateway 路由、权限、数据库增量和自动化测试已完成；前端待实现与联调
 ## 一、业务边界
 本功能用于平台端按客户维护海外仓仓储费的天数阶梯基础资料。一名客户只能存在一份有效配置，配置包含客户、币种和 1 至 100 组连续的天数阶梯。
 当前只提供基础资料维护，不参与本期入库、FBA 自动计费、费用发送、账单、对账或结算。当前也没有启停、计费单位、生效日期、免租期和版本发布能力，前端不得自行补造这些字段或业务动作。
 ## 二、建议页面
 - 页面名称：海外仓阶梯费用
 - 建议路由：`/customers/overseas-storage-fees`
 - 列表筛选：客户 ID、客户公司名称关键字
 - 列表字段：客户、币种、阶梯摘要、版本、创建时间、更新时间
 - 详情与编辑字段：客户 ID、客户公司名称、币种、阶梯起始天、阶梯结束天、仓储费单价
 - 操作：查看、新增、编辑、删除
 编辑和删除必须使用详情返回的最新 `version`。发生 409 冲突时应提示“数据已被修改，请刷新后重试”，重新读取详情，不能静默覆盖。
 ## 三、接口清单
 统一前缀：`/api/platform/v1/overseas-storage-fees`
 | 方法 | 路径 | 用途 | 权限 |
 |---|---|---|---|
 | GET | `/api/platform/v1/overseas-storage-fees` | 分页查询 | `platform:overseas-storage-fee:list` |
 | GET | `/api/platform/v1/overseas-storage-fees/{id}` | 查询详情 | `platform:overseas-storage-fee:list` |
 | POST | `/api/platform/v1/overseas-storage-fees` | 新增 | `platform:overseas-storage-fee:create` |
 | PUT | `/api/platform/v1/overseas-storage-fees/{id}` | 编辑 | `platform:overseas-storage-fee:edit` |
 | DELETE | `/api/platform/v1/overseas-storage-fees/{id}?version={version}` | 删除 | `platform:overseas-storage-fee:delete` |
 仅允许平台端令牌调用。列表查询参数如下：
 | 参数 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `page` | long | 否 | 默认 1，最小 1 |
 | `size` | long | 否 | 默认 20，范围 1 至 200 |
 | `customerId` | long | 否 | 客户 ID 精确查询 |
 | `customerName` | string | 否 | 客户公司名称模糊查询，最多 128 字符 |
 ## 四、请求示例
 新增：
 ```json
 {
  "customerId": "10001",
  "customerName": "示例客户有限公司",
  "currency": "USD",
  "tiers": [
    {"startDay": 1, "endDay": 7, "unitPrice": 0.5},
    {"startDay": 8, "endDay": 30, "unitPrice": 0.8},
    {"startDay": 31, "endDay": 60, "unitPrice": 0.6}
  ]
 }
 ```
 编辑请求结构与新增一致，并增加详情返回的版本号：
 ```json
 {
  "customerId": "10001",
  "customerName": "示例客户有限公司",
  "currency": "USD",
  "tiers": [
    {"startDay": 1, "endDay": 10, "unitPrice": 0.55},
    {"startDay": 11, "endDay": 30, "unitPrice": 0.8}
  ],
  "version": 1
 }
 ```
 说明：Java Long 类型的 ID 在浏览器中统一按字符串保存和传递，避免精度丢失。
 ## 五、响应结构
 详情的 `data` 结构：
 ```json
 {
  "id": "2100000000000000001",
  "customerId": "10001",
  "customerName": "示例客户有限公司",
  "currency": "USD",
  "tiers": [
    {
      "id": "2100000000000000002",
      "startDay": 1,
      "endDay": 7,
      "unitPrice": 0.5,
      "sortNo": 1
    }
  ],
  "version": 0,
  "createdAt": "2026-08-05T10:00:00",
  "updatedAt": "2026-08-05T10:00:00"
 }
 ```
 分页接口的 `data` 包含 `records`、`page`、`size`、`total`、`pages`。新增成功时 `data` 为新增配置 ID；编辑和删除成功时 `data` 为 `null`。
 ## 六、校验规则
 - 一个客户只能有一份有效配置。
 - `customerId` 必须为正数，`customerName` 必填且最多 128 字符。
 - 币种必须是三位大写字母，例如 `CNY`、`USD`。
 - 阶梯必须为 1 至 100 组。
 - 第一组必须从第 1 天开始。
 - 后一组 `startDay` 必须等于前一组 `endDay + 1`。
 - 区间不能间断、重叠或倒置。
 - 起止天数范围为 1 至 36500。
 - 单价必须大于 0，最多 12 位整数和 6 位小数。
 ## 七、错误处理
 | 业务码 | 场景 | 前端处理 |
 |---|---|---|
 | `A0403` | 非平台端访问或缺少按钮权限 | 显示无权限，隐藏无权限操作 |
 | `A0404` | 配置不存在或已删除 | 提示数据不存在并返回列表 |
 | `A0409` | 客户重复配置、阶梯区间冲突、版本过期或并发修改 | 保留用户提示，刷新列表或详情 |
 | `A0422` | 参数、币种、阶梯连续性或单价校验失败 | 显示服务端错误信息并定位表单 |
 | `S0503` | Warehouse 服务不可用或未就绪 | 显示服务暂不可用并允许重试 |
 普通成功响应仍需判断统一响应体 `code === "200"`。
 ## 八、数据库与部署
 本功能复用 Warehouse 数据库，未新增微服务或独立数据库。新增表：
 - `wh_overseas_storage_fee_rule`
 - `wh_overseas_storage_fee_tier`
 同时新增 5 个索引及 4 项按钮权限，平台系统管理员默认获得上述权限。唯一数据库增量入口：
 ```text
 D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql
 ```
 当前已完成 SQL 静态契约校验，但本次功能增量尚未在真实数据库执行。部署或联调前需先在目标库执行统一增量脚本并确认脚本最终输出 `PASS`。
 ## 九、Swagger
 - Gateway 聚合文档：`http://127.0.0.1:9000/webjars/swagger-ui/index.html`，选择 Warehouse 平台端分组。
 - Warehouse 直连文档：`http://127.0.0.1:9204/swagger-ui/index.html`。
 - Gateway OpenAPI：`/warehouse-service/v3/api-docs/platform`。
 ## 十、后端验证结果
 - Warehouse 全量测试：91 项通过。
 - 海外仓阶梯费用 CRUD 定向测试：6 项通过。
 - SQL 契约测试：1 项通过。
 - Gateway 路由契约测试：2 项通过。
 - Maven 构建：`BUILD SUCCESS`。
 - SQL 静态校验：存储过程分隔符、预处理语句配对、唯一最终 `PASS` 和危险语句检查均通过。
 ## 十一、前端验收清单
 - 有列表权限时可进入页面，无权限时路由、菜单和按钮状态正确。
 - 客户 ID 和客户名称筛选、分页及空态正确。
 - 新增后回读详情，ID 全程不转为 JavaScript `Number`。
 - 同一客户重复新增时正确处理 `A0409`。
 - 阶梯间断、重叠、倒置、非第 1 天开始和非正单价均不能提交成功。
 - 编辑使用最新 `version`，过期版本收到 409 后刷新详情。
 - 删除前二次确认，并携带最新 `version`。
 - 请求失败、服务不可用、加载态、空态和重复提交均有明确反馈。
 - 页面不出现启停、生效日期、计费单位、免租期或自动计费开关等未定义字段。
 - 不将本配置接入当前头程/FBA 自动计费流程。
@@ -0,0 +1,193 @@
 # 第三方入仓测量接口联调说明
 > 版本：2026-08-04  
 > 网关基地址：`http://127.0.0.1:9000`（测试环境替换为实际网关域名）
 ## 一、接口用途
 第三方测量设备每次回传一条箱规测量数据和一张对应图片。后端按入仓码匹配入库单，并校验指定货物明细属于该入库单关联订单，然后形成一条测量明细。
 接口只保存测量结果，不执行客服审核、计费、托盘拆分、库位占用或完成入库。
 ## 二、提交接口
 ```http
 POST /openapi/v1/inbound-measurements
 Content-Type: multipart/form-data
 ```
 请求头：
 ```http
 X-App-Key: <第三方应用Key>
 X-Timestamp: <Unix毫秒时间戳>
 X-Nonce: <本次请求唯一随机串>
 X-Signature: <HMAC-SHA256签名>
 Idempotency-Key: <本次业务操作幂等键>
 ```
 multipart 内容：
 | part 名称 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `data` | UTF-8 JSON 文本 | 是 | 一条箱规测量数据，服务端使用原文验签 |
 | `image` | 二进制文件 | 是 | 该条明细唯一对应图片；JPG、PNG、BMP，最大 5 MB |
 `data` 示例：
 ```json
 {
  "eventNo": "M202608040001",
  "externalDetailNo": "BOX-20260804-0001",
  "warehouseCode": "CN-YW-01",
  "inboundCode": "ZBYHK2604100412",
  "inboundDetailId": "190000000000000001",
  "deviceCode": "DEVICE-01",
  "measuredAt": "2026-08-04T10:30:00+08:00",
  "boxSpecification": "40*30*47cm",
  "packageCount": 50,
  "lengthCm": 40.000,
  "widthCm": 30.000,
  "heightCm": 47.000,
  "unitWeightKg": 20.000,
  "remark": ""
 }
 ```
 字段说明：
 | 字段 | 必填 | 规则 |
 |---|---|---|
 | `eventNo` | 是 | 同一 AppKey 下唯一；1～128 位字母、数字、点、下划线、冒号或横线 |
 | `externalDetailNo` | 是 | 第三方物理测量明细唯一号；重复绑定会被拒绝 |
 | `warehouseCode` | 是 | 必须属于该 AppKey 预先绑定的仓库 |
 | `inboundCode` | 是 | 柏悦入仓码，后端据此匹配入库单 |
 | `inboundDetailId` | 是 | 柏悦提供的订单货物明细 ID；必须属于该入库单关联订单 |
 | `deviceCode` | 是 | 测量设备编码，最长 64 位 |
 | `measuredAt` | 是 | ISO 8601 时间且必须包含时区 |
 | `boxSpecification` | 是 | 箱规显示文本，最长 64 位 |
 | `packageCount` | 是 | 本箱规箱数，1～1,000,000 |
 | `lengthCm` | 是 | 单箱长度，单位厘米且大于 0 |
 | `widthCm` | 是 | 单箱宽度，单位厘米且大于 0 |
 | `heightCm` | 是 | 单箱高度，单位厘米且大于 0 |
 | `unitWeightKg` | 否 | 单箱重量，单位 KG且大于 0；重量 OCR 流程可另行确认 |
 | `remark` | 否 | 最长 500 字符 |
 ## 三、签名算法
 先计算图片内容摘要：
 ```text
 imageSha256 = SHA256(image原始字节).lowerHex
 ```
 构造签名 body，`LF` 是单个换行符 `\n`：
 ```text
 signatureBody = data原始UTF-8文本 + LF + imageSha256
 bodySha256 = SHA256(signatureBody的UTF-8字节).lowerHex
 ```
 构造六行 canonical string，末尾不追加换行：
 ```text
 POST
 /openapi/v1/inbound-measurements
 <X-Timestamp>
 <X-Nonce>
 <Idempotency-Key>
 <bodySha256>
 ```
 最终签名：
 ```text
 X-Signature = HMAC-SHA256(appSecret, canonicalString).lowerHex
 ```
 `data` 中任何空格、换行或字段顺序变化都会改变签名。计算签名后必须发送完全相同的 `data` 原文和图片字节。
 ## 四、成功响应
 ```json
 {
  "code": "200",
  "message": "success",
  "data": {
    "eventNo": "M202608040001",
    "inboundCode": "ZBYHK2604100412",
    "inboundDetailId": "190000000000000001",
    "measurementId": "190000000000000010",
    "measurementItemId": "190000000000000020",
    "imageFileId": "190000000000000030",
    "accepted": true,
    "status": "RECEIVED",
    "receivedAt": "2026-08-04T02:30:00Z"
  },
  "requestId": "...",
  "traceId": "...",
  "timestamp": "2026-08-04T02:30:01Z"
 }
 ```
 所有 ID 都是字符串，调用方不得转换为 JavaScript Number。
 ## 五、事件查询
 ```http
 GET /openapi/v1/inbound-measurements/events/{eventNo}
 ```
 GET 同样需要 `X-App-Key`、`X-Timestamp`、`X-Nonce` 和 `X-Signature`，不需要 `Idempotency-Key`。canonical string 中幂等键行为空字符串，body 摘要使用空字节 SHA-256。
 ## 六、幂等与重复规则
 - `X-Nonce`：短时间防重放，使用后不能再次使用。
 - `Idempotency-Key`：一次 HTTP 写操作标识；网络重试必须复用原值。
 - `appKey + eventNo`：第三方业务事件唯一标识。
 - `tenantId + inboundDetailId + externalDetailNo`：测量明细绑定唯一约束。
 - 相同事件号或幂等键重试时，`data` 原文及图片内容必须与首次完全一致，否则返回冲突。
 ## 七、主要失败场景
 | 业务码 | 场景 |
 |---|---|
 | `A0400` | data 不是有效 JSON、图片为空或无法读取 |
 | `A0401` | AppKey、时间戳或签名无效 |
 | `A0403` | AppKey 未绑定请求仓库，或内部凭证无效 |
 | `A0404` | 入仓码不存在，或货物明细不属于入库单关联订单 |
 | `A0409` | 入库状态不允许测量、Nonce 重放、事件/幂等内容不一致、明细重复绑定 |
 | `A0422` | 字段缺失、格式或数值范围不符合要求 |
 | `S0503` | Order 或 File 服务暂不可用 |
 普通业务失败应以响应体 `code` 判断，不能只判断 HTTP 状态。
 ## 八、后台处理过程
 ```text
 验签和防重放
 → 按入仓码及绑定仓库查入库单
 → 调用 Order 校验货物明细归属
 → 检查第三方明细号是否已经绑定
 → 调用 File 保存并校验真实图片
 → 写入一条测量批次和一条测量明细
 → 返回测量、明细和图片ID
 ```
 如果图片已保存但测量数据落库失败，Firstleg 会调用 File 执行补偿清理。
 ## 九、上线前置
 部署新版 Firstleg 前，先执行：
 ```text
 firstleg/src/main/resources/db/phase2-third-party-single-measurement-migration.sql
 ```
 或执行已内联该增量的入库测量与计费统一脚本：
 ```text
 deploy/sql/2026-08-04-入库新增表字段-MySQL8一键执行.sql
 ```
 同时确认 Firstleg、Order、File 使用一致的 `INTERNAL_SERVICE_TOKEN`，并配置 `ORDER_SERVICE_URL`、`FILE_SERVICE_URL` 或启用 Nacos 服务发现。
@@ -0,0 +1,166 @@
 # 双区域部署与 Nacos 规划
 ## 1. 适用范围与结论
 本文冻结国内头程与海外仓服务在开发、测试和生产环境中的部署拓扑、Nacos、数据库及 Event Bridge 边界。账号、Token、API 路由和事件语义继续以《跨区域认证与服务通信契约》为准。
 当前结论：
 - 开发、测试采用单宿主机共置：同一环境内同时部署国内 Compose 与海外 Compose，通过独立容器、网络、端口、Nacos Namespace 和数据库 Schema 隔离。
 - 生产采用国内、海外两套独立区域控制面：各自使用本区域 Nacos 集群、数据库和 Redis，不允许海外服务跨境依赖国内 Nacos、MySQL 或 Redis。
 - 跨区域只开放双区域 API、JWKS 公钥和 Event Bridge 接收入口，不使用跨区域服务发现。
 ## 2. 环境拓扑
 | 环境 | 宿主与网络 | Nacos | 数据库 | 适用目的 |
 |---|---|---|---|---|
 | development | 单宿主机共置国内/海外 Compose | 一套开发 Nacos，国内/海外独立 Namespace | 可共用一个开发 MySQL 实例，但必须使用独立 Schema | 日常开发联调 |
 | test | 单宿主机共置国内/海外 Compose | 一套测试 Nacos，国内/海外独立 Namespace | 可共用一个测试 MySQL 实例，但必须使用独立 Schema | 集成测试和验收 |
 | production-cn | 国内独立部署单元 | 国内高可用 Nacos 集群 | 国内独立 MySQL/Redis | Auth、IAM、头程、国内仓和 Finance |
 | production-overseas | 海外独立部署单元 | 海外高可用 Nacos 集群 | 海外独立 MySQL/Redis | 海外 Gateway、Lastleg 和海外 Warehouse |
 如果开发与测试实际共用同一套 Nacos 实例，必须创建四个 Namespace，不得复用：
 ```text
 development-cn
 development-overseas
 test-cn
 test-overseas
 ```
 Namespace 名称不是服务名。环境变量必须填写 Nacos 实际 Namespace ID；控制台自动生成 UUID 时使用 UUID，不使用展示名称代替。
 ## 3. 服务归属
 ### 3.1 国内区域
 - `gateway`、`auth-service`、`iam-service`
 - `firstleg-service`、`order-service`、`finance-service`
 - 国内 `warehouse-service`、`file-service`、`audit-service` 等公共服务
 - 国内 Event Bridge，用于接收目标区域为 `CN` 的事件并投递本地 Firstleg
 ### 3.2 海外区域
 - `gateway-overseas`
 - `lastleg-service`，同时持有 `baiyue_lastleg` 内的 IAM 安全事件 Inbox/投影，并开放内部事件接收和实时校验端点
 - `warehouse-overseas-service`
 - 海外 `file-service`，独占海外 RDS 中的 `baiyue_file`，只访问海外本区域私有 OSS Bucket；详细边界见《[阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)》
 - 海外 Event Bridge，用于接收目标区域为 `OVERSEAS` 的事件；业务事件和三类 IAM 安全事件按事件类型投递 Lastleg 的不同内部入口
 海外浏览器请求直接进入海外 Gateway，不经过国内 Gateway。Auth 仍只部署在国内；海外服务通过受控 JWKS 地址验证 Auth 签发的短时海外 Token，不访问国内 Redis。
 ## 4. Nacos 规划
 ### 4.1 开发与测试
 非生产环境允许一套 Nacos 实例承载多个 Namespace。国内配置发布自 `baiyue-firstleg/config/nacos/cn/`，海外配置发布自 `baiyue-firstleg/config/nacos/overseas/`，相同 Data ID 依靠 Namespace 隔离。
 国内环境变量：
 ```dotenv
 NACOS_SERVER_ADDR=<当前环境Nacos地址>
 NACOS_NAMESPACE=<当前环境国内Namespace ID>
 REGION_CODE=CN
 DEPLOYMENT_CELL=<environment>-cn
 DATA_RESIDENCY=CN
 ```
 海外环境变量：
 ```dotenv
 OVERSEAS_NACOS_SERVER_ADDR=<当前环境Nacos地址>
 OVERSEAS_NACOS_NAMESPACE=<当前环境海外Namespace ID>
 OVERSEAS_DEPLOYMENT_CELL=<environment>-overseas
 ```
 海外 Compose 必须强制传入 `REGION_CODE=OVERSEAS` 和 `DATA_RESIDENCY=OVERSEAS`，不得继承共享文件中的国内默认值。
 ### 4.2 生产
 生产国内、海外分别部署本区域 Nacos 集群。服务只注册到本区域，不同步或复制临时服务注册表，也不通过公网访问另一地区 Nacos。
 ```dotenv
 # 国内生产凭据
 NACOS_SERVER_ADDR=<国内Nacos内网地址>
 NACOS_NAMESPACE=<production-cn Namespace ID>
 # 海外生产凭据
 OVERSEAS_NACOS_SERVER_ADDR=<海外Nacos内网地址>
 OVERSEAS_NACOS_NAMESPACE=<production-overseas Namespace ID>
 ```
 生产 Nacos 必须启用认证、网络 ACL 和持久化；不暴露公网管理端口。数据库密码、JWT 私钥、内部服务 Token 和第三方密钥不得写入 Nacos 明文，继续由 Jenkins Credentials 或生产密钥管理系统注入。
 ## 5. 数据库隔离
 开发、测试即使共用一个 MySQL 实例，也必须保持以下 Schema 独立：
 | 区域 | 服务 | Schema |
 |---|---|---|
 | 国内 | Event Bridge | `baiyue_event_bridge` |
 | 海外 | Event Bridge | `baiyue_event_bridge_overseas` |
 | 海外 | Lastleg | `baiyue_lastleg` |
 | 海外 | Warehouse | `baiyue_lastlag_warehouse` |
 生产必须进一步使用区域内独立数据库实例或集群。国内服务不得查询海外 Schema，海外服务不得查询国内 Schema；跨区域事实只通过版本化事件或已确认的受保护内部接口传递。
 ## 6. Event Bridge 双实例
 每个区域部署一个相同制品、独立数据库的 Event Bridge：
 ```text
 Firstleg Outbox
  -> 海外 Event Bridge Inbox
  -> Lastleg 本地消费者
 Lastleg Outbox
  -> 国内 Event Bridge Inbox
  -> Firstleg 本地消费者
 ```
 国内 Firstleg 配置海外 Bridge 基础地址，Feign 自动追加接收路径：
 ```dotenv
 LASTLEG_EVENT_BRIDGE_URL=<海外Event Bridge基础地址>
 ```
 海外 Lastleg 配置国内 Bridge 基础地址：
 ```dotenv
 FIRSTLEG_EVENT_BRIDGE_URL=<国内Event Bridge基础地址>
 ```
 区域内消费者使用本地服务地址：
 ```dotenv
 # 海外 Bridge
 EVENT_CONSUMER_URL=http://lastleg-service:9303/internal/lastleg/events
 # 国内 Bridge
 FIRSTLEG_CONTAINER_EVENT_CONSUMER_URL=http://firstleg:9202/internal/firstleg/v1/container-events
 ```
 跨区域 Bridge 接收入口使用 TLS、内部服务身份、网络白名单和幂等校验；不得暴露数据库或消费者内部接口。
 ## 7. Jenkins 与环境文件
 开发、测试可以各用一份 Secret File，同时包含国内和海外非敏感路由变量；Compose 负责选择本区域变量。生产必须拆分凭据：
 ```text
 firstleg-production-cn-env
 firstleg-production-overseas-env
 ```
 生产海外部署不得读取国内数据库、Redis 或 Nacos 地址。Event Bridge 同一制品需要按 `CN`、`OVERSEAS` 两个部署单元分别发布，使用不同 Compose Project、容器名、端口和数据库。
 ## 8. 当前仓库实施差距
 目标架构已冻结，但当前部署代码仍需完成以下收敛：
 1. `docker-compose.overseas.yml` 当前仍从 `NACOS_SERVER_ADDR` 取值，应改为显式使用 `OVERSEAS_NACOS_SERVER_ADDR`。
 2. `deploy/scripts/deploy-built-service.sh` 与 `deploy-services.sh` 的海外服务门禁应校验 `OVERSEAS_NACOS_SERVER_ADDR`。
 3. Jenkins 生产配置需要拆分国内/海外 Secret File，并为 Event Bridge 提供明确区域部署参数或独立 Job。
 4. 海外 Nacos Namespace 创建、配置发布、JWKS 可达性和双向 Event Bridge 真实投递必须分别验收，不能以容器健康检查代替。
 5. 海外 Gateway 和 Nacos 已存在 File Service 入口，但海外统一 SQL 与部署清单尚未包含海外 `file-service`、`baiyue_file`；OSS 接入实施前必须补齐并完成区域内真实上传、下载和双实例读取验收。
 这些差距未完成前，不得声称生产双区域部署已就绪。
@@ -0,0 +1,39 @@
 # 国内货柜履约
 本目录负责国内分柜、订舱、拖车、拣货、装柜、装柜后的报关协同、送港、进港和甩柜事实。整体货柜流程进入收尾，**报关协同代码尚未完成**；当前只在这里查找流程节点，报关开发请转到交接清单。
 ## 当前流程入口
 - [头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)：三大业务块总览和 F01-F40 节点总表。
 - [阶段三：国内货柜履约与出仓](../头程到尾程分阶段流程/阶段三-国内货柜履约与出仓.md)：分柜、订舱、拖车、拣货、装柜、报关和国内出仓的详细操作。
 - [阶段四：海运、目的港与尾程计划](../头程到尾程分阶段流程/阶段四-海运目的港与尾程计划.md)：实际开船后的海运、目的港和尾程计划衔接。
 - [报关资料与船期价格接入梳理](报关资料与船期价格接入梳理.md)：报关资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格专题。
 - [船期日历功能规划](船期日历功能规划.md)：渠道、周模板、单次船期、收货截止时间和按渠道货量统计的独立日历规划。
 - [报关代码开发交接清单](../头程到尾程/报关代码开发交接清单.md)：报关代码当前未完成时，下一开发对话使用的范围和验收条件。
 ## 货柜关键节点
 ```text
 分柜/订舱/拖车 → 拣货 → 装柜完成（LOADED）
                    ├─ 报关协同：资料 → 报关行回执 → 客户确认/打回重做
                    │              → 全部客户确认 → 整柜提交 → 正式申报 → 海关结果
                    ↓ 报关完成
                  进入待发区
                    ↓
          送港运输：离仓 → 送港 → 进港 → 甩柜/改配（如发生）
                                  ↓
                         船舶实际开航后进入海运节点
 ```
 报关完成是进入待发区的门槛。进入待发区后再推进离仓、送港、进港和船期；甩柜/改配只改变运输船次，不影响已完成的报关资料、回执和客户确认。报关行回执、客户确认、正式申报、海关放行、进港、甩柜和实际开船分别记录，不能用其中一个节点代替另一个节点。
 费用确认属于头程下单块的并行事项，不阻断排柜、拣货或装柜；装柜完成时仍未确认的当前有效费用按系统默认确认并保留来源。这个默认确认只适用于费用，不适用于报关资料的客户确认。
 ## 当前变更相关文档
 - [国内货柜履约需求确认表](国内货柜履约需求确认表.md)：需要核对已确认的业务口径时使用。
 - [国内货柜履约页面与原型清单](国内货柜履约页面与原型清单.md)：需要核对页面范围或原型入口时使用。
 ## 冻结记录（只用于追溯）
 开发规划、进度、门禁、验收矩阵、审计、产品确认和旧任务卡已移入[国内货柜履约历史记录](归档/README.md)。这些文件不删除、不回写；若要调整当前流程，修改总览、对应阶段或报关专题，并同步实际接口/权限契约。
@@ -0,0 +1,100 @@
 # 虫虫出海国内货柜履约需求确认表
 > 创建日期：2026-07-28  
 > 当前状态：已进入开发规划（已确认结论按本表执行；技术实现项仍需契约评审）  
 > 用途：记录会影响国内货柜履约范围、流程、数据模型、页面和验收的产品决策。
 ## 一、维护规则
 - 状态统一使用：待确认、确认中、已确认、已取消。
 - 阻断级别统一使用：开工阻断、模块阻断、非阻断。
 - 结论确认后同步更新 `归档/国内货柜履约开发规划.md`、`归档/国内货柜履约开发进度表.md` 和受影响的页面原型。
 - 未确认事项只能作为候选方案，不能直接写成固定开发或验收承诺。
 ## 二、确认事项
 | 编号 | 决策/问题 | 当前建议 | 阻断级别 | 状态 | 负责人 | 计划确认 | 最终结论 | 影响模块 |
 |---|---|---|---|---|---|---|---|---|
 | P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 业务提供可执行规则表，建议可解释并由人工确认 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 装载率上限 110%；税率高排前暂作为可配置排序，不作为不可变硬编码；系统给出可解释建议，人工确认后生成任务 | 智能排柜、拣货任务 |
 | P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 通过订单-柜次关系预留能力，页面按高频场景逐步开放 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 支持一单多柜、一个柜拼多个订单；采用“父订单→子订单→柜次”关系。已装载数量形成子订单，未装载数量自动生成待后续处理的子订单；不新建独立出仓单 | 订单、柜次、排柜、拣货 |
 | P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 已确认 | 产品/业务 | 2026-08-10 | 页面、接口和文档统一使用“预约拖车” | 页面文案、接口字段说明 |
 | P3-Q4 | PDA 开发、扫描与发布方式是什么？ | 保持设备适配层，不绑定厂商 SDK | 非阻断 | 已确认 | 用户当前对话确认 | 2026-08-10 | 采用 uni-app 开发并支持在线更新；Android 广播方式已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`。设备型号不构成开发、发布或验收门禁，扫描适配保持厂商无关 | PDA 拣货、在线更新、真机验收 |
 | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用入库测量与计费处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | PDA 拣货必须依赖实时库存和库位可用量；首版复用入库测量与计费处理单元、当前位置和可用量接口，超量、库存不足和库位不可用由服务端拒绝；不扩展完整 WMS | 入库测量与计费及国内货柜履约契约、拣货、库存边界 |
 | P3-Q6 | 柜封照片有哪些必传类型、数量、采集方式、处理规则和留存期限？ | 五类证据、角色和留存按确认版直接进入契约 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 空仓、半仓、满仓、锁仓、带锁码照五类各至少 1 张有效照片，同类型可无限追加；PDA 只能现场拍照；后台操作员和理货员可人工上传；拣货员只负责 PDA 现场采集，不开放后台人工上传；错图不硬删除，按原因、操作人、时间作废；带锁码照必须填写锁码文本；照片无限期保留，客户不可见照片和锁码 | 装柜、PDA 拍照、Admin 上传、文件存储、订单后程门禁 |
 | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版不对接海关或代理系统；按人工维护资料清单、收集/补件并保存版本，具体清单可配置 | 客户资料、报关审核、文件版本 |
 | P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10；2026-09-24 更正 | `LOADED` 后平台按客户/入仓码收集资料并线下发给报关行；授权人员上传每轮报关行回执，发给对应客户确认。客户打回后重新上传、重新发报关行并生成新回执，直到该客户确认；记录资料版本、回执版本、roundNo、发送时间和确认/打回审计 | 报关协同、客户确认、回执上传 |
 | P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 国内货柜履约只维护订舱与出仓前船期资料 | 已重新归期 | 已确认 | 产品/业务 | 2026-08-19 | 柜子确认离开国内仓库后的船公司/货物跟踪查询、每 3 天最多 3 次、来源、更新时间和过期标识整体归海外仓业务；国内货柜履约不建设或验收该查询 | 国内货柜履约订舱资料、海外仓业务船节点查询 |
 | P3-Q10 | 订单进入“装柜完成”后发现错误如何处理？ | 仅保留线下人工处理和审计，不建设在线冲正 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | `LOADED` 后不提供在线冲正/回退入口，统一线下人工处理；系统保留原状态和审计记录，不由国内 Admin/PDA 推进 `DELIVERED` | 装柜完成门禁、权限、审计 |
 | P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 统一门禁按已确认前置执行；PDA 单柜次单人作业 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10；2026-09-24 更正 | 费用确认不阻断排柜、预装、PDA 或装柜。进入 `LOADED` 只校验物理装柜、PDA、数量、真实柜号和五类证据；`LOADED` 后先完成退税报关，报关完成后进入待发区，再推进送港和船期；甩柜/改配只改变船次，不重做已完成报关；PDA 单柜次单人作业 | 全流程、状态机、PDA、报关、送港、页面进度 |
 | P3-Q12 | 报关回执包含哪些类型，客户确认和海关放行如何衔接？ | 首版人工上传回执并保留版本 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10；2026-09-24 更正 | `LOADED` 后按客户/入仓码收集资料并发送报关行；报关行回执发对应客户确认，客户打回则重新上传、重新发送并生成新回执；所有客户确认后才向报关行提交整柜资料并正式申报；之后分别记录查验、不查验放行、补件/退回等海关结果。回执上传不等于客户确认，客户确认也不等于海关放行 | 报关状态、客户回执、整柜申报、海关结果 |
 | P3-Q13 | 国内货柜履约终点以什么状态为准？ | 国内系统以能掌控的最后环节为终点 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | 国内货柜履约终点为 `LOADED`/装柜完成；`DELIVERED`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 |
 | P3-Q14 | 订舱、渠道柜次、放舱与智能排柜的先后关系是什么？ | 线下已订妥的订舱在创建时完整登记五项真实运输快照并直接确认；放舱不覆盖首次快照 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-12 | 订舱创建请求必须携带提单号、船名、航次、预计开船时间、预计到港时间五项真实运输数据，并直接进入 `CONFIRMED`；渠道、箱型和数量同时确定，系统按箱型需求数量生成绑定渠道的稳定内部柜次。未放舱不影响候选查询、智能推荐、人工调整和保存装柜计划；同一柜次只能装同渠道入库单，服务端禁止跨渠道混装。`RELEASED` 仅作为后续放舱/PDA 门禁，不补录、不覆盖首次五项运输快照；真实集装箱号可在放舱时或之后录入 | 订舱、柜次、智能排柜、预装、PDA、运输信息 |
 | P3-Q15 | 客户未确认费用是否阻断排柜、装柜？装柜完成后如何处理？ | 费用作为并行事实，装柜完成时对当前有效版本做系统默认确认 | 模块阻断 | 已确认 | 用户当前对话确认 | 2026-09-24 | 客户费用确认不阻断排柜、预装、PDA 或装柜。装柜完成后，针对本次已装范围的当前有效且已发布费用版本，若客户未确认则记录“系统默认确认（装柜完成）”；保留客户确认与 `SYSTEM_AUTO_AT_LOADED` 来源、版本、柜次/入仓码、时间和幂等标识。没有有效费用版本不得伪造确认；部分装载不确认余量或整张未完成订单 | 费用版本、装柜完成、客户进度、审计、部分装载 |
 | P3-Q16 | 报关资料何时收集、何时正式报送？ | 装柜后通知报关，按客户确认轮次完成后正式提交 | 模块阻断 | 已确认 | 用户当前对话确认 | 2026-09-24 | `LOADED` 后以最终实装清单通知报关行，按客户/入仓码收集资料并发送报关行；回执发客户确认，打回则重新上传、重新发送并产生新回执，循环至所有客户通过；全部客户确认后再提交整柜资料给报关行确认，由报关行正式申报；海关查验/不查验放行等结果单独记录；报关完成后进入待发区 | 客户资料、回执轮次、客户确认、整柜申报、待发区 |
 | P3-Q17 | 送港和报关是否互相等待？甩柜何时发生？ | 报关完成后进入待发区，实际开船才进入海运 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-09-24 | `LOADED` 后先完成报关；报关完成后进入待发区，再安排拖车、送港和进港。船舱不足记录 `ROLLED_OVER`，保存原船次、改配船次、滚动次数和通知；甩柜/改配不影响已完成报关资料、回执和客户确认；只有承运船舶真实开航才写 `VESSEL_DEPARTED`/海运节点 | 送港、船次、甩柜、海运节点 |
 ### 2.1 PDA 已确认子决策
 | 编号 | 确认日期 | 已确认结论 | 实现/验收含义 |
 |---|---|---|---|
 | P3-PDA-D01 | 2026-08-09 | PDA 正式作业必须联网；断网时不能开始正式拣货、提交、完成任务或推进 `LOADED` | 不建设离线业务提交队列；网络恢复后由员工刷新并重试 |
 | P3-PDA-D02 | 2026-08-09 | 进入任务即标记“拣货中” | 进入动作需调用后端开始接口，不能只改本地页面状态 |
 | P3-PDA-D03 | 2026-08-09 | 扫描结果先保存在本地草稿，点击“提交”时才批量写入后端，不逐码提交 | 批量请求需携带本次草稿全部明细；提交成功后再清理草稿 |
 | P3-PDA-D04 | 2026-08-09 | 未提交草稿需持久化，并绑定作业员、任务和柜次；其他账号不能继承 | 应用退出、前后台切换或设备重启后仍可恢复；成功提交或明确放弃后清理 |
 | P3-PDA-D05 | 2026-08-09 | 允许部分拣货和跳拣；每个未完成项必须填写异常原因 | 存在未解决异常时任务进入异常挂起/待处理，不能完成或推进 `LOADED` |
 | P3-PDA-D06 | 2026-08-09 | 使用轻量、对员工不可见的幂等与版本控制 | 重复提交返回原结果；版本冲突提示员工刷新后重试，不静默覆盖 |
 | P3-PDA-D07 | 2026-08-09 | PDA 只能现场拍照；Admin 可人工上传 | PDA 不提供相册选择；Admin 上传必须受权限、归属和审计约束 |
 | P3-PDA-D08 | 2026-08-09 | 同类型证据允许多张并采用追加记录；错误/重复照片不硬删除，只作废 | 每条照片独立保存；作废记录原因、操作人和时间，历史可追溯 |
 | P3-PDA-D09 | 2026-08-09 | 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效且未作废的照片，可多张；带锁码照同时要求锁码文本 | 服务端完整性门禁按“每类至少一张有效记录”校验，不能按单槽位替换模型实现 |
 > 验收映射：当前自动化已真实覆盖五类证据上传、同类型多图追加、跨类型/伪造 `fileId` 拒绝、锁码文本门禁和错图作废审计；设备在线、持久化草稿批量提交仍按[验收任务拆分与待确认清单](归档/国内货柜履约验收任务拆分与待确认清单.md)保留 coverageGap。
 ## 三、已确认架构决策
 | 编号 | 确认日期 | 最终结论 | 影响 |
 |---|---|---|---|
 | P3-D1 | 2026-08-08 | 国内货柜履约不新建独立出仓单，现有订单列表承载全部主状态；柜次、订舱、拖车、拣货、证据和报关作为订单关联子对象 | 取消出仓单页面和数据模型规划，改为增强现有订单列表/详情及服务端统一编排 |
 | P3-D2 | 2026-08-10 | 订单拆分采用“父订单→子订单→柜次”；已装载数量形成子订单，未装载数量自动生成后续子订单；支持一单多柜和多订单拼柜 | 后端必须保留父子订单、柜次、数量分摊和整体时间线；不得把未装载部分静默丢弃 |
 | P3-D3 | 2026-08-10；2026-09-24 更正 | `LOADED` 只表示物理装柜完成，门禁包含真实柜号、PDA 拣货、数量守恒和五类证据；报关完成后进入待发区，再推进送港/进港；甩柜只影响船期，不影响已完成报关；`LOADED` 后错误线下人工处理 | 统一门禁服务分别维护物理装柜、报关案例、待发区、送港/进港、甩柜和实际开船事实；国内页面不提供在线冲正或 `DELIVERED` 操作 |
 | P3-D4 | 2026-08-10；2026-08-19 更正归期 | 船公司官网查询：每 3 天一次、最多 3 次，保存来源、更新时间和过期标识 | 该能力及首批六家来源整体归海外仓业务，国内货柜履约只保留订舱与出仓前船期资料 |
 | P3-D5 | 2026-08-10 | 初始化仓库常用角色：操作员、拣货员、理货员；按最小权限授予拣货、证据上传和查看能力 | 角色初始化由 IAM/统一 SQL 任务实现，具体权限矩阵在技术契约评审中落表 |
 | P3-D6 | 2026-09-24 | 费用确认不阻断排柜和装柜；装柜完成后对已装范围的当前有效已发布版本执行系统默认确认，来源与客户主动确认分开审计；`LOADED` 后报关采用“报关行回执→客户确认/打回重做→所有客户通过→整柜正式申报→查验/放行”，报关完成后进入待发区，送港/船次单独记录甩柜和实际开船 | 同步费用版本、部分装载、客户报关案例、回执轮次、整柜申报、待发区、送港/船次和客户/后台节点 |
 ## 四、建议确认顺序
 1. 已完成 P3-Q1～P3-Q3、P3-Q5～P3-Q14 的产品确认，可直接进入契约和实现拆分。
 2. P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描；后续按既定发布安排完成常规真机验收。
 3. P3-Q5 已确认复用入库测量与计费实时库存、当前位置和可用量接口，完整 WMS 不纳入国内货柜履约。
 ## 五、产品与业务确认会议
 ### 5.1 参会角色
 - 产品负责人：逐项说明问题、候选方案和影响范围，维护最终结论。
 - 业务负责人：确认流程、规则、例外、责任边界和客户可见范围。
 - 仓库/运营代表：确认现场作业、PDA、照片、拖车、装柜和冲正可执行性。
 - 研发与测试代表：识别数据、接口、设备、权限和验收风险，不代替业务作决定。
 ### 5.2 会议输入
 - 本确认表中的 P3-Q1～P3-Q17。
 - `归档/国内货柜履约开发规划.md` 的流程、状态、里程碑和任务骨架。
 - `国内货柜履约页面与原型清单.md` 中已有参考原型和待补页面。
 - 入库测量与计费输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。
 ### 5.3 每项确认要求
 1. 必须填写负责人、计划确认日期和可执行的最终结论，不能只记录“按建议处理”。
 2. 最终结论需明确正常流程、异常/冲正、权限责任和验收口径。
 3. 暂缓事项必须写明当前范围是否排除、临时方案、影响模块和再次确认日期。
 4. 开工阻断项未解除时，不得将受影响模块标记为可开发。
 5. 会议结束后，将结论同步到开发规划、开发进度表、页面原型和后续验收任务。
 ### 5.4 会议输出（确认版）
 - 14 项确认事项的状态和最终结论已同步；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。
 - 需要新增或调整的原型清单。
 - 国内货柜履约范围内/范围外清单及跨期依赖。
 - 仍有风险的事项、责任人和完成日期。
 - 已允许进入 T02 契约设计与任务拆分；未决技术项只阻断其对应实现，不反向阻断整期已确认范围。
@@ -0,0 +1,56 @@
 # 虫虫出海国内货柜履约页面与原型清单
 > 创建日期：2026-07-28
 > 当前状态：核心 Admin 装柜页面已部署联调；PDA 提交契约和客户端国内货柜履约页面仍未完成
 > 原型依据：`参考资料/出仓流程.png`、现有订单列表/详情、现有 PDA 拣货原型
 > 已确认边界：不新增独立出仓单；国内国内货柜履约终点为 `LOADED`/装柜完成
 ## 一、维护规则
 - 页面状态统一使用：待确认、待原型、原型中、待评审、已确认、开发中、联调中、已阻塞、已完成；“已有/部分参考原型”仅表示原型覆盖程度，不表示功能完成。
 - 页面只有在业务流程、角色权限和关键字段确认后才能标记“已确认”。
 - 页面原型至少覆盖正常态、空态、加载态、失败态、无权限态和关键冲突态。
 - 当前先列页面级大项，后续按开发进度表的大任务逐项拆交互、字段和验收。
 ## 二、管理后台
 | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 |
 |---|---|---|---|---|---|---|
 | P3-ADM-01 | 现有订单列表国内货柜履约增强 | 查询、筛选、国内货柜履约主状态、异常和阻塞摘要 | T03 订单国内货柜履约编排与柜次 | 待原型 | P3-Q2、P3-Q11 | 复用现有订单列表，不新增出仓单列表和创建入口 |
 | P3-ADM-02 | 现有订单详情国内货柜履约增强 | 柜次、任务、五类装柜照片、锁码、报关和时间线 | T03 订单国内货柜履约编排与柜次 | 待原型 | P3-Q11 | 组合现有货柜和装柜清单能力，补统一编排区 |
 | P3-ADM-03 | 智能排柜 | 生成建议、冲突、调整和确认 | T04 智能排柜 | 开发中 | P3-Q1、P3-Q2 | Admin `/container-loading/smart-loading` 已部署；真实完成态受 PDA 门禁阻断 |
 | P3-ADM-04 | 订舱管理 | 订舱申请、结果、变更和异常 | T05 订舱与港务信息 | 已有参考原型 | P3-Q9、P3-Q11 | 已有订舱列表、新增和详情 |
 | P3-ADM-05 | 订舱与出仓前船期资料 | 人工维护船名航次、港口及预计时间快照 | T05 订舱资料 | 部分参考原型 | P3-Q9 | 出仓后的来源、更新时间和节点查询页面整体归海外仓业务 |
 | P3-ADM-06 | 拖车预约 | 服务商、车辆司机、时间窗和节点 | T06 拖车预约 | 已有参考原型 | P3-Q3、P3-Q11 | 已有拖车列表和新增表单，需补预约及到离仓节点 |
 | P3-ADM-07 | 拣货任务与复核 | 分配、进度、差异、复核和异常 | T07 PDA 拣货与复核 | 已阻塞 | P3-Q5 | 真实任务领取可用；PDA `pick` 仍返回 S0500，批量提交契约未实现 |
 | P3-ADM-08 | 装柜证据复核 | 柜号、锁码文本、五类多图、Admin 上传、作废和复核 | T08 装柜及柜封证据 | 开发中 | P3-Q6 | 五类多图追加、作废和 Admin 上传已通过真实接口；终态复核受 PDA 阻断 |
 | P3-ADM-09 | 报关协同 | 资料审核、补件、提交批次和回执上传 | T09 报关资料与回执 | 部分参考原型 | P3-Q7、P3-Q8、P3-Q12 | 已有报关单和单证管理，缺客户补件协同闭环 |
 | P3-ADM-10 | 订单装柜完成操作区 | 门禁检查、确认装柜完成、阻塞原因和冲正 | T10 装柜完成门禁 | 开发中 | P3-Q10、P3-Q11、P3-Q12 | 门禁读取和阻塞原因已有真实接口；置于现有订单详情，不提供在线冲正 |
 ## 三、企业客户端
 | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 |
 |---|---|---|---|---|---|---|
 | P3-CLI-01 | 现有订单列表国内货柜履约增强 | 查看本企业订单的装柜阶段、柜次和当前节点 | T11 客户端国内货柜履约协同 | 待原型 | P3-Q11 | 复用现有订单列表，不新增出仓单列表 |
 | P3-CLI-02 | 现有订单详情国内货柜履约增强 | 时间线、柜号、船期和允许公开的证据 | T11 客户端国内货柜履约协同 | 待原型 | P3-Q6、P3-Q9 | 在现有订单详情补国内货柜履约区块，不新建重复详情对象 |
 | P3-CLI-03 | 报关资料上传 | 清单、上传、补件、版本和处理进度 | T09 报关资料与回执 | 待原型 | P3-Q7 | 文件规则确认后细化 |
 | P3-CLI-04 | 报关回执下载 | 回执列表、类型、版本和授权下载 | T09 报关资料与回执 | 待原型 | P3-Q8、P3-Q12 | 区分客户可见回执 |
 | P3-CLI-05 | 出仓前船期资料 | 订舱预计开船、到港快照和变更 | T11 客户端国内货柜履约协同 | 待原型 | P3-Q9 | 出仓后的实时节点、来源、更新时间和过期展示归海外仓业务 |
 ## 四、PDA
 | 页面 ID | 页面/入口 | 主要能力 | 对应大任务 | 原型状态 | 依赖确认项 | 备注 |
 |---|---|---|---|---|---|---|
 | P3-PDA-01 | 登录 | 人员登录和快捷登录 | T07 PDA 拣货与复核 | 已有静态原型 | - | 真实鉴权待服务端接入 |
 | P3-PDA-02 | 箱号与任务选择 | 领取任务、进入即标记拣货中、选择箱号和查看进度 | T07 PDA 拣货与复核 | 已有静态原型 | P3-Q5、P3-Q11 | 需对接真实任务；单柜次单作业员，不支持换班接管 |
 | P3-PDA-03 | 扫码拣货 | 广播扫码、持久化草稿、整拣、部分拣货、跳拣和撤销 | T07 PDA 拣货与复核 | 开发中 | P3-Q5、P3-Q11 | 广播 Action/Extra 已接入；真实单明细 pick 当前仍有 S0500，断网禁止正式提交 |
 | P3-PDA-04 | 拣货提交 | 批量汇总、异常原因、幂等提交、版本冲突和完成统计 | T07 PDA 拣货与复核 | 已阻塞 | P3-Q5、P3-Q11 | 产品已确认点击提交时批量写后端；真正 batch endpoint、整批事务、幂等与回滚尚未实现 |
 | P3-PDA-05 | 装柜拍照上传 | PDA 现场拍摄五类证据、多图追加、锁码文本、预览、失败重试、作废和提交 | T08 装柜及柜封证据 | 原型中 | P3-Q6 | 每类至少一张有效照片；PDA 不开放相册，Admin 人工上传另设入口 |
 ## 五、下一步收口顺序
 1. 先修复 PDA `pick` 第二处 `S0500`，恢复领取、拣货、复核、装柜完成和报关终态真实链路。
 2. 单独实现 P3-PDA-04 原子批量提交契约，覆盖整批事务、幂等、版本/库存快照和失败回滚。
 3. 完成 P3-PDA-05 真机拍照、多图追加、失败重试与作废验收。
 4. 补齐 P3-ADM-01、P3-ADM-02、P3-ADM-10 和企业客户端国内货柜履约页面的最终交互验收。
 5. 复跑国内货柜履约定向和默认全量 HTTP 验收，只有所有硬门禁真实通过后才把页面和整期标记为完成。
@@ -0,0 +1,18 @@
 # 国内货柜履约历史记录
 本目录保存国内货柜履约的开发规划、进度、开工门禁、验收、审计和旧确认材料。内容不删除，也不作为当前流程入口；当前规则以[国内货柜履约 README](../README.md)、[头程到尾程流程节点梳理](../../头程到尾程流程节点梳理.md)和[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md)为准。
 ## 文件
 - [开发规划](国内货柜履约开发规划.md)
 - [开发进度表](国内货柜履约开发进度表.md)
 - [开发进度表（Excel）](虫虫出海国内货柜履约开发进度表.xlsx)
 - [需求确认表之外的开工门禁与验收记录](国内货柜履约开工门禁.md)
 - [验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)
 - [货柜管理全链验收矩阵](货柜管理全链验收矩阵-2026-08-13.md)
 - [货柜履约原型字段验收矩阵](货柜履约原型字段验收矩阵-2026-08-17.md)
 - [闭环审计报告](国内货柜履约闭环审计报告-2026-08-08.md)
 - [装柜闭环产品确认表](国内货柜履约装柜闭环产品确认表-2026-08-08.md)
 - [装柜闭环开发前确认单](国内货柜履约装柜闭环开发前确认单-2026-08-08.md)
 - [Wave1 开发任务卡](国内货柜履约Wave1开发任务卡-2026-08-09.md)
@@ -0,0 +1,58 @@
 # 国内货柜履约 Wave 1 开发任务卡
 > **历史版本声明（2026-09-24）**：本文是旧版低风险任务拆分，不能直接作为当前开发排期或门禁依据。当前流程改为“柜前资料预收集 → 物理装柜 `LOADED` → 按最终实装清单正式报关 → 有效放行回执后 `DEPARTED_WAREHOUSE`”，费用确认不阻断装柜，装柜完成时按已装范围对当前有效已发布费用版本执行系统默认确认。当前开发范围以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和最新需求确认表为准。
 整理日期：2026-08-09  
 用途：产品确认后用于研发排期和任务分派。  
 当前范围：只做低风险基础能力；不提前实现未确认的主状态机规则。
 ## 一、统一范围口径
 - 不新增独立出仓单主对象、列表或详情页面。
 - 现有订单是国内货柜履约唯一主对象；柜次是执行对象。
 - 订单与柜次通过履约分片/分配关系表达一单多柜、一柜多单和部分履约。
 - 国内国内货柜履约终点是 `LOADED`/装柜完成；国内端不能手工推进 `DELIVERED`。
 - 五类装柜照片为：空仓、半仓、满仓、锁仓、带锁码照；锁码文本单独保存。
 ## 二、第一批可立即开发
 | 编号 | 端/模块 | 任务 | 目标文件或范围 | 验收标准 | 依赖 |
 |---|---|---|---|---|---|
 | W1-BE-01-R | 后端 | 订单-柜次-履约分片契约设计 | 现有 order/firstleg/loading DTO、关系表和 OpenAPI；不得创建 `fl_outbound_order` | 支持多对多关系、快照、版本和客户隔离；形成评审稿 | 产品确认 Q2/Q11 后冻结实现 |
 | W1-BE-06 | 后端 | 拖车幂等与实际节点修复 | TruckAppointmentService、Controller、Mapper、测试 | 缺少幂等键时拒绝；同键重放返回原结果；冲突返回 409；到仓/离仓时间可追溯 | 无 |
 | W1-BE-08 | 后端 | OpenAPI 盘点与集成测试骨架 | 订舱、拖车、排柜、PDA、文件、门禁接口文档和契约测试 | 文档路径与 Controller 一致；建立入库测量与计费终点到装柜完成的测试骨架 | 仅依赖现有接口 |
 | A-01 | Admin | 订舱 DTO、版本和动作权限对齐 | `apps/admin-web/src/modules/ocean-bookings/` | 创建、编辑、提交、确认、放舱、变更、取消均使用真实字段、版本和权限 | 后端现有契约 |
 | A-02 | Admin | 订单详情挂载国内货柜履约作业组件 | `apps/admin-web/src/modules/unified-orders/` | 从订单详情可进入分柜、预装、拣货、装柜；刷新可恢复；错误和无权限有明确提示 | 订单与入库关联字段确认 |
 | PDA-01 | PDA | 五证据槽位和上传队列基础 | `apps/pda-uniapp/pages/` 及文件上传适配 | 五类槽位固定；临时路径不作为业务证据；失败可重试；重复提交不产生重复有效记录 | File 上传接口 |
 | CLI-01 | Client | 内部证据字段脱敏 | `apps/client-web/src/modules/first-leg/` | Client 不返回、不展示照片、锁码和 `sealNo`；订单状态仍可正常展示 | 后端响应兼容 |
 ## 三、必须等产品确认
 | 编号 | 决策 | 未确认前的处理 |
 |---|---|---|
 | Q1 | 排柜硬约束、软偏好和人工确认 | 不升级算法、不生成正式拣货任务 |
 | Q2 | 拼柜、一单多柜、部分拣货是否开放 | 只做关系查询，不冻结聚合规则 |
 | Q3 | `LOADING` 触发时点 | 保留现状，暂不改状态触发代码 |
 | Q4 | PDA 设备、扫描头和仓库权限 | 先做接口适配，不做真机上线承诺 |
 | Q5 | 是否实时校验库存/库位 | 不新增库存扣减逻辑 |
 | Q7/Q8/Q12 | 报关资料、代理批次、回执及门禁关系 | 只做范围设计，不建正式业务状态机 |
 | Q9 | 港务字段、来源、更新时间 | 不新增客户实时承诺 |
 | Q10 | `LOADED` 后冲正和证据修正 | 不实现直接覆盖或冲正接口 |
 | Q11 | 订舱、拖车、报关等强制前置 | 不把并行子状态写成硬门禁 |
 | Q13 | 国内终点及海外仓回传映射 | 国内端移除人工 `DELIVERED` 操作 |
 ## 四、后续波次
 1. Wave 0：完成 Q1～Q13 契约冻结和订单详情低保真确认。
 2. Wave 1：完成本表第一批基础能力。
 3. Wave 2：实现柜次级证据包、PDA 真实上传和服务端 `LOADED` 门禁。
 4. Wave 3：实现报关协同、Client 只读展示和海外仓可信回传接口。
 5. Wave 4：用同一真实订单完成正向、负向、权限、并发、幂等和弱网验收。
 ## 五、禁止误开工项
 - 新建独立出仓单或独立出仓菜单。
 - 允许无拣货、缺照片或缺锁码进入 `LOADED`。
 - 国内 Admin/PDA 手工推进 `DELIVERED`。
 - 在产品未确认前固化部分拣货拆单和一单多柜聚合规则。
@@ -0,0 +1,327 @@
 # 虫虫出海国内货柜履约开发规划：国内出仓
 > 创建日期：2026-07-28  
 > 状态：已进入分模块开发规划  
 > 流程依据：[出仓流程](../参考资料/出仓流程.png)中的头程物流“03 出仓”；当前以 `LOADED` 作为物理装柜节点，报关线和送港线在装柜后并行，实际开船后进入海运节点。
 > 前置阶段：[订单与客户文档](../../订单与客户/README.md) · [入库测量与计费文档](../../入库测量与计费/README.md)
 > 2026-08-10 产品确认版；2026-09-24 按最新流程更正：国内货柜履约不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 仅校验真实柜号、PDA 拣货、数量守恒和五类证据；装柜后报关线按“客户资料→报关行回执→客户确认/打回重做→所有客户通过→整柜正式申报→查验/放行”推进，送港线独立记录离仓、进港、甩柜和改配，实际开船才进入海运。费用确认不阻断排柜和装柜；装柜完成后对已装范围的当前有效已发布费用版本执行系统默认确认，保留客户/系统来源。`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。
 > 当前范围更正：国内货柜履约保留 `DEPARTED_WAREHOUSE`、`PORT_RECEIVED`、`ROLLED_OVER` 和实际开船前的船次/港口事实；承运船舶真实 `VESSEL_DEPARTED` 后的六家船公司官网查询、`CarrierScheduleQuery` 和定时节点查询归入海外仓业务。国内侧不以预计 ETD 提前展示海运中。
 > 主体模型与硬约束：国内货柜履约只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。
 ## 一、国内货柜履约目标
 国内货柜履约承接入库测量与计费“货物完成到仓、实测、差异处理和指定库位”的结果，将已受理货物转化为可执行、可追踪、可审计的国内出仓任务。
 流程覆盖九个动作：
 ```text
 智能排柜 → 订舱 → 预约拖车
    ↓
 PDA 拣货 → 装柜并上传五类证据
    ↓
 `LOADED`/装柜完成
    ├─ 报关：通知报关行 → 客户资料 → 报关行回执 → 客户确认/打回重做
    │          → 所有客户通过 → 整柜正式申报 → 查验/放行
    └─ 送港：拖车 → 离仓 → 送港/进港 → 甩柜/改配（如发生）→ 实际开船
 ```
 国内货柜履约的装柜完成标准是同一订单/柜次已完成排柜和 PDA 拣货，空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效照片已真实上传，锁码文本已保存，数量守恒且服务端门禁通过后推进为 `LOADED`/装柜完成。`LOADED` 后报关线和送港线同时启动；客户确认不阻断送港，进港不代表报关完成，容量不足记录甩柜；只有承运船舶实际开航后才进入海运节点。`DELIVERED`/派送完成必须等货物到达海外仓后由海外仓可信回传推进，不是国内国内货柜履约人工操作。
 ### 原型动作覆盖
 | 原型动作 | 规划模块 | 开发任务 | 覆盖结果 |
 |---|---|---|---|
 | 1. 智能排柜 | 智能排柜 | P3-PLAN-01、P3-PLAN-02 | 已覆盖，按 110% 装载率上限和可配置税率排序实现 |
 | 2. 订舱 | 订舱与出仓前船期资料 | P3-BOOK-01 | 已覆盖 |
 | 3. 预约托车 | 预约拖车 | P3-TRUCK-01 | 已覆盖，统一使用“预约拖车” |
 | 4. PDA 拣货 | PDA 拣货与复核 | P3-PICK-01、P3-PDA-01、P3-PDA-02 | 已覆盖 |
 | 5. 拍货柜及铅封照上传 | 装柜及柜封证据 | P3-LOAD-01、P3-LOAD-02 | 已确认五类证据各至少 1 张有效照片、同类型可多张，锁码文本必填 |
 | 6. 客户上传报关资料 | 报关资料协同 | P3-CUS-01 | 已覆盖 |
 | 7. 整理给到报关代理报关 | 报关资料协同 | P3-CLEAR-01 | 已覆盖 |
 | 8. 回执上传并由客户确认 | 报关行回执与客户确认 | P3-CLEAR-01、P3-CUS-02 | 待补齐多轮回执、客户确认/打回和整柜正式提交 |
 | 9. 送港、甩柜与实际开船 | 送港/船次事实 | P3-TRUCK-01、P3-CUS-02 | 装柜后与报关线并行；实际开船后进入海运节点 |
 ## 二、阶段边界
 ### 纳入国内货柜履约
 - 现有订单国内货柜履约状态、订单-柜次关联、智能排柜建议、人工调整和版本确认。
 - 订舱申请、舱位结果，以及出仓前人工确认或业务录入的船名航次、港口、ETD/ETA 等资料快照。
 - 预约拖车、车辆司机、到仓装柜和离仓记录。
 - PDA 任务领取、扫码拣货、部分拣货、异常、复核和幂等提交。
 - 装柜、柜号、铅封号及货柜/铅封照片证据。
 - `LOADED` 后通知报关行，客户上传报关资料、平台审核补件、线下发送报关行。
 - 报关行回执上传、版本、客户确认/打回重做、客户可见范围和授权下载；所有客户确认后才提交整柜资料正式申报。
 - 装柜后送港、进港、甩柜/改配和实际开船事实。
 - 装柜完成门禁、确认、时间线和站内通知；`LOADED` 后纠错走线下人工流程。
 ### 明确不纳入国内货柜履约
 - 入库、上架、移库、盘点、冻结、补货和完整 WMS；拣货仅复用入库测量与计费实时库存、当前位置和可用量接口。
 - 港区闸口、车队、船公司、海关单一窗口的正式自动化接口。
 - GPS 实时跟车、电子铅封、称重设备、摄像头 OCR 和 IoT 自动采集。
 - 自动报关、关税计算、退税、完整清关业务和自动单证识别。
 - 海上运输、海外清关、目的港提柜、海外仓入库和末端派送。
 - 承运船舶真实 `VESSEL_DEPARTED` 后的 `CarrierScheduleQuery`、船公司查询、定时船节点和海上到港跟踪；整体归海外仓业务。国内侧保留送港、进港和甩柜事实。
 - 无人工确认的全自动排柜、自动订舱和不可逆业务操作。
 ## 三、参与角色与数据边界
 | 角色 | 数据范围 | 主要操作 |
 |---|---|---|
 | 企业订单操作员 | 当前企业订单及关联柜次 | 上传/补充报关资料、查看订舱与出仓前资料、下载回执 |
 | 平台运营 | 授权客户、订单和柜次 | 确认排柜、订舱、维护出仓前船期资料和协调异常 |
 | 仓库主管 | 被授权的平台收货仓 | 分配拣货任务、复核差异、确认装柜和出仓条件 |
 | 仓库作业员 | 分配给本人或本仓的任务 | PDA 扫码、数量确认、异常上报和任务提交 |
 | 操作员 | 授权仓库/订单/柜次 | 查看作业进度、人工上传装柜证据、协助处理异常 |
 | 拣货员 | 分配给本人的单柜次任务 | PDA 扫码、数量确认、异常上报和批量提交；不开放后台人工证据上传 |
 | 理货员 | 授权仓库/柜次 | 人工上传/补充/作废装柜证据、核对柜号和锁码、记录异常 |
 | 拖车调度员 | 授权订单/柜次与车辆范围 | 预约车辆、维护司机/车牌、到仓和离仓节点 |
 | 报关专员 | 授权客户、订单和报关批次 | 审核、退回、整理、提交资料并上传回执 |
 | 平台管理员 | 平台授权范围 | 维护权限、规则和服务商；`LOADED` 后问题按线下流程处理，不提供在线冲正 |
 服务端必须依据登录身份确定企业、仓库、客户和数据范围。前端传入的订单 ID、柜次 ID、仓库 ID、客户 ID、作业员 ID 或报关批次 ID 不能单独作为授权依据。
 ## 四、流程与状态设计
 原图以 1 至 9 编号表达展示动作顺序。按本轮确认，费用确认不阻断排柜或装柜；`LOADED` 只校验物理装柜事实，装柜后报关线和送港线并行，客户确认不阻断送港，进港不代表报关完成，实际开船才进入海运。PDA 单柜次单作业员，不实现多人并行或任务接管。
 ### 1. 现有订单的国内货柜履约主状态
 | 稳定编码 | 中文名称 | 含义 |
 |---|---|---|
 | `WAIT_SPLIT` | 待分柜 | 入库测量与计费已完成，等待排柜/预装 |
 | `LOADING` | 装柜中 | 预装已确认，PDA 执行拣货和装柜证据上传 |
 | `LOADED` | 装柜完成 | 真实柜号、PDA 拣货与数量守恒、五类证据各至少 1 张有效照片和锁码文本已通过服务端门禁；装柜后同时启动报关线和送港线 |
 | `DELIVERED` | 派送完成 | 货物到达海外仓后由海外仓可信回传推进；属于国内货柜履约之后的只读状态 |
 ### 2. 子流程状态
 - 订舱：待订舱、订舱中、已订舱、订舱失败、已取消。
 - 拖车：待预约、已预约、车辆已到仓、装柜中、已离仓、改约、已取消。
 - 拣货：待分配、待拣货、拣货中、待复核、已完成、异常挂起、已取消。
 - 报关：`LOADED` 后待通知报关、客户资料待上传/审核、已发报关行、回执待客户确认、客户已确认、客户打回待重做、所有客户已确认、整柜正式申报、查验、放行/退回；回执上传不等于客户确认，客户确认不等于海关放行。
 - 送港/船期：待送港、已离仓、送港中、已进港、甩柜/改配、待开船；只有实际 `VESSEL_DEPARTED` 后进入海运节点。
 主状态由服务端根据已确认的必要子流程推进。客户端不得通过传任意目标状态跳过拣货复核、装柜证据或已配置的装柜完成门禁。
 ## 五、业务模块
 ### 1. 现有订单与柜次
 - 不创建独立出仓单，现有订单从 `WAIT_SPLIT` 继续推进国内货柜履约状态。
 - 通过“父订单→子订单→柜次”表达一张订单分多柜、多张订单拼柜和拆批；已装载数量形成子订单，未装载数量自动生成后续子订单，子订单必须保留来源订单和数量分摊快照。
 - 订单保持用户当前看到的主状态；柜次承载多订单共享的订舱、拖车、装柜证据和船期信息。
 - 订单详情展示关联柜次、子流程状态、异常和整体时间线。
 - 所有主状态推进使用服务端门禁、幂等键和版本字段防止绕过与并发覆盖。
 ### 2. 智能排柜
 - 原型仅明确“智能排柜”；已确认装载率上限为 110%，税率高排前仅作为可配置排序规则。柜型容量、重量、体积、箱数、同票/混票、不可混装和装载顺序由规则表配置并保留版本。
 - 当前建议首版采用“系统建议、人工确认”；是否允许调整、是否强制填写原因由排柜规则确认。
 - 建议排柜方案保留版本、规则版本、输入快照、操作者和前后差异，以支持追溯。
 - 未确认方案不得生成正式拣货任务或执行不可逆状态变化。
 ### 3. 订舱与出仓前船期资料
 - 国内货柜履约维护订舱、送港、进港、甩柜/改配和实际开船前的状态；承运船舶实际开航后由海外仓业务执行船公司和船节点查询。
 - 船公司/订舱代理、航线、订舱号、船名航次、起运港、目的港、截单、截关、截港、ETD 和 ETA 暂列为候选字段。
 - 订舱失败、改船、甩柜、船期延误和取消暂列为候选异常场景，按业务确认结果实现。
 - 六家船公司来源、每 3 天/最多 3 次、最近有效结果和过期标识，以及对应适配层在 `VESSEL_DEPARTED` 后由海外仓业务船节点查询维护。
 - 国内货柜履约页面展示的 ETD/ETA 必须明确为订舱或人工确认快照，不得伪装成出仓后的实时查询结果。
 - 建议关键信息变更保留旧值、新值、原因，并向授权用户发送站内提醒。
 ### 4. 预约拖车
 - 从往来单位选择已启用拖车服务商，维护车牌、司机、电话和预约时间窗。
 - 记录提柜、到仓、装柜、离仓、还柜节点和交接说明。
 - 支持改约、取消、迟到、未到、车辆更换和柜号变更。
 - 司机手机号等个人信息按最小权限展示，不进入不必要的客户响应。
 - 图片原文“预约托车”建议统一为行业常用的“预约拖车”，需产品最终确认。
 ### 5. PDA 拣货与复核
 - 按已确认排柜方案生成仓库、柜次、订单和货物明细级任务。
 - PDA 支持登录、领取、箱号选择、扫码、数量确认、部分拣货、跳拣、撤销和异常上报；进入任务即标记“拣货中”。
 - 正式作业必须联网；断网不能开始正式拣货、提交、完成任务或推进 `LOADED`，不建设离线业务提交队列。
 - 扫描只更新绑定作业员、任务和柜次的设备持久化草稿；员工点击提交时才将全部明细批量写入后端，成功或明确放弃后清理，其他账号不得继承。
 - 服务端校验任务归属、状态、重复扫码、超量、错货和批量提交；重复提交返回原结果，版本冲突提示刷新后重试。
 - 允许部分拣货和跳拣，但每个未完成项必须填写异常原因；存在未解决差异时任务挂起，不能完成或进入 `LOADED`。
 - 单柜次只允许一名作业员；不实现多人并行、退出接管或换班释放。进入任务即标记拣货中，点击确认完成后由服务端批量落库并参与统一门禁，无需后台二次审核。
 - 扫描器、声音、震动、网络和缓存通过设备适配层实现，不直接绑定单一厂商 SDK。
 ### 6. 装柜及柜封证据
 - 维护柜号、铅封号、装柜开始/完成时间、操作人和异常说明。
 - 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少上传 1 张有效照片，可同类型多张追加；带锁码照同时要求锁码文本。
 - PDA 只能现场拍照；Admin 可通过独立受权入口人工上传。上传前展示柜次、柜号、铅封号和照片类型，防止证据关联错误。
 - 每张照片作为独立记录，支持上传进度、失败重试和提交前预览；错误或重复照片不硬删除，标记作废并记录原因、操作人和时间。
 - 照片记录文件哈希、上传人、上传时间、关联柜次、有效/作废状态和作废审计；照片无限期保留，客户不可见照片和锁码。后台操作员和理货员按权限人工上传，拣货员仅通过 PDA 现场拍照。
 - 锁码重复、已确认的必传照片缺失或复核未通过时禁止确认装柜完成。
 - 修改柜号或铅封号需要二次确认、原因和完整审计。
 ### 7. 报关资料协同
 - `LOADED` 后按最终实装清单建立每个客户/入仓码的报关案例；客户按资料清单上传发票、箱单、合同、委托书和申报要素等文件。
 - 资料清单可按国家/地区、渠道和货物类型配置，并保存订单使用的清单版本。
 - 平台报关专员审核完整性，可退回具体文件并记录补件原因和时限。
 - 资料发送报关行时记录 roundNo 和发送时间，报关行回执上传后发对应客户确认；客户打回则重新上传、重新发送并生成新回执版本。
 - 柜内所有客户确认后才生成整柜正式提交批次，冻结该批次关联的文件版本并交报关行正式申报。
 - 首版采用系统内整理加线下提交，不直接对接海关单一窗口。
 ### 8. 报关回执与客户下载
 - 授权人员人工上传报关行回传的每轮回执并关联客户报关案例；回执类型、版本、roundNo、操作者和客户确认/打回结果可追溯。
 - 替换文件产生新版本，不覆盖原记录；退单或补件形成明确任务。
 - 客户只能下载本企业且标记为客户可见的回执。
 - 文件下载使用授权地址并记录审计，不暴露内部存储路径。
 - 所有客户确认后，平台向报关行提交整柜资料；报关行正式申报后另行记录查验、不查验放行、补件/退回等海关结果。
 ### 9. 装柜完成确认与海外回传边界
 - 服务端校验排柜已确认、PDA 拣货已完成、五类证据各至少 1 张有效且未作废的图片已取得真实 `fileId`、锁码文本已保存。
 - 门禁通过后仅将订单推进为 `LOADED`/装柜完成，记录柜次、柜号、锁码、操作人、时间和证据版本。
 - 该操作必须幂等、乐观锁、完整审计和失败回复，禁止从前端跳过门禁。
 - 装柜完成后发现错误统一线下人工处理；当前不提供在线冲正/回退接口，系统保留原状态、证据和审计记录。
 - `DELIVERED`/派送完成只接受海外仓可信回传，必须有来源身份、签名/防重放、幂等键、请求摘要和审计；国内 Admin/PDA 不提供手工“确认派送完成”操作。
 ## 六、核心数据对象
 | 数据对象 | 关键内容 |
 |---|---|
 | 现有订单国内货柜履约投影 | 订单、客户、仓库、国内货柜履约主状态、关联柜次、子流程摘要和版本 |
 | 父/子订单关系 | 父订单、子订单、来源柜次、已装载数量、未装载数量和自动生成原因 |
 | 排柜方案 | 经确认的规则版本、输入快照、柜次、货物分配、规则计算结果和确认记录 |
 | 柜次 | 柜型、柜号、铅封号、装载顺序、重量、体积和关联订单 |
 | 订舱记录 | 船公司/代理、订舱号、船名航次、港口、舱位和异常 |
 | 出仓前船期资料快照 | 经确认的订舱字段和变更历史；候选字段包括截单、截关、截港、ETD 和 ETA，不包含出仓后节点查询 |
 | 拖车预约 | 服务商、车辆、司机、预约时间窗、到离仓节点和异常 |
 | 拣货任务 | 柜次、货物明细、分配人、作业员、扫描、数量、差异和复核 |
 | 装柜证据 | 柜号、铅封号、照片类型、文件、上传人、时间和可见范围 |
 | 报关批次 | 资料清单版本、文件版本、补件、提交代理和回执 |
 | 出仓时间线 | 事件、前后状态、操作者、发生时间、说明和请求关联 ID |
 基础资料引用必须同时保存稳定 ID 和必要快照。订单、客户、仓库、往来单位、港务/船期信息或文件后续修改时，不得改变历史出仓记录。
 ## 七、应用范围
 ### 管理后台 `apps/admin-web`
 - 增强现有订单列表/详情，展示柜次、各子流程、异常和状态操作。
 - 按已确认的排柜规则提供建议、冲突展示、人工调整、版本对比和确认。
 - 订舱、船期、拖车预约、装柜、柜号、铅封和照片。
 - 报关资料审核、补件、提交批次、回执上传和客户可见控制。
 - 权限至少拆分为查看、排柜、订舱、拖车、仓内复核、报关、确认装柜完成；仓库初始化操作员、拣货员、理货员角色，国内端不提供在线冲正或确认派送完成权限。
 ### 企业客户端 `apps/client-web`
 - 在现有订单中查看关联柜次和允许公开的进度时间线。
 - 上传、补充和查看报关资料及处理结果。
 - 下载客户可见的报关回执。
 - 查看预计开船、到港和船期变更，不暴露内部成本、供应商敏感信息和内部备注。
 ### PDA `apps/pda-uniapp`
 - 仓库人员登录、任务领取、箱号选择、扫码拣货和数量确认。
 - 进入任务即标记“拣货中”；允许部分拣货、跳拣和异常上报，未完成项原因必填并阻断完成。
 - 扫描保存在设备持久化草稿，点击提交时批量写后端；草稿绑定作业员、任务和柜次。
 - PDA 仅现场拍摄五类装柜照片，同类型可多张追加；确认关联信息后上传，并处理进度、失败重试和作废。
 - 在线作业、前后台切换、重复提交、版本冲突和异常退出清理；不支持换班接管，断网不允许正式作业或提交。
 - PDA 采用 uni-app 开发并支持在线更新；Android 广播扫描已按 Action=`android.intent.action.SCANRESULT`、Extra=`value` 接入，扫描适配保持厂商无关。
 ### 服务端 `baiyue-firstleg`
 - 最终保证身份、客户归属、仓库数据范围、权限、状态、门禁、幂等、并发和审计。
 - 管理出仓、排柜、订舱、拖车、拣货、装柜、报关和时间线的事务边界。
 - 文件上传校验类型、大小、内容和权限；使用不可预测标识和授权下载。
 - 国内货柜履约服务端保存订舱与出仓前船期资料；六家船公司和定时船节点查询由海外仓业务负责。车队、海关仍只预留适配层，报关首版全部人工处理，不承诺正式系统对接。
 ## 八、建议里程碑
 | 里程碑 | 交付目标 | 进入条件 |
 |---|---|---|
 | P3-M0 规则与设备锁定 | 流程、角色、状态、排柜规则、PDA、文件和验收确认 | 入库测量与计费到仓契约稳定 |
 | P3-M1 订单与排柜 | 现有订单可进入待分柜，并按确认范围提供柜次建议、人工确认与追溯 | 排柜规则确认 |
 | P3-M2 订舱与拖车 | 订舱、出仓前船期资料、拖车预约和异常处理可用 | 服务商与权限可用 |
 | P3-M3 PDA 拣货 | 在线任务、持久化草稿、批量提交、差异、复核和幂等可用 | 服务端任务与库存契约可用 |
 | P3-M4 装柜封柜 | 柜号、铅封和照片证据完整，门禁生效 | 文件能力与必传清单确认 |
 | P3-M5 报关协同 | `LOADED` 后客户资料、报关行回执、客户确认/打回重做、所有客户通过、整柜正式申报和查验/放行闭环 | 报关资料清单确认 |
 | P3-M6 装柜完成及并行送港 | 真实柜号、PDA 拣货、数量守恒、五类证据和锁码文本满足门禁后进入 `LOADED`；随后并行推进送港/进港/甩柜和报关线，实际开船才进入海运 | 装柜完成、报关线和送港线分开 |
 | P3-M7 联调验收 | 跨端、设备、安全、弱网、性能、迁移和发布完成 | P3-M1 至 P3-M6 验收通过 |
 ## 九、建议开发任务
 | ID | 端 | 模块 | 交付内容 | 优先级 | 依赖 |
 |---|---|---|---|---|---|
 | P3-BASE-01 | 公共 | 出仓契约 | 主/子状态、权限、事件、错误码、门禁和快照模型 | P0 | 入库测量与计费到仓契约 |
 | P3-BASE-02 | 公共 | 数据模型 | 现有订单国内货柜履约投影、订单-柜次、排柜、订舱、拖车、拣货、装柜、报关和时间线 | P0 | P3-BASE-01 |
 | P3-DSP-01 | 后台 | 订单国内货柜履约编排 | 在现有订单列表/详情中接入柜次、子流程、异常、时间线和门禁操作 | P0 | P3-BASE-02 |
 | P3-PLAN-01 | 公共 | 排柜规则 | 按已确认规则实现输入、约束、偏好和冲突判断 | P0 | P3-BASE-02、P3-Q1 |
 | P3-PLAN-02 | 后台 | 智能排柜 | 按已确认范围实现建议、人工确认和追溯 | P0 | P3-PLAN-01 |
 | P3-BOOK-01 | 后台 | 订舱 | 订舱和经确认的船名航次、港口、变更及异常；订舱/拖车服务送港线，不作为 `LOADED` 的报关前置 | P0 | P3-DSP-01 |
 | P3-PORT-01 | 后台/服务端 | 送港、进港与甩柜 | 记录 `DEPARTED_WAREHOUSE`、`PORT_RECEIVED`、`ROLLED_OVER`、改配船次和客户通知；不以预计 ETD 推进海运 | P0 | P3-BOOK-01、P3-TRUCK-01 |
 | P3-TRUCK-01 | 后台 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓、进港和异常 | P0 | P3-DSP-01 |
 | P3-PICK-01 | 公共 | 拣货任务 | 按排柜方案生成任务、明细、差异和复核规则 | P0 | P3-PLAN-02 |
 | P3-PDA-01 | PDA | 在线扫码拣货 | 进入任务标记拣货中、扫描草稿、部分/跳拣异常原因和批量提交 | P0 | P3-PICK-01 |
 | P3-PDA-02 | PDA/服务端 | 草稿与提交安全 | 作业员+任务+柜次持久化草稿、幂等重试、版本冲突、成功/放弃清理 | P0 | P3-PDA-01 |
 | P3-LOAD-01 | 后台 | 装柜封柜 | 柜号、锁码文本、装柜节点、五类多图证据和门禁复核 | P0 | P3-PICK-01 |
 | P3-LOAD-02 | PDA/Admin/服务端 | 柜封拍照上传 | PDA 现场拍摄、Admin 人工上传、五类证据多图追加、真实文件上传、预览、失败重试、作废和提交 | P0 | P3-LOAD-01、文件能力可用 |
 | P3-CUS-01 | 客户端 | 报关资料与客户确认 | `LOADED` 后清单、上传、补件、回执查看、确认/打回和轮次进度 | P0 | 文件能力可用 |
 | P3-CLEAR-01 | 后台 | 报关协同 | 通知报关行、人工审核、回执轮次、客户确认汇总、所有客户通过后整柜正式提交、查验/放行记录 | P0 | P3-CUS-01 |
 | P3-CUS-02 | 客户端 | 回执及送港/船期资料 | 回执确认、打回重做、送港/进港/甩柜和实际开船前状态展示 | P0 | P3-BOOK-01、P3-CLEAR-01 |
 | P3-GATE-01 | 服务端 | 装柜完成与并行分支门禁 | 校验真实柜号、PDA 拣货、数量守恒、五类证据和锁码文本，幂等推进 `LOADED`；随后分别创建报关案例和送港任务，实际开船才推进海运 | P0 | P3-PICK-01、P3-LOAD-01、P3-LOAD-02 |
 | P3-OVERSEAS-01 | 服务端 | 海外仓派送完成回传 | 只接受海外仓可信回传，校验身份、签名、时间窗、防重放和幂等，推进 `DELIVERED` | P1/后续阶段 | 海外仓契约 |
 | P3-NOTIFY-01 | 公共 | 通知异常 | 站内通知、阻塞、责任人、时限和失败补偿 | P1 | 核心流程完成 |
 | P3-TEST-01 | 公共 | 自动化测试 | 权限、排柜、幂等、并发、文件、门禁和状态测试 | P0 | 所有 P0 模块 |
 | P3-DEVICE-01 | PDA | 发布与真机验收 | 扫描头、弱网、性能、电量、前后台和在线更新验证 | P0 | 已确定的 uni-app 发布安排 |
 | P3-REL-01 | 公共 | 发布验收 | 初始化规则、迁移、联调、演练、灰度和生产发布 | P0 | P3-TEST-01、P3-DEVICE-01 |
 ## 十、测试与验收重点
 - 系统排柜符合已确认的业务规则；如启用建议解释、人工调整、版本或原因记录，对应结果可追溯。
 - 多订单拼柜和一单多柜的件数、重量、体积能与入库测量与计费实测版本对账。
 - PDA 重复扫码、超量、错货和重复提交不产生重复扣减或完成事件；断网时禁止正式作业和提交。
 - 本地草稿在应用重启后可由同一作业员、任务和柜次恢复，不能被其他账号继承；批量提交成功后清理。
 - 柜封照片能够在 PDA 现场拍摄或由 Admin 受权上传；同类型可多张追加，失败重试不重复创建同一记录，错图只作废不硬删除。
 - 未完成 PDA 拣货、缺少任意一张必传照片或锁码文本时不能进入 `LOADED`/装柜完成。
 - 企业 A 无法查看、上传或下载企业 B 的报关资料和回执。
 - 报关资料替换、退回、补件、提交和回执均能追溯到明确版本。
 - 订舱与出仓前船期资料变更保留历史；出仓后船节点查询结果的来源、更新时间和过期验收归海外仓业务。
 - 确认装柜完成的并发请求只产生一次状态变化和一次有效审计事件。
 - 管理后台覆盖加载、空态、失败、无权限和数据冲突；PDA 覆盖弱网、前后台切换和硬件扫描。
 - 国内货柜履约验收基线为 `LOADED`/装柜完成；`DELIVERED`/派送完成只由海外仓回传推进，不属于国内国内货柜履约验收条件。
 ## 十一、启动前技术澄清事项
 验收任务拆分、真实 HTTP 覆盖和未确认项解除条件统一见[国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)。当前已确认的 PDA/证据规则已进入 `phase3-container-loading.mjs`、`phase3-loading.mjs`；未确认规则不得标记为国内货柜履约完成。
 | 编号 | 待确认问题 | 当前建议 |
 |---|---|---|
 | P3-Q1 | 智能排柜需考虑哪些硬约束和软偏好？ | 已确认：装载率上限 110%；税率高排前做可配置排序，规则版本化 |
 | P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 已确认：父订单→子订单→柜次；已装载/未装载数量自动形成子订单 |
 | P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 已确认统一使用“预约拖车” |
 | P3-Q4 | PDA 开发、扫描与发布方式是什么？ | 已确认采用 uni-app 开发并支持在线更新；Android 广播接入已完成，设备型号不构成门禁 |
 | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 已确认依赖入库测量与计费实时库存、当前位置和可用量接口；不扩展完整 WMS |
 | P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认：五类各至少 1 张、同类型可多张追加、后台操作员/理货员可上传、拣货员仅 PDA 现场采集、错图作废、无限期保留、客户不可见 |
 | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 已确认首版人工维护清单和版本，不接自动报关 |
 | P3-Q8 | 报关代理如何接收资料和返回回执？ | 已确认 `LOADED` 后线下提交；授权人员人工上传每轮回执，客户确认/打回，所有客户通过后再提交整柜资料 |
 | P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 当前更正：国内货柜履约维护送港、进港、甩柜/改配和实际开船前状态；只有实际开船后进入海运节点查询 |
 | P3-Q10 | 进入装柜完成后发现错误如何处理？ | 已确认线下人工处理，当前不提供在线冲正 |
 | P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 费用确认不阻断排柜/装柜；`LOADED` 只校验物理装柜、PDA、数量和证据；报关线和送港线并行，客户确认不阻断送港，进港不代表报关完成；单柜次单作业员 |
 | P3-Q12 | “报关回执”具体包含哪些类型，海关放行如何与客户确认衔接？ | 已确认：回执人工上传并发客户确认；客户打回则重做并生成新回执；所有客户通过后才整柜正式申报，查验/放行单独记录 |
 | P3-Q17 | 送港和报关是否互相等待？甩柜何时发生？ | 已确认：`LOADED` 后两条线同时启动；送港可先到港，报关可先完成客户确认；船舱不足记录甩柜/改配，实际开船才进入海运 |
 | P3-Q13 | 国内货柜履约终点以什么状态为准？ | 已确认为 `LOADED`/装柜完成；`DELIVERED`/派送完成由海外仓回传，不属于国内国内货柜履约 |
 ## 十二、建议实施顺序
 1. 固化已确认业务规则，按 uni-app 在线更新安排推进 PDA 开发、发布和真机验收。
 2. 统一订单、柜次、订舱、拖车、拣货、报关和出仓前船期资料的稳定编码与关联契约；出仓后查询按海外仓业务衔接。
 3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。
 4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。
 5. 使用脱敏数据演练拼柜、一单多柜、未装数量生成子订单、错拣、补件和改船；`LOADED` 后不演练在线冲正。
 6. 在真实 PDA 和代表性仓库网络环境中完成联调、验收和灰度发布。
@@ -0,0 +1,155 @@
 # 虫虫出海国内货柜履约开发进度表
 > 创建日期：2026-07-28
 > 当前阶段：已确认口径下的分模块部署、联调与缺口收口
 > 总体状态：分模块已部署联调；PDA 主链仍阻断，尚未达到国内货柜履约闭环验收
 > 规划依据：`国内货柜履约开发规划.md`
 > 维护方式：参考订单与客户进度表，采用“总体大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”的结构。
 ## 一、国内货柜履约目标
 国内货柜履约承接入库测量与计费到仓、实测、差异处理、处理单元编码和当前位置记录，完成智能排柜、订舱、拖车预约、PDA 拣货、装柜拍照，并在 `LOADED` 后分别推进报关客户确认闭环和送港/进港/甩柜；只有承运船舶实际开航才进入海运节点。
 当前验收基线已确认为 `LOADED`/装柜完成。`DELIVERED`/派送完成只能在货物到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围。
 ## 二、总体进度（大任务）
 | 大任务 ID | 大任务 | 范围 | 状态 | 进度 | 计划开始 | 计划完成 | 负责人 | 关键依赖/备注 |
 |---|---|---|---|---:|---|---|---|---|
 | T01 | 需求确认与原型 | 锁定阶段边界、流程依赖、排柜规则、设备、文件、报关和港务信息；完成页面原型 | 已完成 | 100% | 2026-07-28 | 2026-08-10 | 总控 | 产品确认版已同步；PDA 采用 uni-app、在线更新和 Android 广播扫描 |
 | T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、订单国内货柜履约投影、柜次、任务、证据、报关和审计模型 | 进行中 | 60% | 2026-08-10 | 待排期 | 总控 | 父子单、硬门禁、仓库角色、证据和费用契约已有真实接口；PDA batch 契约未完成 |
 | T03 | 订单国内货柜履约编排与柜次 | 增强现有订单列表/详情，建立父子订单-柜次关系、拆分/拼柜和时间线 | 联调中 | 80% | 2026-08-10 | 待排期 | 总控 | 父子履约树和柜次分片已通过真实验收，最终 LOADED 仍受 PDA 阻断 |
 | T04 | 智能排柜 | 排柜规则、系统建议、冲突、人工确认和追溯 | 联调中 | 80% | 2026-08-10 | 待排期 | Admin/Firstleg | 智能装柜工作台与真实候选、计划、分配、推送接口已部署；最终完成依赖 PDA |
 | T05 | 订舱与港务信息 | 订舱、变更异常、船公司官网查询、更新时间和过期标识 | 联调中 | 80% | 2026-08-10 | 待排期 | Firstleg/Admin | 订舱、港务船期生命周期已通过；ZIM/COSCO 保留人工兜底 |
 | T06 | 拖车预约 | 服务商、车辆司机、预约时间窗、到离仓节点和异常 | 联调中 | 80% | 2026-08-10 | 待排期 | Firstleg/Admin | 预约生命周期和服务中心串联已通过，最终 LOADED 门禁待 PDA |
 | T07 | PDA 拣货与复核 | 在线进入任务、持久化扫描草稿、批量提交、部分拣货、异常、幂等和单人作业 | 已阻塞 | 45% | 2026-08-10 | 待排期 | Firstleg/PDA | `pick` 第二处真实 S0500 未收口；原子 batch、库存快照、失败整批回滚未实现 |
 | T08 | 装柜及柜封证据 | 装柜节点、柜号、铅封号、PDA 现场拍照、后台角色上传、多图追加、作废和复核 | 联调中 | 80% | 2026-08-10 | 待排期 | Firstleg/Admin/PDA | 五类证据、多图追加、作废和硬门禁已通过；终态仍依赖 PDA |
 | T09 | 装柜后报关资料与客户确认 | `LOADED` 后通知报关行；客户资料→报关行回执→客户确认/打回重做→所有客户通过→整柜正式申报→查验/放行 | 联调中 | 70% | 2026-09-24 | 待排期 | Firstleg/Admin | 多轮回执、客户确认和整柜提交仍待实现 |
 | T10 | 装柜完成与送港/开船门禁 | `LOADED` 校验物理装柜；送港线独立校验订舱/拖车、离仓、进港和甩柜；实际开船才进入海运 | 已阻塞 | 70% | 2026-09-24 | 待排期 | Firstleg | 报关线和送港线并行口径已确认，真实推进与 PDA 修复仍待完成 |
 | T11 | 客户端国内货柜履约协同 | 装柜进度、柜次、回执、预计开船/到港和变更时间线 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 客户不查看装柜照片和锁码；依赖 T05、T09、T10 |
 | T12 | 联调测试与发布 | 跨端联调、自动化测试、PDA 真机、安全、弱网、迁移、验收和发布 | 联调中 | 70% | 2026-08-10 | 待排期 | 总控/测试 | Admin、Firstleg 已分模块部署并持续真实 HTTP 验收；PDA S0500、batch 契约和真机验收未收口 |
 ## 三、详细任务表
 详细任务按大任务逐项拆分。当前先建立任务骨架；每次拆分一个大任务，确认交付内容、优先级和依赖后再进入开发。
 | ID | 大任务 | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 依赖 | 负责人 | 备注 |
 |---|---|---|---|---|---|---|---:|---|---|---|
 | P3-T01-00 | T01 | 公共 | 需求确认与原型 | 完成需求确认表、页面清单和原型评审，锁定开工阻断项 | P0 | 已完成 | 100% | - | 总控 | 已同步产品确认版；PDA 技术路线已确认 |
 | P3-T02-00 | T02 | 公共 | 公共契约与数据模型 | 拆状态、权限、数据模型、接口和审计；初始化操作员/拣货员/理货员角色 | P0 | 进行中 | 60% | P3-T01-00 | 总控 | 主体契约已进入真实联调；PDA 原子 batch 仍缺 |
 | P3-T03-00 | T03 | 后台/服务端 | 订单国内货柜履约编排与柜次 | 实现父订单→子订单→柜次、一单多柜、拼柜、未装数量自动子订单和时间线 | P0 | 联调中 | 80% | P3-T02-00 | Order/Firstleg/Admin | 父子履约树、柜次分片与整体时间线已通过真实接口 |
 | P3-T04-00 | T04 | 后台/服务端 | 智能排柜 | 实现 110% 装载率上限、可配置税率排序、人工确认和版本追溯 | P0 | 联调中 | 80% | P3-T03-00 | Firstleg/Admin | 候选、计划、分配、调整与推送已部署；最终完成依赖 PDA |
 | P3-T05-00 | T05 | 后台/服务端 | 订舱与港务信息 | 订舱状态及六家船公司查询、三日周期、三次上限、过期标识 | P0 | 联调中 | 80% | P3-T03-00 | Firstleg/Admin | 港务生命周期已通过；ZIM/COSCO 为人工兜底，不算自动查询通过 |
 | P3-T06-00 | T06 | 后台/服务端 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常；完成状态供门禁校验 | P0 | 联调中 | 80% | P3-T03-00 | Firstleg/Admin | 预约、附件、历史及服务中心链路已通过真实接口 |
 | P3-T07-00 | T07 | PDA/后台/服务端 | PDA 拣货与复核 | 按单柜次单作业员实现在线草稿、批量提交、异常、幂等和实时库存校验 | P0 | 已阻塞 | 45% | P3-T04-00 | Firstleg/PDA | 广播扫描已接入；真实 pick S0500 与原子 batch 契约仍待收口 |
 | P3-T08-00 | T08 | PDA/后台/服务端 | 装柜及柜封证据 | 实现五类多图追加、角色上传、作废和无限期留存，客户不可见 | P0 | 联调中 | 80% | P3-T07-00 | Firstleg/Admin/PDA | 五类证据与安全边界已通过，真机拍照和终态待验收 |
 | P3-T09-00 | T09 | 客户端/后台/服务端 | 报关资料与客户确认闭环 | 实现客户案例、报关行回执轮次、确认/打回重做、所有客户通过后整柜正式提交、查验/放行记录 | P0 | 联调中 | 70% | P3-T02-00 | Firstleg/Admin | 人工协同接口已部署，客户确认闭环仍待实现 |
 | P3-T10-00 | T10 | 后台/服务端 | 装柜完成与送港/开船事实 | 实现物理 `LOADED`、送港/进港、甩柜/改配和实际开船分层事实，不以报关确认阻断送港 | P0 | 已阻塞 | 70% | P3-T07-00、P3-T08-00、P3-T09-00 | Firstleg | 门禁读取已通过；推进 LOADED 受 PDA 主链阻断 |
 | P3-T11-00 | T11 | 客户端/服务端 | 客户端国内货柜履约协同 | 展示柜次、装柜进度、客户可见回执和船期；不返回照片与锁码 | P0 | 待开始 | 0% | P3-T05-00、P3-T09-00、P3-T10-00 | 待分配 | - |
 | P3-T12-00 | T12 | 公共 | 联调测试与发布 | 维护定向/全量真实 HTTP、PDA 真机、安全和发布回归 | P0 | 联调中 | 70% | P3-T02-00～P3-T11-00 | 总控/测试 | 已进入分模块部署验收；不得用 mock、历史资源或 coverage gap 伪装通过 |
 | P3-T01-PROTO-01 | T01 | 公共 | 原型盘点 | 盘点流程图、后台、企业客户端和 PDA 中与国内货柜履约相关的页面及交互 | P0 | 已完成 | 100% | - | 待分配 | 2026-07-28 已完成首次盘点，来源为 `docs/悦` |
 | P3-T03-PROTO-01 | T03 | 后台 | 订单国内货柜履约编排原型 | 在现有订单列表/详情中设计柜次、子流程摘要、阻塞原因、时间线和操作入口 | P0 | 进行中 | 50% | P3-T01-PROTO-01、P3-Q11 | 待分配 | 不新建出仓单页面 |
 | P3-T04-PROTO-01 | T04 | 后台 | 智能排柜原型核验 | 映射智能装柜的线路页签、筛选、智能锁定、订单分柜、拖放调整和集装箱详情 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 按 110% 装载率上限和可配置税率排序实现 |
 | P3-T05-PROTO-01 | T05 | 后台 | 订舱与出仓前船期资料原型核验 | 映射订舱列表、新增/详情、放舱、船名航次、港口和 ETD/ATD/ETA/ATA 字段 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 出仓后的六家船公司及节点查询已重新归入海外仓业务 |
 | P3-T06-PROTO-01 | T06 | 后台 | 拖车原型核验 | 映射拖车列表、新增表单、运输公司、司机、车头号、装箱日期、费用和附件 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 预约时间窗和到离仓节点仍需按国内货柜履约流程补充 |
 | P3-T07-PROTO-01 | T07 | 后台/PDA | 拣货原型核验 | 对照通用 WMS 出库拣货和现有 PDA 集装箱拣货，锁定可复用交互与真实接口缺口 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 已确认在线作业、进入即开始、持久化草稿和批量提交；真实任务、鉴权与契约仍需完成 |
 | P3-T08-PROTO-01 | T08 | 后台 | 装柜证据原型核验 | 映射货柜列表、预装清单、装柜清单、柜号、单证、船期和装柜明细 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 后台参考较完整，但现场拍照上传原型缺失 |
 | P3-T08-PROTO-02 | T08 | PDA | 装柜拍照原型 | 新增柜次确认、五类证据多图追加、锁码文本、预览、重试、作废和提交页面原型 | P0 | 待开始 | 0% | P3-Q6 | 待分配 | PDA 仅拍照、Admin 可上传、每类至少一张和错图作废已确认 |
 | P3-T09-PROTO-01 | T09 | 后台 | 报关单证原型核验 | 映射报关单列表、单证管理、报关/清关/放行资料及装柜清单附件 | P0 | 已完成 | 100% | P3-T01-PROTO-01 | 待分配 | 客户上传和回执下载页面仍需新建 |
 | P3-T10-PROTO-01 | T10 | 后台 | 装柜完成门禁原型 | 在现有订单详情设计门禁检查、阻塞原因和确认装柜完成交互 | P0 | 进行中 | 30% | P3-Q10～P3-Q12 | 待分配 | 不提供在线冲正，不需要独立门禁页面 |
 | P3-T11-PROTO-01 | T11 | 客户端 | 客户端国内货柜履约原型 | 新增装柜进度、报关资料上传/补件、回执下载和出仓前船期资料展示 | P0 | 待开始 | 0% | P3-Q7～P3-Q9、P3-Q12 | 待分配 | 出仓后船节点页面归海外仓业务 |
 ## 四、原型对照与开发影响
 | 大任务 | `docs/悦` 现有原型 | 覆盖判断 | 开发处理 |
 |---|---|---|---|
 | T03 订单国内货柜履约编排与柜次 | 现有订单列表/详情、货柜列表、装柜清单 | 部分参考 | 增强现有订单页并建立订单-柜次关联，不新增出仓单页面 |
 | T04 智能排柜 | 入库单列表中的“智能装柜”弹窗 | 已有参考 | 复用线路、筛选、锁定、分柜和拖放交互，按 P3-Q1 裁剪规则 |
 | T05 订舱与港务信息 | 订舱列表、新增/详情、放舱、货柜船期字段 | 已有参考 | 复用订舱字段和页面结构，确认港务信息范围及来源后裁剪 |
 | T06 拖车预约 | 拖车列表、新增拖车 | 已有参考 | 复用车辆司机和费用字段，补预约时间窗、到仓及离仓节点 |
 | T07 PDA 拣货与复核 | 通用 WMS 出库、PDA 集装箱拣货 | 已有参考 | 保留扫描交互，按在线作业、持久化草稿、批量提交、异常阻断和轻量冲突提示重做真实契约 |
 | T08 装柜及柜封证据 | 货柜列表、预装清单、装柜清单 | 部分参考 | 后台页面裁剪复用；PDA 只拍照，Admin 可上传，同类型多张追加，错图作废 |
 | T09 报关资料与回执 | 报关单列表、单证管理、装柜清单附件 | 部分参考 | 后台裁剪复用；客户上传、补件和回执下载页面新建 |
 | T10 装柜完成门禁 | 现有订单状态操作和分散证据字段 | 部分参考 | 在订单详情补门禁检查和确认装柜完成；不提供在线冲正或国内确认派送 |
 | T11 客户端国内货柜履约协同 | 头程下单客户端只有船期字段和少量装柜摘要 | 覆盖不足 | 新建国内货柜履约客户端装柜进度、报关和港务信息页面 |
 > `货代SaaS平台原型.html` 是全量平台参考原型，其中海外仓、完整 WMS、费用和清关能力不自动纳入国内货柜履约；所有复用项仍需经过国内货柜履约范围裁剪。
 ## 五、建议拆分模板
 每个大任务按照同一顺序拆成可开发、可验收的小任务：
 1. `RULE`：业务规则、状态、权限和异常。
 2. `DATA`：数据表、字段、快照、版本和审计。
 3. `API`：接口、鉴权、幂等、并发和错误码。
 4. `ADM` / `CLI` / `PDA`：各端页面与交互。
 5. `TEST`：单元、接口、端到端、权限和边界测试。
 6. `ACCEPT`：业务验收、证据和遗留问题。
 例如 T04 智能排柜后续可使用 `P3-T04-RULE-01`、`P3-T04-DATA-01`、`P3-T04-API-01`、`P3-T04-ADM-01`、`P3-T04-TEST-01` 编号。
 ## 六、建议里程碑
 | 里程碑 | 交付目标 | 状态 | 计划完成 |
 |---|---|---|---|
 | P3-M0 需求与原型锁定 | 阶段边界、流程、规则、设备、文件和页面原型确认 | 已完成 | 2026-08-10 |
 | P3-M1 公共契约 | 入库测量与计费及国内货柜履约输入、状态、权限、数据模型和接口契约稳定 | 进行中 | 待排期 |
 | P3-M2 订单国内货柜履约编排 | 现有订单、柜次、排柜、订舱、港务和拖车可关联追溯 | 联调中 | 待排期 |
 | P3-M3 仓内出仓 | PDA 拣货、复核、装柜和柜封证据闭环 | 已阻塞 | 待排期 |
 | P3-M4 报关协同 | 客户资料、后台审核、提交代理、回执上传下载闭环 | 联调中 | 待排期 |
 | P3-M5 装柜完成及并行分支 | 真实柜号、PDA、数量守恒和五类证据门禁满足后进入 `LOADED`；随后并行推进报关客户确认闭环和送港/进港/甩柜，实际开船才进入海运 | 已阻塞 | 待排期 |
 | P3-M6 国内货柜履约上线 | 联调、真机、安全、测试、验收和生产发布完成 | 进行中 | 待排期 |
 ## 七、未确认事项（需求确认进度）
 当前 13 项主确认事项均已有产品最终结论；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。完整结论统一维护在 [国内货柜履约需求确认表](../国内货柜履约需求确认表.md)。
 验收拆分已建立：PDA 进入任务、拣货幂等/版本冲突、五类证据真实上传、多图追加和锁码门禁进入自动化；真机在线、设备草稿批量提交、证据作废、设备与权限留存等仍保留 coverageGap，详见[国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)。
 | 编号 | 阻断级别 | 待确认事项 | 状态 | 主要影响 |
 |---|---|---|---|---|
 | P3-Q1 | 开工阻断 | 智能排柜的硬约束和软偏好 | 已确认 | T04 智能排柜、T07 拣货任务 |
 | P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批装柜 | 已确认 | T03 订单国内货柜履约编排与柜次、T04 智能排柜 |
 | P3-Q3 | 非阻断 | “预约托车”是否统一为“预约拖车” | 已确认 | T06 拖车预约、页面与接口文案 |
 | P3-Q4 | 非阻断 | PDA 开发、扫描与发布方式 | 已确认 | 采用 uni-app 开发并支持在线更新；Android 广播模式已接入，设备型号不构成门禁 |
 | P3-Q5 | 开工阻断 | 拣货是否依赖实时库存和库位可用量 | 已确认 | 复用入库测量与计费实时库存、当前位置和可用量接口；不扩展完整 WMS |
 | P3-Q6 | 模块阻断 | 装柜照片和锁码规则 | 已确认 | 五类多图、角色上传、无限期保留、客户不可见 |
 | P3-Q7 | 模块阻断 | 报关资料清单是否按国家、渠道和货物类型变化 | 已确认 | T09 报关资料、文件版本 |
 | P3-Q8 | 模块阻断 | 报关代理接收资料和返回回执的方式 | 已确认 | 线下提交、人工上传回执 |
 | P3-Q9 | 开工阻断 | 港务信息的业务含义、字段和维护方 | 已确认 | 六家船公司查询、三日周期、三次上限、过期标识 |
 | P3-Q10 | 模块阻断 | 装柜完成后的错误处理和冲正方式 | 已确认 | 线下人工处理，不提供在线冲正 |
 | P3-Q11 | 开工阻断 | 九个动作的强制前置和并行关系 | 已确认 | `LOADED` 后报关线和送港线并行；客户确认不阻断送港，进港不代表报关完成；单柜次单人 |
 | P3-Q12 | 开工阻断 | 报关行回执、客户确认、正式申报和海关结果 | 已确认 | 回执必须发客户确认，打回则重做；所有客户通过后才整柜正式申报，查验/放行单独记录 |
 | P3-Q13 | 开工阻断 | 国内货柜履约终点 | 已确认 | `LOADED`/装柜完成；`DELIVERED` 由海外仓回传，移出国内货柜履约验收 |
 ## 八、开工准入记录
 国内货柜履约已进入分模块部署联调。下表保留开工条件及当前补齐状态，用于检查契约、原型和任务拆分是否仍有缺口，不再作为“尚未开始开发”的结论。
 | 准入编号 | 准入条件 | 当前状态 | 责任方 | 完成证据 |
 |---|---|---|---|---|
 | P3-GO-01 | P3-Q1～P3-Q17 均形成产品结论 | 已完成 | 产品、业务 | `国内货柜履约需求确认表.md` 已同步最终结论 |
 | P3-GO-02 | 确认结论已同步开发规划、进度表、页面清单和验收范围 | 已完成 | 产品、项目负责人 | README、进度表、页面清单和验收口径已按确认版同步 |
 | P3-GO-03 | 关键缺失原型已补齐并评审，包括订单装柜完成门禁、客户端国内货柜履约页面和 PDA 五类多图拍照 | 进行中 | 产品、设计、业务 | 页面清单中的关键页面达到已确认状态 |
 | P3-GO-04 | T02 公共契约完成，入库测量与计费输入、状态机、权限、数据模型、接口、错误码和审计口径稳定 | 进行中 | 前后端、架构/技术负责人 | 主体契约已部署；PDA 原子 batch 契约仍缺 |
 | P3-GO-05 | T03～T12 已拆成 RULE、DATA、API、ADM/CLI/PDA、TEST、ACCEPT 任务，并填写负责人和计划 | 进行中 | 项目负责人、研发、测试 | 已按独立任务推进；客户端、PDA batch 和真机验收任务仍需收口 |
 | P3-GO-06 | 产品、业务、研发和测试完成开工评审，确认范围、依赖、风险和首批任务 | 进行中 | 项目负责人 | 产品范围已确认并开工，正式评审证据仍需归档 |
 当前口径：未完成的准入项作为收口风险继续跟踪，不回退已经开始的开发和联调；只有契约、真机和真实 HTTP 验收全部完成后，才能标记国内货柜履约完成。
 ## 九、状态维护规则
 - 状态统一使用：待确认、待开始、进行中、联调中、测试中、已完成、已阻塞。
 - 进度填写 `0%～100%`；只有开发、测试和业务验收均完成后才能填写 `100%`。
 - 开始开发时填写负责人、计划开始和计划完成日期。
 - 出现阻塞时在备注中填写阻塞原因、责任人和预计解除时间。
 - 大任务进度应由其详细任务加权汇总；当前骨架阶段先人工维护，拆分完成后再确定权重。
 ## 十、下一步收口顺序
 1. 修复 PDA `pick` 第二处 `S0500`，复跑领取、拣货、复核、报关关联和装柜完成链路。
 2. 独立实现 PDA 原子 batch 契约及测试，覆盖整批事务、幂等、服务端库存快照和失败回滚。
 3. 完成 PDA 真机广播扫码、在线草稿、五类证据拍照、多图追加和作废验收。
 4. 收口 T11 客户端国内货柜履约页面及客户可见性、安全边界。
 5. 复跑国内货柜履约定向和默认全量真实 HTTP 验收，完成发布记录后再评估国内货柜履约完成状态。
@@ -0,0 +1,31 @@
 # 国内货柜履约开工门禁
 > 本文维护国内货柜履约跨端开发的稳定门禁。实时任务进度见 `国内货柜履约开发进度表.md`；产品决策以 `国内货柜履约需求确认表.md` 为准。
 ## 可直接开展的范围
 - 已确认规则可进入契约、数据、接口、页面和测试拆分，不需要等待整期所有模块完成。
 - 订单继续承载国内货柜履约主状态，不新建独立出仓单；支持父订单、子订单与柜次关系，以及一单多柜和多订单拼柜。
 - 智能排柜、订舱与船期、拖车预约、PDA 在线拣货、五类装柜证据、`LOADED` 后客户报关确认闭环、送港/甩柜和实际开船按本轮确认流程执行。
 - 国内货柜履约的国内终点为 `LOADED`；`DELIVERED` 只由海外仓可信回传推进。
 ## 跨端硬边界
 - `LOADED` 前必须由服务端校验真实柜号、PDA 拣货与数量守恒、五类有效证据和未解决异常。`LOADED` 后报关线和送港线分别校验：报关线按客户资料、报关行回执、客户确认/打回、所有客户通过、整柜正式申报和海关结果推进；送港线按订舱/拖车、离仓、进港、甩柜和实际开船推进。客户确认不阻断送港，进港不代表报关完成。国内 Admin/PDA 不提供在线冲正或手工推进 `DELIVERED`。
 - PDA 正式作业仅在线；单柜次只允许一名作业员，不支持多人并行、任务接管或换班释放。进入任务即由服务端标记拣货中，扫描草稿按作业员、任务和柜次隔离，提交时批量写入。
 - 每类证据至少一张有效照片，允许同类型追加；错误照片只能作废并保留审计。客户不可见照片与锁码。
 - 报关在 `LOADED` 后正式启动：每个客户经历资料上传、报关行回执、客户确认或打回重做，所有客户通过后才提交整柜资料给报关行正式申报；送港线独立记录拖车、进港、甩柜和实际开船。费用确认不阻断排柜/装柜，装柜完成后对已装范围的当前有效已发布费用版本记录系统默认确认，来源和客户主动确认必须分开审计。
 - 前端页面、菜单和路由只能在对应服务端契约、权限和数据模型稳定后发布；原型中的完整 WMS、海外仓及未确认能力不属于国内货柜履约默认范围。
 ## 局部阻断项
 - PDA 采用 uni-app 开发并支持在线更新；Android 广播扫描已接入。设备型号不构成开发、发布或验收门禁；扫描适配保持厂商无关，按既定发布安排完成常规真机验收。
 - 未冻结的字段、权限码、错误码、迁移方案或跨服务调用，只阻断依赖它们的模块；不得以模拟成功或前端猜测替代服务端契约。
 - 修改任一跨服务契约时，必须同步检查生产者、调用方、OpenAPI、权限、迁移脚本和实际前端消费者。
 ## 使用方式
 1. 先读 `README.md`、`国内货柜履约需求确认表.md` 和本文件，确认任务属于已确认范围。
 2. 再进入目标应用或服务的 `AGENTS.md`，按本地模块入口实现。
 3. 发现新的产品决策或门禁变化时，先更新确认表与本文，再更新受影响模块指引；不要将短期进度、联调故障或环境地址写回模块规则。
@@ -0,0 +1,69 @@
 # 国内货柜履约装柜闭环产品确认表
 > **历史版本声明（2026-09-24）**：本文仅保留 2026-08-08 的原始讨论记录，其中“装柜完成即结束”和报关/离仓关系等内容已被当前流程替代。当前规则以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和最新需求确认表为准：`LOADED` 只表示物理装柜完成；正式报关在装柜完成后按最终实装清单执行，放行回执参与 `DEPARTED_WAREHOUSE` 离仓门禁。
 > 确认方式：产品只需在“产品确认”一列填写“同意”，或写明修改后的规则。  
 > 会议目标：本表确认后直接进入开发，不再补完整高保真原型。
 ## 一、已经确认
 | 事项 | 已确认结论 |
 |---|---|
 | 是否新增出仓单 | 不新增，全部状态继续放在现有订单列表和订单详情中 |
 | 国内国内货柜履约做到哪里结束 | 国内做到“装柜完成”即结束 |
 | 海外仓状态由谁更新 | 货物到达海外仓后，由海外仓回传；国内人员不能手工确认 |
 | 装柜需要哪些照片 | 空仓、半仓、满仓、锁仓、带锁码照片五类；每类至少 1 张有效照片，同类型允许多张 |
 | 是否填写锁码 | 必填 |
 | PDA 照片来源 | PDA 只允许现场拍照；Admin 可人工上传 |
 | 照片拍错如何处理 | 不硬删除、不覆盖；将错误记录作废并保留原因、操作人和时间 |
 | 什么情况下可以装柜完成 | PDA 拣货完成、五类照片各至少 1 张有效且未作废、锁码填写完成 |
 | PDA 提交方式 | 扫描先保存在本地草稿，员工点击提交时一次批量写入后端，不逐码提交 |
 | PDA 网络要求 | 必须联网；断网不能正式作业或提交，恢复后刷新重试 |
 ## 二、需要产品确认
 | 序号 | 需要确认的问题 | 建议方案 | 产品确认 |
 |---:|---|---|---|
 | 1 | 订单什么时候从“待分柜”变成“装柜中”？ | PDA 人员开始第一个拣货任务时，订单自动变成“装柜中” | 已确认：进入任务即标记“拣货中” |
 | 2 | 什么情况算“PDA 拣货完成”？ | 本柜所有应拣货物都已处理完成；有数量差异、错货或漏货时，必须先处理异常 | 部分确认：未完成项必须填写异常原因并挂起，不能完成；多人协作和最终复核口径待确认 |
 | 3 | 是否允许部分拣货或跳过货物？ | 允许暂时部分拣货或跳过，但异常未处理完时不能提交“装柜完成” | 已确认 |
 | 4 | 五类照片在 PDA 和 Admin 分别如何采集？ | PDA 只允许现场拍摄；Admin 可人工上传 | 已确认 |
 | 5 | 照片拍错后能否重新拍？ | 同类型允许多张追加；错误或重复照片作废并保留审计，不硬删除、不替换历史记录 | 已确认 |
 | 6 | 锁码录错后如何处理？ | 装柜完成前可修改；装柜完成后必须由有权限的人员发起更正，并填写原因 | 待确认 |
 | 7 | 是否需要后台人员再次审核照片？ | 建议不增加二次审核；PDA 提交后系统检查完整性，符合条件就自动进入“装柜完成” | 待确认 |
 | 8 | 没有完成订舱，能否装柜完成？ | 建议可以，订舱状态只展示，不阻止装柜完成 | 待确认 |
 | 9 | 没有完成拖车预约，能否装柜完成？ | 建议可以，拖车状态只展示，不阻止装柜完成 | 待确认 |
 | 10 | 没有完成报关或取得报关回执，能否装柜完成？ | 建议可以，报关状态只展示，不阻止装柜完成 | 待确认 |
 | 11 | 一个订单是否允许分到多个柜？ | 建议系统保留支持能力；首版是否开放操作，由产品确认实际业务是否存在 | 待确认 |
 | 12 | 一个柜是否允许装多个订单？ | 建议允许，这是拼柜场景；每个订单都要能查到所属柜次和装载数量 | 待确认 |
 | 13 | 一个订单分到多个柜时，什么时候算订单“装柜完成”？ | 建议该订单关联的所有柜次都完成装柜后，订单才显示“装柜完成” | 待确认 |
 | 14 | 装柜完成后发现错柜、错照片或错锁码，由谁更正？ | 建议只有平台指定角色可以更正，必须填写原因并保留修改前记录 | 待确认 |
 | 15 | 现有“派送完成”状态是否改名？ | 建议改为“海外仓已收货”，避免误解为国内派送或末端派送 | 待确认 |
 | 16 | 海外仓回传后，国内是否还能更改装柜信息？ | 建议不能直接更改，需走单独异常处理流程，不纳入本次国内货柜履约开发 | 待确认 |
 | 17 | 五类照片需要保存多久？ | 请产品、业务或合规给出期限；未确认前不做自动删除 | 待确认 |
 | 18 | 客户是否可以查看五类装柜照片和锁码？ | 建议客户可查看照片和锁码；如存在内部证据，应明确哪些照片仅平台可见 | 待确认 |
 | 19 | 同一柜次是否允许多人并行拣货？ | 待产品确认任务拆分、数量合并、重复扫描和责任归属；未确认前按单任务单作业员设计，但不固化为不可扩展模型 | 待确认 |
 | 20 | 退出任务或换班时是否释放任务？ | 明确任务占用、草稿保留、接管人和超时释放规则 | 待确认 |
 | 21 | PDA 开发、扫描与发布方式是什么？ | 已确认采用 uni-app 开发并支持在线更新；Android 广播协议已接入，设备型号不构成门禁 | 已确认 |
 | 22 | 批量提交超时或失败时如何提示和重试？ | 建议保留草稿，展示可理解错误；员工刷新后重试，重复提交由幂等键返回原结果 | 待确认 |
 ## 三、页面处理确认
 | 页面 | 建议怎么改 | 产品确认 |
 |---|---|---|
 | 订单列表 | 保留现有页面；保留“待分柜、装柜中、装柜完成”，将“派送完成”按第 15 项调整文案 |  |
 | 订单详情 | 增加柜次、PDA 拣货进度、五类多图证据、有效/作废状态、锁码、未完成原因和操作记录 | 部分确认；Admin 权限和客户可见范围待确认 |
 | PDA | 进入任务即标记拣货中；扫描形成持久化本地草稿，点击提交时批量写后端；五类照片各至少一张、可多张追加，PDA 仅现场拍摄 | 已确认；一柜多人协作仍待确认 |
 | 海外仓回传 | 国内订单中只展示回传结果和时间，不提供手工确认按钮 |  |
 | 独立出仓单页面 | 不新增 |  |
 ## 四、产品最终结论
 | 结论 | 产品填写 |
 |---|---|
 | 是否按本表直接开发 |  |
 | 是否还需要补原型 |  |
 | 本次明确不做的内容 |  |
 | 产品确认人 |  |
 | 确认日期 |  |
@@ -0,0 +1,149 @@
 # 国内货柜履约装柜闭环开发前确认单
 > **历史版本声明（2026-09-24）**：本文是旧版“以 `LOADED` 作为国内履约终点”的开发前确认材料，旧规则已被本轮新流程替代。当前按三大业务块梳理；`LOADED` 只表示物理装柜完成，正式报关在装柜完成后按最终实装清单执行，放行回执、订舱、拖车和异常门禁用于推进 `DEPARTED_WAREHOUSE`。费用确认不阻断装柜，当前有效已发布费用版本在 `LOADED` 时按已装载范围默认确认。开发以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和当前确认记录为准。
 > 整理日期：2026-08-08  
 > 用途：产品、业务、仓库、研发在直接开发前确认最小闭环细节  
 > 当前建议：不补完整高保真原型，确认本清单后直接开发
 ## 一、已确认，不再重复讨论
 1. 国内货柜履约不新增独立出仓单，现有订单列表和订单详情承载国内货柜履约主状态。
 2. 国内国内货柜履约终点为 `LOADED`/装柜完成。
 3. `DELIVERED` 只能在货物到达海外仓后由海外仓可信回传推进，国内 Admin/PDA 不提供手工操作。
 4. 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少提交 1 张有效真实图片，可同类型多张追加；带锁码照同时填写锁码文本。
 5. PDA 只能现场拍照，Admin 可人工上传；错图不硬删除，以作废记录保留原因、操作人和时间。
 6. PDA 正式作业必须联网；进入任务即标记“拣货中”，扫描先形成持久化本地草稿，点击提交时一次批量写入后端。
 7. 重复提交返回原结果；版本冲突提示员工刷新重试。部分拣货或跳拣必须逐项填写异常原因，未解决前不能完成任务或进入 `LOADED`。
 ## 二、建议采用的最小闭环
 ```text
 WAIT_SPLIT / 待分柜
  -> 确认订单与柜次关系
  -> 下发并开始 PDA 拣货任务
 LOADING / 装柜中
  -> 拣货完成
  -> 五类证据各至少一张有效图片真实上传并取得 fileId
  -> 锁码文本保存
  -> 服务端门禁校验
 LOADED / 装柜完成
  -> 国内只读，允许授权冲正
  -> 海外仓可信回传
 DELIVERED / 海外仓已收货
 ```
 订单主状态只表达阶段结果。排柜、订舱、拖车、拣货、装柜证据和报关使用关联子状态，不扩展成多个重复主单。
 ## 三、仍待产品确认
 | 编号 | 需要确认 | 建议默认方案 | 不确认的影响 | 产品结论 |
 |---|---|---|---|---|
 | C1 | `LOADING` 在什么时点触发？ | PDA 作业员进入任务时自动标记“拣货中”；仅确认排柜不进入 `LOADING` | 订单状态可能提前或延后 | 已确认 |
 | C2 | “拣货完成”如何判定？ | 柜次下全部必拣明细达到完成态，数量差异已处理或完成授权复核 | 可能绕过未拣货物进入装柜完成 | 待填写 |
 | C3 | 是否允许部分拣货、跳拣？ | 允许；每个未完成项必须填写异常原因，任务挂起待处理，不能完成装柜 | 异常任务无法收口或被错误放行 | 已确认 |
 | C4 | 照片是否允许从相册选择？ | PDA 只允许现场拍照；Admin 可人工上传 | 影响 PDA 交互和真实性校验 | 已确认 |
 | C5 | 同类型照片能否替换？ | 同类型允许多张追加；错误/重复照片作废并保留审计，不硬删除、不替换历史记录 | 证据可能被无痕覆盖 | 已确认 |
 | C6 | 锁码格式和唯一性规则是什么？ | 去除首尾空格，按原值保存；同一有效柜次不可重复，是否限定长度/字符由业务确认 | 无法稳定校验重复或录入错误 | 待填写 |
 | C7 | 谁触发 `LOADED`？ | PDA 点击“完成装柜”后由服务端自动校验并推进，不要求 Admin 二次确认 | 若增加二次确认，需要新增待复核状态、权限和操作页 | 待填写 |
 | C8 | 订舱、拖车、报关是否是 `LOADED` 硬门禁？ | 首版均作为关联信息，不阻断 `LOADED`；以后按配置加入门禁 | 直接影响服务端门禁和验收范围 | 待填写 |
 | C9 | 装柜完成后谁可以冲正？ | 仅平台授权角色；原因必填，保留原证据和反向审计事件 | 错照、错锁码、错柜无法合规修正 | 待填写 |
 | C10 | 一单多柜、拼柜、拆批首版开放哪些操作？ | 数据关系支持多对多，首版页面只开放业务确认的高频场景 | 决定订单何时整体进入 `LOADED` | 待填写 |
 | C11 | 海外仓回传后的用户文案是什么？ | 将现有“派送完成”改为“海外仓已收货”，展示来源和回传时间 | “派送完成”容易与末端派送混淆 | 待填写 |
 | C12 | 五类照片保存多久、哪些角色可查看？ | 沿用文件服务权限隔离；留存期限由业务/合规确认 | 影响存储、清理和审计策略 | 待填写 |
 ## 四、直接开发的交互细节
 ### 4.1 PDA 装柜取证
 - 拣货完成后进入装柜取证步骤，固定展示五类证据，不允许用户自定义图片类型；每类至少 1 张有效照片，可追加多张。
 - PDA 仅允许调用相机现场拍摄，不提供相册选择；Admin 人工上传属于独立受权入口。
 - 每张照片独立显示未拍摄、上传中、上传失败、上传成功或已作废；上传失败可单张重试。
 - 上传成功以服务端返回 `fileId` 为准，本地临时路径不能作为业务证据。
 - 带锁码照片和锁码文本同时存在才算该项完成。
 - 提交时 PDA 做一次完整性提示，服务端再做权威门禁校验。
 - 错误或重复照片不得硬删除，作废时记录原因、操作人和时间。
 - 重复点击、网络重试和前后台切换不得产生重复状态迁移；同类型正常追加的多张照片都是独立有效证据，不按“单槽位替换”去重。
 ### 4.2 PDA 拣货提交
 - 正式作业必须联网；断网时不能进入正式拣货、提交、完成任务或推进 `LOADED`，恢复网络后由员工刷新重试。
 - 进入任务即调用服务端开始动作，并标记为“拣货中”。
 - 扫码过程只更新本地草稿；草稿绑定作业员、任务和柜次并持久化到设备，不能被其他账号继承。
 - 仅在员工点击提交时，将本次草稿的全部明细批量写入后端；成功后清理草稿，明确放弃时按权限和确认流程清理。
 - 提交使用轻量不可见幂等键和服务端版本；重复提交返回原结果，版本冲突提示员工刷新后重试。
 - 一柜多人并行、退出/换班时任务是否释放以及最终完成触发人仍待产品确认。
 - 批量提交超时、后端业务错误和网络恢复后的具体提示、按钮与重试交互仍待产品确认；底层幂等和版本规则不受该交互结论影响。
 ### 4.3 Admin 订单详情
 - 在现有订单详情增加“国内货柜履约作业”区域，不新增出仓单详情。
 - 展示柜次、柜号、拣货进度、五类证据、锁码、各子流程摘要和整体时间线。
 - 门禁未通过时展示具体阻塞项，例如“半仓照未上传”“拣货差异待复核”。
 - `LOADED` 后隐藏普通编辑动作，仅授权角色可发起冲正。
 - `DELIVERED` 显示海外仓回传来源、业务时间、接收时间和回传结果，国内端只读。
 ### 4.4 订单列表
 - 保留待分柜、装柜中、装柜完成等现有页签。
 - 原“派送完成”按 C11 的最终结论调整文案，但底层兼容状态可以继续使用 `DELIVERED`。
 - 操作列继续放在第一列；不同状态只展示当前允许的操作。
 - 状态更新失败、权限不足或版本冲突时不得在前端模拟成功。
 ## 五、服务端最低门禁
 进入 `LOADED` 时至少同时满足：
 - 当前订单/履约状态允许从 `LOADING` 迁移；
 - 订单已关联有效柜次；
 - 柜次拣货任务满足 C2/C3 的最终结论；
 - 五种证据各至少有一条有效且未作废的记录和真实 `fileId`；
 - 锁码文本已保存并满足 C6 的规则；
 - 请求身份、客户、仓库和权限合法；
 - 幂等键未产生冲突，状态版本未过期；
 - C8 最终确认的其他硬门禁均已满足。
 门禁失败时返回稳定错误码和阻塞项清单，不得只返回模糊的“操作失败”。
 ## 六、异常与冲正
 - `LOADED` 前：允许在权限范围内重新拣货、追加拍摄、重传和修改锁码；错图通过作废处理，所有记录保留历史。
 - `LOADED` 后：禁止直接覆盖证据或修改数据库状态，必须发起冲正。
 - 冲正记录原因、申请人、审核/执行人、前后状态、原证据版本和请求关联 ID。
 - 冲正后重新满足门禁才能再次进入 `LOADED`。
 - 已由海外仓回传进入 `DELIVERED` 后，国内冲正是否允许必须单独制定跨业务域处理规则；国内货柜履约当前不提供该操作。
 ## 七、验收用例
 ### 正向
 - 同一真实订单从 `WAIT_SPLIT` 关联柜次、完成 PDA 拣货和五类证据上传，最终进入 `LOADED`。
 - Admin 能追溯柜次、拣货明细、五类多图证据及其有效/作废状态、锁码、操作人和状态时间线。
 - 海外仓合法回传后进入 `DELIVERED`，国内页面只读展示。
 ### 负向
 - 未完成拣货不能进入 `LOADED`。
 - 缺任意一张照片、照片无真实 `fileId` 或缺锁码文本不能进入 `LOADED`。
 - 无权限、跨客户、跨仓库和过期版本请求必须失败。
 - 两个并发完成请求只产生一次有效状态迁移。
 - 网络失败重试不重复创建同一张照片记录；业务主动追加的同类型多张照片允许同时有效。
 - 国内 Admin/PDA 无法手工进入 `DELIVERED`。
 - 伪造、过期、重放或重复的海外仓回传不能重复推进状态。
 ## 八、本次不自动纳入
 - 不新增独立出仓单和对应列表/详情。
 - 不把装船、清关、海外仓入库、海外仓出库和末端派送纳入国内国内货柜履约。
 - 报关、Client 回执和港务信息是否作为国内货柜履约上线必交付，以产品对 P3-Q7/P3-Q8/P3-Q9/P3-Q12 的结论为准。
 - 未确认前，不把订舱、拖车和报关默认设置为 `LOADED` 硬门禁。
 ## 九、会议输出
 产品确认后应形成以下结果：
 1. C1 至 C12 均填写最终结论；不能确认的事项明确排除范围和临时方案。
 2. 更新 `国内货柜履约需求确认表.md` 中对应的 P3-Q2/P3-Q4/P3-Q5/P3-Q6/P3-Q10/P3-Q11/P3-Q12。
 3. 明确是否允许按“服务端门禁 -> PDA -> Admin -> 联调验收”的顺序直接开发。
 4. 将本清单作为接口、页面和测试验收的共同依据。
@@ -0,0 +1,244 @@
 # 虫虫出海国内货柜履约闭环审计报告
 > **历史记录声明（2026-09-24）**：本文记录的是 2026-08-08 的旧口径和旧审计结论，不再作为当前流程或开发门禁依据。当前统一采用三大业务块和“装柜完成后正式报关”的新流程：`LOADED` 只确认物理装柜完成；装柜完成后按最终实装清单正式报送，取得有效回执/放行结果后，结合订舱、拖车和异常门禁推进 `DEPARTED_WAREHOUSE`。费用确认不阻断装柜，装柜完成时对当前有效已发布版本按已装载范围默认确认。当前规则以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和本轮确认记录为准。
 > 审计日期：2026-08-08
 > 审计范围：入库测量与计费终点→智能排柜→订舱→拖车→PDA 拣货→装柜/柜封证据→`LOADED`/装柜完成
 > 审计对象：Admin、Client、PDA、`baiyue-firstleg` 后端、OpenAPI/SQL、自动化测试与现有测试环境报告
 > 结论：**NO-GO，当前不能按“国内货柜履约业务闭环”验收**
 ## 1. 执行摘要
 当前已实现多个真实持久化的国内货柜履约子能力，不是纯页面原型：智能装柜/预装、订舱、拖车、PDA 拣货接口、装柜证据元数据和装柜清单均已有后端实现，订舱和拖车 API 也已在测试环境完成独立生命周期验证。
 用户已于 2026-08-08 确认：**国内货柜履约不新建独立出仓单，现有订单列表就是主流程承载面；国内国内货柜履约以 `LOADED`/装柜完成为终点**。`DELIVERED`/派送完成只能在货物到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围。因此“没有出仓单”不再是缺口；真正的缺口是现有订单与柜次、订舱、拖车、拣货、装柜证据和报关子流程尚未统一编排，服务端也没有为进入 `LOADED` 提供组合门禁。
 最重要的判断是：
 - **已经做出了“排柜到装柜清单”的技术子链路。**
 - **订舱和拖车是可独立运行的业务模块，但尚未与出仓主链强绑定。**
 - **报关资料/补件/代理提交/回执/客户下载基本未建模。**
 - **现有订单进入 `LOADED` 的统一门禁和冲正尚未闭合；平台手工推进 `DELIVERED` 的现有接口与最新业务边界冲突。**
 - **Client 没有国内货柜履约协同入口，PDA 仍是演示数据与真实接口混合，尚未完成真实身份、任务领取、文件上传和真机验收。**
 ## 2. 闭环判定口径
 本次不以“有页面”、“有 Controller”或“单模块测试全绿”作为闭环标准。国内货柜履约只有同时满足以下条件才算闭环：
 1. 同一个真实客户订单能从入库测量与计费终点 `WAIT_SPLIT + APPROVED + CONFIRMED` 进入国内货柜履约。
 2. 同一订单可追溯所属柜次、排柜方案、订舱、拖车、拣货、装柜证据、报关文件与回执。
 3. 服务端独立校验所有强制前置，不能靠页面按钮顺序保证。
 4. 弱网、重复提交、并发、越权、证据缺失和冲正均有明确行为和审计记录。
 5. Admin、Client、PDA 都能用真实身份和真实数据完成各自职责。
 6. 订单能在服务端门禁通过后进入 `LOADED`/装柜完成；国内端不能手工推进 `DELIVERED`。
 7. 有一条测试环境证据，让同一业务对象贯穿全流程，并完成负向门禁验证。
 ## 3. 国内货柜履约业务矩阵
 | 环节 | 当前能力 | 审计结论 | 主要缺口 | 优先级 |
 |---|---|---|---|---|
 | 入库测量与计费入口 | 统一订单已有 `WAIT_SPLIT` 投影 | 部分具备 | 没有一条验收数据从入库测量与计费贯穿到国内货柜履约终点 | P0 |
 | 订单国内货柜履约主编排 | 订单列表已承载待分柜、装柜中、装柜完成等状态 | 部分具备 | 无订单级统一门禁、子流程关联和整体时间线；不需新建出仓单 | P0 |
 | 智能排柜 | 有容量型推荐、预装和持久化 | 部分具备 | 无业务硬约束/软偏好规则版本、冲突解释、独立方案确认和版本对比 | P0 |
 | 订舱/船期 | 后端生命周期可用，测试环境 API 已通过 | 部分具备 | Admin 创建/版本/返回 DTO 存在契约错配；未与订单/柜次强关联；无数据来源和时效语义 | P0 |
 | 拖车预约 | 后端和 Admin 正式模块已存在，API 生命周期已验证 | 部分具备 | 与订单国内货柜履约编排未汇聚；前端需手填多个关联 ID；附件上传未接入；幂等重放不完整 | P0 |
 | PDA 拣货 | 有柜次级拣货服务和入库单级汇总接口 | 部分具备 | 两套语义可互相绕过；无领取/分配/复核/异常挂起/撤销闭环；未校验实时处理单元与库位量 | P0 |
 | 装柜/柜封证据 | 有证据元数据和 File 归属校验 | 部分具备 | 已确认空仓、半仓、满仓、锁仓、带锁码照共 5 张必传，锁码文本必填；当前 Admin/PDA 真实文件上传和服务端硬门禁未实现 | P0 |
 | 客户上传报关资料 | Client 无正式入口 | **未具备** | 无清单版本、上传、补件、进度和客户隔离契约 | P0 |
 | 平台报关协同 | 仅有历史文档类型占位 | **未具备** | 无审核退回、补件、代理提交批次、文件版本冻结 | P0 |
 | 回执上传/客户下载 | 无业务模型和页面 | **未具备** | 无回执类型、版本、可见范围、下载授权和门禁关联 | P0 |
 | 出仓后港务/船节点查询 | 订舱实体有 ETD/ETA、船名航次等字段 | 已重新归入海外仓业务 | 本历史审计发现的来源、更新时间、过期标识和客户查询端缺口由海外仓业务承接，不再作为国内货柜履约闭环缺口 | 海外仓业务 |
 | 装柜完成门禁 | 有 `LOADING -> LOADED`，但当前可无证据完成 | **未具备** | 未强制校验 PDA 拣货、5 张真实图片和锁码文本；无冲正 | P0 |
 | 海外仓回传边界 | 有平台手工 `DELIVERED` 动作 | **契约冲突** | 国内端可手工推进派送完成；缺海外仓可信来源、签名、防重放、幂等和审计契约 | P0/跨业务域 |
 | 客户国内货柜履约可见性 | 订单详情有拣货/装柜少量只读摘要 | 严重不足 | 无柜次、报关、回执、船期变更时间线 | P0 |
 ## 4. 核心阻断项
 ### P0-1：现有订单缺少国内货柜履约统一编排和服务端门禁
 产品已确认不新建独立出仓单，因此应复用现有订单作为国内货柜履约主对象，柜次作为多订单共享的执行对象。当前问题不是少一张单，而是订单状态与各子流程尚未由统一编排器计算。
 当前实际是四条彼此独立的状态链：
 ```text
 装柜计划：EDITING -> LOADING -> COMPLETED
 订单国内国内货柜履约：WAIT_SPLIT -> LOADING -> LOADED
 海外仓后续回传：LOADED -> DELIVERED
 订舱：DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED
 拖车：DRAFT -> ... -> DEPARTED -> COMPLETED
 ```
 订单上没有一个汇聚节点计算“是否可进入下一状态”，因此即使四条链各自通过，也不等于国内货柜履约闭环。应在现有订单/入库履约聚合上增加统一编排，不应新建重复的出仓单业务对象。
 ### P0-2：装柜完成可绕过拣货和柜封证据
 `LoadingDeliveryService` 在类注释中明确声明“不检查证据完整度，不阻断业务流转”。`completeLoading` 只校验当前状态为 `LOADING`，没有校验：
 - 柜次级拣货是否全部复核完成；
 - 入库单级汇总拣货是否与柜次明细一致；
 - 空仓、半仓、满仓、锁仓、带锁码照 5 张必传图片及锁码文本是否齐全；
 - 铅封号是否重复；
 - 订舱、拖车和报关是否属于进入 `LOADED` 的硬门禁（P3-Q11/P3-Q12 尚待确认）。
 现有单元测试 `completesLoadingWithoutEvidenceGate` 还把“无证据也可完成”固化成预期，与国内货柜履约规划直接冲突。
 ### P0-3：国内端可手工推进海外仓状态
 当前存在平台手工完成派送的 `POST /delivery/complete` 能力，但最新业务确认是：只有货物到达海外仓后，才能由海外仓可信回传推进 `DELIVERED`。因此该操作必须从国内 Admin/PDA 的国内货柜履约入口移除或禁用；后续海外仓回传接口需单独定义来源认证、签名/时间窗、防重放、幂等和审计。该接口整改是状态边界修复，但海外仓业务本身不纳入国内货柜履约验收。
 ### P0-4：报关协同和回执链路未实现
 当前未找到以下业务对象和契约：
 - 按国家/渠道/货物类型选择的报关资料清单及版本；
 - 客户上传、替换、补件和进度；
 - 平台完整性审核、退回原因和截止时间；
 - 提交报关代理批次及文件版本冻结；
 - 接收/申报/退单/查验/放行等回执类型；
 - 客户可见范围和授权下载；
 - 回执或海关放行与装柜完成门禁的关系。
 数据库中的 `CUSTOMS_CLEARANCE` 文档类型只是占位，不构成业务闭环。
 ### P0-5：Admin 的后半程组件未装配，订舱 UI 与后端契约错配
 - `UnifiedOrderWorkflowPanel.vue` 已有排柜、拣货、证据和完成装柜交互，但对应作业页未注册到正式路由，统一订单详情也未引用该组件。
 - Admin 现有订单详情没有正式的报关、回执和后程门禁操作面板。
 - 订舱新建页把 `expectedVersion` 初始化为 `null`，而后端创建请求要求非空且大于等于 0。
 - 后端创建订舱返回 Detail 对象，前端 API 按字符串解包并直接用作路由 ID。
 - 订舱状态操作在前端统一用 edit 权限，后端对 submit/confirm/release/change/cancel 使用独立权限和特定 DTO。
 测试环境订舱 API 23/23 通过，证明后端模块可用；上述问题说明浏览器端真实操作仍需独立验收。
 ### P0-6：Client 和 PDA 没有形成真实角色闭环
 Client 只在头程订单详情中显示“拣货进度”和“装柜资料”摘要，没有报关上传/补件、回执下载、船期变更和柜次时间线。
 PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在：
 - 登录使用演示账号，Token、客户和 API Base 由本地选项注入，不是真实仓库作业身份；
 - 任务列表和页面仍保留演示数据与本地成功分支；
 - 拍照后把本地临时路径放进 `fileName`，未先上传 File 服务获得 `fileId`；
 - 无任务领取/作业员分配/后台复核闭环；
 - 无可验证的 Android/HBuilderX 构建命令，未做真机连续扫码、断网重连、前后台切换和重复提交验收。
 ## 5. 已实现且可保留的能力
 本次 NO-GO 不代表国内货柜履约必须重做。以下能力已有明确复用价值：
 - 柜次、智能装柜、预装和装柜清单的持久化模型。
 - 订舱 `DRAFT -> SUBMITTED -> CONFIRMED -> RELEASED` 生命周期、历史和幂等。
 - 拖车从草稿到完成的状态、历史和附件后端能力。
 - 柜次级 PDA 明细拣货、部分拣货和跳过与防重操作。
 - 装柜证据文件归属校验、业务历史、乐观锁和部分幂等基础。
 - Admin 订舱和拖车页面壳、统一订单后半程组件。
 - Client 对统一订单国内货柜履约只读摘要的兼容映射。
 ## 6. 需求确认项重新定性
 `P3-Q6`、`P3-Q13` 和“不新建独立出仓单”已经确认，其余事项仍需按影响范围继续确认。结合现代码，可重新定性为：
 | 编号 | 当前代码事实 | 审计定性 |
 |---|---|---|
 | P3-Q1 排柜规则 | 仅基础容量贪心推荐 | 仍为 P0 产品/业务阻断 |
 | P3-Q2 拼柜/一单多柜/拆批 | 已确认不新建出仓单；拼柜和拆批应由订单-柜次关系表达 | 仍需确认具体可开放场景 |
 | P3-Q3 “拖车”用词 | 代码已统一使用拖车 | 可直接确认，非阻断 |
 | P3-Q4 PDA 设备 | 有广播适配，无目标设备和真机验收 | 仍为上线阻断 |
 | P3-Q5 实时库存/库位 | `locationIds` 未进入服务业务校验 | 仍为 P0 流程阻断 |
 | P3-Q6 柜封照片 | 已确认 5 张必传：空仓、半仓、满仓、锁仓、带锁码照；锁码文本必填 | 需实现文件上传与服务端硬门禁 |
 | P3-Q7/Q8/Q12 报关 | 业务模型未实现 | 仍为 P0 范围和契约阻断 |
 | P3-Q9 港务 | 仅有订舱船期字段 | 仍为 P1，但必须在客户展示前确认 |
 | P3-Q10 冲正 | 无 reverse 动作 | 仍为 P0 高风险状态阻断 |
 | P3-Q11 强制前置/并行 | 子模块彼此独立 | 仍为 P0 统一门禁阻断 |
 | P3-Q13 国内货柜履约终点 | 已确认国内终点为 `LOADED`；`DELIVERED` 由海外仓回传 | 已解除范围阻断；需整改国内手工派送接口 |
 ## 7. 自动化和环境证据
 ### 7.1 本次实际执行
 | 项目 | 命令 | 结果 |
 |---|---|---|
 | Admin | `pnpm test` | 80 个测试文件，418 项通过 |
 | Admin | `pnpm build` | 通过，包含 TypeScript 检查 |
 | Client | `pnpm test` | 176 项通过 |
 | Client | `pnpm build` | 通过，包含 TypeScript 检查 |
 | PDA | `node --test tests/*.test.mjs` | 32 项通过 |
 | Backend | `.\scripts\backend-full-regression.ps1` | Reactor 成功；最终 firstleg 报告 391 项、0 失败、0 错误、2 跳过 |
 ### 7.2 已有测试环境证据
 `reports/admin-test-env-acceptance-all-green-20260808.json` 记录 Gateway `http://8.163.30.128:9000` 的 549/549 项通过，其中订舱 23 项、拖车 43 项、service-center-flow 10 项。这证明已部署子模块的 API 生命周期可用。
 `docs/入库测量与计费及国内货柜履约业务功能测试回归报告.md` 在 2026-08-07 将“国内货柜履约结果”写为通过，但其明确的国内货柜履约测试范围只有：虚拟柜、智能装柜、预装、PDA 拣货和最终装柜清单。该结论应改名为“国内货柜履约装柜子链路通过”，不应作为整期闭环证据。
 ### 7.3 测试缺口
 当前缺少以下验收证据：
 - 同一订单从入库测量与计费 `WAIT_SPLIT` 贯穿到国内货柜履约终点。
 - 订舱、拖车、柜次、拣货、证据和报关关联到同一批订单/柜次。
 - 未完成 PDA 拣货、缺任意一张必传照片或缺锁码文本时，进入 `LOADED` 必须失败。
 - 若 P3-Q11/P3-Q12 将订舱、拖车或报关确认为硬门禁，对应前置未满足时进入 `LOADED` 必须失败。
 - 两个并发装柜完成请求只产生一次状态迁移和一条有效审计事件。
 - 装柜完成后冲正不直接篡改旧状态，且有反向审计记录。
 - 国内 Admin/PDA 无法手工进入 `DELIVERED`；伪造、重放或重复的海外仓回传不能重复推进状态。
 - 客户 A 无法查看、上传或下载客户 B 的报关文件与回执。
 - PDA 真实设备弱网、连续扫描、重复扫码、前后台切换和重复提交。
 ## 8. 建议修复顺序
 ### 里程碑 A：锁定业务契约（P0）
 1. 由产品/业务对尚未确认的 P3-Q1/Q2/Q5/Q7/Q8/Q10/Q11/Q12 给出最终结论。
 2. 按已确认结论固定国内货柜履约终点为 `LOADED`/装柜完成，并将 `DELIVERED` 移出国内国内货柜履约状态操作。
 3. 定义订舱、拖车和报关中哪些是进入 `LOADED` 的强制前置，哪些允许并行。
 ### 里程碑 B：在现有订单上建立国内货柜履约统一编排与门禁（P0）
 1. 复用现有订单主状态，补齐订单-柜次关联、整体时间线、版本和审计投影，不新建出仓单。
 2. 将排柜、订舱、拖车、拣货、证据和报关子流程绑定到订单/柜次。
 3. 服务端实现装柜完成 `check gate`、`LOADED` 状态推进、冲正和并发/幂等。
 4. 禁止入库单汇总拣货绕过柜次明细拣货与复核。
 ### 里程碑 C：补齐报关与文件闭环（P0）
 1. 建立资料清单版本、客户文件版本、补件、代理提交批次、回执和可见范围。
 2. Client 实现上传/补件/回执下载，Admin 实现审核/退回/提交/回执上传。
 3. Admin/PDA 证据上传必须先经 File 服务获得 `fileId`，不得使用文件名或本地路径代替。
 ### 里程碑 D：接通三端（P0）
 1. 修复 Admin 订舱 DTO/版本/动作权限，将后半程作业页挂到正式路由。
 2. 拖车从可选资源中关联订单、订舱和柜次，不让用户手填 ID。
 3. Client 增加出仓进度、柜次、报关、回执和船期变更。
 4. PDA 接真实仓库身份、任务领取、服务端详情和文件上传，删除正式业务中的演示成功分支。
 ### 里程碑 E：端到端验收（P0）
 1. 使用一个独立测试客户和一组可追溯订单完成全链路。
 2. 按本报告 7.3 节逐项做负向、权限、并发、幂等和冲正验收。
 3. 在目标 PDA 真机上完成弱网与扫码验收。
 4. 输出包含订单 ID、柜次 ID、订舱 ID、拖车 ID、证据 ID、报关批次 ID、`LOADED` 状态和审计事件的验收报告。
 ## 9. GO 准入标准
 以下条件全部满足后，才建议将国内货柜履约从 NO-GO 改为 GO：
 - [ ] P3-Q1至P3-Q13 已有明确结论，文档与代码口径一致。
 - [ ] 现有订单可通过柜次追溯全部国内货柜履约子流程。
 - [ ] 装柜完成门禁在服务端生效，缺 PDA 拣货、任一必传照片或锁码文本时不能进入 `LOADED`。
 - [ ] 报关资料、补件、代理提交、回执和客户下载闭环。
 - [ ] Admin 所有国内货柜履约正式入口可达，前后端 DTO 和权限一致。
 - [ ] Client 只能访问当前客户的国内货柜履约数据和文件。
 - [ ] PDA 真实鉴权、任务、扫码、文件上传、弱网和重试已真机通过。
 - [ ] 装柜完成后进入 `LOADED` 并支持授权冲正，国内端不能手工推进 `DELIVERED`。
 - [ ] 同一测试订单完成全链路正向与负向验收，证据可重放。
 ## 10. 最终结论
 当前国内货柜履约建议对外口径为：
 > **国内货柜履约已确认复用现有订单列表承载全部主状态，不新建出仓单，国内终点为 `LOADED`/装柜完成；已完成排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车 API 可用。但订单国内货柜履约统一编排、五张装柜照片与锁码文本硬门禁、报关协同、冲正、Client 协同和 PDA 真机仍未闭环，且国内手工推进 `DELIVERED` 的现有能力必须整改，当前不具备整期验收条件。**
 因此，现阶段不应标记“国内货柜履约完成”，应标记为“**子能力已实现，闭环整改中**”。
@@ -0,0 +1,36 @@
 # 国内货柜履约验收任务拆分与待确认清单
 > 更新日期：2026-08-10
 > 本清单只描述真实 HTTP/设备验收边界，不把原型或 mock 结果视为通过。
 ## 已纳入真实 HTTP 验收
 | 任务 | 真实断言 | 脚本入口 |
 |---|---|---|
 | PDA 进入任务 | 领取后服务端任务立即进入 `IN_PROGRESS`，并绑定当前作业员 | `phase3-container-loading.mjs` |
 | PDA 拣货提交 | 明细数量、重复扫码、旧版本冲突、`operationId` 幂等及复核完成态 | `phase3-container-loading.mjs` |
 | 五类装柜证据 | 空仓、半仓、满仓、锁仓、带锁码照均上传真实文件并按客户/柜次绑定 | `phase3-loading.mjs` |
 | 同类型多图 | 同一证据类型追加第二张真实图片，原记录与新增记录同时保持有效 | `phase3-loading.mjs` |
 | 锁码门禁 | 缺少锁码照片或锁码文本为空时，完成装柜请求被拒绝 | `phase3-loading.mjs` |
 | 统一装柜门禁 | 真实柜号缺失、PDA 未完成、数量不守恒或五类证据不完整时，真实 `LOADED` 请求被拒绝；`LOADED` 后分别验收客户报关回执确认闭环和送港/进港/甩柜事实，任何一条线都不反向阻断物理装柜 | `service-center-flow.mjs` / `phase3-loading.mjs` |
 | 订单/柜次聚合 | 一单多柜、一个柜多订单、父子订单数量分摊及未装数量自动生成子订单可追溯 | `phase3-order-aggregate.mjs`（待补） |
 | 实际开船后船节点查询 | 只有承运船舶真实开航后才进入海运节点；送港、进港和甩柜属于国内货柜履约并行线 | 海外仓业务沿用现有 `CarrierScheduleQuery` 设计验收入口，不再用预计 ETD 或 `DEPARTED_WAREHOUSE` 提前推进海运 |
 | 仓库角色 | 操作员、拣货员、理货员初始化、最小权限和跨客户隔离 | `phase3-role-contract.mjs`（待补） |
 | 伪造与交叉归属 | 不存在 `fileId`、其他证据类型的 `fileId` 不能绑定 | `phase3-loading.mjs` |
 ## 保留 coverageGap 的确认项
 | 编号 | 待确认/待环境能力 | 保留原因 | 解除条件 |
 |---|---|---|---|
 | P3-PDA-D01 | PDA 断网、恢复网络和真机在线限制 | HTTP 验收器无法模拟设备网络与现场相机 | 按既定 uni-app 发布安排在目标设备执行真机脚本 |
 | P3-PDA-D03/D04 | 设备持久化草稿、批量提交、跨账号隔离 | 当前公开服务未提供稳定的设备草稿/批量提交 HTTP 契约 | 固定草稿 DTO、提交端点、幂等键、版本字段和清理语义 |
 ## 并行任务拆分
 1. `P3-ACCEPT-PDA-ONLINE`：PDA 真机在线/断网/前后台验收。
 2. `P3-ACCEPT-PDA-DRAFT`：草稿持久化、批量提交、幂等、版本冲突和跨账号隔离验收。
 3. `P3-ACCEPT-EVIDENCE-VOID`：五类证据多图追加、作废、锁码文本和 `LOADED` 门禁验收。
 4. `P3-ACCEPT-PDA-RELEASE`：按既定 uni-app 在线更新安排完成发布与真机验收。
 每个任务完成后，必须把真实请求、响应状态、业务码、`requestId/traceId` 写入报告，并删除对应 coverageGap；不得以 mock 或数据库直写替代接口验收。
@@ -0,0 +1,45 @@
 # 货柜履约原型字段验收矩阵
 > 更新时间：2026-08-18
 > 范围：货柜、预装/装柜清单、订舱、船期、拖车、报关协同与国内出仓列表。
 > 口径：原型只提供字段与交互参考；当前确认契约、后端 DTO/OpenAPI 和已落地 Admin 优先。`UNKNOWN` 不生成假值、不改名借用其他字段，也不以空值通过验收。
 ## 跨列表统一门禁
 - 操作列必须是第一业务列并固定左侧；原型中拖车、预装把操作列放在末尾的布局由当前统一表格规则覆盖。
 - 平台内部业务单号统一为 `前缀-YYMMDD-NNNN`，按北京时间创建日、单据类型分别从 `0001` 递增：订舱 `OB`、派车单 `TA`、内部货柜登记 `CB`、稳定柜次 `CAB`、预装/装柜清单 `LP`。预装确认后沿用同一 `LP` 编号，不因状态变化更换身份；真实集装箱号、提单号等外部编号不适用本规则。
 - `柜号/cabinetNo` 是平台稳定柜次编号，`集装箱号/containerNo` 是真实物理柜号，两者不得互换。模拟柜可以没有 `containerNo`，真实柜、完成装柜清单和国内出仓聚合必须有。
 - 客户、仓库、渠道、船公司、订舱/拖车/报关供应商名称只能来自服务端冻结快照或正式主数据，不由 fixture 自造名称。
 - ID 使用正整数；数量、重量和体积为非负数；关键时间必须可按 ISO-8601 解析；有供应商 ID 时名称必须非空，无 ID 时不得伪造名称。
 - 文件、异常、轨迹只在正式聚合提供摘要时断言；原型出现但 DTO 未提供的摘要登记为 `UNKNOWN`。
 ## 列表逐字段矩阵
 | 列表 | 原型字段 | Admin 当前列 | 后端事实字段 | 真实 fixture 来源 | 结论 |
 |---|---|---|---|---|---|
 | 货柜 | 操作、集装箱号、装柜清单号、状态、异常、柜号、清关/DO/PU、车队、仓库、提单、船名航次、箱型、船公司、港口、容量、装柜/开船/到港时间 | 操作第一且左固定；柜号、订舱、集装箱号、状态、仓库、车队、提单、航线、箱型、容量、船名航次、船公司及关键时间 | `ContainerBookingEntity` 的稳定身份、来源/记录状态、客户/仓库/渠道、订舱、规格、运输及 `planId/planStatus`；overview 承载异常、单证、轨迹 | `phase3-container-loading` 本轮模拟柜在港口取得真实柜号后按订舱需求原地关联的 ACTIVE 唯一行 | `LANDED_STATIC`；清关/DO/PU、异常、轨迹摘要不在列表 DTO，见 UNKNOWN |
 | 预装清单 | 预装单号、集装箱号、柜号、客户、仓库、船名航次、箱型、状态、SKU数、总件数、体积、重量、创建时间、操作 | 操作第一且左固定；其余列与原型一致 | `PreloadSummary` 全部对应字段及 readiness/version | 同 marker 智能排货、push-preload、真实柜合并和计划级确认 | `LANDED`；“总件数”按当前契约解释为 `totalPackageCount` |
 | 装柜清单 | 操作、仓库、清单号、集装箱号、柜号、状态、总箱/毛重/净重/体积/数量、备注、创建人/时间 | 操作第一且左固定；明细分列客户备注、内部备注、仓库备注，仅仓库备注可编辑 | `ConfirmedSummary` 及 `ConfirmedDetail.items/histories`；三备注随 `FirstLegLoadingPlanCompletedV2` 下发 | 同一计划 PDA 完成后生成的 COMPLETED 清单 | `LANDED_STATIC`：仓库备注 EDITING/LOADING PATCH，COMPLETED 只读 |
 | 订舱 | 委托单位、主票号、放舱、MB/L 当事方、港口、箱量、船公司、截关、ETD/ATD/ATA、船名航次、订舱代理、退仓、单号、操作员、状态 | 操作第一且左固定；订舱号、客户、船公司、代理、船名航次、港口、ETD/ETA、状态、更新时间 | `OceanBookingDtos.Detail`：`oceanBooking/parties/containerRequirements/containers/histories`；DRAFT 可部分保存，RELEASED 完整冻结，订舱本身不登记 `containerNo` | `ocean-bookings` 本轮 DRAFT 编辑及完整放舱；港口关联后 `containers` 才回显 allocation | `LANDED_STATIC`；截关/ATD/ATA、退仓公司、操作员未进入当前列表，见 UNKNOWN |
 | 船期 | 原型订舱区域提供船名、航次、港口和关键时间 | 操作第一且左固定；船期号、来源、船名航次、港口、ETD/ETA、观测/更新时间、过期 | `ScheduleView.schedule+expired`，含来源、港口、ETD/ETA、截单/截关/截港、观测和过期时间 | `phase3-port-schedules` 本轮正式订舱关联观测 | `LANDED` |
 | 拖车 | 派车单号、运输公司、司机、车头号、门店、应付/应收、预计装箱、状态、附件、操作 | 操作第一且左固定；预约号、柜号、客户、运输公司、司机、车辆、门店、计划装货、状态、附件、更新时间 | `TruckAppointmentEntity` 及附件端点；客户和 ACTIVE TRUCKING 承运商为必填快照，订舱/柜次/计划/仓库为可选关联；DISPATCH 前强制提单号与有效 `BILL_OF_LADING` | `truck-appointments` 使用同 marker 客户独立开立，覆盖无提单拒绝、正式提单上传及自身状态机 | `LANDED_STATIC`；附件列来自独立附件接口，不伪造实体字段 |
 | 报关协同 | 模块 13 的传统报关/清关表包含订单、客户、状态、资料与时间等历史字段 | 操作第一且左固定；报关编号、订单/入库关联、资料清单及版本、状态、更新时间 | `CustomsCaseEntity` 与聚合详情的 documents/supplements/submissions/receipts/histories | `phase3-customs` 本轮实际订单、入库、柜次及不可变清单版本 | `LANDED_WITH_OVERRIDE`：当前“报关协同”模型覆盖历史原型；客户名和文件摘要见 UNKNOWN |
 | 国内出仓 | 模块 04 为海外末端派送原型，非当前国内出仓门禁模型 | 操作第一且左固定；入库单、客户、柜号、订舱/拖车/PDA 状态、出仓状态、门禁 | `OutboundDispatchDtos.Aggregate/Detail` 的订单、入库、客户、柜次、计划、PDA、订舱、拖车、状态、版本和 gate/timeline | `phase3-outbound-dispatch` 同 marker LOADED 柜次聚合 | `LANDED_WITH_OVERRIDE`：当前确认契约优先；Admin“柜号”列实际绑定 `containerNo`，建议文案校准 |
 ## UNKNOWN 登记
 | 批次 | 字段/摘要 | 当前缺口 | 验收处理 |
 |---|---|---|---|
 | U1 | 货柜列表清关、DO、PU、异常、轨迹摘要 | overview/专项详情有事实，但货柜列表 DTO 未冻结对应摘要字段 | 不向列表脚本注入假摘要；专项 overview 继续验文件下载、异常历史和轨迹 |
 | U1 | 订舱列表截关、ATD、ATA、退仓公司、操作员 | 原型存在，当前列表与 `OceanBookingDtos` 未全部公开 | 不复用 ETA/更新时间代替；待产品确认是否进入列表 |
 | U1 | 报关列表客户名称、文件/补件/回执摘要 | 实体仅有隔离键，聚合详情有文件事实，列表聚合未冻结这些摘要 | 只断言订单/入库/柜次和清单版本；待列表 DTO 冻结 |
 | U2 | 国内出仓“柜号”展示语义 | Admin 列标题为“柜号”，绑定的是物理 `containerNo` | 合同按 `containerNo` 验值；建议 Admin 文案改为“集装箱号”或同时展示 `cabinetNo` |
 | U2 | 清关列表 | 当前目的港清关走货柜 `/clearance` 专项权限/路径，没有独立、已冻结的清关列表 DTO | 继续详情级验收，不猜独立列表接口 |
 ## 自动化接入
 - `fulfillment-list-field-contract.mjs` 提供八类正式响应的非空、ID、数值与时间格式投影；可选字段使用成对约束，不把 UNKNOWN 强制为必填。
 - `phase3-container-loading` 对 ACTIVE 货柜、预装清单和完成装柜清单执行字段断言。
 - `ocean-bookings`、`phase3-port-schedules`、`truck-appointments`、`phase3-customs`、`phase3-outbound-dispatch` 在既有本轮资源响应上执行字段断言，不增加历史查询或伪造回退。
 - 默认 Admin 全量入口已包含上述生产模块；真实 HTTP 仅在测试环境重新部署且当前对话明确授权后执行。
@@ -0,0 +1,222 @@
 # 货柜管理全链验收矩阵
 > 更新时间：2026-08-17
 > 当前任务：`019ff90b-a72d-7000-abdf-e5363357a564`
 > 父任务：`019ff600-f9f1-78f1-a357-7c80c13e574e`
 > 依赖任务：后端主链 `019ff90b-9b45-7191-b68f-c3b52567e3e4`、动态增量后端 `01a00e91-2124-7960-95d6-e0d0f81959f9`、Admin `019ff90b-a037-79b0-b945-8f88bdbde9c5`
 > 边界：只维护根目录脚本、验收文档和测试矩阵；不修改 Admin 或 Java 业务源码，不部署、不触发 Jenkins、不写测试环境数据库。
 ## 验收口径
 - 本矩阵以当前对话、国内货柜履约产品确认版开发规划和实际冻结契约为准。旧确认单中的待确认项不覆盖后续已冻结结论。
 - 已冻结能力按事实来源落具体路径和断言；尚未冻结能力继续只保留能力级占位，不预设 HTTP 方法、路径、DTO 字段或业务错误码。
 - 自动化必须通过业务 API 生成数据；人工验收必须能从 Admin/PDA 可见入口点击到对应状态。不得以数据库直写、mock、原型或前端本地假状态代替。
 - 每次真实 HTTP 验收记录请求用途、响应状态、业务码、`requestId`、`traceId`、关键资源 ID 和清理/保留策略；敏感凭据不得写入报告。
 - 柜态看板不纳入本轮。
 - 列表逐字段来源、格式门禁与 `UNKNOWN` 登记见《货柜履约原型字段验收矩阵-2026-08-17》；任何未冻结字段不得由 fixture 伪造或用其他字段代填。
 ## 状态数据目录
 | 数据代号 | 必备状态/形态 | 生成前置 | 自动化断言 | 人工可点击入口 | 当前状态 |
 |---|---|---|---|---|---|
 | CT-D01 | 订舱 DRAFT 登记柜型需求并最终放舱 | DRAFT 可部分保存/编辑/删除；完整资料含五项运输事实及 `containerRequirements(type/kind/quantity/spec)` | release 完整性校验后进入 `RELEASED` 并冻结；订舱不含 `containerNo`，不生成货柜或 allocation | 订舱列表/详情仅显示 DRAFT、RELEASED | `LANDED_STATIC`，待环境验收 |
 | CT-D02 | 不同渠道各一单 | 渠道主数据可用 | 柜次/清单/任务不得跨渠道混装或串查 | 排柜候选可按渠道辨识 | 待契约 |
 | CT-D03 | 内部模拟柜已排货、已 push，但无真实柜号/订舱 | 正式装柜仓库、ACTIVE 物流渠道、箱型和容量可用 | 服务端生成稳定 `containerBookingId/cabinetNo`；同仓同渠道 WAIT_SPLIT 可排；无号 `push-preload` 成功并冻结明细、建立唯一 bridge、使预装 `EDITING` 可见，但 PDA 查询必须为 `A0404` | 货柜列表可新增模拟柜，预装清单显示待关联/待补号 | 新时序已冻结，待环境验收 |
 | CT-D04 | 港口真实柜号关联、订舱放舱且预装已确认，PDA 可领取 | CT-D03；订舱 `RELEASED`；港口取得唯一 `containerNo`；选择未满配 `requirementId`；预装进入 `CONFIRMED` | link 四字段在原模拟柜上补齐订舱、真实柜号和运输快照并创建 allocation；四元身份稳定，三项前置任缺一项都无 PDA，claim 后才进入 `LOADING` | PDA 任务列表可进入 | `LANDED_STATIC`，待环境验收 |
 | CT-D05 | 作业中更换真实柜号 | CT-D04，PDA 已开始 | 柜号变化但柜次 ID、任务、清单、证据归属不漂移 | 详情与 PDA 同步显示新柜号 | 待契约 |
 | CT-D06 | 预装清单已生成/确认 | CT-D03 | push 后 `EDITING` 清单可补真实柜号；订舱 `RELEASED` 后通过计划级 `/loading-plans/{loadingPlanId}/confirm` 原子确认全部关联预装票据，返回 `confirmationStatus=CONFIRMED`、`readyForPda=true` 和唯一 `pdaTaskId`；版本、明细、数量及确认历史可追溯 | 预装清单列表/详情可点击 | 计划级确认已冻结，待环境验收 |
 | CT-D07 | 装柜清单进行中/已完成 | CT-D04 | 装载明细、数量、状态与预装来源一致 | 装柜清单列表/详情可点击 | 待契约 |
 | CT-D08 | PDA 领取、拣货、复核、异常摘要 | CT-D04 | overview 分别返回 `taskStatus`、`workflowStatus`、任务 ID、版本、计数、`photoCounts`、`photos`、`downloadPath` 和异常原因；逐照片代理下载成功 | PDA 可完成主流程；Admin 入口待回传 | 服务端已冻结；人工入口待定 |
 | CT-D09 | 报关/清关资料及有效回执 | CT-D06 | 目的港清关走货柜 `/clearance`；出口报关走 loading-list `/customs`；分别验证上传、完成和完成后替换锁定 | 报关协同入口待回传 | 服务端已冻结；人工入口待定 |
 | CT-D10 | DO 附件与 PU 码未填、部分完成、全部完成 | 柜次与运输协同已建立 | `DELIVERY_ORDER` 可独立查询、上传和鉴权下载；PU 资料通过 `/pickup-code` 保存 1–64 位数字字符串并保留前导零，均使用版本校验 | 货柜详情在“报关清关信息”一级区块内直接展示 DO 附件与 PU 码输入 | 已按最新确认收敛；待人工截图确认 |
 | CT-D11 | 正常、异常、取消异常 | 任意有效柜次及显式货柜版本 | 标记/取消使用版本和必填原因；overview 保留 `MARK`/`CANCEL` 全部历史 | 货柜详情入口待回传 | 服务端已冻结；人工入口待定 |
 | CT-D12 | 多节点运输轨迹与操作日志 | CT-D10 | overview 时间线含运输更新、异常和 PDA 事件，按发生时间升序 | 详情时间线入口待回传 | 服务端聚合已冻结；人工入口待定 |
 | CT-D13 | PDA 确认装柜并推进 `LOADED` | inbound `LOADING`、bridge、订舱 `RELEASED`、PDA 全拣和五类 ACTIVE 证据齐备；拖车允许缺失、未完成或存在多条 | PDA `complete` 的主事务不以拖车数量/状态为阻断；提交后才在独立事务 best-effort 同步唯一同柜有效拖车。零条直接跳过，一条可推进 `COMPLETED`，多条或拖车并发只隔离记录同步失败，task/plan/inbound 仍保持 `LOADED` | 订单/柜次详情显示完成且编辑锁定；拖车同步失败单独呈现 | `LANDED_STATIC`：OpenAPI、Service、提交后同步隔离与结算版本回归已冻结；待部署后 HTTP 复核 |
 | CT-D14 | PDA 未最终完成前向同一预装计划增加入库单 | 已有稳定 `loadingPlanId/taskId/containerBookingId`，任务尚未最终完成；新增票满足同客户、仓库、渠道、容量与柜型约束 | `EDITING/LOADING` 可增量；`LOADING` 不回退且复用同一 task；plan/task/item 版本递增，旧 inventory token A0409 后必须刷新；全拣后增项将 `AWAITING_REVIEW` 撤回 `IN_PROGRESS`，证据保留；未拣项可删，已拣数量形成 `minPackageCount` | Admin 预装增量入口与 PDA 同步显示新增项 | `LANDED_STATIC`：assign/adjust/delete 与 capability DTO 已冻结并接入脚本；待部署后真实 HTTP 复核 |
 ## 全链验收用例
 | 用例 | 场景 | 服务端/契约断言 | UI/设备断言 | 证据要求 | 状态 |
 |---|---|---|---|---|---|
 | CT-E01 | 模拟柜原地关联 RELEASED 订舱需求 | link 请求为 `oceanBookingId+requirementId+containerNo+expectedVersion`；成功后模拟柜 ID/cabinetNo/计划/明细稳定并新建 allocation，不存在中间真实柜 | 货柜详情只显示关联后的一个可操作身份 | link 前后柜次、计划、明细、allocation 及 ACTIVE 列表唯一性快照 | `LANDED_STATIC`，待环境验收 |
 | CT-E02 | 渠道隔离 | 不同渠道不能进入同一排柜结果；交叉 ID 请求失败 | 候选、清单和详情不串渠道 | 双渠道正向及交叉负向响应 | 待契约 |
 | CT-E03 | 无真实柜号排柜与 push | 临时身份可完成排柜；`push-preload` 在无 `containerNo` 时成功，只冻结计划、建立 bridge、开放 `EDITING` 预装，不创建 PDA；exact replay 原样返回且计划/版本/历史/link/task 零漂移 | 页面明确展示待补号，不伪造柜号 | push 原始 path/body/key、重放前后全快照、PDA `A0404` | 新时序已冻结，待环境验收 |
 | CT-E04 | 四字段关联及三项前置开放 PDA | 无号 push 后仍无 PDA；未关联、订舱未 `RELEASED`、预装未 `CONFIRMED` 分别查询 PDA 均为 `A0404`；关联时录入唯一真实柜号，最后一个前置完成后仅生成一个 task，claim 才推进 `LOADING` | 关联、放舱、确认前后 PDA 入口状态同步 | 三个逐项负向、唯一 task 四元身份、claim 前后状态 | `LANDED_STATIC`，待环境验收 |
 | CT-E05 | 作业中换号身份不漂移 | 只变更展示柜号；柜次 ID、任务 ID、清单、证据关联不变 | Admin/PDA 刷新后显示新号且进度不丢 | 换号前后关联快照 | 待契约 |
 | CT-E06 | 预装/装柜清单 | push 自动生成/关联预装聚合；仅允许按 `loadingPlanId` 原子确认整份计划，禁止旧单票 `/preload/confirming`、`/preload/confirm`；返回唯一 task 后 claim 才进入 `LOADING` | 两类列表和详情均可人工点击 | `PENDING -> EDITING -> CONFIRMED`、计划版本、readiness、taskId、幂等重放与历史 | 计划级确认已冻结，待环境验收 |
 | CT-E07 | PDA 主链 | 领取、扫码、批量提交、复核、完成；幂等与版本冲突有效 | 真机/目标设备可完成，失败不假成功 | 请求链、设备记录 | 待契约 |
 | CT-E08 | PDA 进度异常摘要 | `GET /api/platform/v1/containers/{id}/overview` 返回 PDA `taskStatus/workflowStatus`、任务身份、版本、计数、照片摘要、文件 ID 与鉴权下载路径；每个路径真实 GET 200 | Admin 入口待回传 | overview 响应、字段完整性及二进制下载证据 | 服务端契约已冻结 |
 | CT-E09 | 清关/报关资料闭环 | 目的港清关：货柜 `/clearance` 查询/上传/完成；出口报关：loading-list `/customs` 查询/上传/完成；两者完成后均禁止替换 | Admin 入口待回传 | 两条专用链路的版本、幂等、完成和锁定负向响应 | 服务端契约已冻结 |
 | CT-E10 | DO/PU | 通用查询、multipart 上传、鉴权下载；上传要求 `Idempotency-Key`、真实文件、`expectedVersion`，重放不得重复上传 | Admin 入口待回传 | 两类型响应、文件哈希/ID、二进制下载、幂等重放 | 服务端契约已冻结 |
 | CT-E11 | 货柜异常及取消历史 | `POST/DELETE /api/platform/v1/containers/{id}/exception` 要求 `expectedVersion` 和必填原因；冲突失败；overview 历史只追加不覆盖 | Admin 入口待回传 | 标记/取消响应、版本冲突、overview 历史 | 服务端契约已冻结；版本来源阻断 |
 | CT-E12 | 运输轨迹/日志 | overview `timeline` 聚合 `TRANSPORT_UPDATE`、`MARK/CANCEL`、`PDA_*`，时间升序且含详情、操作者和发生时间 | Admin 入口待回传 | overview 时间线响应 | 服务端契约已冻结 |
 | CT-E13 | PDA complete 与可选拖车隔离 | 同柜零/一/多条拖车均不阻断 complete：零条直接 `LOADED`；唯一有效拖车可在主事务提交后独立推进 `COMPLETED`；多条、错柜或拖车并发失败不得回滚 task/plan/inbound，且不得误改其他拖车；同键重放不新增历史 | PDA 完成页、入库单和订单详情先显示 `LOADED`；拖车详情显示独立同步结果 | 零/一/多条三条链 + 幂等重放；记录 task/plan/inbound/truck 前后版本、历史数量、业务码和 `requestId/traceId` | `LANDED_STATIC`：提交后独立同步、异常隔离及一对多保护已冻结；多 fixture HTTP 待跑 |
 | CT-E19 | PDA 结算导致版本递增后的最终完成 | final complete 前来源 inbound 为 `LOADING`；settle 可能将来源 version 递增并生成全量或部分实装分片 | complete 必须在 settle 后重新锁定实际完成行并使用当前 version，不得复用结算前快照；full/partial 均成功，真实并发仍 A0409，失败 task/plan/inbound/operation/history 零写入 | PDA、计划、入库单和统一订单显示唯一 `LOADED` 事实 | `LANDED_STATIC`：真实缺陷样本 task `2089254643058184193` 已转为 Node/Java 回归；待修复版本部署后 HTTP 复核 |
 | CT-E20 | PDA pending/detail 工作流一致性 | 同一 task 已有唯一 BATCH、明细全为 PICKED、`pendingItemCount=0` | pending 与 detail 均返回 `AWAITING_REVIEW`；允许证据 GET；派生 actions 为空且不再 POST batch | PDA 待办卡片与详情均显示“待人工复核”，进入取证而非重复拣货 | `LANDED_STATIC`：pending SQL 按明细未完成数投影，OpenAPI 已冻结；待部署后新 marker HTTP 复核 |
 | CT-E14 | 跨客户与跨仓库隔离 | 交叉资源 ID 不可读写下载，不泄露资源存在性 | 页面无越权入口 | 双身份交叉请求证据 | 待契约 |
 | CT-E15 | push 幂等、冲突与事务回滚 | 首次成功请求冻结 path/body/expectedVersion/key；同 key 原样重放只读且返回首次结果；同 key 异参、新 key 重复均冲突；各负向后计划、版本、历史、bridge、PDA 全快照零漂移；首次 push 在 bridge 中途失败时整事务零残留且不得触发 PDA | 冲突或失败后页面刷新仍只显示首次成功事实 | 原始请求、三次回查全快照、失败 `requestId/traceId`；中途失败由后端事务合同覆盖 | 新时序合同已冻结，待环境验收 |
 | CT-E16 | 默认 Admin HTTP 同 marker 完整链 | 默认入口按 `phase3-container-loading -> phase3-loading -> overview/PDA/evidence -> customs -> loading-finalize` 串行；下游只消费 `phase3Loading` 发布的 `taskId/inboundId/loadingPlanId/containerBookingId`，最终同一订单详情和列表均为 `LOADED` | 同一批次可从订单、柜次、预装、PDA、报关入口逐级回查 | 全新 marker、关键资源 ID、五类二进制证据、各请求 `requestId/traceId`、最终统一订单状态 | 静态合同已接入默认入口，待环境 HTTP |
 | CT-E17 | 订舱代理不区分国内/国外 | 供应商必须为正式 `supplierId` 对应的 `ACTIVE + BOOKING` 记录，名称使用服务端快照；查询、创建和内部快照校验不得携带或要求 `DOMESTIC/INTERNATIONAL scope`，但类别或启用状态不符仍 fail-closed | 订舱代理候选不显示国内/国外范围门禁 | fixture 请求、Warehouse 内部快照、Firstleg 类别/启用校验及 Admin 候选静态合同；部署后补真实 HTTP | Warehouse/Firstleg 共享改动已可见；Admin 与环境 HTTP 待收口 |
 | CT-E18 | PDA 进行中增量预装与最终完成竞态 | 领取后、最终完成前新增入库单必须复用同一 task；新项出现后撤回最终完成门禁，旧 token 返回 A0409“库存已变化，请刷新后重试”且零写入；未拣项可删除，已拣项删除或减量拒绝；Admin 增量与 PDA final complete 同锁 task 行，只允许一个事务成功；`COMPLETED` 后全部变更拒绝 | Admin 增量结果与 PDA 队列实时一致，失败提示不伪造完成 | 增删前后计划/task/items/evidence 投影、版本和操作历史；并发双方响应及最终唯一事实 | `LANDED_STATIC`：OpenAPI、HTTP 双请求 winner/loser 脚本及离线合同已接线；待部署后定向复核 |
 ## PDA 完成后未进入 LOADED 的已登记回归
 - 真实测试样本：订单 `NYEXX2608170001`；PDA task、review、装柜计划与五类证据均已完成，但 inbound 仍为 `LOADING`。
 - 历史只读证据：旧柜次曾因拖车 `loading_plan_id=NULL` 被误判 `truck_ready=0`；该门禁已被最新产品结论覆盖，不再作为 PDA 完成前置。
 - 最新冻结：最终入口仍为 `POST /pda-loading/tasks/{taskId}/complete`，保留订舱 `RELEASED`、bridge 和五类 ACTIVE 证据门禁；拖车缺失、未完成或多条均不得阻断。
 - 同步边界：task/plan/inbound 主事务先提交为 `LOADED`；若同稳定 `containerBookingId` 恰有一条有效拖车，再以独立新事务尝试推进 `COMPLETED`。零条直接跳过；多条、错柜或并发冲突不得回滚主事实。
 - 已冻结回归包：① 唯一 `LOADING` 拖车 → PDA complete → inbound `LOADED`，拖车独立同步 `COMPLETED`；② 无拖车仍成功；③ 多拖车仍成功且各拖车零误改；④ 错柜拖车零修改；⑤ 同键重放不新增历史；⑥ 拖车同步异常只保留独立失败证据。
 ## 拖车独立开立契约
 | 验收项 | 正式断言 | 当前结论 |
 |---|---|---|
 | 无履约关联创建 | `oceanBookingId/containerBookingId/loadingPlanId` 可同时为空；本轮客户、正式 ACTIVE `TRUCKING` 承运商、`plannedLoadingAt` 必填；创建后可查询、编辑并独立完成 `DRAFT -> ... -> COMPLETED` | `LANDED_STATIC`：DTO/OpenAPI/Admin 与 HTTP fixture 已接线 |
 | 客户和供应商事实 | `customerId` 必须指向 ACTIVE IAM 客户，名称由 IAM 冻结；`carrierId` 必须指向 ACTIVE TRUCKING 供应商，名称由 Warehouse 冻结；名称仅为一致性提示 | 静态及 HTTP 必填负向已接线 |
 | 可选订舱/柜次 | 任一关联存在时校验客户及仓库；订舱和柜次同时存在时必须有 allocation 关系 | Service/OpenAPI 静态合同已锁定；部署后补不同客户/仓库及 allocation HTTP 负向 |
 | 可选计划 | `loadingPlanId` 仅能与 `containerBookingId` 同时提供，且必须是该柜次当前计划 | 同 marker 柜次派生错误计划 ID 的 HTTP 负向已接线 |
 | PDA 隔离 | 未关联拖车不受 PDA 影响；同柜零/一/多条均不阻断 PDA 主事务；唯一拖车同步失败也只影响拖车自身 | 静态合同已锁定提交后同步与独立事务；部署后按零/一/多 fixture 验证 |
 | Admin 表单 | 客户、承运商、预计装箱时间必填；订舱和柜次明确标注可选，清空后不得残留派生计划/仓库/客户 | Admin 静态合同已接线 |
 | 派车提单门禁 | DRAFT 可先独立开立；DISPATCH 前必须有 `billOfLadingNo` 和有效 `BILL_OF_LADING` 文件，缺任一项明确拒绝 | `truck-appointments` 已覆盖缺失拒绝、正式上传/回查与完整自身状态机；待部署后 HTTP |
 ## 装柜清单三备注
 | 验收点 | 冻结契约 | 自动化证据 |
 |---|---|---|
 | 订单备注关联 | `customerRemark/internalRemark/warehouseRemark/customerServiceRemark` 均以 Order 订单备注为权威；订单列表修改后三类平台备注同步全部未冻结预装明细，预装详情修改后三类平台备注写回订单并同步同票未冻结明细；`customerRemark` 只随客户申报修改同步，禁止冒用 `cargoRemark` | `orders` 写入四条互异 marker；分别从订单列表和预装详情修改后，两个入口精确比较一致性、版本递增与并发冲突 |
 | 冻结边界 | EDITING/LOADING 的预装明细参与订单备注同步；COMPLETED 或 `frozen_at` 非空的装柜历史保留完成时快照，不被订单后续修改覆盖 | 覆盖保存、空白清空、版本递增、旧版本 A0409、完成后订单备注变更不改历史快照 |
 | 幂等与终态 | 同 operationId 同参数精确重放不重复递增；异参冲突；COMPLETED 后 A0409 且零写 | OpenAPI/Service 静态合同已锁定；COMPLETED HTTP 负向待部署后与 finalize 串联 |
 | 动态增量 | assignment/数量调整/删除不得覆盖已有仓库备注 | `phase3-loading` 在 LOADING 增量前后断言原明细仓库备注保持，调整明细备注保持 |
 | 海外事件 | `FirstLegLoadingPlanCompletedV2` 每个 item 含 customer/internal/warehouse 三备注，事件哈希与幂等基于同一稳定 payload | `loading-list-remarks-contract.test.mjs` 锁定 V2 类型与三字段映射；海外消费者仓库不在本仓，列为跨仓部署依赖 |
 | Admin | 客户备注只读；EDITING/LOADING 可从订单列表或预装详情编辑内部、仓库、客服备注，两个入口保存后保持一致；COMPLETED 隐藏编辑 | Admin 静态合同与双入口接口回归 |
 - 结算版本缺陷证据：task `2089254643058184193`、inbound `2089181999189299202` 在 taskVersion=1/inboundVersion=6、PICKED 2/2 与五证据齐备时返回 A0409；requestId=`12a913ba-9845-45f6-91ec-bdba28e3eb9d`、traceId=`395d11b5c0da45eca948a39a08e29d3d`。回归锁定 settle 后重新读取 full/partial 实际完成分片版本；真实并发仍冲突，失败必须零写入。
 ## PDA 进行中增量预装冻结回归
 - 冻结来源仅跟踪动态增量后端任务 `01a00e91-2124-7960-95d6-e0d0f81959f9` 落盘的 SmartLoading assign/adjust/remove、capability DTO/OpenAPI 和版本并发契约；不再向后端主链任务重复询问动态字段。
 - 用户确认：预装清单在 PDA 尚未最终确认装柜完成前允许继续添加入库单，并由原有同一 PDA task 继续拣货；不得通过新建第二个 task 或替换稳定四元身份实现。
 - 必测时序：`EDITING` 添加；task 已领取且仍未完成时添加；新增项进入同一 `taskId + inboundId + loadingPlanId + containerBookingId` 工作集；计划/task/item 版本单调递增；旧 inventory token 返回正式版本冲突并零写入；刷新后可拣新增项并再次满足完成条件。
 - 门禁撤回：新增未拣项后，原先的 ready、完成度及五类证据完成投影不得继续允许 final complete；新增项全部拣完并重新满足正式证据/下游条件后才恢复。
 - 删除与减量：已拣项删除或减量必须拒绝且全链零漂移；未拣项删除成功后同步 task、计划、库存快照与 readiness。正式写端点为 plan assignments、item PATCH、item DELETE，分别使用 planVersion/itemVersion 与 operationId。
 - 并发与终态：Admin 增量与 PDA final complete 并发只允许一个事务成功，失败方必须取得明确业务冲突证据；task/计划进入 `COMPLETED` 后，添加、删除、减量全部拒绝。
 - 隔离基线不变：容量/限重、客户、仓库、物流渠道、柜型/规格和 ACTIVE 柜次归属继续 fail-closed；任何增量都不得借历史入库单、跨 marker 或创建第二个任务绕过。
 - 默认全量接入：`phase3-loading` 已在首次 batch 与 final complete 之间接入本轮 marker 的独立入库单、旧 token 负向、未拣删除、重新加入、调整、刷新补拣和已拣删除/减量零写入；`phase3-pda-convergence` 回查稳定四元和唯一任务，最后由 `phase3-loading-finalize` 串行执行正式 complete，确保结算自身的版本变化不被人为并发遮蔽，成功后回查实际 full/partial 履约分片及唯一 `LOADED` 事实；失败则保存业务码、`requestId/traceId` 并回查 task/plan/inbound/operation 零漂移。真实增量/final 并发使用独立 fixture，不复用主正向链。
 ## P3-Q14 文档同步待总控统一
 - 当前冻结验收时序：订舱只登记 `containerRequirements` 并在完整 release 后进入 `RELEASED`；不会生成真实货柜。未订舱时先建 `SIMULATION/ACTIVE` 模拟柜并排货、无号 push，港口取得真实 `containerNo` 后用四字段 link 原地补全模拟柜并创建 allocation。
 - `docs/国内货柜履约/国内货柜履约需求确认表.md` 的 P3-Q14 尚未完整描述新的 DRAFT/RELEASED 与港口四字段关联模型。本任务不擅改需求确认表，标记为 `WAIT_CONTROLLER_DOC_SYNC`，由总控统一文档；本矩阵及自动化以当前冻结 DTO/OpenAPI 为准。
 - 五项运输事实保存在 DRAFT 聚合，release 只校验完整性并冻结持久化快照；RELEASED 不接受编辑或删除。
 ## 契约冻结清单
 ### 既有冻结基线
 以下能力在本轮新增 overview 契约之前已经由国内货柜履约产品确认版、既有 OpenAPI/Controller 和专项测试冻结。本轮不重定义其路径或状态机。
 | 能力标识 | 冻结边界 | 事实来源 | 状态 |
 |---|---|---|---|
 | `booking-requirements-and-port-link` | 订舱按 `containerRequirements[]` 保存箱型数量，不生成真实柜；link 在港口取得真实柜号后补全模拟柜并创建 allocation | `PlatformContainerController`、`ContainerService`、`OceanBookingService`、`firstleg-v1.yaml`、`ocean-bookings-v1.yaml` | 本轮目标冻结，待环境验收 |
 | `channel-isolation` | 渠道隔离与禁止跨渠道混装 | 国内货柜履约产品确认版及既有排柜契约 | 既有冻结，待环境验收 |
 | `container-number-lifecycle` | 模拟柜无真实柜号允许排柜及 push；push 本身不开放 PDA；link 从未消费真实柜带入唯一 `containerNo`，内部柜、计划、bridge 身份稳定；作业中换号身份稳定 | `ContainerService`、`SmartLoadingService`、`SplitPreloadService`、`LoadingListService`、相关 OpenAPI 与合同测试 | 新时序已冻结，待环境验收 |
 | `preload-and-loading-list` | `PENDING -> EDITING -> CONFIRMED`；计划级确认原子确认全部关联票据并唯一建 task；ACTIVE 模拟柜已关联 `RELEASED` 订舱需求、真实柜号和 readiness 全部满足后 `readyForPda=true`，claim 才推进 `LOADING` | `LoadingListService.confirmPreload`、`LoadingPickService`、`POST /loading-plans/{planId}/confirm` 及 Loading List OpenAPI/DTO | 计划级确认已冻结，待环境验收 |
 | `customs-documents-lock` | 清关/报关专用流程、完成态禁止替换 | 既有 `LoadingListService`、专用 Controller 与专项测试 | 既有冻结，待环境验收 |
 ### 本轮新增冻结契约
 事实来源：`baiyue-firstleg/firstleg/src/main/resources/openapi/phase3-container-overview-v1.yaml`、`PlatformContainerController`、`ContainerOverviewDtos`、`ContainerOverviewService`、`LoadingListService`。
 | 能力标识 | 冻结路径与字段 | 权限/并发 | 状态 |
 |---|---|---|---|
 | `container-overview` | `GET /api/platform/v1/containers/{id}/overview`；聚合 container、loadingPlanId、PDA 摘要、documents、exception/history、timeline | `platform:firstleg:container:list`；旧 `container:view` 已移除 | 已冻结 |
 | `pda-progress-exception-summary` | PDA `taskStatus/workflowStatus`、任务 ID/版本、明细计数、`photoCounts`、`photos`（含 fileId/status/downloadPath）及异常原因；照片下载为 `GET /api/platform/v1/containers/{id}/pda/photos/{fileId}/download` | 随 overview 查看权限；下载复核柜次、计划、入库单与文件归属 | 已冻结 |
 | `container-abnormal-history` | `POST/DELETE /api/platform/v1/containers/{id}/exception`；请求使用 overview 返回的 container.version、必填原因和幂等键 | `platform:firstleg:container:edit`；版本冲突 fail-closed | 已冻结 |
 | `container-documents` | 通用查询、multipart 上传和受控文件下载仅支持 DO；下载透传已校验 Content-Type，非法类型回退 `application/octet-stream`，并返回 UTF-8 文件名、`no-store` 和内容长度 | 查询/下载用 `platform:firstleg:container:list`，上传用 `platform:firstleg:container:edit`；旧 `container:view` 已移除；下载校验柜次、类型、文件 ID 及文件服务 tenant/business 归属 | 已冻结 |
 | `do-pu` | `DELIVERY_ORDER` 使用通用附件查询/上传/下载；PU 资料使用 `PUT /api/platform/v1/containers/{id}/pickup-code` 保存数字码 | `platform:firstleg:container:edit`；两者均使用服务端版本校验 | 已冻结 |
 | `transport-trajectory-log` | overview timeline 的事件类型、详情、操作者、发生时间；服务端升序 | 随 overview 查看权限 | 已冻结 |
 ### 最终安全分流
 1. overview 的 documents 与通用文件接口只覆盖 `DELIVERY_ORDER`；PU 数字码位于 overview.container，不得向通用文件路径传 PU、清关或报关类型。
 2. 目的港清关使用 `/api/platform/v1/containers/{id}/clearance` 及其专用上传、完成动作，权限为 `platform:firstleg:customs:manage`。
 3. 出口报关使用 `/api/platform/v1/first-leg/loading-lists/{planId}/customs` 及其专用上传、完成动作；查询使用 `platform:firstleg:loading-list:list`，旧 `loading-list:view` 已移除，写入使用 `platform:firstleg:customs:manage`。
 4. 清关和出口报关分别验证完成态禁止替换，不能用 DO 通用上传或 PU 码入口替代。
 5. 下载允许透传经校验的 Content-Type，非法值回退二进制类型；同时必须保留 UTF-8 文件名、`no-store`、内容长度及资源归属复核。
 ## 自动化落地门禁
 真实环境脚本只有在对应能力“已冻结=是”后才能加入请求步骤，并必须满足：
 1. 环境地址、账号和令牌只从环境变量读取。
 2. 默认不执行；必须通过显式运行参数开启真实 HTTP。
 3. 只通过业务 API 造数，不连接数据库，不调用 Jenkins。
 4. 支持按本次运行标识检索资源，避免误用历史数据；清理动作仅在契约明确且安全时启用。
 5. 输出脱敏 JSON 报告，逐请求记录 HTTP 状态、业务码、`requestId`、`traceId` 和资源 ID。
 6. 对未冻结能力或冻结来源不一致输出 `BLOCKED_CONTRACT`，不得以跳过后仍报告全链通过。
 ## 当前阻断
 | 阻断 | 影响 | 解除条件 |
 |---|---|---|
 | 测试环境未获得部署授权且本任务禁止部署 | 无法验证环境是否已包含依赖实现 | 人工部署明确提交后，再执行获授权的验收轮次 |
 | 未提供测试环境凭据和两组隔离身份 | 无法执行跨客户/跨仓库/下载鉴权负向用例 | 由总控提供临时验收身份或既有安全注入方式 |
 ## Marker 回归增量（ADMIN-API-20260814032734876）
 | 回归项 | 当前冻结事实与自动化断言 | 当前结论 |
 |---|---|---|
 | Release 正式 DTO | `POST /api/platform/v1/ocean-bookings/{id}/release` 已冻结；`ReleaseRequest` 必填提单号、船名、航次、ETD、ETA，并保留 `expectedVersion`。HTTP fixture 必须携带五字段；Admin 未填齐不得调用 release | `LANDED`，不是路径阻断 |
 | PDA overview 状态语义 | PDA 任务的 `taskStatus=LOADING` 与业务流转 `workflowStatus=AWAITING_REVIEW` 必须分字段返回；进度 100%、未解决数为 0 且任务仍为 `LOADING` 时必须明确为 `AWAITING_REVIEW` | 后端 DTO/OpenAPI/聚合已回传；`LANDED`，待环境 HTTP 验收 |
 | PDA overview 照片下载 | 对 `photos[]` 每个服务端 `downloadPath` 执行真实鉴权 GET；仅接受站内 `/api/` 路径、HTTP 200、非空二进制和非 JSON/HTML Content-Type | HTTP 回归已准备；待获授权环境验收 |
 | 客户公开名称一致性 | `customerId` 筛选后的订舱、拖车和预装列表/详情必须显示 IAM `tenantName`，不得优先 `legalName`；列表、详情及关联名称一致 | 列表筛选与拖车预约新增表单已统一 `tenantName`；`LANDED`，待人工筛选回归 |
 | 已有 `containerNo` 动作语义 | 已有真实柜号时补号动作不可伪装成首次补号；换号前后柜次 ID、PDA taskId、loadingPlanId 和证据归属必须稳定 | Admin 已按柜号是否存在显示“录入集装箱号/修改集装箱号”，后端 HTTP fixture 已锁定身份稳定；`LANDED` |
 | 订舱/拖车详情关联名称 | 详情中的客户、柜次、订舱及关联资源名称必须来自正式详情响应，并与同 ID 列表显示一致 | 后端详情已返回稳定名称字段，Admin 使用详情快照与受控候选回显；`LANDED` |
 | 拖车附件闭环 | `POST /truck-appointments/{id}/attachments` 引用、`POST /truck-appointments/{id}/attachments/upload` 上传关联与 `DELETE /truck-appointments/{id}/attachments/{attachmentId}` 已冻结 | Admin 已提供选择文件、上传并关联、列表及删除入口，HTTP 删除后回查已覆盖；`LANDED` |
 | 中文状态、弹框与 390px 布局 | 列表/详情状态必须中文；release、附件、柜号动作使用正式弹框；390px 下字段、按钮、弹框不横向溢出或遮挡 | `AWAITING_REVIEW`、照片类型、确认按钮已中文化，放舱/改船/附件弹框已落地；桌面与 390px 浏览器无横向溢出；`LANDED` |
 说明：`BLOCKED_CONTRACT` 仅标记明确缺失的 DTO 字段或 Admin 承载，不把已存在的 release、拖车附件 API 路径降级为未冻结能力。
 ## 订舱物流渠道与柜次隔离增量
 | 验收项 | 自动化断言 | 当前结论 |
 |---|---|---|
 | Admin 渠道选择 | 订舱新增/编辑不允许自由输入 `channelCode/channelName`；选择起运仓后使用渠道下拉，查询必须携带 `originWarehouseId` | `LANDED`：Admin 使用受控渠道下拉并调用正式平台渠道接口；Admin 与根静态合同均锁定渠道选择正向及自由输入负向 |
 | 平台渠道目录 | `GET /api/platform/v1/ocean-bookings/channels?originWarehouseId=...` 只返回当前 ACTIVE 价格簿渠道；HTTP fixture 记录本轮 marker、`originWarehouseId` 与服务端路径，不借 Merchant 身份或历史资源 | OpenAPI 已冻结；真实查询生产者已发布 `createdResources.platformLogisticsChannels` |
 | 双有效渠道 fixture | 跨渠道负向必须使用同一起运仓下两个真实有效渠道；只有一个有效渠道时输出 `BLOCKED_FIXTURE`，禁止派生 `-OTHER` 伪渠道 | 脚本门禁与正式渠道生产者已落地；待环境数据验证是否存在双渠道 |
 | 船公司与物流渠道独立 | `shippingCompanyId/shippingCompanyName` 与渠道选择分别建模，不用船公司字段代替渠道字段 | `LANDED`：Admin 与写请求模型分别承载船公司和物流渠道，静态合同已转绿 |
 | 关联柜继承渠道 | 港口 link 后货柜详情 `channelCode` 必须等于 RELEASED 订舱的有效渠道；异渠道入库单不能分配到该柜次 | HTTP 断言已准备；异渠道负向只使用真实 ACTIVE 渠道；写 DTO 不发送服务端拥有的 `channelName` |
 ## 订舱资料字段与可选客户增量
 事实来源：原型 `prototype-src/modules/06-containers.html`、P3-Q14、`OceanBookingDtos.DraftData`、`ocean-bookings-v1.yaml`、Admin `OceanBookingDetailView.vue` 与 `OceanBookingDraftData`。
 | 字段/链路 | 原型与阶段时序 | 自动化断言 | 当前结论 |
 |---|---|---|---|
 | `serviceTerm` | 原型第 516 行以 `*` 标记主要运输条款必填；P3-Q14 未删除该业务快照 | Admin 必填自由文本；Java `@NotBlank`；OpenAPI `required` 且非 nullable；模块基线和统一 SQL 均为 `NOT NULL`；不保留无来源的 `CY-DOOR/DOOR-CY/DOOR-DOOR` 自造字典；验收 fixture 使用原型展示值 `CY-CY` | `LANDED` |
 | `freightTerm` | 原型第 518 行以 `*` 标记运费条款必填；示例值为 `NINGBO`，不构成枚举事实来源 | Admin 必填自由文本；Java `@NotBlank`；OpenAPI `required` 且非 nullable；模块基线和统一 SQL 均为 `NOT NULL`；不保留无来源的 `PREPAID/COLLECT` 自造字典；验收 fixture 使用原型展示值 `NINGBO` | `LANDED` |
 | 可选客户 | 原型第 527 行“客户/公司名称”无必填标记；当前产品确认允许平台先建订舱后关联客户 | Admin 可清空选择；前端类型、Java DTO 与 OpenAPI 均允许 `customerId/customerName` 同时为空，单边填写必须拒绝 | `LANDED` |
 | 可选客户合同 | 不以历史客户或占位 ID/名称替代可空契约 | 共享 builder 保留无客户能力；当前默认 `ocean-bookings` 主链使用正式可选客户字段并验证 DRAFT/RELEASED，不生成柜次 | 离线合同已覆盖；独立无客户 HTTP 链待总控决定 |
 | 指定客户隔离链 | 保留来自本轮入库单的正式客户范围 | `phase3-container-loading` 与既有订舱主链继续断言客户、仓库、渠道一致和跨渠道拒绝，不借历史资源 | 已准备，待部署后 HTTP 验收 |
 | 提单号、船名、航次、ETD、ETA | 原型存在相关展示/录入字段；DRAFT 可部分保存，release 前必须补齐 | 五字段属于持久化 DRAFT；`ReleaseRequest` 只传 `expectedVersion`，服务端校验并冻结已存快照；RELEASED 不可修改 | `LANDED_STATIC` |
 | 单证号 | 原型第 529 行存在“单证号”，但当前阶段 DTO/OpenAPI 未冻结对应写字段 | 不猜字段名或复用提单号；本轮不扩展写契约 | 非本轮能力，不标记接口阻断 |
 离线合同：`ocean-booking-prototype-contract.test.mjs` 锁定原型证据、跨端可选客户、DRAFT 编辑与 release 完整性门禁；`ocean-booking-fixture-contract.test.mjs` 与 `full-regression-entry-contract.test.mjs` 锁定 `containerRequirements` 和默认编排。订舱正式状态仅为 DRAFT/RELEASED。
 ## 内部模拟柜关联真实订舱增量
 事实来源：`PlatformContainerController`、`ContainerDtos`、`ContainerService`、`OceanBookingService`、`OceanBookingMapper`、`firstleg-v1.yaml`、`ocean-bookings-v1.yaml`。
 | 验收项 | 自动化断言 | 当前结论 |
 |---|---|---|
 | 正式订舱列表 | 仅允许 `DRAFT/RELEASED`；DRAFT 可编辑删除，RELEASED 不可编辑删除；内部模拟柜不进入订舱列表 | 契约与 HTTP fixture 已落地，待部署后验证 |
 | 新增内部模拟柜 | `POST /api/platform/v1/containers` 只接收正式装柜仓库、当前 ACTIVE 物流渠道、箱型、容量和限重；不接收真实柜号或订舱；服务端生成稳定 `containerBookingId/cabinetNo` | 契约与 HTTP fixture 已落地，待部署后验证 |
 | 订舱柜型需求 | `POST /ocean-bookings` 保存 `containerRequirements(type/kind/quantity/capacityCbm/maxWeightKg)`；不接收真实柜号，不创建货柜/allocation | DTO/OpenAPI/静态合同及 HTTP fixture 已落地，待部署后验证 |
 | 港口逐柜关联 | 真实柜号取得后，对已有 `SIMULATION/ACTIVE` 柜调用 `{oceanBookingId,requirementId,containerNo,expectedVersion}`；模拟柜 `containerBookingId/cabinetNo/loadingPlan/items` 不变 | 契约与 HTTP fixture 已落地，待部署后验证 |
 | ACTIVE 唯一操作身份 | link 直接补全原模拟柜并创建 allocation；不存在另一条真实柜或 MERGED 中间记录 | 静态合同与 HTTP 列表/详情断言已落地，待部署后验证 |
 | 隔离与唯一占用 | 跨仓、跨渠道、箱型/容量/限重/客户范围不匹配、需求超量或重复柜号拒绝；所有失败保持柜、计划、明细、allocation 和列表零漂移 | 静态合同已锁定；双渠道和主要 HTTP 负向待部署后验证 |
 | 首次关联不可逆门禁 | 存在 PDA、有效装柜证据、业务单证或已进入 `LOADING/COMPLETED` 时首次 link 拒绝 | 服务端静态门禁已锁定；需部署后以独立 marker fixture 验证 |
 | 解绑与换绑 | 服务端仍仅允许完全空的 `WAIT_LOADING` 合并柜执行原子 unlink，并恢复来源为 ACTIVE；一旦已有排货、PDA、证据或单证事实，unlink/rebind 均拒绝 | 静态门禁已锁定；排货后负向 HTTP fixture 已落地，待部署后验证 |
 | 全量编排 | 默认入口先运行 `phase3-container-loading` 完成“模拟柜新增 -> 同仓同渠道排货 -> 首次 link -> PDA”，再由证据、finalize、出仓模块沿本轮 marker 的稳定 ID 继续；禁止历史数据和 mock 回退 | Node 入口合同已锁定，待默认全量 HTTP 验证 |
 离线合同：`container-simulation-association-contract.test.mjs` 锁定跨层契约及全量顺序；`phase3-producer-chain-contract.test.mjs`、`phase3-order-splitting-contract.test.mjs`、`ocean-booking-channel-contract.test.mjs` 锁定生产者只使用 DRAFT/RELEASED、需求关联且不在订舱阶段自动建柜。
@@ -0,0 +1,180 @@
 # 报关资料与船期价格接入梳理
 > **当前用途：报关与船期价格专题参考。** 报关流程已经确认，代码已进入第一批开发；开发交接看[报关代码开发交接清单](../头程到尾程/报关代码开发交接清单.md)。主流程和节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准；本文保留资料字段、回执轮次、价格口径和接口查找信息。
 >
 > 文中“目标、实施顺序、进入条件、待确认事项”等段落属于原评审记录。开发已经完成后，不再据此重新拆开发任务；若与当前确认不一致，以总览和最新业务确认修正对应专题段落。
 本文是企业客户端“报关资料”“船期价格”入口的专题评审记录。当前使用时只取已确认的流程、资料和价格口径；“建议”和“待确认”保留为历史评审痕迹，不再自动生成开发任务或验收门禁。
 **当前基线**：以最新用户确认和[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。旧版需求表、README、开发规划和本文件中的历史建议若发生冲突，先在当前入口记录收尾变更，再决定是否需要修改专题细节。
 **当前实现快照（2026-09-26）**：两份文件链路已经落到平台、客户和 Firstleg 报关接口：客户资料、报关行回执、客户整份回执确认/打回、平台发送报关行执行、真实报关完税文件分别保存并受版本门禁控制。回执发送给报关行后不可再替换；只有包含退税货物的柜才允许走发送执行接口；全买单柜仍走平台直接完成。`brokerSubmittedAt` 只表示发送执行时间，不表示报关完成。PDA 只负责产生 `LOADED` 前置事实，报关验收不创建或操作 PDA 任务；船期、甩柜和改配只修改原柜运输信息，不重置报关资料和确认结果。
 ## 先锁定的范围
 国内货柜履约的物理装柜节点为 `LOADED`。`LOADED` 后先完成退税客户的报关协同，报关完成后进入待发区，再推进船期运输：
 1. **报关线**：仅对退税客户通知报关行，收集退税客户资料，发送报关行，接收报关行回执并发客户确认；客户认为不正确时打回、重新上传、重新发送并生成新回执，循环至柜内退税客户均确认；全部确认后，再将退税申报资料提交报关行确认，由报关行正式申报，记录查验、不查验放行或其他海关结果。买单货物不进入这条资料和回执流程。
 2. **船期线**：报关完成并进入待发区后，安排拖车、从仓库发运、送港、进港；港口容量不足时记录甩柜和改配船次。甩柜/改配只改变运输船次，不重新处理已完成的报关资料、回执和客户确认；`PORT_RECEIVED` 不等于海运中，只有船舶真实开航后才进入海运节点。
 报关完成是进入待发区的前置；进入待发区后才推进船期运输。首期不对接海关单一窗口或报关代理系统：报关行回执以文件上传为主，正式申报由授权人员人工提交，客户确认和海关结果由平台人工记录。
 费用确认是并行事实，不阻断排柜、预装、PDA 或装柜。装柜完成后，对应已实装范围若客户仍未确认当前有效且已发布费用版本，系统记录“系统默认确认（装柜完成）”；不伪造客户点击，保留 `SYSTEM_AUTO_AT_LOADED` 来源、费用版本、柜次/入仓码、时间和幂等标识。没有有效费用版本时不得生成零额或伪造确认，须保留费用异常待办。
 出仓后的实际装船、提单、舱单、结关、退税正式资料和船公司节点查询属于后续或海外仓业务事实，不作为本期国内货柜履约页面、接口和验收范围。若国内页面需要展示，只能消费已确认的跨服务只读快照，并单独定义事件、来源、更新时间和责任边界。
 ## 入口与权威数据
 | 入口 | 本期职责 | 权威数据 | 当前状态 |
 |---|---|---|---|
 | 客户端“报关资料” | `LOADED` 后查看本企业资料包，上传/替换/补件，查看报关行回执并确认或打回 | Firstleg 报关协同；文件由 File 服务保存 | **目标新增独立入口** |
 | 订单中的“上传资料” | 带订单和入仓码上下文进入同一资料包 | 与独立入口共用 packageId 和接口 | **现有快捷入口** |
 | 平台整柜报关工作台 | 按实际装柜清单通知报关行，管理客户资料、回执轮次、全部确认、整柜正式提交和海关结果 | Firstleg 柜级报关与提交批次 | **已有四态，需收敛新投影** |
 | 客户端“船期价格” | 查询当前企业可见的有效渠道、参考船期、最晚进仓、参考时效和估价 | 生效价格簿及服务端估价 | **建议新增独立入口** |
 | 平台“船期价格表” | 上传、解析、核对、发布公共或客户专属价格簿 | Firstleg 价格簿版本 | **已有平台能力** |
 平台端应写“按申报组整理并线下提交”。在跨客户合并规则确认前，默认禁止把不同客户放入同一正式报关单；不得在结论表中把待决规则写成既定能力。
 ## 当前实现事实
 1. 客户端当前通过订单接口查询报关资料，现状主要只对服务端确认已完成装柜的退税订单开放；本目标稿调整为 `LOADED` 后启动本柜报关批次，按客户/入仓码收集资料、接收报关行回执、提交客户确认并支持打回重做。资料可上传、替换、改关联、删除并保留版本；每轮发送和回执都要留痕，客户确认后才进入该客户的 `CUSTOMER_CONFIRMED`。对应接口和权限见 [customs-v1.yaml](../../baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml#L48)。
 2. 当前柜级状态为 WAITING_CUSTOMER_DOCUMENTS → READY_TO_START → DECLARING → COMPLETED；目标需要增加客户确认轮次、整柜正式提交、查验/放行和送港子状态。资料关联以 loadingPlanId、柜级聚合、客户报关案例和整票入仓码为根。
 3. 当前 COMPLETED 会发布报关完成事件并参与待发区门禁。契约将“客户资料确认轮次”“整柜正式提交”“海关查验/放行”分开；报关完成后才允许进入待发区，船期事实独立维护。
 4. 全买单柜已有独立的二次确认接口和导出契约，本期继续保留；需要补齐其在客户确认轮次、整柜正式申报、海关结果和送港/开船状态中的位置。
 5. 客户端现有价格接口为按起运仓查询渠道，以及按指定渠道估算参考费用。/estimate 只返回基础参考费用，不含复杂附加费和最终结算调整；pricingTaxMode 不等同于订单 taxMode。见 [fba-pricing-v1.yaml](../../baiyue-firstleg/firstleg/src/main/resources/openapi/fba-pricing-v1.yaml#L130)。
 6. 仓库内原型与页面索引仍将报关上传、回执下载和出仓前船期资料列为待原型或部分参考；页面范围需同步 [国内货柜履约页面与原型清单.md](国内货柜履约页面与原型清单.md#L30)。
 7. **费用默认确认目前是目标变更，不是现有实现。** 当前装柜完成逻辑只会自动发送/发布费用，不能把 `SENT` 直接当成客户确认；现有费用锁定也主要依赖客户确认时间。实现本轮目标时必须增加确认来源和幂等审计，并改为“客户确认或装柜默认确认 + 已装柜完成后才最终锁定”。部分装载只能确认本次已装范围，余量不能被顺手确认。
 8. **本轮报关完成→待发区门禁和船期例外需要保持独立。** 报关完成后才允许进入待发区；`ROLLED_OVER` 只记录新旧船次和运输变更，不回退或重新评估已完成的报关资料、回执和客户确认。
 ## 报关资料模型
 ### 0. `LOADED` 后报关完成与待发区
 | 线路 | 触发时点 | 顺序 | 结果 |
 |---|---|---|---|
 | 报关线 | `LOADED` 事件产生后 | 通知报关行 → 收集每个客户资料 → 发报关行 → 接收回执 → 发客户确认 → 打回则重传重发并生成新回执 → 所有客户确认 → 整柜资料交报关行确认 → 正式申报 → 查验/放行 | 客户确认轮次、整柜正式申报、海关结果 |
 | 送港线 | 报关完成并进入待发区后 | 安排拖车 → 仓库离开 → 送港 → 进港 → 等待船次；装不下时在原柜船期上人工修改船信息并留痕 | `DEPARTED_WAREHOUSE`、`PORT_RECEIVED`、`ROLLED_OVER`、实际开船 |
 报关资料未完成时不得进入待发区；完成报关并进入待发区后才推进送港。已进港也不代表已经进入海运；只有船舶真实开航后，才写入海运起点。
 客户确认是每个客户报关案例的完成条件；海关放行是整柜正式申报后的外部结果，不能用上传回执或任意“完成文件”代替。
 ### 1. 客户报关案例与资料包
 报关资料主流程在 `LOADED` 后启动。每个客户/入仓码在本柜建立一个 `customerCustomsCase`，再挂载稳定的 `packageId` 和文件版本。案例至少记录：订单/子订单、入仓码或入仓明细、实际装箱数展示、资料清单版本、每个清单项的文件版本、报关行发送时间、回执文件版本、客户确认/打回人和时间、打回原因、当前 `roundNo`、客户可见范围和审计记录。
 资料包不能只关联整票入仓码。已确认支持一单多柜、拆批和父订单—子订单关系，因此每个关联项保存客户、订单、入仓码和装柜明细引用；部分装柜只展示本柜实际箱数并标记线下处理，不在系统内自动做数量分摊。柜次一旦装柜完成不因甩柜改船而变化，受影响案例不能静默重置回执轮次。
 ### 2. 实际装柜绑定快照
 资料包与 loadingPlanId、containerBookingId 的关系应通过绑定记录表达，而不是覆盖原资料包。绑定记录至少保存实际装柜明细引用、实装箱数、客户、订单、入仓码、柜次和绑定版本。`LOADED` 后开始本轮报关时冻结该范围；部分装柜只生成箱数展示和线下处理标记，甩柜改船不使资料绑定和回执轮次失效。
 ### 3. 申报组与柜级总览
 申报组归属一次实际装柜和一次整柜正式提交，记录成员客户案例、合并关系、报关代理、每轮回执、客户确认结果、正式提交时间、正式业务编号、查验/放行结果和异常历史。跨客户合并在业务确认前默认拒绝；若未来开放，必须增加授权、客户可见投影、组成员冻结快照和取消/重组规则。
 柜级总览仅供平台使用，汇总实际装柜行、退税/买单行、缺件、提交批次和门禁结果。客户端接口必须按当前企业裁剪返回，不返回同柜其他客户的名称、数量、资料包 ID、申报组 ID 或异常细节。
 ### 4. 买单、退税和混合柜完成条件
 三类柜不能用一条“缺回执即阻断”的规则代替：
 | 柜型 | `LOADED` 前 | `LOADED` 后报关线 | 完成条件与开船影响 |
 |---|---|---|---|
 | 全买单 | 装柜物理门禁独立判断 | 不进入本报关资料、报关行回执和客户确认流程；继续按买单装柜、导出和运输节点处理 | 不创建退税报关案例，不以报关资料或回执作为门禁 |
 | 退税柜 | 装柜物理门禁独立判断 | 对每个参与入仓码收集/补件，发送报关行，逐份接收回执并让对应客户确认；打回则重做当前案例 | 所有退税客户案例确认后才允许整柜正式提交；正式申报后的查验/放行单独记录 |
 | 混合柜 | 装柜物理门禁独立判断 | 仅退税行建立报关资料和回执确认案例；买单行不进入该流程，仍保留买单装柜和导出事实 | 仅退税客户案例全部确认后才允许提交退税申报批次；不得把买单明细冒充报关确认 |
 同一客户多个入仓码可以共享其授权资料；跨客户物理拼柜不等于允许跨客户正式合报。跨客户合并仍默认禁止，必须有独立授权和客户可见隔离契约。
 ## 状态、事实与门禁
 建议把状态拆成独立事实面，页面总状态只做投影：
 | 事实面 | 建议状态 | 说明 |
 |---|---|---|
 | 客户报关案例 | WAITING_DOCUMENTS、SENT_TO_BROKER、RECEIPT_PENDING_CUSTOMER_CONFIRM、CUSTOMER_CONFIRMED、NEEDS_RESUBMIT、INVALIDATED | 每轮 `roundNo` 保存资料版本、发送时间、报关行回执、客户确认/打回原因；回执上传不等于客户确认 |
 | 整柜申报批次 | WAITING_ALL_CUSTOMER_CONFIRM、ALL_CUSTOMERS_CONFIRMED、FORMAL_SUBMITTED_TO_BROKER、DECLARED、INSPECTION、NO_INSPECTION、RELEASED、REJECTED | 所有客户案例确认后才允许整柜正式提交；首期由授权人员人工记录报关行确认和海关结果 |
 | 送港/船期事实 | PORT_DELIVERY_PENDING、DEPARTED_WAREHOUSE、IN_TRANSIT_TO_PORT、PORT_RECEIVED、ROLLED_OVER、VESSEL_DEPARTED | 与报关案例独立；进港和甩柜不等于海运中，只有真实开船才进入海运节点 |
 | 装柜门禁 | PASS/BLOCKED | 只判断是否满足 LOADED 的已确认前置 |
 上述是首期状态投影。回执首期以文件为主、客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；实际开航首期人工录入，甩柜/改配人工修改原柜船信息并保留原报关事实，不重新评估申报批次。其余稳定编码、退回/重开规则和责任人仍需在开发前确认。当前四态不能直接承担新流程；收敛时应明确旧状态的映射和删除时点，不保留双协议。
 物理 `LOADED` 门禁必须明确校验以下事实：
 1. 真实柜号、预装计划和数量版本完整；
 2. PDA 拣货和复核完成，整批提交成功；
 3. 空仓、半仓、满仓、锁仓、带锁码照五类证据各有至少一张有效照片，锁码文本已保存；
 4. 数量守恒、无未解决 PDA 异常。
 `LOADED` 后创建报关案例；报关案例完成整柜正式申报并达到报关完成条件后，才允许进入待发区并创建/推进送港任务。送港任务继续校验装柜完成、真实柜号、订舱/拖车等运输条件。到港后如船舱不足记录 `ROLLED_OVER`；只有实际 `VESSEL_DEPARTED` 才进入海运节点。报关放行、送港和甩柜不能反向作为 `LOADED` 的前置，甩柜也不改变已完成的报关事实。
 每个写动作都需要 Idempotency-Key、expectedVersion、规范化请求哈希、乐观锁冲突码、审计事件和结果回放。上传、替换、改关联、补件、审核、提交批次、回执上传和门禁确认不得仅靠前端推进。
 ## 权限、文件与接口边界
 现有报关接口使用 merchant:order:view/edit 和 platform:firstleg:customs:list/manage。新增独立入口前必须确认是复用还是拆分为报关专用权限，并落到客户端路由、导航、Controller、OpenAPI x-permission、IAM 初始化 SQL 和服务端对象级校验：
 - 客户查看、上传/替换、补件确认和下载分别校验当前企业、订单/子订单、入仓明细和客户可见标记；不能信任请求中的 tenantId、订单 ID 或入仓码。
 - 平台查看、审核/退回、生成提交批次、上传回执和发布结果分别授权；列表权限只包含详情只读，写权限独立。
 - File 文件类型、业务 ID、客户归属、版本、冻结和下载审计必须定义。现有 `LOADING_LIST_CUSTOMS_SOURCE`、`LOADING_LIST_CUSTOMS_RECEIPT`、`LOADING_LIST_CUSTOMS_RESULT` 只负责不可变文件对象，不能替代客户案例、提交批次和海关结果对象；正式申报与海关结果的独立接入见[专题设计](../头程到尾程/正式申报与海关结果接入设计.md)。
 - File 上传成功但业务写入失败、业务写入成功但 File 失败、替换/作废和重试都要有补偿或可重放规则；不能产生越权文件或孤儿记录。
 独立客户列表、详情、待办计数和平台筛选必须补充明确的路径、分页、稳定排序、筛选参数、空态/无权限响应和错误码。不能只写“新增列表”或继续复用单订单查询接口。
 ## 船期价格接入
 ### 展示边界
 客户页只展示当前企业可见的有效价格簿快照：渠道、起运仓、目的地、pricingTaxMode、计费单位、单价、币种、参考船期、最晚进仓、参考时效、附加费说明、价格簿版本和更新时间。价格簿中的预计船期是参考文本，不是已订舱 ETD、实际开船或到港节点；时区、有效期、来源和过期展示必须明确。
 客户专属与公共价格按版本作用域选择：先选择当前企业专属 ACTIVE 版本；只有不存在专属 ACTIVE 版本时才选择公共 ACTIVE 版本，不能按单条费率缺行再逐行回退。页面展示业务版本号或生效时间，不直接把内部 priceBookVersionId 当作用户可见编号。
 ### 批量估价契约
 若要跨渠道列表展示，服务端新增批量估价契约，至少定义：起运仓、目的类型/目的地、渠道候选、重量、体积、pricingTaxMode、版本快照、批量上限、超时、无命中错误、计费量、单位、币种、基础金额、未包含附加费、舍入规则和排序规则。不得由浏览器自行计算或逐渠道扇出。
 “价格优选”只有在币种、目的地、税模式、计费口径和附加费范围可比时才允许启用；否则只展示参考结果。订单创建时必须重新校验渠道资格和生效版本，明确旧报价失效、金额变化和重新报价的用户提示，不把客户端显示金额当成最终结算金额。
 价格导出如需上线，应另定义客户可见字段、公共/专属价格隔离、导出审计、快照版本、文件保留期限和下载权限；在这些规则确认前不纳入本期上线。
 ## 实施顺序与进入条件
 1. **冻结业务规则**：确认客户资料清单、回执轮次、打回重做、所有客户确认、整柜正式申报、查验/放行、甩柜/改配和跨客户合并；已确认规则以[需求确认表](国内货柜履约需求确认表.md#L24)为准。
 2. **先做服务端契约**：完成 customerCustomsCase、资料版本、报关行回执轮次、客户确认、整柜申报批次、送港/进港/甩柜/开船事实、状态投影、权限、幂等、审计、File 类别和初始化 SQL；同步更新 OpenAPI、Gateway、IAM 和相关消费者。
 3. **接入客户入口**：独立列表/详情与订单快捷入口共用 packageId；仅在 `LOADED` 后进入本柜报关案例，覆盖资料上传、报关行回执查看、确认、打回、重新上传和新回执版本。
 4. **接入平台协同**：`LOADED` 后按最终实装快照通知报关行，逐客户处理资料和回执，全部客户确认后提交整柜资料；人工记录正式申报、查验、不查验放行和其他结果。送港线独立接入拖车、进港、甩柜和实际开船。
 5. **接入船期价格**：先复用有效价格簿和单渠道参考估价，再实现批量估价；批量列表、排序和导出必须先通过接口和价格可比性评审。
 ## 待确认事项
 | 问题 | 阻断范围 | 需要形成的结论 |
 |---|---|---|
 | 资料清单具体项目、条件规则和版本生效方式 | 清单、审核、补件 | 首版人工维护清单及版本负责人 |
 | 客户确认/打回原因和回执轮次 | 客户案例、整柜提交 | 回执版本、roundNo、确认人、打回重做规则 |
 | 海关查验、不查验放行、扣货/补件等正式结果 | 整柜申报批次、客户展示 | 结果类型、凭证、来源、客户可见范围和责任人 |
 | 送港、进港、甩柜、改配船次和实际开船事件 | 待发区、送港线、海运节点 | 事实字段、重试规则、客户通知和船次历史；首期人工录入实际开航，改配人工修改原柜船信息但不改变已完成报关事实 |
 | 价格比较、导出、报价有效期和金额变化提示 | 客户报价页、下单 | 统一币种/税模式/附加费和失效处理 |
 ## 最低验收矩阵
 - 客户 A 无法查询、上传、替换或下载客户 B 的资料、回执、价格和导出文件。
 - 独立入口与订单快捷入口返回同一 packageId、版本历史和待办结果，不产生双历史。
 - 同一幂等键同请求只产生一次记录；同键不同请求、版本冲突、并发换柜和重复回执均返回明确业务错误。
 - `LOADED` 后每个客户案例都能经历“资料上传→报关行回执→客户确认”；打回后只重开对应案例，重新上传、重新发送并产生新回执轮次，其他客户历史不被覆盖。
 - 所有客户案例均 `CUSTOMER_CONFIRMED` 后，平台才允许生成整柜正式提交；正式提交后分别验收查验、不查验放行和其他海关结果。
 - 缺 PDA 结果、缺五类证据、真实柜号或数量不守恒时，`LOADED` 门禁失败；报关完成后才进入待发区，再验收离仓、进港和甩柜；只有真实开船才进入海运节点，甩柜不重做已完成报关。
 - 全买单柜、退税柜和混合柜分别验证状态、权限、导出、回执和门禁结果。
 - 价格无命中、失效版本、跨渠道批量估价、不同币种/税模式、附加费说明和订单创建重验均有可验证结果。
 - 页面覆盖加载、空态、失败、无权限、过期和数据冲突；客户端按 1920×1080、100% 缩放人工验收。
 ## 接入核对入口
 - 客户端订单与现有报关：apps/client-web/src/modules/first-leg/routes.ts、views/FirstLegOrdersView.vue、components/CustomsDocumentsDialog.vue、api/customs.ts。
 - 客户端导航和新页面：apps/client-web/src/navigation/clientNavigation.ts 及对应页面注册、权限和 release 配置。
 - 平台整柜报关：apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue、api/platformContainerCustoms.ts。
 - 后端报关：`../baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/customs/container/`、[customs-v1.yaml](../../baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml#L1)、`phase3-container-customs-schema.sql`。
 - 报价：`../apps/client-web/src/modules/first-leg/api/firstLeg.ts`、`../apps/admin-web/src/modules/fba-pricing/carrier-rates/`、[fba-pricing-v1.yaml](../../baiyue-firstleg/firstleg/src/main/resources/openapi/fba-pricing-v1.yaml#L130)。
 - 国内边界、状态和门禁：[国内货柜履约 README](README.md:3)、[国内货柜履约开发规划（归档）](归档/国内货柜履约开发规划.md:166)、[国内货柜履约需求确认表](国内货柜履约需求确认表.md:24)。
@@ -0,0 +1,671 @@
 # 船期日历功能规划
 > 文档状态：首版开发规划；2026-09-27 复核补充了数据闭环规则。本文是开发依据，不是代码完成或上线验收证明。
 > 规划对象：Admin「国内头程 → 船期管理」独立船期日历。
 > 目标：支持人工维护渠道和船期规律，按周或单次生成具体船期，并按渠道/船期查看收货体积。
 > **当前展示版范围已重新冻结：只做船期维护和只读展示，不做自动归班、不消费预报、不改写收货审核、不自动改绑，也不改变现有智能排柜流程。** 首版只需要让管理人员看到每个航次的已收/预计货量、可用容量、按柜型初算的建议柜数、已订柜和待补柜，并据此人工判断是否合并到其他船。后续若要增加货物归班，再单独立项评审。第 15.8 节覆盖本文此前关于自动归班和异常改配的旧口径。
 > **展示版统计口径**：每个船期按“收货仓 + 渠道 + 起运港 + 目的港”展示；已收使用现有收货/测量结果，预计量使用现有入仓和智能排柜可读数据；不创建或变更船期归班事实。收货截止时间只用于标记“截止前参考量/截止后风险”，不触发自动分配。订柜数只做只读初算，最终以现有智能排柜和人工确认结果为准。
 ## 1. 输入来源与现状边界
 本规划以当前需求描述为业务输入，以用户提供的截图作为页面布局参考。截图中的红框、日期、船名、航次、数量和示例数据均不构成额外指令，也不代表需要沿用的真实业务数据。
 仓库当前已有 `apps/admin-web/src/modules/port-schedules/` 和 Firstleg 的 `portschedule` 服务。现有“港务船期”记录绑定客户、订舱或柜次，主要保存船公司/码头/API 的船期观测、过期时间和海运节点查询结果；对应表为 `fl_port_schedule`。它服务于已存在的订舱和货柜履约链路，不直接承载本规划的排班模板、周循环生成或收货量统计。现有 `port-schedules/routes.ts` 也不是本规划新页面的正式入口；新日历应作为独立 Admin 页面、路由和权限接入，不能把现有隐藏/嵌入式船期组件直接改成排班管理页。
 本功能建议新增“船期计划”域，与现有港务船期并列：
 - 船期计划是运营人员提前安排“哪个渠道哪天开哪班船”，可以没有订舱和真实柜次；价格簿中的参考船期、最晚进仓和参考时效也不能直接当作该计划的实际开船事实。
 - 港务船期是某个订舱/柜次的外部船期事实或人工观测，继续按现有接口和状态机运行。
 - V1 先建立“计划实例 ↔ RELEASED 订舱”的最小关联用于订柜统计；真实柜次、港务船期和海运节点的完整关联后置，不能用计划数据覆盖已产生的运输事实。
 本规划默认这是平台内部运营日历：渠道主数据平台级维护，模板和实例至少按收货仓隔离，实收汇总按“收货仓 + 渠道 + 收货日期”聚合并对平台运营人员可见。V1 不按客户拆分船期计划；如果实际业务存在客户专属船期或价格承诺，必须在开发前把客户作为模板、实例、查询和权限的正式维度，不能在上线后再用名称筛选补救。
 ## 2. 要解决的问题
 运营人员需要在一个页面完成以下工作：
 1. 维护当前可售或可安排的运输渠道，例如“MATSON / 美森”。
 2. 配置固定每周哪几天有船，也可以只添加一班临时船期。
 3. 根据开船时间和渠道的提前收货天数，自动算出收货截止时间。
 4. 在月历上看到每天有几班船，以及每个渠道已收多少立方米、预计有多少货、容量还剩多少和建议订几个柜。
 5. 对已生成的具体船期进行编辑、取消、复制和查看关联货量，并保留变更历史。
 ## 3. 建议的 V1 范围
 ### 3.1 本轮纳入
 - 船期渠道的新增、编辑、启用/停用。
 - 一次性船期的手工添加。
 - 每周模板的配置，按指定周几生成未来具体船期。
 - 每条模板/实例必填收货仓；首版不使用“全部仓”这种模糊范围。
 - 开船时间、预计到港时间、收货截止时间和容量的维护与计算。
 - 月历视图、月份切换、按收货仓/起运港/渠道/船名航次筛选。
 - 选中日期的船期详情和渠道体积汇总。
 - 船期实例的人工编辑、取消、复制下一班和变更历史。
 - 货量按收货仓与渠道只读展示已收实测体积、预计体积、截止前参考量、截止后风险量、已订柜和待补柜；不产生归班事实、不提供货量改绑。
 - 按现有柜型目录计算只读的“建议订柜数”，不直接创建正式订舱或货柜。
 ### 3.2 暂不纳入
 - 船公司官网或第三方 API 自动抓取船期。
 - 自动订舱、舱位分配、放舱、拖车、报关和实际出仓状态推进。
 - 自动归班、预报消费、实收批次绑定、取消后自动改配和异常重新安排。
 - 在收货审核、测量审核或智能排柜流程中增加回调、写入或阻断。
 - 复杂的价格计算、客户报价和财务结算。
 - 以计划日历替代现有订舱/柜次船期事实。
 - 在没有业务确认前自动修改历史入仓数据或批量回溯全部历史货量。
 - 复杂节假日规则、跨时区排班和通知中心；这些作为后续扩展点保留。
 - 容量预占、超容强制处理、正常货量的批量改绑和跨客户拆分；异常货的最小重新安排按第 6.10 节纳入 V1。
 ## 4. 核心概念与生命周期
 | 对象 | 作用 | 关键生命周期 |
 | --- | --- | --- |
 | 渠道 Channel | 表示一类运输服务，如 MATSON / 美森 | `ACTIVE`、`INACTIVE` |
 | 船期模板 Schedule Template | 描述每周固定规律；固定添加一班直接创建实例，不再套一层单次模板 | `DRAFT`、`ACTIVE`、`INACTIVE` |
 | 船期实例 Sailing | 某一具体日期的某一班船，是日历和货量统计的主体 | `DRAFT`、`OPEN`、`CLOSED`、`DEPARTED`、`CANCELLED`、`COMPLETED` |
 | 归班事实 Sailing Assignment | 保存预计量/收货批次与船期的自动归班结果及历史 | `FORECAST_MATCHED`、`RECEIVED`、`LATE`、`UNMATCHED`、`SUPERSEDED` |
 | 订舱关联 Sailing Booking Link | 将已放舱订舱的柜型需求关联到计划船期，用于订柜建议 | `ACTIVE`、`REVOKED` |
 模板生成实例后，实例保存自己的船名、航次、港口、截仓时间和容量快照。以后修改模板不回写已经生成、已编辑或已关联货量的实例；需要调整时由运营人员编辑实例或重新生成未落地的未来实例。
 ## 5. 页面信息架构
 ### 5.1 顶部筛选和操作区
 - 月份：默认当前月，提供上月、下月和“今天”。
 - 收货仓：按仓库筛选；船期计划至少要绑定一个收货仓，不能只靠渠道和起运港推断。
 - 出发港：按港口代码和名称筛选。
 - 船期渠道：按启用渠道筛选，停用渠道仍可用于查询历史。
 - 船名/航次：模糊搜索。
 - 状态：全部、可收货、已截止、已取消、已开船、已完成。
 - 归班状态：全部、预计可赶船、已收、晚到、未安排；用于把“漏排或赶不上”的货量变成运营待办。
 - 操作：`新增船期`、`渠道与模板管理`。
 另设“待安排/异常货量”入口，集中展示当前权限和仓库/渠道范围内仍待处理的货物，显示实际收货日或预计到仓日、等待天数及异常原因。未安排记录没有开船日期，不强行放进某个开船月，也不混入月历主合计；切换月份不使这些待办消失。
 筛选条件应由服务端参与查询，不能先拉取整月全部记录后在浏览器本地拼装统计。
 ### 5.2 月历区
 - 周一至周日为列，显示跨月日期但以浅色区分。
 - 每个日期格显示当天船期数量和航线摘要。
 - 摘要优先显示渠道名和收货体积，例如“美森 120 m³ / 200 m³”；渠道较多时显示前几项并提供“更多”。
 - 当前日期、选中日期、已截止日期、容量超限日期分别使用清晰但不依赖颜色的标签/图标表达。
 - 点击日期后，右侧详情区同步刷新；点击船期卡片可直接进入实例详情。
 ### 5.3 选中日期详情区
 每个船期卡片至少展示：
 - 渠道、船名、航次和船期业务编号。
 - 起运港 → 目的港。
 - 预计开船、预计到港、最终收货截止时间。
 - 已收总量、本船可赶实收、预计可赶、晚到量、已订柜数、建议订柜数和待补柜数；各指标按第 6.6 节计算，已收总量不能直接当作可赶量。班次容量上限和剩余体积仅在已配置班次容量时展示，V1 不因容量不足自动改绑或强制拦截。
 - 当前状态和风险提示：已过截止、接近满舱、超过容量、已取消。
 - `编辑`、`复制为下一班`、`取消船期`、`查看货量明细`。
 删除仅适用于未开船、未关联任何货量的草稿/实例；有货量或已产生履约事实的实例只能取消，不能物理删除。
 ### 5.4 新增/编辑弹窗
 弹窗提供两个明确入口：
 **按周添加**
 - 选择渠道、起运港、目的港。
 - 选择收货仓；同一渠道可按不同收货仓配置不同截止规则。
 - 选择一个或多个周几。
 - 选择开船时间、航程天数或预计到港时间。
 - 设置提前收货天数、有效起止日期和默认容量。
 - 设置船名固定值或船名规则；设置航次生成规则。
 - 选择未来生成范围（建议 4 / 8 / 12 周）。
 - 先预览将生成的实例，再确认批量生成。
 **固定添加一个**
 - 直接填写开船日期时间、船名、航次、起运港、目的港。
 - 填写或确认收货截止时间、预计到港时间、容量。
 - 保存为一条独立实例，可选关联一个模板作为来源。
 周模板中的船名是生成实例的默认值；船司确认后可逐班编辑船名、航次和截止时间。当前展示版编辑实例时保留已保存的绝对截止时间，切换到“按开船前 N 天”后才重新计算；规则快照和覆盖原因待后端契约补齐后再做完整留痕。
 ### 5.5 区间汇总
 月历上方建议提供当前筛选范围的渠道汇总卡：已收实测 CBM、预计可赶 CBM、风险/未安排 CBM、已订柜数、建议订柜数、待补柜数、晚到批次数和船期数量。V1 卡片固定标明“按开船月”，收货月仅在详情和后续报表中使用；多班同渠道同日时仍按船期实例分开，不能只显示一个渠道总数。
 ## 6. 业务规则
 ### 6.1 收货截止时间
 首版把“收货截止时间”正式命名为**最晚到仓时间 `warehouseCutoffAt`**，表示货物最晚什么时候到达我司收货仓，和船公司的截单、截关、截港时间分开保存。默认公式：
 ```text
 最晚到仓日期 = 预计开船本地日期 - 提前收货天数
 最晚到仓时间 = 收货仓截收时刻
 ```
 - 计算使用仓库业务时区，V1 默认 `Asia/Shanghai`；接口统一传 ISO 8601 时间。
 - 计划截止计算只基于实例保存的计划 `etdAt`；后续实际开船时间属于订舱/船节点事实，不反向改写已经产生的收货归班。
 - “提前 N 天”首版固定按自然日计算；工作日和节假日规则放到后续工作日历阶段。
 - 若收货仓暂未配置截收时刻，首版按 18:00 默认并记录规则来源，不能由前端使用浏览器本地时刻隐式补齐。
 - 首版默认使用 `3` 个自然日和 `18:00`；这个默认值不是从截图推断的，而是初始运营参数，后续按试运行数据校准。
 - 单班页面允许选择提前 2/3/4 个自然日或自定义本班截止时间；当前展示版保存计算后的最终 `warehouseCutoffAt`，规则快照与覆盖原因审计字段待后端契约补齐后再启用，页面不宣称已完成服务端留痕。
 - 最终截止时间必须严格早于开船时间；开船时间、截止时间和容量的校验由服务端最终执行。
 - 时间边界统一到毫秒：实际/预计到仓时间等于截止时间视为准时；当前时间大于截止时间才停止新归班，不能由不同页面采用不同的 `<`、`<=` 判断。建议值由服务端计算并返回，前端只展示。
 - 是否跳过周末/节假日、节假日向前顺延几天，需要在产品确认后接入工作日历，不能由前端自行猜测。
 ### 6.2 每周模板生成
 - 按模板有效期和周几生成具体日期，跨月日期仍属于实例，查询某月时按开船时间落入月份返回。
 - V1 采用“预览后手工确认生成”，不做后台滚动生成；页面默认未来 8 周，并提供未来 4/8/12 周快捷范围，生成范围由操作人确认后提交。
 - 生成请求必须幂等；同一模板、日期、航次规则只能生成一条有效实例。
 - 已编辑、已关联货量、已关闭、已开船或已完成的实例不被重新生成覆盖。
 - 发现相同日期/航次冲突时返回冲突清单，让用户选择跳过或进入实例处理，不能静默覆盖。
 - 模板停用只阻止未来生成，不删除历史实例。
 - V1 如遇某周停航或临时改船，允许在生成预览中跳过日期或生成后取消实例；节假日批量例外规则放到后续阶段。
 - 去重和冲突检查必须跨模板执行，至少按“收货仓 + 渠道代码 + ETD 本地日期时间 + 航次”判断，不能只用 `template_id + date` 作为唯一键。
 - 同一收货仓、渠道、起运港和目的港下，若多班船的 ETD 相同，V1 按不可变的 `sailing_no` 升序确定唯一归班；复杂的运营优先级后置。
 ### 6.3 航次号和船名
 V1 支持固定值和“前缀 + ETD 本地日期”两种航次生成规则；每个生成实例允许人工覆盖航次。顺序号和按船名递增规则后置，避免首版因船公司编号规则不同而误生成正式航次。
 业务唯一性首版约束“收货仓 + 渠道代码 + 起运港 + 目的港 + ETD 本地日期时间 + 航次”；同一航次跨不同起运港可以存在，但不能在同一组合内重复。`sailing_no` 在实例创建时生成后保持不变，用于同一 ETD 的确定性排序；展示给用户的业务编号应为船期编号、船名和航次，不能回退显示数据库 ID。
 ### 6.4 可赶船判断和人工改绑
 默认推荐某一入仓记录时，只允许候选实例同时满足：
 - 渠道、起运港和目的港匹配。
 - 状态为 `OPEN`，且当前时间未超过最终收货截止时间。
 - 后续启用容量控制时再校验未超过容量；V1 只展示已配置容量和超量提示，不因容量字段缺失阻断归班。无上限实例可明确标记为“不限舱位”。
 - 按“最早可开船”或产品确认的优先规则排序。
 超过截止时间时不能自动分配到该船期；容量不足在 V1 只显示明确预警，不阻断自动归班，也不能把预警状态伪装成已锁定舱位。任何已关闭、已取消或已开船的船期都不能作为新的自动归班候选。人工改绑必须记录操作者、原船期、新船期、时间和原因。
 建议把“预计归班”和“实际收货统计”分成两条事实：
 - 预计归班可使用入仓单的 `expectedArrivalAt`，只有预计到仓时间早于或等于最终截止时间，才标记为“预计可赶船”。没有预计到仓时间的记录进入“待确认”，不能凭渠道名称或创建时间猜测。
 - 实际统计使用已确认的实际收货时间和审核后的实测体积。已有计划归班的货实际到仓晚于截止时，保留原计划并标记“晚到风险”，不能自动塞到下一班。首次形成实收事实且从未归班的货，若仓库、正式渠道和航线明确，可首次自动选择仍开放且未过截止的最早匹配船期，同时校验实际到仓时间不晚于该船截止；无候选或资料不全则写入“未安排”。因取消、晚到而进入未安排的货不属于“从未归班”，须走第 6.10 节。
 - 同一收货批次只能有一个有效计划归班。自动匹配以收货仓、渠道、港口和最早可赶上的有效实例为条件；同一时间存在多班时，必须有固定排序规则。
 - 归班在入仓计划审核、预计到仓时间/渠道/仓库变化或实际收货确认时重新计算；船期取消时只新增一条 `UNMATCHED` 变更记录并标记待人工处理，不自动塞入下一班。船期仍为 `OPEN` 且尚未达到最终收货截止时间、没有锁班/订舱事实时允许动态重算。船期达到截止时间后冻结当前归班，即使实例仍显示为 `OPEN` 也不再自动换到下一班；截止前尚未匹配的对象才继续寻找后续可赶船。运营确认订舱、船期进入 `CLOSED` 或船期取消后的改配必须产生新的人工或明确改配记录。
 建议的状态落库规则是：预计匹配但尚未收货为 `FORECAST_MATCHED`；实际收货时间不晚于截止且有审核实测体积为 `RECEIVED`；实际收货晚于截止仍沿用原计划为 `LATE`；没有可解释的计划归班为 `UNMATCHED`；重新计算后被新结果替代的旧记录为 `SUPERSEDED`。这些状态首版必须持久化，详情中追溯匹配规则、时间、来源和被替代关系。
 首版自动归班采用“写入事实 + 版本化重算”：
 - 预计匹配、实际收货、晚到和未安排都写入归班事实，不能只在查询时临时计算。
 - 船期仍为 `OPEN` 且未锁班时，重新计算不覆盖旧记录，而是将旧记录标记 `SUPERSEDED` 并写入新版本。
 - 船期进入 `CLOSED` 或已确认订舱后，原归班结果保留；取消、甩柜或改配只新增变更记录，不静默改写历史。
 - V1 仅开放第 6.10 节的异常重新安排，来源记录为 `MANUAL`；正常货量的批量改绑、拆分分配和强制赶船后置。
 - 冻结的是船期归属，不是收货事实的数值。冻结后最终审核、复测、冲正仍更新事实版本及其统计值；原归属保留，不因数值变化自动换船。
 ### 6.5 货量统计
 V1 建议至少将“已收体积”和“预计体积”分开；“预占体积”只有在确认需要锁定容量后再启用：
 - **已收体积**：入仓事实已达到产品确认的可计入状态，并有有效体积。
 - **预计体积**：按预计归班的未收货量单独展示，不直接计入“已收体积”，也不自动扣减容量，除非产品确认要按预计量锁舱。
 - **预占体积**：已明确锁定该船期但尚未形成收货事实的货量；V1 若不做预占则固定为 0。
 - **剩余体积**：配置容量上限时按 `容量上限 - 已收体积 - 预占体积` 计算；V1 未启用预占时预占值为 0，预计体积不扣减剩余容量；结果不得小于 0，无上限显示“—”。
 体积字段必须统一单位为 m³，并保存统计快照时间。V1 只统计明确达到“已收货”状态、且有正数 `actualVolumeCbm` 的收货批次；实测体积是后续作业的权威输入，申报体积仅作对比，计费体积不能冒充“已收体积”。当前 `inboundedAt` 会在多个入库流程节点写入，不能单独视为最终收货事实；V1 必须新增或正式暴露稳定的收货批次事实，不能把 `inboundedAt` 作为替代。取消、草稿、作废或不符合统计口径的记录不计入已收体积。拆批、复测和冲正均按收货批次版本守恒。
 ### 6.5.1 V1 数据来源契约（必须一并实现）
 当前入仓模型已经有 `warehouseId`、`channelCode`、`expectedArrivalAt`、`actualVolumeCbm` 和测量审核状态，但没有稳定的收货批次 ID、实际收货时间和可靠的未收预计 CBM；现有 `originalVolumeCbm` 是客户申报值，不能作为预计可赶体积。首版必须补齐下面两类事实，不能在页面层临时拼接：
 | 事实 | V1 必须提供的字段 | 统计和归班规则 |
 | --- | --- | --- |
 | 收货批次事实 `ReceiptBatchFact` | `receiptBatchId`、`inboundId`、`receivingWarehouseId`、`channelCode`、起运港/目的港快照、`receivedAt`、`actualVolumeCbm`、最终测量批次 ID、审核状态、冲正/作废状态 | 仅 `RECEIVED/APPROVED` 且实测 CBM 大于 0 的批次计入已收；复测替换同一批次最新有效值，冲正/作废不重复计入 |
 | 未收货量预报 `InboundVolumeForecast` | `forecastId`、`inboundId` 或可收货批次键、收货仓/渠道/起运港/目的港、`expectedArrivalAt`、`forecastVolumeCbm`、来源、有效状态、版本和更新时间 | 只有有效状态、预计体积大于 0 且有 ETA 的预报可计入预计可赶量；不得使用 `originalVolumeCbm`、申报箱数或计费体积代替 |
 补充规则：
 - 当前系统没有上述稳定事实的部分，V1 必须由 Firstleg 提供正式的收货批次和货量预报服务事实；页面不直接读取入仓单分页拼装。没有可靠预报时允许只显示已收和风险，但应显示“未提供有效预报”及缺资料票数，不能把未知量写成“预计无货”。数据生产入口按第 6.5.2 节落地。
 - 预报和实收按明确的预报批次关联，不以同一 `inboundId` 就认定整票预报已收完。实收只替换其明确对应的预计批次；未到货部分保留独立有效预报，禁止用实测 CBM 直接减整票预计 CBM。具体拆批与复测规则见第 6.5.2 节。
 - 航线匹配优先使用入仓/预报事实中的起运港和目的港；事实缺失时，仅当启用渠道存在唯一的默认起运港/目的港映射，才使用该映射并保存 `route_source=CHANNEL_DEFAULT`。渠道没有唯一默认航线时进入 `UNMATCHED`/风险，不按目的仓名称或自由文本猜测。
 - 一票分批到仓时按批次统计；复测、冲正和作废必须以版本或状态替换旧值，并保留审计历史。
 - 收货仓、渠道或航线缺失时，批次/预报进入 `UNMATCHED` 或风险清单，不得按渠道名称、订单创建时间或目的地名称猜测。
 日历汇总应与右侧详情使用同一服务端统计口径，避免页面格子和详情卡片出现不同数字。建议由服务端按收货仓、渠道、船期、收货日聚合后一次返回；前端不得跨分页拉取入仓单再自行求和。超过容量时返回明确的 `overCapacity=true`，前端只负责展示。月历按开船日期展示班次，详情中应能展开实际收货日期和未安排/晚到记录，避免把“收货发生日”和“船期开船日”混为一个日期。
 日期维度固定为两种：月历落格使用 `etdAt` 的本地日期；已收体积明细保留收货批次的 `receivedAt` 日期。V1 月历默认按“开船月”汇总，并将归属该船期的已收实测体积展示在对应开船日；收货月只用于详情展开和后续报表，不参与首版月历主合计。没有稳定 `receivedAt` 的批次只能进入风险/未安排，不能回退使用 `inboundedAt`。月历主合计排除已取消实例；取消实例仍可查历史快照，当前货量进入独立异常待办，重新安排后只计入目标实例，不能在两班重复相加。
 ### 6.5.2 事实产生、分批收货与预报替换
 - **实际收货来源**：仓库完成一批到货确认时生成稳定收货批次业务键，记录真实 `receivedAt`、仓库和对应箱/件范围；最终测量审核通过后，该批次的实测体积才能计入已收。到货确认和最终审核是两个独立条件，审核操作时间不能冒充实际到仓时间。到货待审核单列票数；体积未知显示“待测量”，不补成 0 m³。
 - **未收预报来源**：V1 推荐由运营在入仓详情的“货量预报”区域维护预计批次、预计到仓时间、预计 CBM 和航线，Firstleg 保存来源、录入人及版本；更新/作废预报沿用入仓写权限，服务端核验仓库范围。日历消费这些正式事实。客户申报值可作录入参考，但不得未经运营确认直接成为有效预报。
 - **分批规则**：一条有效预报表示一批可对应收货的货物；部分到仓前或确认到仓时，将其拆成“本次到货预报部分”和“剩余未到货部分”，子批次保留父预报键、各自预计 CBM 和预计到仓时间。拆分必须显式确认且预计量合计等于拆分前预计量；修订预计总量则另存一个有原因的新版本。
 - **替换规则**：本次到货批次一经确认，就停止把该部分计为未收预报；尚未测量审核时归入“已到待审核”，审核通过后用该批的实际体积替换。剩余批次继续按自己的预计体积统计。复测只更新对应实收批次，不能改变其他未到货批次的预计量。
 - **无法对应**：实收与预报无法确认对应关系时，相关预计量暂列“待核对”，不与可能重复的实收量一起计入可赶总量；展示缺口原因，运营补齐关系后再恢复。不得凭实测体积相近自动抵消。
 - **首版批次关联入口**：审核事件若能携带 `SAILING_FORECAST:<forecastKey>`，服务端只消费该预报批次；多条有效预报且事件没有明确批次键时，实收保持 `UNMATCHED`/待核对，不自动按相近体积抵销。运营可通过预报维护接口显式绑定实收批次、修订预报或作废预报，所有动作均追加版本并保留原记录。
 - **事件与版本**：到货、审核、预报修订/拆分、冲正和作废均带稳定业务键及版本；同一事件重复到达不重复记量。来源版本更新与归班更新必须具备重试及对账机制，返回事实版本、归班版本和计算时间，不能只声明建了四张表就认为数据链路完成。
 示例：整票预计 100 m³，先拆成本批预计 40、后批预计 60。本批实际到货审核后为 45，则“已收 45 + 未收预计 60 = 可赶 105”；复测为 43 后变成 103。不能用 `100 - 45` 把后批预计改成 55。
 ### 6.6 订柜数量建议
 订柜数量是只读的运营建议，不是正式订舱或货柜创建。首版按以下口径展示：
 ```text
 本船可赶实收 CBM = 当前有效归班为 RECEIVED 的审核实测 CBM
 可赶总 CBM = 本船可赶实收 CBM + 有效未收预计可赶 CBM
 已收口径建议柜数 = 向上取整(本船可赶实收 CBM / 规划装载容量)
 建议订柜数 = 向上取整(可赶总 CBM / 规划装载容量)
 已订规划容量 = 求和(每个有效订舱需求的柜数 × 该柜型规划装载容量)
 待补 CBM = max(0, 可赶总 CBM - 已订规划容量)
 待补柜数（某柜型方案） = 向上取整(待补 CBM / 该方案柜型规划装载容量)
 ```
 - “有效预计 CBM”只取有明确预计到仓时间、渠道/仓库/航线匹配且不晚于最晚到仓时间的有效入仓计划；没有 ETA 的货列为风险，不直接导致多订柜。
 - `LATE` 仍保留在该船历史和已收总量中，但不计入本船可赶实收或订柜建议。已收总量与可赶量是不同指标，不要求相等。
 - 超过截止但尚无到货确认的原预报，保留原归属并标为“到仓待核实”，退出有效预计可赶量；实际到货事实到达后依据真实到仓时间判为准时或晚到。不得仅凭“当前时间已过截止”把所有未审核批次判成晚到。
 - `规划装载容量`、柜型、重量和装载约束复用现有统一柜型目录和智能排柜规则，不在船期日历中另写一套容量或利用率。未选择柜型时，按 40GP/40HQ/45HQ 分别展示方案，不能给出无条件的单一柜数。
 - 已订柜型混合时，展示各柜型数量及合计柜数，先按各自规划容量折算已订容量再计算待补量；不能拿“已订 1 个小柜”直接抵掉“建议 1 个大柜”。柜型容量缺失时待补数显示“待核实”，不默认为 0。
 - 班次容量上限只触发超量预警，不用它截断可赶总量。例如可赶 150 m³、班次上限 100 m³，建议仍按 150 m³ 计算，并标明超出 50 m³；不能少显示所需柜数。
 - 各柜型方案表示“如果待补量全部采用该柜型”的体积初算，未执行重量、混装及实际摆放优化；页面不用“必须订柜数”表示已经确认的订舱指令。
 - 页面必须标注“按体积初算，最终以智能排柜/人工确认结果为准”；重量、箱数、货物混装限制或数据缺失会使结果进入风险提示。
 - 已订柜数只读取 V1 计划船期-订舱关联下的有效 `RELEASED` 订舱需求；日历只保存建议计算的输入、规则版本、计算时间和结果快照，不直接生成正式柜次。
 ### 6.7 容量提示
 - 0%～80%：正常。
 - 80%～100%：接近满舱提示。
 - 大于 100%：超容量提示；V1 不自动阻断只读汇总，也不提供绕过容量的强制关联。异常重新安排仍须满足目标船期状态、截止时间和履约锁定校验。
 - 无容量上限：展示“—”或“不限”，不参与百分比计算。
 ### 6.8 船期实例状态转换
 建议只允许以下状态转换：
 ```text
 DRAFT → OPEN → CLOSED → DEPARTED → COMPLETED
  └──────────────→ CANCELLED
 OPEN → CANCELLED
 CLOSED → CANCELLED（尚未开船；必须确认影响）
 ```
 `CLOSED` 表示停止收货，`DEPARTED`/`COMPLETED` 表示计划记录的运营状态，不得代替现有订舱、装柜或实际船节点事实。实例一旦有有效收货或预占记录，不能回到 `DRAFT`，取消后仍保留货量关联和审计历史。
 建议 `OPEN → CLOSED` 由服务端根据最终截止时间自动生效，页面只展示结果；`CLOSED` 不因刷新或修改筛选重新打开。`DEPARTED`、`COMPLETED` 在 V1 仅允许明确的运营动作或后续已确认事实推进，不能由“预计开船时间已到”直接推断。
 ### 6.9 停用、取消和甩柜
 - 渠道停用只阻止新模板和新实例生成；已经生成且仍为 `OPEN` 的实例默认继续有效，是否批量关闭必须由运营人员明确操作。
 - 取消实例前必须展示影响范围：预计归班量、已收量、预占量和已关联订舱/柜次。已有已收量的实例只能取消或进入改配流程，不能删除。
 - 取消后，将原有效归班标记 `SUPERSEDED`，新增 `UNMATCHED` 版本并保存原船期及 `reason=CANCELLED`，展示为“未安排/待人工处理”；不自动把货量塞进下一班。新版本保留事实引用，原版本可追溯，不原地覆盖历史。
 - 同一取消操作将有效订舱关联改为 `REVOKED`，保留历史快照；不自动作废、重开或修改正式订舱。关联解除后当前订柜统计重新计算，正式订舱是否改船由已有订舱流程处理。
 - 甩柜/改配时保留原实例、原归班和实际收货事实，新增目标实例关联；不能回写或覆盖现有港务船期、订舱资料或报关事实。
 ### 6.10 V1 受限的异常重新安排
 这是本轮推荐的范围补充，解决“异常已展示，但首版没有办法处理”的缺口。只允许处理未安排、晚到或因船期取消而待处理的货，正常批次批量改绑仍后置。
 1. 运营在异常待办选择货物，查看原船期、当前事实版本、原因及匹配候选；选择目标并填写原因后确认，保存前先显示两班的货量变化。
 2. 目标须仓库、正式渠道、港口相符，状态 `OPEN` 且当前未过截止；预报另核验预计到仓时间，实收另核验真实到仓时间。V1 不提供绕过截止、强行修改实收时间或跨仓挪量的入口。
 3. 服务端核验独立异常安排权限、当前归班版本及目标船期版本；原有效版本转 `SUPERSEDED`，新版本写 `MANUAL`，保留原/新船期、操作者、时间和原因。并发重复确认只能成功一次。
 4. 货物如已绑定真实柜次、预装或装柜履约，先阻止在日历直接改配，并指向既有履约流程；不得通过改日历归班绕过实物锁定。无符合条件的目标时继续待安排，可先新增临时船期。
 5. 归班重新安排不自动转移订舱关联；目标班的已订柜仍只来自重新校验后建立的有效订舱关联。
 ## 7. 建议数据模型
 以下为规划字段，具体命名应在接口和 SQL 评审时统一。
 ### 7.1 `fl_sailing_channel`
 | 字段 | 说明 |
 | --- | --- |
 | `id` | 渠道业务主键 |
 | `channel_code` | 稳定渠道代码；固定渠道可映射现有渠道目录，自定义渠道也必须先建立稳定代码。现有装柜的九类渠道分组只作为兼容映射，不能把枚举写死为日历渠道全集 |
 | `channel_name` | 渠道名称，如 MATSON / 美森 |
 | `source_type` | `CATALOG`（复用现有物流渠道）或 `SCHEDULE_ONLY`（仅用于排班，尚未映射为可订舱渠道） |
 | `mapped_channel_code` | 自定义排班渠道对应的正式物流渠道代码，可为空；为空时不能被订舱/价格接口当作正式渠道 |
 | `default_departure_port_code` | 默认起运港，可被模板覆盖 |
 | `default_destination_port_code` | 默认目的港，可被模板覆盖 |
 | `default_cutoff_days` | 默认提前收货天数 |
 | `status` | `ACTIVE` / `INACTIVE` |
 | `remark` | 备注 |
 | `created_at` / `updated_at` | 审计时间 |
 标准渠道优先复用现有仓库范围内的 ACTIVE 物流渠道和稳定 `channelCode`，不能只保存一个自由文本名称。自定义排班渠道必须通过 `SCHEDULE_ONLY` 明确标记，后续若要用于订舱或报价，先完成正式渠道映射。渠道停用不影响历史实例和历史统计；停用后不能新建模板或自动生成未来实例。
 ### 7.2 `fl_sailing_template`
 | 字段 | 说明 |
 | --- | --- |
 | `template_no` | 模板业务编号 |
 | `channel_id` | 所属渠道 |
 | `receiving_warehouse_id` | 收货仓；截止规则和可赶船判断的范围键 |
 | `template_type` | V1 固定为 `WEEKLY` |
 | `weekdays` | 周一至周日的选中集合 |
 | `effective_from` / `effective_to` | 规则有效期 |
 | `departure_time` | 开船本地时间 |
 | `voyage_rule` | 船名/航次生成规则快照 |
 | `transit_days` 或 `eta_time` | 预计到港计算依据 |
 | `cutoff_days` | 模板级提前收货天数 |
 | `cutoff_local_time` | 收货仓默认截收时刻，可被实例覆盖 |
 | `default_capacity_cbm` | 可选的班次计划容量；不替代统一柜型目录的柜容 |
 | `status` | `DRAFT` / `ACTIVE` / `INACTIVE` |
 ### 7.3 `fl_sailing`
 | 字段 | 说明 |
 | --- | --- |
 | `sailing_no` | 船期实例业务编号 |
 | `template_id` | 来源模板，可为空（独立单次船期） |
 | `channel_id` | 渠道快照引用 |
 | `channel_code_snapshot` / `channel_name_snapshot` | 生成时的渠道编码和名称快照 |
 | `receiving_warehouse_id` | 收货仓 |
 | `departure_port_code` / `destination_port_code` | 港口快照 |
 | `vessel_name` / `voyage_no` | 船名和航次 |
 | `etd_at` / `eta_at` | 预计开船、预计到港 |
 | `suggested_cutoff_at` | 计算出的建议截止时间 |
 | `cutoff_at` | 最终收货截止时间 |
 | `cutoff_override` / `cutoff_override_reason` | 是否人工覆盖及原因 |
 | `cutoff_rule_version` | 计算时使用的时区、自然日/工作日和截收时刻规则版本 |
 | `capacity_cbm` | 可选的班次计划容量上限；空值表示不做班次容量提示，不替代统一柜型目录的柜容 |
 | `container_type_code` | 默认柜型；为空时按可用柜型分别给出建议 |
 | `status` | 实例生命周期状态 |
 | `generated_key` | 模板生成幂等键 |
 | `version` | 乐观锁版本 |
 | `created_at` / `updated_at` | 审计时间 |
 不建议把已收体积、剩余体积作为可直接修改的主表字段；它们应由关联事实聚合，必要时做带统计时间的服务端快照。
 ### 7.4 `fl_sailing_assignment`（V1 自动归班；V1 受限异常重新安排）
 V1 必须由服务端持久化自动归班结果；常规人工改绑、拆分分配和预占仍放到 Phase 2，第 6.10 节的异常重新安排除外。归班对象以收货批次或货量预报为最小粒度，不以整张订单或整张入仓单代替。`sailing_id` 可以为空，表示已记录但尚未找到可解释班次的 `UNMATCHED` 结果。
 | 字段 | 说明 |
 | --- | --- |
 | `id` | 归班事实 ID |
 | `sailing_id` | 船期实例；`UNMATCHED` 时为空 |
 | `inbound_id` / `receipt_batch_id` / `forecast_id` | 归班对象；至少有一个稳定业务键 |
 | `assignment_source` | V1 为 `AUTO`；预留 `MANUAL`、`ROLLOVER` |
 | `assignment_version` | 同一归班对象的版本号，重算递增 |
 | `match_status` | `FORECAST_MATCHED` / `RECEIVED` / `LATE` / `UNMATCHED` / `SUPERSEDED` |
 | `volume_cbm` | 本次归属的已收实测体积；V1 固定来自审核后的 `actualVolumeCbm` |
 | `forecast_volume_cbm` | 本次归属的未收有效预计体积，与已收体积分开 |
 | `forecast_source` | 预计体积来源；没有可靠预计体积时为空，不得用申报值冒充已收体积 |
 | `route_source` | 航线来自入仓/预报事实或 `CHANNEL_DEFAULT`，用于追溯匹配依据 |
 | `volume_source` | 已收状态固定为 `MEASURED_ACTUAL`；仅预计状态为空，计费/申报仅作对比或后续扩展 |
 | `rule_version` | 自动归班规则版本 |
 | `matched_at` / `superseded_at` | 归班和被替代时间 |
 | `locked_at` / `lock_reason` | 达到船期截止、确认订舱或船期关闭后冻结归班的时间和原因 |
 | `operator_id` / `reason` | 自动任务/后续人工操作审计 |
 同一批次或预报在同一时刻只能有一个 `AUTO` 有效归班版本；重新计算采用旧版本 `SUPERSEDED` + 新建版本，不能静默覆盖旧历史。
 “同一业务对象”在这里指收货批次，不是整票订单或整张入仓单；一票分批到仓、复测或冲正时，必须按批次守恒，不能用单据级唯一键把后续批次锁死。
 ### 7.5 `fl_sailing_booking_advice_snapshot`
 这是订柜建议的可追溯快照，不是正式订舱记录。每次刷新或人工确认建议时保存：
 | 字段 | 说明 |
 | --- | --- |
 | `sailing_id` / `container_type_code` | 船期和柜型 |
 | `received_cbm` / `forecast_catchable_cbm` / `risk_cbm` | 已收、可赶预计和风险体积 |
 | `planning_capacity_cbm` | 从统一柜型目录读取的规划容量快照 |
 | `recommended_container_count` | 按体积初算的建议柜数 |
 | `booked_container_count` / `shortage_count` | 已订柜数和待补柜数 |
 | `rule_version` / `calculated_at` | 计算规则版本和计算时间 |
 | `risk_codes` | ETA 缺失、重量缺失、箱数缺失、混装限制等风险 |
 ### 7.6 `fl_sailing_booking_link`（V1 最小订舱关联）
 首版要显示“已订柜数”和“待补柜数”，因此必须在 V1 建立计划船期与订舱的最小关系；复杂的实际柜次、甩柜和海运节点关联仍放到后续阶段。
 | 字段 | 说明 |
 | --- | --- |
 | `sailing_id` | 计划船期实例 |
 | `ocean_booking_id` | 海运订舱 |
 | `link_status` | `ACTIVE` / `REVOKED`；解除关系保留历史 |
 | `booking_status_snapshot` | 关联时的订舱状态快照；当前只有订舱状态为 `RELEASED` 才允许计数 |
 | `warehouse_id` / `channel_code` / 起运港 / 目的港 | 关联时的业务匹配快照 |
 | `linked_at` / `operator_id` / `reason` | 关联审计 |
 V1 采用以下计数契约：
 - 只有当前订舱状态为 `RELEASED` 且关联记录为 `ACTIVE` 的订舱才计入已订柜；`DRAFT`、已作废或已解除关联的不计入。`RELEASED` 是订舱状态，不是关联记录状态。
 - 已订柜数按该订舱的柜型需求 `quantity` 汇总，不按已生成真实柜次数量、不按装柜完成数量替代。
 - 一个 `RELEASED` 订舱首版只能关联一个计划船期；如果未来需要一个订舱拆到多班，再升级到按柜型需求行分摊的关系。
 - 关联时必须校验收货仓、渠道代码、起运港、目的港和计划船期一致；不一致进入冲突，不允许仅凭船名/航次文字关联。
 - 订舱解除、作废或计划取消后，已订柜数应在服务端重新计算，并保留原关联历史；不得把已订柜数当作人工可编辑字段。
 ## 8. 接口草案
 接口路径和 DTO 以最终服务端归属为准，以下只作为拆分和评审入口：
 | 能力 | 建议接口 | 说明 |
 | --- | --- | --- |
 | 月历查询 | `GET /platform/v1/sailings/calendar` | 按月份、收货仓、港口、渠道、关键词、状态返回实例和服务端汇总；同时返回未安排/晚到摘要 |
 | 实例详情 | `GET /platform/v1/sailings/{sailingId}` | 返回实例、统计、关联货量和操作权限 |
 | 新增单次实例 | `POST /platform/v1/sailings` | 幂等创建，支持无模板来源 |
 | 编辑/取消实例 | `PUT/PATCH /platform/v1/sailings/{sailingId}` | 乐观锁；取消保留历史 |
 | 渠道管理 | `GET/POST/PUT /platform/v1/sailing-channels` | 启用、停用和主数据维护 |
 | 模板管理 | `GET/POST/PUT /platform/v1/sailing-templates` | 周模板和启停；固定单次船期直接走实例接口 |
 | 生成预览 | `POST /platform/v1/sailing-templates/{id}/generation-preview` | Phase 1 必须支持；返回日期、航次、冲突和截止时间预览 |
 | 批量生成 | `POST /platform/v1/sailing-templates/{id}/generate` | 使用幂等键，返回成功、跳过和冲突清单 |
 | 货量明细 | `GET /platform/v1/sailings/{id}/volume-summary` | V1 返回自动归班结果、服务端汇总和收货批次明细，不要求已经存在人工改绑 |
 | 收货批次事实 | Firstleg 服务正式事实查询（路径以 Controller 归属评审为准） | 提供 `receiptBatchId`、`receivedAt`、最终实测 CBM、审核/冲正状态及仓库/渠道/航线快照；船期页面不得从入仓单分页自行拼装 |
 | 货量预报事实 | Firstleg 服务正式事实查询（路径以 Controller 归属评审为准） | 提供 `forecastId`、`expectedArrivalAt`、`forecastVolumeCbm`、有效状态、版本和来源；没有可靠预报时只返回风险/未安排 |
 | 订柜建议 | `GET /platform/v1/sailings/{id}/booking-advice` | 按柜型返回已收、可赶预计、风险、已订柜、建议柜数和待补柜数；只读 |
 | 订舱关联 | `POST /platform/v1/sailings/{id}/booking-links` | V1 关联一个 `RELEASED` 订舱并校验仓库、渠道、港口和船期；只建立最小关系，不创建柜次 |
 | 手工关联/改绑 | `POST /platform/v1/sailings/{id}/volume-allocations` | Phase 2+；校验截止、容量、收货仓归属和幂等键 |
 | 变更历史 | `GET /platform/v1/sailings/{id}/history` | 实例、模板和手工改绑审计 |
 所有写接口建议使用 `Idempotency-Key`、`expectedVersion` 和服务端权限校验；错误响应应能区分重复生成、容量不足、已截止、状态冲突和归属不一致。
 ## 9. 权限建议
 权限按“看”和“改”拆分，至少包括：
 - `platform:firstleg:sailing-calendar:list`：查看月历、详情、货量汇总和只读历史。
 - `platform:firstleg:sailing-calendar:create`：新增单次船期。
 - `platform:firstleg:sailing-calendar:edit`：编辑、复制和取消。
 - `platform:firstleg:sailing-volume:exception-reassign`：V1 受限异常重新安排；只能处理取消、晚到和未安排货量，不能绕过截止、容量或真实履约锁定。
 - `platform:firstleg:sailing-volume:bind`：常规人工改绑、拆分和预占，Phase 2+ 才启用。
 - `platform:firstleg:sailing-booking:link`：建立或解除计划船期与订舱的最小关联。
 - `platform:firstleg:sailing-template:manage`：渠道、模板、批量生成和停用。
 - `platform:firstleg:sailing-volume:bind`（Phase 2+）：关联/改绑货量。
 - 审计导出或跨业务检索如确有需要，再单独增加权限；普通详情历史不另造重复的只读权限。
 权限只由服务端决定，前端按钮隐藏不能替代后端校验。
 ## 10. 分期建议
 ### Phase 1：可用的日历排班
 - 渠道主数据、单次船期、周模板。
 - 截止时间计算和实例生成。
 - 生成预览、冲突清单和确认后批量生成。
 - 月历、日期详情、渠道维度的预计/已收体积汇总。
 - 服务端自动归班的只读结果：预计可赶船、已收、晚到风险、未安排。
 - 按现有柜型目录计算只读订柜建议：可赶总 CBM、建议柜数、已订柜数、待补柜数和风险提示。
 - 保存自动归班事实和版本历史；建立计划船期与 `RELEASED` 订舱的最小关联，用于计算已订柜数；为取消、晚到和未安排货提供受限异常重新安排。
 - 实例编辑、取消和基础历史。
 Phase 1 不提供正常货量的批量改绑、强制赶截止和容量预占；只提供第 6.10 节的受限异常重新安排。若没有明确归班事实，只展示“未安排”，不能把按渠道汇总的体积伪装成某一班船已收。
 ### Phase 2：排班辅助和容量控制
 - 模板复制和批量调整。
 - 在 V1 已实现的收货仓、渠道、港口、截止时间和确定性排序基础上，Phase 2 再增加复杂优先级、容量约束和多班冲突处理。
 - 容量阈值、超容拦截和有权限的强制处理。
 - 手工关联、改绑、预占和货量明细。
 ### Phase 3：运营增强
 - 工作日/节假日日历。
 - 月度/渠道汇总导出和报表。
 - 截止提醒、异常通知和更完整的审计检索。
 - 与真实柜次、港务船期、甩柜/改配和实际海运节点的完整可追溯关联，但不覆盖已有运输事实；V1 的最小订舱关联已经前置。
 ## 11. 验收标准
 1. 新建“美森每周周四”模板，预览并生成指定月份的所有周四实例；再次生成不产生重复实例。
 2. 新增一条固定船期，能够编辑开船时间、船名、航次、截止时间和容量；已有归班或已收货事实后只能取消，不能物理删除。
 3. 日历格和日期详情显示同一套渠道统计口径；至少能区分预计体积、已收体积、未安排/晚到和剩余容量。
 4. 根据收货仓、起运港、渠道、船名/航次和月份筛选后，月历数量、日期详情和统计合计一致；跨月日期不会重复或漏显示。
 5. 截止时间按服务端规则计算，人工覆盖有明确标识；超过截止或已取消的船期不能被自动推荐。
 6. 接近容量上限和超容量有明确状态；V1 只读提示，不能因为体积初算直接生成正式柜次。
 7. 停用渠道的历史实例可查询，停用后不能创建新的模板实例；渠道改名不改变历史实例的名称快照。
 8. 写接口具备幂等和乐观锁；重复提交、并发编辑、重复生成均返回可理解的冲突信息。
 9. 列表/详情只读、实例编辑/取消、模板管理、货量改绑分别受权限控制；操作历史可追溯到操作者和原因。
 10. 页面展示业务编号、船名、航次、港口和渠道，不以内部数据库 ID 作为用户可见回退。
 11. 对一班固定船和一班临时船，系统能分别展示已收 CBM、截止前预计 CBM、风险 CBM、已订柜数、建议订柜数和待补柜数；建议结果标注计算时间、柜型和规则版本，并明确最终以智能排柜/人工确认结果为准。
 12. 同一收货批次先产生预计归班，之后实际收货并复测；系统保留旧归班版本、只计最新有效实测体积，且不把预计体积与实测体积重复相加。
 13. 同一时刻建立两班船，自动归班结果稳定选择 `sailing_no` 较小者；船期截止后刷新页面，原归班仍显示为 `LATE` 或 `RECEIVED`，不会变成无历史的未安排。
 14. 一个 `RELEASED` 订舱关联一条计划船期，柜型需求数量计入已订柜；`DRAFT` 订舱、未关联订舱和真实柜次数量不会被错误计入。
 15. 自动归班在截止前可以重算；达到截止后原归班被冻结，后续实际收货标记为 `LATE` 时仍保留原船期。没有稳定收货批次或预报事实时只显示风险/未安排，不得用 `inboundedAt`、`originalVolumeCbm` 或入仓单分页合计补出数字。
 ## 12. 首版已冻结与后续校准
 本轮已先采用以下口径，开发按此实现：
 1. 船期模板/实例必须绑定收货仓、渠道、起运港和目的港；不使用“全部仓”作为模糊范围。
 2. 已收只统计 V1 收货批次事实中明确完成收货、最终测量审核通过且 `actualVolumeCbm > 0` 的批次；申报体积和计费体积不计入已收。
 3. V1 新增或正式暴露稳定的 `receiptBatchId + receivedAt` 收货批次事实；不能用现有会被多个流程节点更新的 `inboundedAt` 单独代替。
 4. V1 新增或正式暴露 `forecastVolumeCbm + expectedArrivalAt` 货量预报事实；`originalVolumeCbm`、申报箱数和计费体积不得作为预计可赶量。
 5. 预计可赶量只纳入有明确 ETA、预计体积、渠道/仓库/航线匹配且不晚于 `warehouseCutoffAt` 的有效预报；没有 ETA 或航线的货列为风险/未安排。
 6. 自动归班选择最早可赶的 `OPEN` 船期，并在 V1 持久化 `FORECAST_MATCHED`、`RECEIVED`、`LATE`、`UNMATCHED` 和 `SUPERSEDED` 历史；截止前且未锁班时可以版本化重算，达到截止、`CLOSED` 或已确认订舱后冻结当前归班；船期取消只转为风险/待人工处理，不自动换班；晚到不自动改班。
 7. 同一收货仓、渠道、起运港和目的港下，ETD 相同的多班船按 `sailing_no` 升序确定唯一归班；同一归班对象同一时刻只能有一个有效版本。
 8. `warehouseCutoffAt` 暂定为开船本地日期前 3 个自然日、收货仓 18:00，时区为 `Asia/Shanghai`；它与官方截单/截关/截港分开。
 9. V1 建立计划船期与 `RELEASED` 订舱的最小关联；已订柜数按关联订舱的柜型需求 `quantity` 统计，`DRAFT` 不计入，不按真实柜次数量替代。
 10. 订柜建议复用现有柜型目录、容量和已订柜事实，只读展示建议柜数和待补柜数，不直接创建正式柜次；结果标注“按体积初算，最终以智能排柜/人工确认结果为准”。
 11. V1 航次规则只支持固定值或“前缀 + ETD 本地日期”，生成实例允许人工覆盖；不做顺序号自动递增。
 12. V1 采用人工预览后生成固定周模板实例；停航或临时变更先手工跳过/取消，暂不做节假日自动日历。
 以下事项不阻断首版，但需要在试运行或进入后续阶段前校准：
 1. 多个收货仓是否能共同供货给同一班船；如果可以，建立明确的收货仓组，再做线路级合计，不能直接跨仓混算。
 2. 提前天数是否从自然日升级为工作日，周末/节假日是否接入工作日历。
 3. 渠道是否需要客户专属范围；若需要，客户必须进入模板、实例、查询和权限维度。
 4. 同一渠道同一天多班船的复杂运营优先级、航次生成规则和模板覆盖策略。
 5. 订柜建议是否支持多柜型混合、重量约束和装载率优化；首版按体积初算，最终以智能排柜/人工确认结果为准。
 6. 计划实例与真实柜次、港务船期的完整关联时机，以及甩柜、改配后的运输事实展示。
 ## 13. 工程接入门禁
 进入实现阶段后，页面与接口需要同步维护以下入口：
 - Admin 页面放在 `apps/admin-web/src/modules/` 的独立业务模块内，包含 `pages/`、`routes.ts`、`api/` 和 `types.ts`；不能把模板和实例逻辑塞入现有 `CarrierScheduleQueryPanel.vue`。
 - 正式接入时同步 `src/app/router/index.ts`、`src/core/navigation/adminNavigation.ts` 和平台 IAM 权限初始化；菜单归属应在“国内仓”与“货柜管理”中选定后固定。
 - Firstleg 若承载服务端能力，需同步 Controller、OpenAPI、数据库基线、Gateway 路由和权限契约；月历统计由服务端返回，前端不以 `InboundOrderSummary` 分页结果自行拼装。
 - 需要优先复用现有仓库范围内的正式 `channelCode`/渠道目录，再为确有需要的排班专用渠道建立明确映射；同时校验入库实测字段、订舱/货柜船期和价格簿的引用边界。新计划不能回写港务船期观测或订舱快照。
 - V1 开发前必须先落地 `ReceiptBatchFact`、`InboundVolumeForecast`、`fl_sailing_assignment` 和 `fl_sailing_booking_link` 的服务端事实与索引；Firstleg 的当前基线对应 `phase4-sailing-facts-schema.sql`、`sailingcalendar/fact/entity` 和 `SailingFactsRepository`，部署统一增量也必须包含这四张表。如果这些事实没有来源，接口只能返回风险/未安排，不能伪造已收或已订柜数字。
 - 订柜建议必须读取统一柜型目录和 `RELEASED` 订舱需求；不得另建 40GP/40HQ/45HQ 容量常量，也不得用真实柜次数量替代订舱需求数量。
 - 页面验收覆盖正常、空数据、加载、失败、无权限、并发冲突、已截止、超容量和已取消状态，并按 Admin 当前 1920×1080、100% 缩放基线执行。
 ## 14. 建议实施顺序
 1. 按第 12 节首版冻结口径建立统一的术语、体积、归班、截止时间和订柜建议规则。
 2. 画出模板、实例、货量关联和现有港务船期之间的关系，并评审权限与审计边界。
 3. 先落地服务端查询模型和月历返回结构，再实现 Admin 月历页面，避免前端自行拼装统计。
 4. 用“美森每周周四 + 一条临时船期 + 一批预计到仓数据 + 一批已收实测数据 + 一批晚到数据”做端到端造数和验收。
 5. 完成 Phase 1 后再决定手工改绑、容量预占、工作日历、导出和外部船期接入，避免首期把订舱和船公司接口一起带入。
 ## 15. 本轮复核结论与验收算例
 本轮复核后的结论是：**基础排班可以进入开发；完整的收货统计、订柜建议和异常处理必须按本节算例验收后，才能认为首版可用。** 下面的数字是验收用例，不是初始化数据，也不是对截图示例的默认值。
 ### 15.1 分批收货不能用整票相减
 - 一票有效预报拆为 A 批 40 m³、B 批 60 m³。
 - A 批实际到货并审核为 45 m³时，结果为“已收 45 m³ + 未收预计 60 m³”；不能把整票 100 m³ 直接减去 45 m³后把 B 批改成 55 m³。
 - A 批复测为 43 m³时，只更新 A 批实收版本；B 批仍为 60 m³。任一版本重复消费都不得重复计量。
 - 如果实收不能明确对应 A 或 B，相关预报暂列“待核对”，不把实收和预报同时计入可赶总量。
 ### 15.2 无预报直接收货与晚到的区别
 - 没有预报但首次形成 20 m³审核实收，且仓库、渠道、航线明确、实际到仓时间不晚于某个 `OPEN` 船期截止：自动归入该船，状态为 `RECEIVED`。
 - 已经归属于周四船的批次，实际到仓晚于周四截止：保留周四历史，状态为 `LATE`；已收总量增加，但周四的“本船可赶实收”和订柜建议不增加。
 - 没有归班、资料缺失或已过截止才首次到仓的批次进入异常待办，不能仅因体积或渠道相似自动塞进下一班。
 ### 15.3 订柜建议要排除晚到并抵扣真实柜型容量
 - 40HQ 规划容量按统一柜型目录读取，不能在日历模块复制常量。
 - 一班船有本船可赶实收 40 m³、有效未收预报 28 m³、晚到 35 m³；建议计算量为 68 m³，晚到 35 m³只在已收总量/风险中展示。
 - 若已有一个 40GP 和一个 40HQ 的 `RELEASED` 订舱关联，已订规划容量按两个柜型各自容量折算；不能只按“已订 2 柜”抵扣，也不能把 `DRAFT` 订舱计入。
 - 班次规划容量小于可赶总量时只显示超容量和超出体积，不能静默截断可赶量或降低建议柜数。
 ### 15.4 取消后的异常重新安排
 - `CLOSED` 且尚未开船的船期可以取消；取消会保留原归班和订舱关联历史，将当前货量转为异常待办，不自动改到下一班。
 - 运营有异常重新安排权限时，选择目标 `OPEN` 船期、填写原因，系统同时校验仓库、渠道、港口、截止时间、目标版本和履约锁定状态。
 - 成功后旧归班为 `SUPERSEDED`，新归班为 `MANUAL`，目标班只计一次；目标班订柜关联必须另行建立或确认，不随货量改配自动转移。
 - 已有真实柜次、预装或装柜履约锁定的货不能从日历直接改配，必须回到对应履约流程处理。
 ### 15.5 开发完成判定
 满足以下条件才通过首版业务验收：事实来源可追溯、预报和实收不重复、晚到不增加原班可赶量、取消后有异常处理入口、订柜按柜型需求折算且仅统计有效 `RELEASED` 关联、月历与详情使用同一服务端快照。仅完成页面、接口返回空数组或通过类型/编译检查，均不能作为通过依据。
 ### 15.6 成熟货代系统的排船期做法
 成熟系统把“排船期”视为一条可执行的运输计划，而不是日历上的一个标记，通常分为四层：
 1. **服务/周班模板**：维护渠道、收货仓、起运港、目的港、固定星期、开船时间、时区、默认航程和默认截止规则。固定周班按滚动窗口生成未来 8～12 周的具体航次；模板停用只影响未来生成，不回写历史实例。Oracle OTM 也支持按固定星期时间或相对开船时间的偏移配置航次截点：[Oracle Cutoff Recovery Time](https://docs.oracle.com/en/cloud/saas/transportation/26c/otmol/planning/power_data/rates_and_codes/cutoff_recovery_time_details.htm)。
 2. **具体航次实例**：每班保存自己的船名、航次、计划 ETD/ETA、内部收货截止、船司确认的各类截止、状态和容量。模板只提供默认值；船司确认或运营人工覆盖后，只更新实例并保留变更历史。
 3. **货物归班事实**：预计到仓、审核后的实收批次、体积版本和当前归属独立保存，能追溯自动归班、晚到、取消和人工改配的前后航次。
 4. **订舱执行**：预报量、已收量、已订柜量、待补柜量分开统计。只有已确认/已放舱的订舱关联计入已订柜，草稿和取消订舱不计入。
 一个航次不应只有一个“截止时间”。至少区分：我司仓库最晚收货时间、订舱接受截止、截单/SI、截关/CY、VGM，以及危险品/冷柜等特殊货类截止。DCSA 将这些作为不同的业务节点，并指出其会随船期、码头和货类变化：[DCSA Cut-off Times](https://dcsa.org/newsroom/cut-off-times-in-shipping)。VGM 还必须在装船前提前提交，才能满足装载条件：[IMO VGM](https://www.imo.org/en/ourwork/safety/pages/verification-of-the-gross-mass.aspx)。因此，本系统的“开船前 3 个自然日、收货仓 18:00”只能作为我司内部 `warehouseCutoffAt` 默认值，不能当作船司截关时间。
 自动归班采用以下顺序：先按收货仓、渠道、起运港、目的港筛选 `OPEN` 且尚未超过 `warehouseCutoffAt` 的候选，再按 ETD 最早排序。实际到仓时间等于截止时间仍算准时；超过截止时间后，未锁班、未订舱的货物自动寻找下一班，下一班不存在时进入 `UNMATCHED/待人工`。已经锁班或已确认订舱的货物即使晚到，也保留原 `sailingId`，标记 `LATE/MISSED_CUTOFF`，由运营确认是否转下一班，不能静默改写原归属。
 例如美森固定周四 10:00 开船，义乌仓内部收货截止为周二 18:00：周二 17:59 和 18:00 到仓的货物可赶本周四；周二 18:01 首次到仓的货物只能进入下一周四；已经确认归属本周四的晚到货物则保留本周四并进入晚到异常。
 建议状态补充 `NEAR_CUTOFF` 和 `BOOKING_CONFIRMED/LOCKED`。`NEAR_CUTOFF` 只用于预警，仍允许收货；超过内部截止后由服务端禁止新的自动归班。船司延误、甩柜或取消时，保留原实例和归班历史，生成异常待办并要求明确改配，不直接把货物静默塞入下一班。
 ### 15.7 从当前版本到可运营版本的改造顺序
 结论是保留现有“模板 → 航次实例 → 收货归班 → 货量汇总 → 订柜建议”主模型，不重做日历页面，先补齐以下规则和闭环。
 **P0：上线前必须完成**
 1. 服务端统一执行收货截止门禁。候选航次必须同时满足 `status=OPEN` 和 `arrivalAt <= warehouseCutoffAt`；首次晚到不能继续挂当前航次，已存在归班的晚到只能保留原航次并标记 `LATE`。
 2. 建立锁班和字段冻结。已有确认订舱、人工锁班或履约事实后，禁止直接修改收货仓、渠道、港口、ETD、截止时间等关键字段；需要调整时走复制、取消或异常改配。
 3. 完善预报与实收的批次关联。同一收货批次只能消费一个有效预报；多个预报、错误的预报键、预报作废和拆分必须进入待核对，不能同时计入预报量和实收量。
 4. 取消/甩柜只产生异常待办，不自动把货物静默塞进下一班；人工改配必须记录原航次、目标航次、操作者、时间、原因和目标版本。
 5. 收货仓、渠道、起运港和目的港使用主数据选择并由服务端校验，不能长期依赖前端自由填写名称或 ID。
 6. 月历和详情只统计同一服务端口径：已收使用审核实测 CBM，晚到不计入原班可赶量，取消航次不计入主汇总，已订柜只统计有效的 `RELEASED/CONFIRMED` 关联。
 **P1：首版稳定运行后完成**
 1. 增加预报维护、异常待办、人工改配、订舱关联/撤销等 Admin 操作入口。
 2. 模板支持完整有效期、停班例外、跨月生成和生成前冲突预览；默认滚动生成未来 8～12 周。
 3. 增加 `NEAR_CUTOFF`、待补柜、超容量、未安排等风险提示，并提供按渠道的 CBM 和柜量分组汇总。
 4. 所有写操作接入统一幂等和版本校验，避免重复点击、重复生成和并发覆盖。
 **P2：运营增强**
 再接入船司/码头实际截点、节假日工作日历、容量预占、自动提醒、外部船期同步和更复杂的混合柜型优化。它们不应阻塞首版排船和收货统计上线。
 ### 15.8 当前展示版范围修正（以本节覆盖前文自动归班口径）
 本轮需求已明确：船期日历先作为**展示和决策辅助页面**，不接管现有收货、预报、智能排柜或订舱流程。前文关于 `Sailing Assignment` 自动写入、自动下一班、晚到改配、取消后异常重排和收货审核回调的内容，全部降为后续规划，不纳入当前开发验收。
 当前版本允许运营人员维护渠道、周模板和具体船期；货量相关能力全部只读：
 - **已收 CBM**：读取现有收货/测量流程已经产生的有效实测结果，不在船期页面重新生成收货事实。
 - **预计 CBM**：读取现有入仓预报或智能排柜可读数据；没有可靠来源时显示“暂无数据”，不凭渠道名称或订单分页猜测。
 - **截止前参考量**：按船期的收货仓、渠道、起运港、目的港和 `warehouseCutoffAt` 做查询口径，只用于显示“理论上可供管理人员参考的货量池”，不表示货物已经归入该船。
 - **已明确本船量**：只读取现有系统已经明确关联到该船名/航次或现有订舱/柜次事实的数据；日历不新增关联。
 - **建议订柜数**：按可展示货量和统一柜型容量做初算，显示计算时间、柜型和“最终以智能排柜/人工确认结果为准”；不创建订舱、不锁舱位、不改柜次。
 - **合船判断**：页面只提供“本船未满、建议关注相邻船期”的提示，并展示相邻船的可用容量和货量对比；不自动合并、不自动改绑。
 展示版的数据实现口径再明确一层：已收实测只统计测量审核为 `APPROVED` 且有 `actual_volume_cbm` 的有效入库单，按上一班截止时间到当前班截止时间的窗口汇总；主单只在未拆分时统计，拆分后的有效余量子单单独统计，避免父子单重复。当前没有可核验的预计体积来源时，预计量按 0 展示并在页面提示“暂无可核验数据”，不得把申报体积、原始体积或分页列表合计冒充预计量。已订柜读取已放舱订舱的柜型需求，优先识别已有船期关联，同时允许用仓库、渠道、港口、船名、航次和开船日期做确定性只读匹配；日历页面不创建关联。建议柜数只按统一柜型容量计算，待补柜只做提示。
 当前版本明确不做以下写操作：
 1. 收货审核通过时，不调用船期日历服务，不写入 `fl_sailing_assignment`、预报消费或船期实收事实。
 2. 创建或修订预报不自动生成船期归班；预报维护接口不作为本轮页面入口。
 3. 取消船期不自动把任何货物转到下一班；货物归属仍由原智能排柜和订舱流程维护。
 4. 页面不提供货量异常改配、手工绑定实收、订舱关联/解除等操作；这些操作留在现有业务流程。
 因此，本轮验收重点从“自动归班正确”改为：船期维护正确、展示口径透明、已收/预计/已订柜/建议柜数不重复、取消或截止只影响展示标签、不会改变原收货和智能排柜数据。后续如果需要让管理人员在页面上确认“合并到哪一班”，再单独增加人工确认动作和正式归属模型。
@@ -0,0 +1,108 @@
 # 墨家设备测量上传接口说明
 版本：V3  
 适用对象：墨家箱体测量设备服务
 ## 1. 接口用途
 墨家设备扫描当前箱上的两张标签并上传测量结果：
 - 柏悦唛头二维码，扫描结果作为 `boxCode`；
 - 如果当前箱贴有客户从 Amazon FBA 下载的 FBA 标签，则扫描其中的 Shipment ID，作为 `shipment_id`；非 FBA 货物可以不传。
 每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何处理数据。
 墨家设备属于平台仓库设备，不固定绑定某个客户。柏悦根据全平台唯一的 `boxCode`
 解析真实客户和入库单，并校验该入库单属于 `machineNo` 绑定的仓库；设备不能跨仓上传。
 唛头二维码内容由柏悦生成，设备应原样读取并作为 `boxCode` 上传。例如：
 ```text
 PCHK2608040174#19-1
 ```
 设备不需要解析或修改 `boxCode`。
 `shipment_id` 不是柏悦生成的内容，也不能从 `boxCode` 推导。当前箱存在 Amazon FBA 标签时，设备应实际扫描并原样上传；不存在时可以省略或传空字符串。
 ## 2. 接口地址
 ```text
 POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
 ```
 `<GATEWAY_HOST>` 由柏悦另行提供。
 ## 3. 请求格式
 请求头：
 | Header | 必填 | 说明 |
 |---|---|---|
 | `Content-Type` | 是 | `application/json` |
 | `X-App-Key` | 是 | 柏悦分配的固定应用标识 |
 | `X-Timestamp` | 否 | 首轮联调关闭签名，不传 |
 | `X-Nonce` | 否 | 首轮联调关闭签名，不传 |
 | `X-Signature` | 否 | 首轮联调关闭签名，不传 |
 | `Idempotency-Key` | 否 | 当前同箱号重复上传直接覆盖，不要求设备生成 |
 请求 JSON：
 ```json
 {
  "boxCode": "PCHK2608040174#19-1",
  "shipment_id": "FBA19L5KMY2CU000002",
  "length": 100.1,
  "width": 100.2,
  "height": 100.3,
  "machineNo": "MJ20210327",
  "picture": "data:image/jpeg;base64,/9j..."
 }
 ```
 字段说明：
 | 字段 | 必填 | 说明 |
 |---|---|---|
 | `boxCode` | 是 | 扫描得到的唛头二维码文本，必须原样传输 |
 | `shipment_id` | 否 | 当前箱存在 Amazon FBA 标签时，上传实际扫描得到的 Shipment ID；非 FBA 货物可省略或传空；兼容字段名 `shipmentId` |
 | `length` | 是 | 当前箱长度，单位 cm |
 | `width` | 是 | 当前箱宽度，单位 cm |
 | `height` | 是 | 当前箱高度，单位 cm |
 | `weight` | 不再接收 | 墨家接口只上传尺寸；货物毛重、托盘皮重和净重统一由称重图片确认链路维护 |
 | `machineNo` | 是 | 墨家设备编号，每台机器固定且唯一，并由柏悦绑定到一个实际仓库 |
 | `picture` | 是 | JPEG 图片的 Data URL Base64 文本 |
 ## 4. 图片格式
 图片格式：
 ```text
 data:image/jpeg;base64,<Base64内容>
 ```
 服务端会校验图片格式和大小。当前约定解码后的图片不超过 5 MB。接口不接受图片 URL 或图片 ID。
 ## 5. 返回结果
 成功时返回 HTTP 200 和 JSON 成功结果。墨家只需判断 HTTP 状态和响应中的成功标识，不需要处理柏悦内部业务字段。联调期间，即使模拟箱码暂未匹配柏悦入库单，只要测量字段和图片已被柏悦完整接收并保存，也会返回成功；柏悦自行记录并排查匹配结果。
 失败时，柏悦会返回 HTTP 错误或 JSON 错误信息。设备应记录请求时间、`boxCode`、`shipment_id`、`machineNo` 和响应信息，便于重试和排查。
 ## 6. 重试约定
 网络超时或未收到响应时，设备可以重试同一次上传。当前按 `boxCode` 保存最新结果，同一个箱号重试不会新增多条当前记录。
 同一个 `boxCode` 后续再次上传时，以最新一次设备上传的测量结果为准；本次传了 `shipment_id` 则保存实扫值，未传则保存为空。设备无需额外传版本号。
 ## 7. 待墨家确认
 1. 当前箱存在 Amazon FBA 标签时，是否可以同时扫描柏悦唛头和 Amazon FBA 标签，并分别上传 `boxCode`、`shipment_id`。
 2. `boxCode` 是否可以原样上传完整二维码文本，例如 `PCHK2608040174#19-1`。
 3. 有 Amazon FBA 标签时，`shipment_id` 是否可以原样上传，例如 `FBA19L5KMY2CU000002`；非 FBA 货物允许不传。
 4. `picture` 是否可以按 `data:image/jpeg;base64,...` 格式上传。
 5. 称重图片 OCR 与人工确认不走墨家尺寸上传接口。
 6. `machineNo` 是否每台机器固定且唯一。
 7. 首轮联调完成后，再共同确认动态 HMAC-SHA256 签名的启用时间。
 柏悦侧会另行提供正式接口地址、固定 AppKey 和测试箱码。首轮联调只校验固定 AppKey，不需要 Secret；本文不包含任何真实密钥或柏悦内部业务处理规则。
@@ -0,0 +1,32 @@
 # 头程到尾程当前维护入口
 这里集中列出后续流程变更需要查找和修改的文档。整体流程基线已确认，除报关协同代码外进入收尾；日常只从本目录进入，历史开发材料统一放在[文档归档](../归档/README.md)。
 ## 当前流程文档
 | 用途 | 文档 | 修改什么 |
 |---|---|---|
 | 总览与节点 | [头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md) | 三大业务块、客户进度、后台节点、真实明细和 F01-F40 关系 |
 | 分段流程 | [头程到尾程分阶段流程](../头程到尾程分阶段流程/README.md) | 六个阶段的字段、页面操作、权限、状态和异常 |
 | 货柜入口 | [国内货柜履约 README](../国内货柜履约/README.md) | 分柜、装柜、报关协同、送港和进港的货柜范围 |
 | 报关与船期专题 | [报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md) | 客户资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格 |
 | 报关开发交接 | [报关代码开发交接清单](报关代码开发交接清单.md) | 当前未完成的报关代码范围、完成条件和开发入口 |
 | 头程与报关交互矩阵 | [头程节点与报关清关交互矩阵](头程节点与报关清关交互矩阵.md) | F01-F24 各节点的客户、平台、PDA、报关行和船期交互 |
 | 第一阶段冻结矩阵 | [头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md) | F01-F24 节点、报关完成进入待发区、当前实现缺口和开发前确认项 |
 | 正式申报与海关结果 | [正式申报与海关结果接入设计](正式申报与海关结果接入设计.md) | F22.7 正式申报批次、报关单号、F22.8 查验/补资料/放行/扣货/其他结果及三端边界 |
 | 甩柜改配接入设计 | [甩柜改配接入设计](甩柜改配接入设计.md) | F23.3 原柜人工修改船信息并保留修改历史 |
 ## 变更查找
 - **改客户看到的主节点或三大块关系**：先改总览，再检查对应阶段文档。
 - **改头程下单**：查阶段一、阶段二；费用确认仍是并行事项，不阻断排柜和装柜。
 - **改海运（货柜）**：查阶段三、阶段四和报关专题；报关完成后进入待发区，甩柜只影响船期，实际开船后才进入海运节点。
 - **安排报关开发**：只看[报关代码开发交接清单](报关代码开发交接清单.md)，流程规则回看报关专题，不再从归档的开发规划开始。
 - **改尾程入库和派送**：查阶段五、阶段六。
 - **改页面范围或已确认需求**：查[页面与原型清单](../国内货柜履约/国内货柜履约页面与原型清单.md)和[需求确认表](../国内货柜履约/国内货柜履约需求确认表.md)。
 ## 归档位置
 - [头程到尾程历史文档](../归档/头程到尾程/README.md)：全流程手册、旧现状全景、AI 上下文、易用性方案。
 - [国内货柜履约历史记录](../国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收、审计和旧确认材料。
 - 跨区域认证、权限、统一订单状态、船节点、部署和数据库等正式契约继续留在原业务目录，不归入流程历史归档。
@@ -0,0 +1,173 @@
 # 头程至实际开船节点冻结矩阵与缺口清单
 本文按当前确认结果冻结第一阶段范围：从头程下单开始，完成国内履约、报关协同、送港运输，并记录承运船舶实际开航。尾程入库、派送和签收不在本阶段实现。流程基线同时采用《报关代码开发交接清单》和《头程到尾程流程节点梳理》；原型只用于页面字段和承载方式参考。
 ## 一、阶段边界
 ```text
 头程下单
  F01-F13：下单、审核、到仓、测量、计费、费用确认、组托、待分柜
 国内货柜履约
  F14-F21：分柜、订舱、拖车、拣货、装柜、LOADED
 报关完成后进入待发区
  F22：报关协同
  F23：待发区、送港、进港、甩柜、改配
 海运起点
  F24：承运船舶实际开航
 ```
 本阶段的终点是实际开航事实，不是“报关完成”、国内离仓、目的港清关或海外入仓。`LOADED` 只表示物理装柜完成；报关完成是进入待发区的前置条件，待发区和船期节点分别保存，不能把其中一条线的结果写成另一条线的结果。
 ## 二、F01-F24 节点冻结矩阵
 | 节点 | 客户可见进度 | 后台业务对象 | 必须形成的真实事实 | 当前状态 | 本阶段缺口 |
 |---|---|---|---|---|---|
 | F01-F07 | 待下单、审核中、已审核 | 企业、订单、审核任务 | 提交、补件、审核、入仓单生成 | 已有主链 | 按现有订单契约回归，不在本轮重做 |
 | F08-F10 | 待到仓、测量中、待确认 | 入仓单、测量记录 | 收货、扫码、称重、测量、审核 | 已有主链 | 只核对是否能稳定产出排柜事实 |
 | F11-F13 | 费用待确认、待组托、待分柜 | 费用版本、确认记录、托盘 | 计费推送、客户确认、组托/封托 | 已确认并行规则 | 保证费用默认确认不能冒充报关确认 |
 | F14-F20 | 待分柜、订舱中、装柜中 | 柜次、装柜计划、拖车、PDA 任务 | 分柜、订舱、排车、拣货、照片、铅封、数量核对 | 主链已有 | 核对真实柜号、订舱和装柜快照能否冻结 |
 | F21 | 国内已装柜 | 装柜计划、物理货柜、装柜证据 | 实际柜号、实装箱数、装柜证据、`LOADED` | 已有 | 报关案例按最终实装范围建立；部分装柜只显示已装箱数并标记线下处理，不在系统内自动分摊 |
 | F22.1 | 报关确认中 | 柜级报关聚合内的客户资料范围 | 每客户范围、入仓码范围、混合柜隔离、实装范围回显 | 已实现并通过真实 HTTP 验收 | 独立“案例”对象仍可在正式批次设计时补充；部分装柜仍线下处理 |
 | F22.2 | 待提交资料、待补资料 | 客户资料包 | 上传、替换、关联范围、版本、冻结 | 已实现并通过真实 HTTP 验收 | 资料类型化清单和补件原因待补 |
 | F22.3 | 已发送报关行 | 独立首次发送批次 `brokerSubmission` | 业务批次号、发送人、发送时间、冻结版本、资料快照、幂等历史 | 已实现并通过定向测试与测试环境部署 | 报关行接收确认和回执轮次对象待补 |
 | F22.4 | 待客户确认 | 回执/完成文件版本 | 文件版本、关联客户范围、客户可下载 | 已实现；回执历史和确认动作历史均只读投影 | 独立回执返回时间/下载凭证仍待补 |
 | F22.5 | 客户确认中、已打回 | 客户确认记录与动作历史 | 确认/打回、回执版本、操作人、时间、原因 | 已实现并通过定向测试与测试环境部署 | 通知聚合和报关行回执轮次待补 |
 | F22.6 | 等待整柜确认 | 完税文件齐全门禁 | 所有退税客户确认、发送执行、真实完税文件齐全 | 已实现并通过专项真实 HTTP 验收 | 复杂结果凭证和补资料专项门禁待补 |
 | F22.7 | 已提交正式申报 | 正式申报批次 | 报关行确认、正式申报时间、操作人、批次、报关单号 | 已实现并通过真实 HTTP 7 步联调 | 后续补更复杂的结果凭证类型 |
 | F22.8 | 查验中、待补资料、已放行、扣货/其他 | 海关结果事实 | 报关单号、结果类型、时间、凭证、处理结果 | 已实现并通过真实 HTTP 7 步联调 | 后续补查验/扣货/补资料专项场景的更细验收 |
 | F23.1 | 待发区、送港中、已离仓 | 待发区与送港/出仓任务 | 报关完成时间、待发区门禁、离仓时间、车辆/任务、操作人、证据 | 已实现并通过真实 HTTP 验收 | 继续补待发区客户/平台投影展示 |
 | F23.2 | 已送港、已进港 | 运输和港口事实 | 送港时间、进港时间、来源和凭证 | 部分已有 | 与订舱、拖车和船次事实统一读写 |
 | F23.3 | 已甩柜、等待改船后承运 | 船期记录修改历史 | 甩柜原因、发生时间、修改前后船名/航次/船期、处理人 | 已实现并通过测试环境真实 HTTP；平台与客户端最新船期投影一致 | 继续补页面截图和更复杂异常分支；柜次、订舱关联和报关事实不变 |
 | F24 | 海运中 | 船次实际节点 | 承运船舶、航次、实际开航时间、来源/凭证 | 基础已有 | 只允许实际开航事实推进海运节点 |
 ## 三、当前实现与目标的主要断点
 ### 1. 报关数据模型已支持客户范围，发送批次仍需独立建模
 当前 `fl_customs_container` 仍是柜级状态聚合，但客户资料通过客户和入仓码范围隔离，真实验收已覆盖同柜多客户和混合柜。正式申报批次、海关结果事实、首次发送报关行批次和客户确认动作历史已经独立落地；尚未独立建模的是报关行接收回执、回执轮次和更细的客户案例聚合。
 目标至少需要以下关系：
 ```text
 物理货柜
  ├─ 最终实装快照
  ├─ 客户报关案例 × N
  │    ├─ 客户资料包与版本
  │    ├─ 报关行回执轮次 × N
  │    └─ 客户确认/打回记录与动作历史 × N
  ├─ 整柜正式申报批次
  └─ 海关结果事实 × N
 ```
 ### 2. 当前“报关完成”仍需与正式申报、海关结果区分
 现有完成动作是平台上传每份完成文件，或对全买单柜直接确认；客户确认和完成文件链路已有真实验收。正式申报批次、报关单号和海关结果已经分别记录，仍不能把其中任何一个状态直接当成海关放行或所有运输事实。
 ### 3. 报关完成与待发区的门禁关系
 当前 `CustomsDispatchGateContributor` 要求 `fl_customs_container.status=COMPLETED` 才通过国内出仓门禁，`CustomsAutoDispatchCoordinator` 也在报关完成后自动尝试确认出仓。按最新口径，这不是冲突：报关完成后货柜进入待发区，待发区是送港运输真正开始前的状态门槛；甩柜只在船期运输层处理，不触碰报关事实。
 需要重新定义：
 - 待发区门禁先检查报关 `COMPLETED`，再叠加装柜、PDA、订舱、证据等运输条件；通过后只推进到 `WAITING_FOR_LOADING`。
 - 报关线单独保存客户确认、整柜申报和海关结果；这些事实不会被船期修改覆盖。
 - 报关完成事件只能推进待发区，不得自动伪造送港、进港或开船事实。
 - 实际开航只能由船次实际节点推进。
 ### 4. 客户端基础报关协同闭环已完成
 当前客户端 `CustomsDocumentsView.vue` 提供独立报关资料列表和待办入口，`CustomsDocumentsDialog.vue` 已支持上传、替换、调整关联入仓码、查看和下载报关行回执/真实报关完税文件、确认整份回执和填写原因打回，并展示回执历次上传版本及确认/打回动作历史；仍缺少：
 - 客户案例的进度和通知。
 ### 5. 平台端基础整柜协同闭环已完成
 当前 `ContainerCustomsPanel.vue` 已展示退税资料、首次发送报关行批次、回执/完成文件、客户范围、确认状态、回执历次上传版本和确认/打回动作历史，并支持正式申报批次和海关结果基础操作；仍缺少：
 - 按客户查看案例和实际装柜覆盖；
 - 报关行接收回执和回执轮次管理；
 - 更细的查验、扣货、补资料和其他结果凭证历史。
 ## 四、接口、权限、审计和测试缺口
 ### 接口与数据库
 - OpenAPI 不能继续只暴露旧的四态 `ContainerView`。
 - 需要继续补充报关行接收回执、回执轮次、下载凭证及更复杂结果凭证的查询/命令契约；资料包、首次发送批次、回执版本和确认动作只读历史、整柜申报和海关结果基础契约已落地。
 - 文件仍由 File 服务保存，但每个文件必须绑定业务类型、客户案例/申报批次、版本和覆盖范围。
 - 每个写命令都要带版本和幂等键；重放同参数返回原结果，不同参数返回冲突。
 - 换柜时需要保留新旧柜关联；部分装柜只记录已装箱数和线下处理标记，不在系统内自动做数量分摊或覆盖旧资料。
 ### 权限
 至少区分：
 - 客户上传、替换、补件、确认、打回；
 - 平台客服接收、核对、退回补件；
 - 平台报关操作员发送报关行、上传回执、提交正式申报；
 - 平台人员录入查验、放行、扣货及其他海关结果；
 - 客户和平台各自的只读下载权限。
 ### 审计
 需要保留客户范围、资料版本、回执轮次、确认人、打回原因、提交批次、报关单号、结果凭证和操作时间。客户 A 的动作不能出现在客户 B 的案例中；柜级汇总可以看到客户名和业务编号，但客户端只能看到自身范围。
 ### 测试
 最小验收矩阵至少覆盖：
 1. 单客户和多客户同柜。
 2. 一客户打回时其他客户继续保持已确认。
 3. 同一请求重放、同幂等键换参数、版本冲突。
 4. 未全部客户确认时正式提交被拒绝。
 5. 正式申报、查验、不查验放行、扣货和其他结果分别显示。
 6. 报关完成后货柜进入待发区，等待船舶承运。
 7. 甩柜改配在原柜上人工修改船信息并留痕，柜子和报关事实不变。
 8. 只有实际开航事实推进 F24。
 9. 客户越权读取同柜其他客户资料被拒绝。
 10. 部分装柜能显示实际箱数并留下线下处理标记；换柜不能直接覆盖原案例和历史回执。
 ## 五、开发前仍需业务确认
 以下问题中，前四项已经由《报关代码开发交接清单》和《头程到尾程流程节点梳理》冻结，本轮又补充冻结了文件形态、部分装柜展示、回执确认、首期申报和实际开航/改配处理方式；表格后的内容仍需业务补充，不能由代码现状推断。
 ### 已冻结的业务规则
 | 规则 | 冻结口径 | 依据 |
 |---|---|---|
 | 资料提交时点 | `LOADED` 后按最终实装快照建立客户案例并进入本轮报关 | 交接清单“一、必须实现的报关流程”；总流程 F21/F22 |
 | 同柜客户边界 | 一个客户案例只属于一个客户；同一客户多个入仓码可以共享资料，但跨客户正式合报默认禁止 | 报关专题“申报组与柜级总览”“买单、退税和混合柜完成条件” |
 | 回执与客户确认 | 首期以报关行回执文件为主，客户对整份回执确认；回执上传不等于客户确认 | 本轮业务确认 |
 | 资料与部分装柜 | 报关资料、报关行回执都按文件保存；部分装柜只展示箱数，线下人员处理后续，不做系统内数量分摊 | 本轮业务确认 |
 | 首期正式申报 | 由平台授权人员人工提交并回填报关行确认和海关结果 | 本轮业务确认；报关专题状态约定 |
 | 报关与待发区关系 | 报关完成后货柜才能进入待发区；待发区是等待船舶承运的运输状态，报关和船期事实分开保存 | 本轮业务确认 |
 | 海运起点与改配 | 首期人工录入实际开航；甩柜/改配只变更船期/航次，不重新处理已完成报关资料；只有实际开航事实推进 F24 | 本轮业务确认；交接清单第二条；总流程 F23/F24 |
 ### 本轮补充确认的甩柜/改配口径
 | 项目 | 已确认口径 |
 |---|---|
 | 发起与确认 | 平台人员直接编辑原柜船期，记录操作人、时间、原因和修改前后船信息。 |
 | 资料继承 | 报关完成后资料、平台回执和客户确认与船期独立；甩柜/改配不触发重新上传或重新确认。 |
 | 航次任务 | 平台人工修改原柜船信息，继续使用原任务；保留修改历史和已有节点。 |
 ### 仍需补充的字段和操作规则
 1. 首版资料清单具体项目、条件规则、版本生效方式和责任人是什么？
 2. （已确认）第一版由平台人员直接修改原柜船名、航次和船期，填写原因并保留修改历史。
 3. （已确认）平台人工修改原柜船名、航次和船期；柜子与原任务不变。
 4. （已确认）原航次退税资料、回执和客户确认与船期独立，甩柜/改配不触发重新确认。
 5. （已确认）甩柜/改配与报关资料无关，不重新生成报关批次，不要求客户重新确认。
 6. 修改船信息不生成实际开航事实；只有本柜实际随船开航后才记录 `DEPARTED_ORIGIN_PORT`。
 ### 代码接入前置缺口
 最新确认取消新增航次对象和重建任务的方案。复用现有船期编辑及修改历史，柜次、订舱关联和查询任务保持不变。测试环境已核验平台与客户端都会投影修改后的最新船期，报关资料、回执、完成文件和客户确认保持不变；证据见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`。
 ## 六、冻结结论
 - 第一阶段覆盖 F01-F24，终点为实际开航。
 - F22 报关完成后货柜进入 F23 待发区；甩柜/改配只改变运输航次，不改变报关事实。
 - 客户确认、报关行回执、整柜正式申报、海关放行、离仓、进港、甩柜和实际开航都是独立事实。
 - 先完成节点矩阵、对象关系、状态投影、门禁和验收缺口确认，再进入代码设计。
 - 尾程 F25-F40 暂不纳入本阶段实现，但必须保留 F24 到目的港清关的接口衔接点。
@@ -0,0 +1,78 @@
 # 头程节点与报关清关交互矩阵
 > 本文把头程下单 F01-F24 与报关清关的客户、平台、报关行交互放在同一张图里。当前产品先覆盖国内头程到实际开航；尾程不在本轮。报关资料只适用于包含退税货物的柜，买单货物不创建客户资料协同。
 ## 一、总链路
 ```text
 客户下单/入仓
  → 收货、测量、计费、费用确认
  → 分柜、订舱、拖车、PDA 装柜
  → LOADED（物理事实）
  → 客户上传报关资料
  → 平台冻结资料并首次发送报关行（生成独立批次）
  → 报关行回执
  → 客户确认整份回执/打回
  → 平台把客户确认后的回执发送报关行执行
  → 报关行完成
  → 平台上传真实报关完税文件
  → 报关完成
  → 待发区、送港、进港
  → 甩柜/改配只修改原柜船期
  → 实际开航
 ```
 `LOADED` 是 PDA 产生的装柜事实，也是当前客户报关详情的准入条件；PDA 不参与资料、回执、确认或完税文件接口。报关完成是待发区的门禁，实际开航只由船次实际事实推进。
 ## 二、F01-F21：报关前的头程节点
 | 节点 | 客户动作 | 平台动作 | PDA/运输动作 | 报关影响 |
 |---|---|---|---|---|
 | F01-F07 下单、审核、补件 | 提交订单、补充订单信息 | 审核订单、生成入仓单 | 无 | 仅确定客户、订单和退税/买单属性；不创建报关资料 |
 | F08-F10 到仓、收货、测量 | 查看入仓进度 | 收货、扫码、称重、测量并审核 | 仓内作业 | 形成后续实装范围的来源数据 |
 | F11-F13 计费、费用确认、组托、待分柜 | 查看/确认费用 | 发布费用版本、记录确认、组托封托 | 无 | 费用确认不能代替报关资料确认 |
 | F14-F20 分柜、订舱、拖车、拣货、装柜中 | 查看柜次和船期 | 建立柜次、订舱、拖车和装柜计划 | PDA 领取、拣货、复核、装柜 | 仍不能启动客户报关资料入口 |
 | F21 `LOADED` | 查看实际装箱数 | 固化实际柜号、实装箱数和装柜证据 | PDA 提交并产生 `LOADED` | 按最终实装范围建立退税客户报关资料范围 |
 部分装柜只回显实际箱数并留下线下处理标记，系统不自动分摊数量，也不覆盖原始资料范围。
 ## 三、F22：报关平台与客户交互
 | 子节点 | 平台页面/接口 | 客户页面/接口 | 关键状态与门禁 |
 |---|---|---|---|
 | F22.1 建立资料范围 | Admin 查看柜级退税客户、入仓码和实装范围 | Client 只能看到自身订单范围 | 退税客户按租户和入仓码隔离；买单客户不建资料 |
 | F22.2 客户上传资料 | `GET /api/platform/v1/customs/loading-plans/{planId}` 查看汇总 | `GET /api/merchant/v1/customs/orders/{orderId}`；`POST .../documents/upload`；可替换、调整入仓码范围 | 当前要求 `LOADED`；资料版本和幂等键受门禁控制 |
 | F22.3 首次发送报关行 | Admin `POST .../{planId}/send-to-broker` | 只读看到批次和发送时间 | 资料全部冻结后生成独立 `brokerSubmission` 批次；未首次发送不能上传回执；只适用于含退税货物的柜 |
 | F22.4 上传回执 | Admin `POST .../documents/{documentId}/receipt/upload` | `GET .../receipt/download` | 回执进入 `PENDING`；回执不是报关完成文件 |
 | F22.5 客户确认/打回 | Admin 查看每客户回执状态 | `POST .../receipt/confirm` 或 `.../receipt/reject` | 确认整份回执；打回必须填写原因；版本冲突拒绝 |
 | F22.6 回执冻结与执行 | Admin `POST .../{planId}/submit-to-broker` 再次发送客户确认后的回执 | Client 只能查看确认结果和动作历史 | 发送执行后回执不能替换；`brokerSubmittedAt` 仅表示发送执行时间 |
 | F22.7 正式申报与报关行完成 | Admin 创建/提交正式申报批次、回填报关单号，并上传真实报关完税文件：`POST .../final/upload` | `GET .../final/download`；只读批次投影 | 完税文件齐全后整柜状态才可 `COMPLETED`；正式申报批次和完税文件是两件事，不能把回执或客户确认当成正式申报 |
 | F22.8 清关结果 | 平台人工补录查验、补资料、放行、扣货等独立事实；可处理未决结果 | 客户只读查看自身可见结果和凭证 | 已落地 `customs_declaration_batch`、`customs_clearance_result`；结果不推进待发区、船期或 PDA |
 当前客户端状态映射：`WAITING_UPLOAD` → `DOCUMENT_UPLOADED` → `DECLARING` → `CUSTOMS_COMPLETED`。平台柜级状态映射：`WAITING_CUSTOMER_DOCUMENTS` → `READY_TO_START` → `DECLARING` → `COMPLETED`。`COMPLETED` 仍需继续与正式申报、海关放行和运输节点拆开。
 ## 四、F23-F24：报关完成后的运输交互
 | 节点 | 平台动作 | 客户可见内容 | 报关资料处理 |
 |---|---|---|---|
 | F23.1 待发区、送港、离仓 | 报关完成后通过待发区门禁，记录送港/离仓事实 | 查看待发、送港状态和当前船期 | 资料、回执、完税文件只读保留 |
 | F23.2 进港 | 记录进港时间、来源和凭证 | 查看进港节点 | 不改变报关状态 |
 | F23.3 甩柜/改配 | 平台人员编辑原柜船名、航次、预计时间并记录前后值、原因、操作人 | 查看修改后的当前船期和历史 | 柜号、订舱关联、资料、回执、客户确认和完税文件不变，不重新确认 |
 | F24 实际开航 | 人工录入承运船舶实际开航事实 | 查看海运已开航 | 只记录关联关系，不重做报关 |
 甩柜只改变运输信息，不生成新柜、不重建报关任务、不把预计船期修改误写成实际开航。
 ## 五、当前接口覆盖与待补项
 已落地并部署的基础闭环：客户资料上传/替换/范围调整、平台查看、冻结资料首次发送报关行并生成独立批次、回执上传及历次版本只读投影、客户整份回执确认/打回及动作历史、平台发送报关行执行、真实完税文件上传/下载、退税与买单分流、版本和幂等门禁；当前平台与客户页面均读取最新预计船期字段，实际开航字段单独保留。
 仍需补齐：
 1. 报关行接收确认、回执轮次和回执下载凭证的独立对象及更细历史投影。
 2. 待发区客户/平台投影的更细页面展示和截图证据；`LOADED → 报关 → 待发区` 已在既有混合柜报告中通过，平台与客户改船后的当前船期双端回读已验收。
 正式申报批次和海关结果已在本轮实现并通过真实 HTTP：平台创建/提交批次、录入查验、查询并处理结果，客户按自身订单查询结果；证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。
 报关专项真实 HTTP 证据、构建号和当前 PDA 边界见[报关代码开发交接清单](报关代码开发交接清单.md)、`baiyue-firstleg/reports/focused-customs-flow-without-pda-20260927.json`、`baiyue-firstleg/reports/customs-mixed-20260927i.json` 及 `baiyue-firstleg/reports/customs-prep-container-20260926.json`。专项证据验证客户确认回执、发送报关行、上传完税文件和客户回读 `COMPLETED`，没有调用 PDA；新建混合柜全链路报告已通过 532/532。
 F22.7/F22.8 的独立批次、报关单号和海关结果设计见[正式申报与海关结果接入设计](正式申报与海关结果接入设计.md)；该设计不改变现有两份文件闭环，也不把结果事实写入船期或 PDA 状态。
@@ -0,0 +1,102 @@
 # 报关代码开发交接清单
 > **当前状态：第一阶段报关协同已接入测试环境。** 客户资料、首次发送报关行批次、回执、客户确认历史和真实完税文件已形成独立链路；报关行确认回执和更复杂结果凭证仍是后续补充项。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。
 > **本轮补充确认：** 首期报关行回执以文件为主，客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；报关完成后货柜进入待发区；实际开航首期人工录入，甩柜/改配只变更船期，不重新处理已完成报关资料。
 > **验收证据：** 既有全链路报告保留旧版 526/526、混合柜 532/532 记录；本轮新增代码、数据库和三端已部署，已用现有完成柜做接口烟测并核对首次发送门禁。完整造数到报关回归仍需要测试环境提供 PDA 作业员账号，当前 `test-acceptance.env` 缺少该变量，脚本按契约在装柜前置处停止。
 ## 一、必须实现的报关流程
 从装柜完成（`LOADED`）开始，按柜内客户分别处理：
 1. 按最终实装清单建立客户报关案例和资料包。
 2. 收集客户上传、替换或补充的资料，冻结后由平台生成独立批次首次发送给报关行。
 3. 接收报关行回执并发给对应客户确认。
 4. 客户打回时，只重开对应客户当前轮次，重新上传、重新发送并生成新回执；保留每轮资料、回执、确认人、时间、动作历史和打回原因。
 5. 柜内所有客户确认后，平台发送客户确认后的回执给报关行执行。
 6. 报关行执行完成后，平台上传真实报关完税文件；全部退税资料对应的完税文件齐全后，整柜报关完成。
 7. 分别记录海关查验、不查验放行、扣货或其他正式结果。
 报关行回执、客户确认、整柜正式申报和海关放行是不同节点。客户确认不能自动完成，费用的系统默认确认也不能代替报关资料确认。
 ## 二、报关完成与待发区关系
 - `LOADED` 只表示物理装柜完成；报关资料、回执、客户确认和正式申报仍需独立完成。
 - 报关完成后，货柜才能进入待发区；待发区表示等待船舶承运，不表示已经开船。
 - 送港、进港、甩柜和改配是运输事实；甩柜只在原柜船期记录上人工修改船信息，不回退或重新处理已完成报关资料。
 - 只有承运船舶实际开航后，才推进 `DEPARTED_ORIGIN_PORT` 海运节点。
 ## 三、当前代码交接重点
 ### 已落地的第一批能力
 - 平台端和客户端都能展示当前视角的实际装箱数；部分装柜只展示箱数，后续由线下人员处理，系统不做数量分摊。
 - 报关资料和报关行回执继续按文件上传、覆盖、版本和下载处理；页面文案已区分“回执”和“完成”，避免把上传回执误认为客户确认或正式申报。
 - 首次发送报关行单独记录 `brokerSubmission`（业务批次号、冻结资料版本、快照、操作人和时间）；未完成首次发送时不能上传回执，也不能发送客户确认结果给报关行执行。
 - 报关资料链路仅适用于退税货物；买单货物不创建客户报关资料、回执和客户确认流程。
 - 回执上传后进入待确认状态；客户端已提供整份回执确认和打回入口，平台与客户端都展示每个回执版本的确认/打回历史，打回原因回传后再由平台重新上传回执。
 - 后端 OpenAPI、平台/客户端模型和基础测试已同步实际箱数字段；管理员端、客户端类型检查及相关组件测试已通过。
 旧版资料与回执基础链路已通过测试环境真实 HTTP 验收；两份文件新流程已通过本地单测、契约测试和测试环境部署。报关闭环不依赖 PDA；真实 HTTP 验收应使用已经处于待发区的柜作为前置，不能因为装柜/PDA 前置失败而把报关结论判为失败。
 ### 报关与 PDA、船期的边界
 - PDA 只负责装柜现场作业，产出 `LOADED` 事实；本报关模块不创建、领取、认领或提交 PDA 任务。
 - 报关模块只消费已完成装柜且可进入待发区的柜。装柜链路可以作为系统级前置验收，但不属于报关两份文件闭环的验收内容。
 - 船期、价格、甩柜和改配属于运输模块。甩柜时只人工修改原柜的船名、航次和时间，柜号、报关资料、回执、客户确认和完税文件不变，也不重新创建报关任务。
 ### 本轮对 PDA 关系的落地说明（2026-09-26）
 - PDA 没有参与本轮代码修改，也没有被报关接口调用；客户资料、报关行回执、客户确认和真实报关完税文件仍由平台与客户/报关行接口独立处理。
 - 当前客户报关详情接口只对已完成装柜的订单开放，未达到 `LOADED` 时返回“订单尚未完成装柜”。因此 PDA 只是报关入口的上游准入事实，不是报关协同动作的一部分。
 - 若后续业务确认“装柜前就允许客户上传报关资料”，应单独调整 `LOADED` 准入门禁；不能通过在报关模块里偷偷创建或操作 PDA 任务解决。
 - 本轮测试已用真实 HTTP 建立退税柜、订舱和船期关联，并确认装柜计划仍为 `EDITING`、`readyForPda=false` 时不启动报关；证据见 `baiyue-firstleg/reports/customs-prep-container-20260926.json`。
 ### 本轮报关专项真实 HTTP 证据（2026-09-27）
 - 使用测试库中已完成装柜的退税计划 `loadingPlanId=2103494180160507905`，没有调用任何 PDA 接口。
 - 客户确认回执：HTTP 200、业务码 `200`，报关状态仍为 `DECLARING`。
 - 平台发送客户确认结果给报关行：HTTP 200、业务码 `200`，产生 `brokerSubmittedAt`，状态仍为 `DECLARING`。
 - 平台上传真实报关完税文件：HTTP 200、业务码 `200`；随后平台和客户查询均返回 `COMPLETED`，并可见完成文件。
 - 完整证据：`baiyue-firstleg/reports/focused-customs-flow-without-pda-20260927.json`。该证据证明两份文件报关协同闭环本身不依赖 PDA。
 - 早期全量验收报告 `customs-full-20260926h.json` 的失败项集中在 PDA 任务被分配给其他作业员，导致装柜链未进入 `LOADED`；修正验收作业员绑定并补齐 File 服务回执类型后，新的全链路报告 `customs-mixed-20260927i.json` 已通过 532/532，报关模块 223+47+23 项全部通过。
 ### 本轮部署证据
 - 本轮 Firstleg 后端 `backend-java #652`、下游 `baiyue-firstleg-firstleg #455`、平台管理端 `admin-web-test #473`、客户端 `client-web-test #355` 均已成功部署到测试环境，健康检查为 `UP`。
 - 客户端报关资料定向测试 61/61 通过；报关服务单测、OpenAPI 契约测试和平台报关组件测试结果记录在本轮交接记录及对应构建产物中。
 - 正式申报/海关结果接入提交：Firstleg `ed692ee3`、路由合同修正 `95da66c7`、执行顺序修正 `4bec639a`，`backend-java #639/#640/#641` 成功；Admin `29cb0bd`、顺序修正 `855d8c0`，`admin-web-test #461/#462` 成功；Client `8c8fdbc`、`client-web-test #350` 成功。正式申报和结果真实 HTTP 7 步全部通过，证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。
 - 甩柜改配投影提交 `ac3acfce`、`f1218cef`，平台容器读模型修复提交 `2c4f1ea3`；当前分支的船期展示修复已由 `backend-java #649`、`baiyue-firstleg-firstleg #452` 和 `client-web-test #351` 成功部署。真实验证确认改船只更新原柜船期，平台与客户端同步最新船期，柜号和报关资料/回执/完成文件保持不变，证据见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`。
 - 回执历史投影提交 Firstleg `f6e70ea5`、Admin `ffe91a1`、Client `3e28478` 已成功部署：`backend-java #650`、`baiyue-firstleg-firstleg #453`、`admin-web-test #471`、`client-web-test #353`。健康检查为 `UP`，平台和客户真实接口均返回 `receiptHistory`；证据见 `baiyue-firstleg/reports/customs-receipt-history-20260928.json`。
 - 本轮首次发送批次与确认动作历史提交为 Firstleg `e63cb2b2`、Admin `730defa`、Client `8fd4063`；数据库已核对 `fl_customs_broker_submission` 与 `fl_customs_completion_action_history`。现有完成柜烟测返回 `A0409 当前柜不在报关中`，确认新首次发送接口的状态门禁；证据见 `baiyue-firstleg/reports/customs-send-batch-confirmation-history-20260928.json`。
 当前仍需继续补齐的不是客户资料协同、正式申报和海关结果基础链路，而是：
 - 报关行回执的外部确认/接收回执、下载凭证和回执轮次的更细对象；首次发送批次与客户确认动作历史已经落地；
 - 更复杂的结果凭证上传和补资料专项门禁；
 - 将正式申报/海关结果继续扩展到待发区、送港、进港和实际开航的只读投影，保持运输线独立；F23.3 的船期投影已完成真实 HTTP 核验。
 开发时不要只增加页面节点文案，也不要把旧的 `COMPLETED` 直接当成客户确认、正式申报或海关放行。
 ## 四、开发入口
 先核对当前代码和 OpenAPI，再决定复用或调整现有接口：
 - 客户端报关资料：`apps/client-web/src/modules/first-leg/`，重点查看 `routes.ts`、`CustomsDocumentsDialog.vue` 和 `api/customs.ts`。
 - 平台整柜报关：`apps/admin-web/src/modules/container-loading/`，重点查看 `ContainerCustomsPanel.vue` 和 `api/platformContainerCustoms.ts`。
 - 后端报关：`baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/customs/container/`。
 - 接口与数据：`baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml`、报关相关数据库脚本和 IAM 权限初始化。
 具体类名、接口路径、状态编码和数据库字段以当前代码核对结果为准；本清单只定义业务完成条件，不预先替换技术实现。
 ## 五、完成条件
 - 客户 A 与客户 B 的资料、回执和确认严格隔离。
 - 每个客户都能完成“资料上传 → 报关行回执 → 客户确认/打回”，资料和完成文件保留版本，客户范围严格隔离。
 - 首次发送报关行必须生成独立业务批次；客户每次确认或打回都保留对应回执版本、操作人、时间和原因。
 - 未全部客户确认时不能完成整柜报关；正式申报批次、海关回填结果和报关单号已独立建模，不能把客户确认或完税文件上传直接当作海关放行事实。
 - 海关查验、不查验放行、扣货和其他结果已落地为批次下独立事实；后续只需补更复杂的凭证上传和补资料专项验收。
 - 报关完成后才能进入待发区；进入待发区后才推进送港/进港。甩柜/改配只修改原柜船名、航次和船期并保留历史，不能伪造或覆盖报关资料、回执和客户确认。
 - 重复请求、版本冲突、换柜、部分装柜箱数展示和权限越界都有明确结果和审计记录；部分装柜的后续处理在线下完成。
 - 完成代码联调后，再回写 F22 和阶段三的实现状态；当前真实 HTTP 已通过，后续仍按 `COMPLETED`、海关放行和运输节点分别验收。
@@ -0,0 +1,128 @@
 # 正式申报与海关结果接入设计
 本文只补 F22.7、F22.8 的业务对象和交互边界，不改变已经验收的退税报关基础闭环：客户上传退税资料 → 平台发送报关行 → 报关行回执 → 客户确认或打回 → 平台发送确认结果给报关行 → 平台上传真实报关完税文件。
 ## 一、先冻结现有边界
 ```text
 LOADED
  ↓
 客户退税资料齐全
  ↓ 平台开始报关，冻结资料范围和版本
 DECLARING
  ↓ 报关行回执
 客户确认整份回执 / 打回
  ↓ 平台发送客户确认结果给报关行
 等待真实报关完税文件
  ↓ 每个退税客户均有完成文件
 COMPLETED（平台已收到本轮完税文件）
  ↓
 WAITING_FOR_LOADING（进入待发区）
 ```
 `COMPLETED` 只表示平台收到本轮真实完税文件，不能解释为海关放行、正式申报成功或船舶已开航。正式申报批次可以在报关行执行后、完税文件回传前建立；PDA 只在上游产出 `LOADED`；待发区、送港、甩柜、改配和船舶实际开航属于运输线，不能由正式申报对象反向改写。
 ## 二、F22.7 正式申报批次
 正式申报批次是平台授权人员人工提交后形成的独立事实，粒度为整柜一次申报批次。它引用当前柜级报关聚合和已冻结的客户资料/回执快照，不复制文件内容。
 建议对象：`customs_declaration_batch`
 | 字段 | 说明 |
 |---|---|
 | `id` | 平台长 ID，前端按字符串传输 |
 | `customsContainerId` / `loadingPlanId` | 绑定整柜报关聚合和装柜计划，创建后不可换柜 |
 | `batchNo` | 平台生成的批次号，人工提交前为空或草稿号 |
 | `status` | `READY`、`SUBMITTED`、`ACKNOWLEDGED`、`RESULT_PENDING`、`CLOSED`、`CANCELLED` |
 | `sourceVersion` | 提交时整柜报关聚合版本，防止提交后资料范围漂移 |
 | `receiptSnapshot` | 提交时客户资料、回执、确认结果的客户范围和文件版本快照 |
 | `customsEntryNo` | 报关单号，平台人工回填；同一有效批次唯一 |
 | `submittedBy/submittedAt` | 平台提交人和时间 |
 | `acknowledgedBy/acknowledgedAt` | 报关行或平台确认受理人和时间 |
 | `remark` | 提交说明，长度受服务端限制 |
 创建或提交门禁：
 1. 柜级报关已进入 `DECLARING`，且整柜退税资料已覆盖实际装柜退税票；批次也允许在完税文件上传后的 `COMPLETED` 阶段补建。
 2. 所有退税客户的当前回执均为 `CONFIRMED`。
 3. 已执行发送动作，`brokerSubmittedAt` 已存在。
 4. 提交使用版本号和幂等键；相同请求重放返回同一批次，不同载荷返回冲突。
 5. 提交后禁止修改客户资料范围、回执和确认结果；补资料必须通过新批次或明确的退回重提动作产生新版本，不能覆盖历史批次。
 建议平台接口：
 - `GET /api/platform/v1/customs/loading-plans/{planId}/declaration-batches`
 - `POST /api/platform/v1/customs/loading-plans/{planId}/declaration-batches`
 - `POST /api/platform/v1/customs/loading-plans/declaration-batches/{batchId}/submit`
 - 提交时在请求体回填 `customsEntryNo`，不另设独立改单接口。
 客户端只读当前批次的可见投影，不提供提交和修改入口；客户只能看到自己资料覆盖的结果。
 ## 三、F22.8 海关结果事实
 海关结果不是柜级状态字段，而是批次下的不可变事实记录。一次正式申报可以先产生“待结果”，之后根据实际回执追加查验、补资料、放行、扣货或其他结果；修正不能覆盖历史记录。
 建议对象：`customs_clearance_result`
 | 字段 | 说明 |
 |---|---|
 | `id` | 结果事实长 ID |
 | `declarationBatchId` | 所属正式申报批次 |
 | `resultType` | `INSPECTION`、`SUPPLEMENT_REQUIRED`、`RELEASED`、`DETAINED`、`OTHER` |
 | `resultStatus` | `OPEN`、`RESOLVED`、`CANCELLED` |
 | `customsEntryNo` | 报关单号快照，必须与批次一致 |
 | `occurredAt` | 海关事实发生时间 |
 | `recordedAt/recordedBy` | 平台录入时间和操作人 |
 | `resolution` | 处理结果、补资料说明或扣货原因 |
 | `evidenceFileId` | 可选结果凭证，文件由 File 保存，归属由 Firstleg 校验 |
 | `previousResultId` | 更正或追加结果的前序事实，不能原地覆盖 |
 结果门禁：
 - `INSPECTION` 和 `SUPPLEMENT_REQUIRED` 未解决时，客户看到处理中/待补资料，平台不能显示放行。
 - `RELEASED` 只表示海关放行事实，不自动写入送港、进港或实际开航。
 - `DETAINED` 进入扣货/异常处理，保留原因和凭证，不自动删除报关文件。
 - `OTHER` 必须有说明，不能用空状态吞掉未知海关结果。
 - 只有平台授权人员可以新增或更正结果；客户只能读取自身可见的结果和凭证。
 建议平台接口：
 - `GET /api/platform/v1/customs/loading-plans/declaration-batches/{batchId}/results`
 - `POST /api/platform/v1/customs/loading-plans/declaration-batches/{batchId}/results`
 - `POST /api/platform/v1/customs/loading-plans/clearance-results/{resultId}/resolve`
 - `GET /api/merchant/v1/customs/orders/{orderId}/clearance-results`
 ## 四、三端交互
 | 参与方 | 可以做什么 | 不可以做什么 |
 |---|---|---|
 | 客户 | 上传/替换自身退税资料；查看并确认或打回整份回执；查看自身批次、报关单号、海关结果和凭证 | 不能查看同柜其他客户；不能提交正式申报；不能录入放行/扣货 |
 | 平台报关人员 | 核对资料和回执；发送报关行；创建/提交正式申报批次；回填报关单号；录入和解决海关结果 | 不能用客户确认代替正式申报；不能用完税文件代替放行结果 |
 | 报关行 | 线下处理申报并返回回执、报关单号和海关结果文件 | 不直接调用客户接口；所有回执和结果由平台留痕上传 |
 | PDA/运输 | PDA 产出 `LOADED`；运输处理待发区、送港、进港、甩柜、改配和实际开航 | 不创建报关批次，不修改报关结果，不因甩柜重置资料或确认 |
 ## 五、状态投影
 平台柜级状态继续保留当前四态，用新增投影补充信息：
 | 现有状态 | 新增投影 | 客户文案 |
 |---|---|---|
 | `WAITING_CUSTOMER_DOCUMENTS` | 无有效批次 | 待上传退税报关资料 |
 | `READY_TO_START` | 可开始报关 | 资料已齐，等待平台发送报关行 |
 | `DECLARING` | 回执确认中/已发送报关行/正式申报中 | 报关处理中 |
 | `COMPLETED` | 完税文件齐全，正式申报或结果可能仍未关闭 | 报关文件已完成，等待海关结果（如有） |
 运输投影单独读取待发区和船期对象；甩柜只更新原柜船名、航次和时间历史，不变更批次、资料、回执、结果或客户确认。
 ## 六、最小验收矩阵
 1. 未全部客户确认时创建/提交正式批次返回业务冲突，数据零漂移。
 2. 同一幂等键重放返回同一批次；换参数返回冲突。
 3. 提交后资料范围、回执和客户确认不可修改。
 4. 同一批次可追加查验、补资料、放行、扣货和其他结果，历史顺序稳定。
 5. 查验/补资料未解决时不显示放行；扣货保留原因和凭证。
 6. 客户 A 不能读取客户 B 的批次、结果和文件。
 7. 报关结果不推进送港、进港或实际开航；甩柜只改变原柜船期。
 8. 正式申报和结果事实可以在报关 `COMPLETED` 后继续存在，不能把 `COMPLETED` 直接当成 `RELEASED`。
 本设计已完成代码接入：Firstleg 建立正式申报批次和海关结果表、版本/幂等/审计门禁及平台/客户接口；Admin 页面提供创建、提交、录入和处理入口，Client 页面展示本订单可见结果。真实 HTTP 证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。当前仍保持 `COMPLETED`、海关放行、待发区和实际开航的状态边界，PDA 与船期不参与结果对象。
@@ -0,0 +1,109 @@
 # 测试环境真实联调记录（2026-09-25）
 本记录只登记已经在测试环境真实调用得到的结果，不把本地单测或设计文档当作真实验收证据。环境配置来自本机受控配置目录，不在文档中记录密码、Token 或 Jenkins 凭据。
 ## 一、本批部署
 | 部署单元 | 测试构建 | 结果 | 说明 |
 |---|---:|---|---|
 | `backend-java` | 618 | 成功 | `firstleg` 选择构建；第 617 次因测试仍引用已删除旧方法失败，修正后第 618 次成功 |
 | `admin-web-test` | 454 | 成功 | 平台回执上传不再携带 `finalConfirmation`，上传后等待客户确认 |
 | `client-web-test` | 331 | 成功 | 客户端新增整份回执确认、打回和原因展示 |
 路由合同检查通过；后端报关服务定向测试和 Controller 合同测试通过，Admin 类型检查及报关组件测试通过，Client 类型检查通过。
 ## 二、真实接口证据
 测试客户属于退税客户，使用已完成装柜的测试订单和柜次进行验证。测试库已补齐 `fl_customs_completion_document` 的客户确认字段，现有记录仅用于本次测试。
 ### 1. 客户查看退税报关资料
 调用：
 ```text
 GET /api/merchant/v1/customs/orders/{orderId}
 ```
 结果：`200`。客户只能看到自身资料，返回实际箱数 `40`、退税资料 `1` 份；部分装柜的系统展示只读箱数，不做数量拆分。
 ### 2. 平台查看柜级报关状态
 调用：
 ```text
 GET /api/platform/v1/customs/loading-plans/{loadingPlanId}
 ```
 结果：`200`。平台视角返回同一柜次实际箱数 `40`、退税资料覆盖数和回执状态；客户视角没有返回同柜其他客户资料。
 ### 3. 平台上传报关行回执
 调用：
 ```text
 POST /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/upload?expectedVersion=1
 ```
 结果：`200`，回执状态为 `PENDING`，文件版本变为 `2`。上传回执没有自动把柜次标记为报关完成。
 ### 4. 客户打回整份回执
 调用：
 ```text
 POST /api/merchant/v1/customs/documents/{documentId}/receipt/reject
 ```
 结果：`200`，回执状态为 `REJECTED`，打回原因被保存，柜次仍为 `DECLARING`。
 ### 5. 客户确认整份回执
 调用：
 ```text
 POST /api/merchant/v1/customs/documents/{documentId}/receipt/confirm
 ```
 结果：`200`，回执状态为 `CONFIRMED`；该柜唯一退税客户确认后，柜次变为 `COMPLETED`。相同幂等键重放仍返回同一完成结果。
 ### 6. 头程到报关真实 HTTP 回归
 在补齐国内 PDA 测试作业员凭据后，使用 `scripts/admin-test-env-acceptance.mjs --modules phase3-container-customs` 重新执行依赖闭环，覆盖客户下单、审核、入库测量、分柜/订舱、预装、PDA 装柜、`LOADED`、退税资料上传、平台回执上传、客户回执确认、自动离仓及船期查询任务。
 结果：报告 `baiyue-firstleg/reports/e2e-phase3-container-customs-20260925d.json`，`526/526` 断言通过，`0` 失败；其中混合柜验证确认回执后才进入 `COMPLETED`，自动离仓 `SYSTEM` 历史为 `1` 条，`OUTBOUND_CONFIRM` 船期查询任务为 `1` 条。验收脚本同步提交为 `8940c4bc`。
 ### 7. 送港、船期与实际开航真实 HTTP 回归
 使用 `phase3-port-schedules,phase3-carrier-schedule-queries,phase3-outbound-dispatch` 执行送港和出仓链路，报告 `baiyue-firstleg/reports/e2e-phase3-transport-20260925.json`，`1024/1024` 通过；验证报关完成后国内离仓门禁、拖车自动完成、`OUTBOUND_CONFIRM` 任务唯一性及 `DEPARTED_WAREHOUSE` 事实。
 随后使用 `phase4-carrier-pickup-ready` 执行船节点人工回填，报告 `baiyue-firstleg/reports/e2e-phase4-carrier-pickup-ready-20260925.json`，`1093/1093` 通过；节点按顺序推进到 `AT_ORIGIN_PORT`、`LOADED_ON_VESSEL`、`DEPARTED_ORIGIN_PORT`，并覆盖幂等重放、旧版本冲突、旧节点回写禁止和至 `PICKUP_READY` 的连续事实。
 ## 三、当前已确认的业务边界
 - 报关资料、报关行回执和客户确认流程只适用于退税货物。
 - 买单货物不创建客户报关资料、回执和客户确认流程；买单装柜、导出和运输节点独立处理。
 - 报关资料和回执均为文件；回执状态单独保存，文件版本覆盖会重新进入待确认。
 - 部分装柜只展示实际箱数，后续由线下人员处理，系统不自动分摊数量。
 - `LOADED` 后先完成报关协同；报关完成后货柜进入待发区，等待船期承运。甩柜/改配只影响运输航次，不回退或重做报关资料、回执和客户确认。
 ## 四、F01-F24 验证状态
 | 范围 | 当前证据 | 状态 |
 |---|---|---|
 | F01-F13 下单、审核、到仓、测量、计费、费用确认、组托 | 本批依赖闭环已通过真实 HTTP；仍需拆分逐节点证据和异常分支 | 主链路已验收 |
 | F14-F21 分柜、订舱、拖车、拣货、装柜、`LOADED` | 本批依赖闭环已通过真实 HTTP，包含 PDA 领取、提交、审核和 `LOADED` 冻结 | 主链路已验收 |
 | F22 退税报关资料、回执、客户确认 | 已完成真实平台/客户端闭环 | 本批已验收 |
 | F23 送港、进港、甩柜、改配 | 送港/进港/出仓和船期查询主链路已通过真实 HTTP；已用测试环境真实柜次验证平台人工修改原柜船名/航次/预计时间，柜次、订舱关联和船期记录 ID 不变，修改历史新增 `UPDATE`；报关事实保持不变 | 主链路和原柜人工改船已验收；完整装柜依赖链仍需补 PDA 凭据后复跑 |
 | F24 实际开航 | 已通过人工船节点回填验证 `DEPARTED_ORIGIN_PORT`，顺序、版本和旧节点冲突均通过 | 本批已验收 |
 | F25 以后目的港清关、海外入仓、尾程 | 已有综合真实 HTTP 证据覆盖目的港节点、海外 PDA 收货、库存、排车、出库、派送和跨区回写；`admin-full-postdeploy-66c2651b.json` 相关模块失败数为 0 | 已有主链证据；仍需按具体柜次补最终业务签字和页面截图 |
 ## 五、下一批开发入口
 下一批聚焦 F23 的人工改船页面回读、客户侧船期投影和异常分支；当前已确认只变更原柜船期，柜次、订舱关联和报关事实均不被覆盖。尾程节点再按 F25 以后阶段推进。每批完成后继续追加真实 HTTP 证据。
 ## 六、2026-09-27 追加验证：F23.3 客户船期投影
 - 后端提交 `f1218cef` 已由 `backend-java #643` 完整测试并部署，Firstleg 独立任务 `baiyue-firstleg-firstleg #446` 成功；随后提交 `2c4f1ea3` 由 `backend-java #645` 完整测试并部署，Firstleg 独立任务 `baiyue-firstleg-firstleg #448` 成功；当前分支追加船期展示修复后，`backend-java #647` 与 `baiyue-firstleg-firstleg #450` 也已成功。
 - 修复统一订单运输摘要仍读取订舱初始船名/航次的问题：现在按客户、订舱和柜次读取最新 `fl_port_schedule` 记录，采用窗口函数选取最新观测，保留柜次与报关对象独立性。
 - 对退税柜 `TSTU0152125` 实际执行“创建原柜改配船期 → 平台容器详情与客户订单同时查询 → 版本更新恢复原船信息”。平台和客户端均读到新船名、航次及预计时间；柜号不变，恢复后两端再次一致。本轮不涉及 PDA，PDA 仍只作为 `LOADED` 上游事实。
 - 详细请求结果和断言见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`；此前客户侧单独投影证据仍保留在 `transport-projection-after-schedule-update-20260927.json`。
@@ -0,0 +1,35 @@
 # 甩柜与改配接入设计（F23.3）
 ## 最新确认
 柜子不会变。平台人员在原柜子的船期信息上人工修改船名、航次和预计时间即可；保留修改前后内容、修改人和时间。报关资料、回执、完成文件和客户确认保持不变。
 ## 操作流程
 1. 退税报关完成后进入待发区，等待船舶承运。
 2. 原船装满导致甩柜时，平台编辑该柜当前船期，填写实际安排的船名、航次和预计开船/到港时间。
 3. 保存后继续使用原柜次和原船期查询任务；保留已经发生的离仓、进港事实。
 4. 货柜实际随船开航后，再记录实际开航节点。修改预计船期本身不表示已经开船。
 不新建柜子、订舱关联或航次变更审批对象，不重建船期任务，也不重新上传或确认报关资料。此前建议的 voyage-changes 接口和批次评估状态已取消。
 ## 现有接入入口与待验收项
 现有平台船期页面 `PortSchedulesView.vue` 提供编辑船名、航次、预计开船和到港时间的入口；后端 `PortScheduleService.update` 保持客户、订舱和柜次归属不变，并保存版本和修改前后历史。优先复用该能力。
 当前船期展示已改为读取同一客户、订舱和柜次下最新船期记录，不再固定读取订舱初始快照。平台人工改船后，客户端会同步显示最新船名、航次和预计时间。
 ## 验收要求
 - 修改后柜次、柜号、装柜清单、订舱关联和船期查询任务不变。
 - 船名、航次和预计时间正确更新，平台与客户可见的当前船期一致。
 - 修改前后历史、操作人和时间可追溯，重复请求和版本冲突有明确结果。
 - 报关状态、资料、回执、完成文件、客户确认与修改前一致。
 - 已发生的物理节点不重置，预计时间调整不推进实际开航。
 ## 真实联调证据（2026-09-27）
 测试柜 `TSTU0152125`（`containerBookingId=2104006600809353218`）的退税报关计划
 `2104006600830324737` 已完成资料、回执确认和完税文件闭环。平台创建一次原柜船期改配记录后，客户端同一订单立即读到新船名、航次和预计时间；柜号、柜次不变，报关状态、退税客户数量、资料/回执/完成文件 ID 与版本均未变化。随后已用版本更新恢复原船信息，恢复后的客户端投影再次一致。完整证据见
 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`（平台与客户端同时回读）以及
 `baiyue-firstleg/reports/transport-projection-after-schedule-update-20260927.json`。
@@ -0,0 +1,32 @@
 # 头程到尾程分阶段流程
 本目录是端到端流程的分段查找入口。流程基线已确认，当前用于收尾变更；其中阶段三的报关协同代码尚未完成。总览和节点关系看[《头程到尾程流程节点梳理》](../头程到尾程流程节点梳理.md)，字段、页面操作、权限和异常细节在对应阶段文件维护。
 ## 三大业务块与六个分段
 | 业务块 | 分段 | 节点范围 | 详细文档 |
 |---|---|---|---|
 | **头程下单** | 阶段一：客户准入与头程下单 | F01-F07 | [打开阶段一](阶段一-客户准入与头程下单.md) |
 | **头程下单** | 阶段二：国内到仓、测量计费与组托 | F08-F13 | [打开阶段二](阶段二-国内到仓测量计费与组托.md) |
 | **海运（货柜）** | 阶段三：国内货柜履约与出仓 | F14-F23 | [打开阶段三](阶段三-国内货柜履约与出仓.md) |
 | **海运（货柜）** | 阶段四：海运、目的港与尾程计划 | F24-F27 | [打开阶段四](阶段四-海运目的港与尾程计划.md) |
 | **尾程入库和派送** | 阶段五：海外接柜、库存与库内服务 | F28-F33 | [打开阶段五](阶段五-海外接柜库存与库内服务.md) |
 | **尾程入库和派送** | 阶段六：海外排车、出库、派送与最终回写 | F34-F40 | [打开阶段六](阶段六-海外排车出库派送与回写.md) |
 ## 修改时只看这三层
 1. **总览层**：三大块、客户进度和节点关系变化，改总览节点梳理。
 2. **分段层**：某一段的页面操作、字段、权限、状态或异常，改对应阶段文件。
 3. **专题层**：报关资料、报关行回执、客户确认、送港/甩柜和船期价格，改[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)，并回看总览中的 F22/F23。
 ## 跨段交接
 - 阶段二完成后进入阶段三的分柜；费用确认是并行事项，不阻断排柜、拣货和装柜。
 - 阶段三的装柜完成（`LOADED`）后先完成退税报关；报关完成后货柜进入待发区，再推进送港运输。甩柜/改配只影响船期，不改变已完成报关事实。
 - 报关协同必须经过“客户资料 → 报关行回执 → 客户确认/打回重做”，柜内所有客户确认后才提交整柜资料并正式申报。
 - 送港完成、进港或甩柜都不等于海运中；承运船舶实际开航后才进入阶段四的海运节点。
 - 阶段四形成海外接柜输入后，阶段五负责实收、入库和库存，阶段六负责出库、派送、签收和异常回写。
 ## 旧文档的使用范围
 全流程操作手册、现状全景清单、AI 优化上下文、开发规划、进度表、开工门禁和验收任务继续保留，用于追溯历史决策和实现记录；它们不是当前节点维护入口。新增规则只写入总览、对应阶段或专题文件，避免同一流程在多份历史文档中重复修改。
@@ -0,0 +1,464 @@
 # 阶段一：客户准入与头程下单
 > 对应全景流程：F01～F07。  
 > 阶段起点：企业已注册并可以登录。  
 > 阶段终点：平台审核通过，Order 为 `APPROVED`，Firstleg 已创建正式国内入库单并沿用固定入仓码，统一主状态进入 `WAIT_MEASURE`。  
 > 本文只记录现状流程；易用性问题先登记，不在本文直接改状态、接口或页面。
 ## 1. 阶段目标和边界
 本阶段解决六件事：
 1. 确认“谁可以代表哪个客户下单”；
 2. 确认客户是否具备提交资格；
 3. 冻结订单的国内收货仓、目的仓、渠道、地址和货物申报；
 4. 生成客户可见的订单号和全局唯一入仓码；
 5. 由平台审核订单并建立正式国内入库单；
 6. 把权威订单和申报快照交给下一阶段的国内收货、测量和计费。
 本阶段不负责：货物是否已经到仓、实际尺寸重量、费用最终确认、分柜、装柜、出仓和海外履约。
 ## 2. 角色、终端与权限
 | 角色 | 终端 | 可做操作 | 不可做操作 |
 |---|---|---|---|
 | 企业成员 | Client | 按权限查看本企业订单 | 查看其他客户、平台内部备注和成本 |
 | 企业订单操作员 | Client | 新建、编辑草稿、批量导入、提交、按规则取消 | 指定客户 ID、修改审核状态、维护公共仓库/渠道 |
 | 企业管理员 | Client | 管理本企业成员角色，并拥有获授权的订单操作 | 配置平台后台权限、跨企业授权 |
 | 平台订单运营 | Admin | 查询授权数据、审核、维护允许的申报字段 | 修改客户归属、订单号、入仓码或实测事实 |
 | 平台超级管理员 | Admin | 在平台权限范围内处理全部订单 | 绕过服务端状态机、直接指定任意目标状态 |
 | Order 服务 | 后端 | 保存订单、货物、快照、状态、入仓码、审计和 Outbox | 拥有测量、仓位、柜次或海外库存 |
 | Firstleg 服务 | 后端 | 审核后创建国内入库单，接收版本化申报更新 | 成为订单交易状态权威 |
 客户数据范围必须来自已认证身份。页面传入的 `tenantId/customerId` 不能单独形成授权。
 ## 3. F02 基础资料准备
 ### 3.1 企业和账号
 - 企业注册完成，可以用中文邮箱/手机号和密码登录；
 - 企业基本资料、联系信息和资质文件已填写；
 - 平台已经人工审核企业资料；
 - 当前成员拥有 `order:first-leg:create`、`order:first-leg:submit` 等对应权限；
 - 当前客户 Finance 资金账户存在且提交时可用。
 注册成功不等于具备提交资格。资料未审核通过时仍可登录、补资料和保存草稿，但提交订单必须失败关闭。
 ### 3.2 下单主数据
 | 主数据 | 权威来源 | 下单使用方式 |
 |---|---|---|
 | 国内收货仓 | Warehouse | 只能选 `ACTIVE` 且具备对应收货能力的公共仓 |
 | FBA/海外目的仓 | Warehouse | 按目的类型返回匹配且启用的公共仓 |
 | 私人目的地址 | Order 客户地址簿 | 只能选择本客户 `PRIVATE_DESTINATION`，或保存本单临时快照 |
 | 平台提货地址 | Order 客户地址簿 | `PICKUP` 时选择本客户 `PICKUP` 地址 |
 | 运输渠道与价格 | Firstleg 价格/渠道目录 | 先选国内收货仓，再加载当前有效渠道 |
 | 企业资格 | IAM | 提交时实时校验 |
 | 资金账户 | Finance | 提交时校验实际余额不小于 0 |
 下拉列表只负责选择，提交时服务端必须重新查询权威主数据。Warehouse、IAM 或 Finance 无法返回可信结果时提交失败，不回退前端旧缓存。
 ## 4. F01 企业资料与下单资格流程
 ### 4.1 客户维护企业资料
 入口：Client → 公司信息。
 现状操作：
 1. 填写企业名称、统一社会信用代码、企业类型和注册地址等基本信息；
 2. 填写联系人、手机、邮箱、微信和联系地址；
 3. 上传营业执照；法人身份证为可选资料；
 4. 保存后等待平台审核。
 数据归属：企业和成员属于 IAM。公司联系电话/邮箱是企业资料，不等于成员登录标识；成员手机号修改走账号链路。
 ### 4.2 平台审核企业资料
 入口：Admin → 客户管理/企业资料审核。
 1. 平台查看企业资料和资质；
 2. 资料正确时点击审核通过；
 3. 资料不正确时联系客户修改，不在头程订单流程伪造通过；
 4. 审核通过后，客户获得订单提交资格。
 ### 4.3 提交资格实时检查
 客户打开订单页时可以看到企业资料审核提示，但页面提示不是最终门禁。点击提交时服务端重新检查：
 - 当前客户身份和成员权限；
 - 企业资料审核状态；
 - Finance 资金账户有效响应；
 - 实际余额是否小于 0；
 - 仓库、渠道、目的仓和地址是否仍有效。
 草稿保存不触发资金门禁，因此“能保存”不能解释成“能提交”。
 ## 5. F03 客户单票下单详细操作
 入口：Client → 头程订单 → 创建订单。
 ### 5.1 选择履约类型
 当前主要履约形态：
 | 履约形态 | 业务含义 | 关键限制 |
 |---|---|---|
 | 普通头程 | 普通 FBA、海外仓或私人仓货物 | 按箱码进入后续测量和装柜 |
 | `ONE_CLICK_DROPSHIP` 一件代发 | 国内清点 SKU、组托后跨境，海外按 SKU/箱唛出库 | 每个货物明细必须有 SKU；目的类型固定走海外仓能力，不允许靠货名推导 SKU |
 ### 5.2 选择交货方式
 | 交货方式 | 页面值 | 必填数据 | 后续含义 |
 |---|---|---|---|
 | 快递自送 | `SELF_EXPRESS` | 国内收货仓；快递信息按页面当前要求维护 | 客户自行寄到国内仓 |
 | 平台上门提货 | `PICKUP` | 本企业提货地址、联系人、电话、城市、详细地址、预约提货时间 | 订单冻结客户要求的提货事实；不等于订舱级拖车 |
 | 卡车自送 | `SELF_TRUCK` | 国内收货仓和本单自送信息 | 客户自行送到国内仓 |
 `PICKUP` 地址可从地址簿选择，也可保存当前地址。停用地址不能用于新订单，但历史订单继续显示已冻结快照。
 ### 5.3 选择国内收货仓和渠道
 1. 从平台有效国内收货仓单选；
 2. 选择仓库后加载该仓可用运输渠道；
 3. 选择渠道，保存稳定 `channelCode` 和服务端名称快照；
 4. 选择报价包税方式；
 5. 选择买单或退税；
 6. 选择整柜 `FCL` 或散货 `LCL`；
 7. 木制品货物要求商检时，页面和服务端必须校验。
 渠道编码是业务校验依据，不能从渠道中文名称反推。
 ### 5.4 选择目的类型和目的地
 | 目的类型 | 页面操作 | 服务端规则 |
 |---|---|---|
 | `FBA` | 选择平台维护的有效 FBA 仓 | 仓库类型必须匹配；货物行要求货件编号和跟踪编号 |
 | `OVERSEAS` | 选择平台维护的有效海外目的仓 | 不允许用私人地址或国内仓冒充 |
 | `PRIVATE` | 选择/保存本企业私人地址，填写名称、联系人、电话、国家、城市、地址和邮编 | 地址属于本客户；不创建伪公共仓 |
 一件代发页面不开放 FBA/私人仓选择，使用海外仓路径承接后续海外库存。
 ### 5.5 录入货物明细
 每张订单至少一条货物明细。当前页面覆盖：
 | 分类 | 字段 |
 |---|---|
 | 识别 | SKU、中文品名、英文品名、产品图片、混箱组合 |
 | 包装 | 包装类型（纸箱/托盘/木箱）、材质、箱数、每箱数量、总数量 |
 | 申报尺寸重量 | 长宽高、总毛重、总净重、总体积 |
 | 海关申报 | 报关 HS CODE、清关 HS CODE、申报单价、申报金额 |
 | FBA | 货件编号、跟踪编号、UPC |
 | 产品属性 | 用途、型号、品牌、产品规格、危险品、木制品 |
 | 辅助 | 备注 |
 关键计算和校验：
 - 总数量、总重量和总体积由明细汇总，不能另传一套冲突合计；
 - 箱数、件数、重量和体积必须满足正数/非负规则；
 - FBA 货物必须填写货件编号和跟踪编号；
 - 木制品必须满足商检选择；
 - 一件代发 SKU 强制存在，同一箱可通过混箱组合保存多个 SKU；
 - 图片只保存经 File 校验的文件引用，Order 不长期保存图片二进制。
 ### 5.6 订单级其他信息
 - 期望出货日期：客户期望，不等于平台确认 ETD；
 - 客户备注：客户和平台可见；
 - 客户参考号/跟踪编号：用于客户内部定位，不替代平台订单号；
 - 费用预估：下单阶段只作当前规则下的估算，不能当成最终费用或客户确认版本。
 ### 5.7 保存草稿
 客户点击“保存草稿”：
 - Order 保存主表、Party 快照和货物明细；
 - 状态保持 `DRAFT`；
 - 不生成入仓码；
 - 不创建 Firstleg 正式入库单；
 - 不触发资金账户校验；
 - 后续可继续编辑或取消。
 ## 6. F04 客户批量导入详细流程
 入口：Client → 头程订单 → 批量导入订单。
 ### 6.1 下载模板
 模板按当前登录客户动态生成：
 - 本客户有效提货地址和私人地址；
 - 全部有效国内收货仓；
 - 匹配目的类型的有效目的仓；
 - 当前有效渠道和中文下拉项；
 - 日期、数字和枚举校验。
 模板目录必须读取全部分页候选，不能只生成第一页选项。
 ### 6.2 填写和上传
 - 文件只接受 `.xlsx`；
 - 最大 5MB；
 - 最多 50 行有效数据；
 - 直接选择中文下拉值，不填写内部 ID；
 - 平台上门提货必须填写预约时间和提货地址；
 - 木制品必须选择商检；
 - 一件代发必须填写 SKU。
 ### 6.3 两种导入模式
 | 模式 | 行失败时行为 |
 |---|---|
 | `PARTIAL` | 成功行创建草稿，失败行返回行号、字段和原因 |
 | `ATOMIC` | 任一行失败时整批不创建订单 |
 导入时服务端重新加载仓库、渠道、地址和客户归属，不信任模板隐藏页。成功结果只创建 `DRAFT`，客户仍需检查并提交。
 ## 7. F05 订单提交和入仓码
 ### 7.1 提交前检查
 客户端进行表单校验后，服务端再次校验：
 1. 当前订单属于登录客户且版本一致；
 2. 状态允许提交；
 3. 当前成员有提交权限；
 4. 企业资料已审核通过；
 5. Finance 账户响应有效且实际余额不小于 0；
 6. 国内收货仓、目的仓和渠道仍启用并类型匹配；
 7. 地址属于本客户且类型正确；
 8. 货物字段、FBA 条件、木制品商检和一件代发 SKU 完整。
 ### 7.2 提交事务结果
 成功后：
 - Order 状态 `DRAFT → SUBMITTED`；
 - 统一主状态展示为 `PENDING_REVIEW`；
 - 生成并固定全局唯一入仓码；
 - 写提交历史、操作者和服务端时间；
 - 发布后续协作所需的可靠消息/内部事实；
 - 同一幂等请求重放返回原结果，不产生第二个入仓码。
 入仓码是订单、国内入库、箱码、装柜和海外尾程之间的稳定业务关联码。页面不得用内部订单 ID 替代。
 ### 7.3 F06 草稿编辑与取消
 - 草稿允许有权限的企业操作员继续修改并保存；
 - 已提交订单不得再通过草稿入口覆盖审核中的权威版本；
 - 只有服务端当前状态允许时才能取消，页面按钮不是最终授权；
 - 取消携带当前版本和幂等键，并记录操作人、时间和原因；
 - 已进入不可逆履约的订单不能取消，需进入后续阶段异常流程；
 - 请求超时后先查询当前状态，不换新幂等键盲目重试。
 ## 8. F07 平台审核和申报修订
 入口：Admin → 统一订单 → 待审核。
 ### 8.1 单票审核
 1. 按订单号、入仓码、客户、仓库、渠道或状态定位订单；
 2. 核对客户、交货方式、预约时间、国内收货仓、目的类型、目的仓、货物和申报；
 3. 查看平台可见内部信息和服务端返回的下一动作；
 4. 必要时修改允许的客户申报字段；
 5. 点击审核通过。
 ### 8.2 批量审核
 1. 选择同一操作范围内的待审核订单；
 2. 一次调用批量审核预览，不逐票循环拉详情；
 3. 预览按请求顺序返回中文货物摘要、渠道、目的仓、入仓码、`canApprove` 和 `blockReason`；
 4. 操作员只提交可审核项；
 5. 服务端再次校验状态和版本后逐票处理。
 ### 8.3 平台申报修订边界
 平台可在 `DRAFT/REJECTED/SUBMITTED/APPROVED` 范围内按版本修改客户原始申报，但：
 - 不得修改客户归属、国内收货仓、订单号、入仓码和状态；
 - 不得增删或重排货物行，使用稳定 `itemNo` 定位；
 - 不得覆盖设备/仓库实测、测量审核和计费事实；
 - 国内收货仓或中转仓要变化时必须重新下单；
 - 只有渠道变化时才检查 Firstleg 履约可逆性和重新计价门禁；
 - 内部校验不可用时失败关闭，不能只改 Order 留下跨服务不一致；
 - 成功后通过 `ORDER_DECLARATION_UPDATED_V1` 向 Firstleg 同步完整申报快照和字段变化。
 ### 8.4 审核通过结果
 - Order 状态 `SUBMITTED → APPROVED`；
 - Firstleg 幂等创建正式国内入库单；
 - 正式入库单沿用提交时生成的入仓码；
 - 生成/补齐后续测量和 PDA 使用的稳定箱码映射；
 - 统一主状态进入 `WAIT_MEASURE`；
 - 审核动作和建单结果写入时间线。
 审核通过不代表货物到仓，也不代表测量、计费或入库完成。
 ## 9. 客户订单列表和详情
 ### 9.1 列表筛选
 当前客户可按订单号、国内收货仓、渠道、入仓码/SKU、创建时间、当前状态、目的仓类型和快递单号查询本企业订单。
 ### 9.2 列表核心展示
 列表包含订单号、入仓码、状态、渠道、运输方式、交货方式、预约提货时间、国内收货仓、目的仓、目的类型、箱数、SKU、重量、体积、费用摘要、货件编号、跟踪编号、柜次和船期摘要等。
 数据可能来自 Order 申报和 Firstleg 履约聚合；Order 为 `SUBMITTED` 时必须优先展示待审核，不能因 Firstleg 预投影显示成待测量。
 ### 9.3 详情和可用操作
 详情展示：
 - 订单主信息和客户/地址快照；
 - 货物明细和图片；
 - 入仓码业务关系；
 - 服务端时间线；
 - 当前履约摘要；
 - 当前允许的编辑、提交、费用确认、报关资料等动作。
 平台内部备注、成本、其他客户数据和内部事件字段不能进入客户响应。
 ## 10. 状态机和动作
 ### 10.1 Order 交易状态
 ```text
 DRAFT --提交--> SUBMITTED --平台审核通过--> APPROVED
  └--取消--> CANCELLED
 APPROVED --后续全部履约可信回写--> COMPLETED
 ```
 当前产品不以“审核驳回”作为正常业务路径；历史 `REJECTED` 数据在客户侧仍按待补充/待审核兼容展示，不能据此新增一套驳回流程。
 ### 10.2 统一订单主状态交接
 | Order/Firstleg 事实 | 统一显示 | 下一责任人 |
 |---|---|---|
 | Order `DRAFT` | 草稿 | 客户 |
 | Order `SUBMITTED` | `PENDING_REVIEW` | 平台订单运营 |
 | Order `APPROVED` + 正式入库单 | `WAIT_MEASURE` | 国内仓/测量人员 |
 交易状态和履约主状态是两个维度。平台审核后不应把 Order 交易状态继续当成仓库作业状态。
 ## 11. 数据流转和权威归属
 ```text
 Auth/IAM
  ├─ 当前客户、成员、角色、企业审核资格
  ↓
 Client 下单
  ├─ Warehouse：实时校验国内仓、目的仓和仓库快照
  ├─ Firstleg：读取有效渠道/价格目录
  ├─ Finance：提交时校验资金账户
  ↓
 Order 本地事务
  ├─ 订单主表、Party快照、货物明细
  ├─ 状态、版本、入仓码、时间线、幂等结果
  └─ Outbox/内部调用事实
  ↓ 审核通过
 Firstleg
  ├─ 正式国内入库单
  ├─ 稳定箱码/箱唛来源
  └─ 下一阶段 WAIT_MEASURE
 ```
 ### 11.1 Order 权威数据
 - 客户归属、订单号、入仓码；
 - 客户原始申报和货物明细；
 - 下单时 Party/地址和仓库必要快照；
 - 订单交易状态、版本、幂等和时间线。
 ### 11.2 Order 不拥有的数据
 - 实际尺寸、重量和测量审核；
 - 国内仓位、托盘和装柜事实；
 - 柜次、船节点、海外库存和出库；
 - Finance 钱包和结算主账。
 ### 11.3 关键编号
 | 编号 | 生成时点 | 是否可改 | 用途 |
 |---|---|---|---|
 | `orderNo` | 创建/提交规则生成 | 否 | 客户订单定位 |
 | `inboundCode` | 首次成功提交 | 否 | 国内入库至海外尾程稳定关联 |
 | 客户参考号 | 客户填写 | 按状态 | 客户内部检索，不替代平台编号 |
 | 货物 `itemNo` | 订单明细创建 | 不重排 | 申报更新和箱码来源定位 |
 ## 12. 正常流、分支和异常恢复
 | 场景 | 系统行为 | 操作员处理 |
 |---|---|---|
 | 企业资料未审核 | 可保存草稿，提交拒绝 | 补资料并等待平台审核 |
 | 资金余额小于 0 | 提交拒绝 | 充值或联系财务处理 |
 | Finance/IAM/Warehouse 不可用 | 提交失败关闭 | 保留草稿，服务恢复后原单重试 |
 | 仓库/渠道在草稿后停用 | 提交时拒绝 | 重新选择有效项 |
 | 私人地址归属不符 | 拒绝且不泄露其他客户数据 | 选择本企业地址或新建 |
 | 木制品未选商检 | 表单/服务端拒绝 | 补充商检选项 |
 | FBA 缺货件号/跟踪号 | 提交拒绝 | 补齐对应货物行 |
 | 一件代发缺 SKU | 保存/提交按当前门禁拒绝 | 为每个物理箱内货物补 SKU |
 | 版本冲突 | 当前写入失败且不覆盖新版本 | 刷新订单后重新编辑 |
 | 请求超时 | 不能换新幂等键盲重试 | 先查询订单/幂等结果，再用原操作处理 |
 | 批量导入部分失败 | `PARTIAL` 只建成功行；`ATOMIC` 整批不建 | 按行号和字段修正后重新导入 |
 | 审核时 Firstleg 建单失败 | 不能宣称阶段完成 | 查看服务端结果，受控重试或修复依赖 |
 | 渠道变更不允许 | Order 和 Firstleg 都不写 | 根据阻断原因新建订单或处理下游占用 |
 ## 13. 阶段完成判定
 每张进入阶段二的订单必须同时满足：
 - [ ] Order 属于正确客户且状态为 `APPROVED`
 - [ ] 客户可见订单号存在
 - [ ] 全局唯一入仓码存在且未变化
 - [ ] 国内收货仓、渠道、目的类型和目的地快照完整
 - [ ] 货物明细行集合、箱数、SKU/申报字段符合订单类型
 - [ ] Firstleg 正式国内入库单已创建并沿用同一入仓码
 - [ ] 一件代发稳定箱码与 SKU 来源可用
 - [ ] 统一主状态为 `WAIT_MEASURE`
 - [ ] 审核和建单时间线可查
 - [ ] 重放提交/审核不会生成重复入仓码或重复入库单
 任何一项缺失都不能把订单交给国内仓作为正式测量任务。
 ## 14. 本阶段评审问题
 这些问题不阻断现状记录，但需要业务评审确认后才能进入优化：
 1. 平台上门提货当前在订单中冻结地址和预约时间，但是否存在独立派车、接单、到仓回执流程？若没有，阶段二只能从“货物实际到仓”开始，不能假设提货已被系统履约。
 2. 客户是否仍需要平台代创建订单；若保留，代创建时客户授权、数据来源和通知方式需单列。
 3. 当前产品不设订单审核驳回，但代码兼容 `REJECTED` 历史状态；业务是否确认继续采用“平台修改或联系客户修改、保持待审核”。
 4. 旧系统入仓码模式是否仍会在任何环境启用；若不会，应从正式流程和页面移除。
 5. 下单页的费用预估对客户应如何命名，避免被理解成最终账单。
 6. 一件代发混箱 SKU 的实际填报责任人和现场纠错责任是否已明确。
 ## 15. 阶段二交接包
 交给阶段二“国内到仓、测量、计费与组托”的输入应只有以下权威数据：
 - 客户和订单业务身份；
 - 订单号、入仓码、货物 `itemNo`；
 - 交货方式和预约提货事实；
 - 国内收货仓快照；
 - 渠道与目的仓/私人地址快照；
 - 客户申报箱数、SKU、尺寸、重量、体积和报关资料；
 - 一件代发箱内 SKU 关系；
 - 审核通过时间、版本和幂等历史。
 阶段二新增实测和计费事实，不反向覆盖本阶段客户原始申报。
 ## 16. 事实来源
 - `docs/订单与客户/README.md`
 - `docs/订单与客户/订单与客户头程订单闭环设计.md`
 - `docs/统一订单主状态与操作契约.md`
 - `docs/业务快速索引.md`
 - `apps/client-web/AGENTS.md`
 - `apps/client-web/src/modules/first-leg/views/FirstLegOrdersView.vue`
 - `apps/client-web/src/modules/first-leg/api/firstLeg.ts`
 - `apps/admin-web/AGENTS.md`
 - `apps/admin-web/src/modules/unified-orders/pages/UnifiedOrdersView.vue`
 - `baiyue-firstleg/order/AGENTS.md`
 - `baiyue-firstleg/order/src/main/resources/openapi/order-v1.yaml`
@@ -0,0 +1,437 @@
 # 阶段三：国内货柜履约与出仓
 > 对应全景流程：F14～F23。  
 > 阶段起点：入库单主状态为 `WAIT_SPLIT`，不存在有效 HOLD。  
 > 阶段终点：装柜后完成退税报关并进入待发区，再完成送港线的仓库离开/进港事实；实际开船 `VESSEL_DEPARTED` 由阶段四承接。
 > 本阶段复用订单、入库单、柜次和装柜计划，不新建独立“出仓单”。`LOADED` 后先推进报关协同，报关完成后进入待发区，再推进送港；费用确认是并行事实，装柜完成后对已装范围的当前有效费用版本执行系统默认确认。
 ## 1. 阶段目标和边界
 本阶段把可分柜货物转化为可追溯的真实整柜离仓事实，覆盖：
 1. 模拟柜、智能推荐、人工分配和同柜不可拆组；
 2. 海运订舱草稿、资料补齐和放舱；
 3. 订舱级国内拖车预约；
 4. 模拟柜与订舱柜型需求、真实集装箱号关联；
 5. 预装确认、动态增减和普通散货托盘标签；
 6. 国内 PDA 拣货、整托装柜和异常闭环；
 7. 空仓、半仓、满仓、锁仓、带锁码照五类装柜证据与锁码文本；
 8. 装柜完成、部分装载分片和跨区交接快照；
 9. `LOADED` 后通知报关行、客户资料收集、回执确认、整柜正式申报和海关结果；
 10. 送港、进港、甩柜/改配、实际离仓和拖车费用归集。
 `LOADED` 表示货物已经完成实际装柜。此时先触发报关线：收集退税客户资料、发送报关行、处理回执和客户确认；报关完成后进入待发区，才允许推进拖车、离仓和进港。已进港不代表报关完成，容量不足时记录甩柜和改配船次；甩柜不影响已完成报关资料、回执和客户确认。只有实际开船后才进入海运节点。国内 Admin/PDA 不得把订单推进到海外派送完成 `DELIVERED`。
 ## 2. 角色、终端和对象
 | 角色 | 终端 | 主要操作 |
 |---|---|---|
 | 排柜操作员 | Admin | 创建模拟柜、搜索候选、推荐/人工加入、调整预装 |
 | 订舱操作员 | Admin | 建订舱草稿、维护运输资料、上传文件、放舱 |
 | 国内调度 | Admin | 建订舱级拖车预约、选择供应商、维护时间和附件 |
 | 仓库主管 | Admin | 预装确认、真实柜号补录、任务和证据监督 |
 | PDA 拣货员 | 国内 PDA | 领取唯一柜次任务、扫码、异常、拍照、完成装柜 |
 | 报关操作员 | Admin | 汇总整柜资料、开始报关、上传完成文件、完成报关 |
 | 企业操作员 | Client | 上传本客户退税/报关资料、查看本企业进度和回执 |
 | 出仓操作员 | Admin | 查看组合门禁，必要时人工确认离仓 |
 核心对象：
 | 对象 | 业务作用 | 稳定标识 |
 |---|---|---|
 | 入库单 | 每票/分片货物履约主体 | `inboundId`、入仓码 |
 | 模拟柜/柜次 | 多票货物共享的装载容器 | `containerBookingId`、`cabinetNo` |
 | 装柜计划 | 柜次唯一预装/PDA 作业聚合 | `loadingPlanId` |
 | 海运订舱 | 船司运输和柜型需求聚合 | `oceanBookingId`、`OB-yyMMdd-####` |
 | 拖车预约 | 一个已放舱订舱的国内提柜/送柜任务 | `truckAppointmentId` |
 | PDA 任务 | 单柜次单作业员的现场任务 | `taskId`、任务版本 |
 | 整柜报关 | 柜次级资料冻结和回执 | 柜次及报关记录标识 |
 ## 3. 前置检查
 - 候选入库单已完成阶段二，实际箱数、重量和体积可用；
 - 一件代发已按实际托盘封托；
 - 当前入库单无有效 HOLD；
 - 柜型规格、国内中转仓、有效渠道和供应商主档可用；
 - 操作员理解模拟柜、真实柜号、订舱和拖车是不同对象；
 - 同柜不可拆组、已占用数量和版本冲突均以服务端返回为准；
 - 费用仍可并行维护，客户未确认不阻断排柜、预装、PDA 或装柜；装柜完成后对已装范围的当前有效已发布版本记录系统默认确认。客户确认和系统默认确认来源分开审计；缺少有效费用版本不伪造确认，部分装载不得把余量一起确认。
 ## 4. F14 模拟柜与智能排柜
 ### 4.1 创建模拟柜
 入口：Admin → 国内货柜/智能装柜。
 1. 选择正式装柜仓；
 2. 选择九类计划渠道组之一；
 3. 选择平台有效柜型，核对额定容量和限重；
 4. 填写计划日期和必要备注；
 5. 提交后系统原子创建稳定柜次、`cabinetNo` 和唯一装柜计划；
 6. 此时可以没有真实集装箱号，也不会因创建模拟柜自动产生订舱。
 容量和重量当前允许达到柜型额定值的 150%，超过时服务端拒绝。页面显示仅用于预判，最终以服务端重新计算为准。
 ### 4.2 查询候选
 工作台可查询 `PENDING_REVIEW`、`WAIT_MEASURE`、`WAIT_SPLIT`、`LOADING` 等未完成候选。状态是展示维度，能否加入必须看响应中的 `canAssign` 和原因。
 - 待审核或待测量订单可提前占位；
 - 预装确认和启动 PDA 前，实际作业成员必须进入 `WAIT_SPLIT`；
 - 普通订单按剩余箱数分配；
 - 一件代发按每个未占用的已封托托盘独立返回和分配，禁止拆托；
 - 同柜不可拆组必须成员完整、满箱并原子加入；
 - 推荐顺序以入库时间先进先出为基础。
 ### 4.3 智能推荐和人工加入
 智能推荐：设置筛选范围和装载目标，系统逐项校验渠道、仓库、剩余箱数、体积、重量、托盘完整性、组锁和占用，再返回推荐结果。
 人工加入：选择候选，填写普通货分配箱数或选择一件代发整托，携带计划版本提交。系统重新校验资格；页面旧结果不能作为写入依据。
 一件代发一票多托时逐托展示，其中一托已分配不得隐藏其他未分配托盘。容量不足时跳过整托，不能回退成按箱拆托。
 ### 4.4 调整与费用影响
 - 未产生物理拣货的普通明细可增减或移除；
 - 已拣数量是可调整下限；
 - 同柜组只有全组都未拣时才能整组移除；
 - 单行一件代发只能按该行 `palletId` 整托移除；
 - 成员变化需要重算未冻结的柜级/客户级费用；
 - 已确认、已发送或客户已确认的费用版本不得直接改写，应按费用规则生成新版本或拒绝。
 ## 5. F15 海运订舱与放舱
 ### 5.1 创建草稿
 入口：Admin → 海运订舱。
 1. 选择启用的国内中转仓；
 2. 选择该仓当前有效渠道；
 3. 选择 `ACTIVE/BOOKING` 订舱供应商；
 4. 填写三类参与方和已知运输资料；
 5. 至少维护一项、最多二十项柜型需求，数量为正整数；
 6. 保存为 `DRAFT`，系统生成 `OB-yyMMdd-####` 订舱号。
 草稿允许资料不完整、替换文件和继续编辑。柜型需求只表达需要多少个什么柜型，不创建真实货柜行。
 ### 5.2 补齐并放舱
 放舱前核对：
 - 提单号全局唯一；
 - 船名、航次、起运港、目的港、ETD、ETA 和运输条款完整；
 - 渠道仍有效；
 - 柜型需求与平台规格一致；
 - 存在有效 `BOOKING_CONFIRMATION` 或 `BILL_OF_LADING` 文件；
 - 订舱供应商仍为有效主档。
 点击放舱后状态从 `DRAFT` 进入 `RELEASED`，运输快照永久只读。放舱不要求真实柜号，不得为了通过校验伪造柜号。
 ## 6. F16 订舱级国内拖车
 入口：Admin → 国内拖车预约。
 1. 从服务端候选中选择已 `RELEASED`、有提单号和有效订舱文件的订舱；
 2. 选择 `ACTIVE/TRUCKING/DOMESTIC` 供应商；
 3. 填写计划装柜时间、联系人和附件；
 4. 保存/提交预约；
 5. 重复创建时返回现有非终态预约，不生成第二张。
 拖车单只绑定订舱，不绑定客户、柜次、装柜计划或真实柜号。一个订舱最多一张非终态预约，已有有效完成单不能再次创建收费。
 PDA 装柜完成不推进拖车状态。只有订舱要求的全部柜型数量均已关联，并且所有柜均确认国内离仓后，拖车才自动完成。正金额应付拖车费按各柜最终实装体积守恒分摊并发送 Finance；缺供应商归属、有效体积或费用配置时失败关闭，不做伪造均分。
 ## 7. F17 柜次关联和真实柜号
 入口：Admin → 柜次详情 → 关联订舱/补录柜号。
 1. 选择已放舱订舱的未满配柜型需求；
 2. 选择对应模拟柜；
 3. 校验仓库、渠道映射、柜型、容量、限重和需求剩余数量；
 4. 录入真实集装箱号；
 5. 提交后在原柜次上冻结订舱、需求和柜号快照。
 关联不会更换 `containerBookingId`、`cabinetNo`、装柜计划或明细。真实集装箱号在同一订舱内唯一，不同提单可按业务规则复用。
 订舱关联、预装确认和任务创建技术上可先于柜号，但正式操作应在 PDA 最终完成前补齐。已有柜号纠正仅限计划 `EDITING`、任务未领取且没有物理作业事实。
 ## 8. F18 预装确认、动态增减与标签
 ### 8.1 预装核对与确认
 入口：Admin → 预装清单。
 1. 打开柜次唯一预装计划；
 2. 核对每个入仓码、客户、目的仓、普通箱数或一件代发托盘；
 3. 查看容量、重量、已占用和异常提示；
 4. 确认所有现场成员已到 `WAIT_SPLIT` 且未 HOLD；
 5. 点击计划级确认，生成或开放唯一 PDA 任务；
 6. 记录确认快照、操作人和版本。
 预装进入 `CONFIRMING/CONFIRMED` 只冻结确认快照，不锁死尚未完成柜次。计划仍为 `EDITING/LOADING` 时可继续增加合法明细；未拣明细可调整，已拣明细保持锁定。
 新增或调整后计划和任务版本递增，PDA 旧版本必须刷新再作业。
 ### 8.2 普通散货托盘标签
 普通、非一件代发 FBA 明细在计划 `LOADING/COMPLETED` 且真实柜号有效时生成正式托盘标签：
 1. 系统按平台柜次号、FBA 地址内部编号和三位序号生成冻结托盘码；新柜次号为全局连续且不按日期重置的 `D0001`、`D0002`，托盘码不依赖可跨提单复用的真实柜号；
 2. 地址内部编号从 Warehouse 启用主数据读取；
 3. 缺编号或同柜重复时拒绝生成；
 4. 重复生成必须与已有明细一致；
 5. Admin 全部打印或按仓指定张数打印；
 6. A4 横版每托一页，标签与海外补打复用同一编号。
 该标签与阶段二一件代发 `DP` 托盘不同：一件代发托盘在测量后已实际清点封托，装柜时按冻结整托分配。
 ## 9. F19 国内 PDA 拣货装柜
 ### 9.1 领取和开始
 入口：国内 PDA → 拣货装柜。
 1. 操作员选择当前作业仓；
 2. 打开或扫描柜次任务；
 3. 核对真实柜号、装柜计划和任务版本；
 4. 领取任务后绑定当前作业员、任务和柜次；
 5. 单柜次只允许一名作业员，不支持多人并行或无审计接管；
 6. 进入任务后计划/入库履约按规则进入 `LOADING`。
 正式作业当前只支持在线。设备本地草稿按作业员、任务和柜次隔离；批量提交是否具备完整原子事务仍需在优化/验收中持续核实。
 ### 9.2 普通散货扫码
 - 扫描稳定箱码，一箱一码；
 - 不能用 SKU、件数、入仓码或自由文本代替箱码；
 - 系统核对箱码属于当前入库单、当前任务且尚未处理；
 - 连续扫描先进入当前任务草稿，操作员核对后批量提交；
 - 重复扫描不重复增加实装数量。
 ### 9.3 一件代发整托装柜
 - 扫描 `DP` 托盘码，或扫描成员箱码定位所属已封托托盘；
 - 页面展示托盘、入仓码、箱数和 SKU 汇总；
 - 使用 `PICK_PALLET` 一次提交整托；
 - 禁止部分拣货、拆托或将同托不同订单成员分开提交；
 - 装柜完成按 `palletId` 精确冻结每托箱唛和 SKU，不能按整票模糊复制。
 ### 9.4 部分拣货、跳拣和异常
 允许分批扫描和暂时跳过，但每个未完成项必须选择/填写异常原因。存在未解决异常、缺少处理单元、数量不平或版本冲突时不能完成任务。
 提交超时后先查询任务明细和操作结果，禁止更换幂等键盲目重复提交。版本冲突时刷新任务，保留未提交草稿并重新核对。
 ## 10. F20 装柜证据与铅封
 PDA 按现场要求采集五类证据：
 1. `EMPTY`：空仓照片；
 2. `HALF`：半仓照片；
 3. `FULL`：满仓照片；
 4. `LOCKED`：锁仓照片；
 5. `SEAL`：带有效铅封号的带锁码照片。
 每类至少一张有效照片，同类允许追加。PDA 仅允许现场相机拍摄；有权限的 Admin 操作员/理货员可人工补充，普通拣货员不开放后台上传。
 证据先上传 File 获得合法文件引用，再绑定柜次/任务。错误图片只能作废，不能硬删除；需保留上传、作废、操作者、时间、文件哈希和幂等记录。照片及铅封号当前不对客户展示。
 ## 11. F21 装柜完成与分片
 PDA 点击“完成装柜”时，服务端重新校验：
 - 任务属于当前柜次和仓库且版本一致；
 - 真实集装箱号存在；
 - 所有普通箱码或一件代发整托均核平；
 - 没有未解决异常；
 - 空仓、半仓、满仓、锁仓、带锁码照五类证据和锁码文本完整；
 - 计划明细、已拣数量和最终实装数量守恒。
 校验通过后：
 1. PDA 任务和装柜计划进入 `COMPLETED`；
 2. 实装来源入库单进入 `LOADED`；
 3. 生成最终实装箱码、托盘、SKU 和证据快照；
 4. 对部分装载执行一次分片；
 5. 生成跨区 Outbox，但后续消费必须保持幂等。
 部分装载时，已装数量形成当前柜次的 `LOADED` 子入库单，余量形成可继续 `WAIT_SPLIT` 的后续子单；只允许一层分片，所有子项总和必须等于来源数量。客户订单身份和入仓码关联不能丢失。
 ## 12. F22 客户资料与整柜出口报关
 ### 12.1 F22-A `LOADED` 后通知报关并建立客户案例
 入口：`LOADED` 事件 → Admin/Client → 报关资料。
 1. 装柜完成后按最终实装清单通知报关行，建立本柜报关批次和每个客户/入仓码的 `customerCustomsCase`；
 2. 客户上传本企业资料，平台校验客户、订单、入仓码、实际装载数量和文件归属；
 3. 平台将资料发送给报关行，记录发送时间、资料版本和 `roundNo`；
 4. 报关行返回本轮回执，平台保存文件和回执字段，并向对应客户展示确认任务。
 柜前可以存在资料准备或历史附件，但不创建本柜正式客户确认轮次，也不能显示“已通知报关”。客户资料缺失形成报关补件待办，未完成报关不得进入待发区或推进送港。
 ### 12.2 F22-B 报关行回执与客户确认循环
 客户查看报关行回执后有两个结果：
 1. **确认**：当前客户案例进入 `CUSTOMER_CONFIRMED`，保存确认人、确认时间、回执版本和幂等键；
 2. **打回**：当前案例进入 `NEEDS_RESUBMIT`，保存打回原因；客户重新上传/替换资料，平台重新发送报关行，报关行生成新回执，`roundNo` 加一后再次发客户确认。
 客户打回只重开对应客户案例，不重置其他客户已经确认的轮次。直到柜内所有客户案例都为 `CUSTOMER_CONFIRMED`，才允许进入整柜正式提交。
 ### 12.3 F22-C 所有客户通过后的整柜正式申报
 1. 平台检查所有客户案例均已确认，冻结本柜最终实装和资料版本，生成整柜正式申报批次；
 2. 将整柜资料提交报关行确认，报关行完成正式申报；首版不做外部系统直连，保留人工提交和审计记录；
 3. 海关结果独立记录为查验、免查验放行、补件/退回、扣货等，不把客户确认回执直接当成海关放行；
 4. 报关完成后进入待发区；报关事实不覆盖送港线的离仓、进港、甩柜事实。甩柜只改变运输船期，不回退报关资料、回执或客户确认。
 ## 13. F23 送港、进港与甩柜
 ### 13.1 出仓硬门禁
 送港线的离仓/进港门禁逐项检查：
 - 无有效 HOLD；
 - 入库单为 `LOADED`；
 - 装柜计划为 `COMPLETED`；
 - PDA 柜次任务为 `COMPLETED`；
 - 订舱已 `RELEASED` 且分配当前柜次；
 - 五类证据与有效锁码文本完整；
 - 送港任务和当前船次分配完整；
 - 报关完成是进入待发区以及后续仓库离开、送港和进港的前置。
 订舱、拖车、仓库离开和港口进场属于待发区之后的送港线事实。容量不足时记录 `ROLLED_OVER`，保存原船次、滚动次数、新船次、预计开船时间和客户通知；不重新生成报关批次或客户确认任务。
 ### 13.2 自动与人工确认离仓
 送港状态变化或其他送港门禁满足时系统自动尝试收敛。未自动完成时，平台在柜次/送港页面：
 1. 打开门禁清单；
 2. 逐项处理未通过原因；
 3. 全部通过后点击确认离仓；
 4. 携带当前版本和幂等键提交；
 5. 查看唯一离仓历史和第一条实际节点。
 成功后系统：
 - 写入整柜唯一国内离仓事实；
 - 写入实际 `DEPARTED_WAREHOUSE` 节点；
 - 写入 `PORT_RECEIVED` 或 `ROLLED_OVER`；
 - 维护船次和开船前等待，不把预计 ETD 记成海运在途；
 - 检查并尝试完成订舱级拖车；
 - 保持跨区交接事件可重试且不重复建单。
 实际离仓和进港节点产生后禁止撤销。发现错误转入线下和后续阶段异常处理，不提供修改历史伪装未离仓或未进港的能力。报关线的客户打回、重新发送和海关查验单独记录，不回滚送港事实。
 ## 14. 状态和动作总表
 | 对象 | 关键状态 | 推进动作 |
 |---|---|---|
 | 入库单 | `WAIT_SPLIT → LOADING → LOADED` | 分配/开始 PDA/完成装柜 |
 | 装柜计划 | `EDITING → LOADING → COMPLETED` | 预装调整/PDA 作业/最终完成 |
 | 订舱 | `DRAFT → RELEASED` | 补齐资料并放舱 |
 | 拖车 | 非终态 → `COMPLETED` | 所有要求柜次实际离仓后自动完成 |
 | 报关 | `WAITING_DOCUMENTS → SENT_TO_BROKER → RECEIPT_PENDING_CUSTOMER_CONFIRM → CUSTOMER_CONFIRMED / NEEDS_RESUBMIT → ALL_CUSTOMERS_CONFIRMED → FORMAL_SUBMITTED → INSPECTION/RELEASED` | 装柜后通知报关行；回执必须经对应客户确认，打回则新资料/新回执轮次 |
 | 送港 | `WAITING_FOR_LOADING → PORT_DELIVERY_PENDING → DEPARTED_WAREHOUSE → IN_TRANSIT_TO_PORT → PORT_RECEIVED / ROLLED_OVER` | 报关完成后进入待发区，再安排拖车和进港；容量不足时在原柜船期上人工修改船信息并留痕 |
 | 海运 | `WAITING_SAILING → VESSEL_DEPARTED → IN_TRANSIT` | 只有承运船舶真实开航才进入海运节点 |
 主状态只表达阶段结果。订舱、拖车、PDA、证据和报关保持关联子状态，页面应汇聚展示，但不能互相覆盖。
 ## 15. 异常与恢复
 | 场景 | 处理方式 |
 |---|---|
 | 候选显示可用但提交失败 | 以服务端最新占用/版本为准，刷新后重排 |
 | 待测量订单已占位 | 可保留计划占位，确认预装前必须到 `WAIT_SPLIT` |
 | 一件代发整托容量不足 | 跳过整托或换柜，禁止拆托 |
 | 订舱资料不全 | 保持 `DRAFT`，补齐后再放舱 |
 | 放舱后资料错误 | 不原地篡改冻结快照，按业务异常处置 |
 | 真实柜号暂缺 | 可先关联/确认，但最终装柜前必须补齐 |
 | PDA 旧版本 | 刷新计划，不以旧版本覆盖新增明细 |
 | 扫描错箱/重复箱 | 拒绝或提示已处理，核对稳定箱码 |
 | 未完成项有异常 | 记录原因并解决，禁止完成任务 |
 | 照片错误 | 作废并重拍，不硬删除证据 |
 | 部分装载 | 一次分片，已装与余量数量守恒 |
 | 报关资料缺失 | 定位对应客户/入仓码补件，办理批次不伪造完成 |
 | 出仓门禁未齐 | 展示具体阻断项，条件变化后受控重试 |
 | 离仓请求超时 | 查询唯一离仓历史/节点后再处理，不重复写事实 |
 ## 16. 数据流和阶段完成判定
 ```text
 WAIT_SPLIT 入库单/已封托托盘
  → 模拟柜与唯一装柜计划
  → 已放舱订舱 + 真实柜号 + 订舱级拖车
  → 预装确认/动态调整
  → PDA 实装 + 五类证据
  → COMPLETED / LOADED + 数量分片 + 跨区快照
      ├─ 报关线：通知报关 → 客户资料 → 报关行回执 → 客户确认/打回重做
      │             → 所有客户通过 → 整柜正式申报 → 查验/放行
      └─ 送港线：拖车 → DEPARTED_WAREHOUSE → PORT_RECEIVED
                    → 甩柜/改配（如发生）→ 等待实际开船
  → VESSEL_DEPARTED → 海运节点查询
 ```
 阶段完成必须同时满足：
 - [ ] 最终柜次、装柜计划、订舱、真实柜号关联可追溯
 - [ ] 全部实装箱/托盘/SKU 与入库单数量守恒
 - [ ] PDA 任务完成且无未解决异常
 - [ ] 五类证据和锁码文本完整有效
 - [ ] 装柜计划 `COMPLETED`，实装入库单 `LOADED`
 - [ ] 部分装载时已装子单和余量子单正确
 - [ ] 报关线已为每个客户建立案例，回执、确认/打回和每轮资料版本可追溯
 - [ ] 送港线已记录唯一国内离仓历史；如已进港，存在 `PORT_RECEIVED`，如甩柜，存在原船次/改配船次历史
 - [ ] 客户全部确认后才允许整柜正式提交；正式申报后的查验/放行结果单独记录
 - [ ] 船舶实际开航后才写入 `VESSEL_DEPARTED` 并启动海运节点查询
 - [ ] 跨区事件可幂等重试；甩柜/改配只新增船期事实，不覆盖报关资料、回执和客户确认
 ## 17. 易用性与数据流评审问题
 1. 排柜工作台是否充分解释“可提前占位”和“可实际作业”的差别？
 2. 推荐结果是否应逐项展示未入选原因、容量影响和费用影响？
 3. 模拟柜、柜次编号、真实柜号、订舱号和提单号是否在页面上容易混淆？
 4. 订舱、拖车、预装、PDA、报关是否需要一个柜次级总控清单，而不是跨页面查找？
 5. 预装确认后仍可动态增减时，如何提示 PDA 版本已过期并保护未提交草稿？
 6. PDA 批量提交需要补齐怎样的原子性、离线/弱网和失败整批回滚验收？
 7. 五类证据是否要提供拍摄引导轮廓、清晰度检查和缺图计数？
 8. 部分装载分片在 Client 应如何展示，避免客户误以为整票已经全部装柜？
 9. 报关资料清单、补件责任人、截止时间和回执匹配是否需要结构化待办？
 10. 出仓门禁失败是否需要直接跳转到对应处理页面？
 11. 拖车不作为出仓硬门禁的现行口径，是否与现场调度责任一致？
 12. 实际离仓不可撤销后，错误柜号或错误时间的合规更正流程由谁负责？
 ## 18. 阶段四交接包
 交给阶段四的权威数据包括：
 - 柜次、真实集装箱号、订舱号、提单号、船名和航次；
 - 起运港、目的港、ETD/ETA 和运输条款快照；
 - 最终实装订单、入仓单、箱码、托盘、SKU、重量和体积；
 - 装柜五类证据引用和报关完成事实；
 - 国内离仓时间和 `DEPARTED_WAREHOUSE` 实际节点；
 - 跨区事件版本、事件 ID 和有效载荷哈希；
 - `CarrierScheduleQuery` 及后续船节点查询上下文；
 - 未冻结费用和拖车应付等并行财务结果。
 ## 19. 事实来源
 - `docs/国内货柜履约/README.md`
 - `docs/国内货柜履约/国内货柜履约页面与原型清单.md`
 - `docs/归档/头程到尾程/头程下单到尾程出库现状流程全景清单.md`
 - `docs/统一订单主状态与操作契约.md`
 - `apps/admin-web/src/modules/container-loading/`
 - `apps/admin-web/src/modules/loading-lists/`
 - `apps/pda-uniapp/AGENTS.md`
 - `apps/pda-uniapp/pages/picking/picking.vue`
 - `baiyue-firstleg/firstleg/AGENTS.md`
 - `baiyue-firstleg/firstleg/src/main/resources/openapi/loading-lists-v1.yaml`
 - `baiyue-firstleg/firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml`
 - `baiyue-firstleg/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml`
 - `baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/SmartLoadingService.java`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/LoadingPickService.java`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/outbound/dispatch/service/OutboundDispatchService.java`
@@ -0,0 +1,593 @@
 # 阶段二：国内到仓、测量计费与组托
 > 对应全景流程：F08～F13。  
 > 阶段起点：Order 已审核通过，Firstleg 正式国内入库单已创建，统一主状态为 `WAIT_MEASURE`。  
 > 普通订单终点：测量审核通过，主状态进入 `WAIT_SPLIT`。  
 > 一件代发终点：测量审核后进入 `WAIT_PALLETIZE`，完成清点、归托和封托后进入 `WAIT_SPLIT`。  
 > 本文记录当前可执行流程。费用是并行状态，不作为进入 `WAIT_SPLIT` 的前置条件。
 ## 1. 阶段目标和边界
 本阶段要完成七件事：
 1. 用稳定入仓码、箱码识别实际到仓货物；
 2. 保存设备测量、人工测量、称重图片、OCR 原值和人工修正值；
 3. 核对实收箱数、实测尺寸、重量、预计托数和现场证据；
 4. 审核并冻结本次有效测量结果；
 5. 生成可独立维护、发布和确认的费用版本；
 6. 在需要时执行国内扣货或解除，并完整保留证据；
 7. 对一件代发订单完成逐箱 SKU 清点、归托和封托。
 本阶段不负责模拟柜、排柜、订舱、拖车、装柜、国内出仓、海外入库或尾程出库。普通订单进入 `WAIT_SPLIT` 仅表示已具备后续分柜条件，不表示已入柜、已离仓或已经生成海外库存。
 ## 2. 角色、终端与权限
 | 角色 | 终端 | 主要操作 | 边界 |
 |---|---|---|---|
 | 国内仓收货/测量员 | Admin、测量设备 | 按入仓码定位、录入或接收尺寸、上传称重图片、确认重量、提交测量 | 不审核自己的权限外任务，不改订单客户归属和原始申报 |
 | 国内仓现场主管 | Admin | 复核箱数、尺寸、重量和证据，处理现场差异 | 不直接改费用价格簿和客户账务 |
 | 测量审核员 | Admin | 单票或批量审核、驳回；有专项权限时异常放行 | 不通过修改数据库绕过证据或状态门禁 |
 | 费用操作员 | Admin | 查看系统试算、调整允许字段、确认并发布费用版本 | 不修改测量原始证据，不越权跨客户操作 |
 | 企业费用确认人 | Client | 查看已发送的当前费用版本并确认 | 不能看到未发布版本、其他客户或内部成本 |
 | 扣货操作员 | Admin | 发起 HOLD、上传凭证、按规则解除 | 已拣货、装柜或出仓后不能手工扣货/解除 |
 | 国内 PDA 操作员 | PDA | 一件代发逐箱清点、扫码归托、封托、规则内解封 | 不创建临时箱码，不直接改测量和费用 |
 | Firstleg 服务 | 后端 | 拥有入库单、箱码、测量、审核、费用来源、组托和主流程状态 | 不拥有客户资金主账、公共仓储主档或订单交易主数据 |
 | Finance 服务 | 后端 | 接收不可变费用来源，维护后续账务 | 不成为测量、箱码或主流程状态权威 |
 页面按钮是否可见只能作为操作提示，服务端仍需校验身份、数据范围、权限、当前状态、版本和幂等键。
 ## 3. 阶段输入与作业前检查
 ### 3.1 从阶段一接收的权威数据
 | 数据 | 来源 | 本阶段用途 |
 |---|---|---|
 | 客户、订单号、入仓码 | Order/Firstleg | 识别货主和整票任务 |
 | 国内收货仓 | Order 冻结快照、Warehouse 主档 | 限定实际作业仓和资源范围 |
 | 渠道、目的类型、目的仓/地址 | Order 冻结快照 | 费用试算和后续分柜参考 |
 | 货物 `itemNo`、SKU、申报箱数 | Order 申报快照 | 箱数核对、一件代发清点 |
 | 申报尺寸、重量、体积 | Order 申报快照 | 差异对比，不覆盖实测值 |
 | 履约类型 | Order/Firstleg | 判断普通订单或 `ONE_CLICK_DROPSHIP` |
 | 稳定箱码及箱内 SKU | Firstleg | 测量、PDA 和装柜全过程复用 |
 ### 3.2 现场开始前检查
 - 当前作业仓必须与入库单国内收货仓一致；
 - 入仓码必须可查询到唯一正式入库单；
 - 箱码必须来自系统已生成的稳定箱码池，不得用临时手写编号替代；
 - 订单处于允许采集测量的状态，已提交或已审核的测量批次不可继续修改；
 - 测量设备、秤、相机和网络可用；无法自动识别时必须保留图片并走人工确认；
 - 一件代发必须能够读取每个物理箱与完整 SKU 的冻结关系；
 - 操作员要先区分“申报箱数”和“实际确认箱数”，不得把客户申报直接当作实收事实。
 订单尚处于 `PENDING_REVIEW` 时，系统可允许提前采集测量数据，但不能完成测量审核、计价或进入分柜。正式交接仍以订单审核通过和入库单有效为准。
 ## 4. F08 国内到仓与箱码识别
 ### 4.1 按入仓码收货定位
 入口：Admin → 入库管理/统一入库工作台 → 货品与测量。
 操作步骤：
 1. 扫描或输入入仓码；
 2. 核对订单号、客户、国内仓、履约类型和申报箱数；
 3. 查看该票稳定箱码是否已经生成；
 4. 按实际到货逐箱核对外包装上的箱码；
 5. 对缺码、重码、无法识别或与本票不匹配的箱子先隔离，不直接进入测量；
 6. 确认现场货物与页面显示为同一客户、同一入仓码后再开始采集。
 系统中的“正式到仓”不是靠操作员另造一个新业务编号完成。入仓码负责整票定位，箱码负责物理箱身份，后续设备、人工测量、PDA 组托和装柜继续复用相同映射。
 ### 4.2 普通订单箱码
 - 每个物理箱使用稳定 `boxCode`；
 - 箱码可以由客户或平台下载打印，但是否打印不影响系统中箱码的有效性；
 - 测量记录必须关联稳定箱码或明确的箱规数量，不能只写自由文本；
 - 后续装柜完成时按最终实装事实冻结并向下游传递箱码/箱数。
 ### 4.3 一件代发箱码
 - `fl_inbound_carton_label` 表示物理箱；
 - 箱内一条或多条 SKU 关系在箱码生成时冻结；
 - 标签展示箱内 SKU，但二维码/条码仍只携带稳定箱码；
 - 缺少 SKU 的货物不能生成合格的一件代发箱唛；
 - PDA 清点时扫描这个箱码读取整箱 SKU，不重新手工创建商品明细。
 ### 4.4 到仓差异登记
 | 差异 | 现场处理 | 系统处理原则 |
 |---|---|---|
 | 少箱/分批到货 | 标识未到箱，暂不虚增实收 | 测量总箱数必须基于实际确认结果 |
 | 多箱 | 隔离并查明所属 | 未建立合法箱码关系前不得并入本票 |
 | 箱码破损 | 用入仓码和订单信息核验后补打原箱码 | 不生成第二个物理身份 |
 | 箱码属于其他订单 | 隔离并通知主管 | 禁止强行绑定当前入仓单 |
 | 外包装异常 | 拍照、备注并按异常规则处理 | 证据与业务事实关联，不能只在线下沟通 |
 ## 5. F09 尺寸测量与称重
 ### 5.1 页面和数据组成
 入口：Admin → 入库管理 → 货品与测量。
 一次完整测量至少包含：
 - 测量批次：入库单、批次状态、采集来源、提交人和时间；
 - 测量明细：箱码/箱规、长、宽、高、箱数、体积、设备或人工来源；
 - 重量结果：称重图片、OCR 原值、采用值、毛重/净重、确认状态；
 - 辅助信息：预计托数、测量时间、设备号/事件号、备注和差异原因；
 - 审计字段：创建人、修改人、版本、提交与审核历史。
 客户申报值、设备原始值、OCR 原值、人工修正值和最终计费采用值必须并行保留，不能用最终值覆盖原始证据。
 ### 5.2 设备自动测量
 第三方设备按接口提交入仓码或箱码、长宽高、数量、设备标识和事件号。
 操作要求：
 1. 先在设备端确认扫描的是当前物理箱；
 2. 设备上传后在 Admin 核对是否归入正确入仓单；
 3. 核对尺寸单位、箱数和设备时间；
 4. 重复回调使用同一事件号幂等处理，不生成重复测量；
 5. 设备数据异常时保留原值，另行人工修正，不删除原始记录。
 单次批量测量明细最多 500 条。超过时应按现场批次拆分，而不是截断数据。
 ### 5.3 人工补录尺寸
 适用场景：设备不可用、个别箱复核、非标货或设备数据需要纠正。
 操作步骤：
 1. 点击新增/编辑测量明细；
 2. 选择稳定箱码或填写明确箱规及对应箱数；
 3. 填写长、宽、高，三项都必须大于 0；
 4. 填写测量时间；
 5. 上传必要的测量图片，单个文件不得超过页面限制（当前为 5 MB）；
 6. 写明人工补录或修正原因；
 7. 保存后重新核对明细箱数合计。
 人工补录可以替换可编辑批次中的业务测量项，但不得抹掉同一物理箱已经冻结的扫码身份、设备事件和原始取证。
 ### 5.4 称重图片与 OCR
 操作步骤：
 1. 上传能够清晰看到秤面读数和货物关联的称重图片；
 2. 等待 OCR 返回识别值；
 3. 将 OCR 原值与图片读数比对；
 4. 正确时确认采用；不正确时填写人工修正值和原因；
 5. 确认单位统一换算为系统采用单位；
 6. 将每张有效图片设置为已确认；
 7. 确保最终总重量大于 0。
 即使整票只有 1 箱，也至少需要 1 张已确认重量图片。真实 OCR 凭证未配置或识别失败时，可以保留失败结果后人工确认；这是一条有证据的降级路径，不等于允许无图录重量。
 每张有效重量图片只能计重一次。重复上传、同图重复确认或同一重量被不同图片重复累计时，必须先消除重复再提交。
 ### 5.5 保存前与提交前校验
 点击“保存测量数据”时保存当前可编辑批次；点击“提交审核”前至少检查：
 - 存在至少一条有效测量明细；
 - 所有长宽高、箱数、时间和必要附件合法；
 - 测量明细确认箱数合计等于整票实际确认总箱数；
 - 至少有一张已确认重量图片，全部有效图片均已处理；
 - 最终总重量大于 0；
 - 预计托数为合法正数或满足页面当前规则；
 - 页面没有尚未保存的修改；
 - 当前批次没有被其他人提交或审核；
 - 订单已经审核通过，具备提交审核资格。
 系统尝试依据已确认重量和提交动作建立整票连续库位占用/预留。资源不足等非致命问题应显示明确警告并由仓库处理；不得把警告伪装成已完成物理入库，也不得让位置建议覆盖测量事实。
 ## 6. F10 测量审核与初始计价
 ### 6.1 审核入口
 入口：Admin → 入库管理 → 测量审核。
 审核员按单票或批量打开待审任务，核对：
 - 客户、入仓码、订单号和国内仓；
 - 申报箱数与实际确认箱数差异；
 - 每组箱规的长宽高、数量和体积；
 - 称重图片、OCR 原值、人工采用值和修正原因；
 - 总重量、总体积和预计托数；
 - 客户尺寸规则或价格簿所需维度；
 - 是否存在重复图片、重复箱码、缺失证据或异常备注。
 ### 6.2 审核通过
 点击审核通过后，服务端在同一受控流程中：
 1. 再次校验当前状态、批次版本和证据完整性；
 2. 冻结本次有效测量结果；
 3. 计算或准备初始费用版本；
 4. 普通订单主状态进入 `WAIT_SPLIT`；
 5. 一件代发主状态进入 `WAIT_PALLETIZE`；
 6. 写入审核人、审核时间和状态历史。
 初始计价失败或产生警告时，不应回滚已经合法完成的测量审核，也不能把普通订单从 `WAIT_SPLIT` 拉回旧的计费状态。页面需要明确展示“测量已通过、计价待处理”这两个独立结果。
 批量审核时，每票都必须返回独立结果。部分失败不能让操作员误以为整批全部成功；失败项按入仓码展示原因并保留在待处理列表。
 ### 6.3 审核驳回
 发现数据或证据不合格时填写明确原因并驳回：
 - 驳回原因应说明需要修正的字段或证据；
 - 原测量批次和审核历史保留，不原地覆盖成新记录；
 - 操作员按原因修正允许编辑的数据后重新提交；
 - 历史 `MEASURE_REJECTED` 只作为事实和恢复入口，不代表可以绕过审核直接分柜。
 ### 6.4 异常放行
 异常放行只适用于已驳回测量，且必须同时满足：
 - 环境已开启对应开关；
 - 当前用户具备专项权限；
 - 被放行批次确实处于已驳回状态；
 - 填写非空放行原因；
 - 完整记录操作人、时间、原驳回原因和放行原因。
 异常放行不能变成常规“跳过审核”按钮，也不能补造不存在的称重或测量证据。
 ## 7. F11 费用生成、发布与客户确认
 ### 7.1 费用与主流程的关系
 费用是与主状态并行的业务维度：
 ```text
 测量审核通过 ──→ 主流程：WAIT_SPLIT（普通）/ WAIT_PALLETIZE（一件代发）
       └──────→ 费用：初算 → 人工维护 → 确认/发布 → 客户确认 → 条件满足后冻结
 ```
 因此：
 - 费用未发送不阻止普通订单进入 `WAIT_SPLIT`；
 - 客户未确认费用不把主流程回退；
 - 装柜完成也不能代替客户自动确认费用；
 - 费用的最终冻结需“客户已确认”和“本票已装柜完成”同时成立。
 ### 7.2 系统初算
 入口：Admin → 入库管理 → 费用。
 系统基于已审核测量结果和有效价格簿生成版本化费用，操作员应检查：
 - 计费采用的是哪一组实测重量、体积和计费量；
 - 命中的渠道、目的地区域和价格簿版本；
 - 是否命中客户专属 ACTIVE 价格簿；未命中时才回退公共 ACTIVE 价格簿；
 - 计价模型是重量、体积、仓库费率、区域重量阶梯或其他当前有效模型；
 - 基础费用、附加费、币种、税费或调整项是否完整；
 - 系统警告是否说明缺价格、缺映射或数据不满足模型。
 同柜区域重量阶梯可能在阶段三根据同柜、同客户的最终有效成员聚合后重算；固定模型成员不参与阶梯聚合。此处初算是当前版本事实，不承诺后续永不变化。
 ### 7.3 人工调整
 允许调整时：
 1. 选择当前费用版本；
 2. 查看系统基准量、基准单价和基准金额；
 3. 在服务端允许的范围内修改；当前规则以系统基准量为中心限制上下 10%，含边界；
 4. 填写调整原因；
 5. 完成二次确认；
 6. 保存为新版本，由服务端重新计算金额。
 页面不能只提交最终总额来绕开计费规则。版本、基准、调整值、原因、操作人和时间都要可追溯。
 ### 7.4 平台确认与发送
 操作员确认费用明细无误后执行页面上的确认/发送操作：
 1. 复核客户、入仓码、币种和当前版本；
 2. 确认没有待处理计价警告；
 3. 发布当前费用明细；
 4. 将费用状态置为客户可见的 `SENT`；
 5. 记录发送人、发送时间和版本。
 “发送费用”表示发布当前费用版本供客户查看，不等于已经收款、核销或形成最终财务结算。
 ### 7.5 客户查看和确认
 入口：Client → 头程订单/入库费用。
 客户只有在以下条件同时满足时才能看到费用：
 - 费用属于当前登录客户；
 - 测量已经审核通过；
 - `feeStatus=SENT`；
 - 存在已发布明细。
 客户确认时携带当前 `expectedFeeVersion` 和幂等键。成功后记录确认成员和时间。
 若装柜完成前平台生成并重新发送新版本，旧版本客户确认快照被清空，客户需要确认新版本。旧版本、未发送版本或同一幂等键携带不同参数都必须冲突失败，不能静默覆盖。
 ## 8. F12 国内扣货与解除
 ### 8.1 适用目的
 HOLD 用于在存在费用、资料、风控、货损或其他明确风险时阻断后续物理履约写入。它不是删除订单，也不修改客户和测量事实。
 ### 8.2 发起扣货
 入口：Admin → 统一订单/入库详情 → 扣货。
 操作步骤：
 1. 确认当前入仓单尚未发生不允许回退的实物动作；
 2. 选择或填写扣货原因；
 3. 上传有效凭证；
 4. 核对入仓码、客户和当前版本；
 5. 二次确认后提交；
 6. 查看 HOLD 状态、操作人和时间线是否写入。
 扣货生效后，分柜、拣货、装柜、出仓等后续物理写操作必须由服务端阻断，不能只在前端隐藏按钮。
 ### 8.3 解除扣货
 1. 打开当前有效 HOLD；
 2. 核对风险是否已经消除；
 3. 填写解除原因并补充凭证；
 4. 携带当前版本和幂等键提交；
 5. 系统关闭当前 HOLD，但保留发起与解除历史；
 6. 重新评估主状态允许的下一步动作。
 已经发生拣货、装柜或出仓时，禁止通过手工扣货/解除改变已发生的物理事实。此时应进入对应阶段的异常流程。
 ## 9. F13 一件代发国内清点组托
 ### 9.1 进入条件
 一件代发测量审核通过后不直接进入 `WAIT_SPLIT`，而是：
 - 主状态为 `WAIT_PALLETIZE`；
 - 按预计托数预生成 `DP` 托盘码；
 - 箱码与箱内 SKU 已冻结且可被 PDA 读取；
 - 不创建国内库存；
 - 组托完成后才交给分柜。
 预计托数与实际已生成托盘数不一致时禁止开始作业，应先修正任务或重新生成合法托盘，不允许 PDA 临时造托盘码。
 ### 9.2 Admin 打印托盘信息单
 入口：Admin → 一件代发组托任务。
 1. 打开入仓码对应任务；
 2. 核对预计托数和已生成 `DP` 托盘列表；
 3. 逐托打印 A4 信息单，每托一页；
 4. 核对 Code 128 托盘码、入仓码、总箱数和 SKU 清单；
 5. 将标签贴到对应空托或托盘作业位。
 信息单用于识别和作业，不展示容易过期的实时作业状态。实际状态以 PDA/服务端为准。
 ### 9.3 PDA 逐箱清点与归托
 入口：国内 PDA → 一件代发清点组托。
 允许两种顺序：
 ```text
 先扫托盘 → 连续扫箱并清点 → 确认归托
 先扫箱并清点 → 扫目标托盘 → 确认归托
 ```
 逐箱操作：
 1. 扫描稳定箱码；
 2. PDA 展示整箱 SKU、商品名称和应点数量；
 3. 按完整 SKU 清点实点数量；
 4. 有差异时填写原因并按现场异常规则处理，不能直接改冻结 SKU；
 5. 扫描目标 `DP` 托盘码；
 6. 确认该箱归托；
 7. 继续下一箱，直到本票全部箱处理完成。
 同仓多票在当前规则允许时可以共用一个开放托盘。共托不会改变箱子所属客户、订单、入仓码和 SKU；系统必须保存逐箱归属，不能只保存托盘总数量。
 ### 9.4 封托与解封
 封托前检查：
 - 托盘上所有箱均已完成 SKU 清点；
 - 物理箱数与系统箱数一致；
 - 托盘标签清晰且与 PDA 当前托盘一致；
 - 没有未处理差异或重复归托；
 - 共托场景下各参与任务的数据均完整。
 操作员在 PDA 点击封托。封托后该托成为阶段三的整托候选。
 未进入装柜计划前可按权限和规则解封。共托解封时，所有参与任务和入仓单的相关状态必须同步恢复，不能只恢复其中一票。托盘进入有效装柜计划后不得在本阶段任意解封。
 ### 9.5 组托完成判定
 系统只有在以下条件同时满足时将一件代发入仓单从 `WAIT_PALLETIZE` 推进到 `WAIT_SPLIT`：
 - 本票所有稳定箱码均已清点；
 - 每箱完整 SKU 均已核对；
 - 每箱恰好归属一个有效参与托盘；
 - 本票实际参与的所有托盘均已封托；
 - 没有开放托盘仍包含本票箱子；
 - 箱数、SKU 数量和托盘冻结快照核平。
 预计生成但实际未使用的空托盘不应伪造为已作业托盘；最终事实以实际参与且完成的托盘为准。
 ## 10. 状态机与可用动作
 ### 10.1 主流程状态
 | 当前状态 | 条件/操作 | 下一状态 | 说明 |
 |---|---|---|---|
 | `PENDING_REVIEW` | 可提前采集测量 | 不变 | 不能审核测量、计价或分柜 |
 | `WAIT_MEASURE` | 保存测量 | 不变 | 可反复保存未提交批次 |
 | `WAIT_MEASURE` | 提交测量审核 | 不变/待审维度变化 | 已提交批次冻结 |
 | `WAIT_MEASURE` | 审核驳回 | 驳回事实 | 修正后重新提交 |
 | `WAIT_MEASURE` | 普通订单审核通过 | `WAIT_SPLIT` | 费用并行处理 |
 | `WAIT_MEASURE` | 一件代发审核通过 | `WAIT_PALLETIZE` | 必须先完成清点组托 |
 | `WAIT_PALLETIZE` | 全部箱和实际托盘完成 | `WAIT_SPLIT` | 不创建国内库存 |
 | `WAIT_SPLIT` | 合法解封导致组托不再完整 | `WAIT_PALLETIZE` | 仅限未进入装柜计划等允许条件 |
 测量批次状态、审核状态、费用状态、HOLD 状态和托盘状态是独立维度，不能把它们拼成一条虚假的单状态流水线。
 ### 10.2 费用状态关键约束
 | 费用事实 | 平台可修改 | 客户可见/确认 | 最终冻结 |
 |---|---|---|---|
 | 未生成/初算警告 | 是 | 否 | 否 |
 | 已生成、未发送 | 是 | 否 | 否 |
 | `SENT`、客户未确认 | 是，可生成新版本 | 可见、可确认 | 否 |
 | 客户已确认、尚未装柜完成 | 仍可按规则生成新版本并重新发送 | 新版本需重新确认 | 否 |
 | 客户已确认且装柜完成 | 否 | 已确认 | 是 |
 ### 10.3 HOLD 的正交关系
 HOLD 不必改变主状态文字，但会阻断后续物理履约动作。解除后继续从原主状态判断下一步，不自动跳过测量、组托或分柜条件。
 ## 11. 数据归属与流转
 ### 11.1 关键数据所有者
 | 数据 | 权威系统 | 下游消费者 |
 |---|---|---|
 | 客户申报、订单交易状态 | Order | Firstleg、页面查询 |
 | 入库单、入仓码映射 | Firstleg | Admin、设备、PDA、后续装柜 |
 | 稳定箱码、箱内 SKU | Firstleg | 测量、PDA、装柜事件、尾程 |
 | 公共仓库、库位、托盘资源 | Warehouse | Firstleg 作业引用 |
 | 测量原始值、人工采用值、证据 | Firstleg | 计价、审核、后续审计 |
 | 费用来源和版本 | Firstleg | Client、Finance |
 | 应收应付、收付款、核销 | Finance | 财务终端与对账 |
 | 文件对象 | File | 各业务通过合法文件引用使用 |
 ### 11.2 数据流
 ```text
 Order 审核快照
   ↓
 Firstleg 正式入库单 + 稳定箱码
   ↓
 设备/人工尺寸 + 称重图片/OCR + 人工确认
   ↓
 测量审核冻结 ──────────────→ 主流程 WAIT_SPLIT / WAIT_PALLETIZE
   ├→ 初始费用版本 → 平台维护/发送 → 客户确认 → Finance 来源
   ├→ 仓位连续占用/预留尝试 → Warehouse 资源
   └→ 一件代发 PDA 逐箱清点 → DP 托盘冻结 → WAIT_SPLIT
 ```
 ### 11.3 必须保留的快照和历史
 - 原始客户申报与最终实测同时存在；
 - 设备事件号、设备原值、人工修正值和原因；
 - 原始称重图片、OCR 原值、采用值和确认人；
 - 每次测量提交、驳回、通过和异常放行；
 - 每个费用版本、价格簿来源、系统基准、人工调整和客户确认；
 - 每次 HOLD 发起、证据、解除和版本；
 - 一件代发每箱 SKU 实点、归托、封托和解封历史。
 ## 12. 正常分支、异常与恢复
 | 场景 | 系统行为 | 操作员处理 |
 |---|---|---|
 | 订单未审核但货先到 | 允许按当前规则采集，禁止审核/计价/分柜 | 保留测量草稿，等待订单审核 |
 | 查不到入仓码 | 不创建临时正式入库单 | 隔离货物，核对订单提交/审核结果 |
 | 箱码破损 | 原身份仍有效 | 核验后补打相同箱码 |
 | 设备重复上报 | 按事件号幂等，不重复计量 | 核对已有记录，不换事件号盲重试 |
 | 设备值异常 | 原值保留 | 人工复测并写修正原因 |
 | OCR 失败 | 失败结果和图片保留 | 人工读取、录入并确认 |
 | 重量图片重复 | 禁止重复计重 | 删除/作废重复采用关系后重算 |
 | 明细箱数不等于实收总箱数 | 禁止提交 | 查找漏测、重复测量或到货差异 |
 | 预计托数无效 | 禁止提交或组托 | 仓库重新评估并保存 |
 | 页面有未保存修改 | 禁止提交审核 | 先保存再提交 |
 | 测量被并发提交 | 版本冲突 | 刷新后查看权威结果 |
 | 审核通过但计价失败 | 主状态按审核结果推进，费用显示待处理 | 修复价格簿/映射后重算，不回退测量 |
 | 费用版本过期 | 客户确认冲突 | 刷新并确认当前已发送版本 |
 | HOLD 生效 | 后续实物写入失败关闭 | 处理风险后按证据解除 |
 | 一件代发箱内 SKU 不符 | 不直接改冻结清单 | 记录差异并由有权流程纠正来源 |
 | 开放共托仍含本票箱子 | 本票不能完成组托 | 完成或按规则拆解参与托盘 |
 | 封托后需调整 | 仅未进入装柜计划时可解封 | 有权解封、修正、重新封托 |
 | PDA 请求超时 | 不确定是否成功 | 先查询箱/托当前状态，再用原幂等语义处理 |
 ## 13. 阶段完成判定
 ### 13.1 普通订单
 - [ ] 入仓码、订单、客户和国内仓对应正确
 - [ ] 稳定箱码和实收箱数可追溯
 - [ ] 测量明细箱数与实际确认总箱数一致
 - [ ] 尺寸、重量、图片和人工修正证据完整
 - [ ] 至少一张重量图片已确认且总重量大于 0
 - [ ] 测量批次已审核通过并冻结
 - [ ] 主状态为 `WAIT_SPLIT`
 - [ ] 初始费用已生成，或计价警告已作为独立待办暴露
 - [ ] 若存在 HOLD，下一阶段明确知道当前不可继续物理履约
 - [ ] 重复提交和重复审核不会产生重复事实
 ### 13.2 一件代发订单
 除普通测量条件外，还必须满足：
 - [ ] 每个物理箱和完整 SKU 来源可追溯
 - [ ] 每箱均已完成 SKU 清点
 - [ ] 每箱恰好归属一个实际参与托盘
 - [ ] 所有实际参与托盘均已封托
 - [ ] 共托参与关系和逐箱归属完整
 - [ ] 最终托盘冻结快照存在
 - [ ] 主状态已从 `WAIT_PALLETIZE` 进入 `WAIT_SPLIT`
 - [ ] 未因组托创建国内库存
 费用是否已经发送、客户是否已经确认，不作为本阶段主流程交接到阶段三的硬门槛；但必须作为并行待办清晰展示和持续跟踪。
 ## 14. 易用性与数据流评审问题
 以下问题先记录，后续优化阶段逐项决策：
 1. 到仓页是否需要独立的“实收登记”动作和时间戳，还是继续由首次合法测量/扫码体现到仓？
 2. 订单未审核时允许提前测量，页面应如何醒目标识“仅采集、不可审核”，避免仓库误判流程已放行？
 3. 箱数差异是否需要结构化的少箱、多箱、破损和错货原因，而不是仅填备注？
 4. 真实 OCR 供应商凭证、现场秤图片式样和识别准确率应由谁验收？
 5. 连续库位预留失败目前作为警告时，仓库如何看到并闭环处理，是否需要独立待办？
 6. “发送费用”是否应改名为“发布给客户”，以避免被误解为发送账单或已完成结算？
 7. 计价失败但主流程已进入 `WAIT_SPLIT` 时，是否需要跨页面的费用红点、责任人和超时提醒？
 8. HOLD 的发起责任、审批规则、证据类型和解除责任是否已经形成可审计 SOP？
 9. 一件代发允许跨订单共托时，业务是否确认允许跨客户；若允许，拆托、异常和费用责任如何分摊？
 10. PDA 清点发现 SKU 差异时，目前应走哪个权威纠错入口，谁能修改冻结来源并触发重新打印？
 11. 预计托数与实际托数变化时，是否需要保留预测偏差指标，为仓容和装柜优化提供数据？
 12. 客户费用确认与装柜完成共同冻结的规则，页面是否充分解释“已确认但尚未冻结”。
 ## 15. 阶段三交接包
 交给阶段三“模拟柜、排柜、订舱、拖车、预装、装柜与出仓”的权威输入包括：
 - 入仓单、订单号、入仓码、客户和国内仓；
 - 渠道、目的类型、目的仓/地址快照；
 - 已审核的最终箱数、重量、体积和箱规；
 - 稳定箱码及必要的箱内 SKU 关系；
 - 普通订单预计托数和库位占用/预留结果；
 - 一件代发实际封托的 `DP` 托盘、逐箱归属和 SKU 冻结快照；
 - 当前主状态 `WAIT_SPLIT`；
 - 当前有效 HOLD 及阻断原因；
 - 费用当前版本、发布/客户确认状态和未处理计价警告。
 阶段三可以基于最终装柜成员重算尚未冻结的费用，但不得覆盖本阶段的原始测量、证据或一件代发逐箱组托事实。
 ## 16. 事实来源
 - `docs/归档/头程到尾程/头程下单到尾程出库现状流程全景清单.md`
 - `docs/入库测量与计费/README.md`
 - `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
 - `docs/统一订单主状态与操作契约.md`
 - `apps/admin-web/AGENTS.md`
 - `apps/admin-web/src/modules/inbounds/measurement/InboundMeasurementDialog.vue`
 - `apps/admin-web/src/modules/inbounds/measurement/InboundMeasurementPanel.vue`
 - `apps/admin-web/src/modules/inbounds/fee/InboundFeePanel.vue`
 - `apps/admin-web/src/modules/inbounds/components/InboundWorkflowWorkspace.vue`
 - `apps/admin-web/src/modules/inbounds/components/InboundTaskList.vue`
 - `baiyue-firstleg/firstleg/AGENTS.md`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/InboundMeasurementService.java`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/MeasurementReviewService.java`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/InitialInboundPricingService.java`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/DropshipPalletizationService.java`
 - `baiyue-firstleg/firstleg/src/main/resources/openapi/dropship-palletization-v1.yaml`
@@ -0,0 +1,407 @@
 # 阶段五：海外接柜、库存与库内服务
 > 对应全景流程：F28～F33。  
 > 阶段起点：实际船节点达到 `PICKUP_READY`，整柜尾程计划和海外托盘/库位资源已经就绪。  
 > 主链终点：整柜收货完成，库存同事务入账，尾程主状态为 `INBOUND_COMPLETED`。  
 > 并行范围：库存查询、托盘作业、暂扣、换标、仓储转运和货物废弃。
 ## 1. 阶段目标和边界
 本阶段把海运在途货物转化为海外仓可核对库存：
 1. 海外 PDA 操作员按真实柜号认领待卸货柜；
 2. 核对国内装柜证据并拍摄海外签收三类照片；
 3. 按 FBA 散货、OVERSEAS 逐箱和一件代发整托三种模式实收；
 4. 整柜核平后一次完成计划、任务、库存和卸柜事件；
 5. 提供库存、位置、流水、托盘以及已开放的库内作业；
 6. 对单票执行暂扣/解除；
 7. 处理换标、仓储转运和一件代发货物废弃。
 本阶段不负责海外配送排车、出库发车和最终派送。入仓完成只是后续履约资格之一；有效暂扣、换标未完成或库存被其他子单锁定时仍不能出库。
 ## 2. 角色、终端和权限
 | 角色 | 终端 | 主要操作 | 边界 |
 |---|---|---|---|
 | 海外仓 PDA 操作员 | 海外 PDA | 认领柜、拍照签收、实收、完成整柜、库内作业 | 需 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 和 `lastleg:pda:operate`，仓库由 Token 固定 |
 | 海外仓主管 | Admin | 查询入仓、库存、托盘、异常，处理授权的库存/暂扣操作 | 不用内部 ID 修改他仓资源 |
 | 企业操作员 | Client | 查看本企业库存，发起换标、转运、废弃等自助服务 | 不查看其他客户或直接改实物托盘 |
 | 换标作业员 | 海外 PDA | 认领、扫描旧/新标、拍照、提交复核 | 不自行批准复核或客户确认 |
 | 换标复核员 | Admin | 退回返工、核对作业事实 | 已由客户确认后不能退回 |
 | 废弃审核员 | Admin/PDA | 审批一件代发废弃并触发实际扣减 | 创建申请时不得直接扣库存 |
 | Lastleg | 后端 | 入仓作业、库存业务、子单、状态和事件权威 | 不拥有物理仓/托盘主档 |
 | Warehouse Overseas | 后端 | 海外库位、实物托盘、资源锁和物理状态 | 不拥有库存客户归属和尾程订单 |
 平台管理员和普通客户账号不能进入海外 PDA 柜号签收入口。PDA 请求不接收 `customerId` 或可切换的 `warehouseId`；客户和仓库范围由柜内计划、入仓码和登录 Token 解析。
 ## 3. 作业前检查
 - 操作员账号已绑定唯一 `ACTIVE + OVERSEAS + RECEIVING` 海外仓；
 - 换仓或清空绑定后旧 Token 已失效；
 - 实际节点达到 `PICKUP_READY` 或更晚；
 - 柜内每票订单为 `INBOUND_PLANNED`；
 - 所有计划已经绑定真实托盘、库位和资源锁；
 - `resourcePendingPlanCount=0`；
 - 真实柜号、来源柜聚合键、预计到仓和入仓码完整；
 - 普通货计划箱数、一件代发来源托盘/SKU/箱唛快照可核对；
 - PDA 网络、相机和扫码能力正常。
 只要任一计划仍缺真实资源，就不能准备、签收或开始该柜。PDA 首次扫码只确认计划阶段已预留资源，不在现场重新分配托盘或库位。
 ## 4. F28 海外 PDA 柜号签收
 ### 4.1 查看待卸货柜
 入口：海外 PDA → 拆柜收货。
 候选按物理柜跨客户聚合，仅返回达到 `PICKUP_READY` 且计划资源完整的柜。列表使用真实集装箱号、预计到仓和接柜仓，不显示内部柜次 ID。
 操作员选择柜后：
 1. 系统按平台账号和柜号创建/恢复唯一未完成会话；
 2. 柜被原子认领到当前 Token 固定仓库；
 3. PDA 锁定当前柜，不允许随意切换；
 4. 展开查看柜内全部入仓码、客户隔离任务、目的仓、计划托数和箱数；
 5. 核对当前仓库与现场一致。
 柜级认领允许同柜多客户，但后续每票任务、扫码、库存和流水仍使用入仓码所属的真实客户。
 ### 4.2 查看国内装柜照片
 签收前展开国内五类只读证据：空柜、装载过程、接近完成、满柜/关门前、带铅封号照片。
 - 证据仅用于现场对照，不允许 PDA 修改；
 - 单张图片加载失败时提供重试；
 - 单图失败不阻断拆柜，但应保留加载异常；
 - 现场发现柜号、铅封或外观明显不符时，应先走异常处理而不是盲目签收。
 ### 4.3 拍摄三类签收照片
 依次现场拍摄并上传：
 1. `LICENSE_PLATE`：承运车辆车牌；
 2. `CONTAINER_SEAL`：开封前柜门和铅封；
 3. `DOOR_OPEN`：开柜现场。
 每类固定一张当前有效照片，允许在上传成功后更换。更换失败保留原照片；预览走鉴权下载，不持久化设备临时路径。三类照片全部齐全后才能确认签收。
 ### 4.4 确认签收
 点击确认后，服务端复核柜号、仓库、会话、照片和版本，记录签收人和时间并进入收货。首次开始收货的 `receiving_at` 是整柜唯一实际到仓时间，回传 Admin 清关提柜列表；不能用预约或预计时间代替。
 ## 5. F29 三类实收操作
 ### 5.1 通用规则
 每次实收都必须：
 - 使用当前柜会话；
 - 由业务箱码、入仓码或来源托盘定位唯一计划；
 - 扫描计划已绑定的实物托盘码；
 - 使用稳定幂等键和当前版本；
 - 不超过该计划待收数量；
 - 写入当前客户、仓库、目的仓和库存来源；
 - 返回最新已收、待收和异常信息。
 `assigned/mergeAllowed/urgent/mergeHint` 只消费服务端结果。可合托只是现场选择，不改变收货资格，也不是整柜完成门禁。
 ### 5.2 FBA 散货批量收货
 1. 在柜内选择目标入仓码/目的仓分组；
 2. 扫描冻结 SKU 或用于定位分组的业务码；
 3. 扫描计划绑定的实物托盘码；
 4. 输入本次放入托盘的箱数；
 5. 核对本次、累计和剩余箱数；
 6. 提交 bulk 收货；
 7. 继续下一托或下一入仓码。
 FBA bulk 不提交 `skuCode` 作为库存归属，服务端按计划明细分配。首次扫业务码只选择分组，不自动多收一箱。超收返回冲突且库存不变化。
 ### 5.3 OVERSEAS 逐箱收货
 1. 扫描国内最终实装的稳定箱唛；
 2. 服务端自动解析唯一入仓码和计划；
 3. 扫描目标实物托盘；
 4. 核对箱码、目的模式和托盘兼容性；
 5. 确认单箱收货；
 6. 已收箱再次扫描必须冲突，不重复入账。
 OVERSEAS 必须使用跨区冻结的逐箱事实，禁止改为手工输入批量箱数。
 ### 5.4 一件代发整托收货
 1. 选择柜内一件代发计划；
 2. 扫描国内冻结的来源 `DP` 托盘码；
 3. 查看该托盘所属入仓码、箱数、SKU 和箱唛；
 4. 扫描海外计划绑定的实物托盘；
 5. 使用 `/current/receipts/pallet` 整托确认；
 6. 服务端按来源托盘原子核平全部箱件和 SKU。
 禁止逐箱拆收、改写国内托盘成员或按商品名称猜配。一个国内来源托盘失败时整托不落账。
 ### 5.5 独立收货与合托
 - 独立收货：扫描计划分配的新托盘；
 - 合托：仅在 `mergeAllowed=true` 时，扫描同目的仓已使用托盘；
 - 合托后同一实物托盘可以包含多张入仓单，但每票组成数量独立保存；
 - 单票全部收完不要求因“可合托”再执行一次合托动作。
 ## 6. F30 整柜完成、库存入账与国内回写
 ### 6.1 完成前检查
 点击完成整柜前核对：
 - 柜内所有计划 `pendingPackages=0`；
 - FBA 汇总数量、OVERSEAS 箱码和一件代发来源托盘均核平；
 - 每个库存组成已绑定真实托盘和库位；
 - 三类签收照片存在；
 - 通过 `/unload-photos` 保存了非空且不重复的卸柜照片文件 ID；
 - 没有结果不确定的在途命令或版本冲突。
 ### 6.2 原子完成
 服务端在同一事务内：
 1. 完成每票 PDA 任务和入仓计划；
 2. 将尾程主状态推进为 `INBOUND_COMPLETED`；
 3. 将 `FIRST_LEG` 在途数量转为海外仓可用/对应状态库存；
 4. 写库存余额；
 5. 写按托盘和入仓单拆分的库存位置；
 6. 写进销存流水和实收快照；
 7. 更新托盘组成；
 8. 创建唯一 `OVERSEAS_CONTAINER_UNLOADED` V1 Outbox。
 任一步失败时不能只完成状态、不入库存，或只入库存、不完成任务。相同完成请求重放返回既有结果，不重复增加库存。
 ### 6.3 国内回写
 事件绑定来源头程柜次身份，由服务端冻结，不接受 PDA 拼装。Firstleg 消费后：
 - 记录卸柜完成时间；
 - 记录照片上传/完成事实；
 - 计算预计还空时间；正式业务以卸柜完成后 72 小时为准；
 - 更新目的港码头拖车的还空预警；
 - 以事件 ID、哈希和聚合版本防重与防乱序。
 此事件不代表已经还柜；实际还柜另行推进 `EMPTY_RETURNED`。
 ## 7. F31 库存、盘点、移库和托盘
 ### 7.1 Admin 库存查询
 入口：Admin → 海外仓 → 库存管理。
 核对维度：客户、实际海外仓、目的仓、入仓单、可用/冻结/占用箱数、SKU 展示、实物托盘和库位。余额唯一业务维度不以托盘为归属；多 SKU 可显示 `MIXED`，完整 SKU 保存在箱唛、实收和流水快照。
 列表、详情、汇总和 CSV 必须使用同一权限范围，并默认排除所有数量桶均为零的维度。
 ### 7.2 托盘与位置
 入口：Admin → 海外仓 → 托盘管理。
 - 实物托盘和库位是平台公共资源，`customer_id=0`；
 - 资源锁保存真实业务客户范围；
 - 同一托盘可包含多票，每票箱数保存在库存位置组成；
 - 托盘是 PDA 出库作业单位，不是库存所有权单位；
 - 普通入仓只证明某票有多少箱在该托盘，不证明每个箱唛精确位于哪个托盘；
 - 标签只按真实托盘编码补打，不重新生成编号。
 ### 7.3 PDA 现场查询
 入口：海外 PDA → 库存/库位/托盘查询。
 扫描稳定业务码后查看服务端最新事实，只展示箱码、托盘码、库位码、仓库名称等业务标识，不以内建 ID 回退。
 ### 7.4 商品移库
 入口：海外 PDA → 商品移库。
 1. 扫描来源托盘；
 2. 查看组成和当前版本；
 3. 扫描同仓目标库位；
 4. 核对目标可用；
 5. 提交整托移库；
 6. 服务端原子释放源真实库位并占用目标库位；
 7. 409 冲突后重新扫描，不能用旧版本重试覆盖。
 虚拟库位保持 `ACTIVE`；真实库位与托盘同步 `IDLE/OCCUPIED`。
 ### 7.5 托盘组、拆、换、解绑
 PDA 扫描托盘后按服务端返回的 `palletVersion`、`positionVersion` 执行。每次操作必须核对库存组成并使用稳定幂等键；跨服务业务失败走显式补偿，Lastleg 不直接修改 Warehouse Overseas 的 `wh_` 表。
 ### 7.6 库存盘点
 盘点底层支持创建、恢复、计数、提交、幂等和版本冲突处理；当前海外 PDA 工作台不开放入口，因此不能宣称已完成现场页面验收。需要盘点时以正式开放入口、权限 `lastleg:inventory:adjust` 和最终库存流水为准。
 ## 8. F32 暂扣与解除
 ### 8.1 新增暂扣
 只允许尾程订单已经 `INBOUND_COMPLETED` 且尚未进入出库流程时新增：
 1. Admin 打开尾程订单；
 2. 核对当前库存和后续占用；
 3. 填写暂扣原因和必要凭证；
 4. 携带订单版本和幂等键提交；
 5. 写不可变历史并发布暂扣事件。
 暂扣只作用于本票，阻断该票排车和出库；不影响同柜其他客户/订单，也不回退入仓计划、实收、库存或主状态。
 ### 8.2 解除暂扣
 风险解除后填写原因并提交当前版本。解除不受“尚未进入出库”这一新增条件限制，但不能抹掉已发生的历史或释放其他子单仍合法持有的库存锁。
 ## 9. F33 换标、仓储转运和废弃
 ### 9.1 换标申请
 入口：Client → 海外仓服务 → 换标。
 1. 客户从本企业可用库存选择目标箱/数量；
 2. 选择换标类型：SKU、箱唛或混合；
 3. 填写旧标、新标和数量；
 4. 提交后系统冻结对应库存，防止重复申请和出库占用；
 5. 生成换标子单，精确状态保存在子单和 `sub_order_status`。
 普通入仓没有逐箱唛到托盘的精确快照时，客户填写的我方箱唛是换标作业主键；库存位置只是冻结记账锚点和现场大概位置，不能据此声称箱唛一定在某托。
 ### 9.2 PDA 换标作业
 入口：海外 PDA → 换标收货/执行。
 1. 认领任务并进入处理中；
 2. SKU 类型逐条核对旧 SKU、新 SKU 和批准件数；
 3. 箱唛类型扫描仓库唛头和新 FBA 箱唛；
 4. 混合类型分别完成 `MIXED_CARTON`、`MIXED_SKU`，两项齐全才计一箱完成；
 5. 拍摄并上传作业照片；
 6. 必要时按实际来源拆托、换托并记录 `PALLET_BIND`；
 7. 提交后任务进入 `WAIT_REVIEW`，申请进入 `CUSTOMER_CONFIRM_PENDING`。
 换标移动只能移动本申请 `hold_packages`，不得解冻为普通可用库存。已生成出库单或开始拣货后禁止随意改绑。
 ### 9.3 返工与客户确认
 平台复核发现问题时，使用专用返工接口携带任务版本、幂等键和必填备注退回。上一轮事实和照片归档，当前轮计数清零；客户已确认后不能退回。
 客户核对结果后确认，服务端原子完成复核并释放后续资格。换标主流程相关单据进入 `WAIT_OUTBOUND`；客户确认前不得出库。
 ### 9.4 仓储转运
 入口：Client → 海外仓服务 → 仓储转运。
 1. 客户选择本企业可用库存和目标仓/运输要求；
 2. 提交转运申请；
 3. 平台审核通过或驳回；
 4. 通过后冻结对应库存并进入转运出库；
 5. 实际移出和目标收货按转运单、库存流水和资源操作闭环。
 转运状态保存在子单，不覆盖尾程主状态 `INBOUND_COMPLETED`。
 ### 9.5 一件代发货物废弃
 废弃只使用能够核对 SKU 和箱唛的一件代发库存：
 1. 客户选择箱唛并创建申请；
 2. 箱从 `AVAILABLE` 锁定为 `DISCARD_PENDING`，此时不扣 SKU 箱数；
 3. 有 `lastleg:cargo-discard:approve` 权限的仓库/PDA 人员现场审核；
 4. 拒绝时只释放锁，不扣库存；
 5. 通过时在同一事务调用专用 discard adjustment；
 6. 箱进入 `DISCARDED`，写逐箱流水和唯一幂等键；
 7. 校验扣减前箱数减废弃箱数等于扣减后箱数，且逐箱合计等于申请总数；
 8. 任一失败整体回滚。
 ## 10. 状态与数据归属
 | 维度 | 关键状态 | 说明 |
 |---|---|---|
 | 柜级收货会话 | 待签收/收货中/完成 | 绑定平台账号、柜和实际仓 |
 | 入仓计划/PDA 任务 | 已计划→作业中→完成 | 每票按真实客户隔离 |
 | 尾程主状态 | `INBOUND_PLANNED → INBOUND_COMPLETED` | 子单不能覆盖 |
 | 库存 | `FIRST_LEG` 在途→海外仓库存各数量桶 | 入账必须与状态同事务 |
 | 暂扣 | 有效/解除 | 正交阻断排车出库 |
 | 换标/转运/废弃 | 各自子状态 | 汇总到 `sub_order_status` |
 | 物理资源 | 托盘、库位、锁和版本 | Warehouse Overseas 权威 |
 ## 11. 异常与恢复
 | 场景 | 处理方式 |
 |---|---|
 | `PICKUP_READY` 前看不到柜 | 等待真实节点，不手工绕过候选门禁 |
 | 操作员仓库绑定错误 | 重新绑定并重新登录，旧 Token 失效 |
 | 三类照片上传失败 | 保留旧图/现场重试，不伪造签收 |
 | FBA 超收 | 冲突且库存不变，核对累计/剩余数 |
 | OVERSEAS 重复箱码 | 冲突且不重复入账 |
 | 一件代发来源托盘不符 | 整托拒绝，核对国内冻结快照 |
 | 实收命令超时 | 查询当前实收记录，复用原幂等键 |
 | 任一计划未清零 | 禁止完成整柜，定位具体入仓码 |
 | 完成事务失败 | 状态和库存整体回滚后重试原命令 |
 | 移库/托盘版本冲突 | 重新扫描获取最新版本 |
 | 暂扣票参与排车 | 服务端拒绝，先按权限解除 |
 | 换标一项未完成 | 混合单不计整箱完成 |
 | 换标被退回 | 展示备注，清理设备草稿后按新轮返工 |
 | 废弃审批失败 | 锁定和扣减整体回滚，不产生半套流水 |
 ## 12. 阶段完成判定
 测试环境综合证据 `baiyue-firstleg/reports/admin-full-postdeploy-66c2651b.json` 已覆盖海外 PDA、收货、库存、库内服务和 `phase5-overseas-fulfillment`；上述模块失败数均为 0。这里的清单继续保留为逐票验收条件，不能用综合报告替代具体柜次的业务核对。
 主链完成必须满足：
 - [ ] 柜号由正确仓库操作员认领
 - [ ] 国内五类证据可对照，海外三类签收照片齐全
 - [ ] 实际到仓时间来自首次收货会话
 - [ ] FBA、OVERSEAS、一件代发均按对应模式实收
 - [ ] 每票 `pendingPackages=0`
 - [ ] 库存余额、位置、流水和托盘组成数量一致
 - [ ] 入仓计划和 PDA 任务完成
 - [ ] 尾程主状态为 `INBOUND_COMPLETED`
 - [ ] 卸柜 Outbox 唯一且国内幂等回写成功或可重试
 - [ ] 重放任何实收/完成命令不会重复库存
 库内服务完成以各子单独立判断；它们不改变已经成立的 `INBOUND_COMPLETED`，但未完成的冻结、暂扣或占用必须继续阻断阶段六相应库存。
 ## 13. 易用性与数据流评审问题
 1. 柜级认领前是否需要把计划/资源缺口直接展示为可操作诊断？
 2. 国内五类照片与海外三类照片是否应提供左右对照和异常快捷登记？
 3. 三类收货模式是否需要在页面用颜色/图标强提示，防止操作员走错批量或逐箱入口？
 4. FBA 首次扫码只选分组、不计数的规则是否足够直观？
 5. 合托提示是否应同时展示托盘已有客户、入仓单组成和容量风险？
 6. 整柜完成前是否需要按入仓码显示“剩余几箱/哪几个来源托盘”？
 7. 卸柜完成后 72 小时还空预警应由谁接收、何时升级？
 8. 库存余额、库存位置、托盘组成和箱唛明细是否需要统一钻取入口？
 9. 当前盘点入口隐藏，正式业务发生账实差异时由哪个可见流程处理？
 10. 暂扣原因、换标冻结、转运占用和废弃锁箱是否应统一显示“不可用数量来源”？
 11. 换标混合任务双 Tab 的完成条件是否需要总进度和缺项提示？
 12. 废弃从“申请锁定”到“现场实际扣减”的状态文案是否足够清楚？
 ## 14. 阶段六交接包
 交给阶段六“海外排车、出库、派送与回写”的输入包括：
 - `INBOUND_COMPLETED` 尾程订单和实际海外仓；
 - 客户、入仓单、目的仓和可用库存余额；
 - 每个实物托盘的多票组成、库位和版本；
 - 一件代发来源托盘、SKU 和箱唛可用状态；
 - 有效暂扣、换标、转运、废弃及其他库存锁；
 - 可出库数量、已占用数量和相应库存流水；
 - 客户/平台要求的派送地址、FBA 仓和服务属性。
 ## 15. 事实来源
 - `docs/海外仓业务/README.md`
 - `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
 - `apps/pda-overseas-uniapp/AGENTS.md`
 - `apps/pda-overseas-uniapp/src/pages/operation/operation.vue`
 - `apps/pda-overseas-uniapp/src/pages/pallet/pallet.vue`
 - `apps/pda-overseas-uniapp/src/pages/move/move.vue`
 - `apps/pda-overseas-uniapp/src/pages/relabel/relabel.vue`
 - `baiyue-firstleg/lastleg-service/AGENTS.md`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/pda/`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/relabel/`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/transfer/`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/discard/`
 - `baiyue-firstleg/warehouse-overseas-service/AGENTS.md`
@@ -0,0 +1,312 @@
 # 阶段六：海外排车、出库、派送与最终回写
 > 对应全景流程：F34～F40。  
 > 阶段起点：尾程订单已经 `INBOUND_COMPLETED`，存在可用库存且没有阻断本次履约的暂扣或库存锁。  
 > 阶段终点：派送完成并带签收证据，跨区回写国内；对应国内入库单为 `DELIVERED`，同一 Order 全部有效入库单完成后 Order 为 `COMPLETED`。  
 > 出库、排车、派送和异常是独立子状态，不覆盖尾程主状态。
 ## 1. 阶段目标和边界
 本阶段完成海外仓最后一段实物与数据闭环：
 1. 从真实库存生成智能预排和正式排车；
 2. 发车前将排车转换为车辆级出库单和按目的地拆分的派送单；
 3. PDA 按托盘拣货、扣减库存并在满足组合门禁后发车；
 4. 执行一件代发、换标、转运、退货等独立出库任务；
 5. 上传签收资料并自动完成派送；
 6. 对派送异常执行来源受控的退回入仓；
 7. 保存客户回访并将完成事实回写国内订单。
 “扫码拣货”“出库”“发车”“开始派送”“签收完成”是不同节点。库存只在成功的 PDA 拣货/出库事务按契约扣减，发车不能再次扣库存。
 ## 2. 角色和终端
 | 角色 | 终端 | 主要操作 |
 |---|---|---|
 | 海外调度 | Admin | 智能预排、排车编辑/取消、转派送、维护车辆与预约 |
 | 海外仓 PDA 操作员 | 海外 PDA | 排车拣货、独立出库拣货、完成任务、发车 |
 | 派送运营 | Admin | 开始派送、维护允许状态、上传 BOL/签收资料 |
 | 企业成员 | Client | 查看本企业派送单、状态和允许下载的签收资料 |
 | 异常处理员 | Admin | 创建异常、选择原出库事实、处理退回入仓 |
 | 客服 | Admin | 客户回访、记录结果和附件 |
 | Lastleg | 后端 | 排车、出库、派送、异常、库存命令和完成 Outbox 权威 |
 | Firstleg/Order | 国内后端 | 幂等消费完成事件，推进 `DELIVERED/COMPLETED` |
 PDA 只调用 `/api/pda/**` 专用接口，客户和仓库由 Token、Gateway 和服务端解析；派送与客户回访由 Admin/Client 承载，不进入 PDA。
 ## 3. 出库资格前置检查
 - 尾程订单已 `INBOUND_COMPLETED`；
 - 实际海外仓、目的仓和客户归属明确；
 - 库存余额、位置、托盘组成和可用箱数一致；
 - 无有效暂扣；
 - 换标需要客户确认的，已完成确认；
 - 转运、退货或废弃的库存锁与本次出库不冲突；
 - 一件代发箱唛/SKU 状态为可用；
 - 实物托盘和库位版本仍有效；
 - 车辆、车队和目的地使用有效主数据。
 任何不确定的库存、锁或归属查询都应失败关闭，不能通过前端勾选强行出库。
 ## 4. F34 智能预排和排车维护
 ### 4.1 候选和草稿锁
 入口：Admin → 海外仓 → 排车管理/智能预排。
 候选来自真实入仓计划、已收托盘或具备资格的换标库存。平台可跨客户查看候选，但创建时服务端从所选托盘解析并校验唯一客户范围和唯一海外仓。
 1. 创建随机草稿；
 2. 搜索并选择托盘；
 3. 托盘加入草稿时立即按操作人和草稿标识加锁；
 4. 移除托盘或关闭草稿时释放；
 5. 草稿超时后锁自动失效；
 6. 其他草稿/正式排车不能重复占用同一库存。
 ### 4.2 预排创建
 1. 选择车型；
 2. 核对托位、箱数、重量、目的 FBA 仓或私人地址；
 3. 查看服务端汇总路线；
 4. 点击预排；
 5. 服务端重查托盘、库存、锁和客户范围；
 6. 草稿锁原子转换为正式排车锁；
 7. 生成排车单，初始为 `PENDING_DEPARTURE`。
 路线由已排托盘目的仓编码去重并稳定排序生成，预排和普通编辑都不接收人工路线文本。
 ### 4.3 排车编辑和取消
 可维护：车牌、司机、电话、车队、预计发车/到达、FBA 预约和车辆预约。普通编辑不能修改排车状态。
 未执行、未产生不可逆拣货事实的排车可取消并释放正式锁。开始拣货后不能用取消恢复库存或抹掉作业历史。
 ## 5. F35 排车转派送
 允许状态：`PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART`，且必须早于发车。
 入口：Admin → 排车详情 → 转派送。
 1. 填写预计派送时间；
 2. 选择派送方式、提货/装车类型；
 3. 选择车队/快递、车辆和预约；
 4. 维护费用来源和必要备注；
 5. 核对所有托盘都已经真实入仓且仍由本排车锁定；
 6. 二次确认后提交。
 服务端幂等生成：
 - 一张车辆级 `WAIT_OUTBOUND` 出库单；
 - 按目的 FBA 仓或私人地址拆分的一张或多张 `WAIT_DELIVERY` 派送单；
 - 派送费用只发布一次；
 - BOL 和签收资料绑定拆分后的单仓派送单。
 相同排车重放返回既有单据，不重复生成出库、派送或费用。
 ## 6. F36 排车 PDA 拣货和发车
 ### 6.1 打开任务
 入口：海外 PDA → 排车拣货。
 1. 查看当前 Token 仓库的任务；
 2. 打开排车单，核对排车号、车辆、目的地、托盘和计划箱数；
 3. 页面使用服务端返回的状态和版本，不按本地草稿推断可操作性。
 ### 6.2 扫托盘拣货
 1. 扫描托盘业务码；
 2. 服务端校验托盘属于本排车、当前仓库和有效库存位置；
 3. 校验计划箱数和托盘组成；
 4. 在成功事务中完成库存分配、拣货和相应出库扣减；
 5. 写库存流水、任务进度和幂等记录；
 6. 重复同一命令返回原结果，不再次扣减。
 部分出库若不能整托核平，应先通过合法拆托或组成明细处理，不能按 FIFO 猜测某票来源。
 ### 6.3 完成拣货
 全部托盘和箱数核平后，PDA 任务进入 `COMPLETED`，排车进入 `READY_TO_DEPART`。存在漏托、数量差异、暂扣或库存版本冲突时不能完成。
 ### 6.4 发车门禁
 PDA 只使用详情返回的 `canDepart` 和 `departBlockReason`。服务端至少校验：
 - 车辆信息完整；
 - 拣货任务完成且箱数核平；
 - 排车为 `READY_TO_DEPART`；
 - 平台已经转派送；
 - 关联出库单仍为 `WAIT_OUTBOUND`。
 发车成功后排车进入 `DEPARTED`，出库单进入 `OUTBOUNDED`，释放相应托盘锁。发车只推进履约事实，不再次扣库存。
 ## 7. F37 独立出库任务
 ### 7.1 通用生命周期
 独立出库通常按 `WAIT_PICK → PICKING → PICKED → OUTBOUNDED` 推进。只有尚未开始的 `WAIT_PICK/WAIT_OUTBOUND` 可以取消；作业开始后不能通过取消自动恢复库存。
 PDA 操作：打开本仓任务 → 扫箱/托盘 → 核对来源 → 幂等提交 → 数量核平 → 完成出库。
 ### 7.2 一件代发出库
 - 候选必须已完成入仓，仍有可用箱唛、SKU 和库存位置；
 - 创建时必须解析为唯一客户和唯一仓，禁止跨客户/跨仓一单；
 - 可逐箱扫描；
 - 扫 `DP` 托盘码时原子拣取当前任务内该托全部剩余箱件和 SKU；
 - 任一库存明细失败时整托回滚；
 - 完成后箱唛、SKU 汇总、库存位置和流水必须核平。
 ### 7.3 换标、转运和退货出库
 | 类型 | 前置 | 作业依据 | 结果 |
 |---|---|---|---|
 | 换标出库 | 仓库作业完成且客户确认 | 换标后箱唛、托盘和改绑快照 | 换标单完成、出库 `OUTBOUNDED` |
 | 仓储转运 | 申请审核通过 | 冻结来源托盘和箱数 | 转运出库完成 |
 | 退货出库 | 退货箱/SKU 可用 | 冻结退货库存 | 退货库存扣减、出库完成 |
 退货出库不能与派送异常退回库存恢复混用；前者消费退货库存，后者恢复原出库来源库存。
 ## 8. F38 派送和签收
 派送单状态：`WAIT_DELIVERY → DELIVERING → DELIVERED`，异常情况下可为 `REJECTED/CANCELLED/RETURNED`。
 ### 8.1 查看和开始派送
 Admin/Client 按权限查看拆分后的单仓派送单、目的地、车辆/快递、预约、BOL 和状态历史。客户只能查看本企业。
 平台核对实际出库后开始派送，使单据进入 `DELIVERING`。不能仅因排车发车就把所有拆分派送单自动视为签收。
 ### 8.2 上传签收资料并完成
 1. 打开具体派送单；
 2. 上传该目的仓对应的签收文件/照片；
 3. 核对文件归属、类型和有效性；
 4. 保存签收资料；
 5. 系统在同一业务流程自动将该派送单推进为 `DELIVERED`；
 6. 按关联 `sourceInboundId` 写 `OVERSEAS_DELIVERY_COMPLETED` Outbox。
 不提供脱离签收资料的人工“完成派送”按钮。同车不同 FBA 仓的派送单互不代完成。
 ## 9. F39 派送异常退回
 入口：Admin → 异常订单。
 1. 从原派送单创建异常，状态为 `PENDING`；
 2. 退回明细只能从原出库拣货事实选择，不能自由填写 SKU 或数量；
 3. 开始处理后进入 `PROCESSING`；
 4. 选择服务端校验的真实退回仓、托盘和库位；
 5. 上传 `OVERSEAS_EXCEPTION_EVIDENCE`；
 6. 现场确认退回实收；
 7. 服务端按原出库来源恢复库存并写 `RETURN_STOCK_IN` 流水；
 8. 同事务完成异常并将派送置为 `RETURNED`。
 只有待处理异常可以取消。库存恢复、异常完成和派送退回任一步失败时整体回滚，不留下“派送已退回但库存未恢复”的半套结果。
 ## 10. F40 客户回访和国内最终回写
 ### 10.1 客户回访
 入口：Admin → 客户回访。
 客服选择已完成或需跟进的业务单，记录联系时间、方式、结果、问题、后续动作和附件。回访是服务闭环资料，不替代签收、异常或库存事实。
 ### 10.2 跨区完成事件
 每张实际完成的派送单在业务事务内写 Outbox。Event Bridge 跨区投递后，Firstleg：
 1. 校验内部身份、事件版本、ID 和 Payload 哈希；
 2. 校验来源订单、来源入仓单、入仓码和 FBA 目的仓；
 3. 防止同车其他目的仓事件误完成本票；
 4. 将对应国内入库单从 `LOADED` 推进为 `DELIVERED`；
 5. 写状态历史和事件消费记录。
 ### 10.3 Order 最终完成
 Firstleg 检查同一 Order 的全部有效入库单。只有全部都为 `DELIVERED` 时，才调用 Order 推进交易状态为 `COMPLETED`。
 部分装载形成的余量子单、另一柜或另一目的仓尚未完成时，Order 不能提前完成。重复事件不得重复推进、重复写历史或重复生成费用。
 ## 11. 状态和数据流
 ```text
 INBOUND_COMPLETED + 可用库存
  → 草稿锁 → 正式排车锁 → PENDING_DEPARTURE
  → 转派送：车辆级 WAIT_OUTBOUND + 目的地级 WAIT_DELIVERY
  → PDA 扫托扣库存 → READY_TO_DEPART
  → 发车：DEPARTED + OUTBOUNDED
  → 派送：DELIVERING → 签收资料 → DELIVERED
  → OVERSEAS_DELIVERY_COMPLETED
  → 国内入库单 DELIVERED
  → 同一 Order 全部完成后 COMPLETED
 ```
 尾程主状态保持 `INBOUND_COMPLETED`，排车、出库、派送和异常精确状态分别保存在各自单据并汇总到 `sub_order_status`。
 ## 12. 异常与恢复
 | 场景 | 处理方式 |
 |---|---|
 | 托盘被其他草稿锁定 | 不可选择，等待释放或超时 |
 | 预排时库存变化 | 服务端拒绝，刷新候选重排 |
 | 排车已开始仍取消 | 拒绝，走对应异常流程 |
 | 未转派送就发车 | `canDepart=false`，Admin 先完成转派送 |
 | PDA 扫错托盘 | 拒绝且库存不变 |
 | 扫码超时 | 保留幂等键，查询服务端任务后重试 |
 | 整托一项失败 | 整托回滚，不部分扣库存 |
 | 车辆资料缺失 | `departBlockReason` 明示缺项 |
 | 签收资料上传失败 | 派送保持未完成，重新上传 |
 | 一车多目的地仅一单签收 | 只完成对应派送单 |
 | 异常退回数量超原拣货 | 拒绝，不允许自由扩量 |
 | 退回库存事务失败 | 异常/派送状态同步回滚 |
 | 国内消费暂时失败 | 保留 Outbox/Inbox 受控重试，不手工完成国内单 |
 | 完成事件重复 | 返回既有结果，不重复历史或费用 |
 ## 13. 全流程最终完成判定
 测试环境综合证据 `baiyue-firstleg/reports/admin-full-postdeploy-66c2651b.json` 已覆盖 `phase4-overseas-dispatch`、`phase5-terminal-drayage`、`phase5-overseas-fulfillment`、客户服务和跨区回写模块，相关模块失败数均为 0。清单仍按具体派送单保留，最终上线前需要用业务柜次逐项复核。
 - [ ] 排车候选来自真实、可用且未被其他业务占用的库存
 - [ ] 草稿锁、正式锁和取消/完成释放均可追溯
 - [ ] 排车路线由实际目的地生成
 - [ ] 转派送只发生一次且早于发车
 - [ ] PDA 拣货数量、托盘组成、库存扣减和流水一致
 - [ ] 发车时服务端 `canDepart=true`
 - [ ] 发车没有重复扣库存
 - [ ] 每个目的地拥有独立派送单和签收资料
 - [ ] 派送完成只由有效签收资料触发
 - [ ] 异常退回时原出库来源、恢复库存和证据完整
 - [ ] 完成事件按来源入仓单跨区幂等回写
 - [ ] 国内入库单为 `DELIVERED`
 - [ ] 同一 Order 全部有效入库单完成后才为 `COMPLETED`
 - [ ] 客户可查询本企业最终状态和允许的签收资料
 ## 14. 易用性与数据流评审问题
 1. 智能预排候选是否应直接显示不可选原因、锁定人和锁过期时间？
 2. 车型、托位、箱数、重量和目的仓能否提供装载风险提示？
 3. 转派送为何必须早于发车，页面是否在拣货阶段持续提示？
 4. 排车、出库、派送三个编号和状态是否需要统一时间线和相互跳转？
 5. PDA 扫码即扣库存的关键动作是否需要更强确认和撤销边界说明？
 6. `canDepart/departBlockReason` 能否直接跳转到车辆、拣货或转派送缺项？
 7. 一件代发逐箱与整托两种模式如何防止操作员重复选择？
 8. 一车多目的仓时，签收资料上传如何降低绑错派送单的风险？
 9. 派送异常是否需要标准原因、责任方、时限和赔付关联？
 10. 退回入仓是否需要 PDA 专用入口，而不是只依赖后台操作？
 11. 跨区回写延迟时，海外“已签收”和国内“未完成”如何向客服解释？
 12. Order `COMPLETED` 前是否需要展示仍未完成的具体子入库单/柜次/目的仓？
 ## 15. 事实来源
 - `docs/海外仓业务/README.md`
 - `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
 - `apps/pda-overseas-uniapp/AGENTS.md`
 - `apps/pda-overseas-uniapp/src/pages/dispatch/dispatch.vue`
 - `apps/pda-overseas-uniapp/src/pages/outbound/outbound.vue`
 - `baiyue-firstleg/lastleg-service/AGENTS.md`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/delivery/`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/exceptionorder/`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/customervisit/`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/OverseasDeliveryCompletedConsumer.java`
 - `baiyue-firstleg/order/AGENTS.md`
@@ -0,0 +1,392 @@
 # 阶段四：海运、目的港与尾程入仓计划
 > 对应全景流程：F24～F27。  
 > 阶段起点：柜次已完成送港/进港或甩柜处理，并产生承运船舶实际 `VESSEL_DEPARTED`/`DEPARTED_ORIGIN_PORT` 节点；真实 `DEPARTED_WAREHOUSE` 和 `PORT_RECEIVED` 属于阶段三送港线事实。  
 > 阶段终点：跨区尾程订单完整生成，整柜每票入仓计划及托盘/库位资源已生成或有明确资源失败待办，订单进入 `INBOUND_PLANNED`。  
 > 本阶段同时维护船舶/货柜轨迹和尾程业务准备，但两类状态不得互相冒充。
 ## 1. 阶段目标和边界
 本阶段完成四条相互关联但独立的链路：
 1. 从承运船舶实际开航开始查询并保存十个标准船节点；
 2. 管理目的港清关、海外码头车队、提柜、预计到仓和还空；
 3. 将国内最终实装快照可靠投递到海外区域并创建尾程订单；
 4. 按整柜维护每票计划并转换为可执行的海外入仓计划和资源。
 阶段四不执行海外仓实收、库存入账、库内服务、排车或出库。`PICKUP_READY` 只表示货柜已清关可提，并开放海外 PDA 待收柜候选；它不表示已经到仓或已经产生库存。
 ## 2. 角色、终端和系统边界
 | 角色/系统 | 终端 | 主要职责 |
 |---|---|---|
 | 船期操作员 | Admin | 查看查询任务、标准节点、异常与查询历史，必要时人工补录 |
 | 目的港操作员 | Admin | 维护清关/DO/PU、选择海外车队、发提柜邮件、确认提柜和还柜 |
 | 海外仓计划员 | Admin | 维护整柜预计到仓、每票托数与作业属性、执行柜级转换 |
 | 企业成员 | Client | 查看本企业尾程订单和允许展示的船期/计划进度 |
 | Firstleg | 后端 | 拥有查询任务、标准节点、目的港码头拖车和装柜完成 Outbox |
 | Integration Service | 后端 | 调用船司/轨迹供应商，解析并返回标准化结果，不保存业务主数据 |
 | Event Bridge | 跨区通道 | 版本化、认证地投递业务事件 |
 | Lastleg | 海外后端 | Inbox 幂等消费、尾程订单、计划、在途库存和海外业务状态 |
 | Warehouse | 国内主数据 | 海外共享仓、FBA 目的仓和供应商主档权威 |
 | Warehouse Overseas | 海外资源 | 海外库位、实物托盘和资源锁 |
 所有浏览器海外接口经 `gateway-overseas/`。国内 Auth 仍是账号和 Token 签发方；跨区业务写入通过内部身份、Inbox/Outbox 和事件契约完成，不允许浏览器伪造跨区事件。
 ## 3. 阶段前置检查
 - 柜次存在真实集装箱号、订舱、提单号、送港/进港事实和实际开船节点；
 - 装柜完成事件包含最终实装订单、入仓单、目的类型、箱数及必要托盘/SKU/箱唛快照；
 - 国内五类装柜证据和锁码文本已经冻结；
 - 接柜海外仓是 Warehouse 中 `ACTIVE + OVERSEAS + RECEIVING` 的平台共享物理仓；
 - FBA 目的仓是 Warehouse 有效公共主档，不能用接柜仓或国内仓代替；
 - 船司/轨迹查询标识足以唯一指向目标订舱和柜次；
 - 同柜订单的预计到仓事实必须能够收敛为一个柜级日期。
 ## 4. F24 海运十节点
 ### 4.1 查询任务创建
 承运船舶实际开航事务幂等创建 `CarrierScheduleQuery`。任务必须绑定真实订舱、柜次以及可用的船司、船名航次、提单号或柜号，不创建脱离业务单据的孤立轮询任务。送港、进港、甩柜和客户报关确认在阶段三分别记录，不能用预计 ETD 提前创建“海运中”展示。
 标准节点保留国内送港事实，但海运查询的起点是实际开船：
 `DEPARTED_WAREHOUSE`、`AT_ORIGIN_PORT` 和 `LOADED_ON_VESSEL` 可以作为送港/装船历史补录；客户的“海运中”节点和定时船节点查询以真实 `DEPARTED_ORIGIN_PORT`/`VESSEL_DEPARTED` 为起点。
 ```text
 10 DEPARTED_WAREHOUSE       已离开国内仓
 20 AT_ORIGIN_PORT           已到起运港
 30 LOADED_ON_VESSEL         已装船
 40 DEPARTED_ORIGIN_PORT     已离开起运港
 50 IN_TRANSIT               海运途中
 60 ARRIVED_DESTINATION_PORT 已到目的港
 70 DISCHARGED_FROM_VESSEL   已卸船
 80 PICKUP_READY             已清关、可提柜
 90 PICKED_UP                已提柜
 100 EMPTY_RETURNED          已还空柜
 ```
 ### 4.2 自动查询操作与频率
 入口：Admin → 船期/货柜详情 → 船节点查询。
 平台查看：查询任务状态、当前最新实际节点、预计节点、最近成功时间、下次允许时间、供应商、失败原因、异常事实和每次尝试历史。
 正常查询槽位按北京时间每天 `09:00`、`12:30`、`16:00`。调度器每分钟只扫描已到期任务，不代表每分钟调用船司。
 - 成功、无变化、需人工或永久失败：进入下一固定槽位；
 - 技术性可重试失败：当前槽内按 15/30 分钟退避，含首次最多三次；
 - 重试不得跨越下一正常槽位；
 - 服务恢复后错过的槽位直接顺延，不集中补打供应商；
 - 实际 `EMPTY_RETURNED` 后任务停止。
 ### 4.3 节点时间和推进规则
 | 时间 | 含义 | 推进最新实际节点 |
 |---|---|---|
 | `estimatedAt` | 预计发生时间 | 否 |
 | `actualAt` | 已确认实际时间 | 是 |
 | `observedAt` | 本次观测到事实的时间 | 否 |
 | `createdAt` | 平台写入时间 | 否 |
 只有带 `actualAt` 的标准节点可以推进。节点按序号单调前进；迟到的较早节点可作为历史保存，但不能回退当前节点。供应商缺少中间节点时保持缺失，不能自动补齐。
 同一供应商事件按稳定 `providerEventId` 幂等；无原生 ID 时用稳定字段组合生成哈希。每条事实保留原始节点编码、来源、地点、观测时间和原始响应哈希，但业务表不保存含密钥的完整网页。
 ### 4.4 异常事实
 以下异常与正常节点并行保存：
 - `CUSTOMS_HOLD`：海关扣留；
 - `TERMINAL_HOLD`：码头/堆场扣留；
 - `DOCUMENT_HOLD`：单证问题；
 - `UNKNOWN_HOLD`：其他无法分类扣留。
 异常不能覆盖最近正常节点。解除时新增解除事实，不删除原异常。
 ### 4.5 人工补录
 供应商缺节点、网页需要人工验证或业务已有可信凭证时，有权限人员可在查询详情补录：
 1. 选择标准节点；
 2. 填写实际时间，预计事实不能冒充实际时间；
 3. 填写地点、来源说明和必要凭证；
 4. 核对节点不会回退当前实际进度；
 5. 携带版本和幂等键提交；
 6. 查看历史中来源标识为人工。
 人工补录 `PICKUP_READY` 会通过跨区事实开放海外 PDA 柜号候选；人工补录 `EMPTY_RETURNED` 会停止任务，因此必须使用真实还柜事实。
 ## 5. F25 目的港清关、车队、到仓和还空
 ### 5.1 清关和文件
 入口：Admin → 清关提柜。
 1. 按柜号、提单号、目的港和节点筛选；
 2. 核对目的港清关资料、DO 和 PU 当前版本；
 3. 上传或替换合法文件引用；
 4. 将线下清关结果反映为可信业务事实；
 5. 清关完成、码头明确可提后，确保实际 `PICKUP_READY` 已进入标准节点链。
 清关资料状态和标准船节点有关联但不互相覆盖。只有明确可提事实才能推进 `PICKUP_READY`。
 ### 5.2 选择海外码头车队
 1. 选择 Warehouse 中 `ACTIVE/TRUCKING/OVERSEAS` 供应商；
 2. 服务端读取供应商名称和邮箱快照，不能用自由文本绕过主档；
 3. 首次选择车队只保存选择，不自动发信；
 4. 操作员确认后发送提柜请求邮件；
 5. 邮件进入顺序发送队列，`SENT` 只表示 SMTP 接受，不代表车队已读或已执行；
 6. 失败邮件保留原因，人工确认后重试。
 更换车队时，事务内同时冻结旧车队取消邮件和新车队提柜邮件，并按顺序投递。同一车队重复选择不重复发信。
 ### 5.3 实际提柜
 车队从码头取得重箱后，目的港操作员确认实际提柜时间。服务端推进实际 `PICKED_UP`，但不创建海外库存、不替代 PDA 到仓收货。
 ### 5.4 预计到仓
 清关提柜列表中的“预计到仓”由平台维护：
 1. 输入整柜预计抵达接柜仓的日期/时间；
 2. 按 `sourceContainerBookingId` 锁定整柜；
 3. 原子同步柜内全部尾程订单的 `estimated_warehouse_at`；
 4. 记录版本、操作人和幂等历史；
 5. 任一入仓计划已生成后锁定，不再允许修改。
 预计到仓不能使用订单创建时间、预计到港时间或当前时间替代。同柜订单缺失或日期不一致时，阶段四的计划转换必须阻断。
 ### 5.5 实际到仓与还空
 实际到仓不由 Admin 手填，也不取预约提柜时间；只取海外 PDA 首次开始收货会话的 `receiving_at`。因此本阶段只能展示“待实际到仓”，真实时间在阶段五产生。
 海外 PDA 完成卸柜后，跨区 `OVERSEAS_CONTAINER_UNLOADED` 事件回到 Firstleg。预计报空/还空截止按卸柜完成时间加 72 小时计算并产生预警。
 真实还柜可由供应商节点或有权限人员确认：
 - 时间不得早于卸柜完成时间；
 - 若已有实际提柜时间，也不得早于提柜；
 - 无需为了还柜补造车队、预约或提柜事实；
 - 首次命令可以版本 0 创建记录，车队字段允许为空；
 - 成功后推进实际 `EMPTY_RETURNED`、解除预警并停止查询任务。
 目的港码头拖车、国内订舱级拖车和海外配送排车是三张不同业务单，不得复用状态或费用。
 ## 6. F26 跨区尾程建单
 ### 6.1 国内生产事件
 Firstleg 在装柜完成后按最终实装生成 `FIRST_LEG_LOADING_PLAN_COMPLETED` V3：
 - 信封包含事件 ID、版本、来源区域、聚合版本和 Payload 哈希；
 - Payload 包含来源柜次/计划/真实柜号和每票最终实装；
 - FBA 可以按实装箱数冻结，不伪造逐箱作业账；
 - `OVERSEAS` 必须逐箱冻结箱码事实；
 - 一件代发必须携带一个或多个不可变来源托盘，以及每托 SKU、箱数、数量和箱唛；
 - 物理柜五类国内装柜照片引用一并冻结。
 Outbox 可重复投递，不能因网络失败直接丢事件或在事务外临时拼装 Payload。
 ### 6.2 Event Bridge 投递
 Event Bridge 校验允许的事件类型、版本、来源/目标区域和内部服务身份后投递 Lastleg。IAM 安全事件使用独立入口，不能交给装柜完成消费者。
 ### 6.3 Lastleg Inbox 消费
 Lastleg 消费步骤：
 1. 常量时间校验内部令牌；
 2. 校验事件 ID、版本、来源区域、客户和必要字段；
 3. 校验 Payload 哈希；
 4. 以事件 ID、哈希和来源入仓单唯一约束防重；
 5. 在一个事务内处理整柜全部订单；
 6. 任一票失败时整柜回滚，不留下半套订单；
 7. 重放相同事件返回既有结果。
 ### 6.4 尾程订单和在途库存
 成功消费后：
 - 同一实际集装箱共享业务尾程单号；
 - 每个 `sourceInboundId` 独立生成一条 `ll_order`；
 - 保存来源订单、入仓码、客户、接柜仓、目的仓和货物冻结快照；
 - 主状态为 `PENDING_ASSIGNMENT`；
 - 生成 `FIRST_LEG` 在途库存；
 - 计划生成前以真实来源入仓码作为库存展示快照；
 - 事件只建订单，不自动生成入仓计划。
 一件代发额外生成来源托盘、SKU、箱唛档案和在途库存事实；海外实物托盘资源仍由 Warehouse Overseas 分配，不覆盖国内来源托盘快照。
 ## 7. F27 尾程计划维护和整柜转换
 ### 7.1 柜级工作台
 入口：Admin → 海外仓 → 尾程订单 → 柜级工作台。
 列表使用 `/container-summaries` 按稳定 `sourceContainerBookingId` 服务端聚合，不允许用当前订单分页在浏览器拼柜。列表至少展示：
 - 柜号、来源柜次和预计到仓；
 - 订单数、已建计划数、待建计划数；
 - `allPlansReady`；
 - `resourcePendingPlanCount`；
 - 接柜仓、目的仓分组和异常摘要。
 已完成转换的柜仍保留供查询和允许范围内维护。详情接口返回柜内全部订单和计划，不受列表分页截断。
 ### 7.2 单票计划维护
 对柜内每票填写：
 - 计划托数；
 - 托盘类型；
 - 是否已分配；
 - 是否允许合托；
 - 是否加急；
 - 现场备注。
 入仓码、实际接柜仓和预计到仓只读。保存时校验订单版本、客户范围、Warehouse 当前仓库主档和幂等键。
 “可合托”只给阶段五现场提供选择，不是实收或完成门禁：合托时扫描同目的仓已使用托盘，独立收货扫描新托盘。
 ### 7.3 普通货与一件代发托盘规则
 普通散货：
 - 保留头程已经冻结并跨区传入的托盘码；
 - 海外计划托数不得少于已有托盘码数量；
 - 海外装托密度不同导致托数增加时，在同柜、同 FBA 仓连续补码；
 - 预览分别展示头程已有数、海外补充数和最终托数。
 一件代发：
 - 必须逐托沿用国内封托的 `DP` 托盘码和每托箱数；
 - 不允许重算托数、重分配箱子或改写 SKU/箱唛；
 - 无法绑定真实资源时禁止保存半成品计划。
 ### 7.4 自动触发与柜级预览
 单票柜保存完整计划后立即尝试生成资源；多票柜在最后一票计划齐全时自动触发整柜资源生成。
 转换前读取服务端预览，核对：
 - FBA、一件代发、私人地址等分组；
 - 每票来源托数、补充托数和最终托数；
 - 柜内计划是否全部就绪；
 - 接柜仓、预计到仓是否一致；
 - 阻断项；
 - `snapshotVersion` 和 `snapshotHash`。
 `pendingPlanCount` 表示尚未建立完整计划；`resourcePendingPlanCount` 只表示自动物化资源失败，需要按原柜级入口重试，不能把它当作正常人工步骤。
 ### 7.5 确认转换
 系统执行柜级 Saga：
 1. 以 `sourceContainerBookingId` 锁柜；
 2. 用版本/哈希重新计算预览；
 3. 向 Warehouse Overseas 批量预留真实托盘、库位和资源锁；
 4. 为柜内每票独立生成入仓计划；
 5. 本地事务确认计划并绑定资源；
 6. 尾程订单进入 `INBOUND_PLANNED`；
 7. `FIRST_LEG` 在途库存展示编号从来源入仓码收口为各自 `planNo`。
 整批转换原子且幂等：相同命令重放不生成第二批计划或资源；本地失败只补偿尚未确认的远端资源；远端确认失败的重放只重试确认。
 ## 8. 状态、编号与数据归属
 | 维度 | 关键状态/编号 | 权威系统 |
 |---|---|---|
 | 船节点任务 | ACTIVE/人工/失败/`STOPPED` | Firstleg |
 | 最新实际节点 | 十节点之一 | Firstleg |
 | 目的港码头拖车 | 车队、提柜、卸柜、还柜 | Firstleg |
 | 尾程主单 | `PENDING_ASSIGNMENT → INBOUND_PLANNED` | Lastleg |
 | 入仓计划 | `planNo`、计划属性、资源绑定 | Lastleg |
 | 在途库存 | `FIRST_LEG` | Lastleg |
 | 海外实物资源 | 托盘、库位、锁 | Warehouse Overseas |
 | 仓库/目的仓/供应商 | 业务主档 | Warehouse |
 `containerNo` 是真实集装箱号；`sourceContainerBookingId` 是跨区稳定柜聚合键；`inboundCode` 永远保存真实来源入仓码；`planNo` 只在尾程入仓计划生成后产生。任何页面不得以内建数据库 ID 回退展示业务编号。
 ## 9. 异常与恢复
 | 场景 | 系统行为 | 操作处理 |
 |---|---|---|
 | 船司无变化 | 保存查询尝试，进入下一槽位 | 无需伪造节点 |
 | 船司技术失败 | 15/30 分钟受控重试 | 查看失败原因，必要时人工 |
 | 只有预计到港 | 保存预计事实，不推进实际节点 | 等待真实节点 |
 | 较早节点迟到 | 保存历史，不回退当前节点 | 无需修改最新进度 |
 | 清关/单证扣留 | 单独保存异常 | 处理后新增解除事实 |
 | 车队邮箱无效 | 阻断发信/换队 | 修正 Warehouse 供应商资料 |
 | 事件重复投递 | 返回既有消费结果 | 不人工删 Inbox |
 | 事件哈希不同 | 冲突失败 | 核对生产端版本和 Payload |
 | 柜内任一票事件失败 | 整柜消费回滚 | 修复数据后重放原事件 |
 | 预计到仓缺失/不一致 | 阻断计划生成 | 在计划前按柜统一维护 |
 | 计划版本过期 | 转换冲突 | 刷新预览，重新确认 |
 | 资源预留失败 | `resourcePendingPlanCount` 暴露 | 用原柜级入口定向重试 |
 | 重试结果不确定 | 查询计划和资源事实 | 复用原幂等键，不另建资源 |
 ## 10. 阶段完成判定
 现有测试环境综合证据 `baiyue-firstleg/reports/admin-full-postdeploy-66c2651b.json` 中，`phase4-carrier-nodes`、`phase4-overseas-pda`、`phase4-overseas-pda-operations`、`phase4-overseas-inbound-operations`、`phase4-overseas-dispatch`、`phase4-tail-order-controls` 和 `phase5-overseas-fulfillment` 均为通过；每个模块的失败数为 0。F23.3 的最新船期客户端投影另见 `baiyue-firstleg/reports/transport-projection-after-schedule-update-20260927.json`。
 - [ ] 国内离仓产生的船节点任务绑定真实订舱和柜次
 - [ ] 节点预计/实际/观测时间没有混用
 - [ ] 异常事实与正常节点分开保存
 - [ ] 实际 `PICKUP_READY` 已到达或已有明确待处理状态
 - [ ] 装柜完成 V3 事件已被 Lastleg 幂等消费
 - [ ] 柜内每个来源入仓单只生成一张尾程订单
 - [ ] 尾程订单冻结客户、入仓码、接柜仓、目的仓和最终实装事实
 - [ ] `FIRST_LEG` 在途库存存在且归属正确
 - [ ] 整柜预计到仓完整且一致
 - [ ] 每票入仓计划属性完整
 - [ ] 柜级转换后每票独立 `planNo` 存在
 - [ ] 托盘、库位和资源锁已绑定，或存在可定位的资源失败待办
 - [ ] 尾程订单状态为 `INBOUND_PLANNED`
 - [ ] 重放事件/转换不会重复建单、建计划或占资源
 ## 11. 易用性与数据流评审问题
 1. 船节点、目的港清关和尾程计划是否需要整合为一条柜级时间线，同时保留三个权威状态？
 2. 预计节点与实际节点的视觉差异是否足够明显？
 3. 船司失败、需人工、扣留异常分别由谁负责，是否需要责任人和 SLA？
 4. 发车队邮件后，页面是否明确区分“已入队、SMTP 已接受、车队已执行”？
 5. 预计到仓锁定前是否应显示会影响哪些订单和计划？
 6. 跨区事件失败是否需要业务友好的“缺哪一票/哪一字段”诊断，而不是只显示事件错误？
 7. 柜级工作台的 `pendingPlanCount` 与 `resourcePendingPlanCount` 是否容易混淆？
 8. 普通散货的“头程已有/海外补充/最终托数”是否需要图形化对比？
 9. 一件代发不可重排托盘的约束是否在编辑前就锁定控件？
 10. 转换前预览是否需要展示资源占用和预计库位，减少确认后人工调整？
 11. `PICKUP_READY` 开放 PDA 候选后，若预计到仓和资源计划尚未完成，现场应看到什么阻断提示？
 12. 还柜预警当前同时存在“两天展示”和“72 小时业务规则”的历史描述，正式页面应统一采用服务端 72 小时口径。
 ## 12. 阶段五交接包
 交给阶段五“海外接柜、实收、库存和库内服务”的输入包括：
 - 来源柜次、真实柜号、订舱和最新实际船节点；
 - `PICKUP_READY` 及以后产生的 PDA 候选门禁；
 - 实际接柜海外仓和柜级预计到仓；
 - 柜内全部尾程订单、来源入仓码、目的类型和冻结货物；
 - 每票独立入仓计划及 `assigned/mergeAllowed/urgent/mergeHint`；
 - 已预留并确认的托盘、库位和资源锁；
 - 普通货头程托盘码与海外补码；
 - 一件代发不可变 `DP` 托盘、箱唛和 SKU；
 - 国内装柜五类照片引用及跨区事件审计历史。
 ## 13. 事实来源
 - `docs/海外仓业务/README.md`
 - `docs/海外仓业务/船节点标准化契约.md`
 - `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
 - `docs/跨区域认证与服务通信契约.md`
 - `baiyue-firstleg/firstleg/AGENTS.md`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/portschedule/`
 - `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/terminaldrayage/`
 - `baiyue-firstleg/common-event-contract/AGENTS.md`
 - `baiyue-firstleg/lastleg-service/AGENTS.md`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/service/LoadingCompletedConsumer.java`
 - `baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/`
 - `apps/admin-web/src/modules/port-schedules/`
 - `apps/admin-web/src/modules/overseas-warehouse/`
--- a/Show More
+++ b/Show More