# Hotel-Management-System

**Repository Path**: shadowofnight/hotel-management-system

## Basic Information

- **Project Name**: Hotel-Management-System
- **Description**: 本系统是一套面向中小型酒店、宾馆的综合性管理平台，覆盖前台接待、客房管理、预订管理、收银结账、餐饮挂账、会员管理、评价管理、渠道管理、财务管理、操作日志审计、验证码安全及系统配置等核心业务。支持第三方平台预付订单处理，实现全渠道统一管控。系统通过可视化房态图、流程化操作与精细化权限控制，帮助酒店提升运营效率、降低人工失误，并提供多角色协同作业能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: backend
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-11-10
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 酒店管理系统 - 后端服务

## 📋 项目概述

酒店管理系统后端服务采用 Spring Boot 3.2 + Java 21
构建，基于微服务架构设计，提供完整的酒店业务管理功能，包括房态管理、预订管理、入住管理、收银管理、客房服务、餐饮管理、会员管理、渠道对接等核心模块。

### 技术栈

| 技术           | 版本      | 说明       |
|--------------|---------|----------|
| Spring Boot  | 3.2.0   | 核心框架     |
| Java         | 21      | 编程语言     |
| MyBatis-Plus | 3.5.5   | ORM框架    |
| MySQL        | 8.0     | 关系型数据库   |
| Redis        | 7.2     | 缓存数据库    |
| RabbitMQ     | 3.12    | 消息队列     |
| JWT          | 0.12.3  | 身份认证     |
| SpringDoc    | 2.3.0   | API文档    |
| EasyExcel    | 3.3.3   | Excel处理  |
| Hutool       | 5.8.22  | Java工具类库 |
| Lombok       | 1.18.30 | 简化Java代码 |

### 项目架构

```
backend/
├── hotel-api/              # API网关模块 - 聚合所有服务
├── hotel-auth/             # 认证授权模块 - JWT认证、权限控制
├── hotel-common/           # 公共模块 - 工具类、常量、异常处理
├── hotel-pms/              # 核心业务模块 - 房态、预订、入住、收银
├── hotel-crm/              # 客户关系模块 - 会员、协议单位、评价
├── hotel-restaurant/       # 餐饮模块 - 餐饮录单、对账
├── hotel-housekeeping/     # 客房模块 - 清扫任务、维修管理
├── hotel-report/           # 报表模块 - 营业报表、统计分析
├── hotel-channel/          # 渠道模块 - OTA对接、订单同步
├── hotel-system/           # 系统模块 - 用户、角色、菜单、配置
└── hotel-task/             # 定时任务模块 - 夜审、数据同步
```

---

## 🚀 快速开始

### 环境要求

- JDK 21+
- Maven 3.9+
- MySQL 8.0+
- Redis 7.2+
- RabbitMQ 3.12+（可选，用于渠道对接）

### 本地开发

#### 1. 克隆项目

```bash
git clone https://gitee.com/Zhi_Leo/hotel-management-system.git
cd HotelManagement/backend
```

#### 2. 配置数据库

创建数据库：

```sql
CREATE DATABASE hotel_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

导入初始化脚本：

```bash
mysql -u root -p hotel_management < sql/hotel_management.sql
```

#### 3. 修改配置

编辑 `hotel-api/src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/hotel_management?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: your_password
  data:
    redis:
      host: localhost
      port: 6379
      password:
```

#### 4. 启动项目

```bash
# 编译项目
mvn clean install

# 启动服务
cd hotel-api
mvn spring-boot:run
```

访问 Swagger 文档：http://localhost:8080/swagger-ui.html

---

## 📖 API 接口文档

### 认证相关接口

#### 1. 获取验证码

**请求：**

```http
GET /v1/auth/captcha
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "captchaKey": "uuid-xxxx",
    "captchaImage": "data:image/png;base64,..."
  }
}
```

#### 2. 用户登录

**请求：**

```http
POST /v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456",
  "captchaKey": "uuid-xxxx",
  "captchaCode": "1234"
}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "realName": "系统管理员",
      "roles": ["SUPER_ADMIN"],
      "permissions": ["*"]
    }
  }
}
```

#### 3. 刷新Token

**请求：**

```http
POST /v1/auth/refresh
Authorization: Bearer {token}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "new-token..."
  }
}
```

### 房态管理接口

#### 1. 获取房态概览

**请求：**

```http
GET /v1/room/status/overview
Authorization: Bearer {token}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "available": 45,
    "occupied": 40,
    "cleaning": 10,
    "repair": 5
  }
}
```

#### 2. 获取房间列表

**请求：**

```http
GET /v1/room/list?page=1&size=20&status=AVAILABLE
Authorization: Bearer {token}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      {
        "id": 1,
        "roomNumber": "101",
        "roomTypeName": "标准单人间",
        "floor": 1,
        "status": "AVAILABLE",
        "price": 288.00
      }
    ],
    "totalElements": 100,
    "totalPages": 5
  }
}
```

### 预订管理接口

#### 1. 创建预订

**请求：**

```http
POST /v1/reservation/create
Authorization: Bearer {token}
Content-Type: application/json

