公司里那台用了五年的打印机又卡纸了行政群里消息发了一上午维修师傅下午才看到结果到现场一查卡的不是纸是订书钉。这种场景我相信搞过设备管理的人都经历过设备故障不可怕可怕的是故障信息停留在人传人环节——报修靠喊、进度靠问、统计靠Excel。正因如此很多人开始做基于JavaSpringBoot的设备报修系统把报修、派单、维修、验收整条链路搬到线上让每一台设备的健康状况、每一条工单的流转节点都变得可查询、可追踪、可复盘。这篇文章我会从业务建模、技术选型、数据库设计、核心流程实现、调试避坑、部署交付六个维度完整拆解这套设备报修管理系统的落地过程。适合正在做类似报修管理、工单管理项目的开发者参考也适合刚学完SpringBoot想找一个完整项目练手的同学。不夸张地说这套系统麻雀虽小但状态机、权限控制、并发更新、文件上传这些经典问题它全都碰到了。1. 报修系统的本质先梳理流程再谈代码1.1 没有系统的时候问题到底出在哪报修这件事本质上是一个多人协作的信息流转问题。一台打印机坏了需要经过使用者发现问题→找维修渠道→维修人员上门→鉴定故障→更换备件→确认修好→记录存档这么多个环节。在完全没有信息系统的时候每一个环节都可能断链故障描述在微信里说得不清不楚到了现场才发现需要带专用工具维修师傅今天休息报修信息就躺在某个人的私聊窗口里没人管等修好了也没有人记录这次用了什么零件、花了多少钱下个月同类故障再来一遍还是查不到历史。我做这套系统之前专门花了两天去观察这类问题。结果发现一个很有意思的现象报修链路中最耗时的并不是维修本身而是找人和确认状态这两件事。谁负责派单维修员现在手上有多少单子某个故障是第几次出现这些信息全部散落在不同人的记忆和聊天记录里。系统的价值就在这里它把散落的、口头的、易丢失的信息变成结构化的、可检索的、自动流转的数据。所以如果你准备开发一个设备报修平台我建议第一步不是打开IDEA新建项目而是坐下来把下面几个问题写清楚系统里有哪几类角色每类角色有哪些操作一条报修工单从头到尾会经历哪些状态谁有权利把状态从A改到B这套东西理清楚了技术方案的价值才能体现出来。1.2 角色权限和状态机开发前必须定死的两件事这套系统的角色划分我最终定成了三类对应的权限边界也很清晰角色核心操作数据范围普通用户提交报修、查看进度、验收、评价本人数据维修员接单、填写维修记录、提交完工分配给自己的工单管理员设备管理、用户管理、审核派单、统计全量数据权限模型不用做得太重一张表里放role字段配合一个拦截器做URL级别权限判断就够了比Spring Security的完整模型简单很多但演示效果并不差。如果想把权限做得更好看可以加一张角色权限中间表实现RBAC不过对报修系统这个体量来说简单方案往往更好维护。状态机是整套系统的主心骨我定义成了九个状态枚举值存储数字含义触发角色PENDING_AUDIT0待审核用户提交ASSIGNED1已指派管理员审核派单ACCEPTED2已接单维修员接单PROCESSING3维修中维修员处理COMPLETED4待验收维修员提交完工CONFIRMED5已验收用户确认CLOSED6已关闭系统自动/管理员归档REJECTED7已驳回管理员审核不通过CANCELED8已取消用户取消这里想提醒一句状态机一定不要在开发中边写边改。哪怕想到后面状态不对也要先把完整状态图定稿再动代码。因为状态一改涉及的不只是数据库一个字段而是前端按钮显示逻辑、后端判断逻辑、统计报表口径三个方面同时改。我在这个项目里就把已接单和维修中合并过结果前端要改四处、后端要改六处数据库里还有几条老数据要写脚本处理血泪教训。2. 技术选型为什么SpringBootMyBatis-Plus最适合这类项目2.1 对比SSH/SSMSpringBoot赢在哪SpringBoot真正解放生产力的地方不在语法也不在性能而在约定优于配置。以前用SSH开发光是spring配置文件、struts配置、hibernate映射就要写一大堆XML稍不留神一个Bean没扫到就是半个小时的排错时间。SpringBoot用自动装配和内嵌容器解决了这个问题Maven依赖引进去加上SpringBootApplication注解一个Java进程就能跑起来调试。具体到报修系统我实际用到的SpringBoot特性主要有这几个spring-boot-starter-web内嵌TomcatREST接口和页面渲染都能做spring-boot-starter-validation参数校验比如报修申请里设备ID不能为空、故障描述长度限制通过注解搞定spring-boot-starter-aop配一个切面做操作日志记录谁在什么时间改了什么状态spring-boot-configuration-processor配置文件自动提示少翻官方文档。ORM层面用MyBatis-Plus而不是原生MyBatis最大的原因是通用Mapper省掉大量样板代码。报修系统里按条件分页查询工单这种操作太频繁了用MyBatis-Plus的LambdaQueryWrapper写一套代码通吃所有查询组合而且支持链式调用可读性好很多。如果用的是原生MyBatis每次组合查询基本都要手动写一段动态SQL代码量翻倍不说还容易在XML里写错if和where条件。2.2 前后端方案、JWT鉴权的取舍前后端分离还是服务端渲染这个选择没有绝对答案。为了控制复杂度我选了SpringBoot Thymeleaf Layui jQuery的组合。这套方案的好处是后端直接返回ModelAndView不需要额外部署前端项目适合单人开发或者两三人小组快速出活儿。如果你更习惯前后端分离那么SpringBoot只出REST接口、前端用Vue或React也行但一定记得提前约定统一的接口返回格式。登录鉴权我用的是JWT。为什么不用Session因为这个项目后期要扩展小程序端的报修入口而Session在跨域共享和移动端场景下需要额外配置JWT是无状态的token发到前端后端只管验签。实现也不复杂登录成功用JJWT生成token里面放userId和role前端存到localStorage每次请求在Header中携带Authorization后端用一个HandlerInterceptor拦截校验。这里有一个很容易被忽视的点拦截器放行规则一定要仔细配。登录接口、静态资源、错误页面需要放行报修和管理相关的接口全部拦截。如果放行规则配错要么所有人都能访问管理接口要么登录后也访问不了资源Debug时非常折磨人。对比项Session方案JWT方案跨域支持需要额外配置原生友好服务器状态有状态重启失效无状态水平扩展方便实现复杂度较低中等需要处理token过期适合场景单机演示多端、前后端分离3. 数据库建模工单表的设计比想象中更考验业务理解3.1 五张核心表与关键字段核心表我一共设计了五张用户表user、设备表device、设备分类表device_category、报修工单表repair_order、维修记录表repair_record外加一张评价表evaluation。设备分类表是可选的当设备种类只有几十种时直接在device表里放category_name字段也不影响使用但如果设备数量上千分类表和设备表关联查询、统计报表都会好做很多建议拆。工单表是最核心的表字段设计我比较谨慎。除了id、user_id、device_id、status、priority、create_time、update_time这些常规字段外有几个字段值得重点说order_no工单编号用时间戳加随机数生成方便人工处理和后续统计device_name和device_location设备名称和位置这两个字段是快照创建工单时从设备表冗余复制过来避免设备信息后续变化导致历史工单查询错乱assignee_id维修员的用户IDfinish_time实际完工时间用于计算维修时长、统计维修效率cancel_flag作废标记避免直接物理删除造成的数据断层。工单表和user表、device表的关联关系不复杂就是普通的多对一。维修记录表repair_record是对工单的一对多一个工单可以有多条维修记录维修员每次操作都追加一条记录操作人、操作动作、维修说明、时间。这样既保留了完整的过程留痕也为维修明细页面提供了数据来源。3.2 快照冗余、时间字段和状态枚举再说说快照这个设计思路。表面上看工单表里关联一个device_id就完事了但真实业务里设备信息是会变的这台投影仪可能从三楼会议室搬到四楼培训室也可能因为维修换新而重新命名。如果工单只存device_id等你想查上个月这台设备报修时在哪个位置答案就缺了因为设备表里存的是当前最新位置。把设备名称、位置在创建工单时冗余到工单表里历史数据就能永久定格在业务发生的那一刻。状态枚举前面说过要用int存数字具体到Java代码可以这样写public enum RepairStatus { PENDING_AUDIT(0, 待审核), ASSIGNED(1, 已指派), ACCEPTED(2, 已接单), PROCESSING(3, 维修中), COMPLETED(4, 待验收), CONFIRMED(5, 已验收), CLOSED(6, 已关闭), REJECTED(7, 已驳回), CANCELED(8, 已取消); private final int value; private final String desc; RepairStatus(int value, String desc) { this.value value; this.desc desc; } public int getValue() { return value; } public String getDesc() { return desc; } }这样写的好处很明显数据库里只存0到8这几个数字不会出现待审核和待审这种脏数据Java代码里所有状态判断都走枚举IDE自动补全大大降低手写错误的概率。配合MyBatis-Plus的typeHandler或者直接用getValue()做转换前端展示再映射成中文描述非常顺。时间字段的统一也很重要建议整个项目只使用一种日期类型。我用的是LocalDateTime配合MyBatis-Plus的自动填充注解TableField(fill FieldFill.INSERT)让create_time自动写入update_time用FieldFill.INSERT_UPDATE自动更新。这样业务代码里完全不用手写setCreateTime减少遗漏。4. 工单全流程实现从提交报修到自动归档4.1 提交报修与审核派单用户提交报修时前端是一个表单字段包括选择设备、填写故障描述、上传现场图片。后端接口收到请求后按顺序做四件事第一参数校验。用Validated注解校验必填字段设备ID必须存在并且状态正常故障描述去掉空白字符后长度不能小于5个字符。这个长度限制是为了避免用户随手填一条坏了就提交否则维修员到现场还得打电话问具体情况。第二生成工单号。格式采用yyyyMMddHHmmss加三位随机数或流水号比如20240521153025_102这个编号在演示和后续客服查询时都比自增ID更友好。第三落库并设置状态为待审核同时把设备表里的设备状态改成维修中。第四给管理员发一条站内通知。中小型项目不需要引入消息队列直接向消息表插入一条记录就够管理员首页通过刷新或轮询展示未读消息。审核派单是在管理员端完成的。管理员打开待审核工单列表可以看到报修人、设备位置、故障描述和图片审核通过后指定一个维修员。这里要强调一个操作细节派单成功后要给维修员发送通知同时把工单状态从待审核改成已指派这两个操作必须放在同一个事务里任何一个失败都要整体回滚否则会出现工单状态没变但维修员已经收到消息的尴尬情况。4.2 并发防重的SQL写法派单和接单是整个系统里并发风险最高的两个操作。管理端有多个管理员时可能同时审核同一张工单维修端有多个维修员时可能几乎同时点击同一张工单的接单按钮。最朴素的解决方式是在Java代码里先查询工单当前状态判断是否仍然处于待审核再执行更新。但这样会有一个明显的并发窗口——查询和更新不是原子操作。两个请求同时查到待审核都通过了判断然后相继更新最终结果一定是后一个操作覆盖前一个先到的操作者以为是自己派单成功其实被覆盖了。正确的做法是让UPDATE语句自带条件也就是乐观锁思想的一种实现int update repairOrderMapper.update(null, new LambdaUpdateWrapperRepairOrder() .eq(RepairOrder::getId, orderId) .eq(RepairOrder::getStatus, RepairStatus.PENDING_AUDIT.getValue()) .set(RepairOrder::getStatus, RepairStatus.ASSIGNED.getValue()) .set(RepairOrder::getAssigneeId, repairerId)); if (update 0) { throw new BusinessException(该工单已被处理请刷新后重试); }这条语句的意思是只有当工单当前状态是待审核时才允许它被更新为已指派。如果影响行数为0说明状态已经被别人改掉了直接抛异常提示用户刷新。MySQL的InnoDB在UPDATE时会对匹配行加锁所以这个方案在并发下是安全的。接单、完工验收同理所有状态流转的更新操作都建议采用这种写法比引入version字段的乐观锁更贴合业务。4.3 维修记录、完工验收与自动归档维修员处理工单的过程不是一蹴而就的。可能先去现场看了发现缺少备件等备件到货后再上门修一次。每一次操作都应该在维修记录表里留一条记录内容包括操作类型检查、维修、更换配件、操作说明、操作人、操作时间。完工验收的流程是这样的维修员把状态从维修中改为待验收同时填写维修结论和实际完工时间用户在自己的工单详情页看到待验收状态可以选择确认完成也可以选择驳回并填写原因工单会回到维修中维修员需要重新处理。这一步是业务闭环里最关键的一环它把维修员自我感觉修好了和用户实际验证通过这两个概念明确区分开。如果用户一直不点验收怎么办我加了一个自动归档机制用Spring的Scheduled注解写一个定时任务每小时扫描一次待验收状态且finish_time超过48小时的工单自动将状态改为已关闭。这个需求在很多管理系统里都真实存在面试和答辩时提出来会很有亮点。5. 调试记录这套系统最容易翻车的四个地方5.1 事务失效同一个类里方法自调用第一个坑出现在派单并发送通知这个场景。我在工单Service里写了两个方法assignOrder负责更新工单状态sendNotify负责插入站内通知。为了让这两个操作原子化我给sendNotify方法加了Transactional注解然后在assignOrder方法里直接this.sendNotify()调用。结果测试时故意让sendNotify里抛异常update的工单状态居然没有回滚。排查之后发现原因很典型Spring的事务是通过AOP代理实现的this调用的内部方法会绕过代理对象Transactional注解完全没有生效。解决方式有两种一是把sendNotify方法拆到另一个Service类里让assignOrder通过注入的NotifyService调用二是用((RepairOrderService) AopContext.currentProxy()).sendNotify()拿到代理对象再调。个人建议采用第一种代码更清晰。这类问题在调试时很难一眼发现因为单线程、无并发、数据库不提示报错的情况下事务是否回滚只会在特定异常路径下暴露。所以我在所有涉及多步写操作的服务方法上都做了测试人为在第二步抛异常看第一步是否回滚。5.2 接单并发两个维修员抢同一张工单这个坑是压力测试时发现的。用Postman的Collection Runner同时发10个请求模拟10个维修员抢一张工单结果多张工单的assignee_id被后提交的请求覆盖甚至出现了状态从已指派被改回待审核的情况。根本原因就是我前面说的先查询再更新没有原子性。用SQL条件更新解决后我又给接单增加了二次校验维修员在工单列表页看到的status字段作为隐藏条件提交接单请求时把这个条件带回来后端再做一次匹配从接口层和数据库层双重夹击。这样处理后用同样的10并发测试结果只有第一个请求成功其余请求都返回该工单已被处理的提示逻辑正常。5.3 时间字段数据库和页面差了8小时这个问题的出现场景很典型本地开发一切正常部署到Linux服务器后页面上显示的报修时间比实际时间慢了8小时。排查过程不复杂。先看数据库里存的create_time是不是正确执行select后发现数据本身少了8小时说明问题出在写入环节再看应用程序日志发现本地和服务器日志时间相差也是8小时基本可以确定是MySQL连接时区与服务器系统时区不一致导致的。解决方案是统一三处配置MySQL连接串加serverTimezoneAsia/ShanghaiSpringBoot的spring.jackson.time-zoneGMT8代码层统一用LocalDateTime。改完之后再用select now()和工单的create_time对比测试数据恢复正常。这类时区问题最麻烦的地方在于不会报错只有仔细对比时间字段才会发现。所以我建议所有项目在开发初期就统一时间标准不要等部署阶段才来处理。5.4 文件上传本地能访问服务器上404报修图片上传功能在本地跑得没问题图片保存到项目相对路径下的upload目录浏览器访问也正常。部署到服务器后用jar包启动上传图片同样的操作页面上的图片全部404。原因其实不复杂相对路径依赖的是运行目录jar包启动时工作目录和本地IDE启动时完全不同图片并没有写到你想的那个文件夹里其次即便图片写到了服务器磁盘SpringBoot默认也不会把项目内部目录映射成静态资源URL。解决办法是配置一个绝对路径的上传目录然后用WebMvcConfigurer把该目录映射为/upload/**资源路径代码大概是这样的Configuration public class WebConfig implements WebMvcConfigurer { Value(${file.upload-dir}) private String uploadDir; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/upload/**) .addResourceHandler(file: uploadDir /); } }同时上传文件时要先创建目录判断文件后缀白名单限制文件大小。这些细节在调试文档里都应该写明避免部署的人二次踩坑。6. 交付不是代码能跑打包、调试文档与演示讲解6.1 打包部署清单SpringBoot项目打包部署本身不复杂但有几个环节容易出问题。先检查一遍配置文件数据库连接串是否使用外置配置、上传目录是否采用绝对路径、日志文件路径是否可写。然后执行mvn clean package如果项目里有单元测试建议在package时用mvn package -DskipTests跳过避免本地环境没有测试数据库导致打包失败。打包成功后先在本机用java -jar验证一遍再传到服务器。服务器上建议使用systemd或者脚本管理进程至少要做到日志落盘、启动失败能看到错误栈。如果有Nginx反向代理注意把上传目录和前端静态资源都代理到对应端口上传的图片需要能被外部访问。数据库方面初始化脚本里除了建表语句还应该包含测试数据。测试数据的价值在演示时体现得最明显——干净而全面的演示数据能让评审或者甲方一眼看懂系统全貌。6.2 调试文档到底怎么写才不废调试文档这个东西不少人是应付了事的写个下载运行即可就交差。但我个人认为调试文档是项目交付物里最能体现负责程度的部分它应该能让一个没参与项目的人按步骤把系统跑起来并在遇到问题时能自己排查。我的调试文档分三块第一块环境准备清单。JDK精确到1.8或11MySQL精确到5.7或8.0Maven版本、IDEA版本都写清楚。很多人在环境上卡住往往就是版本不一致导致的。第二块部署运行步骤。从解压源码、导入数据库、修改配置文件、启动主类到浏览器访问每一步都配截图。图片比文字直观得多能省去大量沟通成本。第三块常见问题排查。例如启动报端口被占用怎么处理数据库连接失败怎么检查上传图片404怎么排查时间少了8小时怎么解决。这四类问题在这套系统里几乎必踩提前写好能帮使用者省下大把时间。6.3 演示讲解的核心主线如果是答辩或者向客户演示最怕的就是讲解人从头到尾把功能菜单念一遍这是用户管理、这是设备管理、这是报表。听众完全抓不住重点也体现不出系统设计的好坏。我喜欢用一条业务主线串起整个演示从普通用户登录开始提交一条报修申请切换到管理员视角审核这条申请并指派维修员再切换到维修员视角接单、填写维修记录、提交完工最后切回普通用户视角确认验收并评价。整个过程中顺带把JWT鉴权、状态机流转、并发防重、自动归档这些技术点讲一遍。这样讲的好处在于听众看到的是一个能解决问题的设备维修系统而不是一堆功能点的堆砌。这也是我在多次演示之后总结出来的经验——演示的叙事线应该跟着业务走而不是跟着菜单走。最后说点个人体会。做完这套系统之后我最大的感受不是又多会了一个框架而是明白了业务流程对技术设计的反向约束力有多强。状态机先于代码SQL条件更新防止并发时间字段全项目统一这些经验都不是从框架文档里学到的而是被实际调试逼出来的。设备报修平台只是一个非常典型的增删改查项目但正因为业务闭环完整它几乎把一轮后端开发会遇到的经典问题都演了一遍。如果你正在开发类似的工单、服务申请或者流程审批类系统我希望这篇文章能帮你提前避开那些我踩过的坑把精力省下来多打磨真正能体现设计能力的功能点。