Технічна документація: Telegram‑бот Smart Reports bot

Вступ

Телеграм‑бот Smart Reports bot — це автоматизований помічник для мережі ресторанів та служб доставки. Бот інтегрується з локальним сервером Syrve та хмарним API Syrve Cloud, виконує моніторинг процесів, надсилає попередження та формує звіти. Його мета — допомагати менеджерам оперативно реагувати на проблеми без необхідності входу в систему лояльності.

Бот реалізований з використанням асинхронного фреймворку aiogram 3 та планувальника APScheduler. Основні можливості охоплюють моніторинг кухні та доставки, контроль виручки, формування регулярних і on‑demand звітів, а також управління користувачами та чатами.

Основні функції

Моніторинг кухні та доставки. Бот регулярно опитує API Syrve Cloud і попереджає, коли час приготування або доставки перевищує задані порогові значення.
Контроль виручки. Користувач може встановити ліміт виручки для кожної точки; бот надсилає повідомлення, якщо поточна виручка перевищує цей ліміт, і надає можливість підтвердити інкасацію.
Формування звітів. Бот вміє відправляти короткі та детальні звіти про виручку, роботу кухні, доставку та персонал за розкладом або за запитом.
Управління користувачами, адміністраторами та чатами. Адміністратор може додавати користувачів, визначати для них доступні організації, призначати адмінів та керувати чатами, у які надсилаються звіти.
Гнучке налаштування. Параметри задаються через змінні середовища та конфігураційні файли (JSON), що дозволяє адаптувати бота під конкретну мережу.

Опис сервісів

1. DeliveryService

Використовується для роботи з доставками. Підраховує кількість доставок за сьогодні, обчислює середній час, знаходить затримки («черепахи»). Порогове значення затримки задається змінною SLOW_LIMIT_MIN (за замовчуванням 51 хв).

2. KitchenService

Обробляє дані про відкриті замовлення (зал і доставка). Для кожного замовлення визначає час перебування на кухні (kitchenDuration) та перевищення порогу KITCHEN_SLOW_MIN (21 хв за замовчуванням). Повертає:

Суму й кількість замовлень у роботі.
Максимальний час перевищення.
Список замовлень‑черепах.

3. ReportService

Формує звіти за організаціями. Основні методи:

build_report_for_org(org) — детальний звіт (виручка, кухня, персонал).
totals_for_org(org) — стислий набір показників.
monitor_kitchen() — використовується планувальником для контролю кухні.
broadcast_report() / broadcast_all_orgs() — надсилання звітів у чати.

4. DailyReportService

Обчислює загальний денний звіт для користувача: сумарний виторг, кількість замовлень, кількість доставок, середній чек.

5. EmployeeService

Забезпечує підрахунок персоналу за потрібними ролями. Використовується у звітах.

6. RevenueWatcher

Періодично перевіряє виручку за сьогодні щодо встановленого ліміту для кожного користувача. Якщо виручка перевищує ліміт, бот надсилає попередження з кнопкою «Інкасація зроблена». При натисканні бот зберігає поточний рівень виручки як базовий (since). Ліміти зберігаються у revenue_limits.json і автоматично оновлюються.

7. KitchenWatcher

Перевіряє кухню кожні N хвилин (за замовчуванням 1 хв). Надсилає повідомлення лише тоді, коли з’являються нові черепахи, щоб запобігти спаму. Присутній механізм антиспаму: повідомлення надсилаються не частіше ніж раз у 320 секунд.

8. DeliveryWatcher

Аналізує доставку кожні N хвилин (за замовчуванням 15). Для кожного чату відслідковує середній час та список затримок; повідомлення надсилаються лише при зміні цих показників. Кнопки в повідомленні дозволяють переглянути деталі конкретного замовлення.

9. Планувальник (Report Scheduler)

Файл report_scheduler.py містить налаштування CRON‑триґерів APScheduler. За замовчуванням:

Снепшоти виручки: 13:00, 16:00, 19:00, 22:00.
Снепшоти персоналу: 09:00, 10:00, 13:00, 16:00, 19:00, 22:00.
Моніторинг кухні та доставки: щохвилини.

Адміністратори можуть змінити CRON‑вирази для іншого графіку.

Команди

Загальнодоступні

/start, /help — показує довідкову інформацію.
/ping — перевірка роботи бота (повертає «pong»).
/report — детальний звіт для однієї точки або меню вибору (якщо кілька точок).
/report all — зведений звіт по всіх доступних організаціях.
/kitchen — контроль кухні; показує кількість активних замовлень, суму і максимальний час перевищення, кнопки ведуть до деталей.
/kitchen <номер> — детальна картка замовлення за номером (доставка або зал).
/delivery — зведення по доставках за сьогодні; включає середній час та максимальні затримки.
/delivery <UUID або номер> — показує деталі конкретного замовлення.
/daily — денний підсумковий звіт для користувача (сумарний виторг, кількість замовлень, доставок, середній чек).
/limits — перегляд встановлених лімітів виручки.
/cancel — скасувати поточну операцію (використовується в діалогах).

