From f5783e93286323b045677a6d0c934cacbee33418 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=AF=D1=80=D0=BE=D1=81=D0=BB=D0=B0=D0=B2=20=D0=90=D0=BD?= =?UTF-8?q?=D0=B4=D1=80=D0=B5=D0=B5=D0=B2?= <1frost34eone@gmail.com> Date: Mon, 18 Sep 2023 16:49:40 +0300 Subject: [PATCH] update documentation --- README.md | 18 +- docs/materials/briff.md | 25 +++ docs/materials/instructions.md | 61 +++++++ test.md | 307 +++++++++++++++++++++++++++++++++ 4 files changed, 398 insertions(+), 13 deletions(-) create mode 100644 docs/materials/briff.md create mode 100644 docs/materials/instructions.md create mode 100644 test.md diff --git a/README.md b/README.md index 92c168c..cdae6bc 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ # RandomCoffeeBotTelegram Random Coffee bot for the Telegram +#### Проект телеграм-бота, который предоставляет возможность пообщаться с IT-специалистами - выпускниками разных IT направлений практикума. + # Содержание -1. [БРИФ](#brief) +1. [БРИФ](docs/materials/briff.md) - 1.1 [Инструкции и ритуалы на проекте]() + 1.1 [Инструкции и ритуалы на проекте](docs/materials/instructions.md) - 1.2 [ER - диаграмма сущностей](#er) + 1.2 [ER - диаграмма сущностей](docs/RandomCoffeeER.jpg) 2. [Структура проекта](#structure) 3. [Подготовка к запуску](#start) @@ -31,12 +33,6 @@ Random Coffee bot for the Telegram

