基于SpringBoot的智慧社区管理系统：从门禁报修到工单超时提醒的完整实现

简介：这份资源是面向计算机专业毕业设计场景的完整项目资料包，主题为基于SpringBoot的智慧社区管理系统，适合正在准备毕设的本科生、需要参考企业级Java项目结构的学习者，以及希望了解社区管理类系统设计思路的开发者。压缩包共750个文件，约22.51MB，以203个java源码、141个vue前端组件、161个svg图标、77张jpg与34张png图片为主，另含26个xml配置、41个js脚本、15个css样式及sql建表脚本、docx开发文档、bat启动脚本等，前后端代码与文档资料齐备。已有35人学习下载。资源覆盖用户认证授权、社区通知发布、在线服务请求处理、公共资源预约与财务信息管理等模块，文档中记录了居民信息、服务请求、公共资源等数据表设计与关系映射，并涉及数据备份恢复、权限控制、异常处理与日志策略等实现细节，可作为毕设选题参考、代码复现与论文撰写的实用素材。

1. 智慧社区管理系统到底解决谁的痛点：从一次门禁报修说起

去年冬天，一个老小区物业经理给我看他们的值班记录：一天之内 47 通电话，其中 23 通是门禁卡刷不开，11 通是地下车库道闸不抬杆，剩下的是报修和投诉。值班员拿 Excel 登记，维修工拿微信接单，业主在群里骂，物业在群里道歉。这套流程里没有一处是技术问题，全是信息流转问题——谁报的、派给谁、修没修、多久修完，四个状态散落在四个地方。

基于 SpringBoot 的智慧社区管理系统要干的事，就是把这四个状态收进一个后端服务里：业主端提交工单，物业端派单，维修端接单回执，管理端看统计。它适合两类人：一类是课程设计或毕设需要完整可跑项目的学生，另一类是中小物业想低成本搭一套内部系统的开发者。核心不是炫技，是把「人、房、车、事」四张表的关系理清楚，再用 SpringBoot 把它们串成能用的接口。

2. 技术选型与模块拆分：为什么是 SpringBoot 而不是别的

2.1 单体 SpringBoot 在这个场景下的合理性

很多人一上来就想微服务，我劝你先算一笔账。一个中等社区，常住人口 3000 到 8000，日活请求峰值大概在早晚高峰各 200 到 500 QPS。这个量级用单体 SpringBoot 加一个 MySQL 实例完全扛得住，甚至还有富余。拆成微服务带来的注册中心、配置中心、链路追踪、分布式事务，每一样都是运维成本，而收益在这个量级几乎为零。

SpringBoot 在这个项目里的真实价值是三点：第一，起步依赖把 Web、JPA、Security、Redis 的版本冲突问题一次性解决，你不用再对着 pom 文件调半天；第二，自动配置让数据源、事务管理器、JSON 序列化开箱即用；第三，内嵌 Tomcat 让部署变成java -jar一条命令，物业那边没有运维也能跑起来。

模块拆分我一般按业务边界切，不按技术分层切。常见做法是：

这样切的好处是每个模块的 Service 只依赖自己的 Mapper 和少量公共组件，后面想拆出去也容易。如果按 controller/service/dao 三层切，改一个报修流程要动三个包，时间全花在找文件上。

2.2 数据库表设计里最容易翻车的地方

表设计这块我踩过的坑比写代码多。先说房屋和住户的关系：一套房可以有多任业主（买卖过户），一个业主也可以有多套房。所以 house 和 resident 之间必须是多对多，中间表 house_resident 要带start_date、end_date、relation（业主/租户/家属）三个字段。我见过有人直接在 resident 表里加一个house_id，结果换业主的时候历史记录全丢了。

工单表的设计要点是状态机。work_order 的 status 字段不要用中文，用枚举整数：

