# eh-PMS

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

## Basic Information

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

## Statistics

- **Stars**: 2
- **Forks**: 3
- **Created**: 2026-06-05
- **Last Updated**: 2026-10-27

## 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)
![ArkTS](https://img.shields.io/badge/ArkTS-HarmonyOS%20NEXT-DC322F)
![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.10.45**），支持多端适配（H5/小程序/鸿蒙原生APP/鸿蒙元服务），实现前台客户服务与内部运营管理的一体化管理。涵盖客房运营、预订入住、账单结算、客户关系、员工管理、采购库存、餐饮管理、房务管理、财务管理、会议活动、通知公告等全业务场景。

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

**三端定位**：
- **H5（eh-pms-ui）**：桌面管理员端，51 页面，全功能覆盖
- **鸿蒙原生APP（eh-pms-harmony-app）**：移动端完整版，50 ArkTS 页面
- **鸿蒙元服务（eh-pms-harmony-service）**：免安装轻量版，53 ArkTS 页面（含 2 Widget），通过 WantAgent 跳完整 APP
- **HAR 共享库（eh-pms-harmony-shared）**：两端共用，38 API 模块（含 ApiClient）+ AuthStore Preferences 持久化

## 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| 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 |

### 前端（uni-app 技术栈）

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

### 鸿蒙原生（独立技术栈，与 uni-app 完全脱钩）

| 技术 | 版本 | 说明 |
|------|------|------|
| ArkTS | TypeScript 超集 | 原生鸿蒙开发语言 |
| DevEco Studio | HarmonyOS NEXT | IDE + hvigor 构建 |
| @kit.BasicServicesKit | Stage 模型 | 原生 HTTP 请求 |
| @kit.ArkUI | Stage 模型 | 组件式声明 UI |
| @ohos.data.preferences | - | AKV 持久化（AuthStore） |

## 核心功能

### 前台客户服务

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

### 内部运营管理

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

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

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

👉 保姆级接入教程：[支付对接](docs/integration/支付集成.md) · [支付宝对接](docs/integration/支付宝集成.md) · [短信/邮件对接](docs/integration/短信邮件集成.md)

## 📚 项目文档

| 目录 | 文件 | 说明 |
|------|------|------|
| `docs/` | README.md | 文档中心总览与导航 |
| `docs/design/` | spec.md, design.md, tasks.md | 架构设计、需求规格与任务清单 |
| `docs/api/` | 核心业务域.md, 运营管理域.md, 薄CRUD与聚合查询模块.md | API 端点文档（3 份分组） |
| `docs/development/` | architecture.md, conventions.md, testing.md, tutorial.md | 开发指南、规范、测试与使用手册 |
| `docs/guide/` | quickstart.md, environment.md, faq.md | 快速开始、环境搭建与常见问题 |
| `docs/deployment/` | deployment.md | 部署文档 |
| `docs/database/` | overview.md, multi-database.md | 数据模型概览与多数据库适配 |
| `docs/integration/` | README.md, payment.md, alipay.md, sms-email.md | 第三方对接总览、支付、短信/邮件 |
| `docs/CHANGELOG/` | CHANGELOG.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/多数据库配置.md)。

## 默认账号

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

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

## 项目结构

```
eh-pms/
├── eh-pms-server/          # 后端 SpringBoot 4
│   └── src/main/java/com/ehpms/
│       ├── controller/     # 39 个控制器 (REST /api/v1)
│       ├── service/impl/   # 38 个业务实现
│       ├── 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页面, H5/小程序/APP/iOS)
├── eh-pms-harmony-app/     # 鸿蒙原生 APP (ArkTS, 50页面, DevEco Studio)
├── eh-pms-harmony-service/ # 鸿蒙元服务 (ArkTS, 53页面含2 Widget, 免安装轻量版)
├── eh-pms-harmony-shared/  # ⭐ HAR 共享库 (38 API 模块 + AuthStore + Logger)
├── tests/                  # Python接口测试套件 (137用例)
├── docs/                   # 📚 项目文档中心 (分类导航见docs/README.md)
├── tools/                  # 维护工具 (schema方言转换)
├── start.bat / stop.bat    # Windows 一键启动/停止
└── LICENSE                 # MIT
```

## 多端编译

> 鸿蒙端**不走** uni-app 编译，见下方"鸿蒙原生编译"。

| 平台 | 命令 | 产物目录 |
|------|------|---------|
| 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/` |

**鸿蒙原生（纯血 Harmony，独立技术栈）**：

| 端 | 工具 | 产物 |
|----|------|------|
| 鸿蒙 APP | DevEco Studio Build | .hap → `eh-pms-harmony-app/entry/build/` |
| 鸿蒙元服务 | DevEco Studio Build | .hap → `eh-pms-harmony-service/entry/build/` |

> 📖 鸿蒙开发完整教程：[docs/development/harmony-dev.md](docs/development/鸿蒙开发指南.md)

## 文档

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

| 类别 | 文档 |
|------|------|
| 快速上手 | [快速开始](docs/guide/快速开始.md) · [环境搭建](docs/guide/环境搭建.md) · [FAQ](docs/guide/常见问题.md) |
| 开发指南 | [架构设计](docs/development/架构说明.md) · [HarmonyOS 开发教程](docs/development/鸿蒙开发指南.md) · [开发规范](docs/development/开发规范.md) · [测试指南](docs/development/测试指南.md) |
| 数据库 | [数据模型概览](docs/database/数据库概览.md) · [多数据库适配](docs/database/多数据库配置.md) |
| 第三方对接 | [对接总览](docs/integration/README.md) · [支付对接](docs/integration/支付集成.md) · [支付宝对接](docs/integration/支付宝集成.md) · [短信/邮件](docs/integration/短信邮件集成.md) |
| 部署运维 | [部署指南](docs/deployment/部署文档.md) |
| 历史设计 | [需求规格](docs/design/需求规格.md) · [实现设计](docs/design/架构设计.md) · [使用手册](docs/development/开发教程.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 文档；默认账号上线后立即改密
- 前端 `@dcloudio/*`（uni-app 框架）存在已知的传递依赖漏洞（high 级），
  属于框架级风险，需等待 uni-app 社区发布安全补丁版本后统一升级修复，
  开发与生产环境中请注意避免前端暴露给不可信来源（如直接打开 untrusted HTML）

## 已知限制

- 鸿蒙共享库 UploadApi（`/api/v1/upload` multipart 文件上传）已补齐接口，
  需在 DevEco Studio 环境中编译验证后再用于生产构建
- 会议室预订冲突校验已实现，OTA/门锁等外部系统对接为规划项（见文档中心"第三方对接"扩展套路）

## 许可证

[MIT License](LICENSE)