43 lines
3.4 KiB
Markdown
43 lines
3.4 KiB
Markdown
## 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
|
||
|
||
1. 先确认接口待补充项和后台权限编码。
|
||
2. 按任务清单分模块适配后台页面和 API 类型。
|
||
3. 完成后台接口 Mock/联调、权限组合和错误场景验收。
|
||
4. H5/C 端另行创建或关联变更，不在本变更中合并实现。
|
||
|
||
## Open Questions
|
||
|
||
- 退款和代理充值详情是否需要直接返回企微审批节点人员列表？
|
||
- 各新增后台页面和按钮的最终权限编码是什么？
|
||
- 批量任务、导出任务、企微审批和 Gateway 超时的稳定错误码及重试语义是什么？
|