algorithm/docs/api-reference.md

# 智能算法展示平台 API 文档

## 概述

智能算法展示平台提供了一套完整的API，用于管理算法、调用算法以及获取结果。API遵循RESTful设计原则，返回JSON格式的数据。

### 基础URL

```
http://localhost:8000/api/v1
```

### 认证

大多数API端点需要认证。认证通过在请求头中添加 `Authorization` 字段实现：

```
Authorization: Bearer <your-token>
```

## 算法管理API

### 获取算法列表

**GET** `/algorithms`

获取所有可用算法的列表。

#### 参数
- `type` (可选): 算法类型 (computer_vision, nlp, ml等)
- `skip` (可选): 跳过的记录数，默认为0
- `limit` (可选): 返回的最大记录数，默认为100

#### 响应
```json
{
  "algorithms": [
    {
      "id": "alg-001",
      "name": "图像分类算法",
      "description": "基于深度学习的图像分类算法",
      "type": "computer_vision",
      "status": "active",
      "versions": [],
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "total": 1
}
```

### 获取算法详情

**GET** `/algorithms/{algorithm_id}`

获取特定算法的详细信息。

#### 参数
- `algorithm_id`: 算法ID

#### 响应
```json
{
  "id": "alg-001",
  "name": "图像分类算法",
  "description": "基于深度学习的图像分类算法",
  "type": "computer_vision",
  "status": "active",
  "versions": [
    {
      "id": "ver-001",
      "algorithm_id": "alg-001",
      "version": "v1.0",
      "url": "http://algorithm-service:8000/classify",
      "params": {
        "confidence_threshold": {
          "type": "float",
          "default": 0.5,
          "min": 0.0,
          "max": 1.0
        }
      },
      "input_schema": {},
      "output_schema": {},
      "is_default": true,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}
```

### 创建算法

**POST** `/algorithms`

创建新算法（需要管理员权限）。

#### 请求体
```json
{
  "name": "新算法",
  "description": "算法描述",
  "type": "ml",
  "status": "active"
}
```

#### 响应
```json
{
  "id": "alg-002",
  "name": "新算法",
  "description": "算法描述",
  "type": "ml",
  "status": "active",
  "versions": [],
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}
```

## 算法调用API

### 调用算法

**POST** `/algorithms/call`

调用指定算法。

#### 请求体
```json
{
  "algorithm_id": "alg-001",
  "version_id": "ver-001",
  "input_data": {
    "image_url": "https://example.com/image.jpg"
  },
  "params": {
    "confidence_threshold": 0.7
  }
}
```

#### 响应
```json
{
  "id": "call-001",
  "user_id": "user-001",
  "algorithm_id": "alg-001",
  "version_id": "ver-001",
  "input_data": {
    "image_url": "https://example.com/image.jpg"
  },
  "params": {
    "confidence_threshold": 0.7
  },
  "output_data": {
    "predictions": [
      {
        "class": "cat",
        "confidence": 0.95
      }
    ]
  },
  "status": "success",
  "response_time": 1.2,
  "error_message": null,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}
```

### 获取调用结果

**GET** `/algorithms/calls/{call_id}`

获取特定调用的结果。

#### 参数
- `call_id`: 调用ID

#### 响应
```json
{
  "id": "call-001",
  "user_id": "user-001",
  "algorithm_id": "alg-001",
  "version_id": "ver-001",
  "input_data": {
    "image_url": "https://example.com/image.jpg"
  },
  "params": {
    "confidence_threshold": 0.7
  },
  "output_data": {
    "predictions": [
      {
        "class": "cat",
        "confidence": 0.95
      }
    ]
  },
  "status": "success",
  "response_time": 1.2,
  "error_message": null,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}
```

## 用户管理API

### 用户登录

**POST** `/users/login`

用户登录并获取访问令牌。

#### 请求体
```json
{
  "username": "testuser",
  "password": "password123"
}
```

#### 响应
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

## 历史记录API

### 获取调用历史

**GET** `/history/user-calls`

获取用户的调用历史。

