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

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

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

一、阶段边界

头程下单
  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 四个状态；客户资料根记录挂在柜级报关聚合下，不能表达“同柜多个客户各自有独立案例和轮次”。

目标至少需要以下关系：

物理货柜
  ├─ 最终实装快照
  ├─ 客户报关案例 × 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 到目的港清关的接口衔接点。