# 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 Hotel Management System

![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/Default%20DB-SQLite-003B57)
![License](https://img.shields.io/badge/License-MIT-yellow)

**Languages: [简体中文](README.md)**

## Introduction

eh-PMS is a front-end/back-end separated hotel management system (v2.1.0) with multi-platform
support (Web, PC desktop, Android/iOS apps, HarmonyOS, WeChat mini-program). It covers the full
business scope: room operations, reservations & check-in, billing, customer relations, staff
management, procurement & inventory, dining, housekeeping, finance, meetings & events, and
notifications.

**Zero-setup developer experience**: runs on SQLite with an in-memory cache by default —
**no MySQL or Redis installation required**. Clone, build, start.

## Tech Stack

### Backend

| Tech | Version | Notes |
|------|---------|-------|
| Java | 25 | JDK 25 LTS |
| Spring Boot | 4.1.x | Current OSS-supported line |
| MyBatis-Plus | 3.5.x | ORM (Boot 4 dedicated starter) |
| SQLite / MySQL / PostgreSQL | - | Multi-database, **SQLite by default** |
| Redis (optional) | 7.x | Login-state store in production; in-memory implementation for dev |
| JJWT | 0.13.x | JWT authentication |
| springdoc-openapi | 3.1.x | OpenAPI 3 docs + Swagger UI |
| FastExcel | 1.3.x | Excel export (official successor of EasyExcel) |
| Hutool | 5.8.x | Utility library |
| wechatpay-java | 0.2.x | Official WeChat Pay V3 SDK |

### Frontend

| Tech | Version | Notes |
|------|---------|-------|
| UniApp | 3.x | Cross-platform (H5 / WeChat mini-program / apps) |
| Vue | 3.5 | Composition API |
| TypeScript | 5.x | Type safety |
| Pinia | 2.x | State management |
| Vite | 6.x | Build tool |

## Core Features

### Front-office

| Module | Highlights |
|--------|------------|
| Auth & users | RBAC roles, JWT, account lockout, single-session control |
| Rooms | Room types & rooms CRUD, strict state machine |
| Reservations | Online booking, availability check, confirm/cancel, auto-expiry |
| Check-in | Walk-in & reservation check-in, room change, extension, checkout with bill-settlement guard |
| Bills | Auto-created bills, room charges, consumptions, multi-method payment, **online payment** |
| Customers | Profiles, member levels & discounts, stay history |
| Reports | Occupancy / revenue / room-usage reports, Excel export |
| Settings | Hotel info, business parameters, operation-log audit |

### Back-office

| Module | Highlights |
|--------|------------|
| Staff | Employee files (auto work-no), scheduling, attendance, leave, payroll |
| Procurement | Suppliers, approval chain (apply→approve→order→stock-in), inventory & alerts |
| Dining | Restaurants, dishes with time-based pricing, orders with **auto billing for room service** |
| Housekeeping | Cleaning tasks, repairs, lost & found, room inspection |
| Finance | Daily/monthly settlement, income/expense, the three financial statements |
| Meetings | Room booking with conflict detection, event planning & settlement |
| Notifications | Notices, message center, templates, **SMS / e-mail channel dispatch** |

### Third-party integration layer

| Capability | Notes |
|------------|-------|
| Payment gateway | Mock implementation for local dev; WeChat Pay V3 via official SDK — switch by config |
| SMS | Mock by default; Aliyun SMS implementation |
| E-mail | Mock by default; SMTP via spring-boot-starter-mail |

👉 Step-by-step tutorials: [Payment](docs/integration/payment.md) · [SMS / E-mail](docs/integration/sms-email.md)

## Quick Start

### Requirements

- JDK 25 LTS, Maven 3.8+
- Node.js 18+ (20/22 LTS recommended)
- ~~MySQL 8 / Redis 7~~ (optional: SQLite + in-memory cache by default)

### Option 1: One-click start (Windows)

```bat
:: 1. Build locally (once)
cd eh-pms-server && mvn package -DskipTests && cd ..
cd eh-pms-ui && npm install && cd ..

:: 2. Start everything (backend + H5 frontend + browser)
start.bat

:: Stop
stop.bat
```

### Option 2: Manual start

```bash
# Backend (SQLite; database & seed data created automatically on first run)
cd eh-pms-server
mvn spring-boot:run

# Frontend H5 dev server
cd eh-pms-ui
npm install
npm run dev:h5
```

| Entry | URL |
|-------|-----|
| Frontend (H5) | http://localhost:5173 |
| API docs | http://localhost:8081/swagger-ui.html  (prod profile runs on port 8080) |

### API tests

```bash
pip install -r tests/requirements.txt
cd tests && pytest        # 92 test cases against the real backend
```

### Switch to MySQL / PostgreSQL

```bash
mvn spring-boot:run -Dspring-boot.run.profiles=mysql        # requires Redis; run db/schema.sql manually
mvn spring-boot:run -Dspring-boot.run.profiles=postgresql   # requires Redis; auto schema init
```

See [Multi-database guide](docs/database/multi-database.md) (Chinese).

## Default Accounts

| Role | Username | Password |
|------|----------|----------|
| Administrator | admin | admin123 |
| Receptionist | receptionist | admin123 |
| Room attendant | roomservice | admin123 |

> ⚠️ Change default passwords before going to production.

## Project Structure

```
eh-pms/
├── eh-pms-server/          # Backend (Spring Boot 4)
│   └── src/main/java/com/ehpms/
│       ├── controller/     # 35 controllers (REST /api/v1)
│       ├── service/impl/   # 36 service implementations
│       ├── integration/    # ⭐ Third-party integration layer (pay/sms/email)
│       ├── common/kv/      # Key-value store abstraction (optional Redis)
│       ├── entity/ dto/ mapper/ enums/ task/ aspect/ config/
│   └── src/main/resources/
│       ├── application*.yml    # sqlite(default)/mysql/postgresql/prod
│       └── db/                 # Schema scripts per dialect + seed data
├── eh-pms-ui/              # Frontend UniApp (45+ pages, 31 API modules)
├── tests/                  # Python API test suite (92 cases)
├── docs/                   # 📚 Documentation center (see docs/README.md)
├── tools/                  # Maintenance tools (schema dialect converter)
├── start.bat / stop.bat    # Windows one-click start/stop
└── LICENSE                 # MIT
```

## Multi-platform Build

| Platform | Command | Output |
|----------|---------|--------|
| H5 (Web) | `npm run build:h5` | `dist/build/h5/` |
| WeChat mini-program | `npm run build:mp-weixin` | `dist/build/mp-weixin/` |
| Android | `npm run build:app-android` | `dist/build/app/android/` |
| iOS | `npm run build:app-ios` | `dist/build/app/ios/` |
| HarmonyOS | `npm run build:app-harmony` | `dist/build/app/harmony/` |

## Documentation

📚 **Documentation center**: [docs/README.md](docs/README.md) (in Chinese)

| Category | Documents |
|----------|-----------|
| Getting started | Quick start · Environment · FAQ |
| Development | Architecture · Conventions · Testing guide |
| Database | Data model · Multi-database guide |
| Integration | Overview · Payment · SMS/E-mail |
| Deployment | Deployment guide |
| Legacy design | Spec · Design · User manual |

## Conventions

- REST APIs with a unified `ApiResponse<T>` envelope and JWT Bearer authentication
- Room status transitions strictly validated through a state machine; enum codes only, no magic strings
- Logical deletion via MyBatis-Plus `@TableLogic`
- Custom SQL must be dialect-portable (no `DATE_FORMAT`/`DATE()`)
- All third-party calls live in `integration/` and must ship with a Mock implementation

## Security Notes

- All dependencies are kept on currently supported versions (Spring Boot 4.1.x line;
  EasyExcel replaced by FastExcel to avoid the stale POI dependency)
- Inject secrets (JWT key, payment/SMS/mail credentials) via environment variables — never commit them
- API docs are disabled in the production profile; change default passwords immediately after deployment

## Known Limitations

- Integrations such as OTA / door-lock systems are planned extension points (see docs)

## License

[MIT License](LICENSE)