first commit

README.md

@@ -0,0 +1,90 @@
+# 学生自助分组系统
+
+这是一个基于 B/S 架构的本地/校园网分组系统。项目使用 Python 标准库实现，不需要安装第三方依赖；数据库为 SQLite，学生名单来源为 `2025mt.xlsx`。
+
+## 功能
+
+- 学生用学号登录，首次登录密码也是学号，并强制修改密码。
+- 学生登录后显示姓名、学号和登录状态。
+- 学生可创建组并自动成为组长；其他学生可选择加入。
+- 每组最多 6 人，包括组长。
+- 已加入其他组的学生不能创建新组；组长加入新组时，需确认解散原组；普通成员切换组时需确认退出原组。
+- 学生端和教师端都能直接看到全部组及成员的学号、姓名，无需点开详情。
+- 教师可切换“当前开放登录班级”，未开放班级不能登录。
+- 教师可停止/恢复学生分组操作。
+- 停止后学生只能查看；教师仍可手工建组、改名、设组长、加入、移出、解散。
+- 教师可导出当前班分组为 `.xlsx`。
+
+## 启动
+
+在本目录执行：
+
+```bash
+python3 app.py
+```
+
+默认访问地址：
+
+- 学生端：<http://127.0.0.1:8000/>
+- 教师端：<http://127.0.0.1:8000/teacher>
+
+如果学生要从其他电脑/手机访问，请把 `127.0.0.1` 换成老师电脑的局域网 IP，例如：
+
+```text
+http://192.168.1.20:8000/
+```
+
+可自定义端口和数据库：
+
+```bash
+PORT=8000 GROUP_DB=selfgroup.db python3 app.py
+```
+
+## 教师账号
+
+默认账号：
+
+```text
+账号：teacher
+密码：teacher123
+```
+
+正式使用前建议改用环境变量设置：
+
+```bash
+TEACHER_USER=yourname TEACHER_PASSWORD=your-strong-password python3 app.py
+```
+
+注意：教师密码只在首次创建数据库时写入。如果数据库已存在，修改环境变量后还需要删除旧数据库或直接更新数据库中 `settings` 表的 `teacher_password`。
+
+## 学生名单
+
+服务第一次启动时，如果没有数据库，会自动读取当前目录的 `2025mt.xlsx`。表格至少需要以下表头：
+
+```text
+班级    学号    姓名
+```
+
+也兼容读取：性别、录取编号、备注。
+
+如果换了名单，可以在教师后台上传新的 `.xlsx`。导入会重建学生账号并解散全部已有分组。
+
+## 数据文件
+
+- `selfgroup.db`：学生、密码、分组、班级状态和登录会话。
+- `2025mt.xlsx`：首次启动导入的原始名单。
+
+## 建议部署方式
+
+1. 在教师电脑上运行 `python3 app.py`。
+2. 查看教师电脑局域网 IP。
+3. 将学生端网址发到班级群。
+4. 教师打开 `/teacher`，切换到要分组的班级。
+5. 分组完成后点击“停止学生操作”。
+6. 检查并手工调整分组，然后导出 Excel。
+
+## 注意
+
+- 学生密码使用 PBKDF2 加盐哈希保存，不以明文保存。
+- 系统适合局域网使用；如果在公网部署，请使用 HTTPS 反向代理，并务必修改教师默认密码。
+- SQLite 适合班级规模的小型并发使用，不建议多名教师同时频繁写数据库。