docs: 新增 Gateway 集成和微信公众号支付集成的 OpenSpec 规划文档

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

@@ -0,0 +1,62 @@
+# 微信公众号与微信支付集成提案
+
+## 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`）
+- 需要配置微信回调域名白名单