# 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 為您的內容提供專業評審 🚀