diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b13ebc3 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.claude/ \ No newline at end of file diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..adba1f0 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,225 @@ +# HotelTask - Архитектура системы + +## Обзор системы + +```mermaid +flowchart TB + subgraph ClientLayer["Client Layer"] + WebAdmin["Web Admin
(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
Управление задачами"] + users["users-service
Управление пользователями"] + connections["connections-service
Связи между адаптерами"] + notification["notification-service
Уведомления"] + fileStorage["file-storage-service
Файлы"] + audit["audit-service
Аудит"] + scheduler["scheduler-service
Расписание"] + permissions["permissions-service
Права доступа"] + events["events-service
Мероприятия"] + end + + subgraph DataLayer["Data Layer"] + PostgreSQL[(PostgreSQL
Основная БД)] + Redis[(Redis
Кэш)] + S3[(S3
Файлы)] + 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 | diff --git a/BUSINESS_REQUIREMENTS.md b/BUSINESS_REQUIREMENTS.md new file mode 100644 index 0000000..3d8c4c7 --- /dev/null +++ b/BUSINESS_REQUIREMENTS.md @@ -0,0 +1,107 @@ +MVP «Таск-менеджер для сотрудников отеля HotelTask». +Платформа, состоящая из ряда сервисов, которые решают повседневные задачи, эффективно распределяют ресурсы объекта размещения, а так же предоставляют аналитику для улучшения. + + +Пользователи +Система должна поддерживать следующие роли: + +Администратор системы +- управление пользователями +- настройка ролей и прав доступа +- просмотр всех задач и отчетов + +Менеджер / Супервайзер +- создание и распределение задач +- контроль статусов выполнения +- приоритизация задач + +Линейный сотрудник +- просмотр назначенных задач +- изменение статуса задачи +- добавление комментариев и отметок о выполнении + +API интерфейс +- постановка задач для сотрудников +- изменение статуса задачи + + +Управление пользователями +Система должна обеспечивать: +- регистрацию и авторизацию пользователей +- назначение ролей пользователям +- редактирование профиля пользователя +- деактивацию пользователей + + +Управление задачами +Система должна позволять пользователям cоздавать задачу с указанием: +- названия +- описания +- типа задачи (уборка, ремонт, обслуживание гостей и т. д.) +- приоритета (низкий / средний / высокий / срочный) +- срока выполнения +- ответственного сотрудника +- ответственный супервайзер +- приоритетность + +а также иметь возможность: +- редактировать задачу +- удалять задачу (при наличии прав) +- назначать и переназначать исполнителей +- включать трекинг времени задачи, + + +Система должна поддерживать следующие статусы: +- новая +- в работе +- ожидает +- выполнена +- пауза +- отменена +Сотрудник должен иметь возможность менять статус своих задач. + + +Уведомления +Система должна с помощью push уведомлений: +- уведомлять сотрудника о назначении новой задачи +- уведомлять менеджера о завершении задачи +- отправлять напоминания о приближении срока выполнения + + + Комментарии и вложения +Система должна позволять: +- добавлять комментарии к задачам +- прикреплять фотографии или файлы (например, фото выполненной уборки +- просматривать историю изменений задачи + + +Поиск и фильтрация +Система должна обеспечивать: +- поиск задач по названию и описанию +- фильтрацию по: статусу, приоритету, сотруднику, дате выполнения, типу задачи + + +Отчеты и аналитика +Система должна предоставлять: +- отчет по выполненным задачам за период +- статистику по сотрудникам +- статистику по типам задач +- процент просроченных задач + + + +Доступ с разных устройств +Система должна: +- корректно работать в веб-браузере +- поддерживать мобильные устройства (адаптивный интерфейс) +- app + + +Интеграции +Система должна взаимодействовать с внешнеими PMS: +- получать бронирования с информацией о гостях и номер +- получать статус номера +- изменять статус номера +Система должна взаимодействовать с Консьерж Resonline: +- получать данные в нужный номер с информацией о заказе +- передавать статус заказа diff --git a/C4-Architecture.md b/C4-Architecture.md deleted file mode 100644 index a99db3f..0000000 --- a/C4-Architecture.md +++ /dev/null @@ -1,635 +0,0 @@ -[Назад](/README.md) - -# C4 Architecture Diagrams - TaskManager - -## Содержание -1. [Level 1: System Context](#level-1-system-context) -2. [Level 2: Container Diagram](#level-2-container-diagram) -3. [Level 3: Component Diagram - Tasks Service](#level-3-component-diagram---tasks-service) -4. [Level 3: Component Diagram - Adapter Layer](#level-3-component-diagram---adapter-layer) - ---- - -## Level 1: System Context - -Показывает TaskManager в контексте пользователей и внешних систем. - -```mermaid -C4Context - title System Context diagram for TaskManager - - Person(hotel_staff, "Hotel Staff", "Сотрудники отеля (горничные, техники, менеджеры)") - Person(admin, "System Admin", "Администратор системы") - Person(guest, "Hotel Guest", "Гость отеля") - - System(taskmanager, "TaskManager", "Платформа для управления задачами между подразделениями отеля и интеграции с внешними системами") - - System_Ext(pms, "PMS System", "Система управления отелем (Opera, Fidelio)") - System_Ext(erp, "ERP System", "Система управления ресурсами") - System_Ext(housekeeping, "Housekeeping App", "Приложение для управления уборкой") - System_Ext(email, "Email System", "SMTP сервер для отправки email") - System_Ext(sms, "SMS Gateway", "Сервис отправки SMS (Twilio)") - System_Ext(telegram, "Telegram", "Telegram Bot API") - System_Ext(s3, "AWS S3", "Хранилище файлов") - - Rel(hotel_staff, taskmanager, "Создает и управляет задачами", "Web/Mobile") - Rel(admin, taskmanager, "Настраивает систему, связи, роли", "Web Admin") - Rel(guest, taskmanager, "Создает запросы на обслуживание", "Telegram Bot") - - Rel(taskmanager, pms, "Получает/отправляет данные о бронированиях, номерах", "REST API/Webhook") - Rel(taskmanager, erp, "Интегрируется с учетом ресурсов", "REST API") - Rel(taskmanager, housekeeping, "Отправляет задачи на уборку", "REST API/Push") - Rel(taskmanager, email, "Отправляет уведомления", "SMTP") - Rel(taskmanager, sms, "Отправляет SMS уведомления", "REST API") - Rel(taskmanager, telegram, "Получает запросы гостей, отправляет уведомления", "Webhook/Bot API") - Rel(taskmanager, s3, "Хранит файлы и фото", "S3 API") - - UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2") -``` - ---- - -## Level 2: Container Diagram - -Показывает основные контейнеры (приложения и хранилища данных) внутри TaskManager. - -```mermaid -C4Container - title Container diagram for TaskManager - - Person(hotel_staff, "Hotel Staff", "Сотрудники отеля") - Person(admin, "System Admin", "Администратор системы") - Person(guest, "Hotel Guest", "Гость отеля") - - System_Ext(pms, "PMS System", "Opera/Fidelio") - System_Ext(erp, "ERP System", "ERP") - System_Ext(housekeeping_ext, "Housekeeping App", "External App") - System_Ext(email_ext, "Email System", "SMTP") - System_Ext(sms_ext, "SMS Gateway", "Twilio") - System_Ext(telegram_ext, "Telegram", "Bot API") - System_Ext(s3_ext, "AWS S3", "File Storage") - - Container_Boundary(taskmanager, "TaskManager System") { - - Container(web_admin, "Web Admin", "React, TypeScript", "Веб-приложение для настройки системы и управления") - Container(mobile_app, "Mobile App", "React Native/Flutter", "Мобильное приложение для сотрудников") - - Container(api_gateway, "API Gateway", "Kong/Envoy", "Единая точка входа, маршрутизация, аутентификация") - - Container(tasks_service, "Tasks Service", "Python, FastAPI, gRPC", "Управление задачами") - Container(connections_service, "Connections Service", "Python, FastAPI, gRPC", "Управление связями между адаптерами") - Container(users_service, "Users Service", "Python, FastAPI, gRPC", "Управление пользователями") - Container(permissions_service, "Permissions Service", "Python, FastAPI, gRPC", "Управление ролями и правами (RBAC)") - Container(notification_service, "Notification Service", "Python, FastAPI", "Отправка уведомлений через разные каналы") - Container(file_storage_service, "File Storage Service", "Python, FastAPI", "Управление файлами") - Container(audit_service, "Audit Service", "Python, FastAPI", "Логирование всех действий") - Container(scheduler_service, "Scheduler Service", "Python, FastAPI", "Управление периодическими задачами") - Container(events_service, "Events Service", "Python, FastAPI, gRPC", "Управление мероприятиями") - - Container(pms_adapter, "PMS Adapter", "Python", "Адаптер для PMS системы") - Container(erp_adapter, "ERP Adapter", "Python", "Адаптер для ERP системы") - Container(housekeeping_adapter, "Housekeeping Adapter", "Python", "Адаптер для приложения уборки") - Container(telegram_adapter, "Telegram Bot Adapter", "Python", "Адаптер для Telegram бота") - - ContainerQueue(kafka, "Message Broker", "Apache Kafka", "Асинхронная коммуникация между сервисами") - - ContainerDb(postgres, "Database", "PostgreSQL", "Хранение данных системы") - ContainerDb(redis, "Cache", "Redis", "Кэширование данных, сессии") - } - - Rel(hotel_staff, web_admin, "Использует", "HTTPS") - Rel(hotel_staff, mobile_app, "Использует", "HTTPS") - Rel(admin, web_admin, "Настраивает систему", "HTTPS") - Rel(guest, telegram_adapter, "Отправляет запросы", "Telegram") - - Rel(web_admin, api_gateway, "Делает API запросы", "REST/gRPC-Web") - Rel(mobile_app, api_gateway, "Делает API запросы", "REST/gRPC") - - Rel(api_gateway, tasks_service, "Маршрутизирует запросы", "gRPC") - Rel(api_gateway, users_service, "Маршрутизирует запросы", "gRPC") - Rel(api_gateway, connections_service, "Маршрутизирует запросы", "gRPC") - Rel(api_gateway, events_service, "Маршрутизирует запросы", "gRPC") - Rel(api_gateway, file_storage_service, "Маршрутизирует запросы", "REST") - - Rel(tasks_service, kafka, "Публикует события", "Kafka Protocol") - Rel(connections_service, kafka, "Публикует/читает события", "Kafka Protocol") - Rel(scheduler_service, kafka, "Публикует триггеры", "Kafka Protocol") - Rel(events_service, kafka, "Публикует события", "Kafka Protocol") - Rel(notification_service, kafka, "Читает события", "Kafka Protocol") - Rel(audit_service, kafka, "Читает все события", "Kafka Protocol") - - Rel(tasks_service, permissions_service, "Проверяет права", "gRPC") - Rel(users_service, permissions_service, "Проверяет права", "gRPC") - - Rel(pms_adapter, kafka, "Публикует сообщения", "Kafka Protocol") - Rel(erp_adapter, kafka, "Публикует сообщения", "Kafka Protocol") - Rel(housekeeping_adapter, kafka, "Публикует сообщения", "Kafka Protocol") - Rel(telegram_adapter, kafka, "Публикует сообщения", "Kafka Protocol") - - Rel(pms_adapter, pms, "Получает/отправляет данные", "REST API/Webhook") - Rel(erp_adapter, erp, "Получает/отправляет данные", "REST API") - Rel(housekeeping_adapter, housekeeping_ext, "Отправляет задачи", "REST API/Push") - Rel(telegram_adapter, telegram_ext, "Взаимодействует с ботом", "Webhook/Bot API") - - Rel(notification_service, email_ext, "Отправляет email", "SMTP") - Rel(notification_service, sms_ext, "Отправляет SMS", "REST API") - Rel(notification_service, telegram_ext, "Отправляет сообщения", "Bot API") - - Rel(file_storage_service, s3_ext, "Хранит файлы", "S3 API") - - Rel(tasks_service, postgres, "Читает/пишет данные", "SQL") - Rel(users_service, postgres, "Читает/пишет данные", "SQL") - Rel(connections_service, postgres, "Читает/пишет данные", "SQL") - Rel(permissions_service, postgres, "Читает/пишет данные", "SQL") - Rel(scheduler_service, postgres, "Читает/пишет данные", "SQL") - Rel(events_service, postgres, "Читает/пишет данные", "SQL") - Rel(audit_service, postgres, "Пишет логи", "SQL") - Rel(file_storage_service, postgres, "Пишет метаданные", "SQL") - - Rel(tasks_service, redis, "Кэширует данные", "Redis Protocol") - Rel(users_service, redis, "Кэширует данные", "Redis Protocol") - Rel(permissions_service, redis, "Кэширует права", "Redis Protocol") - - UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="2") -``` - ---- - -## Level 3: Component Diagram - Tasks Service - -Показывает внутреннюю структуру Tasks Service. - -```mermaid -C4Component - title Component diagram for Tasks Service - - Container_Ext(api_gateway, "API Gateway", "Kong/Envoy", "Точка входа") - Container_Ext(kafka, "Kafka", "Apache Kafka", "Message Broker") - ContainerDb_Ext(postgres, "PostgreSQL", "Database", "Основная БД") - ContainerDb_Ext(redis, "Redis", "Cache", "Кэш") - Container_Ext(permissions_service, "Permissions Service", "Python, gRPC", "Проверка прав") - Container_Ext(file_storage_service, "File Storage Service", "Python", "Управление файлами") - - Container_Boundary(tasks_service, "Tasks Service") { - - Component(grpc_api, "gRPC API", "Python, gRPC", "Обработка gRPC запросов") - Component(rest_api, "REST API", "FastAPI", "Обработка REST запросов (fallback)") - - Component(task_controller, "Task Controller", "Python", "Обработка бизнес-логики задач") - Component(status_controller, "Status Controller", "Python", "Управление статусами задач") - Component(dependency_controller, "Dependency Controller", "Python", "Управление зависимостями") - Component(history_controller, "History Controller", "Python", "Управление историей изменений") - - Component(task_repository, "Task Repository", "SQLAlchemy", "Работа с БД задач") - Component(status_repository, "Status Repository", "SQLAlchemy", "Работа с БД статусов") - Component(dependency_repository, "Dependency Repository", "SQLAlchemy", "Работа с БД зависимостей") - Component(history_repository, "History Repository", "SQLAlchemy", "Работа с БД истории") - - Component(kafka_producer, "Kafka Producer", "aiokafka", "Публикация событий в Kafka") - Component(kafka_consumer, "Kafka Consumer", "aiokafka", "Чтение событий из Kafka") - - Component(cache_manager, "Cache Manager", "Redis Client", "Управление кэшем") - Component(permission_client, "Permission Client", "gRPC Client", "Проверка прав доступа") - - Component(task_validator, "Task Validator", "Pydantic", "Валидация данных задач") - Component(event_mapper, "Event Mapper", "Python", "Маппинг событий") - } - - Rel(api_gateway, grpc_api, "Отправляет gRPC запросы", "gRPC") - Rel(api_gateway, rest_api, "Отправляет REST запросы", "HTTP/JSON") - - Rel(grpc_api, task_controller, "Вызывает методы") - Rel(rest_api, task_controller, "Вызывает методы") - - Rel(task_controller, task_validator, "Валидирует данные") - Rel(task_controller, permission_client, "Проверяет права") - Rel(task_controller, task_repository, "Работает с задачами") - Rel(task_controller, status_controller, "Изменяет статусы") - Rel(task_controller, dependency_controller, "Управляет зависимостями") - Rel(task_controller, history_controller, "Записывает историю") - Rel(task_controller, cache_manager, "Кэширует данные") - Rel(task_controller, kafka_producer, "Публикует события") - - Rel(status_controller, status_repository, "Работает со статусами") - Rel(dependency_controller, dependency_repository, "Работает с зависимостями") - Rel(history_controller, history_repository, "Работает с историей") - - Rel(kafka_consumer, event_mapper, "Маппит события") - Rel(event_mapper, task_controller, "Обрабатывает события") - - Rel(task_repository, postgres, "Выполняет SQL запросы", "SQL") - Rel(status_repository, postgres, "Выполняет SQL запросы", "SQL") - Rel(dependency_repository, postgres, "Выполняет SQL запросы", "SQL") - Rel(history_repository, postgres, "Выполняет SQL запросы", "SQL") - - Rel(cache_manager, redis, "Кэширует/читает данные", "Redis Protocol") - Rel(permission_client, permissions_service, "Проверяет права", "gRPC") - - Rel(kafka_producer, kafka, "Публикует события", "Kafka Protocol") - Rel(kafka_consumer, kafka, "Читает события", "Kafka Protocol") - - UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1") -``` - ---- - -## Level 3: Component Diagram - Adapter Layer - -Показывает внутреннюю структуру адаптера (на примере PMS Adapter). - -```mermaid -C4Component - title Component diagram for PMS Adapter (Example) - - System_Ext(pms_system, "PMS System", "Opera/Fidelio", "Внешняя PMS система") - Container_Ext(kafka, "Kafka", "Apache Kafka", "Message Broker") - Container_Ext(postgres, "PostgreSQL", "Database", "Хранение состояния адаптера") - - Container_Boundary(pms_adapter, "PMS Adapter") { - - Component(webhook_handler, "Webhook Handler", "FastAPI", "Принимает webhook от PMS") - Component(api_poller, "API Poller", "Python, APScheduler", "Опрашивает PMS API по расписанию") - Component(rest_client, "REST Client", "httpx", "HTTP клиент для PMS API") - - Component(inbound_transformer, "Inbound Transformer", "Python", "PMS формат → Стандартный формат") - Component(outbound_transformer, "Outbound Transformer", "Python", "Стандартный формат → PMS формат") - - Component(message_validator, "Message Validator", "Pydantic", "Валидация сообщений") - Component(event_publisher, "Event Publisher", "aiokafka", "Публикация событий в Kafka") - Component(event_consumer, "Event Consumer", "aiokafka", "Чтение событий из Kafka") - - Component(state_manager, "State Manager", "SQLAlchemy", "Управление состоянием синхронизации") - Component(error_handler, "Error Handler", "Python", "Обработка ошибок и retry") - Component(config_manager, "Config Manager", "Python", "Управление конфигурацией") - } - - Rel(pms_system, webhook_handler, "Отправляет webhook", "HTTP/JSON") - Rel(api_poller, rest_client, "Запрашивает данные") - Rel(rest_client, pms_system, "Делает API запросы", "REST/SOAP") - - Rel(webhook_handler, inbound_transformer, "Передает данные") - Rel(api_poller, inbound_transformer, "Передает данные") - - Rel(inbound_transformer, message_validator, "Валидирует сообщение") - Rel(message_validator, event_publisher, "Публикует валидное событие") - - Rel(event_consumer, kafka, "Читает исходящие события", "Kafka Protocol") - Rel(event_consumer, outbound_transformer, "Передает событие") - Rel(outbound_transformer, rest_client, "Отправляет в PMS") - - Rel(event_publisher, kafka, "Публикует входящие события", "Kafka Protocol") - - Rel(state_manager, postgres, "Сохраняет состояние", "SQL") - Rel(error_handler, state_manager, "Логирует ошибки") - - Rel(webhook_handler, error_handler, "Обрабатывает ошибки") - Rel(api_poller, error_handler, "Обрабатывает ошибки") - Rel(rest_client, error_handler, "Обрабатывает ошибки") - - Rel(config_manager, api_poller, "Предоставляет конфигурацию") - Rel(config_manager, rest_client, "Предоставляет конфигурацию") - - UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1") -``` - ---- - -## Deployment Diagram (Kubernetes) - -Показывает развертывание в Kubernetes кластере. - -```mermaid -C4Deployment - title Deployment Diagram for TaskManager (Kubernetes) - - Deployment_Node(k8s_cluster, "Kubernetes Cluster", "GKE/EKS/AKS") { - - Deployment_Node(ingress_ns, "Namespace: ingress") { - Container(ingress, "Ingress Controller", "NGINX/Traefik", "Входная точка для внешнего трафика") - } - - Deployment_Node(gateway_ns, "Namespace: gateway") { - Container(api_gateway, "API Gateway", "Kong/Envoy", "3 replicas", "Маршрутизация и аутентификация") - } - - Deployment_Node(services_ns, "Namespace: services") { - Container(tasks_svc, "Tasks Service", "Python, FastAPI", "5 replicas", "Управление задачами") - Container(users_svc, "Users Service", "Python, FastAPI", "3 replicas", "Управление пользователями") - Container(connections_svc, "Connections Service", "Python, FastAPI", "2 replicas", "Управление связями") - Container(permissions_svc, "Permissions Service", "Python, FastAPI", "3 replicas", "RBAC") - Container(notification_svc, "Notification Service", "Python, FastAPI", "3 replicas", "Уведомления") - Container(file_storage_svc, "File Storage Service", "Python, FastAPI", "2 replicas", "Файлы") - Container(audit_svc, "Audit Service", "Python, FastAPI", "2 replicas", "Аудит") - Container(scheduler_svc, "Scheduler Service", "Python, FastAPI", "1 replica", "Планировщик") - Container(events_svc, "Events Service", "Python, FastAPI", "2 replicas", "Мероприятия") - } - - Deployment_Node(adapters_ns, "Namespace: adapters") { - Container(pms_adapter, "PMS Adapter", "Python", "2 replicas", "PMS интеграция") - Container(erp_adapter, "ERP Adapter", "Python", "1 replica", "ERP интеграция") - Container(housekeeping_adapter, "Housekeeping Adapter", "Python", "2 replicas", "Уборка") - Container(telegram_adapter, "Telegram Adapter", "Python", "2 replicas", "Telegram бот") - } - - Deployment_Node(data_ns, "Namespace: data") { - ContainerDb(postgres_primary, "PostgreSQL Primary", "PostgreSQL 15", "1 pod", "Основная БД (master)") - ContainerDb(postgres_replica, "PostgreSQL Replica", "PostgreSQL 15", "2 pods", "Реплики для чтения") - ContainerDb(redis_cluster, "Redis Cluster", "Redis 7", "3 pods", "Кэш и сессии") - ContainerQueue(kafka_cluster, "Kafka Cluster", "Apache Kafka", "3 brokers", "Message broker") - } - - Deployment_Node(monitoring_ns, "Namespace: monitoring") { - Container(prometheus, "Prometheus", "Prometheus", "Сбор метрик") - Container(grafana, "Grafana", "Grafana", "Визуализация метрик") - Container(jaeger, "Jaeger", "Jaeger", "Distributed tracing") - } - } - - Deployment_Node(external_services, "External Services") { - Container(s3, "AWS S3", "Object Storage", "Хранилище файлов") - Container(smtp, "SMTP Server", "Email", "Отправка email") - Container(sms_gateway, "SMS Gateway", "Twilio", "Отправка SMS") - } - - Rel(ingress, api_gateway, "Routes traffic", "HTTPS") - - Rel(api_gateway, tasks_svc, "Calls", "gRPC") - Rel(api_gateway, users_svc, "Calls", "gRPC") - Rel(api_gateway, connections_svc, "Calls", "gRPC") - Rel(api_gateway, events_svc, "Calls", "gRPC") - Rel(api_gateway, file_storage_svc, "Calls", "REST") - - Rel(tasks_svc, kafka_cluster, "Publishes/Consumes", "Kafka Protocol") - Rel(connections_svc, kafka_cluster, "Publishes/Consumes", "Kafka Protocol") - Rel(scheduler_svc, kafka_cluster, "Publishes", "Kafka Protocol") - Rel(notification_svc, kafka_cluster, "Consumes", "Kafka Protocol") - Rel(audit_svc, kafka_cluster, "Consumes", "Kafka Protocol") - - Rel(pms_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol") - Rel(erp_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol") - Rel(housekeeping_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol") - Rel(telegram_adapter, kafka_cluster, "Publishes/Consumes", "Kafka Protocol") - - Rel(tasks_svc, postgres_primary, "Writes", "SQL") - Rel(tasks_svc, postgres_replica, "Reads", "SQL") - Rel(users_svc, postgres_primary, "Writes", "SQL") - Rel(users_svc, postgres_replica, "Reads", "SQL") - Rel(audit_svc, postgres_primary, "Writes logs", "SQL") - - Rel(tasks_svc, redis_cluster, "Cache", "Redis Protocol") - Rel(users_svc, redis_cluster, "Cache", "Redis Protocol") - Rel(permissions_svc, redis_cluster, "Cache permissions", "Redis Protocol") - - Rel(file_storage_svc, s3, "Stores files", "S3 API") - Rel(notification_svc, smtp, "Sends emails", "SMTP") - Rel(notification_svc, sms_gateway, "Sends SMS", "REST API") - - Rel(prometheus, tasks_svc, "Scrapes metrics", "HTTP") - Rel(prometheus, users_svc, "Scrapes metrics", "HTTP") - Rel(grafana, prometheus, "Queries metrics", "HTTP") - - UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1") -``` - ---- - -## Sequence Diagram: Creating Task from External System - -Показывает последовательность действий при создании задачи из внешней системы. - -```mermaid -sequenceDiagram - participant PMS as PMS System (Opera) - participant Adapter as PMS Adapter - participant Kafka as Apache Kafka - participant Connections as Connections Service - participant Tasks as Tasks Service - participant Permissions as Permissions Service - participant Audit as Audit Service - participant Notification as Notification Service - participant DB as PostgreSQL - participant Housekeeping as Housekeeping Adapter - participant HK_App as Housekeeping App - - Note over PMS,HK_App: Сценарий: Гость выехал из номера, нужна уборка - - PMS->>Adapter: Webhook: Guest Checkout (Room 305) - Adapter->>Adapter: Validate webhook signature - Adapter->>Adapter: Transform to standard format - Adapter->>Kafka: Publish: adapters.pms.checkout - - Note over Kafka: Topic: adapters.pms.checkout - - Kafka->>Connections: Consume: adapters.pms.checkout - Connections->>DB: Get routing rules for PMS → TaskManager - DB-->>Connections: Routing rules - Connections->>Connections: Apply rules: checkout → create cleaning task - Connections->>Kafka: Publish: connections.route_task - - Note over Kafka: Topic: connections.route_task - - Kafka->>Tasks: Consume: connections.route_task - Tasks->>Permissions: CheckPermission(source_adapter, create_task) - Permissions->>DB: Query permissions - DB-->>Permissions: Permission granted - Permissions-->>Tasks: Allowed - - Tasks->>Tasks: Create task object - Tasks->>DB: INSERT INTO tasks (...) - DB-->>Tasks: Task created (id: uuid) - - Tasks->>Kafka: Publish: tasks.created - - Note over Kafka: Topic: tasks.created - - par Parallel Processing - Kafka->>Audit: Consume: tasks.created - Audit->>DB: INSERT INTO audit_log - - Kafka->>Notification: Consume: tasks.created - Notification->>DB: Get user notification preferences - DB-->>Notification: User prefers Telegram - Notification->>Notification: Send Telegram notification - - Kafka->>Connections: Consume: tasks.created - Connections->>DB: Get routing rules for TaskManager → Housekeeping - DB-->>Connections: Route to Housekeeping Adapter - Connections->>Kafka: Publish: connections.route_task - end - - Note over Kafka: Topic: connections.route_task - - Kafka->>Housekeeping: Consume: connections.route_task - Housekeeping->>Housekeeping: Transform to Housekeeping App format - Housekeeping->>HK_App: POST /api/tasks (Room 305 cleaning) - HK_App-->>Housekeeping: Task assigned (assignee: Maria) - - Housekeeping->>Kafka: Publish: adapters.housekeeping.task_assigned - - Kafka->>Tasks: Consume: adapters.housekeeping.task_assigned - Tasks->>DB: UPDATE tasks SET assignee_id = ... - Tasks->>Kafka: Publish: tasks.assigned - - Note over PMS,HK_App: Task created and assigned to housekeeping staff -``` - ---- - -## Sequence Diagram: Creating Event with Auto-Generated Tasks - -Показывает создание мероприятия и автоматическую генерацию задач. - -```mermaid -sequenceDiagram - participant User as Sales Manager - participant Web as Web Admin - participant Gateway as API Gateway - participant Events as Events Service - participant Tasks as Tasks Service - participant Kafka as Apache Kafka - participant DB as PostgreSQL - participant Notification as Notification Service - - Note over User,Notification: Сценарий: Создание конференции на 50 человек - - User->>Web: Create Event: "Marketing Conference" - Web->>Gateway: POST /api/v1/events (event details) - Gateway->>Gateway: Authenticate & Authorize - - Gateway->>Events: CreateEvent(gRPC) - Events->>DB: INSERT INTO events - DB-->>Events: Event created (id: uuid) - - Events->>Events: Generate tasks from event template - Note over Events: Tasks: Setup chairs, Prepare projector,
Organize coffee break, etc. - - loop For each generated task - Events->>Tasks: CreateTask(gRPC) - Tasks->>DB: INSERT INTO tasks - DB-->>Tasks: Task created - Tasks->>Kafka: Publish: tasks.created - Tasks-->>Events: Task ID - end - - Events->>DB: INSERT INTO event_tasks (event_id, task_id) - Events->>Kafka: Publish: events.created - Events->>Kafka: Publish: events.tasks_generated - - Events-->>Gateway: Event + generated tasks - Gateway-->>Web: 201 Created (event + tasks) - Web-->>User: Show created event with tasks - - par Notify departments - Kafka->>Notification: Consume: tasks.created - loop For each task - Notification->>Notification: Get assignee notification prefs - Notification->>Notification: Send notification (Telegram/Email) - end - end - - Note over User,Notification: All tasks created and departments notified -``` - ---- - -## Data Flow Diagram - -Показывает потоки данных в системе. - -```mermaid -flowchart TB - subgraph External["External Systems"] - PMS["PMS System"] - ERP["ERP System"] - Guest["Guest (Telegram)"] - end - - subgraph Adapters["Adapter Layer"] - PMS_A["PMS Adapter"] - ERP_A["ERP Adapter"] - TG_A["Telegram Adapter"] - end - - subgraph Kafka["Apache Kafka"] - T1["adapters.*"] - T2["tasks.*"] - T3["connections.*"] - T4["notifications.*"] - T5["audit.*"] - end - - subgraph Core["Core Services"] - Connections["Connections Service
(Routing Rules)"] - Tasks["Tasks Service
(Task Management)"] - Users["Users Service"] - Permissions["Permissions Service"] - end - - subgraph Support["Support Services"] - Notification["Notification Service"] - Audit["Audit Service"] - Scheduler["Scheduler Service"] - end - - subgraph Data["Data Layer"] - DB["PostgreSQL"] - Cache["Redis"] - end - - %% External to Adapters - PMS -->|"Webhook/API"| PMS_A - ERP -->|"API"| ERP_A - Guest -->|"Telegram Bot"| TG_A - - %% Adapters to Kafka - PMS_A -->|"Publish events"| T1 - ERP_A -->|"Publish events"| T1 - TG_A -->|"Publish events"| T1 - - %% Kafka to Connections - T1 -->|"Consume"| Connections - - %% Connections routing - Connections -->|"Route messages"| T3 - T3 -->|"Consume"| Tasks - - %% Tasks operations - Tasks -->|"Publish events"| T2 - Tasks -->|"Query permissions"| Permissions - Tasks -->|"Write/Read"| DB - Tasks -->|"Cache"| Cache - - %% Support services - T2 -->|"Consume"| Notification - T2 -->|"Consume"| Audit - Scheduler -->|"Trigger tasks"| T2 - - Notification -->|"Send notifications"| External - Audit -->|"Write logs"| DB - - %% Users and Permissions - Users -->|"Write/Read"| DB - Permissions -->|"Write/Read"| DB - Permissions -->|"Cache permissions"| Cache - - style Kafka fill:#ff9900 - style Core fill:#00cc66 - style Support fill:#3399ff - style Data fill:#cc66ff -``` - ---- - -## Notes - -### Как использовать эти диаграммы: - -1. **System Context (Level 1)**: Показывает TaskManager как черный ящик в контексте пользователей и внешних систем. Используйте для презентации бизнес-заказчикам. - -2. **Container Diagram (Level 2)**: Показывает основные приложения и хранилища данных. Используйте для обсуждения с архитекторами и DevOps командой. - -3. **Component Diagrams (Level 3)**: Показывают внутреннюю структуру отдельных сервисов. Используйте для разработчиков при проектировании конкретного сервиса. - -4. **Deployment Diagram**: Показывает как система развернута в Kubernetes. Используйте для DevOps и планирования инфраструктуры. - -5. **Sequence Diagrams**: Показывают взаимодействие компонентов во времени для конкретных сценариев. Используйте для понимания бизнес-процессов. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..624db87 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,36 @@ +# HotelTask - Точка входа для агента + +## Промт + +Ты работаешь над проектом **HotelTask** — единой платформой управления задачами для отелей. + +**Проблема:** В отелях разные подразделения (ресепшен, горничные, техслужба, ресторан) используют разрозненные приложения и мессенджеры. Это ненадежно, информация теряется, ресепшен перегружен. + +**Решение:** Система-ядро (Task Manager) со стандартизированным контрактом задач. Внешние системы (PMS, ERP, Housekeeper) подключаются через адаптеры. Коммуникация через Apache Kafka. В админке настраиваются связи между системами. + +**Стек:** Python (FastAPI), PostgreSQL, Redis, Kafka, React (админка). + +--- + +## Файлы проекта + +| Файл | Зона ответственности | +|------|---------------------| +| [CLAUDE.md](CLAUDE.md) | Точка входа агента, промт | +| [CONTEXT.md](CONTEXT.md) | Память между сессиями, текущий статус | +| [ROADMAP.md](ROADMAP.md) | Этапы разработки, границы MVP | +| [BUSINESS_REQUIREMENTS.md](BUSINESS_REQUIREMENTS.md) | Бизнес-требования, роли, функционал | +| [REQUIREMENTS.md](REQUIREMENTS.md) | Структурированные FR/NFR | +| [ARCHITECTURE.md](ARCHITECTURE.md) | Архитектура, сервисы, потоки данных | + +--- + +## Инструкции + +**При работе над аналитикой/разработкой** изучи: +1. [CONTEXT.md](CONTEXT.md) — восстанови контекст +2. [ROADMAP.md](ROADMAP.md) — пойми на каком этапе проект +3. [BUSINESS_REQUIREMENTS.md](BUSINESS_REQUIREMENTS.md) + [REQUIREMENTS.md](REQUIREMENTS.md) — требования +4. [ARCHITECTURE.md](ARCHITECTURE.md) — архитектура + +После изучения скажи: "Изучил, жду инструкций" diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..c673fbe --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,43 @@ +# HotelTask - Контекст проекта + +## Текущий статус + +**Этап:** Проектирование (в процессе) + +Подробности по этапам и границам MVP см. в [ROADMAP.md](ROADMAP.md) + +--- + +## Что сделано + +- [x] Собраны бизнес-требования +- [x] Структурированы FR/NFR +- [x] Определены роли пользователей +- [x] Определен scope MVP +- [x] Высокоуровневая архитектура (9 микросервисов) + +## Что в работе + +- [ ] Схема БД (ERD) +- [ ] API контракты (OpenAPI) +- [ ] Модель данных Task + +--- + +## Ключевые технические решения + +| Решение | Выбор | Обоснование | +|---------|-------|-------------| +| Backend | Python (FastAPI) | Быстрая разработка, async support | +| DB | PostgreSQL | Надежность, JSON support | +| Cache | Redis | Скорость, pub/sub | +| Message Broker | Apache Kafka | Надежная доставка, масштабируемость | +| Frontend | React + TypeScript | Популярность, типизация | +| Auth | JWT | Stateless, масштабируемость | +| Storage | S3-compatible | Стандарт для файлов | + +--- + +## Заметки для следующей сессии + +*(Здесь агент может оставлять заметки для себя)* diff --git a/README.md b/README.md deleted file mode 100644 index 8c13a13..0000000 --- a/README.md +++ /dev/null @@ -1,2 +0,0 @@ -- [Вопросы](/Вопросы.md) -- [Анализ требований](/Анализ%20требований.md) \ No newline at end of file diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md new file mode 100644 index 0000000..f88b2d9 --- /dev/null +++ b/REQUIREMENTS.md @@ -0,0 +1,252 @@ +# Требования к приложению HotelTask + +## Содержание +1. [Функциональные требования](#1-функциональные-требования-fr) +2. [Нефункциональные требования](#2-нефункциональные-требования-nfr) + +--- + +## 1. Функциональные требования (FR) + +### 1.1 Управление пользователями (FR-USER) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-USER-001 | Система должна обеспечивать регистрацию пользователей | High | Да | +| FR-USER-002 | Система должна обеспечивать авторизацию пользователей | High | Да | +| FR-USER-003 | Система должна поддерживать назначение ролей пользователям | High | Да | +| FR-USER-004 | Система должна позволять редактировать профиль пользователя | Medium | Да | +| FR-USER-005 | Система должна позволять деактивировать пользователей | Medium | Да | +| FR-USER-006 | Система должна поддерживать привязку пользователя к подразделению | High | Да | + +### 1.2 Роли и права доступа (FR-ROLE) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-ROLE-001 | Система должна поддерживать роль "Администратор системы" с полным доступом | High | Да | +| FR-ROLE-002 | Система должна поддерживать роль "Менеджер/Супервайзер" для управления задачами | High | Да | +| FR-ROLE-003 | Система должна поддерживать роль "Линейный сотрудник" для выполнения задач | High | Да | +| FR-ROLE-004 | Система должна поддерживать API-доступ для внешних систем | High | Да | +| FR-ROLE-005 | Система должна позволять настраивать гранулярные права доступа | Medium | Нет | + +### 1.3 Управление задачами (FR-TASK) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-TASK-001 | Система должна позволять создавать задачу с названием и описанием | High | Да | +| FR-TASK-002 | Система должна поддерживать типы задач (уборка, ремонт, обслуживание и т.д.) | High | Да | +| FR-TASK-003 | Система должна поддерживать приоритеты задач (низкий, средний, высокий, срочный) | High | Да | +| FR-TASK-004 | Система должна позволять указывать срок выполнения задачи | High | Да | +| FR-TASK-005 | Система должна позволять назначать ответственного сотрудника | High | Да | +| FR-TASK-006 | Система должна позволять назначать супервайзера задачи | Medium | Да | +| FR-TASK-007 | Система должна позволять редактировать задачу | High | Да | +| FR-TASK-008 | Система должна позволять удалять задачу (при наличии прав) | Medium | Да | +| FR-TASK-009 | Система должна позволять переназначать исполнителей | High | Да | +| FR-TASK-010 | Система должна поддерживать трекинг времени выполнения задачи | Medium | Нет | +| FR-TASK-011 | Система должна позволять создавать встречную задачу | Medium | Нет | + +### 1.4 Статусы задач (FR-STATUS) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-STATUS-001 | Система должна поддерживать статус "Новая" | High | Да | +| FR-STATUS-002 | Система должна поддерживать статус "В работе" | High | Да | +| FR-STATUS-003 | Система должна поддерживать статус "Ожидает" | High | Да | +| FR-STATUS-004 | Система должна поддерживать статус "Выполнена" | High | Да | +| FR-STATUS-005 | Система должна поддерживать статус "Пауза" | Medium | Да | +| FR-STATUS-006 | Система должна поддерживать статус "Отменена" | Medium | Да | +| FR-STATUS-007 | Сотрудник должен иметь возможность менять статус своих задач | High | Да | + +### 1.5 Уведомления (FR-NOTIFY) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-NOTIFY-001 | Система должна уведомлять сотрудника о назначении новой задачи (push) | High | Да | +| FR-NOTIFY-002 | Система должна уведомлять менеджера о завершении задачи | High | Да | +| FR-NOTIFY-003 | Система должна отправлять напоминания о приближении срока выполнения | Medium | Да | +| FR-NOTIFY-004 | Система должна поддерживать настройку типов уведомлений для пользователя | Low | Нет | + +### 1.6 Комментарии и вложения (FR-ATTACH) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-ATTACH-001 | Система должна позволять добавлять комментарии к задачам | High | Да | +| FR-ATTACH-002 | Система должна позволять прикреплять фотографии к задачам | High | Да | +| FR-ATTACH-003 | Система должна позволять прикреплять файлы к задачам | Medium | Да | +| FR-ATTACH-004 | Система должна сохранять историю изменений задачи | Medium | Да | + +### 1.7 Поиск и фильтрация (FR-SEARCH) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-SEARCH-001 | Система должна обеспечивать поиск задач по названию | High | Да | +| FR-SEARCH-002 | Система должна обеспечивать поиск задач по описанию | Medium | Да | +| FR-SEARCH-003 | Система должна обеспечивать фильтрацию по статусу | High | Да | +| FR-SEARCH-004 | Система должна обеспечивать фильтрацию по приоритету | High | Да | +| FR-SEARCH-005 | Система должна обеспечивать фильтрацию по сотруднику | High | Да | +| FR-SEARCH-006 | Система должна обеспечивать фильтрацию по дате выполнения | Medium | Да | +| FR-SEARCH-007 | Система должна обеспечивать фильтрацию по типу задачи | Medium | Да | + +### 1.8 Отчеты и аналитика (FR-REPORT) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-REPORT-001 | Система должна предоставлять отчет по выполненным задачам за период | Medium | Нет | +| FR-REPORT-002 | Система должна предоставлять статистику по сотрудникам | Medium | Нет | +| FR-REPORT-003 | Система должна предоставлять статистику по типам задач | Medium | Нет | +| FR-REPORT-004 | Система должна предоставлять процент просроченных задач | Medium | Нет | + +### 1.9 Интеграции (FR-INT) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-INT-001 | Система должна получать бронирования из PMS с информацией о гостях и номерах | High | Да | +| FR-INT-002 | Система должна получать статус номера из PMS | High | Да | +| FR-INT-003 | Система должна изменять статус номера в PMS | High | Да | +| FR-INT-004 | Система должна взаимодействовать с Консьерж Resonline | Medium | Нет | +| FR-INT-005 | Система должна поддерживать подключение произвольных адаптеров | High | Да | +| FR-INT-006 | Адаптер должен регистрировать поддерживаемые типы событий | High | Да | + +### 1.10 Управление связями между системами (FR-CONN) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-CONN-001 | Система должна позволять настраивать маршрутизацию событий между адаптерами | High | Да | +| FR-CONN-002 | Система должна предоставлять интерфейс для настройки связей (событие из А -> Б, В, Г) | High | Да | +| FR-CONN-003 | Система должна хранить реестр подключенных адаптеров и их возможностей | High | Да | + +### 1.11 Планировщик задач (FR-SCHED) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-SCHED-001 | Система должна поддерживать создание регулярных/периодических задач | Medium | Нет | +| FR-SCHED-002 | Система должна автоматически создавать задачи по расписанию | Medium | Нет | + +### 1.12 Модуль мероприятий (FR-EVENT) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-EVENT-001 | Система должна позволять описывать мероприятие | Low | Нет | +| FR-EVENT-002 | Система должна автоматически декомпозировать мероприятие на задачи | Low | Нет | +| FR-EVENT-003 | Система должна поддерживать массовое создание связанных задач | Low | Нет | +| FR-EVENT-004 | Система должна формировать документ "функшн" на основе данных мероприятия | Low | Нет | + +### 1.13 Специализированный интерфейс горничных (FR-HOUSE) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-HOUSE-001 | Система должна предоставлять интерфейс с пошаговым процессом уборки | Medium | Нет | +| FR-HOUSE-002 | Система должна требовать фото до и после уборки | Medium | Нет | +| FR-HOUSE-003 | Система должна фиксировать время начала и окончания уборки | Medium | Нет | + +### 1.14 Интерфейс для гостей (FR-GUEST) + +| ID | Требование | Приоритет | MVP | +|----|------------|-----------|-----| +| FR-GUEST-001 | Система должна предоставлять интерфейс для гостей (бот/веб) | Low | Нет | +| FR-GUEST-002 | Система должна предоставлять набор базовых услуг с кнопками | Low | Нет | +| FR-GUEST-003 | Система должна автоматически создавать задачи из запросов гостей | Low | Нет | + +--- + +## 2. Нефункциональные требования (NFR) + +### 2.1 Производительность (NFR-PERF) + +| ID | Требование | Значение | +|----|------------|----------| +| NFR-PERF-001 | Время отклика API при стандартной нагрузке | < 500ms | +| NFR-PERF-002 | Время отклика API для критических операций | < 200ms | +| NFR-PERF-003 | Прогнозируемое количество пользователей на отель | 20-50 | +| NFR-PERF-004 | Одновременных подключений на отель | до 100 | +| NFR-PERF-005 | Пропускная способность системы | 1000 задач/час на отель | + +### 2.2 Доступность (NFR-AVAIL) + +| ID | Требование | Значение | +|----|------------|----------| +| NFR-AVAIL-001 | Доступность системы (SLA) | 99.5% | +| NFR-AVAIL-002 | Допустимое время простоя в месяц | < 3.6 часа | +| NFR-AVAIL-003 | RTO (Recovery Time Objective) | 1 час | +| NFR-AVAIL-004 | RPO (Recovery Point Objective) | 15 минут | + +### 2.3 Масштабируемость (NFR-SCALE) + +| ID | Требование | Описание | +|----|------------|----------| +| NFR-SCALE-001 | Система должна поддерживать горизонтальное масштабирование сервисов | Микросервисная архитектура | +| NFR-SCALE-002 | Система должна поддерживать добавление новых адаптеров без изменения ядра | Plugin architecture | +| NFR-SCALE-003 | Система должна поддерживать мультитенантность | Несколько отелей на одной инсталляции | + +### 2.4 Безопасность (NFR-SEC) + +| ID | Требование | Описание | +|----|------------|----------| +| NFR-SEC-001 | Все API-запросы должны быть аутентифицированы | JWT/OAuth2 | +| NFR-SEC-002 | Передача данных должна быть зашифрована | HTTPS/TLS 1.3 | +| NFR-SEC-003 | Пароли должны храниться в зашифрованном виде | bcrypt/argon2 | +| NFR-SEC-004 | Система должна вести журнал аудита | audit-service | +| NFR-SEC-005 | Система должна поддерживать RBAC | Ролевая модель доступа | +| NFR-SEC-006 | Система должна защищать от основных OWASP уязвимостей | SQL injection, XSS, CSRF | + +### 2.5 Совместимость (NFR-COMPAT) + +| ID | Требование | Описание | +|----|------------|----------| +| NFR-COMPAT-001 | Веб-интерфейс должен корректно работать в современных браузерах | Chrome, Firefox, Safari, Edge (последние 2 версии) | +| NFR-COMPAT-002 | Веб-интерфейс должен быть адаптивным | Mobile-first design | +| NFR-COMPAT-003 | Мобильное приложение должно поддерживать Android | Android 8.0+ | +| NFR-COMPAT-004 | Мобильное приложение должно поддерживать iOS | iOS 14+ | + +### 2.6 Поддерживаемость (NFR-MAINT) + +| ID | Требование | Описание | +|----|------------|----------| +| NFR-MAINT-001 | Код должен быть покрыт unit-тестами | > 70% coverage | +| NFR-MAINT-002 | Система должна предоставлять метрики для мониторинга | Prometheus-compatible | +| NFR-MAINT-003 | Система должна предоставлять структурированные логи | JSON format | +| NFR-MAINT-004 | Документация API должна быть в формате OpenAPI | Swagger/OpenAPI 3.0 | +| NFR-MAINT-005 | Модульная структура для возможности продажи отдельных модулей | Loosely coupled services | + +### 2.7 Локализация (NFR-L10N) + +| ID | Требование | Описание | +|----|------------|----------| +| NFR-L10N-001 | Интерфейс должен поддерживать русский язык | Primary | +| NFR-L10N-002 | Интерфейс должен поддерживать английский язык | Secondary | +| NFR-L10N-003 | Система должна поддерживать добавление новых языков | i18n ready | + +### 2.8 Инфраструктура (NFR-INFRA) + +| ID | Требование | Технология | +|----|------------|------------| +| NFR-INFRA-001 | База данных | PostgreSQL | +| NFR-INFRA-002 | Кэширование | Redis | +| NFR-INFRA-003 | Файловое хранилище | S3-compatible | +| NFR-INFRA-004 | Очередь сообщений | Apache Kafka | +| NFR-INFRA-005 | Backend-сервисы | Python | +| NFR-INFRA-006 | Web Admin Frontend | TypeScript, React | +| NFR-INFRA-007 | API Gateway | REST API, gRPC, WebSocket | + +### 2.9 Надежность доставки сообщений (NFR-MSG) + +| ID | Требование | Описание | +|----|------------|----------| +| NFR-MSG-001 | Гарантия доставки сообщений | At-least-once delivery | +| NFR-MSG-002 | Сообщения должны сохраняться при недоступности получателя | Kafka persistence | +| NFR-MSG-003 | Система должна поддерживать retry-механизм | Exponential backoff | +| NFR-MSG-004 | Система должна поддерживать dead-letter queue | DLQ для необработанных сообщений | + +--- + +## 3. Глоссарий + +| Термин | Описание | +|--------|----------| +| PMS | Property Management System - система управления отелем | +| Адаптер | Компонент, обеспечивающий интеграцию с внешней системой | +| Событие | Стандартизированное сообщение, передаваемое между системами через Kafka | +| Задача | Единица работы в системе с назначенным исполнителем и статусом | +| Функшн | Документ с описанием мероприятия и задач для служб отеля | +| Хаускипинг | Служба уборки номеров | +| Хаусмен | Сотрудник, отвечающий за перестановку мебели и оборудования | diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..e0f8f41 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,142 @@ +# HotelTask - Дорожная карта + +## Текущий статус: Проектирование + +--- + +## Этап 0: Аналитика +**Статус:** Завершен + +- [x] Собраны бизнес-требования +- [x] Структурированы FR/NFR +- [x] Определены роли пользователей +- [x] Определен scope MVP + +--- + +## Этап 1: Проектирование +**Статус:** В процессе + +- [x] Высокоуровневая архитектура +- [ ] Схема БД (ERD) +- [ ] API контракты (OpenAPI) +- [ ] Модель данных Task + +--- + +## Этап 2: MVP +**Статус:** Ожидает + +### Что входит в MVP: + +**Управление пользователями:** +- Регистрация и авторизация +- Роли: Администратор, Менеджер/Супервайзер, Линейный сотрудник +- Привязка к подразделениям + +**Управление задачами:** +- CRUD операции с задачами +- Все статусы: новая, в работе, ожидает, выполнена, пауза, отменена +- Типы задач, приоритеты, сроки +- Назначение исполнителей + +**Уведомления:** +- Push-уведомления о новых задачах +- Уведомления о завершении задач + +**Комментарии и вложения:** +- Комментарии к задачам +- Прикрепление фото и файлов +- История изменений + +**Поиск и фильтрация:** +- Поиск по названию и описанию +- Фильтры по статусу, приоритету, сотруднику, дате + +**Интерфейсы:** +- Веб-интерфейс (адаптивный) + +**Интеграции:** +- Базовая интеграция с PMS +- Система адаптеров +- Управление связями между системами + +### Разработка MVP: +- [ ] Инфраструктура (Docker, Kafka, PostgreSQL, Redis) +- [ ] tasks-service +- [ ] users-service +- [ ] permissions-service +- [ ] notification-service +- [ ] file-storage-service +- [ ] API Gateway +- [ ] Web Admin +- [ ] PMS Adapter + +--- + +## Этап 3: Расширение функционала +**Статус:** Планируется + +### 3.1 Аудит и аналитика +- audit-service +- Отчет по выполненным задачам за период +- Статистика по сотрудникам +- Статистика по типам задач +- Процент просроченных задач + +### 3.2 Планировщик +- scheduler-service +- Создание регулярных/периодических задач +- Автоматическое создание задач по расписанию + +### 3.3 Трекинг времени +- Время начала и окончания задачи +- Учет времени выполнения + +--- + +## Этап 4: Специализированные модули +**Статус:** Планируется + +### 4.1 Модуль мероприятий (Events Management) +- events-service +- Описание мероприятия +- Автоматическая декомпозиция на задачи +- Массовое создание связанных задач +- Формирование документа "функшн" + +### 4.2 Специализированный интерфейс горничных +- Пошаговый процесс уборки +- Обязательное фото до и после +- Фиксация времени уборки + +### 4.3 Складской модуль +- Учет материалов по службам +- Списание при выполнении задач + +--- + +## Этап 5: Расширение каналов +**Статус:** Планируется + +### 5.1 Мобильные приложения +- Android приложение (8.0+) +- iOS приложение (14+) + +### 5.2 Интерфейс для гостей +- Telegram-бот / веб-приложение +- Базовые услуги с кнопками +- Автоматическое создание задач из запросов + +### 5.3 Голосовой ввод +- Транскрипция голосовых сообщений в текст + +### 5.4 Интеграция с AI +- Обработка свободных текстовых запросов + +--- + +## Что НЕ входит в ближайшие планы: +- Гранулярные права доступа (кастомные permissions) +- Настройка типов уведомлений для пользователя +- Интеграция с Консьерж Resonline diff --git a/Анализ требований.md b/Анализ требований.md deleted file mode 100644 index b4e2534..0000000 --- a/Анализ требований.md +++ /dev/null @@ -1,255 +0,0 @@ -[Назад](/README.md) - -# Анализ требований - -## Приложение: Таск менеджер - -### Потребители: -- Горничные (хаускипинг) -- Техническая (инженерная) служба -- ИТ служба -- Ресторанная служба -- Ресепшен -- Хаусмены -- Менеджеры по продажам - -**Прогнозируемое количество пользователей:** 20-50 на отель - ---- - -### Проблемы и требования: - -#### **Проблема 1: Отсутствие единой системы для передачи задач между подразделениями** - -**AS-IS (как есть):** -- Ресепшен выступает посредником между всеми службами -- Передача задач через звонки и мессенджеры (WhatsApp) -- Информация может теряться, забываться -- Ресепшен перегружен, особенно в часы пик (например, при заезде группы) - -**TO-BE (как должно быть):** -- Автоматизированная система для передачи задач -- Каждое подразделение имеет прямой доступ к системе -- Возможность создать задачу и передать ее напрямую нужному подразделению -- Ресепшен убирается как обязательный источник синхронизации - -**Базовый функционал (MVP):** -- Создание задачи -- Передача задачи нужному подразделению -- Принятие задачи исполнителем -- Отметка о выполнении -- Возможность создать встречную задачу (если требуется) - ---- - -#### **Проблема 2: Невозможность документировать выполнение задач с помощью фото/видео** - -**AS-IS:** -- Фотографии отправляются через мессенджеры (WhatsApp) -- Нет централизованного хранения -- Сложно найти историю выполненных работ - -**TO-BE:** -- Возможность прикрепления фотографий к задаче -- Применимо для всех служб: - - **Горничные:** фото до и после уборки - - **Техническая служба:** фото выполненного ремонта (труба, унитаз и т.д.) - - **ИТ служба:** фото расставленного оборудования -- Возможность показать результат заказчику -- Фиксация состояния объекта - -**Требование:** Возможность прикрепления файлов и фотографий к задачам - ---- - -#### **Проблема 3: Сложность ввода информации в процессе работы** - -**AS-IS:** -- Много времени тратится на набор текста -- Сотрудники вынуждены писать длинные сообщения - -**TO-BE:** -- Голосовой ввод с автоматической транскрипцией в текст -- Ускорение процесса создания и комментирования задач - -**Требование:** Интеграция системы распознавания речи (голосовые сообщения → текст) -**Примечание:** Потребуется использование платных сервисов (западных или отечественных) - ---- - -#### **Проблема 4: Отсутствие автоматизации повторяющихся задач** - -**AS-IS:** -- Регулярные задачи (раз в неделю, месяц) создаются вручную каждый раз - -**TO-BE:** -- Автоматическое создание периодических задач по расписанию -- Применимо для: - - Горничных (регулярная уборка определенных зон) - - Технической службы (плановое обслуживание оборудования) - -**Требование:** Функционал создания регулярных задач с настройкой расписания - ---- - -#### **Проблема 5: Отсутствие учета расходных материалов** - -**AS-IS:** -- Информация о материалах не фиксируется нигде -- Невозможно отследить остатки и планировать закупки -- Не хранится в других системах (в PMS такой информации нет) - -**TO-BE:** -- Складской модуль внутри системы -- Учет материалов по службам: - - **Горничные:** полотенца (разных видов), косметика - - **Техническая служба:** лампочки, расходники -- Первоначальный ввод остатков -- Списание при выполнении задач -- Понимание объемов работы (например, работы прачки) - -**Требование:** Модуль учета материалов -**Примечание:** Это НЕ MVP, но важная часть. Может использоваться не только в Таск менеджере. - ---- - -## Приложение: Модуль управления мероприятиями (Events Management) - -### Потребители: -- Менеджеры по продажам -- Служба хаусменов -- ИТ служба -- Ресторанная служба -- Инженерная служба - ---- - -### Проблемы и требования: - -#### **Проблема 6: Неэффективное управление задачами для мероприятий** - -**AS-IS:** -- Менеджер по продажам вручную составляет "функшн" или "меморандум" (Word документ) -- В документе описываются все задачи для разных служб: - - Застройка зала (расстановка столов, стульев) - - Предоставление оборудования (проектор, экран) - - Организация кофе-брейка - - Перестройка зала -- Документ рассылается службам -- Задачи могут быть упущены или не замечены -- Отсутствует единый контроль выполнения - -**TO-BE:** -- Менеджер описывает мероприятие в системе один раз -- Система автоматически создает задачи для каждой службы -- Автоматическая генерация "функшн" -- Все задачи отслеживаются в единой системе -- Массовое создание связанных задач для разных подразделений - -**Требование:** -- Возможность массового создания задач (bulk task creation) -- Описание мероприятия с автоматической декомпозицией на задачи -- Привязка задач к конференц-залам и времени -- Формирование документа "функшн" на основе введенных данных - -**Примечание:** Функционал, который можно продавать отдельным модулем. Пока не решен полноценно ни одной существующей системой. - ---- - -## Приложение: Горничные (расширенный модуль для Таск менеджера) - -### Потребители: -- Горничные - ---- - -### Проблемы и требования: - -#### **Проблема 7: Отсутствие контроля процесса уборки номеров** - -**AS-IS:** -- Горничная получает распечатку номеров из PMS -- Выполняет уборку -- Сообщает о завершении устно или через мессенджер -- Нет фиксации времени начала/окончания уборки -- Нет фото-подтверждения качества - -**TO-BE:** -- Горничная видит номер в приложении -- Нажимает "Начать уборку" -- Фотографирует номер до уборки -- Выполняет уборку -- Фотографирует номер после уборки -- Отмечает завершение - -**Требование:** Специализированный интерфейс для горничных с пошаговым процессом уборки и обязательным фотографированием - ---- - -## Приложение: Интерфейс для гостей (Guest Interface) - -### Потребители: -- Гости отеля - ---- - -### Проблемы и требования: - -#### **Проблема 8: Перегрузка ресепшена запросами от гостей** - -**AS-IS:** -- Гость звонит на ресепшен с запросом (принести халат, тапочки и т.д.) -- Ресепшен записывает запрос -- Ресепшен создает задачу в Таск менеджере или пишет в WhatsApp -- При большой загрузке (заезд группы): - - Трубки не берутся - - Запросы забываются - - Теряется информация о номере - -**TO-BE:** -- Гость самостоятельно создает запрос через: - - Telegram-бота - - Готовый консьерж-сервис - - Другой интерфейс -- Базовые услуги доступны по кнопкам (принести халат, тапочки и т.д.) -- Возможна интеграция с AI для обработки свободных запросов -- Задача автоматически попадает нужному подразделению -- Ресепшен разгружается - -**Требование:** -- Интерфейс для гостей (бот/веб-приложение) -- Набор базовых услуг с кнопками -- Автоматическое создание задач в Таск менеджере -- Опционально: интеграция с AI для обработки текстовых запросов - -**Примечание:** Может быть интеграцией с существующим консьерж-сервисом, который нужно будет доработать - ---- - -## Общие требования к архитектуре: - -1. **Модульная структура:** Возможность продажи отдельных модулей -2. **Базовый функционал может быть бесплатным:** Freemium-модель для привлечения пользователей -3. **Единая точка доступа:** Все службы работают в одном приложении, а не в разных мессенджерах -4. **Масштабируемость:** Архитектура должна поддерживать добавление новых модулей - ---- - -## Список всех подразделений (требуется уточнить полный список): -- Хаускипинг (горничные) -- Техническая (инженерная) служба -- ИТ служба -- Ресторанная служба -- Ресепшен -- Хаусмены -- Служба консьержа -- Прачечная - ---- - -## Следующие шаги: -1. Уточнить полный список подразделений -2. Детализировать требования для каждого подразделения -3. Определить приоритеты функций (MVP vs расширенный функционал) -4. Создать архитектуру с учетом модульности -5. Получить доступ к тестовой среде существующих систем \ No newline at end of file diff --git a/Архитектура системы TaskManager.md b/Архитектура системы TaskManager.md deleted file mode 100644 index b821b61..0000000 --- a/Архитектура системы TaskManager.md +++ /dev/null @@ -1,1053 +0,0 @@ -[Назад](/README.md) - -# Архитектура системы TaskManager - -## Содержание -1. [Общее описание](#общее-описание) -2. [Архитектурные принципы](#архитектурные-принципы) -3. [Компоненты системы](#компоненты-системы) -4. [Микросервисы](#микросервисы) -5. [Модель данных](#модель-данных) -6. [Коммуникация между сервисами](#коммуникация-между-сервисами) -7. [Контракт сообщений](#контракт-сообщений) -8. [Безопасность и авторизация](#безопасность-и-авторизация) -9. [Масштабирование](#масштабирование) -10. [Технологический стек](#технологический-стек) - ---- - -## Общее описание - -TaskManager - это интеграционная платформа для управления задачами между различными подразделениями отеля и внешними системами. Система выступает в роли мастер-приложения, объединяющего разрозненные системы (PMS, ERP, системы управления уборкой и т.д.) через адаптеры. - -### Ключевые особенности: -- **Мультитенантность**: поддержка нескольких отелей одного владельца (1-50+ отелей) -- **Модульность**: возможность продажи отдельных модулей (базовый функционал, модуль мероприятий, модуль уборки и т.д.) -- **Расширяемость**: простота добавления новых адаптеров для интеграции с внешними системами -- **Гибкость**: настраиваемые роли, статусы задач, правила маршрутизации - ---- - -## Архитектурные принципы - -### 1. Микросервисная архитектура -Система построена на микросервисах, каждый из которых отвечает за свою domain-область. - -### 2. Event-Driven Architecture -Использование Apache Kafka для асинхронной коммуникации и обработки событий. - -### 3. Адаптер-паттерн для интеграций -Каждая внешняя система имеет свой адаптер, который: -- Преобразует данные внешней системы в стандартизированный формат -- Работает как по push, так и по pull модели (в зависимости от возможностей внешней системы) -- Изолирует логику интеграции от бизнес-логики - -### 4. API Gateway -Единая точка входа для клиентских приложений с поддержкой: -- REST API для простых запросов -- gRPC для высокопроизводительной коммуникации -- WebSocket для real-time обновлений - -### 5. CQRS (Command Query Responsibility Segregation) -Разделение операций чтения и записи для повышения производительности. - ---- - -## Компоненты системы - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Client Layer │ -├─────────────────────────────────────────────────────────────────┤ -│ Web Admin │ Mobile Apps │ External Systems │ Telegram Bot│ -└──────┬────────────┬─────────────────┬────────────────┬──────────┘ - │ │ │ │ - └────────────┴─────────────────┴────────────────┘ - │ -┌───────────────────────────┼───────────────────────────────────────┐ -│ API Gateway Layer │ -├───────────────────────────┴───────────────────────────────────────┤ -│ REST API │ gRPC │ WebSocket │ -└───────────────────────────┬───────────────────────────────────────┘ - │ -┌───────────────────────────┼───────────────────────────────────────┐ -│ Service Layer │ -├───────────────────────────┴───────────────────────────────────────┤ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ Tasks │ │ Connections │ │ Users │ │ -│ │ Service │ │ Service │ │ Service │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │Notification │ │ File Storage │ │ Audit │ │ -│ │ Service │ │ Service │ │ Service │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ Scheduler │ │ Permissions │ │ Events │ │ -│ │ Service │ │ Service │ │ Service │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ -└───────────────────────────────────────────────────────────────────┘ - │ -┌───────────────────────────┼───────────────────────────────────────┐ -│ Message Broker (Kafka) │ -├───────────────────────────┴───────────────────────────────────────┤ -│ Topics: tasks.created, tasks.updated, tasks.completed, │ -│ notifications.send, audit.log, etc. │ -└───────────────────────────┬───────────────────────────────────────┘ - │ -┌───────────────────────────┼───────────────────────────────────────┐ -│ Adapter Layer │ -├───────────────────────────┴───────────────────────────────────────┤ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │PMS Adapter │ │ERP Adapter │ │Housekeeping │ │ -│ │ (Opera/...) │ │ │ │ Adapter │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │Telegram Bot │ │ Custom │ │ Custom │ │ -│ │ Adapter │ │ Adapter #N │ │ Adapter #M │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ -└───────────────────────────┬───────────────────────────────────────┘ - │ -┌───────────────────────────┼───────────────────────────────────────┐ -│ Data Layer │ -├───────────────────────────┴───────────────────────────────────────┤ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ PostgreSQL │ │ Redis │ │ S3 │ │ -│ │ (Main DB) │ │ (Cache) │ │ (File Store) │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ -└───────────────────────────────────────────────────────────────────┘ -``` - ---- - -## Микросервисы - -### 1. API Gateway -**Назначение**: Единая точка входа для всех клиентских приложений - -**Ответственность**: -- Маршрутизация запросов к соответствующим микросервисам -- Аутентификация и авторизация -- Rate limiting -- Request/Response трансформация -- Логирование запросов - -**Технологии**: Kong / Envoy / NGINX + gRPC Gateway - -**Endpoints**: -- REST API: `/api/v1/*` -- gRPC: порт 50051 -- WebSocket: `/ws/*` - ---- - -### 2. Tasks Service -**Назначение**: Управление жизненным циклом задач - -**Ответственность**: -- CRUD операции с задачами -- Управление статусами задач (с поддержкой кастомных статусов) -- Управление зависимостями между задачами -- Назначение исполнителей -- Версионирование задач (история изменений) -- Прикрепление файлов к задачам - -**База данных**: PostgreSQL -- Таблицы: `tasks`, `task_statuses`, `task_dependencies`, `task_history`, `task_attachments` - -**Kafka Topics**: -- Публикует: `tasks.created`, `tasks.updated`, `tasks.status_changed`, `tasks.completed`, `tasks.cancelled` -- Подписан на: `scheduler.task_trigger`, `connections.route_task` - -**gRPC Service**: -```protobuf -service TaskService { - rpc CreateTask(CreateTaskRequest) returns (Task); - rpc UpdateTask(UpdateTaskRequest) returns (Task); - rpc GetTask(GetTaskRequest) returns (Task); - rpc ListTasks(ListTasksRequest) returns (ListTasksResponse); - rpc ChangeTaskStatus(ChangeStatusRequest) returns (Task); - rpc AddDependency(AddDependencyRequest) returns (TaskDependency); -} -``` - ---- - -### 3. Connections Service -**Назначение**: Управление связями между системами и правилами маршрутизации - -**Ответственность**: -- Хранение конфигурации связей между адаптерами -- Определение правил маршрутизации сообщений -- Динамическое обновление правил без перезапуска -- Валидация связей - -**База данных**: PostgreSQL -- Таблицы: `connections`, `routing_rules`, `adapters` - -**Модель связи** (направленная): -```json -{ - "id": "uuid", - "source_adapter_id": "uuid", - "target_adapter_id": "uuid", - "routing_rules": [ - { - "condition": "task_type == 'cleaning'", - "action": "route", - "enabled": true - } - ], - "enabled": true, - "created_at": "timestamp", - "updated_at": "timestamp" -} -``` - -**Kafka Topics**: -- Публикует: `connections.updated`, `connections.route_task` -- Подписан на: `tasks.created`, `adapters.message_received` - -**gRPC Service**: -```protobuf -service ConnectionService { - rpc CreateConnection(CreateConnectionRequest) returns (Connection); - rpc UpdateConnection(UpdateConnectionRequest) returns (Connection); - rpc DeleteConnection(DeleteConnectionRequest) returns (Empty); - rpc ListConnections(ListConnectionsRequest) returns (ListConnectionsResponse); - rpc RouteMessage(RouteMessageRequest) returns (RouteMessageResponse); -} -``` - ---- - -### 4. Users Service -**Назначение**: Управление пользователями и их профилями - -**Ответственность**: -- CRUD операции с пользователями -- Управление профилями -- Привязка к отелям и подразделениям -- Хранение настроек пользователя - -**База данных**: PostgreSQL -- Таблицы: `users`, `user_profiles`, `user_hotels`, `departments` - -**Kafka Topics**: -- Публикует: `users.created`, `users.updated`, `users.deleted` - -**gRPC Service**: -```protobuf -service UserService { - rpc CreateUser(CreateUserRequest) returns (User); - rpc GetUser(GetUserRequest) returns (User); - rpc UpdateUser(UpdateUserRequest) returns (User); - rpc ListUsers(ListUsersRequest) returns (ListUsersResponse); -} -``` - ---- - -### 5. Permissions Service -**Назначение**: Управление ролями и правами доступа (RBAC) - -**Ответственность**: -- Управление ролями (с поддержкой кастомных ролей на уровне отеля) -- Управление правами доступа -- Проверка прав доступа -- Привязка пользователей к ролям - -**База данных**: PostgreSQL -- Таблицы: `roles`, `permissions`, `role_permissions`, `user_roles` - -**Предопределенные роли**: -- `system_admin` - системный администратор -- `support` - техническая поддержка -- `hotel_admin` - администратор отеля -- `department_head` - руководитель подразделения -- `worker` - сотрудник - -**Кастомные роли**: отель может создавать свои роли на основе базовых - -**gRPC Service**: -```protobuf -service PermissionService { - rpc CreateRole(CreateRoleRequest) returns (Role); - rpc AssignRole(AssignRoleRequest) returns (UserRole); - rpc CheckPermission(CheckPermissionRequest) returns (PermissionResponse); - rpc ListRoles(ListRolesRequest) returns (ListRolesResponse); -} -``` - ---- - -### 6. Notification Service -**Назначение**: Отправка уведомлений через различные каналы - -**Ответственность**: -- Отправка Email -- Отправка Push-уведомлений -- Отправка SMS -- Отправка сообщений в Telegram -- Отправка сообщений в другие мессенджеры (WhatsApp, Viber и т.д.) -- Управление шаблонами уведомлений -- Управление подписками пользователей - -**База данных**: PostgreSQL -- Таблицы: `notification_templates`, `notification_subscriptions`, `notification_log` - -**Kafka Topics**: -- Подписан на: `notifications.send`, `tasks.created`, `tasks.assigned`, `tasks.completed` - -**Интеграции**: -- Email: SMTP -- Push: Firebase Cloud Messaging (FCM) / Apple Push Notification Service (APNS) -- SMS: Twilio / другие провайдеры -- Telegram: Telegram Bot API -- WhatsApp: WhatsApp Business API - -**gRPC Service**: -```protobuf -service NotificationService { - rpc SendNotification(SendNotificationRequest) returns (NotificationResponse); - rpc CreateTemplate(CreateTemplateRequest) returns (Template); - rpc Subscribe(SubscribeRequest) returns (Subscription); -} -``` - ---- - -### 7. File Storage Service -**Назначение**: Управление файлами и изображениями - -**Ответственность**: -- Загрузка файлов в S3 -- Генерация временных ссылок для скачивания -- Управление метаданными файлов -- Оптимизация изображений (resize, compress) -- Удаление файлов - -**Хранилище**: AWS S3 / MinIO (S3-compatible) - -**База данных**: PostgreSQL -- Таблицы: `files`, `file_metadata` - -**REST API**: -- `POST /api/v1/files/upload` - загрузка файла -- `GET /api/v1/files/{id}` - получение метаданных -- `GET /api/v1/files/{id}/download` - генерация signed URL -- `DELETE /api/v1/files/{id}` - удаление файла - ---- - -### 8. Audit Service -**Назначение**: Логирование всех действий в системе - -**Ответственность**: -- Запись всех изменений в системе -- Хранение истории действий пользователей -- Предоставление API для просмотра логов -- Ретеншн политика (удаление старых логов) - -**База данных**: PostgreSQL (с партиционированием по дате) -- Таблицы: `audit_log` (партиционирована) - -**Kafka Topics**: -- Подписан на: `*.created`, `*.updated`, `*.deleted`, `tasks.*`, `users.*` - -**Модель лога**: -```json -{ - "id": "uuid", - "timestamp": "2025-12-13T10:00:00Z", - "user_id": "uuid", - "hotel_id": "uuid", - "action": "task.created", - "entity_type": "task", - "entity_id": "uuid", - "changes": { - "before": {}, - "after": {} - }, - "ip_address": "192.168.1.1", - "user_agent": "Mozilla/5.0..." -} -``` - -**gRPC Service**: -```protobuf -service AuditService { - rpc LogAction(LogActionRequest) returns (Empty); - rpc GetAuditLog(GetAuditLogRequest) returns (GetAuditLogResponse); -} -``` - ---- - -### 9. Scheduler Service -**Назначение**: Управление периодическими задачами - -**Ответственность**: -- Создание расписаний для задач (cron-подобный синтаксис) -- Триггеринг создания задач по расписанию -- Управление повторяющимися задачами - -**База данных**: PostgreSQL -- Таблицы: `schedules`, `schedule_executions` - -**Модель расписания**: -```json -{ - "id": "uuid", - "name": "Уборка холла каждый день в 8:00", - "cron_expression": "0 8 * * *", - "task_template": { - "title": "Уборка холла", - "description": "Провести уборку холла", - "task_type": "cleaning", - "assignee_id": "uuid" - }, - "enabled": true, - "timezone": "Europe/Moscow", - "next_run": "2025-12-14T08:00:00Z" -} -``` - -**Kafka Topics**: -- Публикует: `scheduler.task_trigger` - -**gRPC Service**: -```protobuf -service SchedulerService { - rpc CreateSchedule(CreateScheduleRequest) returns (Schedule); - rpc UpdateSchedule(UpdateScheduleRequest) returns (Schedule); - rpc DeleteSchedule(DeleteScheduleRequest) returns (Empty); - rpc ListSchedules(ListSchedulesRequest) returns (ListSchedulesResponse); -} -``` - ---- - -### 10. Events Service -**Назначение**: Управление мероприятиями (модуль Events Management) - -**Ответственность**: -- Создание мероприятий -- Автоматическая генерация задач для разных подразделений -- Генерация документа "функшн" -- Управление конференц-залами и ресурсами - -**База данных**: PostgreSQL -- Таблицы: `events`, `event_tasks`, `conference_rooms`, `event_resources` - -**Модель мероприятия**: -```json -{ - "id": "uuid", - "title": "Конференция по маркетингу", - "description": "Описание мероприятия", - "start_time": "2025-12-20T10:00:00Z", - "end_time": "2025-12-20T18:00:00Z", - "conference_room_id": "uuid", - "tasks": [ - { - "department": "housemen", - "title": "Расставить 50 стульев и 10 столов", - "due_before": "2025-12-20T09:00:00Z" - }, - { - "department": "it", - "title": "Подготовить проектор и экран", - "due_before": "2025-12-20T09:30:00Z" - }, - { - "department": "restaurant", - "title": "Организовать кофе-брейк на 50 человек", - "due_before": "2025-12-20T12:00:00Z" - } - ] -} -``` - -**Kafka Topics**: -- Публикует: `events.created`, `events.task_generated` - -**gRPC Service**: -```protobuf -service EventService { - rpc CreateEvent(CreateEventRequest) returns (Event); - rpc UpdateEvent(UpdateEventRequest) returns (Event); - rpc GenerateTasks(GenerateTasksRequest) returns (GenerateTasksResponse); - rpc GenerateFunction(GenerateFunctionRequest) returns (FunctionDocument); -} -``` - ---- - -## Adapter Layer (Адаптеры) - -### Общая архитектура адаптера - -Каждый адаптер - это отдельный микросервис, который: -1. Подключается к внешней системе (API, БД, Webhook endpoint) -2. Слушает Kafka топики для исходящих сообщений -3. Преобразует данные в/из стандартизированного формата -4. Публикует входящие сообщения в Kafka - -**Базовая структура адаптера**: -``` -adapter/ -├── connector/ # Логика подключения к внешней системе -│ ├── api_client.py # REST/SOAP/GraphQL клиент -│ ├── db_client.py # Прямое подключение к БД (если требуется) -│ └── webhook.py # Обработчик входящих webhook'ов -├── transformer/ # Преобразование данных -│ ├── inbound.py # Внешний формат -> Стандартный формат -│ └── outbound.py # Стандартный формат -> Внешний формат -├── kafka/ -│ ├── consumer.py # Обработка исходящих сообщений -│ └── producer.py # Публикация входящих сообщений -└── config.py # Конфигурация адаптера -``` - -### Примеры адаптеров - -#### 1. PMS Adapter (например, Opera) -**Функции**: -- Получение информации о бронированиях -- Создание задач на основе заездов/выездов -- Обновление статуса номеров - -**Режим работы**: Pull (опрос API) + Push (Webhook для событий) - -**Kafka Topics**: -- Публикует: `adapters.pms.reservation_created`, `adapters.pms.checkout` -- Подписан на: `tasks.room_ready`, `tasks.room_cleaned` - ---- - -#### 2. Housekeeping Adapter -**Функции**: -- Получение задач на уборку номеров -- Отправка статусов выполнения уборки -- Загрузка фото до/после уборки - -**Режим работы**: Push (мобильное приложение отправляет данные) - -**Kafka Topics**: -- Публикует: `adapters.housekeeping.task_started`, `adapters.housekeeping.task_completed` -- Подписан на: `tasks.cleaning_assigned` - ---- - -#### 3. Telegram Bot Adapter -**Функции**: -- Прием запросов от гостей через Telegram -- Отправка уведомлений сотрудникам -- Интерактивные кнопки для частых запросов - -**Режим работы**: Push (Telegram Webhook) - -**Kafka Topics**: -- Публикует: `adapters.telegram.guest_request` -- Подписан на: `notifications.send`, `tasks.assigned` - ---- - -## Модель данных - -### Основные сущности - -#### 1. Hotels (Отели) -```sql -CREATE TABLE hotels ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - name VARCHAR(255) NOT NULL, - address TEXT, - owner_id UUID NOT NULL, -- один владелец, несколько отелей - settings JSONB DEFAULT '{}', - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW() -); -``` - -#### 2. Departments (Подразделения) -```sql -CREATE TABLE departments ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - hotel_id UUID REFERENCES hotels(id), - name VARCHAR(255) NOT NULL, - type VARCHAR(50), -- housekeeping, technical, it, restaurant, etc. - created_at TIMESTAMP DEFAULT NOW() -); -``` - -#### 3. Users (Пользователи) -```sql -CREATE TABLE users ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - email VARCHAR(255) UNIQUE NOT NULL, - phone VARCHAR(50), - first_name VARCHAR(100), - last_name VARCHAR(100), - password_hash VARCHAR(255), - is_active BOOLEAN DEFAULT TRUE, - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW() -); - -CREATE TABLE user_hotels ( - user_id UUID REFERENCES users(id), - hotel_id UUID REFERENCES hotels(id), - department_id UUID REFERENCES departments(id), - PRIMARY KEY (user_id, hotel_id) -); -``` - -#### 4. Tasks (Задачи) -```sql -CREATE TABLE tasks ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - hotel_id UUID REFERENCES hotels(id), - title VARCHAR(500) NOT NULL, - description TEXT, - task_type VARCHAR(100), -- cleaning, maintenance, delivery, etc. - priority VARCHAR(20) DEFAULT 'normal', -- low, normal, high, urgent - status_id UUID REFERENCES task_statuses(id), - - -- Исполнители - creator_id UUID REFERENCES users(id), - assignee_id UUID REFERENCES users(id), - department_id UUID REFERENCES departments(id), - - -- Временные метки - due_date TIMESTAMP, - started_at TIMESTAMP, - completed_at TIMESTAMP, - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW(), - - -- Мета-информация - metadata JSONB DEFAULT '{}', -- для хранения дополнительных полей - source_system VARCHAR(100), -- откуда пришла задача - external_id VARCHAR(255) -- ID во внешней системе -); - -CREATE INDEX idx_tasks_assignee ON tasks(assignee_id); -CREATE INDEX idx_tasks_hotel ON tasks(hotel_id); -CREATE INDEX idx_tasks_status ON tasks(status_id); -CREATE INDEX idx_tasks_created ON tasks(created_at); -``` - -#### 5. Task Statuses (Статусы задач) -```sql -CREATE TABLE task_statuses ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - hotel_id UUID REFERENCES hotels(id), -- NULL для глобальных статусов - name VARCHAR(100) NOT NULL, - code VARCHAR(50) NOT NULL, -- created, assigned, in_progress, completed, cancelled, rejected - is_final BOOLEAN DEFAULT FALSE, -- финальный статус (completed, cancelled) - color VARCHAR(7), -- HEX цвет для UI - order_index INT, -- порядок отображения - is_custom BOOLEAN DEFAULT FALSE, -- кастомный статус отеля - created_at TIMESTAMP DEFAULT NOW() -); - --- Предопределенные статусы -INSERT INTO task_statuses (name, code, is_final, order_index) VALUES - ('Создана', 'created', FALSE, 1), - ('Назначена', 'assigned', FALSE, 2), - ('В работе', 'in_progress', FALSE, 3), - ('Выполнена', 'completed', TRUE, 4), - ('Отменена', 'cancelled', TRUE, 5), - ('Отклонена', 'rejected', TRUE, 6); -``` - -#### 6. Task Dependencies (Зависимости задач) -```sql -CREATE TABLE task_dependencies ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - task_id UUID REFERENCES tasks(id) ON DELETE CASCADE, - depends_on_task_id UUID REFERENCES tasks(id) ON DELETE CASCADE, - dependency_type VARCHAR(50) DEFAULT 'finish_to_start', -- finish_to_start, start_to_start - created_at TIMESTAMP DEFAULT NOW(), - UNIQUE(task_id, depends_on_task_id) -); -``` - -#### 7. Task History (История изменений) -```sql -CREATE TABLE task_history ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - task_id UUID REFERENCES tasks(id) ON DELETE CASCADE, - user_id UUID REFERENCES users(id), - action VARCHAR(100), -- created, status_changed, assigned, updated - changes JSONB, -- {"field": "status", "old": "created", "new": "in_progress"} - created_at TIMESTAMP DEFAULT NOW() -); - -CREATE INDEX idx_task_history_task ON task_history(task_id, created_at DESC); -``` - -#### 8. Task Attachments (Вложения) -```sql -CREATE TABLE task_attachments ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - task_id UUID REFERENCES tasks(id) ON DELETE CASCADE, - file_id UUID REFERENCES files(id), - attachment_type VARCHAR(50), -- photo_before, photo_after, document, voice - uploaded_by UUID REFERENCES users(id), - created_at TIMESTAMP DEFAULT NOW() -); -``` - -#### 9. Files (Файлы) -```sql -CREATE TABLE files ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - filename VARCHAR(500), - file_size BIGINT, - mime_type VARCHAR(100), - s3_bucket VARCHAR(255), - s3_key VARCHAR(500), - uploaded_by UUID REFERENCES users(id), - created_at TIMESTAMP DEFAULT NOW() -); -``` - -#### 10. Connections (Связи между адаптерами) -```sql -CREATE TABLE adapters ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - name VARCHAR(255) NOT NULL, - type VARCHAR(100), -- pms, erp, housekeeping, telegram, custom - config JSONB, -- конфигурация подключения - is_active BOOLEAN DEFAULT TRUE, - created_at TIMESTAMP DEFAULT NOW() -); - -CREATE TABLE connections ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - source_adapter_id UUID REFERENCES adapters(id), - target_adapter_id UUID REFERENCES adapters(id), - routing_rules JSONB DEFAULT '[]', -- массив правил маршрутизации - is_enabled BOOLEAN DEFAULT TRUE, - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW() -); -``` - -#### 11. Schedules (Расписания) -```sql -CREATE TABLE schedules ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - hotel_id UUID REFERENCES hotels(id), - name VARCHAR(255), - cron_expression VARCHAR(100), -- "0 8 * * *" - task_template JSONB, -- шаблон задачи для создания - timezone VARCHAR(50) DEFAULT 'UTC', - is_enabled BOOLEAN DEFAULT TRUE, - next_run TIMESTAMP, - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW() -); - -CREATE TABLE schedule_executions ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - schedule_id UUID REFERENCES schedules(id), - executed_at TIMESTAMP DEFAULT NOW(), - task_id UUID REFERENCES tasks(id), -- созданная задача - status VARCHAR(50) -- success, failed -); -``` - -#### 12. Roles & Permissions -```sql -CREATE TABLE roles ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - hotel_id UUID REFERENCES hotels(id), -- NULL для глобальных ролей - name VARCHAR(100) NOT NULL, - code VARCHAR(50), -- system_admin, support, hotel_admin, etc. - is_custom BOOLEAN DEFAULT FALSE, - created_at TIMESTAMP DEFAULT NOW() -); - -CREATE TABLE permissions ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - resource VARCHAR(100), -- tasks, users, connections, etc. - action VARCHAR(50), -- create, read, update, delete - description TEXT -); - -CREATE TABLE role_permissions ( - role_id UUID REFERENCES roles(id), - permission_id UUID REFERENCES permissions(id), - PRIMARY KEY (role_id, permission_id) -); - -CREATE TABLE user_roles ( - user_id UUID REFERENCES users(id), - role_id UUID REFERENCES roles(id), - hotel_id UUID REFERENCES hotels(id), -- в контексте какого отеля - PRIMARY KEY (user_id, role_id, hotel_id) -); -``` - ---- - -## Коммуникация между сервисами - -### 1. Синхронная коммуникация (gRPC) -Используется для: -- Запросы на чтение (GET операции) -- Операции требующие немедленного ответа -- Проверка прав доступа - -**Примеры**: -- API Gateway → Tasks Service: получение списка задач -- API Gateway → Users Service: получение профиля пользователя -- Tasks Service → Permissions Service: проверка прав доступа - -### 2. Асинхронная коммуникация (Kafka) -Используется для: -- Операции записи (создание, обновление) -- Распространение событий -- Интеграция между сервисами - -**Структура Kafka топиков**: -``` -tasks.created # Создана новая задача -tasks.updated # Задача обновлена -tasks.status_changed # Изменен статус задачи -tasks.assigned # Задача назначена -tasks.completed # Задача выполнена - -users.created -users.updated -users.deleted - -connections.updated # Обновлены связи -connections.route_task # Маршрутизация задачи - -notifications.send # Отправить уведомление - -scheduler.task_trigger # Триггер для создания задачи по расписанию - -adapters.*.message # Сообщения от адаптеров (подстановочные топики) - -audit.* # Все события для аудита -``` - -### 3. REST API (для внешних клиентов) -Используется для: -- Web админка -- Мобильные приложения (если gRPC не поддерживается) -- Webhook endpoints для адаптеров - ---- - -## Контракт сообщений - -### Стандартизированное сообщение (Kafka Event) - -```json -{ - "event_id": "uuid", - "event_type": "task.created", - "timestamp": "2025-12-13T10:00:00Z", - "version": "1.0", - - "source": { - "service": "tasks-service", - "adapter_id": "uuid", - "system": "pms_opera" - }, - - "target": { - "adapter_id": "uuid", - "system": "housekeeping_app" - }, - - "payload": { - "task": { - "id": "uuid", - "hotel_id": "uuid", - "title": "Уборка номера 305", - "description": "Гость выехал, требуется полная уборка", - "task_type": "cleaning", - "priority": "normal", - "status": "created", - - "assignee": { - "id": "uuid", - "name": "Иванова Мария", - "department": "housekeeping" - }, - - "metadata": { - "room_number": "305", - "checkout_time": "2025-12-13T12:00:00Z", - "guest_name": "Петров А.А.", - "special_requirements": [] - }, - - "due_date": "2025-12-13T14:00:00Z", - "created_at": "2025-12-13T10:00:00Z" - } - }, - - "correlation_id": "uuid", // для трейсинга - "causation_id": "uuid" // ID события, которое вызвало это событие -} -``` - -### Стандартизированное сообщение для адаптеров - -Адаптеры преобразуют внешний формат в этот контракт: - -```json -{ - "message_id": "uuid", - "message_type": "task_create_request", - "timestamp": "2025-12-13T10:00:00Z", - - "source_system": "pms_opera", - "target_system": "taskmanager", - - "hotel_id": "uuid", - - "data": { - "task": { - // стандартные поля задачи - } - }, - - "external_reference": { - "system": "pms_opera", - "id": "OPERA-12345", - "type": "reservation" - } -} -``` - ---- - -## Безопасность и авторизация - -### 1. Аутентификация -- **JWT токены** для API Gateway -- **mTLS** для межсервисной коммуникации (gRPC) -- **API Keys** для внешних систем (адаптеры) - -### 2. Авторизация (RBAC) -Проверка прав на уровне: -- API Gateway (базовая проверка роли) -- Каждый сервис (детальная проверка permissions) - -**Формат JWT токена**: -```json -{ - "sub": "user_id", - "email": "user@example.com", - "hotels": ["hotel_id_1", "hotel_id_2"], - "roles": [ - { - "hotel_id": "hotel_id_1", - "role": "hotel_admin" - } - ], - "exp": 1234567890 -} -``` - -### 3. Изоляция данных -- Все запросы фильтруются по `hotel_id` на уровне БД -- Row Level Security (RLS) в PostgreSQL -- Пользователи видят только данные отелей, к которым у них есть доступ - ---- - -## Масштабирование - -### 1. Horizontal Scaling -- Все сервисы stateless и могут масштабироваться горизонтально -- Kubernetes HPA (Horizontal Pod Autoscaler) на основе CPU/Memory - -### 2. Database Scaling -- **Read Replicas** для PostgreSQL -- **Connection Pooling** (PgBouncer) -- **Партиционирование** для больших таблиц (audit_log, task_history) - -### 3. Kafka Scaling -- Партиционирование топиков по `hotel_id` -- Consumer Groups для параллельной обработки - -### 4. Caching -- **Redis** для кэширования: - - Данных пользователей - - Разрешений (permissions) - - Конфигурации связей (connections) - - Списков задач - ---- - -## Технологический стек - -### Backend Services -- **Язык**: Python 3.11+ -- **Фреймворк**: FastAPI (для REST) + gRPC -- **ORM**: SQLAlchemy -- **Миграции БД**: Alembic - -### Message Broker -- **Apache Kafka** (одиночный инстанс для MVP) - -### Databases -- **PostgreSQL 15+** (основная БД) -- **Redis 7+** (кэш, сессии) - -### File Storage -- **AWS S3** / MinIO (S3-compatible) - -### API Gateway -- **Kong** / Envoy / NGINX + gRPC Gateway - -### Frontend -- **Framework**: React 18+ с TypeScript -- **UI Library**: Material-UI / Ant Design -- **State Management**: Redux Toolkit / Zustand -- **API Client**: gRPC-Web - -### Infrastructure -- **Containerization**: Docker -- **Orchestration**: Kubernetes -- **CI/CD**: GitLab CI / GitHub Actions -- **Monitoring**: Prometheus + Grafana -- **Logging**: ELK Stack (Elasticsearch, Logstash, Kibana) / Loki -- **Tracing**: Jaeger / OpenTelemetry - -### Development Tools -- **API Documentation**: OpenAPI (Swagger) для REST, Buf для gRPC -- **Code Quality**: Ruff, Black, MyPy -- **Testing**: Pytest, pytest-asyncio - ---- - -## Следующие шаги - -1. Детальная проработка gRPC контрактов (.proto файлы) -2. Проектирование REST API спецификации (OpenAPI) -3. Разработка примера адаптера (PMS Adapter) -4. Проектирование UI/UX для Web админки -5. Настройка CI/CD pipeline -6. Разработка Docker Compose для локальной разработки -7. Kubernetes манифесты для деплоя - diff --git a/Архитектурный скетч.drawio b/Архитектурный скетч.drawio deleted file mode 100644 index 5f01b2d..0000000 --- a/Архитектурный скетч.drawio +++ /dev/null @@ -1,240 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/Вопросы по архитектуре.md b/Вопросы по архитектуре.md deleted file mode 100644 index 1b53dc6..0000000 --- a/Вопросы по архитектуре.md +++ /dev/null @@ -1,117 +0,0 @@ -[Назад](/README.md) - -# Вопросы по архитектуре TaskManager - -## 1. Стандартизация сообщений -- Какие ключевые поля должны быть в стандартизированном сообщении? - - Например: task_id, source_system, target_system, task_type, priority, description, attachments, due_date -- Нужна ли поддержка разных типов задач (одноразовые, периодические, срочные)? - -**Ответ:** -1. Пока не думал над контрактом, тк это уже детали. Наверно общие поля стоит указать, как минимум для примера. Но контракт точно поменяется, многое будет зависить от выбора решений. -2. Задачи точно будут одноразовые и периодические - - ---- - -## 2. Connections-service -- Связи между системами должны быть двусторонними или направленными? -- Нужна ли поддержка правил маршрутизации (например, "все задачи типа 'уборка' из System_1 идут в System_2")? -- Должны ли связи настраиваться динамически через админку без перезапуска сервисов? - -**Ответ:** -1. Сложно сказать, наверное правильнее строить односторонние связи. В случае если нам нужна двусторонняя связь, то мы сперва деляем связь от системы 1 к системе 2, а потом отдельную связь от системы 2 к системе 1. Думаю так будет гибче? -2. Какие то правила наверняка потребуются в будующем, стоит заложится под это, но пока не понятно как это будет -3. Да связи настраиваются динамически через админку и без перезапуска. - - ---- - -## 3. Адаптеры -- Какие типы внешних систем предполагаются для первых адаптеров? (PMS системы, ERP, существующие task-менеджеры?) -- Адаптеры должны работать по push-модели (отправляют сами) или pull-модели (периодически опрашивают внешние системы)? -- Нужна ли поддержка WebHooks для интеграций? - -**Ответ:** -1. PMS, ERP, управление уборщицами -2. Суть адаптера в том, что он адаптер. Системы бывают очень разные, гдето есть api, гдето надо будет самому пойти в базу, гдето нужно опрашивать систему, гдето система сама будет отправлять данные. Вообщем каждый адаптер будет уникален, но его задача адаптировать сообщения от\из системы в нашу -3. Пока сложно сказать, не понятно применение, какие у тебя идеи? - - ---- - -## 4. Tasks-service -- Какие основные статусы задачи? (created, assigned, in_progress, completed, cancelled, rejected?) -- Нужна ли поддержка подзадач и зависимостей между задачами? -- Нужно ли версионирование задач (история изменений)? - -**Ответ:** -1. Пока да, но вероятно пользователь захочет созхдавать "свои" статусы. Поэтому вероятно стоит заложится что в MVP делаем стандартынй набор, а потом чтобы смогли поддержать гибкость -2. Между задачами точно появятся зависимости. На счет подзадач не уверен, пока откажемся от них -3. История изменений нужна - - ---- - -## 5. Безопасность и разграничение доступа -- Будет ли мультитенантность (несколько отелей в одной инсталляции)? -- Какие основные роли предполагаются? (admin, manager, department_head, worker?) -- Нужна ли изоляция данных между отелями? - -**Ответ:** -1. Да отелей у компании может быть несколько -2. админ, техподдержка, и по ролям дальше, все виды сотрудников. скорее всего тоже надо делать настраиваемым, чтобы можно было для отелей настроить свои роли, вдруг там уникальные какието названия -3. Скорее всего нет, так как тот же маркетинг один на всю сетку отелей. Мы все же говорим что отелей несколько, но владелец один. Тоесть между отелями разных владельцев связей не будет! - - ---- - -## 6. Масштабирование -- Сколько отелей планируется поддерживать в одной инсталляции? -- Какой объем сообщений в день ожидается (примерно)? -- Kafka будет в одном экземпляре или нужен кластер? - -**Ответ:** -1. Может быть разное, от 1 до 50 (а может и больше) -2. Пока не известно, будем проводить НТ после разработки MVP -3. Пока предполагаем одну, кажется должно хватить. Разграничивать сообщения топиками. - - ---- - -## 7. Дополнительные сервисы -- **File Storage Service** - где хранить фото/файлы? (S3-compatible, локально, CDN?) -- **Notification Service** - нужны ли уведомления? (email, push, SMS?) -- **Audit Service** - нужен ли отдельный сервис для аудита действий? -- **Scheduler Service** - для периодических задач нужен отдельный сервис? - -**Ответ:** -1. s3 -2. уведомления нужны: email, push, sms, telegram, max и любые другие месенджеры -3. да аудит нужен -4. scheduler тоже нужен - - ---- - -## 8. Технологический стек -- Python сервисы - какой фреймворк? (FastAPI, Django, Flask?) -- Нужна ли REST API Gateway перед всеми сервисами? -- GraphQL рассматривается или только REST? -- Контейнеризация (Docker) + оркестрация (Kubernetes, Docker Compose)? - -**Ответ:** -1. Пока не понятно. Это уже детали -2. Rest api нужно для веба. Но еще для веба нужно получать информацию и от сервера. Поэтому вероятно лучше сразу смотреть в grpc + может rest оставить для каких то отдельных запросов -3. Да, скорее всего кластер кубер. Сервисы по контейнерам с возможностью масштабирования подов - - ---- - -## 9. Дополнительные вопросы от вас -Есть ли у вас дополнительные требования или ограничения, которые нужно учесть при проектировании? - -**Ответ:** -1. Пока наверно все рассказал - - diff --git a/Вопросы.md b/Вопросы.md deleted file mode 100644 index 17c382c..0000000 --- a/Вопросы.md +++ /dev/null @@ -1,27 +0,0 @@ -[Назад](/README.md) - -## Вопросы: - -1. Список всех потребителей приложения Task Manager. Кто потенциально может им начать пользоваться? - -##### Текущий список: -- Хаускипинг (горничные) -- Техническая (инженерная) служба -- ИТ служба -- Ресторанная служба -- Ресепшен -- Хаусмены -- Служба консьержа -- Прачечная - - -2. Какие проблемы для каждого подразделения закрывает Task Manager? - -##### Общие: -- Передача задач от подразделения к подразделению - -##### Хаускипинг (горничные) -- ??? - -##### ??? -- ??? \ No newline at end of file diff --git a/Проблемы.md b/Проблемы.md deleted file mode 100644 index 0ccdb17..0000000 --- a/Проблемы.md +++ /dev/null @@ -1,12 +0,0 @@ -[Назад](/README.md) - -# Список проблем - -1. Отсутствие единой системы для передачи задач между подразделениями -2. Невозможность документировать выполнение задач с помощью фото/видео -3. Сложность ввода информации в процессе работы -4. Отсутствие автоматизации повторяющихся задач -5. Отсутствие учета расходных материалов -6. Неэффективное управление задачами для мероприятий -7. Отсутствие контроля процесса уборки номеров -8. Перегрузка ресепшена запросами от гостей diff --git a/Скетч.svg b/Скетч.svg deleted file mode 100644 index b6d5425..0000000 --- a/Скетч.svg +++ /dev/null @@ -1 +0,0 @@ -
Message Broker
[Container: Apache Kafka]

Очередь сообщений
Message Broker...
connections-service
[Service: Python]

Управляет связями между адаптерами системы
connections-service...
PMS Adapter
[Service: Python]

Адаптер передачи сообщений в систему
PMS Adapter...
Custom Adapter #N
[Service: Python]

Адаптер передачи сообщений в систему
Custom Adapter #N...
PMS
[Software System]

PMS...
ERP
[Software System]

ERP...
Housekeeper
[Software System]

Housekeeper...
tasks-service
[Service: Python]

Управляет всеми тасками системы
tasks-service...
БД
[Container: Postgress]

Сохранение данных системы
БД[Container: Postgress]...
Web admin
[Container: Typescript, React]

Админка для управления системой
Web admin...
Service Layer
[Layer]
Service Layer...
Mobile Apps
[Container: ?]

Отдельные приложения для работников
Mobile Apps...
Telegram Bot
[Container: ?]

Бот для управления системой
Telegram Bot...
Client Layer
[Layer]
Client Layer...
API Gateway Layer
[Layer]
API Gateway Layer...
REST API
[Service: ?]

REST API...
gRPC
[Service: ?]

gRPC...
WebSocket
[Service: ?]

WebSocket...
users-service
[Service: Python]

Управление пользователями системы
users-service...
notification-service
[Service: Python]

Управление уведомлениями системы
notification-service...
file-storage-service
[Service: Python]

Управление файлами системы
file-storage-service...
audit-service
[Service: Python]

Аудит действий пользователя
audit-service...
scheduler-service
[Service: Python]

Создание задач по расписанию
scheduler-service...
permissions-service
[Service: Python]

Управление правами доступа пользователей
permissions-service...
events-service
[Service: Python]

Управление мероприятиями
events-service...
Adapter Layer
[Layer]
Adapter Layer...
ERP Adapter
[Service: Python]

Адаптер передачи сообщений в систему
ERP Adapter...
Housekeeping Adapter
[Service: Python]

Адаптер передачи сообщений в систему
Housekeeping Adapter...
Telegram Bot Adapter
[Service: Python]

Адаптер передачи сообщений в систему
Telegram Bot Adapter...
Data Layer
[Layer]
Data Layer...
Cache
[Container: Redis]

Сохранение данных системы
Cache...
File Storage
[Container: S3]

Сохранение данных системы
File Storage...
External System
[Layer]
External System...
e.g. Makes API calls
[e.g. JSON/HTTP]
e.g. Makes API calls...Text is not SVG - cannot display \ No newline at end of file