---
# System prepended metadata

title: API Documentation

---

# API Documentation
:::spoiler 目錄
[toc]
:::


## feature/login
### 登入
- **URL**: `/login`
- **Method**: `POST`
- **說明**: 用戶登入，取得 JWT Token
- **參數**:
  - **POST**:
    - `username` (string): 用戶名稱
    - `password` (string): 密碼
- **身份權限**: 
  - **老師**: 可登入
  - **學生**: 可登入
- **Headers**: 無
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "access_token": "JWT_TOKEN",
      "user": {
        "id": 1,
        "username": "teacher1",
        "name": "Teacher One"
      }
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 缺少 `username` 或 `password`
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "Username and password are required."
      }
      ```
  - **Case 2**
    - **Condition**: 用戶名或密碼無效
    - **Code**: 401
    - **Content**:
      ```json
      {
        "message": "Invalid username or password."
      }
      ```

- **錯誤回應**:
  - **Code**: 401 Unauthorized
  - **Content**:
    ```json
    { "message": "Invalid username or password." }
    ```

### 取得使用者資料
- **URL**: `/user`
- **Method**: `GET`
- **說明**: 透過 JWT token 取得當前登入使用者的詳細資訊
- **參數**:
  - **GET**: 無
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "user": {
        "id": 1,
        "username": "teacher1",
        "name": "Teacher One"
      }
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: Token 無效
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "Invalid token."
      }
      ```
  - **Case 2**
    - **Condition**: 用戶不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "message": "User not found."
      }
      ```

### 更新使用者資料
- **URL**: `/user`
- **Method**: `PUT`
- **說明**: 更新當前登入使用者的資料
- **參數**:
  - **PUT**:
    - 可選字段如 `password` (string)
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "user": {
        "id": 1,
        "username": "teacher1",
        "name": "Teacher One"
      }
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: Token 無效
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "Invalid token."
      }
      ```
  - **Case 2**
    - **Condition**: 用戶不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "message": "User not found."
      }
      ```

### 刪除學生
- **URL**: `/students/<int:student_id>`
- **Method**: `DELETE`
- **說明**: 刪除指定學生資料
- **參數**:
  - **URL Path**:
    - `student_id` (int): 學生的唯一識別碼
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "message": "Student with ID 1 has been deleted."
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 用戶不是老師
    - **Code**: 403
    - **Content**:
      ```json
      {
        "message": "Access forbidden: Teachers only."
      }
      ```
  - **Case 2**
    - **Condition**: 學生不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "message": "Student not found."
      }
      ```

## feature/course-info
### 取得課程資訊
- **URL**: `/getCourseInfo/<int:course_id>`
- **Method**: `GET`
- **說明**: 根據課程 ID 獲取課程的詳細資訊
- **參數**:
  - **URL Path**:
    - `course_id` (int): 課程 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**: 無
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "id": 1,
      "name": "Math",
      "teacher_id": 1,
      "weekday": "Monday",
      "semester": "Fall 2024"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 課程不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "error": "Course not found"
      }
      ```
      
### 查詢教師課堂
- **URL**: `/courses`
- **Method**: `GET`
- **說明**: 取得當前登入教師的所有課程
- **參數**:
  - **GET**: 無
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    "courses": [
        {
            "archive": false,
            "id": 2,
            "is_favorite": true,
            "name": "電子學",
            "semester": "113-1",
            "teacher_id": 2,
            "teacher_name": "張諭騰",
            "teacher_username": "ytchang",
            "weekday": "Thur"
        },
        {
            "archive": false,
            "id": 6,
            "is_favorite": true,
            "name": "類比積體電路導論",
            "semester": "113-1",
            "teacher_id": 2,
            "teacher_name": "張諭騰",
            "teacher_username": "ytchang",
            "weekday": "Thu"
        },
        {
            "archive": false,
            "id": 7,
            "is_favorite": true,
            "name": "電機專題製作",
            "semester": "113-1",
            "teacher_id": 2,
            "teacher_name": "張諭騰",
            "teacher_username": "ytchang",
            "weekday": "Fri"
        }
    ]
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 用戶不是老師
    - **Code**: 403
    - **Content**:
      ```json
      {
        "message": "Access forbidden: Teachers only."
      }
      ```
  - **Case 2**
    - **Condition**: 教師不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "message": "Teacher not found."
      }
      ```

