РУКОВОДСТВО АДМИНИСТРАТОРА И МАСТЕРА

Интеллектуальный телеграм-бот онлайн-записи клиентов сферы красоты (Эталонная CRM-система).

Роль в системе
Мастер / Администратор (Изабелла)
Базовый часовой пояс
Europe/Moscow (МСК, UTC+3)
Архитектурный стандарт
Aiogram 3 • PostgreSQL • Zero Clutter

1. Введение и концепция панели управления

Панель управления мастера — это персональное изолированное рабочее пространство внутри Telegram, превращающее мессенджер в полноценную CRM-систему соло-мастера.

Ключевые принципы архитектуры:
  • Двусторонняя изоляция (Two-Way Role Guard): Мастер никогда не видит клиентский интерфейс записи, а клиенты не имеют доступа ни к одной функции панели управления. Фильтрация работает на уровне Aiogram Middleware (AdminOnlyMiddleware и ClientOnlyMiddleware).
  • Постоянство интерфейса (Persistent Keyboards): Главное меню всегда закреплено в нижней части экрана смартфона (is_persistent=True), не сворачивается при вводе сообщений или листании чата.
  • Чистый экран (Zero Clutter): Диалог не захламляется сотнями устаревших сообщений. При повторном открытии старые экраны автоматически удаляются.
  • Атомарность и надёжность: Запись, отмена и блокировка слотов выполняются в СУБД PostgreSQL с защитой от накладок и гонок данных (Race Conditions).

2. Вход в систему и архитектура Zero Clutter

Для входа в рабочую панель мастеру достаточно отправить одну из команд:

/start — первичный запуск или перезапуск /admin — мгновенный возврат в панель

Механизм самоочистки Zero Clutter

При отправке /start или /admin активируется функция параллельной очистки чата:

  1. Сканирование истории: Бот определяет диапазон предыдущих сервисных сообщений (до 30 сообщений назад).
  2. Конкурентное удаление: Асинхронно стираются старые графики, календари, списки и дампы.
  3. Фокусировка: В чате появляется ровно одно свежее сообщение приветствия, а внизу экрана активируется постоянное рабочее меню.
Экран приветствия мастера (Zero Clutter) Статус: Авторизован 
Здравствуйте, Fast 👑
Вы авторизованы как мастер и администратор системы (Изабелла).

• Просматривайте актуальные записи клиентов
• Управляйте услугами и ценами
• Добавляйте ручные записи и перерывы
• Делайте рассылки и бэкапы
• Следите за статистикой

3. Главная панель управления (11 ключевых кнопок)

Постоянное Reply-меню мастера состоит из 11 эргономичных кнопок, скомпонованных строго в 5 рядов (4 ряда по 2 кнопки + 5-й ряд из 3 кнопок). Кликните по любой кнопке, чтобы перейти к её описанию:

Раскладка меню мастера (ReplyKeyboardMarkup) is_persistent=True
📅 Расписание на сегодня 📆 Расписание на завтра
🗓 Все записи ➕ Запись по звонку
⏱ График и перерывы 💅 Управление услугами
📢 Рассылка клиентам 💾 Бэкап БД
🏠 Меню 📊 Статистика 📖 Памятка

4. Входящие заявки и цикл подтверждения

Когда клиент оформляет бронирование через бота, заявка переходит в статус PENDING (Ожидает решения мастера). Уведомление поступает мгновенно в личный чат мастера.

Входящая карточка новой брони (статус PENDING) ● Требует действия 
🔔 Новая заявка на запись!

• 👤 Клиент: Анна Смирнова (@anna_beauty)
• 🆔 Telegram ID: 512345678
• 📱 Телефон: +7 999 123-45-67
• 💅 Услуга: Маникюр (60 мин)
• 📅 Дата и время: 28.10.2026 в 11:15
• 💬 Пожелание: Снятие чужого покрытия

Пожалуйста, подтвердите или отклоните заявку:

