huang
63ca12393b
包含 proposal.md、design.md、tasks.md 及各模块 spec 文件（微信配置管理、富友支付、代理充值、订单支付、资产充值适配、微信支付留桩） Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
6.6 KiB
6.6 KiB
Why
当前微信相关参数（公众号 OAuth、小程序、支付凭证）硬编码在环境变量中，只有一套配置，无法动态切换。业务上，微信公众号/小程序随时可能被封禁，需要在管理后台秒级切换到备用配置恢复 OAuth 登录和支付能力。同时需要接入富友支付作为备选通道，降低对微信直连的单一依赖。此外，代理预充值（余额钱包在线充值）当前只有 Store 层骨架，缺少完整的 Service/Handler/回调处理，需要补齐。
What Changes
本提案包含两个目标，按顺序实施：
Goal 1：微信参数配置管理 + 支付流程改造
- 新增微信参数配置管理模块：支持在管理后台 CRUD 管理多套微信参数配置，每套配置 = 完整的"微信身份"（OAuth 公众号 + OAuth 小程序 + 支付凭证），支持全局唯一激活
- 新建
tb_wechat_config表：扁平字段存储 OAuth 参数（公众号 AppID/AppSecret、小程序 AppID/AppSecret）、微信直连支付参数、富友支付参数，支持多配置共存 - 新增富友支付 SDK：基于富友
wxPreCreate接口实现公众号 JSAPI 和小程序支付，移植 cc-coding 项目的 RSA 签名、XML 编解码、GBK 转换等核心逻辑 - 改造订单支付流程：订单创建时从数据库/Redis 动态加载当前生效配置记录
payment_config_id；支付发起（WechatPayJSAPI/WechatPayH5）本次留桩，添加 TODO 标记，保留单例调用——等下一阶段实现动态加载；同时删除启动时基于 YAML 创建 PaymentService 单例的相关代码 - 订单关联配置：
tb_order新增payment_config_id字段，回调按该字段加载对应配置验签，解决配置切换期间在途支付的竞态问题 - 资产充值模块适配：
tb_asset_recharge_record新增payment_config_id字段，充值回调按配置验签 - 常量重命名：
pkg/constants/wallet.go中Card*前缀常量统一重命名为Asset*，与模型层命名一致 - 配置切换安全策略：切换配置时不取消在途订单，旧订单按原配置自然完成或超时过期；无生效配置时只允许钱包/线下支付
- 仅平台用户可操作：通过路由层中间件限制仅平台用户访问
- 审计日志：所有 CRUD 和激活/停用操作记录审计日志，复用现有 AuditServiceInterface
注意：OAuth 配置字段本次只存储和管理（数据库 + 管理界面），OfficialAccountService 的动态加载改造留待 H5/小程序重构时实施。客户端支付发起（调用第三方获取拉起支付参数）本次留桩不实现，在另一个 session 讨论。
Goal 2：代理预充值系统
- 新增代理余额钱包在线充值：完整的 Service + Handler + 回调处理，支持微信在线支付和线下充值
- 代理只能选择微信支付：后端根据当前生效配置自动路由到微信直连或富友，对代理透明
- 线下充值仅平台操作：需要操作密码二次验证
tb_agent_recharge_record新增payment_config_id字段- 充值目标：仅充到余额钱包（
wallet_type=main），佣金钱包通过分佣自动入账
注意：代理充值的客户端支付发起（调用第三方获取拉起参数）同样留桩不实现。回调处理完整实现（解析第三方支付成功通知）。
Capabilities
New Capabilities
wechat-config-management：微信参数配置的 CRUD 管理、激活/停用、全局唯一激活约束、Redis 缓存、接口脱敏、审计日志fuiou-payment：富友支付集成，包括 wxPreCreate 下单（公众号 JSAPI + 小程序）、支付回调验签处理、RSA 签名/XML 编解码agent-recharge：代理余额钱包在线充值，创建充值订单、线下充值确认、回调处理、钱包余额更新
Modified Capabilities
wechat-payment：配置来源从环境变量改为数据库动态加载；Payment 实例从启动时单例改为按需创建（留桩）order-payment：订单新增payment_config_id字段；下单时无生效配置则拒绝第三方支付；回调处理按payment_config_id加载对应配置验签asset-recharge：充值表新增payment_config_id字段；回调处理按配置验签；修复RechargeOrderPrefix废弃问题（当前用"RCH"，实际前缀是"CRCH"）
Impact
- 新增文件：Model（
wechat_config.go）、DTO、Store、Service、Handler、迁移文件、富友 SDK 包（pkg/fuiou/）、常量、错误码、代理充值 Service/Handler - 修改文件：
internal/model/order.go（新增字段）、internal/model/asset_wallet.go（新增字段）、internal/model/agent_wallet.go（新增字段）、internal/service/order/service.go（动态加载配置 + 注入 wechatConfigService）、internal/handler/callback/payment.go（支持富友回调 + 按配置验签 + 修复前缀匹配）、pkg/constants/wallet.go（Card→Asset 重命名）、internal/bootstrap/（注册新模块）、internal/routes/（注册新路由）、cmd/api/docs.go+cmd/gendocs/main.go（文档生成器） - 删除/精简文件（YAML 支付方案遗留代码，必须清理）：
pkg/config/config.go：删除PaymentConfig结构体 +WechatConfig.Payment字段（约 15 行），保留OfficialAccountConfig结构体pkg/config/defaults/config.yaml：删除wechat.payment:配置节（约 10 行），保留wechat.official_account:节pkg/wechat/config.go：删除NewPaymentApp(cfg *config.Config, ...)函数（整个函数，约 30 行），保留NewOfficialAccountAppcmd/api/main.go：从validateWechatConfig中删除所有wechatCfg.Payment.*校验代码（约 40 行），保留公众号校验部分
- 新增 API 路由：
/api/admin/wechat-configs/*（8 个端点）、/api/admin/agent-recharges/*（4 个端点）、/api/callback/fuiou-pay（富友回调） - 数据库变更：新建
tb_wechat_config表、tb_order新增payment_config_id列、tb_asset_recharge_record新增payment_config_id列、tb_agent_recharge_record新增payment_config_id列 - 新增依赖：
golang.org/x/text（GBK 编解码，富友支付需要） - 保留不改造：支付宝支付（AlipayCallback、PaymentMethodAlipay 常量保持原样不动）；
OfficialAccountService及其 YAML 配置（OAuth 本次只存不用）；WechatPayment单例注入（留桩期间保留，等支付发起动态化后再移除） - 性能考虑：生效配置使用 Redis 缓存（TTL 5 分钟，Key：
wechat:config:active），避免每次支付查 DB；配置切换时主动清缓存保证即时生效