ProCharity_back_2.0

Оглавление

1. Описание
   • Технологии
2. Запуск бота локально
3. Для разработки
   • Установка и настройка приложения
   • Запуск
4. Использование
5. Полезная информация
   • Регистрация бота Telegram
   • Режимы работы бота
   • Работа с базой данных
   • Работа с Poetry
   • Использование Ngrok

Описание

Создание чат-бота в Telegram для платформы интеллектуального волонтерства ProCharity (НКО Фонд Друзья).

Сайт https://procharity.ru/

Чат-бот @ProCharity_bot

Платформа представляет собой агрегатор волонтерских заданий от различных благотворительных проектов - любой желающий согласно своим желаниям и умениям может откликаться на конкретные предложения благотворительных проектов о волонтерской помощи, в свою очередь благотворительный проект/фонд выбирает из всех откликов подходящих кандидатов.

Чат-бот реализует функционал волонтерской платформы в приложении Telegram - с помощью JSON рассылает подписчикам новые появляющиеся задания от фондов.

Технологии

Запуск бота локально

1. Создайте и заполните файл .env:

   # Переменные приложения
   BOT_TOKEN= # Токен аутентификации бота
   SECRET_KEY=  # Cекретный ключ для генерации jwt-токенов
   
   # Переменные базы данных
   POSTGRES_DB=procharity_back_db_local  # Название базы данных
   POSTGRES_USER=postgres  # Логин для подключения к базе данных
   POSTGRES_PASSWORD=postgres  # Пароль для подключения к базе данных
   DB_HOST=procharity_postgres  # Название хоста с БД
   DB_PORT=5432  # Порт для подключения к базе данных
   
   # Organization data
   ORGANIZATIONS_EMAIL=[email protected]
   
   # Адреса электронной почты администраторов
   EMAIL_ADMIN=[email protected]

   Note Полный пример переменных окружения.

   Note Для получения токена аутентификации бота обратитесь к разделу Регистрация бота Telegram.

2. Собрать и запустить контейнеры из файла infra/docker-compose.local.yml.

   docker compose -f infra/docker-compose.local.yml up

   Эта команда создаст и запустит все необходимые контейнеры, включая базу данных и бэкенд.

3. После успешного запуска контейнеров, выполните следующую команду, которая войдет в контейнер, выполнит миграции и наполнит тестовую базу данных (включая таблицу пользователей):

   docker exec -it procharity_bot_backend sh -c "alembic upgrade head && python3 fill_db.py with_fake_users"

Если тестовая база данных должна содержать только задания и не должна содержать таблицу пользователей, то необходимо выполнить команду:

```shell
docker exec -it procharity_bot_backend sh -c "alembic upgrade head && python3 fill_db.py"
```

Для разработки

Установка и настройка приложения

1. Клонировать репозиторий.

   git clone https://github.com/Studio-Yandex-Practicum/ProCharity_back_2.0.git
   cd ProCharity_back_2.0

2. Установить зависимости и активировать виртуальное окружение.

   poetry env use python3.11
   poetry install
   poetry shell

   Note Документация по установке Poetry

3. Настроить pre-commit. В режиме poetry shell

   pre-commit install
   

   Note Перед каждым коммитом будет запущен линтер и форматтер, который автоматически отформатирует код согласно принятому в команде codestyle.

4. Создайте и заполните файл .env:

   # Переменные приложения
   BOT_TOKEN= # Токен аутентификации бота
   SECRET_KEY=  # Cекретный ключ для генерации jwt-токенов
   
   # Переменные базы данных
   POSTGRES_DB=procharity_back_db_local  # Название базы данных
   POSTGRES_USER=postgres  # Логин для подключения к базе данных
   POSTGRES_PASSWORD=postgres  # Пароль для подключения к базе данных
   DB_HOST=localhost  # Название хоста с БД
   DB_PORT=5432  # Порт для подключения к базе данных
   
   # Organization data
   ORGANIZATIONS_EMAIL=[email protected]
   
   # Адреса электронной почты администраторов
   EMAIL_ADMIN=[email protected]

   Note Полный пример переменных окружения.

   Note Для получения токена аутентификации бота обратитесь к разделу Регистрация бота Telegram.

