# 代理钱包桌面扫码充值

前端调用顺序、请求示例和页面状态详见 [`代理钱包扫码充值接口对接说明.md`](代理钱包扫码充值接口对接说明.md)。

## 功能范围

代理账号可在后台为当前所属店铺主钱包创建微信 H5/MWEB 或支付宝 WAP 支付链接扫码充值。微信按当前配置选择 v3 H5 或 v2 MWEB，前端自行渲染二维码，支付宝无需开通当面付。平台与超级管理员继续使用既有线下代充和企业微信审批，两个创建路径不共用权限。

充值订单相关响应统一返回：

- `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` 是支付 HTTPS URL，前端直接渲染二维码，不展示或记录支付配置、商户身份和密钥。

平台线下代充使用 `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 重放可在需要时按上述状态和唯一流水口径人工核对。