优化

# Conflicts:
#	独立任务协作登记.md

.gitignore

@@ -1,2 +1,6 @@
 .DS_Store
 **/.DS_Store
+.playwright-cli
+.superpowers
+output
+docs

.idea/.gitignore

@@ -0,0 +1,8 @@
+# 默认忽略的文件
+/shelf/
+/workspace.xml
+# 基于编辑器的 HTTP 客户端请求
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

.idea/docs.iml

@@ -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>

.idea/misc.xml

@@ -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>

.idea/modules.xml

@@ -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>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

AI工程执行与协作约束.md

@@ -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 验收；测试数据库的读写例外仅适用于登记表中已持续授权的总控与专项，并遵守其中的职责和破坏性操作门禁。
+- 环境地址、凭据和 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 由已登记的对应总控统一集成；发生重叠时保留现有改动并跨任务协调。

Admin-Client前端原型还原验收规则.md

@@ -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）。
+
+这些结论只适用于上述操作，不自动推广到其他页面。

Admin全模块样式核对记录.md

@@ -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 测试部署授权并确认版本，再继续完整验收。其余页面和状态仍待逐项核对，本批不代表全模块通过。

Admin国内仓样式核对记录.md

@@ -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 通过。八处确认框均仅补充显式密度入口，提示、权限、版本和提交逻辑未变。人工截图待确认。

Admin客户服务样式核对记录.md

@@ -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 隐藏、回访必填/客户范围、文件选择按钮和附件上传；入仓单选择及附件语义保持原样。

Admin客户管理样式核对记录.md

@@ -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. 海外仓阶梯费用列表：多档位行、横向空间、编辑弹框两类费用并排、档位增删后的表格及校验。

Admin按钮与订单状态颜色清单.md

@@ -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 详情分支的入口另行定向接入，不能宣称改一处已覆盖全应用。

Admin测试环境截图验收记录-20260915.md

@@ -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 项测试、类型检查、构建及差异检查通过；本批只新增截图记录，不将离线检查替代浏览器视觉验收。

Admin海外业务样式核对记录.md

@@ -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 输入保留、幂等重试和卡车/散板状态限制全部通过。

Admin海外仓样式核对记录.md

@@ -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% 截图确认。

Admin消息中心样式核对记录.md

@@ -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 挂载用例核对了按权限查看/已读、任务与模板状态操作、两处详情抽屉、模板不可变编码/变量预览/版本及定时发送表单。实际字段校验、消息发送及服务端结果仍由人工业务验收补充。

Admin财务管理样式核对记录.md

@@ -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% 缩放下截图确认。

Admin货柜管理样式核对记录.md

@@ -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% 缩放人工截图确认。
+- 本轮未部署、未启动后端或修改业务数据。代码验证不替代实际业务写入及视觉验收。

Admin通用资料样式核对记录.md

@@ -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% 缩放下核对修改后截图。首页、系统管理另行继续。

Admin首页与系统管理样式核对记录.md

@@ -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，并返回密度样式入口；该证据只证明开发服务提供了当前代码。
+
+此批无剩余代码检查失败；修改后视觉仍待人工截图。全模块沿组件引用继续复核，不能由四页通过推断其他共享子弹框全部通过。

Admin高密度界面规范.md

@@ -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% 缩放检查独立打开/刷新、列表到详情、浮层普通/全屏/重开、长数据和权限状态。缺少对应截图时保留“待人工截图确认”。

Client界面样式规范.md

@@ -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；菜单背景与部署前一致。四操作折叠分支仅自动化覆盖，缺少真实四操作数据；用户对视觉标准的最终确认待完成。

README.md

@@ -1,21 +1,66 @@
 # 虫虫出海文档索引
 
-项目交付文档按阶段归档，跨阶段原型、调研和过程设计保留在原专题目录。
+项目交付文档按业务域组织。当前开发环境以端到端全流程为统一范围；历史规划、确认和验收记录保留在对应业务域目录，仅用于追溯决策，不构成功能边界。
 
-## 阶段文档
+## 业务域文档
 
-- [一期文档](一期/README.md)：一期范围、开发进度和头程订单最小闭环。
-- [二期文档](二期/README.md)：预约取货、到仓收货、实测差异和指定库位闭环。
-- [三期文档](三期/README.md)：智能排柜、订舱、拖车、PDA 拣货、报关协同和国内出仓闭环。
+- [业务快速索引](业务快速索引.md)：按关键词检索跨端代码入口与业务边界；先查根 AGENTS.md 短路由，按需读取命中行。
 
-## 跨阶段参考
+- [订单与客户](订单与客户/README.md)：登录认证、客户与企业、权限、头程订单和客户工作台。
+- [入库测量与计费](入库测量与计费/README.md)：预约取货、到仓收货、箱码与箱唛、测量、尺寸策略、计价和入库费用。
+- [国内货柜履约](国内货柜履约/README.md)：分柜与同柜、智能排柜、订舱、拖车、PDA 拣货、装柜、报关和国内出仓。
+- [海外仓业务](海外仓业务/README.md)：船节点、海外接柜、入仓、库存、托盘、换标、转运、废弃、退货、排车、PDA 出库、派送、异常退回、客户回访、一件代发及海外本土业务。
+  - [船节点标准化契约](海外仓业务/船节点标准化契约.md)：统一船司原始状态、标准节点、预计/实际时间、异常事实、还柜停止规则和新增船司接入门禁。
+- [财务管理](财务管理/README.md)：应收、应付、费用池、账单、收款、成本、核销、凭证以及国内外业务费用来源。
+- [打印标签维护](打印标签维护/README.md)：箱唛、各类托盘标、HOLD、BOL 与其他单据的现状盘点、参考样张和逐项改版记录。
 
-- `悦/`：产品原型、流程图、历史架构资料和调研数据，仅作为需求参考，不直接等同于已确认范围。
-- `superpowers/`：具体功能的设计与实施记录，按日期和主题维护。
+## 全流程公共契约
+
+- [头程到尾程顺序回路流程图](头程到尾程流程/头程到尾程顺序回路流程图.md)：按“主线节点→完成判定→下一节点；异常→处理→回到原节点复核”建模，提供节点卡模板，适合继续画泳道流程图；附[可编辑示例](头程到尾程流程/头程到尾程顺序回路流程图.drawio)。
+- [头程到尾程流程节点梳理](头程到尾程流程/头程到尾程流程节点梳理.docx)：可直接分发和打印的 Word 文档，按四段流程整理 27 个节点、负责人、正常下一步、异常处理和回流节点。
+- [头程到尾程逐节点思维导图](头程到尾程流程/头程到尾程逐节点思维导图.md)：按实际节点编号，保留建议负责人、正常去向及异常分支，供人工填写和增删；附[可编辑思维导图源文件](头程到尾程流程/头程到尾程逐节点思维导图.mm)。
+- [头程柜级履约尾程流程节点责任与异常梳理](头程到尾程流程/头程柜级履约尾程流程节点责任与异常梳理.md)：按 H/G/W/Z 分解现有流程节点，列出执行岗位、前置、交接、异常和负责人填写栏，附人工待确认问题及[可编辑浏览打印版](头程到尾程流程/头程柜级履约尾程流程节点责任与异常梳理.html)。
+- [头程下单到尾程出库全流程操作手册](头程下单到尾程出库全流程操作手册.md)：从客户头程下单、国内收货测量、分柜装柜和国内出仓，贯通跨区尾程建单、海外接柜入仓、排车、PDA 拣货与尾程出库的角色、操作、状态、编号、门禁和异常处理。
+- [头程下单到尾程出库现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)：以 F01～F40 盘点现有主链、并行流程、条件分支和异常流，明确操作人、入口/出口状态、单据、编号、数据交接和评审项；应先评审本清单，再进入优化。
+- [头程到尾程分阶段流程](头程到尾程分阶段流程/README.md)：F01～F40 六个阶段现状文档已全部完成，逐阶段记录操作、字段、状态、数据流、异常、完成判定和上下游交接条件，可按阶段评审并进入优化。
+- [头程到尾程 AI 流程优化上下文包](头程到尾程AI流程优化上下文包.md)：统一 AI 分析所需的术语、流程变体、RACI、阶段合同、阻断分类、问题证据、指标口径、优化卡模板和完成定义。
+- [头程下单到尾程出库流程易用性与数据流转优化方案](头程下单到尾程出库流程易用性与数据流转优化方案.md)：基于已走通主链梳理现状操作问题，提出统一进度、下一动作、操作回执、数据归属、跨区可观测、PDA 易用性、P0-P2 优先级和验收指标。
+- [跨区域认证与服务通信契约](跨区域认证与服务通信契约.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、跨端契约、接口、权限、SQL、测试和验收入口。
+- 原型中出现的功能不自动成为有效实现；必须由正式契约、代码和验收证据共同确认。

superpowers/specs/2026-07-28-admin-static-rbac-preview-design.md

@@ -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` 事件做实时跨标签同步；其他标签页刷新后读取最新持久化角色。
 
 ### 权限数据流
 

一期/README.md

@@ -1,23 +0,0 @@
-# 一期文档
-
-一期目标是完成平台后台与企业客户端的真实业务基础，以及头程订单最小闭环。
-
-## 文档
-
-- [一期开发进度表](一期开发进度表.md)
-- [一期头程订单闭环设计](一期头程订单闭环设计.md)
-- `虫虫出海一期开发进度表.xlsx`：面向团队日常维护的 Excel 进度表。
-
-## 原型来源
-
-- 产品原型统一位于 `docs/悦/`。
-- 企业登录与注册分别参考 `docs/悦/合并/login.html`、`docs/悦/合并/register.html`；一期只默认包含中文账号密码登录和基础企业注册闭环。
-- 快递公司和往来单位参考 `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` 中“通用”菜单下的对应页面。
-- 原型用于确认信息架构、字段和视觉方向；是否已进入当前 Vue 应用、是否具备完整交互与数据持久化，以一期开发进度表为准。
-
-## 当前边界
-
-- 平台后台：内部账号登录、客户及企业资料审核、内部用户、角色权限、平台收货仓、快递公司、往来单位和头程订单；工作台不作为一期交付项。
-- 企业客户端：中文邮箱/手机号加密码登录、免审核企业注册、企业资料、成员角色权限、头程下单、订单列表和详情；企业资料经平台人工审核通过后才允许提交订单，一期不接短信/邮箱验证码及微信、企业微信登录。
-- 服务端：认证、租户隔离、权限、文件、基础资料、订单状态机、幂等和审计。
-- 不包含工作台、部门/组织架构、完整 WMS、FBA/海外目的仓服务、在线报价、财务结算、完整报关清关、外部物流接口、多语言及微信/企业微信登录；快递公司和往来单位一期支持批量导入，不提供导出。

三期/README.md

@@ -1,16 +0,0 @@
-# 三期文档
-
-三期以头程物流“03 出仓”为范围，完成从排柜、订舱、拖车和仓内拣货，到封柜、报关、国内出仓并等待装船的业务闭环。
-
-## 文档
-
-- [三期开发规划：国内出仓](三期开发规划.md)
-- [三期开发进度表](三期开发进度表.md)：参考一期采用“大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”结构维护。
-- [虫虫出海三期开发进度表（Excel）](虫虫出海三期开发进度表.xlsx)：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。
-- [三期需求确认表](三期需求确认表.md)：集中跟踪 P3-Q1～P3-Q13、负责人和最终结论。
-- [三期页面与原型清单](三期页面与原型清单.md)：按管理后台、企业客户端和 PDA 维护页面范围及原型状态。
-- `参考资料/出仓流程.png`：本期 9 个核心动作及业务终点的原始参考图。
-
-## 当前状态
-
-三期处于范围规划阶段，当前开工结论为 `NO-GO`。当前以原型图片中的“完成国内出仓，等待装船”为阶段终点。动作依赖与并行关系、排柜规则、PDA 设备、拖车协作、柜封照片清单、报关回执及放行门禁、港务/船期信息范围和来源仍需在启动前确认。产品和业务完成确认后先进入契约与任务准备，六项开工准入全部通过后再进入全面功能开发。

三期/三期开发规划.md

@@ -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 和代表性仓库网络环境中完成联调、验收和灰度发布。

三期/三期开发进度表.md

@@ -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 联调、真机、验收和发布任务。

三期/三期需求确认表.md

@@ -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 契约设计与任务拆分的明确结论。

三期/三期页面与原型清单.md

@@ -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. 报关和港务规则确认后，再补客户端及对应后台页面。

业务快速索引.md

@@ -0,0 +1,91 @@
+# 业务快速索引
+
+本文件按需检索，不作为启动必读文档。以下路径均按工作区根目录或表内注明的应用源码根目录起算，不相对于 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 + 柜号 + 收货”。下面是检索提示，不替代业务契约；代码路径均从工作区根起算。用短词检索，不拿整句自然语言做精确匹配。
+
+| 常用说法 | 区分依据 | 首个定位范围 |
+|---|---|---|
+| 没有报价、价格未命中、人工定价、手工报价 | 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` |
+| 审核、测量审核、实测审核 | 仓库测量结果审核 | `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/` |
+| 自动生成托盘、托盘码没生成、计划齐全、重试生成托盘码 | 海外入库计划保存后资源生成，不是国内托盘标签打印 | 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 | 业务路由查“称重确认”或“海外仓库与通用资料”；用国内/海外和业务阶段继续限定 |
+| 海外库位维护、库区、A0溢出位、虚拟收货位 | Admin 海外仓资源维护，区别于 PDA 收货时展示的服务端预留库位 | Admin `apps/admin-web/src/modules/overseas-warehouse/pages/LocationsView.vue` → `api/locations.ts`；海外资源归 `warehouse-overseas-service/`，PDA 收货展示入口见 `apps/pda-overseas-uniapp/src/pages/operation/operation.vue` |
+| 拖车、派车、提柜、还柜 | 国内订舱拖车与目的港码头车队是不同业务；海外配送排车另属 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/`，见下文“退货预报、签收、库存与合箱” |
+| 异常、退回、退仓、回访 | 派送异常退回与库存退货业务不可混用 | 派送查 `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` |
+| 海外业务费用来源与客户财务 | 财务契约、`docs/跨区域认证与服务通信契约.md` | 海外入仓、采购、美国卡车、本土散板和海外仓服务费由 `lastleg-service/financefee/` 校验真实业务归属并版本化审核；通过 `BUSINESS_FEE_SOURCE_CHANGED` 完整快照、`event-bridge-service/` 和国内 Finance `/internal/finance/v1/business-fee-source-events` 可靠入池。`PAYABLE + DIRECT_PAID` 进入已确认成本且不得再次进入 AP 待结算；Client 仍从 `modules/finance/` 读取获准客户财务，不自动开放平台费用来源维护页 |
+
+散货托盘码生成、打印与跨区传递：Admin `modules/loading-lists/components/PalletLabelPrintDialog.vue`；Firstleg `LoadingPalletLabelService`、`LoadingCompletedOutboxService`；Lastleg `LastlegSourcePalletMapper`、`InboundPlanService`。从各项目最近指引继续定位；散货 FBA 标签与一件代发实装托盘分别取各自冻结事实。

二期/README.md

@@ -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 三项计费细节待确认；应收应付、对账、收付款、核销、发票、汇率结算和利润不纳入二期。具体任务状态和实际进度由开发负责人回填，当前文档不代表已承诺完成日期。

入库测量与计费/README.md

@@ -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`

入库测量与计费/产品回传/2026-07-28-产品确认审核记录.md

@@ -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` 可以保持“暂缓”，但必须给出入库测量与计费临时处理规则，否则仍会阻塞对应开发任务。
 
 ## 四、下一步
 

入库测量与计费/产品回传/2026-07-31-产品确认合并记录.md

@@ -1,26 +1,26 @@
-# 2026-07-31 二期产品确认合并记录
+# 2026-07-31 入库测量与计费产品确认合并记录
 
-> 原始回传：[2026-07-31-二期需求确认-产品回传-v1.xlsx](2026-07-31-二期需求确认-产品回传-v1.xlsx)  
-> 回传来源：WXWork 文件 `二期需求确认清单.xlsx`  
+> 原始回传：[2026-07-31-入库测量与计费需求确认-产品回传-v1.xlsx](2026-07-31-入库测量与计费需求确认-产品回传-v1.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 保持待确认。
 - 产品原始回传只读归档，不覆盖；后续回传使用新版本文件名。

入库测量与计费/产品回传/README.md

@@ -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/入库测量与计费/版本归档/`。

入库测量与计费/入库测量与计费V2需求确认清单.md

@@ -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)。

入库测量与计费/入库测量与计费产品待确认事项.md

@@ -1,15 +1,15 @@
-# 虫虫出海二期产品待确认事项
+# 虫虫出海入库测量与计费产品待确认事项
 
 > 更新日期：2026-07-31
 > 适用范围：头程物流“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. 保留产品原始回传和本次会议版本；后续修改用新版本，不覆盖历史文件。
 

入库测量与计费/入库测量与计费前端联调报告-2026-08-04.md

@@ -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 供应商识别和浏览器端体验属于后续环境验收项。**

入库测量与计费/入库测量与计费前端页面清单与多对话并行任务表.md

@@ -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` 代理。

入库测量与计费/入库测量与计费开发规划.md

@@ -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. 使用脱敏初始化数据联调、验收和发布。

入库测量与计费/入库测量与计费开发进度表.md

@@ -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 |
-| 完整库存/WMS | 原型存在 | - | 二期只维护处理单元位置记录 |
+| 应收应付、对账、收付款、核销 | 原型存在 | - | 不纳入入库测量与计费 |
+| 发票、汇率结算、利润和财务报表 | 原型存在 | - | 不纳入入库测量与计费 |
+| PDA | 有“03 出仓”原型 | - | Q9 暂缓，入库测量与计费不接 PDA |
+| 完整库存/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)，再同步本表、开发规划、任务依赖和验收标准。

入库测量与计费/入库测量与计费计费财务模块规划.md

@@ -1,15 +1,15 @@
-# 虫虫出海二期头程计费模块规划
+# 虫虫出海入库测量与计费头程计费模块规划
 
 > 创建日期：2026-07-28
 > 更新日期：2026-07-31
 > 状态：产品已确认范围，计费规则细节确认中
-> 历史文件名保留：`二期计费财务模块规划.md`  
-> 关联规划：[二期开发规划](二期开发规划.md)  
-> 产品确认记录：[2026-07-31 二期产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
+> 历史文件名保留：`入库测量与计费计费财务模块规划.md`
+> 关联规划：[入库测量与计费开发规划](入库测量与计费开发规划.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 对应的应收应付、对账、收付款、发票、汇率结算和利润能力不适用于入库测量与计费。
 
 ## 七、验收重点
 

入库测量与计费/入库测量与计费计费财务需求确认表.md

@@ -1,15 +1,15 @@
-# 二期头程计费需求确认表
+# 入库测量与计费头程计费需求确认表
 
 > 更新日期：2026-07-31
-> 状态：产品已确认二期只做头程计费，当前仅剩 3 项计费细节待确认  
-> 历史文件名保留：`二期计费财务需求确认表.md`  
-> 关联文档：[二期头程计费模块规划](二期计费财务模块规划.md)、[产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
+> 状态：产品已确认入库测量与计费只做头程计费，当前仅剩 3 项计费细节待确认
+> 历史文件名保留：`入库测量与计费计费财务需求确认表.md`
+> 关联文档：[入库测量与计费头程计费模块规划](入库测量与计费计费财务模块规划.md)、[产品确认合并记录](产品回传/2026-07-31-产品确认合并记录.md)
 
 ## 一、已确认的范围
 
-| 编号 | 产品结论 | 二期开发口径 | 状态 |
+| 编号 | 产品结论 | 入库测量与计费开发口径 | 状态 |
 |---|---|---|---|
-| P2-Q13 | 二期只做头程计费 | 建设头程费用项目、计费规则、费用试算、人工补录、调整、确认、作废和费用明细 | 已确认 |
+| P2-Q13 | 入库测量与计费只做头程计费 | 建设头程费用项目、计费规则、费用试算、人工补录、调整、确认、作废和费用明细 | 已确认 |
 
 头程费用结果不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账数据。
 
@@ -29,24 +29,24 @@
 |---|---|---|---|---|---|---|---|---|
 | 待填写 | 待填写 | 待填写 | 待填写 | CNY | 待填写 | 待填写 | 待填写 | 待填写 |
 
-## 三、明确不纳入二期
+## 三、明确不纳入入库测量与计费
 
-| 编号 | 主题 | 二期处理 |
+| 编号 | 主题 | 入库测量与计费处理 |
 |---|---|---|
-| P2-Q17 | 汇率结算和本位币折算 | 不纳入二期 |
-| P2-Q18 | 财务税务结算口径 | 不纳入二期；费用项目如需税率字段，按 Q14 配置 |
-| P2-Q19 | 财务费用审批、应收应付审批 | 不纳入二期；仅保留头程费用调整审计 |
-| P2-Q20 | 客户/供应商对账和结算周期 | 不纳入二期 |
-| P2-Q21 | 账单确认、争议和关闭 | 不纳入二期 |
-| P2-Q22 | 收付款、核销、反核销和银行流水 | 不纳入二期 |
-| P2-Q23 | 发票登记和外部开票平台 | 不纳入二期 |
-| P2-Q24 | 利润、利润率和财务报表 | 不纳入二期 |
+| P2-Q17 | 汇率结算和本位币折算 | 不纳入入库测量与计费 |
+| P2-Q18 | 财务税务结算口径 | 不纳入入库测量与计费；费用项目如需税率字段，按 Q14 配置 |
+| P2-Q19 | 财务费用审批、应收应付审批 | 不纳入入库测量与计费；仅保留头程费用调整审计 |
+| P2-Q20 | 客户/供应商对账和结算周期 | 不纳入入库测量与计费 |
+| P2-Q21 | 账单确认、争议和关闭 | 不纳入入库测量与计费 |
+| P2-Q22 | 收付款、核销、反核销和银行流水 | 不纳入入库测量与计费 |
+| P2-Q23 | 发票登记和外部开票平台 | 不纳入入库测量与计费 |
+| P2-Q24 | 利润、利润率和财务报表 | 不纳入入库测量与计费 |
 
 ## 四、会议填写规则
 
 - 认可当前建议：将建议复制到“最终结论”，状态改为“已确认”。
 - 修改当前建议：填写会议确定的可开发口径，状态改为“已确认”。
-- 暂时无法确定：状态改为“暂缓”，并写清二期临时处理方式。
+- 暂时无法确定：状态改为“暂缓”，并写清入库测量与计费临时处理方式。
 - 不需要填写确认人和确认时间。
 - 确认后保留本次会议文件，不覆盖产品原始回传；新一轮确认使用新版本文件名。
 

入库测量与计费/入库测量与计费费用项目数据归属决策记录.md

@@ -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 推断 | 未被本决策扩大 |

入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md

@@ -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 产品结论仍需产品/业务负责人正式填写，技术实现通过不等于代替产品确认。

入库测量与计费/入库测量与计费需求优化版-原型对照.md

@@ -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. 作废、驳回、审核、文件访问和费用操作均有审计记录。

入库测量与计费/入库测量与计费需求确认清单.md

@@ -1,18 +1,18 @@
-# 虫虫出海二期需求确认清单：头程到仓与头程计费
+# 虫虫出海入库测量与计费需求确认清单：头程到仓与头程计费
 
 > 创建日期：2026-07-28
 > 更新日期：2026-07-31
-> 当前状态：产品已确认二期只做头程计费，3 项计费细节待补充  
+> 当前状态：产品已确认入库测量与计费只做头程计费，3 项计费细节待补充
 > 确认范围：头程物流“02 到仓”及头程费用计算
-> 关联规划：[二期开发规划](二期开发规划.md)  
+> 关联规划：[入库测量与计费开发规划](入库测量与计费开发规划.md)
 > 原型依据：[头程物流流程图](参考资料/头程物流流程图.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-Q17 | 不进入二期 | 不建设汇率结算和本位币折算 |
-| P2-Q18 | 不进入二期 | 不建设财务税务结算口径；费用项目如需税率字段，按 Q14 配置即可 |
-| P2-Q19 | 不进入二期 | 不建设财务费用审核、应收应付审核或会计审计链；保留头程费用调整审计 |
-| P2-Q20 | 不进入二期 | 不建设客户/供应商对账和结算周期 |
-| P2-Q21 | 不进入二期 | 不建设账单确认、争议和关闭流程 |
-| P2-Q22 | 不进入二期 | 不建设收付款、核销、反核销和银行自动认领 |
-| P2-Q23 | 不进入二期 | 不建设发票登记和外部开票平台 |
-| P2-Q24 | 不进入二期 | 不建设利润、利润率和财务报表 |
+| P2-Q13 | 入库测量与计费只做头程计费 | 只建设费用项目、计费规则、费用试算、调整、确认和头程费用明细 |
+| P2-Q17 | 不进入入库测量与计费 | 不建设汇率结算和本位币折算 |
+| P2-Q18 | 不进入入库测量与计费 | 不建设财务税务结算口径；费用项目如需税率字段，按 Q14 配置即可 |
+| P2-Q19 | 不进入入库测量与计费 | 不建设财务费用审核、应收应付审核或会计审计链；保留头程费用调整审计 |
+| P2-Q20 | 不进入入库测量与计费 | 不建设客户/供应商对账和结算周期 |
+| P2-Q21 | 不进入入库测量与计费 | 不建设账单确认、争议和关闭流程 |
+| P2-Q22 | 不进入入库测量与计费 | 不建设收付款、核销、反核销和银行自动认领 |
+| P2-Q23 | 不进入入库测量与计费 | 不建设发票登记和外部开票平台 |
+| 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-Q18 | P0 | 财务税务结算 | 不纳入二期 |
-| P2-Q19 | P0 | 财务费用审批 | 不纳入二期 |
-| P2-Q20 | P0 | 对账周期 | 不纳入二期 |
-| P2-Q21 | P0 | 账单确认争议 | 不纳入二期 |
-| P2-Q22 | P0 | 收付款核销 | 不纳入二期 |
-| P2-Q23 | P1 | 发票管理 | 不纳入二期 |
-| P2-Q24 | P1 | 利润报表 | 不纳入二期 |
+| P2-Q17 | P0 | 汇率结算 | 不纳入入库测量与计费 |
+| P2-Q18 | P0 | 财务税务结算 | 不纳入入库测量与计费 |
+| P2-Q19 | P0 | 财务费用审批 | 不纳入入库测量与计费 |
+| P2-Q20 | P0 | 对账周期 | 不纳入入库测量与计费 |
+| P2-Q21 | P0 | 账单确认争议 | 不纳入入库测量与计费 |
+| P2-Q22 | P0 | 收付款核销 | 不纳入入库测量与计费 |
+| P2-Q23 | P1 | 发票管理 | 不纳入入库测量与计费 |
+| P2-Q24 | P1 | 利润报表 | 不纳入入库测量与计费 |
 
 ## 七、确认完成标准
 
-P2-Q14 至 P2-Q16 形成可开发结论后，头程计费模块可以进入正式任务拆分和开发验收。后续需求变化按变更流程处理，不得将应收应付、对账、付款、核销、发票或利润功能默认带入二期。
+P2-Q14 至 P2-Q16 形成可开发结论后，头程计费模块可以进入正式任务拆分和开发验收。后续需求变化按变更流程处理，不得将应收应付、对账、付款、核销、发票或利润功能默认带入入库测量与计费。
 
 确认完成后需要同步：
 
-- 二期头程计费模块规划。
-- 二期开发规划和开发进度表。
+- 入库测量与计费头程计费模块规划。
+- 入库测量与计费开发规划和开发进度表。
 - 头程计费任务依赖、数据对象和验收标准。
-- 二期会议确认 Excel 及产品回传归档记录。
+- 入库测量与计费会议确认 Excel 及产品回传归档记录。

入库测量与计费/参考资料/头程物流流程图.svg

@@ -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"/>

入库测量与计费/海外仓阶梯费用前端联调说明-2026-08-05.md

@@ -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 自动计费流程。

入库测量与计费/第三方入仓测量接口联调说明-2026-08-04.md

@@ -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 服务发现。

双区域部署与Nacos规划.md

@@ -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 接入实施前必须补齐并完成区域内真实上传、下载和双实例读取验收。
+
+这些差距未完成前，不得声称生产双区域部署已就绪。

国内货柜履约/README.md

@@ -0,0 +1,51 @@
+# 国内货柜履约文档
+
+国内货柜履约以国内头程后程作业为范围，完成从排柜、订舱、拖车和仓内拣货，到装柜证据齐全并进入 `LOADED`/装柜完成的业务闭环。`DELIVERED`/派送完成由到达海外仓后的可信回传推进，不属于国内国内货柜履约操作范围。
+
+> 范围更正：国内货柜履约只维护订舱和出仓前所需的船名航次、港口、ETD/ETA 等资料。柜子确认离开国内仓库后的 `CarrierScheduleQuery`、六家船公司查询、每 3 天/最多 3 次、来源/过期标识和后续定时船节点查询整体归海外仓业务，见 `../海外仓业务/README.md`。国内货柜履约不再建设或验收这套查询。
+
+## 当前主体模型与开工禁令
+
+- 国内货柜履约继续按业务单租户、“平台—客户”两级开发，客户之间严格隔离。Java 与接口中的业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓库、快递公司、托盘、库位等公共资源技术作用域。客户往来单位、订单、文件和费用仍归属客户 `tenant_id>0`。
+- 国内货柜履约不得新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，也不得把当前 `tenant_id` 从客户 ID 改义为上级租户 ID。
+- `tenant`、`Tenant*`、`merchant`、接口路径和字段属于历史兼容命名，继续保留；真实租户能力必须等未来独立需求、数据迁移和跨服务契约方案确认后再实施。
+
+## 文档
+
+- [国内货柜履约闭环审计报告（2026-08-08）](国内货柜履约闭环审计报告-2026-08-08.md)：基于当前代码、接口、自动化和测试环境证据的闭环审计，列出阻断项、优先级和 GO 准入标准。
+- [国内货柜履约装柜闭环产品确认表（2026-08-08）](国内货柜履约装柜闭环产品确认表-2026-08-08.md)：提供给产品直接填写的纯业务确认表，不包含技术实现细节。
+- [国内货柜履约装柜闭环开发前确认单（2026-08-08）](国内货柜履约装柜闭环开发前确认单-2026-08-08.md)：用于产品确认直接开发前的状态、门禁、PDA 取证、冲正和验收细节。
+- [国内货柜履约开发规划：国内出仓](国内货柜履约开发规划.md)
+- [国内货柜履约开发进度表](国内货柜履约开发进度表.md)：参考订单与客户采用“大任务 → 详细任务 → 里程碑 → 未确认事项 → 开工准入 → 验收”结构维护。
+- [虫虫出海国内货柜履约开发进度表（Excel）](虫虫出海国内货柜履约开发进度表.xlsx)：可筛选、可下拉维护并使用公式汇总的项目进度工作簿。
+- [国内货柜履约需求确认表](国内货柜履约需求确认表.md)：集中跟踪 P3-Q1～P3-Q13、负责人和最终结论。
+- [国内货柜履约开工门禁](国内货柜履约开工门禁.md)：维护已确认范围、跨端硬边界和局部阻断项；模块指引引用本文件，不重复维护阶段状态。
+- [国内货柜履约页面与原型清单](国内货柜履约页面与原型清单.md)：按管理后台、企业客户端和 PDA 维护页面范围及原型状态。
+- [国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)：真实 HTTP/真机验收覆盖、coverageGap 解除条件和并行任务入口。
+- `参考资料/出仓流程.png`：本期 9 个核心动作及业务终点的原始参考图。
+
+## 当前状态
+
+国内货柜履约已进入分模块部署联调。已确认不新建独立出仓单，现有订单列表/详情承载主状态；支持一单多柜、一个柜拼多个订单，并采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。进入 `LOADED`/装柜完成前，订舱完成、拖车完成、报关放行回执、PDA 拣货完成及五类证据完整均为服务端硬门禁；`LOADED` 后错误统一线下人工处理，国内 Admin/PDA 不提供在线冲正或手工推进 `DELIVERED`。当前不能因子链路已通过而宣告整期完成，最终结论以真实 HTTP 全链路验收为准。
+
+柜子出仓后的船公司/船节点查询已重新归入海外仓业务。国内货柜履约报关首版不做系统对接，全部由人工整理、线下提交和人工上传回执。仓库初始化角色包括操作员、拣货员、理货员，具体权限矩阵由 IAM 契约任务落表。
+
+P3-Q1～P3-Q13 均已确认；P3-Q4 采用 uni-app 开发并支持在线更新，Android 广播扫描已接入。P3-Q5 复用入库测量与计费实时库存、当前位置和可用量接口，不扩展完整 WMS。
+
+### PDA 当前确认口径（2026-08-10）
+
+- Android 扫描广播方式已接入；PDA 采用 uni-app 开发并支持在线更新，按既定发布安排完成真机验收。
+- 正式作业仅支持在线：进入任务即标记“拣货中”，扫描保存在绑定作业员+任务+柜次的设备持久化草稿，点击提交时批量写后端。
+- 允许部分拣货或跳拣，但每个未完成项必须填写异常原因；存在未解决异常时不能完成或进入 `LOADED`。
+- 重复提交返回原结果，版本冲突提示员工刷新重试。
+- PDA 只能现场拍照，Admin 可人工上传；五类证据各至少 1 张有效照片，可同类型多张追加，错图只作废不硬删除。
+- 单柜次只允许一名作业员作业，不做多人并行和任务接管；进入任务即标记“拣货中”，扫描草稿按作业员+任务+柜次隔离，点击提交时批量写入后端。
+- 后台操作员、理货员可按权限人工上传证据；拣货员只负责 PDA 现场拍照，不开放后台人工上传。照片无限期保留，客户不可见照片和锁码。
+
+### 发布与真实验收状态（2026-08-10）
+
+- Admin 已部署 `b593d72`：智能装柜、预装清单、装柜清单均可访问真实接口；预装/装柜清单不再要求选择仓库，详情仍使用列表行返回的真实仓库归属。
+- Firstleg 已部署 `3bfc11a`：修复 PDA 拣货时库位分配状态提前变更的问题；真实复跑仍发现 PDA `pick` 第二处 `S0500`，当前仍阻断 PDA 复核、装柜完成、报关 LOADED 关联和最终门禁，不能标记国内货柜履约闭环完成。
+- 验收 fixture 顺序已核实为 `orders → inbound-measurement → phase3-container-loading → phase3-loading → phase3-customs → phase3-port-schedules → phase3-loading-finalize`；脚本保留真实失败，不以 mock、历史资源或 coverage gap 伪装通过。
+- PDA“点击提交时批量写入后端”的原子 batch 契约尚未实现；当前页面仍不能证明整批事务、批次幂等、服务端库存快照和失败整批回滚已具备。
+- ZIM hCaptcha、COSCO 动态页继续按产品确认的人工兜底保留为 `MANUAL_REQUIRED`，不作为自动查询 PASS。

国内货柜履约/国内货柜履约Wave1开发任务卡-2026-08-09.md

@@ -0,0 +1,55 @@
+# 国内货柜履约 Wave 1 开发任务卡
+
+整理日期：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`。
+- 在产品未确认前固化部分拣货拆单和一单多柜聚合规则。