#### 参数
- `algorithm_id` (可选): 算法ID
- `status` (可选): 调用状态
- `start_date` (可选): 开始日期
- `end_date` (可选): 结束日期
- `skip` (可选): 跳过的记录数
- `limit` (可选): 返回的最大记录数

#### 响应
```json
{
  "history": [
    {
      "id": "call-001",
      "user_id": "user-001",
      "algorithm_id": "alg-001",
      "version_id": "ver-001",
      "input_data": {},
      "params": {},
      "output_data": {},
      "status": "success",
      "response_time": 1.2,
      "error_message": null,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "count": 1,
  "skip": 0,
  "limit": 100
}
```

### 获取调用统计

**GET** `/history/statistics`

获取调用统计信息。

#### 参数
- `user_id` (可选): 用户ID
- `algorithm_id` (可选): 算法ID

#### 响应
```json
{
  "total_calls": 156,
  "status_counts": {
    "success": 145,
    "failed": 11
  },
  "success_rate": 92.3,
  "avg_response_time": 1.45,
  "today_calls": 12
}
```

## 监控API

### 获取系统健康状况

**GET** `/monitoring/health`

获取系统健康状况。

#### 响应
```json
{
  "status": "healthy",
  "timestamp": "2023-01-01T00:00:00Z",
  "system_metrics": {
    "cpu_percent": 25.5,
    "memory_percent": 45.2,
    "disk_percent": 60.1
  }
}
```

### 获取算法性能指标

**GET** `/monitoring/performance/algorithm/{algorithm_id}`

获取特定算法的性能指标。

#### 参数
- `algorithm_id`: 算法ID
- `days`: 统计天数（默认为7）

#### 响应
```json
{
  "algorithm_id": "alg-001",
  "period_days": 7,
  "total_calls": 50,
  "success_calls": 48,
  "failed_calls": 2,
  "success_rate": 96.0,
  "average_response_time": 1.234,
  "status_distribution": {
    "success": 48,
    "failed": 2
  },
  "timestamp": "2023-01-01T00:00:00Z"
}
```

## 权限管理API

### 检查权限

**POST** `/permissions/check`

检查用户对特定算法的权限。

#### 请求体
```json
{
  "algorithm_id": "alg-001",
  "permission_type": "execute"
}
```

#### 响应
```json
{
  "has_permission": true,
  "user_id": "user-001",
  "algorithm_id": "alg-001",
  "permission_type": "execute"
}
```

## OpenAI集成API

### 生成仿真数据

**POST** `/openai/generate-data`

使用OpenAI生成仿真输入数据。

#### 请求体
```json
{
  "prompt": "一张包含猫和狗的照片",
  "data_type": "image"
}
```

#### 响应
```json
{
  "data": "生成的仿真数据",
  "type": "image"
}
```

## API网关API

### 通过网关调用算法

**POST** `/gateway/call`

通过API网关调用算法，提供统一的访问接口和安全控制。

#### 请求体
```json
{
  "algorithm_id": "alg-001",
  "version_id": "ver-001",
  "input_data": {
    "image_url": "https://example.com/image.jpg"
  },
  "params": {
    "confidence_threshold": 0.7
  }
}
```

#### 响应
```json
{
  "id": "call-001",
  "user_id": "user-001",
  "algorithm_id": "alg-001",
  "version_id": "ver-001",
  "input_data": {
    "image_url": "https://example.com/image.jpg"
  },
  "params": {
    "confidence_threshold": 0.7
  },
  "output_data": {
    "predictions": [
      {
        "class": "cat",
        "confidence": 0.95
      }
    ]
  },
  "status": "success",
  "response_time": 1.2,
  "error_message": null,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}
```

### 获取网关统计信息

**GET** `/gateway/stats`

获取API网关的调用统计信息。

#### 响应
```json
{
  "total_requests": 1250,
  "successful_requests": 1200,
  "failed_requests": 50,
  "blocked_requests": 10,
  "rate_limited_requests": 40,
  "last_updated": "2023-01-01T00:00:00Z"
}
```

## 算法仓库管理API

### 获取算法仓库列表

**GET** `/repositories`

获取所有算法仓库的列表。

