RandomCoffeeBotTelegram

Random Coffee bot for the Telegram

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

Содержание

1. БРИФ

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

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

   1.3. Feature list проекта

   1.4. Диаграмма логики работы бота

2. О проекте

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

   2.2. Используемых технологий в проекте

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

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

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

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

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

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

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

   4.2. Запуск в Docker

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

2. О проекте

2.1 Структура проекта

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

2.2 Используемые технологии в проекте:

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

Примечание: для работы над проектом необходим Python не ниже версии 3.11. Также необходимо установить Poetry (не ниже 1.5.0) и 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, не ниже версии 1.5.0 следуя инструкции с официального сайта.

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

Если у Вас уже установлен менеджер пакетов pip, то можно установить командой:

pip install poetry==1.5.0

Если по каким-то причинам через pip не устанавливается, то для 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.5.0)

P.S.: Если при попытке проверить версию возникает ошибка об отсутствии исполняемого файла (poetry), необходимо после установки добавить его в Path Вашей системы (пути указаны по ссылке на официальную инструкцию по установке чуть выше.)

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

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 core.asgi:application --reload

Базовая команда для запуска БД, миграций, бота и джанго:

make bot-init

запуск бота и контейнера PostgreSQL с существующими данными в БД:

make bot-existing-db

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

make start-db

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

make stop-db

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

make clear-db

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

# Создание тестовых профилей IT-специалистов
make create-itspecialist amount=3

# Создание тестовых профилей рекрутеров
make create-recruiter amount=3

# Создание тестовых пар IT-специалист-рекрутер *временами ругается на уникальность ID
make create-pair amount=3

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. Фикстуры хранятся в файле tests/conftest.py Основные тесты бота хранятся в директории tests. В зависимости от функционала тестов можно добавлять файлы тестов. Файлы тестов должны начинаться с "test_".

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

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

Рекомендации к написанию кода Codestyle