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

## 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`）
- 需要配置微信回调域名白名单