Studio-Yandex-Practicum · KonstantinRaikhert · Jul 12, 2023 · Jul 5, 2023 · Jul 5, 2023 · Jul 6, 2023
diff --git a/.gitignore b/.gitignore
@@ -131,6 +131,9 @@ dmypy.json
 # PyCharm
 .idea
 
+# VSCode
+.vscode
+
 *.sqlite
 
 # Persistence file from bot

diff --git a/Makefile b/Makefile
@@ -1,7 +1,19 @@
-# To generate factories with coordinators info use command:
-# 'make generate_contacts amount=5', where 'amount' is <int> value
-# of factories you want to generate, e.g. 5.
+# for start mySQL container:
+rundb:
+	docker compose -f infra/dev/docker-compose.local.yaml up -d
 
+# for stop mySQL container:
+stopdb:
+	docker compose -f infra/dev/docker-compose.local.yaml down
 
-generate_contacts:
-	python src/bot/factories/contact_factories.py ${amount}
+# for stop mySQL container and delete database:
+deletedb:
+	docker compose -f infra/dev/docker-compose.local.yaml down --volumes
+
+# for start bot with mySQL container:
+runbot-db:
+	docker compose -f infra/dev/docker-compose.local.yaml up -d
+	python src/run_bot.py
+
+filldb:
+	python src/db_fixtures/filldb.py
diff --git a/README.md b/README.md
@@ -1,7 +1,49 @@
-# spread_wings_bot
+# Бот для фонда "Расправь крылья"
 
+#### Проект телеграм-бота, который позволяет всем желающим и нуждающимся получить ответы на все необходимые вопросы в телеграме. [“Расправь крылья”](https://detskyfond.info/).
 
-## Правила работы с git (как делать коммиты и pull request-ы)
+Бот забирает необходимые вопросы и контакты с базы данных сайта на CMS Wordpress.
+
+# Содержание
+
+
+1. [БРИФ](docs/materials/briff.md)
+
+   1.1 [Инструкции и ритуалы на проекте](docs/materials/instructions.md)
+
+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)
+
+<br><br>
+
+# 2. Структура проекта <a id="structure"></a>
+
+| Имя  | Описание |
+| ------------- | ------------- |
+| infrastructure | Docker-compose файлы для запуска проекта с помощью Docker |
+| src | к описанию этой папки стоит вернутся когда рефакторинг закончим |
+
+# 3. Подготовка к запуску <a id="start"></a>
+
+Примечение: использование Poetry и pre-commit при работе над проектом обязательно.
+
+## 3.1. Правила работы с git (как делать коммиты и pull request-ы)<a id="git"></a>:
 
 1. Две основные ветки: `master` и `develop`
 2. Ветка `develop` — “предрелизная”. Т.е. здесь должен быть рабочий и выверенный код
@@ -12,36 +54,116 @@
    - исправление ошибок — `bugfix/название-багфикса`
 6. Пушим свою ветку в репозиторий и открываем Pull Request
 
+## 3.2. Poetry (инструмент для работы с виртуальным окружением и сборки пакетов)<a id="poetry"></a>:
 
-### Предварительные требования:
 
