html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Test #1

Merged
admin merged 256 commits from test into main 2026-09-28 16:01:16 +08:00
Conversation 0 Commits 256 Files Changed 1486
+364 -58
29 changed files with 364 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit a4c9ca162a - Show all commits
README.md
+4 -8
View File
@@ -18,17 +18,12 @@
### 当前流程入口（收尾变更只看这里）
- [头程到尾程流程节点梳理](头程到尾程流程节点梳理.md)：三大业务块、主流程、客户进度/后台节点/真实明细三层映射，以及 F01～F40 关键节点总表。
- [头程到尾程分阶段流程](头程到尾程分阶段流程/README.md)：把三大块拆成六个详细阶段，按阶段查字段、页面操作、权限和异常。
- [国内货柜履约 README](国内货柜履约/README.md)：货柜范围和装柜完成后的报关协同、送港并行关系。
- [报关资料与船期价格接入梳理](国内货柜履约/报关资料与船期价格接入梳理.md)：报关资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格专题。
- [头程到尾程当前维护入口](头程到尾程/README.md)：集中进入总览、六个阶段、货柜入口、报关专题，以及页面和需求参考。
### 历史与参考（保留，不作为日常流程入口）
- [头程下单到尾程出库全流程操作手册](头程下单到尾程出库全流程操作手册.md)
- [头程下单到尾程出库现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)
- [头程到尾程 AI 流程优化上下文包](头程到尾程AI流程优化上下文包.md)
- [头程下单到尾程出库流程易用性与数据流转优化方案](头程下单到尾程出库流程易用性与数据流转优化方案.md)
- [头程到尾程历史文档](归档/头程到尾程/README.md)：全流程操作手册、旧现状全景、AI 上下文和易用性方案。
- [国内货柜履约历史记录](国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收矩阵、审计和旧确认材料。
以上文件继续保留，分别用于历史现状、操作说明和方案追溯；开发规划、进度、门禁和验收记录也按业务域保留，不再与当前节点总表同步改写。
- [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。
@@ -66,6 +61,7 @@
## 维护规则
- 新文档按业务域归档，不新增以开发批次编号命名的目录、文件、标题、任务或范围标签。
- 已完成开发阶段的流程手册、规划、进度和验收资料统一放入 `归档/`；后续流程变更只从[头程到尾程当前维护入口](头程到尾程/README.md)进入。
- 当前交付范围始终按端到端全流程理解；业务域目录只用于检索和职责归属，不用于排除上下游流程。
- 范围、字段或流程冲突时，按“当前对话确认 > 正式契约与确认记录 > 项目指引与代码 > 原型 > 历史记录”判断。
- 新增或修改业务能力时，同步更新业务域 README、跨端契约、接口、权限、SQL、测试和验收入口。
国内货柜履约/README.md
+8 -14
View File
@@ -1,6 +1,6 @@
# 国内货柜履约
本目录负责国内分柜、订舱、拖车、拣货、装柜、装柜后的报关协同、送港、进港和甩柜事实。主流程已经开发完成，当前只在这里查找收尾变更涉及的货柜节点；开发规划和验收记录保留用于追溯，不作为当前流程入口。
本目录负责国内分柜、订舱、拖车、拣货、装柜、装柜后的报关协同、送港、进港和甩柜事实。整体货柜流程进入收尾，**报关协同代码尚未完成**；当前只在这里查找流程节点，报关开发请转到交接清单。
## 当前流程入口
@@ -8,6 +8,7 @@
- [阶段三：国内货柜履约与出仓](../头程到尾程分阶段流程/阶段三-国内货柜履约与出仓.md)：分柜、订舱、拖车、拣货、装柜、报关和国内出仓的详细操作。
- [阶段四：海运、目的港与尾程计划](../头程到尾程分阶段流程/阶段四-海运目的港与尾程计划.md)：实际开船后的海运、目的港和尾程计划衔接。
- [报关资料与船期价格接入梳理](报关资料与船期价格接入梳理.md)：报关资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格专题。
- [报关代码开发交接清单](../头程到尾程/报关代码开发交接清单.md)：报关代码当前未完成时，下一开发对话使用的范围和验收条件。
## 货柜关键节点
@@ -24,18 +25,11 @@
费用确认属于头程下单块的并行事项，不阻断排柜、拣货或装柜；装柜完成时仍未确认的当前有效费用按系统默认确认并保留来源。这个默认确认只适用于费用，不适用于报关资料的客户确认。
## 当前变更相关文档
- [国内货柜履约需求确认表](国内货柜履约需求确认表.md)：需要核对已确认的业务口径时使用。
- [国内货柜履约页面与原型清单](国内货柜履约页面与原型清单.md)：需要核对页面范围或原型入口时使用。
## 冻结记录（只用于追溯）
- [国内货柜履约开发规划](国内货柜履约开发规划.md)
- [国内货柜履约开发进度表](国内货柜履约开发进度表.md)
- [国内货柜履约需求确认表](国内货柜履约需求确认表.md)
- [国内货柜履约开工门禁](国内货柜履约开工门禁.md)
- [国内货柜履约页面与原型清单](国内货柜履约页面与原型清单.md)
- [国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)
- [历史审计报告（2026-08-08）](国内货柜履约闭环审计报告-2026-08-08.md)
- [历史产品确认表（2026-08-08）](国内货柜履约装柜闭环产品确认表-2026-08-08.md)
- [历史开发前确认单（2026-08-08）](国内货柜履约装柜闭环开发前确认单-2026-08-08.md)
- [历史 Wave1 开发任务卡（2026-08-09）](国内货柜履约Wave1开发任务卡-2026-08-09.md)
- [国内货柜履约开发进度表（Excel）](虫虫出海国内货柜履约开发进度表.xlsx)
以上记录不删除、不回写。若要调整当前流程，修改总览、对应阶段或报关专题，并同步实际接口/权限契约；不要为同一节点再次改动冻结记录。
开发规划、进度、门禁、验收矩阵、审计、产品确认和旧任务卡已移入[国内货柜履约历史记录](归档/README.md)。这些文件不删除、不回写；若要调整当前流程，修改总览、对应阶段或报关专题，并同步实际接口/权限契约。
国内货柜履约/国内货柜履约需求确认表.md
+4 -3
View File
@@ -8,7 +8,7 @@
- 状态统一使用：待确认、确认中、已确认、已取消。
- 阻断级别统一使用：开工阻断、模块阻断、非阻断。
- 结论确认后同步更新 `国内货柜履约开发规划.md`、`国内货柜履约开发进度表.md` 和受影响的页面原型。
- 结论确认后同步更新 `归档/国内货柜履约开发规划.md`、`归档/国内货柜履约开发进度表.md` 和受影响的页面原型。
- 未确认事项只能作为候选方案，不能直接写成固定开发或验收承诺。
## 二、确认事项
@@ -47,7 +47,7 @@
| P3-PDA-D08 | 2026-08-09 | 同类型证据允许多张并采用追加记录；错误/重复照片不硬删除，只作废 | 每条照片独立保存；作废记录原因、操作人和时间，历史可追溯 |
| P3-PDA-D09 | 2026-08-09 | 空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效且未作废的照片，可多张；带锁码照同时要求锁码文本 | 服务端完整性门禁按“每类至少一张有效记录”校验，不能按单槽位替换模型实现 |
> 验收映射：当前自动化已真实覆盖五类证据上传、同类型多图追加、跨类型/伪造 `fileId` 拒绝、锁码文本门禁和错图作废审计；设备在线、持久化草稿批量提交仍按[验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)保留 coverageGap。
> 验收映射：当前自动化已真实覆盖五类证据上传、同类型多图追加、跨类型/伪造 `fileId` 拒绝、锁码文本门禁和错图作废审计；设备在线、持久化草稿批量提交仍按[验收任务拆分与待确认清单](归档/国内货柜履约验收任务拆分与待确认清单.md)保留 coverageGap。
## 三、已确认架构决策
@@ -78,7 +78,7 @@
### 5.2 会议输入
- 本确认表中的 P3-Q1～P3-Q17。
- `国内货柜履约开发规划.md` 的流程、状态、里程碑和任务骨架。
- `归档/国内货柜履约开发规划.md` 的流程、状态、里程碑和任务骨架。
- `国内货柜履约页面与原型清单.md` 中已有参考原型和待补页面。
- 入库测量与计费输出契约、目标 PDA 信息、文件存储能力及报关/港务协作现状。
@@ -97,3 +97,4 @@
- 国内货柜履约范围内/范围外清单及跨期依赖。
- 仍有风险的事项、责任人和完成日期。
- 已允许进入 T02 契约设计与任务拆分；未决技术项只阻断其对应实现，不反向阻断整期已确认范围。
国内货柜履约/归档/README.md
+18
View File
@@ -0,0 +1,18 @@
# 国内货柜履约历史记录
本目录保存国内货柜履约的开发规划、进度、开工门禁、验收、审计和旧确认材料。内容不删除，也不作为当前流程入口；当前规则以[国内货柜履约 README](../README.md)、[头程到尾程流程节点梳理](../../头程到尾程流程节点梳理.md)和[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md)为准。
## 文件
- [开发规划](国内货柜履约开发规划.md)
- [开发进度表](国内货柜履约开发进度表.md)
- [开发进度表（Excel）](虫虫出海国内货柜履约开发进度表.xlsx)
- [需求确认表之外的开工门禁与验收记录](国内货柜履约开工门禁.md)
- [验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)
- [货柜管理全链验收矩阵](货柜管理全链验收矩阵-2026-08-13.md)
- [货柜履约原型字段验收矩阵](货柜履约原型字段验收矩阵-2026-08-17.md)
- [闭环审计报告](国内货柜履约闭环审计报告-2026-08-08.md)
- [装柜闭环产品确认表](国内货柜履约装柜闭环产品确认表-2026-08-08.md)
- [装柜闭环开发前确认单](国内货柜履约装柜闭环开发前确认单-2026-08-08.md)
- [Wave1 开发任务卡](国内货柜履约Wave1开发任务卡-2026-08-09.md)
国内货柜履约/国内货柜履约Wave1开发任务卡-2026-08-09.md → 国内货柜履约/归档/国内货柜履约Wave1开发任务卡-2026-08-09.md
+2 -1
View File
@@ -1,6 +1,6 @@
# 国内货柜履约 Wave 1 开发任务卡
> **历史版本声明（2026-09-24）**：本文是旧版低风险任务拆分，不能直接作为当前开发排期或门禁依据。当前流程改为“柜前资料预收集 → 物理装柜 `LOADED` → 按最终实装清单正式报关 → 有效放行回执后 `DEPARTED_WAREHOUSE`”，费用确认不阻断装柜，装柜完成时按已装范围对当前有效已发布费用版本执行系统默认确认。当前开发范围以 [头程到尾程流程节点梳理（重构版）](../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](报关资料与船期价格接入梳理.md) 和最新需求确认表为准。
> **历史版本声明（2026-09-24）**：本文是旧版低风险任务拆分，不能直接作为当前开发排期或门禁依据。当前流程改为“柜前资料预收集 → 物理装柜 `LOADED` → 按最终实装清单正式报关 → 有效放行回执后 `DEPARTED_WAREHOUSE`”，费用确认不阻断装柜，装柜完成时按已装范围对当前有效已发布费用版本执行系统默认确认。当前开发范围以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和最新需求确认表为准。
整理日期：2026-08-09
用途：产品确认后用于研发排期和任务分派。
@@ -55,3 +55,4 @@
- 允许无拣货、缺照片或缺锁码进入 `LOADED`。
- 国内 Admin/PDA 手工推进 `DELIVERED`。
- 在产品未确认前固化部分拣货拆单和一单多柜聚合规则。
国内货柜履约/国内货柜履约开发规划.md → 国内货柜履约/归档/国内货柜履约开发规划.md
+4 -2
View File
@@ -2,8 +2,8 @@
> 创建日期：2026-07-28
> 状态：已进入分模块开发规划
> 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；当前以 `LOADED` 作为物理装柜节点，报关线和送港线在装柜后并行，实际开船后进入海运节点。
> 前置阶段：[订单与客户文档](../订单与客户/README.md) · [入库测量与计费文档](../入库测量与计费/README.md)
> 流程依据：[出仓流程](../参考资料/出仓流程.png)中的头程物流“03 出仓”；当前以 `LOADED` 作为物理装柜节点，报关线和送港线在装柜后并行，实际开船后进入海运节点。
> 前置阶段：[订单与客户文档](../../订单与客户/README.md) · [入库测量与计费文档](../../入库测量与计费/README.md)
> 2026-08-10 产品确认版；2026-09-24 按最新流程更正：国内货柜履约不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 仅校验真实柜号、PDA 拣货、数量守恒和五类证据；装柜后报关线按“客户资料→报关行回执→客户确认/打回重做→所有客户通过→整柜正式申报→查验/放行”推进，送港线独立记录离仓、进港、甩柜和改配，实际开船才进入海运。费用确认不阻断排柜和装柜；装柜完成后对已装范围的当前有效已发布费用版本执行系统默认确认，保留客户/系统来源。`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。
@@ -323,3 +323,5 @@ PDA 拣货 → 装柜并上传五类证据
4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。
5. 使用脱敏数据演练拼柜、一单多柜、未装数量生成子订单、错拣、补件和改船；`LOADED` 后不演练在线冲正。
6. 在真实 PDA 和代表性仓库网络环境中完成联调、验收和灰度发布。
国内货柜履约/国内货柜履约开发进度表.md → 国内货柜履约/归档/国内货柜履约开发进度表.md
+2 -1
View File
@@ -102,7 +102,7 @@
## 七、未确认事项（需求确认进度）
当前 13 项主确认事项均已有产品最终结论；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。完整结论统一维护在 [国内货柜履约需求确认表](国内货柜履约需求确认表.md)。
当前 13 项主确认事项均已有产品最终结论；P3-Q4 已确认采用 uni-app、在线更新与 Android 广播扫描。完整结论统一维护在 [国内货柜履约需求确认表](../国内货柜履约需求确认表.md)。
验收拆分已建立：PDA 进入任务、拣货幂等/版本冲突、五类证据真实上传、多图追加和锁码门禁进入自动化；真机在线、设备草稿批量提交、证据作废、设备与权限留存等仍保留 coverageGap，详见[国内货柜履约验收任务拆分与待确认清单](国内货柜履约验收任务拆分与待确认清单.md)。
@@ -152,3 +152,4 @@
3. 完成 PDA 真机广播扫码、在线草稿、五类证据拍照、多图追加和作废验收。
4. 收口 T11 客户端国内货柜履约页面及客户可见性、安全边界。
5. 复跑国内货柜履约定向和默认全量真实 HTTP 验收，完成发布记录后再评估国内货柜履约完成状态。
国内货柜履约/国内货柜履约开工门禁.md → 国内货柜履约/归档/国内货柜履约开工门禁.md
+1
View File
@@ -28,3 +28,4 @@
1. 先读 `README.md`、`国内货柜履约需求确认表.md` 和本文件，确认任务属于已确认范围。
2. 再进入目标应用或服务的 `AGENTS.md`，按本地模块入口实现。
3. 发现新的产品决策或门禁变化时，先更新确认表与本文，再更新受影响模块指引；不要将短期进度、联调故障或环境地址写回模块规则。
国内货柜履约/国内货柜履约装柜闭环产品确认表-2026-08-08.md → 国内货柜履约/归档/国内货柜履约装柜闭环产品确认表-2026-08-08.md
+2 -1
View File
@@ -1,6 +1,6 @@
# 国内货柜履约装柜闭环产品确认表
> **历史版本声明（2026-09-24）**：本文仅保留 2026-08-08 的原始讨论记录，其中“装柜完成即结束”和报关/离仓关系等内容已被当前流程替代。当前规则以 [头程到尾程流程节点梳理（重构版）](../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](报关资料与船期价格接入梳理.md) 和最新需求确认表为准：`LOADED` 只表示物理装柜完成；正式报关在装柜完成后按最终实装清单执行，放行回执参与 `DEPARTED_WAREHOUSE` 离仓门禁。
> **历史版本声明（2026-09-24）**：本文仅保留 2026-08-08 的原始讨论记录，其中“装柜完成即结束”和报关/离仓关系等内容已被当前流程替代。当前规则以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和最新需求确认表为准：`LOADED` 只表示物理装柜完成；正式报关在装柜完成后按最终实装清单执行，放行回执参与 `DEPARTED_WAREHOUSE` 离仓门禁。
> 确认方式：产品只需在“产品确认”一列填写“同意”，或写明修改后的规则。
> 会议目标：本表确认后直接进入开发，不再补完整高保真原型。
@@ -66,3 +66,4 @@
| 本次明确不做的内容 | |
| 产品确认人 | |
| 确认日期 | |
国内货柜履约/国内货柜履约装柜闭环开发前确认单-2026-08-08.md → 国内货柜履约/归档/国内货柜履约装柜闭环开发前确认单-2026-08-08.md
+2 -1
View File
@@ -1,6 +1,6 @@
# 国内货柜履约装柜闭环开发前确认单
> **历史版本声明（2026-09-24）**：本文是旧版“以 `LOADED` 作为国内履约终点”的开发前确认材料，旧规则已被本轮新流程替代。当前按三大业务块梳理；`LOADED` 只表示物理装柜完成，正式报关在装柜完成后按最终实装清单执行，放行回执、订舱、拖车和异常门禁用于推进 `DEPARTED_WAREHOUSE`。费用确认不阻断装柜，当前有效已发布费用版本在 `LOADED` 时按已装载范围默认确认。开发以 [头程到尾程流程节点梳理（重构版）](../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](报关资料与船期价格接入梳理.md) 和当前确认记录为准。
> **历史版本声明（2026-09-24）**：本文是旧版“以 `LOADED` 作为国内履约终点”的开发前确认材料，旧规则已被本轮新流程替代。当前按三大业务块梳理；`LOADED` 只表示物理装柜完成，正式报关在装柜完成后按最终实装清单执行，放行回执、订舱、拖车和异常门禁用于推进 `DEPARTED_WAREHOUSE`。费用确认不阻断装柜，当前有效已发布费用版本在 `LOADED` 时按已装载范围默认确认。开发以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和当前确认记录为准。
> 整理日期：2026-08-08
> 用途：产品、业务、仓库、研发在直接开发前确认最小闭环细节
@@ -146,3 +146,4 @@ DELIVERED / 海外仓已收货
2. 更新 `国内货柜履约需求确认表.md` 中对应的 P3-Q2/P3-Q4/P3-Q5/P3-Q6/P3-Q10/P3-Q11/P3-Q12。
3. 明确是否允许按“服务端门禁 -> PDA -> Admin -> 联调验收”的顺序直接开发。
4. 将本清单作为接口、页面和测试验收的共同依据。
国内货柜履约/国内货柜履约闭环审计报告-2026-08-08.md → 国内货柜履约/归档/国内货柜履约闭环审计报告-2026-08-08.md
+2 -1
View File
@@ -1,6 +1,6 @@
# 虫虫出海国内货柜履约闭环审计报告
> **历史记录声明（2026-09-24）**：本文记录的是 2026-08-08 的旧口径和旧审计结论，不再作为当前流程或开发门禁依据。当前统一采用三大业务块和“装柜完成后正式报关”的新流程：`LOADED` 只确认物理装柜完成；装柜完成后按最终实装清单正式报送，取得有效回执/放行结果后，结合订舱、拖车和异常门禁推进 `DEPARTED_WAREHOUSE`。费用确认不阻断装柜，装柜完成时对当前有效已发布版本按已装载范围默认确认。当前规则以 [头程到尾程流程节点梳理（重构版）](../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](报关资料与船期价格接入梳理.md) 和本轮确认记录为准。
> **历史记录声明（2026-09-24）**：本文记录的是 2026-08-08 的旧口径和旧审计结论，不再作为当前流程或开发门禁依据。当前统一采用三大业务块和“装柜完成后正式报关”的新流程：`LOADED` 只确认物理装柜完成；装柜完成后按最终实装清单正式报送，取得有效回执/放行结果后，结合订舱、拖车和异常门禁推进 `DEPARTED_WAREHOUSE`。费用确认不阻断装柜，装柜完成时对当前有效已发布版本按已装载范围默认确认。当前规则以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../报关资料与船期价格接入梳理.md) 和本轮确认记录为准。
> 审计日期：2026-08-08
> 审计范围：入库测量与计费终点→智能排柜→订舱→拖车→PDA 拣货→装柜/柜封证据→`LOADED`/装柜完成
@@ -241,3 +241,4 @@ PDA 已有调用拣货/证据/装柜接口的适配代码，但当前仍存在
> **国内货柜履约已确认复用现有订单列表承载全部主状态，不新建出仓单，国内终点为 `LOADED`/装柜完成；已完成排柜/预装/PDA 拣货/装柜清单子链路，订舱和拖车 API 可用。但订单国内货柜履约统一编排、五张装柜照片与锁码文本硬门禁、报关协同、冲正、Client 协同和 PDA 真机仍未闭环，且国内手工推进 `DELIVERED` 的现有能力必须整改，当前不具备整期验收条件。**
因此，现阶段不应标记“国内货柜履约完成”，应标记为“**子能力已实现，闭环整改中**”。
国内货柜履约/国内货柜履约验收任务拆分与待确认清单.md → 国内货柜履约/归档/国内货柜履约验收任务拆分与待确认清单.md
+1
View File
@@ -33,3 +33,4 @@
4. `P3-ACCEPT-PDA-RELEASE`：按既定 uni-app 在线更新安排完成发布与真机验收。
每个任务完成后，必须把真实请求、响应状态、业务码、`requestId/traceId` 写入报告，并删除对应 coverageGap；不得以 mock 或数据库直写替代接口验收。
国内货柜履约/虫虫出海国内货柜履约开发进度表.xlsx → 国内货柜履约/归档/虫虫出海国内货柜履约开发进度表.xlsx
View File
国内货柜履约/货柜履约原型字段验收矩阵-2026-08-17.md → 国内货柜履约/归档/货柜履约原型字段验收矩阵-2026-08-17.md
+1
View File
@@ -42,3 +42,4 @@
- `phase3-container-loading` 对 ACTIVE 货柜、预装清单和完成装柜清单执行字段断言。
- `ocean-bookings`、`phase3-port-schedules`、`truck-appointments`、`phase3-customs`、`phase3-outbound-dispatch` 在既有本轮资源响应上执行字段断言，不增加历史查询或伪造回退。
- 默认 Admin 全量入口已包含上述生产模块；真实 HTTP 仅在测试环境重新部署且当前对话明确授权后执行。
国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md → 国内货柜履约/归档/货柜管理全链验收矩阵-2026-08-13.md
+1
View File
@@ -219,3 +219,4 @@
| 全量编排 | 默认入口先运行 `phase3-container-loading` 完成“模拟柜新增 -> 同仓同渠道排货 -> 首次 link -> PDA”，再由证据、finalize、出仓模块沿本轮 marker 的稳定 ID 继续；禁止历史数据和 mock 回退 | Node 入口合同已锁定，待默认全量 HTTP 验证 |
离线合同：`container-simulation-association-contract.test.mjs` 锁定跨层契约及全量顺序；`phase3-producer-chain-contract.test.mjs`、`phase3-order-splitting-contract.test.mjs`、`ocean-booking-channel-contract.test.mjs` 锁定生产者只使用 DRAFT/RELEASED、需求关联且不在订舱阶段自动建柜。
国内货柜履约/报关资料与船期价格接入梳理.md
+13 -15
View File
@@ -1,6 +1,6 @@
# 报关资料与船期价格接入梳理
> **当前用途：报关与船期价格专题参考。** 主流程和节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准；本文保留资料字段、回执轮次、价格口径和接口查找信息，供收尾变更定位。
> **当前用途：报关与船期价格专题参考。** 报关流程已经确认，代码已进入第一批开发；开发交接看[报关代码开发交接清单](../头程到尾程/报关代码开发交接清单.md)。主流程和节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准；本文保留资料字段、回执轮次、价格口径和接口查找信息。
>
> 文中“目标、实施顺序、进入条件、待确认事项”等段落属于原评审记录。开发已经完成后，不再据此重新拆开发任务；若与当前确认不一致，以总览和最新业务确认修正对应专题段落。
@@ -12,10 +12,10 @@
国内货柜履约的物理装柜节点为 `LOADED`。`LOADED` 后同时启动两条独立流程：
1. **报关线**：通知报关行，收集每个客户资料，发送报关行，接收报关行回执并发客户确认；客户认为不正确时打回、重新上传、重新发送并生成新回执，循环至柜内所有客户均确认；全部确认后，再将整柜资料提交报关行确认，由报关行正式申报，记录查验、不查验放行或其他海关结果。
1. **报关线**：仅对退税客户通知报关行，收集退税客户资料，发送报关行，接收报关行回执并发客户确认；客户认为不正确时打回、重新上传、重新发送并生成新回执，循环至柜内退税客户均确认；全部确认后，再将退税申报资料提交报关行确认，由报关行正式申报，记录查验、不查验放行或其他海关结果。买单货物不进入这条资料和回执流程。
2. **送港线**：安排拖车、从仓库发运、送港、进港；港口容量不足时记录甩柜和改配船次。送港线可以早于或晚于报关线完成，`PORT_RECEIVED` 不等于海运中，只有船舶真实开航后才进入海运节点。
两条线互不作为 `LOADED` 的前置，也不要求一条线完成后才能启动另一条线。首期不对接海关单一窗口或报关代理系统，由授权人员人工录入报关行回执、客户确认和海关结果。
两条线互不作为 `LOADED` 的前置，也不要求一条线完成后才能启动另一条线。首期不对接海关单一窗口或报关代理系统：报关行回执以文件上传为主，正式申报由授权人员人工提交，客户确认和海关结果由平台人工记录。
费用确认是并行事实，不阻断排柜、预装、PDA 或装柜。装柜完成后，对应已实装范围若客户仍未确认当前有效且已发布费用版本，系统记录“系统默认确认（装柜完成）”；不伪造客户点击，保留 `SYSTEM_AUTO_AT_LOADED` 来源、费用版本、柜次/入仓码、时间和幂等标识。没有有效费用版本时不得生成零额或伪造确认，须保留费用异常待办。
@@ -61,13 +61,13 @@
### 1. 客户报关案例与资料包
报关资料主流程在 `LOADED` 后启动。每个客户/入仓码在本柜建立一个 `customerCustomsCase`，再挂载稳定的 `packageId` 和文件版本。案例至少记录：订单/子订单、入仓码或入仓明细、实际装载数量、资料清单版本、每个清单项的文件版本、报关行发送时间、回执版本、客户确认/打回人和时间、打回原因、当前 `roundNo`、客户可见范围和审计记录。
报关资料主流程在 `LOADED` 后启动。每个客户/入仓码在本柜建立一个 `customerCustomsCase`，再挂载稳定的 `packageId` 和文件版本。案例至少记录：订单/子订单、入仓码或入仓明细、实际装箱数展示、资料清单版本、每个清单项的文件版本、报关行发送时间、回执文件版本、客户确认/打回人和时间、打回原因、当前 `roundNo`、客户可见范围和审计记录。
资料包不能只关联整票入仓码。已确认支持一单多柜、拆批和父订单—子订单关系，因此每个关联项还要保存实际装载数量、单位、子订单/装柜明细引用和快照版本。换柜、拆柜或部分装柜时，只重算受影响客户案例，不能静默沿用旧回执轮次。
资料包不能只关联整票入仓码。已确认支持一单多柜、拆批和父订单—子订单关系，因此每个关联项保存客户、订单、入仓码和装柜明细引用；部分装柜只展示本柜实际箱数并标记线下处理，不在系统内自动做数量分摊。换柜时保留新旧柜关联，受影响案例不能静默沿用旧回执轮次。
### 2. 实际装柜绑定快照
资料包与 loadingPlanId、containerBookingId 的关系应通过绑定记录表达，而不是覆盖原资料包。绑定记录至少保存实际装柜明细、数量/UOM、客户、订单、入仓码、柜次和绑定版本。`LOADED` 后开始本轮报关时冻结该快照；换柜、拆柜或部分装柜必须使受影响案例的资料绑定和回执轮次失效并生成新版本，不能静默沿用旧覆盖结论。
资料包与 loadingPlanId、containerBookingId 的关系应通过绑定记录表达，而不是覆盖原资料包。绑定记录至少保存实际装柜明细引用、实装箱数、客户、订单、入仓码、柜次和绑定版本。`LOADED` 后开始本轮报关时冻结该范围；部分装柜只生成箱数展示和线下处理标记，换柜才需要使受影响案例的资料绑定和回执轮次失效并生成新版本。
### 3. 申报组与柜级总览
@@ -81,9 +81,9 @@
| 柜型 | `LOADED` 前 | `LOADED` 后报关线 | 完成条件与开船影响 |
|---|---|---|---|
| 全买单 | 装柜物理门禁独立判断 | 按最终实装买单明细建立客户案例；平台可执行 `complete-all-buy` 生成资料，但仍需将报关行回执发给对应客户确认；全部客户确认后提交整柜资料 | 客户确认完成后才允许整柜正式提交；正式申报后的查验/放行单独记录，不能把二次确认直接当成海关放行 |
| 退税柜 | 装柜物理门禁独立判断 | 对每个参与入仓码收集/补件，发送报关行，逐份接收回执并让对应客户确认；打回则重做当前案例 | 所有客户案例确认后才允许整柜正式提交；正式申报后的查验/放行单独记录 |
| 混合柜 | 装柜物理门禁独立判断 | 买单行和退税行分别建立客户案例并完成回执确认；同柜批次统一保存成员快照 | 两类成员全部确认后才允许整柜正式提交；不得把买单导出明细冒充客户确认或海关放行 |
| 全买单 | 装柜物理门禁独立判断 | 不进入本报关资料、报关行回执和客户确认流程；继续按买单装柜、导出和运输节点处理 | 不创建退税报关案例，不以报关资料或回执作为门禁 |
| 退税柜 | 装柜物理门禁独立判断 | 对每个参与入仓码收集/补件，发送报关行，逐份接收回执并让对应客户确认；打回则重做当前案例 | 所有退税客户案例确认后才允许整柜正式提交；正式申报后的查验/放行单独记录 |
| 混合柜 | 装柜物理门禁独立判断 | 仅退税行建立报关资料和回执确认案例；买单行不进入该流程，仍保留买单装柜和导出事实 | 仅退税客户案例全部确认后才允许提交退税申报批次；不得把买单明细冒充报关确认 |
同一客户多个入仓码可以共享其授权资料；跨客户物理拼柜不等于允许跨客户正式合报。跨客户合并仍默认禁止，必须有独立授权和客户可见隔离契约。
@@ -98,7 +98,7 @@
| 送港/船期事实 | PORT_DELIVERY_PENDING、DEPARTED_WAREHOUSE、IN_TRANSIT_TO_PORT、PORT_RECEIVED、ROLLED_OVER、VESSEL_DEPARTED | 与报关案例独立；进港和甩柜不等于海运中，只有真实开船才进入海运节点 |
| 装柜门禁 | PASS/BLOCKED | 只判断是否满足 LOADED 的已确认前置 |
上述是建议投影，稳定编码、退回/重开规则和责任人必须在开发前确认。当前四态不能直接承担新流程；收敛时应明确旧状态的映射和删除时点，不保留双协议。
上述是首期状态投影。回执首期以文件为主、客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；实际开航首期人工录入，甩柜/改配生成新航次并重新评估申报批次。其余稳定编码、退回/重开规则和责任人仍需在开发前确认。当前四态不能直接承担新流程；收敛时应明确旧状态的映射和删除时点，不保留双协议。
物理 `LOADED` 门禁必须明确校验以下事实：
@@ -150,12 +150,10 @@
| 问题 | 阻断范围 | 需要形成的结论 |
|---|---|---|
| 同一入仓明细部分装到多个柜的数量和单位 | 绑定快照、门禁 | 子订单/装柜明细引用和数量分摊规则 |
| 跨客户合并正式报关单是否允许 | 申报组、权限、客户隔离 | 默认禁止或授权合并的完整契约 |
| 资料清单具体项目、条件规则和版本生效方式 | 清单、审核、补件 | 首版人工维护清单及版本负责人 |
| 报关行回执字段、客户确认/打回原因和回执轮次 | 客户案例、整柜提交 | 回执版本、roundNo、确认人、打回重做规则 |
| 客户确认/打回原因和回执轮次 | 客户案例、整柜提交 | 回执版本、roundNo、确认人、打回重做规则 |
| 海关查验、不查验放行、扣货/补件等正式结果 | 整柜申报批次、客户展示 | 结果类型、凭证、来源、客户可见范围和责任人 |
| 送港、进港、甩柜、改配船次和实际开船事件 | 送港线、海运节点 | 事实字段、重试规则、客户通知和船次历史 |
| 送港、进港、甩柜、改配船次和实际开船事件 | 送港线、海运节点 | 事实字段、重试规则、客户通知和船次历史；首期人工录入实际开航，改配生成新航次并重新评估申报批次 |
| 价格比较、导出、报价有效期和金额变化提示 | 客户报价页、下单 | 统一币种/税模式/附加费和失效处理 |
## 最低验收矩阵
@@ -177,4 +175,4 @@
- 平台整柜报关：apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue、api/platformContainerCustoms.ts。
- 后端报关：baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/customs/container/、[customs-v1.yaml](C:/Users/BY-OY/Desktop/code/chongchong-global/baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml:1)、phase3-container-customs-schema.sql。
- 报价：apps/client-web/src/modules/first-leg/api/firstLeg.ts、apps/admin-web/src/modules/fba-pricing/carrier-rates/、[fba-pricing-v1.yaml](C:/Users/BY-OY/Desktop/code/chongchong-global/baiyue-firstleg/firstleg/src/main/resources/openapi/fba-pricing-v1.yaml:130)。
- 国内边界、状态和门禁：[国内货柜履约 README](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/README.md:3)、[国内货柜履约开发规划](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/国内货柜履约开发规划.md:166)、[国内货柜履约需求确认表](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/国内货柜履约需求确认表.md:24)。
- 国内边界、状态和门禁：[国内货柜履约 README](README.md:3)、[国内货柜履约开发规划（归档）](归档/国内货柜履约开发规划.md:166)、[国内货柜履约需求确认表](国内货柜履约需求确认表.md:24)。
头程到尾程/README.md
+29
View File
@@ -0,0 +1,29 @@
# 头程到尾程当前维护入口
这里集中列出后续流程变更需要查找和修改的文档。整体流程基线已确认，除报关协同代码外进入收尾；日常只从本目录进入，历史开发材料统一放在[文档归档](../归档/README.md)。
## 当前流程文档
| 用途 | 文档 | 修改什么 |
|---|---|---|
| 总览与节点 | [头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md) | 三大业务块、客户进度、后台节点、真实明细和 F01-F40 关系 |
| 分段流程 | [头程到尾程分阶段流程](../头程到尾程分阶段流程/README.md) | 六个阶段的字段、页面操作、权限、状态和异常 |
| 货柜入口 | [国内货柜履约 README](../国内货柜履约/README.md) | 分柜、装柜、报关协同、送港和进港的货柜范围 |
| 报关与船期专题 | [报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md) | 客户资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格 |
| 报关开发交接 | [报关代码开发交接清单](报关代码开发交接清单.md) | 当前未完成的报关代码范围、完成条件和开发入口 |
| 第一阶段冻结矩阵 | [头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md) | F01-F24 节点、报关与送港并行关系、当前实现缺口和开发前确认项 |
## 变更查找
- **改客户看到的主节点或三大块关系**：先改总览，再检查对应阶段文档。
- **改头程下单**：查阶段一、阶段二；费用确认仍是并行事项，不阻断排柜和装柜。
- **改海运（货柜）**：查阶段三、阶段四和报关专题；`LOADED` 后报关协同、送港运输两条线并行，实际开船后才进入海运节点。
- **安排报关开发**：只看[报关代码开发交接清单](报关代码开发交接清单.md)，流程规则回看报关专题，不再从归档的开发规划开始。
- **改尾程入库和派送**：查阶段五、阶段六。
- **改页面范围或已确认需求**：查[页面与原型清单](../国内货柜履约/国内货柜履约页面与原型清单.md)和[需求确认表](../国内货柜履约/国内货柜履约需求确认表.md)。
## 归档位置
- [头程到尾程历史文档](../归档/头程到尾程/README.md)：全流程手册、旧现状全景、AI 上下文、易用性方案。
- [国内货柜履约历史记录](../国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收、审计和旧确认材料。
- 跨区域认证、权限、统一订单状态、船节点、部署和数据库等正式契约继续留在原业务目录，不归入流程历史归档。
头程到尾程/头程至实际开船节点冻结矩阵与缺口清单.md
+164
View File
@@ -0,0 +1,164 @@
# 头程至实际开船节点冻结矩阵与缺口清单
本文按当前确认结果冻结第一阶段范围：从头程下单开始，完成国内履约、报关协同、送港运输，并记录承运船舶实际开航。尾程入库、派送和签收不在本阶段实现。流程基线同时采用《报关代码开发交接清单》和《头程到尾程流程节点梳理》；原型只用于页面字段和承载方式参考。
## 一、阶段边界
```text
头程下单
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` 四个状态；客户资料根记录挂在柜级报关聚合下，不能表达“同柜多个客户各自有独立案例和轮次”。
目标至少需要以下关系：
```text
物理货柜
├─ 最终实装快照
├─ 客户报关案例 × 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 到目的港清关的接口衔接点。
头程到尾程/报关代码开发交接清单.md
+68
View File
@@ -0,0 +1,68 @@
# 报关代码开发交接清单
> **当前状态：流程已确认，报关协同代码进入第一批开发。** 本文是开发交接入口，已落地内容不代表完整报关协同或真实验收通过。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。
> **本轮补充确认：** 首期报关行回执以文件为主，客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；实际开航首期人工录入，甩柜/改配生成新航次并重新评估关联申报批次。
## 一、必须实现的报关流程
从装柜完成（`LOADED`）开始，按柜内客户分别处理：
1. 按最终实装清单建立客户报关案例和资料包。
2. 收集客户上传、替换或补充的资料，发送给报关行。
3. 接收报关行回执并发给对应客户确认。
4. 客户打回时，只重开对应客户当前轮次，重新上传、重新发送并生成新回执；保留每轮资料、回执、确认人、时间和打回原因。
5. 柜内所有客户确认后，提交整柜资料给报关行确认，由报关行正式申报。
6. 分别记录海关查验、不查验放行、扣货或其他正式结果。
报关行回执、客户确认、整柜正式申报和海关放行是不同节点。客户确认不能自动完成，费用的系统默认确认也不能代替报关资料确认。
## 二、必须保持的并行关系
- `LOADED` 之后，报关协同线和送港运输线分别启动，互不作为对方的前置。
- 报关资料未确认只阻断报关线的整柜正式提交，不阻断送港。
- 送港、进港、甩柜和改配独立留痕；只有承运船舶实际开航后才进入海运节点。
- `LOADED` 只表示物理装柜完成，不表示报关完成、已放行或已开船。
## 三、当前代码交接重点
### 已落地的第一批能力
- 平台端和客户端都能展示当前视角的实际装箱数；部分装柜只展示箱数，后续由线下人员处理，系统不做数量分摊。
- 报关资料和报关行回执继续按文件上传、覆盖、版本和下载处理；页面文案已区分“回执”和“完成”，避免把上传回执误认为客户确认或正式申报。
- 报关资料链路仅适用于退税货物；买单货物不创建客户报关资料、回执和客户确认流程。
- 回执上传后进入待确认状态；客户端已提供整份回执确认和打回入口，打回原因回传后再由平台重新上传回执。
- 后端 OpenAPI、平台/客户端模型和基础测试已同步实际箱数字段；管理员端、客户端类型检查及相关组件测试已通过。
这批能力支撑 F21 的实装范围展示和退税客户 F22 的文件承载、回执确认入口；客户案例、回执轮次、整柜正式申报和海关结果仍未完成。
当前实现仍是旧的柜级报关状态和离仓门禁，不能直接证明已经具备以下能力：
- 每客户报关案例和实际装柜快照；
- 报关行回执轮次和客户确认/打回重做；
- 柜内所有客户确认后的整柜正式提交；
- 查验、不查验放行和其他海关结果的独立记录；
- 报关线与送港线的独立状态、幂等、权限和审计。
开发时不要只增加页面节点文案，也不要把旧的 `COMPLETED` 直接当成客户确认、正式申报或海关放行。
## 四、开发入口
先核对当前代码和 OpenAPI，再决定复用或调整现有接口：
- 客户端报关资料：`apps/client-web/src/modules/first-leg/`，重点查看 `routes.ts`、`CustomsDocumentsDialog.vue` 和 `api/customs.ts`。
- 平台整柜报关：`apps/admin-web/src/modules/container-loading/`，重点查看 `ContainerCustomsPanel.vue` 和 `api/platformContainerCustoms.ts`。
- 后端报关：`baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/customs/container/`。
- 接口与数据：`baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml`、报关相关数据库脚本和 IAM 权限初始化。
具体类名、接口路径、状态编码和数据库字段以当前代码核对结果为准；本清单只定义业务完成条件，不预先替换技术实现。
## 五、完成条件
- 客户 A 与客户 B 的资料、回执和确认严格隔离。
- 每个客户都能完成“资料上传 → 报关行回执 → 客户确认”，打回后产生新轮次且不覆盖历史。
- 未全部确认时不能提交整柜正式报关；全部确认后才能进入报关行正式申报。
- 海关查验、不查验放行、扣货和其他结果可分别记录并回显。
- 报关线和送港线可以先后完成，任一线的完成事件不能伪造另一条线的节点。
- 重复请求、版本冲突、换柜、部分装柜箱数展示和权限越界都有明确结果和审计记录；部分装柜的后续处理在线下完成。
- 完成代码联调后，再回写 F22 和阶段三的实现状态；真实验收通过前不要标记“报关完成”。
头程到尾程分阶段流程/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 头程到尾程分阶段流程
本目录是端到端流程的分段查找入口。主流程已经开发完成，当前只用于收尾变更：总览和节点关系看[《头程到尾程流程节点梳理》](../头程到尾程流程节点梳理.md)，字段、页面操作、权限和异常细节在对应阶段文件维护。
本目录是端到端流程的分段查找入口。流程基线已确认，当前用于收尾变更；其中阶段三的报关协同代码尚未完成。总览和节点关系看[《头程到尾程流程节点梳理》](../头程到尾程流程节点梳理.md)，字段、页面操作、权限和异常细节在对应阶段文件维护。
## 三大业务块与六个分段
头程到尾程分阶段流程/阶段三-国内货柜履约与出仓.md
+2 -1
View File
@@ -420,7 +420,7 @@ WAIT_SPLIT 入库单/已封托托盘
- `docs/国内货柜履约/README.md`
- `docs/国内货柜履约/国内货柜履约页面与原型清单.md`
- `docs/头程下单到尾程出库现状流程全景清单.md`
- `docs/归档/头程到尾程/头程下单到尾程出库现状流程全景清单.md`
- `docs/统一订单主状态与操作契约.md`
- `apps/admin-web/src/modules/container-loading/`
- `apps/admin-web/src/modules/loading-lists/`
@@ -434,3 +434,4 @@ WAIT_SPLIT 入库单/已封托托盘
- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/SmartLoadingService.java`
- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/LoadingPickService.java`
- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/outbound/dispatch/service/OutboundDispatchService.java`
头程到尾程分阶段流程/阶段二-国内到仓测量计费与组托.md
+2 -1
View File
@@ -574,7 +574,7 @@ Firstleg 正式入库单 + 稳定箱码
## 16. 事实来源
- `docs/头程下单到尾程出库现状流程全景清单.md`
- `docs/归档/头程到尾程/头程下单到尾程出库现状流程全景清单.md`
- `docs/入库测量与计费/README.md`
- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
- `docs/统一订单主状态与操作契约.md`
@@ -590,3 +590,4 @@ Firstleg 正式入库单 + 稳定箱码
- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/InitialInboundPricingService.java`
- `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/DropshipPalletizationService.java`
- `baiyue-firstleg/firstleg/src/main/resources/openapi/dropship-palletization-v1.yaml`
头程到尾程流程节点梳理.md
+2 -2
View File
@@ -1,6 +1,6 @@
# 头程到尾程流程节点梳理
> **当前用途：收尾变更的流程入口。** 主流程已经开发完成，本文件只保留三大业务块、关键节点和节点之间的关系，便于查找和修改。开发规划、进度、门禁和历史评审不在这里继续维护。
> **当前用途：收尾变更的流程入口。** 整体流程基线已确认，报关协同代码尚未完成；本文件只保留三大业务块、关键节点和节点之间的关系，便于查找和修改。报关开发请看[报关代码开发交接清单](头程到尾程/报关代码开发交接清单.md)，历史开发规划、进度、门禁和评审不在这里继续维护。
>
> **维护原则：** 客户看到的是进度投影，后台看到的是业务对象节点，明细节点记录真实操作和结果。三者使用同一组业务事实，不另建一套客户状态。
@@ -43,7 +43,7 @@
| F11-F13 | 头程下单 | 费用待确认、待组托、待分柜 | 费用版本、确认记录、托盘 | 计费、推送、客户确认、组托/封托 | 费用不阻断主链；装柜完成时未确认的当前有效费用按系统默认确认留痕 |
| F14-F20 | 海运（货柜） | 待分柜、订舱中、装柜准备/进行中 | 柜次、装柜计划、拖车任务、拣货任务 | 分柜、订舱、排车、拣货、拍照、铅封、数量核对 | 通过装柜门禁后才能完成装柜 |
| F21 | 海运（货柜） | 国内已装柜 | 装柜任务已完成 | 实际柜号、实装数量、装柜证据确认 | 产生 `LOADED`；同时启动报关协同和送港运输两条线 |
| F22 | 海运（货柜） | 报关确认中、待补资料、已提交报关 | 客户报关案例、报关批次 | 收集资料、发报关行、接收回执、客户确认或打回、重新上传和重发 | 柜内所有客户确认后，才能提交整柜资料并正式申报；客户确认不等于海关放行 |
| F22 | 海运（货柜） | 报关确认中、待补资料、已提交报关 | 客户报关案例、报关批次 | 收集资料、发报关行、接收回执、客户确认或打回、重新上传和重发 | **流程已确认、代码未完成**；柜内所有客户确认后，才能提交整柜资料并正式申报；客户确认不等于海关放行 |
| F23 | 海运（货柜） | 送港中、已进港、待开船、已甩柜 | 送港/拖车任务、港口和船次事实 | 离仓、送港、进港、甩柜、改配 | 与报关线独立，先后顺序不固定；进港不等于开船 |
| F24 | 海运（货柜） | 海运中 | 船次实际状态 | 承运船舶实际开航、船期回写 | 只有实际开航后进入海运节点 |
| F25-F27 | 海运（货柜） | 目的港处理中、待海外接柜 | 目的港清关/提柜、尾程订单、入仓计划 | 清关、提柜、创建尾程计划 | 形成海外接柜输入，不等于已经入库 |
归档/README.md
+10
View File
@@ -0,0 +1,10 @@
# 文档归档
这里保存已经完成开发阶段、当前不作为日常流程入口的历史文档。归档只改变文件位置，不删除内容；需要追溯旧决策、旧验收或旧开发计划时再进入对应子目录。
## 归档目录
- [头程到尾程](头程到尾程/README.md)：全流程操作手册、旧现状全景、AI 上下文和易用性方案。
- [国内货柜履约归档](../国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收矩阵、审计和旧确认材料。
当前流程只从 [头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md) 开始查找。
归档/头程到尾程/README.md
+11
View File
@@ -0,0 +1,11 @@
# 头程到尾程历史文档
本目录只保留历史操作说明、旧版现状盘点和流程优化材料。它们不再作为当前流程或开发计划入口；当前节点关系以[头程到尾程流程节点梳理](../../头程到尾程流程节点梳理.md)为准，分段细节见[头程到尾程分阶段流程](../../头程到尾程分阶段流程/README.md)。
## 文件
- [全流程操作手册](头程下单到尾程出库全流程操作手册.md)
- [现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)
- [AI 流程优化上下文包](头程到尾程AI流程优化上下文包.md)
- [易用性与数据流转优化方案](头程下单到尾程出库流程易用性与数据流转优化方案.md)
头程下单到尾程出库全流程操作手册.md → 归档/头程到尾程/头程下单到尾程出库全流程操作手册.md
+3 -2
View File
@@ -5,7 +5,7 @@
> 当前口径：以现行服务端模块指引、页面入口和代码状态机为准。历史设计与当前实现冲突的地方集中列在第 11 节，旧文档不能直接作为操作依据。
> 不在主链内展开：换标、仓储转运、货物废弃、退货换标、异常退回、客户回访、海外采购和本土散板；这些能力在第 9 节说明如何接入出库。
> 当前流程基线：见[《头程到尾程流程节点梳理（重构版）》](头程到尾程流程节点梳理.md)。[《头程下单到尾程出库现状流程全景清单》](头程下单到尾程出库现状流程全景清单.md)仅保留旧版 AS-IS 证据；本文侧重一票主链如何按最新报关/送港并行流程实际操作。
> 当前流程基线：见[《头程到尾程流程节点梳理（重构版）》](../../头程到尾程流程节点梳理.md)。[《头程下单到尾程出库现状流程全景清单》](头程下单到尾程出库现状流程全景清单.md)仅保留旧版 AS-IS 证据；本文侧重一票主链如何按最新报关/送港并行流程实际操作。
## 1. 一张图看完整主链
@@ -525,7 +525,7 @@ OVERSEAS：
- `docs/业务快速索引.md`
- `docs/订单与客户/订单与客户头程订单闭环设计.md`
- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
- `docs/国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md`
- `docs/国内货柜履约/归档/货柜管理全链验收矩阵-2026-08-13.md`
- `docs/海外仓业务/README.md`
- `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
- `baiyue-firstleg/order/AGENTS.md`
@@ -535,3 +535,4 @@ OVERSEAS：
- `apps/pda-overseas-uniapp/AGENTS.md`
本文用于统一业务操作和评审口径；接口字段、权限码、并发版本和错误码仍以对应 Controller、DTO、OpenAPI 与服务端状态机为最终依据。
头程下单到尾程出库流程易用性与数据流转优化方案.md → 归档/头程到尾程/头程下单到尾程出库流程易用性与数据流转优化方案.md
+1
View File
@@ -461,3 +461,4 @@ P0 不改变核心状态机，主要是聚合查询、反馈和导航，风险
5. 国内/海外 PDA 接入稳定错误原因、恢复动作和操作回执。
6. 完成 P0 人工验收和埋点基线后，再做表单向导、自动带出和批量体验。
7. 最后基于真实操作数据决定 P2 的智能推荐和 SLA 预警，不凭主观增加自动化。
头程下单到尾程出库现状流程全景清单.md → 归档/头程到尾程/头程下单到尾程出库现状流程全景清单.md
+3 -2
View File
@@ -1,6 +1,6 @@
# 头程下单到尾程出库现状流程全景清单
> **历史现状声明（2026-09-24）**：本文记录旧版 AS-IS 盘点，报关/送港的单线门禁、柜前资料和“四步证据”等内容不再作为当前业务依据。当前流程以 [头程到尾程流程节点梳理（重构版）](头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](国内货柜履约/报关资料与船期价格接入梳理.md) 和最新需求确认表为准：`LOADED` 后报关线与送港线并行，客户回执确认完成后整柜正式申报，甩柜独立记录，实际开船才进入海运节点。
> **历史现状声明（2026-09-24）**：本文记录旧版 AS-IS 盘点，报关/送港的单线门禁、柜前资料和“四步证据”等内容不再作为当前业务依据。当前流程以 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md)、[报关资料与船期价格接入梳理](../../国内货柜履约/报关资料与船期价格接入梳理.md) 和最新需求确认表为准：`LOADED` 后报关线与送港线并行，客户回执确认完成后整柜正式申报，甩柜独立记录，实际开船才进入海运节点。
> 文档性质：现状流程盘点（AS-IS），先描述现在业务怎么走，不在本文讨论页面改版或技术优化。
> 覆盖起点：企业具备下单资格。
@@ -570,7 +570,7 @@ INBOUND_COMPLETED
- `docs/入库测量与计费/README.md`
- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
- `docs/国内货柜履约/README.md`
- `docs/国内货柜履约/货柜管理全链验收矩阵-2026-08-13.md`
- `docs/国内货柜履约/归档/货柜管理全链验收矩阵-2026-08-13.md`
- `docs/海外仓业务/README.md`
- `docs/海外仓业务/虫虫出海全流程人工验收手册.md`
- `baiyue-firstleg/order/AGENTS.md`
@@ -581,3 +581,4 @@ INBOUND_COMPLETED
- `apps/client-web/AGENTS.md`
- `apps/pda-uniapp/AGENTS.md`
- `apps/pda-overseas-uniapp/AGENTS.md`
头程到尾程AI流程优化上下文包.md → 归档/头程到尾程/头程到尾程AI流程优化上下文包.md
+3 -2
View File
@@ -1,6 +1,6 @@
# 头程到尾程 AI 流程优化上下文包
> **规则基线声明（2026-09-24）**：本文中的旧状态表和阶段合同可能保留历史口径，不能覆盖当前流程。当前分析必须先采用 [头程到尾程流程节点梳理（重构版）](头程到尾程流程节点梳理.md) 和 [报关资料与船期价格接入梳理](国内货柜履约/报关资料与船期价格接入梳理.md)：`LOADED` 后报关线、送港线并行，客户逐轮确认后整柜正式申报，送港可甩柜，实际开船后才进入海运节点。
> **规则基线声明（2026-09-24）**：本文中的旧状态表和阶段合同可能保留历史口径，不能覆盖当前流程。当前分析必须先采用 [头程到尾程流程节点梳理（重构版）](../../头程到尾程流程节点梳理.md) 和 [报关资料与船期价格接入梳理](../../国内货柜履约/报关资料与船期价格接入梳理.md)：`LOADED` 后报关线、送港线并行，客户逐轮确认后整柜正式申报，送港可甩柜，实际开船后才进入海运节点。
> 用途：给 AI、产品、业务和技术提供同一份优化输入规范。本文不替代六阶段现状文档，也不直接改变状态机；它定义分析顺序、术语、证据、指标、输出格式和实施门禁，防止 AI 只根据局部页面提出脱离业务事实的建议。
@@ -36,7 +36,7 @@
优化分析的默认入口：
- 总览：[分阶段流程目录](头程到尾程分阶段流程/README.md)
- 总览：[分阶段流程目录](../../头程到尾程分阶段流程/README.md)
- 操作：[全流程操作手册](头程下单到尾程出库全流程操作手册.md)
- 现状：[现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)
- 方案：[易用性与数据流转优化方案](头程下单到尾程出库流程易用性与数据流转优化方案.md)
@@ -296,3 +296,4 @@ AI 应优先：复用服务端权威动作与门禁、减少重复输入、显
10. 国内离仓、海外入仓、海外出库和最终签收的客户可见进度语义。
每项决定应记录：结论、负责人、确认日期、影响阶段、是否改变接口/状态/权限，以及需要更新的文档。未决定项保持“待确认”，不能由 AI 默认选择。