scaffold-wechat 微信模块

模块概述

scaffold-wechat 是 Scaffold v2 的微信集成模块，基于 WxJava SDK 提供微信公众号、小程序、支付、现金红包、商家转账的完整功能。采用数据库动态配置 + YAML 静态配置双模式，支持多公众号/多小程序并行运行。配置管理器（WechatConfigManager）在启动时从数据库加载配置，自动构建 WxMpService / WxMaService / WxPayService 实例并缓存。

功能列表

微信配置管理：多公众号/小程序配置 CRUD、测试连接、设为默认
公众号管理：粉丝同步/查询、自定义菜单管理、模板消息发送、公众号统计
公众号 Portal：消息/事件回调入口（GET 签名验证 + POST 消息接收）
微信认证：小程序登录（wx.login code 换取身份）、手机号绑定、公众号 OAuth2.0 授权
用户绑定：系统用户与微信账号绑定/解绑管理
微信支付：统一下单、订单查询、关闭订单、退款、支付统计
码管理：小程序码/二维码生成、下载、扫码统计
现金红包：发送红包、查询状态、红包统计
商家转账：转账到零钱、查询状态、转账统计
回调通知：支付/退款/红包/转账回调通知处理

核心组件

架构组织

模块按子域分为 6 个子包，每个子包包含独立的 4 层架构：

子包	职责
configmgmt	微信配置管理（WechatConfig CRUD、WechatConfigManager）
mp	公众号管理（粉丝、菜单、模板消息、Portal 回调）
auth	微信认证（小程序登录、OAuth、用户绑定）
pay	微信支付（下单、查询、退款、回调）
qrcode	码管理（小程序码、二维码）
redpack	现金红包
transfer	商家转账
config	自动配置（WechatAutoConfiguration、WechatConfigManager）
properties	配置属性（WechatProperties）

核心组件

组件	说明
WechatConfigManager	微信配置管理器，根据数据库配置构建 WxMpService / WxMaService / WxPayService 实例，内存缓存 + 30 分钟定时刷新
WechatAutoConfiguration	自动配置类，`scaffold.wechat.enabled=true` 时启用
WechatProperties	YAML 静态配置属性，作为数据库配置的兜底

数据实体

实体	说明
WechatConfig	微信配置（公众号/小程序/支付参数）
WechatMpUser	公众号粉丝
WechatUserBind	用户绑定（系统用户 <-> 微信 OpenId）
WechatPayOrder	微信支付订单
WechatQrcode	码记录（小程序码/二维码）
WechatRedpack	现金红包记录
WechatTransfer	商家转账记录

匿名接口

以下接口路径需要在安全模块中配置为匿名访问：

