Document commercial calendars: booking_open, specialists, restricted UX.

Refs EventHub/EventHubSpec#6
Refs EventHub/EventHubBack#54

EventHubBackSpec.md

@@ -1,5 +1,6 @@
 # ТЕХНИЧЕСКОЕ ЗАДАНИЕ (ТЗ) НА ПЛАТФОРМУ EVENTHUB
-Версия: 1.5 (актуальная реализация: выполнены задачи #12–#17)
+Версия: 1.5 (актуальная реализация: выполнены задачи #12–#17; §2.1.2 commercial — контракт
+к реализации)
 
 ## 1. ЦЕЛИ И НАЗНАЧЕНИЕ
 EventHub — платформа для управления событиями с поддержкой календарей, записи участников
@@ -12,12 +13,10 @@ EventHub — платформа для управления событиями
 
 ### 2.1. Календари
 - CRUD календаря (название, описание, теги, владелец)
-- Расшаривание по ссылке (публичная/приватная)
+- Расшаривание по ссылке / приглашения с правами (`calendar_share`) — **фаза 2** (таблица есть;
-- Приглашение пользователей с правами "запись" или "администрирование"
+  user HTTP API и UI — Future, см. §2.1.3)
-- Типы календарей: personal (бесплатный, без записи), commercial (платный, запись клиентов,
+- Типы календарей: `personal` | `commercial` — семантика и коммерческий контур: **§2.1.2**
-  специалисты)
+- Гибкое подтверждение заявок: `auto` | `manual` | `{timeout, N}` (секунды) — детали §2.1.2 / §2.3
-- Гибкое подтверждение заявок: auto (автоматически), manual (вручную), timeout (авто через N
-  секунд)
 - Теги календаря, рейтинг (средняя оценка, количество голосов)
 - После успешной верификации email (`POST /v1/verify`, статус пользователя → `active`) система
   идемпотентно создаёт дефолтный **personal**-календарь владельцу (`logic_calendar:ensure_default_calendar/1`):
@@ -32,10 +31,97 @@ EventHub — платформа для управления событиями
 - `image_url` — изображение календаря
 - `settings` — дополнительные настройки (map)
 
-### 2.1.1. Специалисты календаря (задача #12)
+### 2.1.1. Специалисты календаря
-Реализована отдельная таблица `calendar_specialist`, связывающая пользователя (специалиста) с
+Таблица `calendar_specialist`: связь пользователя-специалиста с **commercial**-календарём.
-календарём. Специалист может иметь отображаемое имя (`name`) и список специализаций
+Поля: `calendar_id`, `user_id`, `name` (отображаемое имя в этом календаре),
-(`specialization`). Статус специалиста: `active` | `inactive`.
+`specialization` (`[binary()]`), `status` (`active` | `inactive`).
+Контракт CRUD, права confirm и связь с `event.specialist_id` — §2.1.2.
+
+### 2.1.2. Коммерческие календари (продуктовый контракт)
+
+Цель: владелец (бизнес) ведёт публичное расписание и принимает записи клиентов; участник находит
+календарь, записывается, получает подтверждение, затем может оставить отзыв. Personal остаётся
+бесплатным «дневником» без записи чужих.
+
+#### Типы и видимость
+
+| | `personal` | `commercial` |
+|---|---|---|
+| Подписка владельца | не требуется | нужна active (trial или paid), иначе **restricted** |
+| Видимость чужим | только владелец (+ share — фаза 2) | публичный просмотр; в search/discover — только если **не** restricted |
+| Booking чужим | **запрещён** (бэкенд `403`, код `personal_calendar`) | разрешён при active подписке владельца |
+| Follow | нет (нет доступа) | да |
+| Специалисты | не используются | CRUD владельца; `specialist_id` на событии |
+| `confirmation` | не влияет на чужие booking | `auto` / `manual` / `{timeout,N}` |
+
+- Смена `personal → commercial`: только при active подписке владельца; иначе `402`.
+- Смена `commercial → personal`: разрешена владельцу; pending booking этого календаря → `cancelled`.
+- Владелец **не** может создать booking на событие своего календаря.
+
+#### Подписка и режим restricted (не downgrade type)
+
+При истечении/отсутствии active подписки календари **остаются** `type=commercial` (данные,
+специалисты, история сохраняются). Включается **restricted mode** — ограничение коммерческого
+функционала; при новой активации подписки функционал **сразу восстанавливается** без смены type.
+
+| Подписка владельца | Поведение |
+|---|---|
+| `active` и `expires_at > now` | полный commercial |
+| иначе (`expired` / нет / `cancelled`) | restricted |
+
+**Restricted:**
+- из search / discovery tops — **исключить**;
+- deep-link `GET /v1/calendars/:id` (и события) — **просмотр разрешён**; в JSON календаря
+  флаг `booking_open: false` (и при active — `true`); UI: «Запись временно недоступна»;
+- новые booking → `403` (`subscription_inactive`);
+- все `pending` booking календарей владельца → `cancelled` (причина `subscription_inactive`),
+  слоты освобождаются;
+- уже `confirmed` — **оставляем**;
+- owner: просмотр/редактирование своих событий и настроек, CRUD specialists — **разрешены**;
+- create нового commercial / upgrade type → `402`.
+
+Периодический job (например раз в 60 с): помечает просроченные подписки `expired`, отменяет
+pending владельца, **не** меняет `calendar.type`. Legacy `downgrade_user_calendars/1`
+(type → personal) — удалить/не использовать.
+
+Первое создание commercial без подписки: **auto-start trial** (один раз, `trial_used`);
+повтор без подписки → `402`. Планы/цены — §2.9.
+
+В ответах календаря (user API): `booking_open` (boolean) — производное от
+`type=commercial` ∧ calendar `active` ∧ подписка владельца active.
+
+#### Запись и capacity
+
+- `POST /v1/events/:id/bookings` только если календарь события commercial, `booking_open=true`,
+  событие `active`, есть свободная вместимость.
+- **Pending занимает capacity** наравне с confirmed (защита от overbook при auto/timeout).
+- Capacity: число booking со статусом `pending` | `confirmed`; `cancelled` не считаются.
+- Политика `confirmation` календаря при создании booking:
+  - `auto` → сразу `confirmed` + `confirmed_at`;
+  - `manual` → `pending`; confirm/decline — владелец или specialist (см. ниже);
+  - `{timeout, N}` → `pending`; через N секунд без решения: auto-confirm, если ещё есть
+    capacity, иначе `cancelled` (`timeout_full`).
+- Участник: `DELETE /v1/bookings/:id` — отмена своей pending/confirmed.
+- WS: `booking_update` участнику и владельцу (и specialist при confirm на «своём» событии).
+
+#### Специалисты
+
+- Специалист = существующий `user`, привязанный к commercial-календарю.
+- API (владелец календаря):
+  - `GET/POST /v1/calendars/:id/specialists`
+  - `PUT/DELETE /v1/calendars/:id/specialists/:user_id`
+- `event.specialist_id` опционален; если задан — только `active` specialist этого календаря
+  (иначе `400`).
+- **Confirm/decline:** владелец — любые booking календаря; `active` specialist — только booking
+  на событиях, где `event.specialist_id` = его `user_id`.
+
+#### Фаза 2 (вне текущего контракта реализации)
+- `calendar_share` (`read` | `write` | `admin`): не путать с follow и платной subscription.
+- Реальный эквайринг, waitlist, оплата услуги клиентом (B2C).
+
+### 2.1.3. Share / приглашения (фаза 2)
+Таблица `calendar_share` (`calendar_id`, `user_id`, `rights`: `read` | `write` | `admin`)
+существует в схеме. User HTTP API и клиентский UI — Future до отдельной задачи.
 
 ### 2.2. События (расширенная версия с повторяющимися событиями)
 
@@ -99,14 +185,15 @@ EventHub — платформа для управления событиями
   (список active доступных календарей); в `GET /v1/calendars/:id` — поле `following` (boolean).
 
 ### 2.3. Запись участников и подтверждение
-- Пользователь может отправить заявку на участие в событии.
+- Запись доступна только на событиях **commercial**-календаря с `booking_open=true` (§2.1.2).
-- В зависимости от `confirmation` календаря заявка либо подтверждается автоматически, либо
+- На personal → `403` (`personal_calendar`); при restricted commercial → `403` (`subscription_inactive`).
-  ожидает ручного подтверждения владельцем, либо подтверждается по таймауту.
+- В зависимости от `confirmation` календаря: auto / manual / timeout (§2.1.2).
-- Бронирование имеет статусы: `pending`, `confirmed`, `cancelled`.
+- Статусы: `pending`, `confirmed`, `cancelled`.
-- Пользователь может отменить свою запись.
+- **Capacity:** лимит слотов считают `pending` + `confirmed` (pending резервирует место).
-- Владелец календаря может подтвердить или отклонить заявку.
+- Участник может отменить свою запись (`DELETE`).
-- При подтверждении фиксируется время (`confirmed_at`).
+- Confirm/decline: владелец календаря — любые заявки; active specialist — только на событиях
-- Вместимость события (`capacity`) ограничивает количество подтверждённых записей.
+  со своим `specialist_id` (§2.1.2).
+- При подтверждении фиксируется `confirmed_at`.
 
 ### 2.4. Отзывы и рейтинги
 - Пользователи могут оставлять отзывы (рейтинг 1–5 и комментарий) на события или календари.
@@ -181,7 +268,11 @@ EventHub — платформа для управления событиями
 - Цены (`logic_subscription:plan_price/1`, minor units): monthly **999**, quarterly **2499**,
   biannual **4499**, annual **7999**; trial — 0. Платёжный шлюз — заглушка (`process_payment` → ok).
 - Статус подписки: `active`, `expired`, `cancelled`.
-- Отслеживание использования пробного периода (`trial_used`).
+- Отслеживание использования пробного периода (`trial_used`); trial стартует автоматически при
+  первой попытке создать/апгрейднуть commercial (§2.1.2).
+- Истечение: периодический job → `expired`; commercial-календари **не** меняют type —
+  переходят в restricted; после `activate` / новой active подписки функционал восстанавливается
+  (§2.1.2). Не использовать legacy downgrade type → personal.
 
 ### 2.10. Административная панель
 - Управление пользователями (просмотр, блокировка, изменение ролей).
@@ -306,12 +397,14 @@ src/
 - `GET /v1/user/following` — календари, которые пользователь отслеживает (follow).
 - `GET /v1/search` — поиск; пустой запрос (только auth + пагинация/`type`) — discovery tops.
 - `GET /v1/calendars` — список календарей.
-- `POST /v1/calendars` — создать календарь.
+- `POST /v1/calendars` — создать календарь (`commercial` → подписка/trial; иначе `402`).
-- `GET /v1/calendars/:id` — календарь (поле `following` для текущего пользователя).
+- `GET /v1/calendars/:id` — календарь (`following`, `booking_open` для текущего контекста).
-- `PUT /v1/calendars/:id` — обновить календарь.
+- `PUT /v1/calendars/:id` — обновить календарь (`personal→commercial` → gate подписки).
 - `DELETE /v1/calendars/:id` — удалить календарь.
 - `POST /v1/calendars/:id/follow` — отслеживать чужой календарь.
 - `DELETE /v1/calendars/:id/follow` — снять follow.
+- `GET/POST /v1/calendars/:id/specialists` — список / добавить специалиста (владелец).
+- `PUT/DELETE /v1/calendars/:id/specialists/:user_id` — обновить / убрать специалиста.
 - `GET /v1/calendars/:calendar_id/events` — события календаря.
 - `POST /v1/calendars/:calendar_id/events` — создать событие.
 - `GET /v1/events/:id` — событие.

EventHubFrontSpec.md

@@ -8,8 +8,9 @@
 
 | Режим | Описание | Ключевые возможности |
 |-------|----------|----------------------|
-| Участник | Поиск и запись на события коммерческих календарей | Поиск, просмотр календаря/события, запись, отмена своей записи, отзывы, жалобы, тикеты |
+| Участник | Поиск и запись на события коммерческих календарей | Поиск, просмотр, запись (если `booking_open`), отмена, отзывы, жалобы, тикеты |
-| Владелец | Управление своими календарями | CRUD календарей и событий, список заявок, confirm/decline, подписка |
+| Владелец | Управление своими календарями | CRUD календарей/событий/специалистов, заявки confirm/decline, подписка |
+| Специалист | Confirm заявок на «свои» события | Те же экраны календаря; confirm/decline только где `specialist_id` = текущий user |
 
 Deep-link на календарь, владельцем которого является текущий пользователь, показывает owner-действия (редактирование, заявки).
 
@@ -50,7 +51,9 @@ Deep-link на календарь, владельцем которого явл
 
 - Главная сущность — **календарь**. Центр UI — виджет с видами **месяц** (default) / **неделя** / **день**.
 - Главные вкладки: **Календарь** (`/`, `/c/:id`), **Найти** (`/search`), **Записи** (`/bookings`), **Ещё** (`/more`).
-- Контекст виджета: свой календарь (селектор) или чужой (browse после поиска). `personal` чужой — только просмотр; `commercial` — запись на событие.
+- Контекст виджета: свой календарь (селектор) или чужой (browse после поиска). Чужой `personal` —
+  только просмотр; чужой `commercial` с `booking_open=true` — запись; при `booking_open=false`
+  (restricted / нет подписки владельца) — просмотр + сообщение «Запись временно недоступна».
 - Выбор события открывает карточку действий: mobile — bottom sheet; desktop — боковая панель. Действия зависят от роли (owner / participant).
 - Без выбранного события — панель «О календаре» (описание, title/meta, рейтинг, отзывы).
   Форма отзыва на календарь/событие — только при confirmed booking; жалоба доступна без записи.
@@ -114,24 +117,31 @@ Redirects: `/discover` → `/search`; `/calendars/:id` → `/c/:id`; `/calendars
 
 ### 5.4. Календари
 - Список своих: `GET /v1/calendars`
-- CRUD: `POST/PUT/DELETE /v1/calendars`, `GET /v1/calendars/:id` (поле `following`)
+- CRUD: `POST/PUT/DELETE /v1/calendars`, `GET /v1/calendars/:id` (`following`, `booking_open`)
 - Follow чужого: `POST/DELETE /v1/calendars/:id/follow`, список `GET /v1/user/following`
   (UI: «Отслеживать» в about, страница `/following`; не путать с `/subscription`)
-- Просмотр коммерческого чужого календаря по id (доступ по правилам бэка)
+- Просмотр коммерческого чужого календаря по id; при `booking_open=false` — баннер
+  «Запись временно недоступна», кнопка записи скрыта
 - HTML month view владельца: `GET /v1/calendars/:calendar_id/view?month=YYYY-MM` — при переключении виджета на **прошедший месяц** (owner + вид «Месяц») автоматически подменяет клиентский grid серверным HTML (live/архив, задача #15). Текущий и будущие месяцы — React-виджет по `GET …/events`.
-- Создание `commercial` требует активной подписки (ответ 402 → экран подписки)
+- Создание / апгрейд `commercial` без подписки → `402` → `/subscription`; после оплаты —
+  возврат к созданию/редактированию
+- Владелец commercial: управление специалистами (`GET/POST/PUT/DELETE …/specialists`);
+  выбор `specialist_id` в форме события; баннер «подписка истекла / истекает»
 
 ### 5.5. События
 - Список: `GET /v1/calendars/:calendar_id/events`
-- CRUD владельца: `POST/PUT/DELETE`
+- CRUD владельца: `POST/PUT/DELETE` (в т.ч. опциональный `specialist_id`)
-- Детали: `GET /v1/events/:id`
+- Детали: `GET /v1/events/:id` (отображение специалиста, если задан)
 - Вхождения: `GET /v1/events/:id/occurrences`
 - Отмена вхождения: `DELETE /v1/events/:id/occurrences/:start_time`
 
 ### 5.6. Запись (bookings)
-- Участник: `POST /v1/events/:id/bookings`, `GET /v1/user/bookings`, `DELETE /v1/bookings/:id`, `GET /v1/bookings/:id`
+- Участник: `POST /v1/events/:id/bookings` только при `booking_open`; иначе UI-сообщение /
-- Владелец: `GET /v1/events/:id/bookings`, `PUT /v1/bookings/:id` с `{ action: confirm | decline }`
+  ответ `403`; `GET /v1/user/bookings`, `DELETE /v1/bookings/:id`, `GET /v1/bookings/:id`
-- Статусы: `pending` | `confirmed` | `cancelled` (режим confirmation календаря: `auto` | `manual` | timeout)
+- Владелец и specialist: `GET /v1/events/:id/bookings`, `PUT /v1/bookings/:id`
+  `{ action: confirm | decline }` (specialist — только свои события, см. BackSpec §2.1.2)
+- Статусы: `pending` | `confirmed` | `cancelled`; confirmation: `auto` | `manual` | timeout
+- Pending резервирует capacity (как на бэке)
 
 ### 5.7. Отзывы
 `GET/POST /v1/reviews`, `GET/PUT/DELETE /v1/reviews/:id`, `GET /v1/user/reviews`. Цели: `event` | `calendar`.
@@ -145,7 +155,8 @@ UI: форма отзыва скрыта без confirmed booking (event — boo
 `GET /v1/subscription`, `POST /v1/subscription` (`start_trial` | `activate` + `plan` + опционально `payment_info`).
 Планы и цены (как Back `plan_price/1`, minor units → ₽): monthly **999**, quarterly **2499**, biannual **4499**, annual **7999**.
 UI: карточки сравнения, локализованный «Бесплатно» без подписки, trial, демо-оплата (шлюз-заглушка).
-Создание commercial-календаря без подписки → `402` → редирект на `/subscription`.
+Создание commercial без подписки → `402` → `/subscription`. После renew commercial-календари
+владельца снова с `booking_open=true` без смены type (BackSpec §2.1.2 restricted → full).
 
 ### 5.10. Тикеты
 - ErrorBoundary / необработанные ошибки → `POST /v1/tickets` с `source=frontend`
@@ -195,13 +206,13 @@ E2E: `e2e/TESTIDS.md`. Моки (`npm run test:e2e`, `project=mock`) — тол
 
 ## 7. Ограничения MVP (Future)
 
-Не реализуется в UI, пока нет user HTTP API:
+Не в текущей волне commercial (§2.1.2 BackSpec уже в scope UI):
-- приглашения / шаринг календаря (`calendar_share`)
+- приглашения / шаринг календаря (`calendar_share`) — фаза 2
-- CRUD специалистов (`calendar_specialist`)
 - серверный logout / revoke session
 - загрузка файлов (вложения)
 - явный `client_type=mobile` (фаза 3 бэка)
 - push-уведомления (таблица `notification` без полноценной доставки)
+- waitlist / оплата услуги клиентом (B2C)
 
 Лайки/дизлайки отзывов: `PUT/DELETE /v1/reviews/:id/vote`, поле `my_vote` в ответах отзывов (EventHubBack#47).