diff --git a/README.md b/README.md index 8812e6c..11164fe 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,241 @@ -# HotelSync — SaaS PMS System +# HotelSync PMS -Современная система управления отелем (PMS) с шахматкой бронирований, менеджером каналов и API. +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 -npm install -npm run dev +# Frontend (порт 5173) +npm install && npm run dev + +# Backend (порт 3000) +cd backend && npm install && npm run dev ``` -Откройте [http://localhost:5173](http://localhost:5173) +**Демо-аккаунты:** -## Демо-аккаунты +| Роль | Email | Пароль | +|---|---|---| +| Менеджер отеля | manager@grand-palace.ru | demo | +| Горничная | cleaner@grand-palace.ru | demo | +| Супер-администратор | admin@hotelsync.io | demo | -| Роль | Email | Пароль | -|-----------------------|---------------------------------|--------| -| Менеджер отеля | manager@grand-palace.ru | demo | -| Горничная | cleaner@grand-palace.ru | demo | -| Супер-администратор | admin@hotelsync.io | demo | +--- -## Функциональность +## Модули -- **Шахматка** — drag-to-book интерфейс, цветовое кодирование по статусам -- **Бронирования** — список с фильтрами, создание, детальная панель -- **Номерной фонд** — карточки номеров, статусы, уборка -- **Уборка** — Kanban-доска: ожидание / в процессе / готово -- **Менеджер каналов** — Booking.com, Airbnb, Expedia, VRBO -- **API-документация** — встроенная документация REST API -- **Светлая / тёмная тема** — переключатель в шапке -- **Мультиарендность** — архитектура SaaS с изоляцией по отелям +### Основные (всегда активны) -## Структура проекта +| Модуль | Маршрут | Описание | +|---|---|---| +| Календарь | `/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` | Техническое обслуживание | + +Видимость пунктов сайдбара определяется ролью автоматически. + +--- + +## Архитектура ``` -src/ -├── components/ -│ ├── calendar/ # Шахматка бронирований -│ ├── bookings/ # Модалки бронирований -│ ├── layout/ # Sidebar, Topbar -│ └── ui/ # Badge, Modal -├── contexts/ # AuthContext, ThemeContext -├── data/ # Мок-данные -├── layouts/ # AppLayout -├── lib/ # Утилиты, константы -├── pages/ # Страницы приложения -└── types/ # TypeScript типы +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/ # Скрипты деплоя ``` -## API +--- -Base URL: `https://api.hotelsync.io/v1` +## Backend API -Документация доступна в приложении: `/grand-palace/api-docs` +**База:** `https://api.hotelsync.ru/api` -## Стек технологий +**Аутентификация:** JWT Bearer token (1h) + refresh token (30d, хранится в Redis). -- React 18 + TypeScript -- Vite 5 -- Tailwind CSS 3 (dark mode) -- React Router 6 -- date-fns -- Lucide React +### Эндпоинты + +| Группа | Префикс | Описание | +|---|---|---| +| 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` — отключено намеренно, иначе сборка не проходит.