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

1. Contract and API Types

• 1.1 src/types/api/agentRecharge.ts：AgentRecharge 新增 external_transaction_no、offline_payment_method_id、offline_payment_method_code、offline_payment_method_name、other_voucher_key（string[] | null），保持 payment_transaction_id 与 payment_voucher_key 语义不变。
• 1.2 扩展 CreateAgentRechargeOfflineRequest：新增必填 offline_payment_method_id、必填 external_transaction_no、可选 other_voucher_key（最多 5 个）。
• 1.3 新增 AgentRechargePaymentVoucherOcrRequest { payment_voucher_key } 与 AgentRechargePaymentVoucherOcrResponse { external_transaction_no }。
• 1.4 在 src/types/api/index.ts 导出新增类型。

2. Agent Recharge Service

• 2.1 src/api/modules/agentRecharge.ts 新增 getSelfRechargePaymentMethods()，请求 GET /api/admin/agent-self-recharge-payment-methods。
• 2.2 新增 recognizePaymentVoucher(data)，请求 POST /api/admin/agent-recharges/payment-voucher-ocr，超时不低于 30000 毫秒。
• 2.3 保留旧 getPaymentMethods() 方法，但页面不再调用。

3. Online Recharge Available Methods

• 3.1 在线充值弹窗改用 getSelfRechargePaymentMethods() 读取 methods / min_amount / max_amount，并把 wechat、alipay 映射为微信、支付宝选项。
• 3.2 methods 为空时提示「当前暂无可用的在线支付方式」并禁用提交，不解释原因。
• 3.3 超管视角不请求该接口（403 兜底）；允许范围变更后不刷新已创建的待支付单。

4. Super Admin Allow-Range Config

• 4.1 允许范围沿用系统配置页通用渲染：GET /api/admin/system-configs 读取、PUT /api/admin/system-configs/{key} 提交字符串化 value；不新增专用接口与专用页面。
• 4.2 wechat_only / alipay_only / both 在系统配置页展示与选择时显示中文标签，未命中映射时回退原值。
• 4.3 新增「代理自充设置」菜单（仅超级管理员），跳转到系统配置页面并带 module=c2b.payment；系统配置页支持从 route.query.module 初始化模块筛选。
• 4.4 在 zh.json、en.json 的 menus.settings 下补充 agentSelfRecharge 中英文文案，并清理系统配置页预存的空样式块。

5. Offline Pre-deposit Create Dialog

• 5.1 新增「收款方式」下拉，数据来自 GET /api/admin/employee-collection-payment-methods（enabled=true、page_size=100），必填，提交 offline_payment_method_id。
• 5.2 新增「交易流水号」输入（必填、可编辑），并提示对照凭证核对。
• 5.3 新增「其他凭证」上传（可选，最多 5 个），提交 other_voucher_key；支付凭证仍必填且至少 1 个，两者分开提交。
• 5.4 VoucherUpload 新增可选 contentType prop 并透传给 getUploadUrl 与 uploadFile；代理充值线下凭证固定传 image/jpeg。
• 5.5 线下提交体按契约组装：{ amount, payment_method: offline, shop_id, offline_payment_method_id, external_transaction_no, payment_voucher_key, other_voucher_key, remark }，未填写的可选字段不提交。

6. Voucher OCR Prefill

• 6.1 支付凭证区新增「识别凭证」按钮，取第一个已上传凭证 Key；未上传凭证时禁用。
• 6.2 识别期间展示 loading（按钮与交易流水号字段）并防重复点击，超时不低于 30 秒。
• 6.3 识别成功写入 external_transaction_no，字段保持可编辑；失败只提示，不清空已填内容、不阻断提交。
• 6.4 不预填金额、付款人、付款时间与备注。

7. List and Detail Display

• 7.1 列表新增线下交易流水号与线下收款方式（offline_payment_method_name 快照）展示，仅线下单展示。
• 7.2 详情新增交易流水号、收款方式（offline_payment_method_code 与 offline_payment_method_name 快照）与其他凭证预览；在线单只展示 payment_transaction_id。
• 7.3 不使用 offline_payment_method_id 反查字典当前值，也不做交易流水号重复校验。
• 7.4 列表不新增交易流水号筛选，保持后端已有查询参数集合不变。

8. Verification

• 8.1 校验 methods 为空、超管调用新接口 403、允许范围变更不影响存量待支付单三种情况。
• 8.2 校验 OCR 成功、失败、超时三条路径均不阻断人工填写与提交。
• 8.3 校验线下单与在线单的两类交易号、收款方式快照与其他凭证展示正确。
• 8.4 运行 npm run build（含 vue-tsc --noEmit）与 npm run check:encoding。
• 8.5 运行 openspec validate update-agent-self-recharge-and-offline-approval --strict。