# ourclass

**Repository Path**: wckjlu/ourclass-lite

## Basic Information

- **Project Name**: ourclass
- **Description**: OurClass是一个实现数据收集、数据分析、自动评分、题库归并，生成学习报告的学生课堂表现智能积分评价系统。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OurClass · 课堂表现智能积分评价系统

> 面向中小学课堂的表现评价与积分管理工具。**解压双击即用，不需要安装 Python、数据库或任何运行环境。**

老师用它给学生课堂表现加分扣分、发布答题任务、查看班级排行，并在大屏上实时展示。
学生用手机扫码答题，答对自动加分。

**开源许可：Apache License 2.0** —— 可免费用于教学，可自由修改、二次开发与商业使用，详见文末[「许可协议」](#九许可协议)一节。

---

## 本项目要解决的主要问题

AI 让教学资源的生成成本趋近于零，但生成出来的东西并没有真正进入课堂的数据循环。本项目要解决的，是「**生成 → 使用 → 结果 → 评价**」这条链路上四个长期断开的环节。

### 问题一：AI 生成的教学资源是一次性消耗品

**具体表现**：老师用 AI 生成的互动练习，生成时并不知道要教哪个班、哪个孩子在哪个知识点上还不熟；用完就与课堂、与学生彻底失联。一学期下来几十个 HTML 文件躺在文件夹里，既不沉淀也不复用，下次还得从头再让 AI 生成一遍。

**造成后果**：老师的备课投入被重复消耗；同一单元的资源无法迭代优化；一份好资源也无法在教研组内传承。

**本项目如何应对**：把「任务」做成资源与数据的共同载体——一个任务里同时保存老师的教学意图（提示词）、AI 产出的资源（答题页）以及这份资源教出的结果。资源从此有归属、可检索、可迭代。

### 问题二：学生的练习结果停在学生设备上，收集不回来

**具体表现**：学生在自己的手机或平板上做完练习，结果只留在那个页面上，一关就没了。老师只能得到「大概谁做得不错」的印象；真要收集，就得让学生举手、报数、拍照，一节课白白耗掉十分钟。

**造成后果**：练习做了却没有数据沉淀，等于没做；老师永远不知道哪道题全班都错了、错在哪里。

**本项目如何应对**：让每一个 AI 生成的答题页都成为数据入口——页面在本地完成判分后，按统一协议逐题回传（题号、学生答案、对错、题干、正确答案、知识点、用时）。学生扫码即用，不注册、不安装、不登录。

### 问题三：收集到的结果不成体系，无法跨时间累积

**具体表现**：即使拿到了当次结果，它也只是「一份报告」——这次对了几道。换一个任务、换一门学科，数据就断了，每次练习都是一座孤岛。

**造成后果**：看不出成长趋势，无法判断某个学生在某个知识点上是持续薄弱还是偶然失误；到了学期末也拿不出一份能说明问题的成长记录。

**本项目如何应对**：所有记录都锚定在终身不变的唯一身份上（学校代号 + 入学年 + 班序 + 生序构成的登录码，升学、换班、换老师都不会改变），并按「学生 × 知识点 × 时间」三个坐标组织。有了坐标，散点才能连成曲线。

### 问题四：练习数据与课堂评价相互脱钩

**具体表现**：练习归练习，积分归积分。课堂上的举手发言、作业完成、小组合作已经有一套表现评价，答题正确率却是另一套，两者互不相通。

**造成后果**：老师要在两套工具之间来回切换；练习数据最终没有进入班级评价体系，学生也感受不到「练得好」在班里有什么体现，练习的动力随之流失。

**本项目如何应对**：练习结果直接进入与课堂表现同一套积分口径，自动加分规则（全班最先完成、全部答对等）即时生效，班级大屏、个人成长报告与学期报告共用同一份数据。

### 还需要补上的一步：让数据回流到下一次生成

以上四个环节打通后，系统已经能记录每一次练习。但「记录」不等于「闭环」——任务分析里那些正确率偏低的题目，目前只停在老师眼前，下一次生成资源时并没有被用上。

真正的闭环，是让班级和个人的薄弱知识点反过来约束下一次的提示词，使生成出来的内容随学情自动调整。这是本项目正在推进的方向，也是它与「一个能出题的 AI 工具」的根本区别。

## 核心工作流：从一份提示词到一条学情数据

本项目的核心价值不在「会用 AI」，而在把 AI 生成能力接进课堂评价的数据循环。一次完整的使用流程是：

```
创建任务 → 写需求生成提示词 → AI 生成互动教学资源（答题页等）
        → 上传 AI 生成的 HTML → 学生扫码答题（免注册）
        → 答题结果实时回传：收集 / 统计 / 分析
        → 按题关联知识点，沉淀进学生成长档案
        → 换算积分，关联课堂评价
```

1. **创建任务**：老师设定学段、年级、学科、册次与任务名，任务就是这条链路的载体——提示词、资源、结果三者同存于一个任务之下。
2. **写需求、生成提示词**：老师写下本班的教学需求（教什么、练什么、什么难度），系统把老师需求与统一提交协议合成完整提示词，复制即可交给任意 AI（豆包、即梦、ChatGPT……）。
3. **AI 生成互动教学资源**：AI 按提示词产出可交互的答题页（HTML），题目自带知识点标签、正确答案与判分规则——资源在生成的那一刻就带着「数据接口」出生。
4. **上传 HTML**：把 AI 生成的文件上传到任务下，系统自动生成学生访问链接与二维码。
5. **学生答题**：学生扫码即答，不注册、不安装、不登录；页面本地判分，逐题按协议回传（题号、学生答案、对错、题干、正确答案、知识点、用时）。
6. **收集、统计、分析**：提交实时汇入任务分析——每题对错人数与正确率、参与名单、最先完成榜、人均得分，答题进行中即可看到，不必等下课。
7. **关联知识点**：每道题携带知识点标签，结果按「学生 × 知识点 × 时间」沉淀，学期报告中形成个人知识掌握强弱榜，跨任务可累积、可比较。
8. **关联课堂评价**：练习结果按自动加分规则即时换算成课堂积分，与举手发言、小组合作进入同一套口径，大屏、报告、成长档案共用同一份数据。

这条链路的价值在于：**老师每一次「用 AI 出一份练习」的普通动作，都在为班级沉淀一条结构化的学情数据**——练完即收，收完即评，评完可查可累积。生成能力大家都有，这条数据链路是本项目独有的。

---

## 一、为什么是「绿色版」

大多数教学软件要求先装数据库、再配运行环境，普通老师很难搞定。
本项目做成**单文件绿色版**：

| 常见做法 | 本项目 |
|---|---|
| 安装 Python + 依赖包 | 不需要，已内置 |
| 安装 MySQL 并配置服务 | 不需要，用 SQLite 单文件数据库 |
| 安装 Node.js 构建前端 | 不需要，页面已预先构建 |
| 配置端口、启动多个进程 | 双击一个 exe，自动打开浏览器 |

老师拿到的是一个文件夹：**解压 → 双击 → 就能用**。

---

## 二、功能

**课堂评价**
- 头像卡片墙式快速加分 / 扣分，支持单人、多人、全班
- 预设常用加扣分项，一键完成
- 小组长可给组内同学加分
- 高频重复加分自动告警，防止刷分

**答题任务**
- 老师创建任务并生成二维码，学生扫码答题（无需登录）
- 答对自动加分，支持多种加分规则（抢答前 N 名、全对、答对即得、按题计分）
- 可设置多次提交策略：仅一次 / 取首次 / 取末次 / 取最高分
- 题目维度分析、按班级对比

**统计与大屏**
- 学生排行、小组排行，支持全校 / 年级 / 班级范围切换
- 科技风全屏数据驾驶舱，适合投屏与领导查看

**系统管理**
- 五种角色：校级管理员 / 班主任 / 科任老师 / 小组长 / 学生
- 可批量添加学生、一键自动分组
- 登录码终身不变，学生凭码登录

### 界面预览

登录页（附品牌标识与版本号）：

![登录页](docs/lite_login.png)

班级大屏 —— 一节课结束一键投屏，排行实时刷新：

![班级大屏](docs/lite_screen.png)

学校数据看板 —— 面向管理者的全校使用概览：

![数据看板](docs/lite_dashboard.png)

---

## 三、给老师：怎么用

1. 把文件夹解压到电脑上（建议 D 盘，不要放桌面）
2. 双击 `OurClass.exe`，打开图形启动器
3. 点 **「▶ 启动服务」**，状态变绿即启动成功
   （首次运行弹出防火墙提示时，点击 **允许访问**）
4. 浏览器自动打开，用默认账号登录：`admin` / `admin123`
5. 登录后立即修改密码；用完点 **「■ 停止服务」** 或直接关闭窗口（数据自动保存）

详细步骤见随包附带的 **`使用说明.txt`**。

> 局域网内的其他电脑、手机、平板，用启动器里显示（可一键复制）的
> `http://192.168.x.x:5000` 地址即可访问，学生扫码答题、大屏投屏都靠它。

---

## 四、给开发者：从源码运行

### 环境要求
- Python 3.10+
- Node.js 18+（仅构建前端时需要）

### 后端

```bash
cd backend
pip install -r requirements.txt
python app.py
```

首次运行会自动完成：建库、创建学校、预置学科、创建管理员账号。
数据默认存放在项目根目录的 `data/` 下。

### 前端

```bash
cd frontend
npm install
npm run dev      # 开发模式，默认 http://localhost:5173
npm run build    # 构建产物输出到 frontend/dist
```

开发模式下前端通过 Vite 代理把 `/api` 转发到 `http://127.0.0.1:5000`。

### 打包为绿色版

```bash
pip install pyinstaller
python build/package_win.py
```

产物在 `build/out/OurClass/`，整个文件夹压缩后即可分发。

---

## 五、目录结构

```
ourclass-lite/
├── backend/               后端服务
│   ├── app.py             入口：初始化 + 启动服务 + 托管前端页面
│   ├── config.py          配置：数据目录与数据库自动定位
│   ├── models.py          数据模型
│   ├── routes/            接口（认证/用户/课程/任务/加分/学科/看板）
│   ├── services/          业务服务
│   └── utils/             权限范围、审计、提示词生成等工具
├── frontend/              前端页面（Vue 3 + Element Plus）
│   ├── src/
│   └── vite.config.js
├── build/
│   ├── launcher.py        图形启动器（启动/停止服务、打开后台、局域网地址、日志）
│   ├── make_icon.py       图标生成脚本（PIL 绘制，产出 assets/ourclass.ico）
│   ├── assets/            图标等打包资源
│   └── package_win.py     打包脚本（--windowed 图形启动器 + 图标）
├── data/                  运行期数据（自动生成，勿提交版本库）
│   ├── ourclass.db        SQLite 数据库
│   ├── uploads/           上传的文件
│   └── backups/           备份目录
├── 使用说明.txt            给老师的一页纸说明
├── README.md
├── LICENSE                Apache License 2.0 协议全文
└── NOTICE                 署名与第三方组件声明（分发时须一并保留）
```

---

## 六、数据与备份

- 所有数据都在 `data/` 文件夹里，核心是 `ourclass.db` 一个文件
- **备份**：复制整个 `data/` 文件夹即可
- **恢复**：复制回去覆盖
- **换电脑**：整个程序文件夹拷过去，数据一起走

不需要数据库管理工具，也不需要导出导入。

---

## 七、技术栈

| 层 | 选型 | 说明 |
|---|---|---|
| 后端 | Flask + SQLAlchemy | 轻量，易于二次开发 |
| 数据库 | SQLite（WAL 模式） | 零安装，单文件，够用且好备份 |
| 服务 | waitress | 多线程 WSGI，应对课堂答题并发 |
| 前端 | Vue 3 + Element Plus + ECharts | 组件化，大屏图表 |
| 打包 | PyInstaller | 生成免安装的可执行程序 |

> 如需改用 MySQL，设置环境变量 `DATABASE_URL` 即可（需自行安装对应驱动）。

---

## 八、常见问题

**Q：端口被占用怎么办？**
程序启动时会自动从 `PORT`（默认 5000）向后找一个空闲端口，并在启动窗口里提示实际使用的端口——**无需手动处理**，照提示的地址访问即可。
若想固定端口，设置环境变量 `PORT=8000` 后重新启动。

> 为什么需要自动切换：Windows 下多个进程可以「同时绑定」同一端口（`SO_REUSEADDR`），
> 但连接只会发给其中一个，表现为**程序启动正常却完全访问不了**。
> 因此程序启动时会用独占方式探测端口，监听后再自检一次响应头 `X-OurClass`，
> 确保服务确实可达，避免这种静默失败。

**Q：浏览器打开后只显示一串 JSON（如 `{"code":404,...,"message":"资源不存在"}`）？**
说明浏览器连到了**同一个端口上的其他程序**（绿色版自己没被访问到）。关掉占用该端口的程序后重启即可；
或直接使用启动窗口里显示的「本机访问」地址。

**Q：可以只复制 `OurClass.exe` 一个文件吗？**
不可以。exe 必须与 `web/` 文件夹同级，否则会显示「未找到页面文件」。分发时请整个文件夹打包。

**Q：数据放在别的盘？**
设置环境变量 `OURCLASS_DATA_DIR=D:\ourclass-data`。

**Q：学生扫码连不上？**
确认手机与电脑在同一 WiFi，且首次启动时放行了防火墙。

---

## 九、许可协议

本项目采用 **Apache License 2.0** 开源，完整协议文本见根目录 [`LICENSE`](./LICENSE) 文件，
署名与第三方组件声明见 [`NOTICE`](./NOTICE) 文件。

### 你可以自由地

- ✅ 在课堂上、学校里免费使用，不限班级数、学生数
- ✅ 复制、修改、二次开发（包括改造成自己学校需要的样式和功能）
- ✅ 分发、发布到你的校园网或公开渠道
- ✅ 用于商业用途（例如作为服务机构的一部分提供给学校）
- ✅ **获得专利授权**——贡献者已就本软件向你授予专利许可，商业使用无后顾之忧

### 你的义务

| # | 要求 | 说明 |
|---|---|---|
| 1 | **附带协议副本** | 分发时把 `LICENSE` 文件一起带上（本项目打包产物中已包含） |
| 2 | **保留声明** | 不得删除源码中的版权、专利、商标、署名声明 |
| 3 | **标注改动** | 如果你修改了源文件，需在文件中注明「此文件已被修改」 |
| 4 | **保留 NOTICE** | 分发时一并保留 `NOTICE` 文件中的署名内容 |
| 5 | **不得冒充官方** | 不可使用本项目名义为你自己的版本做宣传或背书 |

### 关于专利（Apache-2.0 相比 MIT 的核心增值）

- 每位贡献者都向你授予了**永久的、全球范围的、免费的、不可撤销的**专利许可
- 反制条款：如果你反过来起诉他人「本软件侵犯了你的专利」，你因本协议获得的专利授权将**立即终止**

### 关于二次开发的开源要求

Apache-2.0 **不是**「传染性」协议（非 copyleft）：你基于本项目改出来的版本，
**没有义务**开源，可以自行决定是否公开。但上面 5 条义务仍需履行——特别是保留 `LICENSE` 与 `NOTICE`。

### 没有担保

软件按「现状」（AS IS）提供，不附带任何明示或默示的担保。作者不对使用本软件产生的数据丢失、教学事故等问题承担责任。
**请务必定期备份 `data/` 文件夹。**

---

### 第三方组件许可

本项目站到了很多优秀开源项目的肩上，它们同样以宽松协议发布，可安全用于商业与教育场景：

| 组件 | 用途 | 协议 |
|---|---|---|
| [Flask](https://flask.palletsprojects.com/) | Web 框架 | BSD-3-Clause |
| [SQLAlchemy](https://www.sqlalchemy.org/) / Flask-SQLAlchemy | ORM | MIT / BSD-3-Clause |
| [Flask-JWT-Extended](https://flask-jwt-extended.readthedocs.io/) | 登录令牌 | MIT |
| [Flask-Cors](https://flask-cors.readthedocs.io/) | 跨域支持 | MIT |
| [waitress](https://github.com/Pylons/waitress) | 生产级 WSGI 服务器 | ZPL-2.1 |
| [Werkzeug](https://werkzeug.palletsprojects.com/) | WSGI 工具库 | BSD-3-Clause |
| [PyMySQL](https://github.com/PyMySQL/PyMySQL) | MySQL 驱动（可选） | MIT |
| [Vue 3](https://vuejs.org/) / vue-router / Pinia | 前端框架 | MIT |
| [Element Plus](https://element-plus.org/) | UI 组件库 | MIT |
| [ECharts](https://echarts.apache.org/) / vue-echarts | 图表与大屏 | Apache-2.0 |
| [axios](https://axios-http.com/) | HTTP 客户端 | MIT |
| [qrcode](https://github.com/soldair/node-qrcode) | 二维码生成 | MIT |
| [Vite](https://vitejs.dev/) | 前端构建 | MIT |
| [PyInstaller](https://pyinstaller.org/) | 打包为 exe | GPL-2.0-or-later **含 Bootloader 例外条款** |

> **关于 PyInstaller**：它自身是 GPL 协议，但授权文件中明确写着 Bootloader 例外条款——
> *"the authors give you unlimited permission to link or embed compiled bootloader and related
> files into combinations with other programs, and to distribute those combinations without any
> restriction coming from the use of those files."*
>
> 也就是说：**用它打包不会要求你的程序也开源**，本项目仍可按 Apache-2.0 自由分发（本项目未修改其 bootloader 源码）。
> 另外，PyInstaller 的 Run-time Hooks 部分单独采用 **Apache-2.0** 授权，与本项目一致。

完整的第三方署名信息整理在 [`NOTICE`](./NOTICE) 文件中。若你在自己的版本中新增了依赖，请一并核对并保留其许可声明。

---

## 十、参与贡献

欢迎同行一起完善，尤其是：

- 教学场景的新需求（你所在学校的特殊评分规则）
- 界面与交互的改进建议
- 使用中发现的 Bug

方式：直接提 Issue / Pull Request，或把想法发到下面的邮箱。如果这个工具在你的学校用上了，也欢迎来信说说使用效果。

> 请注意：依据 Apache-2.0 第 5 条，你提交的代码将自动以本协议授权给所有使用者，无需另行签署文件。

---

意见反馈：171883774@qq.com