html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-09-24 13:43:53 +08:00
parent 6116ad61e1
commit d8be2ccdef
19 changed files with 801 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files
国内货柜履约/报关资料与船期价格接入梳理.md
+150 -69
View File
@@ -1,99 +1,180 @@
# 报关资料与船期价格接入梳理
本文梳理企业客户端新增的“报关资料”“船期价格”独立入口，及其与当前客户上传资料、平台整柜报关的关系。当前阶段用于产品和业务评审，区分原型展示、已有系统事实与建议接入方式；尚未确认的规则不作为开发验收口径。
本文是企业客户端“报关资料”“船期价格”入口的产品与接口评审稿。文中明确区分三类内容：
## 结论与业务边界
- **已确认**：可进入开发和验收口径。
- **建议**：用于收敛模型，业务确认前不得作为验收承诺。
- **待确认**：必须在对应开发门禁前形成结论、负责人和日期。
| 入口 | 面向谁 | 建议承载的对象和动作 | 权威数据 |
**基线**：以用户 2026-09-24 对本流程的直接确认和本联合评审稿为准；旧版需求表、README 和开发规划中与本流程冲突的门禁必须修改，不能继续作为上位约束。
## 先锁定的范围
国内货柜履约的物理装柜节点为 `LOADED`。`LOADED` 后同时启动两条独立流程：
1. **报关线**：通知报关行，收集每个客户资料，发送报关行，接收报关行回执并发客户确认；客户认为不正确时打回、重新上传、重新发送并生成新回执，循环至柜内所有客户均确认；全部确认后，再将整柜资料提交报关行确认，由报关行正式申报，记录查验、不查验放行或其他海关结果。
2. **送港线**：安排拖车、从仓库发运、送港、进港；港口容量不足时记录甩柜和改配船次。送港线可以早于或晚于报关线完成，`PORT_RECEIVED` 不等于海运中，只有船舶真实开航后才进入海运节点。
两条线互不作为 `LOADED` 的前置，也不要求一条线完成后才能启动另一条线。首期不对接海关单一窗口或报关代理系统，由授权人员人工录入报关行回执、客户确认和海关结果。
费用确认是并行事实，不阻断排柜、预装、PDA 或装柜。装柜完成后，对应已实装范围若客户仍未确认当前有效且已发布费用版本，系统记录“系统默认确认（装柜完成）”；不伪造客户点击，保留 `SYSTEM_AUTO_AT_LOADED` 来源、费用版本、柜次/入仓码、时间和幂等标识。没有有效费用版本时不得生成零额或伪造确认，须保留费用异常待办。
出仓后的实际装船、提单、舱单、结关、退税正式资料和船公司节点查询属于后续或海外仓业务事实，不作为本期国内货柜履约页面、接口和验收范围。若国内页面需要展示，只能消费已确认的跨服务只读快照，并单独定义事件、来源、更新时间和责任边界。
## 入口与权威数据
| 入口 | 本期职责 | 权威数据 | 当前状态 |
|---|---|---|---|
| 客户端“报关资料” | 当前企业成员 | 查看本企业退税订单/入仓码的资料进度，提交、补正资料，核对平台转发的预录单，下载已交付的退税文件 | Firstleg 报关业务；文件由 File 保存 |
| 客户端订单中的“上传资料” | 当前企业成员 | 从订单进入同一份客户报关资料包，预选当前订单/入仓码；作为快捷入口 | 与独立“报关资料”共用同一业务对象和接口 |
| 平台整柜报关工作台 | 平台客服、报关操作员 | 按真实货柜汇总各客户资料，逐票核对，组织合并申报，线下交报关行，回填预录、申报、放行与完成凭证 | Firstleg 柜级聚合和申报记录 |
| 客户端“船期价格” | 当前企业成员 | 查询适用于本企业的有效渠道、参考船期、最晚进仓、时效和估价；可从结果去下单 | Firstleg 当前生效价格簿及服务端估价 |
| 平台“船期价格表” | 平台定价人员 | 上传、核对、发布公共或客户专属价格簿 | Firstleg 价格簿版本 |
| 客户端“报关资料” | `LOADED` 后查看本企业资料包，上传/替换/补件，查看报关行回执并确认或打回 | Firstleg 报关协同；文件由 File 服务保存 | **目标新增独立入口** |
| 订单中的“上传资料” | 带订单和入仓码上下文进入同一资料包 | 与独立入口共用 packageId 和接口 | **现有快捷入口** |
| 平台整柜报关工作台 | 按实际装柜清单通知报关行，管理客户资料、回执轮次、全部确认、整柜正式提交和海关结果 | Firstleg 柜级报关与提交批次 | **已有四态，需收敛新投影** |
| 客户端“船期价格” | 查询当前企业可见的有效渠道、参考船期、最晚进仓、参考时效和估价 | 生效价格簿及服务端估价 | **建议新增独立入口** |
| 平台“船期价格表” | 上传、解析、核对、发布公共或客户专属价格簿 | Firstleg 价格簿版本 | **已有平台能力** |
“报关资料”是客户侧资料协作入口，不代替平台统一申报；“船期价格”是下单前报价查询，不代表某个已订舱货柜的实时船司节点。客户独立入口与订单快捷入口应读取同一份数据，避免出现两套上传历史或互相矛盾的状态。
平台端应写“按申报组整理并线下提交”。在跨客户合并规则确认前，默认禁止把不同客户放入同一正式报关单；不得在结论表中把待决规则写成既定能力。
## 资料来源和当前实现
## 当前实现事实
- 业务文件《出口退税报关全流程》提出客户提交、客服接收与核对、报关行预录、客户确认、正式申报、审单/放行、查验/甩柜、装船/结关及退税资料交付。它描述目标业务流程，其中“报关单在申报前提交”“放行后查验”“装柜完成即可加急提供退税资料”等表述仍需业务解释。
- 外部原型 `C:/Users/BY-OY/Desktop/样式/官网头程下单 2/官网头程下单/优化调整.html` 在客户工作台左侧增加“船期价格”“报关资料”。“报关资料”目前是共用列表模板和三条演示记录，列出资料编号、关联订单、审核状态、资料类型、申报品名、文件数量、提交时间；新增、详情、处理按钮只弹提示，并未给出真实表单和状态流。“船期价格”有目的仓/渠道列表及重量、体积、目的仓查询区，原型价格由脚本生成，估价算法是有体积即选 CBM，否则选 KG，仅可作为交互参考。
- 当前客户端仅在订单列表的“上传资料”队列和订单操作中开放报关弹框，且仅对服务端确认已装柜的退税订单开放。弹框能上传任意文件、将一份文件关联同柜本企业一个或多个入仓码、替换/删除并查看版本；开始报关后只读，整柜完成后可下载平台回传文件。
- 当前平台按已完成装柜计划生成整柜报关聚合。状态仅有待客户资料、可开始、报关中、已完成；客户资料覆盖齐全后平台开始并冻结，混合/退税柜逐份上传一对一完成文件，全买单柜可人工确认完成。完成状态参与国内离仓门禁，但不表示海关已结关。
- 当前价格簿已有公共和客户专属生效版本，客户专属优先，缺失才取公共。客户端已有按起运仓查询可选渠道、按指定渠道及目的地估价的接口；平台有价格簿上传、解析、仓库映射和发布页面。现有客户端没有原型要求的跨渠道价格列表或下载价格表入口。
1. 客户端当前通过订单接口查询报关资料，现状主要只对服务端确认已完成装柜的退税订单开放；本目标稿调整为 `LOADED` 后启动本柜报关批次，按客户/入仓码收集资料、接收报关行回执、提交客户确认并支持打回重做。资料可上传、替换、改关联、删除并保留版本；每轮发送和回执都要留痕，客户确认后才进入该客户的 `CUSTOMER_CONFIRMED`。对应接口和权限见 [customs-v1.yaml](C:/Users/BY-OY/Desktop/code/chongchong-global/baiyue-firstleg/src/main/resources/openapi/customs-v1.yaml:48)。
2. 当前柜级状态为 WAITING_CUSTOMER_DOCUMENTS → READY_TO_START → DECLARING → COMPLETED；目标需要增加客户确认轮次、整柜正式提交、查验/放行和送港子状态。资料关联以 loadingPlanId、柜级聚合、客户报关案例和整票入仓码为根。
3. 当前 COMPLETED 会发布报关完成事件并参与离仓门禁。目标契约改为“客户资料确认轮次”“整柜正式提交”“海关查验/放行”分开；报关线和送港线独立维护，不能让某一条线的完成事件直接代替另一条线。
4. 全买单柜已有独立的二次确认接口和导出契约，本期继续保留；需要补齐其在客户确认轮次、整柜正式申报、海关结果和送港/开船状态中的位置。
5. 客户端现有价格接口为按起运仓查询渠道，以及按指定渠道估算参考费用。/estimate 只返回基础参考费用，不含复杂附加费和最终结算调整；pricingTaxMode 不等同于订单 taxMode。见 [fba-pricing-v1.yaml](C:/Users/BY-OY/Desktop/code/chongchong-global/baiyue-firstleg/firstleg/src/main/resources/openapi/fba-pricing-v1.yaml:130)。
6. 仓库内原型与页面索引仍将报关上传、回执下载和出仓前船期资料列为待原型或部分参考；外部个人电脑路径不能作为唯一事实来源。页面范围需同步 [国内货柜履约页面与原型清单.md](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/国内货柜履约页面与原型清单.md:30)。
## 报关资料如何接入
7. **费用默认确认目前是目标变更，不是现有实现。** 当前装柜完成逻辑只会自动发送/发布费用，不能把 `SENT` 直接当成客户确认；现有费用锁定也主要依赖客户确认时间。实现本轮目标时必须增加确认来源和幂等审计，并改为“客户确认或装柜默认确认 + 已装柜完成后才最终锁定”。部分装载只能确认本次已装范围，余量不能被顺手确认。
### 业务对象
8. **本轮报关/送港并行模型目前也是目标变更。** 当前代码的四态报关和离仓门禁不能直接证明已具备 `customerCustomsCase`、`roundNo`、报关行回执确认、客户打回重做、所有客户汇总、`ROLLED_OVER` 和 `VESSEL_DEPARTED` 事实；开发必须把这些作为新契约实现，不能只在现有页面上增加状态文案。
建议把客户报送与平台申报分开建模，同时让它们在同一柜内关联：
## 报关资料模型
1. **客户资料包**：归属客户，关联订单及入仓码，记录资料清单版本、每类文件及版本、提交人/时间、补件要求、客服核对结果。客户能看到本企业的资料包；在关联真实柜次前也能先提交，不再被“装柜完成”限制。
2. **柜内申报组**：归属平台及真实货柜，固定本次申报覆盖的客户资料包/入仓码、合并关系和报关行。一个柜可有多个申报组；跨客户是否允许归到同一个正式报关单，需业务明确后才能设门禁。申报组保存预录单版本、客户确认、正式报关单号、回执和异常历史。
3. **货柜报关总览**：汇总柜内全部应报关的实际装柜货物、退税/买单票数、缺件数、申报组和海关结果。当前 `containerBookingId` 继续作为货柜关联键；客户界面只展示自己的订单、入仓码和资料，不泄露同柜其他客户信息。
### 0. `LOADED` 后报关线与送港线
客户资料包与实际装柜覆盖要分阶段校验：提前上传时按订单/入仓码归属校验；排柜后展示拟入柜关系；开始正式申报前以实际装柜清单核对覆盖、数量和版本并冻结申报快照。分柜、换柜、部分装柜时不能静默沿用旧柜的覆盖结论。
### 建议流转和责任人
| 阶段 | 责任人 | 系统应记录的关键事实 | 客户可见结果 |
| 线路 | 触发时点 | 顺序 | 结果 |
|---|---|---|---|
| 提交与补件 | 客户 | 清单项、文件版本、订单/入仓码范围、提交时间 | 待平台接收、待补件或已提交 |
| 接收与逐票核对 | 客服 | 接收时间、核对结论、问题项和退回原因 | 核对中、待补件、资料已核对 |
| 组单与交报关行 | 平台 | 申报组、合并范围、报关行、交付批次/时间及附件 | 已提交报关行；只显示本企业相关部分 |
| 预录单核对 | 报关行线下反馈；客服上传；客户确认 | 预录单版本、建议/修改点、客户确认人和时间；修改后重新确认 | 待确认预录单、已确认或待修改 |
| 正式申报与海关反馈 | 平台据凭证录入，未来可对接 | 申报时间、报关单号、回执、退单/补件/查验/放行事实 | 报关中、待补件、查验中、已放行 |
| 船运与退税交付 | 平台及已有船运事实 | 实际装船、提单、舱单/结关凭证、交付文件和时间 | 已装船、已结关、可下载正式资料 |
| 报关线 | `LOADED` 事件产生后 | 通知报关行 → 收集每个客户资料 → 发报关行 → 接收回执 → 发客户确认 → 打回则重传重发并生成新回执 → 所有客户确认 → 整柜资料交报关行确认 → 正式申报 → 查验/放行 | 客户确认轮次、整柜正式申报、海关结果 |
| 送港线 | `LOADED` 事件产生后 | 安排拖车 → 仓库离开 → 送港 → 进港 → 等待船次；装不下时甩柜/改配 | `DEPARTED_WAREHOUSE`、`PORT_RECEIVED`、`ROLLED_OVER`、实际开船 |
页面状态应由这些事实投影生成，不能只靠人工把一个总状态从“报关中”改为“已完成”。资料审核、申报、海关结果、船运和资料交付应分别展示；退单、查验、甩柜等异常保留可追溯的子状态与处理记录，不覆盖已有事实。
两条线路可以先后不同。客户资料未确认只阻断报关线的整柜正式提交，不阻断送港；已进港也不代表报关完成或已经进入海运。只有船舶真实开航后，才写入海运起点。
### 现有实现的影响
客户确认是每个客户报关案例的完成条件；海关放行是整柜正式申报后的外部结果，不能用上传回执或任意“完成文件”代替。
- 客户端：在 `first-leg` 业务域新增独立列表/详情路由，订单上的“上传资料”改为带订单上下文进入同一资料包。列表按登录企业查询，支持订单号/入仓码、资料状态、提交时间筛选；待办数由服务端返回，原型中的角标“2”不能写死。
- 平台端：在整柜报关工作台增加柜内客户资料矩阵、客服核对、申报组、预录单与回执时间线；货柜详情保留报关入口，列表应能按缺件、待核对、待客户确认、待申报、异常筛选。买单柜继续单独展示，不把它伪装成有退税客户资料。
- 服务端：当前 `fl_customs_customer_document` 的“任意文件 + 多入仓码”版本能力可作为文件基础，但需要类型化清单、前置资料包、客服核对与申报组；现有 `WAITING_CUSTOMER_DOCUMENTS → READY_TO_START → DECLARING → COMPLETED` 不能表达新流程。Controller、DTO、OpenAPI、初始化 SQL、权限和状态投影必须按新契约同步收敛。
- 文件与权限：客户只管理本企业未冻结资料；平台能按柜查看和处理，正式申报、回执录入与结果发布使用独立写权限。文件下载继续经受控入口校验归属，不暴露 File 内部 ID 作为业务编号。
- 既有离仓门禁：当前整柜 `COMPLETED` 才自动尝试确认国内离仓。新流程需明确“放行/可离仓”与“开船后结关/正式退税资料完成”是两个不同时间点，避免把结关或文件交付误设为国内离仓前置条件。调整时同步核对 `CustomsAutoDispatchCoordinator`、出仓门禁和船节点事实。
### 1. 客户报关案例与资料包
## 船期价格如何接入
报关资料主流程在 `LOADED` 后启动。每个客户/入仓码在本柜建立一个 `customerCustomsCase`，再挂载稳定的 `packageId` 和文件版本。案例至少记录：订单/子订单、入仓码或入仓明细、实际装载数量、资料清单版本、每个清单项的文件版本、报关行发送时间、回执版本、客户确认/打回人和时间、打回原因、当前 `roundNo`、客户可见范围和审计记录。
客户端独立页建议展示“当前企业适用的有效报价”，并把渠道报价与实际订舱区分：
资料包不能只关联整票入仓码。已确认支持一单多柜、拆批和父订单—子订单关系，因此每个关联项还要保存实际装载数量、单位、子订单/装柜明细引用和快照版本。换柜、拆柜或部分装柜时，只重算受影响客户案例，不能静默沿用旧回执轮次。
| 原型字段/动作 | 建议接入来源 | 需要注意 |
### 2. 实际装柜绑定快照
资料包与 loadingPlanId、containerBookingId 的关系应通过绑定记录表达，而不是覆盖原资料包。绑定记录至少保存实际装柜明细、数量/UOM、客户、订单、入仓码、柜次和绑定版本。`LOADED` 后开始本轮报关时冻结该快照；换柜、拆柜或部分装柜必须使受影响案例的资料绑定和回执轮次失效并生成新版本，不能静默沿用旧覆盖结论。
### 3. 申报组与柜级总览
申报组归属一次实际装柜和一次整柜正式提交，记录成员客户案例、合并关系、报关代理、每轮回执、客户确认结果、正式提交时间、正式业务编号、查验/放行结果和异常历史。跨客户合并在业务确认前默认拒绝；若未来开放，必须增加授权、客户可见投影、组成员冻结快照和取消/重组规则。
柜级总览仅供平台使用，汇总实际装柜行、退税/买单行、缺件、提交批次和门禁结果。客户端接口必须按当前企业裁剪返回，不返回同柜其他客户的名称、数量、资料包 ID、申报组 ID 或异常细节。
### 4. 买单、退税和混合柜完成条件
三类柜不能用一条“缺回执即阻断”的规则代替：
| 柜型 | `LOADED` 前 | `LOADED` 后报关线 | 完成条件与开船影响 |
|---|---|---|---|
| 全买单 | 装柜物理门禁独立判断 | 按最终实装买单明细建立客户案例；平台可执行 `complete-all-buy` 生成资料，但仍需将报关行回执发给对应客户确认；全部客户确认后提交整柜资料 | 客户确认完成后才允许整柜正式提交；正式申报后的查验/放行单独记录，不能把二次确认直接当成海关放行 |
| 退税柜 | 装柜物理门禁独立判断 | 对每个参与入仓码收集/补件，发送报关行，逐份接收回执并让对应客户确认；打回则重做当前案例 | 所有客户案例确认后才允许整柜正式提交；正式申报后的查验/放行单独记录 |
| 混合柜 | 装柜物理门禁独立判断 | 买单行和退税行分别建立客户案例并完成回执确认；同柜批次统一保存成员快照 | 两类成员全部确认后才允许整柜正式提交；不得把买单导出明细冒充客户确认或海关放行 |
同一客户多个入仓码可以共享其授权资料；跨客户物理拼柜不等于允许跨客户正式合报。跨客户合并仍默认禁止，必须有独立授权和客户可见隔离契约。
## 状态、事实与门禁
建议把状态拆成独立事实面，页面总状态只做投影：
| 事实面 | 建议状态 | 说明 |
|---|---|---|
| 渠道、起运仓、目的仓、包税方式、单位、单价 | 生效价格簿的渠道和费率行 | 客户专属优先，否则公共；只展示当前企业可用范围，不向客户端暴露其他客户价格 |
| 参考时效、最晚进仓、船期、附加费说明 | 生效价格簿渠道快照 | 当前多为文本，标记“参考”；不要当作已订舱 ETD 或实际船节点 |
| 重量、体积、目的仓的查询结果 | Firstleg 服务端统一候选筛选及逐渠道估价 | 当前 `/estimate` 只能估算指定渠道；列表页若要一次返回多个可比渠道，需新增批量查询/估价契约，避免浏览器自行计算或逐行扇出 |
| 预估运费 | 服务端价格模型、计费方式和客户生效版本 | 原型“有体积就按 CBM”不适用于所有价格模型；结果显示计费量、单位、币种、价格版本和参考说明 |
| 下载价格表 | 由服务端生成当前企业可见价格快照 | 是否开放原始 XLSX、导出字段及客户专属信息边界待确认；不能直接下载平台上传的全部原件 |
| 客户报关案例 | 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 的已确认前置 |
原型中“价格优选”“时间优选”若进入正式产品，价格排序需基于同币种、同计费口径的完整估价；时效若只有“约 25–30 天”等自由文本，应先统一可比较的数值规则。没有可信比较基础时只展示渠道和参考信息，不给出误导性排名。
上述是建议投影，稳定编码、退回/重开规则和责任人必须在开发前确认。当前四态不能直接承担新流程；收敛时应明确旧状态的映射和删除时点，不保留双协议。
这页是客户查询报价的入口。平台现有价格簿页面继续负责价格发布；实际货柜船期来自订舱及后续船节点，不由价格簿反向覆盖。客户从报价页去创建订单时，可携带渠道、起运仓和目的仓作为表单预选，但创建时仍由服务端重验当前生效版本和渠道资格。
物理 `LOADED` 门禁必须明确校验以下事实：
## 建议实施顺序
1. 真实柜号、预装计划和数量版本完整；
2. PDA 拣货和复核完成，整批提交成功；
3. 空仓、半仓、满仓、锁仓、带锁码照五类证据各有至少一张有效照片，锁码文本已保存；
4. 数量守恒、无未解决 PDA 异常。
1. **先统一模型和用词**：确认资料包、申报组、柜级总览、放行、结关、交付的定义，以及客户/平台分别可见的状态；确定资料清单和合并规则。产出状态图、权限矩阵和文件类型清单。
2. **打通客户资料入口**：让独立“报关资料”页和订单快捷入口共用前置资料包；允许装柜前提交，平台能够接收、逐票核对并要求补件。此阶段先解决提交时点与资料完整性。
3. **接入统一申报协作**：平台按真实装柜清单组单、交报关行、上传预录单，客户确认后记录正式申报及海关反馈；核对离仓门禁的触发事实。
4. **补齐异常与交付**：退单、查验、甩柜、改配、结关、正式资料交付与通知按已确认规则接入，保留每次修改和凭证历史。
5. **上线船期价格查询**：先基于生效价格簿提供客户可见列表和服务端批量估价，再根据已确认的导出、排序和展示规则完善页面。
`LOADED` 后分别创建报关案例和送港任务。报关案例的整柜正式提交只校验所有客户 `CUSTOMER_CONFIRMED`；送港只校验装柜完成、真实柜号、订舱/拖车等运输条件。两条线可以先后不同。到港后如船舱不足记录 `ROLLED_OVER`；只有实际 `VESSEL_DEPARTED` 才进入海运节点。报关放行、送港和甩柜不能反向作为 `LOADED` 的前置。
## 业务待确认
每个写动作都需要 Idempotency-Key、expectedVersion、规范化请求哈希、乐观锁冲突码、审计事件和结果回放。上传、替换、改关联、补件、审核、提交批次、回执上传和门禁确认不得仅靠前端推进。
1. **提交时点**：客户最晚何时提交？装柜前已上传资料在换柜/拆柜时如何重新关联，谁负责确认最终申报范围？
2. **资料清单**：业务文档列出的“发票、箱单、合同、报关单”中，申报前的“报关单”实际指客户提供的哪种单据？清单是否随客户、国家、渠道和货物类型变化？
3. **合并规则**：同客户同柜多票何时自动合并，何时允许分组；跨客户是否绝对不能同一报关单；合并申报的业务编号和取消/重组规则是什么？
4. **预录确认**：客户确认的是整份预录单文件，还是金额、重量、品名、HS 编码等结构化字段？修改后谁重新发起确认？
5. **报关行与海关回传**：首期是否仍由客服线下收发、人工录入并上传凭证；报关单号能否从可信接口取得，若不能则不得写“系统自动抓取”？
6. **放行、查验、甩柜顺序**：业务文档将查验和甩柜列在放行后，应确认实际可发生的时点、放行是否撤销、漏装与改配是否需要重新申报，以及异常关闭条件。
7. **退税交付**：装柜后可加急提供的具体文件是什么，需如何标记“预提供”；正式可用于退税的文件清单及结关判定由谁确认？
8. **全买单柜**：是否继续走独立简化流程，哪些申报和海关节点仍需记录？
9. **船期价格**：客户是否能下载完整价格表；价格“优选”和时效“优选”如何比较；公开报价的有效期、币种、附加费范围与实际结算提示如何表述？
## 权限、文件与接口边界
现有报关接口使用 merchant:order:view/edit 和 platform:firstleg:customs:list/manage。新增独立入口前必须确认是复用还是拆分为报关专用权限，并落到客户端路由、导航、Controller、OpenAPI x-permission、IAM 初始化 SQL 和服务端对象级校验：
- 客户查看、上传/替换、补件确认和下载分别校验当前企业、订单/子订单、入仓明细和客户可见标记；不能信任请求中的 tenantId、订单 ID 或入仓码。
- 平台查看、审核/退回、生成提交批次、上传回执和发布结果分别授权；列表权限只包含详情只读，写权限独立。
- File 文件类型、业务 ID、客户归属、版本、冻结和下载审计必须定义。现有 LOADING_LIST_CUSTOMS_SOURCE/RESULT 不能直接覆盖资料包、提交批次和回执的新类别。
- File 上传成功但业务写入失败、业务写入成功但 File 失败、替换/作废和重试都要有补偿或可重放规则；不能产生越权文件或孤儿记录。
独立客户列表、详情、待办计数和平台筛选必须补充明确的路径、分页、稳定排序、筛选参数、空态/无权限响应和错误码。不能只写“新增列表”或继续复用单订单查询接口。
## 船期价格接入
### 展示边界
客户页只展示当前企业可见的有效价格簿快照：渠道、起运仓、目的地、pricingTaxMode、计费单位、单价、币种、参考船期、最晚进仓、参考时效、附加费说明、价格簿版本和更新时间。价格簿中的预计船期是参考文本，不是已订舱 ETD、实际开船或到港节点；时区、有效期、来源和过期展示必须明确。
客户专属与公共价格按版本作用域选择：先选择当前企业专属 ACTIVE 版本；只有不存在专属 ACTIVE 版本时才选择公共 ACTIVE 版本，不能按单条费率缺行再逐行回退。页面展示业务版本号或生效时间，不直接把内部 priceBookVersionId 当作用户可见编号。
### 批量估价契约
若要跨渠道列表展示，服务端新增批量估价契约，至少定义：起运仓、目的类型/目的地、渠道候选、重量、体积、pricingTaxMode、版本快照、批量上限、超时、无命中错误、计费量、单位、币种、基础金额、未包含附加费、舍入规则和排序规则。不得由浏览器自行计算或逐渠道扇出。
“价格优选”只有在币种、目的地、税模式、计费口径和附加费范围可比时才允许启用；否则只展示参考结果。订单创建时必须重新校验渠道资格和生效版本，明确旧报价失效、金额变化和重新报价的用户提示，不把客户端显示金额当成最终结算金额。
价格导出如需上线，应另定义客户可见字段、公共/专属价格隔离、导出审计、快照版本、文件保留期限和下载权限；在这些规则确认前不纳入本期上线。
## 实施顺序与进入条件
1. **冻结业务规则**：确认客户资料清单、回执轮次、打回重做、所有客户确认、整柜正式申报、查验/放行、甩柜/改配和跨客户合并；已确认规则以[需求确认表](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/国内货柜履约需求确认表.md:24)为准。
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/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/`；报价文本、订舱预计时间和实际船节点各自保留事实来源。
- 客户端订单与现有报关：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](C:/Users/BY-OY/Desktop/code/chongchong-global/baiyue-firstleg/firstleg/src/main/resources/openapi/customs-v1.yaml:1)、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](C:/Users/BY-OY/Desktop/code/chongchong-global/baiyue-firstleg/firstleg/src/main/resources/openapi/fba-pricing-v1.yaml:130)。
- 国内边界、状态和门禁：[国内货柜履约 README](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/README.md:3)、[国内货柜履约开发规划](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/国内货柜履约开发规划.md:166)、[国内货柜履约需求确认表](C:/Users/BY-OY/Desktop/code/chongchong-global/docs/国内货柜履约/国内货柜履约需求确认表.md:24)。