船舶维保管理系统我接触过不少类似的项目。这个标题里提到的 SpringBoot Vue MyBatis MySQL 组合算得上是当前中小型管理系统开发里最成熟、最不容易翻车的一套搭配了。船舶维保这个业务方向和普通的设备维保系统还有些不一样船上设备多、维保周期长、环境特殊系统做得好不好直接关系到船舶安全运营的合规性。我基于过往做过的同类型项目经验把整个系统的设计思路、数据库模型、核心功能实现、前后端联调细节和常见问题排查全部拆开来讲。1. 项目整体设计与技术选型为什么是SpringBoot Vue这套组合1.1 船舶维保管理的业务痛点在聊技术之前先要搞清楚这个系统解决的到底是什么问题。船舶维保不是简单的“到时间就换零件”它涉及非常复杂的业务链条船上线了维保计划要根据船舶运行时长、设备类型、上次维保时间和船级社的检验要求来动态生成到了维保节点要派工单给具体的轮机员或外协团队执行过程中要记录更换的备件、工时、检测数据结束后还要回填结果关联到下一轮维保周期的计算。这些环节如果没有系统支撑纯靠Excel和纸质单据很容易出现三个问题第一维保计划逾期了没人知道第二船舶在港时间有限备件没提前准备好导致维保窗口浪费第三船级社检验时需要历史维保记录纸质材料查找和归档非常痛苦。所以这套系统的核心价值就是三个字控节奏。1.2 前后端分离架构的取舍技术选型上SpringBoot Vue是目前这类管理系统的主流方案。SpringBoot负责提供RESTful APIVue负责页面交互两者通过JSON进行数据交换。为什么不用JSP模板引擎那一套老方案因为船舶维保系统不只是单机使用港口、船东、备件供应商、外协维修队都有查看和操作需求前后端分离之后后端API可以方便地被不同客户端复用维护时也不用改一套页面就重启一个服务。MyBatis的选择也很务实。船舶维保系统的查询条件非常动态化按船名查、按设备类型查、按维保状态查、按时间范围查各种组合非常自由。MyBatis的动态SQL可以让这些条件组合在一个Mapper里灵活拼装而不需要为每一种组合单独写一套查询接口。相比之下JPA在复杂动态查询场景下要么写Query注解要么 Specification 去拼接可读性和调优空间都不如MyBatis直接写SQL来得痛快。MySQL在这个项目里的定位也清晰数据量级在单表几万到几十万行完全够用运维成本低开发环境和生产环境行为一致。这套组合跑在2核4G的服务器上就能稳定支撑几十个并发用户对船舶公司这类内部管理系统来说已经非常宽裕了。2. 数据库设计维保业务的底层模型如何构建2.1 核心表结构与设计思路数据库设计是这类系统的地基我见过太多项目在表结构上欠了债后面写业务代码时处处别扭。船舶维保管理系统通常围绕五个核心表展开外加若干辅助表。船舶基本信息表ship是最基础的主数据字段包括船名、船籍港、IMO编号、建造年份、船舶类型、载重吨、主机型号、辅机型号等。这些字段看着简单但有个容易忽略的点主机型号和辅机型号应该单独建字典表因为维保计划的生成规则高度依赖这些设备型号。直接存字符串虽然省事但后续做“按主机型号查询所有相同设备的维保记录”这种跨船统计时就会很难受。维保计划表maintenance_plan是这个系统的灵魂。核心字段有船舶ID、设备ID、计划类型预防性维保、纠正性维保、状态监测维保、计划周期类型按运行小时、按日历时间、按航行里程、周期值、上次执行时间、下次到期时间、当前状态、维保标准说明。这里有个设计要点下次到期时间的计算逻辑不应该在代码里散落多处而应该集中在一个工具类中因为船舶维保的周期计算规则比较复杂。维保工单表maintenance_order是执行层的载体。字段包括计划ID、船舶ID、工单编号、派工对象、计划开始时间、要求完成时间、实际开始时间、实际完成时间、状态待派工、已派工、执行中、待验收、已完成、已取消、优先级、维保结论、工时数。工单编号推荐生成规则是WO 船名缩写 年月日 当日流水号这样即使不看数据库光看编号就能快速定位是哪条船哪个时间段的工单。备件表spare_part和维保工单表通过维保备件明细表maintenance_order_part关联。备件表的核心字段是备件名称、备件编码、适用设备型号、安全库存、当前库存、供应商、采购周期。安全库存这个字段在维保系统里非常重要它要结合备件的平均消耗速度和采购周期计算采购周期长的备件安全库存必须设置得高一些否则容易在船舶需要更换时缺货。2.2 状态流转模型设计状态字段在表里只是一个小数字但在业务中代表一套完整的流转规则。我习惯把状态流转做在前端下拉框的选项控制里同时后端接口也要做二次校验。维保工单的状态流转逻辑是待派工只能流转到已派工已派工只能流转到执行中执行中只能流转到待验收或已取消待验收只能流转到已完成。后端在更新状态时不能只接收一个状态字段就无条件更新必须做前置状态匹配防止前端被绕过或并发问题导致状态跳变。这里说一个实操细节如果你用MyBatis做状态更新建议在SQL的where条件里带上当前状态匹配比如update maintenance_order set status #{newStatus} where id #{id} and status #{currentStatus}。这样做的好处是天然具备乐观锁的性质如果当前状态已经变了更新影响行数是0事务回滚即可。这比先查一遍再判断再更新要省心得多。2.3 索引设计与查询性能规划索引设计是数据库这块必须重视的。我这里直接给一套经过实践验证的索引方案供参考表名索引字段索引类型设计理由maintenance_planship_id equipment_id联合索引按船舶查维保计划是最常规路径maintenance_plannext_due_date普通索引定时任务扫到期计划的核心字段maintenance_orderplan_id普通索引从计划到工单的反查maintenance_orderstatus due_date联合索引工单看板按状态和时间过滤maintenance_order_partorder_id普通索引工单详情查备件明细索引不是越多越好每多一个索引就多一份写入开销。上面这套索引基本覆盖了维保系统的全部高频查询路径后续如果出现慢查询优先考虑的是优化SQL写法而不是加索引。3. 后端核心功能实现SpringBoot MyBatis的关键代码细节3.1 工程分层与基础配置后端工程建议采用经典的四层结构Controller层负责请求入参校验和响应封装Service层负责业务逻辑和事务管理Mapper层负责数据持久化操作Domain层存放实体对象和DTO对象。出参统一用泛型响应体这里我直接提供一个简单版本public class ApiResponseT implements Serializable { private Integer code; private String message; private T data; public static T ApiResponseT success(T data) { ApiResponseT response new ApiResponse(); response.setCode(200); response.setMessage(操作成功); response.setData(data); return response; } public static T ApiResponseT error(Integer code, String message) { ApiResponseT response new ApiResponse(); response.setCode(code); response.setMessage(message); return response; } }统一响应体的好处在联调阶段就能体现出来前端拿到数据后不用解析多种返回结构只需要在axios拦截器里统一处理code不等于200的情况。3.2 维保计划的动态分页查询维保计划是系统的核心数据入口查询条件可能来自船舶筛选、设备类型筛选、时间范围筛选、状态筛选。这套条件的组合查询用MyBatis动态SQL来实现最合适。select idselectPlanPage resultTypecom.ship.domain.MaintenancePlan SELECT p.*, s.ship_name FROM maintenance_plan p INNER JOIN ship s ON p.ship_id s.id where if testquery.shipId ! null AND p.ship_id #{query.shipId} /if if testquery.equipmentType ! null and query.equipmentType ! AND p.equipment_type #{query.equipmentType} /if if testquery.status ! null AND p.status #{query.status} /if if testquery.startDate ! null AND p.next_due_date gt; #{query.startDate} /if if testquery.endDate ! null AND p.next_due_date lt; #{query.endDate} /if /where ORDER BY p.next_due_date ASC /select这个SQL有个细节值得注意排序用了next_due_date ASC也就是最早到期的排在前面。维保计划列表本质上是一个优先级列表越接近到期的计划越应该被优先处理这种排序方式让业务人员在打开页面时第一时间看到最紧急的事情。分页这里建议用PageHelper它拦截MyBatis的Executor自动生成count和limit语句用法非常简单PageHelper.startPage(pageNum, pageSize); ListMaintenancePlanDTO list maintenancePlanMapper.selectPlanPage(query); PageInfoMaintenancePlanDTO pageInfo new PageInfo(list);有一个坑必须提醒PageHelper的分页参数是线程绑定的也就是说在PageHelper.startPage之后执行的第二条SQL都会被加上分页条件。如果查询方法里在Mapper查询之前还执行了其他SQL分页就会错乱。正确的做法是startPage语句紧贴着Mapper查询方法中间不要插入任何数据库操作。3.3 维保工单生成与派发的事务处理工单生成这个接口是系统里最有代表性的一个事务场景。它要做的事情包括更新维保计划的状态和下次到期时间、创建维保工单记录、扣减备件库存、记录备件出库流水。四件事要么全成功要么全失败必须放在同一个事务里。Override Transactional(rollbackFor Exception.class) public Long generateOrder(OrderCreateDTO dto) { // 1. 校验维保计划当前状态 MaintenancePlan plan maintenancePlanMapper.selectByIdForUpdate(dto.getPlanId()); if (plan null || !Integer.valueOf(1).equals(plan.getStatus())) { throw new BizException(维保计划不存在或当前状态不允许生成工单); } // 2. 生成工单记录 MaintenanceOrder order new MaintenanceOrder(); order.setPlanId(plan.getId()); order.setShipId(plan.getShipId()); order.setOrderNo(generateOrderNo(plan.getShipId())); order.setStatus(0); // 待派工 order.setPlanTime(plan.getNextDueDate()); maintenanceOrderMapper.insert(order); // 3. 更新计划状态为待工单 plan.setStatus(2); maintenancePlanMapper.updateStatus(plan); // 4. 扣减备件库存 for (OrderPartDTO part : dto.getParts()) { int affected sparePartMapper.deductStock(part.getPartId(), part.getQuantity()); if (affected 0) { throw new BizException(备件库存不足: part.getPartName()); } maintenanceOrderPartMapper.insertOrderPart(order.getId(), part); } return order.getId(); }注意这里的selectByIdForUpdate在事务中使用了悲观锁锁定这条计划记录防止两个用户同时针对同一计划生成重复工单。在分布式程度不高、单库部署的内部管理系统里这种级别的控制已经足够可靠。另外一个细节是事务回滚的问题我们手动throw new BizException时要确保类上标注了Transactional(rollbackFor Exception.class)。默认情况下Spring事务只回滚RuntimeException和Error自定义BizException如果继承的是Exception不加rollbackFor就不会触发回滚这个坑很多新手会踩。3.4 维保到期的定时提醒任务维保系统必须要有提前提醒的能力不可能天天让人去看计划列表。常规做法是用Spring的Scheduled注解实现一个定时任务每天凌晨扫描未来30天内到期的维保计划生成提醒消息推送给相关责任人。关于扫描周期的计算这里分享一个经验船舶设备维保窗口不是固定的不同的设备类型有不同的提前提醒天数设定。主机滑油分析类的维保可能要提前45天提醒因为需要安排实验室送检简单的滤器更换提前7天提醒就够了。所以提醒系统不要硬编码一个提前天数建议在维保标准配置表里为不同设备类型设置独立的提前提醒天数。定时任务的实现还有一个容易忽略的问题集群部署时会重复执行。如果你只部署单实例直接加Scheduled没问题如果后面做了多实例部署建议用数据库分布式锁或引入任务调度框架。简单做法就是利用MySQL的行锁特性Scheduled(cron 0 0 2 * * ?) public void scanDuePlans() { String lockKey maintenance_plan_due_scan; boolean locked sysLockMapper.tryLock(lockKey); if (!locked) { return; } try { ListMaintenancePlan duePlans maintenancePlanMapper.selectDuePlans(); // 生成提醒消息... } finally { sysLockMapper.unlock(lockKey); } }这种基于数据库的分布式锁完全能覆盖多实例部署场景不需要额外引入Redis运维成本也更低。4. 前端Vue实现维保操作流程的交互设计4.1 前端工程结构与权限控制前端用的是Vue框架搭配Element UI组件库工程结构建议按模块拆分views目录。这个项目的核心页面包括仪表盘、船舶管理、维保计划、工单管理、备件管理、系统设置。权限控制这里多说一句。系统角色可以分为三类管理员管理船舶主数据、配置维保标准、调度员查看计划、派发工单、执行人员接单、回填维保结果。前端采用路由守卫加菜单动态渲染的方式控制页面可见性。后端每次请求还要再做一次接口权限校验不能只依赖前端的隐藏控制因为前端的控制本质上只是用户体验优化真正的安全边界在后端。路由守卫的核心逻辑很清晰router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (to.path ! /login !token) { next(/login); return; } if (token to.path /login) { next(/); return; } next(); });4.2 动态路由与菜单渲染这里有一个很好的实践经验不同角色的用户在登录后看到的菜单应该是不同的。做法是登录后从后端获取当前用户的菜单和权限列表遍历生成路由表并 addRoute 动态添加到路由实例中菜单渲染也根据同一份数据生成。菜单数据的格式和路由结构高度对应后端返回一份带层级关系的JSON是常规做法[ { path: /plan, name: 维保计划, icon: el-icon-date, children: [ { path: /plan/list, name: 计划列表 }, { path: /plan/calendar, name: 计划日历 } ] } ]这样做的核心价值是权限配置的灵活度极大提高——船东公司和船舶管理公司如果共用同一套系统不同公司分配不同菜单权限一套前端代码就全搞定了。4.3 维保工单操作页面的组件化实现维保工单详情页是这个系统里交互最复杂的页面。它包含的信息有船舶信息卡片、维保计划详情、备件消耗清单、执行记录时间线、验收意见填写区。我建议把信息卡片和时间线拆成独立的子组件页面上只需要做数据组合。备件清单选择是个典型的难点场景。用户在创建工单时需要选备件但备件库存是动态变化的不能把备件列表一次性全部加载到前端。我用的方案是备件选择器做成一个远程搜索组件输入备件名称关键字时请求后端接口后端用模糊查询返回前20条结果用户选择后再传入主表单。这样既保证了交互流畅性也避免了数据量过大导致页面卡顿。handleSparePartSearch(query, callback) { const params { keyword: query, pageNum: 1, pageSize: 20 }; sparePartApi.search(params).then(res { const results res.data.records.map(item ({ value: item.id, label: ${item.partName}剩余: ${item.stock} })); callback(results); }); }还有一个小细节在选择备件时要同步显示当前库存数量如果用户选择的维保用量已经超过库存前端要立刻给出红色警告。这能减少后端因库存不足导致的事务回滚次数虽然后端依然要校验但用户体验会好很多。4.4 与后端联调的状态管理风格Vue项目里的状态管理我推荐使用Pinia或Vuex但不必把所有数据都放进去。维保系统的情况是船舶、备件这类基础数据只在打开对应页面时加载跨页面保留意义不大但登录用户信息和全局权限数据必须放状态管理因为多个页面都要用它来判断操作按钮的显隐。几个页面间共享的数据比如选中的船舶ID、当前角色权限标识这些放store里是合理的。至于维保计划列表数据应该留在页面组件的data里通过keep-alive缓存维持状态即可。刻意把所有数据都塞进store反而会增加维护成本因为store里的数据一旦和页面状态不同步排错会很痛苦。5. 常见问题与排查技巧实录5.1 数据库连接池耗尽这类管理系统运营一段时间后大概率会遇到连接池耗尽的问题具体表现就是应用日志疯狂输出wait connection timeout或者前端接口请求全面超时。排查步骤很有套路第一步看MySQL侧的最大连接数配置show variables like max_connections第二步看应用侧的连接池配置SpringBoot默认的HikariCP最大连接数设置为多少第三步看慢查询日志show processlist就能看到大量Sleep状态的连接。出现连接池耗尽的根因多数情况下是某个接口的数据库操作耗时过长导致连接被长期占用。我遇到过一次原因是维保计划的列表查询没有加索引数据量到3万行后全表扫描越来越慢加上PageHelper分页的count查询也需要走一遍全表连接自然就被占死了。解决方式很直接给next_due_date和status加联合索引查询时间从800毫秒降到30毫秒连接池压力瞬间消失。5.2 MyBatis动态SQL的空条件判断陷阱在XML里写if teststatus ! null时有个细节经常导致线上bug。当前端传参status0时MyBatis的OGNL表达式里status ! null的判断是true的可以正常拼接条件。但如果某天把status字段改成了包装类型Integer前端传了一个字符串0MyBatis在比较时可能会出现类型转换异常。另一个更隐蔽的坑if testshipId ! null and shipId ! 这种写法对Long类型的shipId来说是没问题的但如果shipId是IntegershipId ! 的判断可能会出现OGNL解析异常。统一用法就是只判断! null对于字符串类型才加! 的判断。最靠谱的习惯是所有Query对象里的字段类型都使用包装类型不要用基本类型int、long。否则前端不传这个筛选条件时基本类型会默认给00又是有效值就会把“未传入”和“查询ID为0的数据”混淆掉这个坑排查起来非常耗时。5.3 时间字段的时区和格式化问题船舶维保系统涉及的时间字段特别多计划时间、执行时间、到期时间、完成时间。前后端联调时下面这些常见问题几乎都会遇到。SpringBoot默认返回的LocalDateTime格式是ISO标准字符串也就是2025-03-21T10:30:00中间带个T。前端直接展示会很难看。解决办法是在application.yml里配置全局格式化spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: Asia/Shanghai第二类问题是时区转换导致的时间偏移8小时。如果服务器时区设置的是UTCMySQL也是UTC数据库里存的14:00经过Jackson序列化传给前端时直接变成了06:00。排查思路很直接依次检查MySQL连接URL里的serverTimezone参数、Linux系统时区、JVM默认时区统一切到Asia/Shanghai就不会出这类问题。第三类问题是前端展示到期的精确性。维保计划如果需要精确到小时级别有些设备维保要求在航行小时数到达某个值前必须执行前端表单建议直接用datetime类型组件而后端存储用LocalDateTime不要用Date。如果只需要精确到天级别的提醒用LocalDate类型避免时间部分引起不必要的心智负担。5.4 前后端联调跨域问题开发环境下Vue默认跑在8080端口后端跑在8081端口跨域是必然会遇到的。解决方式有两种常用路线。第一种后端允许跨域写一个CorsFilter配置类Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { CorsConfiguration config new CorsConfiguration(); config.addAllowedOriginPattern(*); config.addAllowedHeader(*); config.addAllowedMethod(*); config.setAllowCredentials(true); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); } }第二种用Vue开发环境的代理在vue.config.js里配置module.exports { devServer: { proxy: { /api: { target: http://localhost:8081, changeOrigin: true, pathRewrite: { ^/api: } } } } };我个人推荐第二种方案因为它完全复刻了生产环境的部署模式——正式环境用Nginx反代把/api转到后端服务开发环境用Vue的proxy模拟同样的行为。这样可以避免一个问题如果后端开了allowCredentialstrue配合allowedOriginPattern()在某些浏览器版本、某些代理工具组合下会出问题而走代理方案浏览器看到的接口请求是同源的根本不会触发跨域逻辑省去很多排查时间。6. 个人实操中的拓展思考6.1 这套架构后续可以怎么演进这套SpringBootVueMyBatisMySQL的架构做好基础功能之后还有很大的扩展空间。如果我有时间在这个项目基础上做二期优先考虑的是下面几个方向。第一个方向是移动端适配。轮机员在机舱现场作业时带电脑并不现实手机端通过浏览器访问H5页面扫码查看工单详情、拍照上传维保现场照片、语音输入维保结论这些功能在船上场景下非常实用。Vue的组件库本身支持响应式布局做一套移动端适配版本不需要改后端接口只是重排前端页面。第二个方向是维保数据的统计分析。积累半年以上的维保数据后可以分析每条船的维保成本、平均故障间隔时间、备件消耗趋势、外协维修占比。这类数据对船东的预算决策很有价值。实现上可以在MySQL里做聚合查询再配合ECharts在前端展示图表。第三个方向是接入物联网设备数据。现在新建造的船舶基本都有机舱监测报警系统可以采集主机转速、滑油压力、排烟温度等实时运行数据。如果能够获取这些数据维保计划就不只是按固定周期触发了还可以基于设备实际运行状态做预测性维护。比如滑油压力持续偏低可能预示滤器堵塞系统自动生成一条临时维保工单。这一块的技术栈会复杂很多涉及消息中间件、时序数据库但在船舶维保这个行业方向里是最有增值空间的应用场景。6.2 给正在做同类系统的人几句实在话和船舶维保管理系统打交道的这段时间里我最深的一个体会是这类管理系统真正难的不是写代码而是把业务规则梳理清楚。同样的维保计划表结构如果期初没有和业务人员把“按小时触发”和“按日历触发”的混合逻辑对齐后期开发完再去改状态流转逻辑代价比重新建一张表还大。如果你是从零开始做这个项目我的建议是先花一周时间梳理业务规则和表单字段再用三天把数据库脚本全部定稿最后再进入代码开发。前期的业务调研做得越细致后期的开发和联调就越顺利。这点投入的回报率远比中途返工要高得多。 船舶维保管理系统我接触过不少类似的项目。这个标题里提到的 SpringBoot Vue MyBatis MySQL 组合算得上是当前中小型管理系统开发里最成熟、最不容易翻车的一套搭配了。船舶维保这个业务方向和普通的设备维保系统还有些不一样船上设备多、维保周期长、环境特殊系统做得好不好直接关系到船舶安全运营的合规性。我基于过往做过的同类型项目经验把整个系统的设计思路、数据库模型、核心功能实现、前后端联调细节和常见问题排查全部拆开来讲。1. 项目整体设计与技术选型为什么是SpringBoot Vue这套组合1.1 船舶维保管理的业务痛点在聊技术之前先要搞清楚这个系统解决的到底是什么问题。船舶维保不是简单的“到时间就换零件”它涉及非常复杂的业务链条船上线了维保计划要根据船舶运行时长、设备类型、上次维保时间和船级社的检验要求来动态生成到了维保节点要派工单给具体的轮机员或外协团队执行过程中要记录更换的备件、工时、检测数据结束后还要回填结果关联到下一轮维保周期的计算。这些环节如果没有系统支撑纯靠Excel和纸质单据很容易出现三个问题第一维保计划逾期了没人知道第二船舶在港时间有限备件没提前准备好导致维保窗口浪费第三船级社检验时需要历史维保记录纸质材料查找和归档非常痛苦。所以这套系统的核心价值就是三个字控节奏。1.2 前后端分离架构的取舍技术选型上SpringBoot Vue是目前这类管理系统的主流方案。SpringBoot负责提供RESTful APIVue负责页面交互两者通过JSON进行数据交换。为什么不用JSP模板引擎那一套老方案因为船舶维保系统不只是单机使用港口、船东、备件供应商、外协维修队都有查看和操作需求前后端分离之后后端API可以方便地被不同客户端复用维护时也不用改一套页面就重启一个服务。MyBatis的选择也很务实。船舶维保系统的查询条件非常动态化按船名查、按设备类型查、按维保状态查、按时间范围查各种组合非常自由。MyBatis的动态SQL可以让这些条件组合在一个Mapper里灵活拼装而不需要为每一种组合单独写一套查询接口。相比之下JPA在复杂动态查询场景下要么写Query注解要么 Specification 去拼接可读性和调优空间都不如MyBatis直接写SQL来得痛快。MySQL在这个项目里的定位也清晰数据量级在单表几万到几十万行完全够用运维成本低开发环境和生产环境行为一致。这套组合跑在2核4G的服务器上就能稳定支撑几十个并发用户对船舶公司这类内部管理系统来说已经非常宽裕了。2. 数据库设计维保业务的底层模型如何构建2.1 核心表结构与设计思路数据库设计是这类系统的地基我见过太多项目在表结构上欠了债后面写业务代码时处处别扭。船舶维保管理系统通常围绕五个核心表展开外加若干辅助表。船舶基本信息表ship是最基础的主数据字段包括船名、船籍港、IMO编号、建造年份、船舶类型、载重吨、主机型号、辅机型号等。这些字段看着简单但有个容易忽略的点主机型号和辅机型号应该单独建字典表因为维保计划的生成规则高度依赖这些设备型号。直接存字符串虽然省事但后续做“按主机型号查询所有相同设备的维保记录”这种跨船统计时就会很难受。维保计划表maintenance_plan是这个系统的灵魂。核心字段有船舶ID、设备ID、计划类型预防性维保、纠正性维保、状态监测维保、计划周期类型按运行小时、按日历时间、按航行里程、周期值、上次执行时间、下次到期时间、当前状态、维保标准说明。这里有个设计要点下次到期时间的计算逻辑不应该在代码里散落多处而应该集中在一个工具类中因为船舶维保的周期计算规则比较复杂。维保工单表maintenance_order是执行层的载体。字段包括计划ID、船舶ID、工单编号、派工对象、计划开始时间、要求完成时间、实际开始时间、实际完成时间、状态待派工、已派工、执行中、待验收、已完成、已取消、优先级、维保结论、工时数。工单编号推荐生成规则是WO 船名缩写 年月日 当日流水号这样即使不看数据库光看编号就能快速定位是哪条船哪个时间段的工单。备件表spare_part和维保工单表通过维保备件明细表maintenance_order_part关联。备件表的核心字段是备件名称、备件编码、适用设备型号、安全库存、当前库存、供应商、采购周期。安全库存这个字段在维保系统里非常重要它要结合备件的平均消耗速度和采购周期计算采购周期长的备件安全库存必须设置得高一些否则容易在船舶需要更换时缺货。2.2 状态流转模型设计状态字段在表里只是一个小数字但在业务中代表一套完整的流转规则。我习惯把状态流转做在前端下拉框的选项控制里同时后端接口也要做二次校验。维保工单的状态流转逻辑是待派工只能流转到已派工已派工只能流转到执行中执行中只能流转到待验收或已取消待验收只能流转到已完成。后端在更新状态时不能只接收一个状态字段就无条件更新必须做前置状态匹配防止前端被绕过或并发问题导致状态跳变。这里说一个实操细节如果你用MyBatis做状态更新建议在SQL的where条件里带上当前状态匹配比如update maintenance_order set status #{newStatus} where id #{id} and status #{currentStatus}。这样做的好处是天然具备乐观锁的性质如果当前状态已经变了更新影响行数是0事务回滚即可。这比先查一遍再判断再更新要省心得多。2.3 索引设计与查询性能规划索引设计是数据库这块必须重视的。我这里直接给一套经过实践验证的索引方案供参考表名索引字段索引类型设计理由maintenance_planship_id equipment_id联合索引按船舶查维保计划是最常规路径maintenance_plannext_due_date普通索引定时任务扫到期计划的核心字段maintenance_orderplan_id普通索引从计划到工单的反查maintenance_orderstatus due_date联合索引工单看板按状态和时间过滤maintenance_order_partorder_id普通索引工单详情查备件明细索引不是越多越好每多一个索引就多一份写入开销。上面这套索引基本覆盖了维保系统的全部高频查询路径后续如果出现慢查询优先考虑的是优化SQL写法而不是加索引。3. 后端核心功能实现SpringBoot MyBatis的关键代码细节3.1 工程分层与基础配置后端工程建议采用经典的四层结构Controller层负责请求入参校验和响应封装Service层负责业务逻辑和事务管理Mapper层负责数据持久化操作Domain层存放实体对象和DTO对象。出参统一用泛型响应体这里我直接提供一个简单版本public class ApiResponseT implements Serializable { private Integer code; private String message; private T data; public static T ApiResponseT success(T data) { ApiResponseT response new ApiResponse(); response.setCode(200); response.setMessage(操作成功); response.setData(data); return response; } public static T ApiResponseT error(Integer code, String message) { ApiResponseT response new ApiResponse(); response.setCode(code); response.setMessage(message); return response; } }统一响应体的好处在联调阶段就能体现出来前端拿到数据后不用解析多种返回结构只需要在axios拦截器里统一处理code不等于200的情况。3.2 维保计划的动态分页查询维保计划是系统的核心数据入口查询条件可能来自船舶筛选、设备类型筛选、时间范围筛选、状态筛选。这套条件的组合查询用MyBatis动态SQL来实现最合适。select idselectPlanPage resultTypecom.ship.domain.MaintenancePlan SELECT p.*, s.ship_name FROM maintenance_plan p INNER JOIN ship s ON p.ship_id s.id where if testquery.shipId ! null AND p.ship_id #{query.shipId} /if if testquery.equipmentType ! null and query.equipmentType ! AND p.equipment_type #{query.equipmentType} /if if testquery.status ! null AND p.status #{query.status} /if if testquery.startDate ! null AND p.next_due_date gt; #{query.startDate} /if if testquery.endDate ! null AND p.next_due_date lt; #{query.endDate} /if /where ORDER BY p.next_due_date ASC /select这个SQL有个细节值得注意排序用了next_due_date ASC也就是最早到期的排在前面。维保计划列表本质上是一个优先级列表越接近到期的计划越应该被优先处理这种排序方式让业务人员在打开页面时第一时间看到最紧急的事情。分页这里建议用PageHelper它拦截MyBatis的Executor自动生成count和limit语句用法非常简单PageHelper.startPage(pageNum, pageSize); ListMaintenancePlanDTO list maintenancePlanMapper.selectPlanPage(query); PageInfoMaintenancePlanDTO pageInfo new PageInfo(list);有一个坑必须提醒PageHelper的分页参数是线程绑定的也就是说在PageHelper.startPage之后执行的第二条SQL都会被加上分页条件。如果查询方法里在Mapper查询之前还执行了其他SQL分页就会错乱。正确的做法是startPage语句紧贴着Mapper查询方法中间不要插入任何数据库操作。3.3 维保工单生成与派发的事务处理工单生成这个接口是系统里最有代表性的一个事务场景。它要做的事情包括更新维保计划的状态和下次到期时间、创建维保工单记录、扣减备件库存、记录备件出库流水。四件事要么全成功要么全失败必须放在同一个事务里。Override Transactional(rollbackFor Exception.class) public Long generateOrder(OrderCreateDTO dto) { // 1. 校验维保计划当前状态 MaintenancePlan plan maintenancePlanMapper.selectByIdForUpdate(dto.getPlanId()); if (plan null || !Integer.valueOf(1).equals(plan.getStatus())) { throw new BizException(维保计划不存在或当前状态不允许生成工单); } // 2. 生成工单记录 MaintenanceOrder order new MaintenanceOrder(); order.setPlanId(plan.getId()); order.setShipId(plan.getShipId()); order.setOrderNo(generateOrderNo(plan.getShipId())); order.setStatus(0); // 待派工 order.setPlanTime(plan.getNextDueDate()); maintenanceOrderMapper.insert(order); // 3. 更新计划状态为待工单 plan.setStatus(2); maintenancePlanMapper.updateStatus(plan); // 4. 扣减备件库存 for (OrderPartDTO part : dto.getParts()) { int affected sparePartMapper.deductStock(part.getPartId(), part.getQuantity()); if (affected 0) { throw new BizException(备件库存不足: part.getPartName()); } maintenanceOrderPartMapper.insertOrderPart(order.getId(), part); } return order.getId(); }注意这里的selectByIdForUpdate在事务中使用了悲观锁锁定这条计划记录防止两个用户同时针对同一计划生成重复工单。在分布式程度不高、单库部署的内部管理系统里这种级别的控制已经足够可靠。另外一个细节是事务回滚的问题我们手动throw new BizException时要确保类上标注了Transactional(rollbackFor Exception.class)。默认情况下Spring事务只回滚RuntimeException和Error自定义BizException如果继承的是Exception不加rollbackFor就不会触发回滚这个坑很多新手会踩。3.4 维保到期的定时提醒任务维保系统必须要有提前提醒的能力不可能天天让人去看计划列表。常规做法是用Spring的Scheduled注解实现一个定时任务每天凌晨扫描未来30天内到期的维保计划生成提醒消息推送给相关责任人。关于扫描周期的计算这里分享一个经验船舶设备维保窗口不是固定的不同的设备类型有不同的提前提醒天数设定。主机滑油分析类的维保可能要提前45天提醒因为需要安排实验室送检简单的滤器更换提前7天提醒就够了。所以提醒系统不要硬编码一个提前天数建议在维保标准配置表里为不同设备类型设置独立的提前提醒天数。定时任务的实现还有一个容易忽略的问题集群部署时会重复执行。如果你只部署单实例直接加Scheduled没问题如果后面做了多实例部署建议用数据库分布式锁或引入任务调度框架。简单做法就是利用MySQL的行锁特性Scheduled(cron 0 0 2 * * ?) public void scanDuePlans() { String lockKey maintenance_plan_due_scan; boolean locked sysLockMapper.tryLock(lockKey); if (!locked) { return; } try { ListMaintenancePlan duePlans maintenancePlanMapper.selectDuePlans(); // 生成提醒消息... } finally { sysLockMapper.unlock(lockKey); } }这种基于数据库的分布式锁完全能覆盖多实例部署场景不需要额外引入Redis运维成本也更低。4. 前端Vue实现维保操作流程的交互设计4.1 前端工程结构与权限控制前端用的是Vue框架搭配Element UI组件库工程结构建议按模块拆分views目录。这个项目的核心页面包括仪表盘、船舶管理、维保计划、工单管理、备件管理、系统设置。权限控制这里多说一句。系统角色可以分为三类管理员管理船舶主数据、配置维保标准、调度员查看计划、派发工单、执行人员接单、回填维保结果。前端采用路由守卫加菜单动态渲染的方式控制页面可见性。后端每次请求还要再做一次接口权限校验不能只依赖前端的隐藏控制因为前端的控制本质上只是用户体验优化真正的安全边界在后端。路由守卫的核心逻辑很清晰router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (to.path ! /login !token) { next(/login); return; } if (token to.path /login) { next(/); return; } next(); });4.2 动态路由与菜单渲染这里有一个很好的实践经验不同角色的用户在登录后看到的菜单应该是不同的。做法是登录后从后端获取当前用户的菜单和权限列表遍历生成路由表并 addRoute 动态添加到路由实例中菜单渲染也根据同一份数据生成。菜单数据的格式和路由结构高度对应后端返回一份带层级关系的JSON是常规做法[ { path: /plan, name: 维保计划, icon: el-icon-date, children: [ { path: /plan/list, name: 计划列表 }, { path: /plan/calendar, name: 计划日历 } ] } ]这样做的核心价值是权限配置的灵活度极大提高——船东公司和船舶管理公司如果共用同一套系统不同公司分配不同菜单权限一套前端代码就全搞定了。4.3 维保工单操作页面的组件化实现维保工单详情页是这个系统里交互最复杂的页面。它包含的信息有船舶信息卡片、维保计划详情、备件消耗清单、执行记录时间线、验收意见填写区。我建议把信息卡片和时间线拆成独立的子组件页面上只需要做数据组合。备件清单选择是个典型的难点场景。用户在创建工单时需要选备件但备件库存是动态变化的不能把备件列表一次性全部加载到前端。我用的方案是备件选择器做成一个远程搜索组件输入备件名称关键字时请求后端接口后端用模糊查询返回前20条结果用户选择后再传入主表单。这样既保证了交互流畅性也避免了数据量过大导致页面卡顿。handleSparePartSearch(query, callback) { const params { keyword: query, pageNum: 1, pageSize: 20 }; sparePartApi.search(params).then(res { const results res.data.records.map(item ({ value: item.id, label: ${item.partName}剩余: ${item.stock} })); callback(results); }); }还有一个小细节在选择备件时要同步显示当前库存数量如果用户选择的维保用量已经超过库存前端要立刻给出红色警告。这能减少后端因库存不足导致的事务回滚次数虽然后端依然要校验但用户体验会好很多。4.4 与后端联调的状态管理风格Vue项目里的状态管理我推荐使用Pinia或Vuex但不必把所有数据都放进去。维保系统的情况是船舶、备件这类基础数据只在打开对应页面时加载跨页面保留意义不大但登录用户信息和全局权限数据必须放状态管理因为多个页面都要用它来判断操作按钮的显隐。几个页面间共享的数据比如选中的船舶ID、当前角色权限标识这些放store里是合理的。至于维保计划列表数据应该留在页面组件的data里通过keep-alive缓存维持状态即可。刻意把所有数据都塞进store反而会增加维护成本因为store里的数据一旦和页面状态不同步排错会很痛苦。5. 常见问题与排查技巧实录5.1 数据库连接池耗尽这类管理系统运营一段时间后大概率会遇到连接池耗尽的问题具体表现就是应用日志疯狂输出wait connection timeout或者前端接口请求全面超时。排查步骤很有套路第一步看MySQL侧的最大连接数配置show variables like max_connections第二步看应用侧的连接池配置SpringBoot默认的HikariCP最大连接数设置为多少第三步看慢查询日志show processlist就能看到大量Sleep状态的连接。出现连接池耗尽的根因多数情况下是某个接口的数据库操作耗时过长导致连接被长期占用。我遇到过一次原因是维保计划的列表查询没有加索引数据量到3万行后全表扫描越来越慢加上PageHelper分页的count查询也需要走一遍全表连接自然就被占死了。解决方式很直接给next_due_date和status加联合索引查询时间从800毫秒降到30毫秒连接池压力瞬间消失。5.2 MyBatis动态SQL的空条件判断陷阱在XML里写if teststatus ! null时有个细节经常导致线上bug。当前端传参status0时MyBatis的OGNL表达式里status ! null的判断是true的可以正常拼接条件。但如果某天把status字段改成了包装类型Integer前端传了一个字符串0MyBatis在比较时可能会出现类型转换异常。另一个更隐蔽的坑if testshipId ! null and shipId ! 这种写法对Long类型的shipId来说是没问题的但如果shipId是IntegershipId ! 的判断可能会出现OGNL解析异常。统一用法就是只判断! null对于字符串类型才加! 的判断。最靠谱的习惯是所有Query对象里的字段类型都使用包装类型不要用基本类型int、long。否则前端不传这个筛选条件时基本类型会默认给00又是有效值就会把“未传入”和“查询ID为0的数据”混淆掉这个坑排查起来非常耗时。5.3 时间字段的时区和格式化问题船舶维保系统涉及的时间字段特别多计划时间、执行时间、到期时间、完成时间。前后端联调时下面这些常见问题几乎都会遇到。SpringBoot默认返回的LocalDateTime格式是ISO标准字符串也就是2025-03-21T10:30:00中间带个T。前端直接展示会很难看。解决办法是在application.yml里配置全局格式化spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: Asia/Shanghai第二类问题是时区转换导致的时间偏移8小时。如果服务器时区设置的是UTCMySQL也是UTC数据库里存的14:00经过Jackson序列化传给前端时直接变成了06:00。排查思路很直接依次检查MySQL连接URL里的serverTimezone参数、Linux系统时区、JVM默认时区统一切到Asia/Shanghai就不会出这类问题。第三类问题是前端展示到期的精确性。维保计划如果需要精确到小时级别有些设备维保要求在航行小时数到达某个值前必须执行前端表单建议直接用datetime类型组件而后端存储用LocalDateTime不要用Date。如果只需要精确到天级别的提醒用LocalDate类型避免时间部分引起不必要的心智负担。5.4 前后端联调跨域问题开发环境下Vue默认跑在8080端口后端跑在8081端口跨域是必然会遇到的。解决方式有两种常用路线。第一种后端允许跨域写一个CorsFilter配置类Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { CorsConfiguration config new CorsConfiguration(); config.addAllowedOriginPattern(*); config.addAllowedHeader(*); config.addAllowedMethod(*); config.setAllowCredentials(true); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); return new CorsFilter(source); } }第二种用Vue开发环境的代理在vue.config.js里配置module.exports { devServer: { proxy: { /api: { target: http://localhost:8081, changeOrigin: true, pathRewrite: { ^/api: } } } } };我个人推荐第二种方案因为它完全复刻了生产环境的部署模式——正式环境用Nginx反代把/api转到后端服务开发环境用Vue的proxy模拟同样的行为。这样可以避免一个问题如果后端开了allowCredentialstrue配合allowedOriginPattern()在某些浏览器版本、某些代理工具组合下会出问题而走代理方案浏览器看到的接口请求是同源的根本不会触发跨域逻辑省去很多排查时间。6. 个人实操中的拓展思考6.1 这套架构后续可以怎么演进这套SpringBootVueMyBatisMySQL的架构做好基础功能之后还有很大的扩展空间。如果我有时间在这个项目基础上做二期优先考虑的是下面几个方向。第一个方向是移动端适配。轮机员在机舱现场作业时带电脑并不现实手机端通过浏览器访问H5页面扫码查看工单详情、拍照上传维保现场照片、语音输入维保结论这些功能在船上场景下非常实用。Vue的组件库本身支持响应式布局做一套移动端适配版本不需要改后端接口只是重排前端页面。第二个方向是维保数据的统计分析。积累半年以上的维保数据后可以分析每条船的维保成本、平均故障间隔时间、备件消耗趋势、外协维修占比。这类数据对船东的预算决策很有价值。实现上可以在MySQL里做聚合查询再配合ECharts在前端展示图表。第三个方向是接入物联网设备数据。现在新建造的船舶基本都有机舱监测报警系统可以采集主机转速、滑油压力、排烟温度等实时运行数据。如果能够获取这些数据维保计划就不只是按固定周期触发了还可以基于设备实际运行状态做预测性维护。比如滑油压力持续偏低可能预示滤器堵塞系统自动生成一条临时维保工单。这一块的技术栈会复杂很多涉及消息中间件、时序数据库但在船舶维保这个行业方向里是最有增值空间的应用场景。6.2 给正在做同类系统的人几句实在话和船舶维保管理系统打交道的这段时间里我最深的一个体会是这类管理系统真正难的不是写代码而是把业务规则梳理清楚。同样的维保计划表结构如果期初没有和业务人员把“按小时触发”和“按日历触发”的混合逻辑对齐后期开发完再去改状态流转逻辑代价比重新建一张表还大。如果你是从零开始做这个项目我的建议是先花一周时间梳理业务规则和表单字段再用三天把数据库脚本全部定稿最后再进入代码开发。前期的业务调研做得越细致后期的开发和联调就越顺利。这点投入的回报率远比中途返工要高得多。