路径前缀	说明
/api/v1/wechat/auth/**	微信认证（小程序登录、OAuth 回调）
/api/v1/wechat/mp/portal/**	公众号 Portal 回调
/api/v1/wechat/pay/notify/**	支付/退款回调通知
/api/v1/wechat/redpack/notify/**	红包回调通知
/api/v1/wechat/transfer/notify/**	转账回调通知

SDK 依赖

WxJava（weixin-java-mp）：公众号 SDK
WxJava（weixin-java-miniapp）：小程序 SDK
WxJava（weixin-java-pay）：支付 SDK

配置参数

配置前缀：scaffold.wechat

参数	类型	默认值	说明
enabled	boolean	false	模块开关（默认关闭，需显式启用）
mp.enabled	boolean	false	公众号功能开关
mp.app-id	String	-	公众号 AppID（YAML 兜底）
mp.app-secret	String	-	公众号 AppSecret
mp.token	String	-	消息校验 Token
mp.aes-key	String	-	消息加密 Key
mp.oauth-redirect-uri	String	-	OAuth2.0 回调地址
miniapp.enabled	boolean	false	小程序功能开关
miniapp.app-id	String	-	小程序 AppID
miniapp.app-secret	String	-	小程序 AppSecret
pay.enabled	boolean	false	支付功能开关
pay.app-id	String	-	关联的 AppID
pay.mch-id	String	-	商户号
pay.api-v3-key	String	-	APIv3 密钥
pay.pay-key	String	-	V2 API 密钥（现金红包签名用）
pay.private-key-path	String	-	商户私钥文件路径
pay.cert-serial-no	String	-	证书序列号
pay.notify-url	String	-	支付回调 URL
pay.refund-notify-url	String	-	退款回调 URL

配置优先级：数据库配置 > YAML 配置。WechatConfigManager 先查数据库默认配置，找不到再从 YAML 构建。

API 接口列表

管理端 API（需 JWT 认证）

WechatConfigController -- 微信配置管理 (`/v1/wechat/config`)

方法	路径	说明
POST	/page	分页查询配置
GET	/detail/{id}	配置详情
POST	/create	创建配置
POST	/update	更新配置
POST	/delete/{id}	删除配置
POST	/test-connection/{id}	测试连接
POST	/set-default/{id}	设为默认配置

WechatMpController -- 公众号管理 (`/v1/wechat/mp`)

方法	路径	说明
POST	/user/page	分页查询粉丝
POST	/user/sync/{configId}	同步粉丝列表
POST	/menu/create/{configId}	创建自定义菜单
GET	/menu/get/{configId}	查询当前菜单
POST	/menu/delete/{configId}	删除自定义菜单
POST	/template/send/{configId}	发送模板消息
GET	/statistics/{configId}	获取公众号统计

WechatUserBindController -- 微信绑定管理 (`/v1/wechat/auth`)

方法	路径	说明
GET	/bindings?userId=	查询用户微信绑定列表
POST	/unbind?userId=	解绑微信账号

WechatPayController -- 微信支付管理 (`/v1/wechat/pay`)

方法	路径	说明
POST	/create	统一下单
POST	/page	分页查询订单
GET	/detail/{id}	订单详情
GET	/query/{orderNo}?configId=	查询微信侧订单状态
POST	/close/{orderNo}?configId=	关闭订单
POST	/refund	申请退款
GET	/statistics/{configId}	支付统计

WechatQrcodeController -- 码信息管理 (`/v1/wechat/qrcode`)

方法	路径	说明
POST	/page	分页查询码信息
POST	/generate	生成码
GET	/detail/{id}	查看码详情
GET	/download-url/{id}	获取码下载地址
GET	/statistics/{configId}	获取码统计
POST	/delete/{id}	删除码记录
POST	/record-scan?scene=&configId=	记录扫码

RedpackController -- 现金红包管理 (`/v1/wechat/redpack`)

方法	路径	说明
POST	/send	发送红包
POST	/page	分页查询红包记录
GET	/detail/{id}	红包详情
POST	/query/{mchBillNo}?configId=	查询微信侧红包状态
GET	/statistics/{configId}	红包统计

TransferController -- 商家转账管理 (`/v1/wechat/transfer`)

方法	路径	说明
POST	/create	发起转账
POST	/page	分页查询转账记录
GET	/detail/{id}	转账详情
POST	/query/{outBatchNo}?configId=	查询微信侧转账状态
GET	/statistics/{configId}	转账统计

匿名 API（无需 JWT 认证）

WechatAuthController -- 微信认证 (`/api/v1/wechat/auth`)

方法	路径	说明
POST	/miniapp/login	小程序登录
POST	/miniapp/phone-bind	小程序手机号绑定
GET	/mp/authorize-url/{configId}?redirectUri=&state=	获取公众号 OAuth 授权 URL
POST	/mp/callback	公众号 OAuth 回调

WechatMpPortalController -- 公众号 Portal 回调 (`/api/v1/wechat/mp/portal`)

方法	路径	说明
GET	/{appId}	微信签名验证
POST	/{appId}	接收微信消息/事件推送

WechatPayNotifyController -- 支付回调 (`/api/v1/wechat/pay/notify`)

方法	路径	说明
POST	/pay/{configId}	支付结果通知
POST	/refund/{configId}	退款结果通知

RedpackNotifyController -- 红包回调 (`/api/v1/wechat/redpack/notify`)

方法	路径	说明
POST	/{configId}	红包回调通知

TransferNotifyController -- 转账回调 (`/api/v1/wechat/transfer/notify`)

方法	路径	说明
POST	/{configId}	转账回调通知

使用示例

1. 配置微信公众号

方式一：通过 API 动态配置（推荐）

POST /v1/wechat/config/create
{
  "platform": "MP",
  "name": "生产公众号",
  "appId": "wx1234567890",
  "appSecret": "abcdef...",
  "token": "mytoken",
  "aesKey": "myaeskey",
  "isDefault": true,
  "status": 1
}

说明：status 字段遵循布尔语义规范，1 = 启用，0 = 禁用

方式二：YAML 静态配置（兜底）

scaffold:
  wechat:
    enabled: true
    mp:
      enabled: true
      app-id: wx1234567890
      app-secret: abcdef...
      token: mytoken
      aes-key: myaeskey

2. 小程序登录

前端调用 wx.login() 获取 code，然后：

POST /api/v1/wechat/auth/miniapp/login
{
  "code": "0a3xxx...",
  "configId": 1234567890
}

返回 JWT token 和用户信息，前端存储 token 后续请求使用。

3. 公众号 OAuth 授权

1. 前端跳转到: GET /api/v1/wechat/auth/mp/authorize-url/{configId}?redirectUri=https://...
2. 用户授权后微信回调到 redirectUri 并携带 code
3. 前端用 code 调用: POST /api/v1/wechat/auth/mp/callback
   {"code": "CODE", "configId": 1234567890}

4. 发送现金红包

POST /v1/wechat/redpack/send
{
  "configId": 1234567890,
  "openId": "oXXXX...",
  "amount": 200,
  "totalNum": 1,
  "wishing": "恭喜发财",
  "actName": "活动名称",
  "remark": "备注"
}

注意事项

模块默认关闭：scaffold.wechat.enabled 默认为 false，需要在配置中显式启用
配置优先级：数据库配置优先于 YAML 配置，WechatConfigManager 先查数据库默认配置，找不到再从 YAML 构建
缓存刷新：WechatConfigManager 缓存每 30 分钟定时清除；修改配置后也会调用 evictCache() 立即生效
匿名路径：所有 /api/v1/wechat/** 路径的接口（认证、回调）需要在安全模块中配置为匿名访问
V2/V3 密钥：支付使用 V3 API（apiV3Key + 私钥证书），现金红包使用 V2 API（payKey 签名），两者密钥不同
证书文件：商户私钥文件路径（privateKeyPath）需要确保服务器上文件存在且有读取权限
多配置支持：同一个 WechatConfigManager 实例管理多个公众号/小程序，通过 configId 路由
状态枚举：
- status 字段（微信配置）遵循布尔语义：1 = 启用，0 = 禁用
- PayOrderStatus、RedpackStatus、TransferStatus 等为多态状态机，不遵循布尔语义规范

待完善功能

商家转账 V3 API 接入（TransferServiceImpl 中 3 个 TODO）：
- 调用微信商家转账到零钱 API（V3）
- V3 转账回调验签与解析
- 调用微信查询 API 同步转账状态

scaffold-wechat 微信模块

模块概述

功能列表

核心组件

架构组织

核心组件

数据实体

匿名接口

SDK 依赖

配置参数

API 接口列表

管理端 API（需 JWT 认证）

WechatConfigController -- 微信配置管理 (/v1/wechat/config)

WechatMpController -- 公众号管理 (/v1/wechat/mp)

WechatUserBindController -- 微信绑定管理 (/v1/wechat/auth)

WechatPayController -- 微信支付管理 (/v1/wechat/pay)

WechatQrcodeController -- 码信息管理 (/v1/wechat/qrcode)

RedpackController -- 现金红包管理 (/v1/wechat/redpack)

TransferController -- 商家转账管理 (/v1/wechat/transfer)

匿名 API（无需 JWT 认证）

WechatAuthController -- 微信认证 (/api/v1/wechat/auth)

WechatMpPortalController -- 公众号 Portal 回调 (/api/v1/wechat/mp/portal)

WechatPayNotifyController -- 支付回调 (/api/v1/wechat/pay/notify)

RedpackNotifyController -- 红包回调 (/api/v1/wechat/redpack/notify)

TransferNotifyController -- 转账回调 (/api/v1/wechat/transfer/notify)

使用示例

1. 配置微信公众号

2. 小程序登录

3. 公众号 OAuth 授权

4. 发送现金红包

注意事项

待完善功能

WechatConfigController -- 微信配置管理 (`/v1/wechat/config`)

WechatMpController -- 公众号管理 (`/v1/wechat/mp`)

WechatUserBindController -- 微信绑定管理 (`/v1/wechat/auth`)

WechatPayController -- 微信支付管理 (`/v1/wechat/pay`)

WechatQrcodeController -- 码信息管理 (`/v1/wechat/qrcode`)

RedpackController -- 现金红包管理 (`/v1/wechat/redpack`)

TransferController -- 商家转账管理 (`/v1/wechat/transfer`)

WechatAuthController -- 微信认证 (`/api/v1/wechat/auth`)

WechatMpPortalController -- 公众号 Portal 回调 (`/api/v1/wechat/mp/portal`)

WechatPayNotifyController -- 支付回调 (`/api/v1/wechat/pay/notify`)

RedpackNotifyController -- 红包回调 (`/api/v1/wechat/redpack/notify`)

TransferNotifyController -- 转账回调 (`/api/v1/wechat/transfer/notify`)