125 lines
2.4 KiB
Markdown
125 lines
2.4 KiB
Markdown
# 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 --admin-email=admin@quickquiz.local --admin-password=password --fresh
|
||
php artisan serve
|
||
```
|
||
|
||
默认管理员：
|
||
|
||
- 邮箱：`admin@quickquiz.local`
|
||
- 密码：`password`
|
||
|
||
## 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` 不作为答案来源。
|
||
- 解析允许为空。
|
||
- 同一题库内按题干、选项文本和正确标记去重。
|
||
- 重复题跳过；格式错误导致整批回滚。
|