# 評分機制後端實現文檔

## 概述

本文檔描述了AI展示平台評分機制的後端實現，包括資料庫設計、API端點和前端整合。

## 資料庫設計

### 評分相關表格

1. **app_judge_scores** - 應用評分表
   - 存儲評審對應用的評分記錄
   - 包含創新性、技術性、實用性、展示效果、影響力等評分項目
   - 自動計算總分

2. **proposal_judge_scores** - 提案評分表
   - 存儲評審對提案的評分記錄
   - 包含問題識別、解決方案可行性、創新性、影響力、展示效果等評分項目
   - 自動計算總分

3. **competition_judges** - 競賽評審關聯表
   - 管理競賽與評審的關聯關係

4. **competition_apps** - 競賽應用關聯表
   - 管理競賽與應用的關聯關係

5. **competition_proposals** - 競賽提案關聯表
   - 管理競賽與提案的關聯關係

## API端點

### 1. 評分管理 API (`/api/admin/scoring`)

#### GET - 獲取評分記錄
```
GET /api/admin/scoring?competitionId={id}&judgeId={id}&status={status}&search={query}
```

**參數:**
- `competitionId` (必需): 競賽ID
- `judgeId` (可選): 評審ID，用於篩選特定評審的評分
- `status` (可選): 狀態篩選 (all/completed/pending)
- `search` (可選): 搜尋關鍵字

**回應:**
```json
{
  "success": true,
  "message": "評分記錄獲取成功",
  "data": {
    "scores": [...],
    "stats": {...},
    "total": 10
  }
}
```

#### POST - 提交評分
```
POST /api/admin/scoring
```

**請求體:**
```json
{
  "judgeId": "judge_id",
  "participantId": "app_id",
  "participantType": "app",
  "scores": {
    "innovation_score": 8,
    "technical_score": 7,
    "usability_score": 9,
    "presentation_score": 8,
    "impact_score": 7
  },
  "comments": "評審意見"
}
```

### 2. 評分記錄管理 API (`/api/admin/scoring/[id]`)

#### PUT - 更新評分記錄
```
PUT /api/admin/scoring/{id}
```

#### DELETE - 刪除評分記錄
```
DELETE /api/admin/scoring/{id}?type={app|proposal}
```

### 3. 評分統計 API (`/api/admin/scoring/stats`)

#### GET - 獲取評分統計
```
GET /api/admin/scoring/stats?competitionId={id}
```

**回應:**
```json
{
  "success": true,
  "message": "評分統計獲取成功",
  "data": {
    "totalScores": 20,
    "completedScores": 15,
    "pendingScores": 5,
    "completionRate": 75,
    "totalParticipants": 10
  }
}
```

## 後端服務

### ScoringService 類別

提供以下主要方法：

1. **submitAppScore()** - 提交應用評分
2. **submitProposalScore()** - 提交提案評分
3. **getCompetitionScores()** - 獲取競賽所有評分記錄
4. **getCompetitionScoreStats()** - 獲取競賽評分統計
5. **getJudgeScores()** - 獲取評審的評分記錄
6. **updateAppScore()** - 更新應用評分
7. **updateProposalScore()** - 更新提案評分
8. **deleteScore()** - 刪除評分記錄

## 前端整合

### 組件更新

1. **ScoringManagement 組件**
   - 更新 `loadScoringData()` 方法以使用API
   - 更新 `handleSubmitScore()` 方法以提交到後端
   - 添加評分統計功能

2. **CompetitionContext 上下文**
   - 更新 `submitJudgeScore()` 方法以使用API
   - 保持向後兼容性

### 數據流程

1. 用戶選擇競賽
2. 前端調用 `/api/admin/scoring/stats` 獲取統計數據
3. 前端調用 `/api/admin/scoring` 獲取評分記錄
4. 用戶提交評分時調用 POST `/api/admin/scoring`
5. 後端更新資料庫並返回結果
6. 前端重新載入數據以顯示最新狀態

## 評分規則

### 應用評分項目
- 創新性 (innovation_score): 1-10分
- 技術性 (technical_score): 1-10分
- 實用性 (usability_score): 1-10分
- 展示效果 (presentation_score): 1-10分
- 影響力 (impact_score): 1-10分

### 提案評分項目
- 問題識別 (problem_identification_score): 1-10分
- 解決方案可行性 (solution_feasibility_score): 1-10分
- 創新性 (innovation_score): 1-10分
- 影響力 (impact_score): 1-10分
- 展示效果 (presentation_score): 1-10分

### 總分計算
總分 = (所有評分項目之和) / 評分項目數量

## 測試

### 資料庫測試
```bash
node scripts/test-scoring.js
```

### API測試
```bash
node scripts/test-scoring-api.js
```

## 部署注意事項

1. 確保資料庫表格已創建
2. 確保觸發器正常工作（自動計算總分）
3. 檢查API端點權限設置
4. 驗證前端組件與API的整合

## 未來改進

1. 添加評分權重配置
2. 實現評分審核流程
3. 添加評分歷史記錄
4. 實現批量評分功能
5. 添加評分導出功能