docs: align firstleg release contracts and add sailing plans

头程到尾程/README.md

@@ -11,13 +11,16 @@
 | 货柜入口 | [国内货柜履约 README](../国内货柜履约/README.md) | 分柜、装柜、报关协同、送港和进港的货柜范围 |
 | 报关与船期专题 | [报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md) | 客户资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格 |
 | 报关开发交接 | [报关代码开发交接清单](报关代码开发交接清单.md) | 当前未完成的报关代码范围、完成条件和开发入口 |
-| 第一阶段冻结矩阵 | [头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md) | F01-F24 节点、报关与送港并行关系、当前实现缺口和开发前确认项 |
+| 头程与报关交互矩阵 | [头程节点与报关清关交互矩阵](头程节点与报关清关交互矩阵.md) | F01-F24 各节点的客户、平台、PDA、报关行和船期交互 |
+| 第一阶段冻结矩阵 | [头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md) | F01-F24 节点、报关完成进入待发区、当前实现缺口和开发前确认项 |
+| 正式申报与海关结果 | [正式申报与海关结果接入设计](正式申报与海关结果接入设计.md) | F22.7 正式申报批次、报关单号、F22.8 查验/补资料/放行/扣货/其他结果及三端边界 |
+| 甩柜改配接入设计 | [甩柜改配接入设计](甩柜改配接入设计.md) | F23.3 原柜人工修改船信息并保留修改历史 |
 
 ## 变更查找
 
 - **改客户看到的主节点或三大块关系**：先改总览，再检查对应阶段文档。
 - **改头程下单**：查阶段一、阶段二；费用确认仍是并行事项，不阻断排柜和装柜。
-- **改海运（货柜）**：查阶段三、阶段四和报关专题；`LOADED` 后报关协同、送港运输两条线并行，实际开船后才进入海运节点。
+- **改海运（货柜）**：查阶段三、阶段四和报关专题；报关完成后进入待发区，甩柜只影响船期，实际开船后才进入海运节点。
 - **安排报关开发**：只看[报关代码开发交接清单](报关代码开发交接清单.md)，流程规则回看报关专题，不再从归档的开发规划开始。
 - **改尾程入库和派送**：查阶段五、阶段六。
 - **改页面范围或已确认需求**：查[页面与原型清单](../国内货柜履约/国内货柜履约页面与原型清单.md)和[需求确认表](../国内货柜履约/国内货柜履约需求确认表.md)。

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

@@ -9,14 +9,14 @@
   F01-F13：下单、审核、到仓、测量、计费、费用确认、组托、待分柜
 国内货柜履约
   F14-F21：分柜、订舱、拖车、拣货、装柜、LOADED
-LOADED 后并行
+报关完成后进入待发区
   F22：报关协同
-  F23：送港、进港、甩柜、改配
+  F23：待发区、送港、进港、甩柜、改配
 海运起点
   F24：承运船舶实际开航
 ```
 
-本阶段的终点是实际开航事实，不是“报关完成”、国内离仓、目的港清关或海外入仓。`LOADED` 只表示物理装柜完成；报关协同线和送港运输线从 `LOADED` 后同时启动，不能把其中一条线的结果写成另一条线的结果。
+本阶段的终点是实际开航事实，不是“报关完成”、国内离仓、目的港清关或海外入仓。`LOADED` 只表示物理装柜完成；报关完成是进入待发区的前置条件，待发区和船期节点分别保存，不能把其中一条线的结果写成另一条线的结果。
 
 ## 二、F01-F24 节点冻结矩阵
 
@@ -27,24 +27,24 @@ LOADED 后并行
 | 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 | 送港中、已离仓 | 送港/出仓任务 | 离仓时间、车辆/任务、操作人、证据 | 已有对象 | 报关确认不能成为送港前置 |
+| F22.1 | 报关确认中 | 柜级报关聚合内的客户资料范围 | 每客户范围、入仓码范围、混合柜隔离、实装范围回显 | 已实现并通过真实 HTTP 验收 | 独立“案例”对象仍可在正式批次设计时补充；部分装柜仍线下处理 |
+| F22.2 | 待提交资料、待补资料 | 客户资料包 | 上传、替换、关联范围、版本、冻结 | 已实现并通过真实 HTTP 验收 | 资料类型化清单和补件原因待补 |
+| F22.3 | 已发送报关行 | 独立首次发送批次 `brokerSubmission` | 业务批次号、发送人、发送时间、冻结版本、资料快照、幂等历史 | 已实现并通过定向测试与测试环境部署 | 报关行接收确认和回执轮次对象待补 |
+| F22.4 | 待客户确认 | 回执/完成文件版本 | 文件版本、关联客户范围、客户可下载 | 已实现；回执历史和确认动作历史均只读投影 | 独立回执返回时间/下载凭证仍待补 |
+| F22.5 | 客户确认中、已打回 | 客户确认记录与动作历史 | 确认/打回、回执版本、操作人、时间、原因 | 已实现并通过定向测试与测试环境部署 | 通知聚合和报关行回执轮次待补 |
+| F22.6 | 等待整柜确认 | 完税文件齐全门禁 | 所有退税客户确认、发送执行、真实完税文件齐全 | 已实现并通过专项真实 HTTP 验收 | 复杂结果凭证和补资料专项门禁待补 |
+| F22.7 | 已提交正式申报 | 正式申报批次 | 报关行确认、正式申报时间、操作人、批次、报关单号 | 已实现并通过真实 HTTP 7 步联调 | 后续补更复杂的结果凭证类型 |
+| F22.8 | 查验中、待补资料、已放行、扣货/其他 | 海关结果事实 | 报关单号、结果类型、时间、凭证、处理结果 | 已实现并通过真实 HTTP 7 步联调 | 后续补查验/扣货/补资料专项场景的更细验收 |
+| F23.1 | 待发区、送港中、已离仓 | 待发区与送港/出仓任务 | 报关完成时间、待发区门禁、离仓时间、车辆/任务、操作人、证据 | 已实现并通过真实 HTTP 验收 | 继续补待发区客户/平台投影展示 |
 | F23.2 | 已送港、已进港 | 运输和港口事实 | 送港时间、进港时间、来源和凭证 | 部分已有 | 与订舱、拖车和船次事实统一读写 |
-| F23.3 | 已甩柜、改配中、待下一航次 | 异常/改配记录 | 甩柜原因、发生时间、原航次、新航次、处理人 | 部分已有 | 需要独立历史，不能覆盖原进港事实 |
+| F23.3 | 已甩柜、等待改船后承运 | 船期记录修改历史 | 甩柜原因、发生时间、修改前后船名/航次/船期、处理人 | 已实现并通过测试环境真实 HTTP；平台与客户端最新船期投影一致 | 继续补页面截图和更复杂异常分支；柜次、订舱关联和报关事实不变 |
 | F24 | 海运中 | 船次实际节点 | 承运船舶、航次、实际开航时间、来源/凭证 | 基础已有 | 只允许实际开航事实推进海运节点 |
 
 ## 三、当前实现与目标的主要断点
 
-### 1. 报关数据模型仍是旧柜级模型
+### 1. 报关数据模型已支持客户范围，发送批次仍需独立建模
 
-当前 `fl_customs_container` 只有 `WAITING_CUSTOMER_DOCUMENTS`、`READY_TO_START`、`DECLARING`、`COMPLETED` 四个状态；客户资料根记录挂在柜级报关聚合下，不能表达“同柜多个客户各自有独立案例和轮次”。
+当前 `fl_customs_container` 仍是柜级状态聚合，但客户资料通过客户和入仓码范围隔离，真实验收已覆盖同柜多客户和混合柜。正式申报批次、海关结果事实、首次发送报关行批次和客户确认动作历史已经独立落地；尚未独立建模的是报关行接收回执、回执轮次和更细的客户案例聚合。
 
 目标至少需要以下关系：
 
@@ -54,54 +54,46 @@ LOADED 后并行
   ├─ 客户报关案例 × N
   │    ├─ 客户资料包与版本
   │    ├─ 报关行回执轮次 × N
-  │    └─ 客户确认/打回记录 × N
+  │    └─ 客户确认/打回记录与动作历史 × N
   ├─ 整柜正式申报批次
   └─ 海关结果事实 × N
 ```
 
