From d955f7d6944e251e9fda080126dc809511900911 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 6 Sep 2026 09:09:14 -0400 Subject: [PATCH] =?UTF-8?q?docs(labs):=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20?= =?UTF-8?q?=D0=A2=D0=97=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B8=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D0=BE=D0=B2=D0=B0=D0=BD=D1=8B=20=D0=BF=D0=BE=20=D1=81=D1=85?= =?UTF-8?q?=D0=B5=D0=BC=D0=B5=20S-N-slug?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - в docs/labs/ будет много заданий; номер ступени и номер задания в имени делают папку оглавлением программы и избавляют от поиска по README (#230). - Что: - шесть ТЗ переименованы через git mv: 1-1…1-5 для ступени 1, 2-1-superset-chart.md для ступени 2; факультатив superset-dashboard.md остался без номера. - обновлены ссылки в docs/labs/README.md, 2-1-superset-chart.md, docs/architecture/dds/session.md и пути в dags/homework_check.py. - правило имен для docs/labs/ в AGENTS.md переписано под S-N-slug. - Проверка: - make lint; скрипт обхода относительных ссылок в docs/ и AGENTS.md — битых нет. Co-Authored-By: Claude Fable 5.1 --- AGENTS.md | 12 ++++++++---- dags/homework_check.py | 10 +++++----- docs/architecture/dds/session.md | 2 +- .../{events-enriched.md => 1-1-events-enriched.md} | 0 .../{top-pages-daily.md => 1-2-top-pages-daily.md} | 0 .../{session-overview.md => 1-3-session-overview.md} | 0 .../{dq-errors-daily.md => 1-4-dq-errors-daily.md} | 0 ...utm-effectiveness.md => 1-5-utm-effectiveness.md} | 0 .../{superset-chart.md => 2-1-superset-chart.md} | 2 +- docs/labs/README.md | 12 ++++++------ 10 files changed, 21 insertions(+), 17 deletions(-) rename docs/labs/{events-enriched.md => 1-1-events-enriched.md} (100%) rename docs/labs/{top-pages-daily.md => 1-2-top-pages-daily.md} (100%) rename docs/labs/{session-overview.md => 1-3-session-overview.md} (100%) rename docs/labs/{dq-errors-daily.md => 1-4-dq-errors-daily.md} (100%) rename docs/labs/{utm-effectiveness.md => 1-5-utm-effectiveness.md} (100%) rename docs/labs/{superset-chart.md => 2-1-superset-chart.md} (98%) diff --git a/AGENTS.md b/AGENTS.md index e6b700f..5d97c7b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -157,10 +157,14 @@ Airflow) и названия из кода. Если для понятия ес дефис (`clickstream-event.md`). Ни даты, ни номера: документ не событие истории, а текущее описание живого формата — и собирается из кода, а не пишется руками. -- Имена файлов в `docs/labs/` — слаг строчными латинскими буквами через дефис - (`top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ учебных - заданий. Ни даты, ни номера: задание — не событие истории, а живой документ, - и правится он вместе с тем, о чем говорит. Слаг называет предмет задания. +- Имена файлов в `docs/labs/` — `S-N-slug.md`: номер ступени, номер задания + внутри ступени и слаг строчными латинскими буквами через дефис + (`1-2-top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ + учебных заданий. Номера повторяют порядок программы из `README.md`, чтобы + папка читалась как оглавление; даты нет: задание — живой документ и + правится вместе с тем, о чем говорит. Слаг называет предмет задания. + Факультативы порядка не имеют и живут под одним слагом + (`superset-dashboard.md`). - Имена файлов в `docs/handbook/` — слаг строчными латинскими буквами через дефис, индекс папки — `README.md`. Здесь живет путеводитель по стенду: учебные главы для менти. Ни дат, ни номеров: глава — живой документ и diff --git a/dags/homework_check.py b/dags/homework_check.py index 68a3342..9c1d786 100644 --- a/dags/homework_check.py +++ b/dags/homework_check.py @@ -109,28 +109,28 @@ def homework_check(): """Дать отдельный результат самопроверки по каждой домашней витрине.""" check_mart.override(task_id="events_enriched")( "dm.events_enriched_v", - "docs/labs/events-enriched.md", + "docs/labs/1-1-events-enriched.md", "events_enriched_vs_dds.sql", "events_enriched_scope.sql", ) check_mart.override(task_id="top_pages_daily")( "dm.top_pages_daily_v", - "docs/labs/top-pages-daily.md", + "docs/labs/1-2-top-pages-daily.md", "top_pages_daily_vs_dds.sql", ) check_mart.override(task_id="session_overview")( "dm.session_overview_v", - "docs/labs/session-overview.md", + "docs/labs/1-3-session-overview.md", "session_overview_vs_dds.sql", ) check_mart.override(task_id="dq_errors_daily")( "dm.dq_errors_daily_v", - "docs/labs/dq-errors-daily.md", + "docs/labs/1-4-dq-errors-daily.md", "dq_errors_daily_vs_ods.sql", ) check_mart.override(task_id="utm_effectiveness")( "dm.utm_effectiveness_v", - "docs/labs/utm-effectiveness.md", + "docs/labs/1-5-utm-effectiveness.md", "utm_effectiveness_vs_dds.sql", ) diff --git a/docs/architecture/dds/session.md b/docs/architecture/dds/session.md index 072473e..d418ec1 100644 --- a/docs/architecture/dds/session.md +++ b/docs/architecture/dds/session.md @@ -111,7 +111,7 @@ - Витрина обзора сессий `session_overview_v`: дневные итоги визитов в срезе устройств; читает `dds.session_v` и поднимает зерно до дня — состав и довод - в ее [ТЗ](../../labs/session-overview.md) (#135). + в ее [ТЗ](../../labs/1-3-session-overview.md) (#135). - DQ-сверка с эталоном (см. выше). - Лаба сессий: менти собирает нарезку сам до знакомства с кодом стенда, потом сравнивает — с эталоном и со стендовой. diff --git a/docs/labs/events-enriched.md b/docs/labs/1-1-events-enriched.md similarity index 100% rename from docs/labs/events-enriched.md rename to docs/labs/1-1-events-enriched.md diff --git a/docs/labs/top-pages-daily.md b/docs/labs/1-2-top-pages-daily.md similarity index 100% rename from docs/labs/top-pages-daily.md rename to docs/labs/1-2-top-pages-daily.md diff --git a/docs/labs/session-overview.md b/docs/labs/1-3-session-overview.md similarity index 100% rename from docs/labs/session-overview.md rename to docs/labs/1-3-session-overview.md diff --git a/docs/labs/dq-errors-daily.md b/docs/labs/1-4-dq-errors-daily.md similarity index 100% rename from docs/labs/dq-errors-daily.md rename to docs/labs/1-4-dq-errors-daily.md diff --git a/docs/labs/utm-effectiveness.md b/docs/labs/1-5-utm-effectiveness.md similarity index 100% rename from docs/labs/utm-effectiveness.md rename to docs/labs/1-5-utm-effectiveness.md diff --git a/docs/labs/superset-chart.md b/docs/labs/2-1-superset-chart.md similarity index 98% rename from docs/labs/superset-chart.md rename to docs/labs/2-1-superset-chart.md index e639b21..c300da1 100644 --- a/docs/labs/superset-chart.md +++ b/docs/labs/2-1-superset-chart.md @@ -6,7 +6,7 @@ ## Сначала прочитать - [«Немного Superset»](../handbook/superset.md); -- [задание 3: `dm.session_overview`](session-overview.md). +- [задание 3: `dm.session_overview`](1-3-session-overview.md). ## Роль графика diff --git a/docs/labs/README.md b/docs/labs/README.md index d6abd5b..b741c46 100644 --- a/docs/labs/README.md +++ b/docs/labs/README.md @@ -9,7 +9,7 @@ | Ступень | Задание | Чему учит | |---|---|---| | 1 | Пять витрин слоя DM | построить результат для потребителя хранилища; уроки каждой витрины — в таблице ниже | -| 2 | [Свой график в Superset](superset-chart.md) | превратить свой результат из хранилища в отчет в BI | +| 2 | [Свой график в Superset](2-1-superset-chart.md) | превратить свой результат из хранилища в отчет в BI | | 3 | Нарежь сессии сам | сравнить свою нарезку визитов с эталоном по числу сессий и найти причину расхождения в отдельных событиях | | 4 | Перепиши нарезку стенда | изменить расчетную сущность внутри готового конвейера и проверить ее внешним эталоном | | 5 | Сначала сторож, потом ломай: заказы | написать проверки качества до рискованного изменения, а не после первой поломки | @@ -27,11 +27,11 @@ | № | Результат | Чему учит | |---|---|---| -| 1 | [`events_enriched_v`](events-enriched.md) | строить слой как договор о данных, а не как их копию | -| 2 | [`top_pages_daily`](top-pages-daily.md) | создавать материализованную витрину с дневной пересборкой в конвейере | -| 3 | [`session_overview`](session-overview.md) | хранить слагаемые для расчета средних и долей | -| 4 | [`dq_errors_daily`](dq-errors-daily.md) | считать брак по дню загрузки и хранить итоги дольше источника | -| 5 | [`utm_effectiveness`](utm-effectiveness.md) | читать `declared_` как предупреждение о сумме со слов клиента | +| 1 | [`events_enriched_v`](1-1-events-enriched.md) | строить слой как договор о данных, а не как их копию | +| 2 | [`top_pages_daily`](1-2-top-pages-daily.md) | создавать материализованную витрину с дневной пересборкой в конвейере | +| 3 | [`session_overview`](1-3-session-overview.md) | хранить слагаемые для расчета средних и долей | +| 4 | [`dq_errors_daily`](1-4-dq-errors-daily.md) | считать брак по дню загрузки и хранить итоги дольше источника | +| 5 | [`utm_effectiveness`](1-5-utm-effectiveness.md) | читать `declared_` как предупреждение о сумме со слов клиента | Общее устройство слоя — [дока DM](../architecture/dm.md). Она отвечает на вопросы «почему так», задание отвечает на вопрос «что сделать».