5.8 KiB
5.8 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；页面恢复时查询原任务，终态后停止轮询，不能因刷新或超时重复创建。
- 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
- 先确认接口待补充项和后台权限编码。
- 按任务清单分模块适配后台页面和 API 类型。
- 完成后台接口 Mock/联调、权限组合和错误场景验收。
- H5/C 端另行创建或关联变更，不在本变更中合并实现。
Open Questions
- 退款和代理充值详情是否需要直接返回企微审批节点人员列表？
- 代理在线充值创建和查询的最终权限编码是否与现有
agent_recharge:*权限保持一致；导出权限编码已由接口文档确定。 - 批量任务、导出任务、企微审批和 Gateway 超时的稳定错误码及重试语义是什么？