Skip to content
BranchesTags

Repository files navigation

MTLA Join Bot

Телеграм-бот для проверки формальных критериев и подготовки заявки на вступление в Ассоциацию Монтелиберо.

Утверждённая целевая семантика

  • /start всегда начинает новую попытку, а не возобновляет прежнюю.
  • Telegram username настоятельно рекомендуется, но не является обязательным критерием.
  • Доказательство владения Stellar-адресом не требуется.
  • Для рекомендации достаточно одной RecommendToMTLA от адреса с балансом MTLAP >= 2.
  • После успешных проверок бот сообщает, что кандидат готов самостоятельно подать заявление через обратную связь движения. Фактическую подачу и решение Ассоциации бот не отслеживает.
  • Проверка рекомендации должна использовать данные конкретного аккаунта BSN, а не скачивать полный bsn.json для каждого действия.

Основные правила процесса закреплены тестами. Рекомендации проверяются через per-account BSN endpoint, а достаточный баланс рекомендателя — по актуальному состоянию точного MTLAP asset в Horizon.

Текущая реализация

  • Автоматическое определение языка пользователя (русский/английский)
  • Пошаговая проверка критериев вступления
    • Проверка наличия юзернейма
    • Согласие с условиями Соглашения
    • Ввод и проверка Стеллар адреса
      • Проверка линии доверия к токену MTLAP
      • Проверка BSN рекомендаций от верифицированных участников МТЛА
  • Хранение данных в MongoDB
  • Отслеживание прогресса пользователей
  • Административные инструменты для анализа

Требования

  • Python 3.11
    • python-telegram-bot - для работы с Telegram API
    • stellar-sdk - для работы со Стеллар блокчейном
    • pymongo - для работы с MongoDB
    • python-dotenv - для загрузки переменных окружения
    • aiohttp - для асинхронных HTTP запросов к BSN Expert
  • MongoDB 4.0+
  • Доступ к интернету для работы с Telegram API и Stellar Network
  • Доступ к BSN Expert API для проверки рекомендаций

Установка

Вариант 1: Локальная установка

  1. Клонируйте репозиторий:
git clone <repository-url>
cd MTLA_join_bot
  1. Установите зависимости:
pip install -r requirements.txt
  1. Установите и запустите MongoDB:
# Ubuntu/Debian
sudo apt-get install mongodb

# macOS (с Homebrew)
brew install mongodb-community
brew services start mongodb-community

# Или используйте Docker
docker run -d -p 27017:27017 --name mongodb mongo:7.0
  1. Создайте файл .env на основе env_example.txt:
cp env_example.txt .env
chmod 600 .env
  1. Отредактируйте .env файл, указав:
    • TELEGRAM_TOKEN - токен вашего бота от @BotFather
    • ADMIN_IDS - ID администраторов через запятую (например: 123456789,987654321)
    • MONGODB_URI - URI для подключения к MongoDB
    • MONGODB_DB - название базы данных
    • MONGODB_COLLECTION - название коллекции

Запуск

Локальный запуск

python main.py

Запуск в Docker

  1. Убедитесь, что установлен Docker

  2. Создайте файл .env на основе env_example.txt:

    cp env_example.txt .env
chmod 600 .env
# Отредактируйте .env файл, указав TELEGRAM_TOKEN и ADMIN_IDS

    Файл .env исключён из Docker build context и не попадает в образ. Compose передаёт его только сервису бота при запуске. После изменения .env достаточно перезапустить сервисы; пересобирать образ не требуется. Это совместимый режим, но значение TELEGRAM_TOKEN остаётся доступно администраторам Docker через сведения о контейнере.

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

    MTLA_JOIN_BOT_ENV_FILE=/secure/path/mtla-join-bot.env ./docker-simple.sh run

    Для production предпочтителен отдельный файл, содержащий только Telegram token. Удалите строку TELEGRAM_TOKEN из общего env-файла, ограничьте доступ к обоим файлам и передайте абсолютный путь:

    chmod 600 /secure/path/mtla-join-bot.env /secure/path/telegram-token
