简介面向计算机专业毕业设计学生与项目实战学习者这份小区物业管理系统源码采用Spring BootVueMySQL等技术栈涵盖业主管理、车位管理、小区管理、管理员管理并配套业主小程序端支持物业费缴纳、停车费缴纳、投诉建议、房屋保修、公告查看与身份绑定等场景。压缩包整体大小46.63MB共包含1011个文件其中Java后端源码、Vue前端页面、小程序WXML/WXSS、数据库SQL脚本及使用文档一应俱全PNG/JPG/GIF等图表资源方便界面预览XML/JSON/JS等配置与逻辑文件便于二次开发。项目为导师认可的高分毕业设计评审98分已有164人学习下载除了可直接运行的完整工程外还附有使用文档、环境搭建说明JDK8、MySQL5.1、Tomcat8与部署注意事项适合作为毕业设计、课程设计或期末大作业的参考蓝本也可用于快速上手Spring Boot与Vue的整合开发。1. 一个 Spring Boot 物业管理系统 zip 包里值得你关注的是什么拿到《基于spring boot的小区物业管理系统源码使用文档高分毕业设计.zip》这类包第一步不是急着解压而是先想清楚你缺的是一套能跑的代码还是一套能被答辩老师追问的完整逻辑大多数这类系统跑起来不难难的是把“业主、房屋、车位、账单、报修工单”这几个对象之间的关系讲明白再把“物业费怎么算”“工单状态怎么流转”在代码里落对。这篇笔记就围绕这两个点展开从选型、建表、核心功能落地到部署和论文对应关系。适合两类人正在做Java毕设的学生以及想快速搭一套小区物业管理后台做二次开发的业务开发。2. 技术选型与项目骨架为什么是 Spring Boot模块怎么拆2.1 Spring Boot 做物业系统比 SSH / SSM 强在哪如果这个项目是用 SSH 或 SSM 写的我现在写这篇笔记的语气会完全不一样要配一堆 XML、要管理各种 jar 包冲突、要手写事务代理。Spring Boot 把这一层全部收走了项目里的重点从“怎么把框架伺候好”变成了“物业业务本身长什么样”。对毕业设计而言这个转变非常关键因为论文的篇幅应该花在需求分析、数据库设计、核心流程上而不是讲 Spring MVC 的 DispatherServlet 怎么工作。Spring Boot 对这类“管理系统”最友好的几点是内嵌 Tomcat一段mvn spring-boot:run就能起服务application.yml一把梭配数据源、端口、日志Starter 依赖把 MyBatis、MySQL、校验、缓存全封装好pom 里加依赖就能直接用。第一个 Spring Boot 程序教学里那套RestController的写法在这里原封不动延续但你能接触到的东西会比 demo 深得多。2.2 标准模块划分与包结构这类小区物业系统的业务边界很清晰业主端和管理员端共用一套后端按功能域拆包。我在改这类项目时习惯按下面的结构组织答辩讲起来也顺com.example.property ├── controller # HTTP 接口层只做参数接收和结果封装 ├── service # 业务逻辑层账单计算、工单流转都在这里 ├── mapper # MyBatis 的 Mapper 接口 ├── entity # 数据库实体 ├── dto # 接口出入参对象避免直接暴露实体 ├── config # 拦截器、跨域配置、静态资源映射 ├── common # 统一返回结果、异常处理、工具类 ├── enums # 工单状态、账单状态等枚举 └── PropertyApplication.javacontroller 层别写业务这是个铁律。很多翻车的项目都是把“计算滞纳金”写在 controller 里后来要复用就只能复制粘贴。service 层才是这个系统的主要阵地尤其账单和工单的逻辑后面我会单独讲。2.3 最小依赖清单和启动配置如果你打算从零搭一个同款pom 里这几样基本就够了。注意我不写死版本号是因为 Spring Boot 2.x 和 3.x 的依赖坐标写法略有差异你在 IDE 里让 Maven 自己解析即可dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId /dependency /dependenciesMyBatis-Plus 在这个场景值得用单表 CRUD 不用写 SQLQueryWrapper直接查列表分页用Page对象。物业系统大部分接口都是单表查询加简单条件比如按楼栋查房屋、按业主查账单用 MyBatis-Plus 能省掉大量重复的 Mapper XML。application.yml里核心配置就三块数据源、MyBatis-Plus 驼峰映射、文件上传大小限制。下面是一个常见配置spring: datasource: url: jdbc:mysql://localhost:3306/property?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 servlet: multipart: max-file-size: 10MB max-request-size: 20MB mybatis-plus: configuration: map-underscore-to-camel-case: true global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0注意map-underscore-to-camel-case这个参数数据库字段一般是create_time实体属性是createTime不开驼峰映射的话每次查询都要起别名烦得很。逻辑删除字段也是我做这类系统必开的物业系统里业主、房屋、账单都不能物理删只能打标记后面避坑章节我会专门解释。3. 数据库设计物业系统的数据模型是论文的得分点3.1 核心表关系业主、房屋、车位、账单怎么挂很多毕设项目把业主和房屋设计成一对一关系也就是业主表里存一个room_id字段。这在真实小区里根本不成立谁家没个两套房或者一套房夫妻俩共同登记。答辩老师问到这种问题最容易让项目露怯。正确做法是业主表、房屋表独立中间加一张关联表记录入住时间、与业主关系产权人、家庭成员、租户。另一个容易乱的地方是账单。物业费是按月生成的每个房屋每个月产生一条账单记录所以账单表至少要有一个bill_month字段格式用2025-06这种而不是存一个时间戳。车位费、水费、电梯费可以都归入同一张账单表用fee_type区分这样前端展示“费用明细”就很简单不用每类费用建一张表。3.2 建表 SQL业主-房屋关联、账单、报修工单我直接给出三张最核心表的简化建表 SQL注释就是给论文的实体关系描述-- 房屋表 CREATE TABLE t_room ( id BIGINT PRIMARY KEY AUTO_INCREMENT, building_no VARCHAR(20) NOT NULL COMMENT 楼栋号如 3 栋, unit_no VARCHAR(20) COMMENT 单元号可选, room_no VARCHAR(20) NOT NULL COMMENT 房号, area DECIMAL(8,2) NOT NULL COMMENT 建筑面积物业费计算依据, owner_id BIGINT COMMENT 当前主要业主 id冗余字段方便列表展示, status TINYINT DEFAULT 0 COMMENT 0 未售 1 已入住 2 空置, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, deleted TINYINT DEFAULT 0 ) COMMENT 房屋表;deleted字段配合我在 2.3 里配置的 MyBatis-Plus 逻辑删除查询时自动过滤。owner_id这个冗余字段是有意保留的因为“这套房子现在属于谁”在绝大多数场景都是查询条件关联表只在需要查“一个业主名下所有房产”时才用得上。-- 物业费账单表 CREATE TABLE t_bill ( id BIGINT PRIMARY KEY AUTO_INCREMENT, room_id BIGINT NOT NULL COMMENT 房屋 id, bill_month VARCHAR(7) NOT NULL COMMENT 账单月份如 2025-06, fee_type TINYINT DEFAULT 0 COMMENT 0 物业费 1 车位费 2 水费, amount DECIMAL(10,2) NOT NULL COMMENT 应收金额, paid_amount DECIMAL(10,2) DEFAULT 0 COMMENT 实收金额, late_fee DECIMAL(10,2) DEFAULT 0 COMMENT 滞纳金, status TINYINT DEFAULT 0 COMMENT 0 未缴 1 部分缴纳 2 已缴清, pay_time DATETIME COMMENT 最后支付时间, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, deleted TINYINT DEFAULT 0 ) COMMENT 物业费账单表;账单表我单独给pay_time不给“缴费开始时间、结束时间”这种模糊设计。amount和paid_amount分开是支持“部分缴费”场景的基础。滞纳金不是账单金额的一部分它是独立计算出来的后面代码里会体现。-- 报修工单表 CREATE TABLE t_repair ( id BIGINT PRIMARY KEY AUTO_INCREMENT, room_id BIGINT NOT NULL COMMENT 报修房屋, owner_id BIGINT NOT NULL COMMENT 报修业主, category VARCHAR(20) COMMENT 报修类型水电、门窗、电梯, description VARCHAR(500) COMMENT 问题描述, image_url VARCHAR(255) COMMENT 现场照片, status TINYINT DEFAULT 0 COMMENT 0 待派单 1 处理中 2 待验收 3 已完成 4 已取消, assignee VARCHAR(50) COMMENT 维修工姓名, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, finish_time DATETIME COMMENT 完成时间, deleted TINYINT DEFAULT 0 ) COMMENT 报修工单表;3.3 金额和时间字段的三个约定这三个约定是我调这类系统调出来的血泪经验直接写进建表规范里最省事。金额一律用DECIMAL(10,2)任何情况下不用 float 和 double。float算钱会出现 19.99 存成 19.989999 这种问题页面展示、对账、导出 Excel 都会翻车。物业费计算涉及单价、面积、月份数乘除完必须用BigDecimal做构造时用字符串禁止new BigDecimal(0.1)这种从 double 转过来的写法。时间字段分两类create_time、update_time这类系统时间用DATETIME DEFAULT CURRENT_TIMESTAMP让数据库生成业务时间像缴费时间pay_time、工单完成时间finish_time由代码写入。原因很简单数据库默认时间只能表达“这行记录什么时候创建的”表达不了“这笔缴费发生在这个时刻”这种业务语义。账单月份的bill_month用VARCHAR(7)存2025-06格式不要用DATE类型。月份是一个“期间”概念而不是一个“时间点”后期做“查某季度所有账单”用字符串LIKE 2025-%或者LEFT(bill_month, 4) 2025都能直接处理比时间函数转换清爽太多。4. 关键功能落地从登录到报修工单状态机4.1 基于 JWT 的登录与权限拦截这类管理系统权限模型一般是两种角色管理员和业主。业主只能操作自己的房屋、自己的账单、自己的报修管理员管理全部数据。最简单的实现就是登录接口签发 JWTpayload 里带userId和role然后写一个 HandlerInterceptor 统一拦截。先看 JWT 工具类这段代码在所有 Spring Boot 项目里几乎是通用的Component public class JwtUtil { Value(${jwt.secret}) private String secret; Value(${jwt.expire}) private Long expire; // 单位毫秒 public String generateToken(Long userId, String role) { return Jwts.builder() .setSubject(String.valueOf(userId)) .claim(role, role) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() expire)) .signWith(Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8))) .compact(); } public Claims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8))) .build() .parseClaimsJws(token) .getBody(); } }secret放配置文件里不要在代码里写死。expire一般设 7200000两小时但这个系统如果业主端是网页可以放宽到 12 小时减少频繁重新登录的抱怨。拦截器的注册方式老项目和新项目写法不同Spring Boot 3 里很多配置迁移成了WebMvcConfigurer的实现类核心逻辑是一样的Configuration public class WebConfig implements WebMvcConfigurer { Resource private JwtInterceptor jwtInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(jwtInterceptor) .addPathPatterns(/api/**) .excludePathPatterns(/api/login, /api/register); } }注意拦截器只管“这个请求有没有带合法 token”角色权限的判断放在方法级别。可以用自定义RequireRole(admin)注解加 AOP 实现也可以简单地在需要管理员的接口里第一步做判断。毕业设计做到后者足够了答辩的时候能说清“为什么这么设计”比炫技更重要。4.2 物业费账单生成与滞纳金计算物业费账单是这类系统最能体现“业务逻辑”的地方也是论文里可以重点写的用例。按月生成账单核心逻辑是结算上个月所有未缴清的账单然后为当前月生成新账单。不能重复生成所以要有幂等控制。Service public class BillService { Resource private BillMapper billMapper; Resource private RoomMapper roomMapper; public void generateMonthlyBills(String billMonth) { // 先查这个月是否已经生成过防止定时任务重复执行 Long count billMapper.countByMonth(billMonth); if (count 0) { return; } // 查出所有在管房屋设定统一单价 ListRoom roomList roomMapper.selectList(null); BigDecimal unitPrice new BigDecimal(1.80); // 每平米单价实际从配置表读取 BigDecimal parkingFee new BigDecimal(120.00); for (Room room : roomList) { BigDecimal amount unitPrice.multiply(room.getArea()) .add(parkingFee).setScale(2, RoundingMode.HALF_UP); Bill bill new Bill(); bill.setRoomId(room.getId()); bill.setBillMonth(billMonth); bill.setAmount(amount); bill.setStatus(0); billMapper.insert(bill); } } }countByMonth这一步是幂等关键。定时任务用Scheduled(cron 0 0 0 1 * ?)每月 1 号凌晨跑一次或者提供一个管理员手动触发的接口。单价不要写在代码里正规做法是建一张配置表物业服务费调整时可以改配置重新生成。滞纳金计算比较容易被忽略。常见规则是超过缴费截止日每天加收应缴金额的千分之三。代码实现要点是“只计算当前时间到截止日期的天数”而且只对status 0的账单计算public BigDecimal calcLateFee(Long billId) { Bill bill billMapper.selectById(billId); if (bill.getStatus() 2) { return BigDecimal.ZERO; // 已缴清 } LocalDate deadline bill.getCreateTime().toLocalDate().plusDays(30); LocalDate today LocalDate.now(); if (today.isBefore(deadline)) { return BigDecimal.ZERO; } long overdueDays ChronoUnit.DAYS.between(deadline, today); BigDecimal rate new BigDecimal(0.003); return bill.getAmount().multiply(rate) .multiply(BigDecimal.valueOf(overdueDays)) .setScale(2, RoundingMode.HALF_UP); }这里有个隐藏坑createTime是账单生成时间拿它加 30 天当缴费截止日逻辑上成立但最好在账单表里加一个deadline字段生成账单时显式写入“本月 31 日”或“次月 20 日”这样规则更清晰迟交天数也不是从系统时间推断的。4.3 报修工单的状态流转与看板统计物业系统的报修流程是典型的状态机场景适合在论文里画一个状态图文字描述即可业主提交工单PENDING管理员派单给维修工PROCESSING维修完成待业主验收PENDING_CONFIRM业主确认通过FINISHED任何阶段都可取消CANCELED。代码层面用枚举约束状态尽量避免在 Service 里写裸数字public enum RepairStatus { PENDING(0, 待派单), PROCESSING(1, 处理中), PENDING_CONFIRM(2, 待验收), FINISHED(3, 已完成), CANCELED(4, 已取消); private final Integer code; private final String desc; RepairStatus(Integer code, String desc) { this.code code; this.desc desc; } public boolean canTransferTo(RepairStatus target) { // 只允许向后流转待派单 - 处理中 - 待验收 - 已完成 return this.code target.code; } }写状态流转逻辑时最大的坑是“跳状态”。比如业主提交后直接改成FINISHED数据库里没报错但流程语义乱了看板统计数据全是错的。所有状态变更走同一个方法方法内先canTransferTo校验这个细节放代码里答辩时能解释“状态机保证了流程严谨性”。业主端的看板统计一般要三个数待处理工单数、进行中工单数、本月已完工单数。直接用 SQL 聚合不需要代码做内存计算Select(script SELECT status, COUNT(*) AS cnt FROM t_repair WHERE room_id #{roomId} AND deleted 0 GROUP BY status /script) ListMapString, Object countByStatus(Long roomId);4.4 文件上传与图片映射报修工单要传现场照片业主头像要传图片。文件上传这块很多毕设项目栽跟头因为本地开发时把文件写到了项目根目录下的upload/文件夹一旦mvn clean或者打成 jar 包部署路径全乱。正确做法是把上传目录配置化然后映射成静态资源。先写作上传接口的核心方法RestController RequestMapping(/api/file) public class FileController { Value(${file.upload-dir}) private String uploadDir; PostMapping(/upload) public String upload(RequestParam(file) MultipartFile file) { if (file.isEmpty()) { throw new BizException(文件不能为空); } String originalFilename file.getOriginalFilename(); String ext originalFilename.substring(originalFilename.lastIndexOf(.)); String filename UUID.randomUUID().toString().replace(-, ) ext; String dateDir new SimpleDateFormat(yyyyMM).format(new Date()); File dir new File(uploadDir File.separator dateDir); if (!dir.exists()) { dir.mkdirs(); } String path dir.getAbsolutePath() File.separator filename; file.transferTo(new File(path)); // 返回可访问的相对路径 return /upload/ dateDir / filename; } }文件名用 UUID 重命名是必须的否则用户传一张1.jpg下一个人再传一张1.jpg就把前面的覆盖了。按月份建子目录是方便后面做存储清理也避免单目录文件过多。配置文件里对应file: upload-dir: /data/property/upload然后在配置类里把本地目录映射成 URL 访问路径Configuration public class StaticResourceConfig implements WebMvcConfigurer { Value(${file.upload-dir}) private String uploadDir; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/upload/**) .addResourceLocations(file: uploadDir /); } }file:前缀是文件系统路径映射的关键没有它Spring 会把/upload/当成 classpath 下的资源路径去查找结果就是图片 404。上传文件返回的 URL 直接存数据库字段前端只要拼上服务器 IP 和端口就能展示不需要额外接口。5. 常见问题排查5 个让物业项目翻车的细节5.1 房屋删除报外键约束删除失败现象管理员在后台删除一个空置房屋接口报错提示外键约束失败但明明没有业主关联这个房屋。原因外键约束指向了账单或工单等历史数据。物业系统里“房屋”和“账单”“报修”天然有强关联一条账单记录了某房屋某月的水电费房屋删除时会触发外键检查。设计师通常只在“当前是否被业主占用”层面做了限制忽略了历史数据引用。解决不要做物理删除改用逻辑删除。deleted字段置 1查询全部带上deleted 0条件。这种系统任何主数据都遵循这个规则业主可以“注销”房屋可以“标记拆除”账单只能“作废”但不能消失。否则后面的报表对账全对不上。5.2 缴费金额和手工账单对不上现象业主在 APP 端缴了物业费后台导出 Excel 统计的金额和业主手动算出的不一致总是差几毛几分。原因金额计算用了float或double。MySQL 里字段是DECIMAL(10,2)但实体类属性用的是DoubleMyBatis 查出来转成 Double 再参与运算精度损失在“金额相加”场景被放大十条账单加起来能差出好几块钱。解决实体类金额字段全用BigDecimal代码里任何涉及金额的乘除都用BigDecimal的方法综合修改量不大但收效立竿见影。排查时检查entity包下所有Double类型的金额字段换成BigDecimal后重新跑一遍对账接口。5.3 前端页面报表加载慢等待时间超 3 秒现象管理员打开“缴费统计”页面按季度展示各楼栋缴费率接口响应时间 3 秒以上数据量其实只有几千条。原因账单表按room_id查询但t_bill表没有建联合索引。前端统计接口通常这么查WHERE bill_month ? GROUP BY room_id没有索引就是全表扫描几千条数据不至于慢到不可用但一加上多表 JOIN 就很吃力。物业系统天然适合“按月查”批量导入历史数据后这个问题会立刻暴露。解决给核心表加上这组索引我用得最多的是这三条ALTER TABLE t_bill ADD INDEX idx_bill_month (bill_month); ALTER TABLE t_bill ADD INDEX idx_bill_room (room_id); ALTER TABLE t_repair ADD INDEX idx_repair_status (status);如果数据量超过十万行还可以考虑在(bill_month, room_id)上建联合索引覆盖大多数月结查询场景。5.4 Spring Boot 3 下的 JWT jar 包报错现象把项目从 Spring Boot 2.7 升级到 3.x原本写好的 JWT 工具类直接编译报错找不到javax.xml.bind.DatatypeConverter或者javax.annotation包。原因Spring Boot 3 的基础包从javax换成了jakarta老版本 JWT 库依赖 JAXB 模块JDK 17 以后默认不带这些运行时包了。很多人拿旧项目改 Spring Boot 3 时翻车就在这里。解决升级jjwt到 0.12.0 以上版本新版的 API 已经从Jwts.parser()变成Jwts.parserBuilder()签名方式也统一成了Keys.hmacShaKeyFor。可以直接用我 4.1 节代码里的写法编译和运行都没问题。如果还报错看 Maven 依赖树里是否有旧版javax.servlet-api冲突排除掉旧坐标即可。5.5 项目根目录下的doc/没有SQL脚本只有使用文档现象解压完 zip 包目录里只有源码、使用文档和说明找不到初始化数据库的 SQL 脚本启动项目后管理后台登录不了。原因部分毕业设计项目的 SQL 脚本不放在项目目录里而是写在使用文档末尾的“数据库配置”一节。如果使用文档是 PDF 或者图片复制里面的建表语句很容易因为格式问题执行报错。解决拿到 zip 包第一件事不是在 IDE 里打开项目而是先完整看一遍使用文档确认三样东西的位置SQL 脚本、配置文件中的数据库账号密码、前端是否另需构建。项目里没有sql/目录时在resources/db/下新建schema.sql和data.sql把建表语句和初始数据放进去再在application.yml里配spring: sql: init: mode: always schema-locations: classpath:db/schema.sql style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" /> Spring Boot小区物业管理系统：选型、建表、功能落地与避坑指南
简介面向计算机专业毕业设计学生与项目实战学习者这份小区物业管理系统源码采用Spring BootVueMySQL等技术栈涵盖业主管理、车位管理、小区管理、管理员管理并配套业主小程序端支持物业费缴纳、停车费缴纳、投诉建议、房屋保修、公告查看与身份绑定等场景。压缩包整体大小46.63MB共包含1011个文件其中Java后端源码、Vue前端页面、小程序WXML/WXSS、数据库SQL脚本及使用文档一应俱全PNG/JPG/GIF等图表资源方便界面预览XML/JSON/JS等配置与逻辑文件便于二次开发。项目为导师认可的高分毕业设计评审98分已有164人学习下载除了可直接运行的完整工程外还附有使用文档、环境搭建说明JDK8、MySQL5.1、Tomcat8与部署注意事项适合作为毕业设计、课程设计或期末大作业的参考蓝本也可用于快速上手Spring Boot与Vue的整合开发。1. 一个 Spring Boot 物业管理系统 zip 包里值得你关注的是什么拿到《基于spring boot的小区物业管理系统源码使用文档高分毕业设计.zip》这类包第一步不是急着解压而是先想清楚你缺的是一套能跑的代码还是一套能被答辩老师追问的完整逻辑大多数这类系统跑起来不难难的是把“业主、房屋、车位、账单、报修工单”这几个对象之间的关系讲明白再把“物业费怎么算”“工单状态怎么流转”在代码里落对。这篇笔记就围绕这两个点展开从选型、建表、核心功能落地到部署和论文对应关系。适合两类人正在做Java毕设的学生以及想快速搭一套小区物业管理后台做二次开发的业务开发。2. 技术选型与项目骨架为什么是 Spring Boot模块怎么拆2.1 Spring Boot 做物业系统比 SSH / SSM 强在哪如果这个项目是用 SSH 或 SSM 写的我现在写这篇笔记的语气会完全不一样要配一堆 XML、要管理各种 jar 包冲突、要手写事务代理。Spring Boot 把这一层全部收走了项目里的重点从“怎么把框架伺候好”变成了“物业业务本身长什么样”。对毕业设计而言这个转变非常关键因为论文的篇幅应该花在需求分析、数据库设计、核心流程上而不是讲 Spring MVC 的 DispatherServlet 怎么工作。Spring Boot 对这类“管理系统”最友好的几点是内嵌 Tomcat一段mvn spring-boot:run就能起服务application.yml一把梭配数据源、端口、日志Starter 依赖把 MyBatis、MySQL、校验、缓存全封装好pom 里加依赖就能直接用。第一个 Spring Boot 程序教学里那套RestController的写法在这里原封不动延续但你能接触到的东西会比 demo 深得多。2.2 标准模块划分与包结构这类小区物业系统的业务边界很清晰业主端和管理员端共用一套后端按功能域拆包。我在改这类项目时习惯按下面的结构组织答辩讲起来也顺com.example.property ├── controller # HTTP 接口层只做参数接收和结果封装 ├── service # 业务逻辑层账单计算、工单流转都在这里 ├── mapper # MyBatis 的 Mapper 接口 ├── entity # 数据库实体 ├── dto # 接口出入参对象避免直接暴露实体 ├── config # 拦截器、跨域配置、静态资源映射 ├── common # 统一返回结果、异常处理、工具类 ├── enums # 工单状态、账单状态等枚举 └── PropertyApplication.javacontroller 层别写业务这是个铁律。很多翻车的项目都是把“计算滞纳金”写在 controller 里后来要复用就只能复制粘贴。service 层才是这个系统的主要阵地尤其账单和工单的逻辑后面我会单独讲。2.3 最小依赖清单和启动配置如果你打算从零搭一个同款pom 里这几样基本就够了。注意我不写死版本号是因为 Spring Boot 2.x 和 3.x 的依赖坐标写法略有差异你在 IDE 里让 Maven 自己解析即可dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId /dependency /dependenciesMyBatis-Plus 在这个场景值得用单表 CRUD 不用写 SQLQueryWrapper直接查列表分页用Page对象。物业系统大部分接口都是单表查询加简单条件比如按楼栋查房屋、按业主查账单用 MyBatis-Plus 能省掉大量重复的 Mapper XML。application.yml里核心配置就三块数据源、MyBatis-Plus 驼峰映射、文件上传大小限制。下面是一个常见配置spring: datasource: url: jdbc:mysql://localhost:3306/property?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 servlet: multipart: max-file-size: 10MB max-request-size: 20MB mybatis-plus: configuration: map-underscore-to-camel-case: true global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0注意map-underscore-to-camel-case这个参数数据库字段一般是create_time实体属性是createTime不开驼峰映射的话每次查询都要起别名烦得很。逻辑删除字段也是我做这类系统必开的物业系统里业主、房屋、账单都不能物理删只能打标记后面避坑章节我会专门解释。3. 数据库设计物业系统的数据模型是论文的得分点3.1 核心表关系业主、房屋、车位、账单怎么挂很多毕设项目把业主和房屋设计成一对一关系也就是业主表里存一个room_id字段。这在真实小区里根本不成立谁家没个两套房或者一套房夫妻俩共同登记。答辩老师问到这种问题最容易让项目露怯。正确做法是业主表、房屋表独立中间加一张关联表记录入住时间、与业主关系产权人、家庭成员、租户。另一个容易乱的地方是账单。物业费是按月生成的每个房屋每个月产生一条账单记录所以账单表至少要有一个bill_month字段格式用2025-06这种而不是存一个时间戳。车位费、水费、电梯费可以都归入同一张账单表用fee_type区分这样前端展示“费用明细”就很简单不用每类费用建一张表。3.2 建表 SQL业主-房屋关联、账单、报修工单我直接给出三张最核心表的简化建表 SQL注释就是给论文的实体关系描述-- 房屋表 CREATE TABLE t_room ( id BIGINT PRIMARY KEY AUTO_INCREMENT, building_no VARCHAR(20) NOT NULL COMMENT 楼栋号如 3 栋, unit_no VARCHAR(20) COMMENT 单元号可选, room_no VARCHAR(20) NOT NULL COMMENT 房号, area DECIMAL(8,2) NOT NULL COMMENT 建筑面积物业费计算依据, owner_id BIGINT COMMENT 当前主要业主 id冗余字段方便列表展示, status TINYINT DEFAULT 0 COMMENT 0 未售 1 已入住 2 空置, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, deleted TINYINT DEFAULT 0 ) COMMENT 房屋表;deleted字段配合我在 2.3 里配置的 MyBatis-Plus 逻辑删除查询时自动过滤。owner_id这个冗余字段是有意保留的因为“这套房子现在属于谁”在绝大多数场景都是查询条件关联表只在需要查“一个业主名下所有房产”时才用得上。-- 物业费账单表 CREATE TABLE t_bill ( id BIGINT PRIMARY KEY AUTO_INCREMENT, room_id BIGINT NOT NULL COMMENT 房屋 id, bill_month VARCHAR(7) NOT NULL COMMENT 账单月份如 2025-06, fee_type TINYINT DEFAULT 0 COMMENT 0 物业费 1 车位费 2 水费, amount DECIMAL(10,2) NOT NULL COMMENT 应收金额, paid_amount DECIMAL(10,2) DEFAULT 0 COMMENT 实收金额, late_fee DECIMAL(10,2) DEFAULT 0 COMMENT 滞纳金, status TINYINT DEFAULT 0 COMMENT 0 未缴 1 部分缴纳 2 已缴清, pay_time DATETIME COMMENT 最后支付时间, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, deleted TINYINT DEFAULT 0 ) COMMENT 物业费账单表;账单表我单独给pay_time不给“缴费开始时间、结束时间”这种模糊设计。amount和paid_amount分开是支持“部分缴费”场景的基础。滞纳金不是账单金额的一部分它是独立计算出来的后面代码里会体现。-- 报修工单表 CREATE TABLE t_repair ( id BIGINT PRIMARY KEY AUTO_INCREMENT, room_id BIGINT NOT NULL COMMENT 报修房屋, owner_id BIGINT NOT NULL COMMENT 报修业主, category VARCHAR(20) COMMENT 报修类型水电、门窗、电梯, description VARCHAR(500) COMMENT 问题描述, image_url VARCHAR(255) COMMENT 现场照片, status TINYINT DEFAULT 0 COMMENT 0 待派单 1 处理中 2 待验收 3 已完成 4 已取消, assignee VARCHAR(50) COMMENT 维修工姓名, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, finish_time DATETIME COMMENT 完成时间, deleted TINYINT DEFAULT 0 ) COMMENT 报修工单表;3.3 金额和时间字段的三个约定这三个约定是我调这类系统调出来的血泪经验直接写进建表规范里最省事。金额一律用DECIMAL(10,2)任何情况下不用 float 和 double。float算钱会出现 19.99 存成 19.989999 这种问题页面展示、对账、导出 Excel 都会翻车。物业费计算涉及单价、面积、月份数乘除完必须用BigDecimal做构造时用字符串禁止new BigDecimal(0.1)这种从 double 转过来的写法。时间字段分两类create_time、update_time这类系统时间用DATETIME DEFAULT CURRENT_TIMESTAMP让数据库生成业务时间像缴费时间pay_time、工单完成时间finish_time由代码写入。原因很简单数据库默认时间只能表达“这行记录什么时候创建的”表达不了“这笔缴费发生在这个时刻”这种业务语义。账单月份的bill_month用VARCHAR(7)存2025-06格式不要用DATE类型。月份是一个“期间”概念而不是一个“时间点”后期做“查某季度所有账单”用字符串LIKE 2025-%或者LEFT(bill_month, 4) 2025都能直接处理比时间函数转换清爽太多。4. 关键功能落地从登录到报修工单状态机4.1 基于 JWT 的登录与权限拦截这类管理系统权限模型一般是两种角色管理员和业主。业主只能操作自己的房屋、自己的账单、自己的报修管理员管理全部数据。最简单的实现就是登录接口签发 JWTpayload 里带userId和role然后写一个 HandlerInterceptor 统一拦截。先看 JWT 工具类这段代码在所有 Spring Boot 项目里几乎是通用的Component public class JwtUtil { Value(${jwt.secret}) private String secret; Value(${jwt.expire}) private Long expire; // 单位毫秒 public String generateToken(Long userId, String role) { return Jwts.builder() .setSubject(String.valueOf(userId)) .claim(role, role) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() expire)) .signWith(Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8))) .compact(); } public Claims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8))) .build() .parseClaimsJws(token) .getBody(); } }secret放配置文件里不要在代码里写死。expire一般设 7200000两小时但这个系统如果业主端是网页可以放宽到 12 小时减少频繁重新登录的抱怨。拦截器的注册方式老项目和新项目写法不同Spring Boot 3 里很多配置迁移成了WebMvcConfigurer的实现类核心逻辑是一样的Configuration public class WebConfig implements WebMvcConfigurer { Resource private JwtInterceptor jwtInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(jwtInterceptor) .addPathPatterns(/api/**) .excludePathPatterns(/api/login, /api/register); } }注意拦截器只管“这个请求有没有带合法 token”角色权限的判断放在方法级别。可以用自定义RequireRole(admin)注解加 AOP 实现也可以简单地在需要管理员的接口里第一步做判断。毕业设计做到后者足够了答辩的时候能说清“为什么这么设计”比炫技更重要。4.2 物业费账单生成与滞纳金计算物业费账单是这类系统最能体现“业务逻辑”的地方也是论文里可以重点写的用例。按月生成账单核心逻辑是结算上个月所有未缴清的账单然后为当前月生成新账单。不能重复生成所以要有幂等控制。Service public class BillService { Resource private BillMapper billMapper; Resource private RoomMapper roomMapper; public void generateMonthlyBills(String billMonth) { // 先查这个月是否已经生成过防止定时任务重复执行 Long count billMapper.countByMonth(billMonth); if (count 0) { return; } // 查出所有在管房屋设定统一单价 ListRoom roomList roomMapper.selectList(null); BigDecimal unitPrice new BigDecimal(1.80); // 每平米单价实际从配置表读取 BigDecimal parkingFee new BigDecimal(120.00); for (Room room : roomList) { BigDecimal amount unitPrice.multiply(room.getArea()) .add(parkingFee).setScale(2, RoundingMode.HALF_UP); Bill bill new Bill(); bill.setRoomId(room.getId()); bill.setBillMonth(billMonth); bill.setAmount(amount); bill.setStatus(0); billMapper.insert(bill); } } }countByMonth这一步是幂等关键。定时任务用Scheduled(cron 0 0 0 1 * ?)每月 1 号凌晨跑一次或者提供一个管理员手动触发的接口。单价不要写在代码里正规做法是建一张配置表物业服务费调整时可以改配置重新生成。滞纳金计算比较容易被忽略。常见规则是超过缴费截止日每天加收应缴金额的千分之三。代码实现要点是“只计算当前时间到截止日期的天数”而且只对status 0的账单计算public BigDecimal calcLateFee(Long billId) { Bill bill billMapper.selectById(billId); if (bill.getStatus() 2) { return BigDecimal.ZERO; // 已缴清 } LocalDate deadline bill.getCreateTime().toLocalDate().plusDays(30); LocalDate today LocalDate.now(); if (today.isBefore(deadline)) { return BigDecimal.ZERO; } long overdueDays ChronoUnit.DAYS.between(deadline, today); BigDecimal rate new BigDecimal(0.003); return bill.getAmount().multiply(rate) .multiply(BigDecimal.valueOf(overdueDays)) .setScale(2, RoundingMode.HALF_UP); }这里有个隐藏坑createTime是账单生成时间拿它加 30 天当缴费截止日逻辑上成立但最好在账单表里加一个deadline字段生成账单时显式写入“本月 31 日”或“次月 20 日”这样规则更清晰迟交天数也不是从系统时间推断的。4.3 报修工单的状态流转与看板统计物业系统的报修流程是典型的状态机场景适合在论文里画一个状态图文字描述即可业主提交工单PENDING管理员派单给维修工PROCESSING维修完成待业主验收PENDING_CONFIRM业主确认通过FINISHED任何阶段都可取消CANCELED。代码层面用枚举约束状态尽量避免在 Service 里写裸数字public enum RepairStatus { PENDING(0, 待派单), PROCESSING(1, 处理中), PENDING_CONFIRM(2, 待验收), FINISHED(3, 已完成), CANCELED(4, 已取消); private final Integer code; private final String desc; RepairStatus(Integer code, String desc) { this.code code; this.desc desc; } public boolean canTransferTo(RepairStatus target) { // 只允许向后流转待派单 - 处理中 - 待验收 - 已完成 return this.code target.code; } }写状态流转逻辑时最大的坑是“跳状态”。比如业主提交后直接改成FINISHED数据库里没报错但流程语义乱了看板统计数据全是错的。所有状态变更走同一个方法方法内先canTransferTo校验这个细节放代码里答辩时能解释“状态机保证了流程严谨性”。业主端的看板统计一般要三个数待处理工单数、进行中工单数、本月已完工单数。直接用 SQL 聚合不需要代码做内存计算Select(script SELECT status, COUNT(*) AS cnt FROM t_repair WHERE room_id #{roomId} AND deleted 0 GROUP BY status /script) ListMapString, Object countByStatus(Long roomId);4.4 文件上传与图片映射报修工单要传现场照片业主头像要传图片。文件上传这块很多毕设项目栽跟头因为本地开发时把文件写到了项目根目录下的upload/文件夹一旦mvn clean或者打成 jar 包部署路径全乱。正确做法是把上传目录配置化然后映射成静态资源。先写作上传接口的核心方法RestController RequestMapping(/api/file) public class FileController { Value(${file.upload-dir}) private String uploadDir; PostMapping(/upload) public String upload(RequestParam(file) MultipartFile file) { if (file.isEmpty()) { throw new BizException(文件不能为空); } String originalFilename file.getOriginalFilename(); String ext originalFilename.substring(originalFilename.lastIndexOf(.)); String filename UUID.randomUUID().toString().replace(-, ) ext; String dateDir new SimpleDateFormat(yyyyMM).format(new Date()); File dir new File(uploadDir File.separator dateDir); if (!dir.exists()) { dir.mkdirs(); } String path dir.getAbsolutePath() File.separator filename; file.transferTo(new File(path)); // 返回可访问的相对路径 return /upload/ dateDir / filename; } }文件名用 UUID 重命名是必须的否则用户传一张1.jpg下一个人再传一张1.jpg就把前面的覆盖了。按月份建子目录是方便后面做存储清理也避免单目录文件过多。配置文件里对应file: upload-dir: /data/property/upload然后在配置类里把本地目录映射成 URL 访问路径Configuration public class StaticResourceConfig implements WebMvcConfigurer { Value(${file.upload-dir}) private String uploadDir; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/upload/**) .addResourceLocations(file: uploadDir /); } }file:前缀是文件系统路径映射的关键没有它Spring 会把/upload/当成 classpath 下的资源路径去查找结果就是图片 404。上传文件返回的 URL 直接存数据库字段前端只要拼上服务器 IP 和端口就能展示不需要额外接口。5. 常见问题排查5 个让物业项目翻车的细节5.1 房屋删除报外键约束删除失败现象管理员在后台删除一个空置房屋接口报错提示外键约束失败但明明没有业主关联这个房屋。原因外键约束指向了账单或工单等历史数据。物业系统里“房屋”和“账单”“报修”天然有强关联一条账单记录了某房屋某月的水电费房屋删除时会触发外键检查。设计师通常只在“当前是否被业主占用”层面做了限制忽略了历史数据引用。解决不要做物理删除改用逻辑删除。deleted字段置 1查询全部带上deleted 0条件。这种系统任何主数据都遵循这个规则业主可以“注销”房屋可以“标记拆除”账单只能“作废”但不能消失。否则后面的报表对账全对不上。5.2 缴费金额和手工账单对不上现象业主在 APP 端缴了物业费后台导出 Excel 统计的金额和业主手动算出的不一致总是差几毛几分。原因金额计算用了float或double。MySQL 里字段是DECIMAL(10,2)但实体类属性用的是DoubleMyBatis 查出来转成 Double 再参与运算精度损失在“金额相加”场景被放大十条账单加起来能差出好几块钱。解决实体类金额字段全用BigDecimal代码里任何涉及金额的乘除都用BigDecimal的方法综合修改量不大但收效立竿见影。排查时检查entity包下所有Double类型的金额字段换成BigDecimal后重新跑一遍对账接口。5.3 前端页面报表加载慢等待时间超 3 秒现象管理员打开“缴费统计”页面按季度展示各楼栋缴费率接口响应时间 3 秒以上数据量其实只有几千条。原因账单表按room_id查询但t_bill表没有建联合索引。前端统计接口通常这么查WHERE bill_month ? GROUP BY room_id没有索引就是全表扫描几千条数据不至于慢到不可用但一加上多表 JOIN 就很吃力。物业系统天然适合“按月查”批量导入历史数据后这个问题会立刻暴露。解决给核心表加上这组索引我用得最多的是这三条ALTER TABLE t_bill ADD INDEX idx_bill_month (bill_month); ALTER TABLE t_bill ADD INDEX idx_bill_room (room_id); ALTER TABLE t_repair ADD INDEX idx_repair_status (status);如果数据量超过十万行还可以考虑在(bill_month, room_id)上建联合索引覆盖大多数月结查询场景。5.4 Spring Boot 3 下的 JWT jar 包报错现象把项目从 Spring Boot 2.7 升级到 3.x原本写好的 JWT 工具类直接编译报错找不到javax.xml.bind.DatatypeConverter或者javax.annotation包。原因Spring Boot 3 的基础包从javax换成了jakarta老版本 JWT 库依赖 JAXB 模块JDK 17 以后默认不带这些运行时包了。很多人拿旧项目改 Spring Boot 3 时翻车就在这里。解决升级jjwt到 0.12.0 以上版本新版的 API 已经从Jwts.parser()变成Jwts.parserBuilder()签名方式也统一成了Keys.hmacShaKeyFor。可以直接用我 4.1 节代码里的写法编译和运行都没问题。如果还报错看 Maven 依赖树里是否有旧版javax.servlet-api冲突排除掉旧坐标即可。5.5 项目根目录下的doc/没有SQL脚本只有使用文档现象解压完 zip 包目录里只有源码、使用文档和说明找不到初始化数据库的 SQL 脚本启动项目后管理后台登录不了。原因部分毕业设计项目的 SQL 脚本不放在项目目录里而是写在使用文档末尾的“数据库配置”一节。如果使用文档是 PDF 或者图片复制里面的建表语句很容易因为格式问题执行报错。解决拿到 zip 包第一件事不是在 IDE 里打开项目而是先完整看一遍使用文档确认三样东西的位置SQL 脚本、配置文件中的数据库账号密码、前端是否另需构建。项目里没有sql/目录时在resources/db/下新建schema.sql和data.sql把建表语句和初始数据放进去再在application.yml里配spring: sql: init: mode: always schema-locations: classpath:db/schema.sql style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />