Task Management Bot

Task Management Bot — Telegram-бот для управления задачами, реализованный на основе Java Spring с использованием реактивного стека и модульной архитектуры.

Ссылка на Docker Hub репозиторий c Docker-образом:

Ссылка на Telegram-бота:

---

Технологический стек

• Язык программирования: Java 23
• Spring Framework (без Spring Boot)
• Spring WebFlux - реактивная обработка запросов
• Spring Modulith - модульная архитектура приложения
• MongoDB - документоориентированная СУБД
• HashiCorp Vault - управление секретами и конфигурациями
• Docker + Docker Compose - контейнеризация и оркестрация сервисов
• Telegram Bot API - взаимодействие с пользователями
• Undertow - основной сервер для обработки HTTP запросов

---

Архитектура

Приложение организовано в виде набора модулей в соответствии с модульной архитектурой Spring Modulith. Каждый модуль соответствует подпакету в ru.spbstu.hsai и решает определённую задачу:

• Telegram (telegram) - запуск бота, приём и обработка входящих обновлений, маршрутизация команд к соответствующим сервисам.
• Usermanagement (usermanagement) - управление пользователями: хранение профилей, прав и ролей.
• Authors (authors) - предоставление информации об авторах.
• Check (check) - эндпоинт для проверки работоспособности сервиса (Health Check).
• Config (config) - загрузка и управление конфигурацией (MongoDB, Vault, безопасность, WebFlux).
• Infrastructure (infrastructure) - служебные классы для запуска сервера и чтения системных свойств.
• Notification (notification) - планирование и отправка уведомлений о задачах.
• Simpletaskmanagment (simpletaskmanagment) - CRUD-операции для простых задач.
• Repeatingtaskmanagment (repeatingtaskmanagment) - CRUD-операции для повторяющихся задач.

Взаимосвязи между модулями:

• Модуль Notification использует Repeatingtaskmanagment, Simpletaskmanagment, Usermanagement и Telegram для формирования и отправки уведомлений.
• Модуль Config зависит от Infrastructure, Check, Authors и Telegram и использует Usermanagement для управления доступом к конфигурации.
• Модуль Telegram взаимодействует с Authors, Usermanagement, Simpletaskmanagment и Repeatingtaskmanagment, передавая команды пользователей в соответствующие сервисы.

Документация Spring Modulith о взаимосвязях между модулями.

---

Сервисы Docker

• vault – сервис для хранения секретов (пароли, токены).
• vault-init – сервис для инициализации Vault: загружает секреты.
• mongo – сервис с базой данных для приложения и СУБД MongoDB.
• app – сервис с основным Java-приложением (Task Management Bot). Зависит от успешного запуска mongo, vault и от корректного завершения работы сервиса vault-init.

Дополнительно:

• Секреты – vault_root_token.txt передается в сервис app.
• Том – mongodb_data сохраняет данные MongoDB между перезапусками.

---

Конфигурация

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

Вам перед запуском понадобится изменить два конфигурационных файла:

1. vault-init.sh - shell-скрипт для проброса секретов (токенов, логинов, паролей) в сервис vault
2. vault_root_token.txt - файл секрета с Vault токеном, который пробрасывается через docker compose в сервис app

Переменные окружения и секреты сервиса vault (нужно сконфигурировать в vault-init.sh):

• VAULT_TOKEN - токен доступа к Vault, записывается переменной окружения во временном контейнере vault-init, его можно записать только после инициализации сервиса vault (см. ниже)
• mongo.host - хост для MongoDB
• mongo.port - порт для MongoDB
• mongo.database - имя базы данных MongoDB
• mongo.username и mongo.password - логин и пароль пользователя базы данных
• telegram.bot.token - токен Telegram-бота (можно получить у BotFather)
• telegram.bot.username - имя Telegram-бота
• superadmin.telegramId, superadmin.username, superadmin.firstName, superadmin.lastName, superadmin.password - данные для SUPER-ADMIN, который обладает особыми привилегиями при администрировании приложением

Переменные окружения сервиса mongo (нужно сконфигурировать в docker-compose.yml):

• MONGO_INITDB_ROOT_USERNAME и MONGO_INITDB_ROOT_PASSWORD - логин и пароль пользователя базы данных (должны совпадать с mongo.username и mongo.password в vault-init.sh)

Переменные окружения и секреты сервиса app (нужно сконфигурировать в docker-compose.yml и в vault_root_token.txt):

• VAULT_ADDR - адрес и порт для доступа к программе Vault в сервисе vault (!изменять не требуется!)

• VAULT_TOKEN_FILE - путь до файла vault_root_token.txt, который экспортируется в качестве секрета в контейнер сервиса app (!изменять не требуется!)

