# Архитектурные решения BitrixDealsBot

В ходе производственной практики разработано серверное приложение
BitrixDealsBot, которое предоставляет менеджеру по продажам интерфейс Telegram
для работы со сделками CRM Битрикс24. Разработанное решение не копирует
CRM-данные в локальную базу: все сведения о сделках, контактах, компаниях,
стадиях и истории запрашиваются через REST API непосредственно в момент действия
пользователя. PostgreSQL хранит только данные, необходимые для идентификации
пользователя Битрикс24 и его привязки к пользователю Telegram-бота, включая
OAuth-токены.

В индивидуальном задании используется термин «лид», однако реализация работает с
сущностью сделки и методами `crm.deal.*`. Команды `/leads` и `/lead` сохранены
как пользовательские псевдонимы `/deals` и `/deal`, поэтому интерфейс остаётся
совместимым с формулировкой задания, а в документации используется технически
точное понятие «сделка».

## Технологический стек

| Уровень       | Технология                | Назначение                                                               |
|---------------|---------------------------|--------------------------------------------------------------------------|
| Язык          | Python 3.13               | Серверная логика сайта и Telegram-бота                                   |
| Telegram      | aiogram 3                 | Асинхронная маршрутизация команд, callback-запросов и опроса сервера     |
| HTTP-сервер   | Flask 3 + Gunicorn        | Страница привязки пользователя Битрикс24 к конкретному аккаунту Telegram |
| Запросы к API | httpx                     | Синхронные и асинхронные запросы к OAuth и REST API Битрикс24            |
| Хранилище     | PostgreSQL 17 + Psycopg 3 | Транзакции, хранимые функции и пулы соединений                           |
| Защита        | Fernet + SHA-256          | Шифрование OAuth-токенов и хеширование одноразовых ссылок                |
| Развёртывание | Docker Compose + nginx    | Изоляция процессов, миграции, HTTPS и обратное проксирование             |

*Таблица 1. Технологический стек решения*

## Состав группы ADR

| ADR                                          | Архитектурное решение                                     | Статус  |
|----------------------------------------------|-----------------------------------------------------------|---------|
| [ADR-001](001-apps-and-database.md)          | Разделение приложения на сайт, Telegram-бот и базу данных | Принято |
| [ADR-002](002-oauth-telegram-binding.md)     | Привязка пользователей Битрикс24 и Telegram               | Принято |
| [ADR-003](003-oauth-credential-lifecycle.md) | Защита и обновление OAuth-токенов                         | Принято |
| [ADR-004](004-bot-layers.md)                 | Слоистая организация Telegram-бота                        | Принято |
| [ADR-005](005-bitrix-deal-read-model.md)     | Получение списка и карточки сделки из Битрикс24           | Принято |
| [ADR-006](006-guarded-deal-mutations.md)     | Изменение сделки с проверкой актуального состояния        | Принято |
| [ADR-007](007-container-deployment.md)       | Развёртывание приложения с помощью Docker Compose         | Принято |
| [ADR-008](008-data-storage-and-access.md)    | Хранение интеграционных данных и разграничение доступа    | Принято |