ddadmin
5bd215d19d
- Зачем:
- при переработке README выяснилось, что профильные доки местами
отстали от кода; находки нужно сохранить как отдельную задачу, чтобы
не потерять и чинить отдельным проходом.
- Что:
- добавлен .scratch/docs-accuracy-audit/findings.md со сверенными с
кодом расхождениями ARCHITECTURE, OPERATIONS, REPO_MAP,
SUPERSET_DASHBOARD (с привязкой к файлам и строкам).
- находки разнесены по серьёзности и снабжены порядком починки.
- Проверка:
- открыть .scratch/docs-accuracy-audit/findings.md; сверить 🔴-пункты
с указанными строками кода.
85 lines
6.3 KiB
Markdown
85 lines
6.3 KiB
Markdown
# Аудит точности технической документации против кода
|
||
|
||
Дата: 2026-06-06 · Статус: открыто (починка не начата)
|
||
|
||
Контекст: при переработке корневого `README.md` (mentee-first) встал вопрос, можно ли
|
||
смело отправлять читателя в профильные доки — не устарели ли они сами. Прогнали сверку
|
||
каждого профильного дока против кода (источник истины — SQL/DDL, batch-SQL, DAG-и,
|
||
`docker-compose.yml`, `Makefile`, скрипты Superset). Ниже — подтверждённые расхождения.
|
||
|
||
README по итогам признан самостоятельно корректным (он ссылается на доки, а не повторяет
|
||
их детали) и закоммичен отдельно. Починку доков решили делать отдельным проходом, с
|
||
оглядкой на параллельную работу Codex (особенно по ARCHITECTURE).
|
||
|
||
## 🔴 Вводит в заблуждение / сломано
|
||
|
||
1. **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`.
|
||
|
||
2. **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`.
|
||
|
||
3. **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`.
|
||
|
||
4. **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`.
|
||
|
||
5. **REPO_MAP: пропущен `sql/ods/20_stg_to_ods.sql`** — первый шаг ETL (STG→ODS) вообще
|
||
отсутствует в карте исполняемых артефактов. `docs/REPO_MAP.md:21-23`.
|
||
|
||
## 🟡 Неполно / неточно
|
||
|
||
6. **ARCHITECTURE: `v_session_overview` считает только авторизованных**
|
||
(`WHERE user_domain_id IS NOT NULL`) — в доке не сказано.
|
||
`docs/ARCHITECTURE.md:304` против `sql/ddl/dm/40_dm.sql:148`.
|
||
|
||
7. **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`.
|
||
|
||
8. **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`.
|
||
|
||
9. **OPERATIONS: у `etl_pipeline` не задокументирован параметр `wait_stg_timeout_sec`**
|
||
(default 600). `docs/OPERATIONS.md:57-66` против `airflow/dags/etl_pipeline_dag.py:265-268`.
|
||
|
||
10. **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`.
|
||
|
||
## 🟢 Мелочи
|
||
|
||
11. **OPERATIONS:** Superset (`8088`) и креды ClickHouse (`default/123456`) не вынесены в
|
||
каноническую секцию портов/доступа (фигурируют только ниже по тексту).
|
||
12. **REPO_MAP:** список документации неполон (нет `SUPERSET_DASHBOARD.md`, `docs/course/`,
|
||
`docs/adr/`, демо-скриптов и т. п.).
|
||
|
||
## Вывод для владельца
|
||
|
||
Концептуальные расхождения ARCHITECTURE (DQ-split, сборка DDS с «сиротами») — это ровно
|
||
то, что подробнее и точнее разбирают уроки 2–3 курса. ARCHITECTURE.md отстал от
|
||
реализации, а свежие уроки догнали код. Де-факто каноном по этим темам стали уроки, а не
|
||
ARCHITECTURE — это стоит учесть при починке (возможно, ARCHITECTURE проще подтянуть к
|
||
формулировкам уроков, чем переписывать с нуля).
|
||
|
||
## Предлагаемый порядок починки
|
||
|
||
1. Сначала 🔴 (искажают модель данных и ломают команду).
|
||
2. Перед правкой ARCHITECTURE — свериться, не редактирует ли её Codex.
|
||
3. `make superset-export`: решить — чинить импорты `export_dashboard.py` или убрать команду
|
||
из документации, если экспорт больше не используется.
|