junhong_cmp_fiber/docs/wechat-config-management/功能总结.md

微信参数配置管理功能

功能概述

在管理后台支持多套微信支付配置的 CRUD 管理，每套配置代表一套完整的"微信身份"（公众号 OAuth + 小程序 OAuth + 支付凭证），支持全局唯一激活约束和秒级切换。同时集成富友支付 SDK，作为微信直连的备选渠道。

背景与动机

原有微信相关参数（公众号 OAuth、小程序、支付凭证）硬编码在环境变量中，只有一套配置，无法动态切换。业务上微信公众号/小程序随时可能被封禁，需要在管理后台秒级切换到备用配置恢复 OAuth 登录和支付能力。同时需要接入富友支付作为备选通道，降低对微信直连的单一依赖。

核心设计

配置切换流程

管理员激活新配置 POST /api/admin/wechat-configs/:id/activate
    │
    ├─ ① BEGIN 事务
    │   ├─ UPDATE tb_wechat_config SET is_active=false WHERE is_active=true
    │   └─ UPDATE tb_wechat_config SET is_active=true WHERE id=:id
    ├─ ② COMMIT
    ├─ ③ DEL Redis "wechat:config:active"（即时生效）
    └─ ④ 记录审计日志
         │
         ├─ 新订单 → 使用新配置（记录新的 payment_config_id）
         └─ 旧订单（待支付）→ 回调时按 payment_config_id 加载旧配置验签
                              └─ 30 分钟超时自动取消

生效配置缓存策略

• Redis Key：wechat:config:active（见 pkg/constants/redis.go）
• TTL：5 分钟（兜底，防 Redis 缓存与 DB 长期不一致）
• 主动失效：激活、停用、更新生效配置、删除配置时主动 DEL 缓存
• 空标记：无生效配置时缓存 "none"，TTL 1 分钟，防止缓存穿透
• 读取流程：Redis GET → 命中返回 → MISS → 查 DB → SET 缓存

配置切换时在途订单处理

• tb_order、tb_asset_recharge_record、tb_agent_recharge_record 均新增 payment_config_id 字段（nullable）
• 下单时记录当前使用的配置 ID，配置切换后旧订单仍按 payment_config_id 加载旧配置验签
• 旧待支付订单由现有 30 分钟超时自动取消机制清理
• 有待支付订单引用的配置不允许删除（软删除后仍可用于验签）

支付回调统一分发

回调到达
    │
    ├─ 微信回调 POST /api/callback/wechat-pay
    │   └─ PowerWeChat SDK 解析 → 取 out_trade_no
    │
    └─ 富友回调 POST /api/callback/fuiou-pay
        └─ GBK→UTF-8 → XML 解析 → 取 mchnt_order_no
    │
    └─ 按订单号前缀分发
        ├─ "ORD"  → 套餐订单   → orderService.HandlePaymentCallback()
        ├─ "CRCH" → 资产充值   → rechargeService.HandlePaymentCallback()
        └─ "ARCH" → 代理充值   → agentRechargeService.HandlePaymentCallback()

接口说明

基础路径

/api/admin/wechat-configs

权限要求：仅超级管理员（user_type=1）和平台用户（user_type=2）可访问，其他类型返回 1005。

接口列表

方法	路径	说明
POST	/api/admin/wechat-configs	创建配置
GET	/api/admin/wechat-configs	查询配置列表（分页+筛选）
GET	/api/admin/wechat-configs/active	查询当前生效配置
GET	/api/admin/wechat-configs/:id	查询配置详情
PUT	/api/admin/wechat-configs/:id	更新配置
DELETE	/api/admin/wechat-configs/:id	软删除配置
POST	/api/admin/wechat-configs/:id/activate	激活配置
POST	/api/admin/wechat-configs/:id/deactivate	停用配置
POST	/api/callback/fuiou-pay	富友支付回调（无需认证）

