docs/二期/二期前端页面清单与多对话并行任务表.md

二期前端页面清单与多对话并行任务表

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

本轮不存在“等待后端提供接口文档”的前置任务。每个前端对话直接只读当前工作区 baiyue-firstleg/ 中的 Controller、DTO、Service、Repository、OpenAPI 和权限 SQL；发现契约问题只登记，不修改后端。

一、结论

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

• Admin 新增 6 个正式菜单页面：入库单、客户计费规则、船司 FBA 价格、库位管理、托盘管理、海外仓阶梯费用。
• 入库详情承载测量/OCR、审核、费用快照、托盘库位结果和历史，不再新增独立“接收审核”页面。
• 正常流程由“测量审核通过”触发后端自动计费、发布费用并完成入库；前端不把 calculate → confirm → send 串成常规人工流程。
• 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 推荐并行波次

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 代理。