专属优惠与线下充值功能说明.md 7.3 KB
专属优惠充值 + 线下充值 功能说明
版本: v7
日期: 2026-06-03
作者: skyline
一、专属充值优惠活动
1.1 功能概述
运营后台创建专属充值配置（如充值 100 元送 20 元），生成小程序二维码。用户扫码进入小程序，在有效期内以专属优惠完成充值。二维码支持多人使用，可限定目标用户范围。
1.2 业务流程
运营后台 微信小程序 后端
| | |
|-- 创建优惠活动 --------->| |
| | |
|-- 生成小程序二维码 ----->| |
| (wxacode.getUnlimited)| |
| | |
| |-- 用户扫码 --> 小程序启动 --|
| | App.vue 检测 scene |
| | 跳转优惠充值页 |
| | |
| |-- GET /common/promotionInfo ->
| | (查询活动详情) |
| | |
| |-- GET /payment/promotionPay ->
| | (发起微信支付) |
| | |
| |-- 微信支付成功回调 --------->|
| | wxNotify 检测 promotionId |
| | 使用活动赠费更新余额 |
1.3 数据库
新表: t_recharge_promotion
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键 |
| title | VARCHAR(128) | 活动标题 |
| recharge_amount | INT | 充值金额（分） |
| grants_amount | INT | 赠送金额（分） |
| target_mode | TINYINT | 1=所有人, 2=指定用户 |
| target_user_ids | TEXT | 目标用户ID列表（JSON数组），null=不限制 |
| start_time | DATETIME | 活动开始时间 |
| end_time | DATETIME | 活动结束时间 |
| status | TINYINT | 0=禁用, 1=启用 |
| token | VARCHAR(32) | 二维码场景值（唯一标识） |
| qr_code_url | VARCHAR(512) | 二维码图片URL |
t_wallet_detail 新增字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| source | VARCHAR(16) | WX_PAY / MANUAL |
| promotion_id | BIGINT | 关联优惠活动ID，null=非活动充值 |
1.4 API 接口
管理后台
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | /rechargePromotion/list |
promotion.list | 分页查询活动列表 |
| GET | /rechargePromotion/detail/{id} |
— | 查询活动详情 |
| POST | /rechargePromotion/add |
promotion.add | 新增活动（自动生成token） |
| POST | /rechargePromotion/modify |
promotion.modify | 修改活动 |
| GET | /rechargePromotion/remove/{id} |
promotion.remove | 删除活动 |
| GET | /rechargePromotion/generateQR/{id} |
promotion.list | 生成小程序二维码（上传OSS） |
小程序端
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /common/promotionInfo?token=xxx |
查询优惠活动详情（含有效期校验） |
| GET | /payment/promotionPay?promotionToken=xxx&stationId=xxx |
发起优惠活动充值支付，返回JSAPI参数 |
1.5 关键逻辑
支付回调区分优惠活动与普通充值：
WxPayServiceImpl.wxNotify() 中先检查 walletDetail.promotionId：
- 不为 null → 用优惠活动的
grantsAmount - 为 null → 走原有站点充值配置逻辑
用户资格校验：
RechargePromotionServiceImpl.checkUserEligible()：
targetMode=1（所有人）→ 直接通过targetMode=2（指定用户）→ 从targetUserIdsJSON 数组解析，检查当前用户ID是否在列表中
二、线下充值
2.1 功能概述
用户通过微信转账给运营人员，运营人员在管理后台代为充值，直接更新用户钱包余额。钱不经过微信商户，无微信交易记录。
2.2 业务流程
用户 --(微信转账)--> 运营人员
|
|-- 登录管理后台 → 线下充值页面
|-- 输入用户手机号 → 查询用户
|-- 输入充值金额 + 赠送金额 + 备注
|-- 确认提交
|
后端: 创建 WalletDetail (source=MANUAL, status=已确认)
更新 Account 余额
创建 SplitRecord (走V2结算)
不创建 PayLog (无微信交易)
2.3 API 接口
管理后台
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| POST | /finance/offlineRecharge |
offlineRecharge | 线下充值 |
请求参数 (JSON Body):
{
"userId": 10001,
"amount": 5000,
"grantsAmount": 500,
"remark": "微信转账充值，流水号: xxx"
}
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 是 | 用户ID |
| amount | Integer | 是 | 充值金额（分） |
| grantsAmount | Integer | 否 | 赠送金额（分），默认0 |
| remark | String | 否 | 备注信息 |
2.4 与线上充值的区别
| 线上充值（微信支付） | 线下充值（人工） | |
|---|---|---|
| WalletDetail.source | WX_PAY | MANUAL |
| WalletDetail.status | 先创建待确认→回调后确认 | 直接已确认 |
| PayLog | 创建 | 不创建 |
| SplitRecord | 创建 | 创建 |
| 退款 | 走微信退款流程 | 暂不支持系统退款（需人工处理） |
| 操作日志 | 微信回调日志 | @SysLog "线下充值" |
三、部署清单
3.1 数据库迁移
执行 SQL: car-wash-entity/src/main/resources/sql/v7_recharge_promotion.sql
3.2 权限分配
在角色管理中为运营人员分配以下权限：
| 权限标识 | 名称 | 菜单 |
|---|---|---|
| promotion.list | 优惠活动管理 | 平台配置 → 专属优惠活动 |
| promotion.add | 优惠活动新增 | 新增按钮 |
| promotion.modify | 优惠活动修改 | 编辑按钮 |
| promotion.remove | 优惠活动删除 | 删除按钮 |
| offlineRecharge | 线下充值 | 财务管理 → 线下充值 |
3.3 小程序发布
- 确保
pages-user/wallet/promotion页面已注册到pages.json - 重新发布小程序（新增页面需审核）
- 确保
wechat.miniapp.appid和wechat.miniapp.secret配置正确（用于生成小程序码）
四、注意事项
- 二维码有效期：微信小程序码本身无过期时间，有效期由活动的
start_time/end_time控制，扫码时后端校验 - 线下充值不可退款：线下充值的资金未经过微信商户，系统无法通过微信退款接口原路退回。如需退线下充值款项，需人工线下处理
- 线下充值的安全性：依赖
offlineRecharge权限控制，所有操作通过@SysLog记录审计日志，WalletDetail.remark 字段记录操作备注 - 活动 token 唯一性：创建活动时自动生成 16 位随机字符串作为 token，数据库有唯一索引防止冲突，失败时自动重试最多 5 次
- 小程序码图片存储：二维码图片上传到阿里云 OSS，URL 存入
qr_code_url字段，重复请求直接返回已有 URL