新增 AI 結果與資料庫整合

scripts/README-evaluation-upload.md

@@ -0,0 +1,124 @@
+# AI 評分結果上傳腳本說明
+
+## 概述
+
+這個腳本用於解析 AI 評分結果的 JSON 資料，並將結果上傳到資料庫的三個相關表中：
+- `evaluations` - 評審記錄主表
+- `evaluation_scores` - 評分結果明細表
+- `evaluation_feedback` - AI 評語和建議表
+
+## 資料庫表結構
+
+### 1. evaluations 表
+儲存評審的基本資訊：
+- `id` - 主鍵
+- `project_id` - 專案 ID
+- `overall_score` - 總分 (78.5)
+- `max_possible_score` - 滿分 (100)
+- `grade` - 等級 (A-)
+- `analysis_duration` - 分析耗時
+- `ai_model_version` - AI 模型版本
+- `status` - 狀態 (completed)
+- `error_message` - 錯誤訊息
+
+### 2. evaluation_scores 表
+儲存各項評分標準的詳細分數：
+- `id` - 主鍵
+- `evaluation_id` - 關聯到 evaluations 表
+- `criteria_item_id` - 關聯到 criteria_items 表
+- `score` - 得分
+- `max_score` - 滿分
+- `weight` - 權重
+- `weighted_score` - 加權分數
+- `percentage` - 百分比
+
+### 3. evaluation_feedback 表
+儲存 AI 的評語和建議：
+- `id` - 主鍵
+- `evaluation_id` - 關聯到 evaluations 表
+- `criteria_item_id` - 關聯到 criteria_items 表 (可為空)
+- `feedback_type` - 反饋類型 (overall/criteria/strength/improvement)
+- `content` - 反饋內容
+- `sort_order` - 排序
+
+## 使用方式
+
+### 1. 環境設定
+確保已設定資料庫連線環境變數：
+```bash
+export DB_HOST=localhost
+export DB_USER=root
+export DB_PASSWORD=your_password
+export DB_NAME=ai_scoring_app
+```
+
+### 2. 執行腳本
+```bash
+cd scripts
+node parse-ai-evaluation.js
+```
+
+### 3. 檢查結果
+腳本會輸出詳細的執行過程，包括：
+- 資料庫連接狀態
+- 各表的記錄創建數量
+- 最終的評分結果摘要
+
+## 重要注意事項
+
+### 1. criteria_item_id 對應
+腳本中的 `criteriaNameToId` 物件需要根據實際資料庫中的 `criteria_items` 表來調整：
+
+```javascript
+const criteriaNameToId = {
+  "應用實務性": 52,  // 需要確認實際 ID
+  "創新性": 53,
+  "成效與效益": 54,
+  "擴散與可複用性": 55,
+  "簡報與表達": 56
+};
+```
+
+### 2. project_id 設定
+腳本中假設專案 ID 為 1，實際使用時需要根據實際情況調整：
+
+```javascript
+const projectId = 1; // 需要根據實際專案 ID 調整
+```
+
+### 3. 資料驗證
+執行前請確認：
+- 資料庫連線正常
+- `criteria_items` 表中有對應的評分項目
+- `projects` 表中有對應的專案記錄
+
+## 資料解析說明
+
+### AI JSON 結構
+腳本解析的 AI JSON 包含以下主要部分：
+- 基本資訊：專案標題、總分、等級等
+- 評分標準：各項標準的得分和反饋
+- 詳細分析：整體分析和關鍵發現
+- 改進建議：保持優勢、關鍵改進、行動計劃
+
+### 資料映射
+- 每個評分標準會創建一條 `evaluation_scores` 記錄
+- 每個評分標準的反饋會創建多條 `evaluation_feedback` 記錄
+- 整體分析會創建 `feedback_type` 為 'overall' 的反饋記錄
+
+## 錯誤處理
+
+腳本包含完整的錯誤處理機制：
+- 資料庫連線錯誤
+- SQL 執行錯誤
+- 資料驗證錯誤
+
+所有錯誤都會在控制台輸出詳細資訊，並確保資料庫連線正確關閉。
+
+## 擴展功能
+
+如需處理其他 AI 評分結果，可以：
+1. 修改 `aiEvaluationResult` 物件
+2. 調整 `criteriaNameToId` 對應關係
+3. 更新 `projectId` 設定
+4. 重新執行腳本