国内货柜履约/国内货柜履约开发规划.md

@@ -0,0 +1,322 @@
+# 虫虫出海国内货柜履约开发规划：国内出仓
+
+> 创建日期：2026-07-28  
+> 状态：已进入分模块开发规划  
+> 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；用户已于 2026-08-08 确认国内国内货柜履约以 `LOADED`/装柜完成为阶段终点
+> 前置阶段：[订单与客户文档](../订单与客户/README.md) · [入库测量与计费文档](../入库测量与计费/README.md)
+
+> 2026-08-10 产品确认版：国内货柜履约不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 硬门禁为订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。
+
+> 当前范围更正：原 `P3-PORT-01`、六家船公司官网查询及 `CarrierScheduleQuery` 是柜子确认离开国内仓库后的业务，整体重新归入海外仓业务。国内货柜履约仅保存订舱与出仓前所需的船名航次、港口和 ETD/ETA 等资料，不建设或验收出仓后的定时节点查询。
+
+> 主体模型与硬约束：国内货柜履约只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。
+
+## 一、国内货柜履约目标
+
+国内货柜履约承接入库测量与计费“货物完成到仓、实测、差异处理和指定库位”的结果，将已受理货物转化为可执行、可追踪、可审计的国内出仓任务。
+
+流程覆盖九个动作：
+
+```text
+智能排柜 → 订舱 → 预约拖车
+    ↓
+PDA 拣货 → 装柜并上传货柜/铅封照片
+    ↓
+客户上传报关资料 → 平台整理提交报关代理 → 上传回执供客户下载
+    ↓
+维护订舱与出仓前所需的船名航次、港口和预计时间
+    ↓
+国内国内货柜履约完成：`LOADED`/装柜完成
+```
+
+国内货柜履约完成标准是同一订单/柜次已完成排柜和 PDA 拣货，空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效照片已真实上传，锁码文本已保存，服务端门禁通过并将订单推进为 `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-PORT-01、P3-CUS-02 对应查询部分 | 已重新归入海外仓业务，不是国内货柜履约动作或验收项 |
+
+## 二、阶段边界
+
+### 纳入国内货柜履约
+
+- 现有订单国内货柜履约状态、订单-柜次关联、智能排柜建议、人工调整和版本确认。
+- 订舱申请、舱位结果，以及出仓前人工确认或业务录入的船名航次、港口、ETD/ETA 等资料快照。
+- 预约拖车、车辆司机、到仓装柜和离仓记录。
+- PDA 任务领取、扫码拣货、部分拣货、异常、复核和幂等提交。
+- 装柜、柜号、铅封号及货柜/铅封照片证据。
+- 客户上传报关资料、平台审核补件、整理并提交报关代理。
+- 报关回执上传、版本、客户可见范围和授权下载。
+- 装柜完成门禁、确认、时间线和站内通知；`LOADED` 后纠错走线下人工流程。
+
+### 明确不纳入国内货柜履约
+
+- 入库、上架、移库、盘点、冻结、补货和完整 WMS；拣货仅复用入库测量与计费实时库存、当前位置和可用量接口。
+- 港区闸口、车队、船公司、海关单一窗口的正式自动化接口。
+- GPS 实时跟车、电子铅封、称重设备、摄像头 OCR 和 IoT 自动采集。
+- 自动报关、关税计算、退税、完整清关业务和自动单证识别。
+- 海上运输、海外清关、目的港提柜、海外仓入库和末端派送。
+- 柜子确认离开国内仓库后的 `CarrierScheduleQuery`、船公司查询、定时船节点和到港跟踪；整体归海外仓业务。
+- 无人工确认的全自动排柜、自动订舱和不可逆业务操作。
+
+## 三、参与角色与数据边界
+
+| 角色 | 数据范围 | 主要操作 |
+|---|---|---|
+| 企业订单操作员 | 当前企业订单及关联柜次 | 上传/补充报关资料、查看订舱与出仓前资料、下载回执 |
+| 平台运营 | 授权客户、订单和柜次 | 确认排柜、订舱、维护出仓前船期资料和协调异常 |
+| 仓库主管 | 被授权的平台收货仓 | 分配拣货任务、复核差异、确认装柜和出仓条件 |
+| 仓库作业员 | 分配给本人或本仓的任务 | PDA 扫码、数量确认、异常上报和任务提交 |
+| 操作员 | 授权仓库/订单/柜次 | 查看作业进度、人工上传装柜证据、协助处理异常 |
+| 拣货员 | 分配给本人的单柜次任务 | PDA 扫码、数量确认、异常上报和批量提交；不开放后台人工证据上传 |
+| 理货员 | 授权仓库/柜次 | 人工上传/补充/作废装柜证据、核对柜号和锁码、记录异常 |
+| 拖车调度员 | 授权订单/柜次与车辆范围 | 预约车辆、维护司机/车牌、到仓和离仓节点 |
+| 报关专员 | 授权客户、订单和报关批次 | 审核、退回、整理、提交资料并上传回执 |
+| 平台管理员 | 平台授权范围 | 维护权限、规则和服务商；`LOADED` 后问题按线下流程处理，不提供在线冲正 |
+
+服务端必须依据登录身份确定企业、仓库、客户和数据范围。前端传入的订单 ID、柜次 ID、仓库 ID、客户 ID、作业员 ID 或报关批次 ID 不能单独作为授权依据。
+
+## 四、流程与状态设计
+
+原型以 1 至 9 编号表达动作顺序。产品确认后，订舱、拖车、报关放行、PDA 拣货和证据完整是进入 `LOADED` 的强制前置；智能排柜、订舱、拖车和资料整理可按子流程并行，但服务端不得绕过门禁。PDA 单柜次单作业员，不实现多人并行或任务接管。
+
+### 1. 现有订单的国内货柜履约主状态
+
+| 稳定编码 | 中文名称 | 含义 |
+|---|---|---|
+| `WAIT_SPLIT` | 待分柜 | 入库测量与计费已完成，等待排柜/预装 |
+| `LOADING` | 装柜中 | 预装已确认，PDA 执行拣货和装柜证据上传 |
+| `LOADED` | 装柜完成 | 订舱、拖车、报关放行回执、PDA 拣货完成，且五类证据各至少 1 张有效照片和锁码文本已通过服务端门禁 |
+| `DELIVERED` | 派送完成 | 货物到达海外仓后由海外仓可信回传推进；属于国内货柜履约之后的只读状态 |
+
+### 2. 子流程状态
+
+- 订舱：待订舱、订舱中、已订舱、订舱失败、已取消。
+- 拖车：待预约、已预约、车辆已到仓、装柜中、已离仓、改约、已取消。
+- 拣货：待分配、待拣货、拣货中、待复核、已完成、异常挂起、已取消。
+- 报关：资料待上传、资料待审核、待补件、待提交、已提交代理、回执待上传、回执已上传、已退回、已取消；有效放行回执是 `LOADED` 硬门禁，首版由授权人员人工上传。
+- 出仓前船期资料：待维护、已确认、信息变更；出仓后节点和“已开船”等运输事实归海外仓业务。
+
+主状态由服务端根据已确认的必要子流程推进。客户端不得通过传任意目标状态跳过拣货复核、装柜证据或已配置的装柜完成门禁。
+
+## 五、业务模块
+
+### 1. 现有订单与柜次
+
+- 不创建独立出仓单，现有订单从 `WAIT_SPLIT` 继续推进国内货柜履约状态。
+- 通过“父订单→子订单→柜次”表达一张订单分多柜、多张订单拼柜和拆批；已装载数量形成子订单，未装载数量自动生成后续子订单，子订单必须保留来源订单和数量分摊快照。
+- 订单保持用户当前看到的主状态；柜次承载多订单共享的订舱、拖车、装柜证据和船期信息。
+- 订单详情展示关联柜次、子流程状态、异常和整体时间线。
+- 所有主状态推进使用服务端门禁、幂等键和版本字段防止绕过与并发覆盖。
+
+### 2. 智能排柜
+
+- 原型仅明确“智能排柜”；已确认装载率上限为 110%，税率高排前仅作为可配置排序规则。柜型容量、重量、体积、箱数、同票/混票、不可混装和装载顺序由规则表配置并保留版本。
+- 当前建议首版采用“系统建议、人工确认”；是否允许调整、是否强制填写原因由排柜规则确认。
+- 建议排柜方案保留版本、规则版本、输入快照、操作者和前后差异，以支持追溯。
+- 未确认方案不得生成正式拣货任务或执行不可逆状态变化。
+
+### 3. 订舱与出仓前船期资料
+
+- 国内货柜履约只维护订舱和装柜/出仓交接所需的预计开船、到港等静态资料，不执行出仓后的船公司或船节点查询。
+- 船公司/订舱代理、航线、订舱号、船名航次、起运港、目的港、截单、截关、截港、ETD 和 ETA 暂列为候选字段。
+- 订舱失败、改船、甩柜、船期延误和取消暂列为候选异常场景，按业务确认结果实现。
+- 六家船公司来源、每 3 天/最多 3 次、最近有效结果和过期标识，以及对应适配层全部移至海外仓业务船节点查询维护。
+- 国内货柜履约页面展示的 ETD/ETA 必须明确为订舱或人工确认快照，不得伪装成出仓后的实时查询结果。
+- 建议关键信息变更保留旧值、新值、原因，并向授权用户发送站内提醒。
+
+### 4. 预约拖车
+
+- 从往来单位选择已启用拖车服务商，维护车牌、司机、电话和预约时间窗。
+- 记录提柜、到仓、装柜、离仓、还柜节点和交接说明。
+- 支持改约、取消、迟到、未到、车辆更换和柜号变更。
+- 司机手机号等个人信息按最小权限展示，不进入不必要的客户响应。
+- 图片原文“预约托车”建议统一为行业常用的“预约拖车”，需产品最终确认。
+
+### 5. PDA 拣货与复核
+
+- 按已确认排柜方案生成仓库、柜次、订单和货物明细级任务。
+- PDA 支持登录、领取、箱号选择、扫码、数量确认、部分拣货、跳拣、撤销和异常上报；进入任务即标记“拣货中”。
+- 正式作业必须联网；断网不能开始正式拣货、提交、完成任务或推进 `LOADED`，不建设离线业务提交队列。
+- 扫描只更新绑定作业员、任务和柜次的设备持久化草稿；员工点击提交时才将全部明细批量写入后端，成功或明确放弃后清理，其他账号不得继承。
+- 服务端校验任务归属、状态、重复扫码、超量、错货和批量提交；重复提交返回原结果，版本冲突提示刷新后重试。
+- 允许部分拣货和跳拣，但每个未完成项必须填写异常原因；存在未解决差异时任务挂起，不能完成或进入 `LOADED`。
+- 单柜次只允许一名作业员；不实现多人并行、退出接管或换班释放。进入任务即标记拣货中，点击确认完成后由服务端批量落库并参与统一门禁，无需后台二次审核。
+- 扫描器、声音、震动、网络和缓存通过设备适配层实现，不直接绑定单一厂商 SDK。
+
+### 6. 装柜及柜封证据
+
+- 维护柜号、铅封号、装柜开始/完成时间、操作人和异常说明。
+- 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少上传 1 张有效照片，可同类型多张追加；带锁码照同时要求锁码文本。
+- PDA 只能现场拍照；Admin 可通过独立受权入口人工上传。上传前展示柜次、柜号、铅封号和照片类型，防止证据关联错误。
+- 每张照片作为独立记录，支持上传进度、失败重试和提交前预览；错误或重复照片不硬删除，标记作废并记录原因、操作人和时间。
+- 照片记录文件哈希、上传人、上传时间、关联柜次、有效/作废状态和作废审计；照片无限期保留，客户不可见照片和锁码。后台操作员和理货员按权限人工上传，拣货员仅通过 PDA 现场拍照。
+- 锁码重复、已确认的必传照片缺失或复核未通过时禁止确认装柜完成。
+- 修改柜号或铅封号需要二次确认、原因和完整审计。
+
+### 7. 报关资料协同
+
+- 客户按资料清单上传发票、箱单、合同、委托书和申报要素等文件。
+- 资料清单可按国家/地区、渠道和货物类型配置，并保存订单使用的清单版本。
+- 平台报关专员审核完整性，可退回具体文件并记录补件原因和时限。
+- 提交报关代理时生成提交批次，冻结该批次关联的文件版本。
+- 首版采用系统内整理加线下提交，不直接对接海关单一窗口。
+
+### 8. 报关回执与客户下载
+
+- 授权人员人工上传代理回传的报关回执并关联提交批次；有效放行回执是装柜完成硬门禁，回执类型、版本和操作者可追溯。
+- 替换文件产生新版本，不覆盖原记录；退单或补件形成明确任务。
+- 客户只能下载本企业且标记为客户可见的回执。
+- 文件下载使用授权地址并记录审计，不暴露内部存储路径。
+
+### 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 报关协同 | 客户上传、平台审核、补件、提交和回执下载闭环 | 报关资料清单确认 |
+| 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 | 后台/服务端 | 出仓后船节点查询 | 已重新归入海外仓业务，不作为国内货柜履约交付或验收项；沿用现有 `CarrierScheduleQuery`，不得重复实现 | 海外仓业务 | P3-BOOK-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 | 客户端 | 报关资料 | 清单、上传、补件、版本和进度查看 | P0 | 文件能力可用 |
+| P3-CLEAR-01 | 后台 | 报关协同 | 人工审核、补件、线下提交代理、人工上传放行回执和版本审计 | P0 | P3-CUS-01 |
+| P3-CUS-02 | 客户端 | 回执及出仓前船期资料 | 回执下载、订舱预计开船/到港快照和变更时间线；出仓后查询展示归海外仓业务 | P0 | P3-BOOK-01、P3-CLEAR-01 |
+| P3-GATE-01 | 服务端 | 装柜完成门禁 | 校验订舱、拖车、报关放行回执、PDA 拣货、五类证据和锁码文本，幂等推进 `LOADED`；`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 | 报关代理如何接收资料和返回回执？ | 已确认线下提交，授权人员人工上传回执 |
+| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 当前更正：国内货柜履约只维护订舱与出仓前船期资料；六家船公司及出仓后节点查询整体归海外仓业务 |
+| P3-Q10 | 进入装柜完成后发现错误如何处理？ | 已确认线下人工处理，当前不提供在线冲正 |
+| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 已确认订舱、拖车、报关放行、PDA 拣货和五类证据为 `LOADED` 硬门禁；单柜次单作业员 |
+| P3-Q12 | “报关回执”具体包含哪些类型，海关放行是否为国内出仓硬门禁？ | 已确认有效放行回执为 `LOADED` 硬门禁，首版人工上传 |
+| P3-Q13 | 国内货柜履约终点以什么状态为准？ | 已确认为 `LOADED`/装柜完成；`DELIVERED`/派送完成由海外仓回传，不属于国内国内货柜履约 |
+
+## 十二、建议实施顺序
+
+1. 固化已确认业务规则，按 uni-app 在线更新安排推进 PDA 开发、发布和真机验收。
+2. 统一订单、柜次、订舱、拖车、拣货、报关和出仓前船期资料的稳定编码与关联契约；出仓后查询按海外仓业务衔接。
+3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。
+4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。
+5. 使用脱敏数据演练拼柜、一单多柜、未装数量生成子订单、错拣、补件和改船；`LOADED` 后不演练在线冲正。
+6. 在真实 PDA 和代表性仓库网络环境中完成联调、验收和灰度发布。

国内货柜履约/国内货柜履约开发进度表.md

@@ -0,0 +1,154 @@
+# 虫虫出海国内货柜履约开发进度表
+
+> 创建日期：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 | 报关资料与回执 | 人工资料清单、后台审核补件、线下提交代理、人工上传放行回执 | 联调中 | 70% | 2026-08-10 | 待排期 | Firstleg/Admin | 人工清单和资料版本已通过；LOADED 子订单关联受 PDA 失败级联阻断 |
+| T10 | 装柜完成门禁 | 校验订舱、拖车、报关放行、PDA 拣货、五类证据和锁码文本，推进 `LOADED` | 已阻塞 | 70% | 2026-08-10 | 待排期 | Firstleg | 门禁逐项读取和 fail-closed 已通过，真实推进 `LOADED` 等 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 | 人工协同接口已部署，最终子订单关联受 PDA 失败级联阻断 |
+| P3-T10-00 | T10 | 后台/服务端 | 装柜完成门禁 | 实现订舱/拖车/放行/PDA/证据硬门禁并推进 `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 | 开工阻断 | 九个动作的强制前置和并行关系 | 已确认 | 订舱/拖车/放行/PDA/证据为硬门禁；单柜次单人 |
+| P3-Q12 | 开工阻断 | 报关回执类型及海关放行是否为装柜完成硬门禁 | 已确认 | 有效放行回执为硬门禁，人工上传 |
+| P3-Q13 | 开工阻断 | 国内货柜履约终点 | 已确认 | `LOADED`/装柜完成；`DELIVERED` 由海外仓回传，移出国内货柜履约验收 |
+
+## 八、开工准入记录
+
+国内货柜履约已进入分模块部署联调。下表保留开工条件及当前补齐状态，用于检查契约、原型和任务拆分是否仍有缺口，不再作为“尚未开始开发”的结论。
+
+| 准入编号 | 准入条件 | 当前状态 | 责任方 | 完成证据 |
+|---|---|---|---|---|
+| P3-GO-01 | P3-Q1～P3-Q13 均形成产品结论 | 已完成 | 产品、业务 | `国内货柜履约需求确认表.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 验收，完成发布记录后再评估国内货柜履约完成状态。

国内货柜履约/国内货柜履约开工门禁.md

@@ -0,0 +1,29 @@
+# 国内货柜履约开工门禁
+
+> 本文维护国内货柜履约跨端开发的稳定门禁。实时任务进度见 `国内货柜履约开发进度表.md`；产品决策以 `国内货柜履约需求确认表.md` 为准。
+
+## 可直接开展的范围
+
+- 已确认规则可进入契约、数据、接口、页面和测试拆分，不需要等待整期所有模块完成。
+- 订单继续承载国内货柜履约主状态，不新建独立出仓单；支持父订单、子订单与柜次关系，以及一单多柜和多订单拼柜。
+- 智能排柜、订舱与船期、拖车预约、PDA 在线拣货、五类装柜证据、人工报关回执和 `LOADED` 服务端门禁按需求确认表执行。
+- 国内货柜履约的国内终点为 `LOADED`；`DELIVERED` 只由海外仓可信回传推进。
+
+## 跨端硬边界
+
+- `LOADED` 前必须由服务端校验订舱完成、拖车完成、有效报关放行回执、PDA 拣货完成和五类有效证据完整；国内 Admin/PDA 不提供在线冲正或手工推进 `DELIVERED`。
+- PDA 正式作业仅在线；单柜次只允许一名作业员，不支持多人并行、任务接管或换班释放。进入任务即由服务端标记拣货中，扫描草稿按作业员、任务和柜次隔离，提交时批量写入。
+- 每类证据至少一张有效照片，允许同类型追加；错误照片只能作废并保留审计。客户不可见照片与锁码。
+- 前端页面、菜单和路由只能在对应服务端契约、权限和数据模型稳定后发布；原型中的完整 WMS、海外仓及未确认能力不属于国内货柜履约默认范围。
+
+## 局部阻断项
+
+- PDA 采用 uni-app 开发并支持在线更新；Android 广播扫描已接入。设备型号不构成开发、发布或验收门禁；扫描适配保持厂商无关，按既定发布安排完成常规真机验收。
+- 未冻结的字段、权限码、错误码、迁移方案或跨服务调用，只阻断依赖它们的模块；不得以模拟成功或前端猜测替代服务端契约。
+- 修改任一跨服务契约时，必须同步检查生产者、调用方、OpenAPI、权限、迁移脚本和实际前端消费者。
+
+## 使用方式
+
+1. 先读 `README.md`、`国内货柜履约需求确认表.md` 和本文件，确认任务属于已确认范围。
+2. 再进入目标应用或服务的 `AGENTS.md`，按本地模块入口实现。
+3. 发现新的产品决策或门禁变化时，先更新确认表与本文，再更新受影响模块指引；不要将短期进度、联调故障或环境地址写回模块规则。

国内货柜履约/国内货柜履约装柜闭环产品确认表-2026-08-08.md

@@ -0,0 +1,66 @@
+# 国内货柜履约装柜闭环产品确认表
+
+> 确认方式：产品只需在“产品确认”一列填写“同意”，或写明修改后的规则。  
+> 会议目标：本表确认后直接进入开发，不再补完整高保真原型。
+
+## 一、已经确认
+
+| 事项 | 已确认结论 |
+|---|---|
+| 是否新增出仓单 | 不新增，全部状态继续放在现有订单列表和订单详情中 |
+| 国内国内货柜履约做到哪里结束 | 国内做到“装柜完成”即结束 |
+| 海外仓状态由谁更新 | 货物到达海外仓后，由海外仓回传；国内人员不能手工确认 |
+| 装柜需要哪些照片 | 空仓、半仓、满仓、锁仓、带锁码照片五类；每类至少 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 仅现场拍摄 | 已确认；一柜多人协作仍待确认 |
+| 海外仓回传 | 国内订单中只展示回传结果和时间，不提供手工确认按钮 |  |
+| 独立出仓单页面 | 不新增 |  |
+
+## 四、产品最终结论
+
+| 结论 | 产品填写 |
+|---|---|
+| 是否按本表直接开发 |  |
+| 是否还需要补原型 |  |
+| 本次明确不做的内容 |  |
+| 产品确认人 |  |
+| 确认日期 |  |

国内货柜履约/国内货柜履约装柜闭环开发前确认单-2026-08-08.md

@@ -0,0 +1,146 @@
+# 国内货柜履约装柜闭环开发前确认单
+
+> 整理日期：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. 将本清单作为接口、页面和测试验收的共同依据。

国内货柜履约/国内货柜履约闭环审计报告-2026-08-08.md

