mini-starter/docs/architecture/payment-integration-design.md

支付集成详细设计

版本信息

版本	日期	描述	作者
1.0	2025-10-15	创建支付集成详细设计文档	Winston

支付架构概览

系统架构

graph TB
    subgraph "前端层"
        A[微信小程序] --> B[支付SDK]
    end

    subgraph "后端服务层"
        C[订单服务] --> D[支付服务]
        D --> E[微信支付API]
        D --> F[支付回调处理]
    end

    subgraph "数据层"
        G[订单数据库] --> H[支付记录]
        I[Redis缓存] --> J[支付状态缓存]
    end

    subgraph "第三方服务"
        K[微信支付平台] --> L[支付结果通知]
    end

    A --> D
    D --> G
    D --> I
    F --> G
    L --> F

微信支付集成

支付方式选择

• JSAPI支付: 适用于微信小程序环境
• Native支付: 备用方案，支持H5环境
• App支付: 未来扩展支持

支付流程

1. 预支付流程

sequenceDiagram
    participant 用户
    participant 小程序
    participant 后端
    participant 微信支付

    用户->>小程序: 确认支付
    小程序->>后端: 请求支付参数
    后端->>后端: 验证订单状态
    后端->>微信支付: 统一下单API
    微信支付-->>后端: 返回预支付ID
    后端->>后端: 生成支付签名
    后端-->>小程序: 返回支付参数
    小程序->>微信支付: 调用支付接口
    微信支付-->>小程序: 支付结果

2. 支付回调流程

sequenceDiagram
    participant 微信支付
    participant 后端
    participant 数据库
    participant 通知服务

    微信支付->>后端: 支付结果通知
    后端->>后端: 验证签名和参数
    后端->>数据库: 更新订单支付状态
    后端->>通知服务: 发送支付成功通知
    后端-->>微信支付: 返回成功响应

技术实现

支付服务接口设计

1. 创建支付订单

interface CreatePaymentRequest {
  orderId: number;           // 订单ID
  totalAmount: number;       // 支付金额（分）
  description: string;       // 支付描述
  openid?: string;          // 用户OpenID
}

interface CreatePaymentResponse {
  paymentId: string;        // 支付ID
  timeStamp: string;        // 时间戳
  nonceStr: string;         // 随机字符串
  package: string;          // 预支付ID
  signType: string;         // 签名类型
  paySign: string;          // 签名
}

2. 支付结果查询

interface QueryPaymentRequest {
  orderId: number;          // 订单ID
  paymentId?: string;       // 支付ID（可选）
}

interface QueryPaymentResponse {
  status: PaymentStatus;    // 支付状态
  transactionId?: string;   // 微信支付订单号
  paidAt?: Date;           // 支付时间
  totalAmount: number;      // 支付金额
}

3. 支付回调处理

interface PaymentCallbackRequest {
  return_code: string;      // 返回状态码
  result_code: string;      // 业务结果
  out_trade_no: string;     // 商户订单号
  transaction_id: string;   // 微信支付订单号
  total_fee: number;        // 订单金额
  time_end: string;         // 支付完成时间
  // ... 其他微信支付参数
}

支付状态管理

支付状态枚举

export enum PaymentStatus {
  PENDING = '待支付',       // 订单创建，等待支付
  PROCESSING = '支付中',    // 支付进行中
  SUCCESS = '支付成功',     // 支付成功
  FAILED = '支付失败',      // 支付失败
  REFUNDED = '已退款',      // 已退款
  CLOSED = '已关闭'         // 支付关闭
}

状态流转规则

// 支付状态流转规则
const paymentStatusRules = {
  [PaymentStatus.PENDING]: [PaymentStatus.PROCESSING, PaymentStatus.CLOSED],
  [PaymentStatus.PROCESSING]: [PaymentStatus.SUCCESS, PaymentStatus.FAILED],
  [PaymentStatus.SUCCESS]: [PaymentStatus.REFUNDED],
  [PaymentStatus.FAILED]: [PaymentStatus.PENDING, PaymentStatus.CLOSED],
  [PaymentStatus.REFUNDED]: [],
  [PaymentStatus.CLOSED]: []
};

