tyapi-server/docs/API调用记录和钱包交易记录功能说明.md

# API调用记录和钱包交易记录功能说明

## 概述

本文档描述了新增的API调用记录和钱包交易记录功能，包括后端API接口和前端页面。

## 功能特性

### 1. API调用记录功能

#### 后端API接口

**获取用户API调用记录**
- **接口地址**: `GET /api/v1/my/api-calls`
- **认证要求**: 需要JWT认证
- **功能**: 获取当前用户的API调用历史记录，支持分页和筛选

**请求参数**:
```json
{
  "page": 1,                    // 页码，默认1
  "page_size": 10,              // 每页数量，默认10
  "start_time": "2024-01-01 00:00:00",  // 开始时间（可选）
  "end_time": "2024-01-31 23:59:59",    // 结束时间（可选）
  "transaction_id": "1234567890",       // 交易ID（可选）
  "product_id": "product_123",          // 产品ID（可选）
  "status": "success"                   // 状态筛选：success/failed/pending（可选）
}
```

**响应格式**:
```json
{
  "code": 200,
  "message": "获取API调用记录成功",
  "data": {
    "items": [
      {
        "id": "api_call_123",
        "access_id": "access_456",
        "user_id": "user_789",
        "product_id": "product_123",
        "product_name": "身份证识别",
        "transaction_id": "1234567890",
        "client_ip": "192.168.1.1",
        "request_params": "{\"image\": \"base64...\"}",
        "response_data": "{\"result\": \"success\"}",
        "status": "success",
        "start_at": "2024-01-15 10:30:00",
        "end_at": "2024-01-15 10:30:05",
        "cost": "0.10",
        "error_type": null,
        "error_msg": null,
        "created_at": "2024-01-15 10:30:00",
        "updated_at": "2024-01-15 10:30:05"
      }
    ],
    "total": 100,
    "page": 1,
    "size": 10
  }
}
```

#### 前端页面

**页面路径**: `/api/usage`
**功能特性**:
- 显示API调用统计信息（总调用次数、成功率）
- 支持按时间范围、交易ID、产品名称、状态筛选
- 分页显示调用记录列表
- 查看调用详情（请求参数、响应数据、错误信息）
- 响应式设计，支持移动端访问

### 2. 钱包交易记录功能

#### 后端API接口

**获取用户钱包交易记录**
- **接口地址**: `GET /api/v1/finance/wallet/transactions`
- **认证要求**: 需要JWT认证
- **功能**: 获取当前用户的钱包消费记录，支持分页和筛选

**请求参数**:
```json
{
  "page": 1,                    // 页码，默认1
  "page_size": 10,              // 每页数量，默认10
  "start_time": "2024-01-01 00:00:00",  // 开始时间（可选）
  "end_time": "2024-01-31 23:59:59",    // 结束时间（可选）
  "api_call_id": "api_call_123",        // API调用ID（可选）
  "min_amount": "0.01",                 // 最小金额（可选）
  "max_amount": "100.00"                // 最大金额（可选）
}
```

**响应格式**:
```json
{
  "code": 200,
  "message": "获取钱包交易记录成功",
  "data": {
    "items": [
      {
        "id": "transaction_123",
        "user_id": "user_789",
        "api_call_id": "api_call_456",
        "amount": "0.10",
        "created_at": "2024-01-15 10:30:05",
        "updated_at": "2024-01-15 10:30:05"
      }
    ],
    "total": 50,
    "page": 1,
    "size": 10
  }
}
```

#### 前端页面

**页面路径**: `/finance/transactions`
**功能特性**:
- 显示消费统计信息（总消费次数、总消费金额）
- 支持按时间范围、API调用ID、金额范围筛选
- 分页显示交易记录列表
- 查看交易详情
- 响应式设计，支持移动端访问

## 技术实现

### 后端架构

#### 1. 数据层
- **实体**: `ApiCall`、`WalletTransaction`
- **仓储**: `ApiCallRepository`、`WalletTransactionRepository`
- **GORM实现**: `GormApiCallRepository`、`GormWalletTransactionRepository`

#### 2. 领域层
- **聚合服务**: `ApiCallAggregateService`、`WalletAggregateService`
- **业务逻辑**: 分页查询、条件筛选、数据统计