渠道类型（provider_type）

值	说明	必填支付字段
wechat	微信直连	wx_mch_id、wx_api_v3_key、wx_cert_content、wx_key_content、wx_serial_no、wx_notify_url
fuiou	富友聚合支付	fy_ins_cd、fy_mchnt_cd、fy_term_id、fy_private_key、fy_public_key、fy_api_url、fy_notify_url

敏感字段脱敏规则

接口响应中所有敏感字段均脱敏，数据库明文存储：

字段类型	脱敏规则	示例
Secret/Key（短）	前4位 + *** + 后4位	abcd***7890
证书/私钥（长）	仅显示状态	[已配置] / [未配置]

更新脱敏字段：不传或传空字符串 = 保留原值；传新明文值 = 替换。

删除保护规则

条件	错误码	错误消息
配置 is_active=true	1171	不能删除当前生效的支付配置，请先停用
存在待支付订单引用	1172	该配置存在未完成的支付订单，暂时无法删除

富友支付 SDK

位置：pkg/fuiou/

文件	说明
types.go	WxPreCreateRequest/Response、NotifyRequest 等 XML 结构体
client.go	Client 结构体、NewClient、RSA 签名/验签、HTTP 请求（XML+GBK）
wxprecreate.go	WxPreCreate 方法（公众号 JSAPI + 小程序支付下单）
notify.go	VerifyNotify（GBK→UTF-8 + XML 解析 + RSA 验签）、BuildNotifyResponse

签名算法：字典序排列参数 → GBK 编码 → MD5 哈希 → RSA 签名 → Base64

新增依赖：golang.org/x/text（GBK 编解码）

数据库变更

新建表 tb_wechat_config（迁移 000078）

字段组	字段	说明
基础信息	id, name, description, provider_type, is_active	配置基础字段
公众号 OAuth	oa_app_id, oa_app_secret, oa_token, oa_aes_key, oa_oauth_redirect_url	公众号相关
小程序 OAuth	miniapp_app_id, miniapp_app_secret	小程序相关
微信直连	wx_mch_id, wx_api_v3_key, wx_api_v2_key, wx_cert_content, wx_key_content, wx_serial_no, wx_notify_url	provider_type=wechat 时使用
富友	fy_ins_cd, fy_mchnt_cd, fy_term_id, fy_private_key, fy_public_key, fy_api_url, fy_notify_url	provider_type=fuiou 时使用
审计	creator, updater, created_at, updated_at, deleted_at	标准审计字段

新增字段

表	字段	类型	迁移文件
tb_order	payment_config_id	bigint, nullable	000079
tb_asset_recharge_record	payment_config_id	bigint, nullable	000080
tb_agent_recharge_record	payment_config_id	bigint, nullable	000081

新增错误码

错误码	常量	说明
1170	CodeWechatConfigNotFound	微信支付配置不存在
1171	CodeWechatConfigActive	不能删除/操作当前生效的支付配置
1172	CodeWechatConfigHasPendingOrders	该配置存在未完成的支付订单
1173	CodeFuiouPayFailed	富友支付失败
1174	CodeFuiouCallbackInvalid	富友回调验签失败
1175	CodeNoPaymentConfig	当前无可用的支付配置

审计日志

以下操作均记录审计日志（异步写入，失败不影响业务）：

操作	operation_type	说明
创建配置	create	after_data 存脱敏后配置
更新配置	update	before/after_data 均脱敏
删除配置	delete	before_data 存脱敏后配置
激活配置	activate	before_data=旧配置，after_data=新配置
停用配置	deactivate	before/after_data 存状态变更

涉及文件

新增文件

