# eh-PMS

**Repository Path**: mgb/eh-pms

## Basic Information

- **Project Name**: eh-PMS
- **Description**: 一款酒店管理系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 酒店管理系统 eh-PMS

![JDK](https://img.shields.io/badge/JDK-25-blue)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1.x-6DB33F)
![Vue](https://img.shields.io/badge/Vue-3.5-42B883)
![uni-app](https://img.shields.io/badge/uni--app-3.x-2B9939)
![SQLite](https://img.shields.io/badge/%E9%BB%98%E8%AE%A4%E6%95%B0%E6%8D%AE%E5%BA%93-SQLite-003B57)
![License](https://img.shields.io/badge/License-MIT-yellow)

**其他语言：[English](README.en.md)**

## 项目简介

eh-PMS 是一款前后端分离的酒店管理系统（v2.1.0），支持多端适配（Web、PC桌面端、Android/iOS APP、HarmonyOS、微信小程序），实现前台客户服务与内部运营管理的一体化管理。涵盖客房运营、预订入住、账单结算、客户关系、员工管理、采购库存、餐饮管理、房务管理、财务管理、会议活动、通知公告等全业务场景。

**开箱即用**：默认使用 SQLite 数据库与内存缓存，**无需安装 MySQL、Redis**，克隆、编译、启动三步完成。

## 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 25 | 开发语言（JDK 25 LTS） |
| Spring Boot | 4.1.x | 应用框架（当前 OSS 支持主线） |
| MyBatis-Plus | 3.5.x | ORM框架（Boot 4 专用 starter） |
| SQLite / MySQL / PostgreSQL | - | 多数据库适配，**默认 SQLite** |
| Redis（可选） | 7.x | 生产环境登录态存储（开发用内存实现，无需安装） |
| JJWT | 0.13.x | 认证令牌 |
| springdoc-openapi | 3.1.x | OpenAPI 3 文档 + Swagger UI |
| FastExcel | 1.3.x | Excel导出（EasyExcel 官方后继） |
| Hutool | 5.8.x | 工具库 |
| wechatpay-java | 0.2.x | 微信支付 V3 官方 SDK |

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| UniApp | 3.x | 跨平台框架（H5/微信小程序/APP/HarmonyOS） |
| Vue | 3.5 | 前端框架 |
| TypeScript | 5.x | 类型安全 |
| Pinia | 2.x | 状态管理 |
| Vite | 6.x | 构建工具 |

## 核心功能

### 前台客户服务

| 模块 | 功能 |
|------|------|
| 用户管理与认证 | 多角色RBAC、JWT认证、账号锁定、并发登录控制 |
| 客房管理 | 客房类型/客房CRUD、四状态严格流转（状态机校验） |
| 预订管理 | 在线预订、可用性校验、确认/取消、超时自动取消 |
| 入住管理 | 办理入住、换房（账单迁移）、续住、退房（账单结清校验） |
| 账单管理 | 自动创建、房费累计、消费项、多方式支付、**在线支付对接** |
| 客户管理 | 客户信息、会员等级与房费折扣（折扣率可用系统参数调整）、历史记录追溯 |
| 报表统计 | 入住率/营收/客房使用报表，Excel导出 |
| 系统设置 | 酒店信息、业务参数、操作日志审计 |

### 内部运营管理

| 模块 | 功能 |
|------|------|
| 员工管理 | 员工档案（工号自动生成）、排班/调班/加班、考勤/请假、薪资/工资条 |
| 采购库存 | 供应商管理/评价、采购申请→审批→下单→入库、出入库/盘点/预警 |
| 餐饮管理 | 餐厅/餐位、菜品分时段定价、餐饮订单/**送餐到房自动入账** |
| 房务管理 | 清洁任务、报修派单、失物招领、客房检查/整改 |
| 财务管理 | 日结/月结、收支登记、三大财务报表 |
| 会议活动 | 会议室预订（时段冲突校验）、活动策划/执行/结算 |
| 通知公告 | 公告发布/已读统计、消息中心、通知模板、**短信/邮件渠道分发** |

### 第三方对接（内置对接层）

| 能力 | 说明 |
|------|------|
| 支付网关 | 默认 Mock 实现本地联调；微信支付 V3 官方SDK实现，改配置即切换 |
| 短信 | 默认 Mock；阿里云短信实现（模板签名配置即用） |
| 邮件 | 默认 Mock；SMTP 实现（spring-boot-starter-mail） |

👉 保姆级接入教程：[支付对接](docs/integration/payment.md) · [短信/邮件对接](docs/integration/sms-email.md)

## 快速开始

### 环境要求

- JDK 25 LTS、Maven 3.8+
- Node.js 18+（推荐 20/22 LTS）
- ~~MySQL 8 / Redis 7~~（可选：默认 SQLite + 内存缓存，无需安装）

### 方式一：一键启动（Windows）

```bat
:: 1. 本地编译（一次性）
cd eh-pms-server && mvn package -DskipTests && cd ..
cd eh-pms-ui && npm install && cd ..

:: 2. 一键启动（后端 + 前端H5 + 自动打开浏览器）
start.bat

:: 停止服务
stop.bat
```

### 方式二：手动启动

```bash
# 后端（SQLite, 首次启动自动建库+种子数据）
cd eh-pms-server
mvn spring-boot:run

# 前端 H5 开发模式
cd eh-pms-ui
npm install
npm run dev:h5
```

| 入口 | 地址 |
|------|------|
| 前端（H5） | http://localhost:5173 |
| 接口文档 | http://localhost:8081/swagger-ui.html （prod profile 端口为 8080） |

### 接口测试

```bash
pip install -r tests/requirements.txt
cd tests && pytest        # 137用例, 直连真实后端
```

### 切换 MySQL / PostgreSQL

```bash
mvn spring-boot:run -Dspring-boot.run.profiles=mysql        # 需Redis, 手动执行db/schema.sql与db/schema_new.sql
mvn spring-boot:run -Dspring-boot.run.profiles=postgresql   # 需Redis, 自动建表
```

详见 [多数据库适配指南](docs/database/multi-database.md)。

## 默认账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 管理员 | admin | admin123 |
| 前台接待员 | receptionist | admin123 |
| 客房服务员 | roomservice | admin123 |

> ⚠️ 上线前请立即修改默认密码。

## 项目结构

```
eh-pms/
├── eh-pms-server/          # 后端 SpringBoot 4
│   └── src/main/java/com/ehpms/
│       ├── controller/     # 37个控制器 (REST /api/v1)
│       ├── service/impl/   # 37个业务实现
│       ├── integration/    # ⭐ 第三方对接层 (支付/短信/邮件)
│       ├── common/kv/      # 键值存储抽象 (Redis可选化)
│       ├── entity/ dto/ mapper/ enums/ task/ aspect/ config/
│   └── src/main/resources/
│       ├── application*.yml    # sqlite(默认)/mysql/postgresql/prod
│       └── db/                 # 各方言建表脚本 + 种子数据
├── eh-pms-ui/              # 前端 UniApp (51页面, 33个API模块)
├── tests/                  # Python接口测试套件 (137用例)
├── docs/                   # 📚 项目文档中心 (分类导航见docs/README.md)
├── tools/                  # 维护工具 (schema方言转换)
├── start.bat / stop.bat    # Windows 一键启动/停止
└── LICENSE                 # MIT
```

## 多端编译

| 平台 | 命令 | 产物目录 |
|------|------|---------|
| H5 (Web) | `npm run build:h5` | `dist/build/h5/` |
| 微信小程序 | `npm run build:mp-weixin` | `dist/build/mp-weixin/` |
| Android APP | `npm run build:app-android` | `dist/build/app/android/` |
| iOS APP | `npm run build:app-ios` | `dist/build/app/ios/` |
| HarmonyOS | `npm run build:app-harmony` | `dist/build/app/harmony/` |

## 文档

📚 **完整文档中心**：[docs/README.md](docs/README.md)

| 类别 | 文档 |
|------|------|
| 快速上手 | [快速开始](docs/guide/quickstart.md) · [环境搭建](docs/guide/environment.md) · [FAQ](docs/guide/faq.md) |
| 开发指南 | [架构设计](docs/development/architecture.md) · [开发规范](docs/development/conventions.md) · [测试指南](docs/development/testing.md) |
| 数据库 | [数据模型概览](docs/database/overview.md) · [多数据库适配](docs/database/multi-database.md) |
| 第三方对接 | [对接总览](docs/integration/README.md) · [支付对接](docs/integration/payment.md) · [短信/邮件](docs/integration/sms-email.md) |
| 部署运维 | [部署指南](docs/deployment/deployment.md) |
| 历史设计 | [需求规格](docs/design/spec.md) · [实现设计](docs/design/design.md) · [使用手册](docs/development/tutorial.md) |

## 开发规范

- **命名**：变量/方法 camelCase，类 PascalCase，数据库列 snake_case
- **注释**：后端 Javadoc + Swagger 注解，前端 TSDoc
- **接口**：RESTful，统一 `ApiResponse<T>`，JWT Bearer Token
- **状态机**：客房状态经 `RoomService.transit()` 严格校验，禁止非法流转
- **枚举**：统一 `getCode()`，禁止硬编码状态字符串
- **逻辑删除**：实体统一 `@TableLogic`
- **跨方言SQL**：禁用 `DATE_FORMAT`/`DATE()` 等方言函数，用区间比较
- **第三方调用**：收敛到 `integration/`，必须提供 Mock 实现与配置开关

## 安全说明

- 本项目已将全部依赖升级至当前受支持的版本（Spring Boot 4.1.x 主线，
  3.2.x/3.5.x 已停止 OSS 维护；EasyExcel → FastExcel 修复旧 POI 风险）
- JWT 密钥、支付/短信/邮件凭据请一律使用环境变量注入，**不要提交真实密钥**
- 生产环境默认关闭 API 文档；默认账号上线后立即改密

## 已知限制

- 会议室预订冲突校验已实现，OTA/门锁等外部系统对接为规划项（见文档中心"第三方对接"扩展套路）

## 许可证

[MIT License](LICENSE)