docs(handoff): зафиксировано закрытие аудита точности доков
- Зачем:
- следующей сессии нужна точка опоры: что сделано, какой канон у слоёв и какие
хвосты остались вне скоупа.
- Что:
- добавлен .scratch/handoffs/2026-06-06-docs-accuracy-done.md.
- зафиксированы рамка путей (Airflow — основной, scripts/make — запасной),
канон по урокам 2–3 и открытые хвосты (лицензия, непроверенные уроки 0,1,4–6).
- Проверка:
- git show --stat HEAD; ссылки на findings.md и коммит 92e9c4b актуальны.
This commit is contained in:
@@ -0,0 +1,58 @@
|
||||
# Handoff: профильные доки выверены по коду (готово)
|
||||
|
||||
Дата: 2026-06-06 · Язык сессии: русский
|
||||
|
||||
Эта сессия **закрыла** аудит точности документации. Делать по нему больше нечего — handoff
|
||||
нужен как точка опоры для следующих шагов, а не как список задач.
|
||||
|
||||
## Что сделано
|
||||
|
||||
- Все 12 находок аудита [`/.scratch/docs-accuracy-audit/findings.md`](../docs-accuracy-audit/findings.md)
|
||||
починены. Файл переведён в статус **закрыто** с резолюцией (см. шапку файла).
|
||||
- Один коммит: **`92e9c4b`** `docs(accuracy): профильная документация выверена по коду`,
|
||||
запушен в `docs/advanced-clickstream-course`. Детали правок — в теле коммита и в `git show 92e9c4b`,
|
||||
здесь не дублирую.
|
||||
- Бонусом поймана и исправлена ошибка, которую аудит пропустил: в таблице портов
|
||||
`SUPERSET_DASHBOARD.md` пароль ClickHouse стоял как «(пустой)» вместо `123456`.
|
||||
|
||||
## Ключевой контекст (пригодится дальше)
|
||||
|
||||
- **Источник истины — код, а не доки.** Этот проход сверял каждый claim против
|
||||
`sql/*`, `airflow/dags/*`, `configs/default_user.xml`, `docker-compose.yml`. Подход себя
|
||||
оправдал — так и нашлись расхождения. Повторять при любых правках доков.
|
||||
- **Канон по слоям — уроки 2–3 курса**, а не ARCHITECTURE. В этой сессии ARCHITECTURE
|
||||
подтянут к их формулировкам (DQ-split как пересекающийся, dds.event как browser-driven
|
||||
LEFT JOIN). Уроки 2–3 сверены с кодом и точны; уроки 0,1,4,5,6 **не** проверял.
|
||||
- **Рамка путей запуска (важно, владелец подчёркивал):** основной путь — **Airflow**
|
||||
(DAG-и `ddl_init`/`kafka_load`/`etl_pipeline`); `scripts/*` и обёртки `make` — **запасной
|
||||
fallback** в обход Airflow. Старый README до правки прямо помечал `make ddl/transform`
|
||||
как «(вне Airflow)», а `scripts/` — «legacy fallback». Эта рамка теперь зафиксирована в
|
||||
REPO_MAP; держать её во всех доках, не возвышать Makefile.
|
||||
- **Параллельный Codex в ветке.** Codex пишет другие уроки в ту же ветку. Git держать
|
||||
строго аддитивно: `git add` только своих файлов, не amend/rebase/reset чужих коммитов.
|
||||
(Свой не-запушенный коммит amend-ить можно — в этой сессии так и поправил оплошность с
|
||||
индексом.)
|
||||
- **Стиль:** чистый литературный русский (память `plain-literary-russian`); house style
|
||||
осознанный (тире «—», «ё», жирное начало абзаца) — линтером не править. `ai-text-lint`
|
||||
гонять только на настоящие маркеры, context `article`.
|
||||
|
||||
## Открытые хвосты (не в скоупе этой сессии)
|
||||
|
||||
- 🅿️ **Лицензия стенда.** Роадмап: CC BY 4.0 для контента; для кода обычно MIT —
|
||||
кандидат на dual MIT + CC BY. Фейк-бейдж лицензии из README уже убран ранее.
|
||||
- **Импорт дашборда не прогонялся вживую.** В `SUPERSET_DASHBOARD.md` команда
|
||||
`superset import-dashboards -p .../ecommerce_analytics.zip.json` указывает на реальный
|
||||
файл, но runtime не проверялся (основной способ сборки — `make superset-dashboard`).
|
||||
- **Уроки 0,1,4,5,6** против кода не сверены — если будут править, сверить так же построчно.
|
||||
|
||||
## Состояние
|
||||
|
||||
- Ветка `docs/advanced-clickstream-course`, рабочее дерево чистое, всё запушено.
|
||||
- `.scratch/` коммитится (не в `.gitignore`); этот handoff одноразовый, уборка best-effort.
|
||||
|
||||
## Suggested skills
|
||||
|
||||
- `grill-with-docs` — если доки снова разойдутся с кодом: выверять формулировки против
|
||||
доменной модели и кода, обновляя док по ходу.
|
||||
- `ai-text-lint` — прогон правок (context `article`, house style не снимать).
|
||||
- `conventional-commits` — для коммитов.
|
||||
Reference in New Issue
Block a user