jrh
/
docs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 Commits
1 Branch
0 Tags
2.6 MiB
 
Tree: 22b292bc15
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '22b292bc15'
${ noResults }
docs/v1.0/server/changelogs/2026-01-27-payment-service-...

6.0 KiB
Raw Blame History

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 - 添加配置示例

新增配置：

# 微信支付
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 使用
  • 不直接面向用户
  • 不处理业务逻辑

使用示例

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. 沙箱测试

# 使用微信支付沙箱环境
WECHAT_PAY_MCHID=<沙箱商户号>
WECHAT_APPID=<沙箱 AppID>

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

2. Mock 测试

# 测试创建支付
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. 回调测试

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

参考文档

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