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

README.md Unescape Escape

AI 智能評審系統

🚀 功能特色

核心功能

技術特色

🏗️ 技術架構

前端技術棧

後端技術棧

開發工具

📁 專案結構