docs(warehouse): упрощены объяснения витрин, сессий и пересчета

Зачем: читателю ступеней 1–4 нужно проследить выбор дней, расчет строки
и публикацию результата без расшифровки метафор.

Что: согласованы справочники DM, сессий, ETL и два раздела хранилища
с комментариями шести SQL-примеров. Уточнены ограничения повторного
запуска и выбора атрибутов при равном времени событий.

Проверка: make lint, git diff --check, локальные Markdown-ссылки и якоря.
SQL без комментариев совпадает; AST Python без строк документации совпадает.
Исторические разделы и материалы вне границ задачи сохранены.

Refs: #249

docs/architecture/dm.md

@@ -1,87 +1,83 @@
 # Слой DM: витрины
 
-Как модель DDS превращается в витрины для потребителя BI: какую форму
-принимает витрина, кто какие витрины строит и как слой проверяется. Состав
-колонок каждой витрины задаёт раздел 7 мастер-спеки; здесь — форма,
-наполнение и контроль.
+Витрины готовят данные DDS для отчетов и дашбордов. Здесь описаны форма
+хранения, правила обновления и проверки. Состав колонок задан в
+[спецификации](../specs/2026-07-30-stand-v2-realism.md#витрины-dm)
+и [учебных заданиях](../labs/README.md).
 
 ## Таблица или представление
 
-Дневной агрегат и сверка по заказам меняют зерно источника. На этом стенде такие
-результаты хранятся в `dm.<имя>_rep` / `_dist` и читаются через публичное
-представление `dm.<имя>_v` с явным списком колонок. Имена и устройство объектов
-следуют общим [конвенциям хранилища](storage.md). Таблицы наполняет
-`dm_transform`; ритм и механика пересборки описаны ниже. В задании этот путь
-приходится пройти целиком: рассчитать агрегат, загрузить его и включить
-обновление в конвейер.
+Зерно — то, чему соответствует одна строка. Например, в заказах это заказ,
+а в дневной выручке — день и категория товара. На стенде результат
+с новым зерном хранится в таблице: отчет читает готовые итоги без
+повторного расчета. Таблицу наполняет `dm_transform`.
 
-Переименование колонок и обогащение строки зерно не меняют. Такие витрины на
-стенде остаются обычными представлениями и не хранят вторую копию событий.
+У такой витрины есть локальная `_rep`, распределенная `_dist` и публичное
+представление `_v` с явным списком колонок. Для замены дневных партиций
+служат еще две таблицы: `_stage_rep` и `_stage_dist`. Это донор — место
+сборки результата перед публикацией. Подробности — в
+[справочнике хранилища](storage.md#имена-объектов).
 
-На объёмах стенда все витрины могли бы остаться представлениями: условия
-проходят сквозь их цепочку
+Если запрос только переименовывает или дополняет поля и сохраняет одну
+строку на событие, достаточно обычного представления. Оно выполняет
+запрос при чтении, не хранит вторую копию событий и не требует пересборки.
+
+На небольших данных стенда и агрегаты могли бы вычисляться при чтении
 ([исследование](../research/2026-08-22-view-predicate-pushdown.md)).
-Мы все равно оставили материализованные агрегаты ради практики: без них в
-программе не было бы загрузки и пересборки витрин. Представления дают другой
-случай: преобразование строк на прежнем зерне.
+Готовые таблицы нужны в программе для практики загрузки, обновления
+и включения витрин в конвейер.
 
 ## Что готово в стенде, а что остаётся заданием
 
-Стенд привозит готовыми витрины трёх сюжетов дашборда этапа 8 и
-инфраструктуру контроля:
+Готовы три витрины дашборда и сводка качества:
 
-- `revenue_daily` — выручка по дням и категориям; образец материализованной
-  витрины, на него ссылаются учебные задания;
-- `purchase_vs_orders` — сверка A+C с классами расхождений; зерно — заказ,
-  шардирование сохраняет ко-локацию заказов по `cityHash64(order_id)`;
-- `daily_traffic` — пара «посетители» / «известные пользователи», обогащение
-  [картой идентичностей](dds/identity.md);
-- `dq_summary` — сводка проверок качества (ниже).
+- `revenue_daily` — одна строка на день заказа и категорию товара;
+  образец дневной пересборки для учебных заданий.
+- `purchase_vs_orders` — одна строка на заказ: сопоставление покупки
+  из кликстрима с заказом магазина и класс расхождения.
+- `daily_traffic` — одна строка на день: число посетителей и известных
+  пользователей с учетом [карты идентичностей](dds/identity.md).
+- `dq_summary` — одна строка на день данных и проверку качества.
 
-Остальные витрины спеки нужно построить в учебных заданиях по готовому ТЗ и
-образцу. Разминка — представление `events_enriched_v` (зерно события), затем
-агрегаты `top_pages_daily`, `session_overview` и `dq_errors_daily`, последней —
-самая содержательная `utm_effectiveness` с уроком `declared_*`. В финале
-каждого задания с агрегатом его задачу нужно добавить в `dm_transform`. До
-этого конвейер о витрине не знает, после — пересобирает её вместе со
-стендовыми. Представление из разминки добавлять некуда: его не нужно
-пересобирать. Тексты заданий лежат в [`docs/labs/`](../labs/README.md).
+В [заданиях ступени 1](../labs/README.md) вы строите `events_enriched_v`,
+`top_pages_daily`, `session_overview`, `dq_errors_daily` и `utm_effectiveness`.
+Для каждой физической витрины нужно добавить сборку в `dm_transform`.
+Представление `events_enriched_v` отдельной задачи не требует.
 
-Дашборд этапа 8 читает только готовые витрины стенда, поэтому его приёмка не
-зависит от домашних заданий. Отдельный дашборд по учебным витринам можно
-собрать в [факультативном задании](../labs/optional/superset-dashboard.md),
-доступном после ступени 2. Устройство стендового дашборда описано в
-[справочнике Superset](superset.md).
+Стендовый дашборд читает готовые витрины и работает до выполнения заданий.
+Дашборд по своим витринам можно собрать в
+[факультативе](../labs/optional/superset-dashboard.md) после ступени 2.
+Устройство стендового дашборда — в [справочнике Superset](superset.md).
 
 ## Ритм пересборки
 
-День витрины пересобирается, пока может измениться его источник, —
-поэтому ритмов три, по числу источников:
+Дни для пересчета выбирают по тому, как меняется источник:
 
-- **от событий и сессий** — день замерзает сразу; пересборка догоняет
-  хвост несобранных дней заменой дневных партиций;
-- **от заказов** — день дышит, пока входит в последний слепок; пересборка
-  заменяет партиции этого отрезка, дни за ним закрыты по построению;
-- **от карты идентичностей** — не замерзает никогда: склейка
-  ретроспективна, покупка сегодня делает куку известной во всех её прошлых
-  днях, а карта пересчитывается целиком.
+- События и сессии прожитого дня на стенде больше не меняются. Витрины
+  по ним собирают диапазон от первого пропущенного дня до последнего
+  прожитого и заменяют дневные партиции.
+- Заказы могут меняться в течение семи модельных дней. Последний слепок ODS
+  задает диапазон дат для пересборки; пропущенные дни могут расширить его.
+- Новые связи карты идентичностей меняют трактовку прошлых визитов:
+  сегодняшняя покупка позволяет узнать пользователя и в ранних днях.
+  Поэтому `daily_traffic`, как и карта, пересчитывается целиком.
 
-Поэтому `daily_traffic` наследует у своего источника и ритм, и механику:
-полный пересчёт всех дней каждый прогон в `ReplacingMergeTree(_load_ts)`,
-как у самой карты. Дневных партиций у неё нет: партиция — единица замены,
-а эта витрина заменяется только целиком. На стенде такая работа остается
-быстрой; витрина читает сессии и карту через их публичные договоры.
-Пересчитывать точечно только затронутые дни не из чего: для этого надо
-знать, какие связки новые, а полный пересчёт карты этот след затирает —
-восстановление следа оставлено лабе повышенной сложности (issue #149).
+`daily_traffic` каждый раз добавляет всю историю новой версией
+в `ReplacingMergeTree(_load_ts)`. Дневных партиций у нее нет, а текущие
+строки выбирает представление через `FINAL`.
 
-У `purchase_vs_orders` два источника и одна непрерывная пересборка. Заказная
-сторона задает изменяемое окно последним принятым слепком ODS, событийная —
-последний прожитый день с `purchase`. Левая граница возвращает первую дыру и
-самый ранний день с `awaiting_order`: предварительная строка уже есть в
-витрине, поэтому поиск отсутствующего дня ее не заметит. Правая граница
-доходит до более позднего из двух хвостов. Так один прогон догоняет пакетный
-разгон длиннее K и не оставляет старое ожидание замороженным.
+У `purchase_vs_orders` два источника. Левая граница — самая ранняя
+из трех дат: начало окна последнего слепка, первый пропущенный день
+и первый день с `awaiting_order`. Последний нужен потому, что строка
+ожидания уже есть в витрине и поиском пропусков не обнаружится.
+Правая граница — более поздняя из конца окна заказов и последнего
+прожитого дня с покупкой. Один запуск пересобирает весь отрезок,
+даже если с предыдущего запуска прошло больше семи модельных дней.
+
+Для учебной сводки брака действует отдельное правило: дни выбираются
+по времени загрузки, а прежние итоги сохраняются после удаления
+источника по TTL. Оно разобрано в
+[задании `dq_errors_daily`](../labs/1-4-dq-errors-daily.md).
 
 ## Витрины стенда
 
@@ -91,34 +87,49 @@
 
 ### `dm.revenue_daily_v`
 
-Зерно: день заказа × категория товара. Витрина читает только оплаченные
+Одна строка — день заказа и категория товара. Витрина читает только оплаченные
 заказы из `dds.order_v`, синхронно разворачивает три массива позиций и узнает
 категорию артикула через `dic.products`. Один заказ с несколькими позициями
 категории считается в `orders` один раз. `units` складывает количество единиц,
-`revenue` складывает цену позиции × количество. Скидка, доставка и итог заказа
-между категориями не делятся. `aov` равен `revenue / orders` в том же срезе и
+`revenue` складывает цену позиции × количество. Скидка и доставка
+в выручку не входят; итог заказа между категориями не делится. `aov` равен `revenue / orders` в том же срезе и
 хранит два знака после запятой.
 
 Первый запуск строит всю доступную историю. Следующие берут границы дней из
 последнего слепка ODS: только источник знает, какие даты еще может изменить.
-Пропущенный оплаченный день расширяет левую границу, чтобы частичный отказ
-не оставил дыру после следующего прогона. Агрегат при этом читает DDS; ODS
-отвечает только на вопрос об объеме.
+Если в DDS есть оплаченные заказы за день, отсутствующий в витрине,
+левая граница расширяется до него. Агрегат читает DDS; ODS отвечает
+только на вопрос об объеме.
 
-`dm.revenue_daily_rep` нарезана по `report_date`; день собирается в
-таблице-доноре и заменяется через `REPLACE PARTITION`. Цель и донор шардируются
+В группе `revenue_daily` дага `dm_transform` три шага:
+
+1. [`revenue_daily_scope.sql`](../../sql/dm/revenue_daily_scope.sql)
+   возвращает `first_day` и `last_day`. Без заказов в ODS или DDS
+   запрос не возвращает строк, и задача завершается ошибкой.
+2. [`revenue_daily_rebuild.sql`](../../sql/dm/revenue_daily_rebuild.sql)
+   очищает донор и одной вставкой собирает весь диапазон в
+   `dm.revenue_daily_stage_dist`. Вставка ждет доставки на шарды.
+3. [`revenue_daily_replace.sql`](../../sql/dm/revenue_daily_replace.sql)
+   заменяет в `dm.revenue_daily_rep` каждую дневную партицию `report_date`
+   готовой партицией `dm.revenue_daily_stage_rep`.
+
+Повтор замены не добавляет копий строк. Ограничения при частичном отказе
+описаны в [конвейере](etl.md#идемпотентность).
+
+Цель и донор шардируются
 по `cityHash64(product_category)`. Кроме дня, у витрины только категория, а
 шесть категорий стартового мира близки по объему. Более сложный составной ключ
 распределил бы эту маленькую таблицу без нового урока.
 
 ### `dm.purchase_vs_orders_v`
 
-Зерно — заказ. Покупки из `dds.event_v` сначала сворачиваются по
+Одна строка — один заказ. Покупки из `dds.event_v` сначала сворачиваются по
 `purchase_id[1]`: контракт источника обещает один номер и одну объявленную
-сумму, а отдельный счет событий оставляет класс `duplicate_event`
-наблюдаемым. Заказы приходят из `dds.order_v`. Обе стороны записаны
-подзапросами, затем соединены `FULL OUTER GLOBAL JOIN`: голая левая
-Distributed-таблица вернула бы каждый непарный заказ по разу с каждого шарда
+сумму. Отдельный счет событий позволяет обнаружить повтор покупки
+и присвоить класс `duplicate_event`. Заказы приходят из `dds.order_v`. Обе стороны записаны
+подзапросами, затем соединены `FULL OUTER GLOBAL JOIN`: левая
+Distributed-таблица без подзапроса вернула бы каждый непарный заказ
+по разу с каждого шарда
 ([исследование](../research/2026-08-22-distributed-join.md)).
 
 Непарная сторона остается `NULL` благодаря `join_use_nulls = 1`. При
@@ -129,10 +140,10 @@ Distributed-таблица вернула бы каждый непарный з
 `duplicate_event`, `amount_delta`, `match`. Поэтому отмененный заказ без
 события остается отмененным, а не потерянным.
 
-Витрина нарезана по `order_day`, цель и донор шардируются по
+Партиции витрины разделены по `order_day`, цель и донор шардируются по
 `cityHash64(order_id)`. Диапазон собирается в доноре одной вставкой и
 заменяется по дням. Первичная сборка охватывает всю историю обоих источников;
-следующие прогоны идут по двустороннему ритму, описанному выше.
+следующие прогоны выбирают дни по правилам обоих источников, описанным выше.
 
 ### `dm.daily_traffic_v`
 
@@ -140,28 +151,26 @@ Distributed-таблица вернула бы каждый непарный з
 `dds.session_v`; `known_users` считает разные `user_id` после левого соединения
 с полной текущей `dds.identity_map_v`. Анонимная сессия остается в витрине.
 Несколько кук одного человека увеличивают `visitors`, но дают одного
-`known_user`, поэтому `known_users <= visitors`.
+известного пользователя, поэтому `known_users <= visitors`.
 
-Сессии и карта лежат по `client_id`, но публичные `_v` скрывают
-`Distributed`-таблицы от локальной подстановки. На ClickHouse 26.3
-`EXPLAIN PLAN` показал чтение обоих шардов на инициаторе: настройка
-`distributed_product_mode = 'local'` локального соединения не дала. Поэтому
-витрина использует явный `GLOBAL LEFT JOIN` через публичные договоры, а не
-подменяет их физическими таблицами. Это дороже по сети, зато граница слоев
-остается явной. Новая связь куки меняет прошлые дни, поэтому каждый запуск
-пишет полную историю новой версией в `ReplacingMergeTree(_load_ts)`, а
-публичное представление выбирает текущие строки через `FINAL`.
+Сессии и карта распределены по `client_id`. Однако на ClickHouse 26.3
+чтение через публичные `_v` с `distributed_product_mode = 'local'`
+не дало локального соединения. Поэтому в запросе явно указан
+`GLOBAL LEFT JOIN`. Он сохраняет сессии без известного пользователя;
+в `known_users` учитываются только ненулевые `user_id`.
+Обновление всей истории новой версией описано в разделе
+[«Ритм пересборки»](#ритм-пересборки).
 
 ## `dm.dq_summary`
 
-Зерно публичного `dm.dq_summary_v` — «день данных × атомарная проверка».
+Одна строка `dm.dq_summary_v` — день данных и одна проверка.
 Строка отвечает, каково качество дня сейчас; историю запусков хранит Airflow.
 Партиция совпадает с днём данных и заменяется через `REPLACE PARTITION`.
 
 Деловые колонки сводки:
 
 - `data_date` — проверяемый день;
-- `check_name` — устойчивое имя инварианта;
+- `check_name` — имя проверяемого правила;
 - `reference_rows` — число деловых ключей на эталонной стороне;
 - `actual_rows` — число деловых ключей в проверяемом объекте;
 - `failed_rows` — число отсутствующих или различающихся ключей;
@@ -173,7 +182,7 @@ Distributed-таблица вернула бы каждый непарный з
 ## Звено DQ конвейера
 
 Даг `dq_check` стоит в `etl_pipeline` после `dm_transform` и проверяет пять
-атомарных договоров:
+правил:
 
 - `sessions_vs_reference`: ключ — `client_id` внутри дня, эталон —
   `uniqExact(VisitID)` из `ods.event_v`, объект — число строк
@@ -197,9 +206,9 @@ Distributed-таблица вернула бы каждый непарный з
 скомпенсировать друг друга общим итогом: `failed_rows` считается после
 сопоставления деловых ключей.
 
-`classes_vs_inventory` — техническая растяжка пути от генератора до DM. Она
-подтверждает, что до витрины доехал записанный в паспорте мир, но не проверяет
-сам генератор: у настоящего магазина такого оракула нет.
+`classes_vs_inventory` сравнивает результат с паспортом мира. Это техническая
+проверка доставки и обработки эталонных данных стенда. Она не проверяет
+сам генератор; у настоящего магазина такого эталона нет.
 
 Четыре SQL-сверки считают дневные итоги в ClickHouse и возвращают Airflow только
 сводку и малый срез диагностики. Техническая сверка с паспортом читает небольшой
@@ -218,17 +227,20 @@ business_key`.
 
 ## Даг самопроверки
 
-Домашние задания проверяет `homework_check` — отдельный даг без расписания,
-который запускают вручную. В нём есть задача для каждого из
-[пяти заданий по витринам](../labs/README.md).
-Задача красная, пока витрины нет или счёт не сходится, и зелёная, когда
-построено верно; сообщение об ошибке говорит, что не так и куда смотреть. Проверки — инварианты против источников витрины,
-золотые константы не прибиваются. В `dq_summary` даг не пишет: он инструмент
-лабы, а не история качества конвейера.
+`homework_check` запускается вручную и содержит задачу для каждого из
+[пяти заданий по витринам](../labs/README.md). Если витрины нет или значения
+расходятся с источником, задача завершается ошибкой. Журнал показывает
+причину и примеры несовпадений. Успех означает, что проверяемые значения
+совпали; остальные требования задания вы проверяете сами.
 
-Приём проверен на соседнем учебном стенде Airflow + Greenplum:
-валидационный даг с группами проверок по слоям давал обратную связь по каждому
-шагу задания, не трогая рабочий конвейер.
+Ожидаемые значения рассчитываются по исходным данным текущего стенда.
+Для четырех заданий это события или сессии DDS, для сводки брака —
+таблицы ошибок ODS. Сравнение по деловому ключу учитывает отсутствующие
+строки с обеих сторон. Результаты не пишутся в `dq_summary`:
+самопроверка учебных витрин отделена от качества готового конвейера.
+
+Готовые SQL-проверки открывайте после собственного решения: они содержат
+расчет существенной части задания.
 
 ## Отклонённые варианты