EventHubSpec/EventHubFrontSpec.md

EventHub Client UI — Техническое задание

Клиентское Web SPA для end-user: владельцы календарей и участники. Администраторы работают в EventHubFrontAdmin. Контракт API — EventHubBackSpec.md и маршруты EventHubBack (порт HTTP 8080, WS 8081).

1. Роли и режимы

Один пользовательский аккаунт; UI разделяется по контексту (не по JWT-роли админки):

Режим	Описание	Ключевые возможности
Участник	Поиск и запись на события коммерческих календарей	Поиск, просмотр, запись (если booking_open), отмена, отзывы, жалобы, тикеты
Владелец	Управление своими календарями	CRUD календарей/событий/специалистов, заявки confirm/decline, подписка
Специалист	Confirm заявок на «свои» события	Те же экраны календаря; confirm/decline только где specialist_id = текущий user

Deep-link на календарь, владельцем которого является текущий пользователь, показывает owner-действия (редактирование, заявки).

Права на операции проверяет бэкенд; фронт скрывает недоступные действия по owner_id / ответу API.

2. Аутентификация и авторизация

Эндпоинты:

• POST /v1/register — регистрация (email, password); статус пользователя pending до верификации.
• POST /v1/verify — подтверждение email { token }; после успеха у пользователя есть дефолтный personal-календарь.
• POST /v1/login — вход; ответ { token, refresh_token, user }. Сессия auth_session с client_type=web.
• POST /v1/refresh — ротация пары токенов по { refresh_token }.
• GET /v1/user/me — профиль текущего пользователя.

Реализация:

• JWT в localStorage под ключами, отличными от Admin UI (избежать коллизии при общем origin).
• Axios: Authorization: Bearer <access>; при 401 — single-flight refresh; при неудаче — редирект на /login.
• При старте приложения — GET /v1/user/me при наличии токена.
• Logout — только клиентский (очистка storage); серверного revoke нет.
• WebSocket: ws://…:8081/ws?token=<access_jwt>; subscribe/unsubscribe по calendar_id.

3. Технологический стек

• Язык: TypeScript
• Сборщик: Vite
• UI: React 19 + Tailwind CSS 4 + shadcn/Radix
• Типографика: Syne (display) + Manrope (UI)
• Состояние: Zustand (auth + mood + lens + calendar context), TanStack React Query v5 (сервер)
• HTTP: Axios с интерсепторами
• Формы: React Hook Form + Zod
• Дата/время: dayjs (ru locale)
• i18n: react-i18next (ru, en)
• Роутинг: React Router 7
• WebSocket: нативный API с переподключением
• Контейнеризация: Docker, Nginx (прокси /v1 → user API :8080, /ws → :8081)

3.1. UX / IA (calendar workspace, mobile-first)

