448 lines
12 KiB
Markdown
448 lines
12 KiB
Markdown
# 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 <repository-url>
|
||
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 為您的內容提供專業評審 🚀 |