简介本资源是一套完整的高校课堂考勤系统毕业设计级项目源码面向Java Web与Vue全栈初学者及计算机专业本科生解决传统人工考勤效率低、数据难统计、管理不透明等教学管理痛点。项目采用Spring Boot Vue前后端分离架构后端以146个Java类和23个XML配置文件构成清晰的SSM风格业务逻辑与数据访问层前端含70个Vue组件及配套CSS/JS资源辅以3个bat批处理脚本install/run/build实现一键部署另含论文.doc与开题.docx两份完整文档支撑课程设计闭环。资源共492个文件涵盖SVG图标、PNG/JPG素材、woff/ttf字体、SQL建表脚本及MP3/MP4多媒体示例压缩包大小为17.63MB。目前已有51人学习下载读者可直接运行调试、理解模块化考勤流程如二维码签到、实时数据看板、导出统计报表掌握企业级前后端协同开发规范与典型目录结构设计。1. 这不是又一个“学生签到页面”SSM686 是一套能跑通教务闭环的 Java Web Vue 考勤系统实战包某高校信息中心曾反馈上线过 3 套前端花哨、后台空转的“考勤系统”教师扫完码数据进不了教务平台学生点完“已到”导出 Excel 却缺课时字段管理员想查某班上周缺勤 Top5SQL 写到第三层 JOIN 就报错。这不是功能堆砌的问题是架构断层——Java 后端没暴露标准 REST 接口Vue 前端没做状态持久化数据库没建好考勤快照表。而这份名为ssm686的资源包恰恰卡在断层最痛的位置它用 Spring Boot非老式 SSM标题中 SSM 是历史命名惯性重写了后端服务层Vue 2.6 实现了带离线缓存的课堂扫码页MySQL 表结构里明确定义了attendance_snapshot和course_session_log两张核心表。它不承诺“一键部署全校”但能让你在本地 Docker 环境里15 分钟内跑通“教师创建课节 → 学生扫码签到 → 后台导出带学号/姓名/时间戳/设备指纹的考勤明细表”全链路。适合正在做课程设计、毕设答辩前两周还在调跨域、或需要快速交付院系级轻量考勤模块的 Java/Vue 开发者。2. 从解压到首屏环境准备、目录结构与启动验证三步闭环2.1 环境依赖清单别被“Java Web”字面意思带偏这个包本质是Spring Boot 2.3.12 Vue CLI 3.12 MySQL 5.7的组合不是传统 WAR 包部署模式。这意味着你不需要 Tomcat 容器也不需要手动配置 web.xml。但必须确认以下三项JDK 版本JDK 1.8.0_291 或更高必须是 8u291低版本会因 Spring Boot 2.3 对 Jakarta EE 的迁移报javax.servlet类找不到Node.jsv14.17.0Vue CLI 3.12 的硬性要求v16 会导致vue-cli-service serve编译失败MySQL5.7.33注意8.0 默认开启caching_sha2_password认证插件而包内application.yml用的是mysql-connector-java:8.0.22需手动改authenticationPlugin配置提示不要用java -version看到 “1.8.0” 就以为过关——执行java -version后检查输出末尾是否含291或更高小版本号Node.js 同理node -v必须精确到v14.17.0用nvm切换比全局安装更稳妥。2.2 解压后直击核心识别四个关键目录与作用解压ssm686.rar后你会看到如下结构已剔除.git、target、node_modules等无关目录ssm686/ ├── backend/ # Spring Boot 工程根目录Maven 结构 │ ├── pom.xml # 关键确认 spring-boot.version2.3.12.RELEASE/spring-boot.version │ └── src/main/ │ └── java/com/example/ssm686/ # 主包名Controller/Service/Entity 全在此 ├── frontend/ # Vue CLI 工程根目录 │ ├── package.json # 关键vue: ^2.6.14, vue-cli-service: ^3.12.1 │ └── src/ │ ├── api/ # 所有 axios 请求封装如 attendance.js 定义 /api/attendance/checkin │ └── router/ # 路由配置重点看 index.js 中 /teacher 和 /student 的权限守卫 ├── docs/ # 数据库脚本与接口文档非 PDF是 .sql 和 .md │ ├── ssm686.sql # 建库建表 SQL含初始化教师/学生账号 │ └── api_ref.md # 每个接口的 request body 示例与 response 字段说明 └── README.md # 仅两行“后端cd backend mvn spring-boot:run”、“前端cd frontend npm run serve”注意backend/src/main/resources/application.yml是配置中枢其中spring.datasource.url默认为jdbc:mysql://localhost:3306/ssm686?useSSLfalseserverTimezoneAsia/Shanghai—— 若你 MySQL 端口不是 3306或数据库名要改必须先改这里再执行 SQL 脚本否则启动直接报Unknown database。2.3 启动验证三步确认服务真正就绪不是“控制台没报错”就算成功步骤一初始化数据库# 在 MySQL 客户端执行确保已创建空库 ssm686 mysql -u root -p ssm686 docs/ssm686.sql该 SQL 脚本会创建 6 张表重点关注t_userrole字段值为TEACHER或STUDENT初始账号密码均为123456t_course_session课节表status字段控制是否可签到OPEN可扫CLOSED关闭t_attendance_record签到主表device_fingerprint字段存扫码设备唯一标识非 IP是前端生成的 UUID步骤二启动后端关键验证点cd backend mvn clean compile spring-boot:run等待日志出现Tomcat started on port(s): 8080 (http) with context path Started Ssm686Application in 8.2 seconds (JVM running for 9.1)此时访问http://localhost:8080/api/test任意未鉴权接口应返回 JSON{code:200,msg:ok,data:null}。若返回 404说明RestController扫描路径不对检查Ssm686Application.java上的SpringBootApplication(scanBasePackages com.example.ssm686)是否匹配实际包名。步骤三启动前端并登录cd frontend npm install # 首次运行必须装完约 3 分钟 npm run serve浏览器打开http://localhost:8081Vue CLI 默认端口输入teacher/123456登录。验证成功标志左上角显示“教师工作台”点击【新建课节】弹窗能正常加载课程下拉框数据来自/api/course/list接口。若下拉框为空打开浏览器开发者工具 → Network 标签筛选 XHR看/api/course/list是否返回 200 且data数组非空 —— 这是前后端连通性的黄金指标。3. 教师端核心流程课节创建、动态二维码生成与实时签到监控3.1 创建课节为什么t_course_session表必须有start_time和end_time在教师工作台点击【新建课节】表单包含课程名称、班级、开始时间、结束时间、最大签到人数。提交后后端CourseSessionController.create()方法会插入一条记录到t_course_session。关键逻辑不在前端校验而在后端// backend/src/main/java/com/example/ssm686/controller/CourseSessionController.java PostMapping(/create) public Result create(RequestBody CourseSession session) { // 1. 强制设置 status OPEN只有 OPEN 状态才允许扫码 session.setStatus(OPEN); // 2. 设置当前时间作为创建时间 session.setCreateTime(new Date()); // 3. 校验结束时间必须晚于开始时间且不能早于当前时间 if (session.getEndTime().before(session.getStartTime()) || session.getStartTime().before(new Date())) { return Result.fail(课节时间设置错误); } courseSessionService.save(session); return Result.success(); }参数说明start_time和end_time不仅用于界面展示更是签到逻辑的闸门。AttendanceService.checkIn()方法在扫码时会校验now start_time now end_time否则返回{code:403,msg:课节未开始或已结束}。这是防止学生提前扫、课后补扫的核心防线不能靠前端 JS 时间校验必须后端强控。3.2 动态二维码生成不是简单 base64而是带签名的短链学生扫码页 URL 并非http://localhost:8081/student/checkin?sessionId123这种明文 ID而是形如https://s686.io/q/abc123的短链。其生成逻辑在QrCodeService.generateQrCode(Long sessionId)// backend/src/main/java/com/example/ssm686/service/QrCodeService.java public String generateQrCode(Long sessionId) { // 1. 生成 6 位随机字符串非 UUID避免过长 String shortCode RandomStringUtils.randomAlphanumeric(6).toLowerCase(); // 2. 存入 t_qr_code_mapping 表关联 sessionId 和 shortCode QrCodeMapping mapping new QrCodeMapping(); mapping.setShortCode(shortCode); mapping.setSessionId(sessionId); mapping.setExpireTime(new Date(System.currentTimeMillis() 24 * 60 * 60 * 1000)); // 24小时过期 qrCodeMappingMapper.insert(mapping); // 3. 返回短链实际项目中此处应调用 Nginx 302 跳转本包用前端路由模拟 return https://s686.io/q/ shortCode; }逻辑说明短链设计解决三个问题① 避免 sessionId 泄露数据库主键规律② 支持过期控制expireTime字段③ 为后续接入真实短链服务如自建 or 使用开源 go-url留扩展点。前端student/checkin.vue通过this.$route.params.code获取abc123再调用/api/qr/resolve?codeabc123接口反查出真实sessionId这才进入签到主流程。3.3 实时签到监控WebSocket 不是噱头是解决“教师想知道谁还没来”的刚需教师工作台右上角有【实时签到】面板显示当前课节已签到人数、未签到名单按学号排序。这并非轮询实现而是基于 Spring Boot WebSocket// backend/src/main/java/com/example/ssm686/config/WebSocketConfig.java Configuration EnableWebSocket public class WebSocketConfig { Bean public ServerEndpointExporter serverEndpointExporter() { return new ServerEndpointExporter(); } } // backend/src/main/java/com/example/ssm686/websocket/AttendanceWebSocket.java ServerEndpoint(/ws/attendance/{sessionId}) Component public class AttendanceWebSocket { private static final MapLong, SetSession SESSIONS new ConcurrentHashMap(); OnOpen public void onOpen(Session session, PathParam(sessionId) Long sessionId) { SESSIONS.computeIfAbsent(sessionId, k - ConcurrentHashMap.newKeySet()).add(session); } // 当学生签到成功触发此广播 public static void broadcastSignin(Long sessionId, String studentNo) { SetSession sessions SESSIONS.get(sessionId); if (sessions ! null) { sessions.forEach(s - { try { s.getBasicRemote().sendText( JSON.toJSONString(Map.of(type, SIGNIN, studentNo, studentNo)) ); } catch (IOException e) { // 移除异常连接 sessions.remove(s); } }); } } }参数说明前端教师页通过new WebSocket(ws://localhost:8080/ws/attendance/123)连接监听message事件。当收到{type:SIGNIN, studentNo:2021001}就将该学号从“未签到列表”移至“已签到列表”。注意WebSocket 路径中的sessionId必须与当前教师查看的课节 ID 一致否则收不到消息—— 这是新手最容易忽略的绑定逻辑。4. 学生端扫码签到离线缓存、设备指纹与防代签三重校验4.1 离线缓存策略Vue PWA 模式下扫码页为何能断网使用frontend/vue.config.js中启用了 PWA 插件// frontend/vue.config.js module.exports { pwa: { workboxOptions: { skipWaiting: true, clientsClaim: true, runtimeCaching: [ { urlPattern: /^https:\/\/.*\/api\/.*$/, handler: NetworkFirst, // API 请求走网络 options: { cacheName: api-cache } }, { urlPattern: /\.(?:png|jpg|jpeg|gif|ico|svg|webp|woff2|ttf|css|js)$/, handler: CacheFirst, // 静态资源缓存 options: { cacheName: static-cache } } ] } } }逻辑说明学生首次访问http://localhost:8081/student/checkin时Service Worker 会缓存 HTML、JS、CSS 及二维码图片。当网络中断刷新页面仍能显示扫码界面因为 HTML/JS 已缓存但扫码动作本身会失败 —— 因为/api/attendance/checkin接口必须联网调用。真正的离线价值在于学生可提前打开页面等教师开课后立即扫码避免网络波动导致首屏加载慢而错过签到窗口。这不是“完全离线”而是“首屏离线 业务操作强联网”。4.2 设备指纹生成为什么不用 IP如何防同一手机多次签到学生扫码后前端attendance.js发送请求// frontend/src/api/attendance.js export function checkIn(sessionId, studentNo) { const fingerprint getDeviceFingerprint(); // 关键函数 return request({ url: /api/attendance/checkin, method: post, data: { sessionId, studentNo, deviceFingerprint: fingerprint } }) } function getDeviceFingerprint() { // 组合UserAgent 屏幕分辨率 语言 时区 Canvas 渲染哈希 const canvas document.createElement(canvas); const ctx canvas.getContext(2d); ctx.textBaseline top; ctx.font 14px Arial; ctx.textRendering optimizeLegibility; ctx.fillText(ssm686, 2, 2); const canvasHash canvas.toDataURL().slice(-10); // 取 DataURL 末10位作简易哈希 return btoa(navigator.userAgent screen.width screen.height navigator.language Intl.DateTimeFormat().resolvedOptions().timeZone canvasHash).substring(0, 32); // Base64 后截取32位 }参数说明deviceFingerprint字段存入t_attendance_record.device_fingerprint。后端AttendanceService.checkIn()会校验同一sessionId下该指纹是否已存在记录。若存在返回{code:409,msg:该设备已签到}。这比单纯校验studentNo更可靠—— 防止学生用多台手机帮同学代扫每台手机指纹不同也避免同一手机切号重复签指纹不变系统拦截。4.3 防代签增强地理位置与拍照水印可选启用包内frontend/src/utils/geolocation.js提供了地理围栏能力默认关闭// frontend/src/utils/geolocation.js export function getLocation() { return new Promise((resolve, reject) { if (!navigator.geolocation) { reject(Geolocation not supported); return; } navigator.geolocation.getCurrentPosition( position resolve({ lat: position.coords.latitude, lng: position.coords.longitude, accuracy: position.coords.accuracy }), err reject(err.message), { enableHighAccuracy: true, timeout: 5000, maximumAge: 30000 } ); }); }逻辑说明若教师在创建课节时勾选“启用位置校验”则后端checkIn()会调用高德/百度地图 API需自行填入 key判断学生上报的经纬度是否在教室坐标 50 米范围内。同时student/checkin.vue中的takePhoto()方法会调用navigator.mediaDevices.getUserMedia拍摄一张带时间戳、学号水印的现场照片base64 存入t_attendance_record.photo_data。这两项是“玄学级防代签”手段不强制开启但代码已预留钩子—— 你需要做的只是在application.yml中配置location.enabledtrue和photo.enabledtrue。5. 避坑指南五个血泪经验总结的高频翻车点与排查路径5.1 现象前端登录后跳转 404地址栏变成http://localhost:8081/#/teacher/dashboard但页面空白原因Vue Router 模式为history但开发服务器npm run serve默认不支持 history fallback导致刷新页面时 Nginx/Apache 无法找到对应 HTML。解决打开frontend/vue.config.js确认devServer.historyApiFallback已启用devServer: { historyApiFallback: true, // 必须为 true port: 8081, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }若已启用仍无效清空浏览器缓存并重启npm run serve。5.2 现象教师创建课节成功但学生扫码提示{code:404,msg:课节不存在}原因t_qr_code_mapping表中shortCode与sessionId关联失败常见于QrCodeService.generateQrCode()中qrCodeMappingMapper.insert(mapping)抛异常但未被捕获如数据库字段长度不足。解决检查t_qr_code_mapping.short_code字段类型是否为VARCHAR(10)脚本中定义为 10若手动改过表结构需同步在generateQrCode方法开头加日志log.info(Generating QR for session: {}, sessionId)确认方法是否执行查询SELECT * FROM t_qr_code_mapping WHERE short_code abc123验证记录是否存在。5.3 现象WebSocket 连接成功但教师页收不到签到消息原因AttendanceWebSocket.broadcastSignin()调用时机错误。该方法应在AttendanceService.checkIn()事务提交后触发而非事务内调用否则事务回滚会导致消息已发但签到失败。解决检查AttendanceServiceImpl.checkIn()方法确认broadcastSignin()是否在attendanceRecordMapper.insert(record)之后且不在Transactional方法内部直接调用。正确做法是使用 Spring 事件机制或异步线程池// 在 checkIn 方法末尾 applicationEventPublisher.publishEvent(new AttendanceSigninEvent(sessionId, studentNo)); // 新建监听器类处理广播 Component public class AttendanceSigninListener implements ApplicationListenerAttendanceSigninEvent { Override public void onApplicationEvent(AttendanceSigninEvent event) { AttendanceWebSocket.broadcastSignin(event.getSessionId(), event.getStudentNo()); } }5.4 现象导出 Excel 明细表时间字段全是1970-01-01原因t_attendance_record.create_time字段类型为BIGINT存毫秒时间戳但 EasyExcel 导出时未做Date类型转换直接 toString() 导致解析失败。解决检查backend/src/main/java/com/example/ssm686/excel/AttendanceExport.java确认DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss)注解是否加在createTime字段上public class AttendanceExport { DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) private Date createTime; // 必须是 Date 类型非 Long }同时在AttendanceController.export()中将数据库查出的Long createTime赋值给AttendanceExport.createTime时需显式转换export.setCreateTime(new Date(record.getCreateTime()))。5.5 现象学生扫码后t_attendance_record表新增记录但t_user.last_login_time未更新原因AttendanceService.checkIn()中只操作了考勤表未联动更新用户表。而教师端“最近活跃学生”统计依赖last_login_time。解决在checkIn()方法中扫码成功后追加更新语句// 更新用户最后登录时间提升教师端数据新鲜度 LambdaUpdateWrapperUser userWrapper new LambdaUpdateWrapper(); userWrapper.eq(User::getStudentNo, studentNo) .set(User::getLastLoginTime, new Date()); userMapper.update(null, userWrapper);注意此操作需在同一个事务中确保原子性。6. 进阶技巧用 Docker Compose 一键拉起全栈环境与生产化部署 checklist6.1 Docker Compose 编排三行命令启动 MySQL Backend Frontend包内未提供 Dockerfile但根据技术栈可快速补全。在项目根目录新建docker-compose.ymlversion: 3.8 services: mysql: image: mysql:5.7.33 container_name: ssm686-mysql environment: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: ssm686 ports: - 3306:3306 volumes: - ./docs/ssm686.sql:/docker-entrypoint-initdb.d/init.sql - mysql-data:/var/lib/mysql backend: build: ./backend container_name: ssm686-backend ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: docker SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/ssm686?useSSLfalseserverTimezoneAsia/Shanghai depends_on: - mysql frontend: build: ./frontend container_name: ssm686-frontend ports: - 8081:80 environment: VUE_APP_API_BASE_URL: http://localhost:8080 depends_on: - backend volumes: mysql-data:关键步骤在backend/src/main/resources/下新建application-docker.yml内容为spring.datasource.url指向mysql服务名frontend/Dockerfile使用nginx:alpineCOPY dist/ /usr/share/nginx/html/执行docker-compose up -d --build等待 2 分钟访问http://localhost:8081即可。优势彻底隔离本地环境避免 JDK/Node 版本冲突MySQL 初始化脚本自动执行服务依赖关系清晰。6.2 生产化部署 checklist从“能跑”到“能扛住”的七项加固项目检查点说明是否完成HTTPS 强制Nginx 配置return 301 https://$host$request_uri;前端所有请求必须走 HTTPS防止deviceFingerprint被中间人篡改□JWT 替换 Sessionbackend/pom.xml加入jjwt-api、jjwt-impl当前用HttpSession并发量大时内存溢出JWT 无状态适合横向扩展□敏感配置外置application.yml中spring.datasource.password改为${DB_PASSWORD}启动时传-e DB_PASSWORDxxx避免密码硬编码在 Git 仓库□日志脱敏logback-spring.xml中pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n/pattern改为过滤studentNo、idCard字段防止日志泄露学生隐私□SQL 注入防护检查所有Select(SELECT * FROM t_user WHERE student_no #{studentNo})是否全为#{}预编译禁用${}${}直接拼接高危□前端资源压缩frontend/vue.config.js中configureWebpack.optimization.minimize true减少 JS/CSS 体积提升首屏速度□健康检查端点backend/src/main/java/com/example/ssm686/controller/HealthController.java添加GetMapping(/actuator/health)供 Kubernetes/LVS 做存活探针□从那以后我每次接手新项目都强制走一遍这个 checklist —— 不是怕线上崩是怕凌晨三点被电话叫醒时发现崩的原因是application.yml里还写着root/root。把配置、日志、安全这些“无聊事”做扎实才能腾出手去优化那个让教师拍手叫好的实时签到动画。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/14 21:30:21 · 阅读 1.2k Spring Boot+Vue考勤系统实战：教务闭环与防代签设计
简介本资源是一套完整的高校课堂考勤系统毕业设计级项目源码面向Java Web与Vue全栈初学者及计算机专业本科生解决传统人工考勤效率低、数据难统计、管理不透明等教学管理痛点。项目采用Spring Boot Vue前后端分离架构后端以146个Java类和23个XML配置文件构成清晰的SSM风格业务逻辑与数据访问层前端含70个Vue组件及配套CSS/JS资源辅以3个bat批处理脚本install/run/build实现一键部署另含论文.doc与开题.docx两份完整文档支撑课程设计闭环。资源共492个文件涵盖SVG图标、PNG/JPG素材、woff/ttf字体、SQL建表脚本及MP3/MP4多媒体示例压缩包大小为17.63MB。目前已有51人学习下载读者可直接运行调试、理解模块化考勤流程如二维码签到、实时数据看板、导出统计报表掌握企业级前后端协同开发规范与典型目录结构设计。1. 这不是又一个“学生签到页面”SSM686 是一套能跑通教务闭环的 Java Web Vue 考勤系统实战包某高校信息中心曾反馈上线过 3 套前端花哨、后台空转的“考勤系统”教师扫完码数据进不了教务平台学生点完“已到”导出 Excel 却缺课时字段管理员想查某班上周缺勤 Top5SQL 写到第三层 JOIN 就报错。这不是功能堆砌的问题是架构断层——Java 后端没暴露标准 REST 接口Vue 前端没做状态持久化数据库没建好考勤快照表。而这份名为ssm686的资源包恰恰卡在断层最痛的位置它用 Spring Boot非老式 SSM标题中 SSM 是历史命名惯性重写了后端服务层Vue 2.6 实现了带离线缓存的课堂扫码页MySQL 表结构里明确定义了attendance_snapshot和course_session_log两张核心表。它不承诺“一键部署全校”但能让你在本地 Docker 环境里15 分钟内跑通“教师创建课节 → 学生扫码签到 → 后台导出带学号/姓名/时间戳/设备指纹的考勤明细表”全链路。适合正在做课程设计、毕设答辩前两周还在调跨域、或需要快速交付院系级轻量考勤模块的 Java/Vue 开发者。2. 从解压到首屏环境准备、目录结构与启动验证三步闭环2.1 环境依赖清单别被“Java Web”字面意思带偏这个包本质是Spring Boot 2.3.12 Vue CLI 3.12 MySQL 5.7的组合不是传统 WAR 包部署模式。这意味着你不需要 Tomcat 容器也不需要手动配置 web.xml。但必须确认以下三项JDK 版本JDK 1.8.0_291 或更高必须是 8u291低版本会因 Spring Boot 2.3 对 Jakarta EE 的迁移报javax.servlet类找不到Node.jsv14.17.0Vue CLI 3.12 的硬性要求v16 会导致vue-cli-service serve编译失败MySQL5.7.33注意8.0 默认开启caching_sha2_password认证插件而包内application.yml用的是mysql-connector-java:8.0.22需手动改authenticationPlugin配置提示不要用java -version看到 “1.8.0” 就以为过关——执行java -version后检查输出末尾是否含291或更高小版本号Node.js 同理node -v必须精确到v14.17.0用nvm切换比全局安装更稳妥。2.2 解压后直击核心识别四个关键目录与作用解压ssm686.rar后你会看到如下结构已剔除.git、target、node_modules等无关目录ssm686/ ├── backend/ # Spring Boot 工程根目录Maven 结构 │ ├── pom.xml # 关键确认 spring-boot.version2.3.12.RELEASE/spring-boot.version │ └── src/main/ │ └── java/com/example/ssm686/ # 主包名Controller/Service/Entity 全在此 ├── frontend/ # Vue CLI 工程根目录 │ ├── package.json # 关键vue: ^2.6.14, vue-cli-service: ^3.12.1 │ └── src/ │ ├── api/ # 所有 axios 请求封装如 attendance.js 定义 /api/attendance/checkin │ └── router/ # 路由配置重点看 index.js 中 /teacher 和 /student 的权限守卫 ├── docs/ # 数据库脚本与接口文档非 PDF是 .sql 和 .md │ ├── ssm686.sql # 建库建表 SQL含初始化教师/学生账号 │ └── api_ref.md # 每个接口的 request body 示例与 response 字段说明 └── README.md # 仅两行“后端cd backend mvn spring-boot:run”、“前端cd frontend npm run serve”注意backend/src/main/resources/application.yml是配置中枢其中spring.datasource.url默认为jdbc:mysql://localhost:3306/ssm686?useSSLfalseserverTimezoneAsia/Shanghai—— 若你 MySQL 端口不是 3306或数据库名要改必须先改这里再执行 SQL 脚本否则启动直接报Unknown database。2.3 启动验证三步确认服务真正就绪不是“控制台没报错”就算成功步骤一初始化数据库# 在 MySQL 客户端执行确保已创建空库 ssm686 mysql -u root -p ssm686 docs/ssm686.sql该 SQL 脚本会创建 6 张表重点关注t_userrole字段值为TEACHER或STUDENT初始账号密码均为123456t_course_session课节表status字段控制是否可签到OPEN可扫CLOSED关闭t_attendance_record签到主表device_fingerprint字段存扫码设备唯一标识非 IP是前端生成的 UUID步骤二启动后端关键验证点cd backend mvn clean compile spring-boot:run等待日志出现Tomcat started on port(s): 8080 (http) with context path Started Ssm686Application in 8.2 seconds (JVM running for 9.1)此时访问http://localhost:8080/api/test任意未鉴权接口应返回 JSON{code:200,msg:ok,data:null}。若返回 404说明RestController扫描路径不对检查Ssm686Application.java上的SpringBootApplication(scanBasePackages com.example.ssm686)是否匹配实际包名。步骤三启动前端并登录cd frontend npm install # 首次运行必须装完约 3 分钟 npm run serve浏览器打开http://localhost:8081Vue CLI 默认端口输入teacher/123456登录。验证成功标志左上角显示“教师工作台”点击【新建课节】弹窗能正常加载课程下拉框数据来自/api/course/list接口。若下拉框为空打开浏览器开发者工具 → Network 标签筛选 XHR看/api/course/list是否返回 200 且data数组非空 —— 这是前后端连通性的黄金指标。3. 教师端核心流程课节创建、动态二维码生成与实时签到监控3.1 创建课节为什么t_course_session表必须有start_time和end_time在教师工作台点击【新建课节】表单包含课程名称、班级、开始时间、结束时间、最大签到人数。提交后后端CourseSessionController.create()方法会插入一条记录到t_course_session。关键逻辑不在前端校验而在后端// backend/src/main/java/com/example/ssm686/controller/CourseSessionController.java PostMapping(/create) public Result create(RequestBody CourseSession session) { // 1. 强制设置 status OPEN只有 OPEN 状态才允许扫码 session.setStatus(OPEN); // 2. 设置当前时间作为创建时间 session.setCreateTime(new Date()); // 3. 校验结束时间必须晚于开始时间且不能早于当前时间 if (session.getEndTime().before(session.getStartTime()) || session.getStartTime().before(new Date())) { return Result.fail(课节时间设置错误); } courseSessionService.save(session); return Result.success(); }参数说明start_time和end_time不仅用于界面展示更是签到逻辑的闸门。AttendanceService.checkIn()方法在扫码时会校验now start_time now end_time否则返回{code:403,msg:课节未开始或已结束}。这是防止学生提前扫、课后补扫的核心防线不能靠前端 JS 时间校验必须后端强控。3.2 动态二维码生成不是简单 base64而是带签名的短链学生扫码页 URL 并非http://localhost:8081/student/checkin?sessionId123这种明文 ID而是形如https://s686.io/q/abc123的短链。其生成逻辑在QrCodeService.generateQrCode(Long sessionId)// backend/src/main/java/com/example/ssm686/service/QrCodeService.java public String generateQrCode(Long sessionId) { // 1. 生成 6 位随机字符串非 UUID避免过长 String shortCode RandomStringUtils.randomAlphanumeric(6).toLowerCase(); // 2. 存入 t_qr_code_mapping 表关联 sessionId 和 shortCode QrCodeMapping mapping new QrCodeMapping(); mapping.setShortCode(shortCode); mapping.setSessionId(sessionId); mapping.setExpireTime(new Date(System.currentTimeMillis() 24 * 60 * 60 * 1000)); // 24小时过期 qrCodeMappingMapper.insert(mapping); // 3. 返回短链实际项目中此处应调用 Nginx 302 跳转本包用前端路由模拟 return https://s686.io/q/ shortCode; }逻辑说明短链设计解决三个问题① 避免 sessionId 泄露数据库主键规律② 支持过期控制expireTime字段③ 为后续接入真实短链服务如自建 or 使用开源 go-url留扩展点。前端student/checkin.vue通过this.$route.params.code获取abc123再调用/api/qr/resolve?codeabc123接口反查出真实sessionId这才进入签到主流程。3.3 实时签到监控WebSocket 不是噱头是解决“教师想知道谁还没来”的刚需教师工作台右上角有【实时签到】面板显示当前课节已签到人数、未签到名单按学号排序。这并非轮询实现而是基于 Spring Boot WebSocket// backend/src/main/java/com/example/ssm686/config/WebSocketConfig.java Configuration EnableWebSocket public class WebSocketConfig { Bean public ServerEndpointExporter serverEndpointExporter() { return new ServerEndpointExporter(); } } // backend/src/main/java/com/example/ssm686/websocket/AttendanceWebSocket.java ServerEndpoint(/ws/attendance/{sessionId}) Component public class AttendanceWebSocket { private static final MapLong, SetSession SESSIONS new ConcurrentHashMap(); OnOpen public void onOpen(Session session, PathParam(sessionId) Long sessionId) { SESSIONS.computeIfAbsent(sessionId, k - ConcurrentHashMap.newKeySet()).add(session); } // 当学生签到成功触发此广播 public static void broadcastSignin(Long sessionId, String studentNo) { SetSession sessions SESSIONS.get(sessionId); if (sessions ! null) { sessions.forEach(s - { try { s.getBasicRemote().sendText( JSON.toJSONString(Map.of(type, SIGNIN, studentNo, studentNo)) ); } catch (IOException e) { // 移除异常连接 sessions.remove(s); } }); } } }参数说明前端教师页通过new WebSocket(ws://localhost:8080/ws/attendance/123)连接监听message事件。当收到{type:SIGNIN, studentNo:2021001}就将该学号从“未签到列表”移至“已签到列表”。注意WebSocket 路径中的sessionId必须与当前教师查看的课节 ID 一致否则收不到消息—— 这是新手最容易忽略的绑定逻辑。4. 学生端扫码签到离线缓存、设备指纹与防代签三重校验4.1 离线缓存策略Vue PWA 模式下扫码页为何能断网使用frontend/vue.config.js中启用了 PWA 插件// frontend/vue.config.js module.exports { pwa: { workboxOptions: { skipWaiting: true, clientsClaim: true, runtimeCaching: [ { urlPattern: /^https:\/\/.*\/api\/.*$/, handler: NetworkFirst, // API 请求走网络 options: { cacheName: api-cache } }, { urlPattern: /\.(?:png|jpg|jpeg|gif|ico|svg|webp|woff2|ttf|css|js)$/, handler: CacheFirst, // 静态资源缓存 options: { cacheName: static-cache } } ] } } }逻辑说明学生首次访问http://localhost:8081/student/checkin时Service Worker 会缓存 HTML、JS、CSS 及二维码图片。当网络中断刷新页面仍能显示扫码界面因为 HTML/JS 已缓存但扫码动作本身会失败 —— 因为/api/attendance/checkin接口必须联网调用。真正的离线价值在于学生可提前打开页面等教师开课后立即扫码避免网络波动导致首屏加载慢而错过签到窗口。这不是“完全离线”而是“首屏离线 业务操作强联网”。4.2 设备指纹生成为什么不用 IP如何防同一手机多次签到学生扫码后前端attendance.js发送请求// frontend/src/api/attendance.js export function checkIn(sessionId, studentNo) { const fingerprint getDeviceFingerprint(); // 关键函数 return request({ url: /api/attendance/checkin, method: post, data: { sessionId, studentNo, deviceFingerprint: fingerprint } }) } function getDeviceFingerprint() { // 组合UserAgent 屏幕分辨率 语言 时区 Canvas 渲染哈希 const canvas document.createElement(canvas); const ctx canvas.getContext(2d); ctx.textBaseline top; ctx.font 14px Arial; ctx.textRendering optimizeLegibility; ctx.fillText(ssm686, 2, 2); const canvasHash canvas.toDataURL().slice(-10); // 取 DataURL 末10位作简易哈希 return btoa(navigator.userAgent screen.width screen.height navigator.language Intl.DateTimeFormat().resolvedOptions().timeZone canvasHash).substring(0, 32); // Base64 后截取32位 }参数说明deviceFingerprint字段存入t_attendance_record.device_fingerprint。后端AttendanceService.checkIn()会校验同一sessionId下该指纹是否已存在记录。若存在返回{code:409,msg:该设备已签到}。这比单纯校验studentNo更可靠—— 防止学生用多台手机帮同学代扫每台手机指纹不同也避免同一手机切号重复签指纹不变系统拦截。4.3 防代签增强地理位置与拍照水印可选启用包内frontend/src/utils/geolocation.js提供了地理围栏能力默认关闭// frontend/src/utils/geolocation.js export function getLocation() { return new Promise((resolve, reject) { if (!navigator.geolocation) { reject(Geolocation not supported); return; } navigator.geolocation.getCurrentPosition( position resolve({ lat: position.coords.latitude, lng: position.coords.longitude, accuracy: position.coords.accuracy }), err reject(err.message), { enableHighAccuracy: true, timeout: 5000, maximumAge: 30000 } ); }); }逻辑说明若教师在创建课节时勾选“启用位置校验”则后端checkIn()会调用高德/百度地图 API需自行填入 key判断学生上报的经纬度是否在教室坐标 50 米范围内。同时student/checkin.vue中的takePhoto()方法会调用navigator.mediaDevices.getUserMedia拍摄一张带时间戳、学号水印的现场照片base64 存入t_attendance_record.photo_data。这两项是“玄学级防代签”手段不强制开启但代码已预留钩子—— 你需要做的只是在application.yml中配置location.enabledtrue和photo.enabledtrue。5. 避坑指南五个血泪经验总结的高频翻车点与排查路径5.1 现象前端登录后跳转 404地址栏变成http://localhost:8081/#/teacher/dashboard但页面空白原因Vue Router 模式为history但开发服务器npm run serve默认不支持 history fallback导致刷新页面时 Nginx/Apache 无法找到对应 HTML。解决打开frontend/vue.config.js确认devServer.historyApiFallback已启用devServer: { historyApiFallback: true, // 必须为 true port: 8081, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }若已启用仍无效清空浏览器缓存并重启npm run serve。5.2 现象教师创建课节成功但学生扫码提示{code:404,msg:课节不存在}原因t_qr_code_mapping表中shortCode与sessionId关联失败常见于QrCodeService.generateQrCode()中qrCodeMappingMapper.insert(mapping)抛异常但未被捕获如数据库字段长度不足。解决检查t_qr_code_mapping.short_code字段类型是否为VARCHAR(10)脚本中定义为 10若手动改过表结构需同步在generateQrCode方法开头加日志log.info(Generating QR for session: {}, sessionId)确认方法是否执行查询SELECT * FROM t_qr_code_mapping WHERE short_code abc123验证记录是否存在。5.3 现象WebSocket 连接成功但教师页收不到签到消息原因AttendanceWebSocket.broadcastSignin()调用时机错误。该方法应在AttendanceService.checkIn()事务提交后触发而非事务内调用否则事务回滚会导致消息已发但签到失败。解决检查AttendanceServiceImpl.checkIn()方法确认broadcastSignin()是否在attendanceRecordMapper.insert(record)之后且不在Transactional方法内部直接调用。正确做法是使用 Spring 事件机制或异步线程池// 在 checkIn 方法末尾 applicationEventPublisher.publishEvent(new AttendanceSigninEvent(sessionId, studentNo)); // 新建监听器类处理广播 Component public class AttendanceSigninListener implements ApplicationListenerAttendanceSigninEvent { Override public void onApplicationEvent(AttendanceSigninEvent event) { AttendanceWebSocket.broadcastSignin(event.getSessionId(), event.getStudentNo()); } }5.4 现象导出 Excel 明细表时间字段全是1970-01-01原因t_attendance_record.create_time字段类型为BIGINT存毫秒时间戳但 EasyExcel 导出时未做Date类型转换直接 toString() 导致解析失败。解决检查backend/src/main/java/com/example/ssm686/excel/AttendanceExport.java确认DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss)注解是否加在createTime字段上public class AttendanceExport { DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) private Date createTime; // 必须是 Date 类型非 Long }同时在AttendanceController.export()中将数据库查出的Long createTime赋值给AttendanceExport.createTime时需显式转换export.setCreateTime(new Date(record.getCreateTime()))。5.5 现象学生扫码后t_attendance_record表新增记录但t_user.last_login_time未更新原因AttendanceService.checkIn()中只操作了考勤表未联动更新用户表。而教师端“最近活跃学生”统计依赖last_login_time。解决在checkIn()方法中扫码成功后追加更新语句// 更新用户最后登录时间提升教师端数据新鲜度 LambdaUpdateWrapperUser userWrapper new LambdaUpdateWrapper(); userWrapper.eq(User::getStudentNo, studentNo) .set(User::getLastLoginTime, new Date()); userMapper.update(null, userWrapper);注意此操作需在同一个事务中确保原子性。6. 进阶技巧用 Docker Compose 一键拉起全栈环境与生产化部署 checklist6.1 Docker Compose 编排三行命令启动 MySQL Backend Frontend包内未提供 Dockerfile但根据技术栈可快速补全。在项目根目录新建docker-compose.ymlversion: 3.8 services: mysql: image: mysql:5.7.33 container_name: ssm686-mysql environment: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: ssm686 ports: - 3306:3306 volumes: - ./docs/ssm686.sql:/docker-entrypoint-initdb.d/init.sql - mysql-data:/var/lib/mysql backend: build: ./backend container_name: ssm686-backend ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: docker SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/ssm686?useSSLfalseserverTimezoneAsia/Shanghai depends_on: - mysql frontend: build: ./frontend container_name: ssm686-frontend ports: - 8081:80 environment: VUE_APP_API_BASE_URL: http://localhost:8080 depends_on: - backend volumes: mysql-data:关键步骤在backend/src/main/resources/下新建application-docker.yml内容为spring.datasource.url指向mysql服务名frontend/Dockerfile使用nginx:alpineCOPY dist/ /usr/share/nginx/html/执行docker-compose up -d --build等待 2 分钟访问http://localhost:8081即可。优势彻底隔离本地环境避免 JDK/Node 版本冲突MySQL 初始化脚本自动执行服务依赖关系清晰。6.2 生产化部署 checklist从“能跑”到“能扛住”的七项加固项目检查点说明是否完成HTTPS 强制Nginx 配置return 301 https://$host$request_uri;前端所有请求必须走 HTTPS防止deviceFingerprint被中间人篡改□JWT 替换 Sessionbackend/pom.xml加入jjwt-api、jjwt-impl当前用HttpSession并发量大时内存溢出JWT 无状态适合横向扩展□敏感配置外置application.yml中spring.datasource.password改为${DB_PASSWORD}启动时传-e DB_PASSWORDxxx避免密码硬编码在 Git 仓库□日志脱敏logback-spring.xml中pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n/pattern改为过滤studentNo、idCard字段防止日志泄露学生隐私□SQL 注入防护检查所有Select(SELECT * FROM t_user WHERE student_no #{studentNo})是否全为#{}预编译禁用${}${}直接拼接高危□前端资源压缩frontend/vue.config.js中configureWebpack.optimization.minimize true减少 JS/CSS 体积提升首屏速度□健康检查端点backend/src/main/java/com/example/ssm686/controller/HealthController.java添加GetMapping(/actuator/health)供 Kubernetes/LVS 做存活探针□从那以后我每次接手新项目都强制走一遍这个 checklist —— 不是怕线上崩是怕凌晨三点被电话叫醒时发现崩的原因是application.yml里还写着root/root。把配置、日志、安全这些“无聊事”做扎实才能腾出手去优化那个让教师拍手叫好的实时签到动画。希望帮到你。本文还有配套的精品资源点击获取