# qbms

**Repository Path**: taj5/qbms

## Basic Information

- **Project Name**: qbms
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QBMS - 选煤领域题库管理系统

<div align="center">

**Question Bank Management System for Coal Preparation**

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![Vue](https://img.shields.io/badge/Vue-3.x-brightgreen.svg)](https://vuejs.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

---

## 📋 目录

- [项目概述](#项目概述)
- [快速开始](#快速开始)
- [技术栈](#技术栈)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [开发指南](#开发指南)
- [部署说明](#部署说明)
- [常见问题](#常见问题)

---

## 项目概述

QBMS（Question Bank Management System）是一个专为选煤领域设计的题库管理系统，支持问题与答案的全生命周期管理，包括存储、查阅、增删改、评分、评论以及数据导入导出功能。

### 核心功能

- ✅ **题目管理**: 创建、编辑、删除、查看题目
- ✅ **答案管理**: 支持 Markdown 格式的答案编辑
- ✅ **标签系统**: 灵活的标签分类和筛选
- ✅ **难度分级**: 简单、中等、困难三级难度
- ✅ **评分评论**: 用户可以对题目进行评分和评论
- ✅ **数据导入导出**: 支持 Excel/CSV 格式批量导入导出
- ✅ **回收站**: 软删除机制，支持恢复已删除题目
- ✅ **权限控制**: 基于角色的访问控制（RBAC）
- ✅ **统计分析**: 题目数量、难度分布等数据统计

---

## 快速开始

### 🚀 一键启动（推荐）

#### Windows 用户

**方法一：双击批处理文件**
```
双击 → start.bat    # 启动所有服务
双击 → stop.bat     # 停止所有服务
```

**方法二：PowerShell 命令行**
```powershell
.\start.ps1    # 启动
.\stop.ps1     # 停止
```

#### Mac/Linux 用户

```bash
chmod +x deploy.sh
./deploy.sh
```

### 🌐 访问地址

| 服务 | 地址 | 说明 |
|------|------|------|
| **前端界面** | http://localhost:5173 | 用户操作界面 |
| **后端API** | http://localhost:8000 | REST API 接口 |
| **API文档** | http://localhost:8000/docs | Swagger UI 交互式文档 |
| **健康检查** | http://localhost:8000/health | 服务状态检查 |

### 📦 Docker Compose 部署

```bash
# 配置环境变量
cp backend/.env.example backend/.env
# 编辑 .env 文件，修改数据库密码等配置

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 🔧 手动启动

#### 后端服务

```bash
cd backend

# 安装依赖
uv pip install -r requirements.txt

# 设置环境变量
export PYTHONPATH=$(pwd)  # Linux/Mac
$env:PYTHONPATH = (Get-Location).Path  # Windows PowerShell

# 启动服务
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

#### 前端服务

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

---

## 技术栈

### 后端技术

| 技术 | 版本 | 用途 |
|------|------|------|
| Python | 3.10+ | 编程语言 |
| FastAPI | 0.100+ | Web 框架 |
| SQLAlchemy | 2.0+ | ORM 框架 |
| Pydantic | 2.0+ | 数据验证 |
| MySQL | 8.0+ | 关系数据库 |
| Redis | 7.0+ | 缓存（可选） |
| JWT | - | 身份认证 |
| pytest | 7.4+ | 单元测试 |

### 前端技术

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue.js | 3.x | 前端框架 |
| Element Plus | 2.x | UI 组件库 |
| Pinia | 2.x | 状态管理 |
| Vue Router | 4.x | 路由管理 |
| Vite | 5.x | 构建工具 |
| Axios | 1.x | HTTP 客户端 |
| Markdown-it | - | Markdown 渲染 |

---

## 功能特性

### 1. 题目管理

- **CRUD 操作**: 完整的增删改查功能
- **Markdown 支持**: 题干和答案支持 Markdown 格式
- **难度分级**: 简单、中等、困难三个等级
- **标签系统**: 多标签分类，支持自定义标签
- **版本控制**: 题目修改历史追踪
- **软删除**: 回收站机制，可恢复误删题目

### 2. 答案管理

- **独立存储**: 答案与题目分离存储
- **双向关联**: 题目和答案互相引用
- **Markdown 渲染**: 支持代码块、列表、表格等
- **实时更新**: 编辑时即时预览

### 3. 评分与评论

- **星级评分**: 1-5 星评分系统
- **平均分数**: 自动计算题目平均分
- **评论功能**: 支持多级评论回复
- **评论统计**: 显示评论数量

### 4. 数据导入导出

- **Excel 支持**: 支持 .xlsx 格式
- **CSV 支持**: 支持 .csv 格式
- **批量操作**: 一次性导入多个题目
- **模板下载**: 提供标准导入模板
- **错误提示**: 详细的导入错误信息

### 5. 统计分析

- **题目统计**: 总数、各难度数量
- **标签统计**: 热门标签、使用频率
- **评分统计**: 平均分、评分分布
- **趋势分析**: 题目创建趋势图

### 6. 权限控制

- **角色管理**: 管理员、普通用户
- **JWT 认证**: Token 有效期 2 小时
- **RBAC 模型**: 基于角色的访问控制
- **操作审计**: 记录创建者和更新者

---

## 项目结构

```
qbms/
├── backend/                    # 后端项目
│   ├── app/
│   │   ├── api/               # API 路由
│   │   │   ├── auth.py        # 认证接口
│   │   │   ├── questions.py   # 题目接口
│   │   │   ├── tags.py        # 标签接口
│   │   │   └── import_export.py # 导入导出接口
│   │   ├── core/              # 核心配置
│   │   │   ├── config.py      # 配置文件
│   │   │   ├── database.py    # 数据库连接
│   │   │   └── security.py    # 安全模块
│   │   ├── models/            # 数据模型
│   │   │   └── __init__.py    # SQLAlchemy 模型
│   │   ├── schemas/           # Pydantic Schema
│   │   │   └── __init__.py    # 请求/响应模型
│   │   ├── services/          # 业务逻辑
│   │   │   ├── question_service.py
│   │   │   ├── auth_service.py
│   │   │   └── import_export_service.py
│   │   └── main.py            # 应用入口
│   ├── tests/                 # 测试文件
│   │   ├── conftest.py        # 测试配置
│   │   ├── test_auth.py       # 认证测试
│   │   ├── test_questions.py  # 题目测试
│   │   ├── test_tags.py       # 标签测试
│   │   ├── test_models.py     # 模型测试
│   │   ├── test_services.py   # 服务测试
│   │   └── test_import_export.py # 导入导出测试
│   ├── .env                   # 环境变量
│   ├── .env.example           # 环境变量示例
│   ├── requirements.txt       # Python 依赖
│   ├── pytest.ini             # 测试配置
│   └── uv.lock                # uv 锁定文件
├── frontend/                  # 前端项目
│   ├── src/
│   │   ├── api/               # API 调用
│   │   │   └── index.js       # API 封装
│   │   ├── components/        # 公共组件
│   │   ├── views/             # 页面组件
│   │   │   ├── Login.vue      # 登录页
│   │   │   ├── Layout.vue     # 布局组件
│   │   │   ├── QuestionList.vue # 题目列表
│   │   │   ├── QuestionForm.vue # 题目表单
│   │   │   ├── QuestionDetail.vue # 题目详情
│   │   │   ├── Statistics.vue # 统计页面
│   │   │   ├── Import.vue     # 导入页面
│   │   │   ├── TagManagement.vue # 标签管理
│   │   │   └── RecycleBin.vue # 回收站
│   │   ├── router/            # 路由配置
│   │   ├── store/             # 状态管理
│   │   ├── utils/             # 工具函数
│   │   ├── App.vue            # 根组件
│   │   └── main.js            # 入口文件
│   ├── public/                # 静态资源
│   ├── package.json           # Node 依赖
│   ├── vite.config.js         # Vite 配置
│   └── index.html             # HTML 模板
├── docker-compose.yml         # Docker 编排
├── Dockerfile.backend         # 后端 Dockerfile
├── Dockerfile.frontend        # 前端 Dockerfile
├── init.sql                   # 数据库初始化脚本
├── start.bat                  # Windows 启动脚本
├── start.ps1                  # PowerShell 启动脚本
├── stop.bat                   # Windows 停止脚本
├── stop.ps1                   # PowerShell 停止脚本
├── deploy.sh                  # Linux/Mac 部署脚本
├── deploy.ps1                 # PowerShell 部署脚本
├── .gitignore                 # Git 忽略配置
└── README.md                  # 项目文档
```

---

## 开发指南

### 环境要求

- **Python**: 3.10+
- **Node.js**: 18+
- **MySQL**: 8.0+
- **Redis**: 7.0+（可选）

### 后端开发

#### 1. 安装依赖

```bash
cd backend
uv pip install -r requirements.txt
```

#### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件
```

关键配置项：
```env
DATABASE_URL=mysql+pymysql://root:password@localhost:3306/qbms
SECRET_KEY=your-secret-key-here
ALLOWED_ORIGINS=http://localhost:5173
```

#### 3. 运行测试

```bash
# 运行所有测试
uv run pytest tests/ -v

# 运行特定测试文件
uv run pytest tests/test_questions.py -v

# 生成覆盖率报告
uv run pytest tests/ --cov=app --cov-report=html
```

#### 4. 启动开发服务器

```bash
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 前端开发

#### 1. 安装依赖

```bash
cd frontend
npm install
```

#### 2. 启动开发服务器

```bash
npm run dev
```

#### 3. 构建生产版本

```bash
npm run build
```

#### 4. 代码规范检查

```bash
npm run lint
```

### 数据库迁移

项目使用 SQLAlchemy ORM，无需手动迁移。首次启动时会自动创建表结构。

如需重置数据库：
```sql
DROP DATABASE IF EXISTS qbms;
CREATE DATABASE qbms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

---

## 部署说明

### Docker Compose 部署（推荐）

#### 1. 准备工作

```bash
# 克隆项目
git clone <repository-url>
cd qbms

# 配置环境变量
cp backend/.env.example backend/.env
```

#### 2. 修改配置

编辑 `backend/.env`：
```env
DATABASE_URL=mysql+pymysql://root:your_password@mysql:3306/qbms
SECRET_KEY=your-production-secret-key
ALLOWED_ORIGINS=http://your-domain.com
```

#### 3. 启动服务

```bash
docker-compose up -d
```

#### 4. 验证部署

```bash
# 检查容器状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 健康检查
curl http://localhost:8000/health
```

### 生产环境部署

#### 后端部署

```bash
# 安装依赖
uv pip install -r requirements.txt

# 使用 Gunicorn 启动
uv run gunicorn app.main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --access-logfile - \
  --error-logfile -
```

#### 前端部署

```bash
# 构建
npm run build

# 使用 Nginx 托管 dist 目录
```

Nginx 配置示例：
```nginx
server {
    listen 80;
    server_name your-domain.com;

    root /path/to/frontend/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 常见问题

### 1. 端口被占用

**问题**: 启动时提示端口 8000 或 5173 已被占用

**解决**:
```bash
# 查找占用端口的进程
netstat -ano | findstr :8000  # Windows
lsof -i :8000                  # Mac/Linux

# 终止进程
taskkill /F /PID <PID>        # Windows
kill -9 <PID>                  # Mac/Linux
```

### 2. 数据库连接失败

**问题**: 后端启动时提示数据库连接错误

**解决**:
1. 确认 MySQL 服务已启动
2. 检查 `backend/.env` 中的数据库配置
3. 确保数据库 `qbms` 已创建
4. 检查用户名和密码是否正确

### 3. CORS 错误

**问题**: 前端无法访问后端 API，提示 CORS 错误

**解决**:
1. 检查 `backend/.env` 中 `ALLOWED_ORIGINS` 包含前端地址
2. 确认 `frontend/vite.config.js` 代理配置正确
3. 清除浏览器缓存

### 4. Token 认证失败

**问题**: 登录后访问 API 提示 401 Unauthorized

**解决**:
1. 清除浏览器 localStorage
2. 重新登录获取新 Token
3. 检查 `SECRET_KEY` 配置是否一致

### 5. 依赖安装缓慢

**问题**: pip 或 npm 安装依赖速度很慢

**解决**:

**Python 国内镜像**:
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**Node.js 国内镜像**:
```bash
npm config set registry https://registry.npmmirror.com
npm install
```

### 6. bcrypt 版本冲突

**问题**: 导入 passlib 时提示 bcrypt 版本不兼容

**解决**:
```bash
uv pip install --force-reinstall bcrypt==4.0.1
```

### 7. Docker 构建缓慢

**问题**: Docker 镜像构建速度很慢

**解决**:
1. 配置 Docker 镜像加速器
2. 清理无用镜像: `docker system prune -a`
3. 使用 `.dockerignore` 排除不必要文件

---

## 运维命令

### Docker 相关

```bash
# 查看所有容器
docker-compose ps

# 查看日志
docker-compose logs -f [service-name]

# 重启服务
docker-compose restart [service-name]

# 进入容器
docker-compose exec backend bash
docker-compose exec mysql bash

# 备份数据库
docker-compose exec mysql mysqldump -u root -p qbms > backup.sql

# 恢复数据库
docker-compose exec -T mysql mysql -u root -p qbms < backup.sql

# 停止并清理
docker-compose down -v
```

### 健康检查

```bash
# 后端健康检查
curl http://localhost:8000/health

# 前端访问测试
curl http://localhost:5173

# API 文档访问
curl http://localhost:8000/docs
```

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 联系方式

- 项目主页: [GitHub Repository](https://github.com/your-username/qbms)
- 问题反馈: [Issues](https://github.com/your-username/qbms/issues)

---

<div align="center">

**Made with ❤️ for Coal Preparation Industry**

</div>