docs/国内货柜履约/报关资料与船期价格接入梳理.md

报关资料与船期价格接入梳理

当前用途：报关与船期价格专题参考。 报关流程已经确认，第一批代码和页面已经接入测试环境；开发交接看报关代码开发交接清单。主流程和节点关系以头程到尾程流程节点梳理为准；本文保留资料字段、回执轮次、价格口径和接口查找信息。

文中“目标、实施顺序、进入条件、待确认事项”等段落属于原评审记录。开发已经完成后，不再据此重新拆开发任务；若与当前确认不一致，以总览和最新业务确认修正对应专题段落。

本文是企业客户端“报关资料”“船期价格”入口的专题评审记录。当前使用时只取已确认的流程、资料和价格口径；“建议”和“待确认”保留为历史评审痕迹，不再自动生成开发任务或验收门禁。

当前基线：以最新用户确认和头程到尾程流程节点梳理为准。旧版需求表、README、开发规划和本文件中的历史建议若发生冲突，先在当前入口记录收尾变更，再决定是否需要修改专题细节。

当前实现快照（2026-09-29）：两份文件链路已经落到平台、客户和 Firstleg 报关接口，客户端“报关资料”和“船期价格”也已经作为独立模块接入导航和路由。客户资料、报关行回执、客户整份回执确认/打回、平台发送报关行执行、真实报关完税文件分别保存并受版本门禁控制。回执发送给报关行后不可再替换；只有包含退税货物的柜才允许走发送执行接口；全买单柜仍走平台直接完成。brokerSubmittedAt 只表示发送执行时间，不表示报关完成。PDA 只负责产生 LOADED 前置事实，报关验收不创建或操作 PDA 任务；船期、甩柜和改配只修改原柜运输信息，不重置报关资料和确认结果。

当前差异与下一步

当前主流程和代码的关系已经收敛：F01-F24（国内头程、报关、待发区、送港、进港、甩柜和实际开航）有最新真实 HTTP 证据；F25-F40（目的港、海外入库、库存、出库、派送和最终回写）已有综合真实 HTTP 证据和页面实现。客户端两个独立模块、订单快捷入口、平台整柜报关工作台和船期价格查询均已接入，不需要再按“新增页面”拆任务。

2026-09-29 的最新综合 F01-F40 验收报告为 baiyue-firstleg/reports/fba-full-current-20260929.json。报告前段业务链大量通过，但尾程和海外 PDA 产生了环境型阻断：test-api-overseas.buggoglobal.com 当时 DNS 不可解析，后续请求均为 fetch failed，因此这份报告不能作为全流程全绿结论，也不能据此判断报关或船期代码失败。此前报关专项 customs-current-20260928.json（543/543）和运输专项 transport-current-20260929.json（1036/1036）仍是当前可复用的绿色证据。

当前状态分为三类任务：

1. 规则已简化并确认：不维护资料类型清单，也不区分逐项责任人；客户或平台只要在资料包上传文件即可。查验、扣货、补资料均由平台人工标记异常，选择预设理由；选择“其他”时填写备注即可，不要求接入短信或自动海关系统。
2. 环境/外部验收：恢复海外测试域名解析后重新跑 F25-F40；COSCO 官方接口凭据、COSCO 动态页面和 ZIM hCaptcha 仍是外部非阻断项；Android/HBuilderX 真机扫码、弱网和在线草稿仍需现场设备验收。
3. 后续增强：报关行接收回执/回执轮次和下载凭证仍可增强，但不影响当前两份文件闭环、客户确认、正式申报和报关完成后进入待发区。
4. 费用默认确认：业务规则已经确认，但代码仍主要完成费用发布/客户确认；LOADED 时按已装范围写入 SYSTEM_AUTO_AT_LOADED、费用版本、柜次/入仓码和幂等审计的落地实现，仍需单独补齐，不能把 SENT 直接当成默认确认。

