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

头程至实际开船节点冻结矩阵与缺口清单

本文按当前确认结果冻结第一阶段范围：从头程下单开始，完成国内履约、报关协同、送港运输，并记录承运船舶实际开航。尾程入库、派送和签收不在本阶段实现。流程基线同时采用《报关代码开发交接清单》和《头程到尾程流程节点梳理》；原型只用于页面字段和承载方式参考。

一、阶段边界

头程下单
  F01-F13：下单、审核、到仓、测量、计费、费用确认、组托、待分柜
国内货柜履约
  F14-F21：分柜、订舱、拖车、拣货、装柜、LOADED
报关完成后进入待发区
  F22：报关协同
  F23：待发区、送港、进港、甩柜、改配
海运起点
  F24：承运船舶实际开航

本阶段的终点是实际开航事实，不是“报关完成”、国内离仓、目的港清关或海外入仓。LOADED 只表示物理装柜完成；报关完成是进入待发区的前置条件，待发区和船期节点分别保存，不能把其中一条线的结果写成另一条线的结果。

二、F01-F24 节点冻结矩阵

节点	客户可见进度	后台业务对象	必须形成的真实事实	当前状态	本阶段缺口
F01-F07	待下单、审核中、已审核	企业、订单、审核任务	提交、补件、审核、入仓单生成	已有主链	按现有订单契约回归，不在本轮重做
F08-F10	待到仓、测量中、待确认	入仓单、测量记录	收货、扫码、称重、测量、审核	已有主链	只核对是否能稳定产出排柜事实
F11-F13	费用待确认、待组托、待分柜	费用版本、确认记录、托盘	计费推送、客户确认、组托/封托	已确认并行规则	保证费用默认确认不能冒充报关确认
F14-F20	待分柜、订舱中、装柜中	柜次、装柜计划、拖车、PDA 任务	分柜、订舱、排车、拣货、照片、铅封、数量核对	主链已有	核对真实柜号、订舱和装柜快照能否冻结
F21	国内已装柜	装柜计划、物理货柜、装柜证据	实际柜号、实装箱数、装柜证据、LOADED	已有	报关案例按最终实装范围建立；部分装柜只显示已装箱数并标记线下处理，不在系统内自动分摊
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	已甩柜、等待改船后承运	船期记录修改历史	甩柜原因、发生时间、修改前后船名/航次/船期、处理人	已实现并通过测试环境真实 HTTP；平台与客户端最新船期投影一致	继续补页面截图和更复杂异常分支；柜次、订舱关联和报关事实不变
F24	海运中	船次实际节点	承运船舶、航次、实际开航时间、来源/凭证	基础已有	只允许实际开航事实推进海运节点

三、当前实现与目标的主要断点

1. 报关数据模型已支持客户范围，发送批次仍需独立建模

当前 fl_customs_container 仍是柜级状态聚合，但客户资料通过客户和入仓码范围隔离，真实验收已覆盖同柜多客户和混合柜。正式申报批次、海关结果事实、首次发送报关行批次和客户确认动作历史已经独立落地；尚未独立建模的是报关行接收回执、回执轮次和更细的客户案例聚合。

目标至少需要以下关系：

物理货柜
  ├─ 最终实装快照
  ├─ 客户报关案例 × N
  │    ├─ 客户资料包与版本
  │    ├─ 报关行回执轮次 × N
  │    └─ 客户确认/打回记录与动作历史 × N
  ├─ 整柜正式申报批次
  └─ 海关结果事实 × N

2. 当前“报关完成”仍需与正式申报、海关结果区分

现有完成动作是平台上传每份完成文件，或对全买单柜直接确认；客户确认和完成文件链路已有真实验收。正式申报批次、报关单号和海关结果已经分别记录，仍不能把其中任何一个状态直接当成海关放行或所有运输事实。

3. 报关完成与待发区的门禁关系

当前 CustomsDispatchGateContributor 要求 fl_customs_container.status=COMPLETED 才通过国内出仓门禁，CustomsAutoDispatchCoordinator 也在报关完成后自动尝试确认出仓。按最新口径，这不是冲突：报关完成后货柜进入待发区，待发区是送港运输真正开始前的状态门槛；甩柜只在船期运输层处理，不触碰报关事实。

需要重新定义：

• 待发区门禁先检查报关 COMPLETED，再叠加装柜、PDA、订舱、证据等运输条件；通过后只推进到 WAITING_FOR_LOADING。
• 报关线单独保存客户确认、整柜申报和海关结果；这些事实不会被船期修改覆盖。
• 报关完成事件只能推进待发区，不得自动伪造送港、进港或开船事实。
• 实际开航只能由船次实际节点推进。

4. 客户端基础报关协同闭环已完成

