# 酒店系统 **Repository Path**: zmd1992/hotel-system ## Basic Information - **Project Name**: 酒店系统 - **Description**: 用户系统：注册、登录、JWT 认证，支持 ADMIN / STAFF / CUSTOMER 三种角色 房型管理：标准间、豪华间、套房、总统套房等多级房型 CRUD 房间管理：单体房间状态管理（可用/已订/维护/预订） 订单管理：完整订单生命周期（待确认→已确认→已入住→已退房→已取消/已退款） 支付集成：支付宝（WAP 支付）和微信支付（扫码支付），支持 Mock 模式 数据统计：Dashboar - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-17 - **Last Updated**: 2026-06-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 酒店管理系统 (Hotel Management System) ## 目录 1. [项目概述](#1-项目概述) 2. [技术栈](#2-技术栈) 3. [系统架构](#3-系统架构) 4. [模块说明](#4-模块说明) 5. [数据库设计](#5-数据库设计) 6. [API 接口文档](#6-api-接口文档) 7. [快速启动](#7-快速启动) 8. [部署指南](#8-部署指南) 9. [项目截图](#9-项目截图) --- ## 1. 项目概述 全栈酒店管理系统，包含三个子项目： | 子项目 | 路径 | 说明 | |--------|------|------| | **Backend** | `backend/` | Spring Boot 3.2.1 REST API 后端服务 | | **Frontend** | `frontend/` | 客户前端 Vue 3 SPA（面向酒店客人） | | **Admin** | `admin/` | 管理后台 Vue 3 SPA（面向酒店员工/管理员） | ### 功能特性 - **用户系统**：注册、登录、JWT 认证，支持 ADMIN / STAFF / CUSTOMER 三种角色 - **房型管理**：标准间、豪华间、套房、总统套房等多级房型 CRUD - **房间管理**：单体房间状态管理（可用/已订/维护/预订） - **订单管理**：完整订单生命周期（待确认→已确认→已入住→已退房→已取消/已退款） - **支付集成**：支付宝（WAP 支付）和微信支付（扫码支付），支持 Mock 模式 - **数据统计**：Dashboard 订单统计、收入统计、房间状态分布图表 --- ## 2. 技术栈 ### 后端 | 技术 | 版本 | 用途 | |------|------|------| | Java | 17 | 运行环境 | | Spring Boot | 3.2.1 | Web 框架 | | Spring Security | 6.x | 认证授权 | | Spring Data JPA / Hibernate | 6.x | ORM | | MySQL | 8.x | 数据库 | | JJWT | 0.12.3 | JWT 令牌 | | Lombok | 最新 | 简化代码 | | SpringDoc OpenAPI | 2.3.0 | API 文档（Swagger） | | Gson | 最新 | JSON 处理 | ### 前端（客户 & 管理后台） | 技术 | 版本 | 用途 | |------|------|------| | Vue | 3.4.15 | 前端框架 | | Vite | 5.0.11 | 构建工具 | | Pinia | 2.1.7 | 状态管理 | | Vue Router | 4.2.5 | 路由 | | Element Plus | 2.5.3 | UI 组件库 | | Axios | 1.6.5 | HTTP 客户端 | | Tailwind CSS | 3.4.1 | 样式框架（仅前端） | | ECharts | 5.4.3 | 图表（仅管理后台） | | dayjs | 1.11.10 | 日期处理 | --- ## 3. 系统架构 ### 分层架构（后端） ``` ┌─────────────────────────────────────────────┐ │ Controller 层 (REST API) │ │ AuthController / RoomController / ... │ ├─────────────────────────────────────────────┤ │ Service 层 (业务逻辑) │ │ AuthService / OrderService / ... │ ├─────────────────────────────────────────────┤ │ Repository 层 (数据访问 / JPA) │ ├─────────────────────────────────────────────┤ │ Entity 层 (数据模型) │ │ User / Role / Room / Order / Payment / ... │ └─────────────────────────────────────────────┘ ``` ### 前端架构 ``` ┌──────────────────┐ ┌──────────────────┐ │ 客户前端 :5173 │ │ 管理后台 :5174 │ │ (Tailwind + EP) │ │ (Element Plus) │ ├──────────────────┤ ├──────────────────┤ │ Pinia Store │ │ Pinia Store │ │ Vue Router │ │ Vue Router │ │ Axios -> /api │ │ Axios -> /api │ └────────┬─────────┘ └────────┬─────────┘ │ │ └──────────┬─────────────┘ │ /api (反向代理) ▼ ┌──────────────────┐ │ Backend :8081 │ │ Spring Boot API │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ MySQL :13306 │ └──────────────────┘ ``` ### 安全架构 - **JWT 认证**：用户注册/登录后获得 JWT Token，后续请求通过 `Authorization: Bearer ` 携带 - `JwtAuthenticationFilter` 拦截所有请求，解析 Token 并设置 SecurityContext - `SecurityConfig` 配置公开端点（`/api/auth/**`, `/api/public/**`, Swagger）和管理员端点权限 - **RBAC 权限模型**：用户 → 角色（Role）→ 权限（Permission），支持细粒度权限控制 --- ## 4. 模块说明 ### 4.1 认证模块 (`AuthController`) | 功能 | 端点 | 说明 | |------|------|------| | 注册 | `POST /api/auth/register` | 用户名/邮箱唯一性校验，BCrypt 加密密码 | | 登录 | `POST /api/auth/login` | 认证后返回 JWT Token（24h 有效期） | | 当前用户 | `GET /api/auth/me` | 获取当前登录用户信息 | ### 4.2 房间模块 (`RoomController`) - **房型管理**：创建/更新/删除房型（标准间、豪华间、套房、总统套房） - **房间管理**：每个房型下有多个实体房间，支持状态变更（可用/入住/维护/预订） - **可用性查询**：按日期范围查询可用房间（JPQL 子查询排除冲突订单） - **默认数据**：系统启动时初始化 4 种房型、34 个房间 ### 4.3 订单模块 (`OrderController`) 订单状态流转： ``` PENDING(待确认) ──→ CONFIRMED(已确认) ──→ CHECKED_IN(已入住) ──→ CHECKED_OUT(已退房) │ │ │ └──→ CANCELLED(已取消)──→ REFUNDED(已退款) └──→ (可续住) ``` | 功能 | 说明 | |------|------| | 创建订单 | 选择房型和日期，系统自动分配可用房间 | | 订单确认 | 管理员/员工确认待处理订单 | | 入住登记 | 登记客人信息（姓名、电话、身份证、人数） | | 退房结账 | 完成退房，计算实际费用 | | 订单取消 | 可取消待确认/已确认/已入住订单 | | 续住 | 已入住的订单可延长入住天数 | | 数据统计 | 订单数量、收入统计（按日期范围） | ### 4.4 支付模块 (`PaymentController`) - **支付宝集成**：WAP 支付，完整生命周期（下单、查询、退款），RSA2 签名 - **微信支付**：扫码支付模式，完整生命周期（下单、查询、关闭、退款），MD5 签名 - **Mock 模式**：当 app-id 以 `your-` 开头时自动启用，生成假二维码/URL，无需真实商户号 - 支持退款操作（管理员权限） ### 4.5 管理后台 | 页面 | 路由 | 功能 | |------|------|------| | Dashboard | `/` | 统计概览 + 房间状态分布饼图 | | 房间管理 | `/rooms` | 房间 CRUD + 状态变更 | | 房型管理 | `/room-types` | 房型 CRUD | | 订单管理 | `/orders` | 订单列表 + 状态流转操作 | | 用户管理 | `/users` | 用户列表 + 启用/禁用 | | 支付管理 | `/payments` | 支付记录 + 退款操作 | ### 4.6 客户前端 | 页面 | 路由 | 功能 | |------|------|------| | 首页 | `/` | Hero 区域 + 房型预览 | | 房间列表 | `/rooms` | 所有房型展示 | | 房间详情 | `/rooms/:id` | 房型详细信息 + 预订入口 | | 预订 | `/booking/:id` | 选择日期、填写信息、下单 | | 我的订单 | `/orders` | 查看自己的所有订单 | | 个人中心 | `/profile` | 个人信息修改 | | 登录/注册 | `/login`, `/register` | 用户认证 | --- ## 5. 数据库设计 ### 实体关系图 ``` ┌─────────┐ ┌──────────┐ ┌────────────┐ │ User │────▶│ Role │◀───▶│ Permission │ └────┬────┘ └──────────┘ └────────────┘ │ │───▶ Order ───▶ Room ───▶ RoomType │ └───▶ Payment ``` ### 表结构
users — 用户表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | BIGINT | PK, AUTO_INCREMENT | 用户 ID | | username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 | | email | VARCHAR(100) | UNIQUE, NOT NULL | 邮箱 | | password | VARCHAR(255) | NOT NULL | BCrypt 加密密码 | | full_name | VARCHAR(100) | | 真实姓名 | | phone | VARCHAR(20) | | 手机号 | | avatar | VARCHAR(500) | | 头像 URL | | role_id | BIGINT | FK → roles.id | 角色 | | active | BOOLEAN | DEFAULT TRUE | 是否启用 | | created_at | TIMESTAMP | | 创建时间 | | updated_at | TIMESTAMP | | 更新时间 |
roles — 角色表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | BIGINT | PK, AUTO_INCREMENT | 角色 ID | | name | VARCHAR(50) | UNIQUE, NOT NULL | 角色名 (ADMIN/STAFF/CUSTOMER) | | description | VARCHAR(255) | | 描述 |
多对多关联表：`user_roles` (user_id, role_id), `role_permissions` (role_id, permission_id)
permissions — 权限表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | BIGINT | PK, AUTO_INCREMENT | 权限 ID | | name | VARCHAR(50) | UNIQUE, NOT NULL | 权限名 | | description | VARCHAR(255) | | 描述 | | resource | VARCHAR(100) | | 资源 | | action | VARCHAR(50) | | 操作 |
room_types — 房型表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | BIGINT | PK, AUTO_INCREMENT | 房型 ID | | name | VARCHAR(100) | UNIQUE, NOT NULL | 房型名 | | description | TEXT | | 描述 | | price | DECIMAL(10,2) | NOT NULL | 每晚价格 | | capacity | INT | | 最大入住人数 | | bed_count | INT | | 床位数 | | amenities | TEXT | | 设施（JSON 或逗号分隔） | | image_url | VARCHAR(500) | | 图片 URL | | active | BOOLEAN | DEFAULT TRUE | 是否启用 |
rooms — 房间表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | BIGINT | PK, AUTO_INCREMENT | 房间 ID | | room_number | VARCHAR(20) | UNIQUE, NOT NULL | 房间号 | | floor | INT | | 楼层 | | description | TEXT | | 描述 | | image_url | VARCHAR(500) | | 图片 URL | | room_type_id | BIGINT | FK → room_types.id | 所属房型 | | status | VARCHAR(20) | NOT NULL | AVAILABLE/OCCUPIED/MAINTENANCE/RESERVED | | active | BOOLEAN | DEFAULT TRUE | 是否启用 |
orders — 订单表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | BIGINT | PK, AUTO_INCREMENT | 订单 ID | | order_number | VARCHAR(50) | UNIQUE, NOT NULL | 订单号 | | user_id | BIGINT | FK → users.id | 下单用户 | | room_id | BIGINT | FK → rooms.id | 预订房间 | | check_in_date | DATE | NOT NULL | 入住日期 | | check_out_date | DATE | NOT NULL | 退房日期 | | nights | INT | NOT NULL | 入住晚数 | | room_price | DECIMAL(10,2) | | 房单价 | | total_amount | DECIMAL(10,2) | | 总金额 | | discount_amount | DECIMAL(10,2) | DEFAULT 0 | 折扣金额 | | final_amount | DECIMAL(10,2) | | 实付金额 | | status | VARCHAR(20) | NOT NULL | PENDING/CONFIRMED/CHECKED_IN/CHECKED_OUT/CANCELLED/REFUNDED | | guest_name | VARCHAR(100) | | 客人姓名 | | guest_phone | VARCHAR(20) | | 客人电话 | | guest_id_card | VARCHAR(50) | | 客人身份证 | | guest_count | INT | | 客人数量 | | special_requests | TEXT | | 特殊要求 | | confirmed_at | TIMESTAMP | | 确认时间 | | checked_in_at | TIMESTAMP | | 入住时间 | | checked_out_at | TIMESTAMP | | 退房时间 | | cancelled_at | TIMESTAMP | | 取消时间 | | cancel_reason | VARCHAR(500) | | 取消原因 |
payments — 支付表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | BIGINT | PK, AUTO_INCREMENT | 支付 ID | | payment_number | VARCHAR(50) | UNIQUE, NOT NULL | 支付单号 | | order_id | BIGINT | FK → orders.id | 关联订单 | | user_id | BIGINT | FK → users.id | 支付用户 | | amount | DECIMAL(10,2) | NOT NULL | 支付金额 | | payment_method | VARCHAR(20) | NOT NULL | ALIPAY/WECHAT_PAY/CREDIT_CARD/CASH | | status | VARCHAR(20) | NOT NULL | PENDING/PAID/REFUNDED/FAILED/EXPIRED | | transaction_id | VARCHAR(100) | | 交易流水号 | | alipay_trade_no | VARCHAR(100) | | 支付宝交易号 | | wechat_pay_transaction_id | VARCHAR(100) | | 微信支付交易号 | | pay_params | TEXT | | 支付参数（JSON） | | return_url | VARCHAR(500) | | 支付回跳 URL |
--- ## 6. API 接口文档 > 启动后端后可通过 Swagger UI 在线查看：`http://localhost:8081/swagger-ui.html` ### 6.1 公开接口（无需认证） | 方法 | 端点 | 说明 | |------|------|------| | POST | `/api/auth/register` | 用户注册 | | POST | `/api/auth/login` | 用户登录 | | GET | `/api/public/room-types` | 获取所有可用房型 | | GET | `/api/public/room-types/{id}` | 获取房型详情 | | GET | `/api/public/rooms` | 查询房间（支持 typeId, status, 日期范围） | | GET | `/api/public/rooms/{id}` | 获取房间详情 | ### 6.2 需要认证（客户） | 方法 | 端点 | 说明 | |------|------|------| | GET | `/api/auth/me` | 获取当前用户信息 | | POST | `/api/orders` | 创建订单 | | GET | `/api/orders` | 获取当前用户订单列表 | | GET | `/api/orders/{id}` | 获取订单详情 | | GET | `/api/orders/number/{orderNumber}` | 按订单号查询 | | POST | `/api/orders/{id}/extend` | 续住 | | POST | `/api/payments` | 创建支付记录 | | GET | `/api/payments` | 获取当前用户支付记录 | | GET | `/api/payments/{id}` | 获取支付详情 | | GET | `/api/orders/{orderId}/payments` | 查询订单的支付记录 | | POST | `/api/payments/{id}/process` | 处理支付 | | POST | `/api/payments/callback` | 支付回调 | ### 6.3 管理员接口（需要 ADMIN / STAFF 角色） | 方法 | 端点 | 说明 | 角色 | |------|------|------|------| | GET | `/api/admin/orders` | 所有订单列表 | ADMIN/STAFF | | GET | `/api/admin/orders/status/{status}` | 按状态筛选 | ADMIN/STAFF | | GET | `/api/admin/orders/statistics` | 订单统计 | ADMIN | | POST | `/api/admin/orders/{id}/confirm` | 确认订单 | ADMIN/STAFF | | POST | `/api/admin/orders/{id}/check-in` | 入住登记 | ADMIN/STAFF | | POST | `/api/admin/orders/{id}/check-out` | 退房结账 | ADMIN/STAFF | | POST | `/api/admin/orders/{id}/cancel` | 取消订单 | ADMIN/STAFF | | POST | `/api/admin/room-types` | 创建房型 | ADMIN | | PUT | `/api/admin/room-types/{id}` | 更新房型 | ADMIN | | DELETE | `/api/admin/room-types/{id}` | 删除房型 | ADMIN | | POST | `/api/admin/rooms` | 创建房间 | ADMIN | | GET | `/api/admin/rooms` | 房间列表 | ADMIN/STAFF | | PUT | `/api/admin/rooms/{id}` | 更新房间 | ADMIN | | PUT | `/api/admin/rooms/{id}/status` | 变更房间状态 | ADMIN/STAFF | | DELETE | `/api/admin/rooms/{id}` | 删除房间 | ADMIN | | GET | `/api/admin/users` | 用户列表 | ADMIN | | GET | `/api/admin/users/{id}` | 用户详情 | ADMIN | | PUT | `/api/admin/users/{id}/status` | 启用/禁用用户 | ADMIN | | DELETE | `/api/admin/users/{id}` | 删除用户 | ADMIN | | GET | `/api/admin/payments` | 支付记录列表 | ADMIN/STAFF | | POST | `/api/admin/payments/{id}/refund` | 退款 | ADMIN | ### 6.4 统一响应格式 ```json { "code": 200, "message": "Success", "data": { ... }, "timestamp": 1712345678000 } ``` | code | 说明 | |------|------| | 200 | 成功 | | 400 | 参数错误/业务异常 | | 401 | 未认证/Token 过期 | | 403 | 无权限 | | 404 | 资源不存在 | | 500 | 服务器内部错误 | --- ## 7. 快速启动 ### 环境要求 - JDK 17+ - Node.js 18+ - MySQL 8.0+ - Maven 3.6+ ### 7.1 数据库 ```sql CREATE DATABASE hotel_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` 默认连接配置（`backend/src/main/resources/application.yml`）： - 主机：`localhost:13306` - 用户名：`root` - 密码：`CyjF4tZs7tPkSph2` ### 7.2 启动后端 ```bash cd backend mvn spring-boot:run ``` 后端默认运行在 `http://localhost:8081`。 首次启动时 `DataInitializer` 会自动创建种子数据： - 3 个角色：ADMIN, CUSTOMER, STAFF - 2 个默认用户：`admin/admin123` (ADMIN 角色), `customer/customer123` (CUSTOMER 角色) - 4 种房型、34 个房间 ### 7.3 启动客户前端 ```bash cd frontend npm install npm run dev ``` 客户前端默认运行在 `http://localhost:5173`。 ### 7.4 启动管理后台 ```bash cd admin npm install npm run dev ``` 管理后台默认运行在 `http://localhost:5174`。 ### 7.5 访问 API 文档 启动后端后访问：`http://localhost:8081/swagger-ui.html` --- ## 8. 部署指南 ### 后端打包部署 ```bash cd backend mvn clean package -DskipTests # 生成 target/hotel-management-0.0.1-SNAPSHOT.jar java -jar target/hotel-management-0.0.1-SNAPSHOT.jar ``` ### 前端构建部署 ```bash # 客户前端 cd frontend npm run build # 生成 dist/ 目录，部署到 Nginx 等 Web 服务器 # 管理后台 cd admin npm run build # 生成 dist/ 目录 ``` ### Nginx 配置示例 ```nginx # 客户前端 server { listen 80; server_name hotel.example.com; root /var/www/hotel-frontend/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://localhost:8081; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } # 管理后台 server { listen 80; server_name admin-hotel.example.com; root /var/www/hotel-admin/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://localhost:8081; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` ### Docker 部署 项目暂未提供 Dockerfile，可按以下方式容器化： ```dockerfile # 后端 Dockerfile FROM openjdk:17-jdk-alpine COPY target/hotel-management-0.0.1-SNAPSHOT.jar app.jar EXPOSE 8081 ENTRYPOINT ["java", "-jar", "/app.jar"] ``` --- ## 9. 项目截图 ![输入图片说明](https://portalback.springautumncome.asia/files/3b27aa44e4ad45899a26d02f487b9059.png)![输入图片说明](https://portalback.springautumncome.asia/files/8461650233db44d1a604bdf6228f61ae.png)![输入图片说明](https://portalback.springautumncome.asia/files/b1d805535e07456a909ec9ede4c389b5.png)![输入图片说明](https://portalback.springautumncome.asia/files/c4b000a4eb724f8086c7db505cc72ff7.png)![输入图片说明](https://portalback.springautumncome.asia/files/8b4806980a104aeeae42cff9fec6078d.png)![输入图片说明](https://portalback.springautumncome.asia/files/06e5dac16aab4924aab8d32c4974a6c4.png)![输入图片说明](https://portalback.springautumncome.asia/files/4c6b78e43a5d4202ad2dcb3cc28fc173.png)![输入图片说明](https://portalback.springautumncome.asia/files/b2f6fe1df470440aadf94128af990ecb.png)![输入图片说明](https://portalback.springautumncome.asia/files/fd3c73d6b8464e329bf946ecbc1ca6cf.png)![输入图片说明](https://portalback.springautumncome.asia/files/a9d5bce57c9a49e28cec713b36724187.png)![输入图片说明](https://portalback.springautumncome.asia/files/c80035fa8b824338aba7b81b75922aae.png)![输入图片说明](https://portalback.springautumncome.asia/files/b396b7a549594f33988b6a855473de13.png)![输入图片说明](https://portalback.springautumncome.asia/files/7cab6089f4364da48efc1fc7fe972c28.png)![输入图片说明](https://portalback.springautumncome.asia/files/b4885b610d5c4c3e8655583a2785cf36.png)![输入图片说明](https://portalback.springautumncome.asia/files/aa71775ad61440ebb60116d8331d4d43.png)![输入图片说明](https://portalback.springautumncome.asia/files/2d6246e57fbb4c00ba5d3b728fd89f06.png)![输入图片说明](https://portalback.springautumncome.asia/files/cf66d2fa3e174dea913ce006067a699d.png) ## 附录 ### 项目结构总览 ``` hotel-system/ ├── backend/ # Spring Boot 后端 │ ├── pom.xml │ └── src/main/ │ ├── java/com/hotel/ │ │ ├── common/ # 通用类（ApiResponse） │ │ ├── config/ # 配置（安全、支付、数据初始化） │ │ ├── controller/ # REST 控制器 │ │ ├── dto/ # 数据传输对象 │ │ ├── entity/ # JPA 实体 │ │ ├── exception/ # 全局异常处理 │ │ ├── repository/ # 数据访问层 │ │ ├── security/ # JWT 安全模块 │ │ └── service/ # 业务逻辑层 │ └── resources/ │ └── application.yml # 应用配置 ├── frontend/ # 客户前端 │ ├── package.json │ ├── vite.config.js │ ├── tailwind.config.js │ └── src/ │ ├── main.js │ ├── App.vue │ ├── router/ # 路由配置 │ ├── stores/ # Pinia 状态管理 │ ├── assets/ # 样式资源 │ └── views/ # 页面组件 ├── admin/ # 管理后台 │ ├── package.json │ ├── vite.config.js │ └── src/ │ ├── main.js │ ├── App.vue │ ├── router/ # 路由配置 │ ├── stores/ # Pinia 状态管理 │ ├── assets/ # 样式资源 │ └── views/ # 页面组件 └── DOCUMENTATION.md # 本文档 ``` ### 种子数据 **默认用户：** | 用户名 | 密码 | 角色 | |--------|------|------| | admin | admin123 | ADMIN | | customer | customer123 | CUSTOMER | **默认房型：** | 房型名称 | 每晚价格 | 容量 | 床数 | 房间数量 | |----------|----------|------|------|----------| | 标准间 | ¥299 | 2 | 2 | 20 (1-2层) | | 豪华间 | ¥499 | 2 | 2 | 8 (3层) | | 套房 | ¥899 | 3 | 3 | 5 (4层) | | 总统套房 | ¥1999 | 4 | 3 | 1 (5层) |