• В vault_root_token необходимо будет записать Vault токен (см. ниже)

Конфигурация секретов docker-compose:

secrets:
  vault_root_token:
    file: vault_root_token.txt

---

Развёртывание

1. Подготовка окружения

В каталог с docker-compose.yml поместите следующие файлы:

• vault-init.sh
• vault_root_token.txt

2. Запуск Vault

Поднимите отдельно контейнер vault (можно без параметра -d, чтобы логи выводились в терминале):

docker compose up -d vault --build

Затем просмотрите логи контейнера vault и найдите строку с Root Token: .... Скопируйте токен:

1. Вставьте его в vault_root_token.txt (одна строка без лишних символов);
2. Укажите этот токен в скрипте vault-init.sh в строке:

   VAULT_TOKEN=replace_this_text_with_token

3. Запуск остальных сервисов

После корректно заполненных данных в конфигурационных файлах можно запустить оставшиеся сервисы:

docker-compose up --build

Самым первым должен запуститься vault-init, который проинициализирует секреты и завершится. После его завершения должен запуститься mongo, после загрузки которого запустится и основной сервис app.

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

Запуск vault-init и mongo

Запуск app

Если вы увидели данные логи и все сервисы продолжают работать без ошибок, то уже можно пользоваться ботом.

---

Использование

HTTP эндпоинты

Метод	Путь	Описание	Права доступа
GET	/hello	Базовый «приветственный» эндпоинт. Возвращает простое текстовое сообщение («Hello, World!») для проверки доступности сервиса.	Любой (permitAll)
GET	/healthcheck	Эндпоинт для проверки «здоровья» сервиса. Возвращает информацию о состоянии приложения (проверка доступности БД).	Любой (permitAll)
PATCH	/users/{telegramId}/promote	Повысить роль пользователя с указанным telegramId. Присваивает роль ADMIN. Также передается новый пароль в теле запроса в формате JSON ({"password":"password123"})	Только ADMIN или SUPER-ADMIN
PATCH	/self_demote	Пользователь, уже обладающий ролью ADMIN, может понизить сам себя до обычного пользователя.	Только ADMIN или SUPER-ADMIN
PATCH	/users/{telegramId}/demote	Понизить роль пользователя с указанным telegramId. Удаляет роль ADMIN.	Только SUPER_ADMIN
GET	/authors	Возвращает список и информацию об авторах и администраторах бота.	Любой (permitAll)
GET	/users	Возвращает список всех зарегистрированных пользователей (кроме данных SUPER-ADMIN).	Только ADMIN или SUPER-ADMIN

Telegram команды

Управление задачами

Команда	Описание
/newtask	Создание новой одноразовой задачи. Пользователь последовательно вводит необходимые параметры (описание, дату, сложность и т. д.).
/updatetask <ID>	Редактирование ранее созданной задачи по её уникальному идентификатору. Позволяет изменить параметры задачи.
/deletetask <ID>	Удаление задачи по указанному идентификатору.
/newrepeatingtask	Создание повторяющейся задачи (ежечасной, ежедневной, еженедельной) с времени и других параметров.

Просмотр задач

Команда	Описание
/mytasks	Отображение списка всех активных (незавершённых) задач пользователя.
/today	Список задач, запланированных на текущую дату.
/week	Задачи, запланированные на текущую календарную неделю.
/date <дд.мм.гггг>	Задачи на конкретную дату, введённую в формате дд.мм.гггг.
/completed	Просмотр завершённых задач пользователя.

Служебные и информационные команды

Команда	Описание
/start	Регистрация нового пользователя и присвоение часового пояса
/status	Отображение текущего состояния бота и его ключевых компонентов.
/authors	Информация об авторах и администраторах проекта.
/help	Вывод справочного сообщения со списком команд

---

Демонстрация работы бота

Ниже представлены screenshots переписки с ботом, иллюстрирующее команды бота.

Команда /start	Команда /help
Команда /newtask	Команда /updatetask
Команда /deletetask	Команда /completed
Команда /authors	Команда /status
Напоминание об одноразовой задаче	Напоминание о просроченном дедлайне
Команды /week, /today

---

Безопасность

• Секреты (токены и учетные данные) не хранятся в коде и конфигурационных файлах — все секреты управляются через Vault.
• Сервисы изолированы в отдельных Docker-контейнерах.
• Доступ к Vault и MongoDB ограничен соответствующими политиками.

---

Лицензия

Проект распространяется под лицензией MIT. Подробнее см. файл LICENSE.

---

Авторы

• Астафьев Игорь
• Ложкина Анастасия
• Плужникова Юлия

---