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

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

本文梳理企业客户端新增的“报关资料”“船期价格”独立入口，及其与当前客户上传资料、平台整柜报关的关系。当前阶段用于产品和业务评审，区分原型展示、已有系统事实与建议接入方式；尚未确认的规则不作为开发验收口径。

结论与业务边界

入口	面向谁	建议承载的对象和动作	权威数据
客户端“报关资料”	当前企业成员	查看本企业退税订单/入仓码的资料进度，提交、补正资料，核对平台转发的预录单，下载已交付的退税文件	Firstleg 报关业务；文件由 File 保存
客户端订单中的“上传资料”	当前企业成员	从订单进入同一份客户报关资料包，预选当前订单/入仓码；作为快捷入口	与独立“报关资料”共用同一业务对象和接口
平台整柜报关工作台	平台客服、报关操作员	按真实货柜汇总各客户资料，逐票核对，组织合并申报，线下交报关行，回填预录、申报、放行与完成凭证	Firstleg 柜级聚合和申报记录
客户端“船期价格”	当前企业成员	查询适用于本企业的有效渠道、参考船期、最晚进仓、时效和估价；可从结果去下单	Firstleg 当前生效价格簿及服务端估价
平台“船期价格表”	平台定价人员	上传、核对、发布公共或客户专属价格簿	Firstleg 价格簿版本

“报关资料”是客户侧资料协作入口，不代替平台统一申报；“船期价格”是下单前报价查询，不代表某个已订舱货柜的实时船司节点。客户独立入口与订单快捷入口应读取同一份数据，避免出现两套上传历史或互相矛盾的状态。

资料来源和当前实现

• 业务文件《出口退税报关全流程》提出客户提交、客服接收与核对、报关行预录、客户确认、正式申报、审单/放行、查验/甩柜、装船/结关及退税资料交付。它描述目标业务流程，其中“报关单在申报前提交”“放行后查验”“装柜完成即可加急提供退税资料”等表述仍需业务解释。
• 外部原型 C:/Users/BY-OY/Desktop/样式/官网头程下单 2/官网头程下单/优化调整.html 在客户工作台左侧增加“船期价格”“报关资料”。“报关资料”目前是共用列表模板和三条演示记录，列出资料编号、关联订单、审核状态、资料类型、申报品名、文件数量、提交时间；新增、详情、处理按钮只弹提示，并未给出真实表单和状态流。“船期价格”有目的仓/渠道列表及重量、体积、目的仓查询区，原型价格由脚本生成，估价算法是有体积即选 CBM，否则选 KG，仅可作为交互参考。
• 当前客户端仅在订单列表的“上传资料”队列和订单操作中开放报关弹框，且仅对服务端确认已装柜的退税订单开放。弹框能上传任意文件、将一份文件关联同柜本企业一个或多个入仓码、替换/删除并查看版本；开始报关后只读，整柜完成后可下载平台回传文件。
• 当前平台按已完成装柜计划生成整柜报关聚合。状态仅有待客户资料、可开始、报关中、已完成；客户资料覆盖齐全后平台开始并冻结，混合/退税柜逐份上传一对一完成文件，全买单柜可人工确认完成。完成状态参与国内离仓门禁，但不表示海关已结关。
• 当前价格簿已有公共和客户专属生效版本，客户专属优先，缺失才取公共。客户端已有按起运仓查询可选渠道、按指定渠道及目的地估价的接口；平台有价格簿上传、解析、仓库映射和发布页面。现有客户端没有原型要求的跨渠道价格列表或下载价格表入口。

报关资料如何接入

业务对象

建议把客户报送与平台申报分开建模，同时让它们在同一柜内关联：

1. 客户资料包：归属客户，关联订单及入仓码，记录资料清单版本、每类文件及版本、提交人/时间、补件要求、客服核对结果。客户能看到本企业的资料包；在关联真实柜次前也能先提交，不再被“装柜完成”限制。
2. 柜内申报组：归属平台及真实货柜，固定本次申报覆盖的客户资料包/入仓码、合并关系和报关行。一个柜可有多个申报组；跨客户是否允许归到同一个正式报关单，需业务明确后才能设门禁。申报组保存预录单版本、客户确认、正式报关单号、回执和异常历史。
3. 货柜报关总览：汇总柜内全部应报关的实际装柜货物、退税/买单票数、缺件数、申报组和海关结果。当前 containerBookingId 继续作为货柜关联键；客户界面只展示自己的订单、入仓码和资料，不泄露同柜其他客户信息。

