ddmitry/clickstream-ch-kafka-superset-demo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docs): slim down AGENTS and split runbook sections

Browse Source 
- Why:\n  - AGENTS.md became too large and mixed policy with operational details\n  - context7 requirement was easy to miss in long text\n- What:\n  - reduce AGENTS.md to a compact contributor contract\n  - add explicit mandatory MCP Context7 workflow block\n  - move runbook details to docs/OPERATIONS.md\n  - move artifact map to docs/REPO_MAP.md\n- Check:\n  - reviewed links and content after split\n  - ensured only documentation files are included in commit
This commit is contained in:
ddadmin
2026-02-08 20:23:42 +03:00
parent a185a56762
commit 03de68e0c5
3 changed files with 167 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+25 -148
View File
@@ -1,164 +1,41 @@
# AGENTS.md
Инструкции для работы с репозиторием мини‑демо хранилища кликстрима.
Короткий контракт для работы в репозитории мини-демо DWH кликстрима.
## Цель репозитория
Решение [тестового задания DE](./data/DE-task.md) — развернуть в `docker compose` минимальный аналитический стек для обработки кликстрима e-commerce:
Реализовать [тестовое задание DE](./docs/DE-task.md): поднять в `docker compose` стек Kafka + ClickHouse + Airflow + Superset + Prometheus/Grafana и получить витрины для первичного анализа.
**Задача:** Подготовить данные для первичного анализа и собрать дашборд, на котором бизнес может сделать выводы.
## Обязательные правила
**Итоговый стек:**
### Данные
- Kafka (источник событий, 1 JSON message = 1 event)
- ClickHouse (STG → ODS → DDS → DM)
- **Airflow** (оркестрация ETL-пайплайна)
- Superset (BI поверх витрин)
- Prometheus + Grafana (мониторинг)
- простой инструмент/скрипт, который читает `.jsonl` и пишет события в Kafka
- Не загружать `*.jsonl` целиком без необходимости: по умолчанию использовать малый срез (`head -n 20..50`).
- Для демо и тестов важнее быстрый и повторяемый прогон, чем полнота данных.
- "Грязные" записи не должны валить пайплайн: ошибки парсинга фиксируются в ODS.
## Ключевые артефакты
### Изменения в коде
### Исполняемые файлы (текущая структура)
- `airflow/dags/` — Airflow DAGs для оркестрации ETL:
- `airflow/dags/ddl_init_dag.py` — инициализация схемы ClickHouse
- `airflow/dags/etl_pipeline_dag.py` — ETL процесс STG → ODS → DDS → DM
- `airflow/dags/kafka_load_dag.py` — загрузка данных в Kafka из JSONL
- `airflow/dags/utils/kafka_helpers.py` — helper-функции для работы с Kafka
- `sql/` — SQL по слоям:
- `sql/ddl/00_databases.sql` — создание БД stg/ods/dds/dm
- `sql/ddl/stg/10_stg.sql` — STG слой (Kafka Engine + MV)
- `sql/ddl/ods/20_ods.sql` — ODS слой (типизация + MV для ошибок)
- `sql/ddl/dds/30_dds.sql` — DDS слой (таблицы для batch-загрузки)
- `sql/ddl/dm/40_dm.sql` — DM слой (витрины VIEW)
- `sql/dds/30_ods_to_dds.sql` — ODS → DDS (argMax + JOIN)
- `sql/dm/40_dds_to_dm.sql` — обновление DQ_summary
- `scripts/` — скрипты автоматизации:
- `apply_clickhouse_ddl.sh` — применение DDL
- `load_kafka_data.sh` — загрузка в Kafka
- `run_batch.sh` — запуск batch-процесса
- `airflow/` — конфигурация Airflow:
- `requirements.txt` — зависимости Airflow/ClickHouse plugin
- Изменения держать минимальными и в скоупе задания (инфра, ingest, трансформации, витрины, мониторинг).
- Не коммитить секреты. Использовать `.env` и `.env.example`.
- При изменении инфраструктуры или DDL обновлять документацию в этом же PR.
- Комментарии в SQL и Bash писать на русском языке.
### Планы и документация (legacy)
- `plans/clickhouse_ddl.md` — исходный план (inline DDL, legacy)
- `plans/runbook.md` — runbook
- `plans/kafka_ingest_plan.md` — план загрузки в Kafka
- `docs/ARCHITECTURE.md` — подробное описание архитектуры
- `data/DE-task.md` — текст задания.
- `data/*.jsonl` — исходные данные (могут быть грязными).
- `configs/` — конфиги ClickHouse/Prometheus/Grafana.
### Проверка API через MCP Context7 (обязательно)
## Правила по данным (важно)
- Для спорных или меняющихся API (особенно Airflow/operators/providers) сначала уточнять актуальную версию через MCP Context7.
- Минимальный порядок: `resolve-library-id` -> `query-docs`.
- Принятое решение фиксировать в коде и/или документации (кратко: что проверили и почему выбрали именно этот вариант).
- Не загружать исходные `*.jsonl` целиком: используйте `head -n 20..50`.
- Для тестов/демо предпочтительнее “малый срез”, чем “идеальная полнота”.
- Данные могут быть с ошибками — пайплайн должен быть устойчивым (в ODS фиксировать ошибки парсинга, а не падать).
## Навигация по документации
## Как запускать (локально)
- [README.md](./README.md) — пользовательский quick start и обзор.
- [docs/REPO_MAP.md](./docs/REPO_MAP.md) — карта исполняемых артефактов и где что менять.
- [docs/OPERATIONS.md](./docs/OPERATIONS.md) — запуск, DAG-параметры, проверки и troubleshooting.
- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — детали по слоям STG/ODS/DDS/DM.
- [docs/COMMIT_RULES.md](./docs/COMMIT_RULES.md) — правила оформления коммитов.
- [plans/](./plans/) — legacy-планы (использовать как исторический контекст, не как источник истины).
Базовые команды:
## Ограничения по структуре
- `make up` (или `docker compose up -d`)
- `make ddl` (применяет SQL из `sql/ddl/00_databases.sql` и `sql/ddl/*/*.sql` в ClickHouse)
- `make data` (пересоздаёт топики и заливает небольшой срез данных в Kafka; полный режим — `FULL=1 make data`)
- `make transform` (запускает batch-процесс ODS → DDS → DM)
- `docker compose up -d`
- `docker compose ps`
- `docker compose logs -f --tail=200 <service>`
- `docker compose down` (сохраняет named volumes, включая `clickhouse-data`)
- `docker compose down -v` (удалит volumes; используйте осознанно)
Порты (см. `docker-compose.yml`):
- ClickHouse native: `localhost:8002`
- ClickHouse HTTP: `localhost:9123`
- Kafka: `localhost:9092`
- Kafka UI: `http://localhost:8082`
- **Airflow: `http://localhost:8080` (admin/admin)**
- Prometheus: `http://localhost:9090`
- Grafana: `http://localhost:3000`
## ClickHouse: применение DDL и загрузка сэмпла
- DDL/пайплайн описаны в `plans/clickhouse_ddl.md`.
- Для быстрой загрузки “первых N строк” используйте команды из раздела “Практические заметки для демо”.
## Конвенции по изменениям
- Держать изменения минимальными и по теме задания (инфра, схема, ingest, витрины).
- Не коммитить секреты. Если требуется пароль/ключи — использовать `.env` и примеры `.env.example`.
- Оформлять коммиты по правилам из [COMMIT_RULES.md](./docs/COMMIT_RULES.md).
- README/планы обновлять вместе с изменениями инфраструктуры/DDL.
- Для спорных или меняющихся API (особенно Airflow/operators/providers) проверять актуальную документацию через `context7` и фиксировать решение в коде/документации.
- **Комментарии в коде — на русском языке**:
- SQL: заголовочный блок с описанием файла, комментарии к каждому логическому блоку
- Bash: шапка с назначением/запуском/требованиями, секции разделены `# -----`
- См. существующие файлы как пример (`sql/ddl/ods/20_ods.sql`, `sql/dds/30_ods_to_dds.sql`, `scripts/run_batch.sh`)
## Airflow DAGs
### `ddl_init` — Инициализация схемы
- Запуск: ручной (Trigger DAG)
- Параметры: `verify_only` (bool, default false)
- Описание: Создаёт БД и таблицы в ClickHouse от 00_databases до 40_dm
### `kafka_load` — Загрузка в Kafka
- Запуск: ручный (Trigger DAG with config)
- Параметры:
- `limit` (int, default 0) — количество строк (0 = все)
- `reset_topics` (bool, default true) — пересоздать топики
- Примеры запуска:
```json
// Полная загрузка (по умолчанию)
{}
// Ограниченная загрузка — 100 строк
{"limit": 100}
```
### `etl_pipeline` — ETL процесс
- Запуск: ручной (Trigger DAG with config)
- Параметры:
- `full_refresh` (bool, default true) — очистить DDS перед загрузкой
- Зависимость: требует наличия данных в STG (от `kafka_load` или `make data`)
## Быстрые проверки
- Kafka ingest: наличие данных в `stg.*` и типизированных строк в `ods.*`.
- Мониторинг: доступность `/metrics` у ClickHouse и скрейп в Prometheus.
- **Airflow: `http://localhost:8080` должен показывать UI и DAG `ddl_init`, `kafka_load` и `etl_pipeline`.**
- BI: витрина `dm.v_events_enriched` должна отвечать за разумное время при фильтре по дате.
## Сценарий работы с Airflow (фаза 2)
```bash
# 1. Запуск инфраструктуры
make up
# 2. Инициализация схемы (один раз)
# Airflow UI → DAGs → ddl_init → Trigger DAG
# 3. Загрузка данных через Airflow (вместо make data)
# Airflow UI → DAGs → kafka_load → Trigger DAG with config
# Параметры по умолчанию: limit=0 (полная загрузка), reset_topics=true
# 4. Запуск ETL
# Airflow UI → DAGs → etl_pipeline → Trigger DAG with config
# {"full_refresh": true}
# 5. Проверка результатов
docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT count() FROM ods.browser_event"
docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT count() FROM dds.event"
docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT * FROM dm.dq_summary"
```
## Связанная документация
- [README.md](./README.md) — пользовательская документация (быстрый старт, архитектура)
- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — подробное описание слоёв и технических решений
- [data/DE-task.md](./data/DE-task.md) — исходное задание
- [COMMIT_RULES.md](./docs/COMMIT_RULES.md) — правила оформления коммитов
## Примечания по текущему состоянию (если что-то “не встаёт”)
Репозиторий развивается итеративно; если `docker compose` не стартует из‑за отсутствующих путей/сетей/сервисов, правьте аккуратно и фиксируйте это в `docker-compose.yml` и/или `configs/`.
- Новые документы создавать в `docs/` (или в профильных подпапках), не в корне репозитория.