-### 2. 当前“报关完成”含义过宽
+### 2. 当前“报关完成”仍需与正式申报、海关结果区分
 
-现有完成动作是平台上传每份完成文件，或对全买单柜直接确认；这不能继续作为客户确认、正式申报、海关放行和可离仓的统一含义。状态需要按客户案例、整柜申报和海关结果分别投影。
+现有完成动作是平台上传每份完成文件，或对全买单柜直接确认；客户确认和完成文件链路已有真实验收。正式申报批次、报关单号和海关结果已经分别记录，仍不能把其中任何一个状态直接当成海关放行或所有运输事实。
 
-### 3. 报关线与送港线的门禁关系需要调整
+### 3. 报关完成与待发区的门禁关系
 
-当前 `CustomsDispatchGateContributor` 要求 `fl_customs_container.status=COMPLETED` 才通过国内出仓门禁，`CustomsAutoDispatchCoordinator` 也在报关完成后自动尝试离仓。这与冻结口径冲突：报关资料未确认只能阻断报关线正式提交，不能阻断送港线。
+当前 `CustomsDispatchGateContributor` 要求 `fl_customs_container.status=COMPLETED` 才通过国内出仓门禁，`CustomsAutoDispatchCoordinator` 也在报关完成后自动尝试确认出仓。按最新口径，这不是冲突：报关完成后货柜进入待发区，待发区是送港运输真正开始前的状态门槛；甩柜只在船期运输层处理，不触碰报关事实。
 
 需要重新定义：
 
-- 送港/离仓门禁只检查装柜、PDA、订舱、证据和其他已确认的运输条件。
-- 报关线单独检查客户案例确认、整柜申报和海关结果。
-- 报关完成事件不能自动伪造送港或开船事实。
+- 待发区门禁先检查报关 `COMPLETED`，再叠加装柜、PDA、订舱、证据等运输条件；通过后只推进到 `WAITING_FOR_LOADING`。
+- 报关线单独保存客户确认、整柜申报和海关结果；这些事实不会被船期修改覆盖。
+- 报关完成事件只能推进待发区，不得自动伪造送港、进港或开船事实。
 - 实际开航只能由船次实际节点推进。
 
-### 4. 客户端缺少报关协同闭环
+### 4. 客户端基础报关协同闭环已完成
 
-当前客户端 `CustomsDocumentsDialog.vue` 只能上传、替换、调整关联入仓码和下载完成文件，缺少：
+当前客户端 `CustomsDocumentsView.vue` 提供独立报关资料列表和待办入口，`CustomsDocumentsDialog.vue` 已支持上传、替换、调整关联入仓码、查看和下载报关行回执/真实报关完税文件、确认整份回执和填写原因打回，并展示回执历次上传版本及确认/打回动作历史；仍缺少：
 
-- 独立报关资料列表和待办数；
-- 报关行回执查看；
-- 当前轮次确认；
-- 打回原因和重新提交；
 - 客户案例的进度和通知。
 
-### 5. 平台端缺少整柜协同闭环
+### 5. 平台端基础整柜协同闭环已完成
 
-当前 `ContainerCustomsPanel.vue` 主要展示缺资料清单、冻结资料和完成文件，缺少：
+当前 `ContainerCustomsPanel.vue` 已展示退税资料、首次发送报关行批次、回执/完成文件、客户范围、确认状态、回执历次上传版本和确认/打回动作历史，并支持正式申报批次和海关结果基础操作；仍缺少：
 
 - 按客户查看案例和实际装柜覆盖；
-- 发送报关行批次；
-- 回执轮次管理；
-- 客户确认汇总；
-- 全部客户确认后的整柜正式提交；
-- 报关单号和海关结果录入；
-- 查验、扣货、补资料和其他结果的历史。
+- 报关行接收回执和回执轮次管理；
+- 更细的查验、扣货、补资料和其他结果凭证历史。
 
 ## 四、接口、权限、审计和测试缺口
 
 ### 接口与数据库
 
 - OpenAPI 不能继续只暴露旧的四态 `ContainerView`。
-- 需要新增客户案例、资料包、发送批次、回执轮次、确认记录、整柜申报和海关结果的查询/命令契约。
+- 需要继续补充报关行接收回执、回执轮次、下载凭证及更复杂结果凭证的查询/命令契约；资料包、首次发送批次、回执版本和确认动作只读历史、整柜申报和海关结果基础契约已落地。
 - 文件仍由 File 服务保存，但每个文件必须绑定业务类型、客户案例/申报批次、版本和覆盖范围。
 - 每个写命令都要带版本和幂等键；重放同参数返回原结果，不同参数返回冲突。
 - 换柜时需要保留新旧柜关联；部分装柜只记录已装箱数和线下处理标记，不在系统内自动做数量分摊或覆盖旧资料。
@@ -129,8 +121,8 @@ LOADED 后并行
 3. 同一请求重放、同幂等键换参数、版本冲突。
 4. 未全部客户确认时正式提交被拒绝。
 5. 正式申报、查验、不查验放行、扣货和其他结果分别显示。
-6. 报关线未完成时送港仍可按运输门禁继续。
-7. 甩柜改配保留原航次事实并生成新航次关联。
+6. 报关完成后货柜进入待发区，等待船舶承运。
+7. 甩柜改配在原柜上人工修改船信息并留痕，柜子和报关事实不变。
 8. 只有实际开航事实推进 F24。
 9. 客户越权读取同柜其他客户资料被拒绝。
 10. 部分装柜能显示实际箱数并留下线下处理标记；换柜不能直接覆盖原案例和历史回执。
@@ -148,17 +140,34 @@ LOADED 后并行
 | 回执与客户确认 | 首期以报关行回执文件为主，客户对整份回执确认；回执上传不等于客户确认 | 本轮业务确认 |
 | 资料与部分装柜 | 报关资料、报关行回执都按文件保存；部分装柜只展示箱数，线下人员处理后续，不做系统内数量分摊 | 本轮业务确认 |
 | 首期正式申报 | 由平台授权人员人工提交并回填报关行确认和海关结果 | 本轮业务确认；报关专题状态约定 |
