refactor project
This commit is contained in:
225
ARCHITECTURE.md
Normal file
225
ARCHITECTURE.md
Normal file
@ -0,0 +1,225 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user