代理在线充值

docs/feature-034-agent-wallet-qr-recharge/功能总结.md

@@ -0,0 +1,85 @@
+# 代理钱包桌面扫码充值
+
+前端调用顺序、请求示例和页面状态详见 [`代理钱包扫码充值接口对接说明.md`](代理钱包扫码充值接口对接说明.md)。
+
+## 功能范围
+
+代理账号可在后台为当前所属店铺主钱包创建微信 Native 或支付宝当面付扫码充值。平台与超级管理员继续使用既有线下代充和企业微信审批，两个创建路径不共用权限。
+
+充值订单相关响应统一返回：
+
+- `recharge_source=platform_offline`、`recharge_source_name=平台线下代充`
+- `recharge_source=agent_online`、`recharge_source_name=代理在线自充`
+
+来源由受控支付方式推导：`offline` 为平台线下代充，`wechat|alipay` 为代理在线自充。列表支持 `recharge_source` 筛选，不新增重复数据库列。
+
+## API 对接
+
+### 查询可用支付方式
+
+`GET /api/admin/agent-recharges/payment-methods`
+
+仅代理账号可用，返回当前真正可预下单、验签和查单的 `wechat`、`alipay`，以及在线充值金额范围 `10000～100000000` 分。
+
+### 创建充值订单
+
+`POST /api/admin/agent-recharges`
+
+代理在线自充请求仅允许：
+
+```json
+{
+  "amount": 10000,
+  "payment_method": "wechat",
+  "request_id": "客户端生成的唯一请求标识"
+}
+```
+
+响应包含 `recharge_id`、`payment_no`、`qr_content`、`recharge_source` 和充值状态。前端直接使用 `qr_content` 渲染二维码，不展示或记录支付配置、商户身份和密钥。
+
+平台线下代充使用 `payment_method=offline`，并按既有契约提交目标 `shop_id`、支付凭证和备注；响应来源为 `platform_offline`。
+
+### 列表、详情与支付状态
+
+- `GET /api/admin/agent-recharges?recharge_source=agent_online`
+- `GET /api/admin/agent-recharges/:id`
+- `GET /api/admin/agent-recharges/:id/payment-status`
+
+列表和详情均返回充值来源。支付状态接口仅用于在线充值，只读取本地充值单和支付单，返回支付确认时间与钱包完成时间，不返回 `qr_content`、内部重试错误或其他钱包余额，也不调用第三方渠道。
+
+前端在页面可见时可每 3 秒轮询；进入已完成、已关闭、已退款或已驳回终态后停止轮询。
+
+## 支付与到账
+
+第三方收款成功后，回调只确认支付事实并写入 `agent_recharge.payment_confirmed.v1` Outbox。Worker 在独立事务中复用主钱包入账能力，以充值记录 ID 的唯一流水保证最多入账一次，并将充值状态从已支付推进为已完成。
+
+支付单保存创建时的 `payment_config_id` 和 `merchant_identity`：微信记录商户号，支付宝记录应用 ID，供未来导出按实际收款身份核对。该内部字段不在创建、列表、详情或支付状态响应中暴露。
+
+## 异常恢复
+
+Worker 每分钟调度一次恢复任务，并使用唯一任务约束避免并发重复扫描。任务固定扫描最多 50 张创建超过 2 分钟的代理在线待支付单：
+
+- 尚无付款内容：使用原 `payment_no` 重试预下单。
+- 已有付款内容：按创建时的支付方式与配置主动查单。
+- 渠道确认成功：复用统一支付确认用例。
+- 渠道明确关闭：条件关闭仍待支付的本地单。
+- 超时、未知或渠道异常：保持原状态，等待后续重试。
+
+微信、支付宝每次预下单和查单均写 Integration Log，其中包含耗时和安全摘要，不保存密钥或完整二维码内容。
+
+## 部署与回滚
+
+推荐顺序：
+
+1. 执行 `000197`、`000198` 数据库迁移。
+2. 确认微信商户号、证书、APIv3 Key、回调地址，或支付宝应用 ID、私钥、公钥、回调地址完整。
+3. 同时发布 API 与 Worker，确认回调路由、Outbox Relay、代理充值消费者和恢复任务均已装配。
+4. 最后开放前端扫码充值入口。
+
+回滚时先关闭前端入口和在线支付方式，停止创建新单；回调、恢复任务、Outbox Relay 和钱包消费者必须继续处理已收款订单。不得删除待支付、已支付或待入账的支付事实。确认资金单全部收敛后，才可回滚应用与数据库迁移。
+
+## 静态验收与未验证边界
+
+本次按用户要求不启动 API/Worker，不连接 PostgreSQL/Redis，不调用真实支付，不发送回调，也不运行自动化测试。交付仅执行格式化、差异检查、编译、静态分析、OpenAPI 生成和 OpenSpec 严格校验。
+
+上线前由发布方核对支付配置与回调公网可达性，并使用一笔微信和一笔支付宝订单确认渠道能返回非空 `qr_content`。回调丢失、重复回调与 Worker 重放可在需要时按上述状态和唯一流水口径人工核对。