-| 报关与送港关系 | `LOADED` 后两条线并行，报关确认、正式申报和海关结果不作为送港前置 | 交接清单“二、必须保持的并行关系”；总流程“四、关键节点” |
-| 海运起点与改配 | 首期人工录入实际开航；甩柜/改配生成新航次，并重新评估关联申报批次；只有实际开航事实推进 F24 | 本轮业务确认；交接清单第二条；总流程 F23/F24 |
+| 报关与待发区关系 | 报关完成后货柜才能进入待发区；待发区是等待船舶承运的运输状态，报关和船期事实分开保存 | 本轮业务确认 |
+| 海运起点与改配 | 首期人工录入实际开航；甩柜/改配只变更船期/航次，不重新处理已完成报关资料；只有实际开航事实推进 F24 | 本轮业务确认；交接清单第二条；总流程 F23/F24 |
+
+### 本轮补充确认的甩柜/改配口径
+
+| 项目 | 已确认口径 |
+|---|---|
+| 发起与确认 | 平台人员直接编辑原柜船期，记录操作人、时间、原因和修改前后船信息。 |
+| 资料继承 | 报关完成后资料、平台回执和客户确认与船期独立；甩柜/改配不触发重新上传或重新确认。 |
+| 航次任务 | 平台人工修改原柜船信息，继续使用原任务；保留修改历史和已有节点。 |
 
 ### 仍需补充的字段和操作规则
 
 1. 首版资料清单具体项目、条件规则、版本生效方式和责任人是什么？
