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