52 lines
5.8 KiB
Markdown
52 lines
5.8 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；页面恢复时查询原任务，终态后停止轮询，不能因刷新或超时重复创建。
|
||
- Decision: 代理钱包在线充值和平台线下代充共用 `POST /api/admin/agent-recharges`，但使用两套互斥的表单模型。在线表单只允许 `amount`、`payment_method` 和 `request_id`；线下表单才允许 `shop_id`、`payment_voucher_key` 和 `remark`，不能把线下表单对象整体复用到在线请求中。
|
||
- Decision: 在线充值弹窗打开时先请求 `/api/admin/agent-recharges/payment-methods`，支付方式和金额上下限完全由响应驱动。金额在界面显示为元，提交前转换为整数分；支付方式为空时禁止提交并显示无可用支付方式提示。
|
||
- Decision: 在线创建成功后只使用返回的 `recharge_id` 查询 `/api/admin/agent-recharges/{id}/payment-status`，把原始 `qr_content` 交给二维码组件。二维码弹窗可见且订单非终态时每 3 秒轮询；弹窗隐藏、页面进入后台或状态进入 3/4/5/6 后停止轮询。
|
||
- Decision: `request_id` 是一次主动在线充值的幂等键。网络超时或断开只用同一个 ID 重试一次并复用后端返回的原订单/二维码；用户关闭弹窗后重新发起充值或改变金额/支付方式时生成新的 ID，冲突响应不得覆盖原表单或自动创建新订单。
|
||
- Decision: 充值列表和详情均以 `recharge_source` 做业务分支，并优先展示 `recharge_source_name`。在线单展示支付方式、第三方流水和支付/完成时间；线下单展示凭证、备注、提交人和审批状态。存在企微审批来源或实例时只读展示审批进度，不显示确认/驳回操作。
|
||
- Decision: 充值相关导出权限按场景拆分：业务列表入口使用 `agent_recharge:export`，导出任务详情使用 `export_task:agent_recharge_detail`，下载文件使用 `export_task:agent_recharge_download`。权限不足时隐藏入口或操作，不通过前端绕过权限。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- 接口 DTO 若未按说明返回，页面无法可靠展示审批人、历史资产标识或新旧字段；通过联调清单阻断实现前确认。
|
||
- 支付配置为空或二维码内容为空时，在线充值无法继续；通过动态支付方式加载、空状态和联调环境中微信/支付宝二维码内容非空校验阻断上线。
|
||
- 在线创建请求若错误生成新的 `request_id`，可能产生重复充值单；通过提交态保存 ID、幂等重试和冲突保护降低重复支付风险。
|
||
- `status=2` 只代表第三方已支付，不代表钱包已经入账；通过以 `status=3` 作为余额刷新条件避免提前展示到账。
|
||
- 设备批量分配接口文档已明确任务列表和详情仅平台用户可操作，前端不得向代理账号展示任务入口或通过前端绕过权限。
|
||
- H5/C 端不在本次实现范围，后台只能依赖后端提供的最终字段，跨端验收需要单独安排。
|
||
- 部分接口文档只给出字段模型，缺少业务错误码、权限编码和分页默认值；这些列入待确认清单。
|
||
|
||
## Migration Plan
|
||
|
||
1. 先确认接口待补充项和后台权限编码。
|
||
2. 按任务清单分模块适配后台页面和 API 类型。
|
||
3. 完成后台接口 Mock/联调、权限组合和错误场景验收。
|
||
4. H5/C 端另行创建或关联变更，不在本变更中合并实现。
|
||
|
||
## Open Questions
|
||
|
||
- 退款和代理充值详情是否需要直接返回企微审批节点人员列表？
|
||
- 代理在线充值创建和查询的最终权限编码是否与现有 `agent_recharge:*` 权限保持一致；导出权限编码已由接口文档确定。
|
||
- 批量任务、导出任务、企微审批和 Gateway 超时的稳定错误码及重试语义是什么？
|