### 上傳課程圖片（目前有 bug (11/24)）
- **URL**: `/upload/<int:course_id>`
- **Method**: `POST`
- **說明**: 上傳並驗證課程圖片，僅支援 JPEG 和 PNG 格式，並限制圖片大小及解析度
- **參數**:
  - **URL Path**:
    - `course_id` (int): 課程 ID
  - **POST**:
    - `image` (File): 上傳的圖片檔案
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**: 無
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "success": "Image uploaded and linked to course successfully"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 課程不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "error": "Course not found"
      }
      ```
  - **Case 2**
    - **Condition**: 圖片格式不支援或大小不符合要求
    - **Code**: 400
    - **Content**:
      ```json
      {
        "error": "Invalid image type, only JPEG and PNG are allowed"
      }
      ```

### 取得課程圖片
- **URL**: `/get_image/<int:course_id>`
- **Method**: `GET`
- **說明**: 獲取指定課程的圖片
- **參數**:
  - **URL Path**:
    - `course_id` (int): 課程 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**: 無
- **成功回應**:
  - **Code**: 200
  - **Content**: 課程圖片
- **例外回應**:
  - **Case 1**
    - **Condition**: 圖片不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "error": "Image not found"
      }
      ```

### 切換收藏課程
- **URL**: `/toggle_favorite/<int:course_id>`
- **Method**: `PUT`
- **說明**: 切換課程收藏
- **參數**:
  - **URL Path**:
    - `course_id` (int): 課程 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
    "success": "Course favorite toggled"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 課程不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "error": "Course not found or not owned by teacher"
      }
      ```
      
### 取得收藏課程
- **URL**: `/favorites`
- **Method**: `GET`
- **說明**: 獲取當前教師標記為收藏的課程列表
- **參數**:
  - **GET**: 無
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "favorites": [
        {
          "id": 1,
          "name": "Math",
          "teacher_id": 1
        }
      ]
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 教師不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "message": "User not found."
      }
      ```
     
### 更新課程資料
- **URL**: `/courses/<int:course_id>`
- **Method**: `PUT`
- **說明**: 更新指定課程的相關資訊
- **參數**:
  - **URL Path**:
    - `course_id` (int): 課程 ID
  - **PUT**:
    - `name` (string, optional): 課程名稱
    - `teacher_id` (int, optional): 教師 ID
    - `weekday` (string, optional): 上課日
    - `semester` (string, optional): 學期
    - `archive` (boolean, optional): 是否封存
    - `image_id` (int, optional): 課程圖片 ID
    - `is_favorite` (boolean, optional): 是否標記為收藏
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "message": "Course updated successfully"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 課程不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "message": "Course not found."
      }
      ```
  - **Case 2**
    - **Condition**: 權限不足
    - **Code**: 403
    - **Content**:
      ```json
      {
        "message": "Access forbidden: Only the owner teacher can edit this course."
      }
      ```
### 取得課程每週資訊
- **URL**: `/getSections/<int:course_id>`
- **Method**: `GET`
- **說明**: 獲取課程的每週課程資訊
- **參數**:
  - **URL Path**:
    - `course_id` (int): 課程 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**: 無
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    "sections": [
        {
            "content": "測試資料",
            "course_id": 1,
            "end_date": "2024-10-08T10:00:00",
            "id": 21,
            "name": "Week 1",
            "publish_date": "2024-09-30T12:00:00",
            "sequence": 1,
            "start_date": "2024-10-08T08:00:00"
        },
        {
            "content": "測試資料",
            "course_id": 1,
            "end_date": "2024-10-15T10:00:00",
            "id": 22,
            "name": "Week 2",
            "publish_date": "2024-10-07T12:00:00",
            "sequence": 2,
            "start_date": "2024-10-15T08:00:00"
        }
    ]

    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 課程不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "error": "Course not found"
      }
      ```


