Обзор аналитики

AACSearch пишет каждый поиск, каждый клик, каждую конверсию и каждое операционное событие, касающееся ваших индексов. Данные доступны в трёх местах — страница Analytics в дашборде, oRPC-процедуры аналитики и CSV / JSON export — чтобы вы могли и диагностировать конкретные запросы, и закрывать петлю, возвращая инсайты в relevance, наполнение контента и анализ выручки.

Эта секция — клиент-facing справочник по этим данным. Страница дашборда покрывает UI; эта секция — концепции, схемы и воркфлоу, превращающие телеметрию в улучшения.

Что меряется

Tenant scope: у каждой строки есть organizationId. Cross-org чтений нет (Инвариант 5).

Схема событий (клиентская)

Публичный сбор событий — POST /events/track (см. packages/api/modules/search/events-public.ts). Принимаемая форма намеренно узкая — без email, без полного IP, UA в 256 символов — её безопасно ставить на любой storefront:

{
  type: "search_query" | "zero_results" | "result_click" | "widget_open"
      | "filter_used" | "conversion" | "visit" | "click";
  sessionId?: string;
  anonymousUserId?: string;
  query?: string;
  productId?: string;
  position?: number;
  filters?: Record<string, unknown>;
  sort?: string;
  locale?: string;
  referrer?: string;
  queryId?: string;             // связывает клики с поиском, который их породил
  conversionType?: string;      // "purchase", "signup", "add_to_cart", …
  metadata?: Record<string, unknown>;
}

Можно слать пачкой до 50 событий ({ events: [...] }) и использовать sendBeacon на unload — оба пути first-class в виджете.

Точные имена (search_query, result_click, …) совпадают с тем, что появляется в таблицах аналитики и тем, что эмиттит SDK / виджет. Держите согласованными; не выдумывайте свои типы на клиенте.

Откуда читать

Дашборд

Analytics дашборд — KPI-плитки, временные ряды, Top Queries, Failed Queries, Activity. UI для всех; селектор периода управляет всеми табами. Ретеншн зависит от плана (24 ч на всех; 30 дней на платных).

oRPC-процедуры

Для программного доступа — protected-процедуры в packages/api/modules/search/router.ts:

Каждая принимает organizationId + period (24h, 7d, 30d) и возвращает Prisma-строки для любого UI.

Export

CSV и JSON — Export.

Замкнутая петля

Аналитика сама по себе — просто дашборд. Смысл — превратить каждую метрику в действие:

E-commerce-петля типична: zero-results → видим missing brand → синоним → меряем восстановление в CTR того же запроса в следующем периоде. SaaS / knowledge-base: низкий-CTR-запрос → переписать title статьи → re-ingest → меряем рост CTR.

Ретеншн и privacy

• Ретеншн. Все строки событий хранятся в окне плана — обычно 90 дней. Агрегаты в SearchActivityEvent хранятся дольше.
• PII. Публичный events-эндпоинт сознательно не принимает полный IP / email. UA обрезается. metadata — opaque, но не больше 4 КБ JSON.
• GDPR / DPA. Scope персональных данных AACSearch — Security & Compliance. Путь аналитики виджета — в стандартном DPA.
• Right-to-be-forgotten. Удаление по anonymousUserId — см. Data privacy по процедуре редактирования.

Примеры

E-commerce

Смотрим: top queries, conversion rate per query, no-result rate, использование фасета brand.

Что читать вместе:

• topQueries за неделю + ctrAnalytics дневной тренд.
• analyticsEvents с фильтром type=conversion для атрибуции выручки.
• noResults панель + brand-additions от контент-команды.

SaaS / knowledge-base

Смотрим: zero-result rate, click-to-article rate, refusal rate у AI ответа.

Что читать вместе:

• Топ zero-result-запросов → gap-ы в help-center.
• knowledge.usageMetrics расход токенов + всплески refusal-rate → регрессии качества после обновления документов.

Связанные страницы

• Queries — popular, low-CTR, reformulations
• Conversions — search-to-click, search-to-conversion
• No-results — петля восстановления
• Relevance quality — возврат аналитики в ранжирование
• Export — CSV / JSON, ретеншн, BI
• Analytics дашборд — UI продукта
• Widget analytics events — что эмиттит виджет