diff --git a/AGENTS.md b/AGENTS.md index 5d97c7b..383dfa7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -157,14 +157,15 @@ Airflow) и названия из кода. Если для понятия ес дефис (`clickstream-event.md`). Ни даты, ни номера: документ не событие истории, а текущее описание живого формата — и собирается из кода, а не пишется руками. -- Имена файлов в `docs/labs/` — `S-N-slug.md`: номер ступени, номер задания - внутри ступени и слаг строчными латинскими буквами через дефис - (`1-2-top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ +- Имена файлов основной программы в `docs/labs/` — `S-N-slug.md`: + номер ступени, номер задания внутри ступени и слаг строчными латинскими + буквами через дефис (`1-2-top-pages-daily.md`). Здесь живут ТЗ учебных заданий. Номера повторяют порядок программы из `README.md`, чтобы папка читалась как оглавление; даты нет: задание — живой документ и правится вместе с тем, о чем говорит. Слаг называет предмет задания. - Факультативы порядка не имеют и живут под одним слагом - (`superset-dashboard.md`). + Факультативы живут в `docs/labs/optional/`, без номеров, под одним слагом + (`superset-dashboard.md`). Общий индекс обеих частей — `docs/labs/README.md`; + отдельного индекса в `optional/` нет. - Имена файлов в `docs/handbook/` — слаг строчными латинскими буквами через дефис, индекс папки — `README.md`. Здесь живет путеводитель по стенду: учебные главы для менти. Ни дат, ни номеров: глава — живой документ и diff --git a/docs/architecture/dm.md b/docs/architecture/dm.md index 452a68a..e3a4442 100644 --- a/docs/architecture/dm.md +++ b/docs/architecture/dm.md @@ -7,20 +7,19 @@ ## Форма: по зерну, не по цене запроса -Витрина, меняющая зерно источника — дневной агрегат, сверка по заказам, — +На этом стенде форма витрины выбрана ради учебной задачи. Витрина, меняющая +зерно источника — дневной агрегат, сверка по заказам, — материализуется: `dm.<имя>_rep` / `_dist` и публичное `dm.<имя>_v` с явным списком колонок, по общим [конвенциям хранилища](storage.md). Наполняет её -`dm_transform`; ритм и механика пересборки — ниже. Витрина, сохраняющая зерно -источника — переименование, обогащение строки, — остаётся обычным -представлением: копию событий ради других имён колонок не держит ни один -боевой склад. +`dm_transform`; ритм и механика пересборки — ниже. Так менти учится пересобирать +агрегат конвейером. Витрина, сохраняющая зерно источника — переименование, +обогащение строки, — остаётся обычным представлением и не копирует события. -Правило выбрано учебной целью, а не ценой запроса. На объёмах стенда +Цена запроса здесь не определяет форму. На объёмах стенда представлениями обошлось бы всё: условия сквозь цепочку представлений проходят ([исследование](../research/2026-08-22-view-predicate-pushdown.md)). -Но пересборка агрегатов конвейером — производственный паттерн, ради -которого стенд и строится, а пара «таблица рядом с представлением» -показывает: форма — решение по роли витрины, у одного слоя законны обе. +Пара «таблица рядом с представлением» показывает, что форма зависит от роли +витрины: в одном слое уместны обе формы. ## Кто строит: стенд и менти @@ -47,8 +46,8 @@ Дашборд этапа 8 стоит только на витринах стенда: приёмка этапа не зависит от выполненных домашек. Свой дашборд по витринам менти — -[необязательная лаба](../labs/superset-dashboard.md) после этапа 8. Устройство -стендового дашборда — в [доке зоны Superset](superset.md). +[необязательная лаба](../labs/optional/superset-dashboard.md), доступная после +ступени 2. Устройство стендового дашборда — в [доке зоны Superset](superset.md). ## Ритм пересборки diff --git a/docs/labs/README.md b/docs/labs/README.md index 46e2315..822128b 100644 --- a/docs/labs/README.md +++ b/docs/labs/README.md @@ -122,8 +122,9 @@ DM](../architecture/dm.md). ### Superset и BI -Открывается после ступени 2. [Свой дашборд в Superset](superset-dashboard.md): -свои объекты BI живут отдельно от стендовых. +Открывается после ступени 2. +[Свой дашборд в Superset](optional/superset-dashboard.md): свои объекты BI живут +отдельно от стендовых. ### Инженерия стенда diff --git a/docs/labs/superset-dashboard.md b/docs/labs/optional/superset-dashboard.md similarity index 99% rename from docs/labs/superset-dashboard.md rename to docs/labs/optional/superset-dashboard.md index d3081f4..c488cbb 100644 --- a/docs/labs/superset-dashboard.md +++ b/docs/labs/optional/superset-dashboard.md @@ -23,7 +23,7 @@ Не добавляйте графики в стендовый дашборд и не правьте его датасеты. При инициализации Superset импорт с `--overwrite` заменит ручные правки стендовых объектов файлами из репозитория. `make up` свой дашборд не стирает; срок жизни -таких объектов описан в [доке Superset](../architecture/superset.md), «Импорт +таких объектов описан в [доке Superset](../../architecture/superset.md), «Импорт при каждой инициализации». Заведите отдельные датасеты и графики, соберите из них свой дашборд. diff --git a/docs/research/2026-08-31-labs-inventory.md b/docs/research/2026-08-31-labs-inventory.md index e4bce60..2204dbb 100644 --- a/docs/research/2026-08-31-labs-inventory.md +++ b/docs/research/2026-08-31-labs-inventory.md @@ -116,7 +116,7 @@ **17. Свой дашборд в Superset (готовая необязательная лаба).** Урок: пользовательские объекты BI хранятся отдельно от стендовых и переживают перезапуск. Стендовые объекты при импорте перезаписываются. -Материал: `docs/labs/superset-dashboard.md`, `docs/architecture/superset.md`. +Материал: `docs/labs/optional/superset-dashboard.md`, `docs/architecture/superset.md`.\ Форма: построить свое. Проверка: глазами — счетного инварианта у раскладки панелей нет. @@ -276,4 +276,4 @@ STG и прием событий нельзя отдавать в форме «удали и перепиши»: код там служит несущей частью стенда. Для этих участков подходят расследования и форма «собери рядом». -У всех счетных проверок остается общая дыра — раскладка по шардам. Поэтому пересчет ключа по `hostName()` должен входить в ТЗ каждого вычитания отдельной строкой. \ No newline at end of file +У всех счетных проверок остается общая дыра — раскладка по шардам. Поэтому пересчет ключа по `hostName()` должен входить в ТЗ каждого вычитания отдельной строкой. diff --git a/docs/specs/2026-09-01-labs-program.md b/docs/specs/2026-09-01-labs-program.md index a0380b8..424b87d 100644 --- a/docs/specs/2026-09-01-labs-program.md +++ b/docs/specs/2026-09-01-labs-program.md @@ -172,7 +172,7 @@ Открывается после ступени 2 основной программы. - **Свой дашборд.** Готовая лаба - [`docs/labs/superset-dashboard.md`](../labs/superset-dashboard.md) учит + [`docs/labs/optional/superset-dashboard.md`](../labs/optional/superset-dashboard.md) учит хранить пользовательские объекты отдельно от стендовых. - **Почему дашборд не видит объект на второй ноде.** Забытый `ON CLUSTER` может остаться незаметным до тех пор, пока дашборд не обратится ко второй ноде.