1. 需求拆解这套系统到底要解决什么问题“居民小区物业报修管理系统”这个题目第一眼看上去像课程设计模板但它其实很贴近实际业务。真正做过小区物业信息化的人会知道报修不是简单的“提交表格-管理员改状态”两层结构而是一条完整业务链业主发现问题、提交报修、物业客服审核派单、维修工接单、上门处理、业主确认结果、评价反馈、工单关闭。任何一个环节断掉都会导致“报了没人管”的投诉这也是物业系统口碑崩坏的常见原因。我接手这个项目时第一件事不是打开IDEA建工程而是找物业的实际管理者聊清楚流程。某物业公司的客服主管告诉我他们最痛的不是没记录而是工单状态更新靠微信群和口头传达月底统计报表全靠手工整理维修工的绩效考核没有数据支撑。所以这套系统真正的价值点在于让报修工单有状态、有责任人、有耗时统计、有评价闭环。只有先把这个业务模型想清楚后面的表结构和接口设计才有依据。适合看这篇文章的人我大致分成三类准备做毕业设计但想把项目做得有深度的学生刚入行的后端开发想了解全栈业务流程的初学者以及想给小区或小公司做信息化系统但没找到合适参考的从业者。文章会从需求、表结构、后端接口、前端交互、部署排查这条线讲全不会只停留在“怎么建个项目跑起来”的层面。1.1 四类角色和核心场景把业务拆开看系统里有四类参与角色业主、物业客服、维修工、系统管理员。业主是报修发起方关心“什么时候有人来处理”物业客服是调度中心负责审核报修单并派给合适的维修工维修工是执行方关心“今天有哪些单子、都在哪个位置”管理员则站在更高维度看整体工单数量、超时情况、维修工绩效。角色对应的核心场景我用一张表梳理角色核心场景系统要做的事典型诉求业主提交报修、查看进度、确认结果、评价报修登记、状态可见、结果回执不被遗忘、进度透明物业客服审核、派单、跟踪、回访待办列表、派单操作、催办提醒快速定位责任人维修工接单、上门维修、填写处理结果工单列表、状态更新、费用登记查看分配任务、反馈结果管理员统计、权限管理、基础数据维护数据报表、用户管理、字典管理考核有依据、数据可追溯这个拆解决定了系统的功能边界。很多项目失败在功能堆砌比如业主端做了公告、缴费、投诉维修端做了考勤打卡结果核心的报修链路反而做得粗糙。我的建议是第一版只把报修主链路做扎实公告、投票这类功能作为后续迭代避免开发资源被稀释。1.2 非功能性需求同样影响设计除了功能需求有三项非功能性约束直接影响技术方案选型。第一是并发量。单个小区住户一般在几百到几千户就算高峰期同时在线一百人QPS也不会超过两位数。这意味着系统不需要复杂的分布式架构一台普通服务器加一个关系型数据库完全够用。我见过有人给这种项目引入微服务和消息队列属于典型的过度设计。第二是数据一致性的要求。报修单的派单动作涉及多人同时操作比如客服A和客服B同时点“派单”或者维修工在自己手机端刷新页面后重复接单系统必须保证同一个工单只能被成功派发一次。处理这个问题需要数据库层面加强约束比如准更新语句配合受影响行数判断。第三是移动端的使用场景。业主提交报修很可能是通过手机浏览器或者微信打开H5页面维修工在现场也需要用手机查看工单详情和更新状态。所以前端不能只做PC后台还得做适配移动端的页面。如果直接做两个独立前端会加大工作量我的选择是做成响应式布局用同一套Vue代码适配不同屏幕宽度。2. 技术选型为什么是Vue3加Spring Boot组合这套技术栈在2024年来看属于务实且成熟的组合。前端Vue3配Element Plus是当前中后台开发的常见方案后端用Spring Boot则几乎成了Java Web默认选项。真正值得聊的不是选什么而是为什么这样选以及选完之后的落地细节。2.1 前端骨架Vue3组合式API的工程化优势Vue3相对Vue2最大的变化是组合式APIComposition API。拿报修工单列表页举例Vue2的写法是把数据放data里、方法放methods里逻辑一多就会显得分散。组合式API允许按业务维度组织代码比如useRepairOrder这个组合函数里可以同时维护列表数据、分页参数、筛选条件和刷新方法不同页面的公共逻辑可以抽出来复用。我对项目的工程结构做了分隔src目录下按api、router、stores、views、composables五个模块组织。api目录集中放请求方法与后端的接口一一对应stores目录放用户登录信息和菜单权限的全局状态composables目录放可复用的业务逻辑比如usePagination封装分页逻辑useFileUpload封装图片上传逻辑。这样就算以后从两个人开发扩展到五个人开发也不会出现命名冲突和逻辑纠缠。组件库方面Element Plus的成熟度足够覆盖表格、表单、弹窗、标签页这些后台常用组件文档齐全社群案例多遇到问题基本能搜到答案。移动端业主页面我额外用了Vant的少量组件比如底部导航和表单控件但整体仍以响应式布局为主没有拆成两个独立项目。2.2 后端骨架Spring Boot的分层边界后端使用Spring Boot 2.x版本配合MyBatis Plus作为持久层框架。Spring Boot带来的最大收益是自动配置和起步依赖省去了大量XML配置时间。分层上我坚持了常规的controller-service-mapper三层但很多同学容易犯的错是把业务逻辑写进Controller。比如“派单”这个动作正确的做法是Service层提供派单方法并加事务注解Controller只负责接收参数、校验权限、调用服务、返回统一结果体。MyBatis Plus的选型理由很直接单表操作不用写SQL自带分页插件代码生成器可以快速生成实体和Mapper接口对字段填充创建时间、更新时间也有内置方案。虽然网上有人说MyBatis Plus是“半自动ORM不够高级”但在这个体量的项目里它的开发效率优势明显大于灵活性损失。需要复杂多表联查的时候再手写SQL和结果映射也不迟。补充一点很多课程项目喜欢把Controller、Service、Mapper写成接口加实现类的双份结构理由是“规范”。我实际开发中除非有明确的AOP代理或多实现需求否则直接写类而不是接口代码量更少阅读和调试也更轻松。规范要服务于可维护性而不是为了看起来规范而增加无用层。2.3 中间件选型MySQL加Redis的经典搭配数据存储上MySQL负责所有业务数据落库Redis负责缓存和临时状态。缓存的重点对象是数据字典、公告信息和业主常用的小区配置数据这些数据读取频率高、修改频率极低非常符合缓存场景。实际上这个项目的实时性需求并不强工单状态变化属于低频事件不需要引入WebSocket做实时推送。业主端查看进度用轮询就够了比如进入工单详情页后每隔10秒拉一次最新状态用户感知不到延迟开发成本却低很多。线程安全、连接池满这些问题在单机低并发场景下也几乎不会遇到中午十二点业主集中查看工单时的并发量完全在普通配置的承受范围之内。3. 数据库设计工单表就是系统的脊椎数据库设计的好坏直接决定后续开发愉快程度。我见过有人把报修单设计成只有“标题、内容、状态、时间”四个字段的极简表结果做到派单功能时发现没有维修工ID字段做到评价功能时发现没法存评分反复改表结构消耗了大量时间。究其原因是没有从业务链路出发设计表。3.1 核心表结构与字段说明我的方案总共设计了八张表用户表、角色表、小区房屋表、报修单表、报修详情处理表、评价表、通知公告表、数据字典表。最重要的就是报修单主表和详情处理表之间的关联。报修单表的关键字段包括报修单号、报修类型ID、描述文字、图片路径、房屋ID、报修人ID、状态、期望时间、分配维修工ID、派单时间、派单人ID、完成时间、费用金额、紧急程度。详情处理表则记录每一次操作痕迹比如谁在什么时间将状态从“待派单”改成了“已派单”附带操作备注。这个设计相当于给工单提了一条审计轨迹后期查“这个单子到底怎么回事”时有据可查。核心建表片段如下CREATE TABLE repair_order ( id BIGINT PRIMARY KEY AUTO_INCREMENT, order_no VARCHAR(32) NOT NULL COMMENT 报修单号, repair_type VARCHAR(50) NOT NULL COMMENT 报修类型水电/门窗/设备等, description VARCHAR(500) NOT NULL COMMENT 问题描述, image_urls TEXT COMMENT 图片路径多个用逗号分隔, house_id BIGINT NOT NULL COMMENT 房屋ID, owner_id BIGINT NOT NULL COMMENT 报修人ID, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待审核 1待派单 2已派单 3维修中 4待确认 5已完成 6已取消, urgency_level TINYINT NOT NULL DEFAULT 1 COMMENT 紧急程度1普通 2紧急 3特急, expect_time DATETIME COMMENT 期望上门时间, assignee_id BIGINT COMMENT 维修工ID, assign_time DATETIME COMMENT 派单时间, assign_by BIGINT COMMENT 派单操作人ID, finish_time DATETIME COMMENT 完成时间, cost_amount DECIMAL(10,2) COMMENT 维修费用, remark VARCHAR(200) COMMENT 备注, create_time DATETIME NOT NULL, update_time DATETIME NOT NULL, KEY idx_order_status (status), KEY idx_order_assignee (assignee_id), KEY idx_order_owner (owner_id) );3.2 状态字段用数字枚举原因有三个状态字段设计成TINYINT数字而不是直接存“待审核”“已派单”这样的中文字符串原因一是存储空间更小二是避免出现“待审核”和“待審核”这种不统一数据三是状态流转时用数值比较更可靠。可读性通过代码中的枚举类来保证前端拿到数字后映射成中文标签展示。状态机定义成七种0待审核、1待派单、2已派单、3维修中、4待确认、5已完成、6已取消。有些项目只做四种状态但我建议保留“待审核”和“待派单”这两个独立阶段。虽然小物业公司可能接到报修单后直接派给维修工审核只是走过场但把审核动作独立出来方便以后接入更严格的审核规则比如紧急报修必须审核后加急派送。维修工“接单”与客服“派单”设计成同一动作即状态从1流转到2时同时写入assignee_id。如果是抢单模式则是维修工自己点接单如果是指派模式则是客服选择维修工后系统自动通知。我实现的是两种模式兼容客服可以直接指定维修工也可以把工单放入公共池让维修工自动抢单。抢单的并发控制后面专门讲。3.3 数据冗余与索引取舍报修单表里冗余了业主的手机号和房屋编号虽然可以通过JOIN关联用户表查出来但工单列表和详情页是读取频率最高的接口每次都JOIN三张表不如冗余一下。代价是如果业主改了手机号需要同步更新冗余字段。考虑到业主手机号很少变动这个取舍是划算的。同样道理报修单详情页展示维修工名字时也可以冗余一个assignee_name字段。索引方面报修单表只建了status、assignee_id、owner_id三个普通索引加主键索引。这个体量的表在百万行以内单索引完全够用不需要考虑联合索引和覆盖索引的复杂优化。查询最常用的场景是“按业主查自己的单”和“按维修工查待办”这两个查询条件对应了owner_id和assignee_id的索引。真到了千万级数据量那是系统模型需要重构的时候了现在提前优化反而增加维护成本。4. 后端核心接口从登录鉴权到派单防并发后端接口设计遵循RESTful风格统一返回结构是Code、Message、Data三字段的JSON对象。所有接口都走统一前缀/api登录接口不需要鉴权其余接口通过拦截器校验JWT Token再从Token里解析用户ID和角色。这个方案简单可靠比整合Spring Security全家桶更适合这个体量的系统。4.1 接口清单与权限矩阵接口按模块划分粗略估算有三十个左右。核心接口我用表格列出来方便大家对照设计自己的项目功能模块接口路径请求方式可用角色说明认证/api/auth/loginPOST全部登录返回Token和用户信息认证/api/auth/logoutPOST登录用户退出登录报修/api/repair/orderPOST业主提交报修单报修/api/repair/order/pageGET全部分页查询按角色默认过滤数据报修/api/repair/order/detailGET全部查询详情及处理记录派单/api/repair/order/assignPOST客服、管理员指派维修工抢单/api/repair/order/grabPOST维修工公共池抢单处理/api/repair/order/processPOST维修工填写维修结果和费用确认/api/repair/order/confirmPOST业主确认完成并评价取消/api/repair/order/cancelPOST业主、客服取消工单统计/api/stats/overviewGET管理员、客服工单数、超时数、平均处理时长用户/api/user/pageGET管理员用户管理列表字典/api/dict/listGET登录用户获取数据字典权限控制的核心思想是“数据可见范围按角色收缩”。业主只能查到自己名下的报修单维修工只能查到分配给自己的或者公共池的单客服和管理员可以看到全量。这个过滤逻辑写在Service层而不是SQL层手写防止前端传参绕过。4.2 登录鉴权的完整链路登录流程是这样的用户提交手机号和密码后端校验通过后生成JWT TokenToken里放入userId、roleId、nickname三个明文信息设置有效期七天。前端的Axios拦截器在每个请求头里带上Authorization字段后端拦截器解析Token解析失败或过期则返回401状态码前端收到401后清除本地缓存并跳转登录页。密码存储用的是BCrypt加密这是Spring Security自带的开源算法。BCrypt自带随机盐相同密码每次加密结果都不同比MD5加固定盐安全性高不少。这个项目我用的是Spring Security的PasswordEncoder实现类但并没有引入整个Spring Security框架避免把简单项目的配置复杂度拉高。拦截器按路径前缀匹配需要特别注意放行预检请求。前后端分离模式下浏览器跨域请求会先发OPTIONS预检拦截器如果校验了OPTIONS请求就会导致跨域报错。处理办法是判断请求方法为OPTIONS时直接放行。这个细节困扰过不少初学者排查起来还比较隐蔽。4.3 派单与抢单的并发控制派单和抢单是系统里并发风险最高的两个接口。客服A选中工单1派给维修工甲客服B同时选中工单1派给维修工乙如果代码是“先查询状态再更新状态”两条请求都会查询到状态为1待派单然后先后执行更新后执行的覆盖先执行的造成重复派单。解决方案是直接用一条原子更新语句完成状态校验和变更代码如下boolean success updateOrderStatusWithCondition( orderId, currentStatus, targetStatus, assigneeId);对应SQL的简化形式是UPDATE repair_order SET status 2, assignee_id #{assigneeId}, assign_time NOW() WHERE id #{orderId} AND status 1关键在于WHERE条件里的status 1。如果更新操作影响的行数等于1说明抢单成功如果影响行数为0说明工单状态已经被别人改了当前操作失败。通过数据库行锁和受影响行数判断从根本上避免并发覆盖问题。需要注意的是这条SQL要在事务里执行否则“状态变更成功但操作日志写入失败”会让数据对不上。维修工抢单接口的分流也需要在应用层控制不能两个维修工同时抢到同一个单。用Redis的SETNX命令加分布式锁也可以但这里用数据库条件更新更直接锁的粒度更小而且不依赖额外组件。4.4 状态流转校验的集中管理状态不能随便跳比如“待审核”不能直接变成“已完成”“已取消”的单也不能重新派单。我在Service层封装了一个状态机校验方法传入当前状态和期望变更后的状态返回是否允许流转。状态机校验和业务动作绑定避免写业务方法时遗漏校验。举例来说工单提交审核后状态是0客服审核通过后转入1派单从1转2维修工接单后开始维修转3维修工填写结果后转4待确认业主确认后转5取消操作只能发生在0、1、2、3这几个非终态阶段。每次状态变更都要写一条处理记录到详情表形成完整操作轨迹。状态机校验统一使用枚举定义后续扩展“维修退回”这类状态时只需改校验类和枚举类不影响其他业务。5. 前端核心实现页面交互与服务端配合前端项目使用Vue3加Vite构建工程初始化用create-vue脚手架组件库按需引入Element Plus。整体页面包括登录页、业主端首页、报修列表页、报修表单页、工单详情页、客服工作台、维修工工作台、数据统计页、用户管理页一共九张核心页面。5.1 请求封装与统一状态处理前端请求封装是工程质量的分水岭。我的axios封装做了四件事统一拼接API地址、自动携带Token、统一处理HTTP错误码、截获业务错误码并弹出提示。以401为例后端返回401时前端不做页面跳转而是用消息提示“登录已过期请重新登录”同时触发路由跳转到登录页并附带redirect参数登录成功后再跳回原页面。除了基础封装还有一层更实用的处理逻辑业务码为429时说明接口限流提示用户操作太频繁业务码为500时把后端返回的Message直接展示给用户不暴露堆栈信息。这样前端代码里很少需要写try-catch大部分异常都在拦截器统一消化业务代码里只需要关心正常数据流。const service axios.create({ baseURL: /api, timeout: 10000 }); service.interceptors.request.use(config { const token localStorage.getItem(token); if (token) { config.headers.Authorization Bearer token; } return config; }); service.interceptors.response.use( response { const res response.data; if (res.code 0) { return res.data; } if (res.code 401) { router.push({ path: /login, query: { redirect: router.currentRoute.value.fullPath } }); return Promise.reject(new Error(未登录或登录过期)); } ElMessage.error(res.message || 请求失败); return Promise.reject(new Error(res.message)); }, error { ElMessage.error(网络异常请检查网络连接); return Promise.reject(error); } );5.2 报修列表的分页、筛选与刷新策略报修列表页是全系统最复杂的页面面向不同角色展示不同数据。复用同一个列表组件通过传入角色类型来控制默认筛选条件业主默认带上ownerId参数维修工默认带上assigneeId或公共池条件客服和管理员默认不带额外条件而可以手动筛选状态和时间范围。分页参数用页码和每页条数两个变量管理每次请求把这两个值传给后端。表格组件做了两项优化一是当前页操作完成后自动刷新当前页数据而不是跳回第一页比如业主确认工单后列表还停留在当前页面二是筛选条件变化时重置页码到第一页避免用户在第5页筛选后看到空数据。状态变更后的刷新策略值得单独讲一下。如果是详情页操作后返回列表列表页需要感知数据变化。最稳妥的做法是列表页在onMounted生命周期重新拉取数据因为Vue组件切换页面时会触发重新挂载。但是如果只是弹出框里改状态页面本身没有重新挂载就需要在弹出框确认回调里主动调用列表的查询方法。这两种策略配合使用基本能覆盖所有数据刷新场景。5.3 移动端的适配细节业主提交报修时用手机打开页面的频率非常高所以报修表单页做了移动端优先的适配。表单控件在小屏幕上尽量全宽展示图片上传支持压缩限制单张不超过两兆。Element Plus表单在移动端默认有左右留白我通过CSS覆盖了容器宽度让控件填满屏幕宽度减少误触。移动端列表页还做了一件小事下拉刷新。直接借用原生touch事件实现下拉到指定距离时触发刷新这个功能对维修工在户外查看待办列表非常实用。初次实现时不建议引入复杂的下拉刷新库原生事件加节流就能实现平滑效果代码量控制在五十行以内。6. 安全方案与性能优化不能只会写增删改查很多课程设计项目做完能跑就验收了但真实场景下安全和性能是不能回避的。尤其是报修系统涉及业主家庭住址、手机号、维修工个人信息数据泄露责任不小系统的安全设计必须到位。6.1 越权漏洞必须做的属主校验最常见的漏洞是水平越权即普通用户可以操作不属于自己的数据。假设接口设计成GET /api/repair/order/detail?id10086业主登录后直接修改请求里的ID值就能查看到其他业主的报修单详情。解决办法是在Service层做属主校验查询详情时后端根据Token解析当前用户ID如果角色是业主且报修单的ownerId不等于当前用户ID直接返回无权限。同样校验也用在状态变更接口上。业主只能确认自己的报修单维修工只能接单和更新分配给自己的工单。这些校验不能依赖前端路由或页面按钮隐藏因为攻击者完全可以绕过前端直接调用接口。我把权限校验统一封装成私有方法在所有涉及业务数据的Service方法第一行调用。6.2 密码安全与日志脱敏密码存储使用BCrypt加密任何地方都不能把明文密码写入日志。用户手机号、身份证号、家庭详细地址都属于敏感数据日志输出时必须脱敏比如手机号只显示前三位后两位中间用星号代替。这个习惯来自真实生产环境的教训曾有开发为了排查问题在日志里打印了完整用户信息日志文件被运维同学误传到公共网盘差点引发隐私事故。后端统一返回给前端的用户信息也要做字段裁剪。登录接口返回用户对象时不要直接返回数据库实体类而是构建一个不包含密码字段的DTO。MyBatis Plus的实体类上也可以加了JsonIgnore注解把密码字段忽略掉双保险更稳妥。6.3 深分页优化与N1查询问题报修单列表做到几千条数据以后默认分页查询会越翻越慢原因在于MySQL的LIMIT深分页会扫描大量无效行。比如LIMIT 10000, 10数据库要从第一行扫描到第10010行再取最后10行效率很低。优化方案是记录上一页最后一条记录的主键或时间戳下一页查询带上这个游标条件。这个改动只影响列表接口不影响分页组件显示。N1查询问题也属于高频坑查询报修单列表时如果每条工单都要再查一次业主姓名和房屋信息一百条工单就会产生一百零一条SQL。解决手段是用MyBatis Plus的批量查询方法或SQL联查一次查出列表需要的关联字段。这属于性能优化别人按F12看到你接口响应只有几百毫秒就很靠谱了。6.4 Redis缓存数据字典与公告数据字典诸如报修类型、紧急程度、小区楼栋信息几乎每个接口都要用到。每次查MySQL没必要我启动时把字典表全量加载到Redis用Hash结构存储Key是字典类型Field是字典项编码Value是中文描述。字典变更时主动删除缓存键让下次查询重新加载。公告信息采用相似策略但设置了五分钟后过期的短缓存这样管理员改了公告内容后最多五分钟客户端就能看到新内容不需要手工清理缓存。缓存粒度按业务场景区分比一刀切地设置一天过期时间更合理。7. 常见问题与排查实战我踩过的坑和解决方案开发过程中遇到的问题是很好的学习素材我把自己和身边人踩过的典型问题整理成一节方便大家排查时对照。这些问题分属并发、前端、部署三个层面每个都有实际场景支撑。7.1 派单并发导致重复指派现象客服A和客服B同时操作同一个工单最后工单显示的是B指派的维修工A明明也操作成功了。排查过程是先在日志里看两个请求的执行时间发现时间戳几乎一样又去查数据库更新记录发现两条UPDATE语句都执行成功了但后执行的覆盖了前一条。根源就是先查询再更新的时间窗口里有并发交叉。修复方式之前已经讲过用条件更新语句把状态校验和状态变更合并成原子操作。这条经验不仅适用于派单凡是“某个字段只能在特定状态下被修改”的场景都应该用类似方式处理不能依赖应用层的先查后改。代码审查时把这个点列为必查项。7.2 前端列表数据更新后界面不刷新现象业主在报修详情页确认完成后返回列表页列表里的状态还是“维修中”。排查后发现详情页和列表页是兄弟路由返回列表时组件从缓存中恢复并不会重新执行onMounted。这个问题在Vue Router的KeepAlive场景下特别常见。修复思路是列表页配合onActivated生命周期重新拉取数据或者在详情页操作成功时通知列表页刷新。我最终采用onActivated方案因为它是全局生效的不需要在页面之间传递事件代码侵入最小。需要注意onActivated和onMounted同时存在时首次进入页面会执行两次查询需要做一次变量标记去重。7.3 响应式数组直接赋值丢失页面更新现象列表页的数据是通过ref声明的响应式数组查询接口返回后直接赋值给这个数组页面数据变了但表格没有重新渲染有时甚至出现页面假死。根源在Vue3的响应式代理对数组下标操作的兼容性问题直接整体赋值会破坏原来的响应式链接。修复方式是把数组赋值操作改为计算属性或者使用reactive包裹整个对象推荐写法是定义result为reactive({ list: [], total: 0 })然后通过result.list response.list赋值这样代理结构不会变化。这个坑很多Vue2转Vue3的同学会遇到写代码时形成固定的数据定义习惯就能避开。7.4 跨域配置问题导致接口访问不了现象本地开发时前端页面能打开但接口全部报错浏览器控制台提示CORS错误。排查后发现前端开发服务器运行在5173端口后端运行在8080端口跨域请求被浏览器拦截。解决办法有前端代理和后端跨域配置两种。前端代理方案是通过Vite配置server.proxy把/api开头的请求转发到8080端口好处是开发环境不需要后端开启跨域生产环境交给Nginx统一处理。后端跨域配置用CrossOrigin注解或者实现WebMvcConfigurer添加跨域映射。我在实际项目中同时保留了这两种方式但生产环境以Nginx反代为主后端跨域配置只在开发环境启用。7.5 中文乱码与时间时区问题现象部署到服务器后业主提交的报修描述出现乱码工单处理时长统计经常是负数。乱码根源在于MySQL连接串上没有指定编码格式解决办法是JDBC连接串加上useUnicodetrue和characterEncodingutf8参数。时区问题出现在MySQL连接串少了serverTimezoneAsia/Shanghai配置导致日期时间字段偏移八小时。这两个问题一次性配置到位能省掉后期大量排查时间。7.6 排查清单速查为了方便日常排查我把常见问题整理成一张速查表问题现象可能原因排查方向解决方案接口401Token过期或未携带检查请求头Authorization重新登录刷新Token接口500SQL异常或空指针查看后端日志堆栈定位具体报错行列表数据重复分页参数未重置检查当前页码筛选条件变化时重置页码前端请求404代理路径错误检查Vite配置修正proxy匹配规则图片加载不了静态资源路径不对检查Nginx映射配置alias或root路径处理时长为负时区偏移查看数据库时间设置serverTimezone8. 部署与验收从本地跑通到正式落地开发完成不代表项目结束部署和验收阶段同样重要。我把生产部署方案设计成前后端分离的标准结构后端打成Jar包运行在服务器上前端打包成静态文件交给Nginx托管通过反向代理解决接口跨域问题。8.1 环境配置与打包后端用Maven打包前先确认多环境配置正确隔离。我用application-dev.yml和application-prod.yml分别维护开发和生产环境配置共同部分放在application.yml。生产环境的数据库地址、Redis地址通过环境变量注入避免数据库密码写死在配置文件里提交到代码仓库。打包命令用mvn clean package -DskipTests跳过单元测试生成的Jar包放在服务器上通过java -jar命令启动。生产环境建议配置成systemd服务这样服务器重启后进程能自动拉起不用人工干预。前端打包用npm run build产物输出到dist目录整体上传到Nginx的html目录下。8.2 Nginx配置要点Nginx配置核心是解决静态资源托管和接口反向代理两个问题。静态资源托管时要注意Vue Router的历史模式不配置try_files的话刷新页面会出现404。反向代理重点是把/api开头的请求转发到后端服务的8080端口并设置合适的超时时间。server { listen 80; server_name your-domain.com; root /opt/repair-system/dist; index index.html; location / { 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; proxy_read_timeout 60s; } }8.3 验收清单与上线后的小优化验收时走三条完整链路业主提交报修、客服派单、维修工处理、业主确认这是一条客服取消工单、业主重新提交这是第二条管理员登录导出统计报表核对工单数量和状态分布这是第三条。权限边界测试要刻意尝试越权操作比如业主尝试访问维修工接口确认后端返回403。提一个容易忽略的点修理工单全流程加超时提醒如果派单后两小时还没有接单系统自动推送提醒给客服这个逻辑用Spring的定时任务实现代码量不大但上线后好评率非常高。体验上还有几处可以直接做的小优化报修提交成功后自动弹窗提示预计处理时间语气友好些工单状态变化时业主端页面顶部出现醒目的状态标签维修工在工作台看到“今日待办数量”的统计卡片心里有数。这些小细节不需要额外开发量但对用户感知的提升很明显。我的体会是这类系统做得让用户没意识到“这是个软件”才算合格。物业客服打开列表扫一眼就知道今天有几个急单维修工到现场拍照上传就算完成节点记录业主提交后不用打电话追问进度。做到这个程度核心不是炫技技术栈而是把业务流转理解到位再配合可靠的数据设计和扎实的前后端配合。这套项目的很多经验比如状态机控制、条件更新防并发、分环境部署换到其他管理系统一样适用。如果你手头正在做类似项目建议先拿纸笔画一遍业务链路再动手写代码整个过程会顺手很多。