让代理充值复用现有网页支付能力

微信按当前 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: 按用户要求未运行自动化测试及真实支付联调
2026-07-30 11:41:50 +08:00
parent 0f4f0d1176
commit 8fc667daee
24 changed files with 692 additions and 352 deletions
--- a/docs/feature-034-agent-wallet-qr-recharge/代理钱包扫码充值接口对接说明.md
+++ b/docs/feature-034-agent-wallet-qr-recharge/代理钱包扫码充值接口对接说明.md
@@ -9,7 +9,7 @@
 1. **同一个创建接口有两条业务路径**：代理账号使用 `wechat|alipay` 在线自充；平台或超级管理员使用 `offline` 线下代充。
 2. **前端必须使用 `recharge_source` 区分来源**：`platform_offline` 是平台线下代充，`agent_online` 是代理在线自充；不要根据账号名称、备注或审批字段猜测。
 3. **代理不能选择充值店铺**：在线充值的店铺和主钱包由登录上下文确定，请求不得发送 `shop_id`、支付凭证或备注。
-4. **二维码由前端渲染**：后端返回支付渠道原始 `qr_content`，不返回二维码图片。
+4. **二维码由前端渲染**：后端在 `qr_content` 返回支付 HTTPS URL，不返回二维码图片。
 5. **网络重试不能创建新请求 ID**：同一次提交重试复用原 `request_id`；用户主动发起下一笔充值时生成新的 `request_id`。
 6. **支付和钱包到账是两个阶段**：`status=2` 表示第三方已收款、钱包入账处理中；只有 `status=3` 才表示钱包到账完成。
 7. **页面轮询只调用本地状态接口**：前端不得直接调用微信、支付宝查单，也不要反复调用创建接口查询状态。
@@ -20,7 +20,7 @@
 | 能力 | 后端实现 | 前端要做什么 |
 | --- | --- | --- |
 | 可用支付方式 | 根据当前有效支付配置返回真正可用的 `wechat`、`alipay` | 打开充值弹窗时先查询；只展示返回数组中的方式 |
-| 代理在线自充 | 从登录账号取得当前店铺和主钱包，创建充值单、支付单并向第三方预下单 | 只提交金额、支付方式和请求 ID；用 `qr_content` 渲染二维码 |
+| 代理在线自充 | 从登录账号取得当前店铺和主钱包，创建充值单、支付单并按配置生成微信 v3 H5/v2 MWEB 或支付宝 WAP 支付 URL | 只提交金额、支付方式和请求 ID；用 `qr_content` 渲染二维码 |
 | 平台线下代充 | 保留既有目标店铺、凭证和企业微信审批流程 | 平台页面继续提交 `offline` 请求并只读展示审批状态 |
 | 充值来源 | 根据受控创建方式返回稳定来源枚举 | 列表、详情和支付状态统一展示 `recharge_source_name` |
 | 支付确认 | 微信/支付宝回调确认第三方收款事实 | 前端无需调用回调接口 |
@@ -124,7 +124,7 @@ Content-Type: application/json
    "recharge_source": "agent_online",
    "recharge_source_name": "代理在线自充",
    "amount": 10000,
-    "qr_content": "weixin://wxpay/bizpayurl?pr=...",
+    "qr_content": "https://pay.example.com/...",
    "status": 1,
    "status_name": "待支付"
  },
@@ -320,7 +320,7 @@ GET /api/admin/agent-recharges/{id}
 ## 十、联调和验收边界

 - OpenAPI 已包含 `/payment-methods`、在线创建、列表来源筛选、详情来源字段和 `/payment-status`。
- 后端已完成微信 Native、支付宝 PreCreate、支付确认、异步钱包入账和回调丢失恢复的代码装配。
+- 后端已完成微信 v3 H5/v2 MWEB、支付宝 WAP 支付 URL、支付确认、异步钱包入账和回调丢失恢复的代码装配。
 - 当前交付已通过 `go build ./...`、`go vet ./...` 和 OpenSpec 严格校验。
 - 按需求方要求，本次未启动 API/Worker，未连接 PostgreSQL/Redis，未调用真实支付渠道，未发送真实回调，也未运行自动化测试。
 - 前端联调环境需具备完整支付配置；至少确认微信和支付宝创建响应分别返回非空 `qr_content`。