@@ -0,0 +1,241 @@
+# 虫虫出海国内货柜履约闭环审计报告
+
+> 审计日期：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` 的现有能力必须整改，当前不具备整期验收条件。**
+
+因此，现阶段不应标记“国内货柜履约完成”，应标记为“**子能力已实现，闭环整改中**”。

国内货柜履约/国内货柜履约需求确认表.md

@@ -0,0 +1,95 @@
+# 虫虫出海国内货柜履约需求确认表
+
+> 创建日期：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 | 全部人工处理：平台整理资料后线下交代理，授权人员人工上传代理回执；系统记录提交批次、回执版本和时间，不建设自动对接 | 报关协同、回执上传 |
+| P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 国内货柜履约只维护订舱与出仓前船期资料 | 已重新归期 | 已确认 | 产品/业务 | 2026-08-19 | 柜子确认离开国内仓库后的船公司/货物跟踪查询、每 3 天最多 3 次、来源、更新时间和过期标识整体归海外仓业务；国内货柜履约不建设或验收该查询 | 国内货柜履约订舱资料、海外仓业务船节点查询 |
+| P3-Q10 | 订单进入“装柜完成”后发现错误如何处理？ | 仅保留线下人工处理和审计，不建设在线冲正 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | `LOADED` 后不提供在线冲正/回退入口，统一线下人工处理；系统保留原状态和审计记录，不由国内 Admin/PDA 推进 `DELIVERED` | 装柜完成门禁、权限、审计 |
+| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 统一门禁按已确认前置执行；PDA 单柜次单人作业 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 订舱完成、拖车完成、报关资料完成且有放行回执、PDA 拣货完成及五类证据完整均为进入 `LOADED` 的强制门禁；PDA 单柜次单人作业，不做多人并行；进入任务即拣货中，提交时批量写入 | 全流程、状态机、PDA、页面进度 |
+| P3-Q12 | 报关回执包含哪些类型，海关放行是否为装柜完成硬门禁？ | 有效放行回执作为硬门禁，首版人工上传 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版回执由人工上传；必须存在有效放行回执才能通过 `LOADED` 门禁。回执类型和版本可追溯，具体字段按人工业务单据映射 | 报关状态、装柜完成门禁、客户回执 |
+| P3-Q13 | 国内货柜履约终点以什么状态为准？ | 国内系统以能掌控的最后环节为终点 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | 国内货柜履约终点为 `LOADED`/装柜完成；`DELIVERED`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内国内货柜履约操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 |
+| P3-Q14 | 订舱、渠道柜次、放舱与智能排柜的先后关系是什么？ | 线下已订妥的订舱在创建时完整登记五项真实运输快照并直接确认；放舱不覆盖首次快照 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-12 | 订舱创建请求必须携带提单号、船名、航次、预计开船时间、预计到港时间五项真实运输数据，并直接进入 `CONFIRMED`；渠道、箱型和数量同时确定，系统按箱型需求数量生成绑定渠道的稳定内部柜次。未放舱不影响候选查询、智能推荐、人工调整和保存装柜计划；同一柜次只能装同渠道入库单，服务端禁止跨渠道混装。`RELEASED` 仅作为后续放舱/PDA 门禁，不补录、不覆盖首次五项运输快照；真实集装箱号可在放舱时或之后录入 | 订舱、柜次、智能排柜、预装、PDA、运输信息 |
+
+### 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 | `LOADED` 的硬门禁包含订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理 | 统一门禁服务负责校验，国内页面不提供在线冲正或 `DELIVERED` 操作 |
+| P3-D4 | 2026-08-10；2026-08-19 更正归期 | 船公司官网查询：每 3 天一次、最多 3 次，保存来源、更新时间和过期标识 | 该能力及首批六家来源整体归海外仓业务，国内货柜履约只保留订舱与出仓前船期资料 |
+| P3-D5 | 2026-08-10 | 初始化仓库常用角色：操作员、拣货员、理货员；按最小权限授予拣货、证据上传和查看能力 | 角色初始化由 IAM/统一 SQL 任务实现，具体权限矩阵在技术契约评审中落表 |
+
+## 四、建议确认顺序
+
+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-Q13。
+- `国内货柜履约开发规划.md` 的流程、状态、里程碑和任务骨架。
+- `国内货柜履约页面与原型清单.md` 中已有参考原型和待补页面。
+- 入库测量与计费输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。
+
+### 5.3 每项确认要求
+
+1. 必须填写负责人、计划确认日期和可执行的最终结论，不能只记录“按建议处理”。
+2. 最终结论需明确正常流程、异常/冲正、权限责任和验收口径。
+3. 暂缓事项必须写明当前范围是否排除、临时方案、影响模块和再次确认日期。
+4. 开工阻断项未解除时，不得将受影响模块标记为可开发。
+5. 会议结束后，将结论同步到开发规划、开发进度表、页面原型和后续验收任务。
+
+### 5.4 会议输出（确认版）
+
+- 14 项确认事项的状态和最终结论已同步；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。
+- 需要新增或调整的原型清单。
+- 国内货柜履约范围内/范围外清单及跨期依赖。
+- 仍有风险的事项、责任人和完成日期。
+- 已允许进入 T02 契约设计与任务拆分；未决技术项只阻断其对应实现，不反向阻断整期已确认范围。

国内货柜履约/国内货柜履约页面与原型清单.md

@@ -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 验收，只有所有硬门禁真实通过后才把页面和整期标记为完成。

国内货柜履约/国内货柜履约验收任务拆分与待确认清单.md

@@ -0,0 +1,35 @@
+# 国内货柜履约验收任务拆分与待确认清单
+
+> 更新日期：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` 请求均被拒绝 | `service-center-flow.mjs` / `phase3-loading.mjs` |
+| 订单/柜次聚合 | 一单多柜、一个柜多订单、父子订单数量分摊及未装数量自动生成子订单可追溯 | `phase3-order-aggregate.mjs`（待补） |
+| 出仓后船节点查询 | 已重新归入海外仓业务，不属于国内货柜履约验收 | 海外仓业务沿用现有 `CarrierScheduleQuery` 设计验收入口，不再补 `phase3-vessel-tracking.mjs` |
+| 仓库角色 | 操作员、拣货员、理货员初始化、最小权限和跨客户隔离 | `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 或数据库直写替代接口验收。

国内货柜履约/货柜履约原型字段验收矩阵-2026-08-17.md

@@ -0,0 +1,44 @@
+# 货柜履约原型字段验收矩阵
+
+> 更新时间：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 仅在测试环境重新部署且当前对话明确授权后执行。

国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md

@@ -0,0 +1,221 @@
+# 货柜管理全链验收矩阵
+
+> 更新时间：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、需求关联且不在订舱阶段自动建柜。

墨家设备测量上传接口说明-V3.md

@@ -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；本文不包含任何真实密钥或柏悦内部业务处理规则。

头程下单到尾程出库全流程操作手册.md

@@ -0,0 +1,538 @@
+# 头程下单到尾程出库全流程操作手册
+
+> 适用范围：企业客户头程下单，国内收货、测量、分柜、装柜、报关与出仓，跨区生成尾程订单，海外接柜入仓、库存、排车及尾程出库。  
+> 流程终点：海外出库单变为 `OUTBOUNDED`；排车场景同时以排车单 `DEPARTED` 为离仓事实。  
+> 当前口径：以现行服务端模块指引、页面入口和代码状态机为准。历史设计与当前实现冲突的地方集中列在第 11 节，旧文档不能直接作为操作依据。  
+> 不在主链内展开：换标、仓储转运、货物废弃、退货换标、异常退回、客户回访、海外采购和本土散板；这些能力在第 9 节说明如何接入出库。
+
+> 完整现状流程目录：见[《头程下单到尾程出库现状流程全景清单》](头程下单到尾程出库现状流程全景清单.md)。该清单以 F01～F40 覆盖主链、并行流程、条件分支和异常流；本文侧重一票主链如何实际操作。
+
+## 1. 一张图看完整主链
+
+```text
+企业资料审核通过、资金账户可用
+  ↓
+客户创建头程订单草稿 → 提交订单 → 生成全局唯一入仓码
+  ↓
+平台审核订单 → 创建国内正式入库单、冻结申报与箱码事实
+  ↓
+国内仓收货 → 测量/称重 → 测量审核 → 进入待分柜
+  ├─ 普通散货/FBA：直接进入分柜
+  └─ 一件代发：先逐箱清点、组托、封托，再进入分柜
+  ↓
+创建模拟柜/订舱 → 智能或人工排柜 → 预装确认
+  ↓
+国内 PDA 拣货装柜 → 五类证据和铅封 → 装柜完成 LOADED
+  ↓
+整柜出口报关完成 → 系统自动收敛或平台确认国内出仓
+  ↓
+船节点：离开国内仓 → 起运港 → 装船 → 在途 → 到目的港 → 卸船 → 可提柜
+  ↓
+装柜完成事件跨区 → 海外生成 PENDING_ASSIGNMENT 尾程订单
+  ↓
+平台按柜预览并转换入仓计划 → 生成/绑定海外托盘资源
+  ↓
+海外 PDA 锁柜 → 三类签收照片 → FBA 按箱数 / OVERSEAS 逐箱收货
+  ↓
+整柜核平完成 → INBOUND_COMPLETED → 海外库存、托盘、库位和流水落账
+  ↓
+平台智能预排/排车 → 维护车辆及预约 → 转派送，生成 WAIT_OUTBOUND 出库单
+  ↓
+海外 PDA 扫托盘拣货并核平 → 发车 → 出库单 OUTBOUNDED / 排车单 DEPARTED
+```
+
+主链有三个不能混淆的“出库/出仓”：
+
+1. 国内装柜完成：入库单为 `LOADED`，表示货已经装入国内出口柜，不等于柜已离开国内仓。
+2. 国内出仓：整柜通过报关等门禁并确认离仓，系统开始船节点跟踪。
+3. 海外尾程出库：海外仓库存经排车/PDA 作业离仓，出库单为 `OUTBOUNDED`。
+
+### 1.1 操作与交接总表
+
+下表把每一步的人工操作、系统自动动作和下一个责任人放在一起。操作员完成当前步骤后，应以“系统结果”作为交接依据，不能只凭口头通知或按钮点击成功提示判断流程已经流转。
+
+| 步骤 | 操作人/终端 | 人工操作 | 系统自动动作与数据结果 | 下一责任人 |
+|---:|---|---|---|---|
+| 1 | 企业客户 / Client | 新建订单，选择仓库、渠道和目的仓，填写货物，保存草稿 | 保存 `DRAFT` 和客户申报快照；不生成入仓码 | 企业客户 |
+| 2 | 企业客户 / Client | 检查后点击“提交订单” | 校验企业资格、资金、仓库和渠道；生成固定入仓码，进入 `PENDING_REVIEW` | 平台订单运营 |
+| 3 | 平台运营 / Admin | 在待审核列表查看详情或批量预览，点击审核通过 | Order 进入 `APPROVED`；Firstleg 建正式入库单和稳定箱码，主状态进入 `WAIT_MEASURE` | 国内仓操作员 |
+| 4 | 国内仓 / 设备、Admin | 按入仓码收货，上传尺寸和称重图片，校正 OCR，提交审核 | 保存测量批次、原始值、修正值、图片和库位块预留 | 测量审核员 |
+| 5 | 审核员 / Admin | 审核测量结果；异常时退回修正 | 普通订单进入 `WAIT_SPLIT`；一件代发进入 `WAIT_PALLETIZE` | 国内履约运营或 PDA |
+| 6 | 国内 PDA | 一件代发逐箱清点、归托、封托 | 冻结真实 DP 托盘及 SKU/箱唛组成，核平后进入 `WAIT_SPLIT` | 国内履约运营 |
+| 7 | 财务/运营、客户 / Admin、Client | 平台试算和发送费用；客户核对并确认 | 独立生成、发布和确认费用版本；不阻断待分柜主流程 | 国内履约运营 |
+| 8 | 国内履约运营 / Admin | 创建模拟柜，选择候选，人工/智能排柜 | 生成稳定柜次、预装计划、分配明细和容量占用 | 订舱/柜务运营 |
+| 9 | 订舱/柜务运营 / Admin | 建订舱草稿、补资料、放舱，关联柜次并录入真实柜号 | 冻结订舱和运输快照，建立订舱需求与柜次分配关系 | 国内履约运营 |
+| 10 | 国内履约运营 / Admin | 核对预装清单并确认 | 固化预装快照，生成或开放国内 PDA 任务 | 国内 PDA |
+| 11 | 国内 PDA | 扫箱/整托拣货，批量提交，拍四步照片和铅封，完成装柜 | 计划 `COMPLETED`、入库单 `LOADED`，发布最终实装事件 | 报关/出仓运营 |
+| 12 | 报关运营 / Admin | 上传出口报关资料并完成报关 | 报关状态完成；系统自动尝试收敛国内出仓门禁 | 出仓运营/系统 |
+| 13 | 出仓运营 / Admin | 自动未收敛时，在柜次门禁面板点击“确认离仓” | 整柜进入已离仓事实，自动建船节点任务和 `DEPARTED_WAREHOUSE` | 船务/海外运营 |
+| 14 | 船务 / Admin、第三方 | 查看自动轨迹，缺失时按权限补录真实节点 | 实际节点单调推进；到 `PICKUP_READY` 后开放海外 PDA 候选 | 海外计划运营、海外 PDA |
+| 15 | 海外计划运营 / Admin | 在尾程订单按柜预览阻断项并确认转换入仓计划 | `PENDING_ASSIGNMENT → INBOUND_PLANNED`；逐票建计划并生成/绑定托盘资源 | 海外 PDA |
+| 16 | 海外 PDA | 选柜锁定，拍车牌/封签/开柜照片，确认签收 | 建立柜级收货会话，冻结实际接柜仓和操作员 | 海外 PDA |
+| 17 | 海外 PDA | FBA 按 SKU+箱数收货，OVERSEAS 按箱唛逐箱收货，完成整柜 | 尾程进入 `INBOUND_COMPLETED`；生成库存余额、仓位、托盘、流水并回写国内 | 海外排车运营 |
+| 18 | 海外运营 / Admin | 智能预排，选择托盘和车型，生成排车，维护车辆/预约 | 锁定托盘并生成 `PENDING_DEPARTURE` 排车单 | 海外运营、海外 PDA |
+| 19 | 海外运营 / Admin | 在发车前点击“转派送”，填写派送信息和费用 | 生成一张 `WAIT_OUTBOUND` 出库单，并按目的仓拆分 `WAIT_DELIVERY` 派送单 | 海外 PDA |
+| 20 | 海外 PDA | 扫托盘拣货、核平、完成拣货；待 `canDepart=true` 后点击发车 | 扫码事务扣减库存；发车后排车 `DEPARTED`、出库单 `OUTBOUNDED` | 派送运营/客户 |
+
+易用性和数据流转的改造目标、优先级与验收指标见[《头程下单到尾程出库流程易用性与数据流转优化方案》](头程下单到尾程出库流程易用性与数据流转优化方案.md)。
+
+## 2. 角色、终端与职责
+
+| 角色 | 使用终端 | 主要职责 |
+|---|---|---|
+| 企业订单操作员 | Client | 新建/导入头程订单、保存草稿、提交、查看入仓码、查看与确认已发送费用 |
+| 平台订单运营 | Admin | 审核订单、修订允许修改的申报信息、查看统一订单主状态 |
+| 国内仓操作员 | Admin/测量设备 | 收货、尺寸测量、称重图片、OCR 校正、测量提交 |
+| 国内履约运营 | Admin | 计费、分柜、模拟柜、订舱、预装、报关、国内出仓 |
+| 国内 PDA 操作员 | 国内 PDA | 普通箱码拣货或一件代发整托拣货、装柜取证、铅封和最终完成 |
+| 海外履约运营 | Admin | 尾程订单、按柜转换入仓计划、预计到仓、排车、转派送、出库与派送单核对 |
+| 海外仓 PDA 操作员 | 海外 PDA | 柜号签收、卸柜入仓、排车拣货、普通/一件代发出库、发车 |
+| 企业客户 | Client | 查看本企业尾程/派送结果；不操作平台排车和 PDA 作业 |
+
+海外 PDA 操作员必须是平台内部 `OVERSEAS_WAREHOUSE_PDA_OPERATOR`，并且只绑定一个启用收货能力的实际海外仓。客户账号、平台普通管理员或国内 PDA 角色不能替代该身份作业。
+
+## 3. 开始前必须准备的基础资料
+
+### 3.1 客户与下单资格
+
+- 企业账号可登录，企业资料已由平台审核通过。
+- 当前用户具备创建、提交头程订单的权限。
+- 客户资金账户可用；草稿保存不校验资金，提交时实际余额小于 0 会被拒绝。
+- 国内收货仓、目的仓、物流渠道及需要使用的往来单位处于有效状态。
+
+### 3.2 国内履约资料
+
+- 价格簿、客户尺寸/计费规则已发布；缺少价格不应伪造费用。
+- 柜型、渠道、订舱代理、拖车供应商等主数据可用。
+- 国内 PDA 人员、仓库和设备已配置。
+
+### 3.3 海外履约资料
+
+- 实际海外收货仓必须为平台公共仓、类型 `OVERSEAS`、状态 `ACTIVE` 且启用 `RECEIVING`。
+- 仓内存在可用库位和实物托盘。
+- 海外 PDA 人员绑定上述唯一实际收货仓。
+- 排车所需车辆、司机、预约信息以及派送费用录入条件已准备。
+
+实际海外收货仓、国内来源仓、FBA/私人目的仓是三个不同概念，不能互相代填。
+
+## 4. 阶段一：客户头程下单与平台审核
+
+### 4.1 客户新建订单
+
+入口：Client → 头程订单。
+
+操作：
+
+1. 点击新建订单，选择运输方式、国内收货仓、渠道和目的类型。
+2. 按目的类型选择 FBA 仓、海外仓或填写私人地址；公共目的仓必须从有效主数据选择。
+3. 填写提货/送货信息、客户参考号、预计时间及备注。
+4. 录入至少一条货物明细，包含箱数、件数、重量、体积、SKU、品名等当前页面要求的字段。
+5. 一件代发必须提供可冻结的 SKU/箱内明细，不能在后续扫码阶段用货名猜测 SKU。
+6. 点击“保存草稿”，检查订单后再点击“提交订单”。
+
+批量下单可使用中文 XLSX 模板，最多 50 行。导入成功只生成草稿，不会自动提交；操作员仍需逐票检查并提交。
+
+系统结果：
+
+- 草稿为 `DRAFT`。
+- 提交成功后 Order 状态为 `SUBMITTED`，统一主状态展示为 `PENDING_REVIEW/待审核`。
+- 提交时生成并固定全局唯一 `inboundCode/入仓码`；草稿阶段没有入仓码。
+- 提交时重新校验企业资格、资金账户、仓库/目的仓和渠道；不能只相信页面下拉快照。
+
+### 4.2 平台审核订单
+
+入口：Admin → 统一订单/头程订单 → 待审核。
+
+操作：
+
+1. 用订单号、入仓码、客户或状态定位订单。
+2. 打开详情，核对客户申报、货物、渠道、国内收货仓和目的仓。
+3. 批量审核时先打开批量审核预览，逐票查看 `canApprove` 和阻断原因。
+4. 如需修订，只修改当前状态允许的平台申报字段；不得改客户、国内收货仓、订单号、入仓码，也不得增删或重排货物行。
+5. 点击审核通过。
+
+系统结果：
+
+- Order 进入 `APPROVED`。
+- Firstleg 幂等创建正式国内入库单，沿用提交时生成的入仓码。
+- 生成或补齐稳定箱码/箱唛映射；后续测量、国内 PDA 和跨区事件都复用这些事实。
+- 统一主状态进入 `WAIT_MEASURE/待测量数据`。
+
+操作门禁：待审核订单即使已经出现 Firstleg 准备中投影，统一列表仍必须显示待审核，不能绕过审核直接进入物理履约。
+
+## 5. 阶段二：国内收货、测量、计费与待分柜
+
+### 5.1 国内仓收货和测量
+
+入口：Admin → 入库管理/统一订单 → 测量；第三方测量设备按入仓码上传。
+
+操作：
+
+1. 仓库按入仓码定位入库单。
+2. 第三方设备或人工逐箱记录长、宽、高和箱数；第三方只能使用业务入仓码/箱码，不能传内部数据库 ID。
+3. 上传至少一张称重图片。
+4. 系统执行 OCR；操作员核对原始值、单位和置信度，必要时填写原因后人工修正。
+5. 确认全部有效称重图片，确保总重量大于 0。
+6. 提交测量审核；审核不通过时修正后重新提交，不能带病进入后续实物作业。
+
+系统结果：
+
+- 测量子流程可经历 `WAIT_MEASURE → MEASURING → MEASURE_PENDING`；审核结果、计费结果分别保存，不能混成一个状态字段。
+- 测量审核通过后，统一主状态进入 `WAIT_SPLIT/待分柜`。
+- 首张称重图片确认时，系统会尽力预留整票库位块；库位指引失败记录警告，但不能伪造成功资源。
+
+### 5.2 费用处理
+
+平台操作：
+
+1. 依据客户规则、渠道、目的仓和价格簿试算。
+2. 检查计费重量/体积、单价、附加费及费用明细。
+3. 必要时按权限调整计费量或费用明细，提交审核并发布。
+4. 将当前费用版本发送给客户。
+
+客户操作：Client 订单详情 → 费用信息 → 核对并确认当前已发送版本。
+
+当前主链口径：测量审核通过后即可进入 `WAIT_SPLIT`；费用是版本化的独立事实，不再阻断或回退主流程。客户确认和装柜完成同时满足后，费用版本最终冻结。不要再按旧文档把“发送费用”理解成唯一入库成功按钮。
+
+### 5.3 一件代发分支
+
+一件代发在测量审核后先进入 `WAIT_PALLETIZE`：
+
+1. 系统按预计托数预生成 `DP` 托盘码。
+2. Admin 打印托盘信息单；PDA 不负责连接打印机。
+3. 国内 PDA 逐箱扫描稳定箱码，清点箱内全部 SKU，并归入现场托盘。
+4. 逐托封托；参与订单的开放托盘必须全部完成。
+5. 全部箱数与实际参与托盘核平后进入 `WAIT_SPLIT`。
+
+一件代发托盘在后续智能装柜中是不可拆整托单元；不能按成员箱部分装柜或跳拣。
+
+## 6. 阶段三：分柜、订舱、国内 PDA 装柜与出仓
+
+### 6.1 建柜与排柜
+
+入口：Admin → 货柜管理 → 送柜报关/智能装柜。
+
+推荐操作顺序：
+
+1. 创建内部模拟柜，选择正式装柜仓、计划渠道组、柜型、容量和限重；系统生成稳定 `containerBookingId` 和 `cabinetNo`。
+2. 在智能装柜工作台按客户、入仓码、状态、到货日期等筛选候选。
+3. 人工加入或使用智能推荐，将入仓单/箱数分配到柜次。
+4. 核对容量、重量、渠道、同柜组和剩余箱数；按钮资格以服务端 `canAssign` 为准。
+5. 生成并维护订舱草稿，补齐提单号、船名、航次、ETD、ETA 等资料后放舱为 `RELEASED`。
+6. 港口取得真实柜号后，将模拟柜与已放舱订舱需求关联并录入 `containerNo`。
+7. 在预装详情核对全部明细并确认预装。
+
+允许待审核、待测量数据提前进入模拟排柜作为占位，但确认预装和启动真实 PDA 作业前，成员必须达到可履约状态。为了避免现有页面与后端历史口径差异，实际操作应在预装确认前补齐真实柜号；无论如何，最终装柜完成前必须有真实柜号。
+
+### 6.2 国内 PDA 拣货和装柜
+
+入口：国内 PDA → 拣货/装柜任务。
+
+普通散货：
+
+1. 领取柜次任务。
+2. 按稳定箱码逐箱扫描；一个有效箱码只代表一箱。
+3. 批量提交本次扫描；断网时不能正式提交，恢复后刷新服务端状态再重试。
+4. 未完成项可暂时挂起，但必须填写异常原因；未核平不能最终完成。
+
+一件代发：扫描托盘码或托盘内任一箱码定位整托，以 `PICK_PALLET` 整托确认，不得拆托拣货。
+
+装柜证据：
+
+- 空仓、半仓、满仓、锁仓四步照片；
+- 带有效铅封号的铅封证据；
+- 同类可追加，错误证据作废并保留审计，不硬删除历史。
+
+最终完成门禁：全部计划明细核平、五类有效证据齐全、铅封号存在且真实柜号已就绪。完成后装柜计划为 `COMPLETED`，来源入库单为 `LOADED`。
+
+### 6.3 出口报关与国内出仓
+
+入口：Admin → 货柜管理 → 柜次详情/国内出仓。
+
+当前整柜出仓门禁：
+
+| 门禁 | 要求 |
+|---|---|
+| 扣货 | 柜内入库单均未被扣货 |
+| 入库单 | 所有绑定入库单为 `LOADED` |
+| 装柜计划 | `COMPLETED` |
+| 国内 PDA | 拣货任务 `COMPLETED` |
+| 订舱 | 已放舱并分配当前柜次，状态 `RELEASED` |
+| 装柜证据 | 四步照片和有效铅封齐全 |
+| 出口报关 | 整柜报关 `COMPLETED` |
+
+拖车状态和独立船期当前只作为参考，不属于服务端硬门禁。出口报关完成后，系统会在全部门禁满足时自动尝试确认离仓；若未自动收敛，平台可在“国内出仓门禁”面板点击“确认离仓”。
+
+成功结果：
+
+- 整柜出仓状态进入 `WAITING_FOR_LOADING`（现有内部编码，业务含义是已确认离开国内仓）；
+- 只写一次整柜离仓历史；
+- 自动创建唯一船节点查询任务和第一条实际 `DEPARTED_WAREHOUSE`；
+- 尝试完成同订舱关联的国内拖车单；
+- 已产生实际离仓节点后不得撤销。
+
+## 7. 阶段四：海运节点、跨区尾程建单和海外入仓
+
+### 7.1 船节点推进
+
+船节点任务由国内出仓自动创建，不能由操作员另造一套。标准实际节点按以下顺序单调推进：
+
+`DEPARTED_WAREHOUSE → AT_ORIGIN_PORT → LOADED_ON_VESSEL → DEPARTED_ORIGIN_PORT → IN_TRANSIT → ARRIVED_DESTINATION_PORT → DISCHARGED_FROM_VESSEL → PICKUP_READY → PICKED_UP → EMPTY_RETURNED`
+
+规则：
+
+- 预计时间只增加预计事实，不推进最新实际节点。
+- 实际节点不能重复、回退或越权覆盖。
+- `PICKUP_READY` 是海外 PDA 待收柜的开放门禁。
+- 实际 `EMPTY_RETURNED` 后查询任务停止。
+
+平台可在 Admin → 船期信息/订舱详情/货柜详情查看，并在第三方数据缺失时按权限人工补录真实节点。
+
+### 7.2 跨区生成尾程订单
+
+国内装柜完成事件通过 Event Bridge 投递海外区域。当前正确结果是：
+
+- 按最终实装数据生成尾程订单和货物冻结快照；
+- 尾程订单状态为 `PENDING_ASSIGNMENT`；
+- 建立 `FIRST_LEG` 在途库存快照；
+- 保留来源订单、来源入仓码、柜号、目的类型、SKU/箱唛、头程托盘码和备注等事实；
+- 不自动创建海外入仓计划。
+
+若页面暂未出现，可等待异步事件收敛后刷新；不得直改海外数据库或手工伪造尾程订单。
+
+### 7.3 平台按柜转换海外入仓计划
+
+入口：Admin → 海外仓 → 尾程订单。
+
+操作：
+
+1. 在柜子工作台按柜号找到 `sourceContainerBookingId` 对应的整柜。
+2. 打开柜级详情，核对柜内所有客户、订单、来源入仓码、目的仓和预计到仓时间。
+3. 先执行“入仓计划预览”，查看按 FBA/一件代发/私人地址的分组、头程已有托数、海外补充托数、最终托数、阻断项和快照版本。
+4. 阻断项为零后确认转换；前端不能自行计算托数或逐票拼装计划。
+5. 转换成功后回到尾程订单/入库单核对每票独立计划、计划号、托盘码和实际接柜仓。
+
+系统规则：
+
+- 整柜锁定、重算、资源预留和逐票建计划是一次原子操作，重放不能生成第二批资源。
+- 尾程订单推进到 `INBOUND_PLANNED`。
+- 散货保留所有头程已有托盘码；海外计划托数更多时按同柜同 FBA 连续补码。
+- 一件代发严格沿用国内封托结果，不能在海外计划中随意改托数。
+- 预计到仓和来源入仓码是冻结事实，不允许人工改写。
+- 计划或真实托盘资源未齐时，海外 PDA 不能接柜。
+
+### 7.4 海外 PDA 柜号签收
+
+前置：船节点已到实际 `PICKUP_READY`，计划和资源完整，当前操作员绑定正确实际海外收货仓。
+
+入口：海外 PDA → 拆柜收货。
+
+操作：
+
+1. 在待卸货列表选择柜号，核对柜内所有入仓码、目的仓、托数和箱数。
+2. 锁定柜号；未完成前不能切换其他柜，其他操作员也不能抢占。
+3. 用真机依次拍摄车牌 `LICENSE_PLATE`、集装箱封签 `CONTAINER_SEAL`、开柜现场 `DOOR_OPEN`。
+4. 三类照片齐全后点击“确认签收并开始收货”。
+
+### 7.5 两种海外实收方式
+
+FBA：
+
+1. 选择 FBA 入仓码并扫描冻结 SKU。
+2. 扫描真实托盘码。
+3. 输入本次放入该托盘的箱数并确认。
+4. 可分多次操作，直至该入仓码待收箱数为 0；不得超收。
+
+OVERSEAS：
+
+1. 扫描最终实装冻结箱唛，系统自动定位所属入仓码。
+2. 扫描真实托盘码。
+3. 逐箱确认；不能用输入箱数代替逐箱扫码。
+4. 非本柜、未实装、已收或不存在的箱唛必须拒绝。
+
+完成整柜：所有入仓码 `pendingPackages=0` 后，点击“完成整柜入库”。系统同事务生成库存余额、仓位、流水和托盘事实，尾程主流程进入 `INBOUND_COMPLETED`，并通过 Outbox 回写国内卸柜完成事实。
+
+## 8. 阶段五：海外排车、PDA 拣货和尾程出库
+
+本节以普通 FBA/私人地址库存的排车出库为主链。暂扣订单不能进入排车或出库；其他同柜订单不受影响。
+
+### 8.1 平台创建排车
+
+入口：Admin → 海外仓 → 排车列表 → 智能预排。
+
+操作：
+
+1. 从真实已完成入仓的计划或已收托盘加载候选。
+2. 把托盘加入预排草稿；加入即锁定，移除或关闭草稿时释放。
+3. 选择车型并检查托位和重量。页面当前提示：大车 30 托/40000 LB，小车 15 托/10000 LB；最终仍以服务端校验为准。
+4. 点击“预排车”，生成正式排车单和正式托盘锁。
+5. 在排车列表点击“编辑”，维护车牌、司机、联系电话、车队、预计发车/到达时间、FBA 预约号和预约状态。
+6. 路线由已排托盘的目的 FBA 仓自动汇总，不能手工编造。
+
+初始排车状态为 `PENDING_DEPARTURE`。未开始且未生成出库单时可移除托盘或取消；取消会释放托盘锁。
+
+### 8.2 平台转派送
+
+入口：Admin → 海外仓 → 排车列表 → 转派送。
+
+可操作状态：`PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART`，但必须在 PDA 发车前完成。
+
+操作：
+
+1. 填写预计派送时间、派送方式、提货方式、装车类型。
+2. 按实际业务填写车队/快递、运单号、司机、电话、车牌、车型、车辆大小和预约账号。
+3. 填写派送费用；按业务条件填写装车费、买约费用和卖家姓名。
+4. 确认提交。
+
+系统结果：
+
+- 一张排车单生成一张车辆级出库单，状态 `WAIT_OUTBOUND`，类型 `DISPATCH_DELIVERY`。
+- 按目的 FBA 仓/私人地址拆成一张或多张派送单，初始状态 `WAIT_DELIVERY`。
+- 尾程订单记录出库单号、派送单号和对应子单状态。
+- 相同排车单重复操作返回既有结果，不能重复建出库单。
+
+### 8.3 海外 PDA 排车拣货
+
+入口：海外 PDA → 排车拣货。
+
+操作：
+
+1. 打开本仓排车任务，核对排车单、车辆、托盘、目的仓和计划箱数。
+2. 扫描托盘业务码；系统验证托盘属于当前排车、当前仓和当前客户库存位置。
+3. 确认本托箱数，重复直至全部托盘和箱数核平。
+4. 点击“完成拣货”。
+
+状态结果：
+
+- 首次成功扫码后任务进入 `PICKING`。
+- 全部托盘核平后 PDA 任务为 `COMPLETED`，排车单为 `READY_TO_DEPART`。
+- 库存扣减点是成功的 PDA 扫码拣货事务；发车只推进排车/出库事实，不得重复扣库存。
+
+### 8.4 海外 PDA 发车并完成尾程出库
+
+发车按钮只消费服务端返回的 `canDepart` 和 `departBlockReason`。必须同时满足：
+
+- 车辆信息完整；
+- PDA 拣货任务完成；
+- 所有托盘和箱数核平；
+- 排车单为 `READY_TO_DEPART`；
+- 平台已经“转派送”；
+- 关联出库单仍为 `WAIT_OUTBOUND`。
+
+点击发车后：
+
+- 排车单进入 `DEPARTED`，记录实际发车时间和已发箱数；
+- 车辆级出库单进入 `OUTBOUNDED`；
+- 释放排车托盘锁；
+- 后续派送单继续在 Admin/Client 流转，派送不在海外 PDA 完成。
+
+至此，“头程下单 → 尾程出库”主链完成。如果业务还要求末端签收，则继续在派送单上传签收资料，系统自动完成派送并向国内回写最终履约完成事实。
+
+## 9. 非普通排车出库的分支
+
+| 出库类型 | 如何进入 | PDA/系统终点 |
+|---|---|---|
+| 一件代发出库 | Admin 从已完成入仓且仍有可用 SKU/箱唛的库存位置创建；候选必须属于唯一客户和唯一海外仓 | 状态 `WAIT_PICK → PICKING → PICKED → OUTBOUNDED`；PDA 可逐箱，也可扫 DP 托盘码原子拣完整托剩余箱件 |
+| 换标出库 | PDA 换标完工、仓库复核、客户确认后；卡车分支进排车，自提/快递直接建出库单 | 客户确认前禁止出库；PDA 完成后出库单 `OUTBOUNDED` |
+| 仓储转运出库 | 客户申请，平台审核通过后生成待出库任务 | PDA 完成后转运单 `OUTBOUNDED`，尾程主单进入在途子状态 |
+| 退货出库 | 从退货箱/SKU 可用库存创建 | 按服务端冻结箱唛和 SKU 实际拣出，不能自由填库存来源 |
+| 派送异常退回 | 从原出库拣货事实选择可退明细 | 实收入真实托盘/库位，恢复库存后异常单完成、派送变 `RETURNED` |
+
+出库列表统一状态包括 `WAIT_PICK`、`PICKING`、`PICKED`、`WAIT_OUTBOUND`、`OUTBOUNDED`、`CANCELLED`。只有尚未执行的 `WAIT_PICK/WAIT_OUTBOUND` 可取消。
+
+## 10. 核心状态与业务编号对照
+
+### 10.1 主状态时间线
+
+| 阶段 | 关键状态 | 业务含义 |
+|---|---|---|
+| 客户下单 | `DRAFT` | 可编辑草稿，无入仓码 |
+| 客户提交 | `SUBMITTED` / `PENDING_REVIEW` | 已生成固定入仓码，待平台审核 |
+| 审核后 | `WAIT_MEASURE` | 国内正式入库单已建立，等待实测 |
+| 一件代发组托 | `WAIT_PALLETIZE` | 等待逐箱清点、组托和封托 |
+| 测量/组托后 | `WAIT_SPLIT` | 可进入真实分柜与预装 |
+| 国内作业 | `LOADING` | 国内 PDA 拣货/装柜中 |
+| 国内装柜完成 | `LOADED` | 装柜完成，但不等于国内离仓 |
+| 海外尾程建单 | `PENDING_ASSIGNMENT` | 事件已建尾程订单，尚未转换入仓计划 |
+| 海外计划完成 | `INBOUND_PLANNED` | 入仓计划和资源就绪 |
+| 海外入仓完成 | `INBOUND_COMPLETED` | 海外库存、仓位和流水已生成 |
+| 排车拣货完成 | `READY_TO_DEPART` | 待平台转派送/发车门禁收敛 |
+| 海外出库完成 | `OUTBOUNDED` / `DEPARTED` | 货已离开海外仓，进入派送阶段 |
+
+### 10.2 编号串联关系
+
+| 编号 | 谁生成 | 用途 |
+|---|---|---|
+| `orderNo` | Order | 客户头程订单号 |
+| `inboundCode` | Order 提交时 | 跨国内入库、装柜、海外尾程的稳定业务关联码 |
+| `containerBookingId` | Firstleg 建柜 | 柜级稳定内部业务身份，跨区事件和海外整柜聚合使用 |
+| `cabinetNo` | Firstleg 建模拟柜 | 平台可见柜次号 |
+| `containerNo` | 港口取得后录入 | 真实集装箱号，PDA 和船运现场识别使用 |
+| `loadingPlanId` | Firstleg 建柜/预装 | 国内预装、PDA 和装柜清单关联 |
+| `palletNo` | 国内/海外资源服务 | 现场托盘扫描身份；一件代发与散货生成规则不同 |
+| `planNo` | Lastleg 转换计划 | 海外入仓计划号 |
+| `dispatchNo` | Lastleg 预排 | 海外排车单号 |
+| `outboundNo` | Lastleg 转派送/独立出库 | 海外出库单号 |
+| `deliveryNo` | Lastleg 转派送 | 按目的仓拆分的派送单号 |
+
+页面不得用内部数据库 ID 代替这些业务编号。编号缺失时应显示“—”，不能拿别的单号冒充。
+
+## 11. 当前统一口径与旧文档差异
+
+1. 费用不再阻断待分柜。旧测量文档把“发送费用给客户”写成入库成功节点；当前 Firstleg 口径是测量审核通过后直接进入 `WAIT_SPLIT`，费用独立版本化。
+2. 跨区事件不自动建海外入仓计划。旧海外验收手册曾写“装柜完成事件直接生成入仓计划”；当前只生成 `PENDING_ASSIGNMENT` 尾程订单，平台必须按柜预览并确认转换。
+3. 国内出仓硬门禁不含拖车和独立船期。当前服务端硬门禁是未扣货、入库单 `LOADED`、装柜计划/PDA完成、订舱 `RELEASED`、装柜证据与出口报关完成；拖车和独立船期仅展示参考。
+4. 国内出仓既有自动收敛也保留人工入口。出口报关完成后系统会自动尝试确认；未收敛时平台可在柜次或国内出仓页手工确认，二者共享同一服务端门禁与幂等结果。
+5. 真实柜号最迟时点存在历史指引差异。当前代码允许在 `EDITING/LOADING` 补录，但最终 PDA 完成前必须存在；为避免页面入口差异，正式操作统一要求预装确认前补齐。
+6. 尾程主状态与子单状态分开。入仓后主流程固定在 `INBOUND_COMPLETED`，排车、出库、派送、换标和转运的精确状态保存在子单，不得互相覆盖。
+
+## 12. 异常处理和禁止绕过事项
+
+- 订单提交失败：先检查企业审核、资金账户、仓库/目的仓和渠道，不要通过保存草稿伪装已提交。
+- 测量失败：修正尺寸/称重证据后重新提交；未确认图片、总重为零和重复箱码不得放行。
+- 排柜失败：以 `canAssign`、剩余箱数、容量、同柜组和版本冲突原因处理，不从前端强塞分配。
+- 国内 PDA 版本冲突：刷新任务和库存快照；不能重复使用旧 token 或旧版本继续提交。
+- 国内出仓失败：逐项查看服务端门禁；不以人工改状态、改数据库或伪造船节点解决。
+- 跨区未建单：先检查事件 Outbox/Event Bridge/Inbox 和幂等结果；不手工补海外订单。
+- 海外 PDA 看不到柜：依次检查实际 `PICKUP_READY`、整柜计划资源、操作员绑定仓、柜是否被锁定。
+- 海外收货不平：按入仓码核对计划数、实收数、箱唛/SKU 和托盘；未核平不能完成整柜。
+- 排车不能发车：直接展示 `departBlockReason`，检查车辆、拣货核平、`READY_TO_DEPART` 和 `WAIT_OUTBOUND` 出库单。
+- 所有写操作都应携带服务端版本和幂等键；超时后先查结果，不能换新键盲目重复操作。
+- 不通过数据库直改、浏览器调用 internal 接口、跨客户 ID 或内部主键跳过正常业务流程。
+
+## 13. 一票到底的验收清单
+
+- [ ] 企业资料审核通过，提交时资金账户通过校验
+- [ ] 客户订单从草稿成功提交并生成唯一入仓码
+- [ ] 平台审核通过，正式国内入库单和箱码事实已建立
+- [ ] 尺寸、称重、OCR 修正和测量审核完整
+- [ ] 普通订单进入 `WAIT_SPLIT`；一件代发先完成组托再进入 `WAIT_SPLIT`
+- [ ] 模拟柜、订舱、真实柜号、预装计划和订单分配关系一致
+- [ ] 国内 PDA 全部拣货，五类证据和铅封齐全
+- [ ] 装柜计划 `COMPLETED`，来源入库单 `LOADED`
+- [ ] 整柜出口报关完成，国内出仓成功并生成船节点任务
+- [ ] 实际船节点到 `PICKUP_READY` 后海外 PDA 才看到柜号
+- [ ] 海外只先生成 `PENDING_ASSIGNMENT` 尾程订单，平台按柜转换计划成功
+- [ ] 海外 PDA 三类签收照片齐全，FBA/OVERSEAS 按正确模式实收
+- [ ] 整柜所有入仓码核平，尾程主流程 `INBOUND_COMPLETED`
+- [ ] 库存余额、托盘、库位和流水一致，国内收到卸柜回写
+- [ ] 排车托盘来源真实且未暂扣，车辆和预约信息完整
+- [ ] 平台转派送生成一张 `WAIT_OUTBOUND` 出库单和按目的仓拆分的派送单
+- [ ] 海外 PDA 拣货核平，服务端 `canDepart=true`
+- [ ] 发车后排车单 `DEPARTED`、出库单 `OUTBOUNDED`，库存与出库数量守恒
+
+## 14. 主要事实来源
+
+- `docs/业务快速索引.md`
+- `docs/订单与客户/订单与客户头程订单闭环设计.md`
+- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
+- `docs/国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md`
+- `docs/海外仓业务/README.md`
+- `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
+- `baiyue-firstleg/order/AGENTS.md`
+- `baiyue-firstleg/firstleg/AGENTS.md`
+- `baiyue-firstleg/lastleg-service/AGENTS.md`
+- `apps/admin-web/src/modules/overseas-warehouse/AGENTS.md`
+- `apps/pda-overseas-uniapp/AGENTS.md`
+
+本文用于统一业务操作和评审口径；接口字段、权限码、并发版本和错误码仍以对应 Controller、DTO、OpenAPI 与服务端状态机为最终依据。