Регламент уведомлений и напоминаний:

  • ✅ Подтвердить: Статус в базе меняется на CONFIRMED. Клиенту отправляется пуш с подтверждением и адресом студии.
  • ❌ Отклонить: Статус меняется на CANCELLED_BY_MASTER. Зарезервированный слот времени (длительность процедуры + 15 мин буфера) мгновенно возвращается в расписание для других клиентов.
  • Регламент тишины: Если мастер занят и не отреагировал на карточку, повторные напоминания отправляются не чаще одного раза в 120 минут и строго в рабочие часы (с 10:00 до 18:00). Ночью бот мастера не беспокоит.

5. Управление расписанием на день («Сегодня» и «Завтра»)

Кнопки 📅 Расписание на сегодня и 📆 Расписание на завтра выводят хронологический список процедур и пауз мастера.

📅 Расписание на сегодня ● Синхронизировано с БД 
📅 Расписание на Сегодня (Пт, 23.10.2026):

☕️ Перерывы / блокировки:
• ☕️ Перерыв: 13:00 - 14:00

📋 Записи клиентов:
✅ 10:00 - 11:00 — Маникюр
   👤 Екатерина (@kate_m)
   📱 +79111234567 | ID: 987654321
   💬 Дизайн двух ногтей

✅ 11:15 - 12:15 — Педикюр
   👤 Ольга (без никнейма)
   📱 +79219876543 | ID: 876543210

6. Журнал «Все записи» и интерактивный календарь на 14 дней

Раздел вызывается нажатием кнопки 🗓 Все записи.

1. Моментальный список: Мастер сразу видит сгруппированный по дням список предстоящих записей на 14 дней вперед.

2. Интерактивный календарь: При нажатии [ 📅 Выбрать конкретную дату ] открывается календарная сетка с разбивкой по 3 неделям:

🗓 Выбор даты (Календарь на 14 дней) Горизонт: 2 недели 
📅 Выберите дату для просмотра расписания:

── 📍 ТЕКУЩАЯ НЕДЕЛЯ ──
[ 🟢 Пт, 23.10 (Сегодня) ]

── 🗓 СЛЕДУЮЩАЯ НЕДЕЛЯ ──
[ 🔹 Пн, 26.10 ]   [ 🔹 Вт, 27.10 ]
[ 🔹 Ср, 28.10 ]   [ 🔹 Чт, 29.10 ]
[ 🔹 Пт, 30.10 ]

── 🗓 ЧЕРЕЗ НЕДЕЛЮ ──
[ ▫️ Пн, 02.11 ]   [ ▫️ Вт, 03.11 ]
[ ▫️ Ср, 04.11 ]   [ ▫️ Чт, 05.11 ]
[ ▫️ Пт, 06.11 ]

7. Запись по звонку (ручное бронирование мастером)

Кнопка ➕ Запись по звонку позволяет внести клиента, который обратился по телефону, через WhatsApp или при личной встрече.

  1. Имя клиента: Мастер вводит имя в чат (например: Елена Власова).
  2. Телефон: Вводится номер. Система автоматически форматирует его в стандарт +7XXXXXXXXXX.
  3. Выбор услуги: Нажатие по инлайн-кнопке нужной процедуры из активного прайс-листа.
  4. Выбор даты: Календарная сетка на 14 дней с учетом выходных и отпусков.
  5. Выбор времени: Расчет свободных окон с учетом длительности услуги и обязательного буфера +15 минут.
Особенность учёта клиентов без Telegram: Если у клиента нет аккаунта в Telegram, система генерирует стабильный отрицательный псевдо-ID на базе цифр телефона. Клиент корректно попадает в базу, учитывается в финансовой статистике и расчете среднего чека.

8. Управление графиком: перерывы, выходные и отпуска

Раздел ⏱ График и перерывы позволяет управлять доступностью мастера без правки конфигураций бота:

⏱ Центр управления графиком Мгновенная блокировка слотов 
⏱ Центр управления рабочим графиком

Выберите требуемое действие с расписанием:

