one-pipe-system/openspec/changes/update-agent-self-recharge-and-offline-approval/proposal.md

Change: 代理自充收款方式配置与线下预存款审批字段

Why

8 月迭代 AUG26-017（对应 PRD-008-021 与 PRD-008-013）包含两项要求：代理在线自充的收款方式由超级管理员维护「允许范围」（仅微信 / 仅支付宝 / 同时支持），代理实际可用方式取允许范围与当前可用商户方式的交集，交集为空时不允许创建在线充值单；线下预存款审批需要补齐「收款方式」「交易流水号」「其他凭证」，其中交易流水号支持从付款凭证 OCR 预填。

后台管理端现状与该要求有差距：在线充值直接调用旧接口 GET /api/admin/agent-recharges/payment-methods，线下代充表单只有店铺、支付凭证与运营备注，充值列表与详情也没有交易流水号、线下收款方式快照与其他凭证字段。

本次按后端实际 OpenAPI 契约对齐：可用方式改读 GET /api/admin/agent-self-recharge-payment-methods；允许范围的读取与写入沿用受控系统配置 GET /api/admin/system-configs 与 PUT /api/admin/system-configs/{key}；交易流水号识别使用 POST /api/admin/agent-recharges/payment-voucher-ocr。

What Changes

• 在线充值可用支付方式改由 GET /api/admin/agent-self-recharge-payment-methods 提供，读取 methods、min_amount、max_amount；旧接口 GET /api/admin/agent-recharges/payment-methods 保留但前端不再调用。
• methods 为空时只提示「当前暂无可用的在线支付方式」并禁用提交，不解释是被允许范围限制还是无可用商户。
• 代理自充允许范围不新增专用接口与专用页面：配置项归属 c2b.payment 模块，超管沿用「系统配置」页面，通过 GET /api/admin/system-configs 读取、PUT /api/admin/system-configs/{key} 提交字符串化 value；前端不硬编码配置 Key，允许范围对代理与平台账号不可见。
• 新增「代理自充设置」菜单（仅超级管理员），跳转到系统配置页面并带 module=c2b.payment 过滤条件；系统配置页面支持从路由 query 初始化模块筛选。
• 线下预存款创建弹窗新增：收款方式（数据源 GET /api/admin/employee-collection-payment-methods 的启用项，提交 offline_payment_method_id）、交易流水号（必填、可编辑）、其他凭证（可选，最多 5 个 other_voucher_key）；支付凭证 payment_voucher_key 仍必填且至少 1 个，与其他凭证分开提交。
• 新增付款凭证 OCR 预填：POST /api/admin/agent-recharges/payment-voucher-ocr 请求 { payment_voucher_key }、响应只有 { external_transaction_no }；结果只作预填且始终可编辑，识别失败不阻断人工填写与提交，请求超时不低于 30 秒并展示 loading。
• 充值列表与详情展示新增字段：external_transaction_no、offline_payment_method_id、offline_payment_method_code、offline_payment_method_name、other_voucher_key；线下单收款方式使用编码/名称快照展示，不用 id 反查字典当前值。
• 代理充值列表不新增交易流水号筛选：GET /api/admin/agent-recharges 未提供该查询参数，交易流水号仅做展示。
• 付款凭证与其他凭证获取上传地址时显式声明 content_type 为 image/jpeg。
• 交易流水号 external_transaction_no 与在线渠道 payment_transaction_id 独立展示、互不覆盖；前端不做交易流水号重复校验。
• 不实现后端接口、商户池逻辑、企微审批回调与 H5/C 端页面。

Impact

• Affected specs: agent-recharge、system-config-management
• Affected code:
  • src/types/api/agentRecharge.ts、src/api/modules/agentRecharge.ts、src/types/api/index.ts
  • src/views/finance/agent-recharge/index.vue、src/views/finance/agent-recharge/detail.vue
  • src/views/settings/system-configs/index.vue、src/types/api/systemConfig.ts
  • src/router/routesAlias.ts、src/router/routes/asyncRoutes.ts
  • src/components/business/VoucherUpload.vue
  • src/locales/langs/{zh,en}.json
• Dependencies: docs/产品迭代8月份/代理.md
• Out of scope: 代理自充设置独立页面、允许范围审计查询接口、企业账号分支、H5/C 端在线充值。