头程下单到尾程出库流程易用性与数据流转优化方案.md

@@ -0,0 +1,463 @@
+# 头程下单到尾程出库流程易用性与数据流转优化方案
+
+> 目标：在现有端到端流程已经走通的基础上，降低学习成本、重复录入、跨页面查找和交接等待，让每个岗位始终知道“货在哪里、现在由谁处理、为什么不能继续、下一步做什么”。  
+> 基线流程：见[《头程下单到尾程出库全流程操作手册》](头程下单到尾程出库全流程操作手册.md)。  
+> 边界：本方案优先复用现有 Admin、Client、国内/海外 PDA、Gateway、Order、Firstleg、Lastleg 和 Warehouse 能力，不新建平行状态机，不引入第二套订单或跨区同步写链路。
+
+> 当前状态：现状全景和六阶段基线已经完成；本文进入分阶段业务评审，暂不直接作为实施基线。AI 分析和评审记录统一遵循[《头程到尾程 AI 流程优化上下文包》](头程到尾程AI流程优化上下文包.md)，逐项决定保留、合并、自动化、简化或删除。
+
+## 1. 优化后的成功标准
+
+流程是否“能走通”只代表功能闭环；易用性优化完成后还应同时达到：
+
+1. 操作员进入一个单据后，10 秒内能回答当前阶段、下一动作、责任岗位和阻断原因。
+2. 同一业务事实只录一次，后续阶段自动带出并注明来源、冻结时间和是否可修改。
+3. 每次操作完成都明确展示“产生了什么结果、下一步去哪里”，并提供可点击入口。
+4. 异步跨区操作不再表现为“点完没反应”，页面可见待投递、处理中、成功或失败。
+5. PDA 扫错时直接说明“扫到了什么、为什么不匹配、正确应该扫什么”，而不是只返回错误码。
+6. 列表默认突出需要当前岗位处理的记录，不要求用户同时理解全部内部状态。
+7. 批量操作在提交前有预览，提交后有逐项结果和可重试项，不能整批静默失败。
+8. 所有阶段以服务端 `nextAction/allowedActions/blockers` 为准，页面不自行猜测资格。
+9. 数据跨服务、跨区域流转可追踪、可重放、可对账，但业务人员不需要接触内部 ID。
+
+## 2. 当前主要问题
+
+### 2.1 操作层问题
+
+| 问题 | 当前表现 | 业务影响 |
+|---|---|---|
+| 页面按模块拆开，缺少一票到底视角 | 订单、测量、货柜、出仓、船节点、尾程、入仓、排车、出库分别查询 | 操作员反复复制订单号、入仓码和柜号，交接依赖群消息 |
+| 状态多但不回答下一步 | 页面显示 `WAIT_SPLIT`、`PENDING_ASSIGNMENT`、`READY_TO_DEPART` 等编码映射 | 新员工知道状态名但不知道该去哪个菜单、找哪个岗位 |
+| 阻断原因与修复入口分离 | 门禁面板告诉用户缺报关、缺车辆或缺计划，但需要自行找页面 | 处理时间长，容易重复点击同一操作 |
+| 操作成功提示过轻 | 常见结果只有“保存成功”或“提交成功” | 用户不清楚是否建了入库单、出库单、派送单或跨区任务 |
+| 相同信息重复填写 | 车辆、司机、目的仓、箱数、费用来源、预计时间在不同阶段重复录入 | 容易产生快照不一致和人工抄错 |
+| 异步流转不可见 | 国内完成后海外页面暂时没有数据，只能等待刷新 | 用户误判失败，重复操作或要求技术人员查库 |
+| PDA 错误反馈缺现场语义 | 扫错托盘/箱唛时只知道失败，不知道资源实际归属 | 仓库人员需要退出任务或电话询问后台 |
+| 批量能力缺少统一反馈 | 批量导入、审核、排柜、计划转换各自反馈形式不同 | 错误定位和重试成本高 |
+
+### 2.2 数据流问题
+
+| 问题 | 风险 |
+|---|---|
+| 交易状态、履约状态、费用状态、子单状态被用户当成一个状态理解 | 页面互相覆盖或展示“倒退”，实际只是不同状态维度 |
+| 同一字段在多个服务留有快照，但页面不显示来源 | 用户无法判断当前值来自客户申报、实测、计划还是实际作业 |
+| 跨区事件处理结果缺少业务可见回执 | 事件已发送、消费失败、资源生成失败等场景只能从日志判断 |
+| 单据间只有内部 ID 关联，缺少统一业务链查询 | 客服无法用订单号/入仓码直接查到柜、尾程计划、排车和出库 |
+| 自动动作和人工动作混在同一历史里 | 无法快速判断是系统自动收敛、第三方回传还是人工补录 |
+| 同步调用失败与业务失败提示不分 | 操作员不知道应补资料、刷新版本还是等待系统重试 |
+| 分页列表承担跨柜/跨客户聚合 | 容易出现只看当前页就做整柜判断的问题 |
+
+## 3. 总体产品方案
+
+### 3.1 一票到底进度条
+
+在 Client 订单详情和 Admin 统一订单详情顶部增加同一套业务阶段条：
+
+```text
+订单提交 → 国内入库 → 测量/组托 → 待分柜 → 国内装柜 → 国内出仓
+→ 海运在途 → 海外计划 → 海外入仓 → 海外排车 → 海外出库 → 派送完成
+```
+
+每个节点只展示四种用户可理解状态：未开始、处理中、已完成、异常。点击节点进入对应详情或只读摘要。
+
+阶段条不能根据前端已有字段自行拼装，应由服务端聚合返回：
+
+- `currentStageCode/currentStageName`：当前主阶段；
+- `stageStatus`：阶段状态；
+- `nextActionCode/nextActionName`：下一动作；
+- `ownerRole/ownerName`：当前责任岗位；
+- `blockers[]`：阻断码、中文原因、修复建议和跳转目标；
+- `relatedDocuments[]`：相关业务单号、状态和详情入口；
+- `lastChangedAt`：最后业务变化时间；
+- `asyncState`：无异步任务、处理中、成功、失败待重试。
+
+实现上优先扩展现有统一订单聚合、柜级 overview 和尾程柜级 summary，不新建另一套可写流程引擎。
+
+### 3.2 “现在做什么”任务卡
+
+列表第一列保持“操作”，并在状态旁增加任务卡：
+
+- 当前需要我做：例如“审核订单”“补称重图片”“确认预装”“转换海外入仓计划”“维护车辆”“先转派送”。
+- 为什么：显示最多两条最高优先级阻断原因。
+- 去处理：直接深链到目标弹窗、页签或 PDA 作业。
+- 谁负责：当前角色无权限时显示责任岗位和只读说明，不显示无效按钮。
+- 完成期限：按业务 SLA 显示剩余时间或超时标记。
+
+服务端必须返回稳定动作编码；页面只负责中文展示和路由，不根据状态组合重新推导动作。
+
+### 3.3 操作完成回执
+
+所有关键写操作采用一致的结果反馈，而不是单纯 Toast：
+
+| 当前操作 | 回执必须告诉用户 |
+|---|---|
+| 提交订单 | 订单号、入仓码、当前状态、下一步由平台审核 |
+| 审核通过 | 已生成的国内入库单/箱码、下一步国内仓测量 |
+| 测量审核通过 | 是否进入待分柜或待组托、费用是否已生成 |
+| 预装确认 | PDA 任务是否已生成、缺真实柜号时的明确提醒 |
+| 国内装柜完成 | 装柜结果、报关状态和国内出仓门禁摘要 |
+| 国内出仓 | 船节点任务是否创建、第一条节点和海外异步建单状态 |
+| 海外计划转换 | 计划数量、托盘数量、资源结果和 PDA 是否可接柜 |
+| 海外整柜入仓完成 | 实收箱数、库存/托盘/库位结果和下一步排车入口 |
+| 转派送 | 出库单号、按目的仓拆分的派送单号、发车尚缺条件 |
+| PDA 发车 | 已出库箱数、排车单/出库单终态和后续派送入口 |
+
+回执应支持“查看结果”和“继续处理下一票”，避免保存后返回一个没有上下文的列表。
+
+## 4. 分阶段易用性优化
+
+### 4.1 客户下单
+
+现状操作：一个较长表单或 XLSX 导入，保存草稿后再提交。
+
+优化：
+
+- 用“运输与仓库 → 货物 → 提货/目的信息 → 确认提交”四步向导组织表单。
+- 顶部常驻草稿保存状态；字段失焦自动保存草稿，但最终提交仍由用户明确点击。
+- 选择目的类型后只展示相关字段：FBA 显示 FBA 仓，海外仓显示公共目的仓，私人仓显示地址。
+- 仓库、渠道、目的仓下拉显示业务名称、代码、地址和可用状态，不展示内部 ID。
+- 提交前集中展示校验清单，点击错误可滚动到对应字段。
+- 批量导入先预览“可创建、需修正、重复”三组；错误报告可按原行号下载，修正后只重试失败行。
+- 提交成功回执直接展示入仓码，并提供复制、打印箱唛和查看订单进度入口。
+
+数据优化：客户端只提交用户输入；仓库名称、地址、渠道名称和客户归属由服务端验证后冻结快照，避免客户端抄写。
+
+### 4.2 平台订单审核
+
+现状操作：列表定位，打开详情或批量预览后审核。
+
+优化：
+
+- 默认进入“待我审核”，按提交时间和加急程度排序。
+- 列表直接展示入仓码、目的类型、目的仓、渠道、箱数/体积/重量和阻断摘要。
+- 批量预览用“可通过/需补资料/系统异常”分组；只允许勾选可通过项。
+- 修改客户申报时做前后对比，标出会影响渠道、计价和排柜的字段。
+- 审核通过后自动跳转“下一票”或进入本票进度页，不要求重新筛选。
+
+数据优化：审核只推进 Order 权威状态；Firstleg 建单结果通过明确回执返回。Firstleg 暂时不可用时显示“审核已提交/建单待收敛”或失败原因，不能把部分成功伪装为整体成功。
+
+### 4.3 国内收货、测量与费用
+
+现状操作：按入仓码查询，测量和称重分多次录入，费用在另一工作区处理。
+
+优化：
+
+- 提供“扫码入仓码进入本票”入口，落地后固定显示客户、订单、目的仓和应收箱数。
+- 将尺寸、称重、图片、审核和库位块放在同一作业页的连续步骤中。
+- OCR 列表突出低置信度、单位异常和重复图片；批量确认高置信度结果。
+- 每条实测数据展示“客户申报值 vs 当前实测值 vs 计费采用值”，差异超阈值自动提示。
+- 审核不通过必须选择标准原因，可一键生成待修正任务；修正后回到原审核人队列。
+- 费用卡明确标注“费用处理不阻断待分柜”，避免运营等待费用后才排柜。
+- 客户收到费用后在订单进度中直接确认，无需进入独立财务菜单寻找。
+
+数据优化：尺寸原始值、修正值、计费值分字段保存；页面必须显示来源，禁止覆盖原始数据。费用用版本号关联测量快照，不复制一套无法追溯的合计。
+
+### 4.4 分柜、订舱和预装
+
+现状操作：在模拟柜、智能装柜、订舱和预装详情之间切换。
+
+优化：
+
+- 建立柜级工作台，顶部固定显示柜次号、真实柜号、订舱、渠道、仓库、容量、重量和下一动作。
+- 左侧候选、右侧已装计划保持筛选和滚动位置；加入后即时显示容量/重量变化。
+- 候选行直接说明不可加入原因，例如“待审核占位可加入，但暂不能确认预装”。
+- 同柜组、一件代发整托用不可拆分卡片展示，避免用户误以为可按行拆分。
+- 订舱放舱、柜次关联、真实柜号、预装确认形成同页检查清单。
+- 真实柜号未填时提供醒目待办；正式操作口径统一在预装确认前补齐。
+- 确认预装前显示最终成员、箱数、托盘、容量、重量、费用重算影响和将生成的 PDA 任务。
+
+数据优化：所有柜级动作使用稳定 `containerBookingId`，`cabinetNo/containerNo` 只作为业务展示身份。预装预览必须来自服务端完整柜级结果，不能使用当前分页数据拼装。
+
+### 4.5 国内 PDA 装柜
+
+现状操作：领取任务、逐箱或整托扫描、本地形成草稿、批量提交、上传证据并完成。
+
+优化：
+
+- 首页默认显示当前仓、当前任务、已扫/应扫、异常数和网络状态。
+- 普通箱、一件代发托盘使用不同颜色和提示音，避免将整托按箱扫描。
+- 扫描成功即时显示货物、入仓码、目标柜和累计数；错误显示扫描对象实际归属。
+- 批量提交前展示新增、重复、错柜和待处理异常四类统计。
+- 五类证据使用固定槽位和进度 `0/5…5/5`；铅封照片和铅封号在同一步完成。
+- 最终完成页只展示服务端门禁，缺哪项就提供对应操作入口。
+- 网络中断保留本地扫描草稿和同一幂等键；恢复后先对账服务端已接收项，再允许重试。
+
+数据优化：箱码、托盘码、柜次和任务全部由服务端解析归属；PDA 不提交客户或猜测仓库范围。批量响应返回逐项结果及服务端最新任务版本。
+
+### 4.6 报关和国内出仓
+
+现状操作：装柜完成后在报关、柜次详情或国内出仓页处理。
+
+优化：
+
+- 柜次详情新增“离仓准备度”，用 7 个门禁卡片显示已完成/阻断。
+- 每个阻断卡片提供深链：去解除扣货、查看 PDA、补证据、完成订舱、处理报关。
+- 明确标注拖车和独立船期“仅供参考，不阻断国内出仓”。
+- 报关完成后的自动确认展示为“系统正在确认离仓”；自动失败时才开放人工处理，并显示失败原因。
+- 离仓成功回执展示船节点任务号和异步海外建单状态。
+
+数据优化：门禁由 Firstleg 整柜锁定重算。页面不缓存门禁结论；执行前后都读取最新版本。自动与人工确认复用同一命令和幂等语义。
+
+### 4.7 船节点和跨区建单
+
+现状操作：多个页面可查看船节点；跨区建单需要等待刷新。
+
+优化：
+
+- 柜级时间线同时展示预计节点、实际节点、异常和数据来源，预计/实际视觉区分。
+- `PICKUP_READY` 节点旁明确显示“海外 PDA 已开放/尚未开放”。
+- 增加跨区处理卡：国内事件已生成、已投递、海外已接收、尾程订单已生成、资源待转换。
+- 超过预期时间仍未建单时，平台可查看业务化失败原因并触发受控重试；不能直接补数据。
+- 同一柜多客户时用柜级聚合显示事件状态，再进入每票结果，避免逐票判断整柜完成。
+
+数据优化：跨区状态使用 `eventId + aggregateId + schemaVersion + payloadHash` 追踪。国内只发布事实，海外只消费并幂等建单；禁止跨区同步双写数据库。
+
+### 4.8 海外入仓计划转换
+
+现状操作：按柜查看、预览、处理阻断后确认转换。
+
+优化：
+
+- 柜级卡片直接显示订单数、待建计划数、资源待补数、预计到仓和准备度。
+- 转换弹窗用三栏对比“头程已有托数、海外补充托数、最终托数”。
+- 阻断项按可操作性排序，并提供修复入口；例如缺预计到仓、目的仓异常、托盘资源失败。
+- 转换后展示逐票计划结果及托盘码，支持只重试 `resourcePendingPlanCount` 指向的资源异常。
+- 已转换柜仍可查询，但主按钮改为“查看/维护计划”，避免用户误以为要重复转换。
+
+数据优化：预览返回 `snapshotVersion/snapshotHash`；提交只回传该快照标识和明确选择。服务端锁柜重算，避免页面停留期间数据变化导致错建计划。
+
+### 4.9 海外 PDA 接柜入仓
+
+现状操作：选择柜、三类照片、按两种模式实收、完成整柜。
+
+优化：
+
+- 待收柜按可作业、未到 `PICKUP_READY`、资源未齐分组；后两组只读显示原因。
+- 进入柜后顶部固定显示柜号、当前操作员、开始时间、总计划/实收/待收。
+- 三类照片采用顺序引导，可重拍但保留审计；完成后自动进入收货，不返回列表。
+- FBA 页只显示“SKU + 本次箱数”，OVERSEAS 页只显示“箱唛逐箱”，从交互上消除模式混用。
+- 扫托盘后显示托盘已含入仓码和剩余容量，合托时提示来源组成。
+- 整柜完成前用入仓码列表标红未核平项，点击直接继续收货。
+- 完成回执显示库存、托盘、库位和国内回写状态。
+
+数据优化：柜级会话只绑定物理柜和实际接柜仓；每票实收、库存和托盘组成仍按客户隔离。PDA 不上传客户 ID 或仓库 ID。
+
+### 4.10 海外排车、转派送和出库
+
+现状操作：智能预排、编辑车辆、转派送、PDA 拣货、发车。
+
+优化：
+
+- 排车候选默认只显示可用库存，暂扣、换标未确认、已锁定的托盘直接说明不可选原因。
+- 预排草稿常驻显示托数、箱数、重量、目的仓、车型容量和超限值。
+- 加入/移除托盘时即时显示锁状态；离开未提交草稿时二次确认并释放锁。
+- 编辑排车时从车辆主数据带出车牌、司机、电话和车队，可覆盖的字段明确标识。
+- “转派送”放在排车详情主流程位置，不藏在更多菜单；未转派送时 PDA 发车页显示平台待办。
+- 转派送自动带出排车、车辆、目的仓、箱数和预约资料，只要求补充缺失字段及费用。
+- 提交前预览将生成的一张出库单和按目的仓拆分的派送单。
+- PDA 拣货页固定显示 `canDepart`；未满足时将服务端阻断原因翻译为动作提示。
+- 发车成功回执显示出库单已完成、库存扣减数、派送单清单和下一责任岗位。
+
+数据优化：排车、出库、派送是三张单据，各自状态独立；转派送只创建一次。库存扣减发生在 PDA 成功扫码事务，发车只推进排车和出库状态，防止重复扣减。
+
+## 5. 数据归属与流转优化
+
+### 5.1 权威数据归属
+
+| 数据 | 权威服务 | 下游使用方式 |
+|---|---|---|
+| 客户、账号、角色、仓库绑定 | IAM/Auth | Token 和服务端身份校验，不接受页面自报客户范围 |
+| 头程订单、客户申报、订单交易状态 | Order | Firstleg 使用版本化事件/内部 DTO，不反向覆盖客户申报 |
+| 国内入库、实测、费用快照、柜次、装柜、出仓、船节点 | Firstleg | Admin/PDA 读写正式 API；向海外发布最终实装事实 |
+| 国内/海外公共仓库主档 | Warehouse | 其他服务按 `warehouseId` 引用并冻结必要快照 |
+| 海外库位、实物托盘和资源锁 | Warehouse Overseas | Lastleg 使用内部资源接口，不复制第二套仓库主档 |
+| 尾程订单、海外计划、库存、排车、出库、派送 | Lastleg | Admin/Client/海外 PDA 经海外 Gateway 访问 |
+| 文件 | File | 业务服务只保存已校验文件 ID 和业务归属 |
+| 国内财务主账 | Finance | 海外费用通过事件入池，不跨区同步改钱包 |
+
+### 5.2 业务主键链
+
+对用户可见的链路检索顺序统一为：
+
+```text
+orderNo / inboundCode
+  → cabinetNo / containerNo
+  → tailOrderNo / planNo
+  → palletNo
+  → dispatchNo
+  → outboundNo
+  → deliveryNo
+```
+
+建议所有详情页提供“关联单据”侧栏，允许用任意一个业务号跳到上游和下游。内部数据库 ID 只留在接口和诊断信息中，不作为页面回退编号。
+
+### 5.3 快照来源标识
+
+页面展示容易混淆的字段时增加来源标签：
+
+| 字段 | 可能来源 | 页面要求 |
+|---|---|---|
+| 箱数、重量、体积 | 客户申报、仓库实测、国内实装、海外实收 | 同时展示当前采用值与来源，历史值可展开 |
+| 仓库/目的仓 | 下单选择、柜级计划、实际接柜仓 | 名称旁标注“国内来源仓/实际接柜仓/FBA目的仓” |
+| 托数 | 头程推荐、头程已有、海外补充、海外最终 | 转换预览分别展示，不把补充数写成最终总数 |
+| 预计/实际时间 | 客户期望、订舱 ETA、预计到仓、实际到仓 | 用不同字段和标签，不用创建时间回退 |
+| 状态 | 主流程、审核、费用、子单 | 分区展示，不用子单状态覆盖主状态 |
+
+### 5.4 异步事件可观测
+
+每个重要异步交接保留统一回执：
+
+- 事件名称、业务单号和来源阶段；
+- `eventId`、版本、发生时间、投递时间、接收时间；
+- 当前状态：待发送、发送中、已接收、已处理、失败待重试、永久失败需人工；
+- 重试次数和最近失败的业务化原因；
+- 下游生成的业务单号；
+- 是否允许受控重试。
+
+业务页面只展示业务化摘要；`requestId/traceId/eventId` 放在“诊断信息”中供技术支持复制。
+
+### 5.5 一致性规则
+
+1. 写操作携带 `expectedVersion` 和幂等键；版本冲突必须刷新，不能由前端自动覆盖。
+2. 同一业务操作超时后先查幂等结果；不能自动换新键重复提交。
+3. 跨服务写入使用本地事务 + Outbox/Inbox，不做国内、海外数据库分布式双写。
+4. 聚合页只做读模型，不成为新的权威数据源。
+5. 计划、门禁和转换必须基于完整柜级/任务级查询，不能用当前分页记录判断整体完成。
+6. 自动动作与人工动作使用同一服务命令，但历史记录明确 `SYSTEM/USER/THIRD_PARTY` 来源。
+7. 下游快照只在规定时点冻结；上游主数据之后变化不静默覆盖历史单据。
+
+## 6. 共性交互规范
+
+### 6.1 状态展示
+
+- 主标题用中文业务状态，稳定编码放在悬浮说明或诊断区。
+- 每页最多突出一个主状态；审核、费用、库存和子单状态分组展示。
+- “等待系统处理”和“等待人工处理”使用不同颜色和图标。
+- 终态不继续显示无效主按钮。
+
+### 6.2 按钮与门禁
+
+- 主按钮文案使用业务结果，例如“确认离仓”“转换整柜入仓计划”“完成整柜入仓”“转派送并生成出库单”。
+- 禁用按钮必须能查看原因；有修复入口时直接跳转。
+- 危险或不可逆操作在确认框中展示影响范围、将生成/冻结的单据和是否可撤销。
+- 批量操作先预览，提交后逐项回执。
+
+### 6.3 搜索与定位
+
+- 所有跨阶段列表至少支持订单号、入仓码、柜次号和真实柜号中的适用项。
+- 海外阶段继续支持计划号、托盘号、排车单号、出库单号和派送单号。
+- 最近搜索和筛选在返回列表时保留。
+- 扫码字段自动识别业务码类型；无法识别时提示允许的码，而不是当作普通关键词无结果。
+
+### 6.4 错误反馈
+
+错误消息统一包含：发生了什么、为什么、用户现在能做什么。示例：
+
+```text
+暂不能发车：平台尚未完成“转派送”，当前排车还没有待出库单。
+请联系海外运营在排车详情完成转派送后刷新本页。
+```
+
+不要向业务用户直接展示内部数据库 ID、SQL 异常或只有 `A0409` 的提示。业务码、requestId 和 traceId 收在可复制的诊断详情中。
+
+## 7. 优先级建议
+
+### P0：先解决“找不到下一步”和“数据是否流转成功”
+
+1. 在统一订单、柜次、尾程订单、排车详情增加当前阶段、下一动作、责任岗位、阻断原因。
+2. 国内出仓、跨区建单、海外计划转换、转派送和发车增加标准操作回执。
+3. 所有门禁项增加修复深链。
+4. 增加跨区事件业务状态卡，覆盖国内装柜到海外尾程建单、海外卸柜到国内回写。
+5. 海外 PDA 发车严格展示 `canDepart/departBlockReason`；错误改为现场可执行文案。
+6. 转派送提交前预览出库单和派送单，成功后直接展示业务单号。
+7. 统一关联单据侧栏和业务编号全链搜索。
+
+P0 不改变核心状态机，主要是聚合查询、反馈和导航，风险相对较低。
+
+### P1：减少重复输入和跨页面操作
+
+1. 客户下单四步向导、自动保存草稿和集中校验。
+2. 审核、测量、排柜、海外计划的批量预览与逐项回执统一。
+3. 柜级工作台整合订舱、真实柜号、预装、PDA、报关和出仓准备度。
+4. 海外收货完成后直接提供“查看库存/创建排车”动作。
+5. 排车编辑从车辆主数据带出司机、电话和车队；转派送复用排车快照。
+6. PDA 扫描反馈增加实际归属、错误对象和恢复动作。
+7. 费用确认嵌入订单进度，不要求客户跨菜单寻找。
+
+### P2：用数据持续优化效率
+
+1. 建立阶段耗时、等待耗时、返工率和阻断原因看板。
+2. 根据历史到仓和处理耗时做 SLA 预警，但不自动改业务事实。
+3. 智能推荐下一批可审核、可排柜、可计划、可排车记录。
+4. 对重复出现的扫码错误、计划资源失败和跨区失败生成问题趋势。
+5. 在保持服务端门禁的前提下，优化默认值和批量操作策略。
+
+## 8. P0 交付拆分
+
+| 交付包 | 前端范围 | 后端范围 | 验收重点 |
+|---|---|---|---|
+| A. 统一进度与下一动作 | Client 订单详情、Admin 统一订单详情 | Order/Firstleg 聚合返回阶段、动作和阻断 | 同一订单两端阶段一致，权限不同但事实一致 |
+| B. 柜级离仓准备度 | Admin 货柜详情、国内出仓 | Firstleg 复用现有柜级 gate/overview | 7 个门禁实时、可深链、自动/人工结果一致 |
+| C. 跨区回执 | Admin 柜次和尾程柜级工作台 | Firstleg Outbox、Event Bridge、Lastleg Inbox 只读聚合 | 能区分待发送、已接收、处理失败和成功建单 |
+| D. 海外计划转换体验 | Admin 尾程订单 | Lastleg 预览/转换响应补充业务化 blockers 和结果 | 不重复建计划，资源异常可定向重试 |
+| E. 排车到出库回执 | Admin 排车、出库、派送详情 | Lastleg 返回出库/派送拆分结果及下一门禁 | 转派送和发车后单号、状态、数量立即可核对 |
+| F. PDA 错误可执行化 | 国内/海外 PDA | Firstleg/Lastleg 错误响应补充稳定原因码和建议动作 | 扫错箱/托盘、版本冲突、未转派送均能现场恢复 |
+
+每个交付包独立上线，但必须复用同一状态和动作编码，不能各页面自行定义一套中文判断。
+
+## 9. 验收指标
+
+### 9.1 效率指标
+
+- 新员工在不查技术文档的情况下完成一票主链关键操作的成功率。
+- 每票从提交到完成审核、测量、排柜、海外计划、排车的人工点击数。
+- 订单号/入仓码在不同页面重复复制粘贴次数。
+- 从看到阻断到进入正确修复页面的平均时间。
+- 批量操作失败后定位具体失败记录的时间。
+
+### 9.2 质量指标
+
+- 重复提交产生重复单据数必须为 0。
+- 跨区事件超过 SLA 未收敛但页面仍显示成功的次数必须为 0。
+- 页面自行推导动作与服务端 `allowedActions` 不一致的次数必须为 0。
+- 因重复录入导致的仓库、目的仓、车辆、箱数不一致数量。
+- PDA 错扫后需要后台或技术人员介入才能恢复的比例。
+
+### 9.3 建议目标值
+
+首轮上线前先采集两周基线，再确认具体下降比例。若当前没有埋点，P0 同步补充：页面进入、主按钮点击、阻断码、操作结果、耗时、回退/重试、跨区收敛时间。埋点只记录业务编码和阶段，不记录密钥、Token 或客户敏感明细。
+
+## 10. 关键验收场景
+
+1. 客户提交订单后立即看到入仓码、待审核和下一责任人。
+2. 审核员打开待审核列表，无需进入详情即可识别可批量通过和需补资料订单。
+3. 测量审核完成后，页面明确显示已进入待分柜且费用可继续独立处理。
+4. 柜次缺报关时，“确认离仓”不可执行，并能一键进入报关区域。
+5. 国内离仓后，页面可见跨区事件进度；海外建单后自动出现尾程订单号。
+6. 海外计划转换前清楚看到头程已有托盘和海外补充托盘，重复提交不重复建资源。
+7. 海外 PDA 扫错柜外箱唛时，提示实际不属于当前柜且库存零变化。
+8. 海外入仓完成后，操作员可直接查看库存或进入排车，不需要重新搜索。
+9. 未转派送时 PDA 明确提示平台应做的动作；转派送完成后刷新即可发车。
+10. 发车成功回执同时展示排车 `DEPARTED`、出库 `OUTBOUNDED` 和各派送单号。
+11. 任一页面用入仓码搜索，都能进入关联单据侧栏查看上游和下游业务号。
+12. 版本冲突、网络超时和幂等重放均不会产生重复订单、计划、托盘、出库或派送单。
+
+## 11. 不建议采用的做法
+
+- 不新建独立“全流程状态表”作为新的可写权威；使用现有权威状态聚合展示。
+- 不让前端通过状态字符串组合推导写资格；服务端返回下一动作和门禁。
+- 不为了页面即时显示而跨区同步写海外数据库。
+- 不把所有业务状态压缩成一个字段，继续区分主流程、审核、费用、库存和子单。
+- 不用内部数据库 ID 作为客户和仓库人员的定位方式。
+- 不通过自动刷新和无限重试掩盖事件失败；失败必须可见并受控重试。
+- 不在多个页面重复维护仓库、车辆、目的仓和客户名称，统一从权威主数据选择并冻结快照。
+
+## 12. 推荐落地顺序
+
+1. 先冻结统一阶段、动作、阻断和责任岗位字典。
+2. 再补服务端聚合字段与跨区回执，不先让各前端自行拼装。
+3. Admin 先落统一订单、柜次、尾程计划、排车四个核心详情页。
+4. Client 接入只读进度、下一动作和费用确认。
+5. 国内/海外 PDA 接入稳定错误原因、恢复动作和操作回执。
+6. 完成 P0 人工验收和埋点基线后，再做表单向导、自动带出和批量体验。
+7. 最后基于真实操作数据决定 P2 的智能推荐和 SLA 预警，不凭主观增加自动化。

