Files
ai-showcase-platform/README-SCORING-BACKEND.md
2025-09-18 18:34:31 +08:00

4.5 KiB
Raw Blame History

評分機制後端實現文檔

概述

本文檔描述了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. 添加評分導出功能