geroy4ik / lomaya_baryery_backend

Бэкенд проекта "Ломая барьеры"

1. О чём проект?

Проект состоит из телеграм-бота, сайта админки, куда дети или их родители присылают ежедневно результаты неких действий. Дети выполняют дома задания, направленные на формирование социально-бытовых навыков (почистить зубы, постирать, помыть посуду), отчитываются по ним, а потом по итогам трехмесячной смены “Умею жить” получают награды.

Сейчас это реализовано направлением фотографий в общий чат, что вызывает некоторые неудобства из-за большого объема, который необходимо самостоятельно проанализировать, иногда фотографии могут отправляться повторно.

2. Начало работы

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

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

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

Установка:

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

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

poetry --version

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

Poetry version 1.1.13

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

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

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

> poetry install > > pre-commit install

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

3. БД

3.1. Запуск локальной БД

Запуск

docker-compose -f docker-compose.local.yaml up

Если у вас запущен Postgres на компьютере, то остановите его или создайте базу для проекта там.

3.2. Миграции

При первом запуске необходимо применить существующие миграции, чтобы в БД создались таблицы

alembic upgrade head

После изменения модели или добавления новой модели, необходимо создать миграцию:

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

В Названии миграции указать какую модель или поле в модели добавили или удалили.

Например

• add_shift_model
• shift_add_field_title
• shift_remove_field_title

После создания миграции ее необходимо применить:

alembic upgrade head

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

Чтобы откатить последнюю миграции, используйте

alembic downgrade -1

Если используются ENUM классы, например поле статус с заранее разрешенными значениями нужно вручную прописать в миграции создание и удаление типа

Описываем тип

STATUS_ENUM_POSTGRES = postgresql.ENUM('started', 'finished', 'preparing', 'cancelled', name='shift_status', create_type=False)
STATUS_ENUM = sa.Enum('started', 'finished', 'preparing', 'cancelled', name='shift_status')
STATUS_ENUM.with_variant(STATUS_ENUM_POSTGRES, 'postgresql')

добавляем к полю

sa.Column('status', STATUS_ENUM, nullable=False),

Прописываем удаление при откате миграции

STATUS_ENUM.drop(op.get_bind(), checkfirst=True)

Пример из миграции

"""init

Revision ID: bc61d3dfbfa8
Revises:
Create Date: 2022-09-18 07:27:34.175636

"""
from alembic import op
import sqlalchemy as sa
from sqlalchemy.dialects import postgresql

# revision identifiers, used by Alembic.
revision = 'bc61d3dfbfa8'
down_revision = None
branch_labels = None
depends_on = None

STATUS_ENUM_POSTGRES = postgresql.ENUM('started', 'finished', 'preparing', 'cancelled', name='shift_status', create_type=False)
STATUS_ENUM = sa.Enum('started', 'finished', 'preparing', 'cancelled', name='shift_status')
STATUS_ENUM.with_variant(STATUS_ENUM_POSTGRES, 'postgresql')

def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('shift',
    sa.Column('id', postgresql.UUID(as_uuid=True), nullable=False),
    sa.Column('created_at', sa.TIMESTAMP(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
    sa.Column('updated_at', sa.TIMESTAMP(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
    sa.Column('status', STATUS_ENUM, nullable=False),
    sa.Column('started_at', sa.DATE(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
    sa.Column('finished_at', sa.DATE(), nullable=False),
    sa.PrimaryKeyConstraint('id')
    )
    # ### end Alembic commands ###

def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_table('shift')
    STATUS_ENUM.drop(op.get_bind(), checkfirst=True)
    # ### end Alembic commands ###

Если добавили значения в choice так же прописываем

def upgrade():
    with op.get_context().autocommit_block():
        op.execute("ALTER TYPE status ADD VALUE 'REJECTED'")

Для отката миграции

• переименовываем текущий тип
• создаем новый (с прежними значениями)
• приписываем новый тип для таблицы
• удаляем старый тип

def downgrade():
    op.execute("ALTER TYPE status RENAME TO status_old")
    op.execute("CREATE TYPE status AS ENUM('STARTED', 'ACCEPTED')")
    op.execute((
        "ALTER TABLE transactions ALTER COLUMN status TYPE status USING "
        "status::text::status"
    ))
    op.execute("DROP TYPE status_old")

3.3. Тестовые данные БД

Подробнее

В проекте реализована возможность генерации фейковых (тестовых) данных для БД.
Для наполнения таблиц таблиц необходимо:

• установить необходмиые зависимости

poetry install

• наполнить БД тестовыми данными Внимание! Перед генерацией тестовых данных, произойдет полное удаление существующих данных БД!

python -m data_factory.main

4. Работа с ботом

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

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

python run.py

Обратите внимание, что без указания доменного имени с установленным  SSL-сертификатом для переменной APPLICATION_URL в переменных окружения, форма регистрации бота загружаться не будет. Чтобы этого избежать при локальном тестировании, воспользуйтесь инструкцией, указанной в пункте 4.2.2.1

4.2. Выбор режима работы бота.

Возможен запуск бота в режимах polling или webhook.

4.2.1. Polling

Запуск

Для запуска бота в режиме polling нужно установить переменной окружения BOT_WEBHOOK_MODE значение false. Дополнительных настроек не требуется.

4.2.1.1. Запуск одного бота без апи только в режиме polling

Запуск

Бот без апи запускается только в режиме polling.

python run_bot.py

4.2.2. Webhook

Запуск

Для запуска бота в режиме webhook нужно установить переменной окружения BOT_WEBHOOK_MODE значение true, а также указать домен, на котором развернуто приложение в переменной APPLICATION_URL:

BOT_WEBHOOK_MODE=true
APPLICATION_URL=https://example.com

4.2.2.1. Отладка приложения с ботом в режиме webhook на локальном компьютере

Необходимые действия

В случае отсутствия сервера с доменным именем и установленным SSL-сертификатом, для отладки приложения можно воспользоваться ngrok для построения туннеля до вашего компьютера.
Для этого необходимо:

• Скачать и установить ngrok
• Зарегестрироваться в сервисе ngrok и получить токен
• зарегистрировать полученный токен на локальном комьютере

ngrok config add-authtoken <ваш токен>

• Запустить тоннель ngrok

ngrok http 8080

• в переменной окружения APPLICATION_URL указать адрес (https), предоставленный сервисом ngrok:

APPLICATION_URL=https://1234-56-78-9.eu.ngrok.io # пример

• Запустить приложение с ботом в режиме webhook (см. выше)

python run.py

Более подробная информация об использовании сервиса ngrok доступна на официальном сайте

4.3 Переменные окружения

Переменные окружения

POSTGRES_DB=lomaya_baryery_db_local  # имя базы данных
POSTGRES_USER=postgres # логин для подключения к базе данных
POSTGRES_PASSWORD=postgres # пароль для подключения к БД
DB_HOST=localhost # название сервиса (контейнера)
DB_PORT=5432 # порт для подключения к БД
BOT_TOKEN= # токен бота
BOT_WEBHOOK_MODE=False # запустить бота в режиме webhook(true)|polling(false)
APPLICATION_URL= # домен, на котором развернуто приложение
SEND_NEW_TASK_HOUR=8  # время отправки нового задания
SEND_NO_REPORT_REMINDER_HOUR=20  # время отправки напоминания об отчёте

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