优化

2026-09-29 17:55:58 +08:00
parent e579ca2d3a
commit 19943112c0
14 changed files with 371 additions and 280 deletions
@@ -1,6 +1,6 @@
 # 头程到尾程当前维护入口

-这里集中列出后续流程变更需要查找和修改的文档。整体流程基线已确认，除报关协同代码外进入收尾；日常只从本目录进入，历史开发材料统一放在[文档归档](../归档/README.md)。
+这里集中列出 F01-F40 全流程变更需要查找和修改的文档。报关协同代码已接入并通过真实 HTTP 验收，当前进入全流程状态与页面证据收尾；日常只从本目录进入，历史开发材料统一放在[文档归档](../归档/README.md)。

 ## 当前流程文档

@@ -10,9 +10,9 @@
 | 分段流程 | [头程到尾程分阶段流程](../头程到尾程分阶段流程/README.md) | 六个阶段的字段、页面操作、权限、状态和异常 |
 | 货柜入口 | [国内货柜履约 README](../国内货柜履约/README.md) | 分柜、装柜、报关协同、送港和进港的货柜范围 |
 | 报关与船期专题 | [报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md) | 客户资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格 |
-| 报关开发交接 | [报关代码开发交接清单](报关代码开发交接清单.md) | 当前未完成的报关代码范围、完成条件和开发入口 |
+| 报关开发交接 | [报关代码开发交接清单](报关代码开发交接清单.md) | 报关代码完成条件、已验收范围和后续增强项 |
 | 头程与报关交互矩阵 | [头程节点与报关清关交互矩阵](头程节点与报关清关交互矩阵.md) | F01-F24 各节点的客户、平台、PDA、报关行和船期交互 |
-| 第一阶段冻结矩阵 | [头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md) | F01-F24 节点、报关完成进入待发区、当前实现缺口和开发前确认项 |
+| 全流程实现对照 | [全流程节点矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md) | F01-F40 节点、现行规则、实现差异和验证边界；保留原文件路径 |
 | 正式申报与海关结果 | [正式申报与海关结果接入设计](正式申报与海关结果接入设计.md) | F22.7 正式申报批次、报关单号、F22.8 查验/补资料/放行/扣货/其他结果及三端边界 |
 | 甩柜改配接入设计 | [甩柜改配接入设计](甩柜改配接入设计.md) | F23.3 原柜人工修改船信息并保留修改历史 |

@@ -1,12 +1,12 @@
-# 头程至实际开船节点冻结矩阵与缺口清单
+# 全流程节点矩阵与缺口清单

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

 ## 一、阶段边界

 ```text
 头程下单
-  F01-F13：下单、审核、到仓、测量、计费、费用确认、组托、待分柜
+  F01-F13：下单、审核、到仓、测量、计费、费用确认、国内扣货/解除、组托、待分柜
 国内货柜履约
  F14-F21：分柜、订舱、拖车、拣货、装柜、LOADED
 报关完成后进入待发区
@@ -14,38 +14,82 @@
  F23：待发区、送港、进港、甩柜、改配
 海运起点
  F24：承运船舶实际开航
+目的港与海外入库
+  F25-F30：目的港处理、尾程订单、入仓计划、接柜、收货、库存入账
+海外库存与出库
+  F31-F37：库内操作、暂扣、库内服务、排车、生成出库/派送单、拣货发车、出库
+派送与完成
+  F38-F40：签收、异常退回、回访和完成回写
 ```

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

