clickstream-data-platform/docs/architecture/dm.md

Слой DM: витрины

Как модель DDS превращается в витрины для потребителя BI: какую форму принимает витрина, кто какие витрины строит и как слой проверяется. Состав колонок каждой витрины задаёт раздел 7 мастер-спеки; здесь — форма, наполнение и контроль.

Форма: по зерну, не по цене запроса

Витрина, меняющая зерно источника — дневной агрегат, сверка по заказам, — материализуется: dm.<имя>_rep / _dist и публичное dm.<имя>_v с явным списком колонок, по общим конвенциям хранилища. Наполняет её dm_transform заменой дневных партиций — той же механикой, что у сущностей DDS (конвейер); объём пересборки — ниже. Витрина, сохраняющая зерно источника — переименование, обогащение строки, — остаётся обычным представлением: копию событий ради других имён колонок не держит ни один боевой склад.

Правило выбрано учебной целью, а не ценой запроса. На объёмах стенда представлениями обошлось бы всё: условия сквозь цепочку представлений проходят (исследование). Но агрегат, пересобираемый партициями, — производственный паттерн, ради которого стенд и строится, а пара «таблица рядом с представлением» показывает: форма — решение по роли витрины, у одного слоя законны обе.

Кто строит: стенд и менти

Стенд привозит готовыми витрины трёх сюжетов дашборда этапа 8 и инфраструктуру контроля:

• revenue_daily — выручка по дням и категориям; образец материализованной витрины, на него ссылаются учебные задания;
• purchase_vs_orders — сверка A+C с классами расхождений; зерно — заказ, шардирование сохраняет ко-локацию заказов по cityHash64(order_id);
• daily_traffic — пара «посетители» / «известные пользователи», локальное обогащение картой идентичностей;
• dq_summary — сводка проверок качества (ниже).

Остальные витрины спеки — учебные задания: менти строит их сам по ТЗ с образцом. Разминка — представление events_enriched_v (зерно события), затем агрегаты top_pages_daily, session_overview и dq_errors_daily, последней — самая содержательная utm_effectiveness с уроком declared_*. Построенная витрина встаёт в конвейер руками менти: финальный пункт каждого ТЗ — добавить задачу своей витрины в dm_transform. До этого конвейер о ней не знает и остаётся зелёным, после — витрина пересобирается наравне со стендовыми.

Дашборд этапа 8 стоит только на витринах стенда: приёмка этапа не зависит от выполненных домашек. Расширение дашборда визуализациями по своим витринам — отдельная домашка после этапа 8.

Объём пересборки

Все материализованные витрины пересобираются одним окном — дышащим окном K от позиции мира, тем же, что у заказов. Витринам от заказов окна хватает по построению: день за окном закрыт, его классы и суммы не меняются. Витринам от событий и сессий окно даже избыточно — их дни замерзают сразу.

Одно следствие названо явно. daily_traffic обогащается картой идентичностей, а карта пересчитывается целиком, и склейка ретроспективна: покупка сегодня делает куку «известной» во всех прошлых днях карты. Дни за окном K в витрину эту новость уже не получат — они хранят число известных на момент закрытия окна. Это решение, а не недосмотр: живое окно показывает текущую склейку, замороженные дни — какой она была тогда, и расхождение между витриной и картой само по себе урок ретроспективности (историю склейки стенд сознательно не хранит — issue #145).

dm.dq_summary

Зерно — «день данных × проверка»: строка отвечает, каково качество дня сейчас, а не сколько раз его проверяли, — история прогонов и так живёт в Airflow. Партиция — день данных; прогон звена DQ заменяет партиции проверенных дней через REPLACE PARTITION. Обещанный спекой перевод с TRUNCATE+INSERT выполняется той же механикой замены, что и у витрин, — ничего отдельного учить не надо.

Звено DQ конвейера

Встаёт в etl_pipeline после DM (конвейер) и проверяет только объекты стенда:

• счётная сверка сессий с эталоном VisitID — кука × день, эталон читается из ods.event_v (модель сессии);
• счётчики классов расхождений против описи мира — по дням с закрытым окном;
• счётные сверки витрин стенда с их DDS-источниками.

Результаты ложатся в dm.dq_summary. Звено — не только сторож конвейера, но и экспонат: менти видит, как контроль качества устроен в бою — по расписанию, с историей, рядом с трансформациями.

Даг самопроверки

Домашки контролирует отдельный даг без расписания: менти запускает его рукой. Задача витрины красная, пока витрины нет или счёт не сходится, и зелёная, когда построено верно; сообщение об ошибке говорит, что не так и куда смотреть. Проверки — инварианты против DDS-источников, золотые константы не прибиваются. В dq_summary даг не пишет: он инструмент лабы, а не история качества конвейера.

Приём проверен на соседнем учебном стенде Airflow + Greenplum: валидационный даг с группами проверок по слоям давал менти обратную связь по каждому шагу домашки, не трогая рабочий конвейер.

Остаётся нарезке

• Имена задач dm_transform, звена DQ и дага самопроверки.
• Ключи шардирования остальных материализованных витрин — вместе с их DDL; правило партиции-донора — в доке хранилища.
• Тексты учебных заданий и точный список проверок обоих контуров.
• Механика сверки A+C в SQL — рамка в спеке, разделы 4 и 7.

Отклонённые варианты

• Весь слой представлениями. Дёшево и всегда свежо, но главный производственный паттерн слоя — пересборка агрегатов — остался бы невидим, а dm_transform — без работы.
• Материализовать всё. Копия событий ради переименования колонок — антипаттерн, который менти увёз бы в бой.
• Гибрид по цене запроса. Выбор формы по стоимости, которой на объёмах стенда нет: сторож без настоящей опасности.
• Проверки домашек в конвейерном звене DQ. Конвейер стоял бы красным до выполнения лаб, а проверка, которая всегда красная, приучает себя игнорировать.
• «Жёлтый» статус недостроенной витрины. У задачи Airflow нет такого состояния; изображать его логами — семантика, которую пришлось бы расшифровывать. Красное «ещё не построено» честнее.
• Самопроверка пишет в dq_summary. Попытки менти смешались бы с историей качества конвейера.
• Superset поверх DDS без слоя DM. Терялся бы урок «витрина — контракт под потребителя», против раздела 7 спеки.

Связанные решения

• Мастер-спека, разделы 4 и 7, — состав колонок витрин и классы сверки.
• Дневной конвейер — запуск dm_transform, объём прогона, замена партиций на кластере.
• Дока хранилища — имена объектов, граница доступа через _v, партиция-донор.
• Карта модели DDS — источники витрин.
• Резолюция — тикет #135 карты #127.