层级	文件	说明
模型	internal/model/wechat_config.go	WechatConfig 模型、渠道类型常量
DTO	internal/model/dto/wechat_config_dto.go	CRUD 请求/响应 DTO、脱敏方法
Store	internal/store/postgres/wechat_config_store.go	CRUD + 激活/停用 + 统计
Service	internal/service/wechat_config/service.go	业务逻辑、缓存管理、删除保护
Handler	internal/handler/admin/wechat_config.go	8 个 Handler 方法
路由	internal/routes/wechat_config.go	路由注册（含平台权限中间件）
SDK	pkg/fuiou/types.go	富友 XML 结构体
SDK	pkg/fuiou/client.go	富友 HTTP 客户端、签名/验签
SDK	pkg/fuiou/wxprecreate.go	富友支付下单
SDK	pkg/fuiou/notify.go	富友回调验签
迁移	migrations/000078_create_wechat_config_table.up.sql	创建 tb_wechat_config 表
迁移	migrations/000079_add_payment_config_id_to_order.up.sql	tb_order 新增字段
迁移	migrations/000080_add_payment_config_id_to_asset_recharge.up.sql	tb_asset_recharge_record 新增字段
迁移	migrations/000081_add_payment_config_id_to_agent_recharge.up.sql	tb_agent_recharge_record 新增字段

修改文件

文件	变更说明
internal/model/order.go	新增 PaymentConfigID *uint 字段
internal/model/asset_wallet.go	新增 PaymentConfigID *uint 字段
internal/handler/callback/payment.go	支持富友回调 + 按订单前缀分发 + 按 payment_config_id 验签
internal/routes/order.go	新增 /api/callback/fuiou-pay 路由
internal/service/order/service.go	注入 wechatConfigService、下单时记录 payment_config_id
internal/bootstrap/ 系列	注册 WechatConfigStore/Service/Handler
cmd/api/docs.go / cmd/gendocs/main.go	注册 WechatConfigHandler

删除/精简文件（YAML 支付方案遗留清理）

文件	变更说明
pkg/config/config.go	删除 PaymentConfig 结构体 + WechatConfig.Payment 字段
pkg/config/defaults/config.yaml	删除 wechat.payment: 整个配置节
pkg/wechat/config.go	删除 NewPaymentApp() 函数（YAML/CertPath 方式已被 DB Base64 方案替代）
cmd/api/main.go	删除 validateWechatConfig 中所有 wechatCfg.Payment.* 相关校验代码

常量定义

// pkg/constants/wallet.go（Card* 重命名为 Asset*，旧名保留为废弃别名）
AssetWalletResourceTypeIotCard   // 原 CardWalletResourceTypeIotCard
AssetWalletResourceTypeDevice    // 原 CardWalletResourceTypeDevice
AssetRechargeOrderPrefix         // "CRCH"（原 CardRechargeOrderPrefix）
AssetRechargeMinAmount           // 最小充值金额（分）
AssetRechargeMaxAmount           // 最大充值金额（分）

// pkg/constants/redis.go
RedisWechatConfigActiveKey()     // "wechat:config:active"

// internal/model/wechat_config.go
ProviderTypeWechat = "wechat"    // 微信直连
ProviderTypeFuiou  = "fuiou"     // 富友

已知限制（留桩）

以下功能本次未实现，待后续会话补全：

• 客户端支付发起：WechatPayJSAPI、WechatPayH5、FuiouPayJSAPI、FuiouPayMiniApp 均为留桩（返回"暂未实现"错误或 TODO 注释），当前仍保留 wechatPayment 单例注入
• OAuth 配置动态加载：OfficialAccountService 仍从环境变量读取，tb_wechat_config 中的 oa_* 字段仅存储，待 H5/小程序重构时切换

部署注意事项

1. 执行数据库迁移（000078~000081）后，现有数据不受影响（新字段均为 nullable）
2. 原环境变量 JUNHONG_WECHAT_PAYMENT_* 系列已不再读取，可清理
3. 首次上线后，需要在管理后台手动创建并激活一个微信配置，否则第三方支付功能处于禁用状态（系统自动降级为仅支持钱包/线下支付）