# EasyleaseFrontend

**Repository Path**: ChanYeeSum/easylease-frontend

## Basic Information

- **Project Name**: EasyleaseFrontend
- **Description**: 宅易租的前端
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-04-16
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: easylease

## README

# 宅易租 v1.0.0

> 基于 Spring Boot + Vue3 的公寓租赁管理系统，提供完整的房屋租赁业务解决方案

## 目录

- [系统架构](#系统架构)
- [技术亮点](#技术亮点)
- [核心技术](#核心技术)
- [模块设计](#模块设计)
- [数据库设计](#数据库设计)
- [接口规范](#接口规范)
- [部署指南](#部署指南)
- [开发规范](#开发规范)
- [常见问题](#常见问题)

---

## 系统架构

### 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                         客户端层                              │
├─────────────────────────────────────────────────────────────┤
│  管理端 (Vue3)         │  用户端 (Vue3 H5)                   │
│  Element Plus          │  Vant UI                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         网关层                                │
├─────────────────────────────────────────────────────────────┤
│  Nginx (反向代理、负载均衡、静态资源)                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      应用服务层                               │
├─────────────────────────────────────────────────────────────┤
│  web-admin (管理端服务)    │    web-app (用户端服务)           │
│  ┌──────────┬──────────┐   │   ┌──────────┬──────────┐        │
│  │ Controller│  Service│   │   │ Controller│  Service│        │
│  ├──────────┼──────────┤   │   ├──────────┼──────────┤        │
│  │   Mapper  │   VO    │   │   │   Mapper  │   VO    │        │
│  └──────────┴──────────┘   │   └──────────┴──────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      中间件层                                 │
├─────────────────────────────────────────────────────────────┤
│  Redis (缓存)  │  MinIO (对象存储)  │  阿里云短信服务          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      数据存储层                               │
├─────────────────────────────────────────────────────────────┤
│  MySQL (主数据存储)                                           │
└─────────────────────────────────────────────────────────────┘
```

### 分层设计

- **表现层 (Controller)**: 接收请求、参数校验、响应封装
- **业务层 (Service)**: 业务逻辑处理、事务管理
- **持久层 (Mapper)**: 数据库操作、MyBatis-Plus 封装
- **公共层 (Common)**: 通用工具、异常处理、切面拦截、配置类

---

## 技术亮点

### 1. MyBatis-Plus 自动 CRUD

使用 MyBatis-Plus 框架，实现基础 CRUD 操作的零 SQL 编写，通过继承 `BaseMapper` 和 `IService` 接口快速完成数据访问层开发。

```java
@Service
public class ApartmentInfoServiceImpl extends ServiceImpl<ApartmentInfoMapper, ApartmentInfo> 
    implements ApartmentInfoService {
    // 基础 CRUD 方法已由父类实现
}
```

**优势**：
- 无需编写简单 SQL，提升开发效率
- 支持 Lambda 语法，类型安全
- 内置分页插件，物理分页性能优秀
- 支持多租户、动态表名等高级特性

### 2. JWT 身份认证

基于 JWT 实现无状态身份认证，支持管理端和用户端双重认证体系。

**实现方案**：
- 使用 `io.jsonwebtoken` 库生成和解析 Token
- 管理端和用户端使用不同的 Secret Key 和过期时间
- 拦截器统一校验 Token 有效性
- 支持自定义 Token 传递参数名称

### 3. 图形验证码安全机制

集成 EasyCaptcha 图形验证码，防止恶意登录和暴力破解。

**特性**：
- 支持算术、中文、英文等多种验证码类型
- 验证码存储在 Redis，设置过期时间
- 登录失败次数限制，防止暴力破解

### 4. 阿里云短信服务集成

集成阿里云短信服务，实现手机号验证码登录功能。

**核心功能**：
- 短信验证码发送
- 验证码有效期控制（Redis 存储）
- 发送频率限制，防止短信轰炸
- 支持多种短信模板

### 5. MinIO 对象存储

使用 MinIO 存储图片等非结构化数据，支持公寓图片、房间图片、用户头像等资源管理。

**特性**：
- 自建 MinIO 服务，降低存储成本
- 图片上传、预览、删除完整功能
- 支持桶（Bucket）级别的权限控制
- 前端直连上传，减轻服务端压力

### 6. Redis 缓存优化

使用 Redis 缓存热点数据，减少数据库压力，提升系统性能。

**缓存策略**：
- **验证码缓存**: 短信验证码、图形验证码临时存储
- **Token 缓存**: 用户登录状态管理
- **热点数据缓存**: 省市区数据、公寓配置信息
- **浏览历史**: 用户浏览记录缓存

### 7. HikariCP 连接池优化

使用 HikariCP 高性能数据库连接池，配置完善的保活检测机制。

**优化配置**：
- 连接保活检测：空闲时验证连接有效性
- 连接最小存活时间：5 分钟
- 连接最大存活时间：9 分钟
- 连接池最大连接数：12
- 最小空闲连接数量：10
- 验证查询 SQL：`SELECT 1`

### 8. 统一异常处理

使用 `@RestControllerAdvice` 实现全局异常处理，统一异常响应格式。

**异常类型**：
- `LeaseException`: 业务异常基类
- `AuthException`: 认证异常
- 参数校验异常统一处理
- 系统异常统一包装

### 9. 逻辑删除机制

使用 MyBatis-Plus 逻辑删除功能，实现数据软删除，保留数据可追溯性。

```java
@TableLogic
private Integer isDeleted;
```

### 10. Knife4j 接口文档

集成 Knife4j 生成美观的 API 接口文档，支持在线调试。

**特性**：
- 基于 Swagger/OpenAPI 3.0
- 支持接口分组（管理端/用户端）
- 在线接口测试
- 接口权限注解展示

---

## 核心技术

### 后端技术栈

| 技术                   | 版本       | 说明                      |
| ---------------------- | ---------- | ------------------------- |
| Spring Boot            | 3.0.5      | 核心框架                  |
| MyBatis-Plus           | 3.5.3.1    | ORM 框架                  |
| JWT                    | 0.11.2     | 身份认证                  |
| Redis                  | -          | 缓存/会话存储             |
| MinIO                  | 8.2.0      | 对象存储                  |
| HikariCP               | -          | 数据库连接池              |
| Knife4j                | 4.1.0      | 接口文档                  |
| EasyCaptcha            | 1.6.2      | 图形验证码                |
| 阿里云短信 SDK          | 2.0.1      | 短信服务                  |
| MySQL                  | 8.0+       | 关系型数据库              |

### 前端技术栈

#### 管理端 (rentHouseAdmin)

| 技术                | 版本    | 说明                 |
| ------------------- | ------- | -------------------- |
| Vue                 | 3.3.4   | 前端框架             |
| TypeScript          | 4.9.3   | 类型语言             |
| Element Plus        | 2.3.7   | UI 组件库            |
| Vite                | 4.3.9   | 构建工具             |
| Pinia               | 2.0.30  | 状态管理             |
| Vue Router          | 4.2.2   | 路由管理             |
| Axios               | 1.4.0   | HTTP 客户端          |
| ECharts             | 5.4.1   | 图表库               |
| 高德地图 JS API      | 1.0.1   | 地图服务             |

#### 用户端 (rentHouseH5)

| 技术                | 版本    | 说明                 |
| ------------------- | ------- | -------------------- |
| Vue                 | 3.3.4   | 前端框架             |
| TypeScript          | 4.7.4   | 类型语言             |
| Vant                | 4.6.0   | 移动端 UI 组件库      |
| Vite                | 4.3.9   | 构建工具             |
| Pinia               | 2.1.4   | 状态管理             |
| Tailwind CSS        | 3.3.2   | CSS 框架             |
| Axios               | 1.4.0   | HTTP 客户端          |
| 高德地图 JS API      | 1.0.1   | 地图服务             |

---

## 模块设计

### 后端模块结构

```
lease/
├── common/                          # 公共模块
│   ├── exception/                   # 全局异常类
│   ├── handler/                     # 全局处理器
│   ├── interceptor/                 # 拦截器
│   ├── login/                       # 登录相关
│   ├── minio/                       # MinIO 配置
│   ├── mybatisplus/                 # MyBatis-Plus 配置
│   ├── result/                      # 统一响应结果
│   ├── sms/                         # 短信服务配置
│   └── utils/                       # 工具类
│
├── model/                           # 实体模型模块
│   ├── entity/                      # 数据库实体类
│   ├── enums/                       # 枚举类
│   └── vo/                          # 视图对象
│
└── web/
    ├── web-admin/                   # 管理端服务 (端口: 8080)
    │   └── java/com/cwnu/lease/web/admin/
    │       ├── controller/          # 控制器
    │       ├── service/             # 业务层
    │       ├── mapper/              # 数据访问层
    │       ├── vo/                  # VO 对象
    │       └── schedule/            # 定时任务
    │
    └── web-app/                     # 用户端服务 (端口: 8081)
        └── java/com/cwnu/lease/web/
            ├── controller/          # 控制器
            ├── service/             # 业务层
            ├── mapper/              # 数据访问层
            └── vo/                  # VO 对象
```

### 前端模块结构

#### 管理端 (rentHouseAdmin)

```
rentHouseAdmin/
├── src/
│   ├── api/                         # API 接口
│   │   ├── apartmentManagement/     # 公寓管理接口
│   │   ├── rentManagement/          # 租赁管理接口
│   │   ├── userManagement/          # 用户管理接口
│   │   └── system/                  # 系统管理接口
│   ├── components/                  # 公共组件
│   ├── views/                       # 页面视图
│   │   ├── apartmentManagement/     # 公寓管理
│   │   ├── rentManagement/          # 租赁管理
│   │   ├── userManagement/          # 用户管理
│   │   ├── system/                  # 系统设置
│   │   └── home/                    # 首页
│   ├── router/                      # 路由配置
│   ├── store/                       # Pinia 状态管理
│   ├── utils/                       # 工具函数
│   └── styles/                      # 样式文件
```

#### 用户端 (rentHouseH5)

```
rentHouseH5/
├── src/
│   ├── api/                         # API 接口
│   ├── views/                       # 页面视图
│   ├── components/                  # 公共组件
│   ├── router/                      # 路由配置
│   ├── store/                       # Pinia 状态管理
│   └── utils/                       # 工具函数
```

### 核心业务模块

| 模块           | 功能描述                                           |
| -------------- | -------------------------------------------------- |
| **公寓管理**   | 公寓信息管理、房间配置、配套设施、费用设置、图片管理 |
| **租赁管理**   | 租约管理、租期设置、支付方式、合同管理             |
| **用户管理**   | 用户信息管理、浏览历史、看房预约                   |
| **系统管理**   | 岗位管理、员工管理、权限控制                       |
| **地图服务**   | 公寓位置展示、周边配套、导航功能                   |
| **文件管理**   | 图片上传、MinIO 对象存储管理                       |

---

## 数据库设计

### 核心表结构

| 表名                    | 说明                 |
| ----------------------- | -------------------- |
| `apartment_info`        | 公寓基本信息表       |
| `room_info`             | 房间信息表           |
| `apartment_facility`    | 公寓配套设施关联表   |
| `room_facility`         | 房间配套设施关联表   |
| `apartment_label`       | 公寓标签关联表       |
| `room_label`            | 房间标签关联表       |
| `lease_agreement`       | 租约协议表           |
| `lease_term`            | 租期配置表           |
| `payment_type`          | 支付方式表           |
| `room_payment_type`     | 房间支付方式关联表   |
| `room_lease_term`       | 房间租期关联表       |
| `attr_key` / `attr_value`| 属性键值对配置表     |
| `fee_key` / `fee_value` | 费用键值对配置表     |
| `graph_info`            | 图片信息表           |
| `province_info`         | 省份信息表           |
| `city_info`             | 城市信息表           |
| `district_info`         | 区县信息表           |
| `user_info`             | 用户信息表           |
| `browsing_history`      | 浏览历史表           |
| `view_appointment`      | 看房预约表           |
| `system_user`           | 系统用户表           |
| `system_post`           | 系统岗位表           |
| `label_info`            | 标签信息表           |
| `facility_info`         | 配套设施信息表       |

### 数据库关系图

```
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  province_info  │────────▶│   city_info     │────────▶│ district_info   │
└─────────────────┘         └─────────────────┘         └─────────────────┘
                                                                   │
                                                                   ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│ apartment_info  │◀───────▶│  room_info      │◀────────│   地区关联       │
└────────┬────────┘         └────────┬────────┘         └─────────────────┘
         │                           │
         ▼                           ▼
┌─────────────────┐         ┌─────────────────┐
│ apartment_facility│       │  room_facility  │
│ apartment_label │         │  room_label     │
│ graph_info      │         │  room_payment   │
└─────────────────┘         │  room_lease_term│
                            └─────────────────┘
                                     │
                                     ▼
                            ┌─────────────────┐
                            │ lease_agreement │
                            │ view_appointment│
                            │ browsing_history│
                            └─────────────────┘
```

---

## 接口规范

### 统一响应格式

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

### 响应码定义

| 状态码 | 说明           |
| ------ | -------------- |
| 200    | 操作成功       |
| 400    | 参数错误       |
| 401    | 未登录/Token失效|
| 403    | 无权限         |
| 404    | 资源不存在     |
| 500    | 服务器内部错误 |

### API 分组

- **管理端 API**: `/admin/xxx` (端口: 8080)
- **用户端 API**: `/app/xxx` (端口: 8081)

---

## 部署指南

### 环境要求

- JDK 17+
- MySQL 8.0+
- Redis 6.0+
- Node.js 16+
- MinIO (最新版)

### 后端部署

1. **初始化数据库**

```bash
mysql -u root -p < lease.sql
```

2. **配置 application.yml**

修改 `web-admin` 和 `web-app` 中的数据库、Redis、MinIO 配置：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/lease?useUnicode=true&characterEncoding=utf-8&useSSL=false
    username: your_username
    password: your_password
  data:
    redis:
      host: localhost
      port: 6379
      password: your_password

minio:
  endpoint: http://localhost:9000
  access-key: your_access_key
  secret-key: your_secret_key
  bucket-name: lease
```

3. **编译打包**

```bash
cd lease
mvn clean package -DskipTests
```

4. **启动服务**

```bash
# 启动管理端服务
java -jar web/web-admin/target/web-admin-1.0-SNAPSHOT.jar

# 启动用户端服务
java -jar web/web-app/target/web-app-1.0-SNAPSHOT.jar
```

### 前端部署

#### 管理端

```bash
cd frontend/rentHouseAdmin
npm install
npm run build
# 将 dist 目录部署到 Nginx
```

#### 用户端

```bash
cd frontend/rentHouseH5
npm install
npm run build
# 将 dist 目录部署到 Nginx
```

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 管理端
    location /admin {
        alias /path/to/rentHouseAdmin/dist;
        try_files $uri $uri/ /admin/index.html;
    }

    # 用户端
    location /app {
        alias /path/to/rentHouseH5/dist;
        try_files $uri $uri/ /app/index.html;
    }

    # API 代理
    location /admin-api/ {
        proxy_pass http://localhost:8080/;
    }

    location /app-api/ {
        proxy_pass http://localhost:8081/;
    }
}
```

---

## 开发规范

### 代码规范

- 遵循阿里巴巴 Java 开发手册
- 使用统一的代码格式化配置（.editorconfig）
- 前端使用 ESLint + Prettier 统一代码风格

### 分支管理

- `main`: 主分支，稳定版本
- `develop`: 开发分支
- `feature/*`: 功能分支
- `bugfix/*`: 修复分支

### 提交规范

```
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具相关
```

---

## 常见问题

### 1. MinIO 图片上传失败

**问题**: 上传图片时提示连接失败

**解决**: 
- 检查 MinIO 服务是否启动
- 确认 `minio.endpoint` 配置正确
- 检查 Bucket 是否存在且权限正确

### 2. 短信发送失败

**问题**: 短信验证码发送失败

**解决**:
- 检查阿里云短信配置是否正确
- 确认短信模板已通过审核
- 查看阿里云控制台错误码说明

### 3. Redis 连接失败

**问题**: 启动时提示 Redis 连接错误

**解决**:
- 检查 Redis 服务是否启动
- 确认密码配置正确
- 检查防火墙设置

### 4. 跨域问题

**问题**: 前端请求报 CORS 错误

**解决**:
- 后端已配置 CORS，检查 allowed origins 是否包含前端地址
- Nginx 代理配置是否正确

---

## 项目预览

### 管理端

- 登录页：账号密码 + 图形验证码登录
- 公寓管理：公寓列表、新增/编辑公寓、房间管理
- 租赁管理：租约列表、租期配置、支付方式
- 用户管理：用户信息、浏览历史、看房预约
- 系统设置：岗位管理、员工管理

### 用户端 (H5)

- 首页：公寓推荐、搜索、筛选
- 公寓详情：图片展示、配套设施、地图位置
- 预约看房：在线预约、查看预约记录
- 个人中心：我的租约、浏览历史、个人信息

---

## 联系我们

如有问题或建议，欢迎提交 Issue 或联系项目维护者。

---

## 许可证

[MIT License](./LICENSE)