-## 二、F01-F24 节点冻结矩阵
+### 实现与验证口径
+
+“已有实现”不等于最新版本已完成验收。下表的既有 HTTP 证据只证明对应报告范围与版本；历史通过不能替代当前完整链路、页面或 PDA 现场验证。报关和运输专项的通过也不能外推为 F01-F40 全部通过。后续增强项不作为首期主流程缺失处理。
+
+2026-09-29 修复后的默认全量真实 HTTP 回归已通过：Admin 11,627 项检查、120 个模块、7,429 次请求，0 失败、0 跳过模块；Client 195 项检查全部通过。F31 换托同库位比较、A0 共享溢出位移库、F33 无贴标转仓查询及跨服务错误处理已修复并部署测试环境；验收脚本补齐直接贴标审核、返工重新领取及禁止回移虚拟收货位的边界。离线合同 128 个文件、773 项断言全部通过。
+
+同票普通 FBA 主链证据为入仓码 `NYEXX2609290171`、柜次 `D1063`、柜号 `TSTU3425326`、排车单 `DS-WH-20260929-067073`、出库单 `OB-WH-20260929-158402`；两张目的仓派送单签收后，已核对来源入仓单 `DELIVERED` 和来源订单 `COMPLETED`。随后故意执行的退回异常测试会改变留存单据状态，不能把最终留存状态误读成未曾完成。退税报关分支另由同一全量报告中的混合柜检查覆盖，不冒充同一票退税至签收证据。
+
+对应证据：`baiyue-firstleg/reports/admin-full-current-20260929-r7.json`、`reports/client-full-current-20260929-r3/client-test-env-20260929063613-e54d44dd.json`、`reports/fba-main-chain-evidence-20260929.json`（后两个路径同属后端仓库）。Admin/Client 报关详情已按 1920×1080 页面核对；船期日历网络恢复后重载正常。未离仓测试柜 `TSTU7897110` 已实际验证首次发送、普通文本回执上传、客户确认后的平台执行、正式申报、其他理由必填备注、异常保存与人工处理；客户确认通过该客户自己的 HTTP 接口完成。异常处理后回执确认保留，未上传完税文件仍保持报关中并阻断离仓。
+
+页面复验发现并修复异常发生时间早 8 小时的问题：国内 `LocalDateTime` 接口改为接收上海业务时间。Admin 提交 `4ead51a5feedf65be9443ddfe3dd45da7ca49e64` 已通过测试环境 Jenkins #482 部署；262 个测试文件、2,121 项测试和构建通过。部署后真实页面新增查验记录的发生时间与服务器记录时间相差 0.879 秒。详见后端仓库 `reports/customs-time-postdeploy-20260929.json` 和 `reports/customs-other-resolved-1920-20260929.jpg`。Android 真机、弱网和外部船司正式凭据仍属于单列验证边界，不纳入本次内置浏览器与 HTTP 通过结论。
+
+## 二、F01-F40 节点冻结矩阵

 | 节点 | 客户可见进度 | 后台业务对象 | 必须形成的真实事实 | 当前状态 | 本阶段缺口 |
 |---|---|---|---|---|---|
 | F01-F07 | 待下单、审核中、已审核 | 企业、订单、审核任务 | 提交、补件、审核、入仓单生成 | 已有主链 | 按现有订单契约回归，不在本轮重做 |
 | F08-F10 | 待到仓、测量中、待确认 | 入仓单、测量记录 | 收货、扫码、称重、测量、审核 | 已有主链 | 只核对是否能稳定产出排柜事实 |
-| F11-F13 | 费用待确认、待组托、待分柜 | 费用版本、确认记录、托盘 | 计费推送、客户确认、组托/封托 | 已确认并行规则 | 保证费用默认确认不能冒充报关确认 |
+| F11 | 费用待确认 | 费用版本、客户确认记录 | 计费推送、客户主动确认、版本留痕 | 已有实现；旧总览的默认确认表述与阶段二及服务指引冲突 | 按现行规则，装柜可自动发布费用，但不能代替客户确认；不将缺少 `SYSTEM_AUTO_AT_LOADED` 列为必修代码缺陷 |
+| F12 | 国内扣货中、已解除 | 国内入仓单 HOLD 记录 | 扣货、解除、原因和后续作业门禁 | 已实现；最新全量 inbound-hold 模块通过 | 与报关海关异常、海外库存暂扣分别维护，不能混为同一节点 |
+| F13 | 待组托、待分柜 | 一件代发清点、托盘和封托记录 | 逐箱清点、归托、封托 | 已有主链 | 结合一件代发路径验证；不要求普通散货重复执行一件代发清点流程 |
 | F14-F20 | 待分柜、订舱中、装柜中 | 柜次、装柜计划、拖车、PDA 任务 | 分柜、订舱、排车、拣货、照片、铅封、数量核对 | 主链已有 | 核对真实柜号、订舱和装柜快照能否冻结 |
 | F21 | 国内已装柜 | 装柜计划、物理货柜、装柜证据 | 实际柜号、实装箱数、装柜证据、`LOADED` | 已有 | 报关案例按最终实装范围建立；部分装柜只显示已装箱数并标记线下处理，不在系统内自动分摊 |
 | F22.1 | 报关确认中 | 柜级报关聚合内的客户资料范围 | 每客户范围、入仓码范围、混合柜隔离、实装范围回显 | 已实现并通过真实 HTTP 验收 | 独立“案例”对象仍可在正式批次设计时补充；部分装柜仍线下处理 |