安全设计

数据安全

1. 敏感信息加密: 支付密钥、用户OpenID等敏感信息加密存储
2. 传输安全: 所有支付相关API使用HTTPS传输
3. 数据脱敏: 日志中脱敏处理敏感支付信息

接口安全

1. 签名验证: 所有支付请求和回调都进行签名验证
2. 防重放攻击: 使用时间戳和随机字符串防止重放攻击
3. 频率限制: 支付接口请求频率限制
4. IP白名单: 微信支付回调IP白名单验证

业务安全

1. 金额验证: 支付金额与订单金额一致性验证
2. 订单状态验证: 防止重复支付
3. 超时处理: 支付超时自动取消
4. 退款保护: 退款金额和状态验证

错误处理

常见错误场景

1. 支付创建失败

• 原因: 微信支付接口异常、参数错误、网络超时
• 处理: 重试机制、降级处理、用户提示

2. 支付回调异常

• 原因: 签名验证失败、重复回调、数据不一致
• 处理: 日志记录、人工干预、状态同步

3. 支付状态不一致

• 原因: 网络延迟、系统异常、第三方服务异常
• 处理: 状态查询、数据修复、告警通知

错误码设计

export enum PaymentErrorCode {
  // 系统错误
  SYSTEM_ERROR = 'PAYMENT_SYSTEM_ERROR',
  NETWORK_ERROR = 'PAYMENT_NETWORK_ERROR',

  // 业务错误
  ORDER_NOT_FOUND = 'PAYMENT_ORDER_NOT_FOUND',
  ORDER_ALREADY_PAID = 'PAYMENT_ORDER_ALREADY_PAID',
  AMOUNT_MISMATCH = 'PAYMENT_AMOUNT_MISMATCH',

  // 微信支付错误
  WECHAT_API_ERROR = 'PAYMENT_WECHAT_API_ERROR',
  WECHAT_SIGN_ERROR = 'PAYMENT_WECHAT_SIGN_ERROR',
  WECHAT_CALLBACK_ERROR = 'PAYMENT_WECHAT_CALLBACK_ERROR'
}

性能优化

缓存策略

1. 支付参数缓存: 预支付参数短期缓存
2. 支付状态缓存: 支付状态查询结果缓存
3. 配置缓存: 微信支付配置信息缓存

异步处理

1. 支付回调异步: 支付回调结果异步处理
2. 状态同步异步: 支付状态同步异步处理
3. 通知发送异步: 支付成功通知异步发送

数据库优化

1. 支付记录分表: 按时间分表存储支付记录
2. 索引优化: 支付相关查询字段添加索引
3. 归档策略: 历史支付数据定期归档

监控和告警

监控指标

1. 支付成功率: 支付成功订单比例
2. 支付响应时间: 支付接口平均响应时间
3. 回调成功率: 支付回调处理成功率
4. 异常率: 支付异常比例

告警规则

1. 支付失败率告警: 支付失败率超过阈值
2. 回调异常告警: 回调处理异常数量过多
3. 系统异常告警: 支付服务不可用
4. 数据不一致告警: 支付状态不一致

测试策略

单元测试

• 支付参数验证测试
• 支付状态流转测试
• 签名验证测试

集成测试

• 微信支付API集成测试
• 支付回调处理测试
• 支付状态同步测试

端到端测试

• 完整支付流程测试
• 异常场景测试
• 性能压力测试

部署和运维

环境配置

# 微信支付配置
WECHAT_APP_ID=your_app_id
WECHAT_MCH_ID=your_mch_id
WECHAT_API_KEY=your_api_key
WECHAT_CERT_PATH=/path/to/cert.pem
WECHAT_KEY_PATH=/path/to/key.pem

# 支付服务配置
PAYMENT_CALLBACK_URL=https://api.example.com/api/v1/payment/callback
PAYMENT_TIMEOUT=1800  # 30分钟

健康检查

• 支付服务可用性检查
• 微信支付API连通性检查
• 数据库连接检查

备份策略

• 支付记录定期备份
• 支付配置备份
• 证书文件备份