+2. （已确认）第一版由平台人员直接修改原柜船名、航次和船期，填写原因并保留修改历史。
+3. （已确认）平台人工修改原柜船名、航次和船期；柜子与原任务不变。
+4. （已确认）原航次退税资料、回执和客户确认与船期独立，甩柜/改配不触发重新确认。
+5. （已确认）甩柜/改配与报关资料无关，不重新生成报关批次，不要求客户重新确认。
+6. 修改船信息不生成实际开航事实；只有本柜实际随船开航后才记录 `DEPARTED_ORIGIN_PORT`。
+
+### 代码接入前置缺口
+
+最新确认取消新增航次对象和重建任务的方案。复用现有船期编辑及修改历史，柜次、订舱关联和查询任务保持不变。测试环境已核验平台与客户端都会投影修改后的最新船期，报关资料、回执、完成文件和客户确认保持不变；证据见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`。
 
 ## 六、冻结结论
 
 - 第一阶段覆盖 F01-F24，终点为实际开航。
-- F22 报关协同和 F23 送港运输从 `LOADED` 后并行启动。
+- F22 报关完成后货柜进入 F23 待发区；甩柜/改配只改变运输航次，不改变报关事实。
 - 客户确认、报关行回执、整柜正式申报、海关放行、离仓、进港、甩柜和实际开航都是独立事实。
 - 先完成节点矩阵、对象关系、状态投影、门禁和验收缺口确认，再进入代码设计。
 - 尾程 F25-F40 暂不纳入本阶段实现，但必须保留 F24 到目的港清关的接口衔接点。

头程到尾程/头程节点与报关清关交互矩阵.md

@@ -0,0 +1,78 @@
+# 头程节点与报关清关交互矩阵
+
+> 本文把头程下单 F01-F24 与报关清关的客户、平台、报关行交互放在同一张图里。当前产品先覆盖国内头程到实际开航；尾程不在本轮。报关资料只适用于包含退税货物的柜，买单货物不创建客户资料协同。
+
+## 一、总链路
+
+```text
+客户下单/入仓
+  → 收货、测量、计费、费用确认
+  → 分柜、订舱、拖车、PDA 装柜
+  → LOADED（物理事实）
+  → 客户上传报关资料
+  → 平台冻结资料并首次发送报关行（生成独立批次）
+  → 报关行回执
+  → 客户确认整份回执/打回
+  → 平台把客户确认后的回执发送报关行执行
+  → 报关行完成
+  → 平台上传真实报关完税文件
+  → 报关完成
+  → 待发区、送港、进港
+  → 甩柜/改配只修改原柜船期
+  → 实际开航
+```
+
+`LOADED` 是 PDA 产生的装柜事实，也是当前客户报关详情的准入条件；PDA 不参与资料、回执、确认或完税文件接口。报关完成是待发区的门禁，实际开航只由船次实际事实推进。
+
+## 二、F01-F21：报关前的头程节点
+
+| 节点 | 客户动作 | 平台动作 | PDA/运输动作 | 报关影响 |
+|---|---|---|---|---|
+| F01-F07 下单、审核、补件 | 提交订单、补充订单信息 | 审核订单、生成入仓单 | 无 | 仅确定客户、订单和退税/买单属性；不创建报关资料 |
+| F08-F10 到仓、收货、测量 | 查看入仓进度 | 收货、扫码、称重、测量并审核 | 仓内作业 | 形成后续实装范围的来源数据 |
+| F11-F13 计费、费用确认、组托、待分柜 | 查看/确认费用 | 发布费用版本、记录确认、组托封托 | 无 | 费用确认不能代替报关资料确认 |
+| F14-F20 分柜、订舱、拖车、拣货、装柜中 | 查看柜次和船期 | 建立柜次、订舱、拖车和装柜计划 | PDA 领取、拣货、复核、装柜 | 仍不能启动客户报关资料入口 |
+| F21 `LOADED` | 查看实际装箱数 | 固化实际柜号、实装箱数和装柜证据 | PDA 提交并产生 `LOADED` | 按最终实装范围建立退税客户报关资料范围 |
+
+部分装柜只回显实际箱数并留下线下处理标记，系统不自动分摊数量，也不覆盖原始资料范围。
+
+## 三、F22：报关平台与客户交互
+
+| 子节点 | 平台页面/接口 | 客户页面/接口 | 关键状态与门禁 |
+|---|---|---|---|
+| F22.1 建立资料范围 | Admin 查看柜级退税客户、入仓码和实装范围 | Client 只能看到自身订单范围 | 退税客户按租户和入仓码隔离；买单客户不建资料 |
+| F22.2 客户上传资料 | `GET /api/platform/v1/customs/loading-plans/{planId}` 查看汇总 | `GET /api/merchant/v1/customs/orders/{orderId}`；`POST .../documents/upload`；可替换、调整入仓码范围 | 当前要求 `LOADED`；资料版本和幂等键受门禁控制 |
+| F22.3 首次发送报关行 | Admin `POST .../{planId}/send-to-broker` | 只读看到批次和发送时间 | 资料全部冻结后生成独立 `brokerSubmission` 批次；未首次发送不能上传回执；只适用于含退税货物的柜 |
+| F22.4 上传回执 | Admin `POST .../documents/{documentId}/receipt/upload` | `GET .../receipt/download` | 回执进入 `PENDING`；回执不是报关完成文件 |
+| F22.5 客户确认/打回 | Admin 查看每客户回执状态 | `POST .../receipt/confirm` 或 `.../receipt/reject` | 确认整份回执；打回必须填写原因；版本冲突拒绝 |
+| F22.6 回执冻结与执行 | Admin `POST .../{planId}/submit-to-broker` 再次发送客户确认后的回执 | Client 只能查看确认结果和动作历史 | 发送执行后回执不能替换；`brokerSubmittedAt` 仅表示发送执行时间 |
+| F22.7 正式申报与报关行完成 | Admin 创建/提交正式申报批次、回填报关单号，并上传真实报关完税文件：`POST .../final/upload` | `GET .../final/download`；只读批次投影 | 完税文件齐全后整柜状态才可 `COMPLETED`；正式申报批次和完税文件是两件事，不能把回执或客户确认当成正式申报 |
+| F22.8 清关结果 | 平台人工补录查验、补资料、放行、扣货等独立事实；可处理未决结果 | 客户只读查看自身可见结果和凭证 | 已落地 `customs_declaration_batch`、`customs_clearance_result`；结果不推进待发区、船期或 PDA |
+
+当前客户端状态映射：`WAITING_UPLOAD` → `DOCUMENT_UPLOADED` → `DECLARING` → `CUSTOMS_COMPLETED`。平台柜级状态映射：`WAITING_CUSTOMER_DOCUMENTS` → `READY_TO_START` → `DECLARING` → `COMPLETED`。`COMPLETED` 仍需继续与正式申报、海关放行和运输节点拆开。
+
+## 四、F23-F24：报关完成后的运输交互
+
+| 节点 | 平台动作 | 客户可见内容 | 报关资料处理 |
+|---|---|---|---|
+| F23.1 待发区、送港、离仓 | 报关完成后通过待发区门禁，记录送港/离仓事实 | 查看待发、送港状态和当前船期 | 资料、回执、完税文件只读保留 |
+| F23.2 进港 | 记录进港时间、来源和凭证 | 查看进港节点 | 不改变报关状态 |
+| F23.3 甩柜/改配 | 平台人员编辑原柜船名、航次、预计时间并记录前后值、原因、操作人 | 查看修改后的当前船期和历史 | 柜号、订舱关联、资料、回执、客户确认和完税文件不变，不重新确认 |
+| F24 实际开航 | 人工录入承运船舶实际开航事实 | 查看海运已开航 | 只记录关联关系，不重做报关 |
+
+甩柜只改变运输信息，不生成新柜、不重建报关任务、不把预计船期修改误写成实际开航。
+
+## 五、当前接口覆盖与待补项
+
+已落地并部署的基础闭环：客户资料上传/替换/范围调整、平台查看、冻结资料首次发送报关行并生成独立批次、回执上传及历次版本只读投影、客户整份回执确认/打回及动作历史、平台发送报关行执行、真实完税文件上传/下载、退税与买单分流、版本和幂等门禁；当前平台与客户页面均读取最新预计船期字段，实际开航字段单独保留。
+
+仍需补齐：
+
+1. 报关行接收确认、回执轮次和回执下载凭证的独立对象及更细历史投影。
+2. 待发区客户/平台投影的更细页面展示和截图证据；`LOADED → 报关 → 待发区` 已在既有混合柜报告中通过，平台与客户改船后的当前船期双端回读已验收。
+
+正式申报批次和海关结果已在本轮实现并通过真实 HTTP：平台创建/提交批次、录入查验、查询并处理结果，客户按自身订单查询结果；证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。
+
+报关专项真实 HTTP 证据、构建号和当前 PDA 边界见[报关代码开发交接清单](报关代码开发交接清单.md)、`baiyue-firstleg/reports/focused-customs-flow-without-pda-20260927.json`、`baiyue-firstleg/reports/customs-mixed-20260927i.json` 及 `baiyue-firstleg/reports/customs-prep-container-20260926.json`。专项证据验证客户确认回执、发送报关行、上传完税文件和客户回读 `COMPLETED`，没有调用 PDA；新建混合柜全链路报告已通过 532/532。
+
+F22.7/F22.8 的独立批次、报关单号和海关结果设计见[正式申报与海关结果接入设计](正式申报与海关结果接入设计.md)；该设计不改变现有两份文件闭环，也不把结果事实写入船期或 PDA 状态。

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

@@ -1,28 +1,31 @@
 # 报关代码开发交接清单
 
-> **当前状态：流程已确认，报关协同代码进入第一批开发。** 本文是开发交接入口，已落地内容不代表完整报关协同或真实验收通过。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。
+> **当前状态：第一阶段报关协同已接入测试环境。** 客户资料、首次发送报关行批次、回执、客户确认历史和真实完税文件已形成独立链路；报关行确认回执和更复杂结果凭证仍是后续补充项。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。
 
-> **本轮补充确认：** 首期报关行回执以文件为主，客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；实际开航首期人工录入，甩柜/改配生成新航次并重新评估关联申报批次。
+> **本轮补充确认：** 首期报关行回执以文件为主，客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；报关完成后货柜进入待发区；实际开航首期人工录入，甩柜/改配只变更船期，不重新处理已完成报关资料。
+
+> **验收证据：** 既有全链路报告保留旧版 526/526、混合柜 532/532 记录；本轮新增代码、数据库和三端已部署，已用现有完成柜做接口烟测并核对首次发送门禁。完整造数到报关回归仍需要测试环境提供 PDA 作业员账号，当前 `test-acceptance.env` 缺少该变量，脚本按契约在装柜前置处停止。
 
 ## 一、必须实现的报关流程
 
 从装柜完成（`LOADED`）开始，按柜内客户分别处理：
 
 1. 按最终实装清单建立客户报关案例和资料包。
-2. 收集客户上传、替换或补充的资料，发送给报关行。
+2. 收集客户上传、替换或补充的资料，冻结后由平台生成独立批次首次发送给报关行。
 3. 接收报关行回执并发给对应客户确认。
-4. 客户打回时，只重开对应客户当前轮次，重新上传、重新发送并生成新回执；保留每轮资料、回执、确认人、时间和打回原因。
-5. 柜内所有客户确认后，提交整柜资料给报关行确认，由报关行正式申报。
-6. 分别记录海关查验、不查验放行、扣货或其他正式结果。
+4. 客户打回时，只重开对应客户当前轮次，重新上传、重新发送并生成新回执；保留每轮资料、回执、确认人、时间、动作历史和打回原因。
+5. 柜内所有客户确认后，平台发送客户确认后的回执给报关行执行。
+6. 报关行执行完成后，平台上传真实报关完税文件；全部退税资料对应的完税文件齐全后，整柜报关完成。
+7. 分别记录海关查验、不查验放行、扣货或其他正式结果。
 
 报关行回执、客户确认、整柜正式申报和海关放行是不同节点。客户确认不能自动完成，费用的系统默认确认也不能代替报关资料确认。
 
-## 二、必须保持的并行关系
+## 二、报关完成与待发区关系
 
-- `LOADED` 之后，报关协同线和送港运输线分别启动，互不作为对方的前置。
-- 报关资料未确认只阻断报关线的整柜正式提交，不阻断送港。
-- 送港、进港、甩柜和改配独立留痕；只有承运船舶实际开航后才进入海运节点。
-- `LOADED` 只表示物理装柜完成，不表示报关完成、已放行或已开船。
+- `LOADED` 只表示物理装柜完成；报关资料、回执、客户确认和正式申报仍需独立完成。
+- 报关完成后，货柜才能进入待发区；待发区表示等待船舶承运，不表示已经开船。
+- 送港、进港、甩柜和改配是运输事实；甩柜只在原柜船期记录上人工修改船信息，不回退或重新处理已完成报关资料。
+- 只有承运船舶实际开航后，才推进 `DEPARTED_ORIGIN_PORT` 海运节点。
 
 ## 三、当前代码交接重点
 
@@ -30,19 +33,49 @@
 
 - 平台端和客户端都能展示当前视角的实际装箱数；部分装柜只展示箱数，后续由线下人员处理，系统不做数量分摊。
 - 报关资料和报关行回执继续按文件上传、覆盖、版本和下载处理；页面文案已区分“回执”和“完成”，避免把上传回执误认为客户确认或正式申报。
+- 首次发送报关行单独记录 `brokerSubmission`（业务批次号、冻结资料版本、快照、操作人和时间）；未完成首次发送时不能上传回执，也不能发送客户确认结果给报关行执行。
 - 报关资料链路仅适用于退税货物；买单货物不创建客户报关资料、回执和客户确认流程。
-- 回执上传后进入待确认状态；客户端已提供整份回执确认和打回入口，打回原因回传后再由平台重新上传回执。
+- 回执上传后进入待确认状态；客户端已提供整份回执确认和打回入口，平台与客户端都展示每个回执版本的确认/打回历史，打回原因回传后再由平台重新上传回执。
 - 后端 OpenAPI、平台/客户端模型和基础测试已同步实际箱数字段；管理员端、客户端类型检查及相关组件测试已通过。
 
-这批能力支撑 F21 的实装范围展示和退税客户 F22 的文件承载、回执确认入口；客户案例、回执轮次、整柜正式申报和海关结果仍未完成。
+旧版资料与回执基础链路已通过测试环境真实 HTTP 验收；两份文件新流程已通过本地单测、契约测试和测试环境部署。报关闭环不依赖 PDA；真实 HTTP 验收应使用已经处于待发区的柜作为前置，不能因为装柜/PDA 前置失败而把报关结论判为失败。
 
-当前实现仍是旧的柜级报关状态和离仓门禁，不能直接证明已经具备以下能力：
+### 报关与 PDA、船期的边界
 
-- 每客户报关案例和实际装柜快照；
-- 报关行回执轮次和客户确认/打回重做；
-- 柜内所有客户确认后的整柜正式提交；
-- 查验、不查验放行和其他海关结果的独立记录；
-- 报关线与送港线的独立状态、幂等、权限和审计。
+- PDA 只负责装柜现场作业，产出 `LOADED` 事实；本报关模块不创建、领取、认领或提交 PDA 任务。
+- 报关模块只消费已完成装柜且可进入待发区的柜。装柜链路可以作为系统级前置验收，但不属于报关两份文件闭环的验收内容。
+- 船期、价格、甩柜和改配属于运输模块。甩柜时只人工修改原柜的船名、航次和时间，柜号、报关资料、回执、客户确认和完税文件不变，也不重新创建报关任务。
+
+### 本轮对 PDA 关系的落地说明（2026-09-26）
+
+- PDA 没有参与本轮代码修改，也没有被报关接口调用；客户资料、报关行回执、客户确认和真实报关完税文件仍由平台与客户/报关行接口独立处理。
+- 当前客户报关详情接口只对已完成装柜的订单开放，未达到 `LOADED` 时返回“订单尚未完成装柜”。因此 PDA 只是报关入口的上游准入事实，不是报关协同动作的一部分。
+- 若后续业务确认“装柜前就允许客户上传报关资料”，应单独调整 `LOADED` 准入门禁；不能通过在报关模块里偷偷创建或操作 PDA 任务解决。
+- 本轮测试已用真实 HTTP 建立退税柜、订舱和船期关联，并确认装柜计划仍为 `EDITING`、`readyForPda=false` 时不启动报关；证据见 `baiyue-firstleg/reports/customs-prep-container-20260926.json`。
+
+### 本轮报关专项真实 HTTP 证据（2026-09-27）
+
+- 使用测试库中已完成装柜的退税计划 `loadingPlanId=2103494180160507905`，没有调用任何 PDA 接口。
+- 客户确认回执：HTTP 200、业务码 `200`，报关状态仍为 `DECLARING`。
+- 平台发送客户确认结果给报关行：HTTP 200、业务码 `200`，产生 `brokerSubmittedAt`，状态仍为 `DECLARING`。
+- 平台上传真实报关完税文件：HTTP 200、业务码 `200`；随后平台和客户查询均返回 `COMPLETED`，并可见完成文件。
+- 完整证据：`baiyue-firstleg/reports/focused-customs-flow-without-pda-20260927.json`。该证据证明两份文件报关协同闭环本身不依赖 PDA。
+- 早期全量验收报告 `customs-full-20260926h.json` 的失败项集中在 PDA 任务被分配给其他作业员，导致装柜链未进入 `LOADED`；修正验收作业员绑定并补齐 File 服务回执类型后，新的全链路报告 `customs-mixed-20260927i.json` 已通过 532/532，报关模块 223+47+23 项全部通过。
+
+### 本轮部署证据
+
+- 本轮 Firstleg 后端 `backend-java #652`、下游 `baiyue-firstleg-firstleg #455`、平台管理端 `admin-web-test #473`、客户端 `client-web-test #355` 均已成功部署到测试环境，健康检查为 `UP`。
+- 客户端报关资料定向测试 61/61 通过；报关服务单测、OpenAPI 契约测试和平台报关组件测试结果记录在本轮交接记录及对应构建产物中。
+- 正式申报/海关结果接入提交：Firstleg `ed692ee3`、路由合同修正 `95da66c7`、执行顺序修正 `4bec639a`，`backend-java #639/#640/#641` 成功；Admin `29cb0bd`、顺序修正 `855d8c0`，`admin-web-test #461/#462` 成功；Client `8c8fdbc`、`client-web-test #350` 成功。正式申报和结果真实 HTTP 7 步全部通过，证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。
+- 甩柜改配投影提交 `ac3acfce`、`f1218cef`，平台容器读模型修复提交 `2c4f1ea3`；当前分支的船期展示修复已由 `backend-java #649`、`baiyue-firstleg-firstleg #452` 和 `client-web-test #351` 成功部署。真实验证确认改船只更新原柜船期，平台与客户端同步最新船期，柜号和报关资料/回执/完成文件保持不变，证据见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`。
+- 回执历史投影提交 Firstleg `f6e70ea5`、Admin `ffe91a1`、Client `3e28478` 已成功部署：`backend-java #650`、`baiyue-firstleg-firstleg #453`、`admin-web-test #471`、`client-web-test #353`。健康检查为 `UP`，平台和客户真实接口均返回 `receiptHistory`；证据见 `baiyue-firstleg/reports/customs-receipt-history-20260928.json`。
+- 本轮首次发送批次与确认动作历史提交为 Firstleg `e63cb2b2`、Admin `730defa`、Client `8fd4063`；数据库已核对 `fl_customs_broker_submission` 与 `fl_customs_completion_action_history`。现有完成柜烟测返回 `A0409 当前柜不在报关中`，确认新首次发送接口的状态门禁；证据见 `baiyue-firstleg/reports/customs-send-batch-confirmation-history-20260928.json`。
+
+当前仍需继续补齐的不是客户资料协同、正式申报和海关结果基础链路，而是：
+
+- 报关行回执的外部确认/接收回执、下载凭证和回执轮次的更细对象；首次发送批次与客户确认动作历史已经落地；
+- 更复杂的结果凭证上传和补资料专项门禁；
+- 将正式申报/海关结果继续扩展到待发区、送港、进港和实际开航的只读投影，保持运输线独立；F23.3 的船期投影已完成真实 HTTP 核验。
 
 开发时不要只增加页面节点文案，也不要把旧的 `COMPLETED` 直接当成客户确认、正式申报或海关放行。
 
