Документация проекта.docx

Документация проекта<br> Проект предназначен для автоматизации взаимодействия между аккредитованными журналистами и пресс-службой через Telegram. Он включает два бота.<br> Журналистский бот – для регистрации журналистов, отправки запросов и получения уведомлений,<br> Административный бот – для управления входящими запросами, публикации материалов и контроля доступа.<br> Кроме того, проект использует Telegram-канал для официальных публикаций и админ-чат для уведомлений и логирования ключевых событий.<br> 1. Архитектура и основные компоненты<br> Проект разделён на несколько модулей.<br> Конфигурация. Файл .env содержит критичные параметры (токены ботов, ID канала, ссылки приглашений и список администраторов). Эти данные используются при инициализации и валидации доступа.<br> Хранилища данных:<br> requests.db сохраняет информацию о запросах журналистов (идентификатор, текст запроса, статус, временные метки).<br> users.db хранит данные пользователей – персональные данные, выбранный язык, статус (одобрен, заблокирован и т.п.).<br> Файлы текстов. Все сообщения, используемые ботами, находятся в файле texts.json. Он содержит шаблоны для двух языков (kz и ru), это обеспечивает поддержку многоязычного интерфейса.<br> Коммуникационные каналы.<br> Telegram-канал для публикаций утверждённых материалов.<br> Админ-чат для отправки уведомлений о событиях, входе пользователей, действиях модераторов и ошибок.<br> 3. Описание алгоритмов административного бота<br> 3.1. Аутентификация и авторизация<br> Инициализация. При старте бот загружает настройки из файла .env. Это позволяет задать токены, идентификаторы чатов и список ID администраторов.<br> Проверка прав доступа. Каждое входящее сообщение проверяется.<br> Извлекается ID отправителя;<br> Сравнивается с ADMIN_USER_IDS. Если пользователь не входит в этот список, бот отправляет сообщение о недостатке прав (текст берётся из texts.json).<br> Логирование входа. При успешном входе в бот отправляется уведомление в админ-чат с данными о пользователе (имя, ID, время входа).<br> 3.2. Обработка команд<br> Админ-бот реагирует на набор команд. Рассмотрим каждую с пошаговой логикой.<br> /publish<br> Перевод бота в режим подготовки публикации.<br> Приём данных от администратора.<br> Текст сообщения,<br> Один или несколько медиа-файлов.<br> Проверка наличия контента. Если и текст, и медиа отсутствуют, отправляется сообщение «nothing_to_publish».<br> Если контент получен, бот уведомляет администратора о возможности подтвердить публикацию, предлагая inline-кнопку «confirm_btn».<br> После подтверждения, бот пересылает подготовленный контент в канал, используя CHANNEL_ID, и отправляет уведомление об успешной публикации («publication_success»).<br> /approve <ID><br> Получение идентификатора запроса.<br> Поиск запроса в базе данных requests.db. Если запрос найден, статус обновляется на «approved».<br> Журналисту отправляется уведомление об одобрении запроса.<br> Формируется лог-сообщение с данными (ID, имя, username) и отправляется в админ-чат.<br> /decline <ID><br> Аналогично команде approve, идентификатор извлекается и ищется соответствующий запрос.<br> Статус запроса меняется на «declined», а журналист получает уведомление об отклонении.<br> Отправляется уведомление в админ-чат с деталями отклонённого запроса.<br> /block <ID><br> Проверка наличия активного статуса блокировки.<br> Если пользователь не заблокирован, обновляется статус в базе users.db.<br> Отправляется сообщение с подтверждением блокировки как пользователю, так и в админ-чат.<br> /stats<br> Бот делает выборку из базы данных по всем запросам.<br> Общее количество запросов,<br> Число одобренных, ожидающих, заблокированных запросов,<br> Количество уникальных пользователей.<br> Собранные данные подставляются в шаблон из texts.json (stats_template) и отправляются в админ-чат.<br> /change_lang<br> Бот предлагает пользователю выбор языков через inline-кнопки.<br> После выбора нового языка бот обновляет запись в базе users.db.<br> Отправляется подтверждающее сообщение (lang_changed).<br> 3.3. Inline-обработка<br> При использовании inline-кнопок (например, одобрение, отклонение, откладывание, ответ).<br> Получение callback query. Бот распознаёт идентификатор действия, который может быть передан в виде строки (например, "approve.12345" или "decline.12345").<br> Парсинг данных. Из callback-данных извлекается тип операции и ID запроса.<br> Обновление статуса. В зависимости от типа операции происходит обновление статуса в базе.<br> Для "approve" – запрос одобряется,<br> Для "decline" – запрос отклоняется,<br> Для "postpone" – запрос переводится в состояние "отложено".<br> Уведомление. После обновления, бот отправляет сообщение соответствующего содержания как журналисту (если требуется), так и в админ-чат с деталями операции.<br> 3.4. Публикация материала в канале<br> Подготовка материала. После сбора текста и медиа, бот хранит временный объект публикации.<br> Проверка содержимого. Если ни текст, ни медиа отсутствуют, публикация отменяется с уведомлением.<br> Подтверждение публикации. При нажатии кнопки «confirm_btn» бот проверяет, что контент соответствует требованиям, и отправляет его в Telegram-канал.<br> Обратная связь. После успешной публикации бот информирует администратора сообщением из texts.json («publication_success»).<br> 3.5. Логирование и отправка уведомлений<br> Все значимые действия (вход в систему, обработка запросов, публикация, ошибки) сопровождаются отправкой текстовых уведомлений в админ-чат.<br> Логирование ошибок. Если на каком-либо этапе происходит исключительная ситуация (например, невалидный формат ID или ошибка при работе с базой), отправляется уведомление с описанием ошибки и, при возможности, инициируется повторная обработка или откат транзакции.<br> 4. Описание алгоритмов журналистского бота<br> 4.1. Регистрация и сбор данных<br> Приветственное сообщение. При первом запуске бот отправляет пользователю приветственное сообщение (welcome) и справочную информацию (help_text) из texts.json.<br> Сбор персональных данных. Если пользователь не зарегистрирован, бот пошагово запрашивает.<br> Имя (ask_first_name),<br> Контактный номер (ask_phone) – с валидацией формата (например, +77011234567),<br> Email (ask_email) – также с проверкой корректности.<br> Сохранение данных. После ввода всех данных, информация сохраняется в users.db для последующей идентификации и выбора языка.<br> 4.2. Отправка запроса<br> Проверка наличия активного запроса. При попытке отправить новый запрос бот проверяет, существует ли уже активная заявка. Если да, отправляется сообщение «request_pending», и новый запрос не создаётся.<br> Ввод текста запроса. Если активного запроса нет, бот предлагает пользователю ввести текст запроса (enter_request_text). Дополнительно, пользователь может прикрепить файлы.<br> Валидация и сохранение. Введённый запрос проверяется на наличие обязательного текста (не должно быть пустым) и затем сохраняется в базе requests.db с начальным статусом «pending».<br> 4.3. Обработка команд<br> /help. Отправляет подробное сообщение со списком команд и инструкциями.<br> /cancel. Позволяет пользователю отменить активный запрос. После отмены статус изменяется на «cancelled», и отправляется уведомление (request_cancelled).<br> /change_lang. Запускает процесс смены языка, аналогичный описанному для админ-бота.<br> 4.4. Уведомления о статусе запроса<br> Автоматическая отправка уведомлений. После отправки запроса бот информирует пользователя (request_sent). При изменении статуса (одобрено, отклонено, заблокировано) бот автоматически отправляет соответствующие сообщения (например, request_approved, request_declined, blocked_info).<br> Взаимодействие с админ-ботом. Все изменения статуса запроса синхронизируются с административным модулем, что позволяет администратору отслеживать историю и оперативно реагировать на изменения.<br> 5. Работа с базами данных<br> 5.1. requests.db<br> Структура записей. Каждая запись содержит.<br> ID запроса — уникальный идентификатор.<br> Данные пользователя. Имя, фамилия, username, ID.<br> Содержание запроса. Текст и прикреплённые файлы (если применимо).<br> Статус запроса: pending, approved, declined, blocked, postponed.<br> Временные метки. Дата и время создания и последнего обновления.<br> Операции:<br> Добавление нового запроса.<br> Обновление статуса запроса (при одобрении, отклонении, отмене).<br> Выборка данных для генерации статистики (команда /stats).<br> 5.2. users.db<br> Структура записей. Содержит персональные данные пользователя: ID, имя, телефон, email, выбранный язык, статус аккаунта (например, зарегистрирован, одобрен, заблокирован).<br> Операции:<br> Регистрация нового пользователя с проверкой на дублирование.<br> Обновление данных при смене языка или изменении статуса (например, при блокировке).<br> 6. Механизм многоязычности<br> 6.1. Хранение текстовых шаблонов<br> Все сообщения для обоих ботов разделены по языковым блокам (kz, ru) в файле texts.json.<br> Каждый текстовой блок включает как приветствия, так и сообщения об ошибках, уведомления и подсказки.<br> 6.2. Алгоритм смены языка<br> При вызове команды /change_lang бот выводит варианты языков через inline-кнопки.<br> После выбора нового языка бот обновляет информацию в users.db, что позволяет при следующих обращениях выбирать нужный языковой шаблон.<br> Подтверждение смены языка отправляется с помощью сообщения lang_changed.<br> 7. Приглашения и одноразовые ссылки<br> 7.1. Механизм одноразовых ссылок<br> Генерация и проверка. При регистрации через специальную ссылку (CHANNEL_INVITE_LINK из .env) бот проверяет, не была ли эта ссылка использована ранее для данного пользователя.<br> Логирование использования. При успешном присоединении пользователя к каналу формируется уведомление, содержащее данные пользователя (ID, username) и ссылку, по которой произошёл вход.<br> Если ссылка используется повторно, бот отправляет предупреждение (invite_repeat) с информацией о повторной попытке.<br> 8. Вспомогательные функции<br> 8.1. Общие вспомогательные функции<br> Валидация входных данных. Функции для проверки корректности форматов телефонов и email, а также наличия обязательных полей.<br> Обёртки для работы с базами данных. Функции для безопасного выполнения запросов к SQLite, включая транзакционное выполнение и обработку исключений.<br> 8.2. Обработка ошибок<br> Локальные проверки. Если пользователь вводит неверный формат ID, бот отправляет сообщение «invalid_id».<br> Глобальное логирование. При возникновении ошибок в работе с базами данных или Telegram-API, бот сразу логирует ошибку, отправляя уведомление в админ-чат. Это позволяет оперативно реагировать на сбои.<br> 8.3. Логирование событий<br> Детальное логирование. Каждое важное действие (вход в бот, отправка запроса, изменение статуса, публикация) сопровождается созданием лог-сообщения с временными метками и идентификаторами пользователей.<br> Логи используются для аудита действий и последующего анализа активности системы, важно для безопасности и оптимизации работы.