-| F22.2 | 待提交资料、待补资料 | 客户资料包 | 上传、替换、关联范围、版本、冻结 | 已实现并通过真实 HTTP 验收 | 资料类型化清单和补件原因待补 |
+| F22.2 | 待提交资料、待补资料 | 客户资料包 | 上传、替换、关联范围、版本、冻结 | 已实现并通过真实 HTTP 验收 | 首期不维护资料类型清单；有文件即可上传，补件通过人工异常理由和备注说明 |
 | F22.3 | 已发送报关行 | 独立首次发送批次 `brokerSubmission` | 业务批次号、发送人、发送时间、冻结版本、资料快照、幂等历史 | 已实现并通过定向测试与测试环境部署 | 报关行接收确认和回执轮次对象待补 |
 | F22.4 | 待客户确认 | 回执/完成文件版本 | 文件版本、关联客户范围、客户可下载 | 已实现；回执历史和确认动作历史均只读投影 | 独立回执返回时间/下载凭证仍待补 |
 | F22.5 | 客户确认中、已打回 | 客户确认记录与动作历史 | 确认/打回、回执版本、操作人、时间、原因 | 已实现并通过定向测试与测试环境部署 | 通知聚合和报关行回执轮次待补 |
-| F22.6 | 等待整柜确认 | 完税文件齐全门禁 | 所有退税客户确认、发送执行、真实完税文件齐全 | 已实现并通过专项真实 HTTP 验收 | 复杂结果凭证和补资料专项门禁待补 |
-| F22.7 | 已提交正式申报 | 正式申报批次 | 报关行确认、正式申报时间、操作人、批次、报关单号 | 已实现并通过真实 HTTP 7 步联调 | 后续补更复杂的结果凭证类型 |
-| F22.8 | 查验中、待补资料、已放行、扣货/其他 | 海关结果事实 | 报关单号、结果类型、时间、凭证、处理结果 | 已实现并通过真实 HTTP 7 步联调 | 后续补查验/扣货/补资料专项场景的更细验收 |
+| F22.6 | 等待整柜确认 | 完税文件齐全门禁 | 所有退税客户确认、发送执行、真实完税文件齐全 | 已实现并通过专项真实 HTTP 验收 | 查验、扣货、补资料作为平台人工异常节点处理，不新增自动凭证门禁 |
+| F22.7 | 已提交正式申报 | 正式申报批次 | 报关行确认、正式申报时间、操作人、批次、报关单号 | 已实现并通过真实 HTTP 7 步联调 | 后续可补报关行接收时间和下载凭证 |
+| F22.8 | 查验中、待补资料、已放行、扣货/其他 | 海关结果事实 | 报关单号、结果类型、时间、人工理由、备注和处理结果 | 已实现；真实 HTTP 与人工异常页面保存/处理通过，发生时间偏差已修复并部署复验 | 不接短信或自动海关系统；真机及外部系统不在页面验证范围 |
 | F23.1 | 待发区、送港中、已离仓 | 待发区与送港/出仓任务 | 报关完成时间、待发区门禁、离仓时间、车辆/任务、操作人、证据 | 已实现并通过真实 HTTP 验收 | 继续补待发区客户/平台投影展示 |
-| F23.2 | 已送港、已进港 | 运输和港口事实 | 送港时间、进港时间、来源和凭证 | 部分已有 | 与订舱、拖车和船次事实统一读写 |
+| F23.2 | 已送港、已进港 | 运输和港口事实 | 送港时间、进港时间、来源和凭证 | 已实现；已有真实 HTTP 证据 | 继续补充最新页面证据，并保持与订舱、拖车和船次事实统一读写 |
 | F23.3 | 已甩柜、等待改船后承运 | 船期记录修改历史 | 甩柜原因、发生时间、修改前后船名/航次/船期、处理人 | 已实现并通过测试环境真实 HTTP；平台与客户端最新船期投影一致 | 继续补页面截图和更复杂异常分支；柜次、订舱关联和报关事实不变 |
