SkyForces
5.7 KiB
ADR-001: разделение приложения на сайт, Telegram-бот и базу данных
Статус: Принято
Дата: 2026-07-23
Контекст
Приложение включает страницу привязки пользователя Битрикс24, Telegram-интерфейс менеджера и хранилище интеграционных данных. HTTP-сайт обрабатывает короткие входящие запросы, тогда как Telegram-бот выполняет длительный polling и параллельные REST-операции.
Решение
Архитектура разделена на три основные структурные единицы: сайт привязки, Telegram-бот и база данных, которая обслуживает остальные компоненты. Зона ответственности каждого модуля определена отдельно. Сайт и бот не делят общий код, а их права на уровне базы данных ограничены.
HTTP-приложение site обслуживает только инициацию привязки и взаимодействует с
REST API и OAuth Битрикс24. Telegram-приложение bot обрабатывает команды
менеджера и взаимодействует как с REST API и OAuth Битрикс24, так и с Telegram
Bot API. PostgreSQL предоставляет обоим процессам устойчивый версионированный
контракт в виде SECURITY DEFINER-функций и поддерживает применение миграций.
Программное решение регистрируется администратором портала как локальное
приложение с указанием ссылки на страницу привязки. Локальное приложение
отправляет на HTTPS-адрес /bitrix/bind идентификационные данные пользователя и
refresh-токен. Сайт обменивает его на новую пару OAuth-токенов, извлекает
доверенные member_id, user_id и client_endpoint из ответа Битрикс24,
проверяет пользователя методом user.current и только после этого выпускает
одноразовую ссылку Telegram.
Рисунок ADR-001/1. UML-диаграмма компонентов программного решения
На схеме также обозначен сервис migrate. Он не является постоянно запущенным
модулем, но отвечает за миграции схемы БД. При перезапуске Docker Compose сервис
последовательно выполняет необходимые SQL-скрипты. Сайт имеет право выполнять
только функцию выпуска ссылки binding.issue_v1. Бот погашает ссылку, получает
привязку и обращается к OAuth-функциям. Прямые операции SELECT, INSERT и
UPDATE над таблицами для ролей приложений запрещены, поэтому граница базы
данных одновременно является границей доступа.
| Компонент | Ответственность | Внешний интерфейс |
|---|---|---|
| nginx | Завершение TLS и проксирование только к сайту | HTTPS → 127.0.0.1:8000 |
| apps.site | OAuth-проверка пользователя и выпуск одноразовой ссылки | POST /bitrix/bind, GET /health |
| apps.bot | Команды Telegram, карточки и операции со сделками | Telegram Bot API, Битрикс REST |
| PostgreSQL | Привязки, токены, транзакционная синхронизация | binding.* и oauth.* |
| migrate | Однократное применение SQL-миграций до старта приложений | db/migrations/*.sql |
| Битрикс24 | Источник CRM-данных и OAuth-контекста | oauth/token, user.current, crm.* |
| Telegram | Пользовательский канал и доставка callback-событий | getUpdates, sendMessage, editMessageText |
Таблица ADR-001/1. Ответственность компонентов архитектуры
Последствия
Разделение уменьшает связанность и позволяет перезапускать или масштабировать процессы независимо. Для коротких входящих запросов используется синхронный Flask/Gunicorn, а для длительного polling и параллельных REST-операций — asyncio/aiogram. Связь приложений формализована версионированными функциями PostgreSQL вместо общего программного модуля.