feat: 初始化项目结构并添加核心功能模块
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
This commit is contained in:
409
archive/handover/payment-api.md
Normal file
409
archive/handover/payment-api.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# 支付服务 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 提供了完整的支付处理功能，支持多种支付渠道，满足不同场景的支付需求。通过合理的缓存机制和异步处理，确保了支付处理的高效性和可靠性。
|
||||
Reference in New Issue
Block a user