ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 90f3ac5ea1 docs(handoff): контекст для уточнения документации по архитектуре

- Зачем:
  - следующая сессия чинит профильные доки, отставшие от кода; нужен
    быстрый вход с готовым рабочим списком, а отработанный handoff про
    корневой README больше не актуален.
- Что:
  - добавлен handoff 2026-06-06-docs-accuracy-fixes.md со ссылкой на
    аудит, порядком починки и ключевым контекстом.
  - удалён отработанный 2026-06-06-root-readme-polish.md.
- Проверка:
  - открыть .scratch/handoffs/2026-06-06-docs-accuracy-fixes.md и
    .scratch/docs-accuracy-audit/findings.md.

2026-06-06 20:17:44 +03:00

4.7 KiB

Raw Blame History

Handoff: уточнение документации по архитектуре

Дата: 2026-06-06 · Язык сессии: русский

Следующая сессия чинит профильную документацию, которая отстала от кода. Рабочий список уже собран и сверён с кодом — не переоткрывай его заново, бери готовый: .scratch/docs-accuracy-audit/findings.md (12 находок, разнесены по серьёзности, с привязкой файл:строка).

Что делать

Чинить доки по списку аудита, начиная с 🔴:

ARCHITECTURE.md — три концептуальных искажения: схема ods.*_errors, DQ-split подан как взаимоисключающий (а строка попадает в обе таблицы), сборка dds.event (browser-driven LEFT JOIN, не симметричный JOIN; «сироты» из location отбрасываются).
SUPERSET_DASHBOARD.md — make superset-export задокументирован как рабочий, но export_dashboard.py падает на устаревших импортах. Решение за владельцем: чинить импорты или убрать команду из доки, если экспорт больше не нужен.
REPO_MAP.md — пропущен первый шаг ETL sql/ods/20_stg_to_ods.sql и ряд артефактов.

Потом 🟡 (неполнота параметров и DQ-маркеров) и 🟢 (мелочи).

Контекст, который сэкономит время

Источник истины — код, не доки: sql/ddl/*, sql/ods|dds|dm/*, airflow/dags/*, superset/*.py, docker-compose.yml, Makefile. Аудит уже сослался на нужные строки.
Ключевой инсайт: концептуальные темы ARCHITECTURE (DQ-split, сборка DDS с сиротами) точнее и подробнее разобраны в уроках 2–3 курса (docs/course/lessons/). Де-факто каноном стали уроки, а не ARCHITECTURE. Скорее всего проще подтянуть ARCHITECTURE к формулировкам уроков, чем переписывать с нуля — и заодно проверить, что урок и код совпадают (уроки свежие, но тоже стоит сверить).
Codex сейчас стоит — параллельной записи в ветку нет, можно править ARCHITECTURE спокойно. Но привычку держать аддитивно не теряй: git add только своих файлов.
Стиль/голос доков: чистый литературный русский без лишних англицизмов (см. память plain-literary-russian); house style осознанный (тире «—», «ё», жирное начало абзаца, двоеточие перед списком) — линтером не правим. ai-text-lint гонять только на настоящие маркеры, context article.
Проверять claim на коде, а не на глаз — этот подход в этой сессии и вскрыл все расхождения.

Состояние

Ветка docs/advanced-clickstream-course. Эта сессия добавила два коммита: ce7f03b (корневой README переписан под менти+песочницу) и 5bd215d (аудит в .scratch). Корневой README трогать больше не нужно — он самостоятельно корректен (только ссылается на доки).
Рабочее дерево чистое (после коммита/пуша этой сессии).
🅿️ Future, не в скоупе: лицензия стенда (роадмап = CC BY 4.0; для кода обычно MIT — кандидат на dual MIT + CC BY); фейк-бейдж лицензии в README уже убран.

Suggested skills

grill-with-docs — выверить формулировки ARCHITECTURE против доменной модели и кода, обновляя док по ходу решений (ровно под эту задачу).
ai-text-lint — прогон правок (context article, house style не снимать).
conventional-commits — для коммитов.

4.7 KiB Raw Blame History Unescape Escape