#### 响应
```json
{
  "success": true,
  "repositories": [
    {
      "id": "repo-001",
      "name": "图像分类算法仓库",
      "description": "图像分类算法的代码仓库",
      "type": "code",
      "repo_url": "https://gitea.example.com/owner/repo.git",
      "branch": "main",
      "local_path": "",
      "algorithm_id": null,
      "status": "active",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ]
}
```

### 获取单个算法仓库详情

**GET** `/repositories/{repo_id}`

获取特定算法仓库的详细信息。

#### 参数
- `repo_id`: 仓库ID

#### 响应
```json
{
  "success": true,
  "repository": {
    "id": "repo-001",
    "name": "图像分类算法仓库",
    "description": "图像分类算法的代码仓库",
    "type": "code",
    "repo_url": "https://gitea.example.com/owner/repo.git",
    "branch": "main",
    "local_path": "",
    "algorithm_id": null,
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 添加算法仓库

**POST** `/repositories`

添加新的算法仓库。

#### 请求体
```json
{
  "name": "新算法仓库",
  "description": "新算法的代码仓库",
  "type": "code",
  "repo_url": "https://gitea.example.com/owner/repo.git",
  "branch": "main",
  "local_path": ""
}
```

#### 响应
```json
{
  "success": true,
  "message": "Repository created successfully",
  "repository": {
    "id": "repo-002",
    "name": "新算法仓库",
    "description": "新算法的代码仓库",
    "type": "code",
    "repo_url": "https://gitea.example.com/owner/repo.git",
    "branch": "main",
    "local_path": "",
    "algorithm_id": null,
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 更新算法仓库

**PUT** `/repositories/{repo_id}`

更新特定算法仓库的信息。

#### 参数
- `repo_id`: 仓库ID

#### 请求体
```json
{
  "name": "更新后的算法仓库",
  "description": "更新后的算法仓库描述",
  "type": "code"
}
```

#### 响应
```json
{
  "success": true,
  "message": "Repository updated successfully",
  "repository": {
    "id": "repo-001",
    "name": "更新后的算法仓库",
    "description": "更新后的算法仓库描述",
    "type": "code",
    "repo_url": "https://gitea.example.com/owner/repo.git",
    "branch": "main",
    "local_path": "",
    "algorithm_id": null,
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 删除算法仓库

**DELETE** `/repositories/{repo_id}`

删除特定的算法仓库。

#### 参数
- `repo_id`: 仓库ID

#### 响应
```json
{
  "success": true,
  "message": "Repository deleted successfully",
  "gitea_deleted": true
}
```

## Gitea集成API

### 获取Gitea配置

**GET** `/gitea/config`

获取Gitea配置信息。

#### 响应
```json
{
  "server_url": "https://gitea.example.com",
  "access_token": "your-access-token",
  "default_owner": "owner",
  "repo_prefix": "alg-"
}
```

### 设置Gitea配置

**POST** `/gitea/config`

设置Gitea配置信息。

#### 请求体
```json
{
  "server_url": "https://gitea.example.com",
  "access_token": "your-access-token",
  "default_owner": "owner",
  "repo_prefix": "alg-"
}
```

#### 响应
```json
{
  "success": true,
  "message": "Gitea config saved successfully"
}
```

### 创建Gitea仓库

**POST** `/gitea/repos/create`

在Gitea上创建仓库。

#### 请求体
```json
{
  "algorithm_id": "alg-001",
  "algorithm_name": "图像分类算法",
  "description": "图像分类算法的代码仓库"
}
```

#### 响应
```json
{
  "id": 1,
  "name": "alg-001",
  "full_name": "owner/alg-001",
  "description": "图像分类算法的代码仓库",
  "private": false,
  "html_url": "https://gitea.example.com/owner/alg-001"
}
```

### 更新Gitea仓库信息

**PATCH** `/gitea/repos/update`

更新Gitea仓库信息。

#### 请求体
```json
{
  "algorithm_id": "alg-001",
  "description": "更新后的仓库描述",
  "private": false
}
```

#### 响应
```json
{
  "success": true,
  "message": "Repository updated successfully"
}
```