docs: full README — modules, API, architecture, deploy, DB schema

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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
+# Frontend (порт 5173)
-npm run dev
+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/
+pms/
-├── components/
+├── src/                    # React frontend (Vite)
-│   ├── calendar/       # Шахматка бронирований
+│   ├── pages/              # 37 страниц
-│   ├── bookings/       # Модалки бронирований
+│   ├── components/         # Переиспользуемые компоненты
-│   ├── layout/         # Sidebar, Topbar
+│   ├── lib/api.ts          # HTTP-клиент (все эндпоинты)
-│   └── ui/             # Badge, Modal
+│   ├── context/            # AuthContext, HotelContext, ModulesContext
-├── contexts/           # AuthContext, ThemeContext
+│   └── App.tsx             # Роутинг
-├── data/               # Мок-данные
+├── backend/
-├── layouts/            # AppLayout
+│   ├── src/
-├── lib/                # Утилиты, константы
+│   │   ├── routes/         # 25+ Fastify-роутов
-├── pages/              # Страницы приложения
+│   │   ├── agent-ws.ts     # WebSocket-сервер для Windows-агентов
-└── types/              # TypeScript типы
+│   │   ├── 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
+| Auth | `/api/auth` | login, refresh, logout, регистрация отеля |
-- Lucide React
+| 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` — отключено намеренно, иначе сборка не проходит.