snake / c
CI/CD
Реестр контейнеров и пакетов
Кирилл Черняев
upd
1 год назад История
README.md

CyberProtect Advent

Данный проект был написан при помощи асинхронного фреймворка для работы с телеграмм ботами aiogram на языке python. В качестве СУБД выступает PostgreSQL. Для миграций используется инструмент alembic.

Запуск бота

  • Создать виртуальное окружение и импортировать все используемые модули из requirements.txt (pip install –r requirements.txt в консоли)
  • Прописать путь к базе данных на PostgreSQL в base/settings.py в поле DATABASE_ACCESS (помечено комментарием)
  • Прописать путь к базе данных на PostgreSQL в alembic.ini в поле sqlalchemy.url (помечено комментарием)
  • Запустить миграции в консоли: alembic upgrade head. По итогу модели sqlalchemy будут преобразованы в таблицы бд. (Будут добавлены таблицы recommendations, user_recommendations, users, alembic_version). Если таблицы не были добавлены, тогда alembic revision –autogenerate, а затем alembic upgrade head.
  • Указать телеграмм id владельца бота в поле OWNER_ID в bot_settings.txt
  • Указать свой токен бота в поле BOT_TOKEN в bot_settings.txt либо использовать уже имеющийся
  • Запустить модуль main.py

Функционал бота

База данных

Используются модели sqlalchemy, которые можно найти в base/database/models.py.

  • User - модель юзера, имеет все данные, получаемые при регистрации, а также колонки recommendations_completed (сколько выполнено рекомендаций, при 30 открывается доступ к последнему тесту), current_recommendation (текущая рекомендация, если получены все - перестают приходить), admin_password (захешированный админ-пароль, выдается главным администратором)
  • Recommendation - устанавливаемые администраторами общие рекомендации. Указывается название, текст и день в адвенте. Изменяемы.
  • UserRecommendation - связь между пользователем и пришедшей рекомендацией, ссылаются на Recommendation через id и на пользователя, имеют статус выполнения. Неизменяемы.

Регистрация

  • При запуске пользователю нужно пройти регистрацию. Для этого у пользователя спрашиваются:
  1. Имя
  2. Часовой пояс в формате UTC (Телеграмм не предоставляет доступа к локальному времени пользователя, поэтому дополнительный вопрос).
  3. Время для получения рекомендаций
  4. Время для получения уведомлений
  5. График
  6. Пол
  7. Возрастная группа

asset_1 asset_2

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

Код регистрации представлен в base/handlers/registration.py

Меню

  • Пользователь может получить доступ к различным функциям бота через меню:
  1. Запуск адвента
  2. Профиль
  3. Новые рекомендации
  4. Результаты выполнения
  5. Приглашение друзей
  6. Прохождение финального теста
  7. Контактные данные

asset_3

Код меню представлен в base/handlers/menu.py

Запуск адвента

  • Пользователь может запустить адвент, после чего запускаются запланированные работы по отправке рекомендаций и уведомлений (запланированные работы в base/handlers/scheduler.py), а юзеру приходит первая рекомендация.
  • У рекомендации удобно можно поменять статус или сразу перейти к результатам. Также запускается запланированная работа по проверке этой рекомендации: если статус через день не будет установлен пользователем, установит бот.
  • При наличии отложенных рекомендаций пользователю приходят уведомления.
  • После запуска кнопка запуска адвента не появляется в новых меню, а старые становятся неактивными.

asset_4 asset_5

Код запуска адвента представлен в base/handlers/advent.py. Там же отлавливаются действия по установке статуса рекомендаций.

Просмотр профиля и изменение данных

  • Пользователь может посмотреть указанные при регистрации данные и поменять их.
  • При нажатии на изменение данных пользователя перекидывает на сценарий регистрации (base/handlers/registration.py). При завершении изменения профиля изменяются также и запланированные работы (если они есть): отправка уведомлений и рекомендаций будет по новому расписанию со следующего дня.

asset_6 asset_7