• Главная сущность — календарь. Центр UI — виджет с видами месяц (default) / неделя / день.
• Главные вкладки: Календарь (/, /c/:id), Найти (/search), Записи (/bookings), Ещё (/more).
• Записи (/bookings) — grouped inbox: «К подтверждению» (owner/specialist pending + Confirm/Decline) и «Мои записи» (participant); пустые группы скрывать. Confirm на карточке события остаётся. Past/expired: бейдж expired («истекла»), Cancel скрыт; empty-state с CTA Discover / календари. Время на list-карточках — вторичное к title (.eh-book-list-time).
• В Ещё: язык (LanguageSwitcher); пункт входящих specialist invites скрыт при pending=0; при pending > 0 — badge со счётчиком (deep-link /invites работает). Mood в Ещё нет — chip в AppShell рядом с BrandWordmark (Front#40; ранее Front#39 в chrome workspace).
• Mood + Lens (Front#39/#40 + controls IA): mood chip (FLOW/MOMENTUM/CONTROL → sheet picker) — в AppShell рядом с логотипом (не в toolbar Month/Week/Day). Workspace chrome разнесён по зонам: (1) селектор календаря; (2) период + вид Месяц/Неделя/День; (3) owner schedule actions («+ Новое событие», «Заполнить расписание» — отдельный ряд); (4) lens «Обзор / На сегодня / Заявки» — в шапке collapsible lens strip (underline/text tabs на desktop, sheet на mobile; не рядом с ViewMode chips). Strip — Front-only derive из уже загруженных events/bookings. Без flip календаря; без 4-го CREATOR. Strip по умолчанию раскрыт на desktop, свёрнут на mobile. Нет на HTML-архиве месяца.
• Week view (Front#40): одна строка day-headers (без дубля заголовков WeekDayColumn); горизонтальный скролл через .eh-cal-week-scroll (mobile ~390).
• Контекст виджета: свой календарь (селектор) или чужой (browse после поиска). Чужой personal — только просмотр; чужой commercial с booking_open=true — запись; при booking_open=false (restricted / нет подписки владельца) — просмотр + сообщение «Запись временно недоступна».
• Свой default personal: поверх сетки — overlay confirmed записей на чужие commercial слоты (Front-only: GET /v1/user/bookings → events/calendars). Заголовок событие · студия · специалист; клик → /c/:foreignCalId/e/:eventId (не в своём cal). Дополнительно (Front#43): overlay своих рабочих слотов commercial, где specialist_id = текущий user — gate через accepted GET /v1/user/specialist-invites
  • проверка active в GET …/specialists, затем GET …/events?from&to; title событие · студия. Personal владельца без accepted invite / без своих слотов чужой roster не зеркалит.
• Guest на чужом commercial (D9 модель B): roster карточек активных специалистов → тап → сетка только со слотами event.specialist_id = выбранный; «Все слоты студии» снимает фильтр. Это не chip-filter на общей сетке. Book как обычно — без specialist в body заявки (слот уже привязан к спецу на событии).
• Agenda rail: empty copy зависит от типа календаря — personal «Нет событий», commercial «Нет слотов».
• Выбор события открывает карточку действий: mobile — bottom sheet; desktop — боковая панель. Действия зависят от роли (owner / participant).
• Без выбранного события — панель «О календаре» (описание, title/meta, рейтинг, отзывы). Форма отзыва на календарь/событие — только при confirmed booking; жалоба доступна без записи. На чужом календаре — CTA «Отслеживать» / Follow (не путать с платной «Подписка»); follow не открывает форму отзыва.
• На чужом /c/:id — CTA «Мой календарь» и таб Calendar не aria-current (intent browse).
• Список отслеживаемых: /following (из «Ещё»).
• Открытие события — navigate push (не replace), чтобы Back возвращал к календарю.
• Owner: WS subscribe на активный календарь; PUT события из карточки; PUT календаря на /calendars.
• Поиск (/search): query/filters в URL params (восстановление при возврате); chip type фильтрует discovery tops без ухода из Popular; в строке результата — id snippet и calendar_title для event.
• CRUD своих календарей — /calendars (из «Ещё»). Legacy /discover, /calendars/:id → redirects.
• На мобиле — bottom tab bar (+ safe-area); на desktop — одна строка chrome: logo + mood chip | nav tabs | nickname + logout (не два ряда header+nav). Сырой email в chrome не показывать — primary identity = nickname (fallback без @). Nav aria-current синхронизирован с useLocation (без remount Outlet по pathname).
• Mood themes — см. §3.2.

3.2. Настроения (mood themes) / режимы CalenTIQ

Публичный бренд UI: CalenTIQ (см. BRANDING.md). Внутренние ключи API/preferences без изменений. Три mood только — без CREATOR, без flip календаря.

Пользователь переключает визуальный режим; атрибут html[data-mood]. Для гостя и при отсутствии preferences.mood — дефолт calm (в профиль при логине не пишется). После входа смена mood сохраняется в preferences.mood через PATCH /v1/user/me.

UI-лейбл	Идентификатор (API)	Характер
FLOW	calm	sage/mist, мягкий градиент (default)
MOMENTUM	energetic	тёмный ink + coral #FF6A3D
CONTROL	business	charcoal + steel #324A5F, более жёсткие радиусы

Где mood:

• Auth (/login, /register, /verify, forgot/reset) — compact MoodSwitcher (+ language).
• AppShell — primary control: mood chip рядом с BrandWordmark → dialog/sheet (не в /more, не в calendar toolbar Month/Week/Day). Desktop: logo + mood | nav | nickname + logout.

Lens (отдельно от mood и от view month/week/day): overview / today / bookings (UI: Обзор / На сегодня / Заявки). Переключатель — в шапке lens strip (не в toolbar рядом с Месяц/Неделя/День). Persist только localStorage (eh.calendar.lens + eh.calendar.lens.pinned); не поле профиля / Back API. Soft-default при смене mood, если lens не pinned пользователем: FLOW→overview, MOMENTUM→today, CONTROL→bookings. Strip над сеткой: free gaps сегодня / события сегодня / upcoming bookings (derive на клиенте из уже загруженных данных).

Язык UI (ru/en): до логина — navigator.language; после входа — поле language профиля (PATCH /v1/user/me). Если в профиле язык пуст — при логине записывается текущий (браузерный/выбранный на экране входа). Язык также в /more и в форме /profile.

4. Маршруты

Публичные:

• /login, /register, /verify

Защищённые (ProtectedRoute):

• / — Calendar Workspace (автовыбор своего календаря или empty-state)
• /c/:calendarId — workspace с календарём
• /c/:calendarId/e/:eventId — workspace + карточка события
• /search — поиск календарей/событий
• /bookings — grouped inbox: (A) к подтверждению (owner/specialist pending) + (B) мои записи участника; deep-link в /c/.../e/...
• /calendars — управление своими календарями (CRUD)
• /more — вторичное меню + language switcher (без mood); пункт specialist invites скрыт, если входящих pending = 0; при pending > 0 — badge со счётчиком (deep-link /invites?token= работает)
• /invites — inbox входящих specialist invites (не смешивать с /bookings)
• /following — отслеживаемые чужие календари (follow; не платная Подписка)
• /reviews, /subscription, /tickets, /profile

Redirects: /discover → /search; /calendars/:id → /c/:id; /calendars/:id/events/:eventId → /c/:id/e/:eventId.

Состояние вида: Zustand calendarContextStore (view, cursorDate, last own calendarId в localStorage); lens — lensStore + localStorage (см. §3.2).

5. Модули

5.1. Auth

Регистрация, верификация, вход, восстановление сессии.

5.2. Профиль

GET /v1/user/me + форма на /profile. Редактируемые через PATCH /v1/user/me: nickname, phone, timezone, avatar_url, language; смена пароля — current_password + password. Read-only в UI: id, email, role, status. Mood — chip в AppShell рядом с BrandWordmark (+ compact на auth); persist preferences.mood через PATCH /v1/user/me (не в /more, не в calendar toolbar). Язык при первом визите — из браузера; при первом логине без language — пишется в профиль. Mood по умолчанию calm, при логине не сидится. Lens — только localStorage (не профиль).

5.3. Поиск (участник)

GET /v1/search — фильтры (type, q, tags, даты, lat/lon/radius, sort, order, пагинация). Без q/дат/tags/geo/sort — топы календарей и событий; иначе — поиск. В списке бейдж типа — calendar|event (не personal/commercial). Даты, теги, geo и сортировка свёрнуты по умолчанию. Переход к /c/:id или /c/:id/e/:eventId. В результатах calendar (и event, если Back отдаёт) может быть image_url — Discover показывает cover (.eh-discover-media--photo); иначе mood wash + initials (.eh-discover-media--fallback, не fake photo-hero). Битый image_url → fallback. Upload API нет — поле URL (seed / ручная установка).

5.4. Календари

• Список своих: GET /v1/calendars
• 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; при booking_open=false — баннер «Запись временно недоступна», кнопка записи скрыта
• HTML month view владельца: GET /v1/calendars/:calendar_id/view?month=YYYY-MM — при переключении виджета на прошедший месяц (owner + вид «Месяц») автоматически подменяет клиентский grid серверным HTML (live/архив, задача #15). Текущий и будущие месяцы — React-виджет по GET …/events.
• Создание / апгрейд commercial без уже active sub/trial → 402 → /subscription (trial — явный start_trial, не auto при create); после оплаты — возврат к созданию/редактированию
• Владелец commercial: специалисты через invite (не сырой user_id): typeahead GET /v1/users/lookup и/или email → POST …/specialist-invites; список active + исходящие pending; deactivate/remove принятых. Выбор specialist_id в форме события (только active). Баннер «подписка истекла / истекает» при booking_open=false. SpecialistsPanel (owner): mobile density — имя/теги сверху, actions снизу full-width (invite/deactivate не ломать); desktop — вертикальный rail + scroll.
• Guest browse commercial: roster активных → фильтр расписания по specialist_id (D9 B; см. §3.1); owner panel не смешивать с guest roster.
• Invitee: inbox входящих GET /v1/user/specialist-invites на /invites — принять / отклонить; deep-link из email → accept по token после логина. В More пункт «Приглашения» показывается только при pending > 0 с badge счётчика (не путать с booking-заявками на /bookings).

5.5. События

• Список: GET /v1/calendars/:calendar_id/events
• 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 только при booking_open; иначе UI-сообщение / ответ 403; GET /v1/user/bookings, DELETE /v1/bookings/:id, GET /v1/bookings/:id. Тело book без specialist (назначение — на event.specialist_id).
• Владелец и specialist:
  • на карточке события: GET /v1/events/:id/bookings + Confirm/Decline (обязательно)
  • inbox /bookings группа «К подтверждению»: GET /v1/user/booking-requests (actionable pending, где user — owner календаря или event.specialist_id; past-pending Back отдаёт как expired и не включает в inbox); те же PUT /v1/bookings/:id { action: confirm | decline } (на expired → 409)
• UI /bookings: две группы (пустые скрывать): К подтверждению + Мои записи (upcoming/past participant). specialist_invite сюда не попадает. Empty state: title + hint + CTA Discover / «Мои календари». Время слота на list-карточках — soft (secondary to title).
• Confirmed overlay на personal (Front-only, Front#35): confirmed из GET /v1/user/bookings на чужих commercial — догрузить event/calendar и нарисовать на своём default personal grid; title событие · студия · специалист; клик → /c/:foreignCalId/e/:eventId. Back API не менялся.
• Specialist duty overlay на personal (Front-only, Front#43): на своём personal — слоты commercial, где event.specialist_id = текущий user. Gate: accepted invites (GET /v1/user/specialist-invites) → unique calendar_id → active specialist (GET /v1/calendars/:id/specialists) → list events viewport. Title событие · студия; клик → /c/:commercialId/e/:eventId. Legacy specialist без invite-записи — вне MVP. Не зеркалить чужой roster на personal owner.
• Статусы: pending | confirmed | cancelled | expired; confirmation: auto | manual | timeout. Past+pending / expired в «Мои записи» и на EventActionCard — бейдж «истекла», Cancel скрыт. На past-событии Book скрыт. Defensive: если API ещё отдал past pending — UI мапит в expired.
• Pending резервирует capacity (как на бэке)

5.7. Отзывы

GET/POST /v1/reviews, GET/PUT/DELETE /v1/reviews/:id, GET /v1/user/reviews. Цели: event | calendar. Голос: PUT /v1/reviews/:id/vote { "value": "like"|"dislike" }, DELETE /v1/reviews/:id/vote; в ответах — my_vote. UI: форма отзыва скрыта без confirmed booking (event — booking на это событие; calendar — booking на событие календаря); подсказка + жалоба остаются.

5.8. Жалобы

POST /v1/reports — target_type: event | calendar | review. Жалоба не требует booking.

5.9. Подписка

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, демо-оплата (шлюз-заглушка). Create/upgrade commercial без уже active sub/trial → 402 → /subscription (сначала явный start_trial или activate; auto-start trial при create нет, Back#61 / BackSpec §2.1.2, §2.9). После renew commercial-календари владельца снова с booking_open=true без смены type (restricted → full).

5.10. Тикеты

• ErrorBoundary / необработанные ошибки → POST /v1/tickets с source=frontend
• Форма «Сообщить о баге» → source=manual
• Список: GET /v1/tickets, детали GET /v1/tickets/:id

5.11. Realtime

Подписка WS на открытые календари; сообщения calendar_update, event_update, booking_update → инвалидация React Query.

5.12. Версии сборки

Как в Admin UI / Back (EventHubSpec/WORKFLOW.md §6):

• Product MAJOR.MINOR из EventHubSpec/VERSION (CI: scripts/resolve-product-version.sh; локальный VERSION — fallback).
• Bake: VITE_APP_VERSION, VITE_APP_BUILD, VITE_GIT_SHA, VITE_BUILT_AT.
• UI: экран «Ещё» — UI {version}.{build} (sha); API — GET /health → API ….

6. Структура проекта

src/
├── api/          — Axios client + *Api.ts
├── hooks/        — React Query hooks
├── store/        — Zustand (auth)
├── pages/        — auth, discover, calendars, events, bookings, reviews, subscription, tickets, profile
├── layouts/      — consumer shell (не admin Control Center)
├── components/ui — shadcn primitives
├── i18n/         — locales ru/en
├── schemas/      — Zod
└── types/

Репозиторий: EventHubFront.

6.1. Стенды и балансировщик

Stand	URL	Swarm
IFT	https://ui.ift.eventhub.local	alias client-ui
stage	https://ui.stage.eventhub.local	alias client-ui
dev	https://ui.dev.eventhub.local	alias client-ui

Образ registry: git.sabilin.com/eventhub/eventhub-front. Traefik host-based (без path prefix). Nginx в контейнере: / SPA, /v1/ → eventhub:8080, /ws → eventhub:8081.

CI: lint → build → Playwright mock (до push) → push image → deploy IFT → e2e-ift (live API) → stage → e2e-stage (live API) (зеркало FrontAdmin). Деплой зависит от EventHubDevOps#7 (deploy-service.sh … client).

E2E: e2e/TESTIDS.md. Моки (npm run test:e2e, project=mock) — только локально / до деплоя. После деплоя на IFT/stage — SMOKE_USER_* + npm run test:e2e:ift|stage против реального API (без Playwright route-моков).

7. Ограничения MVP (Future)

Не в текущей волне (кроме specialist_invite — см. §5.4 / BackSpec §2.1.2):

• шаринг календаря с правами (calendar_share) — фаза 2 (не путать со specialist_invite)
• серверный logout / revoke session
• загрузка файлов (вложения)
• явный client_type=mobile (фаза 3 бэка)
• полноценный push (сейчас in-app notification + email для specialist_invite)
• waitlist / оплата услуги клиентом (B2C)

Лайки/дизлайки отзывов: PUT/DELETE /v1/reviews/:id/vote, поле my_vote в ответах отзывов (EventHubBack#47).

8. Источники истины

• Маршруты и поведение: EventHubBack/src/eventhub_app.erl + handlers
• Продукт и auth: EventHubBackSpec.md §1–2, §6.1
• Swagger client-swagger.json — вторичный (возможен drift, например /v1/auth/refresh vs /v1/refresh)