SKILL.md — Beauty Booking Telegram Bot

Назначение проекта

Проект — Telegram-бот для онлайн-записи клиентов в студию маникюра. Это не одноразовый бот под одного заказчика, а основа переиспользуемого продукта, который можно продавать другим мастерам: маникюр, брови, ресницы, барберы, массаж, косметология.

Главная цель первой версии — за 5–7 дней собрать рабочий MVP:

• клиент видит услуги и цены;
• выбирает мастера;
• выбирает свободное время;
• оставляет запись;
• администратор получает уведомление;
• занятый слот больше не показывается другим клиентам;
• администратор может управлять услугами, мастерами, графиком и записями через Telegram.

Роль Codex

Codex должен работать как старший backend-разработчик Telegram-ботов. Нельзя ограничиваться «демо на кнопках». Нужно собрать аккуратную, расширяемую архитектуру, которую можно потом превратить в продаваемый SaaS/copy-product.

Codex должен:

1. Писать полный рабочий код, а не фрагменты.
2. Следовать текущей структуре проекта.
3. Добавлять комментарии на русском языке в местах, где логика не очевидна.
4. Не ломать уже реализованные сценарии.
5. Делать код пригодным для Railway/VPS-деплоя.
6. Хранить бизнес-логику отдельно от Telegram-хендлеров.
7. Закладывать мультитенантность на будущее, даже если в MVP используется одна студия.

Предпочтительный стек

Основной стек MVP:

• Python 3.11+
• aiogram 3.x
• SQLAlchemy 2.x async
• PostgreSQL в проде
• SQLite допустим для локальной разработки
• Alembic для миграций
• APScheduler для напоминаний и ежедневных задач
• Docker / Docker Compose
• python-dotenv / pydantic-settings

Почему Python + aiogram:

• быстро собрать MVP;
• дешево для клиента;
• удобно делать Telegram-админку;
• легко тиражировать под другие студии;
• проще поддерживать мелкие кастомизации.

Основные сущности

Studio

Студия/проект. В MVP может быть одна студия, но модель нужна сразу.

Поля:

• id
• title
• description
• timezone
• admin_chat_id
• is_active
• created_at
• updated_at

User

Telegram-пользователь.

Поля:

• id
• telegram_id
• username
• first_name
• last_name
• phone
• role: client/admin/master/superadmin
• created_at
• updated_at

Service

Услуга студии.

Поля:

• id
• studio_id
• title
• description
• price
• duration_minutes
• is_active
• sort_order
• created_at
• updated_at

Master

Мастер студии.

Поля:

• id
• studio_id
• user_id nullable
• name
• description
• phone
• is_active
• sort_order
• created_at
• updated_at

MasterService

Связь мастера и услуг, которые он выполняет.

Поля:

• id
• master_id
• service_id

WorkSchedule

Базовый недельный график мастера.

Поля:

• id
• master_id
• weekday: 0-6
• start_time
• end_time
• is_day_off

ScheduleException

Исключения графика: выходной, отпуск, короткий день, дополнительный рабочий день.

Поля:

• id
• master_id
• date
• start_time nullable
• end_time nullable
• is_day_off
• comment

Appointment

Запись клиента.

Поля:

• id
• studio_id
• client_id
• master_id
• service_id
• starts_at
• ends_at
• status: pending/confirmed/cancelled/completed/no_show
• client_name
• client_phone
• comment
• created_at
• updated_at

Setting

Гибкие настройки студии.

Поля:

• id
• studio_id
• key
• value

Основные клиентские сценарии

/start

Показывает приветствие и главное меню:

• Записаться
• Услуги и цены
• Мои записи
• Контакты
• Помощь

Запись клиента

Сценарий:

1. Клиент нажимает «Записаться».
2. Выбирает услугу.
3. Выбирает мастера или «любой мастер».
4. Выбирает дату.
5. Бот показывает свободные слоты.
6. Клиент выбирает слот.
7. Бот спрашивает имя и телефон, если их нет.
8. Бот показывает подтверждение.
9. После подтверждения создается Appointment.
10. Клиент получает сообщение с деталями записи.
11. Администраторы получают уведомление в личку или админ-чат.
12. Слот становится занятым.

