Перейти к содержанию

telegram_bot_service

1. Назначение

telegram_bot_service реализует Telegram-канал оплаты и выдачи цифровых файлов заказа. Бот работает на aiogram, взаимодействует с order_service и product_service.

2. Основные команды и события

  • /start — вход в сценарий.
  • Ввод номера заказа в состоянии waiting_for_order_number.
  • pre_checkout_query — валидация перед платежом.
  • successful_payment — фиксация оплаты.
  • Admin callback: admin_accept_payment_<order_number>.

3. FSM-состояния

  • waiting_for_order_number
  • waiting_for_payment
stateDiagram-v2
  [*] --> waiting_for_order_number: /start
  waiting_for_order_number --> waiting_for_payment: invoice sent
  waiting_for_order_number --> [*]: invalid or already_paid handled
  waiting_for_payment --> [*]: successful_payment
  waiting_for_payment --> waiting_for_payment: any other message

4. Интеграции API

order_service

  • GET /api/orders/by_number/{order_number}/
  • POST /api/orders/update_payment_status_by_number/{order_number}/
  • POST /api/orders/upload_zip/{order_number}/{order_item_id}/
  • POST /api/orders/update_status_by_number/{order_number}/ (логически предусмотрен)

product_service

  • GET /api/models/{model_3d_id}/ (получение parts_xlsx_file_url)
  • загрузка XLSX/медиа по URL для формирования ZIP

5. Бизнес-логика

  • Номер заказа валидируется regex ORD-[A-Z0-9]{8}.
  • Для pending-заказа формируется Telegram invoice.
  • После подтверждения оплаты:
  • обновляется payment status в order-service;
  • формируются ZIP по позициям;
  • ZIP отправляются пользователю;
  • ZIP загружаются в order-service для хранения.

6. Конфигурация

  • TELEGRAM_BOT_TOKEN (обязателен)
  • ORDER_SERVICE_URL
  • PRODUCT_SERVICE_URL
  • TELEGRAM_PAYMENTS_PROVIDER_TOKEN (объявлен, но фактически не задействован в текущем сценарии Stars)

7. Риски

  • Критичность публичных bot-endpoint-ов order-service (AllowAny).
  • Блокирующие HTTP-запросы requests внутри async-handlers.
  • Недостижимый участок кода обновления delivered после раннего return.
  • Жесткая привязка admin-id в обработчике ручного подтверждения.

8. Диаграмма happy-path оплаты

sequenceDiagram
  participant T as TelegramUser
  participant B as telegram_bot_service
  participant O as order_service
  participant P as product_service

  T->>B: /start + order number
  B->>O: GET by_number
  B-->>T: send invoice
  T->>B: successful payment
  B->>O: POST update_payment_status_by_number(paid)
  B->>P: GET model + xlsx metadata
  B->>B: build zip files
  B->>T: send documents
  B->>O: POST upload_zip

9. Дополнительная детализация внутренних функций (append-only)

9.1 Основные функции обработчиков и оркестрации

main() (entrypoint polling)

  • Источник: telegram_bot_service/bot_app/bot.py
  • Назначение: инициализация Bot/Dispatcher и запуск polling.
  • Вход:
  • TELEGRAM_BOT_TOKEN из env.
  • Выход:
  • долгоживущий polling loop.
  • Ошибки:
  • при пустом token запуск не продолжается.

cmd_start(message, state)

  • Источник: telegram_bot_service/bot_app/handlers.py
  • Назначение: старт FSM-сценария оплаты.
  • Вход:
  • Telegram Message, FSM context.
  • Выход:
  • приветственное сообщение и переход в waiting_for_order_number.
  • Side effects:
  • запись состояния FSM.

process_order_number(message, state)

  • Назначение: принять номер заказа, проверить его в order-service и подготовить оплату/выдачу.
  • Вход:
  • текст сообщения пользователя.
  • Выход:
  • invoice, сообщение об ошибке или ветка для уже оплаченного заказа.
  • Side effects:
  • HTTP-запросы в order-service;
  • отправка сообщений и inline-кнопок в Telegram;
  • переходы FSM.

process_pre_checkout(pre_checkout_query, state)

  • Назначение: финальная валидация заказа перед подтверждением платежа.
  • Выход:
  • pre_checkout_query.answer(ok=True/False).

process_payment(message, state)

  • Назначение: обработать successful_payment и запустить выдачу файлов.
  • Side effects:
  • обновление статуса оплаты в order-service;
  • запуск пайплайна сборки/отправки ZIP;
  • отправка итоговых сообщений пользователю.

9.2 Вспомогательные интеграционные функции

make_service_request(method, url, **kwargs)

  • Источник: telegram_bot_service/bot_app/handlers.py
  • Назначение: единая обертка HTTP-вызовов внешних сервисов.
  • Выход:
  • объект requests.Response.
  • Ошибки:
  • сетевые исключения поднимаются в вызывающий код.

create_zip_from_parts_xlsx(parts_xlsx_url, model_name, base_url)

  • Назначение: собрать архив деталей по XLSX.
  • Вход:
  • URL XLSX, имя модели, базовый URL сервиса.
  • Выход:
  • путь к временному ZIP и список отсутствующих деталей (в случае частичных данных).
  • Side effects:
  • загрузка XLSX по сети;
  • поиск STL-файлов на локальном диске;
  • создание temp ZIP.

send_zip_files_for_order(order_data, message, order_number, lang)

  • Назначение: end-to-end выдача файлов по всем позициям заказа.
  • Выход:
  • агрегированные результаты отправки (zip_files_sent, zip_files_created, missing_parts_all).
  • Side effects:
  • запросы в product/order сервисы;
  • отправка документов пользователю в Telegram;
  • загрузка ZIP обратно в order-service;
  • создание и удаление временных файлов.

9.3 Admin и i18n вспомогательные функции

is_admin_user(user_id, username=None)

  • Назначение: проверить, имеет ли пользователь право ручного admin-accept flow.
  • Вход:
  • user_id, опционально username.
  • Выход:
  • bool.

handle_admin_accept_payment(callback_query)

  • Назначение: ручное подтверждение оплаты администратором.
  • Side effects:
  • смена статуса оплаты заказа;
  • повторный запуск ZIP-delivery flow;
  • отправка служебных сообщений.

t(key, lang='ru', **kwargs) и get_user_language(user_id=None)

  • Источник: telegram_bot_service/bot_app/translations.py
  • Назначение:
  • t: получить локализованную строку с fallback;
  • get_user_language: определить язык пользователя (в текущей версии стабильно ru).

9. Соответствие master-документации

Источник верхнего уровня: Master-документация проекта.

Контроль Требование Проверка Артефакт
Bot integration Bot-сценарии согласованы с order/admin контрактами e2e smoke bot flow test notes
Delivery reliability Отправка файлов и уведомлений имеет fallback проверка retry/error handling operations report
Security hygiene Токены и чувствительные данные не попадают в логи/docs ревью конфигурации и сообщений security checklist
Localization consistency Локализация и fallback поведение предсказуемы проверка ключевых шаблонов QA checklist