头程下单到尾程出库现状流程全景清单.md

@@ -0,0 +1,581 @@
+# 头程下单到尾程出库现状流程全景清单
+
+> 文档性质：现状流程盘点（AS-IS），先描述现在业务怎么走，不在本文讨论页面改版或技术优化。  
+> 覆盖起点：企业具备下单资格。  
+> 主链终点：海外仓完成尾程出库；为保证交接完整，附带记录派送、异常退回和国内最终完成回写。  
+> 使用方法：先用第 2 节确认流程是否覆盖，再按第 3～8 节核对操作、状态、单据和数据流。优化讨论统一以后续评审确认的本清单为输入。
+
+## 1. 范围和口径
+
+### 1.1 本文覆盖
+
+- 企业资料、账号权限、下单资格和资金提交门禁；
+- 单票下单、批量导入、编辑、提交、取消和平台审核；
+- 国内收货、箱码、测量、称重、测量审核、费用与扣货；
+- 普通散货和一件代发国内组托分支；
+- 模拟柜、智能排柜、订舱、订舱级拖车、真实柜号、预装、国内 PDA、装柜证据；
+- 整柜出口报关、国内出仓、船节点、目的港清关提柜和还空；
+- 跨区尾程建单、海外入仓计划、海外 PDA 接柜和三种收货形态；
+- 海外库存、暂扣、库内作业及会影响出库的服务分支；
+- 智能排车、转派送、PDA 拣货、发车和普通/一件代发/换标/转运/退货出库；
+- 派送完成、异常退回和国内订单最终回写。
+
+### 1.2 三类时间和三类仓库必须分开
+
+| 容易混淆项 | 正确含义 |
+|---|---|
+| 预计开船/预计到港 | 订舱和船运节点事实，不是预计到海外仓时间 |
+| 预计到仓 | 整柜预计到实际海外接柜仓的时间，入仓计划生成后锁定 |
+| 实际到仓 | 海外 PDA 首次开始收货的时间，不是码头提柜时间 |
+| 国内来源仓 | 国内收货、测量、拣货和装柜的仓库 |
+| 实际海外接柜仓 | 海外 PDA 作业、库存、托盘和库位所在物理仓 |
+| FBA/私人目的仓 | 货物最终送达地址，不是实际接柜仓 |
+
+### 1.3 三种“完成”必须分开
+
+1. `LOADED/装柜完成`：国内仓已经把货装进出口柜。
+2. 国内出仓完成：整柜已经确认离开国内仓，开始船节点跟踪。
+3. `OUTBOUNDED/海外出库完成`：货已经从海外仓出库；后续可能仍在派送中。
+
+## 2. 全量流程目录与覆盖矩阵
+
+### 2.1 订单路径分叉
+
+| 路径 | 国内测量后 | 国内装柜 | 海外实收 | 海外出库 |
+|---|---|---|---|---|
+| 普通 FBA 散货 | 进入 `WAIT_SPLIT` | 按箱码拣货；按真实柜号+FBA仓生成散货托盘码 | 按入仓码/SKU/托盘输入本次实收箱数 | 通常进入智能排车，转派送后 PDA 发车 |
+| OVERSEAS 海外仓货物 | 进入 `WAIT_SPLIT` | 按箱码拣货并冻结最终实装箱唛 | 按最终箱唛逐箱扫码入托 | 可直接一件代发，或先换标、转运、废弃等库内服务再出库 |
+| 一件代发 | 先进入 `WAIT_PALLETIZE`，国内逐箱清点、组托和封托后再 `WAIT_SPLIT` | 国内封托托盘作为不可拆整托进入柜次 | 沿用国内封托来源托盘整托收货 | 从可用 SKU/箱唛库存创建一件代发出库，PDA 逐箱或整托完成 |
+| 私人目的仓 | 进入 `WAIT_SPLIT` | 按普通货物完成国内装柜 | 海外入仓计划按冻结私人地址分组 | 排车转派送时按私人地址拆分派送单 |
+
+### 2.2 交货方式分叉
+
+| 客户选择 | 下单必填 | 国内到仓前的数据流 |
+|---|---|---|
+| 快递自送 `SELF_EXPRESS` | 国内收货仓、快递/跟踪信息按当前页面要求 | 客户自行寄送，系统保留履约快递快照；到仓后进入统一收货测量 |
+| 平台上门提货 `PICKUP` | 本企业提货地址、联系人和预约提货时间 | 订单冻结提货地址与时间；当前主链以订单预约事实进入统一订单，不把它混同订舱级拖车 |
+| 卡车自送 `SELF_TRUCK` | 国内收货仓和客户自送信息 | 客户自行送仓；到仓后进入统一收货测量 |
+
+交货方式只影响货物如何到达国内收货仓；海运订舱级拖车、目的港码头拖车和海外配送排车属于后续三个独立流程。
+
+### 2.3 后置服务分叉
+
+海外入仓完成后并非所有货都直接排车：
+
+```text
+INBOUND_COMPLETED
+  ├─ 无库内服务 → 智能排车/独立出库
+  ├─ 暂扣 → 解除前禁止排车和出库
+  ├─ 换标 → PDA完工 → 仓库复核 → 客户确认 → 排车或直接出库
+  ├─ 仓储转运 → 平台审核 → 转运出库
+  ├─ 货物废弃 → 审核确认时实际扣减库存，不再出库
+  └─ 退货库存 → 合箱/换标后进入退货出库
+```
+
+| 编号 | 流程 | 主要操作者/终端 | 入口状态或触发 | 出口状态或结果 | 是否主链 |
+|---|---|---|---|---|---|
+| F01 | 企业资料与下单资格 | 客户 Client、平台 Admin | 企业已注册 | 企业资料审核通过 | 前置 |
+| F02 | 基础资料准备 | 平台 Admin | 仓库/渠道/价格等待维护 | 可用于下单和履约 | 前置 |
+| F03 | 客户单票下单 | 客户 Client | 有创建权限 | `DRAFT` | 是 |
+| F04 | 客户批量导入 | 客户 Client | 下载当前模板 | 多张 `DRAFT` | 分支 |
+| F05 | 订单提交与入仓码 | 客户 Client | 草稿完整 | `SUBMITTED/PENDING_REVIEW` + 入仓码 | 是 |
+| F06 | 草稿编辑与取消 | 客户 Client | 草稿或允许取消状态 | 更新草稿或 `CANCELLED` | 分支 |
+| F07 | 平台审核与申报修订 | 平台 Admin | 待审核 | `APPROVED` + 正式国内入库单 | 是 |
+| F08 | 国内到仓与箱码 | 国内仓 Admin/设备 | 正式入库单 | 可测量箱码/箱唛事实 | 是 |
+| F09 | 尺寸测量与称重 | 国内仓 Admin/设备 | `WAIT_MEASURE` | 测量批次待审核 | 是 |
+| F10 | 测量审核与初始计价 | 审核员 Admin | 测量完整 | 普通 `WAIT_SPLIT`；一件代发 `WAIT_PALLETIZE` | 是 |
+| F11 | 费用发布与客户确认 | 平台 Admin、客户 Client | 已有计费快照 | `SENT`、客户确认快照 | 并行 |
+| F12 | 国内入库扣货/解除 | 平台 Admin | 尚未发生不可逆物理履约 | HOLD/RELEASE 历史 | 异常 |
+| F13 | 一件代发国内清点组托 | 国内 PDA、Admin | `WAIT_PALLETIZE` | 封托并进入 `WAIT_SPLIT` | 条件主链 |
+| F14 | 模拟柜与智能排柜 | 平台 Admin | 候选可分配 | 柜次+预装计划+分配明细 | 是 |
+| F15 | 海运订舱与放舱 | 平台 Admin | 订舱草稿 | `RELEASED` | 是 |
+| F16 | 国内订舱级拖车 | 平台 Admin | 有效放舱和提单资料 | 拖车单，离仓后自动完成 | 并行 |
+| F17 | 柜次关联与真实柜号 | 平台 Admin | 模拟柜+放舱需求 | 订舱分配关系+真实柜号 | 是 |
+| F18 | 预装确认及动态增减 | 平台 Admin | 成员满足门禁 | 预装确认/PDA 任务 | 是 |
+| F19 | 国内 PDA 拣货装柜 | 国内 PDA | 可领取任务 | 全部货物核平 | 是 |
+| F20 | 国内装柜证据与铅封 | 国内 PDA/Admin | 装柜作业中 | 四步照片+SEAL | 是 |
+| F21 | 装柜完成和分片 | 国内 PDA/系统 | 货物、证据、柜号齐全 | 计划 `COMPLETED`、入库单 `LOADED` | 是 |
+| F22 | 客户退税资料和整柜报关 | 客户 Client、平台 Admin | 装柜完成 | 整柜报关 `COMPLETED` | 是 |
+| F23 | 国内出仓 | 系统/平台 Admin | 整柜门禁通过 | 离仓历史+船节点任务 | 是 |
+| F24 | 海运十节点 | 第三方/船务 Admin | 国内出仓 | `PICKUP_READY` 至 `EMPTY_RETURNED` | 是 |
+| F25 | 目的港清关、车队、到仓和还空 | 平台 Admin | 海外段柜次可操作 | 清关/提柜/到仓/还空事实 | 并行主链 |
+| F26 | 跨区尾程建单 | 系统 | 国内最终实装事件 | `PENDING_ASSIGNMENT` 尾程订单 | 是 |
+| F27 | 尾程计划维护/整柜转换 | 海外运营 Admin | 待分配尾程订单 | `INBOUND_PLANNED`+逐票计划+资源 | 是 |
+| F28 | 海外 PDA 柜号签收 | 海外 PDA | `PICKUP_READY`+资源齐全 | 柜级收货会话 | 是 |
+| F29 | 海外 PDA 三类实收 | 海外 PDA | 已签收 | 各入仓码实收核平 | 是 |
+| F30 | 海外整柜入仓与国内回写 | 海外 PDA/系统 | 全柜待收数为 0 | `INBOUND_COMPLETED`+库存+卸柜回写 | 是 |
+| F31 | 海外库存、盘点、移库和托盘 | 海外 PDA/Admin | 已有库存 | 库存余额/位置/流水变化 | 支撑 |
+| F32 | 海外暂扣与解除 | 平台 Admin | 已完成入仓 | 阻断/恢复排车出库资格 | 异常 |
+| F33 | 换标、转运、废弃 | 客户/平台/PDA | 可用库存 | 新库存/待出库资格/废弃流水 | 分支 |
+| F34 | 智能预排与排车维护 | 海外运营 Admin | 可用托盘/计划 | `PENDING_DEPARTURE` 排车单 | 是 |
+| F35 | 排车转派送 | 海外运营 Admin | 未发车排车 | `WAIT_OUTBOUND` 出库单+派送单 | 是 |
+| F36 | 排车 PDA 拣货与发车 | 海外 PDA | 排车任务 | `READY_TO_DEPART → DEPARTED` | 是 |
+| F37 | 独立出库任务 | 平台 Admin、海外 PDA | 一件代发/换标/转运/退货库存 | `OUTBOUNDED` | 分支 |
+| F38 | 派送和签收 | 平台 Admin、客户 Client | `WAIT_DELIVERY` | `DELIVERED` | 主链后续 |
+| F39 | 派送异常退回 | 平台 Admin、海外仓 | 拒签/退回 | `RETURNED`+恢复库存 | 异常 |
+| F40 | 客户回访和最终国内回写 | 平台 Admin、系统 | 派送完成或异常处理 | 国内入库单/订单最终完成 | 收口 |
+
+## 3. 客户、订单与国内入库流程
+
+### F01 企业资料与下单资格
+
+1. 企业注册成功后可以登录，不因注册审核阻断登录。
+2. 客户在公司信息维护企业基本资料、联系方式和资质文件。
+3. 平台在客户管理审核企业资料；只有审核通过的企业可提交订单。
+4. 企业管理员给成员分配头程订单查看、创建、提交等权限。
+5. 提交订单时还会校验 Finance 资金账户；实际余额小于 0 时拒绝提交。
+
+数据结果：IAM/Auth 保存企业、成员、角色和资格；Order 只消费认证客户身份和资格结果，不接受页面传入客户 ID 作为授权。
+
+### F02 基础资料准备
+
+平台应先维护：国内收货仓、FBA/海外目的仓、物流渠道、客户价格、尺寸规则、供应商、订舱代理、车辆及海外实际收货仓。停用主数据不能用于新单，但历史订单继续显示冻结快照。
+
+### F03 客户单票下单
+
+入口：Client → 头程订单 → 新建。
+
+操作顺序：
+
+1. 选择运输模式、业务类型、国内收货仓、渠道和税务/计价方式。
+2. 选择交货方式：快递自送、平台上门提货或卡车自送。
+3. 平台上门提货时选择/保存本企业提货地址并填写预约提货时间。
+4. 选择目的类型和目的仓；私人仓填写本企业私人目的地址。
+5. 填写货物明细、SKU、品名、箱数、件数、重量、体积及申报资料。
+6. 保存草稿。
+
+输出：`DRAFT`。草稿可以编辑，不生成入仓码，也不进入国内物理履约。
+
+### F04 客户批量导入
+
+1. 下载当前客户动态 XLSX 模板。
+2. 使用模板下拉填写有效仓库、渠道、交货方式和目的仓。
+3. 单次最多 50 行，上传后服务端逐行校验。
+4. 支持部分成功或整批原子模式；成功行只创建草稿。
+5. 客户逐票检查草稿后另行提交。
+
+批量导入不等于批量提交审核，也不能绕过企业、资金和主数据门禁。
+
+### F05 订单提交与入仓码
+
+1. 客户点击“提交订单”。
+2. 服务端重新校验企业资格、资金账户、仓库、渠道、目的仓、地址和货物。
+3. 首次成功提交生成全局唯一且固定的 `inboundCode`。
+4. Order 进入 `SUBMITTED`；统一订单主状态固定显示 `PENDING_REVIEW`。
+5. 提交、入仓码和时间线写入同一业务结果；重复提交不得生成第二个入仓码。
+
+### F06 草稿编辑与取消
+
+- 草稿可编辑、提交或取消。
+- 已提交后的可编辑字段和取消资格以服务端动作返回为准。
+- 已进入物理履约的订单不能由客户自行取消。
+- 平台修订申报不得修改客户、国内收货仓、订单号、入仓码，不得增删或重排货物行。
+
+### F07 平台审核与正式入库单
+
+入口：Admin → 统一订单 → 待审核。
+
+1. 单票查看或一次调用批量审核预览。
+2. 核对入仓码、客户、货物、渠道、目的仓和逐票阻断原因。
+3. 必要时修订当前允许的客户申报字段并保留变更审计。
+4. 审核通过。
+5. Order 进入 `APPROVED`；Firstleg 幂等创建正式国内入库单，沿用原入仓码。
+6. 对需要箱码的订单生成稳定箱码/箱唛和 SKU 快照。
+
+待审核订单即使 Firstleg 已有准备投影，统一主状态仍是待审核，不能提前作为审核通过事实。
+
+### F08 国内到仓与箱码
+
+- 仓库通过入仓码或稳定箱码识别货物。
+- 普通散货使用稳定箱码逐箱关联；一件代发箱码还冻结箱内 SKU。
+- 客户是否下载/打印箱唛不决定箱码是否有效。
+- 设备、人工测量和 PDA 必须复用同一箱码映射，不得临时造码。
+
+### F09 尺寸测量与称重
+
+1. 第三方设备按入仓码/箱码上传长宽高、箱数、设备和事件号；重复事件幂等。
+2. 国内仓上传称重图片，系统执行 OCR。
+3. 操作员保留 OCR 原值并填写修正值/原因。
+4. 每张有效图片只能计重一次；全部称重图片确认且总重量大于 0。
+5. 提交测量审核。
+
+数据并行保存：客户申报值、设备原始值、人工修正值、计费采用值和证据文件，不互相覆盖。
+
+### F10 测量审核与初始计价
+
+1. 审核员检查箱数、尺寸、重量、证据和客户尺寸规则。
+2. 审核通过后执行初始价格匹配和计价。
+3. 普通订单主状态直接进入 `WAIT_SPLIT`。
+4. 一件代发进入 `WAIT_PALLETIZE`，完成国内实际组托后再进入 `WAIT_SPLIT`。
+5. 审核失败按原因修正后重新提交；异常放行必须同时满足配置、权限和原因。
+
+### F11 费用发布与客户确认
+
+1. 平台查看系统基准量、价格簿、计价模型和费用明细。
+2. 允许范围内的人工调整必须带版本、原因和二次确认。
+3. 审核、发布费用，客户在 Client 查看 `SENT` 的当前版本。
+4. 客户带费用版本和幂等键确认。
+5. 新版本会清空旧确认；只有客户已确认且本票装柜完成后费用最终冻结。
+
+费用是并行状态，不阻断 `WAIT_SPLIT`，也不把订单主流程回退到计费状态。
+
+### F12 国内扣货与解除
+
+1. 平台在统一订单对正式入库单执行扣货，填写原因并上传有效凭证。
+2. HOLD 阻断后续物理履约写入。
+3. 解除扣货同样使用版本和幂等键，保留不可变历史。
+4. 已发生拣货、装柜或出仓时禁止手工扣货/解除。
+
+### F13 一件代发国内清点组托
+
+1. 测量审核后按预计托数生成 `DP` 托盘码。
+2. Admin 打印每托信息单。
+3. 国内 PDA 可先扫箱或先扫托盘，逐箱清点完整 SKU 后归托。
+4. 同仓多票可共用开放托盘；参与本票的开放托盘阻断本票完成。
+5. 操作员逐托封托；未进入装柜计划前可按规则解封。
+6. 全部箱和实际参与托盘核平后进入 `WAIT_SPLIT`。
+
+## 4. 国内货柜履约流程
+
+### F14 模拟柜与智能排柜
+
+1. Admin 创建模拟柜，选择正式装柜仓、计划渠道组、柜型、容量和限重。
+2. 系统生成稳定 `containerBookingId`、`cabinetNo` 和唯一预装计划。
+3. 工作台查询 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 候选；状态只用于展示，资格取服务端 `canAssign`。
+4. 待审核/待测量可提前占位，但确认预装和启动 PDA 前必须进入 `WAIT_SPLIT`。
+5. 普通货按箱数分配；一件代发按封托托盘不可拆分分配；同柜组按完整组处理。
+6. 服务端校验剩余箱数、容量、重量、渠道、组锁和版本。
+
+### F15 海运订舱与放舱
+
+1. Admin 新建订舱草稿，可先部分保存柜型需求。
+2. 补齐提单号、船名、航次、ETD、ETA、运输条款、渠道和有效订舱资料。
+3. 点击放舱后状态进入 `RELEASED`，冻结订舱运输快照。
+4. 订舱只记录柜型需求，不在订舱阶段自动创建另一批货柜。
+
+### F16 国内订舱级拖车
+
+1. 从服务端候选选择 `RELEASED` 且资料完整的订舱。
+2. 选择 `TRUCKING/DOMESTIC` 供应商，维护计划装柜时间和附件。
+3. 每个订舱最多一张非终态拖车单；重复创建回到既有单。
+4. 拖车不绑定客户、柜次、装柜计划或真实柜号。
+5. PDA 装柜完成不推进拖车；订舱全部要求货柜确认离开国内仓后，拖车自动完成并生成按实装体积分摊的应付费用。
+
+### F17 柜次关联与真实柜号
+
+1. 港口取得真实柜号后，选择模拟柜和已放舱订舱的未满配柜型需求。
+2. 服务端校验仓库、渠道、柜型、容量、限重、客户范围和柜号唯一性。
+3. 在原模拟柜上补订舱、需求和真实柜号；稳定柜次 ID、计划和明细不变。
+4. 正式操作统一在预装确认和 PDA 启动前补齐真实柜号；最终装柜完成必须有柜号。
+
+### F18 预装确认及动态增减
+
+1. Admin 打开预装详情核对入仓码、箱数、托盘和备注。
+2. 计划级确认整份预装，生成或开放唯一 PDA 任务。
+3. PDA 最终完成前，`EDITING/LOADING` 计划可继续新增满足条件的明细。
+4. 未拣明细可调整或移除；已拣数量形成最小值，不能删除或减到已拣以下。
+5. 新增明细会递增计划/任务版本；PDA 旧版本必须刷新。
+
+### F19 国内 PDA 拣货装柜
+
+普通散货：扫描稳定箱码，一箱一码，批量提交；不能用 SKU、件数或入仓码替代箱码。
+
+一件代发：扫描托盘码或托盘成员箱码定位整托，以 `PICK_PALLET` 一次提交整托；不能部分拣货。
+
+共同流程：领取任务 → 扫描/确认 → 批量提交 → 未完成项处理异常 → 全部核平 → 最终完成。
+
+### F20 装柜证据与铅封
+
+需要四步现场照片 `PHOTO_STEP_1..4` 和一条带铅封号的 `SEAL`。同类可追加；错误照片作废而非硬删除。PDA 现场拍摄，Admin 可按权限补充上传。
+
+### F21 装柜完成和分片
+
+1. 服务端重新校验真实柜号、订舱、计划、PDA 明细和五类证据。
+2. 全部通过后计划进入 `COMPLETED`，来源入库单进入 `LOADED`。
+3. 部分装载时数量守恒：已装数量形成子入库单，余量保留后续子单；只允许一层分片。
+4. 生成最终实装清单、托盘/SKU/箱唛快照和跨区 Outbox。
+
+### F22 客户资料与整柜出口报关
+
+1. 客户按订单上传本客户退税/报关资料。
+2. 平台按整柜汇总多个入仓码资料，开始报关后冻结当前资料。
+3. 平台线下完成报关后逐资料上传完成文件并完成整柜报关。
+4. 全买单柜由平台确认并通过导出中心获取明细。
+5. 报关完成后系统立即尝试确认国内出仓；其他门禁未齐时由受控补偿重试。
+
+### F23 国内出仓
+
+当前硬门禁：未扣货、所有入库单 `LOADED`、装柜计划完成、国内 PDA 完成、订舱 `RELEASED`、四步照片和铅封完整、整柜报关完成。
+
+操作结果：
+
+- 系统自动尝试；未自动收敛时平台在柜次/国内出仓页点击确认离仓。
+- 整柜写入唯一离仓历史并创建 `CarrierScheduleQuery`。
+- 产生第一条实际 `DEPARTED_WAREHOUSE`。
+- 尝试完成订舱级拖车。
+- 产生实际离仓节点后禁止撤销。
+
+独立拖车状态和独立船期只做参考，不是当前出仓硬门禁。
+
+## 5. 海运、目的港和跨区流程
+
+### F24 海运十节点
+
+实际节点依次为：
+
+`DEPARTED_WAREHOUSE → AT_ORIGIN_PORT → LOADED_ON_VESSEL → DEPARTED_ORIGIN_PORT → IN_TRANSIT → ARRIVED_DESTINATION_PORT → DISCHARGED_FROM_VESSEL → PICKUP_READY → PICKED_UP → EMPTY_RETURNED`
+
+- 第三方轨迹或人工补录只能单调推进实际节点。
+- 预计事实不推进最新实际节点。
+- `PICKUP_READY` 才开放海外 PDA 候选。
+- 实际 `EMPTY_RETURNED` 后查询停止。
+
+### F25 目的港清关、车队、到仓和还空
+
+1. Admin 在“清关提柜”查看海外段柜次并维护目的港清关、DO 和 PU。
+2. 选择海外车队后发送提柜请求邮件；换车队时保存旧车队取消和新车队提柜两封邮件。
+3. 预计到仓由平台维护，并按 `sourceContainerBookingId` 同步整柜尾程订单；已有入仓计划后锁定。
+4. 实际到仓只取海外 PDA 首次开始收货时间。
+5. 海外卸柜完成后生成还空截止和预警；可按权限登记真实还柜时间。
+6. 还柜时间不得早于卸柜完成或已有提柜时间；成功后同步 `EMPTY_RETURNED`。
+
+目的港码头拖车与国内订舱级拖车、海外配送排车是三个独立生命周期。
+
+### F26 跨区尾程建单
+
+1. Firstleg 按最终实装发布版本化装柜完成事件。
+2. Event Bridge 跨区域投递，Lastleg Inbox 幂等消费。
+3. 每票生成尾程订单和冻结货物明细，状态 `PENDING_ASSIGNMENT`。
+4. 建立 `FIRST_LEG` 在途库存快照，计划生成前以来源入仓码展示。
+5. 事件只建订单，不自动建入仓计划。
+6. 同一来源事件重放不能生成第二张尾程订单。
+
+## 6. 海外入仓与库存流程
+
+### F27 尾程计划维护和整柜转换
+
+主入口：Admin → 海外仓 → 尾程订单 → 柜级工作台。
+
+1. 按 `sourceContainerBookingId` 查看整柜全部订单，不使用当前分页拼柜。
+2. 可逐票维护托数、托盘类型、分配、可合托、加急和备注；入仓码、接柜仓和预计到仓只读。
+3. 单票柜保存计划后立即生成资源；多票柜在最后一票计划齐全时生成全柜资源。
+4. 柜级转换前读取服务端预览：分组、头程已有托数、海外补充托数、最终托数、阻断项、快照版本/哈希。
+5. 确认转换后服务端锁柜重算，逐票生成独立计划并批量确认托盘/库位资源。
+6. 尾程订单进入 `INBOUND_PLANNED`；资源异常用 `resourcePendingPlanCount` 定向重试。
+
+散货保留头程托盘码，不足部分连续补码；一件代发严格沿用国内封托托盘，不允许重算托数。
+
+### F28 海外 PDA 柜号签收
+
+前置：实际 `PICKUP_READY`、计划和资源齐全、操作员绑定正确收货仓。
+
+1. PDA 在待卸货列表选择物理柜并锁定。
+2. 核对同柜全部入仓码、目的仓、托数和箱数。
+3. 查看国内五类装柜照片作为只读对照；单图加载失败不阻断。
+4. 依次拍车牌 `LICENSE_PLATE`、封签 `CONTAINER_SEAL`、开柜现场 `DOOR_OPEN`。
+5. 三类照片齐全后确认签收并进入收货。
+
+柜级会话按物理柜聚合，可包含多客户；签收后每票 PDA 任务仍按真实客户隔离。
+
+### F29 海外 PDA 三类实收
+
+| 类型 | 操作方式 | 禁止事项 |
+|---|---|---|
+| FBA 散货 | 选入仓码，扫冻结 SKU，扫托盘，输入本次箱数 | 不能超收，不能走逐箱模式 |
+| OVERSEAS | 扫最终实装箱唛自动定位入仓码，扫托盘，逐箱确认 | 不能批量输入箱数，已收箱不能重复收 |
+| 一件代发 | 按国内封托来源托盘整托收货，并逐入仓码核平 | 不能拆解国内冻结托盘事实后重新猜配 |
+
+“可合托”只提供现场选择；独立收货扫新托盘，合托扫同目的仓已使用托盘。它不是实收或整柜完成门禁。
+
+### F30 海外整柜入仓与国内回写
+
+1. 所有入仓码 `pendingPackages=0` 后完成整柜。
+2. 同事务推进计划/任务和尾程主状态 `INBOUND_COMPLETED`。
+3. 生成库存余额、库存位置、进销存流水和托盘组成。
+4. 发布唯一 `OVERSEAS_CONTAINER_UNLOADED` 事件。
+5. 国内写入卸柜完成、照片上传和预计报空时间；事件重放不重复写事实。
+
+### F31 海外库存、盘点、移库和托盘
+
+- Admin 查询库存余额、位置、流水、托盘和 CSV。
+- 海外 PDA 可执行当前工作台已开放的库存/库位/托盘查询、同仓整托移库和托盘组拆换绑。
+- 托盘是现场作业单位，不是库存客户归属单位；同一合托托盘可包含多票组成明细。
+- 普通入仓只记录某票在托盘上的箱数，不代表每个箱唛都有精确托盘快照。
+
+### F32 海外暂扣与解除
+
+1. 只允许尾程订单完成入仓后新增暂扣。
+2. 暂扣只作用于本票，阻断排车和出库，不影响同柜其他票。
+3. 暂扣不回退入仓计划、入仓事实和库存历史。
+4. 解除后恢复后续资格，保留版本化历史。
+
+### F33 换标、转运和废弃
+
+- 换标：客户从可用库存申请，PDA 扫箱/换标/照片，仓库复核后客户确认；客户确认前不能出库。
+- 仓储转运：客户申请，平台在尾程订单审核通过/驳回；通过后进入转运出库。
+- 货物废弃：创建时只冻结库存，仓库/PDA 审核确认时才实际扣减并写逐箱流水。
+
+这些子单状态保存在 `sub_order_status`，不能覆盖尾程主流程 `INBOUND_COMPLETED`。
+
+## 7. 海外排车和出库流程
+
+### F34 智能预排与排车维护
+
+1. Admin 从真实入仓计划、已收托盘或已具备资格的换标库存加载候选。
+2. 托盘加入草稿立即加草稿锁；移除或关闭草稿时释放。
+3. 选择车型，核对托位、箱数、重量和目的仓。
+4. 点击预排，草稿锁原子转换为正式排车锁并生成排车单。
+5. 编辑车牌、司机、电话、车队、预计发车/到达、FBA 预约和车辆预约。
+6. 路线由已排托盘目的仓自动汇总，不能人工填写。
+7. 未执行排车可取消并释放锁；普通编辑不得修改状态。
+
+### F35 排车转派送
+
+可在 `PENDING_DEPARTURE/PICKING/READY_TO_DEPART` 操作，但必须早于发车。
+
+1. 填写预计派送时间、方式、提货/装车类型、车队/快递、车辆、预约和费用。
+2. 服务端校验所有排车托盘已经真实入仓。
+3. 一张排车单生成一张车辆级 `WAIT_OUTBOUND` 出库单。
+4. 按目的 FBA 仓或私人地址生成一张或多张 `WAIT_DELIVERY` 派送单。
+5. 相同排车重复转派送返回既有单据，不重复生成。
+
+### F36 排车 PDA 拣货与发车
+
+1. 海外 PDA 打开本仓排车任务。
+2. 扫描托盘并校验排车、仓库、库存位置和计划箱数。
+3. 成功扫描时执行库存分配、拣货和出库扣减；重复请求幂等。
+4. 全部托盘/箱数核平后 PDA 任务 `COMPLETED`、排车 `READY_TO_DEPART`。
+5. 发车门禁还要求车辆完整、已转派送且出库单仍是 `WAIT_OUTBOUND`。
+6. 发车后排车 `DEPARTED`、出库单 `OUTBOUNDED`，释放托盘锁。
+
+库存扣减发生在成功 PDA 扫码事务；发车只推进排车和出库事实，不能再次扣库存。
+
+### F37 独立出库任务
+
+| 出库类型 | 创建前置 | PDA 操作 | 完成结果 |
+|---|---|---|---|
+| 一件代发 | 已完成入仓、有可用箱唛/SKU/库存位置；一单唯一客户和仓 | 逐箱或扫 DP 托盘整托拣取 | `WAIT_PICK → PICKING/PICKED → OUTBOUNDED` |
+| 换标出库 | 仓库复核且客户确认 | 按换标后箱唛/托盘拣货 | 换标单完成、出库单 `OUTBOUNDED` |
+| 仓储转运 | 申请审核通过 | 按冻结来源托盘/箱数拣货 | 转运单 `OUTBOUNDED` |
+| 退货出库 | 退货箱/SKU 可用库存 | 按冻结退货库存拣货 | 退货库存扣减、出库单完成 |
+
+出库单只有未开始的 `WAIT_PICK/WAIT_OUTBOUND` 可取消；作业开始后不能通过取消恢复库存。
+
+## 8. 派送、异常和最终回写
+
+### F38 派送和签收
+
+派送单状态：`WAIT_DELIVERY → DELIVERING → DELIVERED`；也可能进入 `REJECTED/CANCELLED`。
+
+1. Admin/Client 查看按目的仓拆分的派送单。
+2. 平台开始派送或维护允许的状态。
+3. 上传并保存签收资料后系统自动完成派送；不提供脱离签收资料的人工“完成派送”按钮。
+4. 派送完成发布跨区完成事件。
+
+### F39 派送异常退回
+
+1. 平台从派送创建异常单，状态 `PENDING → PROCESSING → COMPLETED`。
+2. 退回明细只能从原出库拣货事实选择，不能自由填写 SKU/数量。
+3. 退回海外仓时选择服务端校验的真实托盘和库位并实收。
+4. 库存恢复、异常完成和派送 `RETURNED` 同事务完成。
+5. 完成异常必须有 `OVERSEAS_EXCEPTION_EVIDENCE` 证据。
+
+### F40 客户回访和国内最终回写
+
+- 平台在客户回访记录结果和附件，作为派送后的业务闭环资料。
+- 海外派送完成事件回到国内后，Firstleg 按来源订单、入仓码和目的仓校验。
+- 对应国内入库单从 `LOADED` 推进到 `DELIVERED`。
+- 同一 Order 的全部有效入库单都完成后，Order 才进入 `COMPLETED`。
+- 任一事件重放不得重复推进、重复写历史或重复费用。
+
+## 9. 单据、编号和数据交接关系
+
+```text
+客户 orderNo
+  └─ inboundCode（提交时生成）
+      └─ 国内 inboundId / 箱码 / 测量批次 / 费用版本
+          └─ containerBookingId + cabinetNo + containerNo
+              └─ loadingPlanId / 国内 PDA task / 装柜证据
+                  └─ 跨区 eventId
+                      └─ 尾程订单 + planNo
+                          └─ 海外实物 palletNo / 库位 / 库存流水
+                              └─ dispatchNo
+                                  └─ outboundNo
+                                      └─ deliveryNo
+```
+
+业务人员使用订单号、入仓码、柜次号、真实柜号、计划号、托盘号、排车单号、出库单号和派送单号定位。内部数据库 ID 只用于接口关联和诊断，不作为用户可见编号回退。
+
+## 10. 状态维度关系
+
+| 状态维度 | 归属 | 例子 | 不能做的事 |
+|---|---|---|---|
+| 订单交易状态 | Order | `DRAFT/SUBMITTED/APPROVED/CANCELLED/COMPLETED` | 不能用海外子单状态覆盖 |
+| 国内履约主状态 | Firstleg | `WAIT_MEASURE/WAIT_PALLETIZE/WAIT_SPLIT/LOADING/LOADED/DELIVERED` | 费用变化不能回退主状态 |
+| 测量审核 | Firstleg | `PENDING/APPROVED/REJECTED` | 不能代替订单审核 |
+| 费用状态 | Firstleg/Finance | 试算、审核、发布、客户确认 | 不能表示货物已入库或出库 |
+| 柜次/装柜计划 | Firstleg | `EDITING/LOADING/COMPLETED` | 不能替代单票入库状态 |
+| 尾程主流程 | Lastleg | `PENDING_ASSIGNMENT/INBOUND_PLANNED/INBOUND_COMPLETED` | 不用出库/派送子状态覆盖 |
+| 排车 | Lastleg | `PENDING_DEPARTURE/PICKING/READY_TO_DEPART/DEPARTED` | 不等于出库或派送状态 |
+| 出库 | Lastleg | `WAIT_PICK/PICKING/PICKED/WAIT_OUTBOUND/OUTBOUNDED` | 不等于派送签收 |
+| 派送 | Lastleg | `WAIT_DELIVERY/DELIVERING/DELIVERED/REJECTED/RETURNED` | 不反向改写库存，退回走专用事务 |
+
+## 11. 人工动作、系统动作和异步动作
+
+| 类型 | 代表动作 | 判断完成的证据 |
+|---|---|---|
+| 人工动作 | 提交订单、审核、测量确认、预装、PDA 扫码、报关、转派送 | 服务端返回新版本/状态和业务历史，不以按钮消失为准 |
+| 系统同步动作 | 生成入仓码、审核建国内入库单、计划转换、库存扣减 | 同一事务内的单据和状态结果 |
+| 系统异步动作 | 跨区尾程建单、海外卸柜回写、派送完成回写、费用入池 | Outbox/Inbox 消费结果和下游业务单据 |
+| 第三方动作 | 测量设备、船司轨迹、邮件发送 | 带来源、事件号、观测时间和处理结果的不可变记录 |
+
+异步页面暂未出现数据时，先检查事件状态并等待受控重试，不能手工造下游数据。
+
+## 12. 当前明确的流程边界和冲突口径
+
+1. 测量审核通过后主流程进入 `WAIT_SPLIT`；费用独立处理，不再以“发送费用”作为唯一入库成功节点。
+2. 装柜完成跨区事件只生成待分配尾程订单，不自动生成入仓计划。
+3. 国内出仓当前硬门禁不含订舱级拖车状态和独立船期；旧验收稿中的相关硬门禁已过期。
+4. 真实柜号允许后补的历史指引存在差异；正式操作统一在预装确认/PDA 启动前补齐，服务端最终装柜完成必须有柜号。
+5. 海外尾程主状态与换标、转运、排车、出库、派送子状态分开保存。
+6. 目的港提柜时间、预计到仓和实际到仓不能相互替代。
+7. 国内出仓、海外入仓、海外出库和派送完成是四个不同业务节点。
+
+## 13. 文档评审清单
+
+业务、产品、运营、仓库和技术应逐项确认：
+
+- [ ] F01～F40 是否有实际业务流程遗漏
+- [ ] 每一步实际操作者和终端是否正确
+- [ ] 各流程入口状态、完成状态和下一责任岗位是否正确
+- [ ] 三种交货方式和三种海外实收方式是否与现场一致
+- [ ] 一件代发整托规则是否与国内、海外现场一致
+- [ ] 国内订舱级拖车、目的港码头拖车、海外配送排车是否完全区分
+- [ ] 报关、清关、DO、PU、提柜、预计/实际到仓和还空时序是否正确
+- [ ] 跨区只建尾程订单、人工计划转换的口径是否确认
+- [ ] 暂扣、换标、转运、废弃、退货和异常退回对出库资格的影响是否完整
+- [ ] 海外扫码即扣库存、发车不重复扣减的口径是否与仓库账实一致
+- [ ] 派送完成后国内 `DELIVERED/COMPLETED` 回写规则是否符合业务认知
+- [ ] 当前页面是否都存在对应人工入口；缺入口项需单独登记，不能在流程图中假装可操作
+
+评审完成后，再以本清单逐项标注“保留、合并、自动化、简化、删除”，进入易用性和数据流转优化设计。
+
+## 14. 事实来源
+
+- `docs/业务快速索引.md`
+- `docs/订单与客户/README.md`
+- `docs/订单与客户/订单与客户头程订单闭环设计.md`
+- `docs/入库测量与计费/README.md`
+- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
+- `docs/国内货柜履约/README.md`
+- `docs/国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md`
+- `docs/海外仓业务/README.md`
+- `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
+- `baiyue-firstleg/order/AGENTS.md`
+- `baiyue-firstleg/firstleg/AGENTS.md`
+- `baiyue-firstleg/lastleg-service/AGENTS.md`
+- `apps/admin-web/AGENTS.md`
+- `apps/admin-web/src/modules/overseas-warehouse/AGENTS.md`
+- `apps/client-web/AGENTS.md`
+- `apps/pda-uniapp/AGENTS.md`
+- `apps/pda-overseas-uniapp/AGENTS.md`

头程到尾程AI流程优化上下文包.md

@@ -0,0 +1,296 @@
+# 头程到尾程 AI 流程优化上下文包
+
+> 用途：给 AI、产品、业务和技术提供同一份优化输入规范。本文不替代六阶段现状文档，也不直接改变状态机；它定义分析顺序、术语、证据、指标、输出格式和实施门禁，防止 AI 只根据局部页面提出脱离业务事实的建议。
+
+## 1. 第二轮完整性审计结论
+
+现有材料已经覆盖 F01～F40 的操作、状态、异常和交接，但若要让 AI 持续辅助优化，还需要补齐以下横向信息：
+
+| 缺口 | 为什么重要 | 本文补充方式 |
+|---|---|---|
+| 文档读取优先级 | AI 容易拿历史规划覆盖当前实现 | 固定事实优先级和最小上下文 |
+| 统一术语和对象关系 | “柜次、订舱、拖车、托盘”等容易混淆 | 建立术语与禁止混用表 |
+| 流程变体矩阵 | 单一主链会漏掉一件代发、私人地址、异常退回 | 明确变体和分叉点 |
+| 跨端 RACI | 仅写角色仍不清楚谁负责、谁批准、谁被通知 | 建立阶段级责任矩阵 |
+| 输入输出合同 | AI 容易建议重复录入或跨服务改权威数据 | 固定六阶段交接合同 |
+| 阻断原因分类 | “不能继续”若无分类，无法做任务卡和统计 | 定义 blocker 分类和恢复动作 |
+| 指标口径与基线 | 没有分母、起止点就无法验证“更好用” | 建立指标字典和基线采集表 |
+| 问题证据格式 | 主观反馈无法排序，也无法复现 | 统一问题观察记录 |
+| 优化卡模板 | 建议容易停留在“做个工作台” | 强制写现状、方案、数据、验收和回滚 |
+| AI 输出约束 | AI 可能新建平行状态机、引入兼容层或越权自动化 | 明确禁止项和完成定义 |
+
+## 2. AI 读取顺序
+
+每次只读取与目标阶段相关的最小材料，按以下顺序判断事实：
+
+1. 当前对话中的业务确认；
+2. 对应阶段文档；
+3. [现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)；
+4. 目标应用、服务最近的 `AGENTS.md`；
+5. 当前 Controller、DTO、Service、页面和 OpenAPI；
+6. 当前阶段设计/审核记录；
+7. 原型；
+8. 历史规划和旧验收记录。
+
+优化分析的默认入口：
+
+- 总览：[分阶段流程目录](头程到尾程分阶段流程/README.md)
+- 操作：[全流程操作手册](头程下单到尾程出库全流程操作手册.md)
+- 现状：[现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)
+- 方案：[易用性与数据流转优化方案](头程下单到尾程出库流程易用性与数据流转优化方案.md)
+- 约束：本文
+
+出现冲突时必须明确写出“来源 A、来源 B、采用哪一项及原因”，不能静默拼接两套口径。
+
+## 3. 统一术语与禁止混用
+
+| 术语 | 正确定义 | 不得混用为 |
+|---|---|---|
+| 订单号 `orderNo` | 客户交易订单业务号 | 入仓码、入库单号 |
+| 入仓码 `inboundCode` | 从头程提交到海外尾程持续使用的稳定关联码 | 内部 `inboundId`、计划号 |
+| 柜次号 `cabinetNo` | 平台模拟柜/柜次业务编号 | 真实集装箱号 |
+| 真实柜号 `containerNo` | 船司/码头识别的物理集装箱号 | 模拟柜 ID |
+| 海运订舱 | 船司运输、提单和柜型需求聚合 | 柜次、国内拖车 |
+| 国内订舱级拖车 | 一个已放舱订舱的国内提柜/送柜任务 | 目的港码头拖车、海外配送排车 |
+| 目的港码头拖车 | 海外清关后提柜、到仓和还空链路 | 海外配送排车 |
+| 海外配送排车 | 海外库存出库后送往 FBA/私人地址的车辆任务 | 目的港提柜 |
+| 头程普通托盘码 | 预装/装柜阶段按真实柜号与 FBA 仓生成 | 一件代发 `DP` 托盘 |
+| 一件代发 `DP` 托盘 | 国内测量后逐箱 SKU 清点并封托的来源托盘 | 海外仓随意重打托盘 |
+| 海外实物托盘 | Warehouse Overseas 管理的公共物理资源 | 库存客户归属 |
+| `LOADED` | 国内实际装柜完成 | 国内实际离仓、海外入仓 |
+| `DEPARTED_WAREHOUSE` | 柜子实际离开国内仓 | 船已开航 |
+| `PICKUP_READY` | 目的港清关完成、可提柜 | 已提柜、已到海外仓 |
+| `INBOUND_COMPLETED` | 海外实收和库存入账完成 | 已出库、已派送 |
+| `OUTBOUNDED` | 对应出库单已完成出库 | 客户/目的仓已签收 |
+| `DELIVERED` | 目的派送签收完成 | 仅发车或仅上传 BOL |
+
+用户页面只展示业务号；内部 ID 只能出现在接口关联或可折叠诊断信息。
+
+## 4. 必须覆盖的流程变体
+
+AI 分析任何阶段时，至少检查下列适用变体，不能只优化最顺畅的一条 FBA 散货主链：
+
+| 维度 | 变体 | 关键差异 |
+|---|---|---|
+| 下单方式 | 单票、批量导入 | 批量需预览、逐行错误和重试 |
+| 国内交货 | 自送、快递、平台提货 | 平台提货是否有独立派车/回执仍需业务确认 |
+| 目的类型 | FBA、OVERSEAS、PRIVATE | 目的仓、逐箱事实、私人地址和派送拆分不同 |
+| 履约类型 | 普通、一件代发 | 一件代发国内先清点封托，海外必须沿用来源托盘 |
+| 装柜 | 整票、部分装载、一票多柜、多票拼柜 | 分片、数量守恒和 Order 最终完成条件不同 |
+| 海外收货 | FBA bulk、OVERSEAS carton、dropship pallet | 批量箱数、逐箱、整托三种操作不可混用 |
+| 海外托盘 | 独立托盘、同目的仓合托 | 合托不改变客户和入仓单归属 |
+| 后续服务 | 正常排车、换标、转运、废弃、退货出库 | 库存锁、资格和子状态不同 |
+| 派送结果 | 正常签收、拒收/取消、异常退回 | 退回必须恢复原出库来源库存 |
+| 系统结果 | 同步成功、异步处理中、可重试失败、永久失败 | 页面回执和人工动作不同 |
+
+## 5. 六阶段 RACI
+
+缩写：R=实际执行，A=最终负责/批准，C=协作或复核，I=需要知会。
+
+| 阶段 | 企业客户 | 平台订单/运营 | 国内仓/PDA | 海外运营 | 海外仓/PDA | 财务/客服 | 系统 |
+|---|---|---|---|---|---|---|---|
+| 1 下单审核 | R | A/R | I | I | I | C | C |
+| 2 测量计费组托 | C | A/C | R | I | I | C | R |
+| 3 国内装柜出仓 | C | A/R | R | I | I | C | R |
+| 4 海运与尾程计划 | I | R/C | I | A/R | I | I | R |
+| 5 海外入仓与库内 | C | I | I | A/C | R | C | R |
+| 6 排车出库派送 | I/C | I | I | A/R | R | R/C | R |
+
+RACI 是评审起点，不是权限契约。具体按钮仍由服务端权限码、身份范围和当前状态决定。优化建议若改变 A/R，必须列为业务决策，不能由页面设计默认改变职责。
+
+## 6. 阶段输入输出合同
+
+| 阶段 | 最小输入 | 成功输出 | 下一阶段硬前置 |
+|---|---|---|---|
+| 1 | 客户身份、仓库/渠道/目的地、申报 | `APPROVED`、固定入仓码、正式国内入库单 | `WAIT_MEASURE` |
+| 2 | 正式入库单、稳定箱码、实到货物 | 审核实测；普通/组托完成后 `WAIT_SPLIT` | 无 HOLD、数量证据完整 |
+| 3 | `WAIT_SPLIT` 箱/整托、柜型与运输资料 | `LOADED`、报关放行、实际国内离仓 | `DEPARTED_WAREHOUSE` 和最终实装快照 |
+| 4 | 真实柜、订舱、离仓、装柜完成事件 | 尾程订单、`FIRST_LEG` 在途、入仓计划和资源 | `INBOUND_PLANNED`、`PICKUP_READY` |
+| 5 | 可收柜、每票计划、真实资源 | `INBOUND_COMPLETED`、库存余额/位置/流水 | 可用库存且无对应阻断 |
+| 6 | 可用库存、目的地、车辆/服务资料 | 签收、国内 `DELIVERED`、Order `COMPLETED` | 所有有效入库单均完成 |
+
+任何优化都必须说明是否改变合同。只改页面布局时不得暗中改变状态推进、数据所有者或阶段完成判定。
+
+## 7. 阻断原因分类
+
+建议服务端统一返回：`blockerCode/category/message/ownerRole/recoveryAction/deepLink/retryable/detectedAt`。
+
+| 分类 | 示例 | 默认责任 | 恢复方式 |
+|---|---|---|---|
+| `DATA_MISSING` | 缺箱码、重量图片、真实柜号、车辆资料 | 当前录入岗位 | 补齐字段/附件 |
+| `STATE_NOT_READY` | 未审核、未 `WAIT_SPLIT`、未完成拣货 | 上一步岗位 | 完成上一步，不强制跳过 |
+| `PERMISSION_DENIED` | 无审核、放行、调整权限 | 管理员/负责人 | 授权或由有权人处理 |
+| `VERSION_CONFLICT` | 页面版本过期 | 当前操作员 | 刷新并重新核对 |
+| `RESOURCE_CONFLICT` | 托盘/库位/库存已占用 | 仓库/调度 | 换资源或释放合法锁 |
+| `BUSINESS_HOLD` | 国内 HOLD、海外暂扣、换标冻结 | 发起阻断的岗位 | 按证据解除 |
+| `EXTERNAL_WAIT` | 船司、清关、车队、客户确认 | 对应外部协作岗位 | 等待并记录 SLA |
+| `ASYNC_PROCESSING` | Outbox 已发、Inbox 处理中 | 系统 | 自动重试，业务只读 |
+| `ASYNC_RETRYABLE` | 跨区/资源确认暂时失败 | 技术/运营 | 原幂等键受控重试 |
+| `ASYNC_PERMANENT` | 契约字段错误、哈希冲突 | 技术负责人 | 修正源事实后重放 |
+| `IRREVERSIBLE` | 已拣货、已离仓、已签收 | 业务负责人 | 专用异常/冲正流程 |
+
+## 8. 问题证据记录模板
+
+任何“难用、慢、容易错”都先按下表记录，AI 才能比较优先级：
+
+| 字段 | 填写要求 |
+|---|---|
+| 问题编号 | `UX-S阶段-序号`，例如 `UX-S3-004` |
+| 发生阶段/F 编号 | 必填，例如阶段三/F18 |
+| 角色与终端 | 谁在 Admin、Client 或 PDA 操作 |
+| 触发条件 | 什么状态、什么类型、什么前置数据 |
+| 当前操作路径 | 菜单、页面、按钮、扫码顺序 |
+| 期望结果 | 操作员真正想完成的业务结果 |
+| 实际结果 | 页面/接口/状态发生了什么 |
+| 证据 | 截图、录屏、业务号、时间、错误码；不放密钥和敏感数据 |
+| 频率 | 每票/每天次数或样本比例 |
+| 影响 | 多花时间、返工、错账、漏单、需技术介入等 |
+| 临时处理 | 当前怎么绕过去 |
+| 权威事实 | 哪个服务/接口/文档决定正确行为 |
+
+问题优先级建议使用 `影响人数 × 发生频率 × 单次损失 × 风险系数`，同时单独标记合规、资金、库存和数据隔离风险；高风险项不因发生频率低而降级。
+
+## 9. 指标字典与基线
+
+上线任何优化前至少采集两周基线，并固定分子、分母、起止事件：
+
+| 指标 | 起点 | 终点 | 口径 |
+|---|---|---|---|
+| 订单提交耗时 | 打开新建页 | 服务端返回提交成功 | 中位数/P90，排除纯草稿停留 |
+| 审核等待时长 | `SUBMITTED` | `APPROVED` | 区分人工等待和系统建单失败 |
+| 测量作业时长 | 首条测量采集 | 提交审核 | 按箱数分层 |
+| 测量返工率 | 已提交批次 | 被驳回批次 | 驳回批次/提交批次 |
+| 待分柜等待 | 进入 `WAIT_SPLIT` | 首次有效分配 | 区分 HOLD 和无柜资源 |
+| 国内装柜时长 | PDA 任务开始 | `LOADED` | 按普通箱/整托分层 |
+| 离仓阻断时长 | `LOADED` | `DEPARTED_WAREHOUSE` | 按 blocker 分类拆分 |
+| 跨区建单耗时 | Outbox 创建 | Lastleg 消费成功 | P50/P90/P99 和失败率 |
+| 海外计划耗时 | `PENDING_ASSIGNMENT` | `INBOUND_PLANNED` | 区分人工录入与资源失败 |
+| 海外收货时长 | `receiving_at` | `INBOUND_COMPLETED` | 按三种收货模式分层 |
+| 排车等待时长 | 库存具备资格 | 正式排车创建 | 排除暂扣和换标冻结 |
+| 拣货准确率 | PDA 扫码尝试 | 成功核平 | 错托/错箱/重复扫码分别统计 |
+| 派送完成时长 | 排车发车 | 有签收资料的 `DELIVERED` | 按目的地/服务方式分层 |
+| 人工介入率 | 系统异常/阻断 | 需后台或技术处理 | 分 blockerCode |
+| 重复单据数 | 所有幂等重放 | 重复业务单 | 必须为 0 |
+
+埋点只记录阶段、稳定动作码、阻断码、结果、耗时和匿名业务类型；不记录 Token、证件、客户敏感明细或文件内容。
+
+## 10. AI 优化卡标准格式
+
+AI 每提出一项优化，必须完整输出：
+
+```text
+优化编号：OPT-Sx-xxx
+阶段/F 编号：
+问题证据：
+当前角色与操作路径：
+根因类型：交互 / 数据重复 / 状态不可见 / 跨系统等待 / 权限 / 业务规则
+建议方案：
+保持不变的业务规则：
+影响终端：Admin / Client / 国内 PDA / 海外 PDA
+影响服务与权威数据：
+新增或复用的动作码、阻断码：
+同步/异步数据流：
+异常和重试：
+权限与客户隔离：
+埋点和基线指标：
+验收场景：正常 / 分支 / 异常 / 并发 / 幂等 / 越权
+风险与回退：
+优先级及依据：
+待业务确认：
+```
+
+没有证据的建议标记为“假设待验证”，不得直接进入实施清单。
+
+## 11. AI 分析约束
+
+AI 不得：
+
+1. 新建第二套可写全流程状态机；
+2. 用子单状态覆盖 Order、Firstleg 或 Lastleg 主状态；
+3. 让前端根据状态字符串自行推导写资格；
+4. 以内部数据库 ID 作为业务人员定位方式；
+5. 为即时显示做国内/海外数据库同步双写；
+6. 用当前分页数据判断整柜或整票完成；
+7. 把预计时间、创建时间或人工猜测写成实际发生时间；
+8. 为旧字段/旧状态新增兼容分支；
+9. 把按钮隐藏当作服务端权限和状态门禁；
+10. 把自动重试包装成业务成功；
+11. 把一件代发整托拆成普通散货流程；
+12. 在没有现场证据和指标基线时承诺具体效率提升比例。
+
+AI 应优先：复用服务端权威动作与门禁、减少重复输入、显示数据来源、提供修复深链、标准化操作回执、提高异步可观测性，并保证幂等、版本、权限和客户隔离。
+
+## 12. 分阶段优化工作法
+
+每个阶段按同一节奏推进：
+
+1. 业务走查：按阶段文档真实操作一票普通流和适用分支；
+2. 证据采集：记录点击、等待、重复输入、错误和人工交接；
+3. 问题归类：使用 blocker 与根因分类；
+4. 数据核对：标出每个字段的权威来源、快照时点和消费者；
+5. 方案设计：生成优化卡，不先改状态机；
+6. 业务评审：确认 RACI、不可逆点、异常和指标；
+7. 技术影响分析：页面、API、DTO、权限、事件、SQL、测试和部署；
+8. 小步实施：优先 P0 可见性、导航和回执，再做流程合并/自动化；
+9. 验收对比：使用相同业务样本比较基线与上线后指标；
+10. 文档收口：把确认结论回写阶段文档和优化方案，历史假设移出当前基线。
+
+## 13. 优化完成定义
+
+单项优化只有同时满足以下条件才算完成：
+
+- 问题证据和目标指标明确；
+- 正常、分支和异常流程都不丢失；
+- 服务端动作、权限、状态、版本和幂等门禁有效；
+- 权威数据和快照来源没有改变或已明确评审；
+- Admin/Client/PDA 受影响入口同步；
+- 异步结果和失败可见；
+- 业务号可贯通查询且不泄露内部 ID；
+- 自动化检查和人工操作验收均有证据；
+- 上线后指标可与基线比较；
+- 文档、索引和操作说明已更新。
+
+## 14. 仍需业务现场补充的资料
+
+代码和文档无法替代以下现场事实，建议按阶段收集：
+
+- 各岗位实际人员数量、班次、交接方式和峰值单量；
+- 每个页面真实录屏及操作员口述痛点；
+- 常见失败/返工前十名及每月次数；
+- 各阶段目标 SLA、超时升级对象和通知渠道；
+- 纸质标签、称重秤、PDA、打印机和现场网络型号/限制；
+- 平台提货是否存在系统外派车和签收环节；
+- 报关、清关、车队邮件、客户确认等系统外协作耗时；
+- 费用、库存、出库和签收发生争议时的最终责任人；
+- 当前运营最常用的 Excel、群消息和线下登记表；
+- 客户最常咨询的进度问题及客服当前查询路径。
+
+这些资料未收集前，AI 可以提出候选方案，但应明确标注假设，不应直接决定自动化规则或 SLA。
+
+## 15. 待确认问题索引
+
+六份阶段文档共登记 66 个业务/体验评审问题。问题原文保留在各阶段“评审问题”章节，评审时不应只看优化草案：
+
+| 阶段 | 数量 | 重点决策 |
+|---|---:|---|
+| 阶段一 | 6 | 平台提货是否有独立履约、平台代下单、审核驳回口径、旧入仓码、预估费用命名、混箱 SKU 责任 |
+| 阶段二 | 12 | 到仓时间、提前测量、差异原因、OCR、库位警告、费用发布、HOLD、共托和 SKU 纠错 |
+| 阶段三 | 12 | 占位与作业资格、推荐解释、柜号体系、柜级总控、PDA 原子提交、证据、报关和不可逆更正 |
+| 阶段四 | 12 | 柜级时间线、预计/实际节点、船司异常责任、邮件送达语义、跨区诊断、资源失败和还空口径 |
+| 阶段五 | 12 | 柜级资源诊断、照片对照、三种实收、合托、盘点入口、库存不可用来源和换标进度 |
+| 阶段六 | 12 | 草稿锁、装载风险、转派送、三单时间线、扫码扣库存、异常退回、跨区延迟和最终完成解释 |
+
+第一轮评审建议优先决定以下跨阶段问题：
+
+1. 平台提货是否属于系统内完整履约链路；
+2. 到仓时间是否需要独立、权威的实收登记；
+3. HOLD/暂扣的责任人、审批、证据和 SLA；
+4. 国内 PDA 批量提交的原子性和弱网恢复目标；
+5. 排柜占位、预装确认和真实作业资格的统一文案；
+6. 柜级总控台是否作为订舱、PDA、报关、离仓和跨区进度的统一入口；
+7. 跨区事件失败的业务责任人、人工介入边界和重放权限；
+8. 盘点正式入口和账实差异处置流程；
+9. 海外扫码即扣库存的复核、撤销和异常边界；
+10. 国内离仓、海外入仓、海外出库和最终签收的客户可见进度语义。
+
+每项决定应记录：结论、负责人、确认日期、影响阶段、是否改变接口/状态/权限，以及需要更新的文档。未决定项保持“待确认”，不能由 AI 默认选择。

头程到尾程分阶段流程/README.md

@@ -0,0 +1,36 @@
+# 头程到尾程分阶段流程文档
+
+本目录把“头程下单 → 尾程出库”拆成六个可独立评审、以后也可独立优化的阶段。各阶段统一描述现状操作和数据流，不在流程确认前直接决定改版方案。
+
+当前六个阶段的现状基线均已完成。下一步按阶段组织业务、产品、运营、国内仓、海外仓和技术评审；每阶段确认后，再将评审结论转入易用性和数据流转优化方案。
+
+## 分阶段计划
+
+| 阶段 | 范围 | 对应全景流程 | 文档 |
+|---|---|---|---|
+| 阶段一 | 客户准入、基础资料、单票/批量下单、提交、审核、订单交接 | F01～F07 | [阶段一：客户准入与头程下单](阶段一-客户准入与头程下单.md) |
+| 阶段二 | 国内到仓、箱码、测量、称重、费用、扣货、一件代发组托 | F08～F13 | [阶段二：国内到仓、测量计费与组托](阶段二-国内到仓测量计费与组托.md) |
+| 阶段三 | 模拟柜、排柜、订舱、拖车、预装、国内 PDA、报关、出仓 | F14～F23 | [阶段三：国内货柜履约与出仓](阶段三-国内货柜履约与出仓.md) |
+| 阶段四 | 海运节点、目的港、跨区尾程建单、尾程入仓计划 | F24～F27 | [阶段四：海运、目的港与尾程入仓计划](阶段四-海运目的港与尾程计划.md) |
+| 阶段五 | 海外接柜、实收、库存、暂扣和库内服务 | F28～F33 | [阶段五：海外接柜、库存与库内服务](阶段五-海外接柜库存与库内服务.md) |
+| 阶段六 | 海外排车、转派送、PDA 出库、派送、异常和最终回写 | F34～F40 | [阶段六：海外排车、出库、派送与最终回写](阶段六-海外排车出库派送与回写.md) |
+
+## 每阶段统一模板
+
+1. 阶段目标、起点和终点；
+2. 角色、终端和权限边界；
+3. 前置主数据和检查项；
+4. 页面逐步操作；
+5. 字段与条件必填规则；
+6. 状态机、可用动作和不可逆节点；
+7. 单据、编号、快照和数据归属；
+8. 同步/异步调用和上下游交接；
+9. 正常流、条件分支和异常恢复；
+10. 阶段完成判定与评审清单。
+
+总览入口：
+
+- [现状流程全景清单](../头程下单到尾程出库现状流程全景清单.md)
+- [一票主链操作手册](../头程下单到尾程出库全流程操作手册.md)
+- [易用性与数据流转优化草案](../头程下单到尾程出库流程易用性与数据流转优化方案.md)
+- [AI 流程优化上下文包](../头程到尾程AI流程优化上下文包.md)

头程到尾程分阶段流程/阶段一-客户准入与头程下单.md

@@ -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`

