hotel-analysis/ARCHITECTURE.md

HotelTask - Архитектура системы

Обзор системы

flowchart TB
    subgraph ClientLayer["Client Layer"]
        WebAdmin["Web Admin<br/>(TypeScript, React)"]
        MobileApps["Mobile Apps"]
        TelegramBot["Telegram Bot"]
    end

    subgraph APIGateway["API Gateway Layer"]
        REST["REST API"]
        gRPC["gRPC"]
        WebSocket["WebSocket"]
    end

    subgraph ServiceLayer["Service Layer (Python)"]
        tasks["tasks-service<br/>Управление задачами"]
        users["users-service<br/>Управление пользователями"]
        connections["connections-service<br/>Связи между адаптерами"]
        notification["notification-service<br/>Уведомления"]
        fileStorage["file-storage-service<br/>Файлы"]
        audit["audit-service<br/>Аудит"]
        scheduler["scheduler-service<br/>Расписание"]
        permissions["permissions-service<br/>Права доступа"]
        events["events-service<br/>Мероприятия"]
    end

    subgraph DataLayer["Data Layer"]
        PostgreSQL[(PostgreSQL<br/>Основная БД)]
        Redis[(Redis<br/>Кэш)]
        S3[(S3<br/>Файлы)]
    end

    subgraph MessageBroker["Message Broker"]
        Kafka["Apache Kafka"]
    end

    subgraph AdapterLayer["Adapter Layer (Python)"]
        PMSAdapter["PMS Adapter"]
        ERPAdapter["ERP Adapter"]
        HousekeepingAdapter["Housekeeping Adapter"]
        TelegramAdapter["Telegram Bot Adapter"]
        CustomAdapter["Custom Adapter #N"]
    end

    subgraph ExternalSystems["External Systems"]
        PMS["PMS"]
        ERP["ERP"]
        Housekeeper["Housekeeper"]
    end

    %% Client -> API Gateway
    WebAdmin --> REST
    MobileApps --> REST
    MobileApps --> WebSocket
    TelegramBot --> REST

    %% API Gateway -> Services
    REST --> tasks
    REST --> users
    REST --> connections
    gRPC --> tasks
    gRPC --> users
    WebSocket --> notification

    %% Services -> Data
    tasks --> PostgreSQL
    users --> PostgreSQL
    connections --> PostgreSQL
    audit --> PostgreSQL
    scheduler --> PostgreSQL
    permissions --> PostgreSQL
    events --> PostgreSQL

    notification --> Redis
    tasks --> Redis

    fileStorage --> S3

    %% Services <-> Kafka
    tasks <--> Kafka
    notification <--> Kafka
    connections <--> Kafka

    %% Kafka <-> Adapters
    Kafka <--> PMSAdapter
    Kafka <--> ERPAdapter
    Kafka <--> HousekeepingAdapter
    Kafka <--> TelegramAdapter
    Kafka <--> CustomAdapter

    %% Adapters -> External Systems
    PMSAdapter --> PMS
    ERPAdapter --> ERP
    HousekeepingAdapter --> Housekeeper

---

Описание сервисов

Сервис	Назначение	Ключевые функции
tasks-service	Ядро системы	CRUD задач, статусы, назначение исполнителей, история изменений
users-service	Управление пользователями	Регистрация, авторизация, профили, привязка к отелям
connections-service	Маршрутизация событий	Настройка связей "событие A → система B", реестр адаптеров
permissions-service	Права доступа	RBAC, роли, проверка разрешений
notification-service	Уведомления	Push, email, SMS, Telegram, in-app
file-storage-service	Файлы	Загрузка/скачивание фото и документов в S3
audit-service	Аудит	Логирование всех действий в системе
scheduler-service	Планировщик	Создание задач по расписанию (cron)
events-service	Мероприятия	Декомпозиция мероприятий на задачи, генерация "функшн"

---

Слои системы

Client Layer

Клиентские приложения для взаимодействия с системой:

