junhong_cmp_fiber/openspec/changes/wechat-official-account-payment-integration/proposal.md

微信公众号与微信支付集成提案

Why

当前系统的个人客户（C 端用户）无法通过微信公众号登录和使用微信支付功能，导致用户体验不完整。系统已经预留了微信相关的数据模型（wx_open_id, wx_union_id）和支付回调接口，但缺少真实的微信 SDK 集成。为了满足个人客户的核心使用场景（微信扫码登录、钱包充值、购买套餐），需要立即对接微信公众号和微信支付能力。

What Changes

• 新增微信公众号 OAuth 认证：实现用户通过微信授权码获取 OpenID/UnionID 和基本信息（昵称、头像）
• 新增微信支付发起功能：
  • H5 支付：支持移动端浏览器外唤起微信支付
  • JSAPI 支付：支持微信内网页支付
• 完善微信支付回调处理：在现有回调接口基础上补充签名验证和完整的支付状态同步
• 新增微信配置管理：在配置文件中增加微信公众号和支付的必要参数（AppID、Secret、商户号、证书等）
• 集成 PowerWeChat SDK：使用 github.com/ArtisanCloud/PowerWeChat/v3 实现微信 API 调用

Capabilities

New Capabilities

• wechat-official-account: 微信公众号能力（OAuth 认证、获取用户信息）
• wechat-payment: 微信支付能力（H5 支付、JSAPI 支付、支付回调）

Modified Capabilities

无。现有功能不涉及需求级别的变更。

Impact

影响的代码模块：

• pkg/wechat/: 微信服务接口实现（替换 Mock 为真实实现）
• pkg/config/: 新增微信配置项
• internal/service/personal_customer/: 补充微信 OAuth 登录逻辑
• internal/service/order/: 新增微信支付发起和回调验证
• internal/handler/app/: 微信 OAuth 相关 API 端点
• internal/handler/h5/: 微信支付发起 API 端点
• internal/handler/callback/: 补充支付回调签名验证

依赖变更：

• 新增依赖：github.com/ArtisanCloud/PowerWeChat/v3

配置变更：

• 新增环境变量：
  • JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID
  • JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET
  • JUNHONG_WECHAT_PAYMENT_MCH_ID
  • JUNHONG_WECHAT_PAYMENT_API_V3_KEY
  • 等（详见配置设计）

API 变更：

• 修改端点：POST /api/c/v1/bind-wechat（从"not implemented"变为可用）
• 新增端点：
  • POST /api/h5/orders/:id/wechat-pay/jsapi（JSAPI 支付）
  • POST /api/h5/orders/:id/wechat-pay/h5（H5 支付）
• 增强端点：POST /api/callback/wechat-pay（补充签名验证）

数据库变更：

• 无。现有表结构已满足需求。

部署影响：

• 需要提供微信商户证书文件（apiclient_cert.pem、apiclient_key.pem）
• 需要配置微信回调域名白名单