docs/头程到尾程/报关代码开发交接清单.md

# 报关代码开发交接清单

> **当前状态：第一阶段报关协同已接入测试环境。** 客户资料、首次发送报关行批次、回执、客户确认历史和真实完税文件已形成独立链路；报关行确认回执和更复杂结果凭证仍是后续补充项。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.md)为准；流程规则以[报关资料与船期价格接入梳理](../国内货柜履约/报关资料与船期价格接入梳理.md)为准，节点关系以[头程到尾程流程节点梳理](../头程到尾程流程节点梳理.md)为准。

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

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

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

从装柜完成（`LOADED`）开始，按柜内客户分别处理：

1. 按最终实装清单建立客户报关案例和资料包。
2. 收集客户上传、替换或补充的资料，冻结后由平台生成独立批次首次发送给报关行。
3. 接收报关行回执并发给对应客户确认。
4. 客户打回时，只重开对应客户当前轮次，重新上传、重新发送并生成新回执；保留每轮资料、回执、确认人、时间、动作历史和打回原因。
5. 柜内所有客户确认后，平台发送客户确认后的回执给报关行执行。
6. 报关行执行完成后，平台上传真实报关完税文件；全部退税资料对应的完税文件齐全后，整柜报关完成。
7. 分别记录海关查验、不查验放行、扣货或其他正式结果。

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

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

- `LOADED` 只表示物理装柜完成；报关资料、回执、客户确认和正式申报仍需独立完成。
- 报关完成后，货柜才能进入待发区；待发区表示等待船舶承运，不表示已经开船。
- 送港、进港、甩柜和改配是运输事实；甩柜只在原柜船期记录上人工修改船信息，不回退或重新处理已完成报关资料。
- 只有承运船舶实际开航后，才推进 `DEPARTED_ORIGIN_PORT` 海运节点。

## 三、当前代码交接重点

### 已落地的第一批能力

- 平台端和客户端都能展示当前视角的实际装箱数；部分装柜只展示箱数，后续由线下人员处理，系统不做数量分摊。
- 报关资料和报关行回执继续按文件上传、覆盖、版本和下载处理；页面文案已区分“回执”和“完成”，避免把上传回执误认为客户确认或正式申报。
- 首次发送报关行单独记录 `brokerSubmission`（业务批次号、冻结资料版本、快照、操作人和时间）；未完成首次发送时不能上传回执，也不能发送客户确认结果给报关行执行。
- 报关资料链路仅适用于退税货物；买单货物不创建客户报关资料、回执和客户确认流程。
- 回执上传后进入待确认状态；客户端已提供整份回执确认和打回入口，平台与客户端都展示每个回执版本的确认/打回历史，打回原因回传后再由平台重新上传回执。
- 后端 OpenAPI、平台/客户端模型和基础测试已同步实际箱数字段；管理员端、客户端类型检查及相关组件测试已通过。

旧版资料与回执基础链路已通过测试环境真实 HTTP 验收；两份文件新流程已通过本地单测、契约测试和测试环境部署。报关闭环不依赖 PDA；真实 HTTP 验收应使用已经处于待发区的柜作为前置，不能因为装柜/PDA 前置失败而把报关结论判为失败。

### 报关与 PDA、船期的边界

- PDA 只负责装柜现场作业，产出 `LOADED` 事实；本报关模块不创建、领取、认领或提交 PDA 任务。
- 报关模块只消费已完成装柜且可进入待发区的柜。装柜链路可以作为系统级前置验收，但不属于报关两份文件闭环的验收内容。
- 船期、价格、甩柜和改配属于运输模块。甩柜时只人工修改原柜的船名、航次和时间，柜号、报关资料、回执、客户确认和完税文件不变，也不重新创建报关任务。

### 本轮对 PDA 关系的落地说明（2026-09-26）

- PDA 没有参与本轮代码修改，也没有被报关接口调用；客户资料、报关行回执、客户确认和真实报关完税文件仍由平台与客户/报关行接口独立处理。
- 当前客户报关详情接口只对已完成装柜的订单开放，未达到 `LOADED` 时返回“订单尚未完成装柜”。因此 PDA 只是报关入口的上游准入事实，不是报关协同动作的一部分。
- 若后续业务确认“装柜前就允许客户上传报关资料”，应单独调整 `LOADED` 准入门禁；不能通过在报关模块里偷偷创建或操作 PDA 任务解决。
- 本轮测试已用真实 HTTP 建立退税柜、订舱和船期关联，并确认装柜计划仍为 `EDITING`、`readyForPda=false` 时不启动报关；证据见 `baiyue-firstleg/reports/customs-prep-container-20260926.json`。

### 本轮报关专项真实 HTTP 证据（2026-09-27）

- 使用测试库中已完成装柜的退税计划 `loadingPlanId=2103494180160507905`，没有调用任何 PDA 接口。
- 客户确认回执：HTTP 200、业务码 `200`，报关状态仍为 `DECLARING`。
- 平台发送客户确认结果给报关行：HTTP 200、业务码 `200`，产生 `brokerSubmittedAt`，状态仍为 `DECLARING`。
- 平台上传真实报关完税文件：HTTP 200、业务码 `200`；随后平台和客户查询均返回 `COMPLETED`，并可见完成文件。
- 完整证据：`baiyue-firstleg/reports/focused-customs-flow-without-pda-20260927.json`。该证据证明两份文件报关协同闭环本身不依赖 PDA。
- 早期全量验收报告 `customs-full-20260926h.json` 的失败项集中在 PDA 任务被分配给其他作业员，导致装柜链未进入 `LOADED`；修正验收作业员绑定并补齐 File 服务回执类型后，新的全链路报告 `customs-mixed-20260927i.json` 已通过 532/532，报关模块 223+47+23 项全部通过。

### 本轮部署证据

- 本轮 Firstleg 后端 `backend-java #652`、下游 `baiyue-firstleg-firstleg #455`、平台管理端 `admin-web-test #473`、客户端 `client-web-test #355` 均已成功部署到测试环境，健康检查为 `UP`。
- 客户端报关资料定向测试 61/61 通过；报关服务单测、OpenAPI 契约测试和平台报关组件测试结果记录在本轮交接记录及对应构建产物中。
- 正式申报/海关结果接入提交：Firstleg `ed692ee3`、路由合同修正 `95da66c7`、执行顺序修正 `4bec639a`，`backend-java #639/#640/#641` 成功；Admin `29cb0bd`、顺序修正 `855d8c0`，`admin-web-test #461/#462` 成功；Client `8c8fdbc`、`client-web-test #350` 成功。正式申报和结果真实 HTTP 7 步全部通过，证据见 `baiyue-firstleg/reports/formal-customs-declaration-and-clearance-result-20260927.json`。
- 甩柜改配投影提交 `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`。

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

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

开发时不要只增加页面节点文案，也不要把旧的 `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 和阶段三的实现状态；当前真实 HTTP 已通过，后续仍按 `COMPLETED`、海关放行和运输节点分别验收。