Код профиля представлен в base/handlers/profile.py.

Новые рекомендации

  • Вывод списка из 3 (или менее) последних рекомендаций.

asset_8

Код новых рекомендаций представлен в base/handlers/recommendation_list.py.

Результаты выполнения

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

  • Список рекомендаций: отображает до 5 рекомендаций на странице, можно скроллить и выбирать нужные дни для изменения

asset_9 asset_10 asset_11

  • Календарь: отображает сразу все рекомендации в виде дней.

asset_12

Код результатов представлен в base/handlers/results.py.

Приглашение друзей

  • Пользователь может пригласить друзей, скопировав ссылку.

asset_13

Код приглашения друзей представлен в base/handlers/invite_friends.py.

Тест

  • При достижении планки выполненных рекомендаций пользователь может выполнить последний тест, иначе высвечивается сообщение об оставшихся рекомендациях. Ссылка на форму может быть изменена в base/settings.py в поле FINAL_TEST_URL. Количество рекомендаций, необходимых для выполнения, можно изменить в поле MAX_RECOMMENDATIONS (должно быть кратно 5 для корректного отображения календаря, по умолчанию 30)

asset_14 asset_15

Код теста представлен в base/handlers/take_test.py.

Контактные данные

  • Пользователь может просмотреть контактные данные во вкладке “Помощь”.

asset_16

Код помощи представлен в base/handlers/help.py.

Панель главного администратора

  • Пользователь, чей id указан в поле OWNER_ID в bot_settings.txt, может добавить новых администраторов через панель, прописав команду /owner. Для этого ему нужно указать id зарегистрированного в боте пользователя и администраторский пароль. Можно использовать сгенерированный ботом.

asset_17

Код главного администратора представлен в base/handlers/owner.py.

Панель администратора

  • Пользователь с назначенным администраторским паролем (и владелец) может получить доступ к панель администратора через команду /admin. С помощью нее можно взаимодействовать с рекомендациями.

asset_18

  • Добавление рекомендаций через csv-файл.

asset_19 asset_20

  • Добавление рекомендаций в самом приложении.

asset_21

  • Изменение существующих рекомендаций.

asset_22

Код администратора представлен в base/handlers/admin.py.

О структуре бота

  • main.py - главный файл. Для каждого модуля в base/handlers свой рутер, который добавляет обработчики модуля, а в main.py добавляются все рутеры. Там же запускается бот и применяются настройки к нему.
  • base/database/ - модели базы данных.
  • base/filters/ - фильтры и функции для проверки данных.
  • base/handlers/ - обработчики событий, о каждом см. Функционал бота.
  • base/keyboards/ - взаимодействие с клавиатурами Телеграмма через функции генерации.
  • base/middlewares/ - доступ к scheduler (установка запланированных работ) и запросам в базу данных (подробнее в base/utils/db_connect) в обработчиках
  • base/utils/ - дополнительный функционал.
    • base/utils/callbackdata.py - классы с данными для коллбэков
    • base/utils/commands.py - функция с установкой стандартных команд бота (отображаются в меню слева при вводе)
    • base/utils/db_connect.py - класс, наследующий функционал классов AdminRequest (связь с базой данных для действий администраторов), RecommendationRequest (связь с базой данных для действий обычного пользователя), UserRequest (связь с базой данных для действий с пользователем).
    • base/utils/statesform.py - работа с состояниями (регистрация и т.д.)
  • base/settings.py - настройки бота, можно поменять текст при регистрации, ссылку на форму финального теста и т.д.
  • migrations/ - папка с миграциями alembic
  • recommendations.csv/ - несколько тестовых рекомендаций, которые можно добавить

Возможности для расширения

  • Использовать облачные сервисы для поддержки бота
  • Интегрировать Redis в проект для хранения запланированных работ по отправке рекомендаций и уведомлений на сервере
Описание

Python
Readme
0 Форки
0 Звезд
0 Наблюдатели
Конвейеры
0 успешных
0 с ошибкой