update the readme

README.md

@@ -1,2 +1,199 @@
-# python
+# 项目完成总结
+
+## 项目概述
+
+本项目是一个**课堂随机点名系统**，采用**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 -m backend.main 
+
+```
+   `python backend/main.py`
+   - 启动前端：`python frontend/main.py`
+```
+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文档
+