TKBK Studio
TKBK Studio
Услуги, мастера, свободные окна на 14 дней, напоминания за сутки и за 2 часа, предоплата и отзывы
Онлайн-запись прямо в Telegram для салонов красоты, барбершопов, клиник, автосервисов и частных мастеров. Клиент выбирает услугу, мастера, день и свободное время — бот сам учитывает длительность услуги, график, перерывы и уже занятые окна.
За сутки и за 2 часа до визита бот напоминает о записи и даёт перенести или отменить её в два нажатия — меньше неявок и пустых окон. После визита клиент получает кнопку для отзыва на Яндекс Картах. По желанию включается предоплата картой через ЮKassa или Telegram Stars.
Услуги, мастера и график — в простом файле services.json, данные — в SQLite на вашем сервере, без абонентской платы за CRM. Администратор получает уведомления о каждой записи и смотрит расписание командами /today и /week.
Для кого: Салоны красоты, барбершопы, клиники, автосервисы, частные мастера
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
BOT_TOKENТокен бота — @BotFather → /newbotADMIN_CHAT_IDЧат для уведомлений о записях — Ваш ID у @userinfobot или ID группы (отправьте боту /id в группе)PAYMENTS_PROVIDER_TOKENТокен ЮKassa — @BotFather → /mybots → бот → Payments → ЮKassa. Только для предоплаты картойADMIN_IDSДополнительные администраторы — ID через запятую# {{BRAND}} — бот онлайн-записи в Telegram
Клиенты записываются сами за минуту: выбирают услугу, мастера, день и свободное время.
Бот напоминает о визите за сутки и за 2 часа, позволяет перенести или отменить запись,
а после визита просит оставить отзыв. Подходит для салонов, барбершопов, клиник, автосервисов.
## Что умеет
- **Услуги и мастера** из файла `services.json`: длительность, цена, кто какие услуги делает.
- **График**: часы работы по дням недели, перерыв, выходные даты; у мастера — только отличия от общего графика.
- **Свободные окна на 14 дней** (настраивается) с учётом длительности услуги, перерывов и уже занятых записей.
Вариант «Любой свободный мастер». Двойная запись на одно время невозможна.
- **Запись**: имя и телефон спрашиваются один раз — потом подставляются автоматически.
- **Мои записи**: перенос на другое время и отмена в два нажатия.
- **Напоминания** за 24 часа и за 2 часа (фоновая задача, раз в минуту).
- **Предоплата** (по желанию): картой через ЮKassa или Telegram Stars. Время держится 15 минут, потом освобождается.
- **Отзыв после визита**: через несколько часов клиент получает кнопку со ссылкой на Яндекс Карты (или 2ГИС).
- **Администратору**: уведомление о каждой записи, переносе и отмене; `/today`, `/week`, `/booking 12`;
отмена записи с уведомлением клиента и возврат предоплаты звёздами одной кнопкой.
## Запуск за 5 минут
### 1. Получите токены
| Что | Где взять |
|---|---|
| `BOT_TOKEN` | [@BotFather](https://t.me/BotFather) → `/newbot` → имя и юзернейм → скопируйте токен |
| `ADMIN_CHAT_ID` | Ваш ID — напишите [@userinfobot](https://t.me/userinfobot). Для группы администраторов: добавьте бота в группу и отправьте `/id` |
| `PAYMENTS_PROVIDER_TOKEN` | Только для предоплаты картой: @BotFather → `/mybots` → бот → **Payments** → **ЮKassa** (для начала — тестовый) |
Скопируйте `.env.example` в `.env` и впишите значения.
### 2а. Запуск в Docker
```bash
docker compose up -d --build
docker compose logs -f # смотреть логи
```
### 2б. Запуск без Docker (Python 3.12+)
```bash
python -m venv .venv
# Windows: .venv\Scripts\activate Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python -m app
```
Откройте бота в Telegram и нажмите **Старт**.
## Настройка `services.json`
```json
{
"slot_step_minutes": 30,
"min_lead_minutes": 60,
"working_hours": {"mon": ["10:00", "20:00"], "sat": ["11:00", "18:00"], "sun": null},
"breaks": [["14:00", "14:30"]],
"days_off": ["2026-12-31"],
"services": [{"id": "haircut", "title": "Стрижка", "duration": 60, "price": 1800, "description": "…"}],
"masters": [{"id": "anna", "name": "Анна", "about": "стилист", "services": ["haircut"],
"working_hours": {"mon": null}}]
}
```
- `slot_step_minutes` — шаг сетки (записи начинаются в 10:00, 10:30, …); `min_lead_minutes` — за сколько минут
минимум можно записаться.
- `working_hours` — дни `mon`…`sun`, `null` — выходной. Не указанный день тоже выходной.
- У мастера `working_hours`, `breaks`, `days_off` необязательны и задают только отличия от общего графика.
- `duration` — минуты, `price` — рубли (0 — не показывать цену). `id` — латиница, до 16 символов, не меняйте у существующих.
После правок перезапустите бота (`docker compose up -d --build` или заново `python -m app`).
Название, тексты, предоплата, часовой пояс и ссылка для отзывов — в начале `app/config.py`.
## Команды
| Команда | Кто | Что делает |
|---|---|---|
| `/start`, `/book`, `/my`, `/contacts` | клиенты | меню, запись, мои записи, контакты |
| `/paysupport` | клиенты | вопрос по оплате — уходит администратору |
| `/today`, `/week` | админ | записи на сегодня / на 7 дней |
| `/booking 12` | админ | запись с кнопками «Отменить» и «Вернуть звёзды» |
| `/id` | все | ID текущего чата |
## Проверка
```bash
pip install -r requirements.txt pytest==9.1.1
pytest
```
Тесты проверяют расчёт свободных окон, напоминания, `services.json`, телефоны и даты по-русски.
## Структура
```
app/
__main__.py запуск бота и фоновых напоминаний
config.py настройки: .env + значения из мастера
services.py загрузка и проверка services.json
slots.py свободные окна и сроки напоминаний (чистая логика)
db.py SQLite: клиенты и записи
booking.py запись: услуга → мастер → день → время → подтверждение
client.py меню, мои записи, перенос и отмена
payments.py предоплата через Telegram Payments
admin.py /today, /week, отмена и возврат
reminders.py напоминания, отзывы, снятие неоплаченных броней
views.py тексты и даты по-русски
keyboards.py кнопки
services.json услуги, мастера и график
```
## FAQ
**Напоминания не приходят.** Бот должен работать постоянно (Docker или сервер). Напоминание за сутки не отправляется,
если клиент записался меньше чем за 24 часа, — оно было бы лишним.
**Время показывается со сдвигом.** Проверьте часовой пояс в `app/config.py` (`TIMEZONE`) — он из мастера TKBK Studio.
**Клиент записался по телефону — как закрыть время в боте?** Пока проще всего записать клиента через бота самому
(с телефона администратора). Идея для доработки — команда `/block` для ручной брони.
**Как вернуть предоплату?** Звёзды — кнопкой «↩️ Вернуть звёзды» под записью. Оплату картой возвращают в личном кабинете ЮKassa.
**Где взять ссылку на отзывы в Яндекс Картах?** Откройте свою организацию на Яндекс Картах → «Отзывы» → скопируйте ссылку
из адресной строки. Для 2ГИС — аналогично.
**Где хранятся данные?** В SQLite: `data/booking.db` (в Docker — том `booking-data`). Делайте резервные копии.
Услуги с ценами, мастера и онлайн-запись
Оценка 0–10 после заказа: довольных — на Яндекс Карты, 2ГИС и WB, недовольных — сразу к менеджеру
Оплата звёздами или картой, одноразовые ссылки, напоминания о продлении и автоисключение по окончании