Команди для адмінів

/setlimit — встановлення ліміту виручки. Адмін вибирає точку та вводить ліміт.
/dellimit — видалення ліміту виручки.
/users — перегляд користувачів та їх точок.
/adduser <telegram_id> — додати користувача у whitelist та вибрати точки.
/removeuser <telegram_id> — видалити користувача із whitelist та очистити його точки.
/addadmin <telegram_id> — призначити користувача адміном.
/removeadmin <telegram_id> — прибрати користувача зі списку адмінів.
/addchat — додати поточний чат до розсилки.
/removechat — прибрати поточний чат із розсилки.
/autorpt — ручний запуск автоматичної розсилки звітів.

Вибір організацій (точок)

Коли адмін додає користувача, бот пропонує вибрати, до яких організацій (точок) той матиме доступ. Вибір здійснюється через інтерактивні кнопки. Інформація про відповідність користувачів точкам зберігається в user_orgs.json. Користувачі можуть переглядати звіти лише за вибраними точками.

Ліміти виручки

Ліміт задається у гривнях для конкретного користувача та точки.
Бот відстежує різницю між поточною виручкою за день та значенням since. Якщо перевищення понад ліміт — надсилає попередження з кнопкою «Інкасація зроблена».
Натиснувши кнопку, користувач підтверджує інкасацію: поточний виторг зберігається у since, відлік починається заново.
Для скасування інкасації є кнопка «↩️ Скасувати», яка повертає попередній стан.
Ліміти зберігаються у файлі revenue_limits.json та підтримують автоочищення для нового дня.

Моніторинг кухні та доставки

Пороги. Значення порогу для кухні (KITCHEN_THRESHOLD) та доставки (DELIVERY_THRESHOLD) можна задати через змінні середовища або .env.
Фільтрація. Бот повідомляє лише про замовлення, що перевищили порогові значення, щоб уникнути спаму.
Інтервали. Частоту перевірок можна змінити, модифікуючи параметри interval_min у конструкторах KitchenWatcher, DeliveryWatcher та RevenueWatcher у bot/main.py.
Кнопки. Сповіщення включають кнопки з номерами замовлень, що дозволяє швидко перейти до деталей.

Планувальник та розклад

APScheduler використовується для автоматичного надсилання звітів:

Снепшоти виручки: 13:00, 16:00, 19:00, 22:00.
Снепшоти персоналу: 09:00, 10:00, 13:00, 16:00, 19:00, 22:00.
Денний звіт: 23:00.
Моніторинг кухні та доставки: щохвилини.

CRON‑вирази задаються у bot/services/report_scheduler.py і можуть бути змінені під ваші потреби.

Розширення та кастомізація

Код бота побудовано у дусі принципів SOLID та використовує впровадження залежностей (Dependency Injection). Це полегшує розширення й модифікацію:

Нові watcher’и. Можна створити власний клас з методом start() та _runner() і підключити його аналогічно до інших.
Додавання команд. Щоб додати команду, напишіть функцію‑handler у bot/handlers/commands.py та зареєструйте її в Router.
Підключення інших API. Створіть клієнт у bot/api/, сервіс у bot/services/ і впровадьте його до main.py.
Тести. Перед розгортанням змін рекомендовано запускати тести (розміщені в bot/tests/), щоб переконатися у відсутності регресій.

Підтримка та діагностика

Логування. Логування налаштовується у bot/utils/logger.py. Повідомлення можна виводити у файл або стандартний потік; рівень логів та формат можна змінити.
Підключення. Якщо бот не підключається до Syrve, перевірте правильність SYRVE__host, SYRVE__login, SYRVE__password_sha1 та підключення до мережі.
Чати. Якщо повідомлення не приходять, перевірте report_chats.json та переконайтесь, що бот має права надсилати повідомлення у відповідний чат.
Діагностика. Команда /ping повертає «pong» та допомагає перевірити, що бот працює. Для більш детальної діагностики перегляньте логи.

Висновок

Бот Smart Reports bot автоматизує контроль ключових бізнес‑процесів мережі ресторанів: слідкує за швидкістю роботи кухні та доставки, контролює виручку, формує звіти та сповіщає про проблеми у режимі реального часу. Завдяки модульній архітектурі та інтеграції з API Syrve бот легко налаштовувати та розширювати відповідно до специфічних потреб вашого бізнесу.

Використовуючи цей бот, менеджери отримують можливість оперативно реагувати на затримки та перевищення лімітів, приймати рішення на основі актуальних даних та скорочувати час на рутинні операції.