team/tyapi-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
267ff92998dc57923739138ef7bb022338223b53
tyapi-server/docs/API调用记录和钱包交易记录功能说明.md
liangzai 357639462a v0.1
2025-07-28 01:46:39 +08:00

8.0 KiB
Raw Blame History

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

概述

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

功能特性

1. API调用记录功能

后端API接口

获取用户API调用记录

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

请求参数:

{
  "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（可选）
}

响应格式:

{
  "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认证
  • 功能: 获取当前用户的钱包消费记录，支持分页和筛选

请求参数:

{
  "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"                // 最大金额（可选）
}

响应格式:

{
  "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)

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)

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调用记录

请求示例:

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

响应示例:

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

2. 获取钱包交易记录

请求示例:

curl -X GET "http://localhost:8080/api/v1/finance/wallet/transactions?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

响应示例:

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

错误处理

常见错误码

  • 400: 请求参数错误
  • 401: 未认证或认证失败
  • 500: 服务器内部错误

错误响应格式

{
  "code": 400,
  "message": "请求参数错误",
  "data": null
}

性能优化

1. 数据库优化

  • 合理设置索引
  • 使用分页查询避免大量数据查询
  • 缓存热点数据

2. 前端优化

  • 防抖搜索，避免频繁请求
  • 分页加载，减少数据传输
  • 响应式设计，提升用户体验

安全考虑

1. 认证授权

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

2. 数据安全

  • 敏感信息脱敏处理
  • SQL注入防护
  • XSS攻击防护

扩展功能

1. 统计报表

  • 调用量趋势分析
  • 费用统计报表
  • 成功率分析

2. 导出功能

  • 支持Excel导出
  • 支持PDF报表
  • 自定义导出格式

3. 实时监控

  • WebSocket实时推送
  • 调用状态实时更新
  • 异常告警通知

总结

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