# Учебный стенд 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)

> **Стенд заморожен для новых фич.** Он остаётся стабильным учебным стендом:
> что здесь работает, то работает и дальше — курс и лабы живут тут.
> Развитие переехало в
> [clickstream-data-platform](https://git.dementev.space/ddmitry/clickstream-data-platform):
> там одно широкое событие кликстрима вместо четырёх топиков, заказы бэкенда
> вторым источником и ClickHouse кластером.

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

Поток данных коротко:
- **стартовая история**: `world_init → 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-проверок и команд разработки.

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

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

Дальше всё делается в Airflow: `http://localhost:8080` (`admin/admin`).
Список DAG'ов читается лесенкой сверху вниз; на свежем стенде все DAG'и
создаются на паузе, поэтому перед запуском снимайте паузу переключателем
слева от имени.

1. `ddl_init` — снимите паузу и запустите: DAG создаст схему ClickHouse
   (отдельная команда в терминале не нужна).
2. `etl_pipeline` — только снимите паузу: его запустит следующий шаг.
3. `world_init` — снимите паузу и запустите с пустой формой: DAG импортирует
   эталонный мир, запустит ETL и сверит витрины.
4. `world_next_day` — когда захотите добавить ровно один модельный день,
   запустите его с пустой формой. Расписание задано каждые 30 минут, но по
   умолчанию DAG стоит на паузе.

`make up` не запускает live-генератор; live включается отдельно командой
`make generator-continue`.

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

Для полностью автоматического чистого прогона из консоли есть команда — это
тот же путь, что выше через Airflow UI, но одной командой и без ручных шагов
(схему ClickHouse она применяет сама):

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

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

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

```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) — экспорт,
  импорт эталонного мира из Git по умолчанию и live-продолжение.
- [Карта репозитория](./docs/REPO_MAP.md) — где какие файлы и что менять.
- [Реализм генератора](./docs/generator-realism.md) — что в потоке как в бою,
  а что учебная условность.
- [Курс «Кликстрим на ClickHouse»](./docs/course/README.md) — учебная программа на этом
  стенде.
- [DE-task.md](./docs/DE-task.md) — задание, из которого вырос стенд.
