Telegram Bot Визитка Профессиональное Решение

Создание бота визитки для потенциальных клиентов. В визитке разделы, сделанные Reply кнопками. ОБО МНЕ, FAQ, АКЦИИ, TEX.CTEК, ОТЗЫВЫ, ТАРИФЫ, ЗАКАЗАТЬ и удобной CSM Админ панелью внутри телеграмм. для кастомизиции кнопок и разделов в них.

1.1. Структура проекта и конфигурация Создана модульная архитектура с разделением на 9 каталогов: handlers, keyboards, database, services, utils, messages, tests, а также корневые файлы main.py, config.py, states.py, logger.py.

1.2. Конфигурация через Pydantic Settings**Реализована типизированная конфигурация с загрузкой из .env через python-dotenv и pydantic-settings. Настроена валидация токена бота, ID администраторов и каналов подписки. Добавлены свойства для удобного доступа: settings.admin_ids, settings.channel_ids, settings.is_admin(). Реализована поддержка нескольких администраторов через переменную ADMIN_IDS.

1.3. Зависимости проекта**Подключено 8 ключевых библиотек: aiogram 3.4.0+ для Telegram API, pydantic-settings 2.1.0+ для настроек, aiosqlite 0.19.0+ и asyncpg 0.29.0+ для баз данных, redis 5.0.0+ для кэширования, loguru 0.7.0+ для логирования, bleach 6.0.0+ для санитизации HTML, APScheduler 3.10.0+ для планировщика задач.

 Что было реализовано:

2.1. SQLite подключение Асинхронное подключение через aiosqlite с оптимизациями PRAGMA — journal_mode=WAL и synchronous=NORMAL. Автоматическое создание директории data/ при необходимости. Реализованы функции init_db() и get_connection().

2.2. PostgreSQL подключение Асинхронное подключение через asyncpg с поддержкой внешних сервисов Supabase, Neon, Railway. Подключение по URL-формату postgresql://user:pass@host:5432/dbname.

2.3. Универсальный адаптер Единый интерфейс DatabaseAdapter для работы с обеими СУБД. Реализованы SQLiteAdapter и PostgreSQLAdapter. Автоматический выбор базы данных по наличию переменной DATABASE_URL.

2.4. Модели данных Определено 6 таблиц: users — пользователи бота с полями telegram_id, username, created_at, last_seen, last_message_id, last_section. content — тексты разделов с полями section, text, updated_at. buttons — кнопки меню с полями name, label, is_active, order. channels — каналы подписки с полями channel_id, is_required. stats — статистика нажатий с полями button_name, button_label, clicks, last_clicked. photos — фото разделов с полями photo_type, file_id, updated_at.

2.5. Инициализация БД Автоматическое создание 6 таблиц при первом запуске. Заполнение дефолтными данными: кнопки меню, начальный контент, каналы.---

 Что было реализовано:

3.1. Хендлер /start Команда /start как точка входа для новых пользователей. Автоматическая регистрация в БД при первом запуске. Обновление поля last_seen при каждом заходе. Интеграция с проверкой обязательной подписки на каналы.

3.2. Главное меню Реализовано 7 разделов с интерактивными кнопками: Обо мне, Тех. стек, FAQ, Отзывы, Акции, Тарифы, Заказать. Контент загружается из БД через content_manager с кэшированием. Статистика нажатий сохраняется в таблицу stats. Поддержка фото для каждого раздела. Предотвращение дублирования сообщений через проверку поля last_section.

3.3. Reply клавиатуры Главное меню с кнопками 7 разделов. Кнопка Админка доступна только администраторам. Кнопка Заказать для быстрой связи.

3.4. Inline клавиатуры Inline-кнопки для навигации в админ-панели. Кнопки действий — редактировать, удалить, назад. Кнопки подтверждения и отмены.---

 Что было реализовано:

**4.1. Основной интерфейс Полноценная админ-панель с 7 функциями: редактирование текстов всех разделов, изменение названий кнопок, добавление и удаление каналов подписки, просмотр метрик пользователей и нажатий, установка фото для разделов приветствия и меню, массовая отправка сообщений, возврат к главному меню. Доступ по команде /admin или кнопке Админка.

4.2. FSM состояния Реализовано 9 состояний в AdminStates: ожидание текста контента, ожидание названия кнопки старое и новое, ожидание канала для добавления и удаления, ожидание текста рассылки, обработка пригласительной ссылки, ожидание фото приветствия и фото главного меню.

4.3. Админские клавиатуры Inline-кнопки для навигации по 7 разделам админ-панели. Кнопки подтверждения действий. Кнопки отмены и возврата.

