做管理系统这些年，我接触过仓储、设备、物业好几个行业，船舶维保是其中最考验人的一个。原因很简单：船是移动资产，一条船几个月在海上漂，维保工作必须按计划刚性执行，可传统纸质记录和散落的Excel表格又实在无法追溯——上次主机保养是哪天做的、下次滑油更换还剩多少运行小时，全靠老师傅脑子记，风险不小。去年帮某船务公司梳理内部系统时，我落地了一套船舶维保管理系统，技术栈就是标题里写的 Java SpringBoot + Vue3 + MyBatis，数据库用 MySQL，前后端分离。系统规模不大，但把船舶档案、维保计划、工单流转、备件库存、统计报表这些核心业务覆盖全了。这几天我把源码整理出来分享给同行，顺手把设计和实现过程写成这篇文章。想了解真实业务系统怎么落地的后端朋友、想看看 Vue3 在项目中实际怎么用的前端同学，或是正在做船舶信息化选型的人，都可以参考。1. 项目整体设计与选型思路1.1 场景痛点与系统定位船舶维保这个场景，和普通企业设备管理有一个很大的不同：数据产生地点和使用地点经常分离。机务主管在岸基办公室制定计划，轮机员在船上执行工单，船长要看整体维保进度，备件管理员则关心库存够不够。每个角色关心的是同一批数据的不同侧面，这就要求系统从一开始就要把“流程”和“数据一致性”放在首位，而不是简单做个增删改查。传统管理方式的核心痛点有几个。第一，维保计划靠人工盯，什么设备该保养了、什么时候到期，稍有疏忽就会出现漏保养，影响船舶安全。第二，工单执行结果记录在纸上，回到岸基再录入电脑，信息滞后还容易丢失。第三，备件领用和库存对不上，经常出现"账上有、库里没"的情况，紧急采购又赶不上船期。第四，管理层想看的统计报表，全靠人工汇总，工作量巨大。这套系统的定位，就是针对这些痛点做一套轻量级解决方案。不追求大而全，重点把计划、执行、库存三个环节打通：计划自动生成工单，工单执行关联备件领用，备件消耗自动扣库存，报表从这些数据里实时聚合出来。这样一个闭环下来，机务主管打开工作台就能看到各船维保完成情况，轮机员在平板上就能接收工单、填写结果，备件管理员实时掌握库存变化，管理层要数据随时能看。1.2 为什么是前后端分离架构选前后端分离，不是跟风，完全是这个项目的实际需要。船舶行业的用户分散在岸基、船端和港口，未来很可能要做小程序或者对接船岸通讯系统，前后端分离之后，后端只要提供统一的 API，任何终端都可以接入。尤其是船端网络不稳定，将来做离线模式或者数据同步的时候，后端接口独立于前端页面，改起来省事得多。从团队协作角度说，前后端分离也清晰。后端同事专注 SpringBoot 接口开发、MyBatis SQL 调优，前端同事专注 Vue3 组件和交互，两边用接口文档作为契约，并行推进效率明显高于传统的服务端渲染模板开发。而且这套系统的页面以表格、表单、图表为主，页面状态复杂，用 Vue 这类现代前端框架来管理界面状态，体验比 JSP 时代强太多了。再说技术选型。SpringBoot + MyBatis 是 Java 后端在中小企业项目里非常成熟的组合，SpringBoot 把配置简化到极致，MyBatis 则把 SQL 控制权完全还给开发者。这套源码里我故意用原生 MyBatis 的 XML 写法，没有引入 MyBatis-Plus，主要是考虑到教学场景：原生 SQL 看得见摸得着，业务逻辑复杂的时候不会被自动生成的 SQL 坑到。实际商业项目里用 MyBatis-Plus 提效没问题，但理解底层原理还是原生写法最实在。1.3 核心表结构与数据模型拆解数据库我用 MySQL 8.x，InnoDB 引擎，字符集选 utf8mb4。这个细节看起来不起眼，实际上很关键——船舶维保数据里大量英文缩写、特殊符号以及中文生僻字，utf8mb4 才能完整支持，否则存储时会出现乱码或者字符丢失。整个库的表结构可以分成四大类。基础档案类：船舶信息表、设备信息表、备件信息表，负责把管理对象建立起来。计划执行类：维保计划表、维保工单表、工单执行记录表，负责把流程跑起来。库存采购类：备件库存表、备件出入库记录表、采购申请单表，负责把物资管起来。权限类：用户表、角色表、菜单权限表，负责把入口控制住。拿核心的维保工单表举例，字段设计上除了常规的工单编号、关联设备、计划完成时间、指派人、工单状态之外，还有一个“来源计划ID”字段。这个字段特别重要，它把工单和生成它的维保计划关联起来，这样任何时候都能从工单反查是哪个计划触发的，报表统计完成率时也从这里拿数据。类似的隐藏关联逻辑在备件出库单里也有体现，出库单不仅记录备件数量和领用人，还要关联工单ID，这样分析“哪个设备最耗备件”就非常容易了。2. 后端核心模块实现要点2.1 RBAC权限模型与接口鉴权管理系统最先要解决的问题就是权限。这套系统用的是经典的 RBAC 模型，五张表：用户表、角色表、菜单表、用户角色关系表、角色菜单关系表。用户的权限不是直接挂在用户身上，而是通过角色间接关联，这样新增一个岗位只需要配置角色和菜单的关系，不用一个个改用户，维护成本低很多。有一次一个朋友问：我前端把菜单隐藏掉，用户不就看不到按钮了吗，后端加鉴权是不是多此一举？我说这是最典型的误区。前端隐藏菜单只是体验优化，接口不校验才是真正的安全漏洞。有人抓包拿到接口地址，直接构造请求就能操作数据，后果非常严重。所以这套系统里，前端负责"看不见"，后端负责"动不了"。后端权限拦截的实现思路很直接。登录成功后在 Redis 里缓存用户的权限标识集合，每次请求经过一个拦截器，拦截器解析 Token 拿到用户ID，再查 Redis 里的权限集合判断该请求对应的接口是否需要权限。没有权限直接返回 403，不会进入 Controller。这里有一个细节容易踩坑：修改角色权限后，必须删掉该角色下所有用户的缓存，否则旧权限会一直生效。我在系统里是用一个权限变更版本号来解决的，每次变更角色权限，版本号加一，拦截器比较版本号不一致就强制刷新缓存。2.2 维保计划与工单状态机维保计划是整个业务核心的起点。计划分为两种类型：一种是周期型，比如某型柴油机每运行 500 小时更换滑油，系统根据设备运行小时数自动判断是否到期，生成工单；另一种是日历型，比如年检、特检这类按日期固定的项目，到点自动提醒。这两种计划在数据库里用一个计划类型字段区分，触发逻辑不一样，但生成的工单结构是统一的。工单流转是这里最值得讲的部分。我用状态机来管理工单状态，六个状态：待派工、已派工、执行中、待验收、已完成、已取消。每个状态定义了允许的流转方向和操作角色：待派工只能由机务主管操作派工，已派工可以由轮机员确认开始执行，执行中填写完维保结果后提交待验收，验收人确认通过后变为已完成。非法操作在代码层直接拦截，比如已完成的工单不允许再修改，更不允许改回执行中。状态机的好处不只是防呆，还有流程追溯价值。工单表里有一个状态变更记录表，每次状态变化都插一条记录，包括操作人、操作时间、旧状态、新状态、备注。这样出了问题能查到完整的流转链路，是哪个环节、哪个人、什么时间做了什么操作，一清二楚。这个设计最初是船务公司提出的需求，实际上做下来发现对任何流程类系统都有很强的借鉴意义。2.3 备件库存与采购联动逻辑船舶备件管理和普通仓库管理有个明显区别：备件种类杂、计量单位不统一，有的按“个”、有的按“桶”、还有按“公斤”的，而且部分关键备件必须随船携带、不能断供。这套系统在设计库存表时，用统一的备件编码做主键，单位字段独立出来，避免出现换算混乱。工单执行过程有一个领用备件操作，前端选择备件、填写数量后，后端在一个事务里完成三件事：扣减库存表的可用数量、插入一条出库记录、如果库存低于安全阈值则自动生成一条采购申请记录。这三个操作必须在一个事务里，任何一个环节失败都不能写入数据库，否则就会出现库存扣了但出库单没生成这种数据不一致的问题。我在这块代码里加了事务注解，并且把扣减库存的 SQL 写成了乐观锁更新：先查当前库存，再带条件更新，affectedRows 为 0 说明有人并发改了数据，直接报业务异常提示刷新重试，这种处理方式在多人同时操作的场景下非常可靠。备件采购这块，采购申请单生成后有一个简单审批流程，机务主管审批通过后流转到采购员，采购员录入到货信息后，系统自动做入库操作并更新库存。整条链路设计下来，备件从进船到消耗的全生命周期都有据可查。2.4 报表统计的SQL聚合思路报表模块往往是管理系统的点睛之笔。系统里统计了几个核心指标：各船维保计划完成率、设备故障率、近六个月的备件消耗趋势、工单按时完成率。这些指标在数据库层面用分组聚合可以轻松算出来，不需要折腾复杂的大数据组件。以计划完成率为例，思路是这样的：从工单表按船舶分组统计已完成数量，再从工单表按船舶分组统计总数量，两个结果集按船舶关联后计算比率。关键点在于SQL的where条件要处理好时间范围，比如按月统计就按工单创建时间过滤，既能查看趋势，又不会把全量历史数据都捞出来影响性能。我特别想提醒一句话：这类管理系统的报表，能用SQL聚合解决的千万别在前端做。见过不少项目把明细数据全部拉到前端再用JavaScript循环统计，数据量小的时候看不出问题，但超过几千条页面就卡得不能忍。数据库做了几百万行数据的聚合也就几十毫秒，网络传输的数据量还小，这才是一个管理系统的正确打开方式。3. 前端Vue3实现与交互细节3.1 路由守卫与动态菜单Vue3 前端这部分，我用了组合式API风格，配合 Pinia 做全局状态管理。整个前端最核心的交互逻辑就是动态菜单和路由守卫。用户在登录页输入账号密码，后端校验通过后返回一个 Token 和该用户的菜单树，前端把菜单树存进 Pinia，然后通过 Vue Router 的 addRoute 方法动态注册路由。动态路由有一个容易踩的坑：页面刷新后 Pinia 内存里的数据丢失，导致路由表变成空，页面白屏。解决思路是在路由守卫里做一层检查，发现 Store 里没有菜单数据时，重新调用后端接口获取用户信息和菜单，再动态添加路由。这样不管怎么刷新，只要 Token 没过期，系统都能自己恢复状态。路由守卫的另一个职责是登录状态检查。我在 beforeEach 里判断，没有 Token 直接重定向到登录页；有 Token 但没有用户信息时，先拉取用户信息再放行。这里要注意接口并发请求的顺序问题，如果页面里多个组件同时发起接口请求，登录态未初始化时容易被误判为未登录，所以守卫里的初始化过程要加一个 Promise 串行化处理，简单说就是第一个请求拉取用户信息时，后续请求等它完成再走。3.2 表格页面通用封装管理系统里最不缺的就是表格页面，每个业务模块都是列表、搜索、分页、新增、编辑、删除这套流程。如果每个页面都单独写请求逻辑和分页逻辑，代码量会爆炸。我用组合式函数封装了一个 useTable，把“加载数据、搜索条件、分页参数、刷新列表”这套逻辑全部抽进去。具体用法是每个页面调用 useTable 时传入一个接口地址和默认查询参数，返回一个响应式对象和一组方法，模板里直接绑定表格的 data 属性、分页组件的数据源，按钮点击时调用对应的方法。这样每个页面只需要写自己特有的搜索表单和表格列定义，通用逻辑全部复用，后续加字段只改一处。这套封装做完之后，新增一个列表页从原来的两百行代码直接缩减到六七十行，效率提升是肉眼可见的。分页交互上有一个小细节：用户操作完翻页后，回到列表时最好保持之前的页码和搜索条件，而不是回到第一页。这个功能我用一个页面级的状态缓存实现，离开页面时把分页参数存到 sessionStorage，进入页面时恢复。虽然功能不大，但使用体验差别很明显。3.3 数据可视化与弱网适配报表页面用 ECharts 做数据可视化，折线图看备件消耗趋势，柱状图看各船维保完成率对比，饼图看故障类型分布。用 ECharts 要注意一个资源管理问题：图表组件在创建时初始化实例，在组件卸载时必须调用 dispose 销毁，否则内存泄漏，来回切换页面几次后浏览器会明显变卡。容器尺寸变化导致的图表变形也是一个常见问题。浏览器窗口被拖拽后，图表宽度不会自动适配，解决方案是监听容器大小变化，用 ResizeObserver 触发 chart.resize()。这个适配逻辑我封装在一个 BaseChart 组件里，所有图表页面共用。弱网适配方面，船舶场景下用户可能通过卫星网络访问系统，带宽小、延迟高。前端在请求库里的配置要注意：超时时间不能按局域网标准设置，我设了 15 秒超时，加载和提交过程给出明确的 loading 状态，避免用户以为请求卡死了反复点击造成重复数据。相关操作按钮在请求期间要禁用掉，这是一个小交互细节，但没有它，用户会重复提交工单，产生一堆脏数据。4. 从源码到运行的完整实操4.1 环境准备与版本选择想把这套系统跑起来，环境要求不复杂。后端需要 JDK 1.8 或 11、Maven 3.6 以上版本；前端需要 Node.js 16 以上；数据库用 MySQL 8.x；Redis 作为缓存和 Token 存储，版本 5.0 以上即可。版本选择上我多说两句。JDK 11 是目前企业项目兼容性和性能比较平衡的选择，新项目可以上 17，但这套源码在 JDK 8 下也能编译运行，照顾了大部分老项目的环境。Node 版本建议不要低于 16，Vite 对 Node 版本有要求，版本太低启动时会直接报错。MySQL 8.x 和 5.7 有一部分语法差异，比如 8.0 默认字符集是 utf8mb4，5.7 默认是 latin1，所以统一用 8.x 最能减少环境差异带来的问题。4.2 后端启动五步走后端启动流程很简单，核心就五步。第一步，创建一个 MySQL 数据库，名字随意但建议和配置一致，然后执行源码里提供的 init.sql 脚本，这个脚本会创建所有表结构并插入演示数据。第二步，修改 application.yml 配置文件，把数据库地址、用户名、密码改成自己环境的。第三步，启动 Redis，确保端口 6379 可用。第四步，在项目根目录执行 mvn spring-boot:run 或打成 jar 包后运行。第五步，启动成功后访问后端接口地址，看到登录接口返回正常响应就说明环境通了。application.yml 里最关键的配置是数据源和 Redis，其他配置项比如文件上传路径，我用了一个相对路径，部署时要注意目录存在且有写权限。如果修改了 Redis 密码，配置文件里也要同步改，否则启动时不会报错，但登录功能会异常——Token 存不进缓存，每次请求都是未登录状态，这类问题排查起来还挺费时间的。4.3 前端构建与联调配置前端启动前先执行 npm install 安装依赖。如果网络环境不好，可以配置镜像源，这个不多说。依赖安装完成后，执行 npm run dev 启动开发服务器，默认端口是 5173。开发环境的跨域问题我用 Vite 的 proxy 配置解决，而不是在后端开启 CORS。原理是让前端开发服务器把 /api 开头的请求转发到后端的 8080 端口，这样浏览器看到的请求是同源的，自然不存在跨域问题。配置如下：// vite.config.js 核心配置 server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }生产部署时，简单的做法是后端打 jar 包、前端构建静态文件后用 Nginx 托管，再把 /api 路径代理到后端服务。这样一套架构下来，前端和后端在访问路径上统一，也没有跨域问题，维护起来最省心。4.4 演示数据与角色说明系统内置了一套演示数据，包含三条演示船舶、若干设备类型和备件信息，维保计划也有几种典型配置，方便快速体验完整业务流程。用户账号分为三个角色：管理员、机务主管、轮机员。管理员的权限覆盖全部功能，包括数据字典维护和用户管理；机务主管拥有维保计划、工单派工、报表查看的权限；轮机员负责接收工单、填写维保结果和领用备件。建议第一次登录后修改默认密码，系统里也做了这个逻辑——默认密码登录后强制进入修改密码页面。演示数据还有一个作用，就是跑一遍流程后马上能看出数据之间的关系：执行一个工单、领用几个备件、再去库存页面看数量变化、去报表页面看指标统计，整个链路在十几分钟内可以全部体验完。实际上我自己测试时也是这么干的，走通主流程后再去改代码，定位问题会快很多。5. 常见问题与排查技巧实录5.1 数据库连接与中文乱码中文乱码是管理系统里最高频的问题，几乎每个人都有深刻教训。常见的原因是创建数据库时字符集没指定好，MySQL 在某些版本下默认字符集不支持中文。解决方法是建库时明确指定字符集和排序规则：CREATE DATABASE ship_maintenance DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;另一个容易忽略的地方是 JDBC 连接串。在 application.yml 的数据源配置里，URL 末尾一定要加 useUnicode=true 和 characterEncoding=utf8，否则即使数据库字符集正确，连接层依然可能乱码。还有一个细节，MySQL 8.x 的驱动类和 5.x 不一样，配置 driver-class-name 时要注意对应版本。这类问题一般有几个特征：数据库命令行查出来正常、但页面显示乱码，说明问题出在连接层；而数据库里存进去时就已经乱码，则多半是建库字符集问题。分清楚这两条线，排查方向就不会错。5.2 跨域与登录失效问题跨域问题在前后端分离项目里不可避免。开发环境用 Vite proxy 解决后一般不会遇到，但有时候改了后端地址忘了同步改 proxy 配置，也会导致请求打到了别的服务上，表现就是页面能打开但数据全部请求失败。排查时先看浏览器 Network 面板，请求是否真的发到了目标地址，再确认响应状态码。登录失效是另一个高频问题。Token 过期后请求返回 401，前端要有一个全局的响应拦截，遇到 401 时清空本地登录状态并跳转到登录页。但这里有个场景容易忽视：用户正在填写一个很长的维保工单，突然登录失效，填了一半的数据全丢了。我的处理方案是在拦截器里弹一个友好的提示，并且把当前路由和页面数据暂存到 sessionStorage，重新登录后提示用户恢复。这个功能用户评价特别好，减少了不少抱怨。5.3 查询慢与索引设计随着维保工单数据积累，工单表的行数增长很快，如果不加索引，联表查询会越跑越慢。我在这套系统里给工单表建了组合索引，索引字段是（船舶ID，计划完成时间），这样按船舶查工单列表、按时间范围统计完成率都能命中索引，性能提升非常明显。注意组合索引的顺序有讲究，最常用的等值查询字段放前面，范围查询字段放后面。排查慢查询时，最直接的方法是打开 MySQL 的慢查询日志，或者用 EXPLAIN 查看执行计划。看 key 字段是否命中索引，看 rows 字段估算扫描行数，如果扫描行数特别多就要考虑建索引。这里有一个反面经验：曾经有个同事把所有查询字段都建了索引，结果表插入数据变慢，索引维护成本很高。索引不是越多越好，要结合真实的查询场景来定，高频查询字段加索引，低频字段盲目加反而拖累写性能。5.4 权限漏配与数据越权权限这块最容易出现的问题不是权限拦截器写错了，而是接口漏配。新增接口时忘了配置需要的权限标识，结果任何登录用户都能调用，这在验收测试时往往还测不出来，因为测试只关注功能是否正常，不会去验证越权场景。我的排查建议是做一个接口权限清单，把每个 Controller 接口和所需的权限标识列出来，和菜单配置对照检查。还有一个常见问题：同一个接口被两个角色使用，但操作的字段范围和按钮级别不一样，最典型的是机务主管可以删除工单，轮机员只能查看自己的工单。这类问题靠全局拦截器解决不了，必须在业务层做数据范围的校验，比如轮机员查询工单列表时，SQL 里强制加上执行人等于当前用户ID的条件，而不是把参数交给前端传入，否则人家改一下请求参数就能看到别人的工单了。数据越权问题在船舶管理系统里尤其敏感，因为工单里包含维修工时、故障详情、备件消耗，这些都是船舶运营数据，不能随便给无关的人看到。我在这套系统里给查询接口做了一个统一的用户上下文注入，当前登录用户信息从 Token 解析出来塞进 ThreadLocal，SQL 层根据角色自动拼接数据范围条件，这样后端始终以服务端信息为准，前端传什么参数都不能覆盖，安全等级就上来了。说一个我实际项目里的体会。做这类管理系统，技术本身没有什么高深的地方，难的是对业务的理解和对数据一致性的敬畏。船舶维保这种场景，设备漏保养可能直接带来安全隐患，所以系统里每一个状态流转、每一次库存扣减，我都要求有记录、可追溯、防并发。把这套思路想清楚再动手，写代码的时候自然就稳了。源码整理出来之后，有同行问我后续还能加什么功能，我觉得下一步最值得做的是船端离线模式——把工单下载到本地、执行完再同步回岸基，这需要在现有接口结构上加一层同步机制，好在当初接口设计时返回值全部做了统一封装，改造起来不会伤筋动骨。希望这套系统的设计思路能给做同类项目的朋友一些参考，少走几步我曾经踩过的弯路。
做管理系统这些年，我接触过仓储、设备、物业好几个行业，船舶维保是其中最考验人的一个。原因很简单：船是移动资产，一条船几个月在海上漂，维保工作必须按计划刚性执行，可传统纸质记录和散落的Excel表格又实在无法追溯——上次主机保养是哪天做的、下次滑油更换还剩多少运行小时，全靠老师傅脑子记，风险不小。去年帮某船务公司梳理内部系统时，我落地了一套船舶维保管理系统，技术栈就是标题里写的 Java SpringBoot + Vue3 + MyBatis，数据库用 MySQL，前后端分离。系统规模不大，但把船舶档案、维保计划、工单流转、备件库存、统计报表这些核心业务覆盖全了。这几天我把源码整理出来分享给同行，顺手把设计和实现过程写成这篇文章。想了解真实业务系统怎么落地的后端朋友、想看看 Vue3 在项目中实际怎么用的前端同学，或是正在做船舶信息化选型的人，都可以参考。1. 项目整体设计与选型思路1.1 场景痛点与系统定位船舶维保这个场景，和普通企业设备管理有一个很大的不同：数据产生地点和使用地点经常分离。机务主管在岸基办公室制定计划，轮机员在船上执行工单，船长要看整体维保进度，备件管理员则关心库存够不够。每个角色关心的是同一批数据的不同侧面，这就要求系统从一开始就要把“流程”和“数据一致性”放在首位，而不是简单做个增删改查。传统管理方式的核心痛点有几个。第一，维保计划靠人工盯，什么设备该保养了、什么时候到期，稍有疏忽就会出现漏保养，影响船舶安全。第二，工单执行结果记录在纸上，回到岸基再录入电脑，信息滞后还容易丢失。第三，备件领用和库存对不上，经常出现"账上有、库里没"的情况，紧急采购又赶不上船期。第四，管理层想看的统计报表，全靠人工汇总，工作量巨大。这套系统的定位，就是针对这些痛点做一套轻量级解决方案。不追求大而全，重点把计划、执行、库存三个环节打通：计划自动生成工单，工单执行关联备件领用，备件消耗自动扣库存，报表从这些数据里实时聚合出来。这样一个闭环下来，机务主管打开工作台就能看到各船维保完成情况，轮机员在平板上就能接收工单、填写结果，备件管理员实时掌握库存变化，管理层要数据随时能看。1.2 为什么是前后端分离架构选前后端分离，不是跟风，完全是这个项目的实际需要。船舶行业的用户分散在岸基、船端和港口，未来很可能要做小程序或者对接船岸通讯系统，前后端分离之后，后端只要提供统一的 API，任何终端都可以接入。尤其是船端网络不稳定，将来做离线模式或者数据同步的时候，后端接口独立于前端页面，改起来省事得多。从团队协作角度说，前后端分离也清晰。后端同事专注 SpringBoot 接口开发、MyBatis SQL 调优，前端同事专注 Vue3 组件和交互，两边用接口文档作为契约，并行推进效率明显高于传统的服务端渲染模板开发。而且这套系统的页面以表格、表单、图表为主，页面状态复杂，用 Vue 这类现代前端框架来管理界面状态，体验比 JSP 时代强太多了。再说技术选型。SpringBoot + MyBatis 是 Java 后端在中小企业项目里非常成熟的组合，SpringBoot 把配置简化到极致，MyBatis 则把 SQL 控制权完全还给开发者。这套源码里我故意用原生 MyBatis 的 XML 写法，没有引入 MyBatis-Plus，主要是考虑到教学场景：原生 SQL 看得见摸得着，业务逻辑复杂的时候不会被自动生成的 SQL 坑到。实际商业项目里用 MyBatis-Plus 提效没问题，但理解底层原理还是原生写法最实在。1.3 核心表结构与数据模型拆解数据库我用 MySQL 8.x，InnoDB 引擎，字符集选 utf8mb4。这个细节看起来不起眼，实际上很关键——船舶维保数据里大量英文缩写、特殊符号以及中文生僻字，utf8mb4 才能完整支持，否则存储时会出现乱码或者字符丢失。整个库的表结构可以分成四大类。基础档案类：船舶信息表、设备信息表、备件信息表，负责把管理对象建立起来。计划执行类：维保计划表、维保工单表、工单执行记录表，负责把流程跑起来。库存采购类：备件库存表、备件出入库记录表、采购申请单表，负责把物资管起来。权限类：用户表、角色表、菜单权限表，负责把入口控制住。拿核心的维保工单表举例，字段设计上除了常规的工单编号、关联设备、计划完成时间、指派人、工单状态之外，还有一个“来源计划ID”字段。这个字段特别重要，它把工单和生成它的维保计划关联起来，这样任何时候都能从工单反查是哪个计划触发的，报表统计完成率时也从这里拿数据。类似的隐藏关联逻辑在备件出库单里也有体现，出库单不仅记录备件数量和领用人，还要关联工单ID，这样分析“哪个设备最耗备件”就非常容易了。2. 后端核心模块实现要点2.1 RBAC权限模型与接口鉴权管理系统最先要解决的问题就是权限。这套系统用的是经典的 RBAC 模型，五张表：用户表、角色表、菜单表、用户角色关系表、角色菜单关系表。用户的权限不是直接挂在用户身上，而是通过角色间接关联，这样新增一个岗位只需要配置角色和菜单的关系，不用一个个改用户，维护成本低很多。有一次一个朋友问：我前端把菜单隐藏掉，用户不就看不到按钮了吗，后端加鉴权是不是多此一举？我说这是最典型的误区。前端隐藏菜单只是体验优化，接口不校验才是真正的安全漏洞。有人抓包拿到接口地址，直接构造请求就能操作数据，后果非常严重。所以这套系统里，前端负责"看不见"，后端负责"动不了"。后端权限拦截的实现思路很直接。登录成功后在 Redis 里缓存用户的权限标识集合，每次请求经过一个拦截器，拦截器解析 Token 拿到用户ID，再查 Redis 里的权限集合判断该请求对应的接口是否需要权限。没有权限直接返回 403，不会进入 Controller。这里有一个细节容易踩坑：修改角色权限后，必须删掉该角色下所有用户的缓存，否则旧权限会一直生效。我在系统里是用一个权限变更版本号来解决的，每次变更角色权限，版本号加一，拦截器比较版本号不一致就强制刷新缓存。2.2 维保计划与工单状态机维保计划是整个业务核心的起点。计划分为两种类型：一种是周期型，比如某型柴油机每运行 500 小时更换滑油，系统根据设备运行小时数自动判断是否到期，生成工单；另一种是日历型，比如年检、特检这类按日期固定的项目，到点自动提醒。这两种计划在数据库里用一个计划类型字段区分，触发逻辑不一样，但生成的工单结构是统一的。工单流转是这里最值得讲的部分。我用状态机来管理工单状态，六个状态：待派工、已派工、执行中、待验收、已完成、已取消。每个状态定义了允许的流转方向和操作角色：待派工只能由机务主管操作派工，已派工可以由轮机员确认开始执行，执行中填写完维保结果后提交待验收，验收人确认通过后变为已完成。非法操作在代码层直接拦截，比如已完成的工单不允许再修改，更不允许改回执行中。状态机的好处不只是防呆，还有流程追溯价值。工单表里有一个状态变更记录表，每次状态变化都插一条记录，包括操作人、操作时间、旧状态、新状态、备注。这样出了问题能查到完整的流转链路，是哪个环节、哪个人、什么时间做了什么操作，一清二楚。这个设计最初是船务公司提出的需求，实际上做下来发现对任何流程类系统都有很强的借鉴意义。2.3 备件库存与采购联动逻辑船舶备件管理和普通仓库管理有个明显区别：备件种类杂、计量单位不统一，有的按“个”、有的按“桶”、还有按“公斤”的，而且部分关键备件必须随船携带、不能断供。这套系统在设计库存表时，用统一的备件编码做主键，单位字段独立出来，避免出现换算混乱。工单执行过程有一个领用备件操作，前端选择备件、填写数量后，后端在一个事务里完成三件事：扣减库存表的可用数量、插入一条出库记录、如果库存低于安全阈值则自动生成一条采购申请记录。这三个操作必须在一个事务里，任何一个环节失败都不能写入数据库，否则就会出现库存扣了但出库单没生成这种数据不一致的问题。我在这块代码里加了事务注解，并且把扣减库存的 SQL 写成了乐观锁更新：先查当前库存，再带条件更新，affectedRows 为 0 说明有人并发改了数据，直接报业务异常提示刷新重试，这种处理方式在多人同时操作的场景下非常可靠。备件采购这块，采购申请单生成后有一个简单审批流程，机务主管审批通过后流转到采购员，采购员录入到货信息后，系统自动做入库操作并更新库存。整条链路设计下来，备件从进船到消耗的全生命周期都有据可查。2.4 报表统计的SQL聚合思路报表模块往往是管理系统的点睛之笔。系统里统计了几个核心指标：各船维保计划完成率、设备故障率、近六个月的备件消耗趋势、工单按时完成率。这些指标在数据库层面用分组聚合可以轻松算出来，不需要折腾复杂的大数据组件。以计划完成率为例，思路是这样的：从工单表按船舶分组统计已完成数量，再从工单表按船舶分组统计总数量，两个结果集按船舶关联后计算比率。关键点在于SQL的where条件要处理好时间范围，比如按月统计就按工单创建时间过滤，既能查看趋势，又不会把全量历史数据都捞出来影响性能。我特别想提醒一句话：这类管理系统的报表，能用SQL聚合解决的千万别在前端做。见过不少项目把明细数据全部拉到前端再用JavaScript循环统计，数据量小的时候看不出问题，但超过几千条页面就卡得不能忍。数据库做了几百万行数据的聚合也就几十毫秒，网络传输的数据量还小，这才是一个管理系统的正确打开方式。3. 前端Vue3实现与交互细节3.1 路由守卫与动态菜单Vue3 前端这部分，我用了组合式API风格，配合 Pinia 做全局状态管理。整个前端最核心的交互逻辑就是动态菜单和路由守卫。用户在登录页输入账号密码，后端校验通过后返回一个 Token 和该用户的菜单树，前端把菜单树存进 Pinia，然后通过 Vue Router 的 addRoute 方法动态注册路由。动态路由有一个容易踩的坑：页面刷新后 Pinia 内存里的数据丢失，导致路由表变成空，页面白屏。解决思路是在路由守卫里做一层检查，发现 Store 里没有菜单数据时，重新调用后端接口获取用户信息和菜单，再动态添加路由。这样不管怎么刷新，只要 Token 没过期，系统都能自己恢复状态。路由守卫的另一个职责是登录状态检查。我在 beforeEach 里判断，没有 Token 直接重定向到登录页；有 Token 但没有用户信息时，先拉取用户信息再放行。这里要注意接口并发请求的顺序问题，如果页面里多个组件同时发起接口请求，登录态未初始化时容易被误判为未登录，所以守卫里的初始化过程要加一个 Promise 串行化处理，简单说就是第一个请求拉取用户信息时，后续请求等它完成再走。3.2 表格页面通用封装管理系统里最不缺的就是表格页面，每个业务模块都是列表、搜索、分页、新增、编辑、删除这套流程。如果每个页面都单独写请求逻辑和分页逻辑，代码量会爆炸。我用组合式函数封装了一个 useTable，把“加载数据、搜索条件、分页参数、刷新列表”这套逻辑全部抽进去。具体用法是每个页面调用 useTable 时传入一个接口地址和默认查询参数，返回一个响应式对象和一组方法，模板里直接绑定表格的 data 属性、分页组件的数据源，按钮点击时调用对应的方法。这样每个页面只需要写自己特有的搜索表单和表格列定义，通用逻辑全部复用，后续加字段只改一处。这套封装做完之后，新增一个列表页从原来的两百行代码直接缩减到六七十行，效率提升是肉眼可见的。分页交互上有一个小细节：用户操作完翻页后，回到列表时最好保持之前的页码和搜索条件，而不是回到第一页。这个功能我用一个页面级的状态缓存实现，离开页面时把分页参数存到 sessionStorage，进入页面时恢复。虽然功能不大，但使用体验差别很明显。3.3 数据可视化与弱网适配报表页面用 ECharts 做数据可视化，折线图看备件消耗趋势，柱状图看各船维保完成率对比，饼图看故障类型分布。用 ECharts 要注意一个资源管理问题：图表组件在创建时初始化实例，在组件卸载时必须调用 dispose 销毁，否则内存泄漏，来回切换页面几次后浏览器会明显变卡。容器尺寸变化导致的图表变形也是一个常见问题。浏览器窗口被拖拽后，图表宽度不会自动适配，解决方案是监听容器大小变化，用 ResizeObserver 触发 chart.resize()。这个适配逻辑我封装在一个 BaseChart 组件里，所有图表页面共用。弱网适配方面，船舶场景下用户可能通过卫星网络访问系统，带宽小、延迟高。前端在请求库里的配置要注意：超时时间不能按局域网标准设置，我设了 15 秒超时，加载和提交过程给出明确的 loading 状态，避免用户以为请求卡死了反复点击造成重复数据。相关操作按钮在请求期间要禁用掉，这是一个小交互细节，但没有它，用户会重复提交工单，产生一堆脏数据。4. 从源码到运行的完整实操4.1 环境准备与版本选择想把这套系统跑起来，环境要求不复杂。后端需要 JDK 1.8 或 11、Maven 3.6 以上版本；前端需要 Node.js 16 以上；数据库用 MySQL 8.x；Redis 作为缓存和 Token 存储，版本 5.0 以上即可。版本选择上我多说两句。JDK 11 是目前企业项目兼容性和性能比较平衡的选择，新项目可以上 17，但这套源码在 JDK 8 下也能编译运行，照顾了大部分老项目的环境。Node 版本建议不要低于 16，Vite 对 Node 版本有要求，版本太低启动时会直接报错。MySQL 8.x 和 5.7 有一部分语法差异，比如 8.0 默认字符集是 utf8mb4，5.7 默认是 latin1，所以统一用 8.x 最能减少环境差异带来的问题。4.2 后端启动五步走后端启动流程很简单，核心就五步。第一步，创建一个 MySQL 数据库，名字随意但建议和配置一致，然后执行源码里提供的 init.sql 脚本，这个脚本会创建所有表结构并插入演示数据。第二步，修改 application.yml 配置文件，把数据库地址、用户名、密码改成自己环境的。第三步，启动 Redis，确保端口 6379 可用。第四步，在项目根目录执行 mvn spring-boot:run 或打成 jar 包后运行。第五步，启动成功后访问后端接口地址，看到登录接口返回正常响应就说明环境通了。application.yml 里最关键的配置是数据源和 Redis，其他配置项比如文件上传路径，我用了一个相对路径，部署时要注意目录存在且有写权限。如果修改了 Redis 密码，配置文件里也要同步改，否则启动时不会报错，但登录功能会异常——Token 存不进缓存，每次请求都是未登录状态，这类问题排查起来还挺费时间的。4.3 前端构建与联调配置前端启动前先执行 npm install 安装依赖。如果网络环境不好，可以配置镜像源，这个不多说。依赖安装完成后，执行 npm run dev 启动开发服务器，默认端口是 5173。开发环境的跨域问题我用 Vite 的 proxy 配置解决，而不是在后端开启 CORS。原理是让前端开发服务器把 /api 开头的请求转发到后端的 8080 端口，这样浏览器看到的请求是同源的，自然不存在跨域问题。配置如下：// vite.config.js 核心配置 server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }生产部署时，简单的做法是后端打 jar 包、前端构建静态文件后用 Nginx 托管，再把 /api 路径代理到后端服务。这样一套架构下来，前端和后端在访问路径上统一，也没有跨域问题，维护起来最省心。4.4 演示数据与角色说明系统内置了一套演示数据，包含三条演示船舶、若干设备类型和备件信息，维保计划也有几种典型配置，方便快速体验完整业务流程。用户账号分为三个角色：管理员、机务主管、轮机员。管理员的权限覆盖全部功能，包括数据字典维护和用户管理；机务主管拥有维保计划、工单派工、报表查看的权限；轮机员负责接收工单、填写维保结果和领用备件。建议第一次登录后修改默认密码，系统里也做了这个逻辑——默认密码登录后强制进入修改密码页面。演示数据还有一个作用，就是跑一遍流程后马上能看出数据之间的关系：执行一个工单、领用几个备件、再去库存页面看数量变化、去报表页面看指标统计，整个链路在十几分钟内可以全部体验完。实际上我自己测试时也是这么干的，走通主流程后再去改代码，定位问题会快很多。5. 常见问题与排查技巧实录5.1 数据库连接与中文乱码中文乱码是管理系统里最高频的问题，几乎每个人都有深刻教训。常见的原因是创建数据库时字符集没指定好，MySQL 在某些版本下默认字符集不支持中文。解决方法是建库时明确指定字符集和排序规则：CREATE DATABASE ship_maintenance DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;另一个容易忽略的地方是 JDBC 连接串。在 application.yml 的数据源配置里，URL 末尾一定要加 useUnicode=true 和 characterEncoding=utf8，否则即使数据库字符集正确，连接层依然可能乱码。还有一个细节，MySQL 8.x 的驱动类和 5.x 不一样，配置 driver-class-name 时要注意对应版本。这类问题一般有几个特征：数据库命令行查出来正常、但页面显示乱码，说明问题出在连接层；而数据库里存进去时就已经乱码，则多半是建库字符集问题。分清楚这两条线，排查方向就不会错。5.2 跨域与登录失效问题跨域问题在前后端分离项目里不可避免。开发环境用 Vite proxy 解决后一般不会遇到，但有时候改了后端地址忘了同步改 proxy 配置，也会导致请求打到了别的服务上，表现就是页面能打开但数据全部请求失败。排查时先看浏览器 Network 面板，请求是否真的发到了目标地址，再确认响应状态码。登录失效是另一个高频问题。Token 过期后请求返回 401，前端要有一个全局的响应拦截，遇到 401 时清空本地登录状态并跳转到登录页。但这里有个场景容易忽视：用户正在填写一个很长的维保工单，突然登录失效，填了一半的数据全丢了。我的处理方案是在拦截器里弹一个友好的提示，并且把当前路由和页面数据暂存到 sessionStorage，重新登录后提示用户恢复。这个功能用户评价特别好，减少了不少抱怨。5.3 查询慢与索引设计随着维保工单数据积累，工单表的行数增长很快，如果不加索引，联表查询会越跑越慢。我在这套系统里给工单表建了组合索引，索引字段是（船舶ID，计划完成时间），这样按船舶查工单列表、按时间范围统计完成率都能命中索引，性能提升非常明显。注意组合索引的顺序有讲究，最常用的等值查询字段放前面，范围查询字段放后面。排查慢查询时，最直接的方法是打开 MySQL 的慢查询日志，或者用 EXPLAIN 查看执行计划。看 key 字段是否命中索引，看 rows 字段估算扫描行数，如果扫描行数特别多就要考虑建索引。这里有一个反面经验：曾经有个同事把所有查询字段都建了索引，结果表插入数据变慢，索引维护成本很高。索引不是越多越好，要结合真实的查询场景来定，高频查询字段加索引，低频字段盲目加反而拖累写性能。5.4 权限漏配与数据越权权限这块最容易出现的问题不是权限拦截器写错了，而是接口漏配。新增接口时忘了配置需要的权限标识，结果任何登录用户都能调用，这在验收测试时往往还测不出来，因为测试只关注功能是否正常，不会去验证越权场景。我的排查建议是做一个接口权限清单，把每个 Controller 接口和所需的权限标识列出来，和菜单配置对照检查。还有一个常见问题：同一个接口被两个角色使用，但操作的字段范围和按钮级别不一样，最典型的是机务主管可以删除工单，轮机员只能查看自己的工单。这类问题靠全局拦截器解决不了，必须在业务层做数据范围的校验，比如轮机员查询工单列表时，SQL 里强制加上执行人等于当前用户ID的条件，而不是把参数交给前端传入，否则人家改一下请求参数就能看到别人的工单了。数据越权问题在船舶管理系统里尤其敏感，因为工单里包含维修工时、故障详情、备件消耗，这些都是船舶运营数据，不能随便给无关的人看到。我在这套系统里给查询接口做了一个统一的用户上下文注入，当前登录用户信息从 Token 解析出来塞进 ThreadLocal，SQL 层根据角色自动拼接数据范围条件，这样后端始终以服务端信息为准，前端传什么参数都不能覆盖，安全等级就上来了。说一个我实际项目里的体会。做这类管理系统，技术本身没有什么高深的地方，难的是对业务的理解和对数据一致性的敬畏。船舶维保这种场景，设备漏保养可能直接带来安全隐患，所以系统里每一个状态流转、每一次库存扣减，我都要求有记录、可追溯、防并发。把这套思路想清楚再动手，写代码的时候自然就稳了。源码整理出来之后，有同行问我后续还能加什么功能，我觉得下一步最值得做的是船端离线模式——把工单下载到本地、执行完再同步回岸基，这需要在现有接口结构上加一层同步机制，好在当初接口设计时返回值全部做了统一封装，改造起来不会伤筋动骨。希望这套系统的设计思路能给做同类项目的朋友一些参考，少走几步我曾经踩过的弯路。