# 支付集成详细设计

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

## 支付架构概览

### 系统架构
```mermaid
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. 预支付流程
```mermaid
sequenceDiagram
    participant 用户
    participant 小程序
    participant 后端
    participant 微信支付

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

#### 2. 支付回调流程
```mermaid
sequenceDiagram
    participant 微信支付
    participant 后端
    participant 数据库
    participant 通知服务

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

## 技术实现

### 支付服务接口设计

#### 1. 创建支付订单
```typescript
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. 支付结果查询
```typescript
interface QueryPaymentRequest {
  orderId: number;          // 订单ID
  paymentId?: string;       // 支付ID（可选）
}

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

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

### 支付状态管理

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

#### 状态流转规则
```typescript
// 支付状态流转规则
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. 支付状态不一致
- **原因**: 网络延迟、系统异常、第三方服务异常
- **处理**: 状态查询、数据修复、告警通知

### 错误码设计
```typescript
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集成测试
- 支付回调处理测试
- 支付状态同步测试

### 端到端测试
- 完整支付流程测试
- 异常场景测试
- 性能压力测试

## 部署和运维

### 环境配置
```bash
# 微信支付配置
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连通性检查
- 数据库连接检查

### 备份策略
- 支付记录定期备份
- 支付配置备份
- 证书文件备份