#### 3. 应用层
- **应用服务**: `ApiApplicationService`、`FinanceApplicationService`
- **DTO转换**: 实体到响应DTO的映射
- **业务编排**: 调用领域服务，处理应用级逻辑

#### 4. 接口层
- **HTTP处理器**: `ApiHandler`、`FinanceHandler`
- **路由配置**: API路由和财务路由
- **中间件**: JWT认证、请求验证、响应构建

### 前端架构

#### 1. 页面组件
- **API调用记录**: `Usage.vue`
- **钱包交易记录**: `Transactions.vue`
- **通用组件**: `ListPageLayout`、`FilterSection`、`FilterItem`

#### 2. API接口
- **API模块**: `apiApi.getUserApiCalls()`
- **财务模块**: `financeApi.getUserWalletTransactions()`

#### 3. 功能特性
- **筛选功能**: 时间范围、关键词搜索、状态筛选
- **分页功能**: 支持自定义每页数量
- **详情弹窗**: 查看完整记录信息
- **响应式设计**: 适配不同屏幕尺寸

## 数据库设计

### API调用记录表 (api_calls)
```sql
CREATE TABLE api_calls (
    id VARCHAR(64) PRIMARY KEY,
    access_id VARCHAR(64) NOT NULL,
    user_id VARCHAR(36),
    product_id VARCHAR(64),
    transaction_id VARCHAR(64) NOT NULL,
    client_ip VARCHAR(64) NOT NULL,
    request_params TEXT,
    response_data TEXT,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    start_at TIMESTAMP NOT NULL,
    end_at TIMESTAMP,
    cost DECIMAL(20,8),
    error_type VARCHAR(32),
    error_msg VARCHAR(256),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_user_id (user_id),
    INDEX idx_transaction_id (transaction_id),
    INDEX idx_status (status),
    INDEX idx_created_at (created_at)
);
```

### 钱包交易记录表 (wallet_transactions)
```sql
CREATE TABLE wallet_transactions (
    id VARCHAR(36) PRIMARY KEY,
    user_id VARCHAR(36) NOT NULL,
    api_call_id VARCHAR(64) NOT NULL,
    amount DECIMAL(20,8) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP NULL,
    INDEX idx_user_id (user_id),
    INDEX idx_api_call_id (api_call_id),
    INDEX idx_created_at (created_at)
);
```

## 使用示例

### 1. 获取API调用记录

**请求示例**:
```bash
curl -X GET "http://localhost:8080/api/v1/my/api-calls?page=1&page_size=10&status=success" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "获取API调用记录成功",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "size": 10
  }
}
```

### 2. 获取钱包交易记录

**请求示例**:
```bash
curl -X GET "http://localhost:8080/api/v1/finance/wallet/transactions?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "获取钱包交易记录成功",
  "data": {
    "items": [...],
    "total": 50,
    "page": 1,
    "size": 10
  }
}
```

## 错误处理

### 常见错误码
- `400`: 请求参数错误
- `401`: 未认证或认证失败
- `500`: 服务器内部错误

### 错误响应格式
```json
{
  "code": 400,
  "message": "请求参数错误",
  "data": null
}
```

## 性能优化

### 1. 数据库优化
- 合理设置索引
- 使用分页查询避免大量数据查询
- 缓存热点数据

### 2. 前端优化
- 防抖搜索，避免频繁请求
- 分页加载，减少数据传输
- 响应式设计，提升用户体验

## 安全考虑

### 1. 认证授权
- 所有接口都需要JWT认证
- 用户只能查看自己的记录
- 接口权限验证

### 2. 数据安全
- 敏感信息脱敏处理
- SQL注入防护
- XSS攻击防护

## 扩展功能

### 1. 统计报表
- 调用量趋势分析
- 费用统计报表
- 成功率分析

### 2. 导出功能
- 支持Excel导出
- 支持PDF报表
- 自定义导出格式

### 3. 实时监控
- WebSocket实时推送
- 调用状态实时更新
- 异常告警通知

## 总结

API调用记录和钱包交易记录功能为用户提供了完整的API使用追踪和费用管理能力，通过合理的架构设计和功能实现，确保了系统的可扩展性和可维护性。