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