你当前不需要先操作系统或确认代码。资料上传和异常人工处理规则已经足够继续开发；其余技术修复和重新验收由开发侧继续处理。

先锁定的范围

国内货柜履约的物理装柜节点为 LOADED。LOADED 后先完成退税客户的报关协同，报关完成后进入待发区，再推进船期运输：

1. 报关线：仅对退税客户通知报关行，收集退税客户资料，发送报关行，接收报关行回执并发客户确认；客户认为不正确时打回、重新上传、重新发送并生成新回执，循环至柜内退税客户均确认；全部确认后，再将退税申报资料提交报关行确认，由报关行正式申报，记录查验、不查验放行或其他海关结果。买单货物不进入这条资料和回执流程。
2. 船期线：报关完成并进入待发区后，安排拖车、从仓库发运、送港、进港；港口容量不足时记录甩柜和改配船次。甩柜/改配只改变运输船次，不重新处理已完成的报关资料、回执和客户确认；PORT_RECEIVED 不等于海运中，只有船舶真实开航后才进入海运节点。

报关完成是进入待发区的前置；进入待发区后才推进船期运输。首期不对接海关单一窗口或报关代理系统：报关行回执以文件上传为主，正式申报由授权人员人工提交，客户确认和海关结果由平台人工记录。

费用确认是并行事实，不阻断排柜、预装、PDA 或装柜。装柜完成后，对应已实装范围若客户仍未确认当前有效且已发布费用版本，系统记录“系统默认确认（装柜完成）”；不伪造客户点击，保留 SYSTEM_AUTO_AT_LOADED 来源、费用版本、柜次/入仓码、时间和幂等标识。没有有效费用版本时不得生成零额或伪造确认，须保留费用异常待办。

实际装船、提单、舱单、结关、退税正式资料和船公司节点查询仍属于跨服务或外部业务事实；当前国内货柜链已实现本柜船期编辑、送港、进港和实际开航节点，外部船公司自动查询以及更复杂的提单/舱单凭证继续按独立来源和只读快照接入。若国内页面需要展示，只能消费已确认的跨服务只读快照，并单独定义事件、来源、更新时间和责任边界。

入口与权威数据

入口	本期职责	权威数据	当前状态
客户端“报关资料”	LOADED 后查看本企业资料包，上传/替换/补件，查看报关行回执并确认或打回	Firstleg 报关协同；文件由 File 服务保存	已实现：独立入口 + 订单快捷入口
订单中的“上传资料”	带订单和入仓码上下文进入同一资料包	与独立入口共用 packageId 和接口	现有快捷入口
平台整柜报关工作台	按实际装柜清单通知报关行，管理客户资料、回执轮次、全部确认、整柜正式提交和海关结果	Firstleg 柜级报关、提交批次和结果事实	已实现：四态 + 独立正式申报/海关结果投影
客户端“船期价格”	查询当前企业可见的有效渠道、参考船期、最晚进仓、参考时效和估价	生效价格簿及服务端估价	已实现：独立入口
平台“船期价格表”	上传、解析、核对、发布公共或客户专属价格簿	Firstleg 价格簿版本	已有平台能力

平台端应写“按申报组整理并线下提交”。在跨客户合并规则确认前，默认禁止把不同客户放入同一正式报关单；不得在结论表中把待决规则写成既定能力。

当前实现事实

1. 客户端现在同时提供独立“报关资料”入口和订单快捷入口，二者共用同一资料包和版本历史；仅对 LOADED 后的退税订单开放，按客户/入仓码收集资料、接收报关行回执、提交客户确认并支持打回重做。资料可上传、替换、改关联、删除并保留版本；每轮发送和回执都留痕，客户确认后才进入该客户的 CUSTOMER_CONFIRMED。对应接口和权限见 customs-v1.yaml。

2. 当前柜级状态为 WAITING_CUSTOMER_DOCUMENTS → READY_TO_START → DECLARING → COMPLETED；客户确认轮次、首次发送批次、整柜正式提交、查验/放行和送港子状态通过独立事实和只读投影承载。资料关联以 loadingPlanId、柜级聚合、客户报关案例和整票入仓码为根。