@@ -60,9 +93,10 @@
 ## 五、完成条件
 
 - 客户 A 与客户 B 的资料、回执和确认严格隔离。
-- 每个客户都能完成“资料上传 → 报关行回执 → 客户确认”，打回后产生新轮次且不覆盖历史。
-- 未全部确认时不能提交整柜正式报关；全部确认后才能进入报关行正式申报。
-- 海关查验、不查验放行、扣货和其他结果可分别记录并回显。
-- 报关线和送港线可以先后完成，任一线的完成事件不能伪造另一条线的节点。
+- 每个客户都能完成“资料上传 → 报关行回执 → 客户确认/打回”，资料和完成文件保留版本，客户范围严格隔离。
+- 首次发送报关行必须生成独立业务批次；客户每次确认或打回都保留对应回执版本、操作人、时间和原因。
+- 未全部客户确认时不能完成整柜报关；正式申报批次、海关回填结果和报关单号已独立建模，不能把客户确认或完税文件上传直接当作海关放行事实。
+- 海关查验、不查验放行、扣货和其他结果已落地为批次下独立事实；后续只需补更复杂的凭证上传和补资料专项验收。
+- 报关完成后才能进入待发区；进入待发区后才推进送港/进港。甩柜/改配只修改原柜船名、航次和船期并保留历史，不能伪造或覆盖报关资料、回执和客户确认。
 - 重复请求、版本冲突、换柜、部分装柜箱数展示和权限越界都有明确结果和审计记录；部分装柜的后续处理在线下完成。
