# FastQA
**Repository Path**: junluoyu/FastQA
## Basic Information
- **Project Name**: FastQA
- **Description**: 一个功能强大的现代化问卷调查系统,支持多种题型、逻辑跳转、智能防作弊和数据分析
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 14
- **Forks**: 0
- **Created**: 2025-12-07
- **Last Updated**: 2025-12-12
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# FastQA - 问卷调查系统
**[中文](#中文文档) | [English](#english-documentation)**
一个功能强大的现代化问卷调查系统,支持多种题型、逻辑跳转、智能防作弊和数据分析
A powerful modern questionnaire survey system with multiple question types, logic jumping, smart anti-cheating, and data analysis
[](https://fastapi.tiangolo.com)
[](https://vuejs.org)
[](https://www.postgresql.org)
[](LICENSE)
---
## 中文文档
### 📋 目录
- [项目简介](#项目简介)
- [核心功能](#核心功能)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [功能详解](#功能详解)
- [API文档](#api文档)
- [部署指南](#部署指南)
- [贡献指南](#贡献指南)
---
### 项目简介
FastQA是一个基于FastAPI + Vue 3构建的全功能问卷调查系统,提供从问卷创建、发布、答题到数据分析的完整解决方案。系统采用现代化的前后端分离架构,支持灵活的题型配置、智能的逻辑跳转、完善的防作弊机制,适用于教育考试、市场调研、满意度调查等多种场景。
**核心特点**:
- 🎨 拖拽式可视化问卷编辑器
- 🧠 智能逻辑跳转和题目关联
- 🔒 多重防作弊机制(设备指纹、IP限制、时间控制)
- 📊 实时统计分析和多格式数据导出
- 📱 响应式设计,支持PC和移动端
- 🎲 AB卷机制,题目和选项随机化
- 📐 LaTeX数学公式渲染支持
- 📖 错题本和答题记录管理
---
### 核心功能
#### 1. 问卷管理
- ✅ **多类型支持**: 问卷(survey)、试卷(exam)、题库(bank)三种类型
- ✅ **拖拽编辑**: 可视化拖拽式问卷编辑器,支持实时预览
- ✅ **批量导入**: 支持Excel、JSON批量导入题目
- ✅ **模板系统**: 内置常用模板,快速创建问卷
- ✅ **分组管理**: 支持题目分组(section)和分页显示
#### 2. 丰富的题型
- ✅ **选择题**: 单选、多选、下拉选择
- ✅ **填空题**: 单行文本、多行文本、数字输入
- ✅ **判断题**: 是非判断
- ✅ **评分题**: 星级评分、滑块评分
- ✅ **特殊题型**: 矩阵题、图片选择、地理定位、转盘抽奖
#### 3. 智能逻辑跳转
- ✅ **条件跳转**: 根据答案跳转到指定题目
- ✅ **显示控制**: 根据条件显示/隐藏题目
- ✅ **分数计算**: 自动计算总分和单题得分
- ✅ **复杂规则**: 支持AND/OR组合条件
#### 4. 防作弊机制
- ✅ **设备指纹**: 浏览器指纹识别,防止重复答题
- ✅ **IP限制**: IP地址记录和限制
- ✅ **时间控制**: 答题时间限制和有效期设置
- ✅ **答题次数**: 限制单个用户答题次数
- ✅ **随机化**: 题目和选项顺序随机打乱(AB卷)
#### 5. 数据统计与分析
- ✅ **实时统计**: 提交数量、完成率实时展示
- ✅ **图表分析**: ECharts可视化数据分布
- ✅ **交叉分析**: 多维度数据交叉对比
- ✅ **数据导出**: 支持CSV、Excel、宽表格式导出
- ✅ **答题详情**: 查看单个用户的详细答题记录
#### 6. 用户体验
- ✅ **响应式设计**: 自适应PC、平板、手机
- ✅ **进度保存**: 自动保存答题进度,防止数据丢失
- ✅ **题目导航**: 快速跳转到任意题目
- ✅ **公式渲染**: 支持LaTeX数学公式显示
- ✅ **二维码分享**: 生成问卷二维码,便于分享
#### 7. 权限与安全
- ✅ **用户认证**: JWT Token认证,支持Token自动刷新
- ✅ **访问控制**: 公开/密码访问/需登录三种模式
- ✅ **权限管理**: 问卷创建者拥有完全控制权
- ✅ **数据加密**: 敏感数据加密存储
- ✅ **审计日志**: 完整的操作日志记录
#### 8. 其他功能
- ✅ **错题本**: 自动收集错题,支持筛选和查看
- ✅ **个人中心**: 我的问卷、我的答题记录
- ✅ **文件上传**: 支持图片、文件上传(OSS存储)
- ✅ **地图定位**: 高德地图集成,获取答题位置
- ✅ **多语言**: 中英文界面切换(规划中)
---
### 技术栈
#### 后端技术
| 技术 | 版本 | 说明 |
|------|------|------|
| Python | 3.9+ | 编程语言 |
| FastAPI | 0.104.1 | Web框架 |
| SQLAlchemy | 2.0.23 | ORM框架 |
| Alembic | 1.12.1 | 数据库迁移工具 |
| PostgreSQL | 16 | 关系型数据库 |
| Pydantic | 2.5.0 | 数据验证 |
| python-jose | 3.3.0 | JWT认证 |
| Uvicorn | 0.24.0 | ASGI服务器 |
#### 前端技术
| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.24 | 前端框架 |
| Vue Router | 4.2.5 | 路由管理 |
| Pinia | 2.1.7 | 状态管理 |
| Ant Design Vue | 4.1.0 | UI组件库 |
| Vite | 5.0.0 | 构建工具 |
| Axios | 1.6.2 | HTTP客户端 |
| ECharts | 6.0.0 | 图表库 |
| KaTeX | 0.16.25 | 数学公式渲染 |
| VueDraggable | 4.1.0 | 拖拽功能 |
| XLSX | 0.18.5 | Excel处理 |
| QRCode.vue | 3.6.0 | 二维码生成 |
#### 数据库设计
- **users**: 用户表
- **questionnaires**: 问卷表
- **sections**: 题目分组表
- **questions**: 题目表
- **submissions**: 答题记录表
- **answers**: 答案表
---
### 快速开始
#### 前置要求
- Python 3.9+
- Node.js 16+
- PostgreSQL 12+
#### 1. 克隆项目
```bash
git clone https://gitee.com/junluoyu/FastQA
cd FastQA
```
#### 2. 后端配置
**安装依赖**:
```bash
cd backend
pip install -r requirements.txt
```
**配置数据库**:
```bash
# 修改 backend/.env 文件
DATABASE_URL=postgresql://user:password@host:port/database
SECRET_KEY=your-secret-key-here
```
**运行数据库迁移**:
```bash
cd backend
alembic upgrade head
```
**启动后端服务**:
```bash
cd backend
python -m uvicorn app.main:app --host 0.0.0.0 --port 20010
```
后端服务运行在: http://localhost:20010
#### 3. 前端配置
**安装依赖**:
```bash
cd frontend
npm install
```
**配置代理** (frontend/vite.config.js):
```javascript
server: {
proxy: {
'/api': {
target: 'http://localhost:20010',
changeOrigin: true
}
}
}
```
**启动前端服务**:
```bash
cd frontend
npm run dev
```
前端服务运行在: http://localhost:20011
#### 4. 使用启动脚本 (推荐)
项目提供了便捷的启动脚本:
```bash
# 显示帮助信息
./start.sh -h
# 启动后端
./start.sh -b
# 启动前端
./start.sh -f
# 重启后端
./start.sh -rb
# 重启前端
./start.sh -rf
# 停止所有服务
./start.sh -s
```
#### 5. 访问系统
- **前端页面**: http://localhost:20011
- **API文档**: http://localhost:20010/docs
- **ReDoc**: http://localhost:20010/redoc
**默认管理员账号** (首次运行会自动创建):
- 用户名: admin
- 密码: 请查看后端日志
---
### 项目结构
```
FastQA/
├── backend/ # 后端项目
│ ├── app/
│ │ ├── api/
│ │ │ └── v1/
│ │ │ ├── endpoints/ # API端点
│ │ │ │ ├── auth.py # 认证接口
│ │ │ │ ├── questionnaires.py # 问卷管理
│ │ │ │ ├── sections.py # 题目分组
│ │ │ │ ├── questions.py # 题目管理
│ │ │ │ ├── submissions.py # 答题记录
│ │ │ │ ├── statistics.py # 数据统计
│ │ │ │ ├── upload.py # 文件上传
│ │ │ │ └── wrong_questions.py # 错题本
│ │ │ └── router.py # 路由汇总
│ │ ├── core/ # 核心配置
│ │ │ ├── config.py # 应用配置
│ │ │ ├── database.py # 数据库连接
│ │ │ └── security.py # 安全认证
│ │ ├── models/ # 数据库模型
│ │ │ ├── user.py
│ │ │ ├── questionnaire.py
│ │ │ ├── section.py
│ │ │ ├── question.py
│ │ │ ├── submission.py
│ │ │ └── answer.py
│ │ ├── schemas/ # Pydantic模型
│ │ ├── utils/ # 工具函数
│ │ └── main.py # 应用入口
│ ├── alembic/ # 数据库迁移
│ └── requirements.txt # Python依赖
│
├── frontend/ # 前端项目
│ ├── src/
│ │ ├── api/ # API封装
│ │ │ ├── auth.js
│ │ │ ├── questionnaire.js
│ │ │ └── wrongbook.js
│ │ ├── assets/ # 静态资源
│ │ ├── components/ # Vue组件
│ │ │ ├── Sidebar.vue # 侧边栏
│ │ │ ├── QuestionEditor.vue # 题目编辑器
│ │ │ ├── QuestionRenderer.vue # 题目渲染器
│ │ │ └── ...
│ │ ├── router/ # 路由配置
│ │ ├── stores/ # Pinia状态管理
│ │ ├── utils/ # 工具函数
│ │ │ ├── request.js # Axios配置
│ │ │ └── deviceFingerprint.js # 设备指纹
│ │ ├── views/ # 页面组件
│ │ │ ├── Login.vue # 登录页
│ │ │ ├── Register.vue # 注册页
│ │ │ ├── QuestionnaireList.vue # 问卷列表
│ │ │ ├── QuestionnaireCreate.vue # 创建问卷
│ │ │ ├── QuestionnaireEdit.vue # 编辑问卷
│ │ │ ├── QuestionnaireFill.vue # 答题页(PC)
│ │ │ ├── MobileFill.vue # 答题页(移动)
│ │ │ ├── SubmissionResult.vue # 答题结果
│ │ │ ├── QuestionnaireStatistics.vue # 统计分析
│ │ │ ├── MySubmissions.vue # 我的答题
│ │ │ ├── WrongBook.vue # 错题本
│ │ │ └── ...
│ │ ├── App.vue
│ │ └── main.js
│ ├── package.json
│ └── vite.config.js
│
├── start.sh # 启动脚本
├── README.md # 项目说明
├── API_DOCUMENT.md # API文档
├── TASKS.md # 任务清单
└── LICENSE # 许可证
```
---
### 功能详解
#### 1. 问卷编辑器
**拖拽式编辑**:
- 从题型库拖拽题目到画布
- 拖拽调整题目顺序
- 支持题目复制、删除
- 实时预览效果
**题目配置**:
- 题目标题和描述
- 必填/选填设置
- 分值设置(试卷模式)
- 正确答案设置(试卷模式)
- 逻辑跳转规则
- 选项随机化
**批量导入**:
```javascript
// Excel导入示例
题号 | 题型 | 题目 | 选项A | 选项B | 选项C | 选项D | 正确答案
1 | single_choice | 1+1=? | 1 | 2 | 3 | 4 | B
2 | multiple_choice | 偶数有? | 1 | 2 | 3 | 4 | B,D
```
#### 2. 逻辑跳转
**跳转规则配置**:
```json
{
"condition": "and",
"rules": [
{
"question_id": 1,
"operator": "equals",
"value": "A"
}
],
"action": {
"type": "jump",
"target": 5
}
}
```
**支持的操作**:
- `equals`: 等于
- `not_equals`: 不等于
- `contains`: 包含
- `greater_than`: 大于
- `less_than`: 小于
#### 3. 防作弊机制
**设备指纹生成**:
```javascript
// 基于多种浏览器特征生成唯一标识
const fingerprint = CryptoJS.MD5(
navigator.userAgent +
screen.width + screen.height +
navigator.language +
// ... 更多特征
).toString()
```
**防重复提交检查**:
- 设备指纹 + IP + 24小时时间窗口
- 可配置允许答题次数
- 超过限制自动拒绝
#### 4. 数据统计
**统计维度**:
- 总提交数、完成率
- 平均分、最高分、最低分
- 各题正确率
- 选项分布图表
- 答题时长分布
**导出格式**:
- **长表格式**: 每行一个答案
- **宽表格式**: 每行一份答卷,所有答案横向排列
- **Excel**: 带格式和图表
- **CSV**: 纯数据,便于导入其他系统
---
### API文档
#### 认证接口
**用户注册**
```http
POST /api/v1/auth/register
Content-Type: application/json
{
"username": "user123",
"email": "user@example.com",
"password": "password123"
}
```
**用户登录**
```http
POST /api/v1/auth/login
Content-Type: application/json
{
"username": "user123",
"password": "password123"
}
Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"user": {
"id": 1,
"username": "user123",
"email": "user@example.com"
}
}
```
#### 问卷接口
**创建问卷**
```http
POST /api/v1/questionnaires/
Authorization: Bearer
Content-Type: application/json
{
"title": "满意度调查",
"description": "请填写您的满意度",
"questionnaire_type": "survey",
"is_public": true,
"require_login": false
}
```
**获取问卷列表**
```http
GET /api/v1/questionnaires/?skip=0&limit=10&questionnaire_type=survey
Authorization: Bearer
```
**提交答案**
```http
POST /api/v1/questionnaires/{id}/submit
Content-Type: application/json
{
"answers": [
{
"question_id": 1,
"answer_value": "A"
},
{
"question_id": 2,
"answer_value": ["A", "C"]
}
],
"device_fingerprint": "abc123...",
"start_time": "2024-01-01T10:00:00"
}
```
完整API文档请访问: http://localhost:20010/docs
---
### 部署指南
#### 生产环境部署
**1. 使用Docker Compose**
```yaml
# docker-compose.yml
version: '3.8'
services:
postgres:
image: postgres:16
environment:
POSTGRES_DB: fastqa
POSTGRES_USER: fastqa
POSTGRES_PASSWORD: your_password
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
backend:
build: ./backend
ports:
- "20010:20010"
environment:
DATABASE_URL: postgresql://fastqa:your_password@postgres:5432/fastqa
SECRET_KEY: your-production-secret-key
depends_on:
- postgres
frontend:
build: ./frontend
ports:
- "20011:20011"
depends_on:
- backend
volumes:
postgres_data:
```
**2. Nginx反向代理**
```nginx
# /etc/nginx/sites-available/fastqa
server {
listen 80;
server_name your-domain.com;
# 前端
location / {
proxy_pass http://localhost:20011;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# 后端API
location /api {
proxy_pass http://localhost:20010;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# API文档
location /docs {
proxy_pass http://localhost:20010/docs;
}
}
```
**3. 生产环境配置清单**
- [ ] 修改SECRET_KEY为随机强密码
- [ ] 配置CORS允许的域名
- [ ] 启用HTTPS (Let's Encrypt)
- [ ] 配置数据库备份
- [ ] 设置日志轮转
- [ ] 配置监控告警
- [ ] 限制API请求频率
- [ ] 配置CDN加速静态资源
---
### 贡献指南
欢迎贡献代码、提交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
**代码规范**:
- Python: 遵循PEP 8
- JavaScript: 使用ESLint
- 提交信息: 遵循Conventional Commits
---
### 许可证
本项目采用 [MIT License](LICENSE) 开源协议。
---
### 联系方式
- 问题反馈: [GitHub Issues](https://github.com/your-repo/issues)
- 技术交流: 欢迎提交Issue或PR
---
## English Documentation
### 📋 Table of Contents
- [Introduction](#introduction)
- [Key Features](#key-features)
- [Tech Stack](#tech-stack)
- [Quick Start](#quick-start)
- [Project Structure](#project-structure-en)
- [Deployment](#deployment)
- [Contributing](#contributing)
---
### Introduction
FastQA is a full-featured questionnaire survey system built with FastAPI + Vue 3, providing a complete solution from questionnaire creation, publishing, answering to data analysis. The system adopts modern front-end and back-end separation architecture, supports flexible question type configuration, intelligent logic jumping, and comprehensive anti-cheating mechanisms, suitable for various scenarios such as educational examinations, market research, and satisfaction surveys.
**Key Highlights**:
- 🎨 Drag-and-drop visual questionnaire editor
- 🧠 Intelligent logic jumping and question association
- 🔒 Multiple anti-cheating mechanisms (device fingerprint, IP restriction, time control)
- 📊 Real-time statistical analysis and multi-format data export
- 📱 Responsive design, supporting PC and mobile
- 🎲 A/B test mechanism, randomized questions and options
- 📐 LaTeX mathematical formula rendering support
- 📖 Wrong question book and answer record management
---
### Key Features
#### 1. Questionnaire Management
- ✅ **Multiple Types**: Survey, Exam, Question Bank
- ✅ **Drag-and-Drop Editor**: Visual drag-and-drop editor with real-time preview
- ✅ **Batch Import**: Support Excel and JSON batch import
- ✅ **Template System**: Built-in common templates for quick creation
- ✅ **Group Management**: Support question grouping (sections) and pagination
#### 2. Rich Question Types
- ✅ **Choice Questions**: Single choice, multiple choice, dropdown
- ✅ **Fill-in Questions**: Single line text, multi-line text, number input
- ✅ **True/False Questions**: Yes/No judgment
- ✅ **Rating Questions**: Star rating, slider rating
- ✅ **Special Types**: Matrix, image selection, geolocation, wheel lottery
#### 3. Intelligent Logic Jumping
- ✅ **Conditional Jump**: Jump to specified questions based on answers
- ✅ **Display Control**: Show/hide questions based on conditions
- ✅ **Score Calculation**: Automatic calculation of total and individual scores
- ✅ **Complex Rules**: Support AND/OR combination conditions
#### 4. Anti-Cheating Mechanism
- ✅ **Device Fingerprint**: Browser fingerprint recognition to prevent duplicate answers
- ✅ **IP Restriction**: IP address recording and restriction
- ✅ **Time Control**: Answer time limit and validity period setting
- ✅ **Answer Limit**: Limit the number of answers per user
- ✅ **Randomization**: Random shuffling of questions and options (A/B test)
#### 5. Data Statistics & Analysis
- ✅ **Real-time Statistics**: Real-time display of submissions and completion rate
- ✅ **Chart Analysis**: ECharts visualization of data distribution
- ✅ **Cross Analysis**: Multi-dimensional data cross comparison
- ✅ **Data Export**: Support CSV, Excel, wide-format export
- ✅ **Answer Details**: View detailed answer records of individual users
#### 6. User Experience
- ✅ **Responsive Design**: Adaptive to PC, tablet, and mobile
- ✅ **Progress Saving**: Auto-save answer progress to prevent data loss
- ✅ **Question Navigation**: Quick jump to any question
- ✅ **Formula Rendering**: Support LaTeX mathematical formula display
- ✅ **QR Code Sharing**: Generate questionnaire QR code for easy sharing
---
### Tech Stack
#### Backend
- **Framework**: FastAPI 0.104.1
- **ORM**: SQLAlchemy 2.0.23
- **Migration**: Alembic 1.12.1
- **Database**: PostgreSQL 16
- **Authentication**: JWT (python-jose)
- **Validation**: Pydantic 2.5.0
#### Frontend
- **Framework**: Vue 3.5.24
- **Router**: Vue Router 4.2.5
- **State**: Pinia 2.1.7
- **UI**: Ant Design Vue 4.1.0
- **Build**: Vite 5.0.0
- **HTTP**: Axios 1.6.2
- **Charts**: ECharts 6.0.0
- **Math**: KaTeX 0.16.25
---
### Quick Start
#### Prerequisites
- Python 3.9+
- Node.js 16+
- PostgreSQL 12+
#### 1. Clone Repository
```bash
git clone
cd FastQA
```
#### 2. Backend Setup
**Install Dependencies**:
```bash
cd backend
pip install -r requirements.txt
```
**Configure Database** (backend/.env):
```bash
DATABASE_URL=postgresql://user:password@host:port/database
SECRET_KEY=your-secret-key-here
```
**Run Migrations**:
```bash
cd backend
alembic upgrade head
```
**Start Backend**:
```bash
cd backend
python -m uvicorn app.main:app --host 0.0.0.0 --port 20010
```
Backend runs at: http://localhost:20010
#### 3. Frontend Setup
**Install Dependencies**:
```bash
cd frontend
npm install
```
**Start Frontend**:
```bash
cd frontend
npm run dev
```
Frontend runs at: http://localhost:20011
#### 4. Using Start Script (Recommended)
```bash
# Show help
./start.sh -h
# Start backend
./start.sh -b
# Start frontend
./start.sh -f
# Restart backend
./start.sh -rb
# Stop all services
./start.sh -s
```
#### 5. Access System
- **Frontend**: http://localhost:20011
- **API Docs**: http://localhost:20010/docs
- **ReDoc**: http://localhost:20010/redoc
---
### Project Structure (EN)
```
FastQA/
├── backend/ # Backend application
│ ├── app/
│ │ ├── api/v1/endpoints/ # API endpoints
│ │ ├── core/ # Core configurations
│ │ ├── models/ # Database models
│ │ ├── schemas/ # Pydantic schemas
│ │ └── main.py # Application entry
│ ├── alembic/ # Database migrations
│ └── requirements.txt # Python dependencies
│
├── frontend/ # Frontend application
│ ├── src/
│ │ ├── api/ # API wrappers
│ │ ├── components/ # Vue components
│ │ ├── router/ # Router configuration
│ │ ├── stores/ # Pinia stores
│ │ ├── views/ # Page components
│ │ └── main.js # Application entry
│ └── package.json # Node dependencies
│
├── start.sh # Start script
└── README.md # Documentation
```
---
### Deployment
#### Docker Compose Deployment
```bash
# Build and start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
```
#### Nginx Configuration
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:20011;
}
location /api {
proxy_pass http://localhost:20010;
}
}
```
---
### Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
**Development Workflow**:
1. Fork the project
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
---
### License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
### Contact
- Issues: [GitHub Issues](https://github.com/your-repo/issues)
- Discussions: Welcome to submit Issues or PRs
---
**Made with ❤️ by FastQA Team**
⭐ Star us on GitHub — it motivates us a lot!