3. 当前 COMPLETED 会发布报关完成事件并参与待发区门禁。契约将“客户资料确认轮次”“整柜正式提交”“海关查验/放行”分开；报关完成后才允许进入待发区，船期事实独立维护。

4. 全买单柜已有独立的二次确认接口和导出契约；它不创建退税客户资料、回执和确认案例，运输节点仍按装柜、待发区、送港和开船事实推进。

5. 客户端现有价格接口为按起运仓查询渠道，以及按指定渠道估算参考费用。/estimate 只返回基础参考费用，不含复杂附加费和最终结算调整；pricingTaxMode 不等同于订单 taxMode。见 fba-pricing-v1.yaml。

6. 原型文档仍有“待原型/部分参考”的历史表述，但当前页面已按现行契约接入；页面范围以客户端路由、平台报关工作台和当前 OpenAPI 为准，不再把原型中的待建入口当作开发缺口。

7. 费用默认确认目前是目标变更，不是现有实现。 当前装柜完成逻辑只会自动发送/发布费用，不能把 SENT 直接当成客户确认；现有费用锁定也主要依赖客户确认时间。实现本轮目标时必须增加确认来源和幂等审计，并改为“客户确认或装柜默认确认 + 已装柜完成后才最终锁定”。部分装载只能确认本次已装范围，余量不能被顺手确认。

8. 本轮报关完成→待发区门禁和船期例外需要保持独立。 报关完成后才允许进入待发区；ROLLED_OVER 只记录新旧船次和运输变更，不回退或重新评估已完成的报关资料、回执和客户确认。

报关资料模型

0. LOADED 后报关完成与待发区

线路	触发时点	顺序	结果
报关线	LOADED 事件产生后	通知报关行 → 收集每个客户资料 → 发报关行 → 接收回执 → 发客户确认 → 打回则重传重发并生成新回执 → 所有客户确认 → 整柜资料交报关行确认 → 正式申报 → 查验/放行	客户确认轮次、整柜正式申报、海关结果
送港线	报关完成并进入待发区后	安排拖车 → 仓库离开 → 送港 → 进港 → 等待船次；装不下时在原柜船期上人工修改船信息并留痕	DEPARTED_WAREHOUSE、PORT_RECEIVED、ROLLED_OVER、实际开船

报关资料未完成时不得进入待发区；完成报关并进入待发区后才推进送港。已进港也不代表已经进入海运；只有船舶真实开航后，才写入海运起点。

客户确认是每个客户报关案例的完成条件；海关放行是整柜正式申报后的外部结果，不能用上传回执或任意“完成文件”代替。

1. 客户报关案例与资料包

报关资料主流程在 LOADED 后启动。每个客户/入仓码在本柜建立一个 customerCustomsCase，再挂载稳定的 packageId 和文件版本。首期不定义文件类型清单和逐项责任人；资料包只需支持文件上传、替换、版本、报关行发送时间、回执文件版本、客户确认/打回人和时间、打回原因、当前 roundNo、客户可见范围和审计记录。

资料包不能只关联整票入仓码。已确认支持一单多柜、拆批和父订单—子订单关系，因此每个关联项保存客户、订单、入仓码和装柜明细引用；部分装柜只展示本柜实际箱数并标记线下处理，不在系统内自动做数量分摊。柜次一旦装柜完成不因甩柜改船而变化，受影响案例不能静默重置回执轮次。

2. 实际装柜绑定快照

资料包与 loadingPlanId、containerBookingId 的关系应通过绑定记录表达，而不是覆盖原资料包。绑定记录至少保存实际装柜明细引用、实装箱数、客户、订单、入仓码、柜次和绑定版本。LOADED 后开始本轮报关时冻结该范围；部分装柜只生成箱数展示和线下处理标记，甩柜改船不使资料绑定和回执轮次失效。

