break
8fc667daee
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m7s
微信按当前 v2/v3 配置分别生成 MWEB/H5 链接，支付宝复用 C 端 WAP 链接，并让可用支付方式基于生效配置判断。 Constraint: 支付链接统一通过 qr_content 返回，由前端渲染二维码；按要求不运行测试 Rejected: 微信 Native 与支付宝当面付 | 会引入非当前商户配置所需的额外产品开通 Confidence: high Scope-risk: moderate Directive: 微信 H5/MWEB 二维码仅承诺系统相机或外部浏览器扫码链路 Tested: 相关 Go 包编译通过；gofmt 与 git diff --check 通过 Not-tested: 按用户要求未运行自动化测试及真实支付联调
86 lines
4.7 KiB
Markdown
86 lines
4.7 KiB
Markdown
# 代理钱包桌面扫码充值
|
||
|
||
前端调用顺序、请求示例和页面状态详见 [`代理钱包扫码充值接口对接说明.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 重放可在需要时按上述状态和唯一流水口径人工核对。
|