很多公司的新员工入职培训尤其是有大量一线岗位的公司一直是个头疼的事。人事部门把制度文件、安全规范、产品知识做成PPT扔到微信群里员工下载了看不看根本不知道最后签个培训确认书就算完事。这背后的隐患是员工可能根本没学会岗位需要的东西就上了岗。我们这次做的“107员工岗前培训学习平台系统”就是要用一套可追踪、可考核、可统计的线上流程把这件事彻底规范化。整个系统分三端后端用 Spring Boot管理端用 Vue员工学习端用微信小程序。这篇文把从需求梳理、数据库设计到小程序上线的完整过程讲出来重点讲项目里实际踩过的坑给准备做同类系统的朋友一个可以直接参考的路线。1. 为什么会做这个平台业务痛点与技术选型逻辑1.1 传统岗前培训的三笔糊涂账先说需求是怎么来的。团队刚开始接触这个项目时人事部门给的需求其实只有一句话让新员工能在线看课程、然后考试最好能看到谁看完了、谁没看完。听起来简单但真正去梳理业务后会发现线下培训模式积压了三个很要命的问题。第一笔糊涂账是“培训过程不可追踪”。以前的做法是人事把培训资料传到群文件员工自己下载看最后签一张纸质确认书。至于员工是认真学完了还是直接拉到最后一页签字完全无从得知。考试也是纸质试卷人工阅卷考完还要誊写分数一卷一档保存忙的时候经常漏存档。第二笔糊涂账是“内容标准不统一”。各班组自己培训用的PPT版本不一致有的老师傅讲得详细有的照着文件念一遍最后新员工学到的内容参差不齐分配到一个岗位后底子完全不一样。第三笔糊涂账是“考核成本高”。有大量员工需要培训时要安排会议室、监考人员、打印试卷还要防止题目泄漏。这些成本叠加起来一个百人规模的入职季就能把人手占掉大半。所以这个平台的核心需求其实很明确统一课程内容强制按计划学习自动考核判定最后留痕可查。围绕这四个点去设计系统后面所有的功能模块才有方向不至于做成一个花哨但没人用的线上视频站。1.2 为什么是 Spring Boot Vue 微信小程序技术选型是项目启动时争论最多的环节。团队内部当时也有不同声音有的说后端用 Node.js 更轻有的说管理端直接用服务端渲染省事。最后敲定 Spring Boot Vue 微信小程序是从团队维护成本、招聘难度和业务场景三个维度综合考虑的结果。后端选 Spring Boot核心原因是生态成熟。Spring Boot 配合 MyBatis-Plus 做 CRUD 效率很高权限这块用 Spring Security JWT 也算顺理成章社区资料多后面不管谁接手都能快速上手。教务管理类系统最怕的是“某个模块只有某个同事能维护”Spring Boot 这个选型能最大程度降低这种风险。管理端用 Vue是因为这类后台页面大量是表格、表单、级联选择、上传组件Vue 3 配合 Element Plus 基本开箱即用组件库稳定不用自己造轮子。员工端用微信小程序理由更直接员工不用装 App微信扫码就能进入学习门槛最低培训专员把小程序码往群里一发新员工扫一下就完成注册体验比引导下载安装包顺畅得多。这里也说明一下为什么管理端不做成小程序。管理端的操作场景是密集录入、批量分配、报表筛选这些交互在浏览器里配合大屏做很顺手硬塞进小程序反而难用。员工端则是轻量的学习、观看视频、答题小程序完全够用。两端场景不同分开是合理的。2. 后端核心模块拆解课程、考核、学习记录如何联动2.1 数据库设计核心表结构与关键约束这套系统后端的核心模块可以分成四块课程管理、培训任务分配、学习过程记录、考核判定。围绕这几个模块我梳理了下面这些核心表。表名作用关键字段employee员工信息id、工号、姓名、部门、岗位、入职时间course课程主体id、名称、分类、封面、总时长、是否启用course_chapter课程章节id、course_id、章节序号、标题course_material章节下的课件id、chapter_id、类型(视频/PDF/图文)、文件地址、时长employee_course员工培训任务分配记录id、employee_id、course_id、分配时间、状态learning_record学习明细记录id、employee_id、material_id、累计时长、完成状态exam考试配置id、名称、关联课程、及格分、考试时长question_bank题库id、题型、题干、选项、答案、分值exam_paper试卷id、exam_id、试卷名称、总分exam_paper_question试卷题目关联id、paper_id、question_id、排序answer_record答题记录id、employee_id、paper_id、question_id、作答内容、对错几个关键设计点值得展开说。第一员工和课程之间不是直接挂在 employee 表里而是通过 employee_course 关联表实现。因为同一个岗位下不同批次员工要学的课程不同甚至同批次里不同入职时间的人任务也不同用关联表按员工独立分配最灵活。第二learning_record 表一定要加 (employee_id, material_id) 的联合唯一索引否则同一个员工反复进入同一课件学习会产生多条记录进度统计就乱了。第三material_type 字段区分课件类型因为视频、PDF、图文三种课件的“完成”判定逻辑完全不同视频可以按播放时长判定PDF 和图文则要么定时长要么用户手动点击“已学习完成”。2.2 学习进度的上报与判定逻辑学习进度是整个平台的“地基”如果进度算不准后面考试解锁、报表统计全是错的。我们的实现思路是分段上报、服务端累计。小程序端每 30 秒向后端上报一次当前播放位置上报参数包括 courseId、materialId、currentTime 和 eventTime。为什么要带 eventTime就是为了给服务端做校验防止有人伪造 Request 直接刷时长。服务端拿到一次上报后会和数据库里该员工对该课件的最后一次 progress 做差值比对正常情况下两次上报的时间差应该落在 20 到 60 秒之间。如果差值小于 20 秒说明客户端上报过于频繁可能是脚本在刷如果大于 60 秒说明中间有断网或者切后台这次上报的记录要按实际心跳间隔做折减不能全部累加。下面是一段核心进度更新逻辑的示意代码用 Java 写的public void reportProgress(ProgressReportDTO dto) { LearningRecord record learningRecordMapper.selectOne( new LambdaQueryWrapperLearningRecord() .eq(LearningRecord::getEmployeeId, dto.getEmployeeId()) .eq(LearningRecord::getMaterialId, dto.getMaterialId())); // 首次学习则初始化一条记录 if (record null) { record new LearningRecord(); record.setEmployeeId(dto.getEmployeeId()); record.setMaterialId(dto.getMaterialId()); record.setTotalSeconds(0); record.setCompleteFlag(0); } // 核心校验本次上报差值是否在合理区间 long delta dto.getCurrentTime() - record.getLastPosition(); long timeDiff (dto.getEventTime() - record.getLastEventTime()) / 1000; if (delta 0 || delta timeDiff 5) { // 异常上报直接丢弃不累加时长 return; } int realAdd (int) Math.min(delta, 30); record.setTotalSeconds(record.getTotalSeconds() realAdd); record.setLastPosition(dto.getCurrentTime()); record.setLastEventTime(dto.getEventTime()); // 判定完成累计时长达到课件时长90%并且播放位置接近结尾 Material material materialMapper.selectById(dto.getMaterialId()); if (record.getTotalSeconds() material.getDuration() * 0.9 dto.getCurrentTime() material.getDuration() * 0.95) { record.setCompleteFlag(1); } learningRecordMapper.insertOrUpdate(record); }这段逻辑里最容易忽略的一点是“拖动进度条到结尾不算完成”。很多同类系统栽在这个地方员工打开视频直接拖到最后一秒播放位置满足条件但累计时长不够结果被标记完成。我们的判定条件里累计时长和结尾位置是同时满足的所以单纯拖进度条过不了。这个规则上线后确实有员工尝试过最后都老实回来从头看。2.3 自动考核模块题库、抽题与防作弊考试的联动逻辑是员工被分配培训任务后系统按课程维度判断完成状态全部课件的完成标志都为 1 时自动开放对应考试。考试通过默认 60 分及格才算整个培训结业。题库设计按题型区分单选、多选、判断三种客观题。每道题带难度字段试卷生成有两种策略手动组卷培训专员按章节指定题目随机抽题系统按题型和数量配置从题库中按难度比例抽取。随机抽题的好处是员工之间题目顺序不同、选项顺序也不同降低抄袭概率。考试过程的防作弊设计有两层。前端层面小程序里切换到后台或在考试页面点击返回都触发一次“异常离场”记录累计三次强制交卷。倒计时显示是前端本地做的但真正的剩余时间以服务端为准。后端在考试开始时下发截止时间戳前端每次提交答案都会带当前时间服务端判断是否超时超时就拒绝接收并强制交卷。这个设计非常重要因为本地计时可以被篡改服务端时间戳才是最终仲裁。答题记录按 answer_record 表逐题保存。客观题由系统自动判分后台只需做一次汇总即可生成考试成绩。如果以后要加入简答题预留一个人工阅卷字段和审核状态字段就够了这个表结构不需要大改。3. 管理端 Vue 页面权限模型与课件的实操细节3.1 三层权限模型与动态路由管理端的使用者不只是管理员一个角色至少要分三层系统管理员、培训专员、部门主管。系统管理员负责最基础的配置比如部门结构、员工账号、角色分配。培训专员是日常使用最频繁的角色负责课程创建、课件上传、培训计划分配、查看考试成绩。部门主管是只读角色能查看本部门员工的学习进度和考试通过率但不能修改课程内容。三层权限必须在前端路由和后端接口双重控制前端控制只是提升体验真正的防线在后端。前端通过 Vue Router 的 beforeEach 钩子做路由守卫登录时后端返回该用户的角色和权限码列表前端根据权限码动态生成可访问的路由表菜单只渲染有权限的项。按钮级权限用自定义指令 v-permission 控制没有权限的删除、发布按钮直接不渲染。后端接口层面方法上加 PreAuthorize(hasAuthority(course:manage)) 这类注解确保越权请求直接被拒绝。这里分享一个实际教训一开始我们只做了后端接口权限前端把全部菜单都渲染出来用户点进去才发现没数据。后来补上前端动态路由但只控制了页面级权限漏了按钮级。直到有个培训专员把课程发布按钮点出来才意识到按钮权限也得做。所以说管理端权限一定别图省事页面级和按钮级要分开处理。3.2 视频课件的上传、转码与存储课件的存储是这套系统里比较折腾的环节。培训视频的原始素材五花八门有现场录制的 .mov有手机拍摄的 .avi有从网盘下载的各种编码格式。微信小程序的 video 组件对视频格式要求比较严格必须是 H.264 编码的 mp4 文件否则部分设备直接黑屏无法播放。所以上传流程不能只接一个文件上传接口了事。我们最终的方案是管理端前端先做分片上传。因为一部培训视频动辄几百 MB直接用 MultipartFile 一次性上传Nginx 超时、后端内存吃紧都是大概率事件。分片大小设为 5MB前端用 SparkMD5 计算文件唯一标识每片上传带分片序号和总分片数后端按标识暂存分片全部传完后合并文件。合并成功后后端调用 ffmpeg 做转码转码命令大致是ffmpeg -i input.mov -c:v libx264 -c:a aac -b:a 128k -vf scale-2:720 output.mp4转码任务在正式环境里不能直接放在请求线程里同步执行几百 MB 的视频转码可能要几分钟接口会直接超时。我们用了一个简单的异步任务表上传完原始文件后往任务表插入一条转码任务记录后台轮询执行完成后更新状态并回写新文件地址。管理端前端通过轮询接口查询转码状态转码期间显示“处理中”完成后自动刷新为可播放状态。存储方案我们选了 MinIO 做私有化部署。视频文件不直接放服务器本地磁盘因为后面多台服务器部署时本地文件不同步会出大问题。MinIO 暴露的文件地址走 Nginx 加一层鉴权避免课件资源被任意下载。3.3 培训报表用数据驱动人事决策报表模块最初不在需求里是后来培训专员反馈“每次领导问培训完成情况都要去数据库里手动查”才补上的。报表不追求花哨核心就三张课程完成率报表、部门学习进度报表、考试成绩分布报表。课程完成率报表按课程维度统计每门课分配了多少人多少人开始学多少人已完成完成率是多少。部门学习进度报表按部门维度统计可以对比不同部门的学习速度找出推进缓慢的部门。考试成绩分布报表按分数段统计人数直观看出哪些课程内容员工普遍掌握得不好。技术实现上报表数据从 learning_record 和 employee_course 表聚合查询。以后端返回聚合结果、前端用 ECharts 渲染的方式实现不在数据库端做复杂报表中间表。SQL 大概长这样SELECT d.dept_name AS deptName, COUNT(DISTINCT ec.employee_id) AS totalCount, SUM(CASE WHEN ec.status 3 THEN 1 ELSE 0 END) AS doneCount FROM employee_course ec LEFT JOIN employee e ON ec.employee_id e.id LEFT JOIN department d ON e.dept_id d.id WHERE ec.course_id #{courseId} GROUP BY d.dept_name;这套报表上线后人事那边最直接的反馈是终于能拿出数据去和各班组长核对“为什么这个部门两周了还有 60% 的人没开始看”。数据本身不会骗人有据可查之后执行力的推进效率高了很多。4. 微信小程序端员工学习体验与鉴权实现4.1 扫码登录与工号绑定的完整流程员工端小程序的使用链路是培训专员把小程序码发到新员工群员工扫码打开输入工号和初始密码完成绑定之后每次打开直接进入学习首页看到自己名下的培训任务。登录流程里最核心的是微信 openid 和内部账号体系的关联。小程序端调用 wx.login 拿到临时 code传给后端后端用 code 调用微信接口换取 openid 和 session_key。这里有一条红线session_key 绝不能下发到前端也不能写进日志它只在后端保存后续如果需要解密手机号等数据时才会用到。换取 openid 后后端去 employee 表查是否已有绑定记录没有则返回“待绑定”状态小程序端弹出工号密码输入页。绑定成功后后端签发自己的 JWT token后续所有接口请求在 header 里带 Authorization。要注意 JWT 的有效期不能设太长我们设置 7 天过期配合小程序端的 wx.setStorageSync 持久化存储。还有个细节是初始密码问题新员工第一次绑定的密码应该由培训专员批量生成并提醒员工首次登录后修改否则员工离职后账号容易被冒用。4.2 学习打卡与防刷机制员工端和小程序视频播放联动时防刷是最需要反复打磨的部分。前面提到的服务端差值校验是第一道防线。除了那次校验我们还加了两个限制。一是同一账号在同一时刻只能在一个设备上学习。实现方式用 Redis 做一个简单锁key 为 employeeId courseIdvalue 为设备标识播放开始时写入退出或超时后释放。这样可以防止员工用两个设备同时挂机刷时长。二是每个员工每天的学习时长有上限默认 8 小时。这个限制用来预防有人开着视频不管正好应对那种“为了完成而完成”的挂机行为。这里也说明一下防刷机制不能做过度。比如限制太严格正常员工坐地铁时网络切换频繁会造成学习进度频繁上报失败体验很差。我们的策略是网络断点导致的上报丢失不惩罚只限制异常高频和超长时间挂机。平衡点需要在真实使用场景里慢慢调我们的参数是上线第一周根据日志调整过两次才定下来的。4.3 小程序视频播放的兼容性细节小程序原生 video 组件用起来有不少坑尤其是跨机型差异。最典型的是 iOS 上 video 组件的 bindended 事件偶尔不触发导致视频播完了但进度停在 99%。我们最后的兜底方案是在 timeupdate 事件里判断 currentTime 和 duration 的差值小于 0.5 秒时主动调用一次结束上报这样就算 bindended 不触发也能兜住。还有一个问题是用户在学习中途切到后台或退出小程序如果不处理最后一次进度会因为心跳没发出去而丢失。我们在 onHide 和 onUnload 生命周期里都加了上报逻辑并且在视频暂停时也上报一次当前位置。这里有个细节小程序退到后台后onHide 里发的请求有时会被微信挂起不能保证成功。所以我们在前端还在进入页面时就把最后一次已知进度写到本地缓存下次打开时先重放本地进度再做正常上报双保险。包体积也是一个隐藏问题。小程序主包限制 2MB一旦引入 UI 组件库、图表库再加一堆页面很容易超限。我们的处理是把员工端的学习首页、课程详情、播放页、考试页等都放在分包里主包只保留启动页和公共工具最终主包压到 1.3MB 以下顺利通过审核。5. 部署上线与踩坑实录5.1 部署架构与前置条件正式环境我建议至少准备一台 2 核 4G 的云服务器也建议把 MySQL、Redis、MinIO 和 Nginx 分开部署或至少使用云厂商的托管服务避免单机资源互相抢占。我们的部署方式是后端打成 jar 包用 systemd 托管前端 Vue 构建后的静态文件由 Nginx 托管小程序端通过相对路径 /api 走反向代理访问后端接口。小程序上线前有一堆前置条件必须处理好否则审核或真机访问直接失败。第一是 HTTPS所有合法域名必须是备案过的域名且配置 HTTPS 证书。第二是在小程序后台配置 request 合法域名、uploadFile 合法域名和 downloadFile 合法域名分别对应接口地址、上传地址和课件文件地址。这里容易漏的是课件视频地址和封面图地址很多人只配了接口域名结果视频加载不出来才发现。部署后 Nginx 有一个关键配置video 文件真正传输时如果服务器带宽有限几十人同时播放视频会大量占用连接。我们在 Nginx 里开启了静态文件缓存对视频文件配置了强缓存头客户端在重复观看同一课件的章节能直接走本地缓存减少源站压力。5.2 上线阶段遇到并解决的问题上线头两周遇到的问题比开发阶段多得多挑几个印象深的分享。第一个问题是员工更换手机后本地缓存的进度直接丢失。因为小程序端把最后播放位置存在本地而员工上班时用工作手机看回家用自己手机看两台设备之间的进度没有同步。这个问题的本质是本地緩存只能作为兜底不能作为进度的唯一来源。我们把逻辑调整为进入播放页时优先从后端接口拉取该课件的最后进度本地缓存只在断网或请求失败时作为降级方案。修复后多设备切换的问题就消失了。第二个问题是视频上传接口最初直接走了 Nginx 默认配置文件稍一大就被 413 拦截。排查半天发现是默认 client_max_body_size 只有 1MB。虽然最终方案改成了分片上传但分片合并接口单次提交的数据量也不小最后在 Nginx 层统一调大了 body 限制。第三个问题和考试计时有关。最初考试倒计时放在前端本地有员工反馈考试中退出重新进入后倒计时居然刷新了。这是因为每次进入考试页面都重新调用开始考试接口拿到的又是完整的考试时长。修复方案是后端在考试表里记录 begin_time 和 end_time员工每次进入时返回的是 end_time 减去当前时间后的剩余时长异常退出也不影响总体计时。改完之后这个漏洞被堵住了。第四个问题是拖动进度条的判定。前面提到“拖动到结尾不算完成”我们用累计时长双重校验堵住了但上线后又有员工通过快速反复暂停、播放来刷时间。这本质上还是心跳频率校验不够细。后来我们在后端对单次上报的时间增量做了更严格的限制两次上报之间增量的绝对值超过 30 秒就判定异常并丢弃这样频繁暂停播放的增益也变得很低。最后想说一点个人体会。这类企业内部系统的成败技术实现只占一半另一半取决于业务规则设计得是否贴近真实场景。比如课件完成判定定得太松员工挂机刷完定得太严正常使用也会误伤。这些都是上线后根据日志不断磨合出来的不可能一蹴而就。如果你们也在规划类似的岗前培训学习平台建议在需求阶段就把“如何定义学习完成”“如何防刷”“进度如何恢复”这三个问题想清楚它们会在后面每个模块里反复出现。把这个地基打牢整个系统的开发会顺畅很多。
解法)