-# 1. БРИФ - -## 1.2. ER - диаграмма сущностей: -ER диаграммы расположены в директории /docs в двух удобных форматах [.drowio, .jpg] -![ER Диаграмма](/docs/RandomCoffeeER.jpg) - # 2. Структура проекта | Имя | Описание | @@ -308,7 +304,3 @@ make filldb данными. Но, как правило, рекомендуется тестировать все написанные самостоятельно основные функции бота, функции отправки и получения сообщений, функции перенаправления на сторонние или внутренние ресурсы. - -#### Рекомендации к написанию кода [Codestyle](https://github.com/Studio-Yandex-Practicum/RandomCoffeeBotTelegram/tree/develop/docs/codestyle.md) - -#### Диаграмма логики работы бота [Diagram](https://github.com/Studio-Yandex-Practicum/RandomCoffeeBotTelegram/tree/develop/docs/Diagramm_of_bot_logic.drawio) \ No newline at end of file diff --git a/docs/materials/briff.md b/docs/materials/briff.md new file mode 100644 index 0000000..d212d34 --- /dev/null +++ b/docs/materials/briff.md @@ -0,0 +1,25 @@ +# Бриф + +**Цель проекта:** Обеспечить процесс формирования пар для Random Coffee между студентами курса IT-рекрутер и выпускниками IT-специальностей Практикума в Telegram + +**Задачи:** + +Создать Телеграм-бота. + + +## Описание телеграм-бота: + +### [Схема состояний](https://github.com/Studio-Yandex-Practicum/RandomCoffeeBotTelegram/blob/develop/docs/Diagramm%20of%20bot%20logic.jpg) - визуальное изображение стейтов + +Ожидаемая функциональность: + +* создание профиля (учетной записи) каждого участника и хранение его в базе данных +* создание пары между выпускником и рекрутером (нужно, чтобы бот не создавал * пары типа рекрутер-рекрутер или выпускник-выпускник) +* рассылка контактов собеседников после создания пары +* запрос обратной связи у участников (отправляет ссылку на форму) +* повторный вопрос о создании пары после первого участия +* режим администратора должен включать: сброс пар, запрос статистики по парам, удаление профилей (возможно, другие функции по администрированию бота и участников) + + +### Начало работы: +Пользователь заходит в телеграмм и вводит в поисковую строку **@название бота ,** кликает по найденному боту, видит краткое описание, нажимает кнопку menu, после чего появляется окно с 3 кнопками: Поддержка, Старт, Помощь. При нажатии на кнопку старт бот предлагает поучаствовать в неформальном разговоре с выпускником Практикума. diff --git a/docs/materials/instructions.md b/docs/materials/instructions.md new file mode 100644 index 0000000..cf466bd --- /dev/null +++ b/docs/materials/instructions.md @@ -0,0 +1,61 @@ +# Инструкции + +### Общие правила коммуникации на проекте + +1. Рабочее время: распределение времени с пн-вс для студентов, пн-пт для PM и TL, но для решения важных вопросов можно связаться и в выходные: + + PM - с 12:00 до 22.00 по мск; + TL Константин Райхерт - с 16.00 до 23.00 по мск; + + - Работаем недельными спринтами (далее по скорости разработки). + - Стендапы понедельник, среда, пятница + - Еженедельные встречи с тимлидами один на один. + - В середине спринта (вт-чт) груминг задач для формирования бэклога на следующий спринт. + +2. Каналы коммуникации: + - пачка **Random_coffee_recruiter_bot_general** - анонсы и stand up + +3. Notion - место для базы + +### Ритуалы + +1. **Письменный стендап** + +Когда: понедельник, среда, пятница до 19:00 +Где: в тредах к сообщению в пачке +Цель: собрать актуальную информацию о положении дел в команде, выявить направления, требующие проработки тимлидами/техлидами/кураторами +Как: написать сообщение по установленному формату в треде в пачке. (ПМ создает тред с утра) + +2. **Встреча one-to-one** + +Когда: по необходимости +Где: по видео, один на один с тимлидом +Цель: решить вопросы вызывающие стопор, обменяться опытом. +Как: участник команды договаривается о созвоне лично с тимлидом. + +3. **Ретро** + +Когда: по итогам спринта +Где: по видео +Цель: улучшение командных процессов за счет обсуждения предыдущих событий и процессов в команде, которые наблюдались в течение спринта +Как: вместе анализируем спринт и отвечаем на вопросы: + +- Плюсы. Что шло хорошо в прошлой итерации? +- Минусы. Какие проблемы были в прошлой итерации? +- Идеи. Какие идеи появились по ходу ретроспективы? +- План. Какие улучшения мы запланируем на следующую итерацию? +(если необходимо, закрепить ответственного за конкретные события) + +4. **Организация встреч в Zoom** + + 1. Описание встречи + 2. Цели + 3. Фиксированный тайминг + 4. Запись при необходимости + +5. **Стендап (в письменном формате)** +- Что делал вчера: +- Что буду делать сегодня: +- Какие есть вопросы/проблемы (тегай того, с кем конкретно хочешь переговорить): + *Если вопросов/проблем нет, так и пишешь, что их нет* +- Предложения/пожелания: diff --git a/test.md b/test.md new file mode 100644 index 0000000..8219197 --- /dev/null +++ b/test.md @@ -0,0 +1,307 @@ +# Бот для фонда "Расправь крылья!" + +#### Проект телеграм-бота, который позволяет всем желающим и нуждающимся получить ответы на все необходимые вопросы в телеграме. [“Расправь крылья!”](https://detskyfond.info/). + +Бот забирает необходимые вопросы и контакты с базы данных сайта на CMS Wordpress. + +# Содержание + + +1. [БРИФ](docs/materials/briff.md) + + 1.1 [Инструкции и ритуалы на проекте](docs/materials/instructions.md) + + 1.2 [ER - диаграмма сущностей](docs/er_diagramm/er_draw.pdf) + +2. [Структура проекта](#structure) +3. [Подготовка к запуску](#start) + + 3.1. [Правила работы с git](#git) + + 3.2. [Настройка poetry](#poetry) + + 3.3. [Настройка pre-commit](#pre-commit) + + 3.4. [Настройка переменных окружения](#env) + +4. [Запуск бота](#run-bot) + + 4.1. [Запуск проекта локально](#run-local) + + 4.2. [Запуск в Docker](#run-docker) + +5. [Требования к тестам](#test-bot) + +

