# 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 個評分項目： 1. **內容品質** (25%) - 內容的準確性、完整性和專業度 2. **視覺設計** (20%) - 版面設計、色彩搭配和視覺效果 3. **邏輯結構** (20%) - 內容組織的邏輯性和條理性 4. **創新性** (15%) - 創意思維和獨特觀點的展現 5. **實用性** (20%) - 內容的實際應用價值和可操作性 ## 🔧 安裝與設定 ### 環境需求 - Node.js 18+ - pnpm 8+ - MySQL 8.0+ - Chrome 瀏覽器 (用於 PDF 生成) ### 1. 克隆專案 ```bash git clone cd ai-scoring-application ``` ### 2. 安裝依賴 ```bash pnpm install ``` ### 3. 環境變數設定 複製 `env.example` 為 `.env.local` 並設定以下變數： ```env # 應用配置 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. 資料庫初始化 ```bash # 初始化資料庫結構 pnpm run db:init # 測試資料庫連接 pnpm run db:test # 檢查配置 pnpm run config:check ``` ### 5. 安裝 Puppeteer Chrome ```bash npx puppeteer browsers install chrome ``` ### 6. 啟動開發伺服器 ```bash pnpm run dev ``` 應用將在 `http://localhost:12024` 啟動。 ## 🚀 部署 ### Vercel 部署 1. 將專案推送到 GitHub 2. 在 Vercel 中導入專案 3. 設定環境變數 4. 部署完成 ### 自託管部署 ```bash # 建構專案 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 評分流程 1. **內容提取**：從 PPT/影片/網站中提取文字內容 2. **AI 分析**：使用 Gemini AI 分析內容質量 3. **標準對照**：根據設定的評分標準進行評分 4. **結果生成**：產生詳細的評分報告和改進建議 ### PDF 報告生成 - 使用 Puppeteer 生成專業 PDF 報告 - 包含完整的評分結果、圖表和建議 - 支援中文排版和專業格式 - 可自定義報告樣式 ### 文件處理能力 - **PPTX 解析**：提取幻燈片文字內容 - **影片支援**：處理影片檔案上傳 - **網站分析**：分析網站內容 - **多格式支援**：支援多種文件格式 ## 🛠️ 開發指南 ### 添加新的評分標準 1. 在資料庫中添加新的 `criteria_items` 2. 更新 `criteriaNameToId` 映射 3. 測試評分功能 ### 自定義 AI 提示詞 修改 `lib/services/gemini.ts` 中的 `buildScoringPrompt` 方法 ### 添加新的文件格式支援 1. 在 `GeminiService.extractPPTContent` 中添加新的解析邏輯 2. 更新文件類型檢查 3. 測試內容提取功能 ### 自定義 PDF 模板 修改 `lib/utils/html-pdf-generator.ts` 中的 HTML 模板 ## 🐛 故障排除 ### 常見問題 #### 1. Puppeteer Chrome 錯誤 ``` Error: Could not find Chrome ``` **解決方案**： ```bash npx puppeteer browsers install chrome ``` #### 2. 資料庫連接失敗 檢查環境變數設定： ```bash pnpm run db:test ``` #### 3. Gemini API 錯誤 確認 API Key 是否正確設定： ```bash 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 安全 - 實現請求頻率限制 - 添加身份驗證機制 - 敏感信息不在客戶端暴露 ## 🤝 貢獻指南 1. Fork 專案 2. 創建功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 開啟 Pull Request ## 📝 更新日誌 ### v1.0.0 (2024-01-15) - ✨ 初始版本發布 - 🎯 支援 PPT/影片/網站連結上傳 - 🤖 整合 Gemini AI 評分 - 📊 完整的評分報告系統 - 📄 PDF 報告生成功能 ## 📄 授權條款 本專案採用 MIT 授權條款 - 查看 [LICENSE](LICENSE) 文件了解詳情。 ## 📞 技術支援 如有問題或建議，請： - 提交 [Issue](https://github.com/your-repo/issues) - 發送郵件至：your-email@example.com - 查看 [Wiki](https://github.com/your-repo/wiki) 獲取更多文檔 --- **AI 智能評審系統** - 讓 AI 為您的內容提供專業評審 🚀