BitrixDealsBot/README.md

# BitrixDealsBot

**BitrixDealsBot** — это телеграм-бот, который позволяет пользователям
взаимодействовать с CRM-системой Bitrix24 для управления сделками и контактами.
Цель бота — упростить процесс работы с CRM, предоставляя удобный интерфейс для
обновления и отслеживания сделок прямо из Telegram.

Задание выполняется в рамках учебной производственной практики для предприятия
ООО "Интернет-агенство ИНТЕРВОЛГА".

## Формулировка задания

**Telegram-бот “Помощник менеджера CRM”**

Telegram-бот для менеджера по продажам. Бот помогает быстро смотреть новые лиды,
брать их в работу, менять статус и добавлять комментарии.

**Стек:** Любой язык, любая БД, REST API Telegram, REST API Битрикс24

**Функции:**

- команда /leads показывает новые лиды (без ответственных);
- команда /lead ### показывает карточку лида по указанному ID: имя, телефон,
  источник, статус;
- кнопка “Взять” устанавливает ответственного;
- кнопка “Позвонить позже” устанавливает ответственного и планирует звонок через
  1 час;
- кнопка “Закрыть” возвращает в список лидов /leads;
- команда /history показывает историю действий;
- интеграция с Битрикс24 через webhook (Был осуществлен переход на OAuth).

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

Основные архитектурные решения изложены в разделе ADR (Architecture Decision
Records) в папке `docs/adr`. [Главный документ](docs/adr/main.md) может
использоваться для навигации между заметками о принятых решениях.

## Настройка

> [!IMPORTANT]
> Для развертывания проекта требуется Docker и Docker Compose. В Windows
> рекомендуется использовать WSL2. Также требуется внешний nginx для
> проксирования запросов к сайту.

Клонируйте репозиторий и перейдите в папку проекта:

```bash
cd BitrixDealsBot
```

Скопируйте `.env.example` в `.env` и заполните значения. Ключ шифрования можно
создать командой:

```bash
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

`TOKEN_ENCRYPTION_KEY` должен быть одинаковым у сайта и бота. В БД OAuth-токены
попадают уже зашифрованными.

Сгенерируйте или иным способом придумайте пароли для ролей администратора,
пользователя сайта и бота. В PostgreSQL роли создаются автоматически при первом
создании контейнера `db`.

Также укажите URL, который будет использоваться в качестве базового адреса
сайта. Соответственно, для этого бы желательно иметь свой домен, соответствующие
DNS-записи и TLS-сертификат (например, от Let's Encrypt).

Создайте локальное приложение в Битрикс24 и укажите в нем URL для привязки:

```text
https://bot.example.ru/bitrix/bind
```

Битрикс сгенерирует `CLIENT_ID` и `CLIENT_SECRET`, которые нужно указать в
`.env`. В настройках приложения разрешите доступ к CRM и к минимальной
информации о пользователе.
Битрикс передает сайту OAuth-данные приложения. Сайт обменивает `REFRESH_ID` на
новую пару токенов и берет доверенные идентификаторы портала и пользователя из
ответа OAuth-сервера. Затем он проверяет пользователя через `user.current`,
сохраняет зашифрованную пару токенов и показывает ссылку на Telegram.

Также создайте бота в Telegram через BotFather и укажите его токен в `.env`.
Дополнительно укажите в `.env` имя вашего бота, которое будет использоваться в
ссылках на него.

Вы также можете изменить в '.env' стандартную стадию сделки, которая будет
использоваться при взятии сделки в работу. По умолчанию это стадия "C1:PREPARATION". 
Если вы хотите использовать другую стадию, укажите ее код в
переменной `BITRIX_TAKE_TO_WORK_STAGE_ID`.

## Запуск в Docker

```bash
docker compose up --build -d
```

Создаются четыре контейнера:

- `db` — PostgreSQL без опубликованного порта;
- `site` — Flask/Gunicorn на `127.0.0.1:8000` хостовой машины;
- `bot` — aiogram polling без входящего порта;
- `migrate` — контейнер для миграции БД, запускается при каждом
  `docker compose up` и завершается после выполнения миграций.

Инициализация БД выполняется автоматически только для нового volume.

### Внешний nginx

Nginx работает на хосте, вне Docker:

```nginx
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
```

Если на вашем сервере есть панели типа FastPanel, Plesk, ISPmanager, то вы
можете создать сайт с обратным прокси прямо в интерфейсе панели.

## Транзакции и доступ к БД

Сайт подключается ролью `site_app`, бот — `bot_app`. Прямого доступа к таблицам
у них нет.

- `binding.issue_v1` сохраняет OAuth-данные и выпускает ссылку одной
  транзакцией.
- `binding.consume_v1` атомарно погашает ссылку и создает привязку.
- `oauth.*` выдает и обновляет токены только боту.
- короткая DB-аренда защищает refresh-токен от параллельного обновления.

Сетевые запросы к Битриксу не выполняются внутри транзакций.
Назначения на сделки хранятся только в Битриксу. Локальная блокировка в процессе
бота не дает двум Telegram-пользователям одновременно взять одну сделку, а
повторная проверка `ASSIGNED_BY_ID` отсекает устаревшие кнопки.

## Команды бота

- `/start bind_<token>` — привязать пользователя.
- `/deals` или `/leads` — показать сделки с фильтром и пагинацией.
- `/deal 123` — открыть карточку сделки.
- `/help` — показать справку.

Фильтр «Мои сделки» показывает сделки всех стадий, где ответственным назначен
привязанный Битрикс-пользователь.

Кнопка «Позвонить позже» создает дело с напоминанием в Битриксе через час.
История показывает пять последних переходов сделки по стадиям. Кнопка «Стать
ответственным и взять в работу» использует ID привязанного Битрикс-пользователя.
Ответственный также видит кнопку перехода на следующую стадию; финальный переход
выделен как завершение сделки. Перед переходом бот запрашивает необязательный
комментарий для таймлайна: пустая строка или прочерк означают переход без него.