CREATE TABLE work_order ( id BIGINT PRIMARY KEY AUTO_INCREMENT, order_no VARCHAR(32) NOT NULL UNIQUE COMMENT '工单编号，格式 WO+日期+序列', resident_id BIGINT NOT NULL COMMENT '提交人', house_id BIGINT NOT NULL COMMENT '关联房屋', category TINYINT NOT NULL COMMENT '1水电 2门窗 3电梯 4公共设施 5其他', description VARCHAR(500) NOT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT '0待派单 1已派单 2处理中 3已完工 4已评价 5已取消', handler_id BIGINT DEFAULT NULL COMMENT '维修工ID', create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, dispatch_time DATETIME DEFAULT NULL, finish_time DATETIME DEFAULT NULL, INDEX idx_status_create (status, create_time), INDEX idx_handler (handler_id, status) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

idx_status_create这个联合索引是给物业端「待派单列表按时间倒序」用的，idx_handler是给维修工端「我的进行中工单」用的。没有这两个索引，工单量上到几千条之后列表页会明显卡顿。

状态流转必须走 Service 层校验，不能只靠前端按钮控制。比如「已完工」的工单不能再派单，「已取消」的不能再接单。我一般写一个OrderStateMachine类，用 Map 存合法流转：

public class OrderStateMachine { private static final Map<Integer, Set<Integer>> TRANSITIONS = Map.of( 0, Set.of(1, 5), // 待派单 -> 已派单 / 已取消 1, Set.of(2, 5), // 已派单 -> 处理中 / 已取消 2, Set.of(3), // 处理中 -> 已完工 3, Set.of(4) // 已完工 -> 已评价 ); public static void check(int from, int to) { Set<Integer> allowed = TRANSITIONS.getOrDefault(from, Set.of()); if (!allowed.contains(to)) { throw new BizException("工单状态不允许从 " + from + " 变更为 " + to); } } }

这段代码的关键是TRANSITIONS用Map.of声明为不可变，防止运行期被误改。check方法在每次状态变更前调用，抛出的BizException由全局异常处理器统一转成前端能识别的错误码。参数from和to就是当前状态和目标状态，用整数而不是枚举是为了和数据库字段直接对应，少一层转换。

3. 从零跑通最小可用版本：环境、配置与第一个接口

3.1 环境准备与项目骨架生成

我一般用 Spring Initializr 生成骨架，但版本选择有讲究。SpringBoot 3.x 要求 JDK 17 起步，如果你学校机房还是 JDK 8，就老老实实用 2.7.x。热词里有人问「springboot 版本太高」怎么办，答案很简单：看你的 JDK。JDK 8 配 2.7.18，JDK 17 配 3.2.x，别硬凑。

依赖勾选这几项就够了：Spring Web、Spring Data JPA、MySQL Driver、Lombok、Spring Boot DevTools。Security 先不勾，等登录模块再手动加，否则一开始所有接口都被拦，调不通会怀疑人生。

生成后的项目结构我建议这样调整：

src/main/java/com/community/ ├── CommunityApplication.java ├── common/ # 统一返回、异常、工具类 ├── config/ # 数据源、跨域、拦截器配置 ├── module/ │ ├── resident/ # 住户模块 │ ├── access/ # 门禁模块 │ ├── order/ # 工单模块 │ └── bill/ # 费用模块

每个 module 下面再分 controller、service、repository、entity、dto。这样找代码是按业务找，不是按层找。

3.2 application.yml 里必须改的四个参数

spring: datasource: url: jdbc:mysql://localhost:3306/community?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true username: root password: your_password hikari: maximum-pool-size: 10 minimum-idle: 2 connection-timeout: 30000 jpa: hibernate: ddl-auto: update show-sql: true properties: hibernate: format_sql: true server: port: 8080 servlet: context-path: /api

四个必须改的：url里的serverTimezone不写会报时区错误；allowPublicKeyRetrieval=true是 MySQL 8 用 caching_sha2_password 插件时本地连接必须加的；maximum-pool-size默认 10 对社区系统够用，但如果你同时开了定时任务和 Web 请求，建议提到 15；ddl-auto开发期用 update，上线前必须改成 none 并用 SQL 脚本管理表结构，否则哪天实体改错字段，Hibernate 可能把生产表结构改了。

context-path: /api这个设置让所有接口自动带/api前缀，前端配代理的时候少写一层。

3.3 第一个能跑的接口：工单提交

先写实体，再写 Repository，最后写 Controller。实体用 JPA 注解映射：

@Entity @Table(name = "work_order") @Data public class WorkOrder { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(name = "order_no", nullable = false, unique = true, length = 32) private String orderNo; @Column(name = "resident_id", nullable = false) private Long residentId; @Column(name = "house_id", nullable = false) private Long houseId; @Column(nullable = false) private Integer category; @Column(nullable = false, length = 500) private String description; @Column(nullable = false) private Integer status = 0; @Column(name = "handler_id") private Long handlerId; @Column(name = "create_time", nullable = false, updatable = false) private LocalDateTime createTime = LocalDateTime.now(); @Column(name = "dispatch_time") private LocalDateTime dispatchTime; @Column(name = "finish_time") private LocalDateTime finishTime; }

@Data是 Lombok 的，自动生成 getter/setter/toString。createTime用updatable = false保证创建后不会被更新。status给默认值 0，这样 new 出来不设状态也不会是 null。

Repository 继承 JpaRepository，加两个查询方法：

public interface WorkOrderRepository extends JpaRepository<WorkOrder, Long> { Page<WorkOrder> findByStatusOrderByCreateTimeDesc(Integer status, Pageable pageable); List<WorkOrder> findByHandlerIdAndStatusIn(Long handlerId, List<Integer> statuses); }

方法名就是查询语义，findByStatusOrderByCreateTimeDesc对应「按状态查并按创建时间倒序」，Spring Data JPA 会自动生成 SQL。第二个方法给维修工端用，statusIn传[1, 2]就是「已派单和处理中」。

Controller 层：

@RestController @RequestMapping("/order") @RequiredArgsConstructor public class WorkOrderController { private final WorkOrderService orderService; @PostMapping("/submit") public Result<Long> submit(@RequestBody @Valid OrderSubmitDTO dto) { Long orderId = orderService.submit(dto); return Result.ok(orderId); } @GetMapping("/list") public Result<Page<WorkOrder>> list( @RequestParam(defaultValue = "0") Integer status, @RequestParam(defaultValue = "1") Integer page, @RequestParam(defaultValue = "10") Integer size) { return Result.ok(orderService.listByStatus(status, page, size)); } }

@Valid触发 DTO 上的校验注解，比如@NotNull、@Size。Result是统一返回包装，包含 code、msg、data 三个字段。@RequiredArgsConstructor是 Lombok 的构造器注入，比@Autowired字段注入更推荐，因为依赖不可变且方便测试。

Service 里生成工单号用日期加序列：

public Long submit(OrderSubmitDTO dto) { WorkOrder order = new WorkOrder(); order.setOrderNo(generateOrderNo()); order.setResidentId(dto.getResidentId()); order.setHouseId(dto.getHouseId()); order.setCategory(dto.getCategory()); order.setDescription(dto.getDescription()); order.setStatus(0); orderRepository.save(order); return order.getId(); } private String generateOrderNo() { String date = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyyMMdd")); long seq = orderRepository.countByCreateTimeBetween( LocalDate.now().atStartOfDay(), LocalDate.now().plusDays(1).atStartOfDay()) + 1; return "WO" + date + String.format("%04d", seq); }

generateOrderNo用当天工单数加一作为序列，格式WO202501010001。这里有个并发问题：两个请求同时进来可能拿到同一个 seq。生产环境要用 Redis 的INCR或者数据库序列，但课程设计阶段用synchronized修饰这个方法也能应付。我一般会在方法上加@Transactional并配合数据库唯一索引兜底，重复了就让前端重试。

4. 门禁与工单联动：几个容易忽略的接口细节

4.1 访客临时密码的生成与失效

访客通行是这个系统里比较有意思的一块。业主给访客生成一个临时密码，访客在门禁机上输入就能进。密码要满足三个条件：6 位数字、当天有效、用一次就失效。

生成逻辑：

public String generateVisitorPass(Long residentId, Long houseId, String visitorName) { String pass = String.format("%06d", ThreadLocalRandom.current().nextInt(1000000)); Visitor visitor = new Visitor(); visitor.setResidentId(residentId); visitor.setHouseId(houseId); visitor.setVisitorName(visitorName); visitor.setPassCode(pass); visitor.setExpireTime(LocalDateTime.now().plusDays(1)); visitor.setUsed(false); visitorRepository.save(visitor); return pass; }

ThreadLocalRandom比Random在多线程下性能更好，nextInt(1000000)生成 0 到 999999，格式化补零到 6 位。expireTime设成 24 小时后，used标记是否已使用。

校验逻辑：

public boolean verifyPass(String passCode) { Visitor visitor = visitorRepository.findByPassCodeAndUsedFalse(passCode) .orElseThrow(() -> new BizException("密码无效")); if (visitor.getExpireTime().isBefore(LocalDateTime.now())) { throw new BizException("密码已过期"); } visitor.setUsed(true); visitorRepository.save(visitor); return true; }

这里有个坑：findByPassCodeAndUsedFalse如果查到多条会抛异常，所以 passCode 字段要加唯一索引。另外校验和标记已使用必须在同一个事务里，否则并发情况下同一个密码可能被用两次。加@Transactional注解即可。

4.2 工单派单的并发控制

派单是物业端操作，把工单的 handler_id 设成某个维修工，status 从 0 变 1。看起来简单，但两个物业同时点派单就会出问题。我一般用乐观锁：

@Modifying @Query("UPDATE WorkOrder w SET w.handlerId = :handlerId, w.status = 1, w.dispatchTime = :time " + "WHERE w.id = :id AND w.status = 0") int dispatch(@Param("id") Long id, @Param("handlerId") Long handlerId, @Param("time") LocalDateTime time);

这个 UPDATE 带了AND w.status = 0条件，返回受影响行数。如果返回 0，说明工单已经被别人派了，Service 里抛异常提示「工单已被派单」。这比先查再改的写法安全，因为查和改之间没有间隙。

调用处：

@Transactional public void dispatch(Long orderId, Long handlerId) { int rows = orderRepository.dispatch(orderId, handlerId, LocalDateTime.now()); if (rows == 0) { throw new BizException("工单已被派单或状态不允许"); } }

@Modifying告诉 Spring Data JPA 这是更新操作，需要配合@Transactional使用。@Query里用的是 JPQL，字段名是实体属性名不是数据库列名。

5. 避坑与排查：那些让我加班到凌晨的问题

5.1 现象：接口返回中文乱码

原因：MySQL 连接 URL 没加characterEncoding=utf8，或者数据库和表的字符集是 latin1。解决：URL 里补上useUnicode=true&characterEncoding=utf8，建库时用CREATE DATABASE community DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci。已经建好的表用ALTER TABLE work_order CONVERT TO CHARACTER SET utf8mb4转换。

5.2 现象：JPA 保存时 createTime 为 null

原因：实体里createTime字段设了默认值LocalDateTime.now()，但 JPA 在某些情况下会用数据库默认值覆盖，或者字段被标记为insertable = false。解决：要么在实体上不加insertable = false，要么在数据库列上加DEFAULT CURRENT_TIMESTAMP并在实体里用@CreationTimestamp注解。我一般用后者，让数据库和 JPA 各管一半，不容易冲突。

5.3 现象：分页查询 total 总是 0

原因：Spring Data JPA 的Page对象在跨服务传输时，如果用了自定义的PageImpl构造，total 可能丢失。或者前端传的 page 从 0 开始，后端从 1 开始，导致查不到数据。解决：统一约定 page 从 1 开始，Service 里PageRequest.of(page - 1, size)。返回时用new PageImpl<>(content, pageable, total)显式构造。

5.4 现象：定时任务和 Web 请求抢数据库连接

原因：HikariCP 默认最大连接数 10，定时任务批量处理账单时占满连接池，Web 请求排队超时。解决：把maximum-pool-size提到 15 到 20，或者给定时任务单独配一个数据源。更简单的做法是定时任务加@Scheduled时错开高峰，比如凌晨 3 点执行。

5.5 现象：前端跨域请求被拦

原因：开发期前端跑在 5173 端口，后端 8080，浏览器同源策略拦截。解决：加一个全局 CORS 配置：

@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true) .maxAge(3600); } }

注意allowedOriginPatterns和allowedOrigins的区别：前者支持通配符且允许携带凭证，后者在allowCredentials(true)时不能用*。上线后要把*换成具体域名。

6. 让系统真正能用起来的一个技巧：工单超时自动提醒

前面把功能跑通了，但系统能不能真正减轻物业负担，取决于一个细节：工单派出去之后，维修工忘了处理怎么办。我见过太多系统功能齐全但没人用，就是因为缺少这种「推一把」的机制。

我的做法是用 Spring 的@Scheduled加一个简单的超时检查。每 30 分钟扫一次「已派单超过 2 小时仍未处理中」的工单，给维修工发站内信，同时抄送物业主管。

@Component @RequiredArgsConstructor public class OrderTimeoutTask { private final WorkOrderRepository orderRepository; private final NoticeService noticeService; @Scheduled(cron = "0 0/30 * * * ?") public void checkTimeout() { LocalDateTime threshold = LocalDateTime.now().minusHours(2); List<WorkOrder> timeoutOrders = orderRepository .findByStatusAndDispatchTimeBefore(1, threshold); for (WorkOrder order : timeoutOrders) { noticeService.send(order.getHandlerId(), "工单超时提醒", "工单 " + order.getOrderNo() + " 已派单超过2小时，请尽快处理"); } } }

cron = "0 0/30 * * * ?"表示每 30 分钟执行一次，从整点开始。findByStatusAndDispatchTimeBefore是 Repository 方法，查状态为 1 且派单时间早于阈值的工单。noticeService.send写一条站内信记录，前端轮询未读消息数。

这个逻辑有三个可以调的地方：阈值 2 小时可以按小区实际情况改成 4 小时或 1 小时；扫描频率 30 分钟可以改成 15 分钟，但别太频繁，否则数据库压力大；通知方式可以扩展成短信或微信模板消息，但站内信是成本最低的起点。

还有一个更细的技巧：给维修工端的工单列表加一个「剩余时间」字段，前端根据dispatchTime和当前时间算出来，快超时的标黄，已超时的标红。这样维修工自己就能看到优先级，不用等系统提醒。这个字段不用存数据库，在 DTO 里算就行：

public class OrderVO { private Long id; private String orderNo; private String description; private Integer status; private Long remainingMinutes; public static OrderVO from(WorkOrder order) { OrderVO vo = new OrderVO(); vo.setId(order.getId()); vo.setOrderNo(order.getOrderNo()); vo.setDescription(order.getDescription()); vo.setStatus(order.getStatus()); if (order.getDispatchTime() != null && order.getStatus() == 1) { long elapsed = Duration.between(order.getDispatchTime(), LocalDateTime.now()).toMinutes(); vo.setRemainingMinutes(Math.max(0, 120 - elapsed)); } return vo; } }

Duration.between算两个时间点之间的分钟数，Math.max(0, 120 - elapsed)保证剩余时间不为负。这个 VO 只在查询时组装，不落库，所以不会有一致性问题。

我自己的习惯是，每做完一个管理系统，都会问自己一个问题：如果我是那个每天用这个系统的人，哪个环节最让我想摔键盘？答案往往不是功能缺失，而是某个状态不透明、某个提醒不及时。把那个环节补上，系统才算真正交付。希望帮到你。

本文还有配套的精品资源，点击获取