# QuickQuiz

QuickQuiz 是一个前后端分离题库系统。后端为 Laravel + MySQL + JWT + hg/apidoc 注解路由，前端为 Vue 3 + Vite + TypeScript + Element Plus + UnoCSS + Pinia。

 ## Requirements

- PHP 8.3+
- Composer 2+
- MySQL 8 或兼容版本
- Node.js 22+
- npm 10+

## Backend Setup

```bash
composer install
copy .env.example .env
php artisan key:generate
php artisan jwt:secret --force
```

编辑 `.env` 中的 MySQL 配置：

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=quickquiz
DB_USERNAME=root
DB_PASSWORD=
```

phpStudy 默认 MySQL 密码常见为 `root`，如果连接失败请改为：

```env
DB_PASSWORD=root
```

创建数据库后执行：

```bash
php artisan quickquiz:install --fresh
php artisan serve
```

默认管理员：

- 邮箱：`admin@example.com`
- 密码：`123456`

## Frontend Setup

```bash
cd frontend
npm install
npm run dev
```

前端默认代理：

- `/api` -> `http://127.0.0.1:8000`
- `/apidoc` -> `http://127.0.0.1:8000`

## API Documentation

控制器使用 `hg/apidoc` 注解描述 URL、Method、分组和标题。项目额外提供 `App\Providers\ApidocRouteServiceProvider`，用于兼容 Laravel 13 下 `RouteMiddleware` 注解解析结构，并按注解自动注册业务 API 路由。

访问路径：

```text
http://127.0.0.1:8000/apidoc
```

## Testing

本项目测试按 MySQL 配置，默认测试库为 `quickquiz_test`。先创建测试库：

```sql
CREATE DATABASE quickquiz_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

然后执行：

```bash
php artisan test
```

当前环境如果没有启动 MySQL，数据库迁移和 Feature 测试会失败。

## Verification Commands

```bash
php artisan route:list --path=api
vendor\bin\pint --test
cd frontend
npm run build
```

## Import Format

当前 `question.json` 支持如下数组格式：

```json
[
  {
    "questionId": "405323271",
    "questionText": "题干",
    "answerCorrect": true,
    "options": [
      { "text": "选项 A", "correct": false },
      { "text": "选项 B", "correct": true }
    ]
  }
]
```

导入规则：

- 根据正确选项数量识别单选/多选。
- 两个选项且文本为“对/错”时识别判断题。
- `answerCorrect` 不作为答案来源。
- 解析允许为空。
- 同一题库内按题干、选项文本和正确标记去重。
- 重复题跳过；格式错误导致整批回滚。