# Аналитика площадок для AvitoAuto

## 1. Продуктовое решение

AvitoAuto стоит развивать как центр принятия решений по каналам продаж. Владелец должен понимать, где появляются качественные обращения, сколько стоит подтверждённый результат, какие темы растут в поиске и куда имеет смысл направить следующий эксперимент. Для этого нужны собственные данные бизнеса, статистика поискового спроса и отдельный слой внешних оценок площадок.

Рекомендуемая модель: собственный интерфейс, расчёты и сборщики, доступные официальные API и проверенные выгрузки, уже установленная библиотека графиков. Обязательных платных аналитических сервисов и сторонних ИИ-помощников нет. Не требуется писать свою универсальную BI-систему, поисковую машину или инфраструктуру слежения за всем интернетом. Разработать полностью следует именно бизнес-контур AvitoAuto: связи объявления с заявкой и сделкой, понятное сравнение, происхождение каждого числа, рекомендации и действия.

Сейчас подготовлены десять связанных экранов, вычислительная модель, поиск, фильтры, сравнение, сценарий бюджета и экспорт. Коммерческие показатели, запросы и позиции в макетах синтетические. Подключение API, длительный сбор истории и реальная атрибуция относятся к будущей реализации. Реестр 46 площадок заимствован из ранее подготовленного исследования проекта; все его источники заново в этой работе не перепроверялись.

Исследование источников и лицензий выполнено по состоянию на 10 сентября 2026. Проверены README, лицензии и метаданные 15 репозиториев GitHub с фиксацией полного SHA. Это анализ пригодности компонентов, а не аудит безопасности всего их кода, не запуск их тестов и не подтверждение работы на GX10. Документация API подтверждает наличие интерфейса, но не доступ конкретного аккаунта.

### Что будет полезно разным бизнесам

| Бизнес | Решение на основе аналитики | Основной результат |
|---|---|---|
| Частный продавец | Где разместить вещь и стоит ли платить за продвижение | Качественные обращения, срок до продажи, расходы |
| Автоцентр | Какие площадки и автомобили приносят осмотры и сделки | Запись на осмотр, продажа, валовая прибыль |
| Магазин и запчасти | Где востребована категория и какие позиции окупаются | Заказ, выкуп, возврат, маржа после комиссии |
| Услуги | Какие районы и работы дают записи | Подтверждённая запись, выполненная работа |
| Недвижимость | Какие каналы дают реальные показы | Квалифицированный лид, показ, закрытая сделка |
| Подбор персонала | Где приходят подходящие отклики | Отклик, интервью, найм; отдельные права на данные |
| Агентство | Как объяснить клиенту результат и распределить работу | Отчёт по клиенту, расходы, согласованные эксперименты |

Автомобильный пример в макете выбран для наглядности. Схема данных и план охватывают направления существующего реестра. Продажу машины и заявку на ремонт нельзя сравнивать по одной норме конверсии: отрасль, тип результата и модель сделки являются частью фильтра.

## 2. Что есть в проекте

В `app/page.tsx` находятся маршруты кабинета; в `components/` — экраны, обучение и помощь. `lib/domain.ts` хранит модель учебного состояния. Серверная логика расположена в `server/app.mjs` и `server/workflow.mjs`, использует SQLite, пространства компаний, роли, версии объявлений, очередь и аудит. В зависимостях уже есть React и Recharts. Основную сборку и серверные таблицы текущая работа не меняет.

В изученных маршрутах не обнаружен полноценный модуль межплощадочной аналитики, Wordstat, Метрики и поисковых снимков. Обзор публикаций, баланс и отчёт автозагрузки сами по себе не обеспечивают маркетинговую аналитику. Новые адаптеры необходимо проектировать отдельно от исполнительной очереди публикаций, чтобы медленные отчёты не задерживали кабинет.

Материалы `docs/platforms-2026-09-10/` уже задают 46 каналов, категории, варианты подключения и ограничения. Материалы `docs/ai-bots-2026-09-10/` предусматривают аналитика объявлений. Новая работа дополняет эти планы единым контрактом данных и измеримой бизнес-логикой; второго конкурирующего реестра площадок в production создавать не нужно.

## 3. Рабочие макеты

