# 头程节点与报关清关交互矩阵

> 本文把头程下单 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 状态。