头程到尾程分阶段流程/阶段三-国内货柜履约与出仓.md

@@ -0,0 +1,424 @@
+# 阶段三：国内货柜履约与出仓
+
+> 对应全景流程：F14～F23。  
+> 阶段起点：入库单主状态为 `WAIT_SPLIT`，不存在有效 HOLD。  
+> 阶段终点：整柜满足国内出仓门禁，产生唯一实际 `DEPARTED_WAREHOUSE` 节点并开始出仓后的船节点查询。  
+> 本阶段复用订单、入库单、柜次和装柜计划，不新建独立“出仓单”。
+
+## 1. 阶段目标和边界
+
+本阶段把可分柜货物转化为可追溯的真实整柜离仓事实，覆盖：
+
+1. 模拟柜、智能推荐、人工分配和同柜不可拆组；
+2. 海运订舱草稿、资料补齐和放舱；
+3. 订舱级国内拖车预约；
+4. 模拟柜与订舱柜型需求、真实集装箱号关联；
+5. 预装确认、动态增减和普通散货托盘标签；
+6. 国内 PDA 拣货、整托装柜和异常闭环；
+7. 四步装柜照片、铅封照片与铅封号；
+8. 装柜完成、部分装载分片和跨区交接快照；
+9. 客户资料、整柜出口报关与放行；
+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；
+- 柜型规格、国内中转仓、有效渠道和供应商主档可用；
+- 操作员理解模拟柜、真实柜号、订舱和拖车是不同对象；
+- 同柜不可拆组、已占用数量和版本冲突均以服务端返回为准；
+- 费用仍可并行维护，但已经确认/发送或客户已确认版本不得被静默改写。
+
+## 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. `PHOTO_STEP_1`：装柜初始/空柜；
+2. `PHOTO_STEP_2`：装载过程；
+3. `PHOTO_STEP_3`：接近完成；
+4. `PHOTO_STEP_4`：满柜/关门前；
+5. `SEAL`：带有效铅封号的封柜照片。
+
+每类至少一张有效照片，同类允许追加。PDA 仅允许现场相机拍摄；有权限的 Admin 操作员/理货员可人工补充，普通拣货员不开放后台上传。
+
+证据先上传 File 获得合法文件引用，再绑定柜次/任务。错误图片只能作废，不能硬删除；需保留上传、作废、操作者、时间、文件哈希和幂等记录。照片及铅封号当前不对客户展示。
+
+## 11. F21 装柜完成与分片
+
+PDA 点击“完成装柜”时，服务端重新校验：
+
+- 任务属于当前柜次和仓库且版本一致；
+- 真实集装箱号存在；
+- 所有普通箱码或一件代发整托均核平；
+- 没有未解决异常；
+- 四步照片和带铅封号的 `SEAL` 完整；
+- 计划明细、已拣数量和最终实装数量守恒。
+
+校验通过后：
+
+1. PDA 任务和装柜计划进入 `COMPLETED`；
+2. 实装来源入库单进入 `LOADED`；
+3. 生成最终实装箱码、托盘、SKU 和证据快照；
+4. 对部分装载执行一次分片；
+5. 生成跨区 Outbox，但后续消费必须保持幂等。
+
+部分装载时，已装数量形成当前柜次的 `LOADED` 子入库单，余量形成可继续 `WAIT_SPLIT` 的后续子单；只允许一层分片，所有子项总和必须等于来源数量。客户订单身份和入仓码关联不能丢失。
+
+## 12. F22 客户资料与整柜出口报关
+
+### 12.1 客户上传资料
+
+入口：Client → 头程订单 → 报关资料。
+
+客户只可对本企业订单上传退税/报关资料，选择资料类型并填写说明。文件归属、订单归属和客户身份由服务端校验，文件名不能代替合法文件 ID。
+
+### 12.2 平台整柜报关
+
+入口：Admin → 柜次详情 → 出口报关。
+
+1. 查看柜内所有入仓码及其资料覆盖情况；
+2. 对退税资料逐项核对，缺件时联系对应客户补充；
+3. 开始报关时冻结当前参与资料和版本；
+4. 线下向报关代理提交；首版不做外部系统直连；
+5. 完成后为每份退税资料上传一一对应的完成文件；
+6. 全买单柜由平台确认买单，并从导出中心获取最终实装买单明细；
+7. 点击完成整柜报关，写入放行结果和历史。
+
+报关完成后系统立即尝试国内出仓；若其他门禁尚未齐全，保留明确阻断项并由受控补偿重试，不能伪装为已离仓。
+
+## 13. F23 国内出仓
+
+### 13.1 出仓硬门禁
+
+整柜所有关联入库单逐项检查：
+
+- 无有效 HOLD；
+- 入库单为 `LOADED`；
+- 装柜计划为 `COMPLETED`；
+- PDA 柜次任务为 `COMPLETED`；
+- 订舱已 `RELEASED` 且分配当前柜次；
+- 四步照片与有效铅封完整；
+- 整柜报关已完成并放行。
+
+独立拖车状态和独立船期字段提供调度参考，但不是当前确认离仓的硬门禁。拖车在全部订舱柜次离仓后自动完成。
+
+### 13.2 自动与人工确认离仓
+
+报关完成或其他门禁变化时系统自动尝试收敛。未自动完成时，平台在柜次/国内出仓页面：
+
+1. 打开门禁清单；
+2. 逐项处理未通过原因；
+3. 全部通过后点击确认离仓；
+4. 携带当前版本和幂等键提交；
+5. 查看唯一离仓历史和第一条实际节点。
+
+成功后系统：
+
+- 写入整柜唯一国内离仓事实；
+- 创建 `CarrierScheduleQuery`；
+- 写入实际 `DEPARTED_WAREHOUSE` 节点；
+- 触发出仓后船节点查询；
+- 检查并尝试完成订舱级拖车；
+- 保持跨区交接事件可重试且不重复建单。
+
+实际离仓节点产生后禁止撤销。发现错误转入线下和后续阶段异常处理，不提供修改历史伪装未离仓的能力。
+
+## 14. 状态和动作总表
+
+| 对象 | 关键状态 | 推进动作 |
+|---|---|---|
+| 入库单 | `WAIT_SPLIT → LOADING → LOADED` | 分配/开始 PDA/完成装柜 |
+| 装柜计划 | `EDITING → LOADING → COMPLETED` | 预装调整/PDA 作业/最终完成 |
+| 订舱 | `DRAFT → RELEASED` | 补齐资料并放舱 |
+| 拖车 | 非终态 → `COMPLETED` | 所有要求柜次实际离仓后自动完成 |
+| 报关 | 资料收集 → 已冻结办理中 → 已完成/放行 | 客户上传、平台开始、上传回执并完成 |
+| 国内出仓 | 等待门禁 → 可出仓 → 已离仓 | 自动尝试或平台确认 |
+
+主状态只表达阶段结果。订舱、拖车、PDA、证据和报关保持关联子状态，页面应汇聚展示，但不能互相覆盖。
+
+## 15. 异常与恢复
+
+| 场景 | 处理方式 |
+|---|---|
+| 候选显示可用但提交失败 | 以服务端最新占用/版本为准，刷新后重排 |
+| 待测量订单已占位 | 可保留计划占位，确认预装前必须到 `WAIT_SPLIT` |
+| 一件代发整托容量不足 | 跳过整托或换柜，禁止拆托 |
+| 订舱资料不全 | 保持 `DRAFT`，补齐后再放舱 |
+| 放舱后资料错误 | 不原地篡改冻结快照，按业务异常处置 |
+| 真实柜号暂缺 | 可先关联/确认，但最终装柜前必须补齐 |
+| PDA 旧版本 | 刷新计划，不以旧版本覆盖新增明细 |
+| 扫描错箱/重复箱 | 拒绝或提示已处理，核对稳定箱码 |
+| 未完成项有异常 | 记录原因并解决，禁止完成任务 |
+| 照片错误 | 作废并重拍，不硬删除证据 |
+| 部分装载 | 一次分片，已装与余量数量守恒 |
+| 报关资料缺失 | 定位对应客户/入仓码补件，办理批次不伪造完成 |
+| 出仓门禁未齐 | 展示具体阻断项，条件变化后受控重试 |
+| 离仓请求超时 | 查询唯一离仓历史/节点后再处理，不重复写事实 |
+
+## 16. 数据流和阶段完成判定
+
+```text
+WAIT_SPLIT 入库单/已封托托盘
+  → 模拟柜与唯一装柜计划
+  → 已放舱订舱 + 真实柜号 + 订舱级拖车
+  → 预装确认/动态调整
+  → PDA 实装 + 五类证据
+  → COMPLETED / LOADED + 数量分片 + 跨区快照
+  → 整柜报关放行
+  → 国内离仓 + DEPARTED_WAREHOUSE + 船节点查询任务
+```
+
+阶段完成必须同时满足：
+
+- [ ] 最终柜次、装柜计划、订舱、真实柜号关联可追溯
+- [ ] 全部实装箱/托盘/SKU 与入库单数量守恒
+- [ ] PDA 任务完成且无未解决异常
+- [ ] 四步照片、铅封照片和铅封号完整有效
+- [ ] 装柜计划 `COMPLETED`，实装入库单 `LOADED`
+- [ ] 部分装载时已装子单和余量子单正确
+- [ ] 整柜报关已完成并放行
+- [ ] 所有入库单无 HOLD
+- [ ] 唯一国内离仓历史存在
+- [ ] 第一条实际 `DEPARTED_WAREHOUSE` 存在
+- [ ] 船节点查询任务和跨区事件可幂等重试
+
+## 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`

