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

- 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
2026-02-08 20:23:42 +03:00
parent a185a56762
commit 03de68e0c5
3 changed files with 167 additions and 148 deletions
@@ -0,0 +1,94 @@
+# Operations Runbook
+
+Операционный runbook для локального запуска и проверки пайплайна.
+
+## Локальный запуск
+
+Базовые команды:
+
+- `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 ps`
+- `docker compose logs -f --tail=200 <service>`
+- `docker compose down` (сохраняет named volumes, включая `clickhouse-data`)
+- `docker compose down -v` (удаляет named 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`
+
+## Airflow DAGs
+
+### `ddl_init`
+
+- Запуск: ручной (`Trigger DAG`)
+- Параметр: `verify_only` (`bool`, default `false`)
+- Назначение: создаёт БД и таблицы в ClickHouse от `00_databases` до `40_dm`
+
+### `kafka_load`
+
+- Запуск: ручной (`Trigger DAG with config`)
+- Параметры:
+  - `limit` (`int`, default `0`) — количество строк (`0` = все)
+  - `reset_topics` (`bool`, default `true`) — пересоздать топики
+- Примеры:
+
+```json
+{}
+```
+
+```json
+{"limit": 100}
+```
+
+### `etl_pipeline`
+
+- Запуск: ручной (`Trigger DAG with config`)
+- Параметр: `full_refresh` (`bool`, default `true`) — очистить DDS перед загрузкой
+- Зависимость: требует наличия данных в STG (от `kafka_load` или `make data`)
+
+## Рекомендуемый сценарий (фаза 2)
+
+```bash
+# 1. Запуск инфраструктуры
+make up
+
+# 2. Инициализация схемы (один раз)
+# Airflow UI -> DAGs -> ddl_init -> Trigger DAG
+
+# 3. Загрузка данных через Airflow
+# 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"
+```
+
+## Быстрые проверки
+
+- Kafka ingest: наличие данных в `stg.*` и типизированных строк в `ods.*`.
+- Мониторинг: доступность `/metrics` у ClickHouse и скрейп в Prometheus.
+- Airflow UI: `http://localhost:8080` показывает DAG `ddl_init`, `kafka_load`, `etl_pipeline`.
+- BI: витрина `dm.v_events_enriched` отвечает за разумное время при фильтре по дате.
+
+## Troubleshooting
+
+- `etl_pipeline` падает с ошибкой схемы: сначала запустить `ddl_init`.
+- После `docker compose down -v` нужно повторно прогнать: `ddl_init` -> `kafka_load` -> `etl_pipeline`.
+- Для демо по умолчанию использовать малый срез данных; полный прогон делать осознанно.
@@ -0,0 +1,48 @@
+# Repo Map
+
+Карта ключевых артефактов репозитория.
+
+## Исполняемые файлы
+
+### Airflow
+
+- `airflow/dags/ddl_init_dag.py` — инициализация схемы ClickHouse
+- `airflow/dags/kafka_load_dag.py` — загрузка в Kafka из JSONL
+- `airflow/dags/etl_pipeline_dag.py` — ETL процесс STG -> ODS -> DDS -> DM
+- `airflow/dags/utils/kafka_helpers.py` — helper-функции для Kafka
+- `airflow/requirements.txt` — зависимости Airflow/ClickHouse plugin
+
+### 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
+- `scripts/load_kafka_data.sh` — загрузка в Kafka
+- `scripts/run_batch.sh` — batch-процесс
+
+## Данные и конфиги
+
+- `data/*.jsonl` — исходные данные (могут быть грязными)
+- `configs/` — конфиги ClickHouse, Prometheus, Grafana
+
+## Документация
+
+- `README.md` — быстрый старт и обзор проекта
+- `docs/ARCHITECTURE.md` — техническая архитектура
+- `docs/OPERATIONS.md` — запуск, проверки, troubleshooting
+- `docs/DE-task.md` — исходное задание
+- `docs/COMMIT_RULES.md` — правила коммитов
+
+## Legacy-планы
+
+- `plans/clickhouse_ddl.md` — исходный план (inline DDL)
+- `plans/runbook.md` — ранний runbook
+- `plans/kafka_ingest_plan.md` — ранний план Kafka ingest