226 lines
10 KiB
Markdown
226 lines
10 KiB
Markdown
# 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 |
|