feat: 接入微信H5与Native充值支付
This commit is contained in:
@@ -9,7 +9,7 @@
|
||||
1. `泥点充值`
|
||||
2. `会员卡充值`
|
||||
|
||||
前端只负责展示与发起购买，套餐、价格、赠送规则、会员权益、生效时间、钱包余额与交易流水统一由 `server-rs` 后端返回。普通 H5 / 本地联调继续使用 `mock` 渠道：创建订单后立即写入余额或会员状态，并返回最新账户中心快照。微信小程序 web-view 使用 `wechat_mp` 渠道：创建订单时只写入 `pending` 订单并返回小程序 `wx.requestPayment` 参数，真实到账以后端微信支付通知为准。
|
||||
前端只负责展示与发起购买，套餐、价格、赠送规则、会员权益、生效时间、钱包余额与交易流水统一由 `server-rs` 后端返回。支付接入固定为普通商户直连模式：小程序 web-view 使用 `wechat_mp`，移动网页使用 `wechat_h5`，桌面网页使用 `wechat_native` 二维码。生产默认永远不走 `mock`；只有自动测试或显式测试配置手动传 `paymentChannel = "mock"` 时才允许 mock 即时入账。所有真实微信渠道的到账事实以后端微信支付通知和服务端查单为准。
|
||||
|
||||
## 2. 产品规则
|
||||
|
||||
@@ -56,22 +56,25 @@
|
||||
```json
|
||||
{
|
||||
"productId": "points_300",
|
||||
"paymentChannel": "mock"
|
||||
"paymentChannel": "wechat_h5"
|
||||
}
|
||||
```
|
||||
|
||||
行为：
|
||||
|
||||
1. 校验 `productId`
|
||||
2. `paymentChannel = "mock"` 时后端创建已支付订单
|
||||
3. `paymentChannel = "wechat_mp"` 时后端创建待支付订单，并调用微信支付 JSAPI 下单生成小程序支付参数；本地 `orderId` 会作为微信 `out_trade_no` 传递，格式固定为 `rcg` 前缀 + 小写字母数字，长度在 6-32 字符内，满足微信支付 JSAPI 下单文档对商户订单号的限制。商品描述限制为 127 字符内，回调地址限制为 HTTPS、255 字符内且不携带 query/fragment。
|
||||
2. 缺少 `paymentChannel` 或传入未知渠道时直接返回 `400`，不得再默认解释为 `mock`
|
||||
3. 生产/真实支付配置拒绝 `paymentChannel = "mock"`；mock 只服务自动测试或显式 mock 测试配置
|
||||
- `wechat_mp` / `wechat_h5` / `wechat_native` 必须在 `WECHAT_PAY_ENABLED=true` 且 `WECHAT_PAY_PROVIDER=real` 时才允许下单；`WECHAT_PAY_PROVIDER=mock` 不能为真实微信渠道返回 mock 支付载荷。
|
||||
4. `paymentChannel = "wechat_mp"` 时后端创建待支付订单，并调用微信支付 JSAPI 下单生成小程序支付参数；本地 `orderId` 会作为微信 `out_trade_no` 传递，格式固定为 `rcg` 前缀 + 小写字母数字，长度在 6-32 字符内，满足微信支付 JSAPI 下单文档对商户订单号的限制。商品描述限制为 127 字符内，回调地址限制为 HTTPS、255 字符内且不携带 query/fragment。
|
||||
- JSAPI 下单请求必须显式携带 `Accept: application/json`、`Content-Type: application/json` 和 `User-Agent: Genarrative-WechatPay/1.0`；微信侧会把缺少 `User-Agent` 的请求返回为“Http头缺少Accept或User-Agent”。
|
||||
4. mock 泥点套餐立即写入钱包余额与流水，mock 会员套餐立即写入会员状态
|
||||
5. wechat_mp 订单不提前发泥点或会员，只返回待支付订单、账户中心快照与 `wechatMiniProgramPayParams`
|
||||
5. `paymentChannel = "wechat_h5"` 时调用微信支付 H5 下单，返回 `wechatH5Payment.h5Url`，前端跳转到该地址
|
||||
6. `paymentChannel = "wechat_native"` 时调用微信支付 Native 下单，返回 `wechatNativePayment.codeUrl`，前端在充值弹窗内把 `codeUrl` 渲染成二维码
|
||||
7. 所有微信真实渠道订单不提前发泥点或会员，只返回待支付订单、账户中心快照与对应支付载荷
|
||||
|
||||
兼容路径：`POST /api/runtime/profile/recharge/orders`
|
||||
|
||||
响应里的 `wechatMiniProgramPayParams` 只在微信小程序支付渠道返回，字段直接对应 `wx.requestPayment`：
|
||||
响应里的支付字段只在对应微信支付渠道返回。`wechatMiniProgramPayParams` 字段直接对应 `wx.requestPayment`：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -85,11 +88,24 @@
|
||||
}
|
||||
```
|
||||
|
||||
H5 与 Native 响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"wechatH5Payment": {
|
||||
"h5Url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=..."
|
||||
},
|
||||
"wechatNativePayment": {
|
||||
"codeUrl": "weixin://pay.weixin.qq.com/bizpayurl/up?pr=..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 `POST /api/profile/recharge/orders/{order_id}/wechat/confirm`
|
||||
|
||||
需要 Bearer JWT。该接口用于小程序支付页返回 web-view 后的主动查单确认，不替代微信支付通知：
|
||||
需要 Bearer JWT。该接口用于微信支付返回页面或 Native 扫码后的主动查单确认，不替代微信支付通知：
|
||||
|
||||
1. 后端读取本地 `profile_recharge_order` 并校验订单归属、支付渠道和当前状态。
|
||||
1. 后端读取本地 `profile_recharge_order` 并校验订单归属、支付渠道和当前状态；`wechat_mp` / `wechat_h5` / `wechat_native` 都可确认，`mock` 不能走该接口。
|
||||
2. 若订单已是 `paid`，直接返回订单与账户中心快照。
|
||||
3. 若订单仍是 `pending`，后端调用微信支付按商户订单号查单接口。
|
||||
4. 只有微信查单返回 `trade_state = "SUCCESS"` 时，才调用统一入账 procedure 把订单改为 `paid` 并写入钱包流水或会员状态。
|
||||
@@ -127,7 +143,7 @@
|
||||
| 变量 | 说明 |
|
||||
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `WECHAT_PAY_ENABLED` | 是否启用微信支付客户端 |
|
||||
| `WECHAT_PAY_PROVIDER` | `mock` 或 `real` |
|
||||
| `WECHAT_PAY_PROVIDER` | `mock` 或 `real`；真实微信渠道只能使用 `real`，`mock` 只允许显式测试渠道 |
|
||||
| `WECHAT_PAY_MCH_ID` | 微信支付商户号 |
|
||||
| `WECHAT_PAY_MERCHANT_SERIAL_NO` | 商户 API 证书序列号，用于请求微信支付签名头 |
|
||||
| `WECHAT_PAY_PRIVATE_KEY_PEM` / `WECHAT_PAY_PRIVATE_KEY_PATH` | 商户 API 私钥 |
|
||||
@@ -142,19 +158,23 @@
|
||||
2. 弹窗顶部标题为 `账户充值`，右上角关闭。
|
||||
3. 默认打开 `泥点充值`，可切换到 `会员卡充值`。
|
||||
4. 点击套餐后调用下单接口，按钮进入处理中状态；小程序环境走 native 支付页拉起 `wx.requestPayment`，支付页返回后刷新 `profileDashboard`。
|
||||
- 支付渠道由 `src/services/payment/paymentPlatform.ts` 统一判断，业务 UI 不内联区分小程序、手机网页和桌面网页。
|
||||
- 小程序 web-view 内的 H5 只负责加载微信 JS-SDK 并通过 `wx.miniProgram.navigateTo` 跳转到 `/pages/wechat-pay/index`；实际支付必须在小程序 native 页调用 `wx.requestPayment`，不要切换为 H5 支付产品。
|
||||
- native 支付页通过 `wx_pay_result=<requestId>:success|cancel|fail` 回填 web-view；H5 在 `hashchange`、`focus`、`pageshow` 和 `visibilitychange` 中都会尝试消费该结果，避免小程序返回 web-view 时没有触发单一事件导致状态不刷新。
|
||||
- `success` 只表示微信客户端支付流程返回成功，前端随后调用 `POST /api/profile/recharge/orders/{order_id}/wechat/confirm` 由服务端查单确认；只有通知或服务端查单确认为 `SUCCESS` 才入账。
|
||||
- 小程序返回后，前端会对确认接口做短轮询，覆盖微信通知/查单结果与 web-view 恢复之间的秒级时间差；只有确认响应里的订单状态变成 `paid` 后，才触发父级 `profileDashboard` 刷新，确保“我的”页泥点卡片读取到最新余额。
|
||||
- `cancel` 和 `fail` 只复位按钮、刷新账户中心并通过全局支付结果模态展示，不调用入账逻辑。
|
||||
5. 支付结果使用页面级全局模态展示，不写回商品卡片或账户充值弹窗内部；充值弹窗只负责套餐选择、加载失败和下单失败。
|
||||
6. 弹窗内不写大段说明文案，只保留必要金额、泥点、会员权益和操作状态。
|
||||
7. 会员卡充值区以套餐卡片优先展示周期、价格和处理状态；移动端单列，桌面端三列，权益表允许横向滚动，避免小屏挤压。
|
||||
5. 移动网页含微信内 H5 首版统一走 `wechat_h5`：拿到 `h5Url` 后跳转；若微信内 H5 调起失败，失败态提示用户改用系统浏览器或小程序。
|
||||
6. 桌面网页走 `wechat_native`：充值弹窗展示二维码，用户扫码后点击“我已支付”，前端调用 confirm 接口短轮询确认；确认前不刷新父级余额。
|
||||
7. 支付结果使用页面级全局模态展示，不写回商品卡片或账户充值弹窗内部；充值弹窗只负责套餐选择、加载失败和下单失败。
|
||||
8. 弹窗内不写大段说明文案，只保留必要金额、泥点、会员权益和操作状态。
|
||||
9. 会员卡充值区以套餐卡片优先展示周期、价格和处理状态；移动端单列，桌面端三列，权益表允许横向滚动，避免小屏挤压。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. 普通用户打开弹窗能看到泥点与会员套餐。
|
||||
2. 泥点购买后余额增加，流水来源为 `points_recharge`。
|
||||
3. 首充赠送只在首次泥点充值时生效。
|
||||
4. 会员购买后会员状态与到期时间立即更新。
|
||||
5. 移动端弹窗单列可滚动，桌面端接近参考图卡片网格。
|
||||
2. 默认平台通道只会解析到 `wechat_mp` / `wechat_h5` / `wechat_native`，不会解析到 `mock`。
|
||||
3. 泥点购买后余额增加，流水来源为 `points_recharge`。
|
||||
4. 首充赠送只在首次泥点充值时生效。
|
||||
5. 会员购买后会员状态与到期时间立即更新。
|
||||
6. 移动端弹窗单列可滚动，桌面端接近参考图卡片网格。
|
||||
|
||||
Reference in New Issue
Block a user