3. 申报组与柜级总览

申报组归属一次实际装柜和一次整柜正式提交，记录成员客户案例、合并关系、报关代理、每轮回执、客户确认结果、正式提交时间、正式业务编号、查验/放行结果和异常历史。跨客户合并在业务确认前默认拒绝；若未来开放，必须增加授权、客户可见投影、组成员冻结快照和取消/重组规则。

柜级总览仅供平台使用，汇总实际装柜行、退税/买单行、缺件、提交批次和门禁结果。客户端接口必须按当前企业裁剪返回，不返回同柜其他客户的名称、数量、资料包 ID、申报组 ID 或异常细节。

4. 买单、退税和混合柜完成条件

三类柜不能用一条“缺回执即阻断”的规则代替：

柜型	LOADED 前	LOADED 后报关线	完成条件与开船影响
全买单	装柜物理门禁独立判断	不进入本报关资料、报关行回执和客户确认流程；继续按买单装柜、导出和运输节点处理	不创建退税报关案例，不以报关资料或回执作为门禁
退税柜	装柜物理门禁独立判断	对每个参与入仓码收集/补件，发送报关行，逐份接收回执并让对应客户确认；打回则重做当前案例	所有退税客户案例确认后才允许整柜正式提交；正式申报后的查验/放行单独记录
混合柜	装柜物理门禁独立判断	仅退税行建立报关资料和回执确认案例；买单行不进入该流程，仍保留买单装柜和导出事实	仅退税客户案例全部确认后才允许提交退税申报批次；不得把买单明细冒充报关确认

同一客户多个入仓码可以共享其授权资料；跨客户物理拼柜不等于允许跨客户正式合报。跨客户合并仍默认禁止，必须有独立授权和客户可见隔离契约。

状态、事实与门禁

建议把状态拆成独立事实面，页面总状态只做投影：

事实面	建议状态	说明
客户报关案例	WAITING_DOCUMENTS、SENT_TO_BROKER、RECEIPT_PENDING_CUSTOMER_CONFIRM、CUSTOMER_CONFIRMED、NEEDS_RESUBMIT、INVALIDATED	每轮 roundNo 保存资料版本、发送时间、报关行回执、客户确认/打回原因；回执上传不等于客户确认
整柜申报批次	WAITING_ALL_CUSTOMER_CONFIRM、ALL_CUSTOMERS_CONFIRMED、FORMAL_SUBMITTED_TO_BROKER、DECLARED、INSPECTION、NO_INSPECTION、RELEASED、REJECTED	所有客户案例确认后才允许整柜正式提交；首期由授权人员人工记录报关行确认和海关结果
送港/船期事实	PORT_DELIVERY_PENDING、DEPARTED_WAREHOUSE、IN_TRANSIT_TO_PORT、PORT_RECEIVED、ROLLED_OVER、VESSEL_DEPARTED	与报关案例独立；进港和甩柜不等于海运中，只有真实开船才进入海运节点
装柜门禁	PASS/BLOCKED	只判断是否满足 LOADED 的已确认前置

上述是首期状态投影。回执首期以文件为主、客户确认整份回执；正式申报由平台授权人员人工提交并回填结果；查验、扣货、补资料和其他情况均由平台人工点击标记异常、选择理由，选择“其他”时填写备注；异常解除也由平台人工点击处理。实际开航首期人工录入，甩柜/改配人工修改原柜船信息并保留原报关事实，不重新评估申报批次。当前四态不能直接承担新流程；收敛时应明确旧状态的映射和删除时点，不保留双协议。

物理 LOADED 门禁必须明确校验以下事实：

1. 真实柜号、预装计划和数量版本完整；
2. PDA 拣货和复核完成，整批提交成功；
3. 空仓、半仓、满仓、锁仓、带锁码照五类证据各有至少一张有效照片，锁码文本已保存；
4. 数量守恒、无未解决 PDA 异常。

