docs: align firstleg release contracts and add sailing plans
This commit is contained in:
+52
-43
@@ -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 到目的港清关的接口衔接点。
|
||||
|
||||
Reference in New Issue
Block a user