# classroom-workstation

**Repository Path**: ike_lin/classroom-workstation

## Basic Information

- **Project Name**: classroom-workstation
- **Description**: 教室工作台 - 面向教室管理场景的桌面工作台（单 exe 启动，内置 Flask 服务，支持启动/停止/重启/检查更新与内网访问）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教室工作台

面向中小学教室管理场景的轻量级一体化工作台。单页 Web 应用 + 桌面启动器，开箱即用：双击 `教室工作台.exe` 即可在本地启动服务，浏览器访问进行管理。支持本机与局域网（内网）多终端访问。

> 纯本地运行，数据存储在本地 SQLite 数据库，不上传任何云端。

---

## ✨ 功能特性

| 模块 | 说明 |
| --- | --- |
| 🏠 首页 | 班级概况、日期与激励语、快捷入口 |
| 📅 课程表 | 周一至周五课表，点击单元格直接选择科目，支持打印 |
| 🪑 座位表 | 可视化座位编排，支持男女间隔 / 双人桌 / 随机排座，打印 |
| 🧹 值日表 | 值日项目与排班，支持打印 |
| 👩‍🎓 学生名册 | 学号、姓名、性别、家长、住址、备注；支持 Excel 导入导出与搜索 |
| 📝 作业 / 成绩 / 考勤 | 作业布置、成绩记录与学情分析、出勤与请假管理 |
| 📨 家校沟通 | 家长通知与反馈收集 |
| ✅ 待办 / 📊 报表 | 班级待办事项、各类统计报表 |
| ⚙️ 系统设置 | 科目、值日项、主题、老师信息等配置 |

---

## 🚀 快速开始

### 方式一：使用打包好的 exe（推荐）

1. 从 Gitee **发行版（Releases）** 下载 `教室工作台.exe`；
2. 双击运行，弹出启动器界面；
3. 点击 **启动服务**，状态变为「运行中」后，点击 **打开网页** 或复制地址到浏览器访问。

> 数据（数据库、配置）会自动保存在用户目录 `C:\Users\<用户名>\AppData\Roaming\教室工作台` 中，与程序目录分离，重装 / 更新不会丢失。

### 方式二：源码运行

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动（会自动打开浏览器）
python app.py
```

访问地址：`http://127.0.0.1:8778/`

如需重新构建前端（修改了 `web/src/` 后）：

```bash
python build_frontend.py
```

---

## 🖥️ 桌面启动器说明

启动器（`launcher.py`，打包为 `教室工作台.exe`）提供：

- **状态指示**：运行中（绿）/ 停止（红）/ 启动中（黄）；
- **启动 / 停止 / 重启服务**：一键控制本地 Web 服务；
- **访问地址**：
  - 本机地址 `http://127.0.0.1:8778/`
  - 内网地址 `http://<局域网IP>:8778/`（同网段其他设备可直接访问，适合教室场景）
  - 两个地址均支持「复制」按钮一键复制；
- **实时日志**：实时显示服务端运行日志，便于排查问题；
- **检查更新**：依据 Gitee 发行版版本号自动比对，弹窗显示**更新日志**，可选择「立即更新」「暂不更新」「跳过这个版本」「去发行版页」；
- **系统托盘**：服务运行时关闭窗口可最小化到系统托盘，托盘菜单支持显示窗口 / 打开网页 / 启动 / 停止 / 退出；
- **网站图标**：浏览器标签页会显示蓝色黑板风格 favicon。

---

## 🔄 更新机制

更新依据 **Gitee 发行版（Release）**：

- 启动器「检查更新」会请求
  `https://gitee.com/api/v5/repos/ike_lin/classroom-workstation/releases/latest`
  获取最新版本号（`tag_name`）与更新日志（`body`）；
- 若最新版本号大于本地版本（`version.txt`），则提示更新并在弹窗中展示更新日志；
- 点击「立即更新」后，下载发行版中的 exe 安装包，自动替换并重启。

版本号规则：语义化版本 `主.次.修订`（如 `1.0.0`），比较时忽略前缀 `v`。

---

## ⚙️ 配置说明

