3.4 KiB
3.4 KiB
Context
七月迭代后端实现已形成一份统一的前端联调说明，但需求横跨多个后台业务域，并同时涉及 H5/C 端接口。若不先固定边界，前端容易继续依赖旧字段、重复计算服务端事实，或误把 C 端工作纳入后台改造。
Goals / Non-Goals
- Goals: 固定后台页面的调用顺序、字段来源、权限边界、金额单位、异步任务和错误处理规则。
- Goals: 明确 H5/C 端依赖并标注为外部范围，不在本提案任务中实施。
- Non-Goals: 不新增后端接口，不修改数据库，不实现企微/Gateway/Redis/Asynq/对象存储服务端逻辑。
- Non-Goals: 不修改 H5 或 C 端页面、组件和调用代码。
Decisions
- Decision: 后端返回值是业务事实来源。前端不得自行推导实名状态、支付方式、预计到期、可用金额、欠款、审批状态或异步任务状态。
- Decision: 金额统一以分传输和计算，展示层才转换为元；信用和资金更新必须携带服务端返回的
version。 - Decision: H5/C 端接口在规格中单独列为外部依赖，后台只负责在需要时保持接口契约一致。
- Decision: 企微审批继续由原退款/线下充值业务入口触发，后台只读展示
approval_provider、approval_status和approval_status_name，不恢复旧人工审批按钮。 - Decision: 设备批量分配复用设备导入任务页面和任务外壳，通过
operation_type区分分配代理与设置套餐系列。 - Decision: 系列套餐授权使用现有
packages[]数组完成多选，授权详情中的package_id用于已授权标记，套餐列表中的公司成本价与授权成本价分开使用。 - Decision:
docs/所需接口文档是本变更的接口契约索引；页面 API 类型、请求参数、枚举和响应字段必须以对应模块文档为准，不从七月说明中自行扩展路径。 - Decision: 文件类业务统一采用
POST /api/admin/storage/upload-url获取预签名 URL，直传成功后仅把file_key传给批量订购或设备分配接口。 - Decision: 批量订购、设备分配和导出均保存服务端返回的任务 ID；页面恢复时查询原任务，终态后停止轮询，不能因刷新或超时重复创建。
Risks / Trade-offs
- 接口 DTO 若未按说明返回，页面无法可靠展示审批人、历史资产标识或新旧字段；通过联调清单阻断实现前确认。
- 设备批量分配接口文档已明确任务列表和详情仅平台用户可操作，前端不得向代理账号展示任务入口或通过前端绕过权限。
- H5/C 端不在本次实现范围，后台只能依赖后端提供的最终字段，跨端验收需要单独安排。
- 部分接口文档只给出字段模型，缺少业务错误码、权限编码和分页默认值；这些列入待确认清单。
Migration Plan
- 先确认接口待补充项和后台权限编码。
- 按任务清单分模块适配后台页面和 API 类型。
- 完成后台接口 Mock/联调、权限组合和错误场景验收。
- H5/C 端另行创建或关联变更，不在本变更中合并实现。
Open Questions
- 退款和代理充值详情是否需要直接返回企微审批节点人员列表？
- 各新增后台页面和按钮的最终权限编码是什么？
- 批量任务、导出任务、企微审批和 Gateway 超时的稳定错误码及重试语义是什么？