| Экран | Что можно сделать сейчас | Что требует живой реализации |
|---|---|---|
| [Обзор](/#overview) | Менять период и регион, видеть пересчёт заявок и расходов | Синхронизация кабинетов и CRM |
| [Сравнение](/#compare) | Выбирать каналы, сортировать столбцы, раскрывать формулу, скачивать CSV | Проверка сопоставимости реальных метрик |
| [Поисковый спрос](/#demand) | Искать фразу, переключать тип соответствия, открывать карточку | Wordstat API, история, полноценное управление ядром |
| [Выдача Яндекса](/#search) | Сравнивать присутствие доменов и индекс видимости | Импорт региональных снимков и Вебмастер |
| [Воронка и деньги](/#funnel) | Считать заявки, сделки, прибыль и ROMI по выбранным каналам | Дедупликация, возвраты, закрытие когорт |
| [Рынок площадок](/#market) | Искать среди 46 площадок, смотреть паспорта и источники | Обновление доступных публичных оценок по единым определениям |
| [Помощник](/#assistant) | Получать три вида объяснений, менять бюджет, сохранять гипотезу | Локальная модель, проверка фактов, эксперименты |
| [Источники](/#sources) | Просматривать подключение, пустое состояние, загрузку, ошибку | Авторизация и расписание сбора |
| [Отчёты](/#reports) | Выбирать разделы, экспортировать CSV, печатать в PDF средствами браузера | Сохранённые отчёты и доставка по подписке |
| [План](/#phases) | Переходить из каждой фазы к соответствующему экрану | Реальная приёмка разработки |

Дата в учебном бизнес-срезе выбирается с 1 июля по 9 сентября 2026. Предыдущий период имеет ту же длину; если полной истории нет, сравнение не показывается. Wordstat имеет собственное окно последних 30 дней и не притворяется, что его метод топа поддерживает произвольные даты. Состояние макета живёт в памяти вкладки и сбрасывается после перезагрузки. Помощник использует шаблоны, а распределение бюджета — учебную эвристику; это не работающая языковая модель и не прогноз продаж.

## 4. Карта источников {#sources}

Нужно различать пять слоёв: собственные результаты, доступные события внутри площадки, поисковый спрос, поисковую видимость и оценку внешнего рынка. У каждого слоя своя единица измерения. Одно число «весь трафик» скроет различия между посещением, просмотром объявления, человеком, поисковым запросом и заявкой.

| Источник | Полезные данные | Право и ограничение | Очередь |
|---|---|---|---|
| Кабинет Авито | Доступная статистика своих объявлений, обращения, расходы | Конкретные методы и поля сверяются по тарифу, категории и правам. Уже имеющийся токен не доказывает доступ ко всей аналитике | A1 |
| Яндекс Метрика | Визиты своего сайта, источники, цели, устройства, e-commerce | Только доступные счётчики; семплирование и модель атрибуции входят в результат | A1 |
| CRM, заказы, бухгалтерская выгрузка | Заявка, статус, оплата, себестоимость, возврат | Сопоставление идентификаторов, права на выгрузку; без себестоимости нельзя обещать прибыль | A1–A2 |
| Яндекс Директ | Статистика рекламы и затраты | Отчёты своего аккаунта; источник расходов отделён от измерения конверсий | A2 |
| Wordstat | Топ фраз, динамика, региональный интерес | Частоты запросов, не уникальные люди. Период и операторы зависят от метода | A3 |
| Яндекс Вебмастер | Запросы, показы, клики, позиция своего сайта | Подтверждённые права на сайт; агрегаты не заменяют события Метрики | A4 |
| Импорт поисковых снимков | Выдача по теме и региону с параметрами и датой | Базовый путь без платного API; регулярный автоматизированный Search API — отдельная будущая опция | A4 |
| Google Search Console | Поисковые показатели своего сайта в Google | API не гарантирует все строки; нужны отметки о полноте и ограничения выборки | A5 |
| Google Analytics Data API | События и отчёты своих сайтов/приложений | Доступ к ресурсу; настройки identity и моделирования влияют на цифры | A5 |
| AppMetrica | События, установки, переходы, покупки собственного приложения | Отдельная модель мобильной атрибуции; не статистика чужих приложений | A5 |
| Wildberries | Воронка, поиск по своим товарам, остатки, отчёты | Отдельная товарная экономика; проверка подписки, квот и допуска стороннего сервиса | A5 |
| Ozon / Яндекс Маркет | Потенциальные источники статистики продавца, заказов и расходов | В этой работе контракт методов не проверен; адаптер включается после изучения доступного кабинета | A5 |
| Авто.ру / Дром / Циан / hh.ru и другие | Статистика размещений в своей отрасли | API, договорной экспорт или ручная выгрузка по паспорту канала; не обещать единого универсального API | A5 |
| VK и рекламные кабинеты | Свои сообщества, объявления, расходы, переходы | Официальная страница метода в этой сессии недоступна. Поля и допуск уточнить до реализации | A5 |
| Telegram | Доступная статистика собственных каналов и переходов | Импорт/собственные точки контакта; Bot API не является универсальным API статистики Telegram | A5 |
| Яндекс Бизнес / Карты | Действия в своей карточке, звонки и переходы — где доступны | Проверить официальный экспорт/доступ; не путать с API картографических данных | A5 |
| 2ГИС | Справочник, геоданные, геоаналитика | Данные лицензируются; наличие гео-API не доказывает доступ к статистике чужих карточек | A5 |
| Публичные оценки посещаемости | Открытые рейтинги и опубликованные сведения | Дата и методология; без подписки не обещается полная выгрузка | A5 |
| Выгрузка SEO-данных владельца | Готовые позиции, если выгрузка уже есть | Импорт с указанием источника; новую подписку не требует | A4 |
| Выгрузка телефонии владельца | Звонки и источник при наличии связки | CSV/JSON; автоматический API только при имеющемся доступе | A2/A5 |
| Публичные пресс-релизы и отраслевые исследования | Заявления об аудитории и методология | Дата, страна, MAU/DAU/web-visits, автор и первоисточник; не складывать несопоставимое | A5 |
| Собственные UTM, формы, QR и короткие ссылки | Переходы и связь с первым/последним источником | Только свои точки контакта и разрешённые ссылки. Часть покупок произойдёт внутри площадки | A1–A2 |

Документированные основы: [API Метрики](https://yandex.ru/dev/metrika/), [семплирование Метрики](https://yandex.ru/dev/metrika/ru/stat/sampling), [Direct Reports](https://yandex.ru/dev/direct/doc/ru/reports), [Wordstat в Search API](https://aistudio.yandex.ru/ru/docs/search-api/concepts/wordstat), [Вебмастер: поисковые запросы](https://yandex.com/support/webmaster/en/service/popular-queries), [Search API](https://aistudio.yandex.ru/ru/docs/search-api/concepts/web-search).

Другие подтверждённые интерфейсы: [Search Console](https://developers.google.com/webmaster-tools/v1/searchanalytics/query), [GA Data API](https://developers.google.com/analytics/devguides/reporting/data/v1), [AppMetrica](https://appmetrica.yandex.ru/docs/ru/mobile-api/), [WB Analytics](https://dev.wildberries.ru/docs/openapi/analytics), [TGStat API](https://api.tgstat.ru/docs/ru/start/intro.html), [2ГИС](https://dev.2gis.com/), [Similarweb Traffic and Engagement](https://docs.similarweb.com/api-v5/similarweb-api/website-analysis-api/website-performance/traffic-and-engagement), [Топвизор API](https://topvisor.com/ru/api/v2/intro/), [Calltouch: выгрузка отчёта](https://www.calltouch.ru/support/api-metod-vygruzki-otcheta-po-skvoznoy-analitike/).

### Что означает «со всех, где возможно»

Реестр должен иметь для каждой площадки состояния: источник найден, документация проверена, доступ аккаунта проверен, контрольный импорт сверён, регулярный сбор работает. До последнего состояния площадка не отображается как живое подключение. Отсутствие API компенсируется честно обозначенным импортом; недоступное значение остаётся неизвестным.

В базовом плане внешняя аудитория поступает из публичных сведений и доступных владельцу выгрузок. Сравниваются значения только одного типа, периода, географии и поставщика. «Место в рейтинге классифайдов» нельзя сравнивать численно с «миллионами пользователей приложения». Исторические оценки отображаются с датой, без искусственного пересчёта на текущий день. Не следует складывать аудитории Авито, VK и Яндекса: одни люди присутствуют в нескольких источниках.

### Найденные противоречия в документации

В документации Wordstat есть прямой API с `/v1/topRequests`, `/v1/dynamics`, `/v1/regions`, а также облачный маршрут GetTop/GetDynamics/GetRegionsDistribution. Их авторизация и учёт квот различаются. Базовый маршрут — прямой API при имеющемся доступе или импорт; облачный вариант вынесен в будущие дополнения. В данных сохраняется `provider_variant`. [Прямой Wordstat API](https://yandex.ru/support2/wordstat/en/content/api-structure), [облачный Wordstat](https://aistudio.yandex.ru/ru/docs/search-api/concepts/wordstat).

Страницы Wordstat расходятся по поддержке операторов в динамике. Русская страница операторов сообщает о расширении поддержки; отдельные FAQ и английские страницы содержат прежнее ограничение. Поэтому контракт проверяется на контрольных запросах по каждому методу и периоду; неподдержанный режим блокируется, а не незаметно превращается в широкий. [Операторы](https://yandex.ru/support2/wordstat/ru/content/operators), [FAQ](https://yandex.ru/support2/wordstat/ru/content/faq).

В обзоре DataForSEO перечислены поддерживаемые поисковые системы без Яндекса, тогда как старый пример списка endpoints содержит Yandex. Такой источник нельзя принимать как подтверждённую замену официального Yandex Search API. Для Google/Bing его можно рассмотреть отдельно; доступность Яндекса подтвердить живым каталогом аккаунта и условиями. [Обзор DataForSEO](https://docs.dataforseo.com/v3/serp-overview/), [пример endpoints](https://docs.dataforseo.com/v3/serp-endpoints/).

## 5. Собственная разработка без обязательных платных сервисов {#solutions}

Базовый план не требует подписок на внешние аналитические системы или ИИ-помощников. Интерфейс, словарь метрик, расчёты, сопоставление данных, проверку качества, отчёты и внутренние фоновые процессы разрабатываем в AvitoAuto. Используем уже имеющийся стек проекта и доступные официальные источники. Когда прямой API недоступен без оплаты, поддерживаем импорт официальной выгрузки.

Сторонние решения, новые библиотеки, смешанные лицензии и платные источники вынесены в [отдельный документ на будущее](/external.html). Они не являются зависимостями или условием завершения базовых фаз.

1. Существующий React-интерфейс и установленный Recharts для графиков.
2. Собственный серверный модуль расчётов и контролируемые Python/Node-сборщики без отдельной ETL-платформы.
3. Текущая SQLite для пилотных витрин, одна дисциплина записи и отдельная очередь аналитики.
4. Доступные API своих кабинетов и счётчиков; проверяемый CSV/JSON-импорт для остальных источников.
5. Правила и шаблоны объяснений; локальная модель GX10 только как необязательное улучшение формулировок.
6. Регулярные задания и отчёты внутри проекта, без внешнего платного автоматизатора.

Самостоятельная разработка не открывает закрытые данные площадок. Если нет бесплатного разрешённого источника, значение остаётся неизвестным, а автоматизация — недоступной с понятным объяснением. Реальные затраты на собственный сервер и разработку также сохраняются; отсутствие подписок не означает нулевую стоимость эксплуатации.

## 6. Архитектура и модель данных

```text
API / CSV / JSON / разрешённые webhooks
       → очередь загрузок с квотами
       → исходный снимок + хеш + права
       → нормализация и проверка качества
       → факты, связи с CRM, версии формул
       → дневные витрины и кеш
       → экран / отчёт / объяснение / задача
```

Один источник остаётся владельцем каждого факта. API кабинета поставляет просмотры, CRM — статус сделки, финансовая система — оплату и себестоимость. Если один факт пришёл через CSV и API, он не становится двумя событиями. Для расходов нужно хранить категорию затрат: размещение, продвижение, рекламный бюджет, комиссия и операционная работа. Правило включения в CPL/ROMI задаётся явно.

| Сущность | Ключевые поля и назначение |
|---|---|
| `analytics_sources` | workspace, platform, account, auth reference, scopes, capabilities, timezone, состояние |
| `analytics_sync_runs` | source, период, cursor, попытка, версия схемы, статус, квота, source snapshot hash |
| `raw_artifacts` | Тип, локатор, SHA-256, размер, время, срок хранения, версия парсера, отсутствие секретов |
| `metric_definitions` | metric ID, unit, grain, aggregation, denominator, формула, версия, область применимости |
| `metric_facts` | workspace/source/date/entity/region/device/metric/definition version/value/quality |
| `leads`, `deals`, `touchpoints` | ID источника, даты, статусы, связки; ПД отдельно от аналитической витрины |
| `attribution_edges` | deal, touchpoint, model, window, weight, confidence, run; сумма весов сделки ≤ 1 |
| `keyword_sets` | Версионированный набор фраз, оператор, кластер, регион, язык, исключения |
| `keyword_observations` | Provider variant, phrase raw, period, frequency, devices, fetched at, completeness |
| `serp_snapshots` | query set version, фраза, поисковик, регион, устройство, язык, время, глубина, parser version |
| `serp_results` | snapshot, URL, domain, тип элемента, organic position, absolute position, title |
| `market_observations` | Platform, metric type, источник, период, география, web/app, оценка/заявление |
| `saved_views`, `report_runs` | Фильтры, metric versions, snapshot IDs, ACL, срок действия экспорта |
| `insights`, `experiments` | Rule/model version, evidence IDs, действие, ответственный, статус, итог эксперимента |

`value=null` означает неизвестное значение; причина хранится отдельно: нет прав, не поддерживается, не загружено, недостаточная выборка или устарело. Ноль возможен только при подтверждённом полном наблюдении. Валюта и денежная точность хранятся в явном виде; для бухгалтерских сумм используются целые минимальные единицы или decimal, а не накопление binary float.

Ключ факта включает детализацию. Дневной агрегат нельзя загружать одновременно как событие и как ещё один дневной итог. Полученную у источника локальную дату храним вместе с timezone; смешанные московские и UTC-сутки приводим только по документированному правилу. Снимок сохраняет исходные значения, а пересчёт создаёт новую версию витрины.

Везде требуется `workspace_id`: SQL, экспорт, кеш, очередь, raw-хранилище, ссылки помощника и задания отчётов. Клиентский фильтр не является границей доступа. Существующие роли admin/operator/viewer дополняются отдельными правами на финансовые показатели, экспорт и управление источниками.

### Загрузка и обновление

Worker получает lock/lease по источнику и разделу времени, запрашивает очередную страницу, проверяет схему и сохраняет пакет. Cursor фиксируется только после успешной записи данных. Повтор выполняет идемпотентное обновление, а не прибавление. Изменённые прошлые дни пересчитываются по версии источника. 401/403 останавливают источник с понятной причиной; 429 учитывает Retry-After; сетевые ошибки повторяются с ограниченным backoff; дорогие запросы имеют отдельный бюджет.

Для Метрики Logs API данные текущего дня недоступны, а визиты могут обновляться позже. Плановая политика пилота: вчерашний день и повторная загрузка последних 3–7 дней; это настройка продукта, а не универсальная гарантия полноты. Логи у поставщика удаляются только после проверки скачивания и транзакционного сохранения. [Logs API](https://yandex.ru/dev/metrika/ru/logs/). Для Директа использовать механизм актуализации статистики самого API. [Обновление статистики](https://yandex.ru/dev/direct/doc/ru/actual).

Предлагаемая частота: собственные агрегаты раз в несколько часов, зрелые дни ночью; Wordstat — по сроку обновления метода и кешу; поисковые снимки — по доступной выгрузке и фактической дате обновления; внешняя аудитория по периоду поставщика. Частота повышается только при доказанной полезности и доступном бюджете.

## 7. Правила расчёта и алгоритмы {#algorithms}

### Сопоставимые показатели

| Показатель | Правило | Когда скрывать |
|---|---|---|
| CTR | Клики / показы одной сущности и одного источника | Показы и клики из разных систем либо нулевой знаменатель |
| Конверсия сайта | Целевые визиты / визиты с согласованной целью | Нет цели, разный период или неопределённый состав целей |
| Конверсия объявления | Определённые контакты / просмотры по контракту площадки | Площадка не даёт сопоставимый контакт или уникальность |
| CPL | Расходы согласованного состава / уникальные лиды CRM | Лиды или расходы неполны; знаменатель нулевой |
| CAC | Расходы привлечения / новые покупатели | Нет связи клиента со сделками либо доли новых покупателей |
| ROAS | Атрибутированная выручка / рекламные расходы | Неполная выручка; не равен прибыли |
| ROMI | (Атрибутированная валовая прибыль − включённые маркетинговые расходы) / расходы | Нет себестоимости, возвратов или корректного распределения затрат |
| Срок продажи | Продажа − начало размещения; непроданные отдельно | Неизвестна дата начала; нельзя исключать непроданные незаметно |
| Доля неизвестного источника | Лиды без надёжной связи / все лиды | Не подменять числом ноль при отсутствии всей CRM |

Итоговые коэффициенты считаются из сумм числителя и знаменателя, а не средним от процентов площадок. При неполноте показываются известная сумма, покрытие и список исключений. Для валют, VAT и комиссий нужна одна выбранная политика отчёта. Расходы на SEO для органического поиска — отдельный ввод, а не автоматически нулевой бюджет.

### Дедупликация и атрибуция

Сначала используются стабильные ID заявки/сделки и явные ссылки CRM. Затем — проверенный click ID или UTM в своей форме. Повторное обращение не обязательно новая заявка; правило окна и причины объединения сохраняются. Связь только по имени или близкому времени не даёт точного совпадения. Хеширование контакта само по себе не делает данные анонимными и не разрешает объединять разные компании.

На старте достаточно двух прозрачных моделей: первое известное касание и последнее известное касание до заявки. Окно 30 дней в макете — иллюстрация, рабочее окно выбирается по циклу сделки. Неизвестная часть остаётся unattributed. На общей карточке сделки сумма атрибуционных весов не превышает единицу, иначе доход будет посчитан дважды.

Отчёт по когорте заявок и отчёт по дате оплаты различаются. Для дорогого автомобиля сделки текущего месяца могут относиться к лидам прошлого месяца. Нельзя делить все оплаты текущего месяца на все новые лиды и называть это достоверной конверсией когорты. Поздние продажи и возвраты пересчитывают соответствующую историю с сохранением версии.

### Поисковые фразы и кластеры

Сохранять оригинальную строку вместе с операторами. Нормализованная форма используется для поиска дублей и кластеризации, не для подмены запроса к Wordstat. Кавычки фиксируют число слов, но сами по себе не фиксируют словоформы и порядок. Региональные деревья брать у поставщика; родительский регион и дочерние города не суммировать без устранения пересечения. [Операторы Wordstat](https://yandex.ru/support2/wordstat/ru/content/operators).

Последовательность обработки: нормализация Unicode и пробелов → сохранение операторов → точные дубли → словари брендов, товаров и интентов → предложение кластеров → проверка человеком. Embeddings полезны для близких формулировок, но должны сохранять артикулы, отрицания и различия «купить»/«продать»/«ремонт». Кластеры версионируются, чтобы изменение состава не изображало искусственный рост спроса.

Широкие запросы пересекаются. Для витрины «спрос категории» либо выводить набор отдельных частот без суммы, либо использовать заранее определённый непересекающийся метод и описывать его ограничения. Динамика сравнивается по полным равным периодам; сезонность — по одинаковым месяцам/неделям нескольких лет при достаточной истории.

### Поисковая видимость и конкуренты

Снимок определяется кортежем: поисковик, query-set version, фраза, регион, устройство, язык, параметры выдачи, время, глубина и версия парсера. XML Search API содержит результаты без дополнительных элементов, HTML может содержать рекламу и другие блоки; типы результатов нельзя молча смешивать. [Форматы Search API](https://aistudio.yandex.ru/ru/docs/search-api/concepts/web-search).

Индекс в макете: `100 × Σ(wq × discount(position)) / Σ(wq)`, где discount равен `1/log2(position+1)` для топ-10 и нулю за его пределами. Для одного домена берётся лучший органический результат. Частоты здесь являются весами важности тем. Это сравнительный индекс фиксированного ядра, не процент кликов, не доля всех пользователей и не причинная оценка роста продаж.

«Не найден в топ-20» не равно «отсутствует в поиске». Ошибка загрузки снимка не равна нулевой видимости. Недоступные снимки исключаются с показателем покрытия, а исторический тренд строится на сопоставимом ядре. Для сравнения конкурентов важны тематический пересекающийся набор и регион бизнеса, а не средняя позиция по случайным фразам.

### Аномалии, рекомендации и эксперименты

Сначала правила: источник устарел, расходы есть без заявок, отклик падает после смены карточки, растёт доля неизвестного канала. Затем устойчивый baseline по дню недели, медиана и MAD, минимальный объём наблюдений и контроль множественных проверок. Маленькая выборка даёт сообщение «недостаточно данных», а не красный прогноз провала. Корреляция с изменением текста не доказывает причинность.

Рекомендация включает наблюдение, период, основание, ограничение, действие, владельца и критерий проверки. Пример: «Проверить более подробные фото на 20 объявлениях», а не «ИИ увеличит прибыль на 30%». Для оценки эффекта — заранее выбранная основная метрика, контрольная группа, длительность с учётом цикла сделки и запрет выбора результата задним числом.

Распределение бюджета в макете намеренно простое и не готово к реальному расходованию денег. Рабочая версия должна учитывать прибыль, насыщение, минимум данных, интервалы неопределённости, ограничения каналов и резерв на эксперимент. Бюджетный план остаётся предложением до явного действия владельца; аналитический бот не получает права изменения ставок автоматически.

## 8. Интерфейс и поиск

Главный экран отвечает на три вопроса: что произошло, где это произошло, что проверить дальше. Четыре карточки KPI, динамика и таблица дают обзор; каждое число раскрывается в источник, формулу, период и степень полноты. Цвет обозначает направление и статус, но всегда сопровождается текстом. Рост расходов не окрашивается как хороший результат сам по себе.

Общие фильтры: календарные даты, сравниваемый период, компания/филиал, регион, категория, площадка, кабинет, кампания, объявление, устройство, модель атрибуции. В сложных отчётах вторичные фильтры скрываются за «Уточнить», а активные условия остаются видимыми. Для Wordstat и внешней аудитории недоступные фильтры объясняются, а не имитируются.

Три уровня просмотра: сводка владельца, рабочее место маркетолога, подробности аналитика. На телефоне — карточки результатов и горизонтально прокручиваемая таблица внутри своего блока; навигация, экспорт и фильтры доступны с клавиатуры. Важные определения имеют постоянную короткую подпись, а не только подсказку при наведении.

Глобальный поиск должен находить площадку, объявление, артикул, запрос, кампанию, сохранённый отчёт и термин справки. Сначала точное совпадение и полнотекстовый поиск с русской морфологией; семантический поиск добавляется для справки и тем. Финансовые суммы всегда возвращаются структурированным расчётом. Перевод вопроса пользователя в свободный SQL не является первым этапом.

Сохранённое сравнение хранит набор каналов, фильтры, вид графика, модель и версии метрик. Должны быть таблица, линии по времени, столбцы, тепловая карта, scatter «стоимость ↔ качество», воронка и карта регионов. Sankey уместен только при реальных переходах между шагами; нельзя рисовать его из независимых агрегатов.

## 9. Внутренние помощники и скрипты

| Исполнитель | Задача | Ограничение |
|---|---|---|
| Сборщик | Забрать разрешённую страницу/API-отчёт по расписанию | Заданные источники, квоты, только чтение |
| Контролёр качества | Найти неполноту, дубли, дрейф схемы, просрочку | Не исправлять финансовые значения догадкой |
| Аналитик | Сравнить сегменты и объяснить изменение | Только доступные витрины и проверяемые расчёты |
| Семантический помощник | Предложить кластеры и новые темы | Не выдумывать частотность, сохранять артикулы и интент |
| Контролёр видимости | Сравнить поисковые снимки и покрытие | Не выдавать персональную выдачу за абсолютную позицию |
| Редактор отчёта | Собрать объяснение с источниками | Каждое число связано с metric result ID |
| Диспетчер уведомлений | Сообщить о значимом изменении подписчику | Дедупликация, тихие часы, права получателя |

Это роли ограниченных фоновых процессов, а не необходимость запускать семь LLM постоянно. Планировщик и правила выполняют основную работу. Локальная модель на GX10 формулирует объяснения и помогает с текстовым поиском; арифметику считает сервер. Внешние страницы, названия объявлений и CSV рассматриваются как данные, не инструкции модели. Токены источников в контекст не попадают.

Предлагаемые команды будущего модуля:

```text
analytics sources check --source ID --read-only
analytics sync --source ID --from DATE --to DATE --dry-run
analytics import --source ID --file PATH --validate-only
analytics backfill --source ID --from DATE --to DATE
analytics reconcile --run ID --against provider-export
analytics keywords collect --set ID --budget MAX
analytics serp collect --set ID --region ID --budget MAX
analytics quality check --workspace ID
analytics report render --view ID --snapshot ID
analytics retention prune --dry-run
```

Это спецификация, не уже существующий CLI. Каждая команда возвращает машинный JSON-результат, run ID и понятную сводку. Пароли и токены не передаются аргументами. Повторная команда не создаёт дубли; dry-run не расходует платную квоту и явно сообщает, какие проверки требуют реального вызова.

Предлагаемые кодовые точки: `server/analytics/` для контрактов и API, `workers/analytics/` для загрузок, `lib/analytics/` для типов, `components/analytics/` для экранов, `tests/analytics/` для контрольных наборов. Переход в основном меню добавляется после готовности A1, а не как живая панель с учебными цифрами.

## 10. План по фазам {#phases}

Оценки ниже — ориентиры рабочих дней для команды из двух разработчиков с участием аналитика/QA. Это не обязательство по срокам. Зависимость от API, договоров, качества CRM и согласования определений может быть важнее написания кода. A3 и A4 можно вести после контракта A0 независимо от завершения всей экономики A2; реальные интеграции объединяются после проверки данных.

### A0. Контракт данных и дизайн — 6–9 дней

Цель: утвердить, что считается обращением, заявкой, продажей и расходом в каждой отрасли. Выбрать один пилотный бизнес, его 2–3 канала, CRM и счётчик. Подготовить словарь метрик, capabilities источников, правила отсутствующих значений, макеты и сценарии приёмки. Доступ к production-ключам для макетов не нужен.

Результат: спецификации `MetricDefinition`, `SourceCapabilities`, `QualityStatus`, единый каталог каналов и ссылка из каждой пользовательской задачи на экран. Приёмка: по любому KPI можно объяснить источник, формулу и ограничение; владелец проходит сравнение и понимает следующий шаг. Текущая работа предоставляет основу A0, но не заменяет утверждение бизнес-определений владельцем.

### A1. Первый поток реальных данных — 10–15 дней

Цель: связать Авито, свой сайт в Метрике и выгрузку CRM. Реализовать авторизацию чтения, хранилище секретов, нормализацию, очередь, историю запусков, инкрементальный сбор и импорт с предпросмотром ошибок. Отдельно обработать отозванный токен, квоту, неполную выгрузку и восстановление после сбоя.

Приёмка: контрольные дни совпадают с кабинетами при одинаковых фильтрах; повторный импорт не увеличивает суммы; сбой между страницами не теряет и не удваивает данные; чужое пространство недоступно; UI показывает свежесть. До выполнения этого шага «подключено» не показывается. Макеты: обзор и источники.

### A2. Экономика и сравнение — 10–15 дней

Цель: сопоставлять стоимость качественного результата. Добавить лиды, сделки, оплаты, возвраты, связи с объявлениями, категории затрат и две прозрачные модели атрибуции. Реализовать сравнение равных периодов, когорты, нормализацию метрик и отображение неизвестной доли.

Приёмка: ручной эталон включает повторный контакт, две площадки на одной сделке, возврат, позднюю оплату и отсутствующую себестоимость. Доход не удваивается; суммы весов сделки корректны; нулевой знаменатель даёт прочерк; неполный ROMI не показывается как точное число. Макеты: сравнение и воронка.

### A3. Спрос Wordstat — 8–12 дней

Цель: исследовать спрос по темам и регионам. Проверить доступ к прямому API; при недоступности использовать импорт выгрузок Wordstat; реализовать дерево регионов, топ фраз, историю, операторы, минус-слова, кластеры, кеш и квоту. Показать изменение состава ядра и дату следующего обновления.

Приёмка: контрольные фразы с кавычками, отрицаниями, формами слов и городами сверяются с выбранным API. Метод топа не обещает произвольные даты; пересекающиеся запросы не образуют ложную сумму аудитории. При исчерпании доступной квоты сбор приостанавливается; подписка не оформляется автоматически. Макет: поисковый спрос.

### A4. Видимость в поиске — 8–12 дней

Цель: соединить реальные поисковые показатели собственного сайта с наблюдаемыми позициями площадок. Добавить Вебмастер и импорт поисковых снимков. Регулярная автоматическая проверка выдачи через платный Search API остаётся отдельной будущей опцией. Хранить результаты и параметры снимка; выделять органику, рекламу и дополнительные блоки.

Приёмка: результат воспроизводится по сохранённому снимку; ошибка API отличается от отсутствия в топе; смена устройства, региона или ядра не порождает некорректное сравнение. Собственный сайт и конкурентный домен различаются по правам и источникам. Макет: выдача Яндекса.

### A5. Расширение площадок и рыночный слой — 12–20 дней на пакет

Цель: подключать каналы по подтверждённой пользе. Пакет «авто» — Авто.ру/Дром и профильные источники; «товары» — WB/Ozon/Маркет; «услуги» — карты, каталоги, социальные источники; «недвижимость» и «вакансии» — отдельные события результата. Внешнюю аудиторию вести независимо от внутренних данных клиентов.

Приёмка каждого адаптера: доступ конкретного аккаунта, версия API, согласованные поля, пагинация, лимит, идемпотентность, контрольная выгрузка и режим деградации. Для публичных оценок — первоисточник, период, методология, право повторного показа и фактическое покрытие. Платные источники не входят в приёмку базового пакета. Все 46 площадок могут иметь паспорта, но число рабочих подключений показывается отдельно. Макет: рынок площадок.

### A6. Помощник и задачи — 8–12 дней

Цель: объяснять показатели и предлагать проверяемые действия. Начать с правил качества и шаблонов, затем добавить локальную модель с узкими инструментами чтения. У каждой рекомендации сохранить идентификаторы результатов расчёта, ограничения и предложенный эксперимент.

Приёмка: контрольный набор вопросов содержит отсутствие данных, попытку доступа к чужой компании, вредоносную инструкцию в названии объявления и просьбу изменить бюджет. Помощник не выдаёт выдуманные суммы, не исполняет текст источника и не меняет деньги. Успешный ответ воспроизводим по snapshot IDs. Макет: помощник.

### A7. Отчёты и уведомления — 6–10 дней

Цель: выдавать владельцу и команде нужную информацию без ручной сборки. Сохранённые представления, сравнения, CSV/XLSX, PDF, закрытые ссылки, расписание и подписки. Для Telegram/email требуется настройка получателей и авторизация доставки; текущий макет никому ничего не отправляет.

Приёмка: файл совпадает с экраном по фильтрам и версиям метрик; CSV не исполняет пользовательскую формулу; повторный запуск не шлёт дубль; отписка и смена прав действуют до отправки. Отчёт не меняется задним числом без новой версии. Макет: отчёты.

### A8. Надёжность и масштаб — 8–12 дней

Цель: обеспечить долгую работу на ASUS GX10. Метрики worker lag, ошибки API, возраст данных, стоимость сборов, размер хранилища; резервные копии, восстановление, миграции и очистка по сроку хранения. По профилю нагрузки решить, нужны ли PostgreSQL/ClickHouse, вместо преждевременного запуска всего стека.

Предлагаемые цели пилота: 20 одновременных читателей, 12 месяцев истории 10 тысяч объявлений, p95 типового агрегированного отчёта до 2 секунд на подготовленной витрине. Эти значения — критерии будущего теста, не измеренный результат текущего прототипа. Приёмка включает реальный restore drill, межкомпанейскую изоляцию и работу интерфейса при остановленном внешнем API.

### A9. Бизнес-пилот и тиражирование — 2–4 недели наблюдения

Цель: доказать практическую пользу на реальных операциях. Владелец сверяет контрольный период; сотрудник находит слабый канал, объясняет причину и заводит эксперимент; после завершения цикла сделки оценивается результат. Настраиваются отраслевые определения, инструкции и SLA поддержки.

Приёмка: расхождения с кабинетами объяснены, бизнес понимает ограничения, нет потери заявок в интеграции, периодические отчёты используются. Успех аналитики — сокращение времени на проверку и более обоснованные решения; рост продаж оценивается отдельно и не гарантируется внедрением интерфейса.

### Зависимости и рекомендуемый порядок

Первый выпуск: A0 → A1 → минимальная A2 с двумя полными каналами. Следом A3 и A4; затем один отраслевой пакет A5. Помощник A6 получает уже проверенные витрины. Отчёты A7 и надёжность A8 развиваются по мере появления реальных данных; защита доступа и резервирование нужны с A1, а не откладываются до конца. A9 может выявить изменения контракта — их нужно версионировать.

## 11. Ресурсы, эксплуатация и контроль

Базовая версия не требует новых платных API или подписок. Ограничиваем нагрузку на собственный сервер и разрешённые бесплатные квоты: размер файла, число строк, время задания, объём истории и частоту обновления. При недоступности API используем импорт; на экране видны дата и ручной характер обновления.

Например, 300 фраз × 3 региона × 2 устройства × 4 проверки дают 7 200 логических поисковых снимков за условный месяц. Такая частота не обещается бесплатно: в базовой версии снимается ограниченный контрольный набор или импортируется готовая выгрузка. Автоматизация через платный источник потребует отдельного решения и описана только в документе дополнительных вариантов.

Ни макет, ни исследование не оформляли подписки, не расходовали платные квоты и не подключали внешних помощников.

Развёртывание — ASUS GX10, ARM64, Docker/Coolify. Аналитические сборщики не перезапускают чужие сервисы, не имеют доступа к их БД и не используют без согласования общие ClickHouse/Qdrant. Длительные сборки и backfill выполняются отдельными задачами. Для сырых снимков определить срок хранения и ограничение размера; агрегаты могут храниться дольше в соответствии с бизнес-политикой.

Ключи API хранятся зашифрованно на сервере и не попадают в HTML, экспорт, журнал или prompt модели. Демонстрация публична только потому, что содержит учебные сведения и публичные справочные материалы. Реальные отчёты компаний должны наследовать права текущего защищённого кабинета; публичность демо не означает публичность бизнес-аналитики.

## 12. Основные риски и условия готовности

| Риск | Последствие | Защита и приёмка |
|---|---|---|
| Смешение типов трафика | Ложный рейтинг каналов | Единицы, scope и запрет некорректной агрегации |
| Нет CRM / нет связки с площадкой | Нельзя доказать продажи и прибыль | Отдельный охват данных; нет выдуманного ROMI |
| Задержанные данные и возвраты | Отчёт меняется после решения | Статус предварительного периода, перерасчёт, versioned snapshots |
| API или тариф изменился | Сбор молча перестал работать | Capability probe, schema drift, fixture и понятная ошибка |
| Чужие данные в запросе или экспорте | Утечка между компаниями | Tenant scope во всех слоях и отрицательные тесты |
| Персонализация выдачи | Позиции не совпадают с телефоном владельца | Полные параметры снимка и понятное объяснение |
| Лицензия ограничивает embedding | Нельзя использовать выбранный продукт в нужной форме | Проверка нужной функции и редакции до внедрения |
| Модель уверенно ошибается | Неверное бизнес-действие | Серверные расчёты, источники, отказ при неполноте |
| Большой каталог без рабочих адаптеров | Ложная готовность | Раздельные счётчики паспортов и подключений |
| Рост расходов на сбор | Аналитика становится дороже пользы | Бюджеты, кеш, приоритеты и стоимость перед запуском |

Готовность production-модуля подтверждается цепочкой: данные аккаунта → сверка → расчёт → интерфейс → экспорт → восстановление → приёмка владельцем. Прохождение unit-тестов или публикация работающего макета не заменяет эту цепочку.

## 13. Источники и проверяемые материалы

Официальные материалы в тексте имеют прямые ссылки. Дата обращения к веб-источникам и GitHub — 10 сентября 2026; дата публикации, когда она не указана поставщиком, не выдумывается. Реестр площадок — отдельный прежний срез проекта с собственными датами и ограничениями.

Список 15 репозиториев с неизменяемыми ссылками на изученные лицензии вынесен в [документ возможных дополнений](/external.html). Машиночитаемые метаданные, локальные README и лицензии находятся в `evidence/`. При переходе к внедрению выбирать стабильный выпуск и повторно проверять лицензию именно включаемых файлов: SHA исследования не является рекомендацией автоматически поставить свежую ветку разработки.