民宿预订平台 — 项目介绍文档

一、项目概述

本项目是一套民宿在线预订系统，采用前后端分离架构，覆盖从用户浏览民宿、查看房间、在线下单、支付到订单状态流转的完整预订流程。系统围绕普通用户、房东、管理员三角色构建：普通用户可搜索民宿、收藏心仪房源、下单预订并评价；房东可发布与管理自己的民宿和房间、处理订单；管理员负责民宿审核、用户管理、反馈处理及平台运营。系统同时提供平台数据统计与区域订单分析，辅助运营决策。

属性	说明
项目名称	民宿预订平台（Homestay Reservation Platform）
架构模式	B/S 前后端分离
后端技术	Spring Boot 3.5 / MyBatis-Plus 3.5.6 / MySQL 8.0 / Redis / JWT
前端技术	Vue 3 / Element Plus / Pinia / Axios / ECharts / Vite
开发语言	Java 21 / JavaScript（ES6+）
适用场景	计算机毕设、课程设计、源码学习与二次开发

二、技术架构

2.1 后端技术栈

类别	技术选型	版本	说明
核心框架	Spring Boot	3.5.11	Java 企业级开发框架
ORM 框架	MyBatis-Plus	3.5.6	增强版 MyBatis，简化 CRUD
数据库	MySQL	8.0+	关系型数据库
缓存	Spring Data Redis	随 Spring Boot 管理	缓存、分布式锁、JWT 令牌黑名单
安全认证	java-jwt（JWT）	4.4.0	无状态 Token 认证
JSON 处理	fastjson2 / Jackson JSR310	2.0.43 / 2.21.1	高性能 JSON 序列化；Java 8 时间类型支持
参数校验	Spring Validation	随 Spring Boot 管理	DTO 参数校验
工具库	Lombok	随 Spring Boot 管理	简化样板代码
构建工具	Maven	3.8+	依赖管理与项目构建

2.2 前端技术栈

类别	技术选型	版本	说明
核心框架	Vue 3（Composition API）	3.4+	渐进式前端框架
UI 组件库	Element Plus	2.5+	企业级桌面端组件库
路由	Vue Router	4.2+	单页应用路由管理
状态管理	Pinia	2.1+	Vue 官方状态管理库
HTTP 客户端	Axios	1.6+	基于 Promise 的 HTTP 库
图表	ECharts / vue-echarts	5.6+ / 6.6+	数据可视化图表库
日期处理	dayjs	1.11+	轻量级日期时间库
构建工具	Vite	5.0+	下一代前端构建工具

2.3 架构图

