RuoYi-Vue/docs/virtual-pay-setup.md

# 资源直购虚拟支付上线配置

本项目使用微信小程序虚拟支付的 `short_series_goods`（道具直购）模式，不再提供人民币充值积分功能。

## 1. 执行数据库迁移

首次部署依次执行：

1. `sql/virtual_pay_resource.sql`
2. `sql/virtual_pay_resource_specs.sql`
3. `sql/virtual_pay_order_guard.sql`

第二个脚本把每条资源下载项改造成可单独购买的规格，第三个脚本阻止同一用户对同一规格同时产生多笔待支付或已支付订单。已经执行前两个脚本的环境只需补执行第三个脚本。

脚本会：

- 为资源增加分单位价格 `price_fen`；
- 为每条资源下载项增加规格价格、状态和排序；
- 创建价格档位表 `app_virtual_product`；
- 创建虚拟支付订单表 `app_virtual_order`；
- 创建资源访问权益表 `app_resource_entitlement`；
- 为待支付/已支付订单增加数据库唯一防重键；
- 将已有 `is_ad=3` 资源的 `ad_number`（元）迁移为 `price_fen`（分）。
- 旧订单与权益保留整项解锁能力，新订单按下载项规格解锁。

## 2. 配置虚拟支付环境变量

```text
WX_VIRTUAL_PAY_ENABLED=true
WX_VIRTUAL_PAY_OFFER_ID=微信虚拟支付OfferId
WX_VIRTUAL_PAY_APP_KEY=微信虚拟支付现网AppKey
WX_VIRTUAL_PAY_ENV=0
WX_VIRTUAL_PAY_CALLBACK_TOKEN=CHANGE_ME_TO_A_RANDOM_SECRET
```

AppKey 和小程序 Secret 不应提交到 Git，生产环境应由部署平台注入。
未设置这些环境变量时，虚拟支付默认关闭。

## 3. 配置价格档位道具

在微信公众平台的虚拟支付后台按价格创建并发布道具，例如：

| 价格 | productId 示例 |
| --- | --- |
| 1 元 | `resource_100` |
| 5 元 | `resource_500` |
| 10 元 | `resource_1000` |

然后在若依后台编辑付费资源：

- 获取方式选择“付费”；
- 在“资源规格”中按版本从低到高填写排序，例如源码版 `1`、文档版 `2`、部署版 `3`；
- 高排序版本自动包含所有低排序版本，且版本价格必须随排序递增；
- 为每个版本填写价格，例如 5 元填写 `500`；
- 规格价格必须存在于 `app_virtual_product` 的已启用价格档位中，系统会自动匹配对应的 `productId`。
- 所有可能产生的升级差价也必须配置价格档位。例如版本价格分别为 `9900`、`19900`、`29900` 分，还需配置 `10000`、`20000` 分两个差价档位。

后台会自动维护“价格 -> productId”唯一映射；一个 productId 不能绑定多个价格。

用户升级时，服务端按“目标版本当前价格 - 已拥有最高版本当前价格”计算实付金额。前端展示金额仅供参考，签名和订单金额始终由服务端重新计算。高版本退款后，只撤销该高版本订单对应的权益，用户更早单独购买的低版本权益仍然保留。

## 4. 配置消息推送

在小程序后台配置：

```text
URL: https://你的域名/prod-api/app/virtual-pay/callback
Token: 与 WX_VIRTUAL_PAY_CALLBACK_TOKEN 相同
数据格式: JSON
消息加密方式: 明文模式
```

支付发货通知由服务端验签、校验 OpenID/订单/productId/价格后幂等发放资源权益。退款成功通知会撤销对应权益。
回调成功时接口返回 `{"ErrCode":0,"ErrMsg":"success"}`；业务校验或处理失败时返回非零错误码，微信会自动重试。

## 5. 上线检查

1. 后端启动时确认 `WX_VIRTUAL_PAY_ENABLED=true`。
2. 确认道具已审核发布并等待配置生效。
3. 用一条最低价格资源完成真机支付。
4. 检查 `app_virtual_order.status=1` 和 `app_resource_entitlement.status=1`。
5. 重新进入资源详情，确认下载链接只对购买用户返回。

## 6. 启用后台订单管理

执行 `sql/virtual_pay_order_menu.sql`，然后重新登录若依后台。在原“支付订单”菜单的同级位置会出现“虚拟支付订单”，支持按订单号、微信交易号、用户、资源、状态和创建时间查询，并可查看详情或导出 Excel。

虚拟支付订单由微信回调和主动查单流程维护，后台页面只提供查询与导出，不允许人工修改或删除订单。