当前客户端 CustomsDocumentsView.vue 提供独立报关资料列表和待办入口，CustomsDocumentsDialog.vue 已支持上传、替换、调整关联入仓码、查看和下载报关行回执/真实报关完税文件、确认整份回执和填写原因打回，并展示回执历次上传版本及确认/打回动作历史；仍缺少：

• 客户案例的进度和通知。

5. 平台端基础整柜协同闭环已完成

当前 ContainerCustomsPanel.vue 已展示退税资料、首次发送报关行批次、回执/完成文件、客户范围、确认状态、回执历次上传版本和确认/打回动作历史，并支持正式申报批次和海关结果基础操作；仍缺少：

• 按客户查看案例和实际装柜覆盖；
• 报关行接收回执和回执轮次管理；
• 更细的查验、扣货、补资料和其他结果凭证历史。

四、接口、权限、审计和测试缺口

接口与数据库

• OpenAPI 不能继续只暴露旧的四态 ContainerView。
• 需要继续补充报关行接收回执、回执轮次、下载凭证及更复杂结果凭证的查询/命令契约；资料包、首次发送批次、回执版本和确认动作只读历史、整柜申报和海关结果基础契约已落地。
• 文件仍由 File 服务保存，但每个文件必须绑定业务类型、客户案例/申报批次、版本和覆盖范围。
• 每个写命令都要带版本和幂等键；重放同参数返回原结果，不同参数返回冲突。
• 换柜时需要保留新旧柜关联；部分装柜只记录已装箱数和线下处理标记，不在系统内自动做数量分摊或覆盖旧资料。

权限

至少区分：

• 客户上传、替换、补件、确认、打回；
• 平台客服接收、核对、退回补件；
• 平台报关操作员发送报关行、上传回执、提交正式申报；
• 平台人员录入查验、放行、扣货及其他海关结果；
• 客户和平台各自的只读下载权限。

审计

需要保留客户范围、资料版本、回执轮次、确认人、打回原因、提交批次、报关单号、结果凭证和操作时间。客户 A 的动作不能出现在客户 B 的案例中；柜级汇总可以看到客户名和业务编号，但客户端只能看到自身范围。

测试

最小验收矩阵至少覆盖：

1. 单客户和多客户同柜。
2. 一客户打回时其他客户继续保持已确认。
3. 同一请求重放、同幂等键换参数、版本冲突。
4. 未全部客户确认时正式提交被拒绝。
5. 正式申报、查验、不查验放行、扣货和其他结果分别显示。
6. 报关完成后货柜进入待发区，等待船舶承运。
7. 甩柜改配在原柜上人工修改船信息并留痕，柜子和报关事实不变。
8. 只有实际开航事实推进 F24。
9. 客户越权读取同柜其他客户资料被拒绝。
10. 部分装柜能显示实际箱数并留下线下处理标记；换柜不能直接覆盖原案例和历史回执。

五、开发前仍需业务确认

以下问题中，前四项已经由《报关代码开发交接清单》和《头程到尾程流程节点梳理》冻结，本轮又补充冻结了文件形态、部分装柜展示、回执确认、首期申报和实际开航/改配处理方式；表格后的内容仍需业务补充，不能由代码现状推断。

已冻结的业务规则

规则	冻结口径	依据
资料提交时点	LOADED 后按最终实装快照建立客户案例并进入本轮报关	交接清单“一、必须实现的报关流程”；总流程 F21/F22
同柜客户边界	一个客户案例只属于一个客户；同一客户多个入仓码可以共享资料，但跨客户正式合报默认禁止	报关专题“申报组与柜级总览”“买单、退税和混合柜完成条件”
回执与客户确认	首期以报关行回执文件为主，客户对整份回执确认；回执上传不等于客户确认	本轮业务确认
资料与部分装柜	报关资料、报关行回执都按文件保存；部分装柜只展示箱数，线下人员处理后续，不做系统内数量分摊	本轮业务确认
首期正式申报	由平台授权人员人工提交并回填报关行确认和海关结果	本轮业务确认；报关专题状态约定
报关与待发区关系	报关完成后货柜才能进入待发区；待发区是等待船舶承运的运输状态，报关和船期事实分开保存	本轮业务确认
海运起点与改配	首期人工录入实际开航；甩柜/改配只变更船期/航次，不重新处理已完成报关资料；只有实际开航事实推进 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 待发区；甩柜/改配只改变运输航次，不改变报关事实。
• 客户确认、报关行回执、整柜正式申报、海关放行、离仓、进港、甩柜和实际开航都是独立事实。
• 先完成节点矩阵、对象关系、状态投影、门禁和验收缺口确认，再进入代码设计。
• 尾程 F25-F40 暂不纳入本阶段实现，但必须保留 F24 到目的港清关的接口衔接点。