头程到尾程分阶段流程/阶段二-国内到仓测量计费与组托.md

@@ -0,0 +1,592 @@
+# 阶段二：国内到仓、测量计费与组托
+
+> 对应全景流程：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`

头程到尾程分阶段流程/阶段五-海外接柜库存与库内服务.md

@@ -0,0 +1,405 @@
+# 阶段五：海外接柜、库存与库内服务
+
+> 对应全景流程：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. 阶段完成判定
+
+主链完成必须满足：
+
+- [ ] 柜号由正确仓库操作员认领
+- [ ] 国内五类证据可对照，海外三类签收照片齐全
+- [ ] 实际到仓时间来自首次收货会话
+- [ ] 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`

头程到尾程分阶段流程/阶段六-海外排车出库派送与回写.md

@@ -0,0 +1,310 @@
+# 阶段六：海外排车、出库、派送与最终回写
+
+> 对应全景流程：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. 全流程最终完成判定
+
+- [ ] 排车候选来自真实、可用且未被其他业务占用的库存
+- [ ] 草稿锁、正式锁和取消/完成释放均可追溯
+- [ ] 排车路线由实际目的地生成
+- [ ] 转派送只发生一次且早于发车
+- [ ] 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`

头程到尾程分阶段流程/阶段四-海运目的港与尾程计划.md

@@ -0,0 +1,388 @@
+# 阶段四：海运、目的港与尾程入仓计划
+
+> 对应全景流程：F24～F27。  
+> 阶段起点：柜次已确认国内离仓，存在实际 `DEPARTED_WAREHOUSE` 节点和可查询的真实订舱/柜次。  
+> 阶段终点：跨区尾程订单完整生成，整柜每票入仓计划及托盘/库位资源已生成或有明确资源失败待办，订单进入 `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`。任务必须绑定真实订舱、柜次以及可用的船司、船名航次、提单号或柜号，不创建脱离业务单据的孤立轮询任务。
+
+首个实际节点由国内出仓写入：
+
+```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. 阶段完成判定
+
+- [ ] 国内离仓产生的船节点任务绑定真实订舱和柜次
+- [ ] 节点预计/实际/观测时间没有混用
+- [ ] 异常事实与正常节点分开保存
+- [ ] 实际 `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/`

头程到尾程流程/头程到尾程逐节点思维导图.md