-| F24 | 海运中 | 船次实际节点 | 承运船舶、航次、实际开航时间、来源/凭证 | 基础已有 | 只允许实际开航事实推进海运节点 |
+| F24 | 海运中 | 船次实际节点 | 承运船舶、航次、实际开航时间、来源/凭证 | 已实现；实际节点与查询任务已有真实 HTTP 证据 | 继续补充最新一轮页面证据；只允许实际开航事实推进海运节点 |
+| F25 | 目的港处理中、待海外接柜 | 船节点、目的港清关/提柜、尾程订单 | 到港、卸船、清关、提柜和可接柜事实 | 已实现并有综合真实 HTTP 证据 | 外部码头/车队差异继续按异常分支补充 |
+| F26 | 尾程订单待建计划 | 跨区事件、尾程订单 | 装柜完成、船节点和来源入仓单快照可靠投递与消费 | 已实现并有综合真实 HTTP 证据 | 继续观察跨区事件延迟和补偿告警 |
+| F27 | 待建立海外入仓计划 | 入仓计划、计划托盘和资源锁 | 按柜内每票生成计划、预计到仓和托盘资源冻结 | 已实现并有综合真实 HTTP 证据 | 继续补齐异常重试页面证据 |
+| F28 | 待接柜、接柜中 | 海外 PDA 接柜会话 | 柜号认领、三类签收照片和签收确认 | 已实现并有综合真实 HTTP 证据 | Android 真机验收仍是独立非阻塞项 |
+| F29 | 入库中 | 海外 PDA 收货任务 | FBA 散货、海外仓逐箱、一件代发整托等实收事实 | 已实现并有综合真实 HTTP 证据 | 继续补充现场设备和弱网证据 |
+| F30 | 入库完成 | 入库任务、库存和跨区回写事件 | 全柜核平、库存同事务入账、卸柜完成事件 | 已实现并有综合真实 HTTP 证据 | 保持事件幂等和库存数量守恒 |
+| F31 | 库存可用、库内服务中 | 库存、库位、托盘、盘点 | 上架、移库、合托/拆托、盘点和库存流水 | 已实现并有综合真实 HTTP 证据 | 继续补充大批量库存性能验收 |
+| F32 | 暂扣中、已解除 | 暂扣记录和库存锁 | 暂扣原因、解除原因、操作人和库存可用性变化 | 已实现并有综合真实 HTTP 证据 | 暂扣与出库并发场景继续补充 |
+| F33 | 换标/转运/废弃处理中 | 换标、转运、废弃子单 | 客户确认、箱唛/托盘变更、库存锁和实际扣减事实 | 已实现并有综合真实 HTTP 证据 | 继续补充复杂返工和跨仓异常 |
+| F34 | 待派送、排车中 | 智能预排、排车单 | 候选、草稿锁、正式排车和目的仓分配 | 已实现并有综合真实 HTTP 证据 | 继续补充多车多目的仓页面证据 |
+| F35 | 待转派送、待出库 | 排车转派送、出库单、派送单 | 出库/派送单生成、目的仓拆分、费用只发布一次 | 已实现并有综合真实 HTTP 证据 | 保持转派送前不可发车 |
+| F36 | 拣货中、待发车 | 海外 PDA 排车任务 | 托盘扫描、数量核平、车辆资料和发车门禁 | 已实现并有综合真实 HTTP 证据 | Android 真机和弱网恢复仍需专项验证 |
+| F37 | 已出库、派送中 | 出库单、派送单 | 出库完成、库存扣减和派送任务关联 | 已实现并有综合真实 HTTP 证据 | 继续补跨目的仓汇总展示 |
+| F38 | 派送中、已签收 | 派送单、签收凭证 | 签收文件、签收时间和每个目的仓派送完成 | 已实现并有综合真实 HTTP 证据 | 继续补异常签收凭证类型 |
+| F39 | 异常退回处理中 | 异常单、退回入仓和库存恢复 | 拒收/部分拒收、退回、库存恢复和原因历史 | 已实现并有综合真实 HTTP 证据 | 继续补多次退回和部分恢复组合场景 |
+| F40 | 已完成、待回访 | 客户回访、跨区完成事件、订单回写 | 回访记录、`DELIVERED` 回写及订单 `COMPLETED` 收口 | 已实现并有综合真实 HTTP 证据 | 继续补跨区延迟时的客服投影 |

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

