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

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

编辑 .env 中的 MySQL 配置：

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

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

DB_PASSWORD=root

创建数据库后执行：

php artisan quickquiz:install --fresh
php artisan serve

默认管理员：

• 邮箱：admin@example.com
• 密码：123456

Frontend Setup

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 路由。

访问路径：

http://127.0.0.1:8000/apidoc

Testing

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

CREATE DATABASE quickquiz_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

然后执行：

php artisan test

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

Verification Commands

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

Import Format

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

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

导入规则：

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