# 项目完成总结

## 项目概述

本项目是一个**课堂随机点名系统**，采用**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文档