jlintw/taravel

Fork 0

Jethro Lin (aider) c5dbe05383 aider create cursor fix 2

2024-11-13 16:26:27 +08:00

8.9 KiB

Raw Blame History

項目 API 文件

概述

本 API 旨在促進前端與後端系統之間的互動，包括用戶註冊、通過 AI 提供者處理提示以及管理用戶和 API 提供者的管理功能。後端基於 Laravel 構建，確保結構化和安全的框架。

認證

方法: JSON Web Tokens (JWT)
流程:
- 用戶通過登錄進行認證，獲取 JWT。
- 管理員單獨認證，也會獲取具有高級權限的 JWT。
使用方式:
- 在所有受保護的端點中包含 JWT 在 Authorization 標頭中。
- 範例: Authorization: Bearer <token>

API 群組

前端 API

設計用於終端用戶的互動，包括用戶註冊、認證和向 AI 提供者發送提示。

管理員 API

設計用於管理任務，如管理用戶帳戶和配置 AI API 提供者。

端點

前端 API 端點

1. 用戶註冊

端點: /api/frontend/register
方法: POST
描述: 註冊一個新用戶帳戶，初始狀態為「未激活」。
參數:
- 請求體:
  - username (字串, 必填)
  - email (字串, 必填, 有效的電子郵件格式)
  - password (字串, 必填, 最少 8 個字符)

請求範例:

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "SecurePass123"
}

回應:

201 已創建:

{
  "message": "用戶註冊成功。等待激活。",
  "user_id": "12345"
}

400 錯誤的請求:

{
  "error": "驗證失敗。",
  "details": {
    "email": "電子郵件地址格式不正確。"
  }
}

2. 發送提示

端點: /api/frontend/send-prompt
方法: POST
描述: 通過中間件向選定的 AI 提供者發送用戶提示，並返回 AI 的回應。
認證: 必需（用戶 JWT）
參數:
- 請求體:
  - prompt (字串, 必填)

請求範例:

{
  "prompt": "解釋相對論理論。"
}

回應:

200 成功:

{
  "response": "相對論理論包括阿爾伯特·愛因斯坦的兩個相互關聯的理論：狹義相對論和廣義相對論..."
}

400 錯誤的請求:

{
  "error": "提示內容不能為空。"
}

500 內部伺服器錯誤:

{
  "error": "處理提示失敗。請稍後再試。"
}

管理員 API 端點

1. 用戶管理

a. 列出用戶

端點: /api/admin/users
方法: GET
描述: 獲取所有註冊用戶的列表。
認證: 必需（管理員 JWT）
參數:
- 查詢參數:
  - status (字串, 選填, 根據用戶狀態篩選：active/inactive)
  - page (整數, 選填, 分頁)
  - per_page (整數, 選填, 每頁項目數)

請求範例:

GET /api/admin/users?status=active&page=1&per_page=20

回應:

200 成功:

{
  "current_page": 1,
  "per_page": 20,
  "total": 100,
  "data": [
    {
      "user_id": "12345",
      "username": "john_doe",
      "email": "john@example.com",
      "status": "active",
      "registered_at": "2024-04-01T12:34:56Z"
    }
    // 更多用戶...
  ]
}

b. 啟用用戶

端點: /api/admin/users/{user_id}/activate
方法: POST
描述: 啟用用戶帳戶。
認證: 必需（管理員 JWT）
參數:
- 路徑參數:
  - user_id (字串, 必填)
請求範例:
```
POST /api/admin/users/12345/activate
```

回應:

200 成功:

{
  "message": "用戶帳戶已成功啟用。"
}

404 未找到:
```
{
  "error": "未找到用戶。"
}
```

c. 停用用戶

端點: /api/admin/users/{user_id}/deactivate
方法: POST
描述: 停用用戶帳戶。
認證: 必需（管理員 JWT）
參數:
- 路徑參數:
  - user_id (字串, 必填)
請求範例:
```
POST /api/admin/users/12345/deactivate
```

回應:

200 成功:

