新增 AI 結果與資料庫整合

INTEGRATION_SUMMARY.md

@@ -0,0 +1,149 @@
+# 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, 影片等)
+- 包含完整的錯誤處理和日誌記錄