补齐微信虚拟支付查单与补偿
接入微信官方虚拟支付查单并缓存稳定接口令牌 让用户确认与订单过期补偿统一核对支付类型、状态、金额和单号 增加单笔历史订单的 dry-run 与确认指纹补单工具 隔离运行时身份与敏感 openid 文件并补充配置契约和回归测试
This commit is contained in:
@@ -4005,3 +4005,11 @@
|
||||
- 验真与清理边界：Complete 后必须发送签名 HEAD，并严格核对 OSS `Content-Length` 与本地归档大小；Complete 响应不确定时也先用 HEAD 判定对象是否已经完整落盘。只有验真成功后才能把 manifest 标记为 `uploaded`，并按 `keepLocal` 决定是否删除本地归档；失败时 best-effort AbortMultipartUpload，不得提前更新 manifest 或清理本地文件。
|
||||
- 影响范围：数据库备份 OSS 上传实现、备份回归门禁、release 本地归档保留与 timer 恢复流程。
|
||||
- 验证方式：`npm run check:database-backup`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`；线上先对既有归档使用 `--upload-archive ... --keep-local`，确认 OSS 对象长度和可恢复性后再清理积压并恢复 timer。
|
||||
|
||||
## 2026-07-13 微信虚拟支付使用官方查单补偿
|
||||
|
||||
- 背景：`wechat_mp_virtual` 原先被误认为没有服务端查单能力，导致消息推送遗漏后订单只能停在 pending / expired，历史订单也无法按微信真实状态核对。
|
||||
- 决策：`platform-wechat` 按官方协议调用 `POST /xpay/query_order`，使用小程序 `access_token` 与 `HMAC-SHA256(appKey, "/xpay/query_order&" + 实际 JSON body)` 支付签名。用户确认和订单到期补偿都可查虚拟支付订单，但只在单号、支付类型 `order_type=0/7`、金额一致且微信状态为 `2/3/4` 时补入账；退款类型 `1/8` 不发放权益。
|
||||
- 边界：查单使用订单所属用户的小程序 `openid`，不把 AppKey、AppSecret、access token 或 `openid` 下发前端；虚拟支付不得误用微信支付 V3 查单。
|
||||
- 历史单：升级前遗留的 pending 订单不会被 expiration catch-up 覆盖，使用 `spacetime:wechat-virtual-payment:reconcile` 逐单 dry-run，再使用当次 `applyFingerprint` 明确 `--apply`。脚本每次重读本地订单与微信查单结果，指纹漂移、非 `2/3/4`、单号/金额/支付类型 `order_type=0/7` 不一致或非官方 endpoint 时默认拒绝入账。
|
||||
- 验证方式：`cargo test -p platform-wechat --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml virtual_payment_query`、`npm run check:wechat-virtual-payment-reconcile`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
@@ -202,7 +202,7 @@ npm run check:server-rs-ddd
|
||||
12. access JWT 只携带最小设备快照 `device.client_type`、`device.client_runtime`、`device.client_platform`。充值下单按该快照拦截小程序渠道：小程序只允许 `wechat_mp` / `wechat_mp_virtual`；移动网页和微信内 H5 走 `wechat_h5`；桌面网页和桌面微信走 `wechat_native`；`wechat_jsapi` 仅保留后端能力，未接微信开放平台前不由前端自动选择。历史普通 Web 登录态若缺少设备快照也允许继续进入 JSAPI / H5 / Native 渠道的后续支付配置校验，但不放宽小程序虚拟支付。
|
||||
13. 所有微信真实渠道都以微信支付通知或服务端查单确认 `SUCCESS` 为到账事实；小程序、H5 跳转和 Native 二维码返回都不能直接发放泥点或会员。
|
||||
14. 微信 JSAPI / H5 / 小程序 / Native 下单统一显式传 5 分钟 `time_expire`，格式为 RFC3339 秒级时间；Native 额外通过 `wechatNativePayment.expiresAt` 下发给前端二维码弹窗展示。
|
||||
15. 真实微信渠道的新建 pending 充值订单会写入 SpacetimeDB 原生 scheduled 表 `profile_recharge_order_expiration_timer`。到期 reducer 只做数据库内状态转换：订单仍为 `pending` 时更新为 `expired` 并写 `expired_at`，同时删除 timer。HTTP `api-server` 只订阅这张活跃 timer 表的删除事件，收到 `order_id` 后通过 procedure 重新读取订单，只有状态确认为 `expired` 才执行微信查单补偿；支付或主动关闭同样会删除 timer，但会被状态判断忽略。监听断线期间遗漏的删除事件由未检查过期订单 catch-up 补齐，不订阅完整 `profile_recharge_order` 历史表。`SUCCESS` 可把 `expired` 补确认成 `paid` 入账；`NOTPAY` 会调用微信关单并把本地订单保持为 `expired`；`CLOSED` / `REVOKED` / `PAYERROR` / `ORDER_NOT_EXIST` 只记录检查结果。`external-generation-worker` / controller 不处理充值过期；`wechat_mp_virtual` 到期只记录虚拟渠道不可查，后续真实支付通知仍允许 `Expired -> Paid`。
|
||||
15. 真实微信渠道的新建 pending 充值订单会写入 SpacetimeDB 原生 scheduled 表 `profile_recharge_order_expiration_timer`。到期 reducer 只做数据库内状态转换：订单仍为 `pending` 时更新为 `expired` 并写 `expired_at`，同时删除 timer。HTTP `api-server` 只订阅这张活跃 timer 表的删除事件，收到 `order_id` 后通过 procedure 重新读取订单，只有状态确认为 `expired` 才执行微信查单补偿；支付或主动关闭同样会删除 timer，但会被状态判断忽略。监听断线期间遗漏的删除事件由未检查过期订单 catch-up 补齐，不订阅完整 `profile_recharge_order` 历史表。普通微信支付查单中 `SUCCESS` 可把 `expired` 补确认成 `paid` 入账；`NOTPAY` 会调用微信关单并把本地订单保持为 `expired`；`CLOSED` / `REVOKED` / `PAYERROR` / `ORDER_NOT_EXIST` 只记录检查结果。`wechat_mp_virtual` 使用小程序 `access_token` 和虚拟支付 AppKey 调用官方 `/xpay/query_order`，只在返回单号、支付类型 `order_type=0/7`、金额与本地契约一致且状态为 `2/3/4` 时补入账；退款类型 `1/8` 不得触发充值，其余已知状态只记录检查结果。`external-generation-worker` / controller 不处理充值过期。
|
||||
|
||||
## 创作入口泥点扣费契约
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
- 会员商品在微信小程序 WebView 内同样走 `wechat_mp_virtual`，由小程序页调用 `wx.requestVirtualPayment` 的 `short_series_goods` 模式，并在 `signData` 内带 `productId` 与 `goodsPrice`。
|
||||
- 微信内浏览器走 `wechat_jsapi`，复用微信支付 V3 JSAPI 下单返回的预支付参数并通过 `WeixinJSBridge.invoke('getBrandWCPayRequest')` 调起支付；普通 Web 统一走 `wechat_native` 二维码支付，不进入虚拟支付链路，也不依赖 H5 产品权限。`wechat_h5` 仅作为未来 H5 产品权限明确开通后的保留渠道。
|
||||
- `session_key` 只保存在后端认证仓储内，用于计算虚拟支付用户态签名，不下发给前端。
|
||||
- 客户端支付成功回调只代表已拉起支付并返回成功；最终到账仍以后端虚拟支付消息推送写入订单为准，普通微信支付订单则继续走微信支付 V3 notify / query。虚拟支付订单的确认接口只读取本地订单真相，不再用普通微信支付 V3 查单。
|
||||
- 客户端支付成功回调只代表已拉起支付并返回成功；最终到账以后端虚拟支付消息推送或官方 `/xpay/query_order` 查单结果为准，普通微信支付订单则继续走微信支付 V3 notify / query。虚拟支付不得误用普通微信支付 V3 查单。
|
||||
- 小程序 WebView 普通进入不预登录；H5 触发受保护入口或支付前必须保留 `clientRuntime=wechat_mini_program` 等宿主上下文，并用 `MicroMessenger + miniProgram` User-Agent 兜底识别首点 bridge 未就绪场景，再跳转小程序原生授权态，确保后端拿到带 `session_key` 的微信登录态。
|
||||
|
||||
## 关键文件
|
||||
@@ -34,6 +34,7 @@ WECHAT_PAY_PROVIDER=real
|
||||
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_OFFER_ID=<微信虚拟支付 offerId>
|
||||
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_APP_KEY=<现网 AppKey>
|
||||
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_SANDBOX_APP_KEY=<沙箱 AppKey，可选>
|
||||
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_QUERY_ORDER_ENDPOINT=https://api.weixin.qq.com/xpay/query_order
|
||||
WECHAT_MINIPROGRAM_MESSAGE_TOKEN=<微信消息推送 Token>
|
||||
WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=<微信消息推送 EncodingAESKey>
|
||||
WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED=true
|
||||
@@ -47,6 +48,10 @@ WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV=0
|
||||
- `signData`：传给 `wx.requestVirtualPayment` 的订单数据。
|
||||
- `paySig`：`HMAC-SHA256(appKey, "requestVirtualPayment&" + signData)` 的小写 hex。
|
||||
- `signature`：`HMAC-SHA256(session_key, signData)` 的小写 hex。
|
||||
- 服务端虚拟支付查单使用 `POST https://api.weixin.qq.com/xpay/query_order`：请求体固定携带 `openid`、`env` 和 `order_id`，查询参数携带小程序 `access_token` 与 `pay_sig`。`pay_sig` 按官方算法计算为 `HMAC-SHA256(appKey, "/xpay/query_order&" + 实际发送的 JSON body)` 的小写 hex；参与签名的 body 必须与 HTTP 实际发送字节一致。
|
||||
- 查单返回 `status=2/3/4` 分别表示“已支付待发货 / 发货中 / 已发货”，只有这三种状态可以补确认本地订单入账。入账前必须同时校验 `order_id`、支付类型 `order_type=0/7` 和 `order_fee`；`status=0/1/5..10` 只记录供应方状态，不直接发放泥点或会员权益。
|
||||
- `order_type` 的官方枚举是 `0=普通虚拟支付`、`1=普通退款`、`7=iOS 支付`、`8=iOS 退款`，不区分 `short_series_coin` 与 `short_series_goods`。普通和 iOS 的支付单分别使用 `0` 和 `7`；退款类型 `1/8` 绝不可触发充值入账。官方查单响应本身不提供可反查 coin / goods 的字段，不得自行发明数值映射；商品契约继续以本地订单快照和 `order_fee` 一致性作防线。
|
||||
- `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_QUERY_ORDER_ENDPOINT` 默认是微信官方地址，仅用于测试注入 mock endpoint；生产不应覆盖。`WechatConfig` 同时支持注入 stable token 和 query order 两个 endpoint，平台层集成测试必须校验真实发起请求的 mock 路径。
|
||||
- 泥点属于微信虚拟支付代币（coin），`short_series_coin` 的 `buyQuantity` 必须使用当前泥点商品的 `points_amount`；例如 60 泥点商品应传 `buyQuantity: 60`。
|
||||
- 会员直购 `signData` 额外包含 `productId` 和 `goodsPrice`；`goodsPrice` 使用后端商品配置价，和微信后台道具价格校验保持一致。
|
||||
- 微信小程序“开发者服务器接收消息推送”必须配置为安全模式，数据格式选 JSON，URL 统一指向 `/api/profile/recharge/wechat/virtual-notify`。
|
||||
@@ -63,6 +68,35 @@ npm run typecheck
|
||||
npm run check:encoding
|
||||
```
|
||||
|
||||
## 历史订单逐单核对
|
||||
|
||||
升级前已存在的 `wechat_mp_virtual` pending 订单没有 expiration timer，不会被到期 catch-up 自动遍历。这类订单使用受控脚本逐单处理，不得批量改状态：
|
||||
|
||||
```bash
|
||||
# openid 只放入当次临时文件，不作为 CLI 参数或仓库文件。
|
||||
install -m 0600 /dev/null /run/genarrative-virtual-payment-openid
|
||||
|
||||
# 第一次固定 dry-run；人工核对订单、金额、微信状态和 applyFingerprint。
|
||||
npm run spacetime:wechat-virtual-payment:reconcile -- \
|
||||
--database genarrative-prod \
|
||||
--server-url http://127.0.0.1:3101 \
|
||||
--order-id <orderId> \
|
||||
--openid-file /run/genarrative-virtual-payment-openid \
|
||||
--env-file /etc/genarrative/api-server.env
|
||||
|
||||
# 只有 dry-run 显示 eligibleForCredit=true 时，使用同一订单追加 --apply 和当次指纹。
|
||||
npm run spacetime:wechat-virtual-payment:reconcile -- \
|
||||
--database genarrative-prod \
|
||||
--server-url http://127.0.0.1:3101 \
|
||||
--order-id <orderId> \
|
||||
--openid-file /run/genarrative-virtual-payment-openid \
|
||||
--env-file /etc/genarrative/api-server.env \
|
||||
--apply \
|
||||
--confirm <applyFingerprint>
|
||||
```
|
||||
|
||||
脚本每次重新读取本地订单并重新向微信查单；`--apply` 要求事实指纹与前一次 dry-run 完全一致，只对 `status=2/3/4` 且单号、金额、支付类型 `order_type=0/7` 一致的订单调用既有 `mark_profile_recharge_order_paid_and_return`。它使用 `/etc/genarrative/api-server.env` 内的 `GENARRATIVE_SPACETIME_TOKEN` 通过显式 `--server-url` 调用 procedure，不复用 migration operator 身份；不输出 openid、AppSecret、AppKey、access token 或 SpacetimeDB token，且 apply 默认拒绝非微信官方 endpoint。每单完成后立即删除临时 openid 文件。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 旧微信登录快照可能没有 `session_key`；普通进入小程序 WebView 仍允许匿名打开，虚拟支付会由后端拦截并提示用户在小程序内重新登录。H5 内部导航不得清理 `clientType`、`clientRuntime`、`miniProgramEnv`，且首点登录要用小程序 User-Agent 兜底识别，否则登录和支付会误判为普通网页环境。
|
||||
@@ -74,6 +108,6 @@ npm run check:encoding
|
||||
- 微信虚拟支付消息推送使用独立后端入口 `/api/profile/recharge/wechat/virtual-notify`，按 `xpay_goods_deliver_notify` 和 `xpay_coin_pay_notify` 推进充值订单入账；回包需按入站格式返回 `ErrCode=0` / `ErrMsg=success`（JSON 入站回 JSON，XML 入站回 XML），错误时带具体 `ErrMsg` 便于微信侧重试与排障。
|
||||
- 沙箱或基础库失败会把微信返回的 `errCode` / `errMsg` 透传到前端失败弹窗，便于区分微信后台道具、沙箱 AppKey、签名和基础库能力问题。
|
||||
- Web 侧在拉起虚拟支付后会短时轮询 `wx_pay_result`，即使小程序 `web-view` 回写 hash 没触发浏览器 `hashchange`，也必须展示回写的微信错误内容。
|
||||
- WebView 返回但没有拿到 `wx_pay_result` 时，前端必须主动调用订单确认接口，并接入 `/api/profile/recharge/orders/{orderId}/wechat/events` 的 SSE 事件流作为服务端推送兜底；后端收到虚拟支付消息推送并入账后会发布订单更新，SSE 先推当前订单快照，再在订单结束时推 `done`。
|
||||
- WebView 返回但没有拿到 `wx_pay_result` 时，前端必须主动调用订单确认接口，并接入 `/api/profile/recharge/orders/{orderId}/wechat/events` 的 SSE 事件流作为服务端推送兜底；虚拟支付确认接口会使用当前用户后端保存的小程序 `openid` 调用官方 `/xpay/query_order`，查到已支付且契约校验通过后写入订单。后端通过消息推送或查单入账后都会发布订单更新，SSE 先推当前订单快照，再在订单结束时推 `done`。
|
||||
- 小程序订阅消息用于 AI 创作生成结果通知：H5 在生成动作发起前先把页面切到生成进度态并立即调用生成 action，同时非阻塞跳转到小程序原生订阅授权页尝试请求授权；授权接受、拒绝或页面返回都不得阻塞或取消生成。原生页不得改写上一页 `webViewUrl`，避免返回后丢失 H5 当前进度页状态。通知发送只允许发生在玩法草稿生成成功或失败终态之后，api-server 使用当前用户微信登录保存的 openid 调用微信 `subscribeMessage.send`。发送失败只记录 warning，不阻断作品生成。模板 `thing1` 发送玩法模板名，`number6` 发送本次生成结算后的实际泥点扣除，失败退款后固定为 `0`；模板 `time4` 字段必须是北京时间 `YYYY-MM-DD HH:mm`。`WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE` 支持 `formal` / `trial` / `developer`，应与当前发布环境一致。
|
||||
- WebView 返回后，在订单状态拉取或 SSE 等待期间展示不可关闭遮罩“正在确认支付”，阻止用户离开或继续操作；只有确认到最终订单状态后才展示一次最终结果弹窗，不能先弹“正在支付/支付已提交”再二次弹成功。
|
||||
|
||||
Reference in New Issue
Block a user