报关代码开发交接清单

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

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

验收证据： 既有全链路报告保留旧版 526/526、混合柜 532/532 记录；本轮新增代码、数据库和三端已部署，已用现有完成柜做接口烟测并核对首次发送门禁。完整造数到报关回归已补齐测试环境专用国内 PDA 作业员并通过；当前报关主链报告为 543/543，运输节点报告为 1036/1036。

一、必须实现的报关流程

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

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

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

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

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。
本轮页面回归又修复了一个实际问题：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 直接当成客户确认、正式申报或海关放行。

四、开发入口

先核对当前代码和 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、海关放行和运输节点分别验收，不把报关完成合并成海运或尾程完成。
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 真机验收。

15 KiB Raw Blame History Unescape Escape