150 lines
4.9 KiB
Markdown
150 lines
4.9 KiB
Markdown
# AI 評分整合功能總結
|
||
|
||
## 概述
|
||
|
||
已成功將 AI 評分結果整合到資料庫存儲系統中。當用戶上傳 PPT 文件並點擊「開始 AI 評審」按鈕時，系統會自動將所有相關資料上傳到資料庫的三個主要表中。
|
||
|
||
## 整合的資料庫表
|
||
|
||
### 1. projects 表
|
||
- **用途**: 儲存專案基本資訊
|
||
- **創建時機**: AI 分析開始前
|
||
- **主要欄位**:
|
||
- `id`: 專案唯一識別碼
|
||
- `user_id`: 用戶 ID
|
||
- `template_id`: 評分標準模板 ID
|
||
- `title`: 專案標題
|
||
- `description`: 專案描述
|
||
- `status`: 專案狀態 (analyzing → completed)
|
||
- `analysis_started_at`: 分析開始時間
|
||
- `analysis_completed_at`: 分析完成時間
|
||
|
||
### 2. project_files 表
|
||
- **用途**: 儲存上傳的文件資訊
|
||
- **創建時機**: 文件上傳後，AI 分析前
|
||
- **主要欄位**:
|
||
- `id`: 文件唯一識別碼
|
||
- `project_id`: 關聯的專案 ID
|
||
- `original_name`: 原始文件名稱
|
||
- `file_name`: 儲存的文件名稱
|
||
- `file_path`: 文件儲存路徑
|
||
- `file_size`: 文件大小
|
||
- `file_type`: 文件類型
|
||
- `mime_type`: MIME 類型
|
||
- `upload_status`: 上傳狀態
|
||
- `upload_progress`: 上傳進度
|
||
|
||
### 3. evaluations 表
|
||
- **用途**: 儲存 AI 評審的基本資訊
|
||
- **創建時機**: AI 分析完成後
|
||
- **主要欄位**:
|
||
- `id`: 評審唯一識別碼
|
||
- `project_id`: 關聯的專案 ID
|
||
- `overall_score`: 總分
|
||
- `max_possible_score`: 滿分
|
||
- `grade`: 等級評定
|
||
- `analysis_duration`: 分析耗時
|
||
- `ai_model_version`: AI 模型版本
|
||
- `status`: 評審狀態
|
||
- `error_message`: 錯誤訊息
|
||
|
||
### 4. evaluation_scores 表
|
||
- **用途**: 儲存各項評分標準的詳細分數
|
||
- **創建時機**: AI 分析完成後
|
||
- **主要欄位**:
|
||
- `id`: 評分記錄唯一識別碼
|
||
- `evaluation_id`: 關聯的評審 ID
|
||
- `criteria_item_id`: 關聯的評分標準項目 ID
|
||
- `score`: 得分
|
||
- `max_score`: 滿分
|
||
- `weight`: 權重
|
||
- `weighted_score`: 加權分數
|
||
- `percentage`: 得分百分比
|
||
|
||
### 5. evaluation_feedback 表
|
||
- **用途**: 儲存 AI 的評語和建議
|
||
- **創建時機**: AI 分析完成後
|
||
- **主要欄位**:
|
||
- `id`: 反饋記錄唯一識別碼
|
||
- `evaluation_id`: 關聯的評審 ID
|
||
- `criteria_item_id`: 關聯的評分標準項目 ID (可為空)
|
||
- `feedback_type`: 反饋類型 (overall/criteria/strength/improvement)
|
||
- `content`: 反饋內容
|
||
- `sort_order`: 排序順序
|
||
|
||
## 處理流程
|
||
|
||
### 1. 用戶操作
|
||
1. 用戶訪問上傳頁面 (`/upload`)
|
||
2. 上傳 PPT 文件
|
||
3. 填寫專案標題和描述
|
||
4. 點擊「開始 AI 評審」按鈕
|
||
|
||
### 2. 後端處理
|
||
1. **驗證輸入**: 檢查必填欄位和文件格式
|
||
2. **載入評分標準**: 從資料庫獲取評分標準模板
|
||
3. **創建專案記錄**: 在 `projects` 表中創建專案記錄
|
||
4. **處理文件上傳**: 在 `project_files` 表中創建文件記錄
|
||
5. **AI 分析**: 使用 Gemini AI 分析 PPT 內容
|
||
6. **上傳評審結果**: 將 AI 分析結果上傳到資料庫
|
||
- 創建 `evaluations` 記錄
|
||
- 創建 `evaluation_scores` 記錄
|
||
- 創建 `evaluation_feedback` 記錄
|
||
7. **更新專案狀態**: 將專案狀態設為完成
|
||
8. **返回結果**: 將評分結果返回給前端
|
||
|
||
### 3. 前端顯示
|
||
1. 接收評分結果
|
||
2. 儲存到 localStorage
|
||
3. 導向到結果頁面 (`/results`)
|
||
4. 顯示評分結果和圖表
|
||
|
||
## 技術實現
|
||
|
||
### 修改的文件
|
||
- `app/api/evaluate/route.ts`: 主要的 API 端點，整合了資料庫上傳功能
|
||
|
||
### 關鍵功能
|
||
- **錯誤處理**: 即使資料庫上傳失敗，也會返回 AI 分析結果
|
||
- **資料轉換**: 將資料庫格式轉換為 AI 服務期望的格式
|
||
- **完整日誌**: 詳細的控制台日誌記錄整個處理過程
|
||
- **狀態管理**: 正確管理專案和評審的狀態
|
||
|
||
### 資料庫關聯
|
||
- `projects` ← `project_files` (一對多)
|
||
- `projects` ← `evaluations` (一對一)
|
||
- `evaluations` ← `evaluation_scores` (一對多)
|
||
- `evaluations` ← `evaluation_feedback` (一對多)
|
||
- `criteria_items` ← `evaluation_scores` (一對多)
|
||
- `criteria_items` ← `evaluation_feedback` (一對多)
|
||
|
||
## 測試和驗證
|
||
|
||
### 測試腳本
|
||
- `scripts/test-integration.js`: 提供完整的測試指南和檢查要點
|
||
|
||
### 驗證要點
|
||
1. 控制台日誌顯示完整的處理流程
|
||
2. 資料庫正確創建所有相關記錄
|
||
3. 前端正確顯示評分結果
|
||
4. 沒有錯誤或異常
|
||
5. 處理時間在合理範圍內
|
||
|
||
## 使用方式
|
||
|
||
1. 確保資料庫連線正常
|
||
2. 確保有評分標準模板
|
||
3. 啟動應用程式: `npm run dev`
|
||
4. 訪問上傳頁面: `http://localhost:3000/upload`
|
||
5. 上傳 PPT 文件並填寫專案資訊
|
||
6. 點擊「開始 AI 評審」按鈕
|
||
7. 查看結果頁面顯示的評分結果
|
||
|
||
## 注意事項
|
||
|
||
- 所有資料庫操作都包含在 try-catch 區塊中
|
||
- 即使資料庫上傳失敗，AI 分析結果仍會返回給用戶
|
||
- 專案狀態會正確更新為完成狀態
|
||
- 支援多種文件格式 (PPT, PDF, 影片等)
|
||
- 包含完整的錯誤處理和日誌記錄
|