{
  "guestName": "张三",
  "phone": "13800138000",
  "roomTypeId": 1,
  "checkInDate": "2026-08-01",
  "checkOutDate": "2026-08-03",
  "pricePlanId": 1,
  "remark": "预订备注"
}
```

**响应：**

```json
{
  "code": 200,
  "message": "预订创建成功",
  "data": {
    "id": 1,
    "reservationNo": "R20260730001",
    "status": "CONFIRMED"
  }
}
```

#### 2. 查询预订列表

**请求：**

```http
GET /v1/reservation/list?page=1&size=20&status=CONFIRMED
Authorization: Bearer {token}
```

### 入住管理接口

#### 1. 快速入住

**请求：**

```http
POST /v1/stay/check-in
Authorization: Bearer {token}
Content-Type: application/json

{
  "roomId": 1,
  "guestName": "张三",
  "idCard": "123456789012345678",
  "phone": "13800138000",
  "checkInDate": "2026-07-30",
  "expectedCheckOut": "2026-08-01",
  "depositAmount": 500.00,
  "dailyRate": 288.00,
  "pricePlanId": 1
}
```

**响应：**

```json
{
  "code": 200,
  "message": "入住成功",
  "data": {
    "stayId": 1,
    "roomNumber": "101",
    "billNo": "B20260730001"
  }
}
```

#### 2. 换房操作

**请求：**

```http
POST /v1/stay/change-room
Authorization: Bearer {token}
Content-Type: application/json

{
  "stayId": 1,
  "newRoomId": 2,
  "reason": "房间设施故障"
}
```

#### 3. 延住操作

**请求：**

```http
POST /v1/stay/extend
Authorization: Bearer {token}
Content-Type: application/json

{
  "stayId": 1,
  "newCheckOutDate": "2026-08-05"
}
```

### 收银管理接口

#### 1. 查询账单

**请求：**

```http
GET /v1/bill/detail?stayId=1
Authorization: Bearer {token}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "billId": 1,
    "billNo": "B20260730001",
    "totalAmount": 576.00,
    "paidAmount": 500.00,
    "items": [
      {
        "itemType": "ROOM_RATE",
        "itemName": "房费",
        "unitPrice": 288.00,
        "quantity": 2,
        "amount": 576.00
      },
      {
        "itemType": "DEPOSIT",
        "itemName": "押金",
        "unitPrice": 500.00,
        "quantity": 1,
        "amount": 500.00
      }
    ]
  }
}
```

#### 2. 添加消费项目

**请求：**

```http
POST /v1/bill/add-item
Authorization: Bearer {token}
Content-Type: application/json

{
  "billId": 1,
  "itemType": "MINI_BAR",
  "itemName": "矿泉水",
  "unitPrice": 10.00,
  "quantity": 2
}
```

#### 3. 结账退房

**请求：**

```http
POST /v1/bill/checkout
Authorization: Bearer {token}
Content-Type: application/json

