# T-Class

**Repository Path**: lumoumou/t-class

## Basic Information

- **Project Name**: T-Class
- **Description**: 基于 Electron 构建的教学-学习双端系统,实现教师发布试卷、学生在线答题、实时监控答题进度的完整闭环。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-23
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教学-学习系统

基于 Electron 构建的教学-学习双端系统,实现教师发布试卷、学生在线答题、实时监控答题进度的完整闭环。

## TODO
**一期**：基本1
- [x] 教学端和学习端实时监控的答题进度，和学习端上标绿的答题状态不匹配，标绿的是准确的。
**二期**：基本2
- [x] 题目管理-查看题目功能完善
- [x] 教师查看答卷的功能，包括查看历史答卷
- [x] 选择题、判断题自动评分的功能
- [x] 填空题完全吻合的答案自动评分
- [x] 填空题未完全吻合的部分手动评分的功能
- [x] 攒勋章功能：将每个知识点拆分为一份试卷，每完成一份试卷获得一个勋章。
- [x] 在监控页面中实现点击按钮更新全部已交卷的评分，显示获得的分数。仅针对可自动评分的选择题、判断题和完全吻合的填空题。
- [ ] 勋章功能优化，重新梳理
- [ ] 优化:
  - [x] 实时监控页面中的最后活跃时间不对（少了8小时）
  - [ ] 学生端支持查看历史成绩
  - [ ] 实时监控支持监控窗口切换次数
**二.5期**：复习模式和AI接入
详见需求文档“期末复习功能.md”。并实现接入阿里云的qwen-flash模型。
- [x] AI根据文档生成知识点和试题
- [x] 实现复习模式下阶段式答题的功能
- [ ] 以实际应用进一步全流程完善细节
  - [ ] 没有监控页面
  - [ ] 没有成就页面
**三期**：AI接入进行评分
- [ ] 填空题未完全吻合的部分调用AI评分的功能
- [ ] 主观题调用AI自动评分的功能
**四期**：题库的实现
- [ ] 实现题库组卷，根据知识点组装试卷
**五期**：知识图谱的实现
- [ ] 知识图谱接入
**六期**：学生个性化
- [ ] 根据学生的知识点覆盖情况生成差异化试卷、题目

## 词汇
- 教学端：统一名称
- 学习端：统一名称

## 系统架构

- **教学端 (t-teach)**: 教师使用,兼具服务端功能
  - 学生管理
  - 题目管理(支持选择题、判断题和填空题)
  - 试卷管理
  - 实时监控学生答题状态
  - HTTP 服务器(端口 3000)

- **学习端 (t-learn)**: 学生使用
  - 学生登录
  - 查看活跃试卷
  - 在线答题
  - 实时提交答案

## 技术栈

- **前端框架**: Electron
- **服务端**: Express
- **数据库**: SQLite (better-sqlite3)
- **身份认证**: JWT + bcrypt
- **通信方式**: HTTP 轮询

## 安装依赖

### 教学端

```bash
cd t-teach
npm install
```

### 学习端

```bash
cd t-learn
npm install
```

注意: 如果 npm 安装遇到网络问题,可以尝试:
```bash
npm install --registry=https://registry.npmmirror.com
```

## 启动系统

### 1. 启动教学端

```bash
cd t-teach
npm start
```

教学端启动后会:
- 自动初始化 SQLite 数据库
- 启动 HTTP 服务器在 3000 端口
- 打开教学管理界面

### 2. 启动学习端

```bash
cd t-learn
npm start
```

学习端启动后会显示登录界面,学生输入学号和密码登录。

## 使用流程

### 教师端操作流程

1. **管理学生**
   - 在"学生管理"模块添加学生
   - 可以单个添加或批量导入 CSV
   - CSV 格式: `学号,姓名,密码(可选,默认123456)`
   - 示例:
     ```csv
     student_id,name,password
     20240001,张三,123456
     20240002,李四
     ```

