二期优化方案

This commit is contained in:
2026-08-05 11:32:17 +08:00
parent 3e62cc1263
commit ffa3327521
5 changed files with 212 additions and 14 deletions
+12 -3
View File
@@ -15,6 +15,7 @@
- [二期开发进度表](二期开发进度表.md) - [二期开发进度表](二期开发进度表.md)
- [二期开发进度表(Excel)](虫虫出海二期开发进度表.xlsx) - [二期开发进度表(Excel)](虫虫出海二期开发进度表.xlsx)
- [二期前端页面清单与多对话并行任务表](二期前端页面清单与多对话并行任务表.md) - [二期前端页面清单与多对话并行任务表](二期前端页面清单与多对话并行任务表.md)
- [海外仓阶梯费用前端联调说明(2026-08-05)](海外仓阶梯费用前端联调说明-2026-08-05.md)
- [二期需求确认清单:产品与业务确认](二期需求确认清单.md) - [二期需求确认清单:产品与业务确认](二期需求确认清单.md)
- [二期需求确认清单(会议填写 Excel)](二期需求确认清单.xlsx) - [二期需求确认清单(会议填写 Excel)](二期需求确认清单.xlsx)
- [规划依据:头程物流流程图](参考资料/头程物流流程图.svg) - [规划依据:头程物流流程图](参考资料/头程物流流程图.svg)
@@ -38,7 +39,6 @@
## 核心文档 ## 核心文档
- [二期全链路验收结果(2026-08-04)](二期全链路验收结果-2026-08-04.md)
- [二期前端联调报告(2026-08-04)](二期前端联调报告-2026-08-04.md) - [二期前端联调报告(2026-08-04)](二期前端联调报告-2026-08-04.md)
- [第三方入仓测量接口联调说明](第三方入仓测量接口联调说明-2026-08-04.md) - [第三方入仓测量接口联调说明](第三方入仓测量接口联调说明-2026-08-04.md)
- [二期需求优化版 V2:测量、计费、托盘入库主流程](二期需求优化版-v2-测量计费入库主流程.md) - [二期需求优化版 V2:测量、计费、托盘入库主流程](二期需求优化版-v2-测量计费入库主流程.md)
@@ -59,10 +59,19 @@
可重复执行的测试库增量脚本位于: 可重复执行的测试库增量脚本位于:
```text ```text
D:\baiyue-firstleg\deploy\sql\2026-08-04-二期回归字段增量-测试库可重复执行.sql D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql
``` ```
脚本已在本地测试库重复执行验证,包含: 该文件是头程数据库唯一增量入口,后续数据库变更只追加到此文件。当前已包含一期、二期以及海外仓阶梯费用基础资料所需结构、索引和权限。历史日期脚本不再作为部署入口。
其中海外仓阶梯费用新增:
- `wh_overseas_storage_fee_rule`
- `wh_overseas_storage_fee_tier`
- 5 个查询、唯一性和关联索引
- 4 项平台端按钮权限及平台系统管理员默认授权
原二期回归字段仍包含:
- `fl_inbound_weight_result.created_by` - `fl_inbound_weight_result.created_by`
- `fl_inbound_weight_result.updated_by` - `fl_inbound_weight_result.updated_by`
+9 -2
View File
@@ -77,11 +77,18 @@
- 收款、付款、退款、核销、反核销和银行流水。 - 收款、付款、退款、核销、反核销和银行流水。
- 发票、开票接口、会计凭证和总账。 - 发票、开票接口、会计凭证和总账。
- 单票利润、利润率和完整财务报表。 - 单票利润、利润率和完整财务报表。
- 阶梯价、组合优惠和通用计费表达式平台。 - 头程/FBA 阶梯计费、组合优惠和通用计费表达式平台。
- 完整 SKU 库存、盘点、拣货、复核和出库。 - 完整 SKU 库存、盘点、拣货、复核和出库。
- 入库后的常规移库、拆托、并托和库存成本。 - 入库后的常规移库、拆托、并托和库存成本。
- PDA 作业端。 - PDA 作业端。
### 6.1 海外仓阶梯费用的范围例外
- 已纳入“海外仓客户级天数阶梯仓储费”的基础资料 CRUD,归属 Warehouse 服务,不新增独立服务或数据库。
- 一名客户只允许一份有效配置,维护币种及连续的天数区间、仓储费单价。
- 该配置当前只供平台端维护和查询,暂不接入本期头程/FBA 自动计费、费用发送、账单或结算流程。
- 后续接入海外仓实际计费时,需要另行确认计费单位、入库/出库日边界、免租期、尾段处理、币种换算和规则生效版本。
## 七、与原确认问题的对应关系 ## 七、与原确认问题的对应关系
| 原编号 | 原问题 | V2 对应项 | 处理方式 | | 原编号 | 原问题 | V2 对应项 | 处理方式 |
@@ -127,4 +134,4 @@ C1 至 C8 确认后,原 P2-Q14 至 P2-Q16 不再单独维护,避免形成两
| T2 OCR 参数 | 降级链路已验证,真实供应商待接入 | 本地 OCR 未配置,已验证失败后人工修正继续入库 | | T2 OCR 参数 | 降级链路已验证,真实供应商待接入 | 本地 OCR 未配置,已验证失败后人工修正继续入库 |
| T3 托盘库位基础资料 | 已实现并通过 API 创建 | 公共仓资源租户为 `10001`,分配状态 `CONFIRMED` | | T3 托盘库位基础资料 | 已实现并通过 API 创建 | 公共仓资源租户为 `10001`,分配状态 `CONFIRMED` |
完整证据见 [二期全链路验收结果(2026-08-04)](二期全链路验收结果-2026-08-04.md)。 完整接口与回归证据见 [二期前端联调报告(2026-08-04)](二期前端联调报告-2026-08-04.md)。
@@ -1,6 +1,6 @@
# 二期前端页面清单与多对话并行任务表 # 二期前端页面清单与多对话并行任务表
> 盘点日期:2026-08-04 > 盘点日期:2026-08-05
> 适用项目:`apps/admin-web/`、`apps/client-web/` > 适用项目:`apps/admin-web/`、`apps/client-web/`
> 后端范围:只读核对 `baiyue-firstleg/`,本任务不修改后端 > 后端范围:只读核对 `baiyue-firstleg/`,本任务不修改后端
> 当前基线:以后端现有 Controller、DTO、权限和状态机为可联调事实;V2 待确认项不擅自补成前端规则 > 当前基线:以后端现有 Controller、DTO、权限和状态机为可联调事实;V2 待确认项不擅自补成前端规则
@@ -11,7 +11,7 @@
二期前端应围绕已经落地的“入库测量、OCR、测量审核、FBA 计费、托盘库位、客户只读结果”建设,不继续沿用旧 24 项计划直接开工。 二期前端应围绕已经落地的“入库测量、OCR、测量审核、FBA 计费、托盘库位、客户只读结果”建设,不继续沿用旧 24 项计划直接开工。
- Admin 新增 5 个正式菜单页面:入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理。 - Admin 新增 6 个正式菜单页面:入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理、海外仓阶梯费用。
- 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史,不再新增独立“接收审核”页面。 - 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史,不再新增独立“接收审核”页面。
- 正常流程由“测量审核通过”触发后端自动计费、发布费用并完成入库;前端不把 `calculate → confirm → send` 串成常规人工流程。 - 正常流程由“测量审核通过”触发后端自动计费、发布费用并完成入库;前端不把 `calculate → confirm → send` 串成常规人工流程。
- Client 不新增独立入库菜单或列表,只在现有头程订单详情中增加“入库与费用”只读区。 - Client 不新增独立入库菜单或列表,只在现有头程订单详情中增加“入库与费用”只读区。
@@ -36,6 +36,7 @@
| Client 到仓预报 | 规划中存在 | 无商户公开接口 | 不建设 | | Client 到仓预报 | 规划中存在 | 无商户公开接口 | 不建设 |
| 通用费用项目 | V2 C6 白名单待确认 | 无独立费用项目 Controller | 不建设费用项目页 | | 通用费用项目 | V2 C6 白名单待确认 | 无独立费用项目 Controller | 不建设费用项目页 |
| 入库列表路径 | V2 示例使用 `/api/platform/inbounds` | Controller 确实无 `v1`,其他入库接口多为 `/api/platform/v1/...` | API 封装保留真实多前缀,不自行统一 | | 入库列表路径 | V2 示例使用 `/api/platform/inbounds` | Controller 确实无 `v1`,其他入库接口多为 `/api/platform/v1/...` | API 封装保留真实多前缀,不自行统一 |
| 海外仓阶梯费用 | 旧文档排除全部阶梯价 | Warehouse 已提供客户级天数阶梯费用基础资料 CRUD | 新增平台端维护页;当前不接入自动计费 |
## 三、Admin 页面和变更清单 ## 三、Admin 页面和变更清单
@@ -49,6 +50,7 @@
| 船司 FBA 价格 | `/first-leg-pricing/carrier-rates` | 价格查询、详情、新版本、停用;起运仓、渠道、船司、FBA 仓、单价和附加费 | `firstleg:fba-pricing:rate:view/edit` | P0 | | 船司 FBA 价格 | `/first-leg-pricing/carrier-rates` | 价格查询、详情、新版本、停用;起运仓、渠道、船司、FBA 仓、单价和附加费 | `firstleg:fba-pricing:rate:view/edit` | P0 |
| 库位管理 | `/master-data/locations` | 企业和仓库联动、筛选、分页、新增、编辑、启停、删除、可用库位状态 | `platform:location:*` | P0 | | 库位管理 | `/master-data/locations` | 企业和仓库联动、筛选、分页、新增、编辑、启停、删除、可用库位状态 | `platform:location:*` | P0 |
| 托盘管理 | `/master-data/pallets` | 企业和仓库联动、筛选、分页、新增、编辑、删除 | `platform:pallet:*` | P0 | | 托盘管理 | `/master-data/pallets` | 企业和仓库联动、筛选、分页、新增、编辑、删除 | `platform:pallet:*` | P0 |
| 海外仓阶梯费用 | `/customers/overseas-storage-fees` | 按客户分页查询,维护币种、连续天数区间和仓储费单价,支持乐观锁编辑与删除 | `platform:overseas-storage-fee:*` | P1 |
所有业务表格的“操作”列放在第一列,并检查窄屏退化。 所有业务表格的“操作”列放在第一列,并检查窄屏退化。
@@ -67,7 +69,7 @@
### 3.3 全局装配变更 ### 3.3 全局装配变更
- `src/app/router/index.ts`:装配二期模块路由。 - `src/app/router/index.ts`:装配二期模块路由。
- `src/core/navigation/adminNavigation.ts`:在“国内仓”下增加入库单、库位、托盘;新增“头程计费”分组。 - `src/core/navigation/adminNavigation.ts`:在“国内仓”下增加入库单、库位、托盘;新增“头程计费”分组;在客户或海外仓基础资料分组增加“海外仓阶梯费用”。
- 路由和导航测试同步更新。 - 路由和导航测试同步更新。
- IAM 权限页面无需业务改造;后端返回二期权限资源后沿用现有展示和授权能力。 - IAM 权限页面无需业务改造;后端返回二期权限资源后沿用现有展示和授权能力。
- 不恢复“接收审核”“费用项目”“完整财务管理”等原型菜单。 - 不恢复“接收审核”“费用项目”“完整财务管理”等原型菜单。
@@ -106,6 +108,7 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉,新增
| 称重图片 | `file/.../PlatformMeasurementImageController.java` | 上传、OCR 重试和鉴权查看 | | 称重图片 | `file/.../PlatformMeasurementImageController.java` | 上传、OCR 重试和鉴权查看 |
| 托盘 | `warehouse/.../PlatformPalletController.java` | 托盘 CRUD | | 托盘 | `warehouse/.../PlatformPalletController.java` | 托盘 CRUD |
| 库位 | `warehouse/.../PlatformLocationController.java` | 库位 CRUD、状态和可用库位查询 | | 库位 | `warehouse/.../PlatformLocationController.java` | 库位 CRUD、状态和可用库位查询 |
| 海外仓阶梯费用 | `warehouse/.../PlatformOverseasStorageFeeController.java` | 平台端客户级天数阶梯仓储费 CRUD |
| 商户结果 | `firstleg/.../MerchantInboundBillingController.java` | Client 订单入库与费用只读展示 | | 商户结果 | `firstleg/.../MerchantInboundBillingController.java` | Client 订单入库与费用只读展示 |
共同约定: 共同约定:
@@ -122,6 +125,7 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉,新增
### 6.0 实施状态(2026-08-04) ### 6.0 实施状态(2026-08-04)
- `P2-ADM-01` 至 `P2-ADM-11`、`P2-CLI-01`、`P2-QA-01`、`P2-QA-02` 均已完成。 - `P2-ADM-01` 至 `P2-ADM-11`、`P2-CLI-01`、`P2-QA-01`、`P2-QA-02` 均已完成。
- 新增 `P2-ADM-12` 海外仓阶梯费用前端任务:后端接口、权限和 SQL 已完成,前端页面待实现与联调。
- Admin 已通过 `pnpm test`(58 个文件、262 个测试)、`pnpm typecheck` 和 `pnpm build`。 - Admin 已通过 `pnpm test`(58 个文件、262 个测试)、`pnpm typecheck` 和 `pnpm build`。
- Client 已通过 `pnpm test`(135 个测试)、`pnpm typecheck` 和 `pnpm build`。 - Client 已通过 `pnpm test`(135 个测试)、`pnpm typecheck` 和 `pnpm build`。
- Admin 二期新增模块的 Impeccable detector 结果为 `[]`,模块依赖边界测试已通过。 - Admin 二期新增模块的 Impeccable detector 结果为 `[]`,模块依赖边界测试已通过。
@@ -147,6 +151,7 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉,新增
| `P2-ADM-09` | 托盘管理 | 独占 `modules/warehouse-resources/pallets/**` 及测试 | 企业/仓库级联、筛选分页、CRUD;不虚构状态或启停 | 现有企业选择器和仓库 API | W1 | | `P2-ADM-09` | 托盘管理 | 独占 `modules/warehouse-resources/pallets/**` 及测试 | 企业/仓库级联、筛选分页、CRUD;不虚构状态或启停 | 现有企业选择器和仓库 API | W1 |
| `P2-ADM-10` | 入库详情工作台组装 | 独占 `modules/inbounds/pages/InboundOrderDetailView.vue`、`components/InboundWorkflowWorkspace.vue` 及测试 | 将 ADM-01 至 ADM-05 组件组装为详情页;统一刷新、租户切换清理、操作成功回读和托盘库位只读结果 | ADM-01 至 ADM-05 | W2 | | `P2-ADM-10` | 入库详情工作台组装 | 独占 `modules/inbounds/pages/InboundOrderDetailView.vue`、`components/InboundWorkflowWorkspace.vue` 及测试 | 将 ADM-01 至 ADM-05 组件组装为详情页;统一刷新、租户切换清理、操作成功回读和托盘库位只读结果 | ADM-01 至 ADM-05 | W2 |
| `P2-ADM-11` | Admin 全局装配 | 独占各模块 `routes.ts`、`app/router/index.ts`、`core/navigation/adminNavigation.ts` 及对应测试 | 接入全部 Admin 页面、菜单和权限;首个可访问路由正确;不恢复接收审核/费用项目原型菜单 | ADM-06 至 ADM-10 | W3 | | `P2-ADM-11` | Admin 全局装配 | 独占各模块 `routes.ts`、`app/router/index.ts`、`core/navigation/adminNavigation.ts` 及对应测试 | 接入全部 Admin 页面、菜单和权限;首个可访问路由正确;不恢复接收审核/费用项目原型菜单 | ADM-06 至 ADM-10 | W3 |
| `P2-ADM-12` | 海外仓阶梯费用 | 建议独占 `modules/overseas-storage-fees/**` 及测试;路由和菜单在集成时统一修改 | 分页、详情、新增、编辑、删除;客户唯一性、连续阶梯校验、乐观锁冲突、权限态和未保存保护 | `PlatformOverseasStorageFeeController` | W1 |
| `P2-CLI-01` | 商户订单入库费用只读展示 | `apps/client-web/src/modules/first-leg/api/inboundBilling.ts`、`types/inboundBilling.ts`、`components/InboundBillingPanel.vue`、`views/FirstLegOrdersView.vue` 及测试 | 成功/待发布/失败/重试、快速切单、320/720/桌面;无写动作,不消费内部字段 | 只读 `MerchantInboundBillingController` 及 DTO/Service | W1 | | `P2-CLI-01` | 商户订单入库费用只读展示 | `apps/client-web/src/modules/first-leg/api/inboundBilling.ts`、`types/inboundBilling.ts`、`components/InboundBillingPanel.vue`、`views/FirstLegOrdersView.vue` 及测试 | 成功/待发布/失败/重试、快速切单、320/720/桌面;无写动作,不消费内部字段 | 只读 `MerchantInboundBillingController` 及 DTO/Service | W1 |
| `P2-QA-01` | Admin 跨模块回归 | 以新增集成测试和联调记录为主,不重构业务实现 | 租户切换、401/403、业务码、409、幂等、重复提交、图片异常、空/加载/失败、权限按钮、窄屏;运行 test/typecheck/build | `P2-ADM-11` | W4 | | `P2-QA-01` | Admin 跨模块回归 | 以新增集成测试和联调记录为主,不重构业务实现 | 租户切换、401/403、业务码、409、幂等、重复提交、图片异常、空/加载/失败、权限按钮、窄屏;运行 test/typecheck/build | `P2-ADM-11` | W4 |
| `P2-QA-02` | Client 安全与展示验收 | 只读审查和补测试,避免与 CLI-01 同时改订单页 | 不展示内部备注/历史;A0404 中性态;响应隔离;test/typecheck/build | `P2-CLI-01` | W2 | | `P2-QA-02` | Client 安全与展示验收 | 只读审查和补测试,避免与 CLI-01 同时改订单页 | 不展示内部备注/历史;A0404 中性态;响应隔离;test/typecheck/build | `P2-CLI-01` | W2 |
@@ -154,9 +159,9 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉,新增
### 6.2 推荐并行波次 ### 6.2 推荐并行波次
```text ```text
W1(10 个并行开发对话): W1(新增任务可独立开发):
ADM-01 + ADM-02 + ADM-03 + ADM-04 + ADM-05 ADM-01 + ADM-02 + ADM-03 + ADM-04 + ADM-05
ADM-06 + ADM-07 + ADM-08 + ADM-09 + CLI-01 ADM-06 + ADM-07 + ADM-08 + ADM-09 + ADM-12 + CLI-01
↓ ↓
W2(2 个并行对话): ADM-10 + QA-02 W2(2 个并行对话): ADM-10 + QA-02
↓ ↓
@@ -165,7 +170,7 @@ W3(1 个集成对话): ADM-11
W4: QA-01 跨模块联调、构建和回归 W4: QA-01 跨模块联调、构建和回归
``` ```
W1 的 10 个对话没有代码依赖,可以一次全部创建。真正的关键路径是 `ADM-01 至 ADM-05 → ADM-10 → ADM-11 → QA-01`;基础资料、仓库资源和 Client 与该链路完全并行。 `ADM-12` 没有入库主链路依赖,可独立实现;完成后需要把其路由、菜单和权限态纳入 Admin 集成回归。原关键路径仍是 `ADM-01 至 ADM-05 → ADM-10 → ADM-11 → QA-01`。
### 6.3 多对话协作规则 ### 6.3 多对话协作规则
@@ -175,6 +180,7 @@ W1 的 10 个对话没有代码依赖,可以一次全部创建。真正的关
- 入库各业务域分别维护本域 `types.ts` 和 API,不创建共享巨型 DTO 文件;跨域只传 `tenantId: string`、`inboundId: string`、`readonly` 数据和 `changed` 事件。 - 入库各业务域分别维护本域 `types.ts` 和 API,不创建共享巨型 DTO 文件;跨域只传 `tenantId: string`、`inboundId: string`、`readonly` 数据和 `changed` 事件。
- `ADM-01` 至 `ADM-05` 不创建或修改 `InboundOrderDetailView.vue`;详情页面只由 `ADM-10` 组装。 - `ADM-01` 至 `ADM-05` 不创建或修改 `InboundOrderDetailView.vue`;详情页面只由 `ADM-10` 组装。
- `ADM-06`、`ADM-07` 不创建共同的 `fba-pricing/routes.ts`;路由只由 `ADM-11` 创建。 - `ADM-06`、`ADM-07` 不创建共同的 `fba-pricing/routes.ts`;路由只由 `ADM-11` 创建。
- `ADM-12` 不修改入库或 FBA 自动计费模块;海外仓阶梯配置当前仅作为基础资料 CRUD。
- Client 任务保持单对话实现,因为现有订单页超过一千行,拆成多个写任务会集中冲突。 - Client 任务保持单对话实现,因为现有订单页超过一千行,拆成多个写任务会集中冲突。
- 每个任务完成后运行直接相关的测试和 typecheck;最终集成任务再运行全项目测试和构建。 - 每个任务完成后运行直接相关的测试和 typecheck;最终集成任务再运行全项目测试和构建。
- 后端契约疑问直接只读 Controller、DTO、Service、Repository/OpenAPI;本轮不得修改 `baiyue-firstleg/`。 - 后端契约疑问直接只读 Controller、DTO、Service、Repository/OpenAPI;本轮不得修改 `baiyue-firstleg/`。
@@ -215,6 +221,7 @@ W1 的 10 个对话没有代码依赖,可以一次全部创建。真正的关
- 正常审核通过会自动完成后续动作,属于高影响写操作;页面确认文案必须明确结果,并防止重复点击。 - 正常审核通过会自动完成后续动作,属于高影响写操作;页面确认文案必须明确结果,并防止重复点击。
- 计费规则和船司价格接口当前返回列表而非分页对象;页面不要先假设服务端分页。 - 计费规则和船司价格接口当前返回列表而非分页对象;页面不要先假设服务端分页。
- 托盘接口没有状态和启停能力;库位才有 `AVAILABLE/RESERVED/OCCUPIED/DISABLED` 状态。 - 托盘接口没有状态和启停能力;库位才有 `AVAILABLE/RESERVED/OCCUPIED/DISABLED` 状态。
- 海外仓阶梯费用当前没有启停、计费单位和生效日期字段;前端不得自行补造,也不得将该配置接入现有 FBA 自动计费。
## 九、每个任务的统一完成标准 ## 九、每个任务的统一完成标准
+7 -3
View File
@@ -76,7 +76,7 @@
- 金额由服务端按“数量 × 单价”计算,也允许固定金额。 - 金额由服务端按“数量 × 单价”计算,也允许固定金额。
- 费用状态:草稿、待审核、审核通过、审核不通过、作废。 - 费用状态:草稿、待审核、审核通过、审核不通过、作废。
- 审核通过的费用不能直接覆盖,只能作废后重新录入。 - 审核通过的费用不能直接覆盖,只能作废后重新录入。
- 不建设计费维度匹配、阶梯价、最低收费、封顶、组合价、规则版本和事件计费引擎。 - 不建设头程/FBA 计费维度匹配、阶梯价、最低收费、封顶、组合价、规则版本和事件计费引擎。
- 不生成应收、应付、对账单、收付款、核销、发票和利润数据。 - 不生成应收、应付、对账单、收付款、核销、发票和利润数据。
### 8. 文件、打印和导出 ### 8. 文件、打印和导出
@@ -153,10 +153,14 @@
- 托盘管理、处理单元、标签换标/补打/作废生命周期。 - 托盘管理、处理单元、标签换标/补打/作废生命周期。
- 独立差异单、客户确认、隔离区、上架任务和位置历史。 - 独立差异单、客户确认、隔离区、上架任务和位置历史。
- OCR 智能识别和自动测量设备接入。 - OCR 智能识别和自动测量设备接入。
- 海外仓库存、退货、换标、派送、PDA 和完整 WMS。 - 海外仓库存、退货、换标、派送、PDA 和完整 WMS;仅纳入客户级天数阶梯仓储费基础资料 CRUD。
- 阶梯计费、规则引擎、应收应付、对账和完整财务模块。 - 头程/FBA 阶梯计费、规则引擎、应收应付、对账和完整财务模块。
- 批量导入导出、自定义列、批量 ZIP 和复杂报表。 - 批量导入导出、自定义列、批量 ZIP 和复杂报表。
### 7.1 海外仓阶梯费用补充边界(2026-08-05)
Warehouse 服务已提供海外仓客户级天数阶梯仓储费的分页、详情、新增、编辑和删除接口。该功能属于基础资料配置,不代表海外仓 WMS 或自动计费已经纳入二期。当前配置不参与入库/FBA 费用计算、费用发送、账单或结算。
## 八、仍需产品确认的最少事项 ## 八、仍需产品确认的最少事项
1. 测量审核和接收审核是否必须由不同账号完成。 1. 测量审核和接收审核是否必须由不同账号完成。
@@ -0,0 +1,171 @@
# 海外仓阶梯费用前端联调说明
> 更新日期:2026-08-05
> 后端服务:Warehouse Service
> 当前状态:后端 CRUD、Gateway 路由、权限、数据库增量和自动化测试已完成;前端待实现与联调
## 一、业务边界
本功能用于平台端按客户维护海外仓仓储费的天数阶梯基础资料。一名客户只能存在一份有效配置,配置包含客户、币种和 1 至 100 组连续的天数阶梯。
当前只提供基础资料维护,不参与本期入库、FBA 自动计费、费用发送、账单、对账或结算。当前也没有启停、计费单位、生效日期、免租期和版本发布能力,前端不得自行补造这些字段或业务动作。
## 二、建议页面
- 页面名称:海外仓阶梯费用
- 建议路由:`/customers/overseas-storage-fees`
- 列表筛选:客户 ID、客户公司名称关键字
- 列表字段:客户、币种、阶梯摘要、版本、创建时间、更新时间
- 详情与编辑字段:客户 ID、客户公司名称、币种、阶梯起始天、阶梯结束天、仓储费单价
- 操作:查看、新增、编辑、删除
编辑和删除必须使用详情返回的最新 `version`。发生 409 冲突时应提示“数据已被修改,请刷新后重试”,重新读取详情,不能静默覆盖。
## 三、接口清单
统一前缀:`/api/platform/v1/overseas-storage-fees`
| 方法 | 路径 | 用途 | 权限 |
|---|---|---|---|
| GET | `/api/platform/v1/overseas-storage-fees` | 分页查询 | `platform:overseas-storage-fee:list` |
| GET | `/api/platform/v1/overseas-storage-fees/{id}` | 查询详情 | `platform:overseas-storage-fee:list` |
| POST | `/api/platform/v1/overseas-storage-fees` | 新增 | `platform:overseas-storage-fee:create` |
| PUT | `/api/platform/v1/overseas-storage-fees/{id}` | 编辑 | `platform:overseas-storage-fee:edit` |
| DELETE | `/api/platform/v1/overseas-storage-fees/{id}?version={version}` | 删除 | `platform:overseas-storage-fee:delete` |
仅允许平台端令牌调用。列表查询参数如下:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | long | 否 | 默认 1,最小 1 |
| `size` | long | 否 | 默认 20,范围 1 至 200 |
| `customerId` | long | 否 | 客户 ID 精确查询 |
| `customerName` | string | 否 | 客户公司名称模糊查询,最多 128 字符 |
## 四、请求示例
新增:
```json
{
"customerId": "10001",
"customerName": "示例客户有限公司",
"currency": "USD",
"tiers": [
{"startDay": 1, "endDay": 7, "unitPrice": 0.5},
{"startDay": 8, "endDay": 30, "unitPrice": 0.8},
{"startDay": 31, "endDay": 60, "unitPrice": 0.6}
]
}
```
编辑请求结构与新增一致,并增加详情返回的版本号:
```json
{
"customerId": "10001",
"customerName": "示例客户有限公司",
"currency": "USD",
"tiers": [
{"startDay": 1, "endDay": 10, "unitPrice": 0.55},
{"startDay": 11, "endDay": 30, "unitPrice": 0.8}
],
"version": 1
}
```
说明:Java Long 类型的 ID 在浏览器中统一按字符串保存和传递,避免精度丢失。
## 五、响应结构
详情的 `data` 结构:
```json
{
"id": "2100000000000000001",
"customerId": "10001",
"customerName": "示例客户有限公司",
"currency": "USD",
"tiers": [
{
"id": "2100000000000000002",
"startDay": 1,
"endDay": 7,
"unitPrice": 0.5,
"sortNo": 1
}
],
"version": 0,
"createdAt": "2026-08-05T10:00:00",
"updatedAt": "2026-08-05T10:00:00"
}
```
分页接口的 `data` 包含 `records`、`page`、`size`、`total`、`pages`。新增成功时 `data` 为新增配置 ID;编辑和删除成功时 `data` 为 `null`。
## 六、校验规则
- 一个客户只能有一份有效配置。
- `customerId` 必须为正数,`customerName` 必填且最多 128 字符。
- 币种必须是三位大写字母,例如 `CNY`、`USD`。
- 阶梯必须为 1 至 100 组。
- 第一组必须从第 1 天开始。
- 后一组 `startDay` 必须等于前一组 `endDay + 1`。
- 区间不能间断、重叠或倒置。
- 起止天数范围为 1 至 36500。
- 单价必须大于 0,最多 12 位整数和 6 位小数。
## 七、错误处理
| 业务码 | 场景 | 前端处理 |
|---|---|---|
| `A0403` | 非平台端访问或缺少按钮权限 | 显示无权限,隐藏无权限操作 |
| `A0404` | 配置不存在或已删除 | 提示数据不存在并返回列表 |
| `A0409` | 客户重复配置、阶梯区间冲突、版本过期或并发修改 | 保留用户提示,刷新列表或详情 |
| `A0422` | 参数、币种、阶梯连续性或单价校验失败 | 显示服务端错误信息并定位表单 |
| `S0503` | Warehouse 服务不可用或未就绪 | 显示服务暂不可用并允许重试 |
普通成功响应仍需判断统一响应体 `code === "200"`。
## 八、数据库与部署
本功能复用 Warehouse 数据库,未新增微服务或独立数据库。新增表:
- `wh_overseas_storage_fee_rule`
- `wh_overseas_storage_fee_tier`
同时新增 5 个索引及 4 项按钮权限,平台系统管理员默认获得上述权限。唯一数据库增量入口:
```text
D:\baiyue-firstleg\deploy\sql\头程数据库统一增量-MySQL8.sql
```
当前已完成 SQL 静态契约校验,但本次功能增量尚未在真实数据库执行。部署或联调前需先在目标库执行统一增量脚本并确认脚本最终输出 `PASS`。
## 九、Swagger
- Gateway 聚合文档:`http://127.0.0.1:9000/webjars/swagger-ui/index.html`,选择 Warehouse 平台端分组。
- Warehouse 直连文档:`http://127.0.0.1:9204/swagger-ui/index.html`。
- Gateway OpenAPI:`/warehouse-service/v3/api-docs/platform`。
## 十、后端验证结果
- Warehouse 全量测试:91 项通过。
- 海外仓阶梯费用 CRUD 定向测试:6 项通过。
- SQL 契约测试:1 项通过。
- Gateway 路由契约测试:2 项通过。
- Maven 构建:`BUILD SUCCESS`。
- SQL 静态校验:存储过程分隔符、预处理语句配对、唯一最终 `PASS` 和危险语句检查均通过。
## 十一、前端验收清单
- 有列表权限时可进入页面,无权限时路由、菜单和按钮状态正确。
- 客户 ID 和客户名称筛选、分页及空态正确。
- 新增后回读详情,ID 全程不转为 JavaScript `Number`。
- 同一客户重复新增时正确处理 `A0409`。
- 阶梯间断、重叠、倒置、非第 1 天开始和非正单价均不能提交成功。
- 编辑使用最新 `version`,过期版本收到 409 后刷新详情。
- 删除前二次确认,并携带最新 `version`。
- 请求失败、服务不可用、加载态、空态和重复提交均有明确反馈。
- 页面不出现启停、生效日期、计费单位、免租期或自动计费开关等未定义字段。
- 不将本配置接入当前头程/FBA 自动计费流程。