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

---

Быстрый старт

# 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

---

База данных

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	Уведомления

---

Деплой

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.

---

Разработка

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 — отключено намеренно, иначе сборка не проходит.