-- 完成代码联调后，再回写 F22 和阶段三的实现状态；真实验收通过前不要标记“报关完成”。
+- 完成代码联调后，再回写 F22 和阶段三的实现状态；当前真实 HTTP 已通过，后续仍按 `COMPLETED`、海关放行和运输节点分别验收。

头程到尾程/正式申报与海关结果接入设计.md

@@ -0,0 +1,128 @@
+# 正式申报与海关结果接入设计
+
+本文只补 F22.7、F22.8 的业务对象和交互边界，不改变已经验收的退税报关基础闭环：客户上传退税资料 → 平台发送报关行 → 报关行回执 → 客户确认或打回 → 平台发送确认结果给报关行 → 平台上传真实报关完税文件。
+
+## 一、先冻结现有边界
+
+```text
+LOADED
+  ↓
+客户退税资料齐全
+  ↓ 平台开始报关，冻结资料范围和版本
+DECLARING
+  ↓ 报关行回执
+客户确认整份回执 / 打回
+  ↓ 平台发送客户确认结果给报关行
+等待真实报关完税文件
+  ↓ 每个退税客户均有完成文件
+COMPLETED（平台已收到本轮完税文件）
+  ↓
+WAITING_FOR_LOADING（进入待发区）
+```
+
+`COMPLETED` 只表示平台收到本轮真实完税文件，不能解释为海关放行、正式申报成功或船舶已开航。正式申报批次可以在报关行执行后、完税文件回传前建立；PDA 只在上游产出 `LOADED`；待发区、送港、甩柜、改配和船舶实际开航属于运输线，不能由正式申报对象反向改写。
+
+## 二、F22.7 正式申报批次
+
+正式申报批次是平台授权人员人工提交后形成的独立事实，粒度为整柜一次申报批次。它引用当前柜级报关聚合和已冻结的客户资料/回执快照，不复制文件内容。
+
+建议对象：`customs_declaration_batch`
+
+| 字段 | 说明 |
+|---|---|
+| `id` | 平台长 ID，前端按字符串传输 |
+| `customsContainerId` / `loadingPlanId` | 绑定整柜报关聚合和装柜计划，创建后不可换柜 |
+| `batchNo` | 平台生成的批次号，人工提交前为空或草稿号 |
+| `status` | `READY`、`SUBMITTED`、`ACKNOWLEDGED`、`RESULT_PENDING`、`CLOSED`、`CANCELLED` |
+| `sourceVersion` | 提交时整柜报关聚合版本，防止提交后资料范围漂移 |
+| `receiptSnapshot` | 提交时客户资料、回执、确认结果的客户范围和文件版本快照 |
+| `customsEntryNo` | 报关单号，平台人工回填；同一有效批次唯一 |
+| `submittedBy/submittedAt` | 平台提交人和时间 |
+| `acknowledgedBy/acknowledgedAt` | 报关行或平台确认受理人和时间 |
+| `remark` | 提交说明，长度受服务端限制 |
+
+创建或提交门禁：
+
+1. 柜级报关已进入 `DECLARING`，且整柜退税资料已覆盖实际装柜退税票；批次也允许在完税文件上传后的 `COMPLETED` 阶段补建。
+2. 所有退税客户的当前回执均为 `CONFIRMED`。
+3. 已执行发送动作，`brokerSubmittedAt` 已存在。
+4. 提交使用版本号和幂等键；相同请求重放返回同一批次，不同载荷返回冲突。
+5. 提交后禁止修改客户资料范围、回执和确认结果；补资料必须通过新批次或明确的退回重提动作产生新版本，不能覆盖历史批次。
+
+建议平台接口：
+
+- `GET /api/platform/v1/customs/loading-plans/{planId}/declaration-batches`
+- `POST /api/platform/v1/customs/loading-plans/{planId}/declaration-batches`
+- `POST /api/platform/v1/customs/loading-plans/declaration-batches/{batchId}/submit`
+- 提交时在请求体回填 `customsEntryNo`，不另设独立改单接口。
+
+客户端只读当前批次的可见投影，不提供提交和修改入口；客户只能看到自己资料覆盖的结果。
+
+## 三、F22.8 海关结果事实
+
+海关结果不是柜级状态字段，而是批次下的不可变事实记录。一次正式申报可以先产生“待结果”，之后根据实际回执追加查验、补资料、放行、扣货或其他结果；修正不能覆盖历史记录。
+
+建议对象：`customs_clearance_result`
+
+| 字段 | 说明 |
+|---|---|
+| `id` | 结果事实长 ID |
+| `declarationBatchId` | 所属正式申报批次 |
+| `resultType` | `INSPECTION`、`SUPPLEMENT_REQUIRED`、`RELEASED`、`DETAINED`、`OTHER` |
+| `resultStatus` | `OPEN`、`RESOLVED`、`CANCELLED` |
+| `customsEntryNo` | 报关单号快照，必须与批次一致 |
+| `occurredAt` | 海关事实发生时间 |
+| `recordedAt/recordedBy` | 平台录入时间和操作人 |
+| `resolution` | 处理结果、补资料说明或扣货原因 |
+| `evidenceFileId` | 可选结果凭证，文件由 File 保存，归属由 Firstleg 校验 |
+| `previousResultId` | 更正或追加结果的前序事实，不能原地覆盖 |
+
+结果门禁：
+
+- `INSPECTION` 和 `SUPPLEMENT_REQUIRED` 未解决时，客户看到处理中/待补资料，平台不能显示放行。
+- `RELEASED` 只表示海关放行事实，不自动写入送港、进港或实际开航。
+- `DETAINED` 进入扣货/异常处理，保留原因和凭证，不自动删除报关文件。
+- `OTHER` 必须有说明，不能用空状态吞掉未知海关结果。
+- 只有平台授权人员可以新增或更正结果；客户只能读取自身可见的结果和凭证。
+
+建议平台接口：
+
+- `GET /api/platform/v1/customs/loading-plans/declaration-batches/{batchId}/results`
+- `POST /api/platform/v1/customs/loading-plans/declaration-batches/{batchId}/results`
+- `POST /api/platform/v1/customs/loading-plans/clearance-results/{resultId}/resolve`
+- `GET /api/merchant/v1/customs/orders/{orderId}/clearance-results`
+
+## 四、三端交互
+
+| 参与方 | 可以做什么 | 不可以做什么 |
+|---|---|---|
+| 客户 | 上传/替换自身退税资料；查看并确认或打回整份回执；查看自身批次、报关单号、海关结果和凭证 | 不能查看同柜其他客户；不能提交正式申报；不能录入放行/扣货 |
+| 平台报关人员 | 核对资料和回执；发送报关行；创建/提交正式申报批次；回填报关单号；录入和解决海关结果 | 不能用客户确认代替正式申报；不能用完税文件代替放行结果 |
+| 报关行 | 线下处理申报并返回回执、报关单号和海关结果文件 | 不直接调用客户接口；所有回执和结果由平台留痕上传 |
+| PDA/运输 | PDA 产出 `LOADED`；运输处理待发区、送港、进港、甩柜、改配和实际开航 | 不创建报关批次，不修改报关结果，不因甩柜重置资料或确认 |
+
+## 五、状态投影
+
+平台柜级状态继续保留当前四态，用新增投影补充信息：
+
+| 现有状态 | 新增投影 | 客户文案 |
+|---|---|---|
+| `WAITING_CUSTOMER_DOCUMENTS` | 无有效批次 | 待上传退税报关资料 |
+| `READY_TO_START` | 可开始报关 | 资料已齐，等待平台发送报关行 |
+| `DECLARING` | 回执确认中/已发送报关行/正式申报中 | 报关处理中 |
+| `COMPLETED` | 完税文件齐全，正式申报或结果可能仍未关闭 | 报关文件已完成，等待海关结果（如有） |
+
+运输投影单独读取待发区和船期对象；甩柜只更新原柜船名、航次和时间历史，不变更批次、资料、回执、结果或客户确认。
+
+## 六、最小验收矩阵
+
+1. 未全部客户确认时创建/提交正式批次返回业务冲突，数据零漂移。
+2. 同一幂等键重放返回同一批次；换参数返回冲突。
+3. 提交后资料范围、回执和客户确认不可修改。
+4. 同一批次可追加查验、补资料、放行、扣货和其他结果，历史顺序稳定。
+5. 查验/补资料未解决时不显示放行；扣货保留原因和凭证。
+6. 客户 A 不能读取客户 B 的批次、结果和文件。
+7. 报关结果不推进送港、进港或实际开航；甩柜只改变原柜船期。
+8. 正式申报和结果事实可以在报关 `COMPLETED` 后继续存在，不能把 `COMPLETED` 直接当成 `RELEASED`。
+
+本设计已完成代码接入：Firstleg 建立正式申报批次和海关结果表、版本/幂等/审计门禁及平台/客户接口；Admin 页面提供创建、提交、录入和处理入口，Client 页面展示本订单可见结果。真实 HTTP 证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。当前仍保持 `COMPLETED`、海关放行、待发区和实际开航的状态边界，PDA 与船期不参与结果对象。

