Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lalathealter/zhurik

Чат-бот для взаимодействия с абитуриентами
https://github.com/lalathealter/zhurik

Last synced: about 1 month ago
JSON representation

Чат-бот для взаимодействия с абитуриентами

Awesome Lists containing this project

README 

        
# zhurik



Чат-бот для взаимодействия с абитуриентами 



## Инструкции к пользованию



### Подготовка 



Для начала убедитесь, что у вас в системе установлено приложение для контроля версий *Git*. Скачать и установить его можно по следующей ссылке: [https://git-scm.com/download/win](https://git-scm.com/download/win)



Далее нам нужно клонировать удаленный репозиторий, то есть - папку с кодом бота. Скорее всего, вы читаете эту инструкцию как раз на веб-странице репозитория, поэтому сделать это не составит большого труда. Пролистните веб-страницу в самый верх и найдите там зелёную кнопку *Код*, нажмите на неё и скопируйте *https*-ссылку, которая отобразится в небольшом меню. После этого Вам необходимо выбрать папку, в которую Вы будете клонировать данный репозиторий, после чего открыть в ней консоль.



Открыть консоль в этой папке можно двумя путями. Первый - открыть Проводник (базовое приложение для просмотра папок и файлов на Вашем компьютере), зайти через него в нужную вам папку и, зажав клавишу *Shift*, нажать правой кнопкой мыши по любому пустому месту в окне папки. Откроется контекстное меню с несколькими вариантами действий, из которых следуте выбрать *"Открыть окно команд"* (или *"Открыть консоль тут"* - в разных системах оно может называться по-разному). В результате перед вами откроется окно *консоли* - именно с ней мы и будем работать далее.

Второй способ - это открыть консоль в любом месте любым удобным способом, после чего сменить текущую папку на ту, что Вы хотите. Сделать это можно или самостоятельно передвигаясь по папкам путём команды *cd*, или же просто прописав команду *cd полный/адрес/папки*. Получить полный адрес папки можно путём взаимодействия с вашим Проводником.



Далее введите следующую команду: *git clone ссылка_на_репозиторий*, где "ссылка_на_репозиторий" - это копированный вами адрес репозитория. Убедитесь, что он прописан правильно и обязательно содержит в себе указание протокола "https://". После ввода команды нажмите *Enter*, что запустит процесс клонирования. В результате в текущей папке появится ещё одна - с кодом бота. Запомните это место и путь до неё, после чего откройте консоль уже внутри неё. Это - корневая папка всего проекта, и все дальнейшие инструкции по вводу консольных команд необходимо исполнять из неё. 



Перед тем, как продолжить, сначала убедитесь, что у вас корректно установлен интерпретатор *python* и менеджер пакетов *pip* (обычно устанавливается вместе с интерпретатором). Скачать это можно по следующей ссылке: [https://www.python.org/downloads/](https://www.python.org/downloads/)

Проверить это можно при помощи команд `py -v` и `py -m pip -v`, введёных в консоли (т.ж.с. командной строке) - если они исполняются без ошибки и корректно отображают номер версии, то всё в порядке. (ПРИМЕЧАНИЕ: здесь и далее `py` — это команда для использования интерпретатора *python*. В некоторых случаях данным "словом" может также быть `python3` или просто `python`. Если у вас по какой-то причине не работает первое — пробуйте их. Если же и они не сработали, то проблема была в самой установке)

Далее установите все текущие зависимости проекта - `py -m pip install -r requirements.txt`. Замечание для будущих разработчиков: после добавления новых зависимостей файл *requirements.txt* следует обновлять.

Напоследок следует создать текстовый файл с буквальным названием *.env* (пустое имя, расширение "env"), в который следует поместить подобную строчку:

`TG_BOT_TOKEN="выданный_вам_длинный_токен_для_телеграмм_бота"`

Получить строчку токена можно при обращении к официальному боту под именем @BotFather в самом Телеграме и пройдя небольшую процедуру регистрации. 



### Установка базы данных



Для правильной работы статистики необходимо настроить базу данных (на sqlite). Сделать это можно следующей командой: `py db_init.py`.

Замечание для будущих разработчиков: именно в этом файле задаётся структура базы данных в формате SQL. Если вы захотите её поменять, то не забудьте обновить её или в консоли соответствующими командами (вручную), или же запуском `py db_drop.py` (сбросом всей базы данных) и последующим `py db_init.py` (пересозданием).

ВНИМАНИЕ: адрес используемой базы данных задаётся через строчку в файле *.env* следующим образом:

`DB_ADDRESS="путь/до/желаемой/базы/данных.db"`

По умолчанию данный параметр равен *zhurik.db*



### Запуск



Для запуска бота достаточно ввести `py main.py` при нахождении в корневой папке проекта. Если в консоли вы увидели приветственное сообщение об успешном запуске - то бот готов к службе! Найдите его в приложении Телеграм по тому имени, что указывали при регистрации, и напишите команду `/start`.



### Выключение



Если вы хотите отключить бота (ради перезапуска или просто так), то вам достаточно будет открыть окно с консолью, откуда он был запущен (и где в процессе работы выводится информация по его работе) и ввести сочетание клавиш *Ctrl*, *C*. Как только вы увидите, что в консоли снова отображается путь до текущей директории, а рядом моргает текстовый курсор (горизонтальная или вертикальная черта) - дело сделано. Того же эффекта обычно можно добиться закрытием окна с консолью (нажатием на "крестик").



### Корректировка ветвей вопросов



*ВНИМАНИЕ*: ваши изменения вступят в силу только после перезапуска бота.



Древо вопросов и ответов формируется путём обработки файла `questions_tree.json` - текстовом файле в формате `json`.

Для правильной модификации следует: 



- Избегать использования символа *|* в темах и вопросах, так как он используется в качестве разделителя в скрипте выгрузки статистики для формата *.csv*.

- Придерживаться общих правил этого формата.

- Организовать его наподобие следующей древовидной структуры:



```json

{

    "вопрос": "прямой ответ",

    "ещё вопрос": "иной ответ",

    "особенная тема вопросов": {

        "конкретный вопрос": "конкретный ответ",

        "конкретный вопрос 2": "конкретный ответ 2",

        "ещё более углубленная тема вопроса": {

            "самый особенный вопрос": "самый особенный ответ"

        }

    },

    "вопрос о помощи": "ответ с памяткой"

}

```



Где на месте "ключей" объекта - вопросы, а на месте "значений" - или такие же объекты (условно назовём их "темы"), или ответы на них.

Внимание! Перед окончанием заполнения убедитесь, что во всём древе два всяких вопроса отличаются друг от друга или темой-родителем, или текстом. Если они отличаются текстом и темой-родителем, но у самих тем-родителей также идентичны тексты - это тоже считается нарушением формата.

Пример того, как быть НЕ должно:



```json

{

    "вопрос": "ответ",

    "вопрос": "ответ",

    "плохая тема": {

        "дубль": "дубль-ответ",

        "дубль": "дубль-ответ"

    },

    "плохая тема": {

        "дубль": "дубль-ответ",

        "нормальный вопрос": "нормальный ответ"

    }

}

```



*ОТДЕЛЬНОЕ ЗАМЕЧАНИЕ*:

Будьте бдительны при изменении вопросов в файле questions_tree.json! Статистика вопросов напрямую завязана на этой структуре - и поэтому, если вы пожелаете её как-то изменить, то будьте готовы к тому, что цифры статистики потеряют свою актуальность, так как перепутается порядок привязки идентификатора к теме и вопросу. Поэтому в таких случаях *рекомендуется* сбросить всю прошлую статистику и пересоздать базу данных заново. В связи с этой особенностью рекомендуется вести отчётность в *поитеративно* изменениям вопросов.



### Использование разметки MarkDown



В полях ответов (но не вопросов и ведущих к ним веткам!) вы можете использовать разметку *MarkDown* для украшения текста и вставки гиперссылок. Краткая инструкция: любой текст можно обернуть специальными символами для придания ему конкретных эффектов. Далее будут перечислены примеры написания с демонстрацией эффекта.



- обычный текст - вокруг него нет никаких символов, выглядит так.

- \***жирный текст**\* - вокруг него есть звёздочки.

- \_*курсивный текст*\_ - вокруг него есть нижние подчёркивания.

- `[тыкните сюда](https://google.com)` - преобразуется в кликабельную ссылку с текстом "тыкните сюда".



*Внимание!*

Если вы решите использовать в тексте просто звёздочку, или просто нижнее подчёркивание (как элемент текста, а не указание на украшение) - то убедитесь, что вы прописываете его ВНЕ иных элементов украшения и с двумя обратными слэшами, потому что иначе текст может просто сломать бота.

Пример:



`Вот *так* - хорошо\\*`



`*А вот так - очень\\* плохо*`



### Функция обращения к оператору



Для получения контактов оператора достаточно прописать команду `/help`, и бот отправит вам кнопку с ссылкой на пользователя Телеграм.



Манипулировать списком операторов можно при помощи файла `operators.json`: соблюдая разметку данного формата, просто впишите в общий "словарь" сначала имя оператора (как ключ), каким будущий пользователь увидит его на кнопке, а через двоеточие (как значение) – тэг пользователя Телеграм, привязанный к аккаунту вашего оператора. (ПРИМЕЧАНИЕ: обычно тэги пишутся через символ "@", но в самом файле тэг следует вводить без него. Если вы хотите понять, какой тэг у вас – просто откройте свой профиль в Телеграм, и вы найдёте его в поле "Имя пользователя")



### Получение выгрузки из Базы Данных



На данный момент поддерживается получение статистики по запрошенным вопросам. Для того, чтобы её получить, достаточно запустить скрипт *db_stat.py* – сделать это можно при помощи команды `py db_stat.py`, находясь в корневой папке проекта.

Запуск данного скрипта сохранит результаты обработки базы данных в файле с разрешением *.csv* (известный формат, применяемый для ведения таблиц) *.xlsx* (стандартный для офисной программы Excel) внутри папки *stats*. Также во время запуска в консоль будут построчно выводиться аналогичные данные (только с иным порядком колонок).



Внимание!

Все вопросы и темы дополнительно нумеруются программой, начиная с нуля. То есть, если у вас есть вопрос "Как пройти к директору?", то в статистике он отобразится как "Как пройти к директору?-0". Это сделано для избежания конфликтов имён и для того, чтобы идентичные по содержанию вопросы и темы можно было отличить друг от друга. Как правило: чем *ниже* и *глубже* в файле встречается тот или иной похожий вопрос, тем *выше* будет его порядковый номер.



## Требования к боту (для разработчиков)



В результате выполнения проекта должен появиться бот-помощник в Telegram, способный отвечать на вопросы абитуриентов и формировать инструкции по поступлению на направления факультета журналистики.



- Текст соответствует нормам и правилам русского языка

- Во взаимодействии с ботом пользователь может выбирать категории вопроса

- Пользователь имеет возможность возвращаться к предыдущему вопросу

- Существует возможность переадресации пользователя на специалиста отборочной комиссии (отправка контактов в случае, если обращающийся слишком долго ищет ответ на свой вопрос)

- Присутствуют элементы вовлечения пользователя в коммуникацию в рамках мессенджера

- Возможность редактирования ответов бота сотрудниками отборочной комиссии после завершения взаимодействия с проектной командой и инструкции по использованию

- У держателя бота есть возможность отслеживать количество обращений, контактные данные пользователей (номера телефонов и ФИО), формируется статистика по самым популярным вопросам