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

本文把头程下单 F01-F24 与报关清关的客户、平台、报关行交互放在同一张图里。当前产品先覆盖国内头程到实际开航；尾程不在本轮。报关资料只适用于包含退税货物的柜，买单货物不创建客户资料协同。

一、总链路

客户下单/入仓
  → 收货、测量、计费、费用确认
  → 分柜、订舱、拖车、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 实际开航	人工录入承运船舶实际开航事实	查看海运已开航	只记录关联关系，不重做报关

甩柜只改变运输信息，不生成新柜、不重建报关任务、不把预计船期修改误写成实际开航。

五、当前接口覆盖与待补项

已落地并部署的基础闭环：客户资料上传/替换/范围调整、平台查看、冻结资料首次发送报关行并生成独立批次、回执上传及历次版本只读投影、客户整份回执确认/打回及动作历史、平台发送报关行执行、真实完税文件上传/下载、退税与买单分流、版本和幂等门禁；当前平台与客户页面均读取最新预计船期字段，实际开航字段单独保留。

仍需补齐：

报关行接收确认、回执轮次和回执下载凭证的独立对象及更细历史投影。
待发区客户/平台投影的更细页面展示和截图证据；LOADED → 报关 → 待发区 已在既有混合柜报告中通过，平台与客户改船后的当前船期双端回读已验收。

正式申报批次和海关结果已在本轮实现并通过真实 HTTP：平台创建/提交批次、录入查验、查询并处理结果，客户按自身订单查询结果；证据见 baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json。

报关专项真实 HTTP 证据、构建号和当前 PDA 边界见报关代码开发交接清单、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 的独立批次、报关单号和海关结果设计见正式申报与海关结果接入设计；该设计不改变现有两份文件闭环，也不把结果事实写入船期或 PDA 状态。

7.4 KiB Raw Permalink Blame History Unescape Escape