# ClassSwap **Repository Path**: h2ocl/class-swap ## Basic Information - **Project Name**: ClassSwap - **Description**: ClassSwap 是一款专为学校教师设计的智能化换课管理系统，致力于解决教师日常教学中课程调换的痛点问题。系统采用现代化技术栈，提供流畅的用户体验和强大的功能支持。 - **Primary Language**: HTML - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-17 - **Last Updated**: 2026-04-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: MySQL, Nodejs, HTML, CSS, Express ## README # ClassSwap ClassSwap Logo 中文 | [English](https://gitee.com/h2ocl/class-swap/blob/master/README_EN.md) ## 📋 项目简介 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/Node.js-14.0%2B-green.svg)](https://nodejs.org/) [![MySQL](https://img.shields.io/badge/MySQL-5.7%2B-blue.svg)](https://www.mysql.com/) [![Gitee Stars](https://gitee.com/h2ocl/class-swap/badge/star.svg?theme=dark)](https://gitee.com/h2ocl/class-swap/stargazers) [![Gitee Forks](https://gitee.com/h2ocl/class-swap/badge/fork.svg?theme=dark)](https://gitee.com/h2ocl/class-swap/members) **ClassSwap** 是一款专为学校教师设计的智能化换课管理系统，致力于解决教师日常教学中课程调换的痛点问题。系统采用现代化技术栈，提供流畅的用户体验和强大的功能支持，帮助教师更高效地管理课程安排。 --- ## ✨ 项目亮点 - **学生预览功能**：无需登录即可查看今日课程和换课信息，方便学生和家长了解课程安排 - **智能换课匹配**：基于教师课表和时间冲突检测，自动推荐最佳换课方案，减少人工协调成本 - **实时消息通信**：WebSocket 实时推送，消息即时送达，支持一对一私聊，确保沟通顺畅 - **角色权限管理**：区分班主任与普通教师，实现精细化权限控制，保障系统安全 - **课程抢课功能**：课程腾空与抢课机制，提高课程资源利用率，解决临时调课需求 - **班主任课程编辑**：班主任可使用可视化课程表编辑器，批量编辑周一至周五课程 - **现代化 UI 设计**：采用毛玻璃效果和渐变色彩，白色文字配黑色阴影，打造时尚美观的用户体验 - **一键部署启动**：自动化脚本完成环境检测、数据库配置和服务启动，降低技术门槛 - **响应式设计**：适配桌面端和移动端，随时随地管理课程，提高使用灵活性 - **HTML 后缀隐藏**：所有页面均可通过简洁 URL 访问，无需输入 .html 后缀 --- ## 🛠️ 技术栈 | 分类 | 技术 | 版本 | 说明 | |------|------|------|------| | 前端 | HTML5 | - | 语义化标记，SEO 友好，结构清晰 | | 前端 | CSS3 | - | 毛玻璃效果、渐变动画，视觉效果出众 | | 前端 | JavaScript | ES6+ | 原生 JS，无框架依赖，运行高效 | | 后端 | Node.js | 14.0+ | 高性能服务端运行时，稳定可靠 | | 后端 | Express | 4.18+ | 轻量级 Web 框架，路由管理简洁 | | 数据库 | MySQL | 5.7+ | 稳定可靠的关系型数据库，数据存储安全 | | 实时通信 | Socket.io | 4.7.2 | 跨平台实时通信库，消息推送及时 | | 密码加密 | bcryptjs | 2.4.3 | 安全的密码哈希算法，保护用户密码 | --- ## 🎯 核心功能详解 ### 1. 教师管理模块 - **教师注册与登录**：支持新教师注册账号，现有教师登录系统 - **个人信息管理**：查看和管理个人基本信息，包括姓名、邮箱、所属部门等 - **角色权限分配**：区分班主任（可添加课程）和普通教师（只能管理自己的课程） - **教师列表与学科筛选**：查看全校教师信息，按学科部门筛选，方便联系和协调 - **账号管理**：支持教师查看个人账号信息，可随时注销账号 ### 2. 课程管理模块 - **个人课程表管理**：查看、添加、编辑、删除个人课程信息 - **今日/本周课程展示**：快速查看当日和当周课程安排，避免时间冲突 - **班主任专属课程添加**：只有班主任可以添加新课程，确保课程管理的规范性 - **班主任可视化课程编辑**：使用 lessons.html 课程表编辑器，批量编辑周一至周五课程 - **课程腾空与抢课**：教师可以将自己的课程腾空，其他教师可以抢课，提高课程资源利用率 - **课程详情查看**：查看课程的详细信息，包括上课时间、地点、课程代码等 ### 3. 学生预览模块 - **无需登录访问**：学生和家长可直接访问 view.html 查看课程信息 - **今日课程展示**：显示当天所有课程，包含教师、时间、地点信息 - **换课信息展示**：显示当天已批准的换课信息，包括原教师、代课教师、原因等 ### 4. 换课管理模块 - **换课申请发起**：教师可以发起换课申请，选择需要调换的课程和目标教师 - **换课申请处理**：接收换课申请的教师可以同意或拒绝申请 - **多种状态管理**：支持待处理、已同意、已拒绝、协商中等多种状态 - **换课记录查询**：查看历史换课记录，方便追溯和统计 - **消息提醒通知**：换课申请状态变更时，系统会发送消息提醒相关教师 ### 5. 消息通信模块 - **教师一对一实时私聊**：支持教师之间的实时聊天，方便沟通换课事宜 - **消息已读标记**：显示消息的已读/未读状态，避免消息遗漏 - **未读消息提醒**：当有新消息时，系统会显示未读消息数量提醒 - **聊天记录保存**：自动保存聊天记录，方便后续查看和参考 - **消息列表排序**：按最近消息时间排序，优先显示活跃的聊天对话 ### 6. 管理员模块 - **系统数据统计**：查看教师数、课程数、换课申请数、操作日志数等 - **操作日志查看**：追踪所有用户的操作记录 - **数据管理**：清空测试数据，重置系统 --- ## 📁 项目结构 ``` class-swap/ ├── frontend/ # 前端代码（30+ 文件） │ ├── css/ # CSS 样式文件 │ │ └── style.css # 全局样式与毛玻璃效果 │ ├── js/ # JavaScript 文件 │ │ ├── index.js # 首页逻辑 │ │ ├── login.js # 登录逻辑 │ │ ├── register.js # 注册逻辑 │ │ ├── courses.js # 课程管理逻辑 │ │ ├── head-teacher-courses.js # 班主任课程管理逻辑 │ │ ├── lessons.js # 课程表编辑器逻辑 │ │ ├── messages.js # 消息通信逻辑 │ │ ├── swap-requests.js # 换课申请逻辑 │ │ ├── teachers.js # 教师列表逻辑 │ │ ├── account.js # 账号管理逻辑 │ │ ├── admin-dashboard.js # 管理员后台逻辑 │ │ └── bing-bg.js # Bing每日一图背景 │ ├── admin/ # 管理员页面 │ │ └── dashboard.html # 管理员后台页面 │ ├── view.html # 学生预览页面（无需登录） │ ├── login.html # 教师登录页面 │ ├── head-teacher-login.html # 班主任登录页面 │ ├── admin-login.html # 管理员登录页面 │ ├── register.html # 教师注册页面 │ ├── index.html # 系统首页 │ ├── head-teacher-courses.html # 班主任课程管理页面 │ ├── lessons.html # 课程表编辑器页面 │ ├── courses.html # 课程管理页面 │ ├── swap-requests.html # 换课管理页面 │ ├── messages.html # 消息页面 │ ├── teachers.html # 教师列表页面 │ ├── courses-available.html # 可抢课程页面 │ └── account.html # 账号管理页面 ├── backend/ # 后端代码（20+ 文件） │ ├── controllers/ # 业务逻辑控制器 │ │ ├── teacherController.js # 教师控制器 │ │ ├── courseController.js # 课程控制器 │ │ ├── swapController.js # 换课控制器 │ │ ├── messageController.js # 消息控制器 │ │ └── adminController.js # 管理员控制器 │ ├── models/ # 数据访问层 │ │ ├── teacherModel.js # 教师模型 │ │ ├── courseModel.js # 课程模型 │ │ ├── swapRequestModel.js # 换课申请模型 │ │ ├── messageModel.js # 消息模型 │ │ ├── activityLogModel.js # 操作日志模型 │ │ └── adminModel.js # 管理员模型 │ ├── routes/ # API 路由定义 │ │ ├── teacherRoutes.js # 教师路由 │ │ ├── courseRoutes.js # 课程路由 │ │ ├── swapRequestRoutes.js # 换课路由 │ │ ├── messageRoutes.js # 消息路由 │ │ ├── adminRoutes.js # 管理员路由 │ │ └── bingRouter.js # Bing每日一图路由 │ ├── config/ # 配置文件 │ │ └── db.js # 数据库连接配置 │ ├── middleware/ # 中间件 │ │ └── auth.js # 认证中间件 │ └── server.js # 服务器入口文件 ├── scripts/ # 脚本文件 │ └── init-users.js # 数据库初始化脚本 ├── package.json # 项目依赖配置 └── README.md # 项目说明文档 ``` --- ## 🚀 快速开始指南 ### 环境要求 | 依赖 | 版本 | 说明 | 下载链接 | |------|------|------|----------| | Node.js | 14.0+ | 服务端运行环境 | [https://nodejs.org/](https://nodejs.org/) | | MySQL | 5.7+ | 关系型数据库 | [https://dev.mysql.com/downloads/](https://dev.mysql.com/downloads/) | | npm | 6.0+ | 包管理器（Node.js 自带） | 随 Node.js 安装 | | PowerShell | 5.0+ | 运行启动脚本 | Windows 10/11 自带 | ### 安装步骤 ```bash # 1. 克隆项目 git clone https://gitee.com/h2ocl/class-swap.git cd class-swap # 2. 安装依赖 npm install # 3. 启动服务（推荐使用一键脚本） ./server-start.ps1 ``` ### 首次运行配置 **重要：** 首次运行时，脚本会引导您完成以下配置： 1. **MySQL 连接配置** - 输入 MySQL 用户名（通常为 `root`） - 输入 MySQL 密码 - 测试连接是否成功 2. **免密登录设置** - 系统会询问是否保存凭据，方便后续使用 - 保存后，下次运行脚本无需再次输入密码 3. **数据库初始化** - 自动检查 `classswap` 数据库是否存在 - 如果不存在，自动创建数据库并导入结构 - 导入默认数据，包括： - 班主任账号：`head` / `123456` - 普通教师账号：`teacher1` / `123456`，`teacher2` / `123456`，`teacher3` / `123456` - 管理员账号：`admin` / `admin123` - 示例课程数据 4. **服务启动** - 自动启动前端和后端服务器 - 打开浏览器访问系统 - 按 `Ctrl+Q` 停止服务器 ### 默认账号信息 | 角色 | 用户名 | 密码 | 所属部门 | 权限 | |------|--------|------|----------|------| | 班主任 | head | 123456 | 教务处 | 可添加课程，管理所有功能，编辑课程表 | | 普通教师 | teacher1 | 123456 | 数学组 | 只能管理自己的课程，发起换课 | | 普通教师 | teacher2 | 123456 | 语文组 | 只能管理自己的课程，发起换课 | | 普通教师 | teacher3 | 123456 | 英语组 | 只能管理自己的课程，发起换课 | | 管理员 | admin | admin123 | 系统管理 | 系统管理、数据统计、日志查看 | ### 访问地址 **注意：** 所有页面均可通过不带 .html 后缀的 URL 访问，例如：`http://localhost:3000/login` | 页面 | URL（无后缀） | URL（带后缀） | 说明 | |------|--------------|--------------|------| | 学生预览 | /view | /view.html | 无需登录，查看今日课程和换课信息 | | 教师登录 | /login | /login.html | 教师登录入口 | | 班主任登录 | /head-teacher-login | /head-teacher-login.html | 班主任登录入口 | | 管理员登录 | /admin-login | /admin-login.html | 管理员登录入口 | | 系统首页 | /index | /index.html | 教师登录后的首页 | | 课程管理 | /head-teacher-courses | /head-teacher-courses.html | 班主任课程管理 | | 课程表编辑 | /lessons | /lessons.html | 班主任课程表编辑器 | | 换课管理 | /swap-requests | /swap-requests.html | 换课申请管理 | | 可抢课程 | /courses-available | /courses-available.html | 可抢课程列表 | | 消息 | /messages | /messages.html | 消息中心 | | 教师列表 | /teachers | /teachers.html | 教师列表 | | 账号管理 | /account | /account.html | 账号信息管理 | | 管理员后台 | /admin-dashboard | /admin-dashboard.html | 系统管理和统计 | --- ## 📖 详细使用指南 ### 功能操作指南 #### 1. 学生预览（无需登录） 1. **访问预览页面**：直接访问 `http://localhost:3000/view` 2. **查看今日课程**：页面显示当天所有课程信息 3. **查看换课信息**：显示当天已批准的换课信息 #### 2. 课程管理（班主任） 1. **查看课程**：登录后点击"课程管理"进入课程列表 2. **添加课程**：点击"添加课程"按钮，填写课程信息 3. **编辑课程**：点击课程卡片上的"编辑"按钮修改课程信息 4. **删除课程**：点击课程卡片上的"删除"按钮删除课程 5. **腾空课程**：点击课程卡片上的"腾空"按钮，将课程标记为可抢状态 #### 3. 课程表编辑（班主任） 1. **访问编辑器**：点击"课程表编辑"进入编辑器 2. **编辑课程**：在周一至周五各栏中添加、编辑、删除课程 3. **设置时间和地点**：为每门课程设置开始时间、结束时间和上课地点 4. **应用到系统**：点击"应用到系统"按钮，将课程表批量应用到系统 #### 4. 换课管理 1. **发起换课**：点击"换课管理" → "发起换课"，选择要换的课程和目标教师 2. **处理换课申请**：在"换课管理" → "收到的申请"中查看并处理申请 3. **查看换课记录**：在"换课管理" → "历史记录"中查看所有换课记录 #### 5. 消息中心 1. **查看消息**：点击"消息"进入消息中心 2. **发送消息**：选择教师列表中的教师，在聊天框中输入消息并发送 3. **查看未读消息**：消息列表中会显示未读消息数量 #### 6. 抢课功能 1. **查看可抢课程**：点击"可抢课程"进入抢课页面 2. **抢课**：点击课程卡片上的"抢课"按钮，确认后即可获得该课程 3. **查看已抢课程**：抢课后课程会显示在个人课程列表中 #### 7. 管理员后台 1. **访问后台**：以管理员账号登录后访问 `http://localhost:3000/admin-dashboard` 2. **查看统计**：仪表盘显示系统各项统计数据 3. **查看日志**：在"操作日志"中查看所有用户的操作记录 4. **数据管理**：可清空测试数据，重置系统 --- ## 🤝 贡献指南 欢迎开发者参与项目贡献！ ### 贡献流程 1. **Fork 项目**：点击右上角 Fork 按钮，创建自己的分支 2. **创建功能分支**：`git checkout -b feature/your-feature` 3. **提交代码**：`git commit -m "Add your feature"` 4. **推送分支**：`git push origin feature/your-feature` 5. **创建 PR**：在 Gitee 上创建 Pull Request，描述功能或修复 ### 代码规范 - **JavaScript**：遵循 ESLint 规范，使用 2 空格缩进 - **CSS**：使用 BEM 命名规范，保持代码清晰 - **HTML**：使用语义化标签，保持结构清晰 - **提交信息**：使用 Conventional Commits 格式，描述清晰 --- ## 🔧 技术细节 ### 数据库设计 **核心表结构：** | 表名 | 用途 | 关键字段 | 说明 | |------|------|----------|------| | teachers | 教师信息 | id, name, username, role | 存储教师基本信息和角色 | | courses | 课程信息 | id, teacher_id, course_name, day_of_week, start_time, end_time, location, is_available | 存储课程信息和是否可抢状态 | | swap_requests | 换课申请 | id, requester_id, receiver_id, course_id, status, message | 存储换课申请信息和状态 | | messages | 消息记录 | id, sender_id, receiver_id, content, is_read | 存储消息内容和已读状态 | | admins | 管理员信息 | id, username, password | 存储系统管理员信息 | | activity_logs | 操作日志 | id, user_id, action, details | 存储用户操作记录 | ### API 接口 **认证接口：** - `POST /api/teachers/login` - 教师登录 - `POST /api/teachers/logout` - 教师登出 - `POST /api/teachers/register` - 教师注册 - `POST /api/teachers/delete` - 删除教师账号 **课程接口：** - `GET /api/courses/my` - 获取当前用户的课程 - `GET /api/courses/week/list` - 获取本周课程列表 - `POST /api/courses` - 添加课程 - `PUT /api/courses/:id` - 更新课程信息 - `DELETE /api/courses/:id` - 删除课程 - `PUT /api/courses/:id/available` - 设置课程可抢状态 - `GET /api/courses/available` - 获取可抢课程列表 - `POST /api/courses/:id/claim` - 抢课 - `GET /api/courses/public/today` - 获取今日课程（公开API，学生预览用） **换课接口：** - `GET /api/swap-requests/my-requests` - 获取当前用户发起的换课申请 - `GET /api/swap-requests/my-received` - 获取当前用户收到的换课申请 - `POST /api/swap-requests` - 发起换课申请 - `PUT /api/swap-requests/:id/accept` - 同意换课申请 - `PUT /api/swap-requests/:id/reject` - 拒绝换课申请 - `GET /api/swap-requests/public/today` - 获取今日换课信息（公开API，学生预览用） **消息接口：** - `GET /api/messages/conversations` - 获取对话列表 - `GET /api/messages/:teacherId` - 获取与特定教师的消息 - `POST /api/messages` - 发送消息 - `PUT /api/messages/:id/read` - 标记消息为已读 **管理员接口：** - `GET /api/admin/stats` - 获取系统统计 - `GET /api/admin/logs` - 获取操作日志 - `DELETE /api/admin/test-data` - 清空测试数据 --- ## 📊 项目统计 | 指标 | 数值 | 说明 | |------|------|------| | 代码行数 | 10000+ | 包括前后端所有代码 | | 文件数量 | 50+ | 项目总文件数 | | 功能模块 | 7 个核心模块 | 教师、学生预览、课程管理、课程表编辑、换课管理、消息通信、管理员 | | API 接口 | 25+ | 完整的 RESTful API | | 数据库表 | 6 张 | 教师、课程、换课申请、消息、管理员、操作日志 | | 默认账号 | 5 个 | 1 个班主任，3 个普通教师，1 个管理员 | --- ## ❓ 常见问题解答 ### 1. 登录失败怎么办？ - **检查用户名和密码**：确保输入的用户名和密码正确 - **检查数据库连接**：确保 MySQL 服务正常运行 - **检查网络连接**：确保服务器正在运行 - **默认账号**：尝试使用默认账号 `head` / `123456` 登录 ### 2. 无法添加课程怎么办？ - **检查权限**：只有班主任账号可以添加课程 - **检查表单**：确保所有必填字段都已填写 - **检查时间冲突**：避免添加与现有课程时间冲突的课程 ### 3. 学生看不到课程怎么办？ - **检查日期**：确保访问日期是周一至周五 - **检查课程数据**：确保数据库中有今天的课程数据 ### 4. 服务器启动失败怎么办？ - **检查端口**：确保 3000 端口未被占用 - **检查依赖**：确保所有依赖已正确安装 - **检查 MySQL**：确保 MySQL 服务正常运行 - **查看错误信息**：根据错误信息进行排查 --- ## 🛡️ 安全注意事项 1. **密码安全**： - 定期更换密码 - 使用强密码（包含字母、数字、特殊字符） - 不要与他人共享密码 2. **数据安全**： - 定期备份数据库 - 不要在系统中存储敏感信息 - 遵循学校数据管理规定 3. **系统安全**： - 定期更新系统 - 确保服务器防火墙已开启 - 限制系统访问权限 --- ## 📄 许可证 MIT License Copyright (c) 2026 h2ocl --- ## 📞 联系方式 - **项目仓库**：[https://gitee.com/h2ocl/class-swap](https://gitee.com/h2ocl/class-swap) - **开发者**：h2ocl - **技术交流**：欢迎提交 Issue 和 Pull Request - **问题反馈**：请在 Gitee 仓库中提交 Issue --- **ClassSwap** - 让教师换课更简单，让课程管理更高效！ 🎓 *版本：v1.1.0 | 最后更新：2026-04-25*