--- a/docs/feature-034-agent-wallet-qr-recharge/功能总结.md
+++ b/docs/feature-034-agent-wallet-qr-recharge/功能总结.md
@@ -4,7 +4,7 @@

 ## 功能范围

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

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

@@ -35,7 +35,7 @@
 }
 ```

-响应包含 `recharge_id`、`payment_no`、`qr_content`、`recharge_source` 和充值状态。前端直接使用 `qr_content` 渲染二维码，不展示或记录支付配置、商户身份和密钥。
+响应包含 `recharge_id`、`payment_no`、`qr_content`、`recharge_source` 和充值状态。`qr_content` 是支付 HTTPS URL，前端直接渲染二维码，不展示或记录支付配置、商户身份和密钥。

 平台线下代充使用 `payment_method=offline`，并按既有契约提交目标 `shop_id`、支付凭证和备注；响应来源为 `platform_offline`。

--- a/docs/feature-034-agent-wallet-qr-recharge/微信扫码支付产品边界核对.md
+++ b/docs/feature-034-agent-wallet-qr-recharge/微信扫码支付产品边界核对.md
@@ -0,0 +1,103 @@
+# 微信扫码支付产品边界核对
+
+## 结论
+
+1. 微信支付产品和接口协议版本是两个不同维度：`JSAPI`、`Native`、`H5` 是支付产品/用户场景；API v2、API v3 是商户后台调用微信支付的协议版本。
+2. 桌面代理后台展示二维码、用户拿手机微信扫码支付，应使用 **Native 支付**。Native 下单返回 `code_url`，前端把它生成二维码。这正是微信官方定义的扫码支付场景。
+3. JSAPI 确实可以正常支付，但它要求支付页面运行在微信内置浏览器中，并取得当前用户 `openid`，然后由页面调用微信支付控件；它不是“PC 页面展示二维码供另一台手机扫码”的产品。
+4. H5 支付用于手机浏览器（非微信客户端内）跳转拉起微信，v2 返回 `mweb_url`，v3 返回 `h5_url`。这两个 URL 在技术上当然都能编码成二维码；但能否支付取决于扫码后打开它的浏览器环境。微信“扫一扫”会在微信内置浏览器打开，而官方 H5 支付明确面向微信客户端外的浏览器，因此不能把这条路径当作可用的微信扫码支付流程；系统相机或其他扫码工具若把链接交给手机外部浏览器，则可能按 H5 流程拉起微信，但仍须满足支付域名、`Referer` 等官方校验。
+5. 微信支付的能力并非天然“只接受 v3”。官方 API v2 的统一下单用 `trade_type=JSAPI/NATIVE/MWEB`，API v3 则分别提供 JSAPI、Native、H5 下单接口；两代协议都覆盖这三类产品。实际能否调用还取决于商户是否开通对应产品、AppID 与商户号绑定等平台条件。
+6. 项目已按最终产品决定支持两种当前配置：`provider_type=wechat` 调用 v3 H5，`provider_type=wechat_v2` 调用 v2 MWEB；两者分别返回 `h5_url`、`mweb_url`，统一映射为 `qr_content`。
+
+## 产品边界
+
+| 产品 | 官方适用场景 | 下单主要返回物 | 客户端完成支付方式 | 是否适合本需求 |
+| --- | --- | --- | --- | --- |
+| JSAPI | 用户已经在微信客户端内打开商户网页 | `prepay_id`；商户再生成前端调起支付所需参数 | 页面调用微信支付控件，且需传用户 `openid` | 否。除非把代理充值页改成微信内页面并增加 OAuth/OpenID 链路 |
+| Native | PC 网站、实体物料等展示二维码，用户使用微信“扫一扫” | `code_url` | 商户把 `code_url` 生成二维码，用户扫码 | **是，和当前需求完全匹配** |
+| H5（v2 名称 MWEB） | 用户在手机系统浏览器等微信客户端外的移动网页发起支付 | `h5_url`（v2 返回字段为 `mweb_url`） | 当前手机浏览器跳转该 URL 拉起微信 | 有条件可用：系统相机/外部扫码工具进入外部浏览器时可能完成；微信“扫一扫”进入微信内置浏览器时不符合官方 H5 场景 |
+
+因此，“JSAPI 能正常支付”和“它适合桌面扫码”并不矛盾：前者描述支付能力，后者描述用户入口。选型依据应是入口场景，而不是某一种产品是否能够完成扣款。
+
+## `mweb_url` / `h5_url` 生成二维码后的准确边界
+
+先区分两件事：前端二维码组件可以渲染任意 URL，这只证明二维码可以被识别；是否能完成支付由微信支付产品规则和扫码后的浏览器环境决定。API v2 的 `mweb_url` 与 API v3 的 `h5_url` 在这一点上没有产品语义差异，都是 H5 支付跳转地址。
+
+| 扫码入口 | 实际打开环境 | 官方产品边界 | 结论 |
+| --- | --- | --- | --- |
+| 微信“扫一扫” | 微信内置浏览器 | 微信官方将 H5 支付定义为在微信客户端外的移动浏览器中调起微信支付 | 二维码能识别、URL 也能打开，但不能据此认定 H5 支付可完成；这不是官方支持的 H5 入口 |
+| 系统相机、系统扫码器或其他把链接交给浏览器的工具 | Safari、Chrome 等微信外部移动浏览器 | 符合 H5 支付的浏览器场景；浏览器跳转 `mweb_url`/`h5_url` 后拉起微信 | 可以作为 H5 跳转方式，但必须满足商户已开通 H5、支付域名配置、请求来源等校验 |
+
+还有一个容易遗漏的限制：官方开发指引要求 H5 调起链路携带符合配置的 `Referer`，微信支付中间页会进行 H5 权限和安全校验。因此，将下单返回的裸 `mweb_url`/`h5_url` 直接编码进二维码，会让最终行为依赖扫码工具如何打开链接、是否保留合法来源；它不像 Native 的 `code_url` 那样是官方专门定义的“生成二维码后由微信扫码”凭据。更稳妥的 H5 二维码做法是二维码指向商户自己的已配置 H5 页面，再由该页面在外部浏览器中跳转微信返回的 H5 地址。
+
+所以用户提出的说法应修正为：**`mweb_url`/`h5_url` 可以由前端渲染成二维码，系统相机扫码后进入外部浏览器时有条件可支付；但微信“扫一扫”打开的是微信内置浏览器，不满足官方 H5 支付场景。若产品要求用户明确使用微信扫一扫，仍应使用 Native `code_url`。**
+
+## API v2 与 API v3
+
+### 官方能力
+
+- API v2 使用统一下单接口，通过 `trade_type` 区分产品：`JSAPI`、`NATIVE`、`MWEB`。对应返回分别围绕 `prepay_id`、`code_url`、`mweb_url`。
+- API v3 将三类下单拆成独立接口：
+  - JSAPI：`POST /v3/pay/transactions/jsapi`，返回 `prepay_id`；
+  - Native：`POST /v3/pay/transactions/native`，返回 `code_url`；
+  - H5：`POST /v3/pay/transactions/h5`，返回 `h5_url`。
+
+所以正确表述是：**v2 和 v3 都可以承载 JSAPI、Native、H5/MWEB；项目是否支持，取决于对应协议分支有没有实现该产品的下单、签名、查单、关单和回调验签。**
+
+### 本项目当前实现
+
+1. `WechatConfig.ProviderType` 明确把 `wechat` 定义为 v3、`wechat_v2` 定义为 v2；同一条配置模型同时有 `wx_api_v3_key`、证书/私钥/序列号和 `wx_api_v2_key` 字段。
+2. 通用加载器按 `provider_type` 选择实现：
+   - `wechat` 构建 PowerWeChat v3 服务；
+   - `wechat_v2` 构建本地 XML+MD5 v2 服务。
+3. v3 服务目前实现 JSAPI 和 H5；仓库曾有/SDK具备 Native 调用能力，但当前代理充值 Adapter 调的是 `CreateH5Order -> TransactionH5`，把返回的 `H5URL` 放入 `QRContent`。
+4. v2 服务保留 JSAPI，并已增加 `trade_type=MWEB` 下单、`mweb_url` 解析和 v2 查单；通用 v2 Adapter 同步开放 H5/MWEB 与查单能力。
+5. `GET /api/admin/agent-recharges/payment-methods` 读取唯一生效配置，再调用 Adapter 的 `Available`：v3 校验 v3 Key、证书和序列号，v2 校验 APIv2Key；两种配置均可返回 `wechat`。
+
+因此测试环境生效配置为 `provider_type=wechat_v2` 且 APIv2Key、商户号、AppID 和回调地址完整时，接口会返回 `wechat`，创建时使用 MWEB。
+
+## “基于当前支付配置”的准确含义
+
+“基于当前支付配置”不等于“看到哪组密钥非空就自动尝试哪套协议”。当前代码的配置解析规则是：
+
+```text
+唯一 is_active=true 的 WechatConfig
+        │
+        ├─ provider_type=wechat    → 选择 v3 实现 → 校验 v3 凭据
+        ├─ provider_type=wechat_v2 → 选择 v2 实现 → 校验 APIv2Key
+        └─ provider_type=fuiou     → 选择富友实现
+```
+
+也就是说，字段值提供凭据，`provider_type` 决定协议和 Adapter。即使同一行同时填了 v2、v3 字段，代码也不会自动降级或跨协议尝试。支付宝字段则是同一配置行中的并存能力，当前可用性判断不通过 `provider_type=alipay` 分流。
+
+## 本项目最终采用方式
+
+用户已确认接受“系统相机或外部扫码工具打开手机外部浏览器”的 H5/MWEB 使用方式，项目据此采用：
+
+1. `provider_type=wechat`：调用 v3 H5 下单和查单，返回 `h5_url`。
+2. `provider_type=wechat_v2`：调用 v2 MWEB 下单和查单，返回 `mweb_url`。
+3. 两个分支继续使用各自协议的回调验签；支付 URL 统一保存并返回为 `qr_content`。
+4. 前端负责渲染二维码，同时明确提示使用系统相机或外部浏览器扫码；本方案不承诺微信“扫一扫”入口。
+
+## 仓库证据
+
+- `internal/model/wechat_config.go`：`wechat`/`wechat_v2` 的协议含义及两套密钥字段。
+- `pkg/payment/loader.go`：按 `provider_type` 构建 v3 或 v2 服务；v2 Adapter 转发 JSAPI、H5/MWEB 与查单。
+- `pkg/wechat/payment_v2.go`：v2 XML+MD5 的 JSAPI、MWEB 下单与查单实现。
+- `pkg/wechat/payment.go`：v3 JSAPI 返回 `prepay_id/pay_config`，H5 返回 `h5_url`。
+- `internal/infrastructure/payment/wechat_web.go`：代理充值按 `provider_type` 调用 v3 H5 或 v2 MWEB，并把支付 URL 写入 `QRContent`。
+- `internal/application/agentrecharge/online_creation.go`：支付方式接口读取 `is_active=true` 配置，并只返回 Adapter 判定可用的方式。
+
+## 微信支付官方来源
+
+- [JSAPI 支付产品/开发指引](https://pay.weixin.qq.com/doc/v3/merchant/4012791856)
+- [JSAPI 下单 API v3](https://pay.weixin.qq.com/doc/v3/merchant/4012791858)
+- [Native 支付产品/开发指引](https://pay.weixin.qq.com/doc/v3/merchant/4012791874)
+- [Native 下单 API v3](https://pay.weixin.qq.com/doc/v3/merchant/4012791875)
+- [H5 支付产品/开发指引](https://pay.weixin.qq.com/doc/v3/merchant/4012791897)
+- [H5 下单 API v3](https://pay.weixin.qq.com/doc/v3/merchant/4012791902)
+- [API v2 统一下单（官方旧版文档）](https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=9_1)
+- [API v2 Native 支付（官方旧版文档）](https://pay.weixin.qq.com/wiki/doc/api/native.php?chapter=6_1)
+- [API v2 H5 支付（官方旧版文档）](https://pay.weixin.qq.com/wiki/doc/api/H5.php?chapter=15_1)
+
+> 核对日期：2026-07-30。上述来源均为微信支付官方域名；旧版 API v2 文档可能由官方站点重定向到新版文档中心，但其统一下单字段和产品语义也可由仓库现有 v2 实现交叉核对。