客户资料包与实际装柜覆盖要分阶段校验：提前上传时按订单/入仓码归属校验；排柜后展示拟入柜关系；开始正式申报前以实际装柜清单核对覆盖、数量和版本并冻结申报快照。分柜、换柜、部分装柜时不能静默沿用旧柜的覆盖结论。

建议流转和责任人

阶段	责任人	系统应记录的关键事实	客户可见结果
提交与补件	客户	清单项、文件版本、订单/入仓码范围、提交时间	待平台接收、待补件或已提交
接收与逐票核对	客服	接收时间、核对结论、问题项和退回原因	核对中、待补件、资料已核对
组单与交报关行	平台	申报组、合并范围、报关行、交付批次/时间及附件	已提交报关行；只显示本企业相关部分
预录单核对	报关行线下反馈；客服上传；客户确认	预录单版本、建议/修改点、客户确认人和时间；修改后重新确认	待确认预录单、已确认或待修改
正式申报与海关反馈	平台据凭证录入，未来可对接	申报时间、报关单号、回执、退单/补件/查验/放行事实	报关中、待补件、查验中、已放行
船运与退税交付	平台及已有船运事实	实际装船、提单、舱单/结关凭证、交付文件和时间	已装船、已结关、可下载正式资料

页面状态应由这些事实投影生成，不能只靠人工把一个总状态从“报关中”改为“已完成”。资料审核、申报、海关结果、船运和资料交付应分别展示；退单、查验、甩柜等异常保留可追溯的子状态与处理记录，不覆盖已有事实。

现有实现的影响

• 客户端：在 first-leg 业务域新增独立列表/详情路由，订单上的“上传资料”改为带订单上下文进入同一资料包。列表按登录企业查询，支持订单号/入仓码、资料状态、提交时间筛选；待办数由服务端返回，原型中的角标“2”不能写死。
• 平台端：在整柜报关工作台增加柜内客户资料矩阵、客服核对、申报组、预录单与回执时间线；货柜详情保留报关入口，列表应能按缺件、待核对、待客户确认、待申报、异常筛选。买单柜继续单独展示，不把它伪装成有退税客户资料。
• 服务端：当前 fl_customs_customer_document 的“任意文件 + 多入仓码”版本能力可作为文件基础，但需要类型化清单、前置资料包、客服核对与申报组；现有 WAITING_CUSTOMER_DOCUMENTS → READY_TO_START → DECLARING → COMPLETED 不能表达新流程。Controller、DTO、OpenAPI、初始化 SQL、权限和状态投影必须按新契约同步收敛。
• 文件与权限：客户只管理本企业未冻结资料；平台能按柜查看和处理，正式申报、回执录入与结果发布使用独立写权限。文件下载继续经受控入口校验归属，不暴露 File 内部 ID 作为业务编号。
• 既有离仓门禁：当前整柜 COMPLETED 才自动尝试确认国内离仓。新流程需明确“放行/可离仓”与“开船后结关/正式退税资料完成”是两个不同时间点，避免把结关或文件交付误设为国内离仓前置条件。调整时同步核对 CustomsAutoDispatchCoordinator、出仓门禁和船节点事实。

船期价格如何接入

客户端独立页建议展示“当前企业适用的有效报价”，并把渠道报价与实际订舱区分：

原型字段/动作	建议接入来源	需要注意
渠道、起运仓、目的仓、包税方式、单位、单价	生效价格簿的渠道和费率行	客户专属优先，否则公共；只展示当前企业可用范围，不向客户端暴露其他客户价格
参考时效、最晚进仓、船期、附加费说明	生效价格簿渠道快照	当前多为文本，标记“参考”；不要当作已订舱 ETD 或实际船节点
重量、体积、目的仓的查询结果	Firstleg 服务端统一候选筛选及逐渠道估价	当前 /estimate 只能估算指定渠道；列表页若要一次返回多个可比渠道，需新增批量查询/估价契约，避免浏览器自行计算或逐行扇出
预估运费	服务端价格模型、计费方式和客户生效版本	原型“有体积就按 CBM”不适用于所有价格模型；结果显示计费量、单位、币种、价格版本和参考说明
下载价格表	由服务端生成当前企业可见价格快照	是否开放原始 XLSX、导出字段及客户专属信息边界待确认；不能直接下载平台上传的全部原件

