随机点名系统

从 Excel 人员名单中随机抽取人员，支持临时抽选与拖地排班两种模式。

快速开始

方式一：下载可执行文件（推荐）

从 GitHub Releases 下载、运行 RandomSelector_版本号_Setup.exe，无需安装 Python 或任何依赖。

方式二：从源码运行（开发者专用）

# 克隆仓库
git clone https://github.com/BaiLingXi-0136/RandomSelector.git
cd RandomSelector

# 安装依赖
pip install flet pandas

# 启动程序
python main.py

更新到最新版本：

git pull origin main

首次运行程序时，程序会自动在同级目录创建 config/ 文件夹并复制默认数据文件，同时弹出使用说明窗口。用户可自行替换 config/data/DefaultList.xlsx 或通过菜单切换数据文件。

程序已启用单实例保护，重复启动时不会打开多个窗口。

依赖说明：

依赖	版本要求	用途
Python	≥ 3.8	运行环境
flet	≥ 0.21.0	GUI 桌面应用框架
pandas	≥ 1.3.0	Excel 文件读写
pyinstaller	≥ 3.1.0	打包为 exe（可选）

数据文件

程序默认读取 config/data/DefaultList.xlsx。Excel 文件必须可写，且应包含以下列：

姓名	学号	班级	性别

首次使用或更换数据文件时，通过菜单 文件 → 打开数据文件 选择你的 Excel 文件。

---

功能说明

两种抽选模式

模式	人数	保存状态	适用场景
临时模式	1~20 人（可自定义）	不保存	临时点名、课堂提问
拖地模式	固定 3 人	保存到文件	排班轮值、值日安排

抽选操作

1. 在窗口中选择 临时模式 或 拖地模式
2. 临时模式需输入抽选人数（1~20），输入框会实时校验
3. 点击 开始选择 → 逐行动画显示结果，同时顶部大字体实时展示当前抽中姓名
4. 抽选结果自动出现在下方，人数 > 2 时分两栏显示

拖地模式每日限制

拖地模式每天仅允许抽选一次。若当日再次点击"开始选择"，会弹出确认对话框——确认后将清除最近 3 条记录并重新抽取。

回溯替换

选中人员因请假等特殊情况无法参与时，可在结果下方的回溯面板中进行替换：

1. 在输入框中输入该人员的 学号
2. 输入框会实时校验：绿色边框 + 姓名 = 找到，红色边框 = 不在选中列表中
3. 点击 回溯替换，系统自动从剩余人员中随机选一人替换

文件占用监测

程序会实时监测数据文件是否被其他程序（如 Excel、WPS Office）占用：

• 文件被锁定时，顶部显示橙色警告栏，拖地模式自动禁用并强制切换至临时模式
• 文件恢复可写后，警告自动消失，拖地模式恢复正常

查看人员

• 查看所有人员：展示全量名单及选中状态（绿色=已选，红色=未选）
• 查看未选择人员：仅展示尚未被选中的名单

异常检测与错误反馈

程序内置全局异常捕获机制，出现未处理异常时：

• 弹窗提示：显示错误类型、描述及完整 Traceback，用户可复制反馈
• 日志文件：Traceback 自动写入 config/logs/error_YYYYMMDD_HHMMSS.log
• 日志轮转：自动清理旧日志，最多保留 20 个错误日志文件
• 测试入口：菜单 工具 → 测试错误捕获 可手动触发异常，验证捕获机制是否正常

版本更新检测

程序支持自动和手动检查 GitHub 上的最新版本：

• 自动检查：启动时后台检测（可通过 工具 → 选项 关闭），发现新版本时弹窗提示
• 手动检查：工具 → 检查更新，弹出加载窗口等待网络响应，完成后显示结果
• 状态显示：标题栏右侧实时显示更新状态（✓ 已是最新 / ⬆ 新版本可用 / ⚠ 检查失败）
• 网络容错：自动检测 hosts 文件 DNS 劫持（如 Steam++），回退 IP 直连 GitHub CDN

后台下载更新

发现新版本后，可在更新提示对话框中点击 后台下载 自动下载安装包：

• 下载状态栏：主界面底部显示下载进度条、百分比、实时速度和预计剩余时间
• 暂停 / 恢复：下载过程中可随时暂停和恢复
• 断点续传：网络中断或取消下载后，下次下载自动从断点处继续
• 完整性校验：下载完成后自动校验文件大小，确保安装包未损坏
• 打开安装包：下载完成后点击"打开安装包"按钮直接启动安装程序

---

菜单参考

菜单	功能	备注
文件 → 打开数据文件	选择 Excel 数据源	路径会保存，下次自动加载
文件 → 退出	关闭程序
编辑 → 清空选择记录	重置所有选中状态	需二次确认，拖地模式下生效
视图 → 查看所有人员	显示全量名单
视图 → 查看未选择人员	显示可选名单
视图 → 刷新	重载数据并刷新界面	含旋转圆圈动画
工具 → 检查更新	检查 GitHub 最新版本	含加载等待动画
工具 → 选项	配置随机种子与自动更新等功能	相同种子 → 相同结果
工具 → 测试错误捕获	验证错误捕获机制运行正常
帮助 → 使用说明	显示帮助文档	首次运行自动弹出
帮助 → 查看 Markdown 文件	简易 Markdown 文件阅读器
帮助 → 关于	版本与版权信息

---

配置与数据存储

所有配置和数据均存放在 config/ 目录：

config/
├── settings.json                       # 用户配置
├── icon.ico                            # 程序图标
├── data/
     └── DefaultList.xlsx               # 默认数据文件
└── logs/
     ├── error_YYYYMMDD_HHMMSS.log      # 错误日志信息
     ├── app.log                        # 应用日志
     └── debug.log                      # Flet框架等调试信息

设置文件 settings.json 包含的字段：

字段	说明
first_run	首次运行标记（true 时自动弹出帮助）
data_file	当前数据文件路径
seed_enabled	是否启用固定种子
seed_value	种子值（非负整数）
auto_check_update	是否启动时自动检查更新（默认 true）
debug_log_enabled	允许调试信息放行

---

Seed 种子功能

在 工具 → 选项 中启用固定种子后，使用相同种子值、相同数据文件进行抽选，结果完全一致。适用于：

• 测试验证
• 需要复现某次抽选结果的场景