### 獲取課程學生名單
- **URL**: `/getStudents/<int:course_id>`
- **Method**: `GET`
- **說明**: 獲取指定課程的學生列表
- **參數**:
  - **URL Path**:
    - `course_id` (int): 課程 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**: 無
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "students": [
        {
          "id": 1,
          "username": "student1",
          "name": "Student One"
        },
        {
          "id": 2,
          "username": "student2",
          "name": "Student Two"
        }
      ]
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 課程不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "error": "Course not found"
      }
      ```

## feature/file-upload
### 上傳 PDF 檔案
- **URL**: `/api/upload_pdf`
- **Method**: `POST`
- **說明**: 上傳 PDF 檔案，並儲存相關資訊到資料庫
- **參數**:
  - **POST**:
    - `file` (File): 上傳的 PDF 文件
    - `course_id` (int): 課程 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "file_id": 1,
      "message": "PDF file uploaded successfully",
      "filename": "example.pdf"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 缺少 `course_id`
    - **Code**: 400
    - **Content**:
      ```json
      {
        "error": "Course ID is required"
      }
      ```
  - **Case 2**
    - **Condition**: 未選擇檔案或非 PDF 格式
    - **Code**: 400
    - **Content**:
      ```json
      {
        "error": "Only PDF files are allowed"
      }
      ```
### 上傳多類型檔案
- **URL**: `/api/upload_various_file`
- **Method**: `POST`
- **說明**: 上傳多種類型的檔案（如圖片、文字檔）
- **參數**:
  - **POST**:
    - `file` (File): 上傳的檔案
    - `class_id` (int): 班級 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "message": "File uploaded successfully",
      "filename": "example.txt"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 缺少 `class_id`
    - **Code**: 400
    - **Content**:
      ```json
      {
        "error": "Class ID is required"
      }
      ```
  - **Case 2**
    - **Condition**: 未選擇檔案
    - **Code**: 400
    - **Content**:
      ```json
      {
        "error": "No selected file"
      }
      ```


### 下載檔案
- **URL**: `/api/download/<filename>`
- **Method**: `GET`
- **說明**: 下載指定課程的檔案
- **參數**:
  - **URL Path**:
    - `filename` (string): 檔案名稱
  - **GET**:
    - `class_id` (int): 班級 ID
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**: 下載的檔案內容
- **例外回應**:
  - **Case 1**
    - **Condition**: 檔案不存在
    - **Code**: 404
    - **Content**:
      ```json
      {
        "error": "File not found"
      }
      ```
  - **Case 2**
    - **Condition**: 權限不足
    - **Code**: 403
    - **Content**:
      ```json
      {
        "error": "Access forbidden"
      }
      ```

## feature/register
### 註冊 (測試用)
- **URL**: `/register`
- **Method**: `POST`
- **說明**: 處理新使用者的註冊請求。支援教師和學生兩種帳號類型，並檢查帳號名稱是否重複、密碼格式是否符合要求，以及課程是否存在。

- **參數**:
  - **Body**:
    - `username` (`String`, 必填): 使用者名稱
    - `password` (`String`, 必填): 密碼，至少 8 個字元
    - `user_type` (`String`, 必填): 帳號類型，值為 `"teacher"` 或 `"student"`
    - `name` (`String`, 必填): 教師或學生的姓名
    - `course` (`String`, 必填): 課程名稱
    - `group` (`Integer`, 選填): 僅對學生適用，學生的組別號碼，預設為 1

- **身份權限**: 
  - **老師**: 可用
  - **學生**: 可用

- **Headers**: 無

- **成功回應**:
  - **Code**: 201
  - **Content**:
    ```json
    {
      "message": "User registered successfully."
    }
    ```

- **例外回應**:
  - **Case 1**
    - **Condition**: `username` 已存在於系統中
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "Username already exists."
      }
      ```
  - **Case 2**
    - **Condition**: `password` 長度小於 8 個字元
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "Password must be at least 8 characters long."
      }
      ```
  - **Case 3**
    - **Condition**: `course` 不存在於系統中
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "Course not found."
      }
      ```
  - **Case 4**
    - **Condition**: `user_type` 為 `teacher`，但收到 `group` 欄位
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "only user_type is student have group."
      }
      ```
  - **Case 5**
    - **Condition**: 伺服器內部發生錯誤
    - **Code**: 500
    - **Content**:
      ```json
      {
        "message": "Error message describing the issue."
      }
      ```

## feature/LLM
### 開始對話
- **URL**: `/start_conversation`
- **Method**: `POST`
- **說明**: 為教師建立新的對話
- **參數**:
  - **POST**:
    - `course_id` (int): 課程 ID
    - `course_section` (int): 課程資訊的序列號碼
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "uuid": "conversation-uuid-12345"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: Token 無效
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "Invalid token."
      }
      ```
  - **Case 2**
    - **Condition**: 用戶非老師
    - **Code**: 403
    - **Content**:
      ```json
      {
        "message": "Access forbidden: Teachers only."
      }
      ```

