From f3f199c79101fc2763d13ea1e5200c1a80366724 Mon Sep 17 00:00:00 2001 From: Aleksey Sabilin Date: Wed, 22 Jul 2026 16:12:54 +0300 Subject: [PATCH] Document commercial calendars: booking_open, specialists, restricted UX. Refs EventHub/EventHubSpec#6 Refs EventHub/EventHubBack#54 --- EventHubBackSpec.md | 139 ++++++++++++++++++++++++++++++++++++------- EventHubFrontSpec.md | 41 ++++++++----- 2 files changed, 142 insertions(+), 38 deletions(-) diff --git a/EventHubBackSpec.md b/EventHubBackSpec.md index ff95fde..9c84d76 100644 --- a/EventHubBackSpec.md +++ b/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 календаря (название, описание, теги, владелец) -- Расшаривание по ссылке (публичная/приватная) -- Приглашение пользователей с правами "запись" или "администрирование" -- Типы календарей: personal (бесплатный, без записи), commercial (платный, запись клиентов, - специалисты) -- Гибкое подтверждение заявок: auto (автоматически), manual (вручную), timeout (авто через N - секунд) +- Расшаривание по ссылке / приглашения с правами (`calendar_share`) — **фаза 2** (таблица есть; + user HTTP API и UI — Future, см. §2.1.3) +- Типы календарей: `personal` | `commercial` — семантика и коммерческий контур: **§2.1.2** +- Гибкое подтверждение заявок: `auto` | `manual` | `{timeout, N}` (секунды) — детали §2.1.2 / §2.3 - Теги календаря, рейтинг (средняя оценка, количество голосов) - После успешной верификации 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) -Реализована отдельная таблица `calendar_specialist`, связывающая пользователя (специалиста) с -календарём. Специалист может иметь отображаемое имя (`name`) и список специализаций -(`specialization`). Статус специалиста: `active` | `inactive`. +### 2.1.1. Специалисты календаря +Таблица `calendar_specialist`: связь пользователя-специалиста с **commercial**-календарём. +Поля: `calendar_id`, `user_id`, `name` (отображаемое имя в этом календаре), +`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. Запись участников и подтверждение -- Пользователь может отправить заявку на участие в событии. -- В зависимости от `confirmation` календаря заявка либо подтверждается автоматически, либо - ожидает ручного подтверждения владельцем, либо подтверждается по таймауту. -- Бронирование имеет статусы: `pending`, `confirmed`, `cancelled`. -- Пользователь может отменить свою запись. -- Владелец календаря может подтвердить или отклонить заявку. -- При подтверждении фиксируется время (`confirmed_at`). -- Вместимость события (`capacity`) ограничивает количество подтверждённых записей. +- Запись доступна только на событиях **commercial**-календаря с `booking_open=true` (§2.1.2). +- На personal → `403` (`personal_calendar`); при restricted commercial → `403` (`subscription_inactive`). +- В зависимости от `confirmation` календаря: auto / manual / timeout (§2.1.2). +- Статусы: `pending`, `confirmed`, `cancelled`. +- **Capacity:** лимит слотов считают `pending` + `confirmed` (pending резервирует место). +- Участник может отменить свою запись (`DELETE`). +- Confirm/decline: владелец календаря — любые заявки; active specialist — только на событиях + со своим `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` — создать календарь. -- `GET /v1/calendars/:id` — календарь (поле `following` для текущего пользователя). -- `PUT /v1/calendars/:id` — обновить календарь. +- `POST /v1/calendars` — создать календарь (`commercial` → подписка/trial; иначе `402`). +- `GET /v1/calendars/:id` — календарь (`following`, `booking_open` для текущего контекста). +- `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` — событие. diff --git a/EventHubFrontSpec.md b/EventHubFrontSpec.md index de5d36f..0bf7ffc 100644 --- a/EventHubFrontSpec.md +++ b/EventHubFrontSpec.md @@ -8,8 +8,9 @@ | Режим | Описание | Ключевые возможности | |-------|----------|----------------------| -| Участник | Поиск и запись на события коммерческих календарей | Поиск, просмотр календаря/события, запись, отмена своей записи, отзывы, жалобы, тикеты | -| Владелец | Управление своими календарями | CRUD календарей и событий, список заявок, confirm/decline, подписка | +| Участник | Поиск и запись на события коммерческих календарей | Поиск, просмотр, запись (если `booking_open`), отмена, отзывы, жалобы, тикеты | +| Владелец | Управление своими календарями | 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` -- Детали: `GET /v1/events/:id` +- CRUD владельца: `POST/PUT/DELETE` (в т.ч. опциональный `specialist_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` -- Владелец: `GET /v1/events/:id/bookings`, `PUT /v1/bookings/:id` с `{ action: confirm | decline }` -- Статусы: `pending` | `confirmed` | `cancelled` (режим confirmation календаря: `auto` | `manual` | timeout) +- Участник: `POST /v1/events/:id/bookings` только при `booking_open`; иначе UI-сообщение / + ответ `403`; `GET /v1/user/bookings`, `DELETE /v1/bookings/:id`, `GET /v1/bookings/:id` +- Владелец и 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: -- приглашения / шаринг календаря (`calendar_share`) -- CRUD специалистов (`calendar_specialist`) +Не в текущей волне commercial (§2.1.2 BackSpec уже в scope UI): +- приглашения / шаринг календаря (`calendar_share`) — фаза 2 - серверный logout / revoke session - загрузка файлов (вложения) - явный `client_type=mobile` (фаза 3 бэка) - push-уведомления (таблица `notification` без полноценной доставки) +- waitlist / оплата услуги клиентом (B2C) Лайки/дизлайки отзывов: `PUT/DELETE /v1/reviews/:id/vote`, поле `my_vote` в ответах отзывов (EventHubBack#47).