{
  "message": "用戶帳戶已成功停用。"
}

404 未找到:
```
{
  "error": "未找到用戶。"
}
```

2. API 提供者管理

a. 列出 API 提供者

端點: /api/admin/api-providers
方法: GET
描述: 獲取所有已配置的 AI API 提供者列表。
認證: 必需（管理員 JWT）
參數:
- 查詢參數:
  - active (布林值, 選填, 根據活躍狀態篩選)

請求範例:

GET /api/admin/api-providers?active=true

回應:

200 成功:

{
  "data": [
    {
      "provider_id": "openai",
      "name": "OpenAI",
      "active": true,
      "config": {
        "api_key": "sk-********",
        "endpoint": "https://api.openai.com/v1/"
      }
    }
    // 更多提供者...
  ]
}

b. 添加 API 提供者

端點: /api/admin/api-providers
方法: POST
描述: 向系統中添加一個新的 AI API 提供者。
認證: 必需（管理員 JWT）
參數:
- 請求體:
  - provider_id (字串, 必填, 唯一標識)
  - name (字串, 必填)
  - api_key (字串, 必填)
  - endpoint (字串, 必填, 有效的 URL)

請求範例:

{
  "provider_id": "newai",
  "name": "新 AI 提供者",
  "api_key": "new-api-key-12345",
  "endpoint": "https://api.newai.com/v1/"
}

回應:

201 已創建:

{
  "message": "API 提供者已成功添加。",
  "provider_id": "newai"
}

400 錯誤的請求:

{
  "error": "驗證失敗。",
  "details": {
    "provider_id": "provider_id 已被使用。"
  }
}

c. 移除 API 提供者

端點: /api/admin/api-providers/{provider_id}
方法: DELETE
描述: 從系統中移除一個現有的 AI API 提供者。
認證: 必需（管理員 JWT）
參數:
- 路徑參數:
  - provider_id (字串, 必填)
請求範例:
```
DELETE /api/admin/api-providers/newai
```

回應:

200 成功:

{
  "message": "API 提供者已成功移除。"
}

404 未找到:

{
  "error": "未找到 API 提供者。"
}

d. 選擇活躍的 API 提供者

端點: /api/admin/api-providers/{provider_id}/activate
方法: POST
描述: 設定指定的 API 提供者為處理提示的活躍提供者。
認證: 必需（管理員 JWT）
參數:
- 路徑參數:
  - provider_id (字串, 必填)

請求範例:

POST /api/admin/api-providers/openai/activate

回應:

200 成功:

{
  "message": "API 提供者 'OpenAI' 現已成為活躍狀態。"
}

404 未找到:

{
  "error": "未找到 API 提供者。"
}

前端 API 認證端點

如果需要用戶登錄，應包括額外的端點。

3. 用戶登錄

端點: /api/frontend/login
方法: POST
描述: 認證用戶並返回 JWT。
參數:
- 請求體:
  - email (字串, 必填)
  - password (字串, 必填)

請求範例:

{
  "email": "john@example.com",
  "password": "SecurePass123"
}

回應:

200 成功:

{
  "token": "jwt-token-string",
  "expires_in": 3600
}

401 未授權:

{
  "error": "無效的憑證或帳戶未激活。"
}

錯誤處理

所有錯誤回應遵循一致的結構，便於客戶端進行調試和處理。

格式:

{
  "error": "詳細說明錯誤的消息。"
}

8.9 KiB Raw Blame History Unescape Escape

項目 API 文件

目錄

概述

認證

API 群組

前端 API

管理員 API

端點

前端 API 端點

1. 用戶註冊

2. 發送提示

管理員 API 端點

1. 用戶管理

a. 列出用戶

b. 啟用用戶

c. 停用用戶

2. API 提供者管理

a. 列出 API 提供者

b. 添加 API 提供者

c. 移除 API 提供者

d. 選擇活躍的 API 提供者

前端 API 認證端點

3. 用戶登錄

錯誤處理

8.9 KiB

Raw Blame History