优化
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
# 报关资料与船期价格接入梳理
|
||||
|
||||
本文梳理企业客户端新增的“报关资料”“船期价格”独立入口，及其与当前客户上传资料、平台整柜报关的关系。当前阶段用于产品和业务评审，区分原型展示、已有系统事实与建议接入方式；尚未确认的规则不作为开发验收口径。
|
||||
|
||||
## 结论与业务边界
|
||||
|
||||
| 入口 | 面向谁 | 建议承载的对象和动作 | 权威数据 |
|
||||
|---|---|---|---|
|
||||
| 客户端“报关资料” | 当前企业成员 | 查看本企业退税订单/入仓码的资料进度，提交、补正资料，核对平台转发的预录单，下载已交付的退税文件 | 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/`；报价文本、订舱预计时间和实际船节点各自保留事实来源。
|
||||
Reference in New Issue
Block a user