fix: 回调配置, 调整信用位置, 套餐

openspec/changes/update-july-iteration-frontend-integration/design.md

@@ -20,10 +20,19 @@
 - 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 端不在本次实现范围，后台只能依赖后端提供的最终字段，跨端验收需要单独安排。
 - 部分接口文档只给出字段模型，缺少业务错误码、权限编码和分页默认值；这些列入待确认清单。
@@ -38,5 +47,5 @@
 ## Open Questions
 
 - 退款和代理充值详情是否需要直接返回企微审批节点人员列表？
-- 各新增后台页面和按钮的最终权限编码是什么？
+- 代理在线充值创建和查询的最终权限编码是否与现有 `agent_recharge:*` 权限保持一致；导出权限编码已由接口文档确定。
 - 批量任务、导出任务、企微审批和 Gateway 超时的稳定错误码及重试语义是什么？