二期优化方案

2026-08-05 11:32:17 +08:00
parent 3e62cc1263
commit ffa3327521
5 changed files with 212 additions and 14 deletions
@@ -1,6 +1,6 @@
 # 二期前端页面清单与多对话并行任务表

-> 盘点日期：2026-08-04  
+> 盘点日期：2026-08-05  
 > 适用项目：`apps/admin-web/`、`apps/client-web/`  
 > 后端范围：只读核对 `baiyue-firstleg/`，本任务不修改后端  
 > 当前基线：以后端现有 Controller、DTO、权限和状态机为可联调事实；V2 待确认项不擅自补成前端规则
@@ -11,7 +11,7 @@

 二期前端应围绕已经落地的“入库测量、OCR、测量审核、FBA 计费、托盘库位、客户只读结果”建设，不继续沿用旧 24 项计划直接开工。

- Admin 新增 5 个正式菜单页面：入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理。
+- Admin 新增 6 个正式菜单页面：入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理、海外仓阶梯费用。
 - 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史，不再新增独立“接收审核”页面。
 - 正常流程由“测量审核通过”触发后端自动计费、发布费用并完成入库；前端不把 `calculate → confirm → send` 串成常规人工流程。
 - Client 不新增独立入库菜单或列表，只在现有头程订单详情中增加“入库与费用”只读区。
@@ -36,6 +36,7 @@
 | Client 到仓预报 | 规划中存在 | 无商户公开接口 | 不建设 |
 | 通用费用项目 | V2 C6 白名单待确认 | 无独立费用项目 Controller | 不建设费用项目页 |
 | 入库列表路径 | V2 示例使用 `/api/platform/inbounds` | Controller 确实无 `v1`，其他入库接口多为 `/api/platform/v1/...` | API 封装保留真实多前缀，不自行统一 |
+| 海外仓阶梯费用 | 旧文档排除全部阶梯价 | Warehouse 已提供客户级天数阶梯费用基础资料 CRUD | 新增平台端维护页；当前不接入自动计费 |

 ## 三、Admin 页面和变更清单

@@ -49,6 +50,7 @@
 | 船司 FBA 价格 | `/first-leg-pricing/carrier-rates` | 价格查询、详情、新版本、停用；起运仓、渠道、船司、FBA 仓、单价和附加费 | `firstleg:fba-pricing:rate:view/edit` | P0 |
 | 库位管理 | `/master-data/locations` | 企业和仓库联动、筛选、分页、新增、编辑、启停、删除、可用库位状态 | `platform:location:*` | P0 |
 | 托盘管理 | `/master-data/pallets` | 企业和仓库联动、筛选、分页、新增、编辑、删除 | `platform:pallet:*` | P0 |
+| 海外仓阶梯费用 | `/customers/overseas-storage-fees` | 按客户分页查询，维护币种、连续天数区间和仓储费单价，支持乐观锁编辑与删除 | `platform:overseas-storage-fee:*` | P1 |

 所有业务表格的“操作”列放在第一列，并检查窄屏退化。

@@ -67,7 +69,7 @@
 ### 3.3 全局装配变更

 - `src/app/router/index.ts`：装配二期模块路由。
- `src/core/navigation/adminNavigation.ts`：在“国内仓”下增加入库单、库位、托盘；新增“头程计费”分组。
+- `src/core/navigation/adminNavigation.ts`：在“国内仓”下增加入库单、库位、托盘；新增“头程计费”分组；在客户或海外仓基础资料分组增加“海外仓阶梯费用”。
 - 路由和导航测试同步更新。
 - IAM 权限页面无需业务改造；后端返回二期权限资源后沿用现有展示和授权能力。
 - 不恢复“接收审核”“费用项目”“完整财务管理”等原型菜单。
@@ -106,6 +108,7 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增
 | 称重图片 | `file/.../PlatformMeasurementImageController.java` | 上传、OCR 重试和鉴权查看 |
 | 托盘 | `warehouse/.../PlatformPalletController.java` | 托盘 CRUD |
 | 库位 | `warehouse/.../PlatformLocationController.java` | 库位 CRUD、状态和可用库位查询 |
+| 海外仓阶梯费用 | `warehouse/.../PlatformOverseasStorageFeeController.java` | 平台端客户级天数阶梯仓储费 CRUD |
 | 商户结果 | `firstleg/.../MerchantInboundBillingController.java` | Client 订单入库与费用只读展示 |

 共同约定：
@@ -122,6 +125,7 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增
 ### 6.0 实施状态（2026-08-04）

 - `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`。
 - Client 已通过 `pnpm test`（135 个测试）、`pnpm typecheck` 和 `pnpm build`。
 - Admin 二期新增模块的 Impeccable detector 结果为 `[]`，模块依赖边界测试已通过。
@@ -147,6 +151,7 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增
 | `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-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-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 |
@@ -154,9 +159,9 @@ Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增
 ### 6.2 推荐并行波次

 ```text
-W1（10 个并行开发对话）:
+W1（新增任务可独立开发）:
 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
                    ↓
@@ -165,7 +170,7 @@ W3（1 个集成对话）: ADM-11
 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 多对话协作规则

@@ -175,6 +180,7 @@ W1 的 10 个对话没有代码依赖，可以一次全部创建。真正的关
 - 入库各业务域分别维护本域 `types.ts` 和 API，不创建共享巨型 DTO 文件；跨域只传 `tenantId: string`、`inboundId: string`、`readonly` 数据和 `changed` 事件。
 - `ADM-01` 至 `ADM-05` 不创建或修改 `InboundOrderDetailView.vue`；详情页面只由 `ADM-10` 组装。
 - `ADM-06`、`ADM-07` 不创建共同的 `fba-pricing/routes.ts`；路由只由 `ADM-11` 创建。
+- `ADM-12` 不修改入库或 FBA 自动计费模块；海外仓阶梯配置当前仅作为基础资料 CRUD。
 - Client 任务保持单对话实现，因为现有订单页超过一千行，拆成多个写任务会集中冲突。
 - 每个任务完成后运行直接相关的测试和 typecheck；最终集成任务再运行全项目测试和构建。
 - 后端契约疑问直接只读 Controller、DTO、Service、Repository/OpenAPI；本轮不得修改 `baiyue-firstleg/`。
@@ -215,6 +221,7 @@ W1 的 10 个对话没有代码依赖，可以一次全部创建。真正的关
 - 正常审核通过会自动完成后续动作，属于高影响写操作；页面确认文案必须明确结果，并防止重复点击。
 - 计费规则和船司价格接口当前返回列表而非分页对象；页面不要先假设服务端分页。
 - 托盘接口没有状态和启停能力；库位才有 `AVAILABLE/RESERVED/OCCUPIED/DISABLED` 状态。
+- 海外仓阶梯费用当前没有启停、计费单位和生效日期字段；前端不得自行补造，也不得将该配置接入现有 FBA 自动计费。

 ## 九、每个任务的统一完成标准