# 支付服务 API 文档

## 1. 概述

支付服务（PaymentService）提供了全面的支付处理功能，支持多种支付渠道（支付宝、微信支付、银联等），包括支付创建、回调处理、退款处理、对账等核心功能。

## 2. 核心功能

- **支付创建**：支持多种支付渠道的支付请求创建
- **支付回调**：处理支付渠道的异步回调通知
- **退款处理**：支持发起和处理退款请求
- **支付状态查询**：查询支付状态
- **支付列表**：获取支付记录列表，支持分页和过滤
- **支付统计**：获取支付相关的统计数据
- **对账功能**：支持单日对账和批量对账
- **对账报表**：生成对账报表
- **批量处理**：支持批量处理支付记录

## 3. API 端点

### 3.1 创建支付

**请求路径**：`POST /api/payments`

**请求参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户ID |
| orderId | string | 是 | 订单ID |
| amount | number | 是 | 支付金额 |
| currency | string | 是 | 货币类型，如 USD、CNY |
| paymentMethod | string | 是 | 支付方式：ALIPAY、WECHAT、UNIONPAY、STRIPE |
| returnUrl | string | 否 | 支付完成后返回地址 |
| notifyUrl | string | 否 | 支付回调通知地址 |
| metadata | object | 否 | 附加信息，JSON格式 |

**响应格式**：

```json
{
  "paymentId": "PAY-1234567890-12345",
  "redirectUrl": "https://openapi.alipay.com/gateway.do?orderId=PAY-1234567890-12345",
  "qrCodeUrl": "https://wx.tenpay.com/qrcode?orderId=PAY-1234567890-12345",
  "status": "PENDING"
}
```

### 3.2 处理支付回调

**请求路径**：`POST /api/payments/callback`

**请求参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| paymentId | string | 是 | 支付ID |
| orderId | string | 是 | 订单ID |
| status | string | 是 | 支付状态：SUCCESS、FAILED |
| transactionId | string | 是 | 交易ID |
| amount | number | 是 | 支付金额 |
| currency | string | 是 | 货币类型 |
| timestamp | string | 是 | 回调时间戳 |
| signature | string | 是 | 签名，用于验证回调真实性 |

**响应格式**：

```json
{
  "success": true
}
```

### 3.3 发起退款

**请求路径**：`POST /api/payments/refund`

**请求参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户ID |
| paymentId | string | 是 | 支付ID |
| orderId | string | 是 | 订单ID |
| amount | number | 是 | 退款金额 |
| reason | string | 是 | 退款原因 |

**响应格式**：

```json
{
  "refundId": "REFUND-1234567890-12345"
}
```

### 3.4 查询支付状态

**请求路径**：`GET /api/payments/{paymentId}/status`

**响应格式**：

```json
{
  "status": "SUCCESS"
}
```

### 3.5 获取支付列表

**请求路径**：`GET /api/payments`

**查询参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户ID |
| page | number | 否 | 页码，默认1 |
| pageSize | number | 否 | 每页数量，默认20 |
| status | string | 否 | 支付状态过滤 |
| paymentMethod | string | 否 | 支付方式过滤 |
| startDate | string | 否 | 开始日期，格式：YYYY-MM-DD |
| endDate | string | 否 | 结束日期，格式：YYYY-MM-DD |

**响应格式**：

```json
{
  "payments": [
    {
      "id": "PAY-1234567890-12345",
      "tenant_id": "tenant-1",
      "order_id": "order-1",
      "amount": 100,
      "currency": "USD",
      "payment_method": "ALIPAY",
      "status": "SUCCESS",
      "transaction_id": "trans-123456",
      "created_at": "2026-03-17T10:00:00Z",
      "updated_at": "2026-03-17T10:05:00Z"
    }
  ],
  "total": 100
}
```

### 3.6 获取支付统计

**请求路径**：`GET /api/payments/stats`

**查询参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户ID |
| startDate | string | 是 | 开始日期，格式：YYYY-MM-DD |
| endDate | string | 是 | 结束日期，格式：YYYY-MM-DD |

**响应格式**：

```json
{
  "totalAmount": 10000,
  "completedAmount": 8000,
  "failedAmount": 1000,
  "refundedAmount": 500,
  "statusCounts": [
    {
      "status": "SUCCESS",
      "count": 80,
      "amount": 8000
    },
    {
      "status": "FAILED",
      "count": 10,
      "amount": 1000
    }
  ],
  "paymentMethodStats": [
    {
      "paymentMethod": "ALIPAY",
      "count": 50,
      "amount": 5000
    },
    {
      "paymentMethod": "WECHAT",
      "count": 30,
      "amount": 3000
    }
  ]
}
```

### 3.7 对账

**请求路径**：`GET /api/payments/reconcile`

