# Дашборд Superset для E-commerce Analytics

Документация по настройке и использованию Superset дашборда для анализа кликстрима.

---

## Быстрый старт

### 1. Запуск инфраструктуры

```bash
# Чистый прогон: стартовая история генератора -> DM -> Superset
make generated-history-analytics
```

Команда очищает volumes, генерирует стартовую историю, прогоняет batch
STG -> ODS -> DDS -> DM и создаёт metadata Superset. Если данные уже
подготовлены и нужно только пересобрать Superset:

```bash
# Автоматическая инициализация (создание подключения и датасетов)
make superset-init

# Создание дашборда с чартами; при необходимости обновляет metadata колонок датасетов
make superset-dashboard
```

Повторный `make superset-dashboard` синхронизирует чарты этого учебного
дашборда с `CHARTS_CONFIG`: обновляет параметры, переименовывает старые имена и
может удалить лишний чарт-дубль. Удаление ограничено dashboard
`ecommerce-analytics`, поэтому одноимённые чарты менти в других dashboard не
трогаются.

### 2. Доступ к UI

Откройте в браузере: http://localhost:8088

**Логин:** `admin`  
**Пароль:** `admin`

---

## Структура дашборда

### Витрины данных (Datasets)

| Витрина | Таблица ClickHouse | Описание |
|---------|-------------------|------------|
| **Events Enriched** | `dm.v_events_enriched` | Полная обогащённая витрина событий |
| **Daily Traffic** | `dm.v_daily_traffic` | Агрегаты по дням |
| **UTM Effectiveness** | `dm.v_utm_effectiveness` | Эффективность маркетинговых каналов |
| **Top Pages** | `dm.v_top_pages_daily` | Популярность страниц |
| **Session Overview** | `dm.v_session_overview` | Анализ сессий |
| **DQ Summary** | `dm.dq_summary` | Метрики по слоям (строки, ошибки, сироты) |

### Чарты (Charts)

#### KPI-блок (верх дашборда)
- **📊 Total Events** — общее количество событий
- **👤 Unique Users** — уникальные пользователи
- **📈 Avg Events/Visit** — среднее количество событий на визит (`click_id`)
- **🎯 Conversion to /confirmation** — доля просмотров `/confirmation` от просмотров `/home`

KPI разложены в одну строку по 12-колоночной сетке Superset: четыре блока по 3 колонки.
`Unique Sessions` не вынесен отдельной KPI-плиткой: в текущем дашборде важнее
развести события, пользователей и среднюю глубину визита. Генератор создаёт
повторные визиты, поэтому `user_domain_id` и `click_id` уже не идут 1:1.

#### Динамика трафика
- **📅 Events over Time** — линейный график событий с 5-минутными бакетами
  (быстрый проверочный профиль покрывает 6 часов модельного времени, поэтому
  5-минутные бакеты дают видимую динамику без лишнего шума)
- **📱 Traffic by Device** — pie chart распределения по устройствам

#### География
- **🌍 Top Countries by Events** — top-15 стран по количеству событий
  (`COUNT(*)`, единицы — события, штуки). Столбцы заменили прежнюю геовизуализацию:
  на текущем разреженном распределении так видны страна, значение, порядок и
  tooltip. Перекос стран приходит из гео-фактуры статического сида
  `geo_by_click_id`; своя генерация гео описана как отдельный будущий шаг в
  ADR-0006 и не лечится настройкой чарта.

> **Что проверили по Superset.** Через MCP Context7 проверили `/apache/superset`:
> прежний геоплагин описан как legacy-плагин, а ECharts bar chart имеет
> штатные параметры `show_legend`, `rich_tooltip`, подписи осей и формат чисел.
> Поэтому для разреженной географии выбран top-N bar chart
> (`viz_type: echarts_timeseries_bar`), а не донастройка прежней геовизуализации.

#### Маркетинг
- **🔗 UTM Effectiveness Table** — таблица эффективности UTM-меток
- **🪜 Page Funnel** — funnel chart по просмотрам страниц, от `/home` к `/confirmation`

> **Что проверили по Superset 4.1.2.** Через MCP Context7 проверили официальную
> библиотеку `/apache/superset`; документация не дала точной строки `viz_type`.
> В установленном Superset 4.1.2 дополнительно проверили bundled example
> `Featured Charts/Funnel.yaml` и frontend assets: для воронки используется
> `viz_type: funnel`, поэтому dashboard создаёт именно funnel chart.

#### Прохождение строк по слоям
- **🧱 Rows by Layer (event)** — `dist_bar` по `dm.dq_summary`: сколько строк
  одного **event-зерна** в каждом слое конвейера `STG → ODS → DDS → DM`.

> **Почему именно одно зерно, а не сумма по слою.** Чарт берёт по одной
> канонической таблице на слой (`browser_raw → browser_event → event →
> v_events_enriched`). Если суммировать `total_rows` по всем таблицам слоя,
> в один столбец складываются таблицы разного зерна: события, визиты и
> error-таблицы. Получается **ложная «воронка потерь»**, которой нет. На одном
> зерне видно прохождение event-строк по слоям, а не сумму несравнимых таблиц.
>
> Настоящие сигналы качества (`rows_with_errors` в ODS, `orphan_events` в DDS)
> на чистых демо-данных равны нулю и живут в `dm.dq_summary` отдельными
> `check_name` — их разбирают уроки 3–4, а не этот чарт.

> **Порядок столбцов.** В groupby подпись слоя получает числовой префикс
> (`1 · stg`, `2 · ods`, …), а `order_bars` сортирует бары по подписи — иначе
> `dist_bar` ставит их по убыванию значения, а не по порядку конвейера.

### Фильтры (Native Filters)

