3.4 KiB

Raw Permalink Blame History

变更日志: 支付服务规范化重构

日期: 2026-01-26
版本: v2.0
类型: 重构

概述

将 payment-service.md 文档重构为符合 Jointo 技术栈规范的完整实现，包括 Repository 模式、Schema 定义、数据库设计和 API 路由。

变更内容

新增内容

数据库设计
- 添加 Payment 模型定义
- 添加 PaymentMethod 和 PaymentStatus 枚举
- 使用 UUID v7 作为主键
- 金额使用整数（分）存储
Schema 定义
- PaymentCreate: 创建支付订单请求
- PaymentResponse: 支付订单响应
- PaymentCallbackData: 支付回调数据
Repository 层
- PaymentRepository: 数据访问层
- 实现 CRUD 操作
- 添加订单号查询、用户订单列表等方法
Service 层重构
- 遵循依赖注入模式（接收 AsyncSession）
- 使用 Repository 处理数据访问
- 添加完整的业务逻辑和验证
- 集成 loguru 日志记录
API 路由
- 添加完整的 FastAPI 路由示例
- 实现统一响应格式
- 添加认证和授权
数据库迁移
- 提供 008_payment_tables.py 迁移脚本
- 创建 payments 表和索引

架构改进

改进前:

PaymentService (直接实例化第三方支付类)

改进后:

API 路由层 → Service 层 → Repository 层 → Model 层
              ↓
         第三方支付集成

规范符合性

✅ 使用 Repository 模式分离数据访问
✅ 使用 Pydantic Schema 进行类型验证
✅ 使用 SQLModel 定义数据库模型
✅ 异步数据库操作（asyncpg）
✅ 依赖注入模式
✅ 统一错误处理
✅ loguru 日志记录
✅ 统一 API 响应格式
✅ 枚举使用 IntEnum + SMALLINT
✅ UUID v7 主键

技术细节

数据库表结构

CREATE TABLE payments (
    id UUID PRIMARY KEY,
    order_no VARCHAR(64) UNIQUE NOT NULL,
    user_id UUID NOT NULL,
    amount INTEGER NOT NULL,
    payment_method SMALLINT NOT NULL,
    status SMALLINT NOT NULL DEFAULT 1,
    description VARCHAR(255) NOT NULL,
    transaction_id VARCHAR(64),
    paid_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

索引设计

idx_payments_order_no: 订单号查询
idx_payments_user_id: 用户订单列表
idx_payments_status: 状态筛选
idx_payments_created_at: 时间排序

API 端点

POST /api/v1/payments: 创建支付订单
GET /api/v1/payments/{id}: 获取支付订单详情
GET /api/v1/payments: 获取用户支付订单列表
POST /api/v1/payments/callback/wechat: 微信支付回调
POST /api/v1/payments/callback/alipay: 支付宝支付回调

部署说明

运行数据库迁移：

python run_migration.py 008_payment_tables

配置环境变量（见文档配置说明部分）
重启服务

后续优化建议

实现支付订单超时自动取消
添加支付重试机制
实现退款功能
添加支付统计和报表
集成更多支付方式（如银联、PayPal）

变更人: Kiro AI
审核状态: 待审核

3.4 KiB Raw Permalink Blame History