MTLA_JOIN_BOT_ENV_FILE=/secure/path/mtla-join-bot.env \
MTLA_JOIN_BOT_TELEGRAM_TOKEN_FILE=/secure/path/telegram-token \
./docker-simple.sh run

    В этом режиме token подключается через Compose secret read-only в /run/secrets и не сохраняется в Docker image или Config.Env.

    compose.yaml запускает два отдельных сервиса: bot и MongoDB 7.0. MongoDB закреплена по digest, имеет healthcheck и хранит данные в прежнем named volume mtla_join_bot_data; остановка сервисов volume не удаляет. Bot запускается непривилегированным пользователем и стартует только после готовности MongoDB.

  3. Запустите бота:

    # Только для действительно новой пустой установки, один раз:
./docker-simple.sh bootstrap

# Собрать образ и запустить
./docker-simple.sh build && ./docker-simple.sh run

    Если production volume уже должен существовать, не запускайте bootstrap: отсутствие mtla_join_bot_data означает ошибку имени, хоста или восстановления, и run намеренно завершится без запуска пустой базы.

  4. Проверьте статус:

    ./docker-simple.sh status

  5. Посмотрите логи:

    ./docker-simple.sh logs

  6. Остановите бота:

    ./docker-simple.sh stop

Docker команды

  • Сборка образа: ./docker-simple.sh build
  • Явно создать пустой volume новой установки: ./docker-simple.sh bootstrap
  • Запуск: ./docker-simple.sh run
  • Остановка: ./docker-simple.sh stop
  • Логи: ./docker-simple.sh logs
  • Перезапуск: ./docker-simple.sh restart
  • Очистка данных после backup: MTLA_JOIN_BOT_CONFIRM_CLEAN=YES ./docker-simple.sh clean
  • Войти в контейнер: ./docker-simple.sh shell

Production-релизы собираются в GitHub Actions и публикуются в GHCR с обычным тегом latest и неизменяемыми тегами версий. Portainer Swarm stack, первый перенос MongoDB в отдельный сервис, проверки и откат описаны в docs/RELEASE.md.

Структура проекта

MTLA_join_bot/
├── src/
│   └── mtla_bot/           # Основной пакет
│       ├── __init__.py     # Инициализация пакета
│       ├── bot.py          # Основной файл бота
│       ├── config.py       # Конфигурация и настройки
│       ├── stellar_client.py # Клиент для работы со Стеллар блокчейном
│       ├── eligibility.py  # Чистые правила допуска кандидата
│       ├── recommendation_gateway.py # Per-account BSN и live Horizon
│       ├── user_states.py  # Управление состояниями пользователей
│       ├── database.py     # Модуль для работы с MongoDB
│       ├── admin_tools.py  # Административные инструменты
│       ├── admin_config.py # Конфигурация администраторов
│       └── messages.py     # Тексты сообщений на разных языках
├── main.py                 # Точка входа для запуска
├── requirements.txt        # Зависимости проекта
├── Dockerfile              # Bot-only Docker image
├── compose.yaml            # Bot + отдельная MongoDB
├── compose.secret.yaml     # File-secret override
├── docker-simple.sh        # Безопасная обвязка Docker Compose
└── .env                   # Переменные окружения

Команды бота

  • /start - начать процесс заново
  • /restart - начать процесс заново
  • /language - сменить язык

Административные команды

Бот поддерживает административные команды для мониторинга и анализа:

  • /stats - показывает статистику по пользователям
  • /incomplete - показывает незавершенных пользователей
  • /reminders [дни] - показывает кандидатов для напоминания (по умолчанию 7 дней)
  • /user_info <user_id> - показывает детали конкретного пользователя
  • /help_admin - показывает справку по административным командам

Настройка администраторов

  1. Получите ваш Telegram ID у бота @userinfobot
  2. Добавьте ваш ID в переменную ADMIN_IDS в файле .env
  3. Перезапустите бота

Пример в .env файле:

ADMIN_IDS=123456789,987654321

Текущий реализованный процесс

  1. Рекомендация юзернейма - при его отсутствии бот настоятельно рекомендует установить username, но позволяет явно продолжить без него
  2. Согласие с условиями - пользователь должен согласиться с Соглашением
  3. Ввод Стеллар адреса - пользователь вводит свой адрес с возможностью получить справку
  4. Проверка адреса - проверяется существование адреса и линия доверия к MTLAP
  5. Проверка рекомендаций - проверяется наличие рекомендации от верифицированного участника (минимум 2 MTLAP токена)
  6. Завершение - если все проверки пройдены, бот сообщает, что кандидат готов подать заявление через обратную связь движения