4.4. Управление контентом CRUD-операции для 7 разделов контента. Обновление названий кнопок. Управление каналами подписки. Валидация входных данных.

4.5. Рассылка сообщений Массовая отправка сообщений всем зарегистрированным пользователям. Прогресс-бар с отображением статуса. Обработка ошибок для каждого пользователя индивидуально.

4.6. Статистика Общее количество пользователей. Прирост за 24 часа и за 7 дней. Детальная статистика нажатий по каждой из 7 кнопок с числом кликов. Возможность полного сброса статистики.---

 Что было реализовано:

5.1. Сервис проверки подписки Проверка подписки пользователя на все обязательные каналы через Telegram API. Кэширование результата с TTL 1 минута. Генерация пригласительных ссылок для неподписанных каналов.

5.2. Интеграция с /start При запуске бота автоматически проверяется подписка на все каналы из списка. Если пользователь не подписан — показывается сообщение со списком каналов и кнопками-ссылками для подписки. После подписки открывается доступ к основному функционалу.

5.3. Управление каналами из админки Добавление новых каналов по ID в формате @channel_name. Удаление каналов из списка обязательных. Валидация формата канала при вводе.---

 Что было реализовано:

6.1. Таблица photos Создана таблица для хранения фото с 3 полями: photo_type — тип фото с уникальным ограничением, file_id — Telegram file_id для повторного использования, updated_at — дата и время обновления.

6.2. Загрузка фото из админки Отправка фото боту в соответствующем FSM-состоянии. Автоматическое сохранение file_id в базу данных. Возможность замены существующего фото без удаления.

6.3. Отображение фото При открытии раздела отправляется фото вместе с текстом. Если фото не установлено — отправляется только текстовый контент. Кэширование file_id для ускорения загрузки.---

Что было реализовано:

7.1. Цепочка Middleware Реализовано 5 middleware в цепочке выполнения: DeleteUserMessageMiddleware — удаление пользовательских сообщений для чистоты интерфейса. RateLimitMiddleware — ограничение частоты запросов. DatabaseMiddleware — подключение к БД и регистрация пользователя. ServiceMiddleware — внедрение сервисов в контекст. AdminMiddleware — проверка прав администратора.

7.2. Rate Limiting Ограничение запросов: RATE_LIMIT_MAX_REQUESTS за RATE_LIMIT_WINDOW секунд. Значения по умолчанию — 10 запросов за 60 секунд. In-memory хранилище счётчиков. Информирование пользователя о превышении лимита.

7.3. Удаление сообщений Автоматическое удаление сообщений пользователя после обработки. Сохранение сообщений бота — ответы и меню не удаляются. Чистый интерфейс без лишнего шума.

7.4. HTML санитизация Очистка пользовательского ввода от опасных HTML-тегов через bleach. 7 разрешённых тегов: b, i, u, s, a, code, pre. Предотвращение XSS-атак.

7.5. Telegram ссылки Утилиты для генерации ссылок на Telegram. Форматирование ссылок для inline-кнопок.

7.6. Утилиты сообщений Общие функции форматирования сообщений. Шаблоны для стандартных ответов.---

# Что было реализовано:

8.1. Архитектура двухуровневого кэша Реализована 3-уровневая схема получения данных: L1 Local Cache со скоростью 0.1 мс, L2 Redis Cache со скоростью 1-5 мс, и база данных SQLite/PostgreSQL как источник данных. При промахе кэша запрос идёт на следующий уровень.

8.2. Local Cache In-Memory хранилище на базе dict. Настраиваемый TTL для каждого ключа. Автоматическая очистка протухших записей. 5 методов: get, set, delete, clear, stats.

8.3. Redis Cache Асинхронный клиент redis. Сериализация данных через json. Настраиваемый TTL. 5 методов: get, set, delete, clear, disconnect. Персистентность данных через AOF.

8.4. Factory инициализация Функция init_cache с автоматическим выбором бэкенда по параметру backend — redis или local. Подключение при старте бота в main.py.

8.5. Что кэшируется Контент разделов — TTL 5 минут, L1 и L2. Фото file_id — TTL 5 минут, L1 и L2. Проверка подписки — TTL 1 минута, L1 и L2. Пригласительные ссылки — TTL 2 часа, только L1. 8.6. Переключение бэкенда**Локальный режим через CACHE_BACKEND=local. Продакшен через CACHE_BACKEND=redis с указанием REDIS_URL. По умолчанию используется local.---

 Что было реализовано:

9.1. Управление контентмом Получение контента по разделу с автоматическим кэшированием. Обновление текста раздела через админ-панель. Получение и обновление названий кнопок. Статистика нажатий по каждой кнопке.

