Telegram Admin Bot 🤖

Gifty Admin Bot — это ваш персональный ассистент и панель управления всей экосистемой Gifty. Он предназначен для мониторинга системы, управления парсингом, взаимодействия с командой через Weeek и получения оперативных уведомлений.

🚀 Начало работы (Онбординг)

Регистрация

Для входа в систему администрирования вам понадобится секретный ключ (для суперадмина) или приглашение с персональным паролем от ментора.

Найдите бота @giftyai_team_bot в Telegram и нажмите /start.
Если у вас есть секретный ключ (из .env файла), введите: /start <ваш_секретный_ключ>
Если вы новый участник команды, введите полученный от ментора пароль: /start <пароль_из_приглашения>
Дождитесь подтверждения регистрации.

IMPORTANT

Для регистрации по приглашению у вас должен быть установлен Telegram username.

Запрос доступов

Через бота можно отправлять запросы на доступы (GitHub, SSH-доступ к базе и др.). Ориентируйтесь на меню и встроенные подсказки бота.

🔐 Роли и права доступа

Доступ в боте разграничен на основе ролей и разрешений (permissions).

Право	Описание
`all`	Полный доступ ко всем функциям системы.
`stats:view`	Просмотр аналитики пользователей (DAU/MAU) и конверсий.
`system:health`	Мониторинг технического состояния (нагрузка, память, ошибки).
`parsing:manage`	Управление пауками, изменение URL и мониторинг наполнения.
`tasks:manage`	Полная интеграция с Weeek (создание, перенос, закрытие задач).
`notifications:manage`	Настройка подписок на уведомления.

🛠 Основные функции

📊 Статистика (Stats)

Раздел позволяет отслеживать активность пользователей:

Summary: Краткая сводка за 24 часа.
DAU (7d): График активных пользователей за неделю.
MAU (12m): Тренд роста базы за год.
Technical: Технические метрики использования API.

🚀 Состояние (Health)

Мониторинг инфраструктуры в реальном времени:

Время отклика (Latency) основного API.
Количество ошибок (5xx).
Использование ресурсов (Redis, Диск).

🕷 Парсинг (Scraping)

Управление сбором данных с магазинов-партнеров:

Просмотр активных воркеров.
Список "сломанных" источников, требующих внимания.
Mini App Dashboard: Встроенное веб-приложение для детальной настройки пауков (требует HTTPS).

📝 Задачи (Tasks)

Полная синхронизация с Weeek:

Просмотр списка своих задач.
Создание новых задач прямо из Telegram.
Смена дедлайнов и закрытие задач.
Онбординг: специальный чеклист для новых участников команды.

🔔 Подписки

Настройка мгновенных уведомлений в Telegram по темам:

investors: Новые заявки от инвесторов.
partners: Предложения о партнерстве.
system: Критические ошибки и алерты мониторинга.
scraping: Отчеты о завершении циклов парсинга.

🌐 Языки

Бот полностью локализован на Русский (🇷🇺) и Английский (🇺🇸) языки. Сменить язык можно в главном меню кнопкой "Язык".

💻 Разработка и локальный запуск

Запуск бота

Бот запускается из корня проекта:

python -m services.telegram_bot.app.main

Обработка Web App (Dashboard)

Telegram Web App требует HTTPS. Для локальной разработки используйте ngrok или localtunnel:

Запустите фронтенд дашборда на порту 5173.
Пробросьте порт через ngrok: ngrok http 5173.
Укажите полученный HTTPS URL в поле TELEGRAM_WEBAPP_URL в конструировании кнопки (или в .env).

ℹ️ Помощь и справка

Команда /help всегда выведет краткую инструкцию и список доступных действий.