63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# 微信公众号与微信支付集成提案
|
||
|
||
## 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`）
|
||
- 需要配置微信回调域名白名单
|