作为一个常年泡在船厂项目里的Java开发我深知船舶监造这个业务有多“折腾”。船东、船厂、监理方、设备供应商四方人马围绕一条船要在船坞里盯大半年从钢板切割到试航交船每个节点都得留痕、每个报验都得签字、每份图纸都得流转。以前很多船厂还在用Excel加微信群管理这些事进度靠催、记录靠翻、问题靠吼一船造下来光整理报验资料就能堆满一个档案柜。正因如此当时我们团队决定从零搭一套船舶监造管理系统时我没有选择那些重型ERP套件而是基于SpringBoot2 Vue3 MyBatis-Plus MySQL8.0这套组合快速落地了一套自有源码系统。整套系统覆盖了从合同签订到交船结算的全生命周期管理包含船舶建造进度、质量报验、检验申请、监理日志、图纸文档、问题整改、周报月报等核心功能模块配合完整的项目文档非常适合中小型船厂、监理公司以及需要快速私有化部署的团队参考。这篇文章我就把这套系统的完整设计思路、关键实现、部署过程和踩坑记录都摊开来讲希望能给准备做同类业务系统的朋友一个可落地的参考样板。1. 业务拆解与技术选型这套系统到底要解决什么问题1.1 船舶监造业务的真实痛点在展开代码之前得先把业务逻辑吃透。船舶监造不是简单的“看进度”它是一个多角色、长周期、强流程的协同场景。一条散货船从开工到交付周期普遍在10到14个月涉及到的报验项目可能高达两三千个节点每个节点都要走“施工班组自检 - 监理报验 - 船东/第三方抽检 - 意见整改 - 闭合销项”的完整链路。我调研过好几家船厂发现他们最痛的不是没有报表而是数据根本对不上。计划部手里的计划节点、质量部手里的报验记录、监理手里的整改通知常常是三个口径。现场交验单还是纸质版签完字往柜子里一扔后期想统计某个分段的合格率得靠人工翻单据。这种模式不仅效率低而且追溯性极差——船东一旦问起某个问题为什么没闭合往往要花半天去翻记录。所以这套系统在设计之初就定了基调核心不是做一个花哨的看板而是一个“流程引擎 数据台账”先保证所有业务节点都有系统记录再考虑报表和看板展示。1.2 系统角色与权限模型设计船舶监造系统的角色天然是多样化的我梳理了一套五角色权限模型系统管理员负责基础数据维护、用户管理、角色权限配置。船厂项目负责人管理生产计划、录入施工进度、分配施工班组。监理工程师核心业务角色负责报验审核、检验申请审批、问题整改跟踪。船东代表查看进度和质量情况参与报验抽检查看各类报表。供应商/分包商仅查看与自己相关的设备交付进度和图纸文档。这个模型的设计关键点在于权限的“数据范围隔离”。同一个监理工程师只能看到自己负责的船型或分段船东代表虽然是甲方但也不能修改系统的核心业务数据。我用MyBatis-Plus的逻辑删除和数据权限插件配合自定义注解实现了功能权限和数据权限的双层控制。比如监理工程师默认数据范围是“本部门”船东代表是“本船型”管理员才能看全厂所有数据。这样既保证了数据安全又让每个角色打开系统看到的都是“自己的活”。1.3 为什么选SpringBoot2 Vue3 MyBatis-Plus这套组合选型这件事我见过太多为了追新而把团队带沟里的案例。这套系统选型时做过一轮对比最终敲定SpringBoot2 Vue3 MyBatis-Plus的组合核心考量有三点第一团队技术栈的性价比。团队主力全是Java和Vue背景SpringBoot2的市场存量最大、踩坑资料最多遇到问题基本都能查到解决方案不需要从零摸索。Vue3配合Element Plus界面能力完全够用且生态成熟度已经追上Vue2。第二MyBatis-Plus的实用价值。船舶监造这类业务80%以上是标准单表CRUD加关联查询。MyBatis-Plus的BaseMapper和ServiceImpl把单表操作几乎全包了开发效率直线上升。更重要的是它的分页插件和LambdaQueryWrapper在写复杂查询条件时非常顺手不用像MyBatis那样每条SQL都要手写Xml。第三MySQL 8.0的能力匹配。这套系统虽然涉及的业务表有几十张但单表数据量一年撑死几十万行根本不需要上分布式数据库。MySQL 8.0新增的窗口函数、公用表表达式CTE在写复杂统计报表时能省不少事加上JSON字段的支持处理扩展属性比单纯加字段灵活得多。这套组合的综合维护成本也是最低的一个小团队就能完全掌控出了问题自己能排查不需要额外找外部专家契合船舶监造这类业务系统“稳定压倒一切”的需求。2. 后端架构设计与核心模块实现2.1 项目分层结构与基础配置后端项目我采用了经典的四层结构Controller层、Service层、Mapper层、Entity层再加上一个独立的config包和common包。ship-supervision/ ├── src/main/java/com/shipsys/ │ ├── controller/ # 接口层 │ ├── service/ # 业务逻辑层 │ │ ├── impl/ │ ├── mapper/ # 数据访问层 │ ├── entity/ # 实体类 │ ├── dto/ # 数据传输对象 │ ├── vo/ # 视图对象 │ ├── config/ # 配置类 │ │ ├── MybatisPlusConfig.java │ │ ├── SecurityConfig.java │ │ └── WebConfig.java │ ├── common/ # 公共类 │ │ ├── Result.java # 统一返回体 │ │ ├── PageResult.java │ │ └── exception/ │ └── utils/ └── src/main/resources/ ├── application.yml └── mapper/ # XML文件仅在必要时使用这里有一个设计上比较重要的决策基本不用Mapper XML而是全部采取MyBatis-Plus的LambdaQueryWrapper或自定义注解SQL。我在实践中发现大部分业务查询条件都是动态拼接的比如报验单查询需要按船型、分段号、报验类型、状态、时间范围任意组合筛选用LambdaQueryWrapper可以完全通过Java代码动态组装条件可读性和维护性都优于XML里堆砌IF标签。application.yml配置中有几个细节值得注意。数据库连接池用的是HikariCP配置了最大连接数和空闲超时参数spring: datasource: url: jdbc:mysql://localhost:3306/ship_supervision?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: ****** driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 20 minimum-idle: 5 idle-timeout: 300000 connection-timeout: 20000MySQL8.0和旧版驱动有个容易踩的坑就是从com.mysql.jdbc.Driver换成了com.mysql.cj.jdbc.Driver并且URL里如果不指定serverTimezone会直接报时区错误这个配置可以说是血泪教训。2.2 核心业务表设计与MyBatis-Plus实战数据库设计是整个系统的地基。我梳理了20多张核心业务表按业务域可以分为五大块基础数据域船舶类型表、船厂部门表、用户表、角色表。进度管理域建造计划表、实际进度表、里程碑节点表。质量管理域报验申请单表、检验记录表、问题整改单表、不合格品处理表。文档管理域图纸文件表、技术协议表、文档版本记录表。综合管理域监理日志表、周报月报表、会议纪要表、设备到货登记表。以报验申请单表为例设计时需要特别考虑状态流转。我用了integer类型的status字段0表示待提交、1表示待监理审核、2表示待整改、3表示已闭合、4表示已驳回所有状态变更都在Service层的方法中做校验和记录不允许直接修改。之所以不用复杂的流程引擎比如Flowable或Activiti是因为船舶监造的流程相对固定只有一条主线加少量分支用流程引擎反而增加了部署和学习的复杂度。自己写一个轻量级状态机通过常量类定义状态和操作用枚举管理合法的状态转换足够清晰、足够稳定。MyBatis-Plus在这里发挥价值最大的是三件事第一通用CRUD让25张表的增删改查代码量骤降不用为每张表写Mapper XML。第二自动填充功能统一处理create_time、update_time、create_by等审计字段不需要在每个Service里手动set当前用户名和时间。第三分页插件集成简单在MybatisPlusConfig里加上一个拦截器所有业务查询自动支持分页。这在实际开发中省了大量时间。2.3 关键技术细节数据权限、逻辑删除与乐观锁数据权限这个功能是船舶监造系统里最容易被低估的部分。如果不做隔离监理A能看到监理B的全部报验记录部门之间的数据互相交叉很容易造成信息混乱和责任推诿。我通过自定义注解DataScope和MyBatis-Plus的Interceptor实现了SQL层面的数据权限过滤在Mapper方法执行前自动拼接数据权限条件比如and create_dept_id xxx。这样业务代码里不需要写任何权限判断逻辑保持干净。逻辑删除是MyBatis-Plus里非常成熟的能力我只在实体类的deleted字段上加了个TableLogic注解所有删除操作就自动从delete变成update查询时自动带上deleted 0条件。这个功能在用户管理、基础数据维护场景下非常好用误删除后的恢复成本极低。还有一个容易忽略的细节是乐观锁。报验单审核场景里如果两个监理同时打开同一张单据一个在填审核意见一个点了通过就可能出现更新覆盖的问题。我给审核操作加了一个Version注解的version字段配合MyBatis-Plus的乐观锁插件更新时如果版本号不匹配直接抛出异常并提示“数据已被他人修改请刷新后重试”从根本上避免了并发覆盖的问题。2.4 文件上传与预览图纸文档管理的实现船舶监造绕不开图纸文档。一张图纸可能有多个版本现场施工人员需要随时查看到最新版同时历史版本必须可追溯。文件上传的原始代码本身不复杂但有几个决策值得展开说。首先存储方案。我没有选择FastDFS或MinIO这种分布式存储因为系统是单机部署月度文件增量一般也就几个GB。我选择了本地磁盘存储加MySQL元数据记录的方式配置一个upload.path目录按/年/月/日子目录分片存储。文件物理路径不直接暴露给前端下载时通过后端做权限校验后再重新定向避免越权访问。其次文件与业务主键的关联。我设计了一张通用的biz_file表字段包含biz_type业务类型、biz_id业务主键、file_name、file_url、file_size、file_md5。这样做的好处是报验单、整改单、监理日志等所有业务都能复用同一套文件上传逻辑前端只需要在回调里把biz_type和biz_id传给后端就能自动绑定。第三版本管理。图纸上传时前端传一个drawing_no图号后端判断这个图号是否已有记录。如果存在自动把当前记录版本号加1历史版本保留可查询、可下载最新版本默认置为“生效中”。这个机制虽然简单但确实解决了船厂现场最头疼的“图纸版本混乱”问题。3. Vue3前端实现要点与前后端联调3.1 前端工程化与项目搭建前端的搭建思路就一句话用标准Vue3工程化方案别整花活。项目基于Vite构建使用vue3vue-router4piniaelement-plus的组合。npm create vitelatest ship-supervision-web -- --template vue npm install element-plus element-plus/icons-vue pinia vue-router axiosVite相比Webpack的优势是开发体验极好启动速度快、热更新及时。船舶监造这种管理系统页面数量多但都是表单和列表Vite的按需编译让开发阶段几乎不卡顿。代码组织上我重点做了模块化api目录按业务模块拆分接口定义比如api/inspection.js专门负责报验单的增删改查views目录按菜单结构组织页面components目录放一些复用组件比如通用搜索栏、通用表格、通用弹窗表单。每个页面尽量拆成“搜索区 表格区 弹窗表单区”这个三段式模板在业务系统里极度通用开发新页面时能直接套用骨架效率非常高。3.2 核心页面拆解报验管理模块实战报验管理是整个系统前端最核心的页面交互逻辑比较典型值得单独拆开讲。页面左侧是船舶分段树形结构右侧是报验单列表。点击左侧任意分段右侧自动加载该分段下的所有报验记录。这里我用了Element Plus的el-tree数据源是一棵“船型 - 分段 - 区域”的层级树。树节点的数据和报验单通过sectionId关联。列表支持多条件筛选报验类型焊接/涂装/尺寸/密性、状态、时间范围、关键字搜索。筛选条件变化时重新调用接口并带上分页参数。这里有个细节我用ref声明筛选表单对象在onSearch方法里先手动重置currentPage为1否则从第5页筛选时可能会导致“当前页为空”的尴尬情况。报验单的新增和编辑用同一个el-dialog组件通过formType区分是新增还是编辑。表单校验用Element Plus的el-form的rules属性在提交前执行validate方法。后端虽然也做了校验但前端拦截能省去一次无谓的网络请求。前端还做了一个小优化表格里的状态字段直接映射为el-tag标签不同状态显示不同颜色例如待监理审核用警告色、已闭合用成功色、已驳回用危险色让处理人员扫一眼就能看清当前单子的状态在每天要处理几十上百条报验单的现场场景里这个细节能够切实提升操作效率。3.3 axios二次封装与请求拦截器axios的封装看起来是基础工作但封装得好不好直接影响全项目代码的整洁度。我封装了一个request.js统一配置baseURL和超时时间并在拦截器里做三件事第一请求拦截器从localStorage读取token加到请求头Authorization字段保证每个请求都携带身份凭证。第二响应拦截器统一处理业务码。后端返回固定格式{code: 200, msg: success, data: ...}前端判断code不等于200时弹出错误消息等于401时清理本地登录信息并跳转到登录页。这样前端页面代码里几乎不用做任何错误处理只需要关心成功分支。第三导出和下载大文件的场景需要特殊处理普通的responseType: json拿不到文件流需要显式设置responseType: blob并在拿到响应后根据Content-Disposition头解析文件名。单页面的逻辑清晰之后整个前端的复杂点基本就都集中在“表单校验”和“状态联动”这两类事情上了。3.4 前端权限控制与路由守卫前端也做了按钮级的权限拦截这部分的设计思路是后端返回当前用户的权限标识列表前端在路由守卫里根据路径匹配权限标识无权限则跳转403页面。按钮级权限用自定义指令v-permission实现比如只有监理工程师角色才显示“审核通过”按钮。// 自定义指令按钮权限控制 app.directive(permission, { mounted(el, binding) { const requiredPermission binding.value const userPermissions store.state.user.permissions || [] if (!userPermissions.includes(requiredPermission)) { el.parentNode el.parentNode.removeChild(el) } } })这里有个值得提醒的点前端权限控制只是用户体验层面不是安全边界。按钮隐藏只是“看不到”懂技术的人依然可以手动调用接口。所以后端接口的权限校验必须做到严格、完整不能依赖前端的隐藏逻辑。4. 数据库设计与MySQL8.0实践4.1 核心表结构与字段设计这里放一个相对精简的建表语句示例以报验申请单表为例展示字段设计思路CREATE TABLE inspection_order ( id bigint NOT NULL AUTO_INCREMENT, order_no varchar(32) NOT NULL COMMENT 报验单编号, ship_id bigint NOT NULL COMMENT 船舶ID, section_id bigint NOT NULL COMMENT 分段ID, inspection_type varchar(20) NOT NULL COMMENT 报验类型WELDING/COATING/DIMENSION/TIGHTNESS, work_content varchar(500) DEFAULT NULL COMMENT 报验工作内容, apply_user_id bigint NOT NULL COMMENT 申请人ID, supervisor_id bigint DEFAULT NULL COMMENT 监理工程师ID, status int NOT NULL DEFAULT 0 COMMENT 状态0待提交 1待审核 2待整改 3已闭合 4已驳回, apply_time datetime DEFAULT NULL COMMENT 申请时间, inspection_time datetime DEFAULT NULL COMMENT 报验时间, inspection_result varchar(20) DEFAULT NULL COMMENT 检验结果, reject_reason varchar(500) DEFAULT NULL COMMENT 驳回原因, version int NOT NULL DEFAULT 1 COMMENT 乐观锁版本号, deleted tinyint NOT NULL DEFAULT 0 COMMENT 逻辑删除标记, create_by varchar(50) DEFAULT NULL, create_time datetime DEFAULT CURRENT_TIMESTAMP, update_by varchar(50) DEFAULT NULL, update_time datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_order_no (order_no), KEY idx_section_status (section_id, status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;几个索引设计的细节说明一下。order_no是业务编号用于给用户看的单号必须唯一索引。idx_section_status是联合索引因为列表页最常见的查询场景是按分段加状态筛选这个索引能极大提升查询效率。apply_time字段带默认值CURRENT_TIMESTAMP通常在按时间范围筛选时建单独索引。从MySQL5.7升级到8.0之后建表时我统一用了utf8mb4字符集存储中文和生僻字完全没问题排序规则用utf8mb4_general_ci兼容性和排序行为都稳定。MySQL8.0默认就是utf8mb4不会出现个别字符乱码的情况。4.2 复杂报表的SQL优化技巧船舶监造的周报、月报往往是领导层最关注的页面报表里有各船型的建造进度、一次报验合格率、问题整改及时率等指标。这些统计SQL如果写得不好几万条数据就能把数据库拖到响应几秒钟。这里分享一个用MySQL8.0窗口函数统计“各船型月度一次报验合格率”的SQL示例SELECT ship_name, DATE_FORMAT(inspection_time, %Y-%m) AS month, COUNT(*) AS total_count, SUM(CASE WHEN inspection_result PASS AND try_count 1 THEN 1 ELSE 0 END) AS first_pass_count, ROUND(SUM(CASE WHEN inspection_result PASS AND try_count 1 THEN 1 ELSE 0 END) / COUNT(*), 4) AS first_pass_rate FROM ( SELECT s.ship_name, io.inspection_time, io.inspection_result, ROW_NUMBER() OVER (PARTITION BY io.section_id, io.work_content ORDER BY io.apply_time ASC) AS try_count FROM inspection_order io JOIN ship s ON io.ship_id s.id WHERE io.status 3 ) t GROUP BY ship_name, month ORDER BY ship_name, month;这里的关键在于内层用ROW_NUMBER()给每个分段每项工作按申请时间排序找出首次报验记录。如果首次报验就通过计入一次合格否则即使后续整改通过也不算一次合格。以前这种统计逻辑要写子查询嵌套代码又长又难维护MySQL8.0的窗口函数一条SQL就解决了执行效率也远高于多层子查询。实际优化报表SQL时我的经验是先看清业务口径确定统计的逻辑基础再写SQL。很多慢查询不是SQL本身写得差而是统计口径不明确导致多次扫描大表。把口径理清楚配合合理的索引报表页的响应时间基本都能控制在1秒以内。4.3 数据初始化与演示数据准备项目交付时数据库脚本分为三份schema.sql建库建表、init_data.sql初始化基础数据角色、菜单、系统参数、demo_data.sql导入演示数据。演示数据做得足够真实对验收和演示的帮助非常大。我整理演示数据时模拟了一条船的完整建造过程从立项、分段切割、船体合拢、下水、试航到交付在计划表里写好了每个里程碑的计划日期和实际日期报验单里覆盖了各种状态已闭合的、待整改的、已驳回的都有整改单里附带了整改前后对比的说明和图片路径。这样系统交付后客户一打开系统看到的不是空页面而是非常饱满的真实业务场景对理解系统价值帮助特别大。5. 部署过程与文档配套从源码到上线5.1 本地环境搭建完整步骤整套系统在开发环境跑起来按部就班也就三个步骤第一步初始化数据库。创建数据库ship_supervision后依次执行schema.sql和init_data.sql脚本。这里强调一下MySQL8.0的认证插件和旧版本不同。如果客户端工具连接提示认证插件错误需要在MySQL配置文件的[mysqld]部分添加default_authentication_pluginmysql_native_password或者创建用户时指定IDENTIFIED WITH mysql_native_password BY 密码。这个坑在MySQL8.0初装阶段特别常见。第二步启动后端。用IDEA打开后端项目等待Maven下载依赖后修改application.yml里的数据库用户名为本机账号再启动ShipSupervisionApplication主类。后端默认跑在8080端口启动成功后访问http://localhost:8080/api/health返回{code:200,msg:success}就算正常。第三步启动前端。在ship-supervision-web目录下执行npm install npm run dev前端默认跑在5173端口。由于前后端端口不一致需要在vite.config.js里配置代理把/api前缀请求转发到后端8080端口server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }这个代理配置如果不写前端请求会出现跨域报错那是开发阶段最常见的拦路虎。生产环境部署时我更推荐用Nginx直接托管前端静态文件同时配置反向代理指向后端服务一套Nginx配置搞定静态资源服务和接口转发。5.2 项目文档包含哪些核心内容这套系统源码里附带的文档我建议拿到源码后优先精读这几份架构设计说明文档详细描述了系统的整体架构图、模块划分、技术选型理由帮助接手人快速理解全局约20页。数据库设计文档包含25张核心表的字段说明、ER关系图、索引设计说明。这是后续做二次开发最常用的资料改表结构时对照文档能避免漏改关联表。接口API文档每个接口的请求方法、参数说明、返回示例都整理得很完整。前端对接时不用翻代码直接对着文档写调用逻辑即可。部署运维手册从服务器环境要求、JDK版本、MySQL版本、Nginx配置到部署步骤一步步截图说明。这份手册对运维人员最友好照着做基本就能完成私有化部署。5.3 生产环境部署要点生产环境部署比开发复杂不少有几个前置检查和优化项非常关键。首先JDK版本务必用JDK8或JDK11的较新补丁版本SpringBoot2对这两个版本兼容性最好。我用JDK8和JDK11分别测试过整体稳定性没有明显差异但如果用到一些高版本Java特性就推荐JDK11。其次MySQL8.0的配置文件需要根据服务器资源做适量调优。默认配置适合开发环境生产环境建议把innodb_buffer_pool_size设置为物理内存的60%左右max_connections适当调大。OOM问题在Java后端常见生产环境启动后端时建议在启动脚本里显式指定堆内存参数java -Xms512m -Xmx1024m -jar ship-supervision.jar --spring.profiles.activeprod第三Nginx配置里要重点设置上传文件大小限制。图纸文件动辄几十MB默认的client_max_body_size 1m会导致大文件上传直接报413错误。我配置成了一个合理的值server { listen 80; server_name your-domain.com; client_max_body_size 100m; location / { root /opt/ship-web/dist; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }部署时还顺手做了一个监控检查写了一个简单的Shell脚本每隔30秒检查后端进程是否存活挂掉就自动重启并记录日志。虽然不够精细但对这套系统的稳定性保障非常有用。6. 常见问题与排查技巧实录6.1 连接MySQL8.0时报时区错误这是新手首发遇到率最高的问题。报错信息类似The server time zone value й׼ʱ is unrecognized or represents more than one time zone.原因很简单MySQL8.0的JDBC驱动要求明确指定时区。解决办法是在application.yml的JDBC URL最后追加serverTimezoneAsia/Shanghai或者干脆在MySQL连接初始化时执行SET GLOBAL time_zone 8:00。个人建议两种都做后端配置是代码层面的保障MySQL全局时区是数据层面的统一双保险更稳妥。6.2 MyBatis-Plus分页失效问题MyBatis-Plus的分页插件需要手动配置拦截器如果忘记配置分页查询会返回全量数据前端翻页完全失效。很多人以为MyBatis-Plus开箱即用但分页恰恰是需要显式注册的。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }这个配置加好之后Page对象才能正常工作。顺便一提分页插件对流式查询、嵌套查询的兼容性有小概率出问题但如果业务SQL全部采用单表查询或简单关联查询基本不会踩到。6.3 文件上传413与文件路径权限问题上传报错413基本都是Nginx的client_max_body_size没有调大把配置文件里的相应参数调大再重载配置即可。另外一个隐蔽问题是文件上传成功但下载时报404多半是上传目录的绝对路径在Linux和Windows下写法不一致造成的。我在后端把所有文件路径都改为动态获取不能写死盘符路径。部署时如果文件存储在/opt/upload/目录Nginx的location需要指向该路径同时确保运行后端的用户对目录有读写权限。我曾经踩过工作目录权限不足导致文件无法写入的坑排查了半天才发现是目录属主不是当前用户。6.4 前后端联调时的PID属性丢失问题Fastjson和Jackson在序列化时如果实体类用了类似Long类型的大数值ID且前端JavaScript精度不够会出现ID后几位变成0的情况导致后续操作找不到对应记录。经典解决方案是在后端的Id字段上增加JsonSerialize(using ToStringSerializer.class)把Long序列化为字符串。这个坑在ID超过JavaScript安全整数上限之后就一定会踩提前预防比事后改代码成本低得多。6.5 报表数据不准的排查思路如果发现报表筛选结果和实际对不上我的排查思路是三步走第一步先核对SQL的统计口径和业务口径是否一致比如“一次报验合格”的定义是首次报验通过还是任意首次尝试通过第二步检查查询语句是否遗漏了deleted 0条件逻辑删除导致脏数据混入统计第三步检查业务数据本身是否有历史遗留的不合格数据比如演示数据里有些单据的数据不完整。绝大多数报表异常都是这三个原因之一找到根因后修正SQL或清洗数据问题基本都能解决。7. 实操体会与项目扩展方向系统上线运行以来最有价值的体验是重流程、重记录的系统稳定性比花哨功能更重要。船舶监造这类业务场景下用户真正高频使用的功能其实就是报验单录入、查询、审核、整改闭环、进度台账把这几条主链路打磨顺畅系统就已经成功了。我见过一些同类系统功能堆了一大堆最后用户日常用的还是最核心的那几个页面其余花哨功能反而是负担。基于这套系统后续还可以朝几个方向扩展。一是增加移动端适配现场监理拿着平板或手机在现场报验时能直接拍照上传省掉回办公室补录的步骤这个场景在船厂现场非常刚需。二是引入消息通知机制报验单提交后实时推送给对应监理整改超期时自动提醒能有效缩短业务流转周期。三是接入电子签章和CA认证让报验单、检验记录在线上具备法律效力彻底替代纸质签字。如果业务规模扩大人手增多还可以把单机版平滑升级为集群部署引入Redis缓存和MQ异步处理减轻数据库压力。最后再分享一个压箱底的小经验做这类业务系统一定要在项目早期就缠着业务人员梳理清楚状态流转的所有分支。状态机的设计一旦成型后期改动的成本非常高。我在这个项目里为报验单的每个状态转换都写了单元测试确保所有合法路径和异常分支都在控制之中。这个习惯帮我避免了很多次“改一个状态导致另一个流程卡死”的连锁线上事故。如果你正在计划做类似的监造或项目管理系统先把业务流程图烂熟于心再动手写代码这比选什么技术栈都重要。