优化

2026-09-24 13:43:53 +08:00
parent 6116ad61e1
commit d8be2ccdef
19 changed files with 801 additions and 220 deletions
@@ -2,12 +2,12 @@

 > 创建日期：2026-07-28  
 > 状态：已进入分模块开发规划  
-> 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；用户已于 2026-08-08 确认国内国内货柜履约以 `LOADED`/装柜完成为阶段终点
+> 流程依据：[出仓流程](参考资料/出仓流程.png)中的头程物流“03 出仓”；当前以 `LOADED` 作为物理装柜节点，报关线和送港线在装柜后并行，实际开船后进入海运节点。
 > 前置阶段：[订单与客户文档](../订单与客户/README.md) · [入库测量与计费文档](../入库测量与计费/README.md)

-> 2026-08-10 产品确认版：国内货柜履约不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 硬门禁为订舱完成、拖车完成、报关放行回执、PDA 拣货完成和五类证据完整；`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。
+> 2026-08-10 产品确认版；2026-09-24 按最新流程更正：国内货柜履约不新建独立出仓单；支持一单多柜、一个柜拼多个订单，采用“父订单→子订单→柜次”关系，已装载数量形成子订单，未装载数量自动生成后续子订单。`LOADED` 仅校验真实柜号、PDA 拣货、数量守恒和五类证据；装柜后报关线按“客户资料→报关行回执→客户确认/打回重做→所有客户通过→整柜正式申报→查验/放行”推进，送港线独立记录离仓、进港、甩柜和改配，实际开船才进入海运。费用确认不阻断排柜和装柜；装柜完成后对已装范围的当前有效已发布费用版本执行系统默认确认，保留客户/系统来源。`LOADED` 后错误线下人工处理。五类证据各至少 1 张有效照片，同类型多张追加，PDA 仅现场拍照，后台操作员和理货员可人工上传，照片无限期保留且客户不可见。

-> 当前范围更正：原 `P3-PORT-01`、六家船公司官网查询及 `CarrierScheduleQuery` 是柜子确认离开国内仓库后的业务，整体重新归入海外仓业务。国内货柜履约仅保存订舱与出仓前所需的船名航次、港口和 ETD/ETA 等资料，不建设或验收出仓后的定时节点查询。
+> 当前范围更正：国内货柜履约保留 `DEPARTED_WAREHOUSE`、`PORT_RECEIVED`、`ROLLED_OVER` 和实际开船前的船次/港口事实；承运船舶真实 `VESSEL_DEPARTED` 后的六家船公司官网查询、`CarrierScheduleQuery` 和定时节点查询归入海外仓业务。国内侧不以预计 ETD 提前展示海运中。

 > 主体模型与硬约束：国内货柜履约只实现“平台—客户”两级，业务 `tenant_id > 0` / `tenantId` 当前表示客户 ID；`tenant_id=0` 是平台身份、平台 RBAC 和平台公共仓储资源技术作用域，客户往来单位、订单、文件和费用归属客户 `tenant_id>0`。禁止新增租户主表、租户选择器、客户所属租户配置、租户切换、租户级 RBAC 或租户级配置，禁止把现有 `tenant_id` 改义为上级租户 ID；历史类名、路径和字段继续兼容。

@@ -20,16 +20,15 @@
 ```text
 智能排柜 → 订舱 → 预约拖车
    ↓
-PDA 拣货 → 装柜并上传货柜/铅封照片
+PDA 拣货 → 装柜并上传五类证据
    ↓