2. **创建试卷**
   - 在"试卷管理"模块创建新试卷
   - 填写试卷标题和考试时长(可选)

3. **添加题目**
   - 在“题目管理”模块选择试卷
   - 通过表单逐题添加,或批量导入 JSON
   - JSON 格式示例:
     ```json
     [
       {
         "question_type": "choice",
         "question_text": "以下哪个是 JavaScript 的数据类型?",
         "options": ["String", "Integer", "Character", "Float"],
         "correct_answer": "A",
         "score": 10
       },
       {
         "question_type": "judge",
         "question_text": "JavaScript 是强类型语言",
         "correct_answer": "false",
         "score": 5
       },
       {
         "question_type": "fill_blank",
         "question_text": "JavaScript 是一种___语言,常用于___开发",
         "options": [
           {
             "blank_index": 1,
             "validate_rules": ["trim", "ignore_case", "multiple_answers"],
             "possible_answers": ["脚本", "解释型"]
           },
           {
             "blank_index": 2,
             "validate_rules": ["trim", "ignore_case", "multiple_answers"],
             "possible_answers": ["Web", "网页", "前端"]
           }
         ],
         "correct_answer": "[\"脚本\", \"Web\"]",
         "score": 10
       }
     ]
     ```
   - 填空题创建说明:
     - 使用连续3个及以上下划线(`___`)标记填空位置
     - 系统自动检测填空数量并生成配置表单
     - 每个填空可配置多个可接受答案
     - 默认支持忽略大小写、忽略前后空格
     - 多空题按空比例评分(例:答对2/3个空,得2/3分数)

4. **发布试卷**
   - 在"试卷管理"模块点击"发布"按钮
   - 同一时间只能有一份活跃试卷
   - 发布新试卷会自动撤回旧试卷

5. **实时监控**
   - 在"实时监控"模块查看学生答题状态
   - 显示每个学生的答题进度和班级统计
   - 数据每 3 秒自动刷新

### 学生端操作流程

1. **登录**
   - 输入教师分配的学号和密码
   - 首次登录密码通常为 `123456`

2. **查看试卷**
   - 登录后自动轮询活跃试卷(每 5 秒)
   - 显示试卷标题、题目数量、时长等信息

3. **开始答题**
   - 点击"开始答题"按钮进入答题页面
   - 每次选择/修改答案后自动提交到服务器
   - 右侧显示答题卡,绿色表示已答题

4. **提交试卷**
   - 完成所有题目后点击"提交试卷"
   - 未答完也可以提交,系统会提示

5. **修改密码**
   - 登录页面点击"修改密码"链接
   - 输入学号、旧密码和新密码

## 数据存储

教学端的数据存储在用户目录下:
- Windows: `C:\Users\<用户名>\AppData\Roaming\t-teach\teaching.db`
- macOS: `~/Library/Application Support/t-teach/teaching.db`
- Linux: `~/.config/t-teach/teaching.db`

数据库包含以下表:
- `students`: 学生信息
- `papers`: 试卷信息
- `questions`: 题目信息
- `answers`: 答题记录
- `answer_sessions`: 答题会话

## API 接口

