145 lines
7.8 KiB
Markdown
145 lines
7.8 KiB
Markdown
# EventHub — карта для AI-агентов (Zed / Cursor)
|
||
|
||
Кросс-репо ориентир: где какой модуль и куда класть правки. Детали API — в `EventHubBackSpec.md` / `EventHubFrontSpec.md` / `EventHubFrontAdminSpec.md`. Процесс — `WORKFLOW.md`.
|
||
|
||
## Репозитории
|
||
|
||
| Репо | Стек | Зона |
|
||
|------|------|------|
|
||
| `EventHubBack` | Erlang/OTP 28, Cowboy, Mnesia | Public + Admin API |
|
||
| `EventHubFront` | React + Vite + TanStack Query | Клиентский SPA (CalenTIQ) |
|
||
| `EventHubFrontAdmin` | React + Vite | Admin SPA |
|
||
| `EventHubSpec` | Markdown | Спеки, UI-PARITY, workflow |
|
||
| `EventHubAiRouter` | FastAPI + LiteLLM | Zed gateway / routing |
|
||
| `EventHubDevOps` | Docker Swarm | Стенды, deploy |
|
||
|
||
**Правило:** один агент / один PR — один репо. Не смешивать Front и Back в одной сессии правок.
|
||
|
||
Бренд UI: **CalenTIQ**. Внутренние имена репо `EventHub*` не менять.
|
||
|
||
## Домен (кратко)
|
||
|
||
- **User** — владелец календарей / запись на слоты
|
||
- **Calendar** — расписание, специалисты, follow
|
||
- **Event** — слоты (в т.ч. recurring)
|
||
- **Booking / booking-request** — запись / заявка
|
||
- **Ticket / Review / Report** — поддержка, отзывы, жалобы
|
||
- **Subscription** — подписка владельца
|
||
- **Specialist invite** — приглашение специалиста в календарь
|
||
- **Admin** — модерация, аудит, stats (отдельный JWT)
|
||
|
||
Стенды: **dev** локально, **IFT**, **stage** (`https://stage.calentiq.com`, admin `https://admin.stage.calentiq.com`).
|
||
|
||
---
|
||
|
||
## EventHubBack (`src/`)
|
||
|
||
Слои (сверху вниз):
|
||
|
||
| Слой | Путь | Ответственность |
|
||
|------|------|-----------------|
|
||
| HTTP | `handlers/`, `handlers/admin/` | Cowboy handlers, валидация входа/ответа |
|
||
| Logic | `logic/` | Бизнес-правила, оркестрация core |
|
||
| Core | `core/` | Mnesia-таблицы / CRUD сущности |
|
||
| Infra | `infra/` | Mnesia, auth helpers, workers, migrations |
|
||
| Middleware | `middlewares/` | Auth JWT и т.п. |
|
||
|
||
### Типичные пары handler → logic → core
|
||
|
||
| Домен | Handler(s) | Logic | Core |
|
||
|-------|------------|-------|------|
|
||
| Auth / session | `handler_login`, `handler_register`, `handler_auth`, `handler_refresh`, `handler_verify` | `logic_auth`, `logic_auth_session`, `logic_user` | `core_user`, `core_session`, `core_auth_session`, `core_verification` |
|
||
| Password reset | `handler_forgot_password`, `handler_reset_password` | `logic_password_reset` | `core_password_reset` |
|
||
| Calendars | `handler_calendars`, `handler_calendar_by_id`, `handler_calendar_view` | `logic_calendar` | `core_calendar` |
|
||
| Specialists | `handler_calendar_specialists`, `handler_specialist_invites`, `handler_calendar_specialist_invites` | `logic_calendar_specialist`, `logic_specialist_invite` | `core_calendar_specialist`, `core_specialist_invite` |
|
||
| Follow | `handler_calendar_follow`, `handler_user_following` | `logic_calendar_follow` | `core_calendar_follow` |
|
||
| Events | `handler_events`, `handler_event_by_id`, `handler_event_occurrences` | `logic_event`, `logic_recurrence` | `core_event` |
|
||
| Bookings | `handler_bookings`, `handler_booking_by_id`, `handler_user_bookings`, `handler_user_booking_requests` | `logic_booking` | `core_booking` |
|
||
| Reviews | `handler_reviews`, `handler_review_by_id`, `handler_user_reviews`, `handler_review_vote` | `logic_review` | `core_review`, `core_review_vote` |
|
||
| Tickets | `handler_tickets`, `handler_ticket_by_id` | `logic_ticket` | `core_ticket` |
|
||
| Reports | `handler_reports` | `logic_report` | `core_report` |
|
||
| Search / lookup | `handler_search`, `handler_users_lookup` | `logic_search`, `logic_user_lookup` | — |
|
||
| Subscription | `handler_subscription` | `logic_subscription` | `core_subscription` |
|
||
| Notifications | — | `logic_notification` | `core_notification` |
|
||
| Admin API | `handlers/admin/admin_handler_*` | `logic_admin`, `logic_moderation`, `logic_automoderation`, `logic_stats` | `core_admin`, `core_admin_*`, `core_banned_words`, `core_automod_*` |
|
||
|
||
Миграции: `src/migrations/`. Сборка/тесты: **только WSL** (`source scripts/wsl-dev-env.sh`, `rebar3 eunit`).
|
||
|
||
---
|
||
|
||
## EventHubFront (`src/`)
|
||
|
||
| Путь | Зачем |
|
||
|------|--------|
|
||
| `pages/` | Экраны маршрутов |
|
||
| `api/*Api.ts` | HTTP к Back |
|
||
| `components/calendar/` | UI календаря / workspace |
|
||
| `layouts/AppShell.tsx` | Оболочка |
|
||
| `store/` | Zustand (auth, mood, locale, calendar context) |
|
||
| `hooks/` | React hooks (API, WS, swipe) |
|
||
| `lib/` | Утилиты (payloads, schedule, booking display) |
|
||
| `i18n/` | Локали |
|
||
|
||
### Страницы → смысл
|
||
|
||
| Page | Маршрут (ориентир) | Тема |
|
||
|------|-------------------|------|
|
||
| `DiscoverPage` | discover | Поиск / лента |
|
||
| `CalendarsPage` | calendars | Список календарей |
|
||
| `CalendarWorkspacePage` | `/c/:id` | Основной workspace слотов |
|
||
| `BookingsPage` | bookings | Мои записи / inbox заявок |
|
||
| `ReviewsPage` | reviews | Отзывы |
|
||
| `TicketsPage` / `TicketDetailPage` | tickets | Тикеты |
|
||
| `SubscriptionPage` | subscription | Подписка |
|
||
| `FollowingPage` | following | Подписки на календари |
|
||
| `SpecialistInvitesPage` | invites | Инвайты специалиста |
|
||
| `ProfilePage` / `MorePage` | profile / more | Профиль / меню |
|
||
| `pages/auth/*` | login/register/… | Auth |
|
||
|
||
npm / Playwright — **только WSL** (см. `.cursor/rules/npm-wsl.mdc`).
|
||
|
||
---
|
||
|
||
## EventHubFrontAdmin (`src/`)
|
||
|
||
| Путь | Зачем |
|
||
|------|--------|
|
||
| `pages/dashboard` | Дашборд |
|
||
| `pages/users`, `calendars`, `events` | Справочники |
|
||
| `pages/tickets`, `reports`, `inbox` | Модерация / inbox |
|
||
| `pages/reviews`, `automod`, `banned-words` | Контент / автомод |
|
||
| `pages/subscriptions`, `admins`, `audit`, `monitoring` | Биллинг / админы / аудит / метрики |
|
||
| `api/*Api.ts` | Admin API client |
|
||
| `store/authStore.ts` | Admin session |
|
||
|
||
---
|
||
|
||
## EventHubAiRouter (`router/`, `config/`)
|
||
|
||
| Файл / папка | Зачем |
|
||
|--------------|--------|
|
||
| `router/router.py` | Zed `/v1/chat/completions`, ветка tools vs text |
|
||
| `router/hierarchical.py` | Plan (Qwen3.8-Max) / workers / verify (DeepSeek) / plan_confirm |
|
||
| `router/agent_hier.py` | При `tools`: Coder-30B executor + tool_calls (Zed Write) |
|
||
| `router/orchestrator.py` | Tiers / lanes A–B–C, Redis session |
|
||
| `config/orchestration.yaml` | Модели plan/verify/executor, таймауты, synthetic=never |
|
||
| `config/providers.yaml` | Novita / VPN (`novita-planner` = Max) |
|
||
| `scripts/gen-litellm-config.py` | Генерация LiteLLM YAML |
|
||
|
||
IFT: `https://ai-router.ift.calentiq.com/v1`, модель `smart-router`.
|
||
Клиент-канон: **Zed Agent** (openai-compatible) → AiRouter; не Claude Code/Codex ACP как primary (обход бюджета).
|
||
|
||
---
|
||
|
||
## Куда править (шпаргалка)
|
||
|
||
| Задача | Репо | Куда смотреть |
|
||
|--------|------|----------------|
|
||
| Баг API / Mnesia | Back | `handlers` → `logic` → `core` |
|
||
| UI клиент | Front | `pages` + `api` + `components/calendar` |
|
||
| UI админки | FrontAdmin | `pages` + `api` |
|
||
| Контракт / процесс | Spec | `*Spec.md`, `WORKFLOW.md`, `design/` |
|
||
| Zed routing / hierarchical | AiRouter | `router/*`, `config/orchestration.yaml` |
|
||
|
||
Перед крупным планом: **утвердить** шаги с пользователем; не раздувать scope (не трогать соседний репо «заодно»).
|