|
|
# 项目完成总结
|
|
|
|
|
|
## 项目概述
|
|
|
|
|
|
本项目是一个**课堂随机点名系统**，采用**PyQt5前端 + FastAPI后端**的架构实现。系统支持随机点名和顺序点名两种模式，具有完整的积分管理、数据可视化和Excel导入导出功能。
|
|
|
|
|
|
## 已完成功能
|
|
|
|
|
|
### ✅ 基础功能
|
|
|
|
|
|
1. **学生管理**
|
|
|
- ✅ 从Excel文件导入学生名单（学号、姓名、专业）
|
|
|
- ✅ 保存到MySQL数据库
|
|
|
- ✅ 查看学生列表
|
|
|
- ✅ 删除学生功能
|
|
|
|
|
|
2. **点名功能**
|
|
|
- ✅ 随机点名（积分越高，被点概率越低）
|
|
|
- ✅ 按学号顺序点名
|
|
|
- ✅ 显示被点学生的姓名和学号
|
|
|
- ✅ 记录学生到达情况
|
|
|
- ✅ 记录回答问题情况
|
|
|
|
|
|
3. **积分系统**
|
|
|
- ✅ 初始积分为0
|
|
|
- ✅ 点到且到达：+1分
|
|
|
- ✅ 回答问题评分：
|
|
|
- 准确重复问题：+0.5分
|
|
|
- 不能重复问题：-1分
|
|
|
- 准确回答问题：+0.5-3分（可自定义）
|
|
|
- ✅ 总积分越高，被随机点到的概率越低（使用反比例函数实现）
|
|
|
|
|
|
4. **数据可视化**
|
|
|
- ✅ 积分排名柱形图
|
|
|
- ✅ 积分排名折线图
|
|
|
- ✅ 显示积分和点名次数的双Y轴图表
|
|
|
- ✅ 可切换图表类型
|
|
|
- ✅ 可调整显示数量
|
|
|
|
|
|
5. **数据导出**
|
|
|
- ✅ 导出积分详单（Excel格式）
|
|
|
- ✅ 包含学号、姓名、专业、随机点名次数、总积分
|
|
|
|
|
|
### ✅ 进阶功能
|
|
|
|
|
|
1. **点名转移权**
|
|
|
- ✅ 被点名两次后自动获得一次转移权
|
|
|
- ✅ 支持转移点名给其他同学
|
|
|
|
|
|
2. **随机事件系统**
|
|
|
- ✅ 双倍加分：积分翻倍
|
|
|
- ✅ 疯狂星期四：积分增加50%
|
|
|
- ✅ 幸运星：积分增加20%
|
|
|
- ✅ 30%概率触发特殊事件
|
|
|
|
|
|
## 技术实现
|
|
|
|
|
|
### 后端技术栈
|
|
|
- **FastAPI**: 现代、快速的Web框架，自动生成API文档
|
|
|
- **SQLAlchemy**: ORM框架，数据库操作
|
|
|
- **Pydantic**: 数据验证和序列化
|
|
|
- **Pandas + OpenPyXL**: Excel文件处理
|
|
|
- **PyMySQL**: MySQL数据库驱动
|
|
|
|
|
|
### 前端技术栈
|
|
|
- **PyQt5**: 跨平台GUI框架
|
|
|
- **Matplotlib**: 数据可视化
|
|
|
- **Requests**: HTTP客户端，与后端通信
|
|
|
|
|
|
### 核心算法
|
|
|
|
|
|
1. **加权随机算法**：
|
|
|
```python
|
|
|
权重 = 1 / (积分 + 1)
|
|
|
```
|
|
|
- 积分越低，权重越高
|
|
|
- 确保所有学生都有被点到的可能
|
|
|
|
|
|
2. **积分计算**：
|
|
|
```
|
|
|
总积分变化 = (到达分 + 重复问题分 + 回答问题分) × 事件倍数
|
|
|
```
|
|
|
|
|
|
## 项目结构
|
|
|
|
|
|
```
|
|
|
.
|
|
|
├── backend/ # FastAPI后端
|
|
|
│ ├── main.py # 主程序入口
|
|
|
│ ├── config.py # 配置文件
|
|
|
│ ├── models.py # 数据库模型
|
|
|
│ ├── routers/ # API路由
|
|
|
│ └── utils/ # 工具函数
|
|
|
├── frontend/ # PyQt5前端
|
|
|
│ ├── main.py # 主程序入口
|
|
|
│ ├── main_window.py # 主窗口
|
|
|
│ ├── widgets/ # 自定义组件
|
|
|
│ └── utils/ # 工具函数
|
|
|
├── data/ # 数据文件
|
|
|
├── docs/ # 文档
|
|
|
├── scripts/ # 脚本
|
|
|
└── requirements.txt # 依赖包
|
|
|
```
|
|
|
|
|
|
## 原型设计
|
|
|
|
|
|
- **工具选择**: 墨刀（Modao）
|
|
|
- **选择理由**: 免费、易用、支持交互式原型、中文支持好
|
|
|
- **设计内容**:
|
|
|
- 主界面布局（标签页设计）
|
|
|
- 各功能模块界面设计
|
|
|
- 交互流程设计
|
|
|
- **文档位置**: `docs/prototype.md`
|
|
|
|
|
|
## 使用说明
|
|
|
|
|
|
### 快速开始
|
|
|
|
|
|
1. **安装依赖**：
|
|
|
```bash
|
|
|
pip install -r requirements.txt
|
|
|
```
|
|
|
|
|
|
2. **配置数据库**：
|
|
|
- 编辑 `backend/config.py`
|
|
|
- 填入MySQL数据库连接信息
|
|
|
|
|
|
3. **启动应用**：
|
|
|
|
|
|
- 启动后端：
|
|
|
|
|
|
```bash
|
|
|
# 在./backend/config中配置数据库参数
|
|
|
export DB_PASSWORD=${数据库密码}
|
|
|
# 选择是否进行测试数据库开发
|
|
|
export DEV_MOD=TEST
|
|
|
|
|
|
```
|
|
|
|
|
|
- 启动前端：`python frontend/main.py`
|
|
|
|
|
|
|
|
|
```bash
|
|
|
python -m frontend.main
|
|
|
```
|
|
|
|
|
|
|
|
|
## 文件清单
|
|
|
|
|
|
### 核心代码文件
|
|
|
- ✅ `backend/main.py` - 后端主程序
|
|
|
- ✅ `backend/models.py` - 数据库模型
|
|
|
- ✅ `backend/routers/` - API路由（3个文件）
|
|
|
- ✅ `backend/utils/` - 工具函数（3个文件）
|
|
|
- ✅ `frontend/main.py` - 前端主程序
|
|
|
- ✅ `frontend/main_window.py` - 主窗口
|
|
|
- ✅ `frontend/widgets/` - 界面组件（4个文件）
|
|
|
- ✅ `frontend/utils/api_client.py` - API客户端
|
|
|
|
|
|
### 配置文件
|
|
|
- ✅ `requirements.txt` - Python依赖
|
|
|
- ✅ `backend/config.py` - 数据库配置
|
|
|
- ✅ `.gitignore` - Git忽略文件
|
|
|
|
|
|
### 文档文件
|
|
|
- ✅ `README.md` - 项目说明
|
|
|
- ✅ `启动说明.md` - 启动和使用说明
|
|
|
- ✅ `项目结构说明.md` - 项目结构详解
|
|
|
- ✅ `docs/prototype.md` - 原型设计说明
|
|
|
- ✅ `项目完成总结.md` - 本文件
|
|
|
|
|
|
### 脚本文件
|
|
|
- ✅ `scripts/create_sample_excel.py` - 创建示例Excel
|
|
|
- ✅ `start_backend.sh` - 仅启动后端
|
|
|
- ✅ `start_frontend.sh` - 仅启动前端
|
|
|
|
|
|
## 特色功能
|
|
|
|
|
|
1. **智能概率算法**：确保积分低的学生有更多被点机会，平衡课堂参与度
|
|
|
|
|
|
2. **随机事件系统**：增加点名的趣味性和随机性
|
|
|
|
|
|
3. **转移权机制**：被点名两次后可转移，增加互动性
|
|
|
|
|
|
4. **数据可视化**：直观展示积分排名和点名次数
|
|
|
|
|
|
5. **完整的Excel支持**：导入学生名单，导出积分详单
|
|
|
|
|
|
## 注意事项
|
|
|
|
|
|
1. **数据库配置**：
|
|
|
- 需要先创建MySQL数据库
|
|
|
- 配置信息在 `backend/config.py`
|
|
|
|
|
|
2. **端口占用**：
|
|
|
- 后端默认使用8000端口
|
|
|
- 如被占用，修改 `backend/config.py` 中的 `API_PORT`
|
|
|
|
|
|
4. **API文档**：
|
|
|
- 后端启动后访问 http://127.0.0.1:8000/docs 查看API文档
|
|
|
|
|
|
|