**查询参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户ID |
| date | string | 是 | 对账日期，格式：YYYY-MM-DD |
| paymentMethod | string | 否 | 支付方式过滤 |

**响应格式**：

```json
{
  "date": "2026-03-17",
  "paymentMethod": "ALIPAY",
  "payments": {
    "total": 10,
    "successful": 8,
    "pending": 1,
    "failed": 1,
    "totalAmount": 1000
  },
  "refunds": {
    "total": 2,
    "successful": 2,
    "totalAmount": 200
  },
  "netAmount": 800
}
```

### 3.8 批量处理支付

**请求路径**：`POST /api/payments/batch`

**请求参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户ID |
| paymentIds | array | 是 | 支付ID数组 |
| action | string | 是 | 操作类型：SYNC_STATUS、CANCEL |

**响应格式**：

```json
{
  "success": 5,
  "failed": 0
}
```

### 3.9 生成对账报表

**请求路径**：`GET /api/payments/reconciliation-report`

**查询参数**：

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户ID |
| startDate | string | 是 | 开始日期，格式：YYYY-MM-DD |
| endDate | string | 是 | 结束日期，格式：YYYY-MM-DD |

**响应格式**：

```json
{
  "tenantId": "tenant-1",
  "period": {
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  },
  "summary": {
    "totalPayments": 300,
    "successfulPayments": 250,
    "totalPaymentAmount": 30000,
    "totalRefunds": 50,
    "successfulRefunds": 45,
    "totalRefundAmount": 5000,
    "netAmount": 25000
  },
  "dailyResults": [
    {
      "date": "2026-03-01",
      "payments": {
        "total": 10,
        "successful": 8,
        "pending": 1,
        "failed": 1,
        "totalAmount": 1000
      },
      "refunds": {
        "total": 2,
        "successful": 2,
        "totalAmount": 200
      },
      "netAmount": 800
    }
  ],
  "generatedAt": "2026-03-31T23:59:59Z"
}
```

## 4. 数据模型

### 4.1 支付记录 (cf_payments)

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 支付ID，格式：PAY-时间戳-随机数 |
| tenant_id | string | 租户ID |
| order_id | string | 订单ID |
| amount | decimal(10,2) | 支付金额 |
| currency | string | 货币类型 |
| payment_method | string | 支付方式 |
| status | string | 支付状态：PENDING、SUCCESS、FAILED |
| transaction_id | string | 交易ID |
| redirect_url | string | 支付跳转URL |
| qr_code_url | string | 二维码URL |
| metadata | text | 附加信息，JSON格式 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### 4.2 退款记录 (cf_refunds)

| 字段名 | 类型 | 描述 |
|-------|------|------|
| id | string | 退款ID，格式：REFUND-时间戳-随机数 |
| tenant_id | string | 租户ID |
| payment_id | string | 支付ID |
| order_id | string | 订单ID |
| amount | decimal(10,2) | 退款金额 |
| currency | string | 货币类型 |
| status | string | 退款状态：PENDING、SUCCESS、FAILED |
| reason | string | 退款原因 |
| transaction_id | string | 退款交易ID |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

## 5. 错误处理

| 错误码 | 描述 |
|-------|------|
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 404 | 支付记录不存在 |
| 500 | 服务器内部错误 |

## 6. 性能指标

- **支付创建响应时间**：< 1秒
- **支付状态查询响应时间**：< 500ms
- **支付列表查询响应时间**：< 1秒
- **支付统计响应时间**：< 2秒
- **对账响应时间**：< 3秒

## 7. 安全注意事项

- 支付回调必须验证签名，确保回调的真实性
- 敏感信息（如支付凭证）不应存储在数据库中
- 所有API请求必须进行身份验证和权限检查
- 支付相关操作应记录详细的审计日志

## 8. 集成示例

### 8.1 创建支付示例

```javascript
// 前端调用示例
async function createPayment() {
  const response = await fetch('/api/payments', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN'
    },
    body: JSON.stringify({
      tenantId: 'tenant-1',
      orderId: 'order-123',
      amount: 100,
      currency: 'USD',
      paymentMethod: 'ALIPAY',
      returnUrl: 'https://example.com/return',
      notifyUrl: 'https://example.com/notify'
    })
  });
  
  const result = await response.json();
  if (result.paymentId) {
    // 跳转到支付页面或显示二维码
    window.location.href = result.redirectUrl;
  }
}
```

### 8.2 处理支付回调示例

```javascript
// 后端处理回调示例
app.post('/api/payments/callback', async (req, res) => {
  try {
    const callbackData = req.body;
    const success = await PaymentService.handleCallback(callbackData);
    res.json({ success });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});
```

## 9. 总结

支付服务 API 提供了完整的支付处理功能，支持多种支付渠道，满足不同场景的支付需求。通过合理的缓存机制和异步处理，确保了支付处理的高效性和可靠性。