ai-showcase-platform/README-SCORING-BACKEND.md

評分機制後端實現文檔

概述

本文檔描述了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 (可選): 搜尋關鍵字

回應:

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

POST - 提交評分

POST /api/admin/scoring

請求體:

{
  "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}

回應:

{
  "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分

總分計算

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

測試

資料庫測試

node scripts/test-scoring.js

API測試

node scripts/test-scoring-api.js

部署注意事項

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

未來改進

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