学生小档案

老师在本机管理班级和学生资料，学生可通过同一 Wi-Fi、手机热点或 ngrok 公网链接填写。文字和照片存储在老师电脑的 SQLite 数据库中。

Windows 免配置版

dist/StudentAlbum-Windows-x64-v0.3.4.zip 是给 Windows 10 / 11 64 位电脑使用的便携包。它包含 Python、Pillow 和 ngrok，不需要另行配置开发环境。

1. 把压缩包完整解压到桌面或“文档”文件夹。
2. 双击“安装并启动学生小档案.cmd”。
3. 桌面会生成带应用图标的“学生小档案”快捷方式并自动打开管理页。
4. 以后只需双击桌面的图标。

升级到新版时，解压新版后再次双击“安装并启动学生小档案.cmd”即可。安装程序会自动停止旧版后台服务、迁移旧资料与 ngrok 配置、更新快捷方式并启动新版，避免浏览器继续连到旧版进程。需要卸载时可双击“卸载学生小档案.cmd”；卸载默认保留学生资料和 ngrok 配置，防止误删。

便携包不会包含开发电脑上的数据库、学生资料或 ngrok 凭证。妈妈电脑上的资料保存在解压目录的 app/data/album.sqlite3。Windows 版的 ngrok 凭证会迁移并保存在当前用户的应用数据目录，后续升级不需要再次输入。

日常使用

1. 在 Mac 双击 启动学生档案.command，保持窗口开启、电脑联网且不休眠。
2. 首次使用，在老师管理页的「本学期班级」填写学期和班级。多个班级可用逗号、顿号或换行分隔；之后可继续添加，重名不重复创建。
3. Windows 日常启动时会自动同时启动局域网入口和 ngrok 公网入口；老师端会并排显示两个入口的状态和地址。首次没有 ngrok 凭证时，直接在公网卡片粘贴 Authtoken 并保存。
4. 保存 Authtoken 后程序会自动连接 ngrok、读取实际公网地址并保存，后续启动自动复用；连接成功后点击「复制公网链接」即可发给学生。手机不需要和电脑在同一个 Wi-Fi。 Windows 版不会假设具体代理软件或端口：会依次利用直连/TUN、环境变量代理、Windows 手动系统代理、PAC/WPAD 自动代理及 WinHTTP 代理，并记住上一次成功的来源以便下次优先尝试。
5. 学生选择班级、填写学号姓名并保存续填口令，随后填写资料和上传照片。
6. 老师名单每 3 秒自动刷新，可以按班级标签切换，查看和修改资料、导出名单；忘记续填口令可在学生详情中重置。
7. 删除学生后资料进入回收站；回收站按班级归类，可恢复单个学生或一键恢复整个班级。删除含学生的班级时，班内学生也会进入回收站。

ngrok 免费入口可能先显示 Visit Site 提示，按提示继续。网络异常时管理页会把公网状态标记为异常并禁用复制按钮，但仍展示固定公网地址；可点击「重新连接」。运行期间持续读取实际 tunnel 地址，只有与固定地址一致时才标记为在线。

老师管理页：本机工作台。学生本机预览：填写页。这两个本机网址不能直接在手机访问。

按 Control+C 或关闭启动窗口停止服务，数据库会保留。旧的「启动演示.command」仍可用，会转到正式启动入口。

同一 Wi‑Fi / 热点收集

不使用 ngrok 时，可运行 python3 scripts/serve.py --local --lan。老师电脑与学生手机连接到同一个 Wi‑Fi 或老师手机热点后，管理页会显示 http://局域网地址:8766/。这个入口只提供学生填写页和提交接口；老师管理页仍只能在电脑本机打开。学生离开该网络后链接失效。

数据和身份

• 新安装没有班级和学生，不含示例记录。未配置班级时学生页显示等待提示。
• data/album.sqlite3 保存班级、文字资料、续填凭证散列、会话和照片。照片以 JPEG 二进制存储，实际保存完整图片，最大边优化为 1800 像素并移除照片元数据。
• 学号在每个班级内唯一；不同班可有相同学号。续填使用「班级 + 学号 + 六位口令」，换手机或服务重启后仍可继续。
• 文字输入停顿后自动保存，失败时明确提示并重试；不会在保存失败时显示完成。当前标签页暂存未提交文字，关闭前有未保存提醒。照片上传失败需重新选择上传。
• 老师端仅监听本机 8765 端口，ngrok 只转发学生端 8766。学生只能查看和修改自己已登录的档案。
• 本机管理依赖当前电脑的登录环境，尚未增加独立的老师密码；不要在不受信任的共享电脑账户中运行。
• 班级支持新增和删除。删除空班级会直接移除；删除含学生的班级会将学生移入回收站，恢复该班级即可一并恢复学生。
• 数据和 ngrok 凭证均已忽略 Git。备份时先停止程序，再复制整个 data 文件夹到安全位置；导出的 CSV 仅含文字，不包含照片。

运行与验证

依赖 Python 3 和 Pillow。启动器在缺少 Pillow 时创建项目内虚拟环境并安装 requirements.txt，ngrok 缺失时从官方源下载。

仅本机运行：python3 scripts/serve.py --local。

集成测试：python3 scripts/test_app.py -v。测试在临时目录建立数据库，覆盖空数据、多班级、重复建档、照片、重启续填、访问隔离和口令限流，不写入正式 data。

生成 Windows 便携包：python3 packaging/build_windows.py。

GitHub 自动测试和发布已配置在 .github/workflows/windows.yml：提交到 main 或创建拉取请求会在 Windows 上测试、打包并使用包内 Python 实际启动网页；推送 v0.4 这样的版本标签会在测试通过后发布 Release。具体发布和保留旧数据的更新步骤见 GitHub 发布流程。妈妈可收藏 最新版下载页，以后始终从同一页面下载。

v0.1 为最初学生端原型快照；v0.2 加入正式老师管理端、数据库和回收站；v0.3 加入长辈友好界面、自动快照恢复和 Windows 发布流程；v0.3.1 加入双网络状态；v0.3.2 修复新版与旧后台进程切换并加入卸载；v0.3.3 加入页面内 ngrok 首次配置、全局姓名搜索和班级表单整理；v0.3.4 加入 Windows ngrok 网络路径自动探测和代理自动切换。