ddadmin
92e9c4b45a
- Зачем:
- профильные доки отстали от реализации: схема 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-валидатором.
94 lines
7.2 KiB
Markdown
94 lines
7.2 KiB
Markdown
# Аудит точности технической документации против кода
|
||
|
||
Дата: 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).
|
||
|
||
## 🔴 Вводит в заблуждение / сломано
|
||
|
||
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` или убрать команду
|
||
из документации, если экспорт больше не используется.
|