ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 92e9c4b45a docs(accuracy): профильная документация выверена по коду

- Зачем:
  - профильные доки отстали от реализации: схема ods.*_errors, DQ-split и
    сборка dds.event описывались неверно, ряд артефактов и параметров отсутствовал.
    Канон по этим темам де-факто задают свежие уроки 2–3 курса.
- Что:
  - ARCHITECTURE: ods.*_errors как копия с Kafka-метаданными+raw+error_reason;
    DQ-split подан как пересекающийся; dds.event — browser-driven LEFT JOIN с
    маркером location_not_found; добавлен перечень DQ-маркеров; уточнены
    dq_summary (слой dm, orphan_events) и v_session_overview.
  - REPO_MAP: добавлен sql/ods/20_stg_to_ods.sql, утилиты DAG, скрипты Superset;
    scripts/make помечены как запасной путь, Airflow — основной.
  - OPERATIONS: параметр wait_stg_timeout_sec; порт Superset и креды ClickHouse.
  - SUPERSET_DASHBOARD: исправлен пароль ClickHouse (123456); убран сломанный
    make superset-export, удалён superset/export_dashboard.py и target в Makefile.
- Проверка:
  - git diff проверен против sql/*, airflow/dags/*, configs/default_user.xml;
    ER-диаграмма провалидирована mermaid-валидатором.

2026-06-06 21:43:31 +03:00

7.2 KiB

Raw Blame History

Аудит точности технической документации против кода

Дата: 2026-06-06 · Статус: закрыто (все 12 находок починены 2026-06-06)

Резолюция. 🔴 #1–#3 правлены в ARCHITECTURE.md (схема *_errors, DQ-split как пересекающийся, dds.event как browser-driven LEFT JOIN + маркер location_not_found) — формулировки подтянуты к урокам 2–3. #4: владелец решил убрать make superset-export (раздел доки + target в Makefile + битый superset/export_dashboard.py удалены). 🟡 #6–#10 и 🟢 #11–#12 закрыты в ARCHITECTURE.md/OPERATIONS.md/REPO_MAP.md (добавлен перечень DQ-маркеров, параметр wait_stg_timeout_sec, порты Superset/креды CH, пропущенные артефакты). Заодно зафиксирована рамка: основной путь — Airflow, scripts//make — запасной.

Контекст: при переработке корневого README.md (mentee-first) встал вопрос, можно ли смело отправлять читателя в профильные доки — не устарели ли они сами. Прогнали сверку каждого профильного дока против кода (источник истины — SQL/DDL, batch-SQL, DAG-и, docker-compose.yml, Makefile, скрипты Superset). Ниже — подтверждённые расхождения.

README по итогам признан самостоятельно корректным (он ссылается на доки, а не повторяет их детали) и закоммичен отдельно. Починку доков решили делать отдельным проходом, с оглядкой на параллельную работу Codex (особенно по ARCHITECTURE).

🔴 Вводит в заблуждение / сломано

ARCHITECTURE: схема ods.*_errors описана неверно. Док подаёт таблицы ошибок как копию типизированной таблицы события (с event_id, parse_errors). Реально это метаданные Kafka + raw + error_reason — другая схема. docs/ARCHITECTURE.md:149,529-532 против sql/ddl/ods/20_ods.sql:46-58.
ARCHITECTURE: DQ-split подан как взаимоисключающий. Док: «валидные → основная таблица, ошибки → errors». Реально строка с валидным event_id, но битым event_ts/click_id попадает в обе таблицы одновременно. docs/ARCHITECTURE.md:160-162,520-521 против sql/ods/20_stg_to_ods.sql:67,91-96.
ARCHITECTURE: dds.event — browser-driven LEFT JOIN, а не симметричный JOIN 1:1. event_id, которые есть только в location_event (без browser), в dds.event не попадают. Маркер location_not_found в доке не упомянут. docs/ARCHITECTURE.md:205,446-460,398 против sql/dds/30_ods_to_dds.sql:139,141-172.
SUPERSET_DASHBOARD: make superset-export задокументирован как рабочий, но сломан. superset/export_dashboard.py:22-23 импортирует несуществующие модули Superset (superset.dashboards.data_access_layer, superset.charts.data_access_layer) и падает в except ImportError → sys.exit(1). Плюс реальный файл экспорта — superset/dashboards/ecommerce_analytics.zip.json, а док обещает ecommerce_analytics.json. docs/SUPERSET_DASHBOARD.md:81-83,202-207.
REPO_MAP: пропущен sql/ods/20_stg_to_ods.sql — первый шаг ETL (STG→ODS) вообще отсутствует в карте исполняемых артефактов. docs/REPO_MAP.md:21-23.

🟡 Неполно / неточно

ARCHITECTURE: v_session_overview считает только авторизованных (WHERE user_domain_id IS NOT NULL) — в доке не сказано. docs/ARCHITECTURE.md:304 против sql/ddl/dm/40_dm.sql:148.
ARCHITECTURE: dq_summary шире, чем сказано. Док: «слои stg/ods/dds». Реально есть ещё слой dm (v_events_enriched) и метрика orphan_events. docs/ARCHITECTURE.md:320-331 против sql/dm/40_dds_to_dm.sql:99-115.
ARCHITECTURE: перечень DQ-маркеров неполон. Не упомянуты geo_country_missing (DDS click), bad_geo_latitude/bad_geo_longitude/bad_user_domain_id (ODS), os_timezone в ER-диаграмме DEVICE_BY_CLICK. sql/dds/30_ods_to_dds.sql:50, sql/ods/20_stg_to_ods.sql:172,227-228.
OPERATIONS: у etl_pipeline не задокументирован параметр wait_stg_timeout_sec (default 600). docs/OPERATIONS.md:57-66 против airflow/dags/etl_pipeline_dag.py:265-268.
REPO_MAP: пропущены артефакты. Скрипты superset/{init_superset,create_dashboard,export_dashboard}.py, утилиты airflow/dags/utils/{sql_helpers,airflow_params}.py. Описание sql/dm/40_dds_to_dm.sql занижено («обновление dq_summary» вместо полного TRUNCATE+INSERT DDS→DM). docs/REPO_MAP.md:9-13,21-23.

🟢 Мелочи

OPERATIONS: Superset (8088) и креды ClickHouse (default/123456) не вынесены в каноническую секцию портов/доступа (фигурируют только ниже по тексту).
REPO_MAP: список документации неполон (нет SUPERSET_DASHBOARD.md, docs/course/, docs/adr/, демо-скриптов и т. п.).

Вывод для владельца

Концептуальные расхождения ARCHITECTURE (DQ-split, сборка DDS с «сиротами») — это ровно то, что подробнее и точнее разбирают уроки 2–3 курса. ARCHITECTURE.md отстал от реализации, а свежие уроки догнали код. Де-факто каноном по этим темам стали уроки, а не ARCHITECTURE — это стоит учесть при починке (возможно, ARCHITECTURE проще подтянуть к формулировкам уроков, чем переписывать с нуля).

Предлагаемый порядок починки

Сначала 🔴 (искажают модель данных и ломают команду).
Перед правкой ARCHITECTURE — свериться, не редактирует ли её Codex.
make superset-export: решить — чинить импорты export_dashboard.py или убрать команду из документации, если экспорт больше не используется.

7.2 KiB Raw Blame History Unescape Escape