{
  "stayId": 1,
  "paymentMethod": "CASH",
  "paidAmount": 600.00
}
```

---

## 🗄️ 数据库设计

### 核心数据表

#### 1. 房间相关表

**room_type（房型表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| type_name | varchar(50) | 房型名称 |
| base_price | decimal(10,2) | 基础价格 |
| capacity | int | 容纳人数 |
| description | varchar(500) | 描述 |
| amenities | varchar(500) | 设施配置 |

**room（房间表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| room_number | varchar(10) | 房间号 |
| room_type_id | bigint | 房型ID |
| floor_id | bigint | 楼层ID |
| status | tinyint | 房态：空房/占用/清扫/维修 |
| room_number | varchar(10) | 房间号 |

**floor（楼层表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| floor_number | int | 楼层号 |
| room_count | int | 房间数 |

#### 2. 预订入住表

**reservation（预订表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| reservation_no | varchar(30) | 预订号 |
| guest_name | varchar(50) | 客人姓名 |
| phone | varchar(20) | 联系电话 |
| room_type_id | bigint | 房型ID |
| check_in_date | date | 预计入住日期 |
| check_out_date | date | 预计离店日期 |
| status | tinyint | 状态：待确认/已确认/已入住/已取消 |
| price_plan_id | bigint | 价格计划ID |

**stay（入住表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| room_id | bigint | 房间ID |
| guest_name | varchar(50) | 客人姓名 |
| id_card | varchar(20) | 身份证号 |
| phone | varchar(20) | 联系电话 |
| check_in_time | datetime | 入住时间 |
| expected_check_out | date | 预计离店日期 |
| actual_check_out | datetime | 实际离店时间 |
| status | tinyint | 状态：在住/已退房 |
| daily_rate | decimal(10,2) | 每日房价 |

#### 3. 账单相关表

**bill（账单表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| bill_no | varchar(30) | 账单号 |
| stay_id | bigint | 入住ID |
| total_amount | decimal(12,2) | 总金额 |
| paid_amount | decimal(12,2) | 已付金额 |
| discount_amount | decimal(12,2) | 优惠金额 |
| status | tinyint | 状态：未结清/已结清 |

**bill_item（账单明细表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| bill_id | bigint | 账单ID |
| item_type | tinyint | 项目类型：房费/餐饮/迷你吧/赔偿/押金 |
| item_name | varchar(100) | 项目名称 |
| unit_price | decimal(10,2) | 单价 |
| quantity | int | 数量 |
| amount | decimal(12,2) | 金额 |

#### 4. 会员相关表

**member（会员表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| member_no | varchar(30) | 会员号 |
| name | varchar(50) | 姓名 |
| phone | varchar(20) | 手机号 |
| level | int | 等级 |
| points | int | 积分 |
| balance | decimal(12,2) | 余额 |

**corporate（协议单位表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| corporate_name | varchar(100) | 单位名称 |
| contact_person | varchar(50) | 联系人 |
| contact_phone | varchar(20) | 联系电话 |
| discount_rate | decimal(5,2) | 折扣率 |

#### 5. 系统管理表

**user（用户表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| username | varchar(50) | 用户名 |
| password | varchar(100) | 密码 |
| real_name | varchar(50) | 真实姓名 |
| phone | varchar(20) | 手机号 |
| email | varchar(100) | 邮箱 |
| status | tinyint | 状态：正常/禁用 |

**role（角色表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| role_name | varchar(50) | 角色名称 |
| role_code | varchar(50) | 角色编码 |
| description | varchar(200) | 描述 |

**menu（菜单表）**
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| menu_name | varchar(50) | 菜单名称 |
| parent_id | bigint | 父菜单ID |
| path | varchar(200) | 路由路径 |
| permission | varchar(50) | 权限标识 |

### ER 关系图

```
room_type 1:N room
floor 1:N room
room 1:N stay
reservation 1:1 stay
stay 1:1 bill
bill 1:N bill_item
member N:N stay
corporate N:N stay
user N:N role
role N:N menu
```

---

## 🔧 环境配置

### 配置文件说明

#### application.yml

```yaml
server:
  port: 8080

spring:
  application:
    name: hotel-management
  
  # 数据源配置
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/hotel_management
    username: root
    password: root
    
  # Redis配置
  data:
    redis:
      host: localhost
      port: 6379
      password:
      database: 0
      
  # 文件上传配置
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 20MB

# JWT配置
jwt:
  secret: hotel-management-jwt-secret-key
  expiration: 86400000  # 24小时
  refresh-expiration: 604800000  # 7天

# MyBatis-Plus配置
mybatis-plus:
  mapper-locations: classpath*:mapper/**/*.xml
  type-aliases-package: com.hotel.*.entity
  configuration:
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
```

### 环境变量

| 变量名            | 说明            | 默认值                             |
|----------------|---------------|---------------------------------|
| DB_HOST        | 数据库主机         | localhost                       |
| DB_PORT        | 数据库端口         | 3306                            |
| DB_NAME        | 数据库名称         | hotel_management                |
| DB_USERNAME    | 数据库用户名        | root                            |
| DB_PASSWORD    | 数据库密码         | root                            |
| REDIS_HOST     | Redis主机       | localhost                       |
| REDIS_PORT     | Redis端口       | 6379                            |
| JWT_SECRET     | JWT密钥         | hotel-management-jwt-secret-key |
| JWT_EXPIRATION | Token过期时间（毫秒） | 86400000                        |

---

## 🐳 Docker 部署

### 构建镜像

```bash
# 构建后端镜像
cd backend
docker build -t hotel-backend:1.0.0 .
```

### Docker Compose 部署

项目根目录提供了完整的 docker-compose.yml 文件：

```bash
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f backend