| Фильтр | Поле | Тип | Применение |
|--------|------|-----|------------|
| 📅 Date Range | `event_date` | Time Range | Charts с `event_date`; по умолчанию `No filter`, чтобы стартовая история не скрывалась фильтром даты |
| 🌍 Country | `geo_country` | Multi-select | Charts на `dm.v_events_enriched` |
| 📱 Device Type | `device_type` | Multi-select | Charts на `dm.v_events_enriched` |
| 🌐 Browser | `browser_name` | Multi-select | Charts на `dm.v_events_enriched` |

Фильтры работают через левую панель Superset. Click-to-filter между виджетами не включен:
клик по сектору pie chart, столбцу Top Countries, строке таблицы или funnel не меняет остальные charts.

Фильтр применяется только к charts, где есть нужное поле. Агрегированные витрины
`dm.v_utm_effectiveness` и `dm.v_top_pages_daily` содержат `event_date`, но не содержат
`geo_country`, `device_type` и `browser_name`. `dm.dq_summary` использует `check_date`;
бизнес-фильтры на него не рассчитаны.

---

## Команды Makefile

```bash
# Основные
make up          # Запуск всех сервисов
make down        # Остановка сервисов
make clean      # Остановка с удалением volumes
make logs service=superset  # Логи сервиса

# ETL
make generated-history-analytics # Чистый прогон генерации до Superset
make generated-history-check     # Проверка DM и Superset metadata
make ddl         # Применение DDL в ClickHouse
make data        # Архивная загрузка data/*.jsonl в Kafka
make transform   # Запуск batch-процесса

# Superset
make superset-init      # Инициализация (подключение + датасеты)
make superset-dashboard # Создание дашборда
make superset-ui        # Показать URL и логин
make superset-restart   # Перезапуск сервиса
```

---

## Ручная настройка (если автоматика не сработала)

### Создание подключения к ClickHouse

1. Откройте **Settings → Database Connections**
2. Нажмите **+ Database**
3. Выберите **ClickHouse**
4. Введите SQLAlchemy URI:
   ```
   clickhousedb://default:123456@clickhouse:8123/default
   ```
5. Установите:
   - **Expose in SQL Lab:** ✅
   - **Allow DDL:** ❌
6. Нажмите **Connect**

### Импорт датасетов

```bash
# Внутри контейнера
docker compose exec superset bash
python /app/superset_init/init_superset.py
```

### Создание чартов вручную

1. Перейдите в **Charts → + Chart**
2. Выберите датасет (например, `dm.v_events_enriched`)
3. Настройте визуализацию:
   - **Viz Type:** Big Number / Line Chart / Pie Chart / ECharts Bar / Table
   - **Metrics:** COUNT(*), COUNT(DISTINCT ...)
   - **Dimensions:** группировки
   - **Filters:** фильтры
4. Нажмите **Create Chart**

### Создание дашборда

1. **Dashboards → + Dashboard**
2. Назовите: "E-commerce Analytics Dashboard"
3. Добавьте чарты из списка
4. Настройте layout (drag-and-drop)
5. Добавьте Native Filters (фильтры вверху)
6. Сохраните

---

## Импорт дашборда

Основной способ собрать дашборд — `make superset-dashboard` (скрипт `create_dashboard.py`).
Готовый экспорт дашборда лежит в репозитории на случай ручного импорта:
`superset/dashboards/ecommerce_analytics.zip.json` (внутри контейнера —
`/app/superset_init/dashboards/ecommerce_analytics.zip.json`).

```bash
# Импорт через CLI
docker compose exec superset superset import-dashboards -p /app/superset_init/dashboards/ecommerce_analytics.zip.json

# Или через UI: Settings → Import Dashboards
```

---

## Расширение дашборда

### Добавление нового чарта

1. Отредактируйте `superset/create_dashboard.py`
2. Добавьте конфигурацию в `CHARTS_CONFIG`
3. Запустите: `make superset-dashboard`

Пример нового чарта:
```python
{
    "slice_name": "📊 My New Chart",
    "viz_type": "echarts_bar",
    "dataset_name": "v_events_enriched",
    "params": {
        "x_axis": "event_type",
        "metrics": [{"sqlExpression": "COUNT(*)", "label": "Count"}],
        "time_range": "No filter"
    }
}
```

---

## Troubleshooting

### Superset не стартует

```bash
# Проверить логи
make logs service=superset

# Перезапуск
make superset-restart

# Полная переинициализация
docker compose down -v
make generated-history-analytics
```

### Нет данных в чартах

```bash
# Проверить данные в ClickHouse
docker compose exec clickhouse clickhouse-client -q "SELECT count() FROM dm.v_events_enriched"

# Перезапустить ETL
make transform
```

### Ошибка подключения к ClickHouse

```bash
# Проверить доступность ClickHouse
docker compose exec superset bash -c "ping clickhouse"

# Проверить порт
docker compose exec superset bash -c "curl clickhouse:8123"
```

---

## Порты сервисов

| Сервис | URL | Логин/Пароль |
|--------|-----|--------------|
| Superset | http://localhost:8088 | admin / admin |
| ClickHouse HTTP | http://localhost:9123 | default / 123456 |
| Airflow | http://localhost:8080 | admin / admin |
| Grafana | http://localhost:3000 | admin / admin |
| Prometheus | http://localhost:9090 | - |
| Kafka UI | http://localhost:8082 | - |

---

## Дополнительные ресурсы

- [Superset Documentation](https://superset.apache.org/docs/intro)
- [ClickHouse SQL Reference](https://clickhouse.com/docs/en/sql-reference)
- [ARCHITECTURE.md](./ARCHITECTURE.md) — архитектура хранилища