原型中“价格优选”“时间优选”若进入正式产品，价格排序需基于同币种、同计费口径的完整估价；时效若只有“约 25–30 天”等自由文本，应先统一可比较的数值规则。没有可信比较基础时只展示渠道和参考信息，不给出误导性排名。

这页是客户查询报价的入口。平台现有价格簿页面继续负责价格发布；实际货柜船期来自订舱及后续船节点，不由价格簿反向覆盖。客户从报价页去创建订单时，可携带渠道、起运仓和目的仓作为表单预选，但创建时仍由服务端重验当前生效版本和渠道资格。

建议实施顺序

1. 先统一模型和用词：确认资料包、申报组、柜级总览、放行、结关、交付的定义，以及客户/平台分别可见的状态；确定资料清单和合并规则。产出状态图、权限矩阵和文件类型清单。
2. 打通客户资料入口：让独立“报关资料”页和订单快捷入口共用前置资料包；允许装柜前提交，平台能够接收、逐票核对并要求补件。此阶段先解决提交时点与资料完整性。
3. 接入统一申报协作：平台按真实装柜清单组单、交报关行、上传预录单，客户确认后记录正式申报及海关反馈；核对离仓门禁的触发事实。
4. 补齐异常与交付：退单、查验、甩柜、改配、结关、正式资料交付与通知按已确认规则接入，保留每次修改和凭证历史。
5. 上线船期价格查询：先基于生效价格簿提供客户可见列表和服务端批量估价，再根据已确认的导出、排序和展示规则完善页面。

业务待确认

1. 提交时点：客户最晚何时提交？装柜前已上传资料在换柜/拆柜时如何重新关联，谁负责确认最终申报范围？
2. 资料清单：业务文档列出的“发票、箱单、合同、报关单”中，申报前的“报关单”实际指客户提供的哪种单据？清单是否随客户、国家、渠道和货物类型变化？
3. 合并规则：同客户同柜多票何时自动合并，何时允许分组；跨客户是否绝对不能同一报关单；合并申报的业务编号和取消/重组规则是什么？
4. 预录确认：客户确认的是整份预录单文件，还是金额、重量、品名、HS 编码等结构化字段？修改后谁重新发起确认？
5. 报关行与海关回传：首期是否仍由客服线下收发、人工录入并上传凭证；报关单号能否从可信接口取得，若不能则不得写“系统自动抓取”？
6. 放行、查验、甩柜顺序：业务文档将查验和甩柜列在放行后，应确认实际可发生的时点、放行是否撤销、漏装与改配是否需要重新申报，以及异常关闭条件。
7. 退税交付：装柜后可加急提供的具体文件是什么，需如何标记“预提供”；正式可用于退税的文件清单及结关判定由谁确认？
8. 全买单柜：是否继续走独立简化流程，哪些申报和海关节点仍需记录？
9. 船期价格：客户是否能下载完整价格表；价格“优选”和时效“优选”如何比较；公开报价的有效期、币种、附加费范围与实际结算提示如何表述？

接入核对入口

• 客户导航与订单：apps/client-web/src/modules/first-leg/routes.ts、views/FirstLegOrdersView.vue、components/CustomsDocumentsDialog.vue、api/customs.ts。
• 平台整柜报关：apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue；后端 baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/customs/container/、src/main/resources/openapi/customs-v1.yaml、src/main/resources/db/phase3-container-customs-schema.sql。
• 报价：apps/admin-web/src/modules/fba-pricing/carrier-rates/；后端 MerchantPriceBookController、MerchantPriceBookService、PriceBookDtos、fba-pricing-v1.yaml；客户端现有 apps/client-web/src/modules/first-leg/api/firstLeg.ts。
• 离仓与船节点：CustomsAutoDispatchCoordinator、OutboundDispatchService、portschedule/；报价文本、订舱预计时间和实际船节点各自保留事实来源。