Запуск

1. Запустить Docker с БД.

   sudo docker compose -f infra/docker-pg.yml up -d

2. Применить миграции базы данных.

   alembic upgrade head
   

3. Выполнить скрипт наполнения тестовой базы.

   Генерация тестовых данных без таблицы пользователей

   python3 fill_db.py

   Генерация тестовых данных c таблицей пользователей

   python3 fill_db.py with_fake_users

4. Запустить сервер приложения.

   uvicorn src:app --reload

Использование

После выполнения инструкций, описанных в разделе "Для разработки",

будет запущен FastAPI-сервер по адресу http://localhost:8000.

Также по адресу http://localhost:8000/docs доступна полная документация API.

Полезная информация

Данный раздел содержит информацию, которая может быть полезна для разработчиков. Настоятельно рекомендуем каждому прочитать его хотя бы один раз.

Регистрация бота Telegram

1. Найдите в Telegram бота @BotFather и откройте с ним чат.

2. Напишите ему /newbot.

3. Придумайте и напишите название бота. Оно будет отображаться в контактах и чатах. Например: My Dev Bot.

4. Придумайте и напишите юзернейм. Он используется для упоминания бота и в ссылках. Юзернейм должен быть на латинице и обязательно заканчиваться на «bot». Например: my_dev_bot.

5. Готово. @BotFather пришлет токен бота — его нужно скопировать в переменную окружения BOT_TOKEN (см. в разделе "Установка и Запуск").

   Note Документация о боте BotFather

Режимы работы бота

1. Запуск без API приложения

   Выполнить скрипт запуска.

   python src/run.py

   Warning: Возможно только в режиме polling.

2. Polling

   Задать значение переменной окружения (.env).

   BOT_WEBHOOK_MODE=False

3. Webhook

   Задать значение переменным окружения (.env).

   BOT_WEBHOOK_MODE=True
   APPLICATION_URL=http://example.com  # Пример

   Note Подробнее о webhooks

   Note Для теста через HTTPS можно использовать Ngrok (см. раздел "Использование Ngrok").

Работа с базой данных

Создание миграций

1. Применить существующие миграции:

   alembic upgrade head

2. Создать новую миграцию:

   alembic revision --autogenerate -m "<Название миграции>"

   В название миграции указывается для какого поля или модели внесены изменения, например:

   • add_shift_model
   • shift_add_field_title
   • shift_remove_field_title

3. Повторить пункт 1, для применения созданной миграции.

Откат миграций

1. Откатить последнюю миграцию:

   alembic downgrade -1

Работа с Poetry

В этом разделе представлены наиболее часто используемые команды.

Подробнее: https://python-poetry.org/docs/cli/

1. Настройка окружения проекта Установку необходимо выполнять через curl, как в документации.

   poetry env use python3.11; poetry install

2. Активировать виртуальное окружение

   poetry shell

3. Добавить зависимость

   poetry add <package_name>

   Note Использование флага --dev (-D) позволяет установить зависимость, необходимую только для разработки. Это полезно для разделения develop и prod зависимостей.

Запустить скрипт без активации виртуального окружения

poetry run <script_name>.py

Использование Ngrok

Этот раздел будет полезен, если у вас нет доменного имени с установленным SSL-сертификатом.

Ngrok — это инструмент, который позволяет создавать временный общедоступный адрес (туннель) для вашего локального сервера, находящимся за NAT или брандмауэром.

Подробнее: https://ngrok.com/

Для установки следуйте официальным инструкциям.

https://ngrok.com/download

В режиме локального запуска.

1. Запустите сервер:

   ngrok http http://127.0.0.1:8000/
   

2. Задайте значение переменной окружения в файле (.env) :

   APPLICATION_URL=https://1234-56-78-9.eu.ngrok.io  
   # Это пример. Рабочее значение нужно взять
   в появившемся окне ngrock п.1
   

В режиме разработки. Задайте значение переменной окружения в (.env).

USE_NGROK=True