9. Каталог услуг, прайс-лист и безопасное удаление (Soft Delete)

Кнопка 💅 Управление услугами открывает интерактивный конфигуратор прайс-листа.

💅 Карточка услуги: Маникюр ● Активна в онлайн-записи 
💅 Услуга: Маникюр

• Длительность: 60 минут
• Стоимость: 2 500 ₽
• Статус: ✅ Активна (клиенты могут записываться)
• Описание: Аппаратный маникюр с выравниванием
Архитектурный принцип Soft Delete: Физическое удаление услуг из базы данных запрещено ограничением FOREIGN KEY ... ON DELETE RESTRICT. При нажатии «Удалить услугу» поле is_deleted устанавливается в True. Услуга полностью исчезает из интерфейса записи, но сохраняется в базе для защиты истории прошлых визитов и достоверности финансовых отчетов.

10. Финансовая аналитика и статистика

Кнопка 📊 Статистика формирует детализированный управленческий отчет с мгновенным переключением периодов (Сегодня / Неделя / Месяц / Всё время):

📊 Аналитика и статистика мастера Октябрь 2026 г. 
📊 Аналитика и статистика мастера
🗓 Период: Октябрь 2026 г.

💰 ФИНАНСОВЫЕ ИТОГИ:
• Выручка: 145 000 ₽
• Средний чек: 2 636 ₽

📅 ВИЗИТЫ И НАГРУЗКА:
• Всего записей: 58
  ├ ✅ Подтверждено: 55
  ├ ⏳ В ожидании: 1
  └ ❌ Отменено: 2 (доходимость 96%)
• Отработано часов: 55 ч 00 мин

💅 ТОП ПРОЦЕДУР ПО СПРОСУ:
  1. Маникюр — 28 виз. (70 000 ₽)
  2. Педикюр — 15 виз. (45 000 ₽)
  3. Ресницы — 12 виз. (30 000 ₽)

👥 КЛИЕНТСКАЯ БАЗА:
• Клиентов за период: 42
• Новых клиентов: +14
• Всего клиентов в базе: 189

11. Сервисные рассылки клиентам

Раздел 📢 Рассылка клиентам позволяет отправить объявление всем клиентам базы (об отпуске, акциях или графике на праздники).

Защита от случайной отправки: После ввода текста бот никогда не отправляет рассылку моментально. Он формирует карточку предпросмотра с указанием точного числа получателей (N чел.) и кнопками подтверждения: [ 🚀 Да, разослать сообщение ] и [ ❌ Отменить ].

12. Резервное копирование базы данных (Бэкап)

Создание дампа базы данных PostgreSQL:

  • По кнопке в меню: 💾 Бэкап БД
  • По быстрой команде в чат: /backup

Бот запускает утилиту pg_dump | gzip и присылает готовый сжатый архив формата .sql.gz с меткой даты и времени прямо в чат Telegram. Копия автоматически сохраняется на сервере в /opt/bot-zakaz/data/backups/.

Также работает еженедельный автоматический бэкап (каждый понедельник в 03:00 ночи через APScheduler).

13. Интеллектуальный антиспам и Чёрный список

Система защищает расписание мастера от спамеров и бот-атак:

Лимит безопасности: Клиенту разрешено создавать не более 3 попыток бронирования за 5 минут. При 4-й попытке клиент мгновенно блокируется (is_banned = True). Все его неподтвержденные заявки аннулируются, а слоты сразу же освобождаются для реальных клиентов. Мастер получает алерт с красной сиреной.
🚨 Экстренное оповещение службы безопасности АВТОБАН АКТИВИРОВАН 
🚨 Сработала автоматическая защита от спама!

Пользователь превысил лимит создания записей (более 3 попыток за 5 минут) и был автоматически заблокирован:
• 👤 Клиент: Иван Петров (@ivan_spammer)
• 📱 Телефон: +79990001122
• 🆔 Telegram ID: 777888999

🧹 Освобождено зарезервированных слотов: 3