头程到尾程/测试环境真实联调记录-20260925.md

@@ -0,0 +1,109 @@
+# 测试环境真实联调记录（2026-09-25）
+
+本记录只登记已经在测试环境真实调用得到的结果，不把本地单测或设计文档当作真实验收证据。环境配置来自本机受控配置目录，不在文档中记录密码、Token 或 Jenkins 凭据。
+
+## 一、本批部署
+
+| 部署单元 | 测试构建 | 结果 | 说明 |
+|---|---:|---|---|
+| `backend-java` | 618 | 成功 | `firstleg` 选择构建；第 617 次因测试仍引用已删除旧方法失败，修正后第 618 次成功 |
+| `admin-web-test` | 454 | 成功 | 平台回执上传不再携带 `finalConfirmation`，上传后等待客户确认 |
+| `client-web-test` | 331 | 成功 | 客户端新增整份回执确认、打回和原因展示 |
+
+路由合同检查通过；后端报关服务定向测试和 Controller 合同测试通过，Admin 类型检查及报关组件测试通过，Client 类型检查通过。
+
+## 二、真实接口证据
+
+测试客户属于退税客户，使用已完成装柜的测试订单和柜次进行验证。测试库已补齐 `fl_customs_completion_document` 的客户确认字段，现有记录仅用于本次测试。
+
+### 1. 客户查看退税报关资料
+
+调用：
+
+```text
+GET /api/merchant/v1/customs/orders/{orderId}
+```
+
+结果：`200`。客户只能看到自身资料，返回实际箱数 `40`、退税资料 `1` 份；部分装柜的系统展示只读箱数，不做数量拆分。
+
+### 2. 平台查看柜级报关状态
+
+调用：
+
+```text
+GET /api/platform/v1/customs/loading-plans/{loadingPlanId}
+```
+
+结果：`200`。平台视角返回同一柜次实际箱数 `40`、退税资料覆盖数和回执状态；客户视角没有返回同柜其他客户资料。
+
+### 3. 平台上传报关行回执
+
+调用：
+
+```text
+POST /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/upload?expectedVersion=1
+```
+
+结果：`200`，回执状态为 `PENDING`，文件版本变为 `2`。上传回执没有自动把柜次标记为报关完成。
+
+### 4. 客户打回整份回执
+
+调用：
+
+```text
+POST /api/merchant/v1/customs/documents/{documentId}/receipt/reject
+```
+
+结果：`200`，回执状态为 `REJECTED`，打回原因被保存，柜次仍为 `DECLARING`。
+
+### 5. 客户确认整份回执
+
+调用：
+
+```text
+POST /api/merchant/v1/customs/documents/{documentId}/receipt/confirm
+```
+
+结果：`200`，回执状态为 `CONFIRMED`；该柜唯一退税客户确认后，柜次变为 `COMPLETED`。相同幂等键重放仍返回同一完成结果。
+
+### 6. 头程到报关真实 HTTP 回归
+
+在补齐国内 PDA 测试作业员凭据后，使用 `scripts/admin-test-env-acceptance.mjs --modules phase3-container-customs` 重新执行依赖闭环，覆盖客户下单、审核、入库测量、分柜/订舱、预装、PDA 装柜、`LOADED`、退税资料上传、平台回执上传、客户回执确认、自动离仓及船期查询任务。
+
+结果：报告 `baiyue-firstleg/reports/e2e-phase3-container-customs-20260925d.json`，`526/526` 断言通过，`0` 失败；其中混合柜验证确认回执后才进入 `COMPLETED`，自动离仓 `SYSTEM` 历史为 `1` 条，`OUTBOUND_CONFIRM` 船期查询任务为 `1` 条。验收脚本同步提交为 `8940c4bc`。
+
+### 7. 送港、船期与实际开航真实 HTTP 回归
+
+使用 `phase3-port-schedules,phase3-carrier-schedule-queries,phase3-outbound-dispatch` 执行送港和出仓链路，报告 `baiyue-firstleg/reports/e2e-phase3-transport-20260925.json`，`1024/1024` 通过；验证报关完成后国内离仓门禁、拖车自动完成、`OUTBOUND_CONFIRM` 任务唯一性及 `DEPARTED_WAREHOUSE` 事实。
+
+随后使用 `phase4-carrier-pickup-ready` 执行船节点人工回填，报告 `baiyue-firstleg/reports/e2e-phase4-carrier-pickup-ready-20260925.json`，`1093/1093` 通过；节点按顺序推进到 `AT_ORIGIN_PORT`、`LOADED_ON_VESSEL`、`DEPARTED_ORIGIN_PORT`，并覆盖幂等重放、旧版本冲突、旧节点回写禁止和至 `PICKUP_READY` 的连续事实。
+
+## 三、当前已确认的业务边界
+
+- 报关资料、报关行回执和客户确认流程只适用于退税货物。
+- 买单货物不创建客户报关资料、回执和客户确认流程；买单装柜、导出和运输节点独立处理。
+- 报关资料和回执均为文件；回执状态单独保存，文件版本覆盖会重新进入待确认。
+- 部分装柜只展示实际箱数，后续由线下人员处理，系统不自动分摊数量。
+- `LOADED` 后先完成报关协同；报关完成后货柜进入待发区，等待船期承运。甩柜/改配只影响运输航次，不回退或重做报关资料、回执和客户确认。
+
+## 四、F01-F24 验证状态
+
+| 范围 | 当前证据 | 状态 |
+|---|---|---|
+| F01-F13 下单、审核、到仓、测量、计费、费用确认、组托 | 本批依赖闭环已通过真实 HTTP；仍需拆分逐节点证据和异常分支 | 主链路已验收 |
+| F14-F21 分柜、订舱、拖车、拣货、装柜、`LOADED` | 本批依赖闭环已通过真实 HTTP，包含 PDA 领取、提交、审核和 `LOADED` 冻结 | 主链路已验收 |
+| F22 退税报关资料、回执、客户确认 | 已完成真实平台/客户端闭环 | 本批已验收 |
+| F23 送港、进港、甩柜、改配 | 送港/进港/出仓和船期查询主链路已通过真实 HTTP；已用测试环境真实柜次验证平台人工修改原柜船名/航次/预计时间，柜次、订舱关联和船期记录 ID 不变，修改历史新增 `UPDATE`；报关事实保持不变 | 主链路和原柜人工改船已验收；完整装柜依赖链仍需补 PDA 凭据后复跑 |
+| F24 实际开航 | 已通过人工船节点回填验证 `DEPARTED_ORIGIN_PORT`，顺序、版本和旧节点冲突均通过 | 本批已验收 |
+| F25 以后目的港清关、海外入仓、尾程 | 已有综合真实 HTTP 证据覆盖目的港节点、海外 PDA 收货、库存、排车、出库、派送和跨区回写；`admin-full-postdeploy-66c2651b.json` 相关模块失败数为 0 | 已有主链证据；仍需按具体柜次补最终业务签字和页面截图 |
+
+## 五、下一批开发入口
+
+下一批聚焦 F23 的人工改船页面回读、客户侧船期投影和异常分支；当前已确认只变更原柜船期，柜次、订舱关联和报关事实均不被覆盖。尾程节点再按 F25 以后阶段推进。每批完成后继续追加真实 HTTP 证据。
+
+## 六、2026-09-27 追加验证：F23.3 客户船期投影
+
+- 后端提交 `f1218cef` 已由 `backend-java #643` 完整测试并部署，Firstleg 独立任务 `baiyue-firstleg-firstleg #446` 成功；随后提交 `2c4f1ea3` 由 `backend-java #645` 完整测试并部署，Firstleg 独立任务 `baiyue-firstleg-firstleg #448` 成功；当前分支追加船期展示修复后，`backend-java #647` 与 `baiyue-firstleg-firstleg #450` 也已成功。
+- 修复统一订单运输摘要仍读取订舱初始船名/航次的问题：现在按客户、订舱和柜次读取最新 `fl_port_schedule` 记录，采用窗口函数选取最新观测，保留柜次与报关对象独立性。
+- 对退税柜 `TSTU0152125` 实际执行“创建原柜改配船期 → 平台容器详情与客户订单同时查询 → 版本更新恢复原船信息”。平台和客户端均读到新船名、航次及预计时间；柜号不变，恢复后两端再次一致。本轮不涉及 PDA，PDA 仍只作为 `LOADED` 上游事实。
+- 详细请求结果和断言见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`；此前客户侧单独投影证据仍保留在 `transport-projection-after-schedule-update-20260927.json`。

头程到尾程/甩柜改配接入设计.md

@@ -0,0 +1,35 @@
+# 甩柜与改配接入设计（F23.3）
+
+## 最新确认
+
+柜子不会变。平台人员在原柜子的船期信息上人工修改船名、航次和预计时间即可；保留修改前后内容、修改人和时间。报关资料、回执、完成文件和客户确认保持不变。
+
+## 操作流程
+
+1. 退税报关完成后进入待发区，等待船舶承运。
+2. 原船装满导致甩柜时，平台编辑该柜当前船期，填写实际安排的船名、航次和预计开船/到港时间。
+3. 保存后继续使用原柜次和原船期查询任务；保留已经发生的离仓、进港事实。
+4. 货柜实际随船开航后，再记录实际开航节点。修改预计船期本身不表示已经开船。
+
+不新建柜子、订舱关联或航次变更审批对象，不重建船期任务，也不重新上传或确认报关资料。此前建议的 voyage-changes 接口和批次评估状态已取消。
+
+## 现有接入入口与待验收项
+
+现有平台船期页面 `PortSchedulesView.vue` 提供编辑船名、航次、预计开船和到港时间的入口；后端 `PortScheduleService.update` 保持客户、订舱和柜次归属不变，并保存版本和修改前后历史。优先复用该能力。
+
+当前船期展示已改为读取同一客户、订舱和柜次下最新船期记录，不再固定读取订舱初始快照。平台人工改船后，客户端会同步显示最新船名、航次和预计时间。
+
+## 验收要求
+
+- 修改后柜次、柜号、装柜清单、订舱关联和船期查询任务不变。
+- 船名、航次和预计时间正确更新，平台与客户可见的当前船期一致。
+- 修改前后历史、操作人和时间可追溯，重复请求和版本冲突有明确结果。
+- 报关状态、资料、回执、完成文件、客户确认与修改前一致。
+- 已发生的物理节点不重置，预计时间调整不推进实际开航。
+
+## 真实联调证据（2026-09-27）
+
+测试柜 `TSTU0152125`（`containerBookingId=2104006600809353218`）的退税报关计划
+`2104006600830324737` 已完成资料、回执确认和完税文件闭环。平台创建一次原柜船期改配记录后，客户端同一订单立即读到新船名、航次和预计时间；柜号、柜次不变，报关状态、退税客户数量、资料/回执/完成文件 ID 与版本均未变化。随后已用版本更新恢复原船信息，恢复后的客户端投影再次一致。完整证据见
+`baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`（平台与客户端同时回读）以及
+`baiyue-firstleg/reports/transport-projection-after-schedule-update-20260927.json`。