238 lines
20 KiB
Markdown
238 lines
20 KiB
Markdown
# 二期前端页面清单与多对话并行任务表
|
||
|
||
> 盘点日期：2026-08-05
|
||
> 适用项目：`apps/admin-web/`、`apps/client-web/`
|
||
> 后端范围：只读核对 `baiyue-firstleg/`，本任务不修改后端
|
||
> 当前基线：以后端现有 Controller、DTO、权限和状态机为可联调事实；V2 待确认项不擅自补成前端规则
|
||
|
||
> 主体模型：前端只呈现“平台—客户”两级；接口 `tenantId` 当前表示客户 ID。任务中的“租户切换”统一理解为客户切换，不新增租户选择器或租户级权限。
|
||
|
||
本轮不存在“等待后端提供接口文档”的前置任务。每个前端对话直接只读当前工作区 `baiyue-firstleg/` 中的 Controller、DTO、Service、Repository、OpenAPI 和权限 SQL；发现契约问题只登记，不修改后端。
|
||
|
||
## 一、结论
|
||
|
||
二期前端应围绕已经落地的“入库测量、OCR、测量审核、FBA 计费、托盘库位、客户只读结果”建设，不继续沿用旧 24 项计划直接开工。
|
||
|
||
- Admin 新增 6 个正式菜单页面：入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理、海外仓阶梯费用。
|
||
- 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史，不再新增独立“接收审核”页面。
|
||
- 正常流程在“测量审核通过”后直接进入 `WAIT_SPLIT`；后端可尽力生成初算费用，但价格缺失或初算失败不得阻塞主流程。平台人员可独立修改计费量、单价和附加费，金额由服务端重算。
|
||
- Client 不新增独立入库菜单或列表，只在现有头程订单详情中增加“入库与费用”只读区。
|
||
- 到仓预报、预约、签到、分批收货、标签、冲正、差异通知、上架任务、位置历史和通用费用项目当前没有匹配的公开后端接口，暂不拆前端实现任务。
|
||
|
||
## 二、事实来源和冲突处理
|
||
|
||
当前 V2 确认清单的 C1-C8、T1-T3 仍是待确认状态，但后端已经形成一套更收敛的可联调实现。因此本轮按以下顺序执行：
|
||
|
||
1. 用户本轮要求：只整理和开发前端，不修改后端，可以直接只读后端代码。
|
||
2. 后端真实 Controller、DTO、权限 SQL、状态枚举和服务编排。
|
||
3. `二期需求优化版-v2-测量计费入库主流程.md` 的范围边界。
|
||
4. Admin 原型仅用于布局、字段和交互参考，不补造后端没有的业务能力。
|
||
|
||
已确认的实现差异：
|
||
|
||
| 主题 | 旧规划或 V2 描述 | 当前后端事实 | 前端处理 |
|
||
|---|---|---|---|
|
||
| 正常入库动作 | 人工试算、确认、发送费用后入库 | 测量审核通过后直接进入待分柜，费用仅作独立初算和人工维护 | 审核成功后刷新详情；初算失败展示非阻断提示，不影响待分柜操作 |
|
||
| 托盘库位 | 操作员选择托盘和候选库位 | 测量提交/审核编排自动准备和占用，平台无人工分配公开接口 | 详情只读展示分配结果 |
|
||
| 接收审核 | 独立页面 | 无独立节点 | 不建设；相关结果并入详情和审核区 |
|
||
| Client 到仓预报 | 规划中存在 | 无商户公开接口 | 不建设 |
|
||
| 通用费用项目 | V2 C6 白名单待确认 | 无独立费用项目 Controller | 不建设费用项目页 |
|
||
| 入库列表路径 | V2 示例使用 `/api/platform/inbounds` | Controller 确实无 `v1`，其他入库接口多为 `/api/platform/v1/...` | API 封装保留真实多前缀，不自行统一 |
|
||
| 海外仓阶梯费用 | 旧文档排除全部阶梯价 | Warehouse 已提供客户级天数阶梯费用基础资料 CRUD | 新增平台端维护页；当前不接入自动计费 |
|
||
|
||
## 三、Admin 页面和变更清单
|
||
|
||
### 3.1 正式菜单页面
|
||
|
||
| 页面 | 建议路由 | 主要内容 | 主要权限 | 优先级 |
|
||
|---|---|---|---|---|
|
||
| 入库单 | `/inbounds` | 企业选择、四个后端页签、多条件筛选、服务端分页、详情入口 | `platform:firstleg:inbound:list` | P0 |
|
||
| 入库详情 | `/inbounds/:inboundId` | 概览、运输快照、内部备注、文件、状态历史、测量、审核、费用、托盘库位 | `platform:firstleg:inbound:view` 及各操作权限 | P0 |
|
||
| 客户计费规则 | `/first-leg-pricing/customer-rules` | 规则查询、详情、新版本、停用；KG/CBM、换算系数、舍入和有效期 | `firstleg:fba-pricing:rule: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/pallets` | 企业和仓库联动、筛选、分页、新增、编辑、删除 | `platform:pallet:*` | P0 |
|
||
| 海外仓阶梯费用 | `/customers/overseas-storage-fees` | 按客户分页查询，维护币种、连续天数区间和仓储费单价，支持乐观锁编辑与删除 | `platform:overseas-storage-fee:*` | P1 |
|
||
|
||
所有业务表格的“操作”列放在第一列，并检查窄屏退化。
|
||
|
||
### 3.2 入库详情内部功能
|
||
|
||
入库详情建议作为一个路由页，以页签或分区承载以下能力，不为每一步增加侧边栏菜单：
|
||
|
||
| 分区 | 能力 | 交互边界 |
|
||
|---|---|---|
|
||
| 概览与历史 | 入仓码、订单/客户/仓库快照、申报与实测汇总、文件、内部备注、状态历史 | 切换企业后清空全部上下文 |
|
||
| 测量与 OCR | 第三方箱规、测量草稿、称重图片上传/预览/OCR 重试、OCR 原值、置信度、人工修正、确认、提交审核 | 汇总重量和体积以服务端结果为准；不覆盖 OCR 原值 |
|
||
| 测量审核 | 原单、第三方测量、OCR 三组数据对比；通过、驳回、审核历史、异常放行 | 通过/驳回/放行携带幂等键；放行必须有专属权限和原因 |
|
||
| 费用快照 | 最新费用、规则版本、价格版本、实际量、折算量、计费量、单价、附加费、总额、发送状态 | 正常流程只读；已发布费用可按权限调整且必须填写原因 |
|
||
| 托盘库位 | 托盘号、分配体积/箱数、库位编码和占用结果 | 只读，不让前端拼托盘号、选择或占用库位 |
|
||
|
||
### 3.3 全局装配变更
|
||
|
||
- `src/app/router/index.ts`：装配二期模块路由。
|
||
- `src/core/navigation/adminNavigation.ts`：在“国内仓”下增加入库单、库位、托盘；新增“头程计费”分组；在客户或海外仓基础资料分组增加“海外仓阶梯费用”。
|
||
- 路由和导航测试同步更新。
|
||
- IAM 权限页面无需业务改造；后端返回二期权限资源后沿用现有展示和授权能力。
|
||
- 不恢复“接收审核”“费用项目”“完整财务管理”等原型菜单。
|
||
|
||
## 四、Client 页面变更清单
|
||
|
||
Client 只修改现有 `FirstLegOrdersView.vue` 的订单详情抽屉，新增“入库与费用”只读区，不改路由、导航或模块注册。
|
||
|
||
展示内容：
|
||
|
||
- 入库结果：入仓码、入库状态、完成时间、平台收货仓。
|
||
- 实测汇总：实际箱数、实重、净重、实测体积、材积重、计费重量/体积。
|
||
- 托盘库位：托盘数、托盘号、分配体积、箱数和库位编码。
|
||
- 费用结果：计费模式、换算系数、实际量、折算量、最终计费量、单价、小计、附加费、总额、币种、规则/价格版本和发送时间。
|
||
- 只展示公开备注；不展示内部备注、原始操作历史、内部原因和操作人 ID。
|
||
|
||
状态处理：
|
||
|
||
- 草稿订单不请求入库费用接口，显示“订单提交后可查看入库结果”。
|
||
- 后端业务码 `A0404` 作为中性待处理态，显示“入库及费用结果尚未发布”。
|
||
- 其他失败只影响此区块，保留订单详情并提供区块级重试。
|
||
- 快速切换订单时使用请求序号或 `orderId` 校验，旧响应不得覆盖新订单。
|
||
- 不增加客户确认、调整、审核、发送费用或照片下载动作。
|
||
|
||
## 五、真实接口域
|
||
|
||
前端实现直接读取相邻 Controller/DTO，不需要另行准备后端接口文档。首批任务按以下接口域联调：
|
||
|
||
| 接口域 | Controller 入口 | 前端用途 |
|
||
|---|---|---|
|
||
| 入库查询 | `firstleg/.../PlatformInboundOrderController.java` | Admin 入库列表和聚合详情 |
|
||
| 测量/OCR | `firstleg/.../PlatformInboundMeasurementController.java` | 测量草稿、提交、OCR 登记/修正/确认 |
|
||
| 测量审核 | `firstleg/.../PlatformInboundMeasurementReviewController.java` | 通过、驳回、异常放行、审核历史 |
|
||
| FBA 基础资料 | `firstleg/.../PlatformFbaMasterDataController.java` | 客户规则和船司价格版本维护 |
|
||
| FBA 费用 | `firstleg/.../PlatformFbaPricingController.java` | 最新费用、异常恢复接口、已发布费用调整 |
|
||
| 称重图片 | `file/.../PlatformMeasurementImageController.java` | 上传、OCR 重试和鉴权查看 |
|
||
| 托盘 | `warehouse/.../PlatformPalletController.java` | 托盘 CRUD |
|
||
| 库位 | `warehouse/.../PlatformLocationController.java` | 库位 CRUD、状态和可用库位查询 |
|
||
| 海外仓阶梯费用 | `warehouse/.../PlatformOverseasStorageFeeController.java` | 平台端客户级天数阶梯仓储费 CRUD |
|
||
| 商户结果 | `firstleg/.../MerchantInboundBillingController.java` | Client 订单入库与费用只读展示 |
|
||
|
||
共同约定：
|
||
|
||
- 浏览器代码使用现有 `/api` 基地址，不硬编码 Gateway 地址。
|
||
- 普通业务 HTTP 200 后仍需判断响应体 `code === "200"`。
|
||
- Java Long 在 JSON 中按字符串处理，前端不得转为 `Number`。
|
||
- Admin 当前接口显式需要代表目标客户的 `tenantId`；切换企业必须清空仓库、详情、编辑、上传和幂等上下文。
|
||
- 409 表示版本或并发冲突，页面应刷新最新详情，不静默覆盖。
|
||
- 审核通过、驳回、异常放行和费用写操作按 Controller 要求携带 `Idempotency-Key`。
|
||
|
||
## 六、多对话并行任务表
|
||
|
||
### 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 结果为 `[]`，模块依赖边界测试已通过。
|
||
- Admin 二期页面已再次按平台后台原型校正搜索条件、表格字段、字段顺序和详情分区；视觉组件统一复用现有 `QueryToolbar`、`DataTable`、`AppDrawer` 及状态组件。
|
||
- 原型字段只在当前后端 Controller/DTO 支持时落地；未恢复接收审核、客户确认、报关、智能装柜、托盘状态/启停、尺寸/承重及无接口的导入导出。
|
||
- Client 入库费用区沿用既有订单详情视觉，补充换算系数、舍入精度和规则/价格版本，保持只读并继续使用“入仓码”业务术语。
|
||
- 本轮未修改 `baiyue-firstleg/`；8.1 节的 Client 服务端响应数据暴露风险仍是上线阻断，不影响本轮前端任务完成状态。
|
||
|
||
### 6.1 任务定义
|
||
|
||
下表中未写应用前缀的 Admin 路径均相对 `apps/admin-web/src/`。
|
||
|
||
| ID | 对话任务 | 负责范围和文件所有权 | 交付与验收 | 依赖 | 波次 |
|
||
|---|---|---|---|---|---|
|
||
| `P2-ADM-01` | 入库列表与聚合查询 | 独占 `modules/inbounds/core/**`、`pages/InboundOrdersView.vue` 及测试 | 本域 types/API；企业选择、四页签、筛选、分页、操作列第一列、概览/历史只读组件、加载/空/错/权限态 | 只读入库查询 Controller/DTO | W1 |
|
||
| `P2-ADM-02` | 测量草稿与箱规 | 独占 `modules/inbounds/measurement/**` 及测试 | 本域 types/API/组件；第三方箱规、测量草稿、保存、提交审核、版本冲突和未保存保护 | 只读测量 Controller/DTO | W1 |
|
||
| `P2-ADM-03` | 称重图片与 OCR | 独占 `modules/inbounds/weight/**` 及测试 | 本域 types/API/组件；上传、预览、OCR 重试、原值/置信度、人工修正和确认 | 只读 File、测量 Controller/DTO | W1 |
|
||
| `P2-ADM-04` | 测量审核 | 独占 `modules/inbounds/review/**` 及测试 | 本域 types/API/组件；三组数据对比、历史、通过、驳回、异常放行、幂等和权限 | 只读审核 Controller/DTO/Service | W1 |
|
||
| `P2-ADM-05` | 入库费用快照 | 独占 `modules/inbounds/fee/**` 及测试 | 本域 types/API/组件；最新费用、完整计价过程、状态和已发布费用调整；不串常规 calculate/confirm/send | 只读 FBA 费用 Controller/DTO/Service | W1 |
|
||
| `P2-ADM-06` | 客户计费规则 | 独占 `modules/fba-pricing/customer-rules/**` 及测试 | 查询、详情、新版本、停用、权限和未保存保护 | 只读 `PlatformFbaMasterDataController` 客户规则契约 | W1 |
|
||
| `P2-ADM-07` | 船司 FBA 价格 | 独占 `modules/fba-pricing/carrier-rates/**` 及测试 | 查询、详情、新版本、停用、起运仓/渠道/船司/FBA 仓/价格和有效期 | 只读 `PlatformFbaMasterDataController` 价格契约 | W1 |
|
||
| `P2-ADM-08` | 库位管理 | 独占 `modules/warehouse-resources/locations/**` 及测试 | 企业/仓库级联、筛选分页、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-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 |
|
||
|
||
### 6.2 推荐并行波次
|
||
|
||
```text
|
||
W1（新增任务可独立开发）:
|
||
ADM-01 + ADM-02 + ADM-03 + ADM-04 + ADM-05
|
||
ADM-06 + ADM-07 + ADM-08 + ADM-09 + ADM-12 + CLI-01
|
||
↓
|
||
W2（2 个并行对话）: ADM-10 + QA-02
|
||
↓
|
||
W3（1 个集成对话）: ADM-11
|
||
↓
|
||
W4: QA-01 跨模块联调、构建和回归
|
||
```
|
||
|
||
`ADM-12` 没有入库主链路依赖，可独立实现；完成后需要把其路由、菜单和权限态纳入 Admin 集成回归。原关键路径仍是 `ADM-01 至 ADM-05 → ADM-10 → ADM-11 → QA-01`。
|
||
|
||
### 6.3 多对话协作规则
|
||
|
||
- 每个对话只修改任务表声明的文件边界；发现需要改公共文件时留给 `P2-ADM-11`。
|
||
- `router/index.ts`、`adminNavigation.ts` 和对应测试只能由集成任务修改。
|
||
- 库位和托盘任务不得各自创建或修改同一个 `warehouse-resources/routes.ts`。
|
||
- 入库各业务域分别维护本域 `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/`。
|
||
|
||
## 七、当前后端源码未落地、暂不开发的范围
|
||
|
||
| 能力 | 本轮处理 | 原因 |
|
||
|---|---|---|
|
||
| 到仓预报和线下预约结果 | 暂不开发 | 无商户/平台公开接口 |
|
||
| 签到、分批收货、处理单元 | 暂不开发 | 无匹配 Controller |
|
||
| 标签打印和换标 | 暂不开发 | Print 服务仍是骨架，无业务公开接口 |
|
||
| 收货冲正 | 暂不开发 | 无匹配 Controller |
|
||
| 申报实测差异通知 | 暂不开发 | 无匹配 Controller |
|
||
| 上架任务和位置历史 | 暂不开发 | 当前只有托盘/库位和自动占用，无平台作业接口 |
|
||
| 通用费用项目白名单 | 暂不开发 | C6 未确认且无独立 Controller |
|
||
| 通知失败人工重试 | P1 候选 | 当前无明确平台公开接口 |
|
||
| 入库后换位 | P1 候选 | 当前无平台公开接口 |
|
||
| 测量视频、单票导出 | P1 候选 | 当前无明确契约 |
|
||
| 客户照片查看 | 暂不开发 | 当前无商户文件下载接口 |
|
||
|
||
## 八、上线阻断和风险
|
||
|
||
### 8.1 Client 数据暴露风险（上线阻断）
|
||
|
||
当前 `MerchantInboundBillingService` 直接返回平台侧 `InboundOrderDetail`，其中可能包含全部 `internalNotes` 和未按商户可见性过滤的 `files`。即使 Client 页面不渲染，这些字段仍会下发到浏览器。
|
||
|
||
前端必须做到：
|
||
|
||
- 商户 DTO 不声明、不读取、不渲染内部备注和原始内部历史。
|
||
- 不记录或展示原始响应对象。
|
||
|
||
但前端无法消除网络响应中的数据暴露，因此正式上线前仍需后端改为商户专用 DTO 或服务端字段过滤。该项不在本轮后端修改授权范围内，只登记为上线阻断。
|
||
|
||
### 8.2 需求和实现风险
|
||
|
||
- V2 C1-C8 尚未正式确认；若产品推翻当前自动计费入库流程，需要重新评估页面动作和任务边界。
|
||
- Admin 多个接口仍要求前端显式传目标 `tenantId`，与 V2“不相信前端 tenantId”的文字描述不同；前端按现有 Controller 调用，最终数据范围仍由服务端校验。
|
||
- 正常审核通过会自动完成后续动作，属于高影响写操作；页面确认文案必须明确结果，并防止重复点击。
|
||
- 计费规则和船司价格接口当前返回列表而非分页对象；页面不要先假设服务端分页。
|
||
- 托盘接口没有状态和启停能力；库位才有 `AVAILABLE/RESERVED/OCCUPIED/DISABLED` 状态。
|
||
- 海外仓阶梯费用当前没有启停、计费单位和生效日期字段；前端不得自行补造，也不得将该配置接入现有 FBA 自动计费。
|
||
|
||
## 九、每个任务的统一完成标准
|
||
|
||
- 严格按真实权限控制路由、菜单和按钮；前端权限只控制展示，服务端继续最终授权。
|
||
- 覆盖加载、空态、失败、无权限、业务冲突、重复操作和数据过期。
|
||
- 所有业务表格操作列在第一列，桌面端可固定左侧；窄屏不依赖表格末端操作。
|
||
- 所有 ID 保持字符串，金额、体积、重量和换算系数不硬编码、不自行推导为业务事实。
|
||
- 写操作成功后刷新服务端状态；409 或版本冲突提示用户并重载，不静默覆盖。
|
||
- Admin 运行 `pnpm test`、`pnpm typecheck`、`pnpm build`。
|
||
- Client 运行 `pnpm test`、`pnpm typecheck`、`pnpm build`。
|
||
- 不修改后端、不启动本地 Java/Nacos/数据库；联调默认通过测试 Gateway 的 `/api` 代理。
|