441 lines
8.9 KiB
Markdown
441 lines
8.9 KiB
Markdown
# 項目 API 文件
|
||
|
||
## 目錄
|
||
1. [概述](#概述)
|
||
2. [認證](#認證)
|
||
3. [API 群組](#api-群組)
|
||
- [前端 API](#前端-api)
|
||
- [管理員 API](#管理員-api)
|
||
4. [端點](#端點)
|
||
- [前端 API 端點](#前端-api-端點)
|
||
- [1. 用戶註冊](#1-用戶註冊)
|
||
- [2. 發送提示](#2-發送提示)
|
||
- [管理員 API 端點](#管理員-api-端點)
|
||
- [1. 用戶管理](#1-用戶管理)
|
||
- [a. 列出用戶](#a-列出用戶)
|
||
- [b. 啟用用戶](#b-啟用用戶)
|
||
- [c. 停用用戶](#c-停用用戶)
|
||
- [2. API 提供者管理](#2-api-提供者管理)
|
||
- [a. 列出 API 提供者](#a-列出-api-提供者)
|
||
- [b. 添加 API 提供者](#b-添加-api-提供者)
|
||
- [c. 移除 API 提供者](#c-移除-api-提供者)
|
||
- [d. 選擇活躍的 API 提供者](#d-選擇活躍的-api-提供者)
|
||
5. [錯誤處理](#錯誤處理)
|
||
6. [安全性考量](#安全性考量)
|
||
7. [可擴展性](#可擴展性)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
本 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 個字符)
|
||
- **請求範例**:
|
||
|
||
```json
|
||
{
|
||
"username": "john_doe",
|
||
"email": "john@example.com",
|
||
"password": "SecurePass123"
|
||
}
|
||
```
|
||
|
||
- **回應**:
|
||
- **201 已創建**:
|
||
|
||
```json
|
||
{
|
||
"message": "用戶註冊成功。等待激活。",
|
||
"user_id": "12345"
|
||
}
|
||
```
|
||
|
||
- **400 錯誤的請求**:
|
||
|
||
```json
|
||
{
|
||
"error": "驗證失敗。",
|
||
"details": {
|
||
"email": "電子郵件地址格式不正確。"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. 發送提示
|
||
|
||
- **端點**: `/api/frontend/send-prompt`
|
||
- **方法**: `POST`
|
||
- **描述**: 通過中間件向選定的 AI 提供者發送用戶提示，並返回 AI 的回應。
|
||
- **認證**: 必需（用戶 JWT）
|
||
- **參數**:
|
||
- **請求體**:
|
||
- `prompt` (字串, 必填)
|
||
- **請求範例**:
|
||
|
||
```json
|
||
{
|
||
"prompt": "解釋相對論理論。"
|
||
}
|
||
```
|
||
|
||
- **回應**:
|
||
- **200 成功**:
|
||
|
||
```json
|
||
{
|
||
"response": "相對論理論包括阿爾伯特·愛因斯坦的兩個相互關聯的理論：狹義相對論和廣義相對論..."
|
||
}
|
||
```
|
||
|
||
- **400 錯誤的請求**:
|
||
|
||
```json
|
||
{
|
||
"error": "提示內容不能為空。"
|
||
}
|
||
```
|
||
|
||
- **500 內部伺服器錯誤**:
|
||
|
||
```json
|
||
{
|
||
"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 成功**:
|
||
|
||
```json
|
||
{
|
||
"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 成功**:
|
||
|
||
```json
|
||
{
|
||
"message": "用戶帳戶已成功啟用。"
|
||
}
|
||
```
|
||
|
||
- **404 未找到**:
|
||
|
||
```json
|
||
{
|
||
"error": "未找到用戶。"
|
||
}
|
||
```
|
||
|
||
##### c. 停用用戶
|
||
|
||
- **端點**: `/api/admin/users/{user_id}/deactivate`
|
||
- **方法**: `POST`
|
||
- **描述**: 停用用戶帳戶。
|
||
- **認證**: 必需（管理員 JWT）
|
||
- **參數**:
|
||
- **路徑參數**:
|
||
- `user_id` (字串, 必填)
|
||
- **請求範例**:
|
||
|
||
```
|
||
POST /api/admin/users/12345/deactivate
|
||
```
|
||
|
||
- **回應**:
|
||
- **200 成功**:
|
||
|
||
```json
|
||
{
|
||
"message": "用戶帳戶已成功停用。"
|
||
}
|
||
```
|
||
|
||
- **404 未找到**:
|
||
|
||
```json
|
||
{
|
||
"error": "未找到用戶。"
|
||
}
|
||
```
|
||
|
||
#### 2. API 提供者管理
|
||
|
||
##### a. 列出 API 提供者
|
||
|
||
- **端點**: `/api/admin/api-providers`
|
||
- **方法**: `GET`
|
||
- **描述**: 獲取所有已配置的 AI API 提供者列表。
|
||
- **認證**: 必需（管理員 JWT）
|
||
- **參數**:
|
||
- **查詢參數**:
|
||
- `active` (布林值, 選填, 根據活躍狀態篩選)
|
||
- **請求範例**:
|
||
|
||
```
|
||
GET /api/admin/api-providers?active=true
|
||
```
|
||
|
||
- **回應**:
|
||
- **200 成功**:
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
- **請求範例**:
|
||
|
||
```json
|
||
{
|
||
"provider_id": "newai",
|
||
"name": "新 AI 提供者",
|
||
"api_key": "new-api-key-12345",
|
||
"endpoint": "https://api.newai.com/v1/"
|
||
}
|
||
```
|
||
|
||
- **回應**:
|
||
- **201 已創建**:
|
||
|
||
```json
|
||
{
|
||
"message": "API 提供者已成功添加。",
|
||
"provider_id": "newai"
|
||
}
|
||
```
|
||
|
||
- **400 錯誤的請求**:
|
||
|
||
```json
|
||
{
|
||
"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 成功**:
|
||
|
||
```json
|
||
{
|
||
"message": "API 提供者已成功移除。"
|
||
}
|
||
```
|
||
|
||
- **404 未找到**:
|
||
|
||
```json
|
||
{
|
||
"error": "未找到 API 提供者。"
|
||
}
|
||
```
|
||
|
||
##### d. 選擇活躍的 API 提供者
|
||
|
||
- **端點**: `/api/admin/api-providers/{provider_id}/activate`
|
||
- **方法**: `POST`
|
||
- **描述**: 設定指定的 API 提供者為處理提示的活躍提供者。
|
||
- **認證**: 必需（管理員 JWT）
|
||
- **參數**:
|
||
- **路徑參數**:
|
||
- `provider_id` (字串, 必填)
|
||
- **請求範例**:
|
||
|
||
```
|
||
POST /api/admin/api-providers/openai/activate
|
||
```
|
||
|
||
- **回應**:
|
||
- **200 成功**:
|
||
|
||
```json
|
||
{
|
||
"message": "API 提供者 'OpenAI' 現已成為活躍狀態。"
|
||
}
|
||
```
|
||
|
||
- **404 未找到**:
|
||
|
||
```json
|
||
{
|
||
"error": "未找到 API 提供者。"
|
||
}
|
||
```
|
||
|
||
### 前端 API 認證端點
|
||
|
||
*如果需要用戶登錄，應包括額外的端點。*
|
||
|
||
#### 3. 用戶登錄
|
||
|
||
- **端點**: `/api/frontend/login`
|
||
- **方法**: `POST`
|
||
- **描述**: 認證用戶並返回 JWT。
|
||
- **參數**:
|
||
- **請求體**:
|
||
- `email` (字串, 必填)
|
||
- `password` (字串, 必填)
|
||
- **請求範例**:
|
||
|
||
```json
|
||
{
|
||
"email": "john@example.com",
|
||
"password": "SecurePass123"
|
||
}
|
||
```
|
||
|
||
- **回應**:
|
||
- **200 成功**:
|
||
|
||
```json
|
||
{
|
||
"token": "jwt-token-string",
|
||
"expires_in": 3600
|
||
}
|
||
```
|
||
|
||
- **401 未授權**:
|
||
|
||
```json
|
||
{
|
||
"error": "無效的憑證或帳戶未激活。"
|
||
}
|
||
```
|
||
|
||
## 錯誤處理
|
||
|
||
所有錯誤回應遵循一致的結構，便於客戶端進行調試和處理。
|
||
|
||
- **格式**:
|
||
|
||
```json
|
||
{
|
||
"error": "詳細說明錯誤的消息。"
|
||
}
|
||
```
|