---
name: direct-analytics-skill
description: |
  Универсальный сборщик и аналитик данных Яндекс.Директ + Яндекс.Метрика для любого проекта.
  Запускай этот скилл когда нужно: выгрузить статистику кампаний/объявлений/ключевых слов,
  рассчитать DRR/ROAS/CPA/CR/CTR, построить аналитику в разрезах (устройства, регионы, время,
  ключи, площадки, объявления), сравнить периоды (WoW, MoM), найти аномалии.
  Также используй при словах: рекламная аналитика, расход Директа, эффективность кампаний,
  матчинг Метрики, ДРР, РОАС, ЦПА.
---

# direct-analytics-skill

Сбор, кэширование и многомерная аналитика Яндекс.Директ + Яндекс.Метрика для любого кабинета.

## Первый запуск: настройка проекта

Проверь наличие конфига: `~/.direct_analytics/{project}/config.json`.
Если отсутствует — запусти setup:

```bash
python scripts/setup.py
```

Setup запросит интерактивно:
- `project_name` — название проекта (namespace кэша и конфига)
- `DIRECT_TOKEN` — OAuth-токен Яндекс.Директ
- `DIRECT_LOGIN` — логин клиентского кабинета (`agency-clientlogin` или прямой)
- `METRIKA_TOKEN` — OAuth-токен Яндекс.Метрики
- `METRIKA_COUNTER` — ID счётчика Метрики
- `METRIKA_GOAL_IDS` — ID целей для конверсий (через запятую; enter = все цели)
- `CURRENCY` — валюта кабинета (по умолчанию RUB)

Конфиг сохраняется в `~/.direct_analytics/{project}/config.json`.

Управление проектами:
```bash
python scripts/setup.py --list                    # список проектов
python scripts/setup.py --new                     # добавить проект
python scripts/setup.py --set-default NAME        # проект по умолчанию
python scripts/setup.py --show NAME               # показать конфиг (без токенов)
```

## Архитектура кэша (SQLite)

Все сырые данные хранятся локально: `~/.direct_analytics/{project}/cache.db`

Таблицы: `direct_campaigns`, `direct_adgroups`, `direct_ads`, `direct_stats`,
`metrika_sessions`, `metrika_ecommerce`, `matched_results`

Логика работы с кэшем:
1. Перед API-запросом — проверка наличия данных за каждую дату диапазона
2. Запрашиваются только отсутствующие даты (инкрементальное обновление)
3. Сегодняшний день никогда не кэшируется (данные неполные)
4. Принудительное обновление: флаг `--refresh` (перезаписывает кэш)

## Основные команды

### Сбор данных
```bash
# вчерашний день (по умолчанию)
python scripts/collect.py

# конкретный проект
python scripts/collect.py --project berezka

# период (берёт из кэша то, что уже есть)
python scripts/collect.py --date_from 2026-04-01 --date_to 2026-04-30

# принудительное обновление кэша
python scripts/collect.py --date 2026-05-01 --refresh
```

### Аналитика
```bash
python scripts/analyze.py \
  [--project NAME]                         # проект (иначе default)
  [--period 7d|14d|30d|90d]               # готовые периоды
  [--date_from D --date_to D]             # кастомный период
  [--dim DIMENSION]                        # разрез (см. таблицу ниже)
  [--compare prev_period|prev_year]        # сравнение периодов
  [--filter campaign=NAME|device=mobile]   # фильтр
  [--anomaly]                              # детект аномалий
  [--top N]                                # топ-N строк (по расходу)
  [--format table|json|html]               # формат вывода
```

## Разрезы аналитики (--dim)

| `--dim`       | Что показывает                          | Применение                   |
|---------------|-----------------------------------------|------------------------------|
| `campaign`    | сводка по кампаниям (дефолт)            | общая эффективность          |
| `device`      | mobile / desktop / tablet               | корректировка ставок         |
| `region`      | регионы показа                          | гео-эффективность            |
| `keyword`     | ключевые слова + CTR/CPC/CR             | оптимизация ключей и ставок  |
| `hour`        | распределение по часам суток            | управление расписанием       |
| `placement`   | поиск vs РСЯ + топ площадок РСЯ         | отключение неэффективных     |
| `ad`          | объявления + CTR/CR                     | A/B анализ креативов         |
| `day`         | динамика по дням                        | тренды и сезонность          |
| `utm`         | разбивка по UTM-меткам                  | атрибуция по меткам          |

## KPI и формулы

```
DRR   = расход / выручка × 100%
ROAS  = выручка / расход × 100%
CPA   = расход / конверсии
CR    = конверсии / клики × 100%
CTR   = клики / показы × 100%
CPM   = расход / показы × 1000
AOV   = выручка / конверсии (средний чек)
CPClick = расход / клики (ср. цена клика)
```

При match_confidence < 0.5 (L3-матчинг) — помечать данные как приблизительные.

## Алгоритм матчинга

- **L1 (conf=0.95)**: точное совпадение `utm_source+utm_medium+utm_campaign+utm_content`
- **L2 (conf=0.70)**: `utm_campaign` ≈ ID или названию кампании Директа (нечёткое)
- **L3 (conf=0.20)**: остаток из Метрики (канал `yandex/cpc`) распределяется пропорционально расходу

## Детект аномалий (--anomaly)

Сравнивает текущий период с предыдущим аналогичным. Флаги:
- расход вырос/упал >30% WoW при схожем количестве дней
- конверсии = 0 при кликах > порога (по умолчанию 50)
- CTR < 0.3% или > 20%
- ROAS < 100% (расход > выручки)
- площадки РСЯ: CR=0 + расход > 500 руб. → кандидаты на отключение
- кампании без показов >3 дней при статусе "активна"

## Скрипты

| Файл                   | Назначение                                      |
|------------------------|-------------------------------------------------|
| `scripts/setup.py`     | мастер настройки проекта и управление конфигами |
| `scripts/db.py`        | менеджер SQLite-кэша (CRUD + инвалидация)       |
| `scripts/collect.py`   | сбор из Директа + матчинг с Метрикой (с кэшем) |
| `scripts/analyze.py`   | многомерная аналитика + сравнение периодов      |

Подробности по API-лимитам и особенностям → `references/api_notes.md`