┌─────────────────────────────────────────────────────────┐
│                      浏览器（Browser）                    │
├───────────────────────┬─────────────────────────────────┤
│   前台页面（Front）     │     后台管理（Admin）             │
│   localhost:5173       │     localhost:5173/admin         │
│   · 首页/轮播图/公告    │     · 数据统计仪表盘（ECharts）    │
│   · 民宿搜索/民宿详情   │     · 民宿审核（通过/驳回）        │
│   · 房间浏览/在线预订   │     · 全平台订单管理              │
│   · 我的订单/收藏/评价  │     · 用户管理（启用/禁用）        │
│   · 反馈建议/个人中心   │     · 反馈/公告/轮播图管理         │
│                       │     · 房东工作台（房源/房间/订单）  │
└───────────────────────┴─────────────────────────────────┘
                          │  HTTP /api/*
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Spring Boot 后端（localhost:8080）            │
├─────────────┬──────────────┬──────────────┬──────────────┤
│  Interceptor │  Controller  │   Service    │   Mapper     │
│  JWT 认证     │  user/民宿    │   业务逻辑    │  MyBatis-Plus│
│  @Anonymous  │  order/房东   │   事务管理    │  XML 自定义SQL│
│  @RequireRole│  admin/公告   │   定时任务    │  Redis 缓存/锁│
│  Redis黑名单  │              │   分布式锁    │              │
└─────────────┴──────────────┴──────────────┴──────────────┘
                          │
                          ▼
┌──────────────────────┐  ┌──────────────────────────────┐
│     MySQL 8.0        │  │          Redis               │
│     共 9 张数据表     │  │  缓存 / 分布式锁 / JWT黑名单 │
└──────────────────────┘  └──────────────────────────────┘

2.4 安全设计

JWT 认证拦截器：JwtInterceptor 统一拦截所有接口，解析 Authorization: Bearer <token> 后写入 UserContext（ThreadLocal），请求结束自动清理，防止内存泄漏；同时检查 Redis 令牌黑名单，已登出的 Token 将被拒绝
JWT 令牌黑名单：用户登出时将 Token 存入 Redis，TTL 等于 Token 剩余有效期，确保登出后 Token 立即失效，而不是仅前端丢弃
@Anonymous 注解：标注公开接口（如注册、登录、民宿列表、公告轮播等），免登录访问，无需维护路径白名单
@RequireRole 注解：按角色控制接口访问（管理员=2、房东=1），权限不足返回 403
密码 MD5 加密：注册、修改密码时使用 MD5 摘要存储，数据库不保存明文
逻辑删除：所有业务表均含 deleted 字段，MyBatis-Plus 全局逻辑删除配置，避免物理删除造成数据丢失
统一响应与异常：所有接口返回 Result<T> 统一结构，GlobalExceptionHandler 全局兜底异常并映射为统一错误码

三、功能模块

3.1 前台功能（普通用户）

模块	功能点	说明
首页	轮播图展示、公告滚动、平台统计、热门推荐	轮播 Banner、公告类型标识（重要/普通）、民宿/订单/用户/好评率统计
民宿搜索	关键词、城市、价格区间、排序	支持按名称/描述/地址模糊搜索；价格区间筛选；价格升降序、评分降序
民宿详情	民宿信息、房间列表、设施、入住须知	展示民宿封面、多图、设施标签、入住/退房时间、联系电话及所有上架房间
在线预订	选择日期、入住人数、自动计价	按入住/退房日期自动计算天数与总价，生成订单号，下单即原子扣减房间库存
我的订单	订单列表、状态筛选、支付/取消	订单全生命周期管理；待支付订单 30 分钟内未支付由定时任务自动取消并释放库存
订单评价	完成订单后评价	仅已完成订单可评价，支持评分（1-5 星）与文字内容
收藏	收藏/取消收藏、我的收藏列表	支持分页查看收藏的民宿及收藏状态校验
反馈建议	提交反馈、查看我的反馈	提交标题与内容，管理员处理后可查看回复
个人中心	修改资料、上传头像、修改密码	昵称/手机号/邮箱/头像可编辑；修改密码需验证原密码

3.2 房东端功能（角色：房东）

模块	功能点	说明
数据概览	房源、订单、评价等统计	房东专属工作台首页，实时汇总经营数据
民宿管理	发布/编辑民宿、上架/下架	新发布的民宿进入待审核状态，管理员审核通过后方可上架销售
房间管理	新增/编辑/删除房间、上下架	维护房型、面积、床型、价格、原价、库存、设施与多图
订单管理	确认订单、办理入住、完成订单、拒绝退款	按订单状态推进：待确认→已确认→已入住→已完成；可拒绝订单并退款释放库存
评价管理	查看收到的评价、回复评价	对用户评价进行回复互动

3.3 后台功能（管理员）

模块	功能点	说明
仪表盘	平台数据统计、区域订单统计	ECharts 可视化：民宿/用户/订单等指标，支持按省份/城市维度分析订单分布
民宿审核	审核通过/驳回	对房东提交的待审核民宿进行审核，驳回需填写原因，房东修改后可重新提交
订单管理	全平台订单查询	按订单号、用户、状态多条件分页检索
用户管理	用户列表、启用/禁用、新增/编辑用户	按用户名/手机号/角色/状态检索，可创建用户（含房东）
反馈管理	反馈列表、回复、删除	处理用户反馈并回复
公告管理	公告增删改查	类型（普通/重要）、启用/禁用
轮播图管理	轮播图增删改查	标题、图片、跳转链接、排序、启用/禁用
个人信息	查看/修改管理员信息	与前台个人中心一致

四、项目亮点

4.1 三角色权限体系

系统基于 role 字段实现**普通用户（0）/ 房东（1）/ 管理员（2）**三角色模型：

注册接口仅允许注册普通用户或房东，管理员账号只能由已有管理员创建；
房东与管理员共用 /admin 后台，前端路由守卫与后端 @RequireRole 双重校验，房东仅能看到自己的工作台菜单（我的民宿/房间/订单/评价），管理员仅能看到平台管理菜单；
订单详情等敏感接口额外校验归属（userId / landlordId），杜绝越权访问。

4.2 民宿审核机制

房东发布的民宿默认进入待审核状态，管理员审核通过后方可对用户展示与预订：

管理员驳回时需填写驳回原因，房东修改后重新提交，自动回到待审核状态；
已下架民宿可重新上架，上架仅限已审核通过或已下架状态的民宿。

4.3 订单全流程状态机

订单状态完整覆盖预订生命周期，并通过 OrderStatusEnum 枚举统一管理：

状态	说明	可执行操作
待支付	下单后生成，30 分钟内有效	支付、取消
待确认	已支付，等待房东确认	房东确认、用户取消
已确认	房东已确认	房东办理入住
已入住	用户已入住	房东完成订单
已完成	订单完结，恢复库存	用户评价
已取消 / 已退款	取消或拒绝订单	释放库存

4.4 库存防超卖与支付超时自动取消

库存防超卖：下单时通过 MySQL 原子扣减（UPDATE room SET stock = stock - 1 WHERE stock > 0）与 Redis 分布式锁（RedisUtil.tryLock()，锁键格式 order:lock:room:{roomId}）双重保障，避免并发下单导致超卖；取消/完成/退款时自动恢复库存；
定时任务：OrderExpireTask 每分钟（cron 0 * * * * ?）扫描一次，自动取消支付超时的待支付订单并恢复库存，防止死单占用库存。

4.5 多条件组合搜索

民宿列表接口支持关键词 + 城市 + 价格区间 + 日期 + 排序多维组合检索：

关键词匹配名称、描述、详细地址；
价格区间通过房间表子查询过滤符合条件的民宿；
支持价格升/降序、评分降序排序；
首页统计、推荐民宿、热门排序等场景均有对应接口支撑。

4.6 代码规范性

全局统一异常处理（GlobalExceptionHandler），错误码枚举化管理（ErrorCode）；
统一响应体（Result<T>），所有接口返回格式一致；
所有数据库操作使用 Lambda 表达式构建条件（LambdaQueryWrapper），避免字段名硬编码；
实体继承 BaseEntity，公共字段（id、createTime、updateTime、deleted）统一维护；
状态字段全部枚举化（订单、民宿、用户角色/状态），前端直接展示状态文本；
文件上传路径集中配置（file.upload-path），默认头像、上传资源走统一静态映射。

4.7 Redis 全功能集成

项目深度集成 Redis，覆盖缓存、分布式锁、JWT 令牌黑名单三大场景：

场景	实现方式	说明
数据缓存	`@Cacheable` / `@CacheEvict`	轮播图（10 分钟）、民宿详情（5 分钟）等热点数据缓存，写入时自动失效
分布式锁	`RedisUtil.tryLock()` / `releaseLock()`	订单创建时按房间加锁，防止并发超卖；Lua 脚本保证释放锁的原子性
JWT 黑名单	`RedisTemplate` 直接操作	登出时将 Token 写入 Redis，TTL = Token 剩余有效期；`JwtInterceptor` 校验时先查黑名单
库存管理	`RedisUtil.decrementStock()` / `incrementStock()`	Redis 端 Lua 脚本实现库存原子操作
防重复提交	`RedisUtil.setRepeatSubmit()`	基于 `SETNX` 实现的接口幂等性保护

配置类 RedisConfig 统一管理 RedisTemplate（配置 JavaTimeModule 支持 Java 8 时间序列化）和 CacheManager（按业务数据设置不同 TTL）。

五、项目结构

homestay-reservation-platform/
├── db/                          # 数据库脚本（init.sql 建库建表+基础数据；demo.sql 演示数据）
├── springboot/                  # 后端 Spring Boot
│   └── src/main/
│       ├── java/com/example/
│       │   ├── common/          # 公共模块（注解/配置/枚举/异常/拦截器/工具类/统一响应）
│       │   ├── controller/      # 控制器
│       │   ├── service/         # 业务逻辑
│       │   ├── mapper/          # MyBatis-Plus Mapper
│       │   ├── entity/          # 实体类
│       │   ├── dto/             # 数据传输对象
│       │   ├── vo/              # 视图对象
│       │   ├── task/            # 定时任务
│       │   └── MainApplication.java   # 启动类
│       └── resources/           # 配置（application.yml、mapper XML、static 静态资源）
├── vue/                         # 前端 Vue 3
│   └── src/
│       ├── api/                 # 接口封装
│       ├── components/          # 公共组件
│       ├── layouts/             # 布局（FrontLayout 前台）
│       ├── router/              # 路由
│       ├── store/               # Pinia 状态
│       ├── utils/               # 工具（request）
│       └── views/               # 页面（admin 后台 / 前台）
├── uploads/                     # 文件上传目录（avatars 头像 / demo 演示图片）
│   ├── avatars/                # 用户头像
│   └── demo/                   # 演示数据图片（banner / homestay / room）
└── doc/                        # 项目文档