-客户上传报关资料 → 平台整理提交报关代理 → 上传回执供客户下载
-    ↓
-维护订舱与出仓前所需的船名航次、港口和预计时间
-    ↓
-国内国内货柜履约完成：`LOADED`/装柜完成
+`LOADED`/装柜完成
+    ├─ 报关：通知报关行 → 客户资料 → 报关行回执 → 客户确认/打回重做
+    │          → 所有客户通过 → 整柜正式申报 → 查验/放行
+    └─ 送港：拖车 → 离仓 → 送港/进港 → 甩柜/改配（如发生）→ 实际开船
 ```

-国内货柜履约完成标准是同一订单/柜次已完成排柜和 PDA 拣货，空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效照片已真实上传，锁码文本已保存，服务端门禁通过并将订单推进为 `LOADED`/装柜完成。`DELIVERED`/派送完成必须等货物到达海外仓后由海外仓可信回传推进，不是国内国内货柜履约人工操作。
+国内货柜履约的装柜完成标准是同一订单/柜次已完成排柜和 PDA 拣货，空仓、半仓、满仓、锁仓、带锁码照五类证据各至少 1 张有效照片已真实上传，锁码文本已保存，数量守恒且服务端门禁通过后推进为 `LOADED`/装柜完成。`LOADED` 后报关线和送港线同时启动；客户确认不阻断送港，进港不代表报关完成，容量不足记录甩柜；只有承运船舶实际开航后才进入海运节点。`DELIVERED`/派送完成必须等货物到达海外仓后由海外仓可信回传推进，不是国内国内货柜履约人工操作。

 ### 原型动作覆盖

@@ -42,8 +41,8 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 | 5. 拍货柜及铅封照上传 | 装柜及柜封证据 | P3-LOAD-01、P3-LOAD-02 | 已确认五类证据各至少 1 张有效照片、同类型可多张，锁码文本必填 |
 | 6. 客户上传报关资料 | 报关资料协同 | P3-CUS-01 | 已覆盖 |
 | 7. 整理给到报关代理报关 | 报关资料协同 | P3-CLEAR-01 | 已覆盖 |
-| 8. 回执上传到系统供客户下载 | 报关回执与客户下载 | P3-CLEAR-01、P3-CUS-02 | 已覆盖，首版由授权人员人工上传放行回执 |
-| 9. 出仓后查询港务/船节点 | 海外仓业务船节点定时查询 | 原 P3-PORT-01、P3-CUS-02 对应查询部分 | 已重新归入海外仓业务，不是国内货柜履约动作或验收项 |
+| 8. 回执上传并由客户确认 | 报关行回执与客户确认 | P3-CLEAR-01、P3-CUS-02 | 待补齐多轮回执、客户确认/打回和整柜正式提交 |
+| 9. 送港、甩柜与实际开船 | 送港/船次事实 | P3-TRUCK-01、P3-CUS-02 | 装柜后与报关线并行；实际开船后进入海运节点 |

 ## 二、阶段边界

@@ -54,8 +53,9 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 - 预约拖车、车辆司机、到仓装柜和离仓记录。
 - PDA 任务领取、扫码拣货、部分拣货、异常、复核和幂等提交。
 - 装柜、柜号、铅封号及货柜/铅封照片证据。
- 客户上传报关资料、平台审核补件、整理并提交报关代理。
- 报关回执上传、版本、客户可见范围和授权下载。
+- `LOADED` 后通知报关行，客户上传报关资料、平台审核补件、线下发送报关行。
+- 报关行回执上传、版本、客户确认/打回重做、客户可见范围和授权下载；所有客户确认后才提交整柜资料正式申报。
+- 装柜后送港、进港、甩柜/改配和实际开船事实。
 - 装柜完成门禁、确认、时间线和站内通知；`LOADED` 后纠错走线下人工流程。

 ### 明确不纳入国内货柜履约
@@ -65,7 +65,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 - GPS 实时跟车、电子铅封、称重设备、摄像头 OCR 和 IoT 自动采集。
 - 自动报关、关税计算、退税、完整清关业务和自动单证识别。
 - 海上运输、海外清关、目的港提柜、海外仓入库和末端派送。
- 柜子确认离开国内仓库后的 `CarrierScheduleQuery`、船公司查询、定时船节点和到港跟踪；整体归海外仓业务。
+- 承运船舶真实 `VESSEL_DEPARTED` 后的 `CarrierScheduleQuery`、船公司查询、定时船节点和海上到港跟踪；整体归海外仓业务。国内侧保留送港、进港和甩柜事实。
 - 无人工确认的全自动排柜、自动订舱和不可逆业务操作。

 ## 三、参与角色与数据边界
@@ -87,7 +87,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片

 ## 四、流程与状态设计

-原型以 1 至 9 编号表达动作顺序。产品确认后，订舱、拖车、报关放行、PDA 拣货和证据完整是进入 `LOADED` 的强制前置；智能排柜、订舱、拖车和资料整理可按子流程并行，但服务端不得绕过门禁。PDA 单柜次单作业员，不实现多人并行或任务接管。
+原图以 1 至 9 编号表达展示动作顺序。按本轮确认，费用确认不阻断排柜或装柜；`LOADED` 只校验物理装柜事实，装柜后报关线和送港线并行，客户确认不阻断送港，进港不代表报关完成，实际开船才进入海运。PDA 单柜次单作业员，不实现多人并行或任务接管。

 ### 1. 现有订单的国内货柜履约主状态

@@ -95,7 +95,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 |---|---|---|
 | `WAIT_SPLIT` | 待分柜 | 入库测量与计费已完成，等待排柜/预装 |
 | `LOADING` | 装柜中 | 预装已确认，PDA 执行拣货和装柜证据上传 |
-| `LOADED` | 装柜完成 | 订舱、拖车、报关放行回执、PDA 拣货完成，且五类证据各至少 1 张有效照片和锁码文本已通过服务端门禁 |
+| `LOADED` | 装柜完成 | 真实柜号、PDA 拣货与数量守恒、五类证据各至少 1 张有效照片和锁码文本已通过服务端门禁；装柜后同时启动报关线和送港线 |
 | `DELIVERED` | 派送完成 | 货物到达海外仓后由海外仓可信回传推进；属于国内货柜履约之后的只读状态 |

 ### 2. 子流程状态
@@ -103,8 +103,8 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 - 订舱：待订舱、订舱中、已订舱、订舱失败、已取消。
 - 拖车：待预约、已预约、车辆已到仓、装柜中、已离仓、改约、已取消。
 - 拣货：待分配、待拣货、拣货中、待复核、已完成、异常挂起、已取消。
- 报关：资料待上传、资料待审核、待补件、待提交、已提交代理、回执待上传、回执已上传、已退回、已取消；有效放行回执是 `LOADED` 硬门禁，首版由授权人员人工上传。
- 出仓前船期资料：待维护、已确认、信息变更；出仓后节点和“已开船”等运输事实归海外仓业务。
+- 报关：`LOADED` 后待通知报关、客户资料待上传/审核、已发报关行、回执待客户确认、客户已确认、客户打回待重做、所有客户已确认、整柜正式申报、查验、放行/退回；回执上传不等于客户确认，客户确认不等于海关放行。
+- 送港/船期：待送港、已离仓、送港中、已进港、甩柜/改配、待开船；只有实际 `VESSEL_DEPARTED` 后进入海运节点。

 主状态由服务端根据已确认的必要子流程推进。客户端不得通过传任意目标状态跳过拣货复核、装柜证据或已配置的装柜完成门禁。

@@ -127,10 +127,10 @@ PDA 拣货 → 装柜并上传货柜/铅封照片

 ### 3. 订舱与出仓前船期资料

- 国内货柜履约只维护订舱和装柜/出仓交接所需的预计开船、到港等静态资料，不执行出仓后的船公司或船节点查询。
+- 国内货柜履约维护订舱、送港、进港、甩柜/改配和实际开船前的状态；承运船舶实际开航后由海外仓业务执行船公司和船节点查询。
 - 船公司/订舱代理、航线、订舱号、船名航次、起运港、目的港、截单、截关、截港、ETD 和 ETA 暂列为候选字段。
 - 订舱失败、改船、甩柜、船期延误和取消暂列为候选异常场景，按业务确认结果实现。
- 六家船公司来源、每 3 天/最多 3 次、最近有效结果和过期标识，以及对应适配层全部移至海外仓业务船节点查询维护。
+- 六家船公司来源、每 3 天/最多 3 次、最近有效结果和过期标识，以及对应适配层在 `VESSEL_DEPARTED` 后由海外仓业务船节点查询维护。
 - 国内货柜履约页面展示的 ETD/ETA 必须明确为订舱或人工确认快照，不得伪装成出仓后的实时查询结果。
 - 建议关键信息变更保留旧值、新值、原因，并向授权用户发送站内提醒。

@@ -165,18 +165,20 @@ PDA 拣货 → 装柜并上传货柜/铅封照片

 ### 7. 报关资料协同

- 客户按资料清单上传发票、箱单、合同、委托书和申报要素等文件。
+- `LOADED` 后按最终实装清单建立每个客户/入仓码的报关案例；客户按资料清单上传发票、箱单、合同、委托书和申报要素等文件。
 - 资料清单可按国家/地区、渠道和货物类型配置，并保存订单使用的清单版本。
 - 平台报关专员审核完整性，可退回具体文件并记录补件原因和时限。
- 提交报关代理时生成提交批次，冻结该批次关联的文件版本。
+- 资料发送报关行时记录 roundNo 和发送时间，报关行回执上传后发对应客户确认；客户打回则重新上传、重新发送并生成新回执版本。
+- 柜内所有客户确认后才生成整柜正式提交批次，冻结该批次关联的文件版本并交报关行正式申报。
 - 首版采用系统内整理加线下提交，不直接对接海关单一窗口。

 ### 8. 报关回执与客户下载

- 授权人员人工上传代理回传的报关回执并关联提交批次；有效放行回执是装柜完成硬门禁，回执类型、版本和操作者可追溯。
+- 授权人员人工上传报关行回传的每轮回执并关联客户报关案例；回执类型、版本、roundNo、操作者和客户确认/打回结果可追溯。
 - 替换文件产生新版本，不覆盖原记录；退单或补件形成明确任务。
 - 客户只能下载本企业且标记为客户可见的回执。
 - 文件下载使用授权地址并记录审计，不暴露内部存储路径。
+- 所有客户确认后，平台向报关行提交整柜资料；报关行正式申报后另行记录查验、不查验放行、补件/退回等海关结果。

 ### 9. 装柜完成确认与海外回传边界

@@ -246,8 +248,8 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 | P3-M2 订舱与拖车 | 订舱、出仓前船期资料、拖车预约和异常处理可用 | 服务商与权限可用 |
 | P3-M3 PDA 拣货 | 在线任务、持久化草稿、批量提交、差异、复核和幂等可用 | 服务端任务与库存契约可用 |
 | P3-M4 装柜封柜 | 柜号、铅封和照片证据完整，门禁生效 | 文件能力与必传清单确认 |
-| P3-M5 报关协同 | 客户上传、平台审核、补件、提交和回执下载闭环 | 报关资料清单确认 |
-| P3-M6 装柜完成 | 订舱、拖车、放行回执、PDA 拣货、五类证据和锁码文本满足门禁后进入 `LOADED`/装柜完成 | 装柜完成硬门禁已确认 |
+| P3-M5 报关协同 | `LOADED` 后客户资料、报关行回执、客户确认/打回重做、所有客户通过、整柜正式申报和查验/放行闭环 | 报关资料清单确认 |
+| P3-M6 装柜完成及并行送港 | 真实柜号、PDA 拣货、数量守恒、五类证据和锁码文本满足门禁后进入 `LOADED`；随后并行推进送港/进港/甩柜和报关线，实际开船才进入海运 | 装柜完成、报关线和送港线分开 |
 | P3-M7 联调验收 | 跨端、设备、安全、弱网、性能、迁移和发布完成 | P3-M1 至 P3-M6 验收通过 |

 ## 九、建议开发任务
@@ -259,18 +261,18 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 | P3-DSP-01 | 后台 | 订单国内货柜履约编排 | 在现有订单列表/详情中接入柜次、子流程、异常、时间线和门禁操作 | P0 | P3-BASE-02 |
 | P3-PLAN-01 | 公共 | 排柜规则 | 按已确认规则实现输入、约束、偏好和冲突判断 | P0 | P3-BASE-02、P3-Q1 |
 | P3-PLAN-02 | 后台 | 智能排柜 | 按已确认范围实现建议、人工确认和追溯 | P0 | P3-PLAN-01 |
-| P3-BOOK-01 | 后台 | 订舱 | 订舱和经确认的船名航次、港口、变更及异常；订舱完成是 `LOADED` 门禁 | P0 | P3-DSP-01 |
-| 原 P3-PORT-01 | 后台/服务端 | 出仓后船节点查询 | 已重新归入海外仓业务，不作为国内货柜履约交付或验收项；沿用现有 `CarrierScheduleQuery`，不得重复实现 | 海外仓业务 | P3-BOOK-01、确认国内出仓 |
-| P3-TRUCK-01 | 后台 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常 | P0 | P3-DSP-01 |
+| P3-BOOK-01 | 后台 | 订舱 | 订舱和经确认的船名航次、港口、变更及异常；订舱/拖车服务送港线，不作为 `LOADED` 的报关前置 | P0 | P3-DSP-01 |
+| P3-PORT-01 | 后台/服务端 | 送港、进港与甩柜 | 记录 `DEPARTED_WAREHOUSE`、`PORT_RECEIVED`、`ROLLED_OVER`、改配船次和客户通知；不以预计 ETD 推进海运 | P0 | P3-BOOK-01、P3-TRUCK-01 |
+| P3-TRUCK-01 | 后台 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓、进港和异常 | P0 | P3-DSP-01 |
 | P3-PICK-01 | 公共 | 拣货任务 | 按排柜方案生成任务、明细、差异和复核规则 | P0 | P3-PLAN-02 |
 | P3-PDA-01 | PDA | 在线扫码拣货 | 进入任务标记拣货中、扫描草稿、部分/跳拣异常原因和批量提交 | P0 | P3-PICK-01 |
 | P3-PDA-02 | PDA/服务端 | 草稿与提交安全 | 作业员+任务+柜次持久化草稿、幂等重试、版本冲突、成功/放弃清理 | P0 | P3-PDA-01 |
 | P3-LOAD-01 | 后台 | 装柜封柜 | 柜号、锁码文本、装柜节点、五类多图证据和门禁复核 | P0 | P3-PICK-01 |
 | P3-LOAD-02 | PDA/Admin/服务端 | 柜封拍照上传 | PDA 现场拍摄、Admin 人工上传、五类证据多图追加、真实文件上传、预览、失败重试、作废和提交 | P0 | P3-LOAD-01、文件能力可用 |
-| P3-CUS-01 | 客户端 | 报关资料 | 清单、上传、补件、版本和进度查看 | P0 | 文件能力可用 |
-| P3-CLEAR-01 | 后台 | 报关协同 | 人工审核、补件、线下提交代理、人工上传放行回执和版本审计 | P0 | P3-CUS-01 |
-| P3-CUS-02 | 客户端 | 回执及出仓前船期资料 | 回执下载、订舱预计开船/到港快照和变更时间线；出仓后查询展示归海外仓业务 | P0 | P3-BOOK-01、P3-CLEAR-01 |
-| P3-GATE-01 | 服务端 | 装柜完成门禁 | 校验订舱、拖车、报关放行回执、PDA 拣货、五类证据和锁码文本，幂等推进 `LOADED`；`LOADED` 后仅线下人工处理 | P0 | P3-PICK-01、P3-LOAD-01、P3-LOAD-02 |
+| P3-CUS-01 | 客户端 | 报关资料与客户确认 | `LOADED` 后清单、上传、补件、回执查看、确认/打回和轮次进度 | P0 | 文件能力可用 |
+| P3-CLEAR-01 | 后台 | 报关协同 | 通知报关行、人工审核、回执轮次、客户确认汇总、所有客户通过后整柜正式提交、查验/放行记录 | P0 | P3-CUS-01 |
+| P3-CUS-02 | 客户端 | 回执及送港/船期资料 | 回执确认、打回重做、送港/进港/甩柜和实际开船前状态展示 | P0 | P3-BOOK-01、P3-CLEAR-01 |
+| P3-GATE-01 | 服务端 | 装柜完成与并行分支门禁 | 校验真实柜号、PDA 拣货、数量守恒、五类证据和锁码文本，幂等推进 `LOADED`；随后分别创建报关案例和送港任务，实际开船才推进海运 | P0 | P3-PICK-01、P3-LOAD-01、P3-LOAD-02 |
 | P3-OVERSEAS-01 | 服务端 | 海外仓派送完成回传 | 只接受海外仓可信回传，校验身份、签名、时间窗、防重放和幂等，推进 `DELIVERED` | P1/后续阶段 | 海外仓契约 |
 | P3-NOTIFY-01 | 公共 | 通知异常 | 站内通知、阻塞、责任人、时限和失败补偿 | P1 | 核心流程完成 |
 | P3-TEST-01 | 公共 | 自动化测试 | 权限、排柜、幂等、并发、文件、门禁和状态测试 | P0 | 所有 P0 模块 |
@@ -305,11 +307,12 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
 | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 已确认依赖入库测量与计费实时库存、当前位置和可用量接口；不扩展完整 WMS |
 | P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认：五类各至少 1 张、同类型可多张追加、后台操作员/理货员可上传、拣货员仅 PDA 现场采集、错图作废、无限期保留、客户不可见 |
 | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 已确认首版人工维护清单和版本，不接自动报关 |
-| P3-Q8 | 报关代理如何接收资料和返回回执？ | 已确认线下提交，授权人员人工上传回执 |
-| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 当前更正：国内货柜履约只维护订舱与出仓前船期资料；六家船公司及出仓后节点查询整体归海外仓业务 |
+| P3-Q8 | 报关代理如何接收资料和返回回执？ | 已确认 `LOADED` 后线下提交；授权人员人工上传每轮回执，客户确认/打回，所有客户通过后再提交整柜资料 |
+| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 当前更正：国内货柜履约维护送港、进港、甩柜/改配和实际开船前状态；只有实际开船后进入海运节点查询 |
 | P3-Q10 | 进入装柜完成后发现错误如何处理？ | 已确认线下人工处理，当前不提供在线冲正 |
-| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 已确认订舱、拖车、报关放行、PDA 拣货和五类证据为 `LOADED` 硬门禁；单柜次单作业员 |
-| P3-Q12 | “报关回执”具体包含哪些类型，海关放行是否为国内出仓硬门禁？ | 已确认有效放行回执为 `LOADED` 硬门禁，首版人工上传 |
+| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 费用确认不阻断排柜/装柜；`LOADED` 只校验物理装柜、PDA、数量和证据；报关线和送港线并行，客户确认不阻断送港，进港不代表报关完成；单柜次单作业员 |
+| P3-Q12 | “报关回执”具体包含哪些类型，海关放行如何与客户确认衔接？ | 已确认：回执人工上传并发客户确认；客户打回则重做并生成新回执；所有客户通过后才整柜正式申报，查验/放行单独记录 |
+| P3-Q17 | 送港和报关是否互相等待？甩柜何时发生？ | 已确认：`LOADED` 后两条线同时启动；送港可先到港，报关可先完成客户确认；船舱不足记录甩柜/改配，实际开船才进入海运 |
 | P3-Q13 | 国内货柜履约终点以什么状态为准？ | 已确认为 `LOADED`/装柜完成；`DELIVERED`/派送完成由海外仓回传，不属于国内国内货柜履约 |

 ## 十二、建议实施顺序