-### 1. 报关数据模型已支持客户范围，发送批次仍需独立建模
+### 1. 客户范围和首次发送批次已落地，回执轮次属于后续增强

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

+### 1.1 费用自动发布与客户确认必须区分
+
+阶段二“费用计费与确认”和 `baiyue-firstleg/firstleg/AGENTS.md` 明确规定：费用不阻断排柜和装柜，装柜完成不得代替客户自动确认，客户确认与本票装柜完成共同构成最终冻结条件。`FbaPricingService.autoSendAfterLoadingCompleted` 执行平台费用确认与发送，`confirmByCustomer` 才记录客户确认人和时间；`SENT` 不等于客户确认。旧总览要求 `SYSTEM_AUTO_AT_LOADED` 的表述与现行规则冲突，不能据此直接新增自动代客确认。若未来明确改变该规则，再同步费用版本、确认来源和冻结边界。
+
+### 1.2 海关异常按人工节点处理
+
+海关短信由平台人员人工查看和操作，系统不接短信、不自动判断查验或扣货。平台在正式申报批次上人工标记异常，选择“查验”“扣货”“补资料”或“其他”等理由；选择“其他”时填写备注，后续由平台人员人工解除或录入处理结果。异常是申报批次上的附加事实，不改变已上传资料、回执和客户确认历史。
+
 目标至少需要以下关系：

 ```text
@@ -86,14 +130,14 @@

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

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

 ### 接口与数据库

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

 ### 审计

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

 ### 测试

@@ -127,9 +171,9 @@
 9. 客户越权读取同柜其他客户资料被拒绝。
 10. 部分装柜能显示实际箱数并留下线下处理标记；换柜不能直接覆盖原案例和历史回执。

-## 五、开发前仍需业务确认
+## 五、后续增强（无需当前业务确认）

-以下问题中，前四项已经由《报关代码开发交接清单》和《头程到尾程流程节点梳理》冻结，本轮又补充冻结了文件形态、部分装柜展示、回执确认、首期申报和实际开航/改配处理方式；表格后的内容仍需业务补充，不能由代码现状推断。
+以下内容不阻断当前开发：回执接收时间、回执轮次和下载凭证可以后续增强；海关短信、查验、扣货、补资料和其他异常按平台人工标记、选择理由和填写备注处理。

 ### 已冻结的业务规则

@@ -151,14 +195,14 @@
 | 资料继承 | 报关完成后资料、平台回执和客户确认与船期独立；甩柜/改配不触发重新上传或重新确认。 |
 | 航次任务 | 平台人工修改原柜船信息，继续使用原任务；保留修改历史和已有节点。 |

-### 仍需补充的字段和操作规则
+### 已确认的字段和操作规则

-1. 首版资料清单具体项目、条件规则、版本生效方式和责任人是什么？
-2. （已确认）第一版由平台人员直接修改原柜船名、航次和船期，填写原因并保留修改历史。
-3. （已确认）平台人工修改原柜船名、航次和船期；柜子与原任务不变。
-4. （已确认）原航次退税资料、回执和客户确认与船期独立，甩柜/改配不触发重新确认。
-5. （已确认）甩柜/改配与报关资料无关，不重新生成报关批次，不要求客户重新确认。
-6. 修改船信息不生成实际开航事实；只有本柜实际随船开航后才记录 `DEPARTED_ORIGIN_PORT`。
+1. （已确认）首期不维护资料类型清单和逐项责任人；资料包只要有文件即可上传、替换和留版本。
+2. （已确认）查验、扣货、补资料和其他结果由平台人员人工标记异常、选择理由；选择“其他”时填写备注，异常解除也由平台人工点击。
+3. （已确认）第一版由平台人员直接修改原柜船名、航次和船期，填写原因并保留修改历史。
+4. （已确认）平台人工修改原柜船名、航次和船期；柜子与原任务不变。
+5. （已确认）原航次退税资料、回执和客户确认与船期独立，甩柜/改配不触发重新确认。
+6. （已确认）修改船信息不生成实际开航事实；只有本柜实际随船开航后才记录 `DEPARTED_ORIGIN_PORT`。

 ### 代码接入前置缺口

@@ -166,8 +210,8 @@

 ## 六、冻结结论

- 第一阶段覆盖 F01-F24，终点为实际开航。
+- 全流程基线覆盖 F01-F40；F01-F24 终点为实际开航，F25-F40 继续完成目的港、海外入库、出库、派送和最终回写。
 - F22 报关完成后货柜进入 F23 待发区；甩柜/改配只改变运输航次，不改变报关事实。
 - 客户确认、报关行回执、整柜正式申报、海关放行、离仓、进港、甩柜和实际开航都是独立事实。
- 先完成节点矩阵、对象关系、状态投影、门禁和验收缺口确认，再进入代码设计。
- 尾程 F25-F40 暂不纳入本阶段实现，但必须保留 F24 到目的港清关的接口衔接点。
+- 节点清单覆盖完整范围；各节点实现与验证程度以表内状态为准，不将整张矩阵标为全部验收完成。
+- F25-F40 已有实现，最新默认全量 HTTP 回归已通过，并核对同票签收后的国内完成回写；本轮报关可写异常页面操作已完成，设备和外部船司边界继续单列，不能用 HTTP 全绿替代这些证据。
@@ -1,6 +1,6 @@
 # 头程节点与报关清关交互矩阵

-> 本文把头程下单 F01-F24 与报关清关的客户、平台、报关行交互放在同一张图里。当前产品先覆盖国内头程到实际开航；尾程不在本轮。报关资料只适用于包含退税货物的柜，买单货物不创建客户资料协同。
+> 本文把 F01-F40 全流程中的头程、海运与报关清关交互放在同一张图里；其中 F01-F24 是国内头程到实际开航，F25-F40 由阶段四至阶段六继续承接。报关资料只适用于包含退税货物的柜，买单货物不创建客户资料协同。

 ## 一、总链路

@@ -69,7 +69,7 @@
 仍需补齐：

 1. 报关行接收确认、回执轮次和回执下载凭证的独立对象及更细历史投影。
-2. 待发区客户/平台投影的更细页面展示和截图证据；`LOADED → 报关 → 待发区` 已在既有混合柜报告中通过，平台与客户改船后的当前船期双端回读已验收。
+2. 待发区客户/平台投影的更细页面展示和截图证据；`LOADED → 报关 → 待发区` 已在混合柜报告中通过，平台与客户改船后的当前船期双端回读已验收。F25-F40 的海运目的港、海外入库、库存、出库、派送和最终回写由阶段四至阶段六维护，综合证据见 `baiyue-firstleg/reports/admin-overseas-chain-final-fixture-20260924.json`。

 正式申报批次和海关结果已在本轮实现并通过真实 HTTP：平台创建/提交批次、录入查验、查询并处理结果，客户按自身订单查询结果；证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。

@@ -1,10 +1,10 @@
 # 报关代码开发交接清单

-> **当前状态：第一阶段报关协同已接入测试环境。** 客户资料、首次发送报关行批次、回执、客户确认历史和真实完税文件已形成独立链路；报关行确认回执和更复杂结果凭证仍是后续补充项。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。
+> **当前状态：报关协同已接入测试环境。** 客户资料、首次发送报关行批次、回执、客户确认历史和真实完税文件已形成独立链路；海关查验、扣货、补资料和其他结果由平台人员人工标记异常、选择理由并填写备注，不接短信或自动海关系统。报关行接收回执和下载凭证仍可后续增强。头程至尾程的全流程范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。

 > **本轮补充确认：** 首期报关行回执以文件为主，客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；报关完成后货柜进入待发区；实际开航首期人工录入，甩柜/改配只变更船期，不重新处理已完成报关资料。

-> **验收证据：** 既有全链路报告保留旧版 526/526、混合柜 532/532 记录；本轮新增代码、数据库和三端已部署，已用现有完成柜做接口烟测并核对首次发送门禁。完整造数到报关回归仍需要测试环境提供 PDA 作业员账号，当前 `test-acceptance.env` 缺少该变量，脚本按契约在装柜前置处停止。
+> **验收证据：** 既有全链路报告保留旧版 526/526、混合柜 532/532 记录；本轮新增代码、数据库和三端已部署，已用现有完成柜做接口烟测并核对首次发送门禁。完整造数到报关回归已补齐测试环境专用国内 PDA 作业员并通过；当前报关主链报告为 543/543，运输节点报告为 1036/1036。

 ## 一、必须实现的报关流程

@@ -18,7 +18,7 @@
 6. 报关行执行完成后，平台上传真实报关完税文件；全部退税资料对应的完税文件齐全后，整柜报关完成。
 7. 分别记录海关查验、不查验放行、扣货或其他正式结果。

-报关行回执、客户确认、整柜正式申报和海关放行是不同节点。客户确认不能自动完成，费用的系统默认确认也不能代替报关资料确认。
+报关行回执、客户确认、整柜正式申报和海关放行是不同节点。客户确认不能自动完成，平台费用确认与发布也不能代替报关资料确认。

 ## 二、报关完成与待发区关系

@@ -70,11 +70,16 @@
 - 甩柜改配投影提交 `ac3acfce`、`f1218cef`，平台容器读模型修复提交 `2c4f1ea3`；当前分支的船期展示修复已由 `backend-java #649`、`baiyue-firstleg-firstleg #452` 和 `client-web-test #351` 成功部署。真实验证确认改船只更新原柜船期，平台与客户端同步最新船期，柜号和报关资料/回执/完成文件保持不变，证据见 `baiyue-firstleg/reports/platform-and-client-transport-projection-20260927.json`。
 - 回执历史投影提交 Firstleg `f6e70ea5`、Admin `ffe91a1`、Client `3e28478` 已成功部署：`backend-java #650`、`baiyue-firstleg-firstleg #453`、`admin-web-test #471`、`client-web-test #353`。健康检查为 `UP`，平台和客户真实接口均返回 `receiptHistory`；证据见 `baiyue-firstleg/reports/customs-receipt-history-20260928.json`。
 - 本轮首次发送批次与确认动作历史提交为 Firstleg `e63cb2b2`、Admin `730defa`、Client `8fd4063`；数据库已核对 `fl_customs_broker_submission` 与 `fl_customs_completion_action_history`。现有完成柜烟测返回 `A0409 当前柜不在报关中`，确认新首次发送接口的状态门禁；证据见 `baiyue-firstleg/reports/customs-send-batch-confirmation-history-20260928.json`。
