clickstream-ch-kafka-superset-demo/README.md

# Учебный стенд DWH кликстрима

[![Stack](https://img.shields.io/badge/stack-Kafka%20%7C%20ClickHouse%20%7C%20Airflow%20%7C%20Superset%20%7C%20Prometheus%2FGrafana-blue)](./docker-compose.yml)
[![Layers](https://img.shields.io/badge/layers-STG%20→%20ODS%20→%20DDS%20→%20DM-green)](./docs/ARCHITECTURE.md)

Живой стек для работы с кликстримом: Kafka, ClickHouse, Airflow, Superset и мониторинг
(Prometheus с Grafana) поднимаются в Docker одной командой. На этом стенде можно учиться
по курсу или просто поднять его у себя и поэкспериментировать с потоковой загрузкой и
витринами.

Поток данных коротко:
- **стартовая история**: `generator backfill → Kafka → ClickHouse (STG) →
  batch STG → ODS → DDS → DM → Superset`.
- **живое продолжение**: `generator live → Kafka → ClickHouse (STG) → batch ETL
  → Superset`.

Файлы `data/*.jsonl` больше не основной источник аналитики. Пока они остаются
архивной кладовкой значений для генератора: браузеры, страны, устройства и UTM.

## Куда дальше

- **Хочешь учиться** — открой [курс «Кликстрим на ClickHouse»](./docs/course/README.md).
  Это продвинутый курс «со звёздочкой»: основные приёмы инженерии данных проходишь прямо
  на этом стенде.
- **Хочешь поднять и попробовать** — следуй быстрому старту ниже.
- **Хочешь разобраться в устройстве** — смотри [архитектуру слоёв](./docs/ARCHITECTURE.md),
  [запуск и эксплуатацию](./docs/OPERATIONS.md) и [карту репозитория](./docs/REPO_MAP.md).

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

Перед первой командой нужны `Docker` с `docker compose`, `make`, `bash`, `curl`,
`git` и `uv`. `uv` нужен для локальных Python-проверок и команд разработки.

Для ручной работы поднимите стенд и создайте стартовую историю через Airflow:

```bash
make up
make ddl
docker compose ps
```

Откройте Airflow: `http://localhost:8080` (`admin/admin`). Запустите
`generator_control` с операцией `backfill`: DAG создаст стартовую историю,
запустит ETL и выполнит `check`. `make up` не запускает live-генератор; live
включается отдельно командой `make generator-continue`.

После обновления репозитория снова выполните `make up`: команда пересобирает
Airflow-образ и подтягивает новые зависимости и DAG-и. Superset-дэшборд
собирается позже, когда DM уже готов: через `make generated-history-analytics`
или `make superset-init`.

Для полностью автоматического чистого прогона из консоли остаётся команда:

```bash
make generated-history-analytics
```

По умолчанию это быстрый профиль `ci`: 6 часов модельного времени. Историю на
2 суток с суточной волной можно прогнать одной командой. В live-продолжении
`daily-wave` идёт с ×60: модельные сутки проходят примерно за 24 настенные
минуты.

```bash
PROFILE=daily-wave make generated-history-analytics
```

Разовую длительность можно задать без ручного расчёта правой границы:

```bash
GEN_HISTORY_DURATION=2d make generated-history-analytics
```

Повторить техническую проверку после такого прогона только стартовой истории:

```bash
CHECK_LIVE_SEAM=0 make generated-history-check
```

Стык backfill/live проверяйте отдельным коротким сценарием:

```bash
make generated-history-runtime-check
```

Перед коммитом используйте быстрые проверки:

```bash
make test
make lint
```

Они не чистят volumes и не запускают долгие стендовые сценарии. Полная проверка
стыка backfill/live остаётся отдельной командой `make generated-history-runtime-check`.

Сохранить стартовую историю в файл и восстановить её без новой генерации можно
по [runbook стартовой истории](./docs/runbooks/startup-history.md).

Проверить, что данные дошли до витрин:

```bash
docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 \
  --query "SELECT count() FROM dm.v_events_enriched"
```

Подробный сценарий запуска, параметры DAG-ов и разбор частых проблем — в
[OPERATIONS](./docs/OPERATIONS.md).

## Сервисы и доступы

| Сервис | Адрес | Назначение | Логин/пароль |
|--------|-------|------------|--------------|
| Airflow | `http://localhost:8080` | оркестрация ETL | admin/admin |
| ClickHouse | `http://localhost:9123/play` | SQL-запросы | default/123456 |
| Kafka UI | `http://localhost:8082` | просмотр топиков | — |
| Superset | `http://localhost:8088` | дашборды | admin/admin |
| Prometheus | `http://localhost:9090` | метрики | — |
| Grafana | `http://localhost:3000` | графики метрик | admin/admin |

Готовый дашборд в Superset:
`http://localhost:8088/superset/dashboard/ecommerce-analytics/` — он создаётся
во время `make generated-history-analytics`. Состав и настройка дашборда описаны в
[SUPERSET_DASHBOARD](./docs/SUPERSET_DASHBOARD.md).

## Как устроен поток данных

```mermaid
flowchart LR
    subgraph GEN["Generator"]
        BF["backfill"]
        LIVE["live"]
    end

    subgraph Kafka["Kafka"]
        Topics[4 топика]
    end

    subgraph CH["ClickHouse"]
        STG["STG: сырые данные"]
        ODS["ODS: типизация + DQ"]
        DDS["DDS: сущности"]
        DM["DM: витрины VIEW"]
    end

    BF -->|стартовая история| Kafka
    LIVE -->|продолжение| Kafka
    Kafka -->|Kafka MV| STG
    STG -->|batch| ODS -->|batch| DDS -->|VIEW| DM

    DDL["DDL"] -.-> CH
```

«Грязные» записи не роняют пайплайн: ошибки разбора складываются в `ods.*_errors` и в
поле `parse_errors`, а обработка продолжается.

Подробное описание слоёв STG/ODS/DDS/DM, диаграммы и обоснование решений —
в [ARCHITECTURE](./docs/ARCHITECTURE.md).

## Документация

- [Архитектура и слои](./docs/ARCHITECTURE.md) — устройство STG/ODS/DDS/DM, диаграммы,
  обоснование решений.
- [Запуск и эксплуатация](./docs/OPERATIONS.md) — сценарий запуска, параметры DAG-ов,
  мониторинг, частые проблемы.
- [Runbook стартовой истории](./docs/runbooks/startup-history.md) — экспорт,
  импорт и live-продолжение из готового артефакта.
- [Карта репозитория](./docs/REPO_MAP.md) — где какие файлы и что менять.
- [Курс «Кликстрим на ClickHouse»](./docs/course/README.md) — учебная программа на этом
  стенде.
- [DE-task.md](./docs/DE-task.md) — задание, из которого вырос стенд.