Бот для фонда "Расправь крылья!"

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

Бот забирает необходимые вопросы и контакты с базы данных сайта на CMS Wordpress.

Содержание

1. БРИФ

   1.1 Инструкции и ритуалы на проекте

   1.2 ER - диаграмма сущностей

2. Структура проекта

3. Подготовка к запуску

   3.1. Правила работы с git

   3.2. Настройка poetry

   3.3. Настройка pre-commit

   3.4. Настройка переменных окружения

4. Запуск бота

   4.1. Запуск проекта локально

   4.2. Запуск в Docker

5. Требования к тестам

2. Структура проекта

Имя	Описание
infrastructure	Docker-compose файлы для запуска проекта с помощью Docker
src	к описанию этой папки стоит вернутся когда рефакторинг закончим

3. Подготовка к запуску

Примечение: использование Poetry и pre-commit при работе над проектом обязательно.

3.1. Правила работы с git (как делать коммиты и pull request-ы):

1. Две основные ветки: master и develop
2. Ветка develop — “предрелизная”. Т.е. здесь должен быть рабочий и выверенный код
3. Создавая новую ветку, наследуйтесь от ветки develop
4. В master находится только production-ready код (CI/CD)
5. Правила именования веток
   • весь новый функционал — feature/название-функционала
   • исправление ошибок — bugfix/название-багфикса
6. Пушим свою ветку в репозиторий и открываем Pull Request

3.2. Poetry (инструмент для работы с виртуальным окружением и сборки пакетов):

Poetry - это инструмент для управления зависимостями и виртуальными окружениями, также может использоваться для сборки пакетов. В этом проекте Poetry необходим для дальнейшей разработки приложения, его установка обязательна.

Как скачать и установить?

Установка:

Установите poetry следуя инструкции с официального сайта.

Команды для установки:

Для UNIX-систем и Bash on Windows вводим в консоль следующую команду:

curl -sSL https://install.python-poetry.org | python -

Для WINDOWS PowerShell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

После установки перезапустите оболочку и введите команду

poetry --version

Если установка прошла успешно, вы получите ответ в формате

Poetry (version 1.2.0)

Для дальнейшей работы введите команду:

poetry config virtualenvs.in-project true

Выполнение данной команды необходимо для создания виртуального окружения в папке проекта.

После предыдущей команды создадим виртуальное окружение нашего проекта с помощью команды:

poetry install

Результатом выполнения команды станет создание в корне проекта папки .venv. Зависимости для создания окружения берутся из файлов poetry.lock (приоритетнее) и pyproject.toml

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

poetry add <package_name>

Пример использования:

poetry add starlette

Также poetry позволяет разделять зависимости необходимые для разработки, от основных. Для добавления зависимости необходимой для разработки и тестирования необходимо добавить флаг --dev

poetry add <package_name> --dev

Пример использования:

poetry add pytest --dev

Порядок работы после настройки

Чтобы активировать виртуальное окружение, введите команду:

poetry shell

Существует возможность запуска скриптов и команд с помощью команды без активации окружения:

poetry run <script_name>.py

Примеры:

poetry run python script_name>.py

poetry run pytest

poetry run black

Порядок работы в оболочке не меняется. Пример команды для Win:

python src\run_bot.py

Доступен стандартный метод работы с активацией окружения в терминале с помощью команд:

Для WINDOWS:

source .venv/Scripts/activate

Для UNIX:

source .venv/bin/activate

В этом разделе представлены наиболее часто используемые команды. Подробнее: https://python-poetry.org/docs/cli/

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

poetry shell

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

poetry add <package_name>

Обновить зависимости

poetry update

3.3. Pre-commit (инструмент автоматического запуска различных проверок перед выполнением коммита):

Настройка pre-commit

1. Убедиться, что pre-comit установлен:

pre-commit --version

2. Настроить git hook скрипт:

   pre-commit install

Далее при каждом коммите у вас будет происходить автоматическая проверка линтером, а так же будет происходить автоматическое приведение к единому стилю.

3.4. Настройка переменных окружения

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

4. Запуск бота

Сейчас возможен запуск бота только в режиме polling.

4.1. Запуск проекта локально

В локальной разработке предусмотрено использование персистентности бота в файле pickle. (Хранится в корневой директории local_persistence, если необходимо сбросить состояние бота - необоходимо удалить файл.)

Запуск бота в локальной среде рекомендуется выполнять с помощью команд:

запуск django-приложения (Без БД) вместе с ботом для локальной разработки:

# Перейти в директорию c кодовой базой проекта src/, где лежит manage.py
cd src/

# Запустить веб-сервер командой
poetry run uvicorn config.asgi:application --reload

запуск бота с контейнером PostgreSQL:

make runbot-db

запуск контейнера с PostgreSQL:

make rundb

остановка контейнера с PostgreSQL:

make stopdb

остановка контейнера с PostgreSQL и удаление базы данных:

make deletedb

наполнение PostgreSQL тестовыми данными:

# Not ready yet
make filldb

4.2. Запуск проекта в Docker

1. Запуск Redis (работает в режиме redis=True) - убедитесь, что в .env установлено необходимое значение

2. Убедиться, что docker compose установлен: docker compose --version

3. Из папки infra/dev/ запустить docker-compose:

   sudo docker-compose -f docker-compose.stage.yaml up

5. Требования к тестам

Запуск тестов

Все тесты запускаются командой:

pytest

Или

make run_tests

Выборочно тесты запускаются с указанием выбранного файла:

pytest test_start.py

Или

make run_unit_tests

Написание тестов

Для написания тестов используется pytest. Основные настройки тестов хранятся в файле conftest.py. Фикстуры хранятся в файле fixtures/fixture_data.py Основные тесты бота хранятся в файле test_bot.py. В зависимости от функционала тестов можно добавлять файлы тестов. Файлы тестов должны начинаться с "test_".

Что необходимо тестировать

Разработчик самостоятельно определяет функционал, который будет покрыт данными. Но, как правило, рекомендуется тестировать все написанные самостоятельно основные функции бота, функции отправки и получения сообщений, функции перенаправления на сторонние или внутренние ресурсы.