# 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."
}
```
Sign in with Wallet
Connect another wallet