LOADED 后创建报关案例；报关案例完成整柜正式申报并达到报关完成条件后，才允许进入待发区并创建/推进送港任务。送港任务继续校验装柜完成、真实柜号、订舱/拖车等运输条件。到港后如船舱不足记录 ROLLED_OVER；只有实际 VESSEL_DEPARTED 才进入海运节点。报关放行、送港和甩柜不能反向作为 LOADED 的前置，甩柜也不改变已完成的报关事实。

每个写动作都需要 Idempotency-Key、expectedVersion、规范化请求哈希、乐观锁冲突码、审计事件和结果回放。上传、替换、改关联、补件、审核、提交批次、回执上传和门禁确认不得仅靠前端推进。

权限、文件与接口边界

现有报关接口使用 merchant:order:view/edit 和 platform:firstleg:customs:list/manage。新增独立入口前必须确认是复用还是拆分为报关专用权限，并落到客户端路由、导航、Controller、OpenAPI x-permission、IAM 初始化 SQL 和服务端对象级校验：

• 客户查看、上传/替换、补件确认和下载分别校验当前企业、订单/子订单、入仓明细和客户可见标记；不能信任请求中的 tenantId、订单 ID 或入仓码。
• 平台查看、审核/退回、生成提交批次、上传回执和发布结果分别授权；列表权限只包含详情只读，写权限独立。
• File 文件类型、业务 ID、客户归属、版本、冻结和下载审计必须定义。现有 LOADING_LIST_CUSTOMS_SOURCE、LOADING_LIST_CUSTOMS_RECEIPT、LOADING_LIST_CUSTOMS_RESULT 只负责不可变文件对象，不能替代客户案例、提交批次和海关结果对象；正式申报与海关结果的独立接入见专题设计。
• File 上传成功但业务写入失败、业务写入成功但 File 失败、替换/作废和重试都要有补偿或可重放规则；不能产生越权文件或孤儿记录。

独立客户列表、详情、待办计数和平台筛选必须补充明确的路径、分页、稳定排序、筛选参数、空态/无权限响应和错误码。不能只写“新增列表”或继续复用单订单查询接口。

船期价格接入

展示边界

客户页只展示当前企业可见的有效价格簿快照：渠道、起运仓、目的地、pricingTaxMode、计费单位、单价、币种、参考船期、最晚进仓、参考时效、附加费说明、价格簿版本和更新时间。价格簿中的预计船期是参考文本，不是已订舱 ETD、实际开船或到港节点；时区、有效期、来源和过期展示必须明确。

客户专属与公共价格按版本作用域选择：先选择当前企业专属 ACTIVE 版本；只有不存在专属 ACTIVE 版本时才选择公共 ACTIVE 版本，不能按单条费率缺行再逐行回退。页面展示业务版本号或生效时间，不直接把内部 priceBookVersionId 当作用户可见编号。

批量估价契约

若要跨渠道列表展示，服务端新增批量估价契约，至少定义：起运仓、目的类型/目的地、渠道候选、重量、体积、pricingTaxMode、版本快照、批量上限、超时、无命中错误、计费量、单位、币种、基础金额、未包含附加费、舍入规则和排序规则。不得由浏览器自行计算或逐渠道扇出。

“价格优选”只有在币种、目的地、税模式、计费口径和附加费范围可比时才允许启用；否则只展示参考结果。订单创建时必须重新校验渠道资格和生效版本，明确旧报价失效、金额变化和重新报价的用户提示，不把客户端显示金额当成最终结算金额。

价格导出如需上线，应另定义客户可见字段、公共/专属价格隔离、导出审计、快照版本、文件保留期限和下载权限；在这些规则确认前不纳入本期上线。

实施顺序与进入条件

