# 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. 重新執行腳本