12 KiB
12 KiB
AI 智能評審系統
一個基於 Next.js 和 Google Gemini AI 的智能評審平台，支援多種格式內容上傳（PPT、影片、網站連結），並根據自定義評分標準進行 AI 智能評分。
🚀 功能特色
核心功能
- 多格式內容支援：支援 PPT/PPTX、影片檔案、網站連結上傳
- 自定義評分標準：可設定評分項目、權重比例和滿分標準
- AI 智能評分：使用 Google Gemini AI 進行內容分析和評分
- 詳細評分報告：提供完整的評分結果、改進建議和行動計劃
- PDF 報告生成：可下載專業的 PDF 評分報告
- 歷史記錄管理：追蹤所有評審記錄和統計數據
技術特色
- 現代化 UI：基於 Radix UI 和 Tailwind CSS 的響應式設計
- TypeScript：完整的類型安全支援
- 資料庫整合：MySQL 資料庫存儲所有評審數據
- PDF 生成：使用 Puppeteer 生成專業 PDF 報告
- 文件處理：支援 PPTX 解析和內容提取
🏗️ 技術架構
前端技術棧
- 框架：Next.js 14.2.16 (App Router)
- 語言：TypeScript 5
- 樣式：Tailwind CSS 4.1.9
- UI 組件：Radix UI + shadcn/ui
- 字體：Geist Sans/Mono + Playfair Display
- 圖表：Recharts
後端技術棧
- API：Next.js API Routes
- 資料庫：MySQL 8.0
- ORM：mysql2 (原生 SQL)
- AI 服務：Google Generative AI (Gemini 1.5 Pro)
- PDF 生成：Puppeteer 24.22.1
- 文件處理：adm-zip, mammoth
開發工具
- 包管理：pnpm
- 代碼規範：ESLint
- 類型檢查：TypeScript
- 部署：Vercel Analytics
📁 專案結構
ai-scoring-application/
├── app/ # Next.js App Router
│ ├── api/ # API 路由
│ │ ├── criteria-templates/ # 評分標準模板 API
│ │ ├── evaluate/ # 評審 API
│ │ ├── evaluation/ # 評審記錄 API
│ │ ├── history/ # 歷史記錄 API
│ │ └── upload/ # 文件上傳 API
│ ├── criteria/ # 評分標準頁面
│ ├── history/ # 歷史記錄頁面
│ ├── results/ # 評分結果頁面
│ ├── upload/ # 文件上傳頁面
│ ├── layout.tsx # 根佈局
│ ├── page.tsx # 首頁
│ └── globals.css # 全域樣式
├── components/ # React 組件
│ ├── ui/ # UI 組件庫
│ ├── sidebar.tsx # 側邊欄
│ ├── share-modal.tsx # 分享模態框
│ └── theme-provider.tsx # 主題提供者
├── lib/ # 核心庫
│ ├── services/ # 業務邏輯服務
│ │ ├── database.ts # 資料庫服務
│ │ ├── gemini.ts # Gemini AI 服務
│ │ └── evaluation-upload.ts # 評審上傳服務
│ ├── utils/ # 工具函數
│ │ ├── html-pdf-generator.ts # PDF 生成器
│ │ ├── pdf-generator.ts # 舊版 PDF 生成器
│ │ └── file-path.ts # 文件路徑工具
│ ├── models/ # 資料模型
│ ├── config.ts # 配置管理
│ └── database.ts # 資料庫連接
├── database/ # 資料庫相關
│ ├── schema.sql # 資料庫架構
│ └── README.md # 資料庫說明
├── public/ # 靜態資源
├── uploads/ # 上傳文件存儲
├── data/ # 示例數據
├── examples/ # 示例代碼
├── hooks/ # React Hooks
├── styles/ # 額外樣式
├── package.json # 專案依賴
├── tsconfig.json # TypeScript 配置
├── next.config.mjs # Next.js 配置
├── tailwind.config.js # Tailwind 配置
└── README.md # 專案說明
🗄️ 資料庫架構
核心資料表
用戶管理
users- 用戶基本資訊user_sessions- 用戶會話管理
評分標準
criteria_templates- 評分標準模板criteria_items- 評分項目明細
專案管理
projects- 評審專案project_files- 專案文件project_websites- 專案網站連結
評審記錄
evaluations- 評審記錄evaluation_scores- 評分結果明細evaluation_feedback- AI 評語和建議
系統設定
system_settings- 系統配置參數
預設評分標準
系統預設包含 5 個評分項目：
- 內容品質 (25%) - 內容的準確性、完整性和專業度
- 視覺設計 (20%) - 版面設計、色彩搭配和視覺效果
- 邏輯結構 (20%) - 內容組織的邏輯性和條理性
- 創新性 (15%) - 創意思維和獨特觀點的展現
- 實用性 (20%) - 內容的實際應用價值和可操作性
🔧 安裝與設定
環境需求
- Node.js 18+
- pnpm 8+
- MySQL 8.0+
- Chrome 瀏覽器 (用於 PDF 生成)
1. 克隆專案
git clone <repository-url>
cd ai-scoring-application
2. 安裝依賴
pnpm install
3. 環境變數設定
複製 env.example 為 .env.local 並設定以下變數：
# 應用配置
NEXT_PUBLIC_APP_URL=http://localhost:12024
NEXT_PUBLIC_APP_NAME=AI 智能評審系統
# 資料庫配置
DB_HOST=mysql.theaken.com
DB_PORT=33306
DB_NAME=db_AI_scoring
DB_USER=root
DB_PASSWORD=your_password
# AI 配置
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-1.5-pro
GEMINI_MAX_TOKENS=8192
4. 資料庫初始化
# 初始化資料庫結構
pnpm run db:init
# 測試資料庫連接
pnpm run db:test
# 檢查配置
pnpm run config:check
5. 安裝 Puppeteer Chrome
npx puppeteer browsers install chrome
6. 啟動開發伺服器
pnpm run dev
應用將在 http://localhost:12024 啟動。
🚀 部署
Vercel 部署
- 將專案推送到 GitHub
- 在 Vercel 中導入專案
- 設定環境變數
- 部署完成
自託管部署
# 建構專案
pnpm run build
# 啟動生產伺服器
pnpm run start
📖 API 文檔
評分標準模板 API
獲取所有模板
GET /api/criteria-templates
獲取預設模板
GET /api/criteria-templates/default
獲取特定模板
GET /api/criteria-templates/[id]
文件上傳 API
上傳文件
POST /api/upload
Content-Type: multipart/form-data
Body:
- files: File[] (支援多檔案上傳)
- projectTitle: string
- projectDescription: string
- templateId: number
評審 API
開始評審
POST /api/evaluate
Content-Type: application/json
Body:
{
"projectId": number,
"templateId": number
}
獲取評審結果
GET /api/evaluation/[id]
下載 PDF 報告
GET /api/evaluation/[id]/download
刪除評審記錄
DELETE /api/evaluation/[id]/delete
歷史記錄 API
獲取歷史記錄
GET /api/history
Query Parameters:
- page: number (預設 1)
- limit: number (預設 20)
獲取統計數據
GET /api/history/stats
🎯 使用流程
1. 設定評分標準
- 進入「評分標準」頁面
- 選擇或創建評分標準模板
- 設定評分項目和權重比例
2. 上傳內容
- 進入「上傳文件」頁面
- 填寫專案資訊（標題、描述）
- 選擇評分標準模板
- 上傳 PPT/影片文件或提供網站連結
3. AI 分析評分
- 系統自動提取內容
- 使用 Gemini AI 分析內容
- 根據評分標準進行評分
- 生成詳細的評分結果
4. 查看結果
- 進入「評分結果」頁面查看詳細評分
- 瀏覽各項評分和 AI 評語
- 查看改進建議和行動計劃
- 下載 PDF 報告
5. 歷史管理
- 在「歷史記錄」頁面查看所有評審記錄
- 追蹤評分統計和趨勢
- 重新查看過往評審結果
🔍 核心功能詳解
AI 評分流程
- 內容提取：從 PPT/影片/網站中提取文字內容
- AI 分析：使用 Gemini AI 分析內容質量
- 標準對照：根據設定的評分標準進行評分
- 結果生成：產生詳細的評分報告和改進建議
PDF 報告生成
- 使用 Puppeteer 生成專業 PDF 報告
- 包含完整的評分結果、圖表和建議
- 支援中文排版和專業格式
- 可自定義報告樣式
文件處理能力
- PPTX 解析：提取幻燈片文字內容
- 影片支援：處理影片檔案上傳
- 網站分析：分析網站內容
- 多格式支援：支援多種文件格式
🛠️ 開發指南
添加新的評分標準
- 在資料庫中添加新的
criteria_items - 更新
criteriaNameToId映射 - 測試評分功能
自定義 AI 提示詞
修改 lib/services/gemini.ts 中的 buildScoringPrompt 方法
添加新的文件格式支援
- 在
GeminiService.extractPPTContent中添加新的解析邏輯 - 更新文件類型檢查
- 測試內容提取功能
自定義 PDF 模板
修改 lib/utils/html-pdf-generator.ts 中的 HTML 模板
🐛 故障排除
常見問題
1. Puppeteer Chrome 錯誤
Error: Could not find Chrome
解決方案：
npx puppeteer browsers install chrome
2. 資料庫連接失敗
檢查環境變數設定：
pnpm run db:test
3. Gemini API 錯誤
確認 API Key 是否正確設定：
pnpm run config:check
4. 文件上傳失敗
檢查文件大小和格式限制：
- 最大文件大小：100MB
- 支援格式：ppt, pptx, pdf, mp4, avi, mov, wmv, flv, webm
日誌調試
應用使用 console.log 輸出詳細的調試信息，可以在瀏覽器開發者工具和伺服器終端中查看。
📊 性能優化
資料庫優化
- 使用連接池管理資料庫連接
- 建立適當的索引提升查詢性能
- 使用事務確保數據一致性
AI 處理優化
- 實現請求超時機制
- 添加錯誤重試邏輯
- 優化提示詞減少 Token 消耗
前端優化
- 使用 React.memo 減少不必要的重新渲染
- 實現虛擬滾動處理大量數據
- 使用 Next.js 圖片優化
🔒 安全考量
數據安全
- 所有用戶輸入都經過驗證和清理
- 使用參數化查詢防止 SQL 注入
- 文件上傳限制和類型檢查
API 安全
- 實現請求頻率限制
- 添加身份驗證機制
- 敏感信息不在客戶端暴露
🤝 貢獻指南
- Fork 專案
- 創建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 開啟 Pull Request
📝 更新日誌
v1.0.0 (2024-01-15)
- ✨ 初始版本發布
- 🎯 支援 PPT/影片/網站連結上傳
- 🤖 整合 Gemini AI 評分
- 📊 完整的評分報告系統
- 📄 PDF 報告生成功能
📄 授權條款
本專案採用 MIT 授權條款 - 查看 LICENSE 文件了解詳情。
📞 技術支援
如有問題或建議，請：
- 提交 Issue
- 發送郵件至：your-email@example.com
- 查看 Wiki 獲取更多文檔
AI 智能評審系統 - 讓 AI 為您的內容提供專業評審 🚀