做这个项目前，我在某高校后勤见过真实的报修流程：学生填纸质单子，维修工靠电话确认楼层和时间，管理员月底手工导Excel统计工作量。报修进度对学生是个黑盒，维修压力对管理部门也是个黑盒。所以我动手做了这套“基于微信小程序的校园保修系统”，后端用 SpringBoot，前端用微信小程序原生框架，核心就是把“谁报修、谁处理、处理到哪一步”变成一条透明、可追踪、能统计的工单流。微信扫码即用，不用单独装App，天然适合高校场景；SpringBoot负责接口、鉴权和数据落库，开发效率高，部署也简单。这套东西很适合课程设计、毕业设计，或者刚接触前后端分离的小团队拿去当脚手架。下面把整体设计、表结构、后端核心、小程序端交互和踩过的坑一次讲透。
1. 项目定位与整体设计思路
很多同学拿到这类题目第一反应是堆页面：登录页、报修页、管理页各来一套，结果做到后面发现核心的“工单状态流转”根本没想清楚。我设计时反着来，先把业务流程画成一条闭环，再反推接口和页面。
1.1 为什么是“微信小程序+SpringBoot”组合
小程序端看中的是零安装和微信授权登录。校园里学生、老师、维修工都有微信，扫一扫或搜索进入，不用记账号密码，这一点比传统Web系统友好太多。而且小程序对图片上传、表单填写的支持很完整，做报修需要填“位置+问题描述+现场照片”这三个信息，天然贴合。
后端选 SpringBoot，不是因为互联网大厂都在用，而是它在学生项目和技术学习中太合适了。SpringBoot 自带内嵌Tomcat，打一个jar包就能跑；整合 MyBatis-Plus 后写CRUD基本不用手写复杂SQL；拦截器做登录鉴权、Redis存会话、阿里云OSS存图片都有成熟的脚手架。相比Node.js和PHP，Java生态在事务控制、状态机这类“业务严谨性”要求高的场景更稳。报修系统最怕订单状态错乱，SpringBoot的@Transactional能保证一个操作里多个表的数据一致。
还有一个很实在的原因：这个组合的参考资料多。遇到任何报错，不管是小程序端还是后端，搜索匹配度都很高，对刚入门的人极其友好。
1.2 三类角色与完整业务闭环
这个系统不只有“学生提交、维修工处理”两层，我加入了管理员角色，把流程拆成五步：
- 学生提交报修单，填写楼栋、房间、问题分类、描述和现场照片。
- 管理员在后台看到待派单列表，把工单指派给对应维修工。
- 维修工收到指派通知，接单后开始处理，状态变为“维修中”。
- 维修工处理完成，填写维修说明和结果，状态变为“已完成”。
- 学生确认完成并打分评价，整个工单闭环。
为什么要加管理员派单这一环节？因为校园报修不是外卖抢单，维修工有固定片区，擅长项目也不同。系统初期如果直接让学生选维修工，既不现实也不公平。管理员派单还能在高峰期平衡工作量。如果后期想更高效，可以改成“维修工自主抢单+管理员兜底”的混合模式，接口都不需要大改，只改状态流转逻辑即可。
必须设置“取消”功能。学生提交了工单，但自己搞定了问题，比如路由器重启一下就好了，这时候应该允许学生在“待派单”或“已接单未开始”状态下取消，避免形成无效工单。
1.3 技术选型的细节考量
权限认证这块，我没有用复杂的OAuth2或JWT，而是用 token 机制：小程序调用 wx.login 拿到临时 code，后端再拿着 code 换成 openid。第一次登录时自动注册用户，并把生成的 token 返回给小程序，之后所有请求都在请求头里带 token。这样实现简单、够用，也符合“不要过早引入复杂度”的原则。
图片存储我一开始用本地磁盘，把上传文件放到服务器某个目录，然后通过 SpringBoot 静态资源映射暴露访问地址。这个方案在量小的场景完全够用。但如果你做的项目要部署到云服务器，建议直接用对象存储OSS或COS，图片上传接口不变，只是把存储层换成OSS客户端。用OSS后，小程序端可以直接拿到带签名的URL显示图片，不用关心服务器静态映射配置，避免很多麻烦。
数据层我选 MySQL + MyBatis-Plus。MyBatis-Plus 的 LambdaQueryWrapper 能省掉大量拼接SQL的代码，分页插件也内置了。做后台统计查询时，联合查询部分可以手动写一个mapper XML，灵活性足够。
2. 数据库设计与核心表结构
数据库是整个系统最需要花时间设计的地方。我第一版把评价字段直接塞进报修单表，后来发现扩展性很差，比如想记录维修工多次维修感想、学生追评都没法做。拆表之后清晰很多。
2.1 用户表与三端身份设计
用户表是所有角色的基础，字段如下：
CREATE TABLE sys_user ( id BIGINT AUTO_INCREMENT PRIMARY KEY, openid VARCHAR(64) NOT NULL UNIQUE, nickname VARCHAR(64), avatar_url VARCHAR(255), role TINYINT DEFAULT 1 COMMENT '1学生 2维修工 3管理员 4超级管理员', student_no VARCHAR(32), department VARCHAR(64), phone VARCHAR(20), building VARCHAR(32), room VARCHAR(32), create_time DATETIME, update_time DATETIME );角色区分我直接用了数字字段，没做单独的角色表。原因很简单：角色是固定、轻量的，不会出现一个用户有多个角色的复杂需求。维修工和管理员是后台手动导入或修改role字段来分配的。小程序端登录时，用户只能是“学生/普通用户”，管理员账号从后台登录时验证角色后跳转管理页面。
这里有个关键点：同一个微信openid在测试时可能对应多个身份。我本地测试时会用一个开关，在登录接口里允许指定测试账号角色，否则手机上没法同时模拟学生和维修工。正式环境必须去掉这个逻辑，通过后管审核来分配角色。
2.2 报修工单主表
报修工单表是核心中的核心，我设计它的原则是“一个工单的所有关键信息都在一行记录里，只放高频查询字段，低频大文本拆出去”。
CREATE TABLE repair_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_no VARCHAR(32) NOT NULL COMMENT '工单编号', user_id BIGINT NOT NULL COMMENT '学生ID', assignee_id BIGINT DEFAULT NULL COMMENT '维修工ID', category_id BIGINT COMMENT '分类ID', title VARCHAR(100) NOT NULL, description TEXT, building VARCHAR(64), room VARCHAR(64), contact_phone VARCHAR(20), images TEXT COMMENT 'JSON数组，存图片URL', status TINYINT DEFAULT 0 COMMENT '0待派单 1维修中 2已完成 3已取消 4已评价', is_urgent TINYINT DEFAULT 0 COMMENT '是否加急', start_time DATETIME COMMENT '维修开始时间', finish_time DATETIME COMMENT '完成时间', rating TINYINT COMMENT '评分1-5', feedback VARCHAR(500), create_time DATETIME, update_time DATETIME );status字段是状态机核心。我把“已完成”和“已评价”拆成两个状态，是为了统计报表时区分“维修完成率”和“学生满意率”。新增的is_urgent是第二版迭代加的，学生勾选“紧急”后，管理员列表可以按紧急度排序，优先级更高，这个字段在答辩或演示时是一个很好的亮点。
order_no工单编号用年月日+自增序号生成，比如202506120001，方便人工查询和Excel统计。
我建议工单表不要存学生完整的宿舍地址，只存building和room两个字段，便于查询。学生具体姓名、电话通过user_id关联用户表获取，避免user_id变更导致的数据冗余。
2.3 辅助表：分类、评价、状态日志
报修分类表特别简单，提前初始化水电、门窗、空调、网络、家具、其他等几类。但是注意，不要把分类写死在前端，因为维修工的技能分配和后端统计都依赖这个表，以后加“电梯维修”“热水系统”分类时，不用改小程序代码。
状态流转日志表是容易被忽略、但排查问题时最救命的一张表：
CREATE TABLE order_log ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_id BIGINT NOT NULL, action VARCHAR(20) COMMENT 'submit/assign/accept/complete/cancel/rate', from_user_id BIGINT, content VARCHAR(255), create_time DATETIME );为什么要记录日志？想象这个场景：学生说“我的工单被取消了，我没取消过”，如果没有日志，你根本不知道是谁在什么时候取消的。有了日志，直接查order_log，看到管理员或维修工在某个时间点执行过cancel操作，问题立刻定位。同时这个日志还能支撑“工单处理时长分析”，比如从提交到接单花了多久、接单到完成花了多久，都是管理报表的核心指标。
评价表单独拆出来的原因是：一个工单理论上可以多次评价，比如维修完成后学生评价一次，一个月后设备又出问题，可以追加评价。拆开之后，追加评价不影响工单主表。
3. SpringBoot后端核心实现
后端结构我用的是经典分层：controller、service、mapper、entity，另外加一个common包放统一返回结果、异常处理、拦截器。下面按实际开发顺序讲最重要的事。
3.1 后端分层结构与启动配置
目录结构不必追求复杂DDD，Controller只做参数校验和返回，Service写业务逻辑，Mapper层继承MyBatis-Plus的BaseMapper，简单直接。
这里要强调一个规范：Controller层不要返回裸对象，统一返回Result<T>。我自定义了code、message、data三个字段。好处是前端可以统一在request.js里判断code，不用每个接口单独处理错误。比如未登录返回 code=401，前端收到后直接跳转登录页。如果每个接口返回格式不统一，小程序里的错误处理就非常痛苦。
启动类上记得添加@MapperScan("xxx.mapper")，这是MyBatis-Plus开发中最常见的启动即报错原因。如果不想用注解扫描，也可以在启动类上加@MapperScan或者每个Mapper上写@Mapper注解。
3.2 微信登录与身份鉴权的实现
登录接口流程是：
- 小程序调用
wx.login()拿 code。 - 后端接收 code 后，调用微信接口
code2Session交换 openid 和 session_key。 - 用 openid 查用户表，如果没有就自动注册。
- 生成随机 token 保存到 Redis，key 为
token:用户ID，设置过期时间（我设了7天）。 - 返回 token 和用户基本信息给小程序。
这里要注意，code 是一次性的，只能使用一次。如果你在本地调试时发现同一个 code 反复报错，那不是代码问题，是微信接口的幂等限制。还有session_key属于敏感信息，绝对不能返回给小程序或者直接存储，它只用于解密手机号等场景。
登录鉴权我拦截除login外的所有接口。写一个AuthInterceptor，从请求头取Authorization，解析token后把userId放入ThreadLocal。Service里就可以直接用UserContext.getUserId()来获取当前操作人，省得每写一个接口就把userId作为参数传来传去。
3.3 报修单状态机的接口设计
接口设计围绕状态机展开。每个状态变更接口，Service层第一件事是“当前状态对不对”，再做业务操作，最后写日志。
以“维修工接单”为例：
@Transactional public boolean accept(Long orderId) { Long workerId = UserContext.getUserId(); int rows = repairOrderMapper.update(null, new LambdaUpdateWrapper<RepairOrder>() .eq(RepairOrder::getId, orderId) .eq(RepairOrder::getStatus, 0) .set(RepairOrder::getStatus, 1) .set(RepairOrder::getAssigneeId, workerId) .set(RepairOrder::getStartTime, new Date()) ); if (rows == 1) { orderLogMapper.insert(new OrderLog(orderId, "accept", workerId, "维修工接单开始处理")); } return rows == 1; }关键在于eq(status, 0)这个条件。如果两个维修工同时点击接单，数据库层面只有一个 update 会成功，另一个影响行数为0。这个技巧叫“乐观锁条件更新”，比先查再改更可靠，也不用引入额外的悲观锁。
学生取消接口判断更严格，只有状态是0待派单时才允许取消。管理员取消则可以在1维修中时取消，但要记录原因，并通知维修工。
订单列表查询我推荐分状态查询而不是一次全查，通过status参数区分。小程序端底部用tab切换“全部、待处理、处理中、已完成”，每个tab就是一个查询参数。后端分页用 MyBatis-Plus 的Page，前端传页码和页大小即可。
3.4 图片上传与静态资源映射
图片上传接口相对独立，我单独讲它是因为这里有特别多坑。上传逻辑本身不复杂：小程序调用wx.uploadFile，把图片文件作为 multipart form-data 发给后端，后端的MultipartFile接收，存到指定目录，生成UUID文件名，返回完整URL给前端。
本地开发时，图片要想在小程序里正常显示，SpringBoot必须配置静态资源映射：
spring: web: resources: static-locations: file:D:/upload/或者用WebMvcConfigurer添加映射：
registry.addResourceHandler("/upload/**") .addResourceLocations("file:D:/upload/");很多同学卡在“上传成功但图片打不开”，十有八九是静态资源映射没生效。另一个常见问题是后端接收不到文件，因为SpringBoot默认单次请求最大文件大小是1MB。报修照片动辄2-3MB，必须修改配置：
spring: servlet: multipart: max-file-size: 10MB max-request-size: 20MB我第二版已经改成了OSS存储，本地不再存图片。但本地开发还是保留这个上传接口，保证没有OSS环境也能跑通全流程。
4. 小程序前端的核心页面与交互
小程序端的页面数量不多，但我把每个角色的页面做了拆分，避免在一个页面里堆太多条件渲染。完整的页面结构如下：
4.1 小程序目录划分与请求封装
页面按角色分目录，便于管理和后续扩展：
pages/ login/ # 登录 index/ # 首页 repair/ submit/ # 提交报修 list/ # 我的报修列表 detail/ # 报修详情 worker/ list/ # 待接单列表 work/ # 维修工作台 admin/ dispatch/ # 派单管理 dashboard/ # 数据统计 category/ # 分类管理 user/ index/ # 个人中心每个页面的逻辑我都尽量简洁：页面只负责渲染和交互事件，请求统统走utils/request.js封装。小程序原生wx.request比较啰嗦，我封装后全局处理URL前缀、token注入、code错误拦截。
// utils/request.js 核心片段 const BASE_URL = 'https://example.com/api'; function request(url, method, data) { return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + url, method, data, header: { 'Content-Type': 'application/json', 'Authorization': wx.getStorageSync('token') }, success(res) { if (res.data.code === 0) { resolve(res.data.data); } else if (res.data.code === 401) { wx.navigateTo({ url: '/pages/login/login' }); } else { wx.showToast({ title: res.data.message }); reject(res.data); } }, fail: reject }); }); }BASE_URL 建议不要直接写在多个请求里，不然改环境时改到怀疑人生。我在 app.js 里用全局变量维护，开发环境和生产环境切换只改一个位置。
4.2 学生端：提交报修与进度查询
提交报修页是学生最常用的页面。表单字段我控制得很克制：分类、标题/问题描述、楼栋、房间号、手机号、照片、是否加急。字段越少，学生填完的意愿越高。有些系统要求学生填工号、学号、身份类型，完全是多此一举，openid已经能识别身份了。
照片上传这里要用wx.chooseMedia选择图片，再逐张或循环调wx.uploadFile得到URL，最后把URL数组塞进表单一起提交。注意wx.uploadFile不支持多文件同时上传，必须循环调。我图片上传接口一次处理一张，前端循环上传。按3张图片算，耗时大概1到2秒，可接受。
提交成功后，前台调wx.navigateBack回到“我的报修”列表，并静默刷新。学生最关心的是进度，因此列表卡片上要清晰展示当前状态。我用不同颜色标签区分：灰色待派单、蓝色维修中、绿色已完成、红色已取消。状态文案要讲究，待派单可以写成“等待工作人员处理”，维修中写成“师傅正在处理中”，不要用太技术化的词。
维修完成后，详情页底部出现“评价”按钮，只有当前状态为已完成时显示。评价内容包含星星评分和文字反馈，提交后状态变成已评价。这里要测试清楚：学生在完成状态下反复点击评价是否会重复提交。我在Service层判断了当前状态，只有已完成状态才能评，评价后将状态置为已评价，并发重复请求只能成功一次，这也是用条件更新解决的。
4.3 维修端与管理端：接单派单
维修工登录后看到的是待接单列表和正在进行列表。列表卡片上突出显示地址和紧急程度。紧急工单右上角加“急”字标签，并用红色强调，这样维修工能快速决策。
接单操作在详情页完成，点击接单后按钮立刻变成“处理中不可取消”，同时底部出现“完成维修”按钮。完成时需要填写维修说明，比如“更换水龙头密封圈”或“检修网络面板，重新打水晶头”。这个说明会写入order_log日志，并最终展示给学生。
管理端的派单页是后台核心。列表只显示待派单记录，管理员点击一条后弹出维修工选择器。维修工列表按片区或擅长分类过滤，比如水暖问题只显示水暖组维修工。这里我做了简单的动态查询：管理员选择分类后，筛选维修工的speciality字段，分类表和维修工之间是字符串匹配，没有建多对多关系。如果团队大、工单多，建议后面改成技能标签多对多表，但这套方案对校园场景完全够用。
管理端的统计页也是必须的，我放了三个数字卡片：今日待派单数、本周完成数、本月平均处理时长。再放一个柱状图展示最近7天各类别报修数量。图表用小程序原生的canvas画太费劲，我直接用echarts-for-weixin组件，集成不复杂，效果非常加分。毕业设计或者汇报演示时，这个统计页最能体现系统价值。
5. 关键难点与常见问题排查
开发过程中踩过的坑比写代码花的时间还多。我把最影响人心情的几个问题整理成速查表，帮你省掉排查方向。
5.1 登录403/401：code值问题套餐
小程序请求后端登录接口时，最常见的报错是401或系统异常。分三类排查：
第一，code是否正确。wx.login返回的code是临时凭证，只能交换一次。我写过一遍调用登录后，又在第二个页面用同一个code重复请求，结果微信返回错误。排查方法是后端打印收到的code，再到微信开发者工具里重新编译一次，确保每次都是新code。
第二，appid和secret是否正确。有人把测试号复制到代码里，结果和线上小程序的基础库配置不对应。建议把appid和secret统一维护在SpringBoot的application.yml中，不要hardcode在代码里。工具类里加一段校验日志，请求参数、返回结果都打印出来。
第三，网络问题，本地开发时小程序请求http://127.0.0.1:8080是可以的，前提是开发者工具里勾选了“不校验合法域名”。真机调试时，局域网IP、HTTPS、备案域名三个问题会连环出现。一个稳妥的联调方案是：用内网穿透工具把本地电脑的8080端口临时映射成一个HTTPS域名，小程序请求这个域名即可，省去每次部署到云服务器的等待。
5.2 跨域与线上环境配置
小程序原生请求不受浏览器同源策略限制，所以一般不存在跨域问题。但如果你把后端接口放在域名A，图片放在域名B，或者小程序WebView加载网页，就要注意合法域名校验问题。
微信小程序请求的域名必须在“小程序管理后台->开发管理->服务器域名”里配置，且必须是HTTPS、ICP备案的合规域名。开发阶段可以用“不校验合法域名”按钮绕过，但上线前必须配好。
另外要注意：开发环境经常是HTTP，上线必须HTTPS。我在云服务器上部署时，用Nginx反向代理到SpringBoot服务，并且配置了SSL证书，这也是最标准的生产方式。Nginx的配置不超过20行：
server { listen 443 ssl; server_name yourdomain.com; ssl_certificate cert.pem; ssl_certificate_key key.pem; location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这样小程序只请求https://yourdomain.com/api，后端不需要处理跨域头，因为浏览器同源策略在这里不生效。
5.3 上传图片显示不出来的连环排查
图片上传成功但前端显示不了，这个问题我在联调时遇到过不少次，总结了一套排查路径：
上传成功后，确认返回的URL到底怎么拼接。如果返回的是相对路径/upload/xxx.jpg，小程序端直接访问是会失败的，必须拼上域名前缀。我后来在返回结果里直接给出完整URL，前端不做任何拼接。
静态资源映射只认本地路径，注意file:D:/upload/后面必须带一个斜杠结尾。如果你的代码里写的是file:D:/upload，很多情况会映射失败。Linux服务器上路径大小写敏感，这些细节都要注意。
如果图片传到了服务器，同时Nginx也在运行，必须检查Nginx的静态资源规则，不能仅仅在后端配置路径映射。我在Nginx中加了对/upload目录的别名指向，生产环境就不依赖SpringBoot托管图片文件了。
最后，别忘了检查微信后台的“downloadFile合法域名”配置。图片URL所在的域名如果不加进配置，小程序里是加载不出来的，真机调试时尤其明显。开发工具模拟器能显示，真机不行，大概率就是这个原因。
5.4 状态错乱与并发难题
报修系统中，状态错乱是最严重的业务问题。比如维修工处理完点了完成，学生这个页面还停留在“待派单”状态，刷新后才变成已完成，这不是状态错乱，而是页面缓存问题。但如果未登录用户能操作别人的工单，那就是严重的问题了。
我统一在Service层做了三件事防止状态错乱：第一，所有状态变更都带前置状态条件，UPDATE语句里写死当前状态；第二，所有获取改动的userId都从token中解析，不用前端传入的userId；第三，所有变更操作都先写日志，便于事后追溯。
一个反向案例：我曾经在Controller层直接接收前端传来的orderId和targetStatus，前端传什么就更新什么，结果学生用抓包工具把状态改成已评价，管理员后台统计直接混乱。后来改成接口定义的语义化操作，比如accept、complete、cancel，不允许前端传任意目标状态。语义化操作的好处是业务边界清晰，而且方便加各种前置校验，这个设计思路分享给你，尤其是要交作业或者开源的项目，代码评审时这套逻辑很容易被认可。
5.5 容易被忽略的MySQL时区与字符集问题
小程序端显示时间和数据库存的时间不一致，经常差8小时，这是时区问题。MySQL连接串必须加上serverTimezone=Asia/Shanghai，同时JVM参数加-Duser.timezone=Asia/Shanghai，双保险。如果数据库用的UTC，后端又是中国时区，写入时间会出现两套标准，查询排序也会错。
字符集问题见得多的是中文乱码。创建表时统一用utf8mb4，MySQL连接串加characterEncoding=utf8。我在数据库初始化脚本里把所有字符串字段都写明白字符集，避免因为环境默认值不同出现乱码。这里有一个细节：utf8mb4和utf8在小表情场景下区别很大，学生反馈里经常带emoji，用utf8会存不进去报错，所以必须用utf8mb4。
6. 写在最后：如果你也想复现这套系统
做这套系统最大的体会是：业务闭环比技术细节更重要。一开始我花了很多时间在“怎么把页面做得好看”上，后来发现真正让学生和老师认可的，是“工单状态永远可查、处理记录永远有迹可循”。技术层面的SpringBoot、小程序、MySQL，都是常见的通用技能，真正拉开差距的是有没有把状态机、权限边界、数据追溯这些设计想清楚。
如果想复现，我建议按这个顺序推进：先画业务状态图，列清楚每个状态谁可以操作；再设计表结构，确保主表和日志表覆盖所有业务；然后先完成后端全部接口，用Postman测通；最后才写小程序页面，复用封装的request.js，页面开发会快很多，因为你不需要边写页面边调整接口。
最后分享一个加分技巧：在报修详情页加一条时间轴。学生提交、管理员派单、维修工接单、完成维修、学生评价，每个节点都在时间轴上一目了然。这个功能不仅让系统看起来专业，也把order_log的价值显性化了。我在这套系统第二版里加上时间轴后，使用者反馈“终于知道维修进度卡在哪个环节了”，这一个改动带来的满意度提升比任何花哨功能都明显。如果时间允许，建议你也把这个细节加上去，它会让整套系统的完整度再上一个台阶。