@@ -0,0 +1,172 @@
+# 头程到尾程逐节点思维导图
+
+2026年9月22日 · 人工梳理与分工版
+
+按实际业务节点编号，不限定阶段或步数。展开每个节点查看负责人、正常去向、异常处理和特殊分支。
+
+岗位为建议分工，姓名留空待填；异常转交路径供人工确认。编号用于讨论定位，可并行或提前的动作以节点说明为准。
+
+标记“待确认”的处理入口或完结规则，需要人工补充，不能当作已具备的系统能力。
+
+思维导图源文件：[头程到尾程逐节点思维导图.mm](头程到尾程逐节点思维导图.mm)。可在支持 FreeMind 格式的软件中导入，填写姓名、增删节点。
+
+新增步骤可沿用相邻编号加字母，例如 04A。详细依据保留在[原梳理文档](头程柜级履约尾程流程节点责任与异常梳理.md)。
+
+- **01 客户下单**
+  - 负责人：客户下单员 · 姓名____
+  - 正常：提交订单 → 02 审核；同时安排 03 送仓。
+  - 异常：资料缺失／下单失败 → 客服协助客户补正 → 重新提交。
+
+- **02 订单审核**
+  - 负责人：订单审核员 · 姓名____
+  - 正常：审核通过；与 03—05 可并行，06 测量审核通过前须完成本步。
+  - 异常：申报／渠道有误 → 审核员联系客户补正 → 重新审核。
+
+- **03 拉货／客户送仓**
+  - 负责人：国内提货跟单 · 姓名____
+  - 正常：上门拉货或客户自送 → 04 到仓收货。
+  - 异常：未备货／迟到／运输破损 → 提货跟单联系客户、司机 → 改约或补交接记录。
+  - 说明：拉货执行、司机交接的现场规则待补充；当前系统主要记录预约信息。
+
+- **04 国内到仓收货**
+  - 负责人：国内收货员 · 姓名____
+  - 正常：核对订单、箱数、外包装 → 05 称重测量。
+  - 异常：无单／少件／多件／破损 → 收货员留证，仓库主管与客服核对 → 明确收货处理后交测量。
+
+- **05 称重测量**
+  - 负责人：国内测量员 · 姓名____
+  - 正常：采集重量、尺寸、箱数和图片 → 06 测量审核；称重确认时开始分配库位。
+  - 异常：漏测／错码／读数异常 → 测量员复测补证 → 重新提交审核。
+
+- **06 测量审核**
+  - 负责人：测量审核员 · 姓名____
+  - 正常：普通货审核通过 → 07 在库交接 → 08 排柜；一件代发另走下方分支。
+  - 异常：数据／证据存疑 → 审核员联系测量员复核 → 再审；退回修改入口待确认。
+  - **06A 一件代发拆箱清点**
+    - 负责人：国内清点员 · 姓名____
+    - 正常：按箱核对 SKU 与数量 → 06B 归托封托。
+    - 异常：差异 → 仓库主管、客服核对；接受差异须留原因，接受权限待定。
+  - **06B 打托／归托／封托**
+    - 负责人：国内打托员 · 姓名____
+    - 正常：清点完成、封托完成 → 08 排柜；封托托盘作为不可拆分单元。
+    - 异常：漏清点／托盘未封 → 国内仓主管安排补作业 → 封托后继续。
+
+- **07 国内入库／库位确认**
+  - 负责人：国内仓管 · 姓名____
+  - 正常：确认货物所在库位和交接信息 → 08 排柜；库位安排随 05 开始，本步核对在库结果。
+  - 异常：库位不足／货位不符 → 国内仓主管落实存放位置并核对记录 → 交接后继续。
+
+- **08 排柜／分柜**
+  - 负责人：柜务 · 姓名____
+  - 正常：确定本柜装哪些货 → 11 国内拣货；可与 09 订舱准备并行。
+  - 异常：超容／扣货／审核未完成 → 柜务协调仓库、审核员 → 调整计划或解除阻断后再拣货。
+  - 说明：待审核、待测量可先占位；实物作业须满足审核、清点封托等条件。
+
+- **09 订舱／放舱**
+  - 负责人：船务 · 姓名____
+  - 正常：确认舱位、船期和放舱资料 → 10 国内拖柜。
+  - 异常：无舱／甩柜／船期调整 → 船务协调船司、柜务 → 确认新船期及装柜安排。
+
+- **10 国内拖柜：预约、提柜到仓**
+  - 负责人：国内运输跟单 · 姓名____
+  - 正常：订舱已放舱、资料齐全后预约；司机提空柜到国内仓 → 12 装柜。
+  - 异常：车不到／柜不可用／资料缺失 → 运输跟单联络车队、船务 → 补资料或重新安排。
+
+- **11 国内拣货**
+  - 负责人：国内拣货员 · 姓名____
+  - 正常：按装柜计划找到货物、扫码核对 → 12 装柜。
+  - 异常：找不到／错货／少件／扣货 → 国内仓主管与柜务核对 → 补拣、调整计划或解除阻断。
+
+- **12 装柜完成**
+  - 负责人：国内装柜主管 · 姓名____
+  - 正常：核对实装、柜号和装柜证据 → 13 出口报关；同时开始海外接柜准备。
+  - 异常：实装不符／装不下／证据缺失 → 装柜主管与柜务核实 → 调整、补证后确认完成。
+  - **12A 海外接柜准备**
+    - 负责人：海外计划员 · 姓名____
+    - 正常：装柜完成后系统生成尾程订单 → 人工准备入仓计划、托盘与库位 → 18 拆柜收货。
+    - 异常：订单未同步／计划或资源缺失 → 计划员联系履约运营、仓库主管补齐；系统失败转技术处理。
+
+- **13 出口报关**
+  - 负责人：出口报关专员 · 姓名____
+  - 正常：装柜完成后处理整柜报关、收齐完成资料 → 14 国内出仓。
+  - 异常：资料缺失／退单／查验 → 报关专员联系客户、代理 → 补正或配合查验，完成后继续。
+
+- **14 国内出仓**
+  - 负责人：国内出仓员 · 姓名____
+  - 正常：报关完成且出仓条件齐备 → 确认离仓，交 15 海运跟踪。
+  - 异常：报关未完成／扣货／交接不符 → 出仓员暂停放行，联系对应主责 → 条件满足后出仓。
+
+- **15 海运／到港跟踪**
+  - 负责人：船务 · 姓名____
+  - 正常：跟踪开船、到港、卸船 → 与 16 清关、17 提柜衔接。
+  - 异常：延误／改港／节点未更新 → 船务核实船司消息 → 更新计划并交客服通知客户。
+
+- **16 目的港清关**
+  - 负责人：海外清关专员 · 姓名____
+  - 正常：可提前备资料；确认清关放行和提柜条件 → 17 海外提柜。
+  - 异常：补件／查验／未放行 → 清关专员联系代理、客户 → 处理并确认可提柜后继续。
+
+- **17 海外提柜／送仓**
+  - 负责人：海外运输跟单 · 姓名____
+  - 正常：预约港口提柜、协调海外仓接收 → 18 拆柜收货。
+  - 异常：无车／提柜失败／仓库约不上 → 海外运输跟单协调港口、车队、仓库 → 改约并跟进额外费用。
+
+- **18 海外拆柜收货**
+  - 负责人：海外收货员 · 姓名____
+  - 正常：按入仓计划扫描、清点、记录实收 → 无差异时交 19 入库。
+  - 异常：短收／超收 → 海外仓主管登记差异、留证 → 待核平；可结束卸柜，但不能直接成为可用库存，核平入口待确认。
+  - **18A 卸柜后还空柜**
+    - 负责人：海外运输跟单 · 姓名____
+    - 正常：卸柜结束 → 安排还空并记录凭证；与后续库存、出库流程并行。
+    - 异常：还空受阻／临近截止 → 海外运输跟单联系车队、堆场 → 调整还空安排并跟进费用。
+
+- **19 海外入库／库位确认**
+  - 负责人：海外仓管 · 姓名____
+  - 正常：正常收货形成库存，核对真实托盘、库位和可用数量 → 20 排车。
+  - 异常：库位不符／暂扣／数量仍有差异 → 海外仓主管核实 → 满足可用条件后再交拣货。
+  - **19A 一件代发独立出库**
+    - 负责人：一件代发运营 · 姓名____
+    - 正常：按独立出库单逐箱或整托拣货，核对 SKU 与数量后出库；签收、回访和整单完结衔接待确认。
+    - 异常：缺货／错 SKU／数量不符 → 代发运营与海外仓核对 → 补货或调整后再出库。
+
+- **20 海外排车**
+  - 负责人：海外调度 · 姓名____
+  - 正常：确定车辆、路线、目的地与货物 → 21 转派送、22 拣货；可提前预排，实际拣货须有可用库存。
+  - 异常：无车／预约冲突／库存不足 → 海外调度协调仓库、车队 → 调整排车与交付安排。
+
+- **21 转派送／生成待出库单**
+  - 负责人：海外调度 · 姓名____
+  - 正常：生成派送关联和待出库单 → 23 发车前核对；可在 22 拣货前或过程中进行，必须早于 24 发车。
+  - 异常：资料缺失／生成失败 → 海外调度补齐资料、核实关联 → 成功后才能发车。
+
+- **22 按排车拣货**
+  - 负责人：海外拣货员 · 姓名____
+  - 正常：按排车任务、托盘与库位扫描拣货 → 23 核平复核。
+  - 异常：少货／错托／暂扣／货位不符 → 海外仓主管核查 → 补拣或协调调度调整。
+
+- **23 拣货核平／发车前复核**
+  - 负责人：海外仓主管 · 姓名____
+  - 正常：核对实拣、出库单、车辆及必需资料 → 条件齐备交 24 发车。
+  - 异常：数量未核平／单据缺失 → 海外仓主管联系拣货员、调度补齐 → 复核无误后继续。
+  - 说明：此处是作业检查节点，不表示另设一项系统审批。
+
+- **24 发车／确认出库**
+  - 负责人：海外出库员 · 姓名____
+  - 正常：按系统可发车条件确认发车、完成出库 → 25 派送签收；调度负责车辆交接。
+  - 异常：系统阻断／司机未到／交接不符 → 出库员暂停，海外调度协调处理 → 满足条件后发车。
+
+- **25 派送／签收**
+  - 负责人：派送运营 · 姓名____
+  - 正常：送达、保存有效签收资料 → 26 整单完结核对；同时进入 27 客户回访。
+  - 异常：拒签／送达失败 → 派送运营登记异常 → 退回时按实收恢复到真实托盘、库位 → 另行安排后续；不按正常签收完结。
+
+- **26 整单完结**
+  - 负责人：履约运营 · 姓名____
+  - 正常：全部有效履约片段完成后，系统汇总整单完结；履约运营核对结果。
+  - 异常：还有余货／其他柜未完成／回传失败 → 履约运营追踪对应环节，系统故障转技术 → 齐备后完结。
+  - 说明：27 回访独立进行；财务结清另行核对。
+
+- **27 客户回访**
+  - 负责人：客服 · 姓名____
+  - 正常：普通派送签收后回访，记录反馈、处理结果和附件；与 26 整单完结核对并行。
+  - 异常：联系不上／投诉／索赔 → 客服持续跟进，交对应业务主管处理 → 反馈客户并补回访记录。

头程到尾程流程/头程到尾程逐节点思维导图.mm

@@ -0,0 +1,178 @@
+<?xml version='1.0' encoding='utf-8'?>
+<map version="1.0.1">
+  <node TEXT="头程 → 柜子 → 尾程｜逐节点流程" ID="logistics-process" FOLDED="false">
+    <richcontent TYPE="NOTE">
+      <html>
+        <body>
+          <p>按实际业务节点编号，不限定阶段或步数。展开每个节点查看负责人、正常去向、异常处理和特殊分支。</p>
+          <p>岗位为建议分工，姓名留空待填；异常转交路径供人工确认。编号用于讨论定位，可并行或提前的动作以节点说明为准。</p>
+          <p>标记“待确认”的处理入口或完结规则，需要人工补充，不能当作已具备的系统能力。</p>
+        </body>
+      </html>
+    </richcontent>
+    <node TEXT="01 客户下单｜客户下单员" ID="step-01" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：客户下单员 · 姓名____" />
+      <node TEXT="正常：提交订单 → 02 审核；同时安排 03 送仓。" />
+      <node TEXT="异常：资料缺失／下单失败 → 客服协助客户补正 → 重新提交。" />
+    </node>
+    <node TEXT="02 订单审核｜订单审核员" ID="step-02" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：订单审核员 · 姓名____" />
+      <node TEXT="正常：审核通过；与 03—05 可并行，06 测量审核通过前须完成本步。" />
+      <node TEXT="异常：申报／渠道有误 → 审核员联系客户补正 → 重新审核。" />
+    </node>
+    <node TEXT="03 拉货／客户送仓｜国内提货跟单" ID="step-03" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内提货跟单 · 姓名____" />
+      <node TEXT="正常：上门拉货或客户自送 → 04 到仓收货。" />
+      <node TEXT="异常：未备货／迟到／运输破损 → 提货跟单联系客户、司机 → 改约或补交接记录。" />
+      <node TEXT="说明：拉货执行、司机交接的现场规则待补充；当前系统主要记录预约信息。" />
+    </node>
+    <node TEXT="04 国内到仓收货｜国内收货员" ID="step-04" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内收货员 · 姓名____" />
+      <node TEXT="正常：核对订单、箱数、外包装 → 05 称重测量。" />
+      <node TEXT="异常：无单／少件／多件／破损 → 收货员留证，仓库主管与客服核对 → 明确收货处理后交测量。" />
+    </node>
+    <node TEXT="05 称重测量｜国内测量员" ID="step-05" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内测量员 · 姓名____" />
+      <node TEXT="正常：采集重量、尺寸、箱数和图片 → 06 测量审核；称重确认时开始分配库位。" />
+      <node TEXT="异常：漏测／错码／读数异常 → 测量员复测补证 → 重新提交审核。" />
+    </node>
+    <node TEXT="06 测量审核｜测量审核员" ID="step-06" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：测量审核员 · 姓名____" />
+      <node TEXT="正常：普通货审核通过 → 07 在库交接 → 08 排柜；一件代发另走下方分支。" />
+      <node TEXT="异常：数据／证据存疑 → 审核员联系测量员复核 → 再审；退回修改入口待确认。" />
+      <node TEXT="06A 一件代发拆箱清点｜国内清点员" ID="step-06A" FOLDED="true">
+        <node TEXT="负责人：国内清点员 · 姓名____" />
+        <node TEXT="正常：按箱核对 SKU 与数量 → 06B 归托封托。" />
+        <node TEXT="异常：差异 → 仓库主管、客服核对；接受差异须留原因，接受权限待定。" />
+      </node>
+      <node TEXT="06B 打托／归托／封托｜国内打托员" ID="step-06B" FOLDED="true">
+        <node TEXT="负责人：国内打托员 · 姓名____" />
+        <node TEXT="正常：清点完成、封托完成 → 08 排柜；封托托盘作为不可拆分单元。" />
+        <node TEXT="异常：漏清点／托盘未封 → 国内仓主管安排补作业 → 封托后继续。" />
+      </node>
+    </node>
+    <node TEXT="07 国内入库／库位确认｜国内仓管" ID="step-07" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内仓管 · 姓名____" />
+      <node TEXT="正常：确认货物所在库位和交接信息 → 08 排柜；库位安排随 05 开始，本步核对在库结果。" />
+      <node TEXT="异常：库位不足／货位不符 → 国内仓主管落实存放位置并核对记录 → 交接后继续。" />
+    </node>
+    <node TEXT="08 排柜／分柜｜柜务" ID="step-08" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：柜务 · 姓名____" />
+      <node TEXT="正常：确定本柜装哪些货 → 11 国内拣货；可与 09 订舱准备并行。" />
+      <node TEXT="异常：超容／扣货／审核未完成 → 柜务协调仓库、审核员 → 调整计划或解除阻断后再拣货。" />
+      <node TEXT="说明：待审核、待测量可先占位；实物作业须满足审核、清点封托等条件。" />
+    </node>
+    <node TEXT="09 订舱／放舱｜船务" ID="step-09" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：船务 · 姓名____" />
+      <node TEXT="正常：确认舱位、船期和放舱资料 → 10 国内拖柜。" />
+      <node TEXT="异常：无舱／甩柜／船期调整 → 船务协调船司、柜务 → 确认新船期及装柜安排。" />
+    </node>
+    <node TEXT="10 国内拖柜：预约、提柜到仓｜国内运输跟单" ID="step-10" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内运输跟单 · 姓名____" />
+      <node TEXT="正常：订舱已放舱、资料齐全后预约；司机提空柜到国内仓 → 12 装柜。" />
+      <node TEXT="异常：车不到／柜不可用／资料缺失 → 运输跟单联络车队、船务 → 补资料或重新安排。" />
+    </node>
+    <node TEXT="11 国内拣货｜国内拣货员" ID="step-11" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内拣货员 · 姓名____" />
+      <node TEXT="正常：按装柜计划找到货物、扫码核对 → 12 装柜。" />
+      <node TEXT="异常：找不到／错货／少件／扣货 → 国内仓主管与柜务核对 → 补拣、调整计划或解除阻断。" />
+    </node>
+    <node TEXT="12 装柜完成｜国内装柜主管" ID="step-12" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内装柜主管 · 姓名____" />
+      <node TEXT="正常：核对实装、柜号和装柜证据 → 13 出口报关；同时开始海外接柜准备。" />
+      <node TEXT="异常：实装不符／装不下／证据缺失 → 装柜主管与柜务核实 → 调整、补证后确认完成。" />
+      <node TEXT="12A 海外接柜准备｜海外计划员" ID="step-12A" FOLDED="true">
+        <node TEXT="负责人：海外计划员 · 姓名____" />
+        <node TEXT="正常：装柜完成后系统生成尾程订单 → 人工准备入仓计划、托盘与库位 → 18 拆柜收货。" />
+        <node TEXT="异常：订单未同步／计划或资源缺失 → 计划员联系履约运营、仓库主管补齐；系统失败转技术处理。" />
+      </node>
+    </node>
+    <node TEXT="13 出口报关｜出口报关专员" ID="step-13" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：出口报关专员 · 姓名____" />
+      <node TEXT="正常：装柜完成后处理整柜报关、收齐完成资料 → 14 国内出仓。" />
+      <node TEXT="异常：资料缺失／退单／查验 → 报关专员联系客户、代理 → 补正或配合查验，完成后继续。" />
+    </node>
+    <node TEXT="14 国内出仓｜国内出仓员" ID="step-14" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：国内出仓员 · 姓名____" />
+      <node TEXT="正常：报关完成且出仓条件齐备 → 确认离仓，交 15 海运跟踪。" />
+      <node TEXT="异常：报关未完成／扣货／交接不符 → 出仓员暂停放行，联系对应主责 → 条件满足后出仓。" />
+    </node>
+    <node TEXT="15 海运／到港跟踪｜船务" ID="step-15" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：船务 · 姓名____" />
+      <node TEXT="正常：跟踪开船、到港、卸船 → 与 16 清关、17 提柜衔接。" />
+      <node TEXT="异常：延误／改港／节点未更新 → 船务核实船司消息 → 更新计划并交客服通知客户。" />
+    </node>
+    <node TEXT="16 目的港清关｜海外清关专员" ID="step-16" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外清关专员 · 姓名____" />
+      <node TEXT="正常：可提前备资料；确认清关放行和提柜条件 → 17 海外提柜。" />
+      <node TEXT="异常：补件／查验／未放行 → 清关专员联系代理、客户 → 处理并确认可提柜后继续。" />
+    </node>
+    <node TEXT="17 海外提柜／送仓｜海外运输跟单" ID="step-17" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外运输跟单 · 姓名____" />
+      <node TEXT="正常：预约港口提柜、协调海外仓接收 → 18 拆柜收货。" />
+      <node TEXT="异常：无车／提柜失败／仓库约不上 → 海外运输跟单协调港口、车队、仓库 → 改约并跟进额外费用。" />
+    </node>
+    <node TEXT="18 海外拆柜收货｜海外收货员" ID="step-18" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外收货员 · 姓名____" />
+      <node TEXT="正常：按入仓计划扫描、清点、记录实收 → 无差异时交 19 入库。" />
+      <node TEXT="异常：短收／超收 → 海外仓主管登记差异、留证 → 待核平；可结束卸柜，但不能直接成为可用库存，核平入口待确认。" />
+      <node TEXT="18A 卸柜后还空柜｜海外运输跟单" ID="step-18A" FOLDED="true">
+        <node TEXT="负责人：海外运输跟单 · 姓名____" />
+        <node TEXT="正常：卸柜结束 → 安排还空并记录凭证；与后续库存、出库流程并行。" />
+        <node TEXT="异常：还空受阻／临近截止 → 海外运输跟单联系车队、堆场 → 调整还空安排并跟进费用。" />
+      </node>
+    </node>
+    <node TEXT="19 海外入库／库位确认｜海外仓管" ID="step-19" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外仓管 · 姓名____" />
+      <node TEXT="正常：正常收货形成库存，核对真实托盘、库位和可用数量 → 20 排车。" />
+      <node TEXT="异常：库位不符／暂扣／数量仍有差异 → 海外仓主管核实 → 满足可用条件后再交拣货。" />
+      <node TEXT="19A 一件代发独立出库｜一件代发运营" ID="step-19A" FOLDED="true">
+        <node TEXT="负责人：一件代发运营 · 姓名____" />
+        <node TEXT="正常：按独立出库单逐箱或整托拣货，核对 SKU 与数量后出库；签收、回访和整单完结衔接待确认。" />
+        <node TEXT="异常：缺货／错 SKU／数量不符 → 代发运营与海外仓核对 → 补货或调整后再出库。" />
+      </node>
+    </node>
+    <node TEXT="20 海外排车｜海外调度" ID="step-20" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外调度 · 姓名____" />
+      <node TEXT="正常：确定车辆、路线、目的地与货物 → 21 转派送、22 拣货；可提前预排，实际拣货须有可用库存。" />
+      <node TEXT="异常：无车／预约冲突／库存不足 → 海外调度协调仓库、车队 → 调整排车与交付安排。" />
+    </node>
+    <node TEXT="21 转派送／生成待出库单｜海外调度" ID="step-21" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外调度 · 姓名____" />
+      <node TEXT="正常：生成派送关联和待出库单 → 23 发车前核对；可在 22 拣货前或过程中进行，必须早于 24 发车。" />
+      <node TEXT="异常：资料缺失／生成失败 → 海外调度补齐资料、核实关联 → 成功后才能发车。" />
+    </node>
+    <node TEXT="22 按排车拣货｜海外拣货员" ID="step-22" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外拣货员 · 姓名____" />
+      <node TEXT="正常：按排车任务、托盘与库位扫描拣货 → 23 核平复核。" />
+      <node TEXT="异常：少货／错托／暂扣／货位不符 → 海外仓主管核查 → 补拣或协调调度调整。" />
+    </node>
+    <node TEXT="23 拣货核平／发车前复核｜海外仓主管" ID="step-23" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外仓主管 · 姓名____" />
+      <node TEXT="正常：核对实拣、出库单、车辆及必需资料 → 条件齐备交 24 发车。" />
+      <node TEXT="异常：数量未核平／单据缺失 → 海外仓主管联系拣货员、调度补齐 → 复核无误后继续。" />
+      <node TEXT="说明：此处是作业检查节点，不表示另设一项系统审批。" />
+    </node>
+    <node TEXT="24 发车／确认出库｜海外出库员" ID="step-24" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：海外出库员 · 姓名____" />
+      <node TEXT="正常：按系统可发车条件确认发车、完成出库 → 25 派送签收；调度负责车辆交接。" />
+      <node TEXT="异常：系统阻断／司机未到／交接不符 → 出库员暂停，海外调度协调处理 → 满足条件后发车。" />
+    </node>
+    <node TEXT="25 派送／签收｜派送运营" ID="step-25" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：派送运营 · 姓名____" />
+      <node TEXT="正常：送达、保存有效签收资料 → 26 整单完结核对；同时进入 27 客户回访。" />
+      <node TEXT="异常：拒签／送达失败 → 派送运营登记异常 → 退回时按实收恢复到真实托盘、库位 → 另行安排后续；不按正常签收完结。" />
+    </node>
+    <node TEXT="26 整单完结｜履约运营" ID="step-26" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：履约运营 · 姓名____" />
+      <node TEXT="正常：全部有效履约片段完成后，系统汇总整单完结；履约运营核对结果。" />
+      <node TEXT="异常：还有余货／其他柜未完成／回传失败 → 履约运营追踪对应环节，系统故障转技术 → 齐备后完结。" />
+      <node TEXT="说明：27 回访独立进行；财务结清另行核对。" />
+    </node>
+    <node TEXT="27 客户回访｜客服" ID="step-27" FOLDED="true" POSITION="right">
+      <node TEXT="负责人：客服 · 姓名____" />
+      <node TEXT="正常：普通派送签收后回访，记录反馈、处理结果和附件；与 26 整单完结核对并行。" />
+      <node TEXT="异常：联系不上／投诉／索赔 → 客服持续跟进，交对应业务主管处理 → 反馈客户并补回访记录。" />
+    </node>
+  </node>
+</map>

头程到尾程流程/头程到尾程顺序回路流程图.drawio

@@ -0,0 +1,63 @@
+<mxfile host="app.diagrams.net" modified="2026-09-22T00:00:00.000Z" agent="Codex" version="24.7.17">
+  <diagram id="sequential-loop-flow" name="顺序回路示例">
+    <mxGraphModel dx="1200" dy="900" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="n01" value="01 客户下单&#10;负责人：客户下单员&#10;通过→下一节点&#10;异常：资料补正" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="60" y="40" width="270" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="e01" value="异常处理&#10;客服协助补正后回 01" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="420" y="45" width="260" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="bad-01" value="异常" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="n01" target="e01" />
+        <mxCell id="back-01" value="处理完成，回本节点复核" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="e01" target="n01" />
+        <mxCell id="next-01" value="通过" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;strokeColor=#6c8ebf;endArrow=block;html=1;" edge="1" parent="1" source="n01" target="n02" />
+        <mxCell id="n02" value="02 订单审核&#10;负责人：订单审核员&#10;通过→下一节点&#10;异常：申报／渠道有误" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="60" y="180" width="270" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="e02" value="异常处理&#10;补正后回 02" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="420" y="185" width="260" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="bad-02" value="异常" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="n02" target="e02" />
+        <mxCell id="back-02" value="处理完成，回本节点复核" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="e02" target="n02" />
+        <mxCell id="next-02" value="通过" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;strokeColor=#6c8ebf;endArrow=block;html=1;" edge="1" parent="1" source="n02" target="n03" />
+        <mxCell id="n03" value="03 拉货／客户送仓&#10;负责人：国内提货跟单&#10;通过→下一节点&#10;异常：未备货／迟到／破损" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="60" y="320" width="270" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="e03" value="异常处理&#10;改约或补交接后回 03" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="420" y="325" width="260" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="bad-03" value="异常" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="n03" target="e03" />
+        <mxCell id="back-03" value="处理完成，回本节点复核" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="e03" target="n03" />
+        <mxCell id="next-03" value="通过" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;strokeColor=#6c8ebf;endArrow=block;html=1;" edge="1" parent="1" source="n03" target="n04" />
+        <mxCell id="n04" value="04 到仓验收与测量&#10;负责人：收货员／测量员&#10;通过→下一节点&#10;异常：差异／漏测／错码" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="60" y="460" width="270" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="e04" value="异常处理&#10;补收或复测后回 04" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="420" y="465" width="260" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="bad-04" value="异常" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="n04" target="e04" />
+        <mxCell id="back-04" value="处理完成，回本节点复核" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="e04" target="n04" />
+        <mxCell id="next-04" value="通过" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;strokeColor=#6c8ebf;endArrow=block;html=1;" edge="1" parent="1" source="n04" target="n05" />
+        <mxCell id="n05" value="05 测量审核&#10;负责人：测量审核员&#10;通过→下一节点&#10;异常：数据或证据存疑" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="60" y="600" width="270" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="e05" value="异常处理&#10;复测补证后回 05；订单门禁回 02" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="420" y="605" width="260" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="bad-05" value="异常" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="n05" target="e05" />
+        <mxCell id="back-05" value="处理完成，回本节点复核" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="e05" target="n05" />
+        <mxCell id="next-05" value="通过" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;strokeColor=#6c8ebf;endArrow=block;html=1;" edge="1" parent="1" source="n05" target="n06" />
+        <mxCell id="n06" value="06 入库／库位确认&#10;负责人：国内仓管&#10;通过→下一节点&#10;异常：库位不足／货位不符" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="60" y="740" width="270" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="e06" value="异常处理&#10;落实位置并修正后回 06" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="420" y="745" width="260" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="bad-06" value="异常" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="n06" target="e06" />
+        <mxCell id="back-06" value="处理完成，回本节点复核" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;dashed=1;strokeColor=#b85450;endArrow=block;html=1;" edge="1" parent="1" source="e06" target="n06" />
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

头程到尾程流程/头程到尾程顺序回路流程图.md

@@ -0,0 +1,52 @@
+# 头程到尾程流程节点清单
+
+填写规则：`节点｜负责人｜完成后进入｜异常处理后回到`。姓名、时限和凭证由现场补充。
+
+## 主流程
+
+| 编号 | 节点 | 负责人 | 完成后进入 | 异常处理后回到 |
+|---|---|---|---|---|
+| 01 | 客户下单 | 客户下单员：____ | 02 订单审核 | 资料补正后回 01 |
+| 02 | 订单审核 | 订单审核员：____ | 03 拉货／送仓 | 补正后回 02 |
+| 03 | 拉货／客户送仓 | 国内提货跟单：____ | 04 到仓收货 | 改约或补交接后回 03 |
+| 04 | 到仓收货 | 国内收货员：____ | 05 称重测量 | 差异确认后回 04 |
+| 05 | 称重测量 | 国内测量员：____ | 06 测量审核 | 补测补证后回 05 |
+| 06 | 测量审核 | 测量审核员：____ | 07 入库／库位 | 数据问题回 05；订单门禁回 02 后再回 06 |
+| 07 | 国内入库／库位 | 国内仓管：____ | 08 排柜 | 修正库位后回 07 |
+| 08 | 排柜／分柜 | 柜务：____ | 09 订舱／放舱 | 调整计划后回 08 |
+| 09 | 订舱／放舱 | 船务：____ | 10 国内拖柜 | 新船期或资料确认后回 09 |
+| 10 | 国内拖柜：预约、提柜到仓 | 国内运输跟单：____ | 11 国内拣货 | 改约或补资料后回 10 |
+| 11 | 国内拣货 | 国内拣货员：____ | 12 装柜完成 | 补拣或调整后回 11 |
+| 12 | 装柜完成 | 国内装柜主管：____ | 13 出口报关 | 调整或补证后回 12 |
+| 13 | 出口报关 | 报关专员：____ | 14 国内出仓 | 补正或查验后回 13 |
+| 14 | 国内出仓 | 国内出仓员：____ | 15 海运跟踪 | 解除阻断后回 14 |
+| 15 | 海运／到港跟踪 | 船务：____ | 16 目的港清关 | 核实船期后回 15 |
+| 16 | 目的港清关 | 海外清关专员：____ | 17 海外提柜 | 补件、查验或放行后回 16 |
+| 17 | 海外提柜／送仓 | 海外运输跟单：____ | 18 海外拆柜收货 | 改约后回 17 |
+| 18 | 海外拆柜收货 | 海外收货员：____ | 19 海外入库 | 短收／超收先待核平，完成后回 19 |
+| 19 | 海外入库／库位 | 海外仓管：____ | 20 海外排车 | 满足可用库存条件后回 19 |
+| 20 | 海外排车 | 海外调度：____ | 21 转派送、22 拣货 | 调整车辆或预约后回 20 |
+| 21 | 转派送／生成待出库单 | 海外调度：____ | 23 发车前复核 | 补齐资料后回 21 |
+| 22 | 按排车拣货 | 海外拣货员：____ | 23 发车前复核 | 补拣或库存调整后回 22 |
+| 23 | 拣货核平／发车前复核 | 海外仓主管：____ | 24 发车／出库 | 补齐数量、单据、车辆后回 23 |
+| 24 | 发车／确认出库 | 海外出库员：____ | 25 派送签收 | 满足发车条件后回 24 |
+| 25 | 派送／签收 | 派送运营：____ | 26 整单完结；27 回访 | 拒签／失败：退回恢复库存，后续重新安排 |
+| 26 | 整单完结 | 履约运营：____ | 流程结束 | 还有未完成片段时回对应节点 |
+| 27 | 客户回访 | 客服：____ | 流程结束 | 投诉或联系不上时由客服继续跟进 |
+
+## 特殊分支
+
+| 分支 | 负责人 | 流程 | 异常回流 |
+|---|---|---|---|
+| 一件代发国内处理 | 国内清点员／打托员：____ | 06 测量审核 → 拆箱清点 → 归托封托 → 07 入库／库位 → 08 排柜 | 差异回清点；漏清点或未封托回打托 |
+| 海外接柜准备 | 海外计划员：____ | 12 装柜完成后提前准备入仓计划、托盘、库位 | 资料或资源缺失回计划准备 |
+| 卸柜后还空 | 海外运输跟单：____ | 18 拆柜完成 → 安排还空 | 还空受阻回运输跟单处理 |
+| 一件代发海外独立出库 | 一件代发运营：____ | 按独立出库单逐箱或整托拣货 → 复核 → 出库 | 缺货或错 SKU 回海外仓核对；签收和完结规则待确认 |
+
+## 并行关系
+
+- 02 审核与 03 拉货、04 收货、05 测量可以并行；06 测量审核前必须完成 02。
+- 08 排柜、09 订舱准备可以并行；10 拖柜预约须等订舱放舱和资料齐备。
+- 12 装柜完成后即可准备海外入仓计划，不必等待海运到港。
+- 21 转派送可以早于或晚于 22 拣货，但必须早于 24 发车。
+- 26 整单完结与 27 客户回访并行，回访不阻断整单完结。