Огляд

Telegram-бот для запису на масаж — це система бронювання для масажного кабінету (або подібного сервісу), де клієнти проходять запис у Telegram, а персонал підтверджує або відхиляє заявки.

Платформа поєднує динамічні слоти, запобігання подвійному бронюванню, опційну синхронізацію з Google Calendar, автоматичні нагадування клієнтам та веб-панель для щоденних операцій.

Проєкт орієнтований на невелику команду: один сервіс на VPS, PostgreSQL як джерело даних і зрозумілий операційний workflow без окремих черг або важкої інфраструктури.

Контекст

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

Основними вимогами були:

• покрокове бронювання (тривалість, майстер, дата, час, контакти);
• динамічні слоти за робочими годинами та довжиною сесії;
• підтвердження адміністратором до фіналізації запису;
• ролі персоналу та керування майстрами;
• український та англійський інтерфейс у боті;
• опційна інтеграція з Google Calendar;
• автоматичні нагадування клієнтам;
• веб-панель для перегляду та обробки записів.

Відповідальність

У межах проєкту:

• архітектура застосунку та модульна структура;
• Telegram-бот (aiogram 3) і FSM-сценарій бронювання;
• схема PostgreSQL і міграції Alembic;
• генерація слотів і виявлення конфліктів;
• підтвердження та відхилення записів із сповіщеннями клієнту;
• інтеграція Google Calendar;
• нагадування на APScheduler;
• веб-адмінка (FastAPI);
• Docker-образ, compose і GitLab CI/CD деплой.

Рішення

Рішення реалізоване як єдиний Python-сервіс, який обслуговує Telegram-взаємодію, фонові нагадування та за потреби веб-адмінку.

Клієнт у Telegram обирає параметри сесії, бачить доступні слоти та отримує статус заявки після рішення адміністратора. Адміністратори працюють через Telegram або веб-панель: переглядають pending-записи, підтверджують або відхиляють їх із повторною перевіркою доступності слоту.

Доступність враховує підтверджені та очікуючі записи в базі та, за налаштуванням, зайнятість у Google Calendar. При збої зовнішнього календаря система продовжує працювати на основі даних у PostgreSQL.

Технічні деталі

Стек

• Python 3.12
• aiogram 3
• PostgreSQL
• SQLAlchemy 2 (async)
• Alembic
• FastAPI
• APScheduler
• Google Calendar API
• Docker
• GitLab CI

Архітектура

У проєкті розділено:

• обробники Telegram і FSM-сценарій бронювання;
• сервіси слотів, нагадувань і дій над записами;
• репозиторії та ORM-моделі;
• веб-адмінку;
• міграції схеми БД.

Спільна логіка підтвердження та відхилення використовується і в Telegram, і в веб-панелі, щоб уникнути розбіжностей у бізнес-правилах.

Функціональність

Реалізовано:

• локалізований інтерфейс бота (UA/EN);
• бронювання з динамічними слотами та перевіркою конфліктів;
• ролі owner / admin / master;
• підтвердження та відхилення записів;
• опційну синхронізацію з Google Calendar;
• нагадування клієнтам перед візитом;
• веб-адмінку: записи, майстри, клієнти (read-only);
• деплой через Docker і GitLab CI.

Виклики

Основними викликами були:

• узгодження доступності між базою даних і зовнішнім календарем;
• безпечне підтвердження записів при можливих гонках за слот;
• збереження єдиних бізнес-правил для Telegram і веб-інтерфейсу;
• надійні нагадування без дублювання повідомлень;
• продакшен-деплой і супровід на VPS.

Результат

У результаті отримано:

• повноцінний Telegram-first продукт бронювання;
• контрольоване планування з адміністративним підтвердженням;
• опційну інтеграцію з Google Calendar;
• автоматичні нагадування без окремих черг повідомлень;
• веб-панель для операційної роботи;
• повторюваний деплой через Docker і CI/CD.

Проєкт демонструє поєднання бот-інтерфейсу, backend-логіки, інтеграцій і продакшен-розгортання для малого сервісного бізнесу.

Медіа

Галерея містить:

• сценарій бронювання в Telegram;
• роботу адміністратора з підтвердженням записів;
• екрани веб-адмінки;
• приклади експлуатації системи в продакшені.

Примітки

• Продакшен-орієнтований booking-продукт.
• Telegram як основний канал для клієнтів.
• Веб-адмінка доповнює операційний workflow персоналу.