# 項目 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": "詳細說明錯誤的消息。"
  }
  ```