1. 冻结业务规则：确认文件可上传即可、回执轮次、打回重做、所有客户确认、整柜正式申报、异常理由/备注、甩柜/改配和跨客户合并；已确认规则以需求确认表为准。
2. 先做服务端契约：完成 customerCustomsCase、资料版本、报关行回执轮次、客户确认、整柜申报批次、送港/进港/甩柜/开船事实、状态投影、权限、幂等、审计、File 类别和初始化 SQL；同步更新 OpenAPI、Gateway、IAM 和相关消费者。
3. 接入客户入口：独立列表/详情与订单快捷入口共用 packageId；仅在 LOADED 后进入本柜报关案例，覆盖资料上传、报关行回执查看、确认、打回、重新上传和新回执版本。
4. 接入平台协同：LOADED 后按最终实装快照通知报关行，逐客户处理资料和回执，全部客户确认后提交整柜资料；平台人工记录正式申报，并通过异常节点选择查验、扣货、补资料或其他理由，必要时填写备注和处理结果。送港线独立接入拖车、进港、甩柜和实际开船。
5. 接入船期价格：先复用有效价格簿和单渠道参考估价，再实现批量估价；批量列表、排序和导出必须先通过接口和价格可比性评审。

已确认的简化规则

问题	阻断范围	需要形成的结论
报关资料上传	客户案例、整柜提交	不区分文件类型；有文件即可上传、替换和保留版本
客户确认/打回原因和回执轮次	客户案例、整柜提交	回执版本、roundNo、确认人、打回重做规则
海关查验、扣货、补资料和其他异常	整柜申报批次、客户展示	平台人工标记异常并选择理由；选择“其他”时填写备注，不接短信或自动海关系统
送港、进港、甩柜、改配船次和实际开船事件	待发区、送港线、海运节点	事实字段、重试规则、客户通知和船次历史；首期人工录入实际开航，改配人工修改原柜船信息但不改变已完成报关事实
价格比较、导出、报价有效期和金额变化提示	客户报价页、下单	统一币种/税模式/附加费和失效处理

最低验收矩阵

• 客户 A 无法查询、上传、替换或下载客户 B 的资料、回执、价格和导出文件。
• 独立入口与订单快捷入口返回同一 packageId、版本历史和待办结果，不产生双历史。
• 同一幂等键同请求只产生一次记录；同键不同请求、版本冲突、并发换柜和重复回执均返回明确业务错误。
• LOADED 后每个客户案例都能经历“资料上传→报关行回执→客户确认”；打回后只重开对应案例，重新上传、重新发送并产生新回执轮次，其他客户历史不被覆盖。
• 所有客户案例均 CUSTOMER_CONFIRMED 后，平台才允许生成整柜正式提交；正式提交后分别验收查验、不查验放行和其他海关结果。
• 缺 PDA 结果、缺五类证据、真实柜号或数量不守恒时，LOADED 门禁失败；报关完成后才进入待发区，再验收离仓、进港和甩柜；只有真实开船才进入海运节点，甩柜不重做已完成报关。
• 全买单柜、退税柜和混合柜分别验证状态、权限、导出、回执和门禁结果。
• 价格无命中、失效版本、跨渠道批量估价、不同币种/税模式、附加费说明和订单创建重验均有可验证结果。
• 页面覆盖加载、空态、失败、无权限、过期和数据冲突；客户端按 1920×1080、100% 缩放人工验收。

接入核对入口

• 客户端订单与现有报关：apps/client-web/src/modules/first-leg/routes.ts、views/FirstLegOrdersView.vue、components/CustomsDocumentsDialog.vue、api/customs.ts。
• 客户端导航和新页面：apps/client-web/src/navigation/clientNavigation.ts 及对应页面注册、权限和 release 配置。
• 平台整柜报关：apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue、api/platformContainerCustoms.ts。
• 后端报关：../baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/customs/container/、customs-v1.yaml、phase3-container-customs-schema.sql。
• 报价：../apps/client-web/src/modules/first-leg/api/firstLeg.ts、../apps/admin-web/src/modules/fba-pricing/carrier-rates/、fba-pricing-v1.yaml。
• 国内边界、状态和门禁：国内货柜履约 README、国内货柜履约开发规划（归档）、国内货柜履约需求确认表。