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

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

```mermaid
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 |