# 自動化AI考題系統

一個使用 Laravel 12 和 AI 技術建立的自動化考題管理和練習平台。

## 功能特性

### 1. 考試管理
- 建立和管理多個考試
- 為每個考試添加詳細說明
- 查看考試的所有題目

### 2. 題目管理
- 手動新增題目
- **批量導入題目**（支持 CSV、JSON、TXT 格式）
- 編輯和刪除題目
- 支持多種題目類型：選擇題、簡答題、論述題

### 3. AI 智能功能 🤖
- **自動生成答案**：AI 根據題目自動生成標準答案
- **自動生成解釋**：AI 提供詳細的解題步驟和知識點解釋
- 批量生成：導入題目時可選擇自動生成答案

### 4. 學生練習
- 線上練習考試
- 實時反饋（查看 AI 生成的詳解）
- 自動評分
- 查看成績和答題詳情

### 5. 認證系統
- 用戶註冊和登入
- 基於角色的訪問控制（建立者、學生）

## 安裝和設置

### 系統需求
- PHP >= 8.4.0
- MySQL 或 MariaDB
- Composer

### 安裝步驟

1. **複製項目**
```bash
git clone <repository-url>
cd exam
```

2. **安裝依賴**
```bash
composer install
```

3. **環境配置**
```bash
cp .env.example .env
php artisan key:generate
```

4. **配置數據庫**
編輯 `.env` 文件設置數據庫連接：
```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=exam_pake
DB_USERNAME=root
DB_PASSWORD=Steps@db2025
```

5. **運行遷移**
```bash
php artisan migrate
```

6. **生成示例數據（可選）**
```bash
php artisan db:seed
```

7. **啟動開發服務器**
```bash
php artisan serve
```

訪問 `http://localhost:8000`

## 使用指南

### 教師/管理員

#### 1. 建立考試
1. 登入系統
2. 點擊「建立考試」
3. 輸入考試名稱和描述

#### 2. 添加題目

**方式一：手動新增**
1. 進入考試詳情
2. 點擊「新增題目」
3. 輸入題目内容和選擇題目類型
4. 勾選「使用 AI 自動生成答案和解釋」（可選）
5. 提交

**方式二：批量導入** ⭐
1. 點擊「導入題目」
2. 選擇考試
3. 選擇文件並上傳（支持 CSV、JSON、TXT）
4. 勾選「自動使用 AI 生成答案」
5. 上傳導入

### 導入文件格式

#### CSV 格式
```csv
question_text,question_type
求解方程 2x + 3 = 7,short_answer
什麼是光合作用？,essay
```

頭行：`question_text,question_type`
- `question_text`：題目內容
- `question_type`：題目類型（multiple_choice, short_answer, essay）

#### JSON 格式
```json
{
  "questions": [
    {
      "text": "求解方程 2x + 3 = 7",
      "type": "short_answer"
    },
    {
      "text": "什麼是光合作用？",
      "type": "essay"
    }
  ]
}
```

#### TXT 格式
每行一道題目，預設為「簡答題」：
```
求解方程 2x + 3 = 7
什麼是光合作用？
Python 中的 for 迴圈如何使用？
```

### 學生

#### 參與練習
1. 登入系統
2. 點擊「練習考試」
3. 選擇一個考試
4. 逐題作答
5. 提交後查看成績和詳細解釋

## API 集成

### 配置 OpenAI API（用於 AI 功能）

1. 獲取 OpenAI API Key：https://platform.openai.com/api-keys
2. 編輯 `.env` 文件：
```
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
```

3. 編輯 `config/services.php`：
```php
'openai' => [
    'key' => env('OPENAI_API_KEY'),
],
```

## 數據库架構

### 主要表結構

- **users**：用戶帳號
- **exams**：考試信息
- **questions**：題目信息（包含 AI 生成的答案和解釋）
- **student_results**：學生成績
- **student_answers**：學生作答記錄

## 授權和策略

- **Exam Policy**：只有考試建立者才能編輯和刪除考試
- 所有認證用戶都可以查看和練習所有考試
- 任何用戶都可以建立新的考試

## 開發和擴展

### 主要文件結構
```
app/
├── Http/
│   └── Controllers/
│       ├── ExamController.php
│       ├── QuestionController.php
│       ├── StudentAnswerController.php
│       ├── ImportController.php
│       └── Auth/
├── Models/
│   ├── Exam.php
│   ├── Question.php
│   ├── StudentResult.php
│   └── StudentAnswer.php
├── Services/
│   └── AIAnswerGenerationService.php
└── Policies/
    └── ExamPolicy.php

routes/
├── web.php
└── auth.php

resources/views/
├── layouts/
├── exams/
├── questions/
├── practice/
├── import/
└── auth/

database/
├── migrations/
└── seeders/
```

## 故障排除

### 常見問題

1. **AI 功能不工作**
   - 檢查 OpenAI API Key 是否正確配置
   - 查看 `storage/logs/laravel.log` 中的錯誤

2. **導入文件失敗**
   - 確保文件格式正確
   - 檢查文件編碼為 UTF-8
   - 檢查文件大小小於 10MB

3. **數據庫連接錯誤**
   - 確認 MySQL 服務正在運行
   - 檢查 `.env` 中的數據庫配置
   - 確認數據庫已創建

## 貢獻和反饋

歡迎提交 Issue 和 Pull Request！

## 許可

MIT License

---

**系統地址**：http://pake-exam.steps.tw

**最後更新**：2026 年 3 月 18 日