Merge pull request 'docs(labs): ТЗ необязательной лабы «свой дашборд в Superset»' (#199) from 197-superset-lab into main

Reviewed-on: #199

AGENTS.md

@@ -160,7 +160,7 @@ Airflow) и названия из кода. Если для понятия ес
 - Имена файлов в `docs/labs/` — слаг строчными латинскими буквами через дефис
   (`top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ учебных
   заданий. Ни даты, ни номера: задание — не событие истории, а живой документ,
-  и правится он вместе с тем, о чем говорит. Слаг называет витрину задания.
+  и правится он вместе с тем, о чем говорит. Слаг называет предмет задания.
 - Имена файлов в `docs/adr/` — `NNNN-краткое-имя.md`: сквозной номер из четырёх
   цифр и слаг (`0001-stand-services.md`). Решения нумеруются подряд, дата
   в имени не нужна.

docs/architecture/dm.md

@@ -46,9 +46,9 @@
 пересобирать нечего. Тексты заданий — в [`docs/labs/`](../labs/README.md).
 
 Дашборд этапа 8 стоит только на витринах стенда: приёмка этапа не зависит
-от выполненных домашек. Расширение дашборда визуализациями по своим
-витринам — отдельная домашка после этапа 8. Устройство самого дашборда — в
-[доке зоны Superset](superset.md).
+от выполненных домашек. Свой дашборд по витринам менти —
+[необязательная лаба](../labs/superset-dashboard.md) после этапа 8. Устройство
+стендового дашборда — в [доке зоны Superset](superset.md).
 
 ## Ритм пересборки
 
@@ -215,7 +215,8 @@ business_key`.
 ## Даг самопроверки
 
 Домашки контролирует `homework_check` — отдельный даг без расписания: менти
-запускает его рукой. По задаче на каждое из пяти [заданий](../labs/README.md).
+запускает его рукой. По задаче на каждое из
+[пяти заданий по витринам](../labs/README.md).
 Задача красная, пока витрины нет или счёт не сходится, и зелёная, когда
 построено верно; сообщение об ошибке говорит, что не так и куда смотреть. Проверки — инварианты против источников витрины,
 золотые константы не прибиваются. В `dq_summary` даг не пишет: он инструмент

docs/architecture/superset.md

@@ -78,6 +78,12 @@ superset import-directory /app/import --overwrite
 лежит в git. Пробовать интерфейс менти никто не мешает — но все, что должно
 пережить перезапуск, приезжает файлом.
 
+Это правило относится только к стендовым объектам. Свои датасеты, графики и
+дашборды менти живут в той же базе метаданных Superset, а импорт трогает
+только объекты с известными ему uuid. Поэтому свои объекты переживают
+`make up` и `make rebuild-storage`. Их стирает только `make clean` или
+адресный сброс базы метаданных по рецепту ниже.
+
 ## Как снять свежий экспорт
 
 Маршрут один: правишь на живом стенде, забираешь экспорт, кладешь дерево в git.

docs/labs/README.md

@@ -1,9 +1,13 @@
-# Учебные задания: витрины слоя DM
+# Учебные задания: витрины слоя DM и дашборд в Superset
 
-Пять домашек. Стенд привозит слой DM наполовину: витрины трех сюжетов
-дашборда и контроль качества построены, остальные витрины строит менти.
-Каждое задание — самостоятельное ТЗ: что за витрина, какое у нее зерно,
-из чего она собирается и как проверить, что собралась верно.
+Пять домашних заданий — про витрины слоя DM. Стенд привозит слой
+наполовину: витрины трех сюжетов дашборда и контроль качества построены,
+остальные витрины строит менти. Каждое из них — самостоятельное ТЗ: что за
+витрина, какое у нее зерно, из чего она собирается и как проверить, что
+собралась верно.
+
+Шестое задание — необязательная лаба в Superset. В ней менти собирает свой
+дашборд поверх пяти витрин.
 
 Общее устройство слоя — [дока DM](../architecture/dm.md). Она отвечает на
 вопросы «почему так», задание отвечает на вопрос «что сделать».
@@ -13,18 +17,19 @@
 Задания идут по нарастанию: каждое следующее опирается на то, что уже
 усвоено.
 
-| № | Витрина | Чему учит |
+| № | Результат | Чему учит |
 |---|---|---|
 | 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_` в имени — предупреждение, а не украшение |
+| 6 | [Свой дашборд в Superset](superset-dashboard.md) — необязательная лаба | свои объекты BI живут отдельно от стендовых |
 
 ## Общие правила
 
-Они одни на все пять заданий, поэтому записаны здесь, а не повторяются в
-каждом ТЗ.
+Они одни для пяти заданий по витринам, поэтому записаны здесь, а не
+повторяются в каждом ТЗ.
 
 **Читать — через `_v`.** Публичный договор сущности DDS — представление с
 суффиксом `_v`: `dds.event_v`, `dds.session_v`. Витрина называет только
@@ -74,18 +79,18 @@ DDS, и задания остаются независимыми. Исключе
 собрано верно. В сводку качества конвейера `dm.dq_summary` он не пишет:
 это инструмент лабы, а не история качества стенда.
 
-Проверка у всех заданий устроена одинаково и золотых констант не содержит:
-рядом с витриной независимым запросом собирается тот же ответ — прямо из
-источника витрины, минуя ее саму. У четырех заданий источник эталона тот
-же, что у витрины, `dds.session_v` или `dds.event_v`; у задания 4 это
-таблицы брака ODS, потому что в DDS у брака представительства нет. Обе
-стороны соединяются по деловому ключу через `FULL OUTER JOIN`, и считается
-число строк, где стороны разошлись или одной стороны нет. Ноль — зеленый.
+Проверка пяти заданий по витринам устроена одинаково и золотых констант не
+содержит: рядом с витриной независимым запросом собирается тот же ответ —
+прямо из источника витрины, минуя ее саму. У четырех заданий источник эталона
+тот же, что у витрины, `dds.session_v` или `dds.event_v`; у задания 4 это
+таблицы брака ODS, потому что в DDS у брака представительства нет. Обе стороны
+соединяются по деловому ключу через `FULL OUTER JOIN`, и считается число строк,
+где стороны разошлись или одной стороны нет. Ноль — зеленый.
 Полное соединение здесь обязательно: при обычном пропавший день или
 пропавший ключ просто не попал бы в результат и остался бы незамечен.
 
-Раздел «Как проверить себя» каждого ТЗ называет деловой ключ и сравниваемые
-величины. Тот же прием в стендовом исполнении — [даг
+Раздел «Как проверить себя» каждого ТЗ по витрине называет деловой ключ и
+сравниваемые величины. Тот же прием в стендовом исполнении — [даг
 `dq_check`](../../dags/dq_check.py) и запросы в [`sql/dq/`](../../sql/dq).
 
 **Предупреждение.** Запросы самой проверки лежат в `sql/dq/` открыто, и

docs/labs/superset-dashboard.md

@@ -0,0 +1,87 @@
+# Задание 6 (необязательное): свой дашборд в Superset
+
+**Чему учит:** довести свои витрины до потребителя — завести в Superset
+датасеты поверх публичных представлений, подобрать графики под вопросы и
+собрать из них один связный экран.
+
+Эта лаба идет после заданий 1–5 и опирается на их результат. Ее можно
+пропустить: основной предмет стенда — ClickHouse, а здесь вся работа — в
+интерфейсе BI.
+
+## Роль дашборда
+
+Собери обзор трафика и поведения посетителей. Он должен отвечать на три
+вопроса: что происходило в магазине, какие страницы, устройства и рекламные
+каналы дали результат, были ли ошибки приема данных.
+
+Стендовый дашборд «Бизнес-сюжеты» собран из готовых витрин. Свой дашборд
+собери из пяти витрин, которые ты построил в заданиях. Копировать раскладку
+стендового дашборда не нужно: выбери форму, в которой ответы читаются без
+пояснений рядом с экраном.
+
+## Свои объекты — отдельно
+
+Не добавляй графики в стендовый дашборд и не правь его датасеты. При
+инициализации Superset импорт с `--overwrite` заменит ручные правки стендовых
+объектов файлами из репозитория. `make up` свой дашборд не стирает; срок жизни
+таких объектов описан в [доке Superset](../architecture/superset.md), «Импорт
+при каждой инициализации».
+
+Заведи отдельные датасеты и графики, собери из них свой дашборд. Назови его,
+например, «Мои витрины DM». Это то же правило, по которому DDL домашек лежит
+в `sql/ddl/70-labs.sql`: стенд привозит свои объекты, менти создает свои.
+
+## Датасеты
+
+Заведи в подключении `ClickHouse` пять физических датасетов схемы `dm`:
+
+- `events_enriched_v`;
+- `top_pages_daily_v`;
+- `session_overview_v`;
+- `dq_errors_daily_v`;
+- `utm_effectiveness_v`.
+
+## Состав дашборда
+
+Каждая из пяти витрин должна появиться хотя бы в одном графике. Точный тип
+графика выбери сам. На дашборде покажи следующее:
+
+| Витрина | Что показать |
+|---|---|
+| `events_enriched_v` | число событий по часу и типу события |
+| `top_pages_daily_v` | страницы с просмотрами, посетителями и добавлениями в корзину |
+| `session_overview_v` | сравнение устройств по визитам, отказам и визитам с покупкой |
+| `dq_errors_daily_v` | число ошибок по дню загрузки, источнику и классу |
+| `utm_effectiveness_v` | трафик, покупки и заявленную выручку по рекламным каналам |
+
+Для долей используй слагаемые из витрин. Например, доля отказов считается
+как сумма `bounce_sessions`, деленная на сумму `sessions`. Среднее по готовым
+долям для такого графика не подходит — урок задания 3 остается в силе.
+
+Названия графиков, осей и показателей должны объяснять экран без чтения SQL.
+
+## Как проверить себя
+
+Эта лаба проверяется глазами. У расположения панелей и понятных подписей нет
+счетного инварианта, поэтому задачи для нее в `homework_check` нет.
+
+Открой список дашбордов и проверь:
+
+- «Бизнес-сюжеты» остался отдельным стендовым дашбордом;
+- твой дашборд открывается без ошибок и содержит график от каждого из пяти
+  датасетов;
+- подписи, единицы измерения и легенды читаются без обращения к SQL;
+- прямой трафик не исчез из графика UTM, а заявленная выручка не выдана за
+  серверную;
+- пустой график ошибок нормален, если в таблицах брака сейчас нет строк.
+
+Последний проход сделай как читатель: найди на экране самый заметный канал,
+страницу и устройство, затем проверь, понятно ли из подписей, что именно
+сравнивается. Если ответ приходится угадывать, поправь график или его название.
+
+## Приемка
+
+- [ ] пять датасетов читают публичные представления витрин заданий 1–5;
+- [ ] создан отдельный дашборд, стендовые объекты не изменены;
+- [ ] каждая витрина представлена хотя бы одним графиком;
+- [ ] дашборд проверен глазами по разделу выше.

docs/specs/2026-07-30-stand-v2-realism.md

@@ -660,7 +660,10 @@ ADR 0002 с приёмочными совпадают почти целиком.
   работой после этой спеки; редизайн лаб v1 (#7) остаётся в v1 и сюда не
   переносится. Исключение — домашки слоя DM: ТЗ витрин менти и даг
   самопроверки забраны в этап 4 резолюцией #135, потому что витрина менти и
-  конвейер, в который она встает, проектируются вместе. Единый стиль блока
+  конвейер, в который она встает, проектируются вместе. Сюда же —
+  необязательная лаба «свой дашборд в Superset» (#197): она стоит на
+  витринах домашек DM и продумана до готового ТЗ в этапе 8, тогда как
+  остальные лабы пока на уровне идей. Единый стиль блока
   домашек — за работой учебного пути. Спека даёт будущим лабам только
   опорные точки — контрольные числа описи (сверка, идентичность). Явное
   следствие: после этапа 9 стенд работает, но учебного пути на нём ещё нет.