242 lines
12 KiB
Markdown
242 lines
12 KiB
Markdown
# HotelSync PMS
|
||
|
||
SaaS-система управления отелем (Property Management System).
|
||
|
||
**Стек:** React 18 + TypeScript + Vite + Tailwind CSS 3 · Fastify + TypeScript · PostgreSQL 16 · Redis 7 · Docker
|
||
|
||
**Продакшн:** https://app.hotelsync.ru · API: https://api.hotelsync.ru
|
||
|
||
---
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
# Frontend (порт 5173)
|
||
npm install && npm run dev
|
||
|
||
# Backend (порт 3000)
|
||
cd backend && npm install && npm run dev
|
||
```
|
||
|
||
**Демо-аккаунты:**
|
||
|
||
| Роль | Email | Пароль |
|
||
|---|---|---|
|
||
| Менеджер отеля | manager@grand-palace.ru | demo |
|
||
| Горничная | cleaner@grand-palace.ru | demo |
|
||
| Супер-администратор | admin@hotelsync.io | demo |
|
||
|
||
---
|
||
|
||
## Модули
|
||
|
||
### Основные (всегда активны)
|
||
|
||
| Модуль | Маршрут | Описание |
|
||
|---|---|---|
|
||
| Календарь | `/calendar` | Шахматка бронирований: drag & drop, статусы, фильтры по номерам и категориям |
|
||
| Бронирования | `/bookings` | Список бронирований с поиском, фильтрами, экспортом |
|
||
| Номера | `/rooms` | Управление номерным фондом, фотографии, статусы |
|
||
| Категории | `/room-categories` | Категории номеров, базовые цены, фотогалерея |
|
||
| Тарифы | `/tariffs` | Тарифные планы, периоды, надбавки |
|
||
| Ценообразование | `/dynamic-pricing` | Динамические цены по периодам и дням недели |
|
||
| Гости | `/guests` | База гостей, история бронирований, паспортные данные |
|
||
| Пользователи | `/users` | Сотрудники и роли |
|
||
| Настройки | `/settings` | Настройки отеля, SMTP, Telegram, уведомления |
|
||
| Отчёты | `/reports` | Аналитика загрузки, выручки, ADR, RevPAR |
|
||
| Карта этажей | `/floor-map` | Визуальная карта этажей с drag & drop расстановкой номеров |
|
||
| Оборудование | `/equipment` | Рабочие места, агенты Windows, ККТ и принтеры |
|
||
| График | `/schedule` | Рабочее расписание персонала (неделя/месяц) |
|
||
| Документы | `/documents` | Шаблоны документов |
|
||
| Скидки | `/discounts` | Промокоды и скидки |
|
||
|
||
### Подключаемые модули (через `/modules`)
|
||
|
||
| Модуль | Маршрут | Описание |
|
||
|---|---|---|
|
||
| Горничные | `/housekeeping` | Задания на уборку, статусы, фото-отчёты, назначение, авто-стратегии |
|
||
| Менеджер каналов | `/channels` | Подключение OTA-каналов (Яндекс, Островок, Суточно, Авито, Bronevik и др.) |
|
||
| Касса (POS) | `/pos` | Кассовые смены, фискальные чеки через ККТ АТОЛ |
|
||
| Отзывы | `/reviews` | Модерация отзывов гостей, QR-коды для сбора отзывов |
|
||
| Room Service | `/room-service` | Меню и заказы из номеров в реальном времени |
|
||
| Аренда | `/rental` | Аренда объектов (апартаменты, конференц-залы и т.п.) |
|
||
| Лояльность | `/loyalty` | Программа лояльности: уровни, баллы, правила начисления |
|
||
|
||
### Публичные страницы (без авторизации)
|
||
|
||
| Страница | Маршрут | Описание |
|
||
|---|---|---|
|
||
| Форма отзыва | `/review/:slug` | Страница для гостя: оставить отзыв по QR-коду |
|
||
| Room Service гость | `/room-service/:slug` | Страница для гостя: сделать заказ из номера |
|
||
| Виджет бронирования | `/booking-widget` | Встраиваемый виджет для сайта отеля |
|
||
| TV-приветствие | `/tv-welcome` | Конфигуратор NetUP IPTV welcome-экрана |
|
||
|
||
---
|
||
|
||
## Роли пользователей
|
||
|
||
| Роль | Доступ |
|
||
|---|---|
|
||
| `super_admin` | Панель `/admin`, все отели |
|
||
| `hotel_admin` | Все разделы своего отеля + настройки |
|
||
| `manager` | Бронирования, номера, гости, касса |
|
||
| `housekeeper` | Горничные, своё расписание |
|
||
| `technician` | Техническое обслуживание |
|
||
|
||
Видимость пунктов сайдбара определяется ролью автоматически.
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
pms/
|
||
├── src/ # React frontend (Vite)
|
||
│ ├── pages/ # 37 страниц
|
||
│ ├── components/ # Переиспользуемые компоненты
|
||
│ ├── lib/api.ts # HTTP-клиент (все эндпоинты)
|
||
│ ├── context/ # AuthContext, HotelContext, ModulesContext
|
||
│ └── App.tsx # Роутинг
|
||
├── backend/
|
||
│ ├── src/
|
||
│ │ ├── routes/ # 25+ Fastify-роутов
|
||
│ │ ├── agent-ws.ts # WebSocket-сервер для Windows-агентов
|
||
│ │ ├── db.ts # pg Pool
|
||
│ │ └── index.ts # Точка входа
|
||
│ └── migrations/ # 45 SQL-миграций (auto-run при старте)
|
||
├── nginx/ # nginx конфиги
|
||
└── deploy/ # Скрипты деплоя
|
||
```
|
||
|
||
---
|
||
|
||
## Backend API
|
||
|
||
**База:** `https://api.hotelsync.ru/api`
|
||
|
||
**Аутентификация:** JWT Bearer token (1h) + refresh token (30d, хранится в Redis).
|
||
|
||
### Эндпоинты
|
||
|
||
| Группа | Префикс | Описание |
|
||
|---|---|---|
|
||
| Auth | `/api/auth` | login, refresh, logout, регистрация отеля |
|
||
| Hotels | `/api/hotels/:slug` | CRUD настроек отеля |
|
||
| Rooms | `/api/hotels/:slug/rooms` | Номерной фонд |
|
||
| Categories | `/api/hotels/:slug/categories` | Категории номеров |
|
||
| Bookings | `/api/hotels/:slug/bookings` | Бронирования + гости |
|
||
| Housekeeping | `/api/hotels/:slug/housekeeping` | Задания, настройки, расписание |
|
||
| Channels | `/api/hotels/:slug/channels` | OTA-каналы |
|
||
| Guests | `/api/hotels/:slug/guests` | База гостей |
|
||
| Tariffs | `/api/hotels/:slug/tariffs` | Тарифы и периоды |
|
||
| Users | `/api/hotels/:slug/users` | Пользователи и роли |
|
||
| Workstations | `/api/hotels/:slug/workstations` | Рабочие места агентов |
|
||
| Schedule | `/api/hotels/:slug/schedule` | Расписание персонала |
|
||
| Loyalty | `/api/hotels/:slug/loyalty` | Программа лояльности |
|
||
| Chat | `/api/hotels/:slug/chat` | Внутренний чат |
|
||
| Notifications | `/api/hotels/:slug/notifications` | Push-уведомления |
|
||
| Rental | `/api/hotels/:slug/rental` | Объекты аренды |
|
||
| NetUP | `/api/hotels/:slug/netup` | NetUP IPTV |
|
||
| Agent | `/api/agent` | Сопряжение агентов |
|
||
| Agent Release | `/api/agents/latest-release` | Актуальная версия агента |
|
||
| Upload | `/api/upload` | Загрузка фото |
|
||
|
||
### WebSocket
|
||
|
||
- `/ws` — real-time обновления для браузера (бронирования, уборка)
|
||
- `/ws/agent` — постоянное соединение с Windows-агентами (команды ККТ, печать)
|
||
|
||
---
|
||
|
||
## Оборудование и агент
|
||
|
||
На странице **Оборудование** (`/equipment`) управляются рабочие места и устройства:
|
||
|
||
- **Рабочее место** — Windows-компьютер с установленным агентом HotelSync Agent
|
||
- **ККТ** — фискальный регистратор АТОЛ (не способ оплаты). Подключается через ДТО веб-сервис (HTTP, порт 16732), не через COM-порт напрямую
|
||
- **Принтер** — сетевой чековый принтер или Windows-принтер
|
||
- **NetUP** — локальный IPTV-сервер (в агентном режиме URL не указывается — берётся из конфига устройства)
|
||
|
||
Агент устанавливается на Windows, сопрягается по 6-значному коду. После сопряжения — постоянное WebSocket-соединение с сервером для получения команд.
|
||
|
||
→ Подробнее: [hotelsync-agent/README.md](https://github.com/Golomazov/hotelsync-agent)
|
||
|
||
---
|
||
|
||
## База данных
|
||
|
||
PostgreSQL 16. Миграции (`backend/migrations/`) запускаются автоматически при старте бэкенда.
|
||
|
||
**Основные таблицы:**
|
||
|
||
| Таблица | Описание |
|
||
|---|---|
|
||
| `hotels` | Отели, настройки, SMTP, Telegram |
|
||
| `users` | Пользователи, роли, bcrypt-пароли |
|
||
| `rooms` | Номера (категория, этаж, статус, фото) |
|
||
| `room_categories` | Категории номеров, цены, фото |
|
||
| `bookings` | Бронирования (статус, цены, источник) |
|
||
| `booking_guests` | Гости в бронировании + паспортные данные |
|
||
| `guests` | База гостей |
|
||
| `housekeeping_tasks` | Задания на уборку |
|
||
| `housekeeping_settings` | Настройки авто-назначения |
|
||
| `channels` | OTA-каналы |
|
||
| `tariffs` | Тарифные планы |
|
||
| `rate_periods` | Периоды цен |
|
||
| `rate_overrides` | Переопределения цен по дням |
|
||
| `workstations` | Рабочие места (агент, онлайн-статус) |
|
||
| `workstation_devices` | Устройства рабочего места (ККТ, принтеры) |
|
||
| `loyalty_settings` | Настройки программы лояльности |
|
||
| `staff_schedule` | Рабочее расписание |
|
||
| `chat_rooms` / `chat_messages` | Внутренний чат |
|
||
| `notifications` | Уведомления |
|
||
|
||
---
|
||
|
||
## Деплой
|
||
|
||
```bash
|
||
ssh root@92.63.177.212 "cd /opt/hotelsync && bash deploy.sh"
|
||
```
|
||
|
||
`deploy.sh` выполняет:
|
||
1. `git pull` из Gitea
|
||
2. Пересборку Docker-образов frontend и backend
|
||
3. Перезапуск контейнеров с нужными volume-монтированиями
|
||
4. Перезагрузку nginx
|
||
|
||
**Контейнеры:**
|
||
|
||
| Контейнер | Назначение |
|
||
|---|---|
|
||
| `hotelsync-nginx` | Reverse proxy, SSL (порты 80/443/8080) |
|
||
| `hotelsync-api` | Fastify API (внутренний порт 3000) |
|
||
| `hotelsync-frontend` | React SPA (внутренний порт 80) |
|
||
| `hotelsync-postgres` | PostgreSQL 16 |
|
||
| `hotelsync-redis` | Redis 7 (сессии, refresh-токены) |
|
||
| `hotelsync-gitea` | Self-hosted Git (порт 3001) |
|
||
| `hotelsync-adminer` | DB Web UI (порт 8080, basic auth) |
|
||
|
||
**Volumes на сервере:**
|
||
- `/opt/hotelsync/uploads` → `/app/uploads` (фото)
|
||
- `/opt/hotelsync/agent-updates` → `/app/agent-updates` (установщики агента)
|
||
|
||
---
|
||
|
||
## CI/CD
|
||
|
||
Gitea Actions (`.gitea/workflows/deploy.yml`) — автодеплой при пуше в `main`.
|
||
|
||
---
|
||
|
||
## Разработка
|
||
|
||
```bash
|
||
npm run dev # frontend dev-сервер
|
||
npm run build # сборка frontend
|
||
cd backend && npm run dev # backend dev-сервер
|
||
cd backend && npm run build # сборка backend
|
||
```
|
||
|
||
> `tsconfig.json`: `noUnusedLocals` / `noUnusedParameters` = `false` — отключено намеренно, иначе сборка не проходит.
|