• Web Admin (React, TypeScript) — админка для управления системой
• Mobile Apps — мобильные приложения для сотрудников
• Telegram Bot — бот для управления задачами

API Gateway Layer

Точки входа для клиентов:

• REST API — основной API для веб и мобильных клиентов
• gRPC — высокопроизводительное межсервисное взаимодействие
• WebSocket — real-time уведомления

Service Layer

Микросервисы на Python (FastAPI), каждый отвечает за свою domain-область.

Data Layer

• PostgreSQL — основное хранилище данных
• Redis — кэширование, сессии
• S3 — файловое хранилище (фото, документы)

Message Broker

Apache Kafka — асинхронный обмен сообщениями между сервисами и адаптерами.

Adapter Layer

Адаптеры для интеграции с внешними системами. Каждый адаптер:

• Преобразует данные внешней системы в стандартный формат
• Работает как по push, так и по pull модели
• Изолирует логику интеграции от бизнес-логики

External Systems

Внешние системы отеля: PMS, ERP, системы управления уборкой и другие.

---

Потоки данных

Клиенты → API Gateway

Источник	Назначение	Данные
Web Admin	REST API	Запросы на управление задачами, пользователями, настройками
Mobile Apps	REST API	Запросы на работу с задачами, профилем
Mobile Apps	WebSocket	Подписка на real-time уведомления
Telegram Bot	REST API	Команды от пользователей бота

API Gateway → Сервисы

Источник	Назначение	Данные
REST API	tasks-service	CRUD операции с задачами
REST API	users-service	Авторизация, управление профилями
REST API	connections-service	Настройка связей между адаптерами
gRPC	tasks-service, users-service	Межсервисные синхронные вызовы
WebSocket	notification-service	Подключения клиентов для push-уведомлений

Сервисы → Хранилища данных

Источник	Назначение	Данные
tasks-service	PostgreSQL	Задачи, статусы, история изменений
users-service	PostgreSQL	Пользователи, профили, привязки к отелям
connections-service	PostgreSQL	Правила маршрутизации, реестр адаптеров
permissions-service	PostgreSQL	Роли, права доступа
audit-service	PostgreSQL	Журнал действий
scheduler-service	PostgreSQL	Расписания, шаблоны задач
events-service	PostgreSQL	Мероприятия, шаблоны декомпозиции
notification-service	Redis	Очереди уведомлений, статусы доставки
tasks-service	Redis	Кэш часто запрашиваемых задач
file-storage-service	S3	Фотографии, документы, вложения

Сервисы ↔ Kafka

Сервис	Публикует	Подписан на
tasks-service	События задач (создание, изменение статуса)	Команды на создание задач от адаптеров
notification-service	—	События задач для отправки уведомлений
connections-service	Маршрутизированные события	Входящие события от адаптеров

Kafka ↔ Адаптеры

Адаптер	В Kafka	Из Kafka
PMS Adapter	Бронирования, статусы номеров, данные гостей	Запросы на изменение статуса номера
ERP Adapter	Данные о материалах, заявки	Списания, обновления остатков
Housekeeping Adapter	Статусы уборки	Задачи на уборку
Telegram Bot Adapter	Сообщения от гостей	Уведомления для отправки

Адаптеры → Внешние системы

Адаптер	Внешняя система	Данные
PMS Adapter	PMS	Синхронизация бронирований и статусов номеров
ERP Adapter	ERP	Синхронизация складских данных
Housekeeping Adapter	Housekeeper	Синхронизация задач уборки

---

Технологический стек

Компонент	Технология
Backend	Python 3.11+ (FastAPI)
Frontend	TypeScript, React
База данных	PostgreSQL 15+
Кэш	Redis 7+
Файловое хранилище	S3-compatible (AWS S3 / MinIO)
Message Broker	Apache Kafka
API	REST, gRPC, WebSocket
Аутентификация	JWT / OAuth2
Контейнеризация	Docker
Оркестрация	Kubernetes