+- 本轮页面回归又修复了一个实际问题：Client 订单列表契约此前没有保留 `taxMode`，导致真实退税订单在“报关资料”页被过滤为 0 个资料包；Client `214fe4f` 已补齐退税字段映射，测试部署 `client-web-test #357` 成功。随后发现船期价格页首次加载重复请求渠道列表，`32c5241` 已收敛初始化监听，`client-web-test #358` 成功。
+- 后续回归又修复两个页面事实问题：未知海外仓不再把内部仓库 ID当作客户可见名称；报关完成详情改为明确提示“真实报关完税文件已齐全”。同时同步了现有实现对应的离线合同断言，客户端全量 `npm test` 已通过 `398/398`，生产构建通过，提交 `ffbe348`，测试部署 `client-web-test #359` 成功。
+- 测试环境内置浏览器已按 1920×1080 复验 Admin 与 Client：最新 Admin 柜次详情展示 `LOADED`、8 条仓内节点、PDA 作业摘要 100%、报关“已完成”、国内离仓“已自动离仓”和 7/7 门禁通过；最新 Client 报关资料页展示退税资料包“报关完成”，详情可见回执版本、客户确认状态、真实完税文件和下载入口。Client 船期价格查询以 100 KG/1.2 CBM 真实调用 15 个估价接口并返回 4 个匹配渠道；同一页面初始化只保留 1 次渠道列表请求。
+- 页面请求量抽样：Admin 货柜详情 13 个 API 请求且无重复；Client 报关资料列表 10 个不同 API 请求，打开两个资料详情各刷新一次资料接口；Client 船期价格初始化 1 次渠道请求，查询阶段 15 次并行估价请求，符合当前“每渠道估价”契约。完整新造数 HTTP 链已解除 PDA 前置阻塞并通过；报告 `baiyue-firstleg/reports/customs-current-20260928.json` 共 543/543 项通过，包含订单、测量、PDA 装柜、混合柜报关资料、回执、客户确认、报关行执行、完税文件、自动离仓和客户端下载。
+- 2026-09-28 再次复核：测试 API 健康检查、Admin 货柜列表/详情和 Client 报关资料页均返回 HTTP 200；Admin 与 Client 均在 1920×1080 下重新打开验证。已完成柜调用首次发送接口并携带确认参数，服务端返回 `A0409 当前柜不在报关中`，证明已完成柜不会重复创建报关批次；当前无新增数据库记录。客户端全量测试保持 `398/398` 通过，`client-web-test #359` 成功。

 当前仍需继续补齐的不是客户资料协同、正式申报和海关结果基础链路，而是：

 - 报关行回执的外部确认/接收回执、下载凭证和回执轮次的更细对象；首次发送批次与客户确认动作历史已经落地；