9.2. Управление сообщениями Безопасная отправка сообщений с обработкой ошибок. Удаление сообщений по ID. Редактирование существующих сообщений. Логирование всех действий.

9.3. Рассылка Массовая рассылка всем зарегистрированным пользователям. Прогресс-бар с индикацией числа отправленных. Счётчик успешных и неудачных отправок. Задержка между сообщениями для защиты от анти-спам фильтмов Telegram.

9.4. Автоматические бекапы Ежедневный бекап БД в 00:00 через APScheduler. Хранение бекапов 7 дней. Возможность ручного запуска. Стартовый бекап при каждом запуске бота. Расположение — data/backups.

9.5. Проверка подписки Проверка статуса подписки через Telegram API get_chat_member. Кэширование результатов с TTL 1 минута. Генерация пригласительных ссылок для каналов.---

 Что было реализовано:

10.1. Loguru конфигурация Консольный вывод с цветным форматированием и эмодзи, уровень из настроек. Файл ошибок logs/errors.log с ротацией 10 МБ, сжатием ZIP и хранением 30 дней. Автоматическая фильтрация — маскировка токенов и ADMIN_ID в логах.

10.2. Уровни логирования 5 уровней: DEBUG для детальной отладки, INFO для общей информации, WARNING для предупреждений, ERROR для ошибок, CRITICAL для критических ошибок.

10.3. Формат логов**Каждая строка содержит дату и время, уровень с эмодзи, путь к модулю, имя функции, номер строки и сообщение.

10.4. Специализированные функции 6 функций: log_startup — логирование запуска, log_shutdown — логирование остановки, log_admin_action — действия админа, log_database_error — ошибки БД, log_network_error — сетевые ошибки, а также стандартные logger.info, logger.error, logger.warning.---

 Что было реализовано:

11.1. Система миграций 5 миграций, автоматически применяемых при старте бота. Миграция 001 — добавление поля last_message_id в users. Миграция 002 — добавление приветствия в content. Миграция 003 — добавление поля last_section в users для предотвращения дублей. Миграция 004 — создание таблицы photos для хранения фото. Миграция 005 — добавление button_label и last_clicked в stats.

11.2. Механизм применения**Проверка текущей версии схемы перед применением. Последовательное применение только неприменённых миграций. Поддержка rollback для критичных миграций — миграция 001. Логирование каждой миграции.

11.3. Совместимость с SQLite и PostgreSQL**Условная логика для каждой СУБД. Проверка версии SQLite для поддержки DROP COLUMN — начиная с версии 3.35.0. Использование IF NOT EXISTS для PostgreSQL.

 Что было реализовано:

12.1. Dockerfile Образ на базе python:3.12-slim. Установка gcc как системной зависимости. Оптимизация Python окружения — PYTHONDONTWRITEBYTECODE=1, PYTHONUNBUFFERED=1, PIP_NO_CACHE_DIR=1. Создание непривилегированного пользователя botuser. Запуск бота от имени botuser без root-прав.

12.2. Docker Compose**2 сервиса: bot — кастомный образ из Dockerfile, redis — redis:7-alpine. Health check для Redis через redis-cli ping. 4 именованных volume — bot_data, bot_logs, bot_backups, redis_data. Изолированная сеть bot-network. Автоматический рестарт unless-stopped для обоих сервисов. Зависимость bot от redis с условием service_healthy.

12.3. Скрипт деплоя  Автоматизация развёртывания на VPS через deploy.sh. 6 шагов: проверка SSH подключения, проверка Docker и Docker Compose, копирование файлов на сервер, создание .env файла, сборка Docker образов, запуск контейнеров.

12.4. .dockerignore Исключены из образа 5 элементов: .git — история версий, __pycache__ — кэш Python, .env — секреты, logs — логи, data/backups — бекапы.---

Что было реализовано:

13.1. Системная проверка**Тест system_check.py проверяет 5 аспектов: наличие .env файла и необходимых переменных, подключение к БД, доступность Redis если включён, структуру директорий, наличие установленных зависимостей.

13.2. Тесты кэширования**Тест test_cache.py покрывает 4 группы: Local Cache — операции get, set, delete, clear и TTL. Redis Cache — подключение и операции. Factory инициализация — выбор бэкенда. Производительность — сравнение скорости отклика L1 и L2.

13.3. Документация**6 файлов документации: README.md — основное руководство, TECH_STACK.md — этапы реализации, DOCUMENTATION.md — подробная документация API, REDIS_SETUP.md — инструкция по настройке Redis, REDIS_QUICK_START.md — быстрый старт Redis, .env.example — шаблон конфигурации.---

Удобный компонент для воронки продаж. Максимально гибкий и универсальный