### 對話
- **URL**: `/chat/<string:conversation_uuid>`
- **Method**: `POST`
- **說明**: 在指定對話中傳送訊息並獲取回應
- **參數**:
  - **URL Path**:
    - `conversation_uuid` (string): 對話的唯一識別碼
  - **POST**:
    - `user_input` (string): 用戶輸入的訊息
    - `file_id` (int, optional): 文件的唯一識別碼（如需要從文件中提取內容）
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "answer": "AI 回應的內容"
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: UUID 無效或未提供
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "The UUID of conversation is invalid."
      }
      ```
  - **Case 2**
    - **Condition**: 權限不足
    - **Code**: 401
    - **Content**:
      ```json
      {
        "message": "Not authorized."
      }
      ```

---

### 取得對話歷史
- **URL**: `/conversation          /<string:conversation_uuid>`
- **Method**: `GET`
- **說明**: 獲取指定對話的歷史記錄
- **參數**:
  - **URL Path**:
    - `conversation_uuid` (string): 對話的唯一識別碼
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "uuid": "conversation-uuid-12345",
      "history": [
        {
          "id": 1,
          "sender": "user",
          "message": "用戶訊息內容",
          "sent_at": "2024-11-22 10:30:00"
        },
        {
          "id": 2,
          "sender": "assistant",
          "message": "AI 回應內容",
          "sent_at": "2024-11-22 10:31:00"
        }
      ]
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: UUID 無效或未提供
    - **Code**: 400
    - **Content**:
      ```json
      {
        "message": "The UUID of conversation is invalid."
      }
      ```
  - **Case 2**
    - **Condition**: 權限不足
    - **Code**: 401
    - **Content**:
      ```json
      {
        "message": "Not authorized."
      }
      ```


### 列出對話
- **URL**: `/list_conversations`
- **Method**: `GET`
- **說明**: 列出當前教師的所有對話
- **參數**:
  - **GET**: 無
- **身份權限**: 
  - **老師**: 可用
  - **學生**: 禁止
- **Headers**:
  - `Authorization`: Bearer Token
- **成功回應**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "conversations": [
        {
          "course_name": "軟體工程",
          "course_section": "Week 1",
          "uuid": "conversation-uuid-12345",
          "summary": "對話摘要內容",
          "created_at": "2024-11-22 10:00:00"
        }
      ]
    }
    ```
- **例外回應**:
  - **Case 1**
    - **Condition**: 用戶非老師
    - **Code**: 403
    - **Content**:
      ```json
      {
        "message": "Access forbidden: Teachers only."
      }
      ```
## feature/assignments
### 新增作業
- **URL**: `/assignments`
- **Method**: `POST`
- **說明**: 教師新增作業，並可附帶檔案。
- **參數**:
    - **POST**:
        - `title` (`String`, 必填): 作業標題
        - `description` (`String`, 選填): 作業描述
        - `due_date` (`Datetime`, 必填): 截止期限
        - `course_id` (`Integer`, 必填): 作業對應課程
        - `files` (`list`, 選填): 檔案鏈結
- **身份權限**:
    - **老師**: 可用
    - **學生**: 禁止
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 200
    - **Content**:
        ```json
        {
          "message": "Assignment created successfully.",
          "assignment": {
            "id": 1,
            "title": "作業標題",
            "description": "作業描述",
            "due_date": "2024-11-30T23:59:59",
            "created_date": "2024-11-23T12:00:00",
            "modified_date": "2024-11-23T12:00:00",
            "files": ["https://example.com/file1.pdf", "https://example.com/file2.docx"]
          }
        }
        ```
