junhong_cmp_fiber/openspec/changes/archive/2026-03-17-add-payment-config-management/design.md

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 表结构

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 字段纳入同一配置，切换配置时原子性同步