# 停止服务
docker-compose down
```

### Docker Compose 配置说明

```yaml
services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "9073:9073"
    environment:
      JAVA_OPTS: "-Xmx512m -Xms256m"
      SPRING_PROFILES_ACTIVE: prod
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/hotel_management
      SPRING_DATASOURCE_USERNAME: hotel_user
      SPRING_DATASOURCE_PASSWORD: hotel_pass
      SPRING_DATA_REDIS_HOST: redis
      SPRING_DATA_REDIS_PORT: 6379
    depends_on:
      - mysql
      - redis
      - rabbitmq
```

---

## 📝 开发规范

### 代码规范

#### 1. 命名规范

- **类名**：大驼峰命名法（UserService）
- **方法名**：小驼峰命名法（getUserById）
- **常量**：全大写下划线分隔（MAX_SIZE）
- **包名**：全小写

#### 2. 分层架构

```
controller/   - 控制层：处理HTTP请求
service/      - 服务层：业务逻辑处理
mapper/       - 数据访问层：数据库操作
entity/       - 实体类：数据库表映射
dto/          - 数据传输对象：接口参数响应
vo/           - 视图对象：前端展示数据
enums/        - 枚举类：常量定义
config/       - 配置类：框架配置
```

#### 3. 异常处理

统一使用 `GlobalExceptionHandler` 处理异常：

```java
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BusinessException.class)
    public R<Void> handleBusinessException(BusinessException e) {
        return R.fail(e.getCode(), e.getMessage());
    }
    
    @ExceptionHandler(Exception.class)
    public R<Void> handleException(Exception e) {
        return R.fail(500, "系统异常");
    }
}
```

#### 4. 统一响应格式

所有接口统一返回 `R<T>` 格式：

```java
public class R<T> {
    private int code;
    private String message;
    private T data;
}
```

### 日志规范

```java
@Slf4j
@Service
public class UserServiceImpl implements UserService {
    
    public User getUserById(Long id) {
        log.debug("查询用户信息，userId: {}", id);
        User user = userMapper.selectById(id);
        log.info("查询用户成功，userName: {}", user.getUsername());
        return user;
    }
}
```

### 事务管理

```java
@Service
@Transactional(rollbackFor = Exception.class)
public class ReservationServiceImpl implements ReservationService {
    
    @Override
    public void createReservation(ReservationDTO dto) {
        // 业务逻辑
    }
}
```

### 权限控制

使用 Spring Security + JWT 进行权限控制：

```java
@PreAuthorize("hasPermission('reservation:create')")
@PostMapping("/create")
public R<Long> create(@RequestBody ReservationDTO dto) {
    return R.ok(reservationService.createReservation(dto));
}
```

---

## 🔒 安全措施

### 1. 认证授权

- JWT Token 认证
- 密码 BCrypt 加密
- Redis 存储 Token 黑名单
- TOTP 双因素认证（可选）

### 2. 数据安全

- 敏感字段脱敏（手机号、身份证）
- SQL 注入防护（MyBatis-Plus）
- XSS 攻击防护
- CSRF 防护

### 3. 接口安全

- 接口限流（基于 Redis）
- IP 白名单
- 验证码校验
- 操作日志记录

---

## 📊 性能优化

### 1. 数据库优化

- 使用 MyBatis-Plus 分页插件
- 开启 SQL 执行日志
- 配置 HikariCP 连接池
- 建立必要的索引

### 2. 缓存优化

- Redis 缓存热点数据
- 使用 Spring Cache 注解
- 配置缓存过期时间
- 避免缓存穿透

### 3. 异步处理

- 使用 RabbitMQ 处理异步任务
- 渠道订单异步同步
- 消息推送异步发送

---

## 🧪 测试

### 单元测试

```bash
# 运行所有测试
mvn test

# 运行指定测试类
mvn test -Dtest=UserServiceTest
```

### 接口测试

使用 Postman 或 Swagger UI 进行接口测试。

---

## 📚 相关文档

- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [MyBatis-Plus 官方文档](https://baomidou.com/)
- [Spring Security 官方文档](https://spring.io/projects/spring-security)
- [Redis 官方文档](https://redis.io/documentation)

---

## 👨‍💻 作者

酒店管理系统开发团队
负责人：Aimee

---

## 📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。