This commit is contained in:
@@ -0,0 +1,364 @@
|
||||
## Context
|
||||
|
||||
当前系统通过环境变量配置微信参数（`pkg/config/config.go` 中的 `WechatConfig` 结构体，包含 `OfficialAccountConfig` 和 `PaymentConfig`），在启动时创建全局单例 `PaymentService`，注入到 `order.Service` 中使用。这种模式无法动态切换支付凭证，也不支持富友支付渠道。
|
||||
|
||||
公众号 OAuth 配置同样硬编码在环境变量中，与支付配置相互独立。业务上，一套"微信身份"包含公众号 AppID、小程序 AppID 和支付凭证，三者必须原子性切换，否则会出现 OpenID 与 AppID 不匹配的问题。
|
||||
|
||||
代理充值模块目前只有 Store 层（`internal/store/postgres/agent_recharge_store.go`），缺少 Service 层和 Handler 层，无法通过 API 发起充值。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 在管理后台 CRUD 管理多套微信配置（OAuth + 支付），支持微信直连和富友两种渠道
|
||||
- 全局唯一激活约束：任意时刻最多一个配置生效
|
||||
- 配置切换秒级生效，不影响在途支付
|
||||
- 无生效配置时系统降级为仅支持钱包/线下支付
|
||||
- 接入富友支付的公众号 JSAPI + 小程序支付能力
|
||||
- 支付回调按订单关联的 `payment_config_id` 验签，解决切换期间的竞态问题
|
||||
- 代理充值完整实现 Service/Handler/回调
|
||||
- 所有配置操作记录审计日志
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不支持同时激活多个配置进行负载均衡或路由
|
||||
- 不支持支付宝直连（现有支付宝代码保留不改造）
|
||||
- 不加密存储敏感字段（明文存储，接口返回时脱敏）
|
||||
- 不自动检测配置有效性（如证书过期、商户号封禁）
|
||||
- 不实现富友退款功能（后续按需扩展）
|
||||
- 不动态加载 OAuth 配置（本次只存不用，`OfficialAccountService` 暂时继续从环境变量读取）
|
||||
- 不实现客户端支付发起（留桩，另一个会话讨论）
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: 表名和提案名称
|
||||
|
||||
**选择：`tb_wechat_config`（非 `tb_payment_config`）**
|
||||
|
||||
OAuth 配置纳入管理后，每套配置代表一套完整的微信身份（公众号 + 小程序 + 支付），切换配置等于原子性切换一切。用 `payment_config` 命名会遗漏 OAuth 语义，用 `wechat_config` 更准确地反映其职责范围。
|
||||
|
||||
### Decision 2: 扁平字段按前缀分组
|
||||
|
||||
**选择：扁平字段，按前缀分组（`oa_` / `miniapp_` / `wx_` / `fy_`）**
|
||||
|
||||
替代方案为 JSONB 字段存储不同渠道的参数。选择扁平字段的理由：系统使用者为非技术人员，前端表单可直接映射字段，无需 JSON 编辑器；字段级别的 NOT NULL 约束和验证更明确；不适用的字段留空即可（`provider_type=wechat` 时 `fy_*` 字段全部为空）。
|
||||
|
||||
### Decision 3: Payment 实例生命周期管理
|
||||
|
||||
**选择：按需创建 + Service 层缓存，配置变更时清除**
|
||||
|
||||
- 替代方案 A：启动时创建单例（当前方案）—— 无法动态切换
|
||||
- 替代方案 B：每次支付请求都创建新实例 —— 性能浪费
|
||||
- 选择方案：`PaymentConfigService` 维护当前生效配置的 Payment 实例内存缓存，配置切换时清除缓存，下次请求时按新配置重建实例
|
||||
|
||||
**「留桩」期间的过渡说明：**
|
||||
本次实现后，`WechatPayJSAPI`/`WechatPayH5` 方法加 TODO 注释但保留对 `s.wechatPayment` 单例的调用。这意味着在「留桩」期间：
|
||||
- `internal/bootstrap/dependencies.go` 的 `WechatPayment` 字段**暂时保留**
|
||||
- `internal/bootstrap/services.go` 和 `handlers.go` 的 `deps.WechatPayment` 注入**暂时保留**
|
||||
- 等 WechatPayJSAPI/WechatPayH5 完成动态加载改造后，再统一删除上述字段和注入点
|
||||
|
||||
**回调（callback）不属于留桩范围**：任务 1.6.1 的「留桩」仅指验签逻辑，回调的订单分发（按 payment_config_id 路由）必须完整实现，详见 Decision 5。
|
||||
|
||||
### Decision 4: 生效配置缓存策略
|
||||
|
||||
**选择：Redis 缓存 + 主动失效**
|
||||
|
||||
- 缓存 Key：**`wechat:config:active`**（全项目统一使用此命名，spec 文档中任何地方写 `payment:config:active` 均为笔误，以本文档为准），存储完整配置 JSON，TTL 5 分钟
|
||||
- 主动失效：激活/停用/更新/删除配置时主动 DEL 缓存
|
||||
- 读取流程：Redis GET → 命中返回 → MISS 则查 DB → SET 缓存
|
||||
- 空标记：无配置时缓存 `"none"` TTL 1 分钟，防止缓存穿透
|
||||
- Redis Key 定义在 `pkg/constants/redis.go`：`RedisWechatConfigActiveKey()`
|
||||
|
||||
### Decision 5: 配置切换时在途订单处理
|
||||
|
||||
**选择：不取消在途订单，自然完成或过期**
|
||||
|
||||
替代方案为切换时批量取消所有待支付的第三方订单，但用户可能已拉起支付正在输密码，取消订单会导致钱扣了但订单已取消，需要人工退款。
|
||||
|
||||
实现方式：
|
||||
1. `tb_order` 新增 `payment_config_id` 字段（nullable，钱包/线下支付不需要）
|
||||
2. `tb_asset_recharge_record` 新增 `payment_config_id` 字段
|
||||
3. `tb_agent_recharge_record` 新增 `payment_config_id` 字段
|
||||
4. 下单时记录当前使用的配置 ID
|
||||
5. 回调处理时，按 `payment_config_id` 加载对应配置进行验签
|
||||
6. 未支付的旧订单靠现有的 30 分钟超时自动取消机制清理
|
||||
7. 有待支付订单引用的配置不允许删除（软删除后仍可用于回调验签）
|
||||
|
||||
### Decision 6: 富友支付接入方案
|
||||
|
||||
**选择：基于 `wxPreCreate` 接口，支持公众号 JSAPI 和小程序支付**
|
||||
|
||||
- 接口地址：`POST /wxPreCreate`（生产地址从配置读取）
|
||||
- 公众号 JSAPI：`trade_type=JSAPI`，`sub_appid=公众号AppID`，`sub_openid=用户公众号OpenID`
|
||||
- 小程序支付：`trade_type=LETPAY`，`sub_appid=小程序AppID`，`sub_openid=用户小程序OpenID`
|
||||
- 签名算法：RSA + MD5（字典序排列参数 → GBK 编码 → MD5 哈希 → RSA 签名 → Base64）
|
||||
- 通信协议：XML + GBK 编码 + 双重 URL 编码
|
||||
- 回调处理：GBK → UTF-8 转换 → XML 解析 → RSA 验签
|
||||
- 代码组织：`pkg/fuiou/` 包，从 cc-coding 项目移植核心逻辑，适配本项目的日志和错误处理规范
|
||||
|
||||
### Decision 7: 模块分层设计
|
||||
|
||||
**遵循 Handler → Service → Store → Model 分层：**
|
||||
|
||||
```
|
||||
internal/
|
||||
├── model/
|
||||
│ ├── wechat_config.go # WechatConfig 模型 + 常量
|
||||
│ └── dto/
|
||||
│ ├── wechat_config_dto.go # 配置管理 DTO
|
||||
│ └── agent_recharge_dto.go # 代理充值 DTO
|
||||
├── store/postgres/
|
||||
│ ├── wechat_config_store.go # CRUD + 激活/停用
|
||||
│ └── agent_recharge_store.go # 已有，需扩展
|
||||
├── service/
|
||||
│ ├── wechat_config/service.go # 配置管理业务逻辑
|
||||
│ └── agent_recharge/service.go # 代理充值业务逻辑（新建）
|
||||
├── handler/
|
||||
│ ├── admin/wechat_config.go # 配置管理 Handler
|
||||
│ ├── admin/agent_recharge.go # 代理充值 Handler（新建）
|
||||
│ └── callback/payment.go # 改造：支持富友回调 + 按配置验签
|
||||
├── routes/
|
||||
│ ├── wechat_config.go # 配置管理路由
|
||||
│ └── agent_recharge.go # 代理充值路由（新建）
|
||||
└── bootstrap/ # 注册新模块
|
||||
|
||||
pkg/
|
||||
└── fuiou/
|
||||
├── client.go # 富友 HTTP 客户端
|
||||
└── types.go # 请求/响应结构体
|
||||
```
|
||||
|
||||
### Decision 8: 接口脱敏策略
|
||||
|
||||
**敏感字段在 API 响应中脱敏，数据库明文存储：**
|
||||
|
||||
| 字段类型 | 脱敏规则 | 示例 |
|
||||
|---------|---------|------|
|
||||
| Secret/Key（短） | 显示前4后4，中间 `***` | `secr****7890` |
|
||||
| 证书/私钥（长） | 仅显示状态 | `[已配置]` / `[未配置]` |
|
||||
|
||||
更新时：不传或传空字符串 = 不修改，传新值 = 替换。
|
||||
|
||||
### Decision 9: 前端支付方式展示
|
||||
|
||||
富友支付对用户透明，前端统一显示"微信支付"。后端根据生效配置的 `provider_type` 自动路由到微信直连或富友，前端不感知具体支付渠道。
|
||||
|
||||
### Decision 10: OAuth 配置管理策略
|
||||
|
||||
OAuth 字段（公众号 AppID/AppSecret、小程序 AppID/AppSecret）存入 `tb_wechat_config`。本次只存不用——`OfficialAccountService` 暂时继续从环境变量读取。H5/小程序重构时切换为从数据库动态加载。保证切换配置时 OAuth 和支付 AppID 原子性同步。
|
||||
|
||||
**因此，以下代码本次不删除：**
|
||||
- `pkg/config/config.go` 中的 `OfficialAccountConfig` 结构体（`WechatConfig.OfficialAccount` 字段仍需使用）
|
||||
- `pkg/config/defaults/config.yaml` 中的 `wechat.official_account` 配置节（`OfficialAccountService` 仍从中读取）
|
||||
- `cmd/api/main.go` 中 `validateWechatConfig` 里对公众号配置的校验逻辑（仅删除支付相关校验）
|
||||
|
||||
**以下代码本次必须删除（Payment 相关的 YAML 方案完全废弃）：**
|
||||
- `pkg/config/config.go` 的 `PaymentConfig` 结构体 + `WechatConfig.Payment` 字段
|
||||
- `pkg/config/defaults/config.yaml` 的 `wechat.payment` 配置节
|
||||
- `pkg/wechat/config.go` 的 `NewPaymentApp(cfg *config.Config, ...)` 函数（从 YAML/CertPath 创建 Payment 实例，被 DB 方案彻底取代）
|
||||
- `cmd/api/main.go` `validateWechatConfig` 中所有 `wechatCfg.Payment.*` 相关校验
|
||||
|
||||
### Decision 11: 代理充值设计
|
||||
|
||||
- 仅充到余额钱包（`wallet_type=main`）
|
||||
- 代理只能充自己店铺，平台可指定任意店铺
|
||||
- 支付方式：`wechat`（在线）/ `offline`（线下，仅平台，需操作密码）
|
||||
- 回调处理完整实现，客户端支付发起留桩
|
||||
|
||||
### Decision 12: Card → Asset 常量重命名
|
||||
|
||||
`pkg/constants/wallet.go` 中 `Card*` 前缀统一改为 `Asset*`，原 `Card*` 常量保留为废弃别名（向后兼容）。
|
||||
|
||||
影响范围：`CardWalletResourceType*`、`CardWalletStatus*`、`CardTransactionType*`、`CardRechargeOrderPrefix`、`CardRechargeMinAmount`、`CardRechargeMaxAmount`。
|
||||
|
||||
## tb_wechat_config 表结构
|
||||
|
||||
```sql
|
||||
CREATE TABLE tb_wechat_config (
|
||||
-- 基础字段
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL, -- 配置名称
|
||||
description TEXT, -- 配置描述
|
||||
provider_type VARCHAR(20) NOT NULL, -- 支付渠道: wechat / fuiou
|
||||
is_active BOOLEAN NOT NULL DEFAULT FALSE, -- 是否激活
|
||||
|
||||
-- OAuth 公众号
|
||||
oa_app_id VARCHAR(100) NOT NULL, -- 公众号 AppID
|
||||
oa_app_secret VARCHAR(200) NOT NULL, -- 公众号 AppSecret
|
||||
oa_token VARCHAR(200), -- 消息验证 Token
|
||||
oa_aes_key VARCHAR(200), -- 消息加密 AESKey
|
||||
oa_oauth_redirect_url VARCHAR(500), -- OAuth 回调地址
|
||||
|
||||
-- OAuth 小程序
|
||||
miniapp_app_id VARCHAR(100), -- 小程序 AppID
|
||||
miniapp_app_secret VARCHAR(200), -- 小程序 AppSecret
|
||||
|
||||
-- 支付-微信直连 (provider_type=wechat 时使用)
|
||||
wx_mch_id VARCHAR(100), -- 商户号
|
||||
wx_api_v3_key VARCHAR(200), -- API V3 密钥
|
||||
wx_api_v2_key VARCHAR(200), -- API V2 密钥
|
||||
wx_cert_content TEXT, -- 证书内容 (Base64)
|
||||
wx_key_content TEXT, -- 私钥内容 (Base64)
|
||||
wx_serial_no VARCHAR(200), -- 证书序列号
|
||||
wx_notify_url VARCHAR(500), -- 支付回调地址
|
||||
|
||||
-- 支付-富友 (provider_type=fuiou 时使用)
|
||||
fy_ins_cd VARCHAR(50), -- 机构号
|
||||
fy_mchnt_cd VARCHAR(50), -- 商户号
|
||||
fy_term_id VARCHAR(50), -- 终端号
|
||||
fy_private_key TEXT, -- 商户 RSA 私钥 (Base64)
|
||||
fy_public_key TEXT, -- 富友 RSA 公钥 (Base64)
|
||||
fy_api_url VARCHAR(500), -- API 地址
|
||||
fy_notify_url VARCHAR(500), -- 回调地址
|
||||
|
||||
-- 审计字段
|
||||
creator BIGINT NOT NULL DEFAULT 0, -- 创建人 ID
|
||||
updater BIGINT NOT NULL DEFAULT 0, -- 更新人 ID
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
deleted_at TIMESTAMPTZ -- 软删除
|
||||
);
|
||||
|
||||
CREATE INDEX idx_wechat_config_is_active ON tb_wechat_config(is_active) WHERE deleted_at IS NULL;
|
||||
CREATE INDEX idx_wechat_config_provider_type ON tb_wechat_config(provider_type) WHERE deleted_at IS NULL;
|
||||
```
|
||||
|
||||
## 流程图
|
||||
|
||||
### 配置切换流程
|
||||
|
||||
```
|
||||
管理员调用 PUT /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 实例缓存
|
||||
+--⑤ 记录审计日志
|
||||
|
|
||||
+-- 新订单 --> 使用新配置
|
||||
+-- 旧订单(待支付) --> 回调时按 payment_config_id 加载旧配置验签
|
||||
+-- 30分钟超时自动取消
|
||||
```
|
||||
|
||||
### 改造后的第三方支付流程（两步走）
|
||||
|
||||
```
|
||||
步骤1: H5 创建订单
|
||||
POST /api/h5/orders
|
||||
+-- payment_method = "wechat"
|
||||
+-- 系统查询 active 配置
|
||||
+-- IF 有配置 --> 记录 payment_config_id 到订单
|
||||
+-- 返回 order (payment_status=1 待支付)
|
||||
|
||||
步骤2: 发起微信支付（留桩）
|
||||
POST /api/h5/orders/:id/wechat-pay/jsapi
|
||||
+-- 加载 order.payment_config_id 对应配置
|
||||
+-- 按 provider_type 分发:
|
||||
| +-- wechat --> PaymentService.CreateJSAPIOrder()
|
||||
| +-- fuiou --> FuiouClient.WxPreCreate()
|
||||
+-- 返回支付参数给前端（本次留桩）
|
||||
|
||||
步骤3: 支付回调
|
||||
POST /api/callback/wechat-pay 或 /api/callback/fuiou-pay
|
||||
+-- 解析订单号
|
||||
+-- 按订单号前缀分发:
|
||||
| +-- "ORD" --> 套餐订单 --> 查 tb_order
|
||||
| +-- "CRCH" --> 资产充值 --> 查 tb_asset_recharge_record
|
||||
| +-- "ARCH" --> 代理充值 --> 查 tb_agent_recharge_record
|
||||
+-- 按 payment_config_id 加载配置
|
||||
+-- 用对应凭证验签
|
||||
+-- 调用对应 Service.HandlePaymentCallback()
|
||||
```
|
||||
|
||||
### 代理预充值流程
|
||||
|
||||
```
|
||||
代理/平台 --> POST /api/admin/agent-recharges
|
||||
|
|
||||
+-- 验证权限: 代理只能充自己店铺，平台可指定店铺
|
||||
+-- 验证金额范围 (100元~100万元)
|
||||
+-- 查找目标店铺的 main 钱包
|
||||
|
|
||||
+-- IF payment_method = "wechat"
|
||||
| +-- 查询 active 配置 --> 无配置则拒绝
|
||||
| +-- 记录 payment_config_id
|
||||
| +-- 创建充值订单 (status=1 待支付)
|
||||
| +-- 返回订单信息（客户端支付发起留桩）
|
||||
|
|
||||
+-- IF payment_method = "offline"
|
||||
+-- 验证是否平台账号 --> 非平台拒绝
|
||||
+-- 返回订单信息（status=1 待支付，等待线下确认）
|
||||
|
||||
平台确认线下充值 --> POST /api/admin/agent-recharges/:id/offline-pay
|
||||
+-- 验证操作密码
|
||||
+-- 事务内:
|
||||
| +-- 更新充值订单状态 (status=2 已支付)
|
||||
| +-- 增加余额钱包余额（乐观锁）
|
||||
| +-- 创建钱包交易记录
|
||||
+-- 记录审计日志
|
||||
```
|
||||
|
||||
### 回调统一分发流程
|
||||
|
||||
```
|
||||
回调到达
|
||||
|
|
||||
+-- 微信回调 POST /api/callback/wechat-pay
|
||||
| +-- PowerWeChat SDK 解析 + 取 out_trade_no
|
||||
|
|
||||
+-- 富友回调 POST /api/callback/fuiou-pay
|
||||
| +-- GBK->UTF-8 --> XML解析 --> 取 mchnt_order_no
|
||||
|
|
||||
+-- 按订单号前缀分发
|
||||
|
|
||||
+-- "ORD" --> 套餐订单
|
||||
| +-- 查询 tb_order --> 取 payment_config_id
|
||||
| +-- 加载配置验签
|
||||
| +-- orderService.HandlePaymentCallback()
|
||||
|
|
||||
+-- "CRCH" --> 资产充值（修复：当前代码用废弃的 "RCH"）
|
||||
| +-- 查询 tb_asset_recharge_record --> 取 payment_config_id
|
||||
| +-- 加载配置验签
|
||||
| +-- rechargeService.HandlePaymentCallback()
|
||||
|
|
||||
+-- "ARCH" --> 代理充值（全新）
|
||||
+-- 查询 tb_agent_recharge_record --> 取 payment_config_id
|
||||
+-- 加载配置验签
|
||||
+-- agentRechargeService.HandlePaymentCallback()
|
||||
```
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| 风险 | 影响 | 缓解措施 |
|
||||
|------|------|----------|
|
||||
| 配置切换后旧回调验签失败 | 用户付了钱但订单未处理 | 订单记录 `payment_config_id`，回调按该字段加载配置验签 |
|
||||
| Redis 缓存与 DB 不一致 | 短暂使用旧配置 | TTL 5 分钟兜底 + 切换时主动失效 |
|
||||
| 富友 SDK 是自研非开源 | 维护成本 | 从已验证的 cc-coding 项目移植，核心逻辑已线上运行 |
|
||||
| 证书 Base64 存 DB 体量大 | 单行数据量增大 | 证书文件通常 2-4KB，Base64 后约 3-6KB，可接受 |
|
||||
| 多实例部署缓存一致性 | 某实例使用旧缓存 | Redis 是共享的，DEL 操作对所有实例生效；内存缓存通过 Redis MISS 时重建 |
|
||||
| Card→Asset 常量重命名 | 引用处需要更新 | 旧常量保留为废弃别名，渐进迁移 |
|
||||
| OAuth 只存不用 | 数据在但不生效 | 明确标注为预留，H5 重构时切换 |
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. **数据库迁移**：新建 `tb_wechat_config` 表 + `tb_order`、`tb_asset_recharge_record`、`tb_agent_recharge_record` 各新增 `payment_config_id` 列（nullable，不影响存量数据）
|
||||
2. **常量重命名**：`Card*` → `Asset*`，旧名保留为废弃别名
|
||||
3. **删除 YAML 支付配置基础设施**（以下操作必须作为独立任务明确执行，不可遗漏）：
|
||||
- `pkg/config/config.go`：删除 `PaymentConfig` 结构体、删除 `WechatConfig.Payment` 字段
|
||||
- `pkg/config/defaults/config.yaml`：删除 `wechat.payment:` 整个配置节（保留 `wechat.official_account:` 节，OAuth 继续使用）
|
||||
- `pkg/wechat/config.go`：删除 `NewPaymentApp(cfg *config.Config, ...)` 函数（从文件路径创建 Payment 的方式已被 DB Base64 方案取代）
|
||||
- `cmd/api/main.go`：删除 `validateWechatConfig` 中所有 `wechatCfg.Payment.*` 相关的校验代码（保留公众号校验部分）
|
||||
4. **代码部署**：新代码兼容无配置场景（无生效配置 = 降级为纯钱包支付）
|
||||
5. **配置迁移**：将当前环境变量中的微信参数手动录入为第一个配置并激活
|
||||
6. **回滚策略**：回滚代码后，支付流程回退到读取环境变量的单例模式（若 `deps.WechatPayment` 仍存在），新表数据不影响旧逻辑
|
||||
|
||||
## Closed Questions
|
||||
|
||||
- ~~富友支付是否需要退款？~~ → 暂不包含（Non-Goals 已声明）
|
||||
- ~~是否需要配置变更审计日志？~~ → 必须纳入，复用 `AuditServiceInterface`
|
||||
- ~~充值模块是否需要改造？~~ → 全部纳入，资产充值 + 代理充值都加 `payment_config_id`
|
||||
- ~~支付宝如何处理？~~ → 保留不改造
|
||||
- ~~OpenID 与 AppID 一致性？~~ → OAuth 字段纳入同一配置，切换配置时原子性同步
|
||||
Reference in New Issue
Block a user