栖禾公寓

栖禾公寓是一套面向长租公寓场景的前后端分离项目，包含管理后台、移动端 H5 和 Spring Boot 后端服务。项目覆盖公寓管理、房源管理、预约看房、租约管理、用户管理等核心业务，适合作为租赁业务系统的完整示例，也可以继续扩展为实习或作品集项目。

项目概览

• 管理端：面向运营或管理员，负责公寓、房间、租约、预约、系统用户等业务管理
• 移动端 H5：面向租客，负责找房、房源详情、预约看房、租约查看、浏览历史等操作
• 后端：提供管理端和移动端两套 API，负责鉴权、业务处理、数据持久化、文件上传与资源管理

技术栈

后端

• Java 17
• Spring Boot 3.0.5
• MyBatis-Plus 3.5.3.1
• MySQL 8
• Redis
• MinIO
• JWT
• Knife4j / SpringDoc
• EasyCaptcha
• 阿里云短信 SDK

管理端前端

• Vue 3.3.4
• TypeScript
• Vite 4
• Element Plus 2.3.7
• Pinia
• Vue Router 4
• Axios
• ECharts

H5 前端

• Vue 3.3.4
• TypeScript
• Vite 4
• Vant 4.6.0
• Pinia
• Vue Router 4
• Axios
• Tailwind CSS
• 高德地图 JS API Loader

功能模块

管理后台

• 登录认证与验证码
• 公寓信息管理
• 房间信息管理
• 公寓配套与房间配套管理
• 标签、属性、费用项、支付方式、租期配置
• 看房预约管理
• 租约管理
• 系统用户与岗位管理
• 移动端用户管理

移动端 H5

• 手机号验证码登录
• 房源搜索与筛选
• 公寓详情查看
• 房间详情查看
• 预约看房
• 我的预约
• 我的租约
• 浏览历史
• 个人中心

项目结构

lease
├─ README.md
├─ rentHouseAdmin                 # 管理后台前端
├─ rentHouseH5                    # 移动端 H5 前端
└─ qihe-lease                # Spring Boot 后端
   ├─ common                      # 公共模块：工具类、统一返回、异常处理、JWT、MinIO、Redis 等
   ├─ model                       # 数据模型模块：实体类、枚举
   ├─ web
   │  ├─ web-admin                # 管理端 API
   │  └─ web-app                  # H5 API
   └─ pom.xml

后端模块说明

common

公共能力模块，主要包含：

• MyBatis-Plus 配置
• 全局异常处理
• 统一响应对象
• JWT 工具
• 登录用户上下文
• MinIO 配置
• Redis 常量与公共工具
• 阿里云短信配置

model

数据模型模块，主要包含：

• 公寓、房间、租约、预约、用户等实体
• 业务状态枚举
• 基础实体字段定义

web-admin

管理端 API，主要负责：

• 公寓管理
• 房间管理
• 系统管理
• 租赁管理
• 用户管理
• 登录与权限校验

web-app

移动端 API，主要负责：

• 登录与短信验证码
• 地区、租期、支付方式等基础查询
• 房源搜索与详情查询
• 看房预约
• 浏览历史
• 租约信息

核心业务对象

项目当前包含的核心实体主要有：

• ApartmentInfo 公寓
• RoomInfo 房间
• LeaseAgreement 租约
• ViewAppointment 看房预约
• UserInfo 移动端用户
• SystemUser 管理端用户
• SystemPost 岗位
• GraphInfo 图片资源
• FacilityInfo 配套
• LabelInfo 标签
• AttrKey / AttrValue 属性
• FeeKey / FeeValue 费用项
• PaymentType 支付方式
• LeaseTerm 租期

运行环境

建议环境：

• JDK 17
• Maven 3.9+
• Node.js 16+
• MySQL 8.x
• Redis 6.x / 7.x
• MinIO

配置说明

后端核心配置文件：

• web-admin application.yml
• web-app application.yml

当前本地默认配置使用：

• MySQL：localhost:3306
• Redis：127.0.0.1:6379
• MinIO：http://127.0.0.1:9000

前端环境配置文件：

• rentHouseAdmin/.env.development
• rentHouseH5/.env.development

本地启动

1. 启动基础依赖

确保以下服务已可用：

• MySQL
• Redis
• MinIO

2. 启动后端

进入后端目录：

cd qihe-lease

构建：

mvn clean package -DskipTests

启动管理端后端：

mvn -pl web/web-admin spring-boot:run

启动 H5 后端：

mvn -pl web/web-app spring-boot:run

默认端口：

• 管理端 API：http://localhost:8080
• H5 API：http://localhost:8081

接口文档：

• 管理端：http://localhost:8080/doc.html
• H5：http://localhost:8081/doc.html

3. 启动管理端前端

cd rentHouseAdmin
npm install
npm run dev

默认访问地址：

• http://localhost:5173

4. 启动 H5 前端

cd rentHouseH5
npm install
npm run dev

默认访问地址：

• http://localhost:5174

说明：

• 若端口被占用，Vite 会自动顺延到下一个可用端口
• 管理端和 H5 的前端都通过环境变量代理到各自后端

构建命令

后端

cd qihe-lease
mvn clean package -DskipTests

管理端前端

cd rentHouseAdmin
npm run build

H5 前端

cd rentHouseH5
npm run build

接口与鉴权说明

• 管理端通过图形验证码 + 账号密码登录
• H5 通过手机号验证码登录
• 鉴权令牌采用 JWT
• 请求头使用 access-token
• 部分 H5 接口依赖登录态访问

图片与文件存储说明

项目中的房源图片、公寓图片依赖 MinIO 存储。数据库 graph_info 表中保存的是图片 URL。

如果你导入的是历史数据库数据，可能会遇到以下情况：

• 数据库里的图片 URL 指向旧环境
• 本地 MinIO 中不存在对应对象
• 页面显示“加载失败”

处理方式：

1. 在管理后台重新上传公寓或房间图片
2. 或者批量迁移图片资源并更新 graph_info.url

常见问题

1. 页面能打开，但部分接口返回未登录

原因：

• 该接口需要 JWT 登录态
• 请求头未携带 access-token

2. H5 房源图片显示“加载失败”

原因：

• 数据库中保存的是旧图片地址
• MinIO 中没有对应对象

3. 后端能启动，但登录或业务接口报错

优先检查：

• MySQL 配置是否正确
• Redis 是否已启动
• MinIO 是否可访问
• 数据库表和基础数据是否完整

4. 前端改了 .env 但页面标题没更新

原因：

• Vite 在启动时读取环境变量

处理：

• 重启前端开发服务

适合继续扩展的方向

• 增加审核流，如预约审核、租约审批
• 增加操作日志和审计日志
• 增加房源上下架记录
• 增加首页统计看板
• 增加短信模板与通知管理
• 增加对象存储资源管理页
• 增加 Docker 一键部署脚本

说明

• 当前目录名仍保留原始工程结构，不影响运行
• 若用于作品集或实习项目展示，建议继续统一数据库演示数据、默认账号、接口域名和对象存储资源