# quiz

**Repository Path**: newsd/quiz

## Basic Information

- **Project Name**: quiz
- **Description**: 在线答题项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 在线答题系统（Quiz System）

[![Java](https://img.shields.io/badge/Java-17-ED8B00?logo=openjdk&logoColor=white)](https://www.oracle.com/java/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.x-6DB33F?logo=springboot&logoColor=white)](https://spring.io/projects/spring-boot)
[![Vue](https://img.shields.io/badge/Vue-3.4.x-42B883?logo=vue.js&logoColor=white)](https://vuejs.org/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?logo=mysql&logoColor=white)](https://www.mysql.com/)
[![Redis](https://img.shields.io/badge/Redis-7.x-DC382D?logo=redis&logoColor=white)](https://redis.io/)

> 一个完整的在线答题系统，包含**用户端 H5** 和**后台管理端 PC** 两个前端应用，共用一套 Spring Boot 3 后端服务。支持单选/多选即时判题、错题重做、收藏、学习统计、题库管理、题目 Excel 导入导出等功能。

---

## 📋 目录

- [技术栈](#-技术栈)
- [功能概览](#-功能概览)
- [系统架构](#-系统架构)
- [项目结构](#-项目结构)
- [数据库设计](#-数据库设计)
- [接口概览](#-接口概览)
- [认证与权限](#-认证与权限)
- [快速开始](#-快速开始)
- [开发路线图](#-开发路线图)
- [文档索引](#-文档索引)

---

## 🛠 技术栈

### 后端

| 技术 | 版本 | 用途 |
|---|---|---|
| JDK | 17 | 运行环境 |
| Spring Boot | 3.2.x | 核心框架 |
| Spring Security | 6.x | 认证鉴权 |
| MyBatis-Plus | 3.5.x | ORM 框架 |
| MySQL | 8.0.x | 关系型数据库 |
| Redis | 7.x | 缓存、Token 存储 |
| Druid | 1.2.x | 数据库连接池 |
| Knife4j | 4.x | 接口文档（OpenAPI 3） |
| EasyExcel | 3.3.x | Excel 导入导出 |
| Hutool | 5.8.x | 工具类库 |
| jjwt | 0.12.x | JWT 签发与解析 |

### 前端

| 技术 | 版本 | 用途 |
|---|---|---|
| Vue | 3.4.x | 前端框架 |
| Vite | 5.x | 构建工具 |
| Vue Router | 4.x | 路由管理 |
| Pinia | 2.x | 状态管理 |
| Axios | 1.x | HTTP 请求 |
| Element Plus | 2.x | 管理端 UI 组件 |
| Vant | 4.x | 用户端 UI 组件 |
| ECharts | 5.x | 图表展示 |
| UnoCSS / SCSS | - | 样式方案 |

---

## ✨ 功能概览

### 用户端（H5 移动端风格）

| 模块 | 功能 |
|---|---|
| 首页 | 题库列表浏览、热门标签、关键字搜索 |
| 答题 | 单选即时判题、多选提交判题、实时计时器、题目进度、上/下题切换 |
| 成绩页 | 得分圆环、正确率、答题时长、答对/答错数量 |
| 个人中心 | 用户信息卡片、学习数据总览（时长/题量/正确率）、答题数量设置 |
| 错题重做 | 逐题展示错题、标注正确答案与用户错误答案、支持从错题本移除 |
| 收藏夹 | 收藏题目列表、查看解析、取消收藏 |

### 管理端（PC 后台风格）

| 模块 | 功能 |
|---|---|
| 仪表盘 | 统计卡片（用户/题库/题目/答题数）、近 7 日趋势图、热门题库 TOP5 |
| 用户管理 | 用户列表、创建/编辑、封禁/解封、逻辑删除、Excel 导出 |
| 题库管理 | 题库 CRUD、上下线切换、逻辑删除 |
| 题目管理 | 题目 CRUD、选项管理、Excel 模板下载/批量导入/导出 |
| 答题管理 | 答题记录列表、详情查看、错题库、收藏夹、导出 |
| 系统设置 | 系统配置项管理、管理员信息/密码修改、操作日志查询 |

---

## 🏗 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                      客户端层                            │
│  ┌───────────────┐            ┌────────────────────┐    │
│  │  用户端 H5     │            │  后台管理端 PC      │    │
│  │  Vue3 + Vant  │            │  Vue3 + Element+   │    │
│  └───────┬───────┘            └─────────┬──────────┘    │
└──────────┼──────────────────────────────┼───────────────┘
           │  HTTPS / RESTful             │
           ▼                              ▼
┌─────────────────────────────────────────────────────────┐
│                    Nginx 反向代理                        │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│              Spring Boot 3 后端服务                      │
│  ┌────────────┐  ┌────────────┐  ┌────────────────┐    │
│  │ 认证过滤器  │→ │ Controller │→ │    Service     │    │
│  │  JWT/权限   │  │   层       │  │      层        │    │
│  └────────────┘  └────────────┘  └───────┬────────┘    │
│                                          │              │
│                                 ┌────────▼────────┐     │
│                                 │  MyBatis-Plus   │     │
│                                 └────────┬────────┘     │
└──────────────────────────────────────────┼──────────────┘
                                           │
                    ┌──────────────────────┼──────────────────┐
                    ▼                      ▼                  ▼
             ┌────────────┐         ┌────────────┐     ┌────────────┐
             │   MySQL8   │         │   Redis    │     │  文件存储   │
             │  业务数据   │         │ 缓存/Token │     │ 本地/OSS   │
             └────────────┘         └────────────┘     └────────────┘
```

### 后端模块划分

| 模块 | 职责 |
|---|---|
| `quiz-common` | 公共工具类、常量定义、统一响应体、全局异常 |
| `quiz-pojo` | 实体类（Entity）、数据传输对象（DTO）、视图对象（VO） |
| `quiz-mapper` | MyBatis-Plus Mapper 接口 |
| `quiz-service` | 业务逻辑实现 |
| `quiz-web` | Controller 控制层 + 启动类 + 配置类 |

---

## 📁 项目结构

### 当前已有文件（设计阶段）

```
quiz/
├── 第一版/                    # v1 原型 HTML
│   ├── admin.html
│   ├── answer.html
│   ├── index.html
│   └── profile.html
├── 第二版原型图/              # v2 原型 HTML
│   ├── admin.html
│   ├── answer.html
│   ├── index.html
│   └── profile.html
├── init.sql                   # 数据库建表脚本（10 张表）
├── 前后端开发步骤文档.md       # 30 Step 开发路线图
├── 前后端总体设计文档.md       # 技术选型 + 架构 + 功能设计
├── 后端接口文档.md             # 旧版接口文档
├── 后端接口文档2.0.md          # 最新版接口文档（69 个接口）
└── 数据库设计文档.md           # 10 张表详细设计
```

### 规划中的代码结构（待落地）

```
quiz/
├── quiz-backend/              # Spring Boot 3 多模块工程
│   ├── quiz-common/
│   ├── quiz-pojo/
│   ├── quiz-mapper/
│   ├── quiz-service/
│   ├── quiz-web/
│   │   ├── src/main/java/com/quiz/
│   │   │   ├── QuizApplication.java
│   │   │   ├── config/        # WebMvc / Security / MybatisPlus / Redis / Knife4j
│   │   │   ├── controller/    # user/ admin/ common/
│   │   │   ├── interceptor/
│   │   │   ├── handler/       # 全局异常处理
│   │   │   └── filter/        # JWT 过滤器
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       └── application-prod.yml
│   └── pom.xml
└── quiz-frontend/             # Vue 3 + Vite 单应用（含用户端 + 管理端）
    ├── src/
    │   ├── api/               # 接口封装
    │   ├── components/        # 公共组件
    │   ├── layouts/           # UserLayout / AdminLayout
    │   ├── router/            # user.routes / admin.routes
    │   ├── stores/            # Pinia: user / quiz / app
    │   ├── utils/             # request / auth / format
    │   ├── views/
    │   │   ├── user/          # Home / Quiz / Result / Profile / WrongBook / Favorite
    │   │   └── admin/         # Dashboard / UserManage / CategoryManage / QuestionManage / RecordManage / Setting
    │   ├── App.vue
    │   └── main.js
    ├── .env.development
    ├── .env.production
    ├── vite.config.js
    └── package.json
```

---

## 💾 数据库设计

### 表清单（共 10 张表）

| 表名 | 说明 | 关键字段 |
|---|---|---|
| `t_user` | 用户表 | username, password(BCrypt), role, status |
| `t_category` | 题库分类表 | name, icon, tag, question_count(冗余), answer_count(冗余) |
| `t_question` | 题目表 | category_id, type(1单选/2多选), content, correct_answer, difficulty |
| `t_question_option` | 题目选项表 | question_id, option_key(A/B/C/D), option_content |
| `t_answer_record` | 答题记录表（一次会话） | user_id, category_id, total_count, correct_count, accuracy, duration |
| `t_answer_detail` | 答题明细表（单题作答） | record_id, question_id, user_answer, correct_answer, is_correct |
| `t_wrong_question` | 错题表 | user_id + question_id（唯一约束）, wrong_count |
| `t_favorite` | 收藏表 | user_id + question_id（唯一约束） |
| `t_system_config` | 系统配置表 | config_key（唯一）, config_value（key-value 结构） |
| `t_operation_log` | 操作日志表 | module, operation, method, params, ip, duration, status |

### E-R 关系

```
t_user 1 ──── N t_answer_record 1 ──── N t_answer_detail
   │                    │                       │
   │                    N                       N
   │              t_category ──────────── t_question 1 ── N t_question_option
   │                    │                       │
   N                    N                       N
t_wrong_question ───────┘                       │
   N                                            │
t_favorite ─────────────────────────────────────┘
```

- 统一使用 `id`（BIGINT, AUTO_INCREMENT）作为主键
- 统一审计字段：`create_time`、`update_time`、`deleted`（逻辑删除）
- 字符集：`utf8mb4`，排序规则：`utf8mb4_general_ci`
- 初始化配置（`t_system_config`）：`default_question_count=5`、`enable_register=true`、`enable_answer_record=true`、`random_question_order=false`

建表 SQL 见 [init.sql](init.sql)，详细字段设计见 [数据库设计文档.md](数据库设计文档.md)。

---

## 🌐 接口概览

### 统一响应结构

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1716192000000
}
```

### 全局状态码

| code | 含义 | code | 含义 |
|---|---|---|---|
| 200 | 成功 | 403 | 无权限 |
| 400 | 参数错误 | 404 | 资源不存在 |
| 401 | 未登录 / Token 失效 | 500 | 服务器内部错误 |
| 1001 | 用户名已存在 | 1002 | 用户名或密码错误 |
| 2001 | 题库不存在 | 2002 | 题目不存在 |
| 3001 | 答题记录不存在 | 4001 | 配置项不存在 |

### 接口分布（共 69 个）

| 模块 | 接口数 | 路径前缀 |
|---|---|---|
| 认证（登录/注册/登出/刷新） | 5 | `/api/auth` |
| 用户（资料/密码/学习统计） | 5 | `/api/user` |
| 题库（用户端列表/详情/热门） | 3 | `/api/category` |
| 题目（随机抽题/收藏） | 4 | `/api/question` |
| 答题记录（提交/列表/错题/收藏/趋势） | 10 | `/api/record` |
| 管理端-仪表盘 | 4 | `/api/admin/dashboard` |
| 管理端-用户管理 | 8 | `/api/admin/user` |
| 管理端-题库管理 | 6 | `/api/admin/category` |
| 管理端-题目管理（含 Excel 导入导出） | 8 | `/api/admin/question` |
| 管理端-答题管理 | 5 | `/api/admin/record` |
| 管理端-系统设置 | 5 | `/api/admin/config` |
| 管理端-操作日志 | 3 | `/api/admin/log` |
| 文件上传 | 3 | `/api/file` |

完整接口文档见 [后端接口文档2.0.md](后端接口文档2.0.md)。

---

## 🔐 认证与权限

### JWT 认证流程

```
用户  ──POST /api/auth/login──▶  后端校验  ──生成 JWT──▶  Redis 存入 Token
 ▲                                                       │
 │    ◀──────── 返回 token + userInfo ─────────────────────┘
 │
请求 ──Header: Authorization: Bearer {token}──▶ JWT 过滤器解析──▶ SecurityContext
                                                        │
                                                        ▼
                                              Redis 校验 Token 是否有效
                                                        │
                                              ┌─────────┴─────────┐
                                              ▼                   ▼
                                         ✅ 放行请求          ❌ 返回 401
```

- Token 有效期：2 小时，存储于 Redis（`quiz:token:{userId}`）
- 支持 Token 刷新：`POST /api/auth/refresh`
- 登出：从 Redis 中删除 Token（黑名单机制）

### 角色定义

| 角色 | code | 说明 |
|---|---|---|
| 普通用户 | `USER` | 用户端 |
| VIP 用户 | `VIP` | 用户端（更多权益预留） |
| 管理员 | `ADMIN` | 后台管理端 |
| 超级管理员 | `SUPER_ADMIN` | 后台管理端（全部权限） |

### 权限控制

- **后端**：`@PreAuthorize("hasRole('ADMIN')")` 注解 + JWT 过滤器
- **前端**：路由守卫（`meta.requiresAuth` 校验登录，`meta.roles` 校验角色）

---

## 🚀 快速开始

### 环境要求

| 依赖 | 版本 |
|---|---|
| JDK | 17+ |
| Maven | 3.9+ |
| Node.js | 18+ |
| MySQL | 8.0+ |
| Redis | 7.x |

### 数据库初始化

```bash
# 1. 创建数据库并导入表结构
mysql -u root -p < init.sql

# 2. 插入系统配置初始化数据（SQL 待补充）
# 默认管理员账号：admin / 123456（密码需 BCrypt 加密）
```

### 后端启动（规划中）

```bash
cd quiz-backend
mvn clean install -DskipTests
cd quiz-web
mvn spring-boot:run
# 访问 http://localhost:8080/doc.html 打开 Knife4j 接口文档
```

### 前端启动（规划中）

```bash
cd quiz-frontend
pnpm install
pnpm dev
# 用户端：http://localhost:5173
# 管理端：http://localhost:5173/#/admin

# 开发（用户端和管理端共用）
cd d:\ai_project\quiz\quiz-frontend
npm run dev          # http://localhost:5173/#/home 用户端
                     # http://localhost:5173/#/admin/dashboard 管理端

# 生产构建（已验证通过 ✓ built in 46.32s）
npm run build

# 生产预览
npm run preview
```

### 缓存设计

| 缓存 Key | 说明 | 过期时间 |
|---|---|---|
| `quiz:token:{userId}` | 用户 JWT Token | 2h |
| `quiz:category:list` | 题库列表 | 30min |
| `quiz:question:{id}` | 题目详情 | 1h |
| `quiz:stats:dashboard` | 仪表盘统计 | 5min |
| `quiz:user:info:{userId}` | 用户信息 | 30min |

---

## 🗺 开发路线图

项目按 **30 个 Step** 推进开发，可分为四个阶段：

### 阶段一：后端基础建设（Step 0 ~ 7）

| Step | 内容 |
|---|---|
| 0 | 环境准备 + 前后端项目初始化 |
| 1 | 数据库设计与初始化 |
| 2 | 后端骨架搭建（统一响应、异常、Swagger） |
| 3 | 认证模块（登录/注册/JWT） |
| 4 | 用户模块 |
| 5 | 题库模块（用户端） |
| 6 | 题目模块（随机抽题/收藏） |
| 7 | 答题记录模块 |

### 阶段二：后端管理端（Step 8 ~ 15）

| Step | 内容 |
|---|---|
| 8 | 管理端-仪表盘 |
| 9 | 管理端-用户管理 |
| 10 | 管理端-题库管理 |
| 11 | 管理端-题目管理（含 Excel 导入导出） |
| 12 | 管理端-答题管理 |
| 13 | 管理端-系统设置 |
| 14 | 管理端-操作日志 |
| 15 | 文件上传模块 |

### 阶段三：前端用户端（Step 16 ~ 22）

| Step | 内容 |
|---|---|
| 16 | 前端项目初始化 |
| 17 | 前端通用封装（Axios/路由守卫/Pinia） |
| 18 | 用户端首页 |
| 19 | 用户端答题页 |
| 20 | 用户端成绩页 |
| 21 | 用户端个人中心 |
| 22 | 用户端错题重做 + 收藏夹 |

### 阶段四：前端管理端（Step 23 ~ 30）

| Step | 内容 |
|---|---|
| 23 | 管理端布局与路由 |
| 24 | 管理端仪表盘 |
| 25 | 管理端用户管理 |
| 26 | 管理端题库管理 |
| 27 | 管理端题目管理 |
| 28 | 管理端答题管理 |
| 29 | 管理端系统设置 + 日志 |
| 30 | 联调、测试与部署 |

每个 Step 包含目标、功能清单、接口清单、AI 提示词、完成标志，详见 [前后端开发步骤文档.md](前后端开发步骤文档.md)。

---

## 📚 文档索引

| 文档 | 说明 |
|---|---|
| [前后端总体设计文档.md](前后端总体设计文档.md) | 技术选型、系统架构、功能设计、缓存策略 |
| [后端接口文档2.0.md](后端接口文档2.0.md) | 69 个 RESTful 接口完整定义（推荐阅读） |
| [数据库设计文档.md](数据库设计文档.md) | 10 张表字段设计、索引、E-R 关系 |
| [init.sql](init.sql) | MySQL 8 建表脚本 |
| [前后端开发步骤文档.md](前后端开发步骤文档.md) | 30 Step 开发路线图（含 AI 提示词） |
| [后端接口文档.md](后端接口文档.md) | 旧版接口文档（供参考） |
| 第一版/ | v1 原型 HTML |
| 第二版原型图/ | v2 原型 HTML |

---

## 📄 License

MIT License