Глоссарий cita.kz
Единый словарь терминов проекта. Все агенты обязаны использовать термины из этого файла. При расхождении — приоритет у этого документа.
| # | Термин (RU) | EN | Определение | Пример в системе |
|---|---|---|---|---|
| 1 | Бронирование (Запись) | Booking | Запись клиента к мастеру на конкретную услугу, дату и время. Имеет жизненный цикл статусов: pending → confirmed → completed / cancelled / rejected. | Клиент создаёт booking через POST /public/{slug}/booking, провайдер подтверждает через Telegram inline-кнопку |
| 2 | Слот | Slot | Свободный временной интервал внутри рабочего дня мастера, доступный для записи. Вычисляется на лету: рабочие часы минус перерывы минус существующие bookings. | GET /public/{slug}/slots?date=2026-03-20&master_id=xxx → {work_start, work_end, busy_intervals} |
| 3 | Мастер | Master / Specialist | Специалист, оказывающий услуги в рамках бизнеса. Привязан к бизнесу (business_id), имеет M2M связь с услугами (master_services) и собственное расписание. | Мастер "Анна" привязана к услугам "Стрижка женская" и "Окрашивание" |
| 4 | Бизнес | Business / Salon | Организация (салон, барбершоп, студия), зарегистрированная на платформе. Идентифицируется по slug (обычно номер телефона). Содержит мастеров, услуги, категории, расписание. | Business slug="7017017001", name="Салон Айгерим", address="ул. Абая 10" |
| 5 | Услуга | Service | Конкретная процедура с фиксированной длительностью (минуты) и ценой (₸). Принадлежит бизнесу, может входить в категорию. | Service: name="Стрижка женская", duration=60, price=5000 |
| 6 | Клиент | Client | Человек, записывающийся на услугу. В системе представлен двумя сущностями: Client (phone + business_id, для CRM) и опционально User с role=CUSTOMER (для Telegram auth). | Client: phone="77017017001", first_name="Иван", business_id=xxx |
| 7 | Расписание | Schedule | Набор из 7 записей (по одной на каждый день недели, 0=Mon..6=Sun) с рабочими часами, перерывом и флагом активности. Существует на двух уровнях: бизнес (master_id=NULL) и мастер. | Schedule: day_of_week=0, start_time="09:00", end_time="18:00", break_start_time="13:00", break_end_time="14:00", is_active=true |
| 8 | Рабочие часы | Working Hours | Время начала и окончания рабочего дня мастера или бизнеса. Задаётся в Schedule как start_time и end_time (формат "HH:MM"). | start_time="09:00", end_time="18:00" |
| 9 | Перерыв | Break | Нерабочий интервал внутри рабочего дня (обед). Задаётся в Schedule как break_start_time и break_end_time. Учитывается при расчёте слотов как busy interval. | break_start_time="13:00", break_end_time="14:00" — обеденный перерыв |
| 10 | Отмена | Cancellation | Перевод бронирования в статус "cancelled". Инициируется провайдером (через админку или Telegram-бот). При отмене клиент получает Telegram-уведомление. | PATCH /bookings/{id} {status: "cancelled"} → notification клиенту |
| 11 | Перенос | Reschedule | Изменение даты/времени существующей записи. Реализован через RescheduleProposal: провайдер предлагает новое время → клиент принимает/отклоняет через Telegram. Proposal имеет TTL 24 часа. | POST /reschedule/{booking_id} {proposed_date, proposed_time} → Telegram клиенту с кнопками ✅/❌ |
| 12 | Напоминание | Reminder | Уведомление клиенту перед предстоящей записью. ⚠️ В текущей версии НЕ реализовано. Планируется: push за N часов до start_at. | Не реализовано. Техдолг. |
| 13 | Telegram Mini App | Telegram Mini App | Веб-приложение внутри Telegram (WebApp API). Отдельный фронтенд на Next.js 16 + Zustand. Аутентификация через initData + HMAC-SHA256. Роли: customer, provider. | mini-app/src/app/customer/booking/page.tsx — страница записи внутри Telegram |
| 14 | 2GIS | 2GIS Integration | Интеграция с API 2GIS (Suggest API) для автокомплита городов и адресов в Казахстане. Используется при регистрации бизнеса. Фильтр: country_id=4 (KZ), locale=ru_KZ. | GET /location/cities?q=Алм → список городов KZ; GET /location/addresses?q=Абая&lat=...&lon=... |
| 15 | Категория услуг | Service Category | Группировка услуг бизнеса по типу. Услуга может принадлежать одной категории (или не принадлежать). | Category: name="Стрижки" → Services: "Стрижка женская", "Стрижка мужская" |
| 16 | Администратор | Admin | Пользователь с role="ADMIN", управляющий одним бизнесом. Создаётся при регистрации. Имеет JWT-доступ к CRUD услуг, мастеров, расписания, записей. | User: email="admin@salon.kz", role="ADMIN", business_id=xxx |
| 17 | Суперадмин | SuperAdmin | Платформенный администратор. Отдельная аутентификация (не через таблицу User). Видит все бизнесы, все записи, может seed/delete/reset password. | POST /superadmin/login → JWT с isSuperAdmin=true |
| 18 | Онлайн-запись | Online Booking | Процесс создания бронирования через веб-интерфейс (/{slug}) или Telegram Mini App. Включает выбор услуги → мастера → даты/времени → ввод данных → подтверждение. | Клиент заходит на cita.kz/7017017001, проходит 4 шага, POST booking |
| 19 | Подтверждение | Confirmation | Перевод бронирования из статуса "pending" в "confirmed" провайдером. Происходит через: 1) Telegram inline-кнопку ✅, 2) админ-панель (PATCH /bookings/{id}). Клиент получает Telegram-уведомление с адресом. | Провайдер нажимает ✅ в Telegram → booking.status=confirmed → клиенту: "✅ Запись ПОДТВЕРЖДЕНА, адрес: ..." |
| 20 | No-show | No-show | Ситуация, когда клиент не приходит на подтверждённую запись. ⚠️ В текущей версии НЕ отслеживается (нет статуса "no_show", нет автоматической логики). | Не реализовано. Техдолг. |
| 21 | Рейтинг | Rating | Оценка мастера или услуги клиентом. ⚠️ В текущей версии НЕ реализован. Нет модели, нет API. | Не реализовано. Техдолг. |
| 22 | Slug | Slug | Уникальный URL-идентификатор бизнеса. По умолчанию — нормализованный номер телефона (10 цифр). Используется в маршрутах: /{slug}, /my/{slug}. | slug="7017017001" → cita.kz/7017017001 |
| 23 | Подписка | Subscription | Запись в таблице subscriptions, связывающая Telegram chat_id с контекстом уведомлений. Типы: PROVIDER_BUSINESS (провайдер), CLIENT_PHONE (клиент по телефону), CLIENT_BOOKING (клиент по записи). | Subscription: context_type=PROVIDER_BUSINESS, context_ref=business_id, telegram_chat_id="123456" |
| 24 | Deep Link | Deep Link | Telegram-ссылка с payload для автоматической привязки: t.me/citakz_bot?start=provider_{business_id} или t.me/citakz_bot?start=client_{booking_id}. Обрабатывается в telegram_handler.py. | https://t.me/citakz_bot?start=provider_abc123 → бот создаёт Subscription для бизнеса |
| 25 | Busy Interval | Busy Interval | Занятый временной отрезок внутри рабочего дня: перерыв или существующее бронирование. Возвращается фронтенду в формате [["13:00","14:00"],["15:00","15:30"]]. | busy_intervals в ответе GET /public/{slug}/slots |
| 26 | Price Snapshot | Price Snapshot | Цена услуги, зафиксированная в момент создания бронирования (booking.price_snapshot). Не меняется, даже если услуга подорожала. | Booking создан с price_snapshot=5000, позже Service.price стал 6000 — booking.price_snapshot остаётся 5000 |