- 更复杂的结果凭证上传和补资料专项门禁；
+- 更细的报关行接收回执和下载凭证；海关异常继续按人工理由和备注处理，不新增自动结果凭证门禁；
 - 将正式申报/海关结果继续扩展到待发区、送港、进港和实际开航的只读投影，保持运输线独立；F23.3 的船期投影已完成真实 HTTP 核验。

 开发时不要只增加页面节点文案，也不要把旧的 `COMPLETED` 直接当成客户确认、正式申报或海关放行。
@@ -96,7 +101,10 @@
 - 每个客户都能完成“资料上传 → 报关行回执 → 客户确认/打回”，资料和完成文件保留版本，客户范围严格隔离。
 - 首次发送报关行必须生成独立业务批次；客户每次确认或打回都保留对应回执版本、操作人、时间和原因。
 - 未全部客户确认时不能完成整柜报关；正式申报批次、海关回填结果和报关单号已独立建模，不能把客户确认或完税文件上传直接当作海关放行事实。
- 海关查验、不查验放行、扣货和其他结果已落地为批次下独立事实；后续只需补更复杂的凭证上传和补资料专项验收。
+- 海关查验、不查验放行、扣货、补资料和其他结果已落地为批次下独立事实；平台人员人工选择理由，选择“其他”时填写备注并人工处理异常。
 - 报关完成后才能进入待发区；进入待发区后才推进送港/进港。甩柜/改配只修改原柜船名、航次和船期并保留历史，不能伪造或覆盖报关资料、回执和客户确认。
 - 重复请求、版本冲突、换柜、部分装柜箱数展示和权限越界都有明确结果和审计记录；部分装柜的后续处理在线下完成。