教学端提供以下 HTTP API (http://localhost:3000):

| 端点 | 方法 | 功能 |
|------|------|------|
| /api/login | POST | 学生登录 |
| /api/student/change-password | POST | 修改密码 |
| /api/paper/active | GET | 获取活跃试卷 |
| /api/answer/start | POST | 开始答题 |
| /api/answer/submit | POST | 提交单题答案 |
| /api/answer/finish | POST | 完成答卷 |

## 注意事项

1. **网络连接**: 学习端需要能够访问教学端的 3000 端口,确保在同一局域网内
2. **服务器地址**: 如果教学端不在本机,需要修改 `t-learn/main.js` 中的 `SERVER_URL`
3. **并发支持**: 系统设计支持大班规模(100人以上)
4. **数据安全**: 学生密码使用 bcrypt 加密存储
5. **轮询机制**:
   - 学习端轮询活跃试卷: 5 秒
   - 答题时检测试卷状态: 10 秒
   - 教学端监控刷新: 3 秒

## 常见问题

### 1. 学习端无法连接服务器
- 确保教学端已启动
- 检查防火墙是否允许 3000 端口
- 确认网络连接正常

### 2. 依赖安装失败
- 尝试使用国内镜像源安装
- 检查 Node.js 版本(建议 16+)

### 3. 数据库相关错误
- 删除数据库文件重新初始化
- 检查文件权限

# 打包发布

系统支持打包为独立可执行文件,无需安装 Node.js 环境即可运行。

### 安装打包工具

首先需要在两个端安装 electron-builder:

```bash
# 教学端
cd t-teach
npm install electron-builder --save-dev

# 学习端
cd t-learn
npm install electron-builder --save-dev
```

### 打包教学端

```bash
cd t-teach
npm run build
```

打包成功后,生成的文件位于 `dist` 目录:
- `T-Teach-教学端-1.0.0-portable.exe` (绿色便携版)

### 打包学习端

```bash
cd t-learn
npm run build
```

打包成功后,生成的文件位于 `dist` 目录:
- `T-Learn-学习端-1.0.0-portable.exe` (绿色便携版)

### 打包说明

1. **便携版特点**:
   - 无需安装,双击即可运行
   - 数据存储在用户目录,不受程序位置影响
   - 适合批量分发给学生使用

2. **打包配置**:
   - 目标平台: Windows x64
   - 打包格式: Portable (便携版)
   - 输出目录: `../dist` (项目根目录下的 dist 文件夹)

3. **首次打包注意事项**:
   - 首次打包会下载 Electron 二进制文件(约 100MB)
   - 如果网络较慢,可设置镜像源:
     ```bash
     set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
     ```
   - 打包时间约 2-5 分钟,请耐心等待

4. **分发说明**:
   - 教学端分发给教师使用
   - 学习端可以批量分发给学生
   - 学生端连接服务器需要修改 `SERVER_URL`(见下方网络配置)

### 跨机器部署

如果学习端和教学端不在同一台电脑:

1. **修改服务器地址** (打包前修改):
   
   编辑 `t-learn/main.js`,找到:
   ```javascript
   const SERVER_URL = 'http://localhost:3000';
   ```
   
   修改为教学端的 IP 地址:
   ```javascript
   const SERVER_URL = 'http://192.168.1.100:3000';  // 替换为实际 IP
   ```

2. **防火墙配置**:
   - 在教学端电脑上允许 3000 端口入站连接
   - Windows 防火墙设置步骤:
     1. 打开"Windows Defender 防火墙"
     2. 点击"高级设置"
     3. 添加入站规则,允许 TCP 端口 3000

3. **网络测试**:
   在学生端电脑上测试连接:
   ```bash
   curl http://192.168.1.100:3000/api/paper/active
   ```
   如果返回 JSON 数据则表示连接成功。

## 开发说明

### 项目结构

```
t-class/
├── t-teach/              # 教学端
│   ├── main.js          # 主进程
│   ├── database.js      # 数据库管理
│   ├── server.js        # HTTP 服务器
│   ├── renderer.js      # 渲染进程
│   ├── index.html       # 主界面
│   ├── styles.css       # 样式文件
│   └── package.json     # 依赖配置
│
└── t-learn/             # 学习端
    ├── main.js          # 主进程
    ├── renderer.js      # 渲染进程
    ├── index.html       # 主界面
    ├── styles.css       # 样式文件
    └── package.json     # 依赖配置
```

### 扩展功能

如需添加新功能,可以参考以下扩展点:
- 添加新题型: 修改 `database.js` 和 `renderer.js` 中的题目渲染逻辑
- 添加统计图表: 在监控模块中引入图表库(如 Chart.js)
- 支持图片题目: 添加图片上传和显示功能
- 导出成绩: 在教学端添加导出 Excel 功能

## 许可证

MIT License