v0.1
This commit is contained in:
319
docs/API调用记录和钱包交易记录功能说明.md
Normal file
319
docs/API调用记录和钱包交易记录功能说明.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 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使用追踪和费用管理能力，通过合理的架构设计和功能实现，确保了系统的可扩展性和可维护性。
|
||||
Reference in New Issue
Block a user