Важно: двойная запись на один и тот же слот запрещена на уровне сервиса и базы.

Мои записи

Клиент видит будущие записи:

• услуга;
• мастер;
• дата и время;
• статус;
• кнопка отмены.

Отмена клиентом может быть ограничена настройкой, например не позднее чем за 3 часа.

Админ-сценарии

Команда /admin доступна только администраторам.

Меню администратора:

• Записи
• Услуги
• Мастера
• График
• Настройки
• Статистика

Управление услугами

Администратор может:

• добавить услугу;
• изменить название;
• изменить цену;
• изменить длительность;
• включить/выключить услугу;
• удалить/скрыть услугу.

Управление мастерами

Администратор может:

• добавить мастера;
• изменить имя;
• изменить описание;
• привязать услуги к мастеру;
• включить/выключить мастера.

Управление графиком

Минимальная версия:

• установить рабочие дни мастера;
• указать начало и конец рабочего дня;
• задать выходной на конкретную дату;
• добавить исключение графика.

Управление записями

Администратор может:

• смотреть записи на сегодня;
• смотреть записи на завтра;
• смотреть записи по мастеру;
• отменить запись;
• отметить как выполненную;
• написать клиенту вручную через Telegram, если доступен username.

Генерация свободных слотов

Алгоритм:

1. Получить выбранную услугу и ее длительность.
2. Получить график мастера на выбранную дату.
3. Учесть исключения графика.
4. Разбить рабочее время на слоты с шагом 15/30 минут.
5. Убрать слоты, которые пересекаются с активными записями.
6. Не показывать прошедшее время для текущего дня.
7. Вернуть только свободные слоты.

Пересечение записей проверять условием:

• новая_запись.starts_at < существующая.ends_at
• новая_запись.ends_at > существующая.starts_at

Статусы записей

• pending — создана, ожидает подтверждения, если нужен такой режим;
• confirmed — подтверждена;
• cancelled — отменена;
• completed — выполнена;
• no_show — клиент не пришел.

В MVP можно сразу создавать confirmed.

Уведомления

Минимально:

• уведомление админу при новой записи;
• уведомление клиенту после записи;
• уведомление клиенту при отмене;
• уведомление админу при отмене клиентом.

Желательно заложить:

• напоминание за 24 часа;
• напоминание за 2 часа;
• ежедневная сводка админу утром.

Будущие коммерческие функции

Эти функции не обязательно делать в первом коммите, но архитектура не должна мешать их добавить:

• несколько студий в одной базе;
• тарифы Free/Basic/Pro;
• кастомный дизайн приветствия;
• онлайн-предоплата;
• WebApp-админка;
• экспорт записей в Google Sheets;
• интеграция Google Calendar;
• CRM-карточка клиента;
• история посещений;
• черный список клиентов;
• рассылки по клиентам;
• промокоды;
• отзывы после визита;
• витрина услуг;
• мультифилиалы.

Требования к качеству

• Код должен запускаться локально одной командой.
• Все настройки должны быть в .env.
• Не хранить токены в коде.
• Хендлеры должны быть тонкими.
• Бизнес-логика должна быть в сервисах.
• Работа с БД должна быть через репозитории или сервисный слой.
• Все callback_data должны быть короткими и предсказуемыми.
• Все сообщения пользователю — на русском языке.
• Ошибки должны логироваться.
• Бот не должен падать при неверном вводе пользователя.

MVP-критерий готовности

Проект считается готовым, если можно пройти полный путь:

1. Админ добавляет 15 услуг.
2. Админ добавляет 4 мастеров.
3. Админ задает график каждому мастеру.
4. Клиент выбирает услугу.
5. Клиент выбирает мастера.
6. Клиент выбирает свободный слот.
7. Клиент подтверждает запись.
8. Админ получает уведомление.
9. Второй клиент не может занять тот же слот.
10. Админ видит запись в списке.
11. Админ может отменить или завершить запись.