SkyForces
65 lines
5.7 KiB
Markdown
65 lines
5.7 KiB
Markdown
# 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 вместо общего программного модуля.
|