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>
62 lines
6.6 KiB
Markdown
62 lines
6.6 KiB
Markdown
## 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 行），保留 `NewOfficialAccountApp`
|
||
- `cmd/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；配置切换时主动清缓存保证即时生效
|