# Payment Service 实现

> **日期**：2026-01-27  
> **类型**：新功能  
> **影响范围**：支付服务

---

## 变更概述

实现 payment-service 作为纯技术服务，封装微信支付和支付宝 SDK，为 recharge-service 提供支付能力。

---

## 变更详情

### 1. 创建支付 SDK 封装

**新增文件**：
- `app/services/payment/wechat_payment.py` - 微信支付 SDK 封装
- `app/services/payment/alipay_payment.py` - 支付宝 SDK 封装
- `app/services/payment/__init__.py` - 模块导出

**功能**：
- ✅ 微信支付 Native 扫码支付
- ✅ 支付宝扫码支付
- ✅ 支付回调签名验证
- ✅ 完整的错误处理和日志记录

### 2. 实现主服务类

**新增文件**：
- `app/services/payment_service.py` - 支付服务主类

**功能**：
- ✅ 统一的支付接口（支持微信/支付宝）
- ✅ 自动路由到对应的支付 SDK
- ✅ 参数验证和异常处理
- ✅ 完整的类型提示

### 3. 更新配置

**修改文件**：
- `app/core/config.py` - 添加支付配置项
- `.env.example` - 添加配置示例

**新增配置**：
```python
# 微信支付
WECHAT_PAY_MCHID: str
WECHAT_PAY_PRIVATE_KEY: str
WECHAT_PAY_CERT_SERIAL_NO: str
WECHAT_PAY_APIV3_KEY: str
WECHAT_APPID: str
WECHAT_PAY_NOTIFY_URL: str

# 支付宝
ALIPAY_APPID: str
ALIPAY_PRIVATE_KEY: str
ALIPAY_PUBLIC_KEY: str
ALIPAY_NOTIFY_URL: str
```

### 4. 更新依赖

**修改文件**：
- `requirements.txt` - 添加支付 SDK

**新增依赖**：
```
wechatpayv3>=1.2.0
python-alipay-sdk>=3.0.0
```

---

## 技术实现

### 服务架构

```
recharge-service (充值业务服务)
    ↓ 调用
payment-service (支付 SDK 封装)
    ├── WechatPayment (微信支付)
    └── AlipayPayment (支付宝)
    ↓ 调用
第三方支付平台 API
```

### 核心特性

#### 1. 纯技术服务
- ❌ 无数据库依赖（不需要 AsyncSession）
- ❌ 无数据表（不管理 models/repositories）
- ❌ 无 API 路由（不对外暴露接口）
- ✅ 只封装第三方 SDK 调用

#### 2. 无状态设计
- 每次调用都是独立的
- 不存储任何数据
- 不依赖上下文

#### 3. 内部调用
- 只被 recharge-service 使用
- 不直接面向用户
- 不处理业务逻辑

### 使用示例

```python
from app.services.payment_service import PaymentService

# 初始化服务（无需 session）
payment_service = PaymentService()

# 创建支付订单
payment_params = await payment_service.create_payment(
    order_no="RCH20260127123456",
    amount=100.00,
    payment_method="wechat",
    description="充值 1000 积分"
)
# 返回: {'qrcode_url': 'weixin://...', 'expires_in': 1800}

# 验证支付回调
is_valid = await payment_service.verify_callback(
    payment_method="wechat",
    callback_data={'headers': {...}, 'body': {...}}
)
```

---

## 支付方式

### 微信支付
- **Native 扫码支付**：生成二维码，用户扫码支付
- **H5 支付**：移动端网页支付（待扩展）
- **小程序支付**：微信小程序内支付（待扩展）
- **JSAPI 支付**：微信公众号内支付（待扩展）

### 支付宝
- **扫码支付**：生成二维码，用户扫码支付
- **H5 支付**：移动端网页支付（待扩展）
- **APP 支付**：移动应用内支付（待扩展）

---

## 配置说明

### 微信支付配置

1. **获取商户号**：登录微信支付商户平台
2. **下载证书**：API 证书（包含私钥和序列号）
3. **设置 APIv3 密钥**：在商户平台设置
4. **配置回调 URL**：`https://api.jointo.ai/api/v1/recharge/callbacks/wechat`

### 支付宝配置

1. **创建应用**：登录支付宝开放平台
2. **生成密钥对**：使用支付宝密钥生成工具
3. **上传公钥**：将应用公钥上传到支付宝
4. **获取支付宝公钥**：从平台下载
5. **配置回调 URL**：`https://api.jointo.ai/api/v1/recharge/callbacks/alipay`

---

## 安全性

### 签名验证
- ✅ 微信支付：使用 APIv3 签名验证
- ✅ 支付宝：使用 RSA2 签名验证
- ✅ 所有回调必须验证签名

### 密钥管理
- ✅ 私钥存储在环境变量中
- ✅ 不在代码中硬编码
- ✅ 生产环境使用密钥管理服务

### 日志记录
- ✅ 记录所有支付操作
- ✅ 记录签名验证结果
- ✅ 不记录敏感信息（密钥、完整签名）

---

## 后续工作

### 1. 实现 recharge-service
- 管理 recharge_orders 表
- 管理 payment_callbacks 表
- 调用 payment-service 创建支付
- 处理支付回调
- 增加用户积分

### 2. 扩展支付方式
- 微信 H5 支付
- 微信小程序支付
- 支付宝 H5 支付
- 支付宝 APP 支付

### 3. 添加测试
- 单元测试（Mock SDK 调用）
- 集成测试（使用沙箱环境）
- 回调验证测试

### 4. 监控和告警
- 支付成功率监控
- 回调失败告警
- 异常支付告警

---

## 依赖关系

**被依赖**：
- recharge-service（充值服务）

**依赖**：
- wechatpayv3（微信支付 SDK）
- python-alipay-sdk（支付宝 SDK）
- loguru（日志）

---

## 测试建议

### 1. 沙箱测试
```bash
# 使用微信支付沙箱环境
WECHAT_PAY_MCHID=<沙箱商户号>
WECHAT_APPID=<沙箱 AppID>

# 使用支付宝沙箱环境
ALIPAY_APPID=<沙箱 AppID>
```

### 2. Mock 测试
```python
# 测试创建支付
payment_service = PaymentService()
result = await payment_service.create_payment(
    order_no="TEST123",
    amount=0.01,
    payment_method="wechat",
    description="测试订单"
)
assert 'qrcode_url' in result
```

### 3. 回调测试
```python
# 测试签名验证
is_valid = await payment_service.verify_callback(
    payment_method="wechat",
    callback_data=mock_callback_data
)
assert is_valid is True
```

---

## 参考文档

- [微信支付开发文档](https://pay.weixin.qq.com/wiki/doc/apiv3/index.shtml)
- [支付宝开放平台](https://opendocs.alipay.com/open/270/105898)
- [wechatpayv3 SDK](https://github.com/minibear2021/wechatpayv3)
- [python-alipay-sdk](https://github.com/fzlee/alipay)

---

**变更类型**：新功能  
**影响范围**：支付服务  
**向后兼容**：是（新增服务）  
**需要迁移**：否