- 用户数据（配置、数据库、日志、**前端 web/**）统一存放在用户目录：`%APPDATA%\教室工作台\`（即 `C:\Users\<用户名>\AppData\Roaming\教室工作台`）。
  - `web\`：前端资源（HTML/CSS/JS/图标），首次运行自动解包；
  - `config.json`：应用配置与偏好（老师姓名、科目、主题等），运行时自动生成与维护；
  - `data\workstation.db`：业务数据库（SQLite），请勿手动编辑；
  - `data\server.log`：运行日志。
- **程序目录保持干净**：`教室工作台.exe` 同级不写入任何运行时数据，可放心放入 `Program Files` 等受保护或只读目录。

### 自定义数据目录

默认数据在用户目录，你也可把数据放到任意位置（如其他盘 `D:\教室数据`）：

1. **启动器界面**：点击「数据目录」右侧的 **更改**，选择目录后可选「迁移现有数据」，重启生效；
2. **配置文件**：在 `教室工作台.exe` 所在目录新建 `datapath.txt`，写入一行目标路径（如 `D:\教室数据`）；
3. **环境变量**：设置 `JXGZT_DATA_DIR` 指向目标路径。

优先级：环境变量 > `datapath.txt` > 默认用户目录。旧版本（数据在程序目录）首次运行会自动迁移，历史配置与数据不丢失。

- 服务默认端口 `8778`，若被占用会自动顺延。

---

## 📦 目录结构

```
教室工作台/
├── app.py              # Flask 后端服务（单文件）
├── launcher.py         # 桌面启动器（GUI + 服务控制 + 更新 + 托盘）
├── build_frontend.py   # 前端打包脚本（esbuild 合并 bundle）
├── gen_icons.py        # 生成 favicon.ico / tray.ico
├── version.txt         # 当前版本号
├── requirements.txt    # Python 依赖
├── config.json         # 默认配置模板（构建用，运行时数据不写在此处）
├── web/                # 前端（index.html + css + 已合并的 bundle，只读资源）
│   ├── index.html
│   ├── favicon.ico     # 网站图标
│   ├── tray.ico        # 托盘图标
│   ├── css/app.css
│   ├── js/app.bundle.js
│   └── src/js/         # 前端源码（模块）
└── data/               # 开发期本地数据（已 gitignore；实际运行数据在用户目录）
```

> 仓库中的 `web/`、`config.json` 是**源码/构建模板**；打包后运行时，`web/`、`config.json`、`data/` 都会解包/写入用户目录 `%APPDATA%\教室工作台\`，程序目录（exe 同级）保持干净。

---

## 🛠️ 自行打包为 exe

需安装 [PyInstaller](https://pyinstaller.org/)：

```bash
pip install pyinstaller
pyinstaller classroom.spec        # 见仓库内 spec
# 产物位于 dist/教室工作台.exe
```

打包以 `launcher.py` 为入口，自动收集 `app.py`、`web/`、`config.json`、`version.txt` 及 Flask 等依赖。

---

## 📝 最近更新

### v1.0.10
- **修复「关闭窗口最小化到托盘」失效**：重构 `on_close` 与 `hide_to_tray`，关闭按钮永远先最小化到托盘、绝不直接退出进程；仅在托盘菜单「退出」时才会真正关闭。托盘图标的创建与启动全程异常保护，即使托盘不可用也会退化为最小化到任务栏（不再出现窗口“消失且无法恢复”的假死现象）。

### v1.0.9
- **自更新进度可视化**：点击「立即更新」后弹出进度窗口，实时显示下载百分比与已下载/总大小（MB）；后台线程下载，界面不卡顿。若服务端未返回文件大小则自动切换为不确定（滚动）进度。

### v1.0.8
- **程序目录彻底干净**：前端 `web/`（含 favicon.ico / tray.ico）也解包到用户目录 `%APPDATA%\教室工作台\web`，不再放在 exe 同级。
- **数据目录可自定义**：支持通过启动器「数据目录 → 更改」按钮、程序目录下的 `datapath.txt`、或环境变量 `JXGZT_DATA_DIR` 指定数据存放位置（如其他盘）。
- 优先级：环境变量 > `datapath.txt` > 默认用户目录；更改时可选择将现有配置/数据库/日志一并迁移。
- 旧版本（web/ 在程序目录）首次运行时会自动迁移到用户目录，历史资源不丢失。

### v1.0.7
- **数据与程序分离**：配置文件 `config.json`、数据库 `workstation.db`、运行日志等用户数据统一写入用户目录 `%APPDATA%\教室工作台`，不再存放在 `exe` 同目录。
- 旧版本（数据在程序目录）首次运行时会自动迁移到用户目录，历史配置与数据不丢失。
- 程序目录仅保留只读的 `web/` 前端资源，可放入 `Program Files` 等受保护目录。

### v1.0.6
- 停止服务后自动将访问地址重置为占位提示，避免显示已失效的旧地址。

### v1.0.5
- `server.log` 超过 1MB 自动轮转为 `server.log.1`，避免长期运行无限增长。
- 复制地址改为在日志框提示，不再每次弹窗。

### v1.0.4
- 自更新脚本加入 `chcp 65001`，避免 EXE 位于中文路径时更新替换失败。
- 自更新退出前先停止托盘线程，避免残留托盘图标。

### v1.0.3
- 修复托盘菜单回调的线程安全问题，避免偶发崩溃。

### v1.0.2
- 更新对话框增加「立即更新 / 暂不更新 / 跳过这个版本 / 去发行版页」按钮，修复按钮被日志框挤出可视区域的问题。
- 支持关闭窗口最小化到系统托盘。
- 新增网站 favicon。
- 升级后自动补齐 `web/` 目录新增文件。

---

## 📄 开源说明

本项目遵循 MIT 开源协议，欢迎学习、二次开发与贡献。