196 lines
4.5 KiB
Markdown
196 lines
4.5 KiB
Markdown
# 評分機制後端實現文檔
|
||
|
||
## 概述
|
||
|
||
本文檔描述了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. 添加評分導出功能
|