Если это реальный клиент или ошибка, вы можете разблокировать его командой:
/unban 777888999

Команды ручного управления блокировкой:

/ban <telegram_id> — ручная блокировка пользователя /unban <telegram_id> — снятие бана и сброс счетчика спама

14. Сводная памятка команд и регламентов

Быстрые команды в чат:

Команда Описание действия Клик для копирования
/start Очистка истории чата (Zero Clutter) и вывод панели управления Копировать
/admin Мгновенный сброс текущего состояния и возврат на главный экран Копировать
/backup Создание и отправка сжатого архива базы данных PostgreSQL Копировать
/ban <id> Блокировка нарушителя с аннулированием заявок и освобождением слотов Копировать
/unban <id> Разблокировка пользователя и сброс счетчиков антиспама Копировать
/cancel Отмена пошагового сценария (рассылки, ручной записи, добавления услуги) Копировать

Назначение 11 кнопок постоянного меню:

Кнопка Раздел Основное назначение
📅 Расписание на сегодня Оперативный график Показ клиентов и перерывов на текущий день с телефонами и пожеланиями
📆 Расписание на завтра Оперативный график Показ клиентов и перерывов на следующий рабочий день
🗓 Все записи Журнал записей Список визитов на 14 дней и календарная сетка с выбором даты
➕ Запись по звонку Ручная бронь Пошаговое оформление клиента по телефону без Telegram
⏱ График и перерывы Доступность Перерывы 30/60 мин, закрытие остатка дня, выходные и отпуска
💅 Управление услугами Прайс-лист Редактирование цен, длительности, добавление услуг, Soft Delete
📢 Рассылка клиентам Маркетинг/Сервис Массовое сообщение клиентам с защитой от случайного клика
💾 Бэкап БД Безопасность Мгновенное скачивание резервной копии базы данных
📊 Статистика Аналитика Выручка, средний чек, часы работы, топ услуг (сегодня/неделя/месяц/всё время)
📖 Памятка База знаний Краткая справка по всем функциям и горячим командам прямо в боте
🏠 Меню Zero Clutter Сброс диалога, удаление старых сообщений и возврат на стартовый экран

15. Таблица соответствия: Паспорт vs Реализация

Полный аудит параметров системы подтверждает 100% схождение технического паспорта (passport.md) и программного кода эталона:

Параметр системы Значение в паспорте Реализация в кодовой базе Статус
Имя мастера Изабелла settings.master_name = "Изабелла" ✅ Соответствует
Рабочие часы мастера 10:00 — 18:00 (Пн–Пт) work_start = 10:00, work_end = 18:00 ✅ Соответствует
Горизонт планирования Строго 14 дней вперед get_available_dates(14) ✅ Соответствует
Шаг генерации слотов 15 минут Цикл с шагом timedelta(minutes=15) ✅ Соответствует
Буфер на уборку/отдых +15 минут после процедуры buffer_minutes = 15 ✅ Соответствует
Очистка чата Zero Clutter Удаление до 30 сообщений send_master_welcome_with_cleanup ✅ Соответствует
Двусторонняя изоляция Мастер и клиент изолированы AdminOnlyMiddleware + ClientOnlyMiddleware ✅ Соответствует
Постоянство клавиатур is_persistent=True Включено во всех Reply-клавиатурах ✅ Соответствует
Удаление услуг (Soft Delete) Защита целостности через флаг is_deleted = True, ForeignKey RESTRICT ✅ Соответствует
Антиспам-лимит Не более 3 заявок за 5 мин max_attempts = 3, window_seconds = 300 ✅ Соответствует
Освобождение слотов Аннулирование PENDING заявок cancel_pending_bookings_for_client ✅ Соответствует
Панель мастера 11 кнопок (4 ряда x 2 + 5-й ряд x 3) get_master_main_menu_kb ✅ Соответствует
Резервное копирование Дамп в чат + еженедельный крон BackupService (pg_dump | gzip) ✅ Соответствует