khasmamedov-telegram-bot

Банковское приложение с телеграмм-ботом и начинкой на java, c внешним хранилищем данных

Базовое верхнеуровневое представление:

Про проект в-общем:

1. Бот является лишь пользовательским интерфейсом, что взаимодействует с пользователем (фронт)

2. Сервис, или прослойка (движок), написанная на java, выполняет бизнес-логику и выступает прокладкой между фронтом и БД

3. Второй слой, или БД (аналог ДАО) - служит для хранения и обработки данных

GBP IT-factory | Документация(_пока пуста_) | GitHub

Команды телеграмма (видео)
Архитектура приложения (видео)
Тесты (видео)
Запуск и начало работы
Команды_бота

Весь проект на диаграмме ниже:

@startUML
actor Клиент
participant Telegram
participant Service
participant Backend

Клиент -> Telegram: Запрос на действие со счетом:\n проверить баланс,\n пополнить,\n снять деньги,\n перевести
activate Telegram
Telegram -> Service: Валидация запроса
deactivate Telegram
activate Service
alt Вернуть клиенту запрос на доработку 
    Service -> Telegram: Клиентский запрос содержит ошибки
    deactivate Service
    activate Telegram
    Telegram -> Клиент: Клиент перепроверяет запрос;\n завершает работу, либо шлет запрос заново
    deactivate Telegram
else Запрос уже прошел цепочку клиент-телеграм-сервис + в сервисе успешно прошел проверку
    activate Service
    Service -> Service: Бизнес-логика
    Service -> Backend: Обработка данных
    deactivate Service
    activate Backend 
    Backend -> Service: Возврат успешности операции и\или \n данных, если они были запрошены
    deactivate Backend 
    activate Service
    Service -> Telegram: Дополнительная обработка данных (если требуется)
    deactivate Service
    activate Telegram
end    
Telegram -> Клиент: возврат данных
deactivate Telegram
@endUML

Как_запустить_и_начать_работу

Подготовка программ/окружения

Для локальной установки приложения вам понадобятся Git, Java 21, Gradle, IDEA

Получение токена

Вам нужен токен (действует как пароль), если его еще нет:
см. документацию

Способы запуска приложения - standAlone (1 и 2) и основной - как докер-приложение (3)

Получение проекта

Скачать проект с репозитория выше целиком перейдя по ссылке на гитхаб
code -> download zip
Распаковать архив, добавить в среду разработки как новый проект
Либо, склонировать его
git@github.com:gpb-it-factory/khasmamedov-middle-service.git
примечание про зависимости

Запуск проекта отдельно (1, 2)

Собрать проект в готовый к исполнению файл
gradle build (если есть установленный грэдл)
- ИЛИ же .\gradlew build (если Windows и грэдла нет)
- ИЛИ же chmod +x gradlew ./gradlew build (если Linux и грэдла нет)
Запустить его с параметрами:
java -jar ./build/libs/khasmamedov-telegram-bot-0.0.1-SNAPSHOT.jar --bot.token="здесь ваш токен"
примечание про пути
ИЛИ же - запуск проекта "под ключ":
.\gradlew.bat bootRun --args='--bot.token=<здесь ваш токен>' (Windows)
./gradlew.bat bootRun --args='--bot.token=<здесь ваш токен>' (Linux)
!ВАЖНО: <> нужно удалять, токен будет в 'НАЗВАНИЕ_ТОКЕНА' как выйти из приложения

Запуск проекта через докер (3)

Если у вас еще нет докера, нужно его скачать:
ссылка на докер
Создать в докере image (посмотреть docker -> images в системе)
docker build -t telegram-bot .
возможная ошибка сборки
Запустить приложение:
- В фоновом режиме:
  docker run --name telegram-bot -d -e BOT_TOKEN="здесь ваш токен" telegram-bot
  чтобы выйти в этом случае - набрать в терминале: docker stop telegram-bot
- С отображением результатов работы программы, включая логи и возможные ошибки: docker run --name telegram-bot -it -e bot.token="здесь ваш токен" telegram-bot
  выход из приложения <span title="Если вы видите ошибку типа docker: Error response from daemon: Conflict. The container name "/имя контейнера" is already in use by container "длинное имя". You have to remove (or rename) that container to be able to reuse that name.,
  вам потребуется остановить это контейнер перед тем как запускать программу:
  docker stop 23a960d080bd5798917cb70c5a33992c3ae2a715a9cd0187822cab80f632973e docker rm 23a960d080bd5798917cb70c5a33992c3ae2a715a9cd0187822cab80f632973e">примечание про ошибки контейнеров

После запуска приложения можно открывать телеграм web-версию, найти @SomeBankBot и использовать Команды_бота в нем

Команды_бота

Список команд бота на настоящий момент:

Обычные текстовые команды

Здесь сейчас нет команд, но в дальнейшем возможно наполнение функционалом команд, например /help и пр.

любая не зарегистрированная команда (см. ниже) сейчас выдает -> no such command

Команды пользователя с полным функционалом

Регистрация

Создать нового пользователя

Ввести /register в ТГ-боте

Ответ в случае успеха: Пользователь создан
Ответ в случае попытки повторной регистрации того же пользователя: Пользователь уже зарегистрирован: statusCode
Ошибка создания пользователя: Ошибка при регистрации пользователя: statusCode
Прочие ошибки: Не могу зарегистрировать, ошибка: детальное описание ошибки или Произошла серьезная ошибка: детальное описание ошибки

Получить пользователя по идентификатору в Telegram
пока не реализовано

Счета

Открыть новый счёт для пользователя

Ввести /createaccount в ТГ-боте
Ответ в случае успеха: Счет создан (при открытии нового счета на баланс автоматически кладется 5000 рублей)

Ответ в случае попытки повторной регистрации того же пользователя: Такой счет у данного пользователя уже есть: statusCode
Ошибка создания пользователя: Ошибка при создании счета: statusCode
Прочие ошибки: Не могу зарегистрировать счет, ошибка или Произошла серьезная ошибка во время создания счета: детальное описание ошибки
открытие счёта в нашем Мини-банке. В данный момент у клиента может быть только один счёт

Получить счета пользователя

Ввести /currentbalance в ТГ-боте
Ответ в случае успеха: Список счетов пользователя: + список счетов (сейчас у пользователя 1 счет)

Возможный ответ в случае отсутствия счетов: Нет счетов у пользователя
Ошибка получения: Не могу получить счета (пустой ответ // не найдено счетов)
Прочие ошибки: Не могу получить счета, ошибка: + ошибка (расшифровка) или Произошла серьезная ошибка во время получения счетов: + ошибка (расшифровка)

Переводы

Создать перевод со счёта пользователя на счёт другого пользователя

Ввести /transfer [toTelegramUser] [amount] в ТГ-боте, где:
toTelegramUser - пользователь, на счёт которого совершается перевод, amount - сумма перевода.
Сумма перевода должна быть положительной и команда должна быть в точности как написано выше
Ответ в случае успеха: Перевод успешно выполнен, ID перевода: + transferId (айди)

Возможный ответ в случае наличия ошибки перевода: Не могу совершить денежный перевод: + currentStatus (статус ошибки)
Прочие ошибки: Не могу выполнить денежный перевод, ошибка: + responseErrorString (расшифровка) или Произошла серьезная ошибка во время выполнения денежного перевода: + ошибка (расшифровка)