- 完成代码联调后，再回写 F22 和阶段三的实现状态；当前真实 HTTP 已通过，后续仍按 `COMPLETED`、海关放行和运输节点分别验收。
+- F22 和阶段三的实现状态已按当前代码和真实 HTTP 结果回写；后续继续按 `COMPLETED`、海关放行和运输节点分别验收，不把报关完成合并成海运或尾程完成。
+
+- 2026-09-29：补齐测试环境专用 `CN_FIRSTLEG_PDA_OPERATOR` 账号并验证登录，重新执行 `phase3-container-customs` 正式 HTTP 造数链；订单、测量、PDA 领取/扫码/提交、`LOADED` 硬门禁、混合柜 BUY/TAX 隔离、首次发送批次、回执幂等、客户确认、报关行执行、完税文件、`COMPLETED`、自动离仓和 Client 完税文件下载共 543/543 通过，348 个唯一 HTTP 请求，0 个 coverage gap。报告：`baiyue-firstleg/reports/customs-current-20260928.json`。
+- 2026-09-29：继续执行头程运输节点造数链；订舱、港务船期、甩柜改船、拖车预约、报关完成后的待发区、国内离仓门禁和船司查询策略共 1036/1036 通过，641 个唯一 HTTP 请求，0 个阻塞缺口。甩柜只更新原柜船期，柜次及报关事实不变。报告：`baiyue-firstleg/reports/transport-current-20260929.json`；剩余 4 个缺口均为非阻塞的 COSCO/ZIM 外部接入或 Android 真机验收。