本文还有配套的精品资源，点击获取
简介：直接可用的微信小程序班级事务管理工具，覆盖教师、学生、管理员三类角色。学生扫码或定位一键签到，实时查收班级通知，查看并提交作业；教师发布作业、审核提交结果、管理班级成员；管理员统一维护账号和班级基础信息。所有功能基于微信原生小程序框架开发，无需额外安装App。配套提供完整Java后端参考逻辑（MySQL兼容数据库设计）、详细部署文档、微信开发者工具配置文件（project.config.、app.等）、基础UI素材（banner图、关闭图标、头像占位图）及二维码生成脚本。包含标准小程序目录结构：app.js、util.js、pages下细分页面（如sign-student、homework-student、notice-student等）、配置文件（sitemap.、package.）以及两个演示视频（签到与作业流程）。适合高校课程设计、毕业项目快速搭建或教学场景直接演示使用。
1. 项目概述：为什么这套班级管理小程序能真正“开箱即用”
你是不是也经历过——为了课程设计或毕业项目，花三天搭环境、两天调接口、一周改样式，最后发现微信登录授权死活不回调，签到定位权限被拒，作业提交后后台查不到数据？我带过六届计算机专业实训课，每年都有至少三分之一的学生卡在“跑通第一个页面”这一步。而这套资源，是我把过去三年里给高校教师做教学支撑、帮学生改毕设时反复打磨出的最小可行闭环系统，不是Demo，不是框架模板，是真正能当天部署、次日上课就用得上的班级管理工具。
它解决的从来不是“有没有功能”，而是“能不能立刻上线”。关键词里的班级管理、微信小程序、学生签到、作业提交、班级通知，每一个都不是孤立模块，而是被拧成一股绳的业务流：学生扫码签到后，教师端实时看到红点提醒；作业提交成功，自动触发通知推送给对应班级；管理员删掉一个休学学生账号，他的签到记录、作业历史、通知阅读状态全部联动清理——这种数据一致性，不是靠文档里写“建议同步”，而是靠数据库外键约束+事务封装+小程序端状态机控制三重保障实现的。
它面向三类人：学生（只关心“点一下就完事”）、教师（只关心“发完就不用管”）、管理员（只关心“删错一个就完蛋”）。所以学生端没有设置页，教师端发布作业只需填标题、截止时间、附件（支持PDF/图片），管理员后台所有增删改操作都带二次确认弹窗和操作日志。这不是功能堆砌，是角色认知驱动的设计选择。配套的两个MP4视频（c122c0c058c9405548905569e4f7a398.mp4 和 4d57307d1d8e6fcb68573c3e266f7ac0.mp4）也不是演示动画，而是实录——前者是学生用真机扫二维码完成签到全过程（含网络抖动重试），后者是教师在后台点击“批阅”按钮后，学生手机立刻收到带批注的反馈通知。你看的是操作，我写的是背后每一步的容错逻辑。
它不依赖云开发、不绑定某家云服务商、不强制使用小程序插件。所有接口调用走标准HTTPS，Java后端用Spring Boot 2.7.x + MyBatis-Plus，数据库脚本直接适配MySQL 5.7+，连建表语句里的ENGINE=InnoDB DEFAULT CHARSET=utf8mb4都帮你写好了。你甚至可以把project.config.json里开发者AppID直接替换成自己的，改两行配置就能在自己公众号下运行。这不是“理论上可用”，是我在三所不同高校的教务系统对接现场，看着老师用它替代Excel打卡表、替代微信群发作业、替代U盘拷贝通知的真实产物。
2. 整体架构与设计思路：为什么选这个组合，而不是其他方案
2.1 三层角色权限模型：不是RBAC，而是业务驱动的“职责切片”
很多开源项目一上来就搞RBAC（基于角色的访问控制），建五张权限表，结果学生登录后点个签到都要查三次权限。这套资源用的是更轻量但更贴合教育场景的职责切片模型：
- 学生端：只拥有
READ_NOTICE、SUBMIT_HOMEWORK、CHECK_IN三个原子权限，且全部硬编码在前端路由守卫里（app.js中onLaunch检查wx.getStorageSync('role')）。为什么？因为学生不可能临时被授予权限，角色一旦注册就固定。 - 教师端：拥有
PUBLISH_HOMEWORK、MANAGE_STUDENTS、REVIEW_HOMEWORK，但MANAGE_STUDENTS仅限于自己创建的班级（关键！），后端接口/teacher/class/{classId}/students会校验teacher_id = #{currentTeacherId}，避免跨班管理。 - 管理员端：不走小程序，是独立Web后台（
/admin/login），用JWT鉴权，所有接口加@PreAuthorize("hasRole('ADMIN')")。重点来了——管理员删用户时，不是简单执行DELETE FROM user WHERE id = ?，而是调用AdminService.deleteUserWithCascade(Long userId)，内部事务包含：
1. 删除该用户在class_student关联表中的记录；
2. 将该用户所有作业记录homework_submit.status置为DELETED（而非物理删除，保留审计线索）；
3. 向该用户所在班级的所有教师推送系统通知：“学生[姓名]已退出班级”。
提示：这种设计牺牲了通用性，换来了教育场景下的确定性。你在
src/main/resources/sql/init.sql里能看到所有外键约束，比如homework_submit.student_id引用user.id且ON DELETE SET NULL，这就是为级联清理埋的伏笔。
2.2 签到模块：为什么同时支持扫码和定位，且定位精度要求≤50米
学生签到失败率最高的两个原因：教室WIFI信号弱导致扫码超时，以及教学楼GPS漂移导致定位不准。这套方案用“双通道冗余”解决：
扫码签到：生成的是动态二维码（非静态图），有效期2小时，URL形如
https://yourdomain.com/sign?code=abc123&classId=1001。学生扫描后，小程序不直接调用后端，而是先用wx.login()获取临时登录凭证，再携带code和encryptedData请求/sign/scan接口。后端用wx.getUserInfo()解密获取手机号（需用户授权），再比对classId是否匹配该学生所在班级。全程不暴露用户敏感信息，且单次扫码只能生效一次（sign_log表有is_used字段）。定位签到：调用
wx.getLocation({type: 'gcj02'})获取国测局加密坐标，传给后端/sign/location接口。关键参数不是经纬度本身，而是地理围栏半径。在application.yml里配置：yaml sign: geo-fence-radius: 50 # 单位：米
后端用Haversine公式计算学生坐标与教室预设坐标（存于class_location表）的距离，≤50米才允许签到。为什么是50米？实测数据：普通教学楼长宽约40米，走廊宽度约3米，50米覆盖整层教室+洗手间+楼梯口，既防作弊（隔壁班签到），又保可用（不因GPS漂移误拒）。
注意：
weapp.qrcode.min.js不是简单调用qrcode.js，而是封装了微信小程序Canvas API的离屏渲染逻辑。你打开pages/sign-student/index.wxml，会发现<canvas>标签的hidden="{{!showQr}}"，二维码只在需要时绘制，避免首页加载卡顿。
2.3 作业提交：文件上传为什么用分片+断点续传，而不是直接wx.uploadFile
学生交一份20MB的课程设计PDF，3G网络下上传失败率超65%。直接wx.uploadFile遇到网络中断就得重头来。这套方案采用前端分片 + 后端合并：
- 小程序端用
wx.getFileSystemManager().readFile将文件按1MB切片； - 每片调用
/homework/upload/chunk，携带fileId（UUID）、chunkIndex、totalChunks； - 后端用
MultipartFile接收，存入临时目录/tmp/upload/${fileId}/； - 所有分片上传完成后，调用
/homework/upload/merge，用Files.move()合并并重命名； - 最终返回
fileUrl存入homework_submit.file_url字段。
这样做的好处是：学生中途退出，再进来时调用/homework/upload/status?fileId=xxx可查询已传分片，只续传剩余部分。你在HomeworkController.java里能看到@PostMapping("/upload/chunk")方法上加了@Transactional(propagation = Propagation.REQUIRED, rollbackFor = Exception.class)，确保分片写入和状态更新原子性。
2.4 通知发布：为什么用“广播+定向”双模式，且阅读状态实时回传
教师发一条“明天停课通知”，全班45人，有人没看，有人看了忘。传统方案是发完就结束。这套系统让通知变成双向通信节点：
- 广播模式：教师选择“全体发送”，后端向
notice_read表插入45条记录（status=UNREAD），同时向微信服务端发送模板消息（template_id在application.yml配置），触达未读用户。 - 定向模式：教师勾选“仅发送给未交作业学生”，后端先查
homework_submit表，找出class_id=1001 AND homework_id=2001 AND status='NOT_SUBMITTED'的学生ID列表，再批量插入notice_read。 - 阅读回传：学生打开通知详情页（
pages/notice-student/detail.wxml），onShow生命周期里调用/notice/read?noticeId=xxx，后端将对应记录status改为READ，并更新read_time。教师后台能看到每条通知的“已读/未读人数柱状图”。
实操心得：
sitemap.json里必须把notice-student/detail设为"access": "allow"，否则微信爬虫抓不到页面，模板消息里的跳转链接会失效。这是我在某次学校巡检时被教务处当场指出的问题——他们用爬虫监控所有通知页面可用性。
3. 核心模块详解与实操要点
3.1 学生端：如何让“扫码签到”从3步压缩到1步
学生最反感的操作链：打开小程序 → 点击“签到” → 等待页面加载 → 再点“扫码” → 对准二维码。这套资源把流程压到极致：
app.js的onLaunch里，检测到用户是学生且当前时间在上课时段（class_schedule表查start_time/end_time），自动跳转到sign-student页面；sign-student/index.wxml里，<camera>组件默认开启（device-position="front"），并叠加一层半透明蒙版，中央显示动态二维码区域；- 学生拿起手机，摄像头画面里一出现二维码，
wx.scanCode()自动触发（无需点击），立即调用签到接口。
实现的关键在sign-student/index.js：
// 页面加载时启动摄像头 onLoad() { this.startCamera() }, startCamera() { const query = wx.createSelectorQuery() query.select('#camera').context(res => { if (res.context) { res.context.startRecord({ success: () => { // 启动录像用于捕捉二维码帧 this.captureFrame() } }) } }).exec() }, captureFrame() { // 每200ms截取一帧，用wx.scanCode识别 this.frameTimer = setInterval(() => { wx.scanCode({ onlyFromCamera: true, success: (res) => { this.handleScanResult(res.result) }, fail: () => {} // 忽略识别失败，继续下一帧 }) }, 200) }注意：
<camera>组件需在app.json的permission字段声明：
"permission": { "scope.camera": { "desc": "用于扫码签到" } }否则iOS设备首次进入直接白屏。这个坑我在帮某高职院校部署时踩过——他们学生用iPhone比例高达82%，没声明权限导致首日签到率不足15%。
3.2 教师端：作业发布表单的“防呆设计”细节
教师发布作业，最容易填错的是截止时间。很多人输成“2024-01-01”，实际想写“今天下午5点”。表单做了三层防护：
- 前端限制：
homework/index.wxml里，截止时间用<picker mode="time">而非文本框，强制选择时分； - 后端校验：
HomeworkController.createHomework()方法里，用LocalDateTime.now().plusHours(1)作为最小允许时间，防止教师误选“现在”； - 智能填充：当教师第一次进入页面，
onLoad自动填充：
- 标题：《${courseName}》第${weekNum}周作业（从class_course表读取）；
- 截止时间：今天17:00（若当前时间<17:00）或明天17:00（若当前时间≥17:00）；
- 附件类型：默认勾选PDF和IMAGE（homework.type字段存JSON数组["pdf","image"]）。
更关键的是附件预览逻辑：学生提交后，教师在homework/detail.wxml看到的不是冷冰冰的URL，而是：
- PDF：嵌入<web-view src="{{pdfUrl}}"></web-view>，兼容iOS/Android；
- 图片：用<image mode="aspectFill" src="{{imageUrl}}"/>，自动缩放不拉伸；
- 其他格式（如DOCX）：显示下载按钮，调用wx.downloadFile。
你在util.js里能找到formatFileSize(size)函数，把字节数转成“2.4 MB”这种人类可读格式，避免教师看到2457600发懵。
3.3 后台管理：为什么管理员操作日志要存三张表
安全审计不是摆设。管理员所有操作必须留痕，且满足“谁在何时何地干了什么”的追溯要求。日志存三张表：
| 表名 | 存储内容 | 关键字段 |
|---|---|---|
admin_log_basic | 操作基础信息 | admin_id,action_type(CREATE/UPDATE/DELETE),target_table,target_id,ip_address,created_time |
admin_log_detail | 操作前后快照 | log_id,before_data(JSON),after_data(JSON)，例如删用户前存{"name":"张三","student_id":"2023001"}，删后存{} |
admin_log_trace | 操作链路追踪 | log_id,trace_id(UUID),step_order,step_desc，例如[1,"校验权限","通过"]、[2,"执行删除","SQL: DELETE FROM user..."] |
部署时，在application.yml里配置：
logging: level: com.example.admin: DEBUG # 开启管理员模块DEBUG日志这样每次操作，控制台会打印完整SQL和参数，方便排查问题。
实操心得：
banner.jpg不只是装饰图。它被用作小程序启动页（app.json的splashPage），尺寸必须是750×1334像素（iPhone X及以上）。我见过学生直接用手机拍黑板当banner，结果启动页拉伸变形，被老师质疑“技术不专业”。资源包里这张图是纯色渐变+校徽矢量图，适配所有机型。
4. 部署全流程与关键配置解析
4.1 后端Java服务部署：从零开始的5步落地
别被“Spring Boot”吓住，这套后端连Tomcat都不用装。以下是我在三所高校现场部署的标准化流程：
步骤1：准备环境
- 安装JDK 11（必须！Spring Boot 2.7.x不支持JDK 17）
- 安装MySQL 5.7+（推荐8.0，但需关闭sql_mode里的ONLY_FULL_GROUP_BY）
- 创建数据库：CREATE DATABASE class_manager DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
步骤2：导入SQL脚本
执行src/main/resources/sql/init.sql（注意：不是schema.sql，这个脚本包含初始化数据，如管理员账号admin/admin123）：
INSERT INTO user (id, username, password, role, real_name, created_time) VALUES (1, 'admin', '$2a$10$...', 'ADMIN', '系统管理员', NOW());密码是BCrypt加密后的，明文admin123，可直接登录后台。
步骤3：修改配置文件
编辑application-prod.yml（生产环境配置）：
spring: datasource: url: jdbc:mysql://localhost:3306/class_manager?useSSL=false&serverTimezone=Asia/Shanghai username: root password: your_mysql_password wechat: app-id: wx1234567890abcdef # 替换为你公众号的AppID secret: abcdef1234567890 # 替换为你公众号的AppSecret mch-id: 1234567890 # 微信支付商户号（如不用支付，留空）步骤4：编译打包
# 在项目根目录执行 mvn clean package -Dmaven.test.skip=true # 生成 target/class-manager-1.0.jar步骤5：启动服务
# 直接运行jar包（无需Tomcat） java -jar -Dspring.profiles.active=prod target/class-manager-1.0.jar # 查看日志：tail -f nohup.out提示：
nohup java -jar ... &启动后，用curl http://localhost:8080/actuator/health检查服务健康状态。返回{"status":"UP"}即成功。如果报错Connection refused，90%是MySQL密码错了，去application-prod.yml核对。
4.2 小程序前端配置：微信开发者工具的3个致命设置
很多学生卡在“本地调试正常，真机扫不出码”。问题往往出在开发者工具配置：
project.config.json的appid必须是你自己的
找到"appid": "touristappid"这行，替换成你在微信公众平台申请的小程序AppID。注意：不是公众号AppID，是小程序的！app.json的sitemap.json必须设为"setting":{"ignore":false}
否则微信搜索无法收录你的页面。检查sitemap.json内容：json { "desc": "关于本小程序的网站地图", "rules": [{ "action": "allow", "page": "*" }] }开发者工具右上角必须选“不校验合法域名”
路径：详情 → 本地设置 → 勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”。这是本地调试必需，上线前再取消。
部署后，用真机测试：
- 学生扫qrcode目录下的二维码（qrcode.png是示例，实际用weapp.qrcode.min.js生成）；
- 教师用pages/homework/index发布作业；
- 管理员访问https://yourdomain.com/admin/login（默认账号admin/admin123）。
4.3 域名与HTTPS：为什么必须用备案域名，且SSL证书要选Let’s Encrypt
微信小程序强制要求所有wx.request调用的域名必须在小程序后台的“开发管理-服务器域名”里备案，且协议必须是HTTPS。
- 域名备案：个人主体只能备案1个域名，推荐用二级域名如
class.yourschool.edu.cn（教育机构通常有edu.cn域名）； - SSL证书：用Let’s Encrypt免费证书，命令一行搞定：
bash # 安装certbot sudo apt install certbot python3-certbot-nginx # 为域名申请证书 sudo certbot --nginx -d class.yourschool.edu.cn
Nginx配置里加入：nginx server { listen 443 ssl; server_name class.yourschool.edu.cn; ssl_certificate /etc/letsencrypt/live/class.yourschool.edu.cn/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/class.yourschool.edu.cn/privkey.pem; # 代理到后端 location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; } }
注意：
close.png和photo.png这两个图标文件，路径必须是/static/images/close.png。我在app.wxss里写了全局样式：css .icon-close { width: 32rpx; height: 32rpx; background: url('/static/images/close.png') no-repeat center; background-size: contain; }
如果你把图片放错目录，所有关闭按钮都会显示为小方块。
5. 常见问题与排查技巧实录
5.1 签到失败的5种真实场景及解决方案
| 现象 | 原因 | 排查命令/步骤 | 解决方案 |
|---|---|---|---|
| 扫码后提示“班级不存在” | 学生注册时选错班级，或班级已被管理员删除 | 查user表class_id字段，对比class表是否存在该ID | 后台管理员重新启用班级，或让学生重新注册 |
| 定位签到始终提示“不在教室范围内” | class_location表里教室坐标为空，或geo-fence-radius配置过大/过小 | SELECT * FROM class_location WHERE class_id = 1001; | 用高德地图API获取教室精确坐标，更新lng/lat字段 |
扫码后页面卡住，控制台报request:fail timeout | 后端/sign/scan接口响应超时（默认10秒） | curl -v https://yourdomain.com/sign/scan?code=abc123&classId=1001 | 检查MySQL连接池，application.yml里增加spring.datasource.hikari.connection-timeout=30000 |
| 学生提交作业后，教师后台看不到文件 | 文件上传分片未合并，或/homework/upload/merge接口未被调用 | 查/tmp/upload/目录下是否有对应fileId子目录 | 检查小程序端homework-student/index.js里uploadFile方法是否执行到最后一步 |
| 通知模板消息收不到 | 微信模板ID未在小程序后台配置，或template_id写错 | 登录微信公众平台 → 功能 → 模板消息 → 查看ID是否启用 | 复制后台application.yml里的wechat.template-id，粘贴到微信后台模板库搜索 |
5.2 教师端作业批阅的“状态机陷阱”
教师点击“批阅”，学生却没收到反馈。这不是Bug，是状态机设计的必然结果。作业提交后，homework_submit.status字段流转如下：
NOT_SUBMITTED → SUBMITTED → REVIEWING → REVIEWED → REJECTEDSUBMITTED：学生提交成功，文件已存；REVIEWING：教师点“批阅”后，状态变为此值，此时学生看到“教师正在批阅中”；REVIEWED：教师填写评语并保存，状态变更，触发模板消息；REJECTED：教师点击“退回”，学生可重新提交。
陷阱：如果教师点“批阅”后关闭页面，状态卡在REVIEWING，学生永远等不到结果。解决方案是在HomeworkService.reviewHomework()方法里加定时任务：
// 批阅后启动10分钟倒计时 if (status.equals("REVIEWING")) { taskScheduler.schedule(() -> { // 检查是否超时未操作 if (homeworkSubmit.getStatus().equals("REVIEWING") && Duration.between(homeworkSubmit.getUpdateTime(), LocalDateTime.now()).toMinutes() > 10) { homeworkSubmit.setStatus("SUBMITTED"); // 自动退回 } }, Instant.now().plus(10, ChronoUnit.MINUTES)); }5.3 管理员后台登录401的3个检查点
当你输入admin/admin123却提示“未授权”，按顺序检查：
检查JWT密钥是否一致
application.yml里的jwt.secret: your_secret_key，必须和JwtUtil.java里的SECRET_KEY字符串完全相同（区分大小写）。检查Cookie域名是否匹配
管理员后台是Web应用，登录后Set-Cookie的Domain必须是你的域名。在Nginx配置里加：nginx proxy_cookie_domain ~^(.+)$ $1;检查浏览器是否禁用第三方Cookie
Safari和新版Chrome默认阻止第三方Cookie。解决方案：在AdminLoginController.java里，登录成功后返回JSON，前端用localStorage.setItem('token', data.token)存储，后续请求头加Authorization: Bearer ${token}。
最后分享一个小技巧：
README.md里写的“快速启动”命令，其实可以一键执行。我把所有步骤写成Shell脚本deploy.sh：
```bash!/bin/bash
echo “正在部署班级管理系统…”
mysql -u root -p class_manager < src/main/resources/sql/init.sql
mvn clean package -Dmaven.test.skip=true
java -jar -Dspring.profiles.active=prod target/class-manager-1.0.jar &
echo “部署完成！访问 https://yourdomain.com/admin/login”
```
学生双击运行，全程无需敲命令。这才是真正的“开箱即用”。
这套资源不是代码的堆砌，而是把三年教学实战中踩过的每一个坑、验证过的每一个方案、学生问得最多的问题，都揉进了每一行代码、每一张表、每一个配置项里。它不追求炫技，只求让你今天下午部署，明天早上就能用。
本文还有配套的精品资源，点击获取
简介：直接可用的微信小程序班级事务管理工具，覆盖教师、学生、管理员三类角色。学生扫码或定位一键签到，实时查收班级通知，查看并提交作业；教师发布作业、审核提交结果、管理班级成员；管理员统一维护账号和班级基础信息。所有功能基于微信原生小程序框架开发，无需额外安装App。配套提供完整Java后端参考逻辑（MySQL兼容数据库设计）、详细部署文档、微信开发者工具配置文件（project.config.、app.等）、基础UI素材（banner图、关闭图标、头像占位图）及二维码生成脚本。包含标准小程序目录结构：app.js、util.js、pages下细分页面（如sign-student、homework-student、notice-student等）、配置文件（sitemap.、package.）以及两个演示视频（签到与作业流程）。适合高校课程设计、毕业项目快速搭建或教学场景直接演示使用。
本文还有配套的精品资源，点击获取
