diff --git a/AGENTS.md b/AGENTS.md index 092c2cb..4c75c4b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -160,7 +160,7 @@ Airflow) и названия из кода. Если для понятия ес - Имена файлов в `docs/labs/` — слаг строчными латинскими буквами через дефис (`top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ учебных заданий. Ни даты, ни номера: задание — не событие истории, а живой документ, - и правится он вместе с тем, о чем говорит. Слаг называет витрину задания. + и правится он вместе с тем, о чем говорит. Слаг называет предмет задания. - Имена файлов в `docs/adr/` — `NNNN-краткое-имя.md`: сквозной номер из четырёх цифр и слаг (`0001-stand-services.md`). Решения нумеруются подряд, дата в имени не нужна. diff --git a/docs/architecture/dm.md b/docs/architecture/dm.md index 3f9a9e2..f297591 100644 --- a/docs/architecture/dm.md +++ b/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` даг не пишет: он инструмент diff --git a/docs/architecture/superset.md b/docs/architecture/superset.md index b182e7d..7de6924 100644 --- a/docs/architecture/superset.md +++ b/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. diff --git a/docs/labs/README.md b/docs/labs/README.md index 363d09c..c607f8b 100644 --- a/docs/labs/README.md +++ b/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/` открыто, и diff --git a/docs/labs/superset-dashboard.md b/docs/labs/superset-dashboard.md new file mode 100644 index 0000000..47c36d0 --- /dev/null +++ b/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; +- [ ] создан отдельный дашборд, стендовые объекты не изменены; +- [ ] каждая витрина представлена хотя бы одним графиком; +- [ ] дашборд проверен глазами по разделу выше.