Особенности интерфейса

  • Обычные клавиатурные кнопки вместо inline кнопок для лучшего UX
  • Раздельные сообщения для каждой проблемы (не один длинный список)
  • Автоматическое очищение кнопок при переходе между шагами
  • Контекстная помощь с ссылками на статьи и чаты

База данных MongoDB

Бот использует MongoDB для хранения данных пользователей. Структура документа пользователя:

{
  "user_id": 123456789,
  "username": null,
  "attempt_id": "7fa8e4d6d4994c7f86aab8f9bf43c424",
  "language": "ru",
  "state": "checking_username",
  "stellar_address": "G...",
  "has_username": false,
  "username_warning_acknowledged": true,
  "agreed_to_terms": true,
  "has_trustline": true,
  "candidate_mtlap_balance": "0",
  "has_recommendation": false,
  "recommender_username": null,
  "created_at": "2024-01-01T00:00:00Z",
  "last_activity": "2024-01-01T00:00:00Z",
  "progress": {
    "username_check": false,
    "agreement": true,
    "address_entered": true,
    "trustline_check": true,
    "recommendation": false
  }
}

/start и /restart создают новый attempt_id и сбрасывают текущий прогресс. Inline-кнопки процесса привязаны к попытке, поэтому кнопка из старого запуска не может изменить новый процесс. Поле username допускает null.

Тесты

PYTHONPATH=src python -m unittest discover -s tests -q

Проверочные и финальные поля

  • candidate_mtlap_balance - канонический баланс кандидата из проверенного snapshot
  • has_recommendation - есть ли квалифицированная рекомендация
  • final_delivery_message_id - Telegram message ID доставленного финального ответа
  • final_delivered_at - время подтверждённой доставки
  • final_delivery_attempts - общее число попыток отправки результата

Состояние finalizing означает, что все факты уже сохранены, но доставку финального ответа или запись completed нужно повторить. Бот автоматически подбирает такие записи после восстановления сервиса и после перезапуска; каждая отправка сначала получает атомарный lease, а после трёх записанных попыток фон перестаёт отправлять сам. Явная кнопка кандидата остаётся доступна: она повторяет только доставку, а не проверки. Доставка at-least-once, поэтому при редком сбое между Telegram и MongoDB финальное сообщение может прийти повторно.

Административные функции

Модуль admin_tools.py предоставляет инструменты для анализа данных:

from mtla_bot.admin_tools import AdminTools

admin = AdminTools()

# Получить статистику
stats = admin.get_user_statistics()

# Получить незавершенных пользователей
incomplete = admin.get_incomplete_users_report()

# Получить кандидатов для напоминания
reminders = admin.get_reminder_candidates(days_inactive=7)

# Получить детали пользователя
user_details = admin.get_user_details(user_id=123456789)

Новые функции

Проверка рекомендаций

Бот интегрирован с BSN Expert для проверки рекомендаций:

  • Загрузка входящих RecommendToMTLA только для проверяемого аккаунта
  • Проверка live-баланса рекомендателя (минимум 2 MTLAP точного issuer)
  • Ограниченные timeout, retry, размер ответа и параллельность запросов
  • Информативные сообщения о статусе рекомендаций
  • Ссылки на чат Площади для получения рекомендаций

Улучшенный интерфейс

  • Обычные клавиатурные кнопки для лучшего UX
  • Раздельные сообщения для каждой проблемы
  • Автоматическое очищение кнопок при переходах
  • Контекстная помощь с эмодзи и ссылками

Настройка

Ссылки и конфигурация

В файле config.py можно настроить:

  • Ссылки на инструкции и статьи
  • Адрес токена MTLAP
  • Сеть Стеллар (mainnet/testnet)
  • Параметры подключения к MongoDB
  • Ссылки на чаты и боты для помощи

Добавление новых языков

В файле messages.py добавьте новый язык в словарь MESSAGES и соответствующие ссылки в config.py.

Мониторинг и аналитика

Бот автоматически отслеживает:

  • Прогресс каждого пользователя
  • Время создания и последней активности
  • Распределение пользователей по состояниям
  • Пользователей для напоминания

При необработанной технической ошибке бот отправляет безопасное сообщение о временной недоступности вместо молчания. Ошибки BSN/Horizon не записываются как отсутствие обязательного условия.

Лицензия

MIT License

About

Telegram bot for application to MTLA

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages