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_".
+
+#### Что необходимо тестировать
+Разработчик самостоятельно определяет функционал, который будет покрыт
+данными. Но, как правило, рекомендуется тестировать все написанные
+самостоятельно основные функции бота, функции отправки и получения сообщений,
+функции перенаправления на сторонние или внутренние ресурсы.