# 报关代码开发交接清单

> **当前状态：流程已确认，报关协同代码进入第一批开发。** 本文是开发交接入口，已落地内容不代表完整报关协同或真实验收通过。第一阶段冻结范围和缺口以[头程至实际开船节点冻结矩阵与缺口清单](头程至实际开船节点冻结矩阵与缺口清单.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 和阶段三的实现状态；真实验收通过前不要标记“报关完成”。