html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-09-18 16:48:32 +08:00
parent cab9b6d8ba
commit 083c567905
17 changed files with 5463 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6
View File
@@ -16,6 +16,11 @@
## 全流程公共契约 ## 全流程公共契约
- [头程下单到尾程出库全流程操作手册](头程下单到尾程出库全流程操作手册.md)：从客户头程下单、国内收货测量、分柜装柜和国内出仓，贯通跨区尾程建单、海外接柜入仓、排车、PDA 拣货与尾程出库的角色、操作、状态、编号、门禁和异常处理。
- [头程下单到尾程出库现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)：以 F01～F40 盘点现有主链、并行流程、条件分支和异常流，明确操作人、入口/出口状态、单据、编号、数据交接和评审项；应先评审本清单，再进入优化。
- [头程到尾程分阶段流程](头程到尾程分阶段流程/README.md)：F01～F40 六个阶段现状文档已全部完成，逐阶段记录操作、字段、状态、数据流、异常、完成判定和上下游交接条件，可按阶段评审并进入优化。
- [头程到尾程 AI 流程优化上下文包](头程到尾程AI流程优化上下文包.md)：统一 AI 分析所需的术语、流程变体、RACI、阶段合同、阻断分类、问题证据、指标口径、优化卡模板和完成定义。
- [头程下单到尾程出库流程易用性与数据流转优化方案](头程下单到尾程出库流程易用性与数据流转优化方案.md)：基于已走通主链梳理现状操作问题，提出统一进度、下一动作、操作回执、数据归属、跨区可观测、PDA 易用性、P0-P2 优先级和验收指标。
- [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。 - [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。
- [双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。 - [双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。
- [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。 - [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。
@@ -28,6 +33,7 @@
- [Admin 海外仓样式核对记录](Admin海外仓样式核对记录.md)：海外仓 10 个菜单、独立详情、作业弹框和共享组件显式接入边界。 - [Admin 海外仓样式核对记录](Admin海外仓样式核对记录.md)：海外仓 10 个菜单、独立详情、作业弹框和共享组件显式接入边界。
- [AI 工程执行与协作约束](AI工程执行与协作约束.md)：工作区、依赖、Git、部署、数据库、质量门禁和独立任务协作规则。 - [AI 工程执行与协作约束](AI工程执行与协作约束.md)：工作区、依赖、Git、部署、数据库、质量门禁和独立任务协作规则。
- [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。 - [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
- [数据库版本迁移与 Jenkins 自动发布方案](数据库版本迁移与Jenkins自动发布方案.md)：生产灰度后的不可变基线、Flyway 版本规则、国内/海外迁移边界、测试频繁迭代与 Jenkins 自动发布流程。
- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、健康检查与失败处理。 - [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、健康检查与失败处理。
- [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：ECS/ALB、RDS MySQL、Redis、OSS、Nacos、RocketMQ、压测、高可用、监控、备份与上线清单。 - [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：ECS/ALB、RDS MySQL、Redis、OSS、Nacos、RocketMQ、压测、高可用、监控、备份与上线清单。
- [阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)：Admin、Client、国内/海外 PDA 文件接入 OSS 的区域拓扑、存储适配、权限、一致性、实施拆分、验收门禁和方案评审。 - [阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)：Admin、Client、国内/海外 PDA 文件接入 OSS 的区域拓扑、存储适配、权限、一致性、实施拆分、验收门禁和方案评审。
国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md
+3 -3
View File
@@ -83,12 +83,12 @@
| 验收点 | 冻结契约 | 自动化证据 | | 验收点 | 冻结契约 | 自动化证据 |
|---|---|---| |---|---|---|
| 来源隔离 | `customerRemark` 来自订单客户备注；`internalRemark` 来自最新内部备注，禁止冒用 `cargoRemark` | `orders` 写入三条互异 marker；`phase3-loading` 精确比较来源与非串值 | | 订单备注关联 | `customerRemark/internalRemark/warehouseRemark/customerServiceRemark` 均以 Order 订单备注为权威；订单列表修改后三类平台备注同步全部未冻结预装明细，预装详情修改后三类平台备注写回订单并同步同票未冻结明细；`customerRemark` 只随客户申报修改同步，禁止冒用 `cargoRemark` | `orders` 写入四条互异 marker；分别从订单列表和预装详情修改后，两个入口精确比较一致性、版本递增与并发冲突 |
| 仓库备注 | `warehouseRemark` 仅在 EDITING/LOADING 通过正式 item PATCH 维护；空白归一化为 null | 覆盖保存、空白清空、版本递增、旧版本 A0409 后回查零漂移 | | 冻结边界 | EDITING/LOADING 的预装明细参与订单备注同步；COMPLETED 或 `frozen_at` 非空的装柜历史保留完成时快照，不被订单后续修改覆盖 | 覆盖保存、空白清空、版本递增、旧版本 A0409、完成后订单备注变更不改历史快照 |
| 幂等与终态 | 同 operationId 同参数精确重放不重复递增；异参冲突；COMPLETED 后 A0409 且零写 | OpenAPI/Service 静态合同已锁定；COMPLETED HTTP 负向待部署后与 finalize 串联 | | 幂等与终态 | 同 operationId 同参数精确重放不重复递增；异参冲突；COMPLETED 后 A0409 且零写 | OpenAPI/Service 静态合同已锁定；COMPLETED HTTP 负向待部署后与 finalize 串联 |
| 动态增量 | assignment/数量调整/删除不得覆盖已有仓库备注 | `phase3-loading` 在 LOADING 增量前后断言原明细仓库备注保持，调整明细备注保持 | | 动态增量 | assignment/数量调整/删除不得覆盖已有仓库备注 | `phase3-loading` 在 LOADING 增量前后断言原明细仓库备注保持，调整明细备注保持 |
| 海外事件 | `FirstLegLoadingPlanCompletedV2` 每个 item 含 customer/internal/warehouse 三备注，事件哈希与幂等基于同一稳定 payload | `loading-list-remarks-contract.test.mjs` 锁定 V2 类型与三字段映射；海外消费者仓库不在本仓，列为跨仓部署依赖 | | 海外事件 | `FirstLegLoadingPlanCompletedV2` 每个 item 含 customer/internal/warehouse 三备注，事件哈希与幂等基于同一稳定 payload | `loading-list-remarks-contract.test.mjs` 锁定 V2 类型与三字段映射；海外消费者仓库不在本仓，列为跨仓部署依赖 |
| Admin | 客户/内部备注只读，仅仓库备注显示编辑入口；COMPLETED 隐藏编辑 | Admin 静态合同已锁定 | | 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 实际完成分片版本；真实并发仍冲突，失败必须零写入。 - 结算版本缺陷证据：task `2089254643058184193`、inbound `2089181999189299202` 在 taskVersion=1/inboundVersion=6、PICKED 2/2 与五证据齐备时返回 A0409；requestId=`12a913ba-9845-45f6-91ec-bdba28e3eb9d`、traceId=`395d11b5c0da45eca948a39a08e29d3d`。回归锁定 settle 后重新读取 full/partial 实际完成分片版本；真实并发仍冲突，失败必须零写入。
## PDA 进行中增量预装冻结回归 ## PDA 进行中增量预装冻结回归
头程下单到尾程出库全流程操作手册.md
+538
View File
@@ -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
+463
View File
@@ -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
+581
View File
@@ -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
+296
View File
@@ -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
+36
View File
@@ -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
+464
View File
@@ -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
+424
View File
@@ -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
+592
View File
@@ -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
+405
View File
@@ -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
+310
View File
@@ -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
+388
View File
@@ -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/`
数据库版本迁移与Jenkins自动发布方案.md
+477
View File
@@ -0,0 +1,477 @@
# 数据库版本迁移与 Jenkins 自动发布方案
## 1. 文档状态与目标
- 状态：方案已评审，待分阶段实现。
- 适用环境：共享测试环境、国内生产环境、海外生产环境。
- 适用数据库：MySQL 8。
- 迁移工具：Flyway。
- 发布入口：Jenkins。
目标是让每次上线自动执行当前代码版本所需的数据库变更，人工只负责代码评审、发布审批和上线验收，不再登录服务器手工执行 SQL。
本方案只定义后续版本迁移机制，不重新执行现有初始化 SQL，不授权重置、清空或修复任何环境的数据。
## 2. 核心结论
1. 现有两份统一 SQL 只作为空库初始化基线，不能在已有数据库重复执行。
2. 后续数据库变化必须新增不可变的版本迁移文件，禁止修改已经在共享测试或生产执行过的文件。
3. 国内和海外使用独立目录、独立数据库连接、独立 Flyway 历史表，禁止跨区域或跨 schema 混合执行。
4. Jenkins 每次部署都执行 `info -> validate -> migrate -> validate`，不能仅依赖 Git diff 判断是否需要迁移。
5. 发布顺序为：构建并推送全部镜像 -> 执行数据库迁移 -> 部署同一批已构建镜像 -> 健康检查和人工验收。
6. 测试环境允许频繁发版，但已执行迁移同样不可修改；修正必须新增更高版本。
7. 测试重置是独立任务，生产环境永远不允许自动 `clean`、重建或回滚数据库。
## 3. 当前迁移起点
### 3.1 已执行的初始化基线
生产环境已经分别执行：
- 国内：`头程数据库统一增量-MySQL8.sql`
- 海外：`海外区域统一增量-MySQL8.sql`
当时验收结果：
- 国内初始化通过，共 208 张表。
- 海外初始化通过，共 137 张表。
生产执行文件的 SHA-256：
- 国内：`27fbb98c603f7be1681eb4672b0e8d3010944e339fb64c0dfc00fa89b99ef036`
- 海外：`df91d199b84d02509cbe1f9a3a50a44e209e8c746a94ca40da7db32858d6d3a5`
当前仓库内同名文件与生产执行版本存在漂移风险。因此在启用自动迁移前，必须先从生产部署留档或当时上传文件中找回上述精确版本，以哈希复核后冻结为基线。不能直接把当前本地同名文件认定为生产基线。
### 3.2 国内数据库边界
国内区域当前包含：
- `baiyue_auth`
- `baiyue_iam`
- `baiyue_order`
- `baiyue_warehouse`
- `baiyue_firstleg`
- `baiyue_file`
- `baiyue_audit`
- `baiyue_event_bridge`
- `baiyue_finance`
### 3.3 海外数据库边界
海外区域当前包含：
- `baiyue_lastleg`
- `baiyue_lastlag_warehouse`
- `baiyue_event_bridge_overseas`
`baiyue_lastlag_warehouse` 的现有拼写视为当前数据库事实。若后续决定改名，必须作为单独的受控迁移处理，不能在引入 Flyway 时顺带修改。
## 4. 推荐目录结构
```text
baiyue-firstleg/
└─ deploy/
└─ sql/
├─ README.md
├─ VERSION
├─ baseline/
│ ├─ cn/
│ │ └─ V0.0.0__cn_baseline.sql
│ └─ overseas/
│ └─ V0.0.0__overseas_baseline.sql
├─ migrations/
│ ├─ cn/
│ │ ├─ baiyue_auth/
│ │ ├─ baiyue_iam/
│ │ ├─ baiyue_order/
│ │ ├─ baiyue_warehouse/
│ │ ├─ baiyue_firstleg/
│ │ ├─ baiyue_file/
│ │ ├─ baiyue_audit/
│ │ ├─ baiyue_event_bridge/
│ │ └─ baiyue_finance/
│ └─ overseas/
│ ├─ baiyue_lastleg/
│ ├─ baiyue_lastlag_warehouse/
│ └─ baiyue_event_bridge_overseas/
└─ scripts/
├─ validate-migrations.*
└─ migrate-region.*
```
约束：
- 一个迁移文件只能修改一个 schema。
- 每个 schema 使用自己的 `flyway_schema_history`。
- 国内任务不能获得海外数据库连接，海外任务不能获得国内数据库连接。
- `VERSION` 只声明当前代码对应的数据库发布版本，例如 `0.0.10`，不能在 Jenkins 页面由操作人临时输入。
- 服务模块下的 `resources/db/` 可以继续作为最终结构或开发参考，但上线迁移的唯一事实来源必须是 `deploy/sql/migrations/`。
## 5. 基线规则
### 5.1 新建空库
新建空库时执行已冻结的 `V0.0.0` 基线，再执行所有高于 `0.0.0` 的版本迁移。
### 5.2 已初始化数据库
生产和现有共享测试库已经具备基线结构，接入 Flyway 时只做一次受控登记：
1. 备份数据库并确认可恢复。
2. 对照基线校验关键 schema、表和索引。
3. 复核基线文件 SHA-256。
4. 将数据库标记为基线版本 `0.0.0`。
5. 从 `V0.0.1.1` 开始执行后续迁移。
严禁为了建立历史表而重新执行完整初始化 SQL。
### 5.3 基线不可变
一旦 `V0.0.0` 用于任何共享环境：
- 禁止编辑、覆盖、重新生成或重命名。
- 若发现基线缺陷，新增正常版本迁移修正。
- 基线文件与其 SHA-256 必须永久留档。
## 6. 版本号和文件命名
业务发布版本使用三段数字：
```text
0.0.1 -> 0.0.2 -> 0.0.10 -> 0.1.0 -> 1.0.0
```
同一业务版本允许多条迁移，通过第四段递增：
```text
V0.0.1.1__create_login_audit_table.sql
V0.0.1.2__add_user_last_login_at.sql
V0.0.2.1__add_order_declared_value.sql
V0.0.10.1__create_export_task_index.sql
```
规则：
- Flyway 按数字段比较，`0.0.10` 正确大于 `0.0.2`。
- 同一仓库内版本必须唯一且严格递增。
- 文件名只使用 ASCII 小写字母、数字和下划线。
- 描述应说明业务动作，不能使用 `fix.sql`、`new.sql`、`final.sql` 等模糊名称。
- `deploy/sql/VERSION` 必须等于本次发布版本。
- 一个版本可以没有数据库变更；此时仍执行 `validate`，不会重复执行旧迁移。
示例：
```text
deploy/sql/VERSION
0.0.10
```
版本号是数据库迁移顺序，不应使用时间戳、Git 提交号或 Jenkins 构建号替代。镜像仍应使用不可变 Git commit 标签，以便代码和数据库发布记录相互追踪。
## 7. 迁移类型
### 7.1 版本迁移
业务表结构和受控数据变更统一使用 `V...__...sql`：
- 每个版本只执行一次。
- 执行后保存校验和。
- 执行过的文件不得修改。
### 7.2 可重复迁移
第一阶段不建议使用 `R__...sql`。视图、存储过程等确有需要时再单独引入，因为内容变化会触发再次执行，评审和回滚要求更高。
### 7.3 禁止内容
自动迁移文件中禁止：
- `DROP DATABASE`、`CREATE DATABASE`、切换到其他区域 schema。
- 无保护的 `DROP TABLE`、`TRUNCATE` 或全表删除。
- 密码、Token、云账号密钥和真实客户数据。
- 测试造数、开发演示数据或测试环境专用数据。
- MySQL 客户端的 `--force` 或忽略错误逻辑。
- 在单个文件中同时修改多个 schema。
- 依赖当前时间或不稳定查询结果生成不可重复状态。
## 8. 生产兼容策略：Expand / Contract
数据库迁移通常不能像应用镜像一样直接回滚。生产发布必须采用向前兼容方式。
### 8.1 Expand：先扩展
允许自动执行的典型变化：
- 新增表。
- 新增允许为空或带安全默认值的字段。
- 新增索引，但需要提前评估锁表时间和磁盘空间。
- 新增不破坏旧代码的枚举值或配置数据。
应用发布前，新旧应用版本都必须能够在扩展后的结构上运行。
### 8.2 Migrate：迁移或回填
大量历史数据回填不应塞进普通启动迁移：
- 小规模、可快速完成且可验证的数据修正可以使用版本迁移。
- 大规模回填必须使用独立、可观测、可限速、可续跑的任务。
- 回填完成前不能删除旧字段或旧索引。
### 8.3 Contract：最后收缩
删除字段、改字段类型、收紧非空、重建大索引等破坏性操作，必须在旧代码完全下线并经过观察期后，于后续版本单独执行。
因此应用回滚通常只回滚镜像，不自动回滚已经成功执行的扩展型数据库迁移。
## 9. Jenkins 自动发布流程
### 9.1 总体顺序
```text
合并到 main
-> 静态检查与测试
-> 构建全部目标服务镜像
-> 推送不可变 commit 标签
-> 数据库迁移预检
-> 国内/海外迁移
-> 数据库迁移复验
-> 部署同一批预构建镜像
-> 健康检查
-> 人工业务验收
```
数据库迁移失败时，应用部署必须停止。不能出现部分服务已经上线、随后才发现数据库迁移失败的情况。
### 9.2 构建与部署解耦
当前总控和单服务 Job 需要支持等价于以下两种模式：
- `BUILD_ONLY`：构建并推送镜像，不部署。
- `DEPLOY_ONLY`：只部署指定的不可变镜像标签，不重新构建。
总控流程：
1. 计算并固定本次 Git commit 镜像标签。
2. 调用所有目标服务执行 `BUILD_ONLY`。
3. 确认所有镜像均已推送成功。
4. 执行数据库迁移。
5. 数据库迁移成功后，对同一批镜像执行 `DEPLOY_ONLY`。
这样可以避免迁移成功后才开始构建、或部分服务使用不同提交版本。
### 9.3 每次部署都要运行的迁移步骤
不能只在 Git diff 命中 `deploy/sql/` 时执行。每次实际部署都运行：
```text
flyway info
flyway validate
flyway migrate
flyway validate
```
原因：
- 重试发布时 Git diff 可能为空，但数据库可能尚未迁移。
- 手工重跑旧构建时仍需确认数据库历史一致。
- `migrate` 对已执行版本是幂等的，会跳过而不会重复执行。
Git diff 可以用于显示“本次包含数据库文件变化”和加强审批，但不能作为是否运行迁移的唯一条件。
### 9.4 国内与海外任务
建议拆分为两个明确的 Jenkins stage 或两个下游 Job：
- `db-migrate-cn`
- `db-migrate-overseas`
每个任务只加载本区域：
- 数据库地址。
- 迁移专用账号密码。
- schema 清单。
- 对应迁移目录。
若一次发布同时影响国内和海外，两个区域迁移必须全部成功后才能部署任何依赖这些变更的应用。第一阶段建议串行执行，日志更清楚，失败处理也更简单。
### 9.5 Flyway 运行环境
- 使用固定版本的 Flyway Docker 镜像，禁止 `latest`。
- 镜像先同步到当前已验证可访问的内部镜像仓库。
- Jenkins 仅挂载只读 SQL 目录。
- 数据库密码从 Jenkins Credentials 注入，不进入 Git、构建参数默认值或控制台明文日志。
- 连接必须启用适合生产的 TLS 设置，并明确字符集与时区。
## 10. 测试环境频繁执行策略
### 10.1 共享测试库
共享测试库遵循与生产相同的不可变迁移规则：
- 一个版本只执行一次。
- 修改已执行文件会导致 `validate` 失败。
- 发现错误后新增更高版本修正，例如从 `V0.0.10.2` 修正到 `V0.0.10.3`。
这正是测试环境应提前发现的问题，不能通过修改历史文件掩盖。
### 10.2 开发者临时库
仅个人本地或一次性临时数据库可以删除后从基线重建。它不代表共享测试环境策略。
### 10.3 测试重置任务
如确需频繁重置，建立独立 Jenkins Job，例如 `db-reset-test`，并满足：
- 环境写死为 `test`，不能由参数切换成 `prod`。
- 主机、实例和 schema 使用精确白名单。
- 数据库名必须匹配测试前缀和预期清单。
- 使用测试专用凭据，凭据本身没有生产权限。
- 执行前显示目标并进行明确确认。
- 重置后执行基线、全部迁移和独立测试造数。
生产 Job 中不提供 `clean`、`reset`、`repair` 按钮或参数。
## 11. 提交前静态门禁
当 `deploy/sql/` 变化时，流水线至少检查：
1. 文件路径属于已登记的区域和 schema。
2. 文件名符合 `V数字.数字.数字.序号__描述.sql`。
3. 新版本大于仓库已有版本，且不存在重复版本。
4. 已发布版本文件没有被修改、删除或重命名。
5. `deploy/sql/VERSION` 不小于最大迁移版本，且与发布元数据一致。
6. 文件只影响所属 schema，不出现跨库限定名。
7. 不包含禁止语句、密钥或真实客户数据。
8. SQL 以 UTF-8 保存，结构和注释符合仓库数据库规范。
9. 国内和海外目录没有相互引用。
静态扫描只是门禁，不代替在临时 MySQL 8 数据库执行完整迁移测试。
## 12. 数据库账号与权限
应用账号与迁移账号必须分离。
### 12.1 应用账号
只授予运行期所需的 DML 权限，不应具备建表、删表、修改结构等 DDL 权限。
### 12.2 迁移账号
只由 Jenkins 使用，按区域和 schema 授予完成受控迁移所需的最小权限。国内、海外建议使用不同凭据。
### 12.3 管理员账号
RDS 高权限管理员账号不应长期配置在 Jenkins 中。紧急人工恢复时使用受审计的临时授权流程。
## 13. 失败、恢复与重跑
### 13.1 迁移前失败
镜像已经构建但迁移尚未开始时，直接停止发布。未部署的镜像保留以便排查或重试。
### 13.2 迁移执行失败
1. 立即停止后续应用部署。
2. 保存 Flyway 输出、数据库错误、版本、区域、schema 和 Git commit。
3. 确认 MySQL 是否已经提交了部分 DDL；不能假定整个 SQL 文件自动回滚。
4. 人工判断数据库真实状态。
5. 通过新的更高版本迁移向前修复。
禁止自动执行 `flyway repair`。只有确认数据库状态与预期完全一致后，才允许由数据库负责人进行受审计的人工修复。
### 13.3 迁移成功、应用失败
- 若迁移属于 Expand 类型，回滚应用镜像，数据库结构保留。
- 修复应用后使用同一数据库版本重新部署。
- 若迁移不是向后兼容的，则说明变更未满足本方案门禁，不应进入生产自动发布。
### 13.4 数据库回滚
自动流水线不执行逆向 SQL。严重事故依赖：
- RDS 备份和时间点恢复能力。
- 发布前备份或快照策略。
- 新增向前修复迁移。
- 经人工审批的恢复方案。
## 14. 日志与验收证据
每次迁移至少记录：
- Jenkins 构建号。
- Git commit 和镜像标签。
- `deploy/sql/VERSION`。
- 环境与区域。
- schema 名称。
- Flyway 镜像版本。
- 迁移前、迁移后版本。
- 本次实际执行的迁移文件列表及校验和。
- `validate` 结果和最终退出码。
日志中必须遮蔽数据库密码、Token 和连接串敏感参数。
应用部署完成后，人工只需要验收：
- Jenkins 数据库阶段全部通过。
- Flyway 历史表与目标版本一致。
- 服务健康检查通过。
- 国内、海外关键业务路径可用。
## 15. 分阶段实施清单
### 阶段 A：冻结事实
- 找回生产实际执行的两份初始化 SQL。
- 校验上述生产 SHA-256。
- 归档为不可变 `V0.0.0` 基线。
- 对生产和测试数据库做一次结构核对。
### 阶段 B：建立迁移目录与校验脚本
- 新增 `VERSION`。
- 建立国内、海外、schema 级目录。
- 增加文件名、版本、路径、禁止语句和历史不可变检查。
- 在临时 MySQL 8 中验证从空库到最新版的完整迁移。
### 阶段 C：接入共享测试
- 为各 schema 建立 Flyway 历史表并登记 `0.0.0`。
- Jenkins 测试发布接入 `info/validate/migrate/validate`。
- 验证重复发布不重复执行迁移。
- 验证失败阻止应用部署。
### 阶段 D：改造生产流水线
- 单服务 Job 支持构建与部署解耦。
- 总控先构建全部镜像，再执行迁移，最后部署。
- 配置国内、海外迁移专用凭据。
- 保留现有生产确认门禁；是否取消发布确认应另行决定，不和数据库迁移改造绑定。
### 阶段 E：生产启用
- 先选一个只包含安全新增的版本演练。
- 核对 RDS 备份和恢复能力。
- 国内、海外按发布范围执行迁移。
- 完成健康检查与人工业务验收。
## 16. 首次落地的验收标准
首次启用自动迁移必须同时满足：
- 生产基线文件哈希已确认，没有使用漂移的本地副本。
- 国内和海外历史表相互独立。
- 任一迁移失败都会阻断所有依赖服务的部署。
- 重跑同一 Jenkins 构建不会重复执行成功迁移。
- 篡改已执行文件会被 `validate` 阻止。
- 测试重置任务无法连接生产数据库。
- Jenkins 日志不泄露凭据。
- 部署使用构建阶段确定的同一批不可变镜像。
## 17. 官方参考
- [Flyway Versioned migrations](https://documentation.red-gate.com/fd/versioned-migrations-273973333.html)
- [Flyway Repeatable migrations](https://documentation.red-gate.com/fd/repeatable-migrations-273973335.html)
- [Flyway Schema history table](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html)
- [Flyway Validate](https://documentation.red-gate.com/flyway/reference/commands/validate)
订单与客户/README.md
+2
View File
@@ -10,6 +10,8 @@
## 文档 ## 文档
- [客户端简化与易用性优化建议](客户端简化与易用性优化建议.md)：基于当前客户端实现的产品讨论稿，包含导航、首页、核心流程、实施优先级及易用性验收建议。
- [客户端首页简化样板](客户端首页简化样板.md)：首页样板的原型差异、操作承载、数据边界及人工查看要点。
- [订单与客户开发进度表](订单与客户开发进度表.md) - [订单与客户开发进度表](订单与客户开发进度表.md)
- [订单与客户头程订单闭环设计](订单与客户头程订单闭环设计.md) - [订单与客户头程订单闭环设计](订单与客户头程订单闭环设计.md)
- `虫虫出海订单与客户开发进度表.xlsx`：面向团队日常维护的 Excel 进度表。 - `虫虫出海订单与客户开发进度表.xlsx`：面向团队日常维护的 Excel 进度表。
订单与客户/客户端简化与易用性优化建议.md
+372
View File
@@ -0,0 +1,372 @@
# 企业客户端简化与易用性优化建议
日期：2026-09-18
适用范围：企业客户工作台 `apps/client-web/`
文档状态：方案 A 第一版已实现并通过本地检查；菜单最终位置及 `1920×1080`、浏览器缩放 `100%` 的视觉效果待人工截图评审确认。
## 0. 2026-09-18 最新原型评估结论
本轮核对的最新文件来自微信缓存目录，修改时间为 `2026-09-18 11:37:20`，SHA-256 为 `9FA64EB74381DFB11506799E1EF33593EE11C0300F362AF875902984CE5D2E20`。仓库中的 `docs/悦/官网头程下单/workbench.html` 仍是 2026-09-08 的另一版本，二者不能混用为同一份验收依据；若后续确认最新版为正式原型，应先将正式副本归档到仓库再进入逐页还原。
最新原型的首页方向可以采用，但应采用其**信息架构与视觉减负原则**，不应原样复制技术实现或直接按原型侧栏删除菜单：
- 首页收敛为业务入口、订单筛选、待办分类和订单列表，符合当前“登录后直接办事”的方向。
- 原型仍保留彩色业务图标、渐变、阴影和悬浮效果，不是完全无色的极简风；正式实现宜进一步减轻阴影和装饰，同时保留业务辨识色、状态色和待办红点。
- 原型使用 Tailwind CDN 和 Font Awesome，正式项目继续使用 Vue、Element Plus 与 Lucide，只迁移视觉规则，不新增第二套组件和图标体系。
- 原型在 `1200px` 以下把 6 张业务卡片切成 `3 × 2`，会重新占满首屏；正式项目继续按内容区宽度响应，桌面窄屏保持单行横向浏览。订单区始终使用高密度表格，不再按内容宽度切换为订单卡片；列宽不足时由表格内部横向滚动承载。
- 原型侧栏只有 6 个业务叶子，而当前代码在拥有全部相关权限时有 22 个正式菜单叶子。直接照抄会让 16 个已实现入口失去稳定主入口，因此首页视觉改造与菜单信息架构必须分开评审。
- 本轮只形成产品与信息架构文档，不修改共享导航、路由、权限资源或页面实现。
## 1. 建议先做什么
建议围绕客户的四个问题重新组织体验：**我要发货、我的货到哪了、有什么需要我处理、我要付多少钱。**
第一轮以“首页 → 头程订单 → 下单 → 计费与费用确认”为样板，同时修正充值、退货等容易误解的文案。先减少找入口、找字段和判断下一步的成本，再推广到海外仓、财务和企业设置。
本方案的重点是：
| 方向 | 具体变化 | 客户获得的帮助 |
| --- | --- | --- |
| 入口更集中 | 主导航收敛为首页、我的订单、海外仓、费用与账单、企业设置；个人和消息放入固定工具区 | 知道一件事应该去哪里做 |
| 首页能办事 | 首屏突出待处理事项、常用操作和最近订单 | 登录后知道先做什么 |
| 列表更好读 | 默认只显示关键列，筛选分常用与展开项 | 快速找到订单、状态和下一步 |
| 表单分层 | 按场景显示必填项，系统已有信息自动带入，补充字段分组 | 少填重复内容，少在长表格里找错误 |
| 操作结果更明确 | 区分草稿与已提交、费用确认与付款、充值申请与到账、签收与换标完成 | 不因名称简短而误判业务结果 |
| 失败可以继续 | 保留输入、定位错误、恢复查询条件，重要操作仍明确确认 | 出错后能继续，不必重新开始 |
**证据范围：**本文基于当前源码、路由清单、应用指引及指定原型的静态审查。没有用户行为统计、访谈或真实页面操作记录，因此下文“现状”指代码事实，“问题”是待验证的体验判断，“建议”是拟议目标。视觉与实际操作效果均为**待人工截图确认**，不以本文件宣布页面改造完成。
## 2. 当前主要负担在哪里
| 已核实的实现现状 | 对客户可能造成的负担 | 优化判断 |
| --- | --- | --- |
| 在拥有全部相关权限时，导航定义包含 9 个顶层节点、22 个正式菜单叶子；实际显示受成员权限过滤 | 业务创建、履约查询、企业设置分散，需要记住系统分类 | 调整信息架构，完整保留已有业务入口与权限 |
| 首页已调整为 6 个权限化业务创建入口，并嵌入头程筛选、待办 Tab 和真实订单列表 | 高频创建与查单已经集中，但历史列表仍分散在多个业务菜单 | 保留当前首页样板，菜单负责稳定的历史查询与业务管理入口 |
| 6 个首页业务入口均跳转独立创建页；首页订单列表不再重复显示“创建订单” | 入口职责已经更清楚，但快速建草稿、批量导入等次级创建方式的位置尚未统一 | 后续在首页卡片次级动作与订单中心页内操作之间二选一 |
| 头程列表默认打开过多可选列，客户侧同时暴露订单号与入仓码 | 找货、看进度时需要理解多套编号，且大量次要信息挤占首屏 | 客户侧统一以入仓码为主业务编号，重做默认列与常用筛选，继续复用已有列设置能力 |
| 创建页货物明细集中展示 30 余个字段；明细区还有创建多张订单草稿的 Excel 导入入口 | 填一张订单和批量建多张订单容易混淆 | 单单货物录入与批量建单明确分开 |
| 快速下单每行生成独立草稿，成功后回普通订单列表 | 容易误以为已提交，还要重新寻找刚生成的草稿 | 成功结果明确草稿状态，并引导继续完善 |
| “确认计费重”实际涉及计费依据、费用金额及确认后锁定 | 按钮没有完整表达操作后果 | 改为“核对计费与费用”，保留正式确认门槛 |
| “退货换标”路由实际承载退货预报、签收；退货库存和箱号管理共用组件但粒度不同 | 退货签收完成可能被理解为换标或出库完成；库存入口难区分 | 用准确阶段名称，统一库存入口并保留不同查看粒度 |
| 充值提交后进入人工审核，按钮叫“确认充值”；账单使用“已收、未收”等平台视角 | 可能把提交申请当作到账，或把确认账单当作付款 | 以客户视角说明动作、结果和剩余步骤 |
| 企业管理分成员、角色、菜单权限；权限配置展示权限码、“全量替换”等技术表达 | 企业管理员需要先理解内部权限结构 | 将配置流程串联，默认展示业务能力与修改影响 |
其中，跨业务“我的订单”页面当前标记为 `prototype`，没有作为正式路由开放。不能把它当成已经可用的订单聚合中心。
## 3. 导航与首页怎么简化
### 3.1 建议的入口归属
建议将顶层导航收敛为以下五项。这里的“我的订单”首先是导航分组，首轮可以直接承接现有分类列表；建设跨业务统一列表另行评估。
| 建议一级入口 | 收纳的当前入口 | 入口内的组织方式 |
| --- | --- | --- |
| 首页 | 业务总览 | 待处理事项、常用操作、最近订单、少量关键指标 |
| 我的订单 | 头程订单列表、快速下单、海外采购、美国本土卡、美本土散板、派送订单列表 | 按业务类型进入现有列表；创建操作集中在清晰的创建入口 |
| 海外仓 | 入库订单列表、贴标申请、仓储转运、货物废弃、退货换标、退货库存、退货箱号管理 | 入库记录、仓内服务、退货管理；退货库存保留按 SKU 和按箱查看 |
| 费用与账单 | 资金账户、客户账单 | 先看可用资金和待处理账单，再看流水、充值申请和记录 |
| 企业设置 | 企业资料、企业成员、角色管理、菜单权限 | 企业资料、成员与权限；角色和权限配置在同一流程内衔接 |
固定工具区提供“消息”和“个人资料与账号安全”；退出登录放在个人菜单中。消息继续复用已存在的顶部入口，无须在两个位置保持同等视觉权重。
导航设计遵循以下约束：
- 一个业务能力保留一个清楚的主归属；首页快捷操作只是通往它的入口。
- 按当前成员的真实权限展示；财务、企业管理和创建操作不能因菜单合并而扩大权限。拥有查询权限不等于拥有创建、提交或确认权限。
- “贴标申请”是否改名为“贴标与换标”，以及“美国本土卡／美本土散板”的完整客户名称，需要业务人员确认含义后统一菜单、页面标题与帮助文案。
- “退货换标”当前入口建议改为“退货预报与签收”；退货签收、换标、出库分别呈现各自状态。
- 合并退货库存入口时保留 SKU 明细、箱内明细和箱级汇总的差异，不把不同粒度的数据直接合计。
- 同一批调整同步修改面包屑、页签、快捷入口和相关测试；新原型确认后收敛为一套导航，不并行保留两套新旧模式。
### 3.2 当前菜单盘点：为什么看起来少了很多
当前正式导航由模块路由自动汇总，并按当前成员权限过滤。拥有全部相关权限时，共有 **9 个顶层节点、22 个正式菜单叶子**：
| 当前顶层节点 | 正式菜单叶子 | 数量 | 最新极简原型是否保留 |
| --- | --- | ---: | --- |
| 业务总览 | 业务总览 | 1 | 保留 |
| 头程物流 | 订单列表、快速下单 | 2 | 未放入侧栏，仅首页保留头程快捷入口 |
| 出海下单 | 海外采购、美国本土卡、美本土散板 | 3 | 未放入侧栏，仅首页保留快捷入口 |
| 海外仓 | 贴标申请、仓储转运、货物废弃、退货换标、退货库存、退货箱号管理 | 6 | 全部未放入侧栏，只有首页两个快捷入口覆盖部分能力 |
| 订单管理 | 入库订单列表、派送订单列表 | 2 | 保留 |
| 财务结算 | 资金账户、客户账单 | 2 | 只保留账单类入口，资金账户改由顶部充值和个人区域间接进入 |
| 企业管理 | 企业资料、企业成员、角色管理、菜单权限 | 4 | 只保留公司信息，成员和权限管理未体现 |
| 我的信息 | 我的信息 | 1 | 保留 |
| 消息中心 | 我的消息 | 1 | 未放入侧栏，适合移到顶部固定工具区 |
最新版极简原型侧栏实际只有：业务总览、入库订单列表、派送订单列表、应付账单、公司信息、我的信息，共 **6 个业务叶子**，另有退出登录。它适合作为“极简壳层”的视觉参考，但不能作为当前完整菜单清单。
菜单“缺失”需要分为四种情况，不能用一次补菜单操作混在一起处理：
1. **权限过滤。**当前成员没有叶子权限时，该菜单及空父分组会隐藏。这是预期行为，应先核对账号权限，不应通过前端强制显示。
2. **已有正式页面但原型未画。**头程、出海下单、海外仓服务、资金账户、企业成员与权限、消息都属于此类，必须在新信息架构中找到稳定归属。
3. **隐藏流程页。**新增、编辑、详情页面有正式路由，但不应独立占用侧栏；从首页快捷入口、列表操作或详情下钻进入。
4. **尚未正式开放。**跨业务“我的订单”仍标记为 `prototype`，不能因为菜单需要聚合入口就提前开放；统一订单查询需要单独确认数据与接口契约。
此外，现有“快速下单”实际生成订单草稿，“批量导入订单”位于头程订单列表工具栏。它们是创建方式，不宜为了补齐数量继续平铺为多个同级业务栏目。
### 3.3 菜单是否随极简风优化
建议同步优化，但不和首页视觉改造一次性强绑定。原因如下：
- 只改首页、不改菜单，页面会更轻，但侧栏仍按系统模块分类，客户仍需记住“头程物流、出海下单、订单管理”的内部边界。
- 直接照极简原型删侧栏，已实现业务会失去可发现性；只有创建权限、没有部分列表权限的成员还可能无法从首页之外找到入口。
- 导航叶子同时参与权限过滤、首个可访问页面、面包屑、父分组展开和工作区页签。菜单调整不是单纯 CSS 工作，必须联查路由与权限测试。
- 首页快捷卡片是高频创建入口，不应成为某项业务唯一入口；用户仍需要稳定的列表入口查看历史订单、错误状态和后续进度。
因此建议把首页和菜单拆成两个决策：
1. **首页视觉可以先确认。**采用轻量极简、真实筛选、待办 Tab、订单列表和 6 个权限化创建入口。
2. **菜单先完成归属表，再决定放置形态。**在最终位置确认前保留现有正式入口，不删除、不复制第二套导航。
### 3.4 后续评审的两套菜单放置方案
#### 方案 A：五个主入口的任务型侧栏（推荐）
**2026-09-18 实现记录：**客户端已按本方案形成第一版。侧栏使用“首页、订单中心、海外仓、费用与账单、企业设置”五个任务入口；“快速下单”在菜单中按真实结果显示为“快速建草稿”；消息和个人信息移动到顶部固定工具区。现有路由和权限编码未删除或合并，侧栏按当前成员权限继续过滤。根据 2026-09-18 人工截图反馈，壳层进一步向当前原型收敛：侧栏使用浅蓝底、深蓝品牌区和蓝色渐变激活态，顶栏取消重复的页面标题和说明并改为简洁问候。首页不生成或显示工作页签，正文直接从紧凑顶栏下方开始；其他页面继续保留多任务工作页签。新建、编辑和详情类页签支持独立的短标题，例如“退货换标 · 新建”，避免与正文大标题完全重复；海外仓服务页删除页面内部第二套面包屑，只保留应用壳层路径。桌面侧栏保持 `224px`，为首页订单区释放宽度。订单区保留“全部、确认计费重、上传资料”筛选，取消双列卡片模式，统一恢复为带分页和列设置的表格列表；默认仅显示入仓码、状态、渠道、运输方式、交货方式、收货仓和创建时间等核心列，其余字段由“显示字段筛选”打开。头程详情已从大弹框改为受权限保护的独立工作页签，点击列表详情或入仓码直接进入；详情内容改用紧凑的分区标题、字段表格和明细表格，取消收发货方、柜次和货物摘要的卡片式堆叠。订单主进度与柜次进度合并为客户唯一的“履约进度”，柜次仅作为该进度下的明细；柜次、快递和入库费用尚无数据时使用紧凑提示行，不再展示占据大面积首屏的空态。海外采购、美国本土卡和美本土散板的共用订单页也已改为共享查询栏、数据表和四列紧凑详情网格，统一操作列、状态标签、分页、容器边距和业务编号入口。该记录表示实现状态，不替代最终人工视觉验收。
| 建议位置 | 收纳入口 | 说明 |
| --- | --- | --- |
| 首页 | 业务总览 | 6 个创建入口、待处理筛选、最近订单；不重复承载所有历史列表 |
| 订单中心 | 头程订单、海外采购、美国本土卡、美本土散板、入库订单、派送订单 | 按订单类型进入现有正式列表；跨业务统一列表在接口契约确认前不开放 |
| 海外仓 | 贴标申请、仓储转运、货物废弃、退货预报与签收、退货库存 | 按“服务申请、退货、库存”二级分组；退货箱号作为库存页内查看方式或保留子入口，不能直接删除 |
| 费用与账单 | 资金账户、客户账单 | 充值作为资金账户内操作；顶部可保留余额或充值快捷入口 |
| 企业设置 | 企业资料、企业成员、角色管理、菜单权限 | 普通成员只显示有权限的页面；企业管理员保留完整管理入口 |
顶部或侧栏底部固定工具区放置：我的消息、个人资料与账号安全、退出登录。这样既保持极简主导航，又不牺牲已实现能力。
“快速下单／快速建草稿”和“Excel 批量建草稿”有两个候选位置，需后续确认：
- 作为首页“头程下单”卡片的次级创建方式；优点是创建入口集中。
- 作为订单中心中“头程订单”的页内操作；优点是避免首页卡片出现多个按钮。
#### 方案 B：保留当前业务域侧栏，仅做视觉减负
保持头程物流、出海下单、海外仓、订单管理、财务结算、企业管理等现有分组，只统一图标、行高、展开方式和工具区。该方案改动风险较低、权限映射最直接，但顶层入口仍多，不能完全解决客户需要记忆系统分类的问题。
不建议当前直接采用“无侧栏、全部放顶部菜单或九宫格”的方案。22 个权限化入口在顶部会形成拥挤的多级菜单，在窄屏上也更难访问；如果未来采用应用启动器，仍需保留订单和设置的稳定导航路径。
### 3.5 菜单位置确认前的临时原则
- 保留当前正式导航，不按最新版原型删减 16 个已实现入口。
- 首页 6 个卡片只负责创建；订单历史和业务进度仍从对应列表进入。
- 创建、编辑、详情继续作为隐藏流程页，不新增侧栏叶子。
- 消息和个人资料可以先作为顶部固定工具候选，但在位置确认前不删除现有入口。
- 所有菜单继续按真实权限过滤；菜单合并只改变归属和展示，不合并权限编码、不扩大访问范围。
- 最终选定方案后，一次性同步路由导航、面包屑、父分组展开、工作区页签、权限配置文案和自动化测试。
### 3.6 首页优先展示“现在要处理什么”
首页建议按以下顺序安排内容：
1. **阻断事项。**企业资料待完善或被驳回、资金限制等，显示原因和下一步。待审核与审核驳回分别说明，不把所有情况统一写成“请完善资料”。
2. **待我处理。**候选事项包括待完善草稿、待确认计费与费用、待提交报关资料、待确认账单、待确认换标结果。每条包含业务编号、待办原因、更新时间和明确动作。
3. **常用操作。**头程发货、批量建草稿、海外仓服务、查看账单等，按权限显示。首轮使用固定、经确认的排序，不增加个性化推荐系统。
4. **最近业务。**显示少量最近订单及进度，帮助客户接着上次操作；可进入对应分类列表。
5. **帮助与概览。**提供真实可用的操作说明及联系方式，统计明确业务和时间范围。
首页待办属于需要核对数据契约的能力，不能直接把“未读消息数”当成待办数。已读消息不等于业务已处理，旧通知也不能覆盖最新业务状态。
实施前逐项核对是否已有客户范围内的查询和状态字段。缺少聚合能力时，首轮只提供有依据的快捷入口，不伪造数字；不得遍历全部订单后拼凑跨业务总数。每个数据区独立表达加载、无数据、失败和无权限，失败显示“暂无法获取”而非零。
## 4. 高频流程怎么改
### 4.1 头程下单：先选创建方式，再完成当前任务
统一入口中清楚区分三种方式：
| 方式 | 适用场景 | 操作结果必须写清楚 |
| --- | --- | --- |
| 填写订单 | 本次准备好一票货物资料 | 可保存草稿；满足审核、权限和字段要求后另行提交 |
| 快速建草稿 | 先按渠道、目的仓和 SKU 建立多张草稿 | 每行形成一张草稿，尚未提交 |
| Excel 批量建草稿 | 已在表格中整理多票资料 | 最多按现有 50 行上限导入，结果为草稿，尚未提交 |
单张订单建议重新设计为三个信息阶段：**运输与目的地 → 货物信息 → 核对并提交**。这是新交互建议，先用原型验证是否减少填写负担；不强制将所有简单业务表单改成多步流程。
字段按用途分层：
| 字段类型 | 展示原则 | 示例与边界 |
| --- | --- | --- |
| 当前任务必填 | 默认展开，标明单位与填写示例 | 运输渠道、目的地、当前场景所需货物信息 |
| 场景触发必填 | 选定场景后出现；提交前完整校验 | FBA 相关标识、木制品关联资料、报关资料；不能隐藏后跳过校验 |
| 已有可信信息 | 从当前企业或选定业务带入并允许核对 | 企业名称、已保存联系信息、仓库选项；前端不能自行决定企业归属 |
| 可计算信息 | 按已确认公式展示结果和单位 | 箱数与件数的合计；费用仍以服务端正式结果为准 |
| 补充信息 | 按业务分组展开，提示尚缺项 | 备注、产品补充信息；是否选填以真实契约为准 |
长货物表格默认突出本场景关键字段，详细申报或产品属性按组编辑；若使用弹框、展开行等承载方式，必须逐项纳入新原型确认。错误同时出现在字段附近和顶部摘要，点击摘要能定位字段及货物行，保留已填写内容。
危险品、木制品、报关方式等声明必须由客户明确选择，不能为减少点击替客户作出业务承诺。运费含税方式与报关方式分别解释，不合并成一个模糊开关。
快速建草稿或批量导入后，结果页显示本次成功记录、失败行、待完善内容和“继续完善”；不要只弹成功提示后丢回无筛选的全部订单。
批量导入采用“下载模板 → 上传并校验 → 查看结果”的说明结构。“部分成功／原子导入”改为“只导入正确的行／全部正确后再导入”。结果明确 Excel 行号、失败原因和修正方法；仅重试失败行的具体方式需核对幂等契约，避免再次导入已成功行。
### 4.2 查订单：默认看得懂，需要时查得全
建议头程列表默认展示约 8–10 个关键业务列，最终由真实长编号和人工截图确定宽度。可优先考虑：**操作、入仓码、状态、目的地、货物摘要、创建或更新时间**。客户从提交后开始统一使用入仓码查询、查看详情和导出；草稿尚未生成入仓码时明确显示“提交后生成”，不向客户暴露平台订单号或内部 ID。只有确有数据来源时才增加“待处理事项”，不由前端猜测。
- 操作列放在第一列，需要固定时固定左侧；勾选控件放在其后，不照搬当前选择列在前的顺序。
- 常用筛选保留业务编号、状态、时间；目的仓、渠道等进入展开筛选，并提示已启用的筛选条件。
- 继续复用现有列显隐和排序能力，提供“恢复默认列”；完整业务信息在详情和可选列中保留。
- 查看详情返回后保留筛选、页码和滚动位置。现有页签与缓存能力应先复用，不能为了简洁丢失编辑内容。
- 列表只突出当前可执行的关键操作，其他动作是否折叠由新原型逐页确认；批量操作仅保留已有契约支持的能力。
- 状态展示同时回答“当前到哪一步、下一步由谁处理”。客户主状态用于概览，测量、报关、运输等子流程在详情中单独解释。
不将所有业务强行映射成一套扁平状态；派送完成、退货签收完成和换标完成不是同一事实。订单详情建议采用“业务编号与当前状态 → 待处理事项 → 履约进度 → 货物/费用/资料”的信息顺序，具体独立页或弹框沿逐操作原型确定。
### 4.3 费用、账单和充值：客户知道自己确认了什么
| 场景 | 建议文案和展示 | 必须保留的业务边界 |
| --- | --- | --- |
| 入库计费 | 列表“核对计费与费用”；首屏展示业务编号、计费依据、单价、附加费、合计；正式按钮“确认计费与费用” | 只确认服务端当前已推送版本；保留二次确认、版本与幂等校验、确认后锁定 |
| 客户账单 | 提供“待我确认”等入口；经财务核对后用“已入账付款／待支付”等客户视角词语 | 账单确认与付款分开；付款认定以平台核实入账结果为准，不能把客户上传凭证等同到账 |
| 资金账户 | 主区突出可用资金和限制下单的原因；授信、冻结及流水保留清晰展开入口 | 总可用金额不能遮蔽实际余额为负、授信有效期等限制；以服务端判断为准 |
| 充值申请 | “填写金额 → 使用已启用渠道付款 → 上传凭证 → 提交充值申请”；结果“已提交，待审核，尚未到账” | 无有效收款码不能提交；不模拟支付成功，不把申请金额计入实际余额 |
账单快捷分类及精确数量需核对接口查询能力，不能只筛当前分页数据却称为“全部待确认”。资金账户初始加载、真实零余额和加载失败保持区分。
### 4.4 海外仓与退货：按客户目的组织，保留阶段差异
海外仓入口先让客户区分“查看入库记录、申请仓内服务、处理退货”。进入具体服务后再选择仓库、业务来源和货物；不把仓库内部托盘、库位或内部库存 ID 暴露成客户必须理解的概念。
贴标与换标申请建议按“选择仓库和库存 → 选择服务内容 → 整理本次明细 → 核对费用与提交”分区：
- 三套现有模板“SKU 关联、箱号关联、SKU 混箱换标”始终可用，增加适用说明和推荐提示，不随换标类型隐藏。
- 区分“上传待导入关系”和“加入本次申请明细”，分别显示数量；只有加入本次明细的库存才随申请提交和冻结。
- 涉及箱唛换标时，整单一个 FBA 目的仓；一行代表一箱，箱数固定为 1；不得为了压缩表格合并箱级关系。
- 费用按已确认契约校验并明确币种；应用指引要求换标申请提交正数 CNY 费用，但本次页面审查尚未证实这一点已完整实现，实施前须联查页面与实际接口。不得自行填充金额或模拟冻结；配送方式及相应附件要求也需保留。
- “确认测量数据”“确认换标完成”前先展示相关实测数据、差异或完工照片，再进行明确确认；不能用一个通用“确定”按钮代替对结果的核对。
退货链路分别呈现“退货预报、仓库签收、库存、后续换标/出库”，只有已有正式业务关联时才提供继续办理入口。签收结果使用“签收完成”等限定文案；换标确认前不得继续出库。货物废弃申请保留业务编号、货物与数量核对，说明实际执行废弃后的不可逆后果；申请能否取消按服务端当前状态判断，不将“提交申请”描述为立即废弃或一律不可取消。
### 4.5 海外采购与美国运输：减少猜选项和填重复信息
当前海外采购、本土卡车和散板列表的状态筛选是自由输入框。建议按各业务的服务端有效枚举提供中文选项，避免客户猜测应输入中文还是状态码。
卡车和散板表单先明确运输场景，再按“路线与地址、货物、联系人”分组。柜型等字段是否按场景出现需核对接口要求，不能直接删去；预算单价、预算总价和币种保持区分。带入已有联系人或地址时让客户核对，避免默认提交过期信息。
海外入库查询可先精简常用筛选，将预约、排车等细分状态放到展开筛选及详情。如果改成一个“业务编号”搜索框，需要接口支持，或明确让客户选择编号类型；不能在前端猜测编号后同时拼接多个精确查询条件。入库页面保持现有只读边界。
### 4.6 企业资料、成员与消息：降低日常管理成本
新客户登录后，用一个明确的状态区连接“完善资质 → 提交审核 → 审核结果 → 可以提交订单”。营业执照和统一社会信用代码突出显示，法人身份证等选填资料收进补充区域；审核驳回直接显示原因及修改入口。
当前资质上传弹框已经支持一键保存并提交审核，应复用这一能力；本轮重点改善入口和引导，不重复开发同一流程。待审核期间是否能保存某类草稿，按对应业务已有规则说明。
成员与权限建议采用“选择成员 → 选择职责角色 → 核对可以做的事”的表达。新增角色后直接衔接权限配置，隐藏普通用户无需理解的权限码，保存前提示新增与移除的能力。切换角色或离开配置页时，保护尚未保存的修改。职责模板属于后续建议，不假设现有系统已经支持。
个人信息与企业资料保持分开：“登录标识”可改为“登录账号与手机号”，公司联系电话仍由企业资料维护；修改登录信息会使现有会话失效时，提前用结果语言说明。
消息分类由自由输入改为与服务端正式类型对应的可选项。未来增加“去处理”入口时，先补齐受控的业务类型和关联信息，校验当前企业、权限与最新状态，再跳转现有正式页面。当前消息契约只有正文等信息，不能从消息文字猜测业务链接或执行动作。
## 5. 统一交互与文案规则
| 项目 | 建议规则 |
| --- | --- |
| 页面重点 | 每个当前任务有一个清楚的主动作；标题、描述、页签与面包屑避免重复占据首屏 |
| 表单 | 字段有标签、单位、示例；必填随场景解释；高级信息可以分组但不遗漏校验 |
| 保存与提交 | “保存草稿”“提交订单”“提交申请”“确认费用”分别命名，成功提示写明真实结果 |
| 二次确认 | 费用锁定、账单确认、换标确认、废弃等保留；不在普通查阅和无副作用跳转上增加确认 |
| 空态 | 说明没有记录还是没有符合筛选的记录，并给出创建或清除筛选入口；受权限约束 |
| 错误态 | 说明哪里失败、输入是否保留、如何继续；诊断编号放在可复制的故障详情内 |
| 权限态 | 不可访问的业务不展示可点击假入口；有查看权限但不能办理时说明原因及联系对象 |
| 文件 | 显示用途、格式、大小限制、上传结果、预览/下载入口；失败可以重试，替换影响明确 |
| 时间与金额 | 标明币种、单位和必要时区；预计与实际、参考报价与正式费用明确区分 |
| 业务标识 | 客户侧头程全流程以入仓码为主编号，后续履约展示计划号、箱号等必要业务编号；草稿显示“提交后生成”，其他缺失显示“—”或未关联，不展示平台订单号，不回退内部 ID |
| 可访问性 | 保留键盘操作、可见焦点和完整标签；状态不只靠颜色，精简不依靠缩小字号和点击区域 |
可优先统一的文案示例：
| 当前表达 | 建议表达 | 使用条件 |
| --- | --- | --- |
| 快速下单 | 快速建草稿 | 当前动作仅生成草稿时 |
| 原子导入 | 全部正确后再导入 | 保持原有整批成功/失败语义 |
| 确认计费重 | 核对计费与费用 | 入口文案；正式确认仍提示锁定后果 |
| 确认充值 | 提交充值申请 | 客户提交付款截图等待审核时 |
| 退货换标 | 退货预报与签收 | 当前独立退货入口的职责范围 |
| 改关联／覆盖 | 修改适用入仓码／替换文件 | 报关开始前允许修改时 |
| 服务端版本、不可变历史 | 上传记录、历史版本 | 保留版本记录及审计事实 |
## 6. 建议实施顺序与依赖
P0 表示容易误解业务后果或与当前明确契约冲突，应最先核对；P1 表示首轮主要体验收益；P2 表示在样板验证后继续改善。这里不承诺人天或上线日期，需在原型和接口差距明确后估算。
| 优先级 | 工作包 | 实施范围与依赖 | 完成判断 |
| --- | --- | --- | --- |
| P0 | 修正操作结果文案 | 费用确认、充值申请、退货阶段、快速草稿；核对相关弹框与成功态 | 客户能准确说出结果及下一步，没有付款/到账/完成状态误解 |
| P0 | 清理既有旧模式分支 | 头程源码仍有 `LEGACY_MANUAL`、旧系统入仓码条件分支；需沿真实 API 核对生产者、消费者、测试后按最新契约收敛 | 不保留新旧并跑；当前环境是否命中尚未验证，不宣称已经出现于页面 |
| P1 | 列表减负 | 头程默认列、筛选、上下文恢复；海外采购与运输状态改中文选项 | 首屏可读核心信息，完整字段可查，返回不丢条件，筛选无需输入状态码 |
| P1 | 首页和导航样板 | 路由导航、首页、权限过滤、新原型；真实待办数字另核对查询能力 | 每项现有业务有归属，主页可找到头程入口，不开放 prototype 占位页 |
| P1 | 单单及批量创建优化 | 创建页、快速草稿、导入结果；核对必填规则、错误定位和幂等 | 区分建单方式，生成后能继续完善，失败重试不重复建单 |
| P1 | 费用与海外确认优化 | 费用依据、完工证据、确认后果；保留独立写权限与版本控制 | 确认前看到相关证据，过期状态不能继续提交 |
| P2 | 海外仓与退货入口收敛 | 库存不同粒度、服务申请与阶段命名、新原型 | SKU/箱关系不丢失，签收与后续处理明确 |
| P2 | 财务、企业设置与消息 | 任务筛选、成员角色衔接、未保存保护；消息关联可能需要后端契约 | 不依赖技术术语完成常见任务，权限边界保持正确 |
建议先交付一套可评审样板：**首页、头程列表、创建订单、计费与费用确认**。对四页逐项明确详情、新增、编辑、确认和文件预览的承载方式、字段顺序、按钮位置与状态，再进入实现。
需要后端配合的能力单独列清：跨业务待办统计、跨业务统一订单查询、账单任务筛选、消息到业务的受控关联，以及已有接口尚不支持的结果集定位。它们都不能仅靠换菜单名称完成；新增接口须同步正确区域 Gateway、Controller、OpenAPI、权限和调用端。
不在首轮新增多语言、移动端适配、在线报价引擎、即时聊天、复杂推荐或新的统计平台。暂不建设“简易版/专业版”两套业务协议；通过一套页面的默认展示与按需展开降低复杂度。
## 7. 怎样验证确实更好用
### 7.1 先测基线，再对照样板
邀请 5–8 名具有代表性的客户使用者，覆盖新客户、日常下单人员、财务人员和企业管理员；人数是首轮建议，不能据此推断所有客户偏好。用同样的业务场景和数据分别操作当前页面与新原型，记录任务完成率、耗时、走错入口、字段报错和求助次数。
| 测试任务 | 建议验收目标 |
| --- | --- |
| 新客户找到企业审核入口 | 无口头指引，在 30 秒内找到，知道当前缺什么与下一步是谁处理 |
| 从首页找到头程发货或指定业务 | 30 秒内定位；常用任务目标入口建议不超过 2 次点击，不含表单填写和必要业务确认 |
| 填写一张准备好资料的订单 | 必填项可定位；保存、提交结果不混淆；无协助完成率建议达到 90% |
| 批量导入含错误行的资料 | 能区分成功与失败行，找到修正位置，明确成功记录仍是草稿 |
| 查询指定订单并返回列表 | 找到进度与下一步；返回后保留筛选和页码 |
| 核对费用、确认账单、提交充值申请 | 所有参与者都能区分费用确认、付款及到账；误判实际后果视为未通过 |
| 查看退货签收及换标结果 | 所有参与者都能区分签收完成、换标完成和出库完成 |
| 修改角色后切换对象 | 未保存内容不会无提示丢失；权限变化可被核对 |
上述数值是建议目标，当前没有实测基线，不写成已取得的改善比例。若样板增加步骤却没有降低错误或完成时间，应调整流程，不能只以按钮数更少判定成功。
### 7.2 实现验收
- 使用 `1920×1080`、浏览器缩放 `100%`，由人工完成操作并提供截图，核对默认态、长编号、多行数据、加载、空态、错误态、无权限与过期状态。
- 涉及页面改造时，先形成逐页逐操作的原型核对矩阵；本文不是已批准的视觉替代规范，不能据此直接批量换成抽屉、弹框或“更多”菜单。
- 前端实现后运行客户端声明的直接受影响测试、`pnpm typecheck` 和 `pnpm build`；共享导航、组件及状态修改需覆盖消费者。纯文档交付不代表这些实现检查已经执行。
- 新增、改名或删除对外 API 时，完成调用端到 Gateway、服务、OpenAPI 与权限的联查，并运行仓库要求的网关合同检查。
- 部署、真实 HTTP 与环境数据变更按仓库授权规则另行执行；本次文档编写没有开展这些操作。
## 8. 评审时建议确认的四项决定
1. **首轮主场景：**建议先做头程客户“发货—查询—费用确认”闭环；如实际客户以海外仓为主，应调整样板顺序。
2. **导航结构与位置：**在“方案 A：五个任务型主入口”和“方案 B：保留业务域侧栏”之间确认；同时决定个人信息、消息放顶部还是侧栏底部，以及快速建草稿放首页卡片还是订单中心页内。确认前不删除任何正式菜单。
3. **创建流程：**是否接受“填写订单、快速建草稿、Excel 批量建草稿”的命名，以及分阶段填写的原型方向。
4. **首页待办范围：**优先哪些真实待办、由哪些接口提供；没有数据支持的项先只提供入口。
以上为进入页面设计前需要对齐的产品选择，不影响先使用本文讨论方向。
## 附录：主要核对依据
以下行号为本次审查时的位置，后续修改可能变化；定位时以文件及符号共同核对。
| 依据 | 核对位置或内容 |
| --- | --- |
| [客户端应用指引](../../apps/client-web/AGENTS.md) | 模块入口、正式发布边界、头程草稿、财务、海外仓、人工验收要求 |
| [模块注册](../../apps/client-web/src/modules/registry.ts)、[导航组装](../../apps/client-web/src/navigation/clientNavigation.ts) | 正式菜单汇总；`buildModuleNavigation` 与 `filterNavigationByPermissions` |
| [订单模块路由](../../apps/client-web/src/modules/order-management/routes.ts) | 第 9–14 行：统一“我的订单”仍为 prototype；海外入库、派送为 active |
| [首页](../../apps/client-web/src/modules/dashboard/views/DashboardView.vue) | 6 个权限化创建入口、独立新建路由、头程订单列表嵌入与内容区响应式规则 |
| [应用壳层](../../apps/client-web/src/layouts/AppLayout.vue) | 第 206、253、263 行附近：顶部消息、工作页签、面包屑；已有 KeepAlive |
| [头程订单页](../../apps/client-web/src/modules/first-leg/views/FirstLegOrdersView.vue) | 第 83、117、150、1215、2093、2141、2151 行附近：筛选、默认列、费用入口、旧模式分支、导入及货物字段 |
| [快速建单页](../../apps/client-web/src/modules/first-leg/views/QuickOrderView.vue) | 第 398–431 行附近：创建成功跳转、草稿说明及旧模式条件提示 |
| [计费确认组件](../../apps/client-web/src/modules/first-leg/components/InboundBillingPanel.vue) | 第 58、258 行附近：二次确认、费用锁定与面板内容 |
| [报关资料组件](../../apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue) | 第 240–293 行附近：资料覆盖、版本记录、修改与下载动作 |
| [海外仓路由](../../apps/client-web/src/modules/overseas-warehouse/routes.ts) | 第 27–42 行：退货入口及共用库存组件的两种配置 |
| [海外仓服务页](../../apps/client-web/src/modules/overseas-warehouse/views/WarehouseServiceView.vue) | 第 827、873、1014、1079 行附近：客户确认、模板入口和待导入关系 |
| [海外采购与运输共用页](../../apps/client-web/src/modules/cross-border/components/BusinessOrdersView.vue)、[海外入库页](../../apps/client-web/src/modules/order-management/views/InboundOrdersView.vue) | 共用页第 298、332 行附近的状态筛选与表单；入库页第 91–114 行附近的筛选和多类状态 |
| [资金账户](../../apps/client-web/src/modules/finance/views/FinanceAccountView.vue) | 第 224、252、296 行附近：资金信息、充值流程与提交文案 |
| [客户账单](../../apps/client-web/src/modules/finance/views/FinanceBillsView.vue) | 第 30、178、189、208 行附近：收款视角、筛选、客户确认 |
| [企业资料](../../apps/client-web/src/modules/tenant-management/views/CompanyProfileView.vue) | 第 192、444、544、692 行附近：资质定位、提交审核、默认页签及现有提交能力 |
| [权限配置](../../apps/client-web/src/modules/tenant-management/views/PermissionsView.vue) | 第 30、36、102、114、124 行附近：切换加载、技术表达与权限树 |
| [消息页](../../apps/client-web/src/modules/notifications/views/NotificationsView.vue)、[消息契约](../../apps/client-web/src/modules/notifications/contracts.ts) | 分类为自由输入；详情契约当前无业务动作关联信息 |
| [客户栏目架构原型](../悦/柏悦物流客户端/柏悦物流客户端-栏目架构图.html)、[仓库工作台原型](../悦/官网头程下单/workbench.html) | 现有栏目及流程参考；仓库工作台仍为 2026-09-08 版本，不能将其中业务能力直接视为当前已开放 |
| 2026-09-18 最新工作台原型 | 微信缓存文件修改时间 `2026-09-18 11:37:20`，SHA-256 `9FA64EB74381DFB11506799E1EF33593EE11C0300F362AF875902984CE5D2E20`；正式实施前需归档到仓库并取得稳定路径 |
| [平台客户层级与权限契约](../平台客户层级与权限契约.md)、[前端原型验收规则](../Admin-Client前端原型还原验收规则.md)、[工程执行约束](../AI工程执行与协作约束.md) | 客户可见语义、逐页原型确认、人工验收与实现边界 |
订单与客户/客户端首页简化样板.md
+106
View File
@@ -0,0 +1,106 @@
# 客户端首页简化样板
日期：2026-09-18。依据：[客户端简化与易用性优化建议](客户端简化与易用性优化建议.md)及本轮“先修改一个首页看看效果”的要求。
本轮直接实现首页样板，供人工查看后调整。当前用户要求作为首页布局变更依据；其余页面继续沿用各自已确认原型。验收视口为 1920×1080、缩放 100%，状态为待人工截图确认。
## 修改前核对矩阵
原型入口：[workbench.html](../悦/官网头程下单/workbench.html) 的 `#dashViewHome`（第 3532 行附近）；当前实现入口：[DashboardView.vue](../../apps/client-web/src/modules/dashboard/views/DashboardView.vue)。
| 页面/操作 | 原型与当前承载 | 本轮样板 | 原因及影响 |
| --- | --- | --- | --- |
| 首页布局 | 原型为三列海外业务卡片；当前为卡片主区及账户、概览、支持侧栏 | 欢迎区、常用入口、头程订单动态、需要处理、其他业务 | 头程入口前置，减少不提供实际功能的提示按钮；只修改首页内容区 |
| 创建/查询业务 | 原型卡片进入业务；当前为正式路由跳转 | 按成员权限显示常用入口，进入现有创建页或列表 | 不新增表单、不改变下单承载或权限 |
| 企业认证提醒 | 当前首次进入弹出 520px 居中提醒，进入资质上传 | 持续可见的状态提示，主动点击进入已有资质上传弹框 | 减少登录后打断；审核中、驳回、停用分别解释；不改资质操作本身 |
| 继续草稿 | 原型首页未定义；原订单列表已有草稿操作 | 显示少量真实草稿及“前往订单列表完善”入口 | 同时要求列表与编辑权限；沿用列表办理，避免同名编辑路由缓存引发跨草稿错误 |
| 费用确认 | 首页未定义；列表进入正式确认弹框 | 仅在近期订单有服务端待确认标志时提示“前往订单列表核对” | 不假装直达具体确认页，不在首页提交确认 |
| 最近业务 | 当前首页未展示列表 | 只读头程订单摘要；编号缺失为“—” | 显示部分记录，不作全量统计；完整查询进入订单列表 |
| 文件预览、删除、审核 | 首页未定义 | 不新增首页操作，保留原业务页面承载 | 不改变既有重要操作的确认门槛 |
## 数据与状态
- 企业资料、已提交头程订单、草稿分别使用现有公开 API，独立处理失败；不加载成员、资质附件或仓库主档。
- 使用首页局部状态，不覆盖订单列表的共享集合与筛选结果。每次回到首页重新获取，刷新期间不将旧数据当作最新事实。
- 只取一页少量订单和草稿，不展示“全部待办/全部订单”数字；近期没有费用提示不表示企业没有其他待确认费用。
- 无权限不发对应请求；失败、加载、成功空态分别展示，不以假记录或零值补齐。
- 移除首页原有尚不可用的帮助按钮、固定联系时效承诺及基于局部订单集合的汇总数字。
- 保留现有响应式能力，本轮不新增其他视口验收。
## 人工查看要点
1. 首页可以直接找到头程创建与查询；海外仓、账单及其他业务入口符合账号权限。
2. 正常、无订单、请求失败、只读成员、企业待认证/审核中/驳回时，页面都有明确结果。
3. 草稿与费用提示进入真实订单列表，按钮明确说明目的地，首页不直接编辑或自动确认。
4. 长企业名、订单号和入仓码可阅读，键盘可访问入口；不展示内部 ID。
5. 返回首页更新数据，返回订单列表不会因首页加载而替换列表数据。
## 本地检查
- 首页数据编排行为测试 14 项通过，覆盖权限、独立失败、并行加载、草稿筛选、排序与业务编号。
- 客户端全量本地测试 344 项通过，类型检查和构建通过；旧首页的源码文本快照测试随旧布局替换，由新的行为测试验证读取边界。
- 静态复核发现草稿编辑页按路由名缓存，首页样板因此使用订单列表入口，不新增可能打开错误草稿的直接链接。
- 未进行真实接口验收或 AI 截图；视觉与实际操作待人工确认。
## 订单与海外仓列表统一（2026-09-18）
根据 1920×1080、浏览器缩放 100% 的人工截图，以下页面统一使用客户端订单列表的紧凑视觉语言：
- 入库订单、派送订单；
- 贴标申请、仓储转运、货物废弃；
- 退货签收、退货库存、退货箱号。
统一规则：
1. 页面路由面包屑和工作区标签已经说明当前位置，列表内容不再重复显示大标题与说明文字。
2. 查询条件使用四列网格工具栏；字段有短标签，日期使用一个范围控件，查询和重置固定在底部操作行。
3. 新增操作放入表格工具栏右侧；表格工具栏左侧显示列表名称和总数，不在页面右上角单独悬浮。
4. 表格操作列固定在第一列；长编号单行省略并保留悬浮提示；状态使用轻量标签；行高、表头、边框和分页沿用共享密度变量。
5. 无数据时保留表头与紧凑空态，不再撑出大面积空白；错误状态与正常空数据保持区分。
6. 共用页面从同一入口收敛：贴标、转运、废弃共用列表骨架；退货库存和退货箱号共用列表骨架，避免同组页面继续产生不同间距和分页样式。
本轮只调整列表承载和视觉密度，不改变接口、业务状态、权限和创建流程。退货签收及箱号详情后续已按下文规则改为独立工作区页面。
本地检查：客户端 349 项测试、类型检查及生产构建通过；未部署、未执行真实接口或测试环境操作，更新后的 100% 截图仍需人工确认。
## 按钮层级统一（2026-09-18）
列表及详情页面统一遵循“一个操作区只突出一个主要动作”的规则：
1. 查询、新增、最终提交使用蓝色主按钮；同一区域不并列多个同等醒目的主按钮。
2. 重置、取消、返回、重试和下载等辅助操作使用白底描边按钮；按钮文字直接说明结果，不使用含义不清的“确定”。
3. 表格内的详情、编辑、查看等操作改为紧凑文字按钮，超过三个操作时继续收入口径一致的“更多”菜单，避免操作列被一排按钮撑宽。
4. 删除、停用、取消申请等不可逆或负向操作只使用红色文字或危险按钮；不把普通业务状态颜色当作按钮层级。
5. 桌面按钮统一为 32px 高、6px 圆角、13px 字号、16px 图标；小型及行内操作为 28px 高，相邻操作保持 8px 间距。
6. 禁用、加载和键盘焦点由共享样式处理；分页按钮保留方形控件样式，不套用表格行内文字按钮。
本轮将规则落在客户端共享样式、查询工具栏和数据表格中，已统一的订单与海外仓列表自动应用；业务专属的提交、危险操作和权限逻辑不变。客户端 350 项测试、类型检查及生产构建均通过，未部署，仍需按 1920×1080、浏览器缩放 100% 人工截图确认。
### 入库订单详情补充
入库订单详情不再使用重复大标题和多张纵向卡片。返回入口、计划号、集装箱/海外仓摘要和状态合并到 64px 顶栏；概览使用 42px 高的标签值行；入仓明细与托盘明细复用共享紧凑表格。计划号和状态不在概览中重复展示，页面内容统一收进一个有边界的连续详情面板。调整后客户端 351 项测试、类型检查及生产构建通过。
派送单详情同步采用相同结构：派送单号、海外仓、派送方式和状态进入 64px 顶栏；订单概览、运输预约使用 42px 信息行；货物与费用明细复用共享表格。客户可见的派送状态、派送方式、提货方式、装载类型、车型和预约账号转换为中文，不直接展示后端枚举值。调整后客户端 352 项测试、类型检查及生产构建通过。
### 贴标申请与退货签收详情补充
贴标申请详情和退货签收详情改为以业务编号为参数的独立工作区路由，列表点击“详情”后不再打开弹框，也不再依赖列表页内部状态。返回操作统一回到对应列表；新建贴标申请或退货预报成功后直接进入新建记录的详情页，避免重复打开列表标签。
两个详情均采用连续详情面板：64px 顶栏合并返回入口、业务编号、页面类型和状态；概览信息使用紧凑标签值网格；SKU、签收批次和换标任务继续使用表格展示，不拆成占空间的大卡片。贴标履约状态转换为客户可读文案，仓库显示沿用仓库目录，不向客户展示内部仓库 ID。
本轮新增独立详情路由和防回退测试后，客户端 354 项测试、类型检查及生产构建通过。未部署、未执行真实接口或测试环境操作；1920×1080、浏览器缩放 100% 的最终视觉仍待人工截图确认。
### 全部业务详情统一补充
继续按“列表紧凑、详情连续、业务编号贯穿”的原则完成客户端业务详情盘点与收敛：
- 入库订单、派送订单、头程订单；
- 海外采购、美国本土卡、美本土散板；
- 贴标申请、退货签收、仓储转运、货物废弃、退货箱号；
- 客户账单、消息详情。
上述详情均通过独立受权限保护的工作区路由打开，URL 优先使用计划号、订单号、退货单号、箱号、账单号等客户可见业务编号。列表不再承载业务详情弹框；企业资料编辑、成员/角色编辑及文件预览仍保留弹框或抽屉，因为它们属于短编辑或预览任务，不属于业务详情页。
详情视觉统一为一个有外边距和边界的连续面板：64px 左右的紧凑顶栏承载返回、业务编号、摘要、状态和必要动作；概览信息使用紧凑标签值网格；多条货物、费用、收款、托盘或签收记录使用表格；不再用多个大卡片堆叠。页面内同时提供加载、无数据、失败和重试状态，避免接口失败后只留下空白页面。
客户端全量 356 项测试、类型检查及生产构建通过。未部署、未执行真实接口或测试环境操作；最终仍需按 1920×1080、浏览器缩放 100% 逐页人工截图确认。