# 项目结构说明

## 目录结构

```
.
├── backend/                    # FastAPI后端
│   ├── __init__.py
│   ├── main.py                # 主程序入口
│   ├── config.py              # 配置文件（数据库连接等）
│   ├── database.py            # 数据库连接和会话管理
│   ├── models.py              # SQLAlchemy数据库模型
│   ├── schemas.py             # Pydantic模型（API请求/响应）
│   ├── init_db.py             # 数据库初始化脚本
│   ├── routers/               # API路由
│   │   ├── __init__.py
│   │   ├── students.py        # 学生管理相关API
│   │   ├── rollcall.py        # 点名相关API
│   │   └── scores.py          # 积分和排名相关API
│   └── utils/                 # 工具函数
│       ├── __init__.py
│       ├── excel.py           # Excel文件处理
│       ├── probability.py     # 概率计算（随机点名算法）
│       └── events.py          # 随机事件系统
│
├── frontend/                   # PyQt5前端
│   ├── __init__.py
│   ├── main.py                # 主程序入口
│   ├── main_window.py         # 主窗口
│   ├── utils/                 # 工具函数
│   │   ├── __init__.py
│   │   └── api_client.py      # API客户端（与后端通信）
│   └── widgets/               # 自定义组件
│       ├── __init__.py
│       ├── student_management.py  # 学生管理界面
│       ├── rollcall.py            # 点名界面
│       ├── score_management.py    # 积分管理界面
│       └── visualization.py       # 数据可视化界面
│
├── data/                      # 数据文件目录
│   └── students_template.xlsx # 示例Excel文件
│
├── docs/                      # 文档目录
│   └── prototype.md           # 原型设计说明
│
├── scripts/                   # 脚本目录
│   └── create_sample_excel.py # 创建示例Excel脚本
│
├── requirements.txt           # Python依赖包列表
├── README.md                  # 项目说明文档
├── 项目结构说明.md            # 本文件
└── .gitignore                 # Git忽略文件
```

## 核心模块说明

### 后端模块

#### 1. 数据库模型 (`backend/models.py`)
- `Student`: 学生表
  - 基本信息：学号、姓名、专业
  - 积分信息：总积分、随机点名次数、顺序点名次数
  - 特殊功能：转移权次数
  
- `RollCallRecord`: 点名记录表
  - 记录每次点名的详细信息
  - 包含积分变化、事件类型等
  
- `ScoreRecord`: 积分记录表
  - 记录每次积分变化的详细历史

#### 2. API路由

**学生管理 (`backend/routers/students.py`)**:
- `GET /api/students/`: 获取学生列表
- `GET /api/students/{id}`: 获取单个学生
- `POST /api/students/`: 创建学生
- `POST /api/students/import-excel`: 从Excel导入学生
- `DELETE /api/students/{id}`: 删除学生

**点名功能 (`backend/routers/rollcall.py`)**:
- `POST /api/rollcall/start`: 开始点名（随机/顺序）
- `POST /api/rollcall/record`: 记录点名结果并更新积分
- `GET /api/rollcall/records`: 获取点名记录列表
- `POST /api/rollcall/transfer`: 转移点名（使用转移权）

**积分管理 (`backend/routers/scores.py`)**:
- `GET /api/scores/ranking`: 获取积分排名
- `GET /api/scores/export`: 导出积分详单（Excel）
- `GET /api/scores/statistics`: 获取统计信息

#### 3. 核心算法

**概率计算 (`backend/utils/probability.py`)**:
- `calculate_probability_weights()`: 计算每个学生的权重
  - 使用反比例函数：权重 = 1 / (积分 + 1)
  - 积分越低，权重越高，被点概率越大
  
- `weighted_random_select()`: 加权随机选择
  - 使用 `random.choices()` 实现加权随机
  
- `get_random_student()`: 从数据库随机选择学生
- `get_next_order_student()`: 按学号顺序获取下一个学生

**随机事件 (`backend/utils/events.py`)**:
- `trigger_random_event()`: 触发随机事件
  - 双倍加分：积分翻倍
  - 疯狂星期四：积分增加50%
  - 幸运星：积分增加20%

### 前端模块

#### 1. 主窗口 (`frontend/main_window.py`)
- 使用 `QTabWidget` 实现标签页布局
- 包含四个主要功能模块

#### 2. 功能组件

**学生管理 (`frontend/widgets/student_management.py`)**:
- 学生列表表格展示
- Excel导入功能
- 学生删除功能

**点名界面 (`frontend/widgets/rollcall.py`)**:
- 点名模式选择（随机/顺序）
- 被点学生信息大屏显示
- 点名结果记录表单
- 最近点名历史记录

**积分管理 (`frontend/widgets/score_management.py`)**:
- 统计信息展示
- 积分排名表格
- 导出积分详单功能

**数据可视化 (`frontend/widgets/visualization.py`)**:
- 使用 Matplotlib 绘制图表
- 支持柱形图和折线图切换
- 显示积分和点名次数的双Y轴图表

#### 3. API客户端 (`frontend/utils/api_client.py`)
- 封装所有与后端API的通信
- 提供简洁的接口供前端组件调用
- 统一的错误处理

## 数据流程

### 点名流程

1. 用户点击"开始点名"
2. 前端调用 `POST /api/rollcall/start`
3. 后端根据模式选择学生：
   - 随机模式：使用加权随机算法
   - 顺序模式：按学号顺序
4. 返回被点学生信息
5. 用户记录点名结果
6. 前端调用 `POST /api/rollcall/record`
7. 后端计算积分变化：
   - 到达：+1分
   - 重复问题：-1/0/+0.5分
   - 回答问题：0-3分
   - 应用随机事件倍数
8. 更新学生积分和记录

### 积分计算规则

1. **基础积分**：
   - 到达：+1分
   - 未到达：0分

2. **回答问题**：
   - 不能重复问题：-1分
   - 未测试：0分
   - 准确重复：+0.5分
   - 准确回答：+0.5-3分（可自定义）

3. **随机事件**：
   - 普通：×1.0
   - 双倍加分：×2.0
   - 疯狂星期四：×1.5
   - 幸运星：×1.2

4. **转移权**：
   - 被点名两次后获得一次转移权
   - 可以在被点名时转移给其他同学

## 技术栈

### 后端
- **FastAPI**: 现代、快速的Web框架
- **SQLAlchemy**: ORM框架
- **Pydantic**: 数据验证
- **Pandas**: 数据处理
- **OpenPyXL**: Excel文件处理
- **PyMySQL**: MySQL数据库驱动

### 前端
- **PyQt5**: GUI框架
- **Matplotlib**: 数据可视化
- **Requests**: HTTP客户端

### 数据库
- **MySQL**: 关系型数据库