-1. **Poetry** Зависимости и пакеты управляются через **poetry**. Убедитесь, что **poetry** [установлен](https://python-poetry.org/docs/#osx--linux--bashonwindows-install-instructions) на вашем компьютере и ознакомьтесь с [документацией](https://python-poetry.org/docs/cli/).
-2. **Docker** В проекте будем использовать MySQL. Рекомендуем запускать БД через Docker, следуя дальнейшим инструкциям.
-3. Файлы **requirements** Файлы редактировать вручную не нужно. Обновляются через pre-commit хуки (если есть изменение в зависимостях, то список обновится при коммите).
-4. **pre-commit хуки**
-   [Документация](https://pre-commit.com)
-   При каждом коммите выполняются хуки (автоматизации) перечисленные в **.pre-commit-config.yaml**. Если не понятно какая ошибка мешает сделать коммит можно запустить хуки вручную и посмотреть ошибки:
-   ```shell
-   pre-commit run --all-files
-   ```
+Poetry - это инструмент для управления зависимостями и виртуальными окружениями, также может использоваться для сборки пакетов. В этом проекте Poetry необходим для дальнейшей разработки приложения, его установка <b>обязательна</b>.<br>
+
+<details>
+ <summary>
+ Как скачать и установить?
+ </summary>
+
+### Установка:
+
+Установите poetry следуя [инструкции с официального сайта](https://python-poetry.org/docs/#installation).
+<details>
+ <summary>
+ Команды для установки:
+ </summary>
+Для 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 -*
+</details>
+<br>
+После установки перезапустите оболочку и введите команду
+
+> 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
+</details>
 
-Это инструмент управления зависимостями и виртуальным окружением,
-также используется для упаковки проектов на Python.
-Подробнее: https://python-poetry.org/
+<details>
+ <summary>
+ Порядок работы после настройки
+ </summary>
 
-1. Установить, следуя официальным инструкциям.
-    https://python-poetry.org/docs/#installation
+<br>
 
-2. Изменить конфигурацию Poetry (опционально).
-    ```shell
-    poetry config virtualenvs.in-project true
-    ```
-    > **Note**:
-    > Позволяет создавать виртуальное окружение в папке проекта.
+Чтобы активировать виртуальное окружение, введите команду:
 
-### Работа с Poetry
+> 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
+
+</details>
 
 В этом разделе представлены наиболее часто используемые команды.
 Подробнее: https://python-poetry.org/docs/cli/
@@ -60,40 +182,83 @@ poetry add <package_name>
 ```shell
 poetry update
 ```
+## 3.3. Pre-commit (инструмент автоматического запуска различных проверок перед выполнением коммита)<a id="pre-commit"></a>:
 
-### Настройка ```pre-comit```:
+<details>
+ <summary>
+ Настройка pre-commit
+ </summary>
+<br>
+1. Убедиться, что pre-comit установлен:
 
-1. Убедиться, что ```pre-comit``` установлен:
    ```shell
    pre-commit --version
    ```
 2. Настроить git hook скрипт:
+
    ```shell
    pre-commit install
    ```
 
-### Запуск ```Redis``` (работает в режиме ```redis=True```):
+Далее при каждом коммите у вас будет происходить автоматическая проверка
+линтером, а так же будет происходить автоматическое приведение к единому стилю.
+</details>
 
-1. Убедиться, что ```Docker``` установлен:
-2. Загрузить образ ```Redis```:
-   ```shell
-   sudo docker image pull redis
-   ```
+## 3.4. Настройка переменных окружения <a id="env"></a>
+
+Перед запуском проекта необходимо создать копию файла
+```.env.example```, назвав его ```.env``` и установить значение токена бота, базы данных почты и тд.
+
+# 4. Запуск бота <a id="run-bot"></a>
+
+### Сейчас возможен запуск бота только в режиме `polling`.<br>
+
+## 4.1. Запуск проекта локально <a id="run-local"></a>
+
+В локальной разработке предусмотрено использование персистентности бота в файле pickle. (Хранится в корневой директории `local_persistence`, если необходимо сбросить состояние бота - необоходимо удалить файл.)
+
+
+Запуск бота в локальной среде рекомендуется выполнять с помощью команд:
+
+запуск бота с контейнером MySQL:
+```shell
+make runbot-db
+```
+
+запуск контейнера с MySQL:
+```shell
+make rundb
+```
+
+остановка контейнера с MySQL:
+```shell
+make stopdb
+```
+
+остановка контейнера с MySQL и удаление базы данных:
+```shell
+make deletedb
+```
+
+наполнение MySQL тестовыми данными:
+```shell
+make filldb
+```
+
+
+## 4.2. Запуск проекта в Docker <a id="run-docker"></a>
+
+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
    ```
 
-3.1. Проверка доступности ```Redis```:
-   ```shell
-   python
-   import redis
-   r = redis.from_url('redis://localhost:6379')
-   print(r.ping())
-   exit()
-   ```
+# 5. Требования к тестам <a id="test-bot"></a>
 
-### Требования к тестам
 #### Запуск тестов
 Все тесты запускаются командой:
    ```shell

diff --git a/docs/materials/briff.md b/docs/materials/briff.md
@@ -0,0 +1,58 @@
+# Бриф
+
+## **Информация о заказчике:**
+
+**Заказчик:** Благотворительный фонд социальной помощи детям «Расправь крылья!»
+
+**Деятельность организации:** создан в 2007 году для помощи детям через вовлечение граждан, бизнеса и НКО в благотворительность. Работает на территории Российской Федерации.
+
+
+Направления деятельности:
+
+* Социальная адаптация воспитанников и выпускников организаций для детей-сирот и детей, оставшихся без попечения родителей.
+* Развитие навыков самоорганизации, коммуникации, самообслуживания у подростков с выраженными интеллектуальными нарушениями. Расширение возможностей выбора видов занятости и преодоление социальной эксклюзии. Создание в регионах систем сопровождения выпускников организаций для детей-сирот и детей, оставшихся без попечения родителей.
+* Повышение квалификации специалистов, работающих с детьми.
+
+
+**Цель проекта:** создать бота-помощника для организации, который сможет отвечать на часто задаваемые вопросы, связанные с программами помощи фонда, пособиями и льготами.
+
+*Выгода для заказчика*: уменьшение нагрузки на работников фонда.
+
+*Выгода для пользователей (соискателей помощи)*: получение информации в режиме 24/7.
+
+
+**Задачи:**
+
+Создать Телеграм-бота.
+
+**Как реализовано сейчас:**
+
+Вся информация находится на сайте, но (по словам заказчика) детям и подросткам эта площадка не подходит, им удобнее взаимодействовать через Телеграм.
+
+## Описание телеграм-бота:
+
+### [Схема состояний](https://github.com/Studio-Yandex-Practicum/spread_wings_bot/blob/develop/docs/rasprav_krilya.jpg?raw=true) - визуальное изображение стейтов
+
+Ожидаемая функциональность:
+
+* Получить информацию о юридической помощи.
+* Получить информацию о психологической помощи.
+* Получить информацию о социальной помощи.
+* Получить информацию о программах помощи Фонда и подать заявку на участие.
+* Возможность задать вопрос координатору фонда, если ответ на него не найден
+* Возможность записаться на прием к специалисту фонда
+
+### Начало работы:
+Пользователь заходит в телеграмм и вводит в поисковую строку **@название бота ,** кликает по найденному боту, видит краткое описание, нажимает кнопку start, после чего появляется окно с 5 кнопками: Юридическая помощь, Психологическая помощь, Социальная помощь, Участие в программах Фонда, Задать вопрос.
+
+### Основная функциональность
+
+* Юридическая помощь
+
+* Психологическая помощь
+
+* Социальная помощь
+
+* Участие в программах Фонда
+
+* Задать вопрос