+ +# 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 следуя [инструкции с официального сайта](https://python-poetry.org/docs/#installation). +
+ + Команды для установки: + +Для 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 + +_Пример использования:_ + +> poetry add starlette + +Также poetry позволяет разделять зависимости необходимые для разработки, от +основных. +Для добавления зависимости необходимой для разработки и тестирования необходимо +добавить флаг ***--dev*** + +> poetry add --dev + +_Пример использования:_ + +> poetry add pytest --dev + +
+ +
+ + Порядок работы после настройки + + +
+ +Чтобы активировать виртуальное окружение, введите команду: + +> poetry shell + +Существует возможность запуска скриптов и команд с помощью команды без +активации окружения: + +> poetry run .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/ + +#### Активировать виртуальное окружение +```shell +poetry shell +``` + +#### Добавить зависимость +```shell +poetry add +``` + +#### Обновить зависимости +```shell +poetry update +``` +## 3.3. Pre-commit (инструмент автоматического запуска различных проверок перед выполнением коммита): + +
+ + Настройка pre-commit + +
+1. Убедиться, что pre-comit установлен: + + ```shell + pre-commit --version + ``` +2. Настроить git hook скрипт: + + ```shell + pre-commit install + ``` + +Далее при каждом коммите у вас будет происходить автоматическая проверка +линтером, а так же будет происходить автоматическое приведение к единому стилю. +
+ +## 3.4. Настройка переменных окружения + +Перед запуском проекта необходимо создать копию файла +```.env.example```, назвав его ```.env``` и установить значение токена бота, базы данных почты и тд. + +# 4. Запуск бота + +### Сейчас возможен запуск бота только в режиме `polling`.
+ +## 4.1. Запуск проекта локально + +В локальной разработке предусмотрено использование персистентности бота в файле pickle. (Хранится в корневой директории `local_persistence`, если необходимо сбросить состояние бота - необоходимо удалить файл.) + + +Запуск бота в локальной среде рекомендуется выполнять с помощью команд: + +запуск django-приложения (Без БД) вместе с ботом для локальной разработки: +```shell +# Перейти в директорию c кодовой базой проекта src/, где лежит manage.py +cd src/ + +# Запустить веб-сервер командой +poetry run uvicorn config.asgi:application --reload +``` + +запуск бота с контейнером PostgreSQL: +```shell +make runbot-db +``` + +запуск контейнера с PostgreSQL: +```shell +make rundb +``` + +остановка контейнера с PostgreSQL: +```shell +make stopdb +``` + +остановка контейнера с PostgreSQL и удаление базы данных: +```shell +make deletedb +``` + +наполнение PostgreSQL тестовыми данными: +```shell +# Not ready yet +make filldb +``` + + +## 4.2. Запуск проекта в Docker + +1. Запуск ```Redis``` (работает в режиме ```redis=True```) - убедитесь, что в .env установлено необходимое значение + +2. Убедиться, что ```docker compose``` установлен: + ```docker compose --version``` +3. Из папки ```infra/dev/``` запустить ```docker-compose```: + ```shell + sudo docker-compose -f docker-compose.stage.yaml up + ``` + +# 5. Требования к тестам + +#### Запуск тестов +Все тесты запускаются командой: + ```shell + pytest + ``` + + Или + + ```shell + make run_tests + ``` +Выборочно тесты запускаются с указанием выбранного файла: + ```shell + pytest test_start.py + ``` + + Или + + ```shell + make run_unit_tests + ``` + +#### Написание тестов +Для написания тестов используется pytest. +Основные настройки тестов хранятся в файле conftest.py. +Фикстуры хранятся в файле fixtures/fixture_data.py +Основные тесты бота хранятся в файле test_bot.py. В зависимости от функционала +тестов можно добавлять файлы тестов. Файлы тестов должны начинаться с "test_". + +#### Что необходимо тестировать +Разработчик самостоятельно определяет функционал, который будет покрыт +данными. Но, как правило, рекомендуется тестировать все написанные +самостоятельно основные функции бота, функции отправки и получения сообщений, +функции перенаправления на сторонние или внутренние ресурсы.