优化

头程到尾程/README.md

@@ -0,0 +1,29 @@
+# 头程到尾程当前维护入口
+
+这里集中列出后续流程变更需要查找和修改的文档。整体流程基线已确认，除报关协同代码外进入收尾；日常只从本目录进入，历史开发材料统一放在[文档归档](../归档/README.md)。
+
+## 当前流程文档
+
+| 用途 | 文档 | 修改什么 |
+|---|---|---|
+| 总览与节点 | [头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md) | 三大业务块、客户进度、后台节点、真实明细和 F01-F40 关系 |
+| 分段流程 | [头程到尾程分阶段流程](../头程到尾程分阶段流程/README.md) | 六个阶段的字段、页面操作、权限、状态和异常 |
+| 货柜入口 | [国内货柜履约 README](../国内货柜履约/README.md) | 分柜、装柜、报关协同、送港和进港的货柜范围 |
+| 报关与船期专题 | [报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md) | 客户资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格 |
+| 报关开发交接 | [报关代码开发交接清单](报关代码开发交接清单.md) | 当前未完成的报关代码范围、完成条件和开发入口 |
+| 第一阶段冻结矩阵 | [头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md) | F01-F24 节点、报关与送港并行关系、当前实现缺口和开发前确认项 |
+
+## 变更查找
+
+- **改客户看到的主节点或三大块关系**：先改总览，再检查对应阶段文档。
+- **改头程下单**：查阶段一、阶段二；费用确认仍是并行事项，不阻断排柜和装柜。
+- **改海运（货柜）**：查阶段三、阶段四和报关专题；`LOADED` 后报关协同、送港运输两条线并行，实际开船后才进入海运节点。
+- **安排报关开发**：只看[报关代码开发交接清单](报关代码开发交接清单.md)，流程规则回看报关专题，不再从归档的开发规划开始。
+- **改尾程入库和派送**：查阶段五、阶段六。
+- **改页面范围或已确认需求**：查[页面与原型清单](../国内货柜履约/国内货柜履约页面与原型清单.md)和[需求确认表](../国内货柜履约/国内货柜履约需求确认表.md)。
+
+## 归档位置
+
+- [头程到尾程历史文档](../归档/头程到尾程/README.md)：全流程手册、旧现状全景、AI 上下文、易用性方案。
+- [国内货柜履约历史记录](../国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收、审计和旧确认材料。
+- 跨区域认证、权限、统一订单状态、船节点、部署和数据库等正式契约继续留在原业务目录，不归入流程历史归档。

头程到尾程/头程至实际开船节点冻结矩阵与缺口清单.md

@@ -0,0 +1,164 @@
+# 头程至实际开船节点冻结矩阵与缺口清单
+
+本文按当前确认结果冻结第一阶段范围：从头程下单开始，完成国内履约、报关协同、送港运输，并记录承运船舶实际开航。尾程入库、派送和签收不在本阶段实现。流程基线同时采用《报关代码开发交接清单》和《头程到尾程流程节点梳理》；原型只用于页面字段和承载方式参考。
+
+## 一、阶段边界
+
+```text
+头程下单
+  F01-F13：下单、审核、到仓、测量、计费、费用确认、组托、待分柜
+国内货柜履约
+  F14-F21：分柜、订舱、拖车、拣货、装柜、LOADED
+LOADED 后并行
+  F22：报关协同
+  F23：送港、进港、甩柜、改配
+海运起点
+  F24：承运船舶实际开航
+```
+
+本阶段的终点是实际开航事实，不是“报关完成”、国内离仓、目的港清关或海外入仓。`LOADED` 只表示物理装柜完成；报关协同线和送港运输线从 `LOADED` 后同时启动，不能把其中一条线的结果写成另一条线的结果。
+
+## 二、F01-F24 节点冻结矩阵
+
+| 节点 | 客户可见进度 | 后台业务对象 | 必须形成的真实事实 | 当前状态 | 本阶段缺口 |
+|---|---|---|---|---|---|
+| F01-F07 | 待下单、审核中、已审核 | 企业、订单、审核任务 | 提交、补件、审核、入仓单生成 | 已有主链 | 按现有订单契约回归，不在本轮重做 |
+| F08-F10 | 待到仓、测量中、待确认 | 入仓单、测量记录 | 收货、扫码、称重、测量、审核 | 已有主链 | 只核对是否能稳定产出排柜事实 |
+| F11-F13 | 费用待确认、待组托、待分柜 | 费用版本、确认记录、托盘 | 计费推送、客户确认、组托/封托 | 已确认并行规则 | 保证费用默认确认不能冒充报关确认 |
+| F14-F20 | 待分柜、订舱中、装柜中 | 柜次、装柜计划、拖车、PDA 任务 | 分柜、订舱、排车、拣货、照片、铅封、数量核对 | 主链已有 | 核对真实柜号、订舱和装柜快照能否冻结 |
+| F21 | 国内已装柜 | 装柜计划、物理货柜、装柜证据 | 实际柜号、实装箱数、装柜证据、`LOADED` | 已有 | 报关案例按最终实装范围建立；部分装柜只显示已装箱数并标记线下处理，不在系统内自动分摊 |
+| F22.1 | 报关确认中 | 客户报关案例 | 每客户案例、客户范围、入仓码范围、实装箱数显示 | 缺失 | 新增客户级案例和柜内覆盖信息；部分装柜显示箱数并交线下处理 |
+| F22.2 | 待提交资料、待补资料 | 客户资料包 | 上传、替换、补充、资料类型、版本、提交时间 | 部分已有 | 当前任意文件模型需补类型化清单和补件原因 |
+| F22.3 | 已发送报关行 | 报关行发送批次 | 发送范围、文件快照、发送人、发送时间、报关行 | 缺失 | 新增发送批次及幂等历史 |
+| F22.4 | 待客户确认 | 回执轮次 | 报关行回执、回执版本、返回时间、关联客户案例 | 缺失 | 新增每客户/每轮回执对象 |
+| F22.5 | 客户确认中、已打回 | 客户确认记录 | 确认/打回、成员、时间、原因、当前轮次 | 缺失 | 客户端新增确认与打回，打回只重开当前客户 |
+| F22.6 | 等待整柜确认 | 柜级申报批次 | 所有客户案例确认完成的门禁快照 | 缺失 | 未全部确认不得进入整柜正式提交 |
+| F22.7 | 已提交正式申报 | 整柜正式申报 | 提交报关行确认、正式申报时间、操作人、批次 | 缺失 | 不能用旧 `start` 直接代替正式申报 |
+| F22.8 | 查验中、待补资料、已放行、扣货/其他 | 海关结果事实 | 报关单号、结果类型、时间、凭证、处理结果 | 缺失 | 查验、不查验放行、扣货和其他结果分开记录 |
+| F23.1 | 送港中、已离仓 | 送港/出仓任务 | 离仓时间、车辆/任务、操作人、证据 | 已有对象 | 报关确认不能成为送港前置 |
+| F23.2 | 已送港、已进港 | 运输和港口事实 | 送港时间、进港时间、来源和凭证 | 部分已有 | 与订舱、拖车和船次事实统一读写 |
+| F23.3 | 已甩柜、改配中、待下一航次 | 异常/改配记录 | 甩柜原因、发生时间、原航次、新航次、处理人 | 部分已有 | 需要独立历史，不能覆盖原进港事实 |
+| F24 | 海运中 | 船次实际节点 | 承运船舶、航次、实际开航时间、来源/凭证 | 基础已有 | 只允许实际开航事实推进海运节点 |
+
+## 三、当前实现与目标的主要断点
+
+### 1. 报关数据模型仍是旧柜级模型
+
+当前 `fl_customs_container` 只有 `WAITING_CUSTOMER_DOCUMENTS`、`READY_TO_START`、`DECLARING`、`COMPLETED` 四个状态；客户资料根记录挂在柜级报关聚合下，不能表达“同柜多个客户各自有独立案例和轮次”。
+
+目标至少需要以下关系：
+
+```text
+物理货柜
+  ├─ 最终实装快照
+  ├─ 客户报关案例 × N
+  │    ├─ 客户资料包与版本
+  │    ├─ 报关行回执轮次 × N
+  │    └─ 客户确认/打回记录 × N
+  ├─ 整柜正式申报批次
+  └─ 海关结果事实 × N
+```
+
+### 2. 当前“报关完成”含义过宽
+
+现有完成动作是平台上传每份完成文件，或对全买单柜直接确认；这不能继续作为客户确认、正式申报、海关放行和可离仓的统一含义。状态需要按客户案例、整柜申报和海关结果分别投影。
+
+### 3. 报关线与送港线的门禁关系需要调整
+
+当前 `CustomsDispatchGateContributor` 要求 `fl_customs_container.status=COMPLETED` 才通过国内出仓门禁，`CustomsAutoDispatchCoordinator` 也在报关完成后自动尝试离仓。这与冻结口径冲突：报关资料未确认只能阻断报关线正式提交，不能阻断送港线。
+
+需要重新定义：
+
+- 送港/离仓门禁只检查装柜、PDA、订舱、证据和其他已确认的运输条件。
+- 报关线单独检查客户案例确认、整柜申报和海关结果。
+- 报关完成事件不能自动伪造送港或开船事实。
+- 实际开航只能由船次实际节点推进。
+
+### 4. 客户端缺少报关协同闭环
+
+当前客户端 `CustomsDocumentsDialog.vue` 只能上传、替换、调整关联入仓码和下载完成文件，缺少：
+
+- 独立报关资料列表和待办数；
+- 报关行回执查看；
+- 当前轮次确认；
+- 打回原因和重新提交；
+- 客户案例的进度和通知。
+
+### 5. 平台端缺少整柜协同闭环
+
+当前 `ContainerCustomsPanel.vue` 主要展示缺资料清单、冻结资料和完成文件，缺少：
+
+- 按客户查看案例和实际装柜覆盖；
+- 发送报关行批次；
+- 回执轮次管理；
+- 客户确认汇总；
+- 全部客户确认后的整柜正式提交；
+- 报关单号和海关结果录入；
+- 查验、扣货、补资料和其他结果的历史。
+
+## 四、接口、权限、审计和测试缺口
+
+### 接口与数据库
+
+- OpenAPI 不能继续只暴露旧的四态 `ContainerView`。
+- 需要新增客户案例、资料包、发送批次、回执轮次、确认记录、整柜申报和海关结果的查询/命令契约。
+- 文件仍由 File 服务保存，但每个文件必须绑定业务类型、客户案例/申报批次、版本和覆盖范围。
+- 每个写命令都要带版本和幂等键；重放同参数返回原结果，不同参数返回冲突。
+- 换柜时需要保留新旧柜关联；部分装柜只记录已装箱数和线下处理标记，不在系统内自动做数量分摊或覆盖旧资料。
+
+### 权限
+
+至少区分：
+
+- 客户上传、替换、补件、确认、打回；
+- 平台客服接收、核对、退回补件；
+- 平台报关操作员发送报关行、上传回执、提交正式申报；
+- 平台人员录入查验、放行、扣货及其他海关结果；
+- 客户和平台各自的只读下载权限。
+
+### 审计
+
+需要保留客户范围、资料版本、回执轮次、确认人、打回原因、提交批次、报关单号、结果凭证和操作时间。客户 A 的动作不能出现在客户 B 的案例中；柜级汇总可以看到客户名和业务编号，但客户端只能看到自身范围。
+
+### 测试
+
+最小验收矩阵至少覆盖：
+
+1. 单客户和多客户同柜。
+2. 一客户打回时其他客户继续保持已确认。
+3. 同一请求重放、同幂等键换参数、版本冲突。
+4. 未全部客户确认时正式提交被拒绝。
+5. 正式申报、查验、不查验放行、扣货和其他结果分别显示。
+6. 报关线未完成时送港仍可按运输门禁继续。
+7. 甩柜改配保留原航次事实并生成新航次关联。
+8. 只有实际开航事实推进 F24。
+9. 客户越权读取同柜其他客户资料被拒绝。
+10. 部分装柜能显示实际箱数并留下线下处理标记；换柜不能直接覆盖原案例和历史回执。
+
+## 五、开发前仍需业务确认
+
+以下问题中，前四项已经由《报关代码开发交接清单》和《头程到尾程流程节点梳理》冻结，本轮又补充冻结了文件形态、部分装柜展示、回执确认、首期申报和实际开航/改配处理方式；表格后的内容仍需业务补充，不能由代码现状推断。
+
+### 已冻结的业务规则
+
+| 规则 | 冻结口径 | 依据 |
+|---|---|---|
+| 资料提交时点 | `LOADED` 后按最终实装快照建立客户案例并进入本轮报关 | 交接清单“一、必须实现的报关流程”；总流程 F21/F22 |
+| 同柜客户边界 | 一个客户案例只属于一个客户；同一客户多个入仓码可以共享资料，但跨客户正式合报默认禁止 | 报关专题“申报组与柜级总览”“买单、退税和混合柜完成条件” |
+| 回执与客户确认 | 首期以报关行回执文件为主，客户对整份回执确认；回执上传不等于客户确认 | 本轮业务确认 |
+| 资料与部分装柜 | 报关资料、报关行回执都按文件保存；部分装柜只展示箱数，线下人员处理后续，不做系统内数量分摊 | 本轮业务确认 |
+| 首期正式申报 | 由平台授权人员人工提交并回填报关行确认和海关结果 | 本轮业务确认；报关专题状态约定 |
+| 报关与送港关系 | `LOADED` 后两条线并行，报关确认、正式申报和海关结果不作为送港前置 | 交接清单“二、必须保持的并行关系”；总流程“四、关键节点” |
+| 海运起点与改配 | 首期人工录入实际开航；甩柜/改配生成新航次，并重新评估关联申报批次；只有实际开航事实推进 F24 | 本轮业务确认；交接清单第二条；总流程 F23/F24 |
+
+### 仍需补充的字段和操作规则
+
+1. 首版资料清单具体项目、条件规则、版本生效方式和责任人是什么？
+
+## 六、冻结结论
+
+- 第一阶段覆盖 F01-F24，终点为实际开航。
+- F22 报关协同和 F23 送港运输从 `LOADED` 后并行启动。
+- 客户确认、报关行回执、整柜正式申报、海关放行、离仓、进港、甩柜和实际开航都是独立事实。
+- 先完成节点矩阵、对象关系、状态投影、门禁和验收缺口确认，再进入代码设计。
+- 尾程 F25-F40 暂不纳入本阶段实现，但必须保留 F24 到目的港清关的接口衔接点。

头程到尾程/报关代码开发交接清单.md

@@ -0,0 +1,68 @@
+# 报关代码开发交接清单
+
+> **当前状态：流程已确认，报关协同代码进入第一批开发。** 本文是开发交接入口，已落地内容不代表完整报关协同或真实验收通过。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。
+
+> **本轮补充确认：** 首期报关行回执以文件为主，客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；实际开航首期人工录入，甩柜/改配生成新航次并重新评估关联申报批次。
+
+## 一、必须实现的报关流程
+
+从装柜完成（`LOADED`）开始，按柜内客户分别处理：
+
+1. 按最终实装清单建立客户报关案例和资料包。
+2. 收集客户上传、替换或补充的资料，发送给报关行。
+3. 接收报关行回执并发给对应客户确认。
+4. 客户打回时，只重开对应客户当前轮次，重新上传、重新发送并生成新回执；保留每轮资料、回执、确认人、时间和打回原因。
+5. 柜内所有客户确认后，提交整柜资料给报关行确认，由报关行正式申报。
+6. 分别记录海关查验、不查验放行、扣货或其他正式结果。
+
+报关行回执、客户确认、整柜正式申报和海关放行是不同节点。客户确认不能自动完成，费用的系统默认确认也不能代替报关资料确认。
+
+## 二、必须保持的并行关系
+
+- `LOADED` 之后，报关协同线和送港运输线分别启动，互不作为对方的前置。
+- 报关资料未确认只阻断报关线的整柜正式提交，不阻断送港。
+- 送港、进港、甩柜和改配独立留痕；只有承运船舶实际开航后才进入海运节点。
+- `LOADED` 只表示物理装柜完成，不表示报关完成、已放行或已开船。
+
+## 三、当前代码交接重点
+
+### 已落地的第一批能力
+
+- 平台端和客户端都能展示当前视角的实际装箱数；部分装柜只展示箱数，后续由线下人员处理，系统不做数量分摊。
+- 报关资料和报关行回执继续按文件上传、覆盖、版本和下载处理；页面文案已区分“回执”和“完成”，避免把上传回执误认为客户确认或正式申报。
+- 报关资料链路仅适用于退税货物；买单货物不创建客户报关资料、回执和客户确认流程。
+- 回执上传后进入待确认状态；客户端已提供整份回执确认和打回入口，打回原因回传后再由平台重新上传回执。
+- 后端 OpenAPI、平台/客户端模型和基础测试已同步实际箱数字段；管理员端、客户端类型检查及相关组件测试已通过。
+
+这批能力支撑 F21 的实装范围展示和退税客户 F22 的文件承载、回执确认入口；客户案例、回执轮次、整柜正式申报和海关结果仍未完成。
+
+当前实现仍是旧的柜级报关状态和离仓门禁，不能直接证明已经具备以下能力：
+
+- 每客户报关案例和实际装柜快照；
+- 报关行回执轮次和客户确认/打回重做；
+- 柜内所有客户确认后的整柜正式提交；
+- 查验、不查验放行和其他海关结果的独立记录；
+- 报关线与送港线的独立状态、幂等、权限和审计。
+
+开发时不要只增加页面节点文案，也不要把旧的 `COMPLETED` 直接当成客户确认、正式申报或海关放行。
+
+## 四、开发入口
+
+先核对当前代码和 OpenAPI，再决定复用或调整现有接口：
+
+- 客户端报关资料：`apps/client-web/src/modules/first-leg/`，重点查看 `routes.ts`、`CustomsDocumentsDialog.vue` 和 `api/customs.ts`。
+- 平台整柜报关：`apps/admin-web/src/modules/container-loading/`，重点查看 `ContainerCustomsPanel.vue` 和 `api/platformContainerCustoms.ts`。
+- 后端报关：`baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/customs/container/`。
+- 接口与数据：`baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml`、报关相关数据库脚本和 IAM 权限初始化。
+
+具体类名、接口路径、状态编码和数据库字段以当前代码核对结果为准；本清单只定义业务完成条件，不预先替换技术实现。
+
+## 五、完成条件
+
+- 客户 A 与客户 B 的资料、回执和确认严格隔离。
+- 每个客户都能完成“资料上传 → 报关行回执 → 客户确认”，打回后产生新轮次且不覆盖历史。
+- 未全部确认时不能提交整柜正式报关；全部确认后才能进入报关行正式申报。
+- 海关查验、不查验放行、扣货和其他结果可分别记录并回显。
+- 报关线和送港线可以先后完成，任一线的完成事件不能伪造另一条线的节点。
+- 重复请求、版本冲突、换柜、部分装柜箱数展示和权限越界都有明确结果和审计记录；部分装柜的后续处理在线下完成。
+- 完成代码联调后，再回写 F22 和阶段三的实现状态；真实验收通过前不要标记“报关完成”。