# 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.

![UML-диаграмма компонентов программного решения](assets/report/architecture-components.png)

*Рисунок 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 вместо общего программного модуля.