- **例外回應**:
    - **Case 1**
        - **Condition**: 用戶非老師
        - **Code**: 403
        - **Content**:
            ```json
            {
              "message": "Only teachers can create assignments."
            }
            ```
    - **Case 2**
        - **Condition**: 輸入資料缺失
        - **Code**: 400
        - **Content**:
            ```json
            {
              "message": "Missing required field: 'title'"
            }
            ```
    
### 查詢作業
- **URL**: `/assignments/<int:course_id>`
- **Method**: `GET`
- **說明**: 查詢指定課程的所有作業。
- **參數**:
    - **URL Path**:
        - `course_id` (int): 課程 ID
- **身份權限**:
    - **老師**: 可用
    - **學生**: 可用
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 200
    - **Content**:
        ```json
        {
          "assignments": [
            {
              "id": 1,
              "title": "作業標題",
              "description": "作業描述",
              "due_date": "2024-11-30T23:59:59",
              "created_date": "2024-11-23T12:00:00",
              "modified_date": "2024-11-23T12:00:00",
              "files": ["https://example.com/file1.pdf"]
            }
          ]
        }
        ```
    
### 修改作業
- **URL**: `/assignments/<int:assignment_id>`
- **Method**: `PUT`
- **說明**: 教師修改指定作業資料與附帶檔案。
- **參數**:
    - **URL Path**:
        - `assignment_id` (int): 作業 ID`
    - **PUT**:
        - `title` (`String`, 必填): 作業標題
        - `description` (`String`, 選填): 作業描述
        - `due_date` (`Datetime`, 必填): 截止期限
        - `files` (`list`, 選填): 檔案鏈結
- **身份權限**:
    - **老師**: 可用
    - **學生**: 禁止
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 200
    - **Content**:
        ```json
        {
          "message": "Assignment updated successfully."
        }
        ```
- **例外回應**:
    - **Case 1**
        - **Condition**: 用戶非老師
        - **Code**: 403
        - **Content**:
            ```json
            {
              "message": "Only teachers can update assignments."
            }
            ```
    - **Case 2**
        - **Condition**: 輸入資料缺失
        - **Code**: 400
        - **Content**:
            ```json
            {
              "message": "Invalid data."
            }
            ```
### 刪除作業
- **URL**: `/assignments/<int:assignment_id>`
- **Method**: `DELETE`
- **說明**: 教師刪除指定作業。
- **參數**:
    - **URL Path**:
        - `assignment_id` (int): 作業 ID
- **身份權限**:
    - **老師**: 可用
    - **學生**: 禁止
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 200
    - **Content**:
        ```json
        {
          "message": "Assignment deleted successfully."
        }
        ```
- **例外回應**:
    - **Case 1**
        - **Condition**: 用戶非老師
        - **Code**: 403
        - **Content**:
            ```json
            {
              "message": "Only teachers can delete assignments."
            }
            ```
## feature/submissions
### 查詢作業
- **URL**:`/assignments/<int:course_id>`
- **Method**:`GET`
- **說明**: 查詢指定課程的所有作業
- **參數**:
    - **URL Path**:
        - `course_id`(int): 課程 ID
- **身份權限**:
    - **老師**: 可用
    - **學生**: 可用
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 200
    - **Content**:
        ```json
        {
          "assignments": [
            {
              "id": 1,
              "title": "作業標題",
              "description": "作業描述",
              "due_date": "2024-11-30T23:59:59",
              "created_date": "2024-11-23T12:00:00",
              "modified_date": "2024-11-23T12:00:00",
              "files": ["https://example.com/file1.pdf"]
            }
          ]
        }
        ```
### 學生繳交作業
- **URL**:`/submissions`
- **Method**:`POST`
- **說明**: 學生繳交指定課程的作業
- **參數**:
    - **POST**:
        - `assignment_id` (`Integer`, 必填): 作業 ID
        - `description` (`String`, 選填): 作業描述
        - `files` (`list`, 選填): 檔案鏈結
- **身份權限**:
    - **老師**: 禁用
    - **學生**: 可用
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 201
    - **Content**:
        ```json
        {
          "message": "Submission created successfully."
        }
        ```
- **例外回應**:
    - Code: 400 (缺少必要欄位)
    - **Content**:
        ```json
        {
          "message": "Missing required field: assignment_id"
        }
        ```
    - Code: 500 (伺服器錯誤)
    - **Content**:
        ```json
        {
          "Error creating submission: <error details>"
        }
        ```

### 修改繳交的作業
- **URL**: `/submissions/<int:submission_id>`
- **Method**: `PUT`
- **說明**: 學生修改已繳交的作業。
- **參數**:
     - **URL Path**:
        - `submission_id` (int, 必填): 作業提交的 ID
    - **PUT**:
        - `description` (String, 選填): 新的作業描述。
        - `files` (List, 選填): 替換的檔案 URL 列表。
- **身份權限**:
    - **老師**: 禁止
    - **學生**: 可用(僅能修改自己的作業)
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 200
    - **Content**:
        ```json
            {
              "message": "Submission updated successfully."
            }
        ```
- **例外回應**:
    - **Code**: 404 (提交不存在或無權限)
    - **Content**:
        ```json
            {
              "message": "Submission not found or permission denied."
            }
        ```
    - **Code**: 500 (伺服器錯誤)
    - **Content**:
        ```json
            {
              "message": "Error updating submission: <error details>"
            }
        ```
### 新增評分
- **URL**: `/submissions/<int:submission_id>/grade`
- **Method**: `POST`
- **說明**: 教師為指定的作業提交新增評分和評語。
- **參數**:
    - **URL Path**:
        - `submission_id` (int, 必填): 作業提交的 ID
    - **POST**:
        - `score` (Number, 必填): 評分，應為數字 (整數或浮點數)。
        - `feedback` (String, 選填): 評語。
- **身份權限**:
    - **老師**: 可用
    - **學生**: 禁止
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 201
    - **Content**:
        ```json
            {
              "message": "Submission graded successfully.",
              "submission": {
                "submission_id": 123,
                "assignment_id": 1,
                "student_id": 456,
                "score": 90,
                "feedback": "Well done!",
                "submitted_at": "2024-11-22T10:00:00"
              }
            }
        ```
- **例外回應**:
    - **Case 1**
        - **Condition**: 用戶非老師
        - **Code**: 403
        - **Content**:
            ```json
            {
              "message": "Only teachers can add grades."
            }
            ```
    - **Case 2**
        - **Condition**: 提交的評分資料缺失或格式錯誤
        - **Code**: 400
        - **Content**:
            ```json
            {
              "message": "Score must be provided and should be a number."
            }
            ```
    - **Case 3**
        - **Condition**: 作業提交已經被評分
        - **Code**: 400
        - **Content**:
            ```json
            {
              "message": "Grade already exists. Use the update API to modify the grade."
            }
            ```

### 更新評分
- **URL**: `/submissions/<int:submission_id>/grade`
- **Method**: `PUT`
- **說明**: 教師更新指定的作業提交的評分和評語。
- **參數**:
    - **URL Path**:
        - `submission_id` (int, 必填): 作業提交的 ID
    - **PUT**:
        - `score` (Number, 必填): 新評分，應為數字 (整數或浮點數)。
        - `feedback` (String, 選填): 新評語。
- **身份權限**:
    - **老師**: 可用
    - **學生**: 禁止
- **Headers**:
    - **Authorization**: Bearer Token
- **成功回應**:
    - **Code**: 200
    - **Content**:
        ```json
        {
          "message": "Submission grade updated successfully.",
          "submission": {
            "submission_id": 123,
            "assignment_id": 1,
            "student_id": 456,
            "score": 95,
            "feedback": "Excellent improvement!",
            "submitted_at": "2024-11-22T10:00:00"
          }
        }
        ```
- **例外回應**:
    - **Case 1**
        - **Condition**: 用戶非老師
        - **Code**: 403
        - **Content**:
            ```json
            {
              "message": "Only teachers can update grades."
            }
            ```
    - **Case 2**
        - **Condition**: 提交的評分資料缺失或格式錯誤
        - **Code**: 400
        - **Content**:
            ```json
            {
              "message": "Score must be provided and should be a number."
            }
            ```
    - **Case 3**
        - **Condition**: 評分不存在
        - **Code**: 400
        - **Content**:
            ```json
            {
              "message": "Grade does not exist. Use the add API to create a grade."
            }
            ```