docs(handbook): написана глава «Хранилище и его слои»

- Зачем: - первая глава путеводителя: без нее читатель попадает из README сразу в справочники, минуя объяснение пути данных (тикет #218, карта #206). - Что: - добавлена docs/handbook/storage-layers.md: путь STG → ODS → DDS → DM, правило чтения через _v, зона dic, таблица ключей соединения слоев и два SELECT для самостоятельной пробы. - в docs/handbook/README.md раздел «Будущие главы» стал «Главы», аннотация первой главы ведет в ее файл. - Проверка: - обе команды из раздела «Проверка» тикета #218 дают пустой вывод; оба SELECT прогнаны на живом стенде от пользователя analyst. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-02 16:14:04 -04:00
100 changed files with 2857 additions and 8484 deletions
@@ -10,7 +10,6 @@ CLICKHOUSE_ETL_PASSWORD=etl-26-writer
 CLICKHOUSE_LIFECYCLE_PASSWORD=lifecycle-26-owner
 CLICKHOUSE_BI_PASSWORD=bi-26-reader
 CLICKHOUSE_ANALYST_PASSWORD=analyst-26-reader
 CLICKHOUSE_STUDENT_PASSWORD=student-26-lab
 CLICKHOUSE_GRAFANA_PASSWORD=grafana-26-reader
 KAFKA_EXTERNAL_PORT=29092
 PROMETHEUS_PORT=29090
@@ -8,26 +8,15 @@
 Стенд строится по спеке
 [«Боевой реализм стенда (v2)»](docs/specs/2026-07-30-stand-v2-realism.md).
-Стенд рассчитан на начинающих инженеров данных. Они недавно изучили ClickHouse,
+Отсюда вопрос к любой доработке — коду, проверке, документу: **чему на ней
-но почти не работали с ним руками. Здесь они разбирают и достраивают хранилище
+научится менти?** Ответ называется одной фразой до того, как писать. Не
 небольшого интернет-магазина: проходят путь от загрузки данных до витрин и BI.
 Программа дает практику общепринятых инженерных приемов. После нее участники
 должны уметь построить похожее хранилище без готового образца. Состав и порядок
 работы задает [программа учебных заданий](docs/specs/2026-09-01-labs-program.md).
 Стенд существует только ради обучения. Его поддержка имеет смысл, когда
 сохраняет возможность пройти программу или сама становится учебной задачей.
 Отдельной эксплуатационной ценности у стенда нет.
 Отсюда вопрос к любой доработке — коду, проверке, документу: **чему она
 учит?** Ответ называется одной фразой до того, как писать. Не
 складывается фраза — это вопрос владельцу, а не строчка кода: проверки в этом
 репозитории однажды уже переросли продукт.
 **Усложнение не бесплатно, и платит за него учебная ценность.** Чем сложнее
-стенд, тем хуже он как учебный материал: внимание читателя конечно, и каждая
+стенд, тем хуже он как учебный материал: внимание менти конечно, и каждая
 конструкция, которую он обязан расшифровать по дороге к уроку, списывается с
-этого счёта. Поэтому вопрос выше имеет вторую половину: **что читатель платит,
+этого счёта. Поэтому вопрос выше имеет вторую половину: **что менти платит,
 чтобы это прочесть, и что получает взамен?** Ответ «вопрос — и ничего»
 означает, что писать не нужно.
@@ -46,10 +35,15 @@
 ## Кому что поручать
-Автор задачи сам пишет и редактирует код, комментарии и документы, если
+Читатель здесь не побочный потребитель, а тот, ради кого стенд существует:
-владелец не задал другое распределение работы.
+код, комментарии и документы и есть продукт. Поэтому всё, что человек будет
 читать и разбирать, пишет модель с чувством меры — сейчас это Opus. Codex
 берёт техническую работу без вкусовых решений: миграции, разбор журналов и
 объёмного вывода, обход репозитория, повторяющиеся правки. Там его запас
 лимитов работает на нас, а экономить их на читаемом коде — экономия ложная:
 переписывать выйдет дороже, чем сразу написать хорошо.
-Делить работу стоит не целыми задачами, а подзадачами, и решать
+Делить работу между ними стоит не целыми задачами, а подзадачами, и решать
 это при планировании. Вкусовая часть идёт первой: она задаёт форму, имена и
 границы, под которые механическая потом подстраивается.
@@ -76,9 +70,6 @@ Airflow) и названия из кода. Если для понятия ес
 писал: простые слова, короткие фразы, сложную мысль поясняй при первом
 упоминании. Если понятность и буквальная точность спорят — выбирай понятность.
 При создании или редактировании лабораторных следуй
 [правилам учебного текста](docs/specs/2026-09-01-labs-program.md#как-писать-задания).
 Внутренние рассуждения и промежуточные пометки по ходу работы веди на
 английском — он экономнее по токенам. На русском остаётся всё, что видит и
 хранит проект: итоговые ответы, документы, комментарии в коде и SQL, сообщения
@@ -166,21 +157,14 @@ Airflow) и названия из кода. Если для понятия ес
  дефис (`clickstream-event.md`). Ни даты, ни номера: документ не событие
  истории, а текущее описание живого формата — и собирается из кода, а не
  пишется руками.
- Имена файлов основной программы в `docs/labs/` — `S-N-slug.md`:
+- Имена файлов в `docs/labs/` — слаг строчными латинскими буквами через дефис
-  номер ступени, номер задания внутри ступени и слаг строчными латинскими
+  (`top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ учебных
-  буквами через дефис (`1-2-top-pages-daily.md`). Здесь живут ТЗ
+  заданий. Ни даты, ни номера: задание — не событие истории, а живой документ,
-  учебных заданий. Номера повторяют порядок программы из `README.md`, чтобы
+  и правится он вместе с тем, о чем говорит. Слаг называет предмет задания.
  папка читалась как оглавление; даты нет: задание — живой документ и
  правится вместе с тем, о чем говорит. Слаг называет предмет задания.
  Факультативы живут в `docs/labs/optional/`, без номеров, под одним слагом
  (`superset-dashboard.md`). Общий индекс обеих частей — `docs/labs/README.md`;
  отдельного индекса в `optional/` нет.
 - Имена файлов в `docs/handbook/` — слаг строчными латинскими буквами через
  дефис, индекс папки — `README.md`. Здесь живет путеводитель по стенду:
-  учебные главы для читателя. Ни дат, ни номеров: глава — живой документ и
+  учебные главы для менти. Ни дат, ни номеров: глава — живой документ и
-  правится вместе с тем, что описывает. Исходники интерактивной карты лежат
+  правится вместе с тем, что описывает.
  подпапкой `architecture-map/`, а ее рендер — файлом `architecture-map.html`
  рядом с главами.
 - Имена файлов в `docs/adr/` — `NNNN-краткое-имя.md`: сквозной номер из четырёх
  цифр и слаг (`0001-stand-services.md`). Решения нумеруются подряд, дата
  в имени не нужна.
@@ -1,7 +1 @@
-@AGENTS.md
+@AGENTS.md
 # Читабельность языка
 Пиши легко для чтения. Сокращай количество мыслей, а не количество слов, которыми выражена каждая мысль.
 Please remove all mannered prose.
@@ -1,275 +1,229 @@
 # Кликстрим-платформа (стенд v2)
-Словарь понятий, которые встречаются в учебных заданиях, документации и коде
+Словарь понятий проекта: одни и те же слова для одних и тех же вещей —
-стенда.
+у владельца, кода, документов и агентов. Только язык, никаких решений.
 ## Язык
 - [Люди и события](#люди-и-события)
 - [Хранилище и форматы данных](#хранилище-и-форматы-данных)
 - [Заказы](#заказы)
 - [Модельное время и запуск стенда](#модельное-время-и-запуск-стенда)
 - [Устройство генератора](#устройство-генератора) — для чтения его кода
  и технических справочников.
 ### Люди и события
 **Человек**:
 Участник модели магазина, который может заходить с одного или двух
 устройств. Генератор знает, какие идентификаторы посетителя ему принадлежат,
 но в событиях сайта этой связи нет.
 **Посетитель**:
 Браузер на устройстве, который счетчик сайта узнает по куке — сохраненному
 в браузере идентификатору. В кликстриме он обозначается `ClientID`:
 `uniq(ClientID)` считает посетителей, и у одного человека их может быть несколько.
 _Избегать_: «посетитель» про человека после объединения его идентификаторов.
 **Пользователь магазина**:
 Человек, известный серверной части магазина под идентификатором `user_id`.
 Он указан в заказах и позволяет связать разные `ClientID` одного человека;
 в кликстриме поля `user_id` нет. Например, покупки с телефона и ноутбука
 могут иметь разные `ClientID`, но один `user_id` в заказах.
 **Визит**:
 Последовательность событий одного посетителя без пауз длиннее 30 минут
 и без перехода через полночь по часовому поясу счетчика. Сессия означает
 то же самое; поле `VisitID` служит эталоном в задании по нарезке сессий.
 **День активности**:
 День, в который посетитель появился на сайте хотя бы раз: впервые или
 вернувшись. За один день активности у него может быть несколько визитов.
 _Избегать_: визит в значении целого дня активности.
 **Паспорт куки**:
 Устройство и город, закрепленные за посетителем во все дни его активности.
 Генератор записывает их в поля событий. У двух посетителей одного человека
 город совпадает, а устройства различаются.
 **Торговое событие**:
 Запись о добавлении товара в корзину или о покупке: `add_to_cart` или
 `purchase`. Это отдельная строка кликстрима со страницей, где произошло
 действие: карточкой товара для корзины или страницей подтверждения для покупки.
 ### Хранилище и форматы данных
 **Хранилище**:
-Аналитическая база стенда в ClickHouse. Данные проходят слои STG, ODS, DDS
+Аналитическая база стенда — кластер ClickHouse со слоями STG/ODS/DDS/DM.
-и DM: от исходных сообщений до витрин для отчетов. Хранилище принимает
+Принимающая сторона границы «трекер | хранилище»: нормализует имена и стили
-данные по документации источников и приводит их к своей модели и именам.
+источников, строится по их документации.
-_Избегать_: склад, склад данных.
+_Избегать_: склад, склад данных
 **Сырые данные**:
-Исходные сообщения Kafka, сохраненные в слое STG без разбора: одно сообщение
+Слой STG хранилища и его содержимое: сообщение топика, положенное строкой,
-занимает одну строку таблицы. Слой STG также называют сырым слоем.
+как пришло, без разбора. В прозе — сырые данные и сырой слой; про
-_Избегать_: сырьё.
+конкретную таблицу или базу — STG.
-
+_Избегать_: сырьё
 **Справочник**:
 Готовые сведения из внешнего источника, которыми хранилище дополняет
 свои данные. На стенде они находятся в базе `dic`; пока это только каталог
 товаров. Объект `DICTIONARY` ClickHouse — одна из форм доступа к справочнику.
 _Избегать_: словарь в значении справочных данных: это слово уже обозначает
 `DICTIONARY` и словарь понятий.
 **Каталог товаров**:
 Список товаров с артикулами, названиями, категориями, брендами, ценами
 и уровнями спроса. Файл `data/catalog/products.csv` общий для генератора
 и справочника ClickHouse; товары можно добавлять строками в этом формате.
 **Нормализованное имя**:
 Имя поля источника, записанное в стиле `snake_case`: например,
 `ClientID` становится `client_id`. Оно указано в описании выгрузки и
 контракте схемы. Слой DDS выбирает имена по своей модели данных, поэтому
 они не обязаны повторять нормализованные имена источника.
 **Описание выгрузки**:
 Документ, который объясняет поля и формат событий источника:
 [`docs/formats/clickstream-event.md`](docs/formats/clickstream-event.md).
 По нему строится прием данных в хранилище. Документ собирается из
 описаний колонок генератора: правят их, затем пересобирают документ.
 _Избегать_: описание схемы, документация контракта.
 **Техническая проверка**:
 Проверка по внутреннему эталону стенда, например сравнение числа событий
 с паспортом мира. Проверка качества данных (DQ) опирается на данные
 магазина и связи между ними; ей не нужен эталон генератора, которого
 у настоящего магазина нет.
 _Избегать_: DQ-проверка в значении проверки по паспорту мира.
 ### Заказы
 **Слепок**:
 Дневная выгрузка состояния заказов из серверной части магазина.
 Она содержит заказы, оформленные за последние семь модельных дней,
 с учетом изменений к концу дня. Опоздавший заказ может отсутствовать
 в первых слепках.
 **Дата слепка**:
 Дата модельного дня, на конец которого снято состояние заказов;
 поле `snapshot_date` одинаково во всех строках выгрузки. Даты оформления
 заказов могут различаться; выгрузка отправляется на следующий модельный день.
 **Время аудита источника**:
 Время создания и последнего изменения записи заказа по часам базы
 магазина: поля `created_at` и `updated_at`. Время покупки в событии
 `purchase` записывает счетчик сайта, и оно может отличаться от этих полей.
 **Окно изменяемости**:
 Семь модельных дней, включая день оформления, в течение которых заказ
 может измениться и входит в слепки. После этого его состояние окончательно.
 Например, заказ от 1 июня входит в окно слепков за 1–7 июня; опоздание
 сокращает число его появлений, но не сдвигает конец окна.
 **Пакетный забор**:
 Чтение сообщений Kafka отдельным запросом по команде. Так хранилище
 принимает заказы после отправки всего слепка. События сайта оно принимает
 непрерывно через материализованное представление.
 _Избегать_: смешивать с пакетным режимом генератора: забор — чтение
 на стороне хранилища, режим генератора — отправка.
 ### Модельное время и запуск стенда
 **Мир**:
 Модель интернет-магазина: люди, их посещения сайта, товары и заказы,
 которые создает генератор.
 **Ось модельного времени**:
 Календарь магазина в генераторе. Первый день, D0, — 1 июня 2026 года,
 понедельник (`world.ORIGIN`); следующие дни отсчитываются от него.
 Реальное время — часы компьютера, на котором работает стенд. Дата запуска
 не меняет даты событий: D0 остается 1 июня, даже если стенд запущен осенью.
 **Граница суток**:
 Конец одного модельного дня и начало следующего, полночь по часовому
 поясу счетчика. Здесь заканчиваются визиты и снимается состояние заказов
 для слепка. Даги времени продвигают мир только на целые дни.
 **Стартовый мир**:
 Данные первых восьми модельных дней, с понедельника по следующий
 понедельник, которыми стенд наполняется при первом `make up`.
 Команда вызывает `world_initialize`: если мир уже готов и сохранен,
 повторный запуск оставляет данные и позицию времени прежними.
 `make rebuild-storage` пересоздает стартовый мир. При неизменных коде,
 каталоге и настройках его данные повторяются и служат эталоном проверок.
 _Избегать_: зерновой мир.
 **Паспорт мира**:
 Файл для сверки с эталонными данными: `data/world-inventory.json`.
 В нем записаны зерно генерации, версия генератора, контрольная сумма
 каталога, число событий и контрольная сумма каждого начального дня,
 контрольные суммы слепков и счетчики расхождений по заказам.
 В git хранится паспорт; сами события и слепки пересчитываются генератором.
 _Избегать_: опись мира, манифест, мини-манифест.
 **Пошаговый режим**:
 Продвижение модельного времени по явной команде: запустить генерацию
 следующего дня или нескольких дней.
 **Пакетный режим**:
 Отправка событий готового модельного дня без пауз между ними.
 Используется для начального наполнения, пересборок и проверок.
 **Живой день**:
 Постепенная отправка событий по времени их появления в модельном дне,
 с ускорением: по умолчанию сутки занимают около 24 реальных минут.
 Чтобы следующие дни запускались автоматически, снимают с паузы `world_live`.
 **Даги модельного времени**:
 Наборы связанных задач Airflow для генерации следующих дней магазина:
 `world_next_day`, `world_live_day` и `world_live`. Первые два выполняют
 шаг по времени, третий автоматически запускает живые дни, пока снят с паузы.
 Короткое название — даги времени.
 _Избегать_: пульт мира, управляющие даги.
 **Шаговый даг**:
 Даг, который отправляет данные следующих модельных дней и после успеха
 записывает новую позицию времени. `world_next_day` отправляет их пачкой,
 `world_live_day` — один день с ускорением. У них нет расписания;
 их запускают вручную или из другого дага.
 _Избегать_: работник.
 ### Устройство генератора
 **Зерно генерации**:
 Число, которое задает повторяемую последовательность случайных выборов
 генератора. Одинаковые зерно и день дают одинаковые данные при неизменных
 коде, каталоге и настройках. Эталон использует `CANONICAL_SEED` из `seeds.py`.
 **Состав мира**:
-Люди в модели, их идентификаторы посетителей и заранее заданные привычки:
+Постоянная часть мира генератора — популяция посетителей, их привычки,
-когда они приходят, как часто возвращаются, склонны ли покупать.
+двухкуковые пары. По дням его выдаёт план состава.
-У части людей две куки — это двухкуковые пары.
+_Избегать_: состояние мира
 _Избегать_: состояние мира.
 **План состава**:
-Расчет того, какие посетители придут в каждый день и какие свойства у них
+Способ спросить состав мира: функция зерна, выдающая его по дням —
-будут. В `plan.py` из зерна и номера дня получаются новые посетители,
+когорту новых кук, их возвраты, назначенные заказы двухкуковых пар.
 их возвраты и назначенные заказы людей с двумя куками.
 **Когорта дня**:
 Группа людей, впервые пришедших в один день, со всеми их куками и днями
 активности. Генератор рассчитывает ее по зерну и номеру первого дня.
 **Приток**:
 Появление новых посетителей (`ClientID`) по мере продвижения модельного
 времени. Поэтому число разных посетителей за весь период растет и
 не совпадает с числом посетителей за отдельный день.
 **Хвост возвратов**:
 Срок от первого появления человека, в пределах которого его куки могут
 возвращаться на сайт. У человека с двумя куками конец срока общий.
 **Предыстория**:
 Люди, впервые пришедшие до D0, и план их активности. До D0 события
 не создаются; возвраты этих людей дают повторных посетителей уже в первый
 день генерируемых данных.
 **Покупатель**:
 Человек, которому генератор заранее назначил повышенную склонность
 покупать. Он чаще доходит до заказа, но иногда покупают и остальные.
 Из таких людей выбираются те, у кого будут две куки.
 _Избегать_: покупатель в значении любого посетителя с покупкой за день;
 для этого случая — «визит с заказом».
 **Уровень спроса**:
 Свойство товара, от которого зависит, как часто после просмотра карточки
 его добавляют в корзину. В колонке `demand` каталога три значения:
 `магнит`, `обычный`, `залёживается`. Они постоянны по дням и задают
 различия в конверсии товаров и брендов.
 **Конфигурация мира**:
 Числовые настройки модели магазина в `world.py`: приток, частота возвратов,
 доли покупателей, начальная дата и другие параметры. Изменение этих
 настроек меняет генерируемые данные.
 **Подпоток**:
-Отдельная последовательность случайных выборов для части генератора,
+Ветвь дерева случайности генератора: своё зерно у состава мира, у каждого
-например для торговли в заданный день. В `seeds.py` она определяется
+дня и у каждого компонента дня. Подпоток задан позицией в дереве, а не
-общим зерном, днем и компонентом; для состава мира есть отдельные
+порядком вычислений.
-последовательности. Результат не зависит от порядка расчета частей.
+
 **Конфигурация мира**:
 Модуль чистых данных со всеми числами мира: приток, профили возвратов, доли
 покупателей, D0. Правка модуля — смена мира. Модуль-близнец контракта схемы:
 там колонки, здесь числа.
 **Когорта дня**:
 Люди, впервые пришедшие в мир в один день, со всеми их куками и днями
 активности. Единица плана состава: когорта — функция зерна и номера дня.
 **Человек**:
 Устойчивая личность в составе мира, которой принадлежат одна или две куки.
 Не поле источника: кликстрим видит куку, а заказ — пользователя магазина.
 **Посетитель**:
 Кука, наблюдаемая в кликстриме и обозначенная `ClientID`; единица
 `uniq(ClientID)`. Один человек может быть представлен несколькими посетителями.
 _Избегать_: «посетитель» про человека после склейки
 **Пользователь магазина**:
 Представление человека со стороны заказов; в записи заказа обозначается
 `user_id`. Через заказы связывает разные куки человека, в кликстрим напрямую
 не попадает.
 **Приток**:
 Появление новых кук на всём протяжении оси модельного времени; единица —
 кука (`ClientID`). Из-за притока накопленная аудитория растёт с
 горизонтом и не совпадает с дневной.
 **Хвост возвратов**:
 Окно активности, отсчитанное от первого дня человека и общее на обе
 его куки; дольше окна кука не возвращается.
 **Предыстория**:
 Когорты плана с первым днём активности до D0; событий не порождают.
 **День активности**:
 День, в который кука хоть раз появилась в мире: день её рождения или день
 возврата. Единица плана состава: за день он у куки один, а визитов внутри
 него бывает несколько.
 _Избегать_: визит (визит — про сессию)
 **Визит**:
 Подряд идущие события одной куки без пауз длиннее 30 минут, не пересекающие
 границу суток. Поле `VisitID` — эталон для лабы сессий. «Сессия» — то же
 понятие словами аналитики: в данных и в коде оно зовётся визитом, но имена
 вроде «лаба сессий» и «сборка сессий» остаются.
 **Паспорт куки**:
 Устройство и город, приписанные куке на всю жизнь: кука — это браузер на
 устройстве. Держит их план состава, разворачивает в поля события
 день-функция; у двухкуковой пары город один на две куки, устройства разные.
 **Покупатель**:
 Человек, которого план состава пометил склонным покупать. Метка значима:
 помеченный доходит до заказа заметно чаще прочих, но и непомеченный иногда
 покупает. Из покупателей отбираются двухкуковые пары.
 _Избегать_: «покупатель» про того, кто купил в конкретный день — это визит
 с заказом.
 **День-функция**:
-Расчет событий одних модельных суток по зерну и номеру дня, без генерации
+Функция (зерно, номер дня), выдающая упорядоченный поток событий этих
-предыдущих дней. Функция `day.stream(seed, day)` возвращает события
+модельных суток. Состояния между днями нет: день D не зависит от того,
-в порядке времени.
+прожиты ли дни до него.
-**Судьба заказа**:
+**Торговое событие**:
-Заранее рассчитанные изменения заказа: итоговый статус, время оплаты
+Событие корзины или покупки — отдельная строка потока, а не просмотр
-или отмены, удаленная позиция и задержка первого появления в слепке.
+страницы. Садится на ту страницу, где случилось: корзина — на карточку
-Они укладываются в семидневное окно заказа. Слепок показывает состояние
+товара, покупка — на страницу подтверждения заказа.
-на выбранный день без проигрывания предыдущих изменений.
+
 **Справочник**:
 Данные, которые хранилище не производит, а получает готовыми со стороны:
 содержимым владеет источник вне хранилища, слои только читают. Живут в базе
 `dic`. Первый и пока единственный — каталог товаров.
 _Избегать_: словарь — этим словом в проекте зовут и глоссарий понятий, и
 объект `DICTIONARY` ClickHouse, одну из форм, в которой справочник доступен.
 **Каталог товаров**:
 `data/catalog/products.csv` — общий файл генератора и словаря
 ClickHouse. Форма файла решена, длина — нет: строки дописываются.
 **Уровень спроса**:
 Свойство товара в каталоге: как часто открытую карточку кладут в корзину.
 Три значения — магнит, обычный, залёживается. Постоянная часть мира, а не
 поведение дня: он и делает конверсию «просмотр → корзина» по товарам и
 брендам различимой.
 **Ось модельного времени**:
 Собственный календарь мира генератора. Дни считаются от фиксированного
 первого дня D0; реальный календарь в модели не участвует. Между прогонами
 живут только зерно и позиция на оси.
 **Стартовый мир**:
 Первые восемь дней оси (понедельник по понедельник), которыми стенд
 наполняется при каждом `make up`. Он же эталонный мир, всегда один и тот же:
 на нем принимаются следующие этапы.
 _Избегать_: зерновой мир
 **Паспорт мира**:
 `data/world-inventory.json` — единственное, что о мире хранится в git: шапка
 (зерно, версия генератора, хеш каталога), строка на каждый день событий
 (число и хеш байтов) и строка на каждый отправленный слепок (хеш байтов).
 Счётчик сверх этого заводится только с названным читателем. Сам мир не
 хранится, а пересчитывается; паспорт отвечает на один вопрос: тот ли это мир.
 _Избегать_: опись мира, манифест, мини-манифест
 **Пошаговый режим**:
 Базовый способ движения по оси модельного времени: «прожить следующий
 день» — явное действие.
 **Живой день**:
 Проигрывание текущего модельного дня в реальном времени с ускорением;
 включается по требованию — постоянным фоном идёт, только пока включён
 выключатель `world_live`.
 **Пакетный режим**:
 Проигрывание готового дня пачкой, без темпа: заливка снимка при старте
 стенда, пересборки и проверки.
 **Даги модельного времени**:
 Даги Airflow, которыми двигают ось модельного времени: шаговые даги играют
 день — пачкой или в темпе, — а выключатель держит стенд живущим, пока включён.
 Коротко — даги времени.
 _Избегать_: пульт мира, управляющие даги
 **Шаговый даг**:
 Даг модельного времени, который играет день и ставит позицию на оси:
 `world_next_day` — пачкой, `world_live_day` — в темпе. Запускается руками,
 расписания и паузы не имеет; автоматику поверх него даёт выключатель.
 _Избегать_: работник
 **Граница суток**:
 Единственный структурный шов модели: сессии режутся по ней, слепок заказов
 снимается на ней, день проживается только целиком.
 **Контракт схемы**:
-Описания колонок события в модуле генератора `schema.py`: имена,
+Python-модуль с описателями колонок события — собственность генератора.
-типы и ограничения. По ним генератор создает и проверяет события,
+Из него выводятся генератор, валидация и документация формата; хранилище
-а `schema_doc.py` собирает описание выгрузки для хранилища.
+строится по документации, не по модулю.
 **Нормализованное имя**:
 Имя колонки источника, приведённое к нашему стилю (snake_case). Живёт в
 контракте схемы и в описании выгрузки. Не то же, что имя атрибута в модели
 данных: слой DDS складывает модель и называет атрибуты по ней.
 **Описание выгрузки**:
 Публичная документация формата события: таблица колонок, собранная из
 контракта схемы. По ней пишется сторона хранилища — как в бою по документации
 источника. Правится только контракт, документ пересобирается.
 _Избегать_: описание схемы, документация контракта
 **Канонический сериализатор**:
-Код в `serialize.py`, который превращает события и записи заказов в JSON
+Единственная граница, где запись генератора превращается в байты. Фиксированный
-для отправки. Порядок ключей и формат значений фиксированы, поэтому
+порядок ключей и строк — основа побайтовой воспроизводимости.
 одинаковые записи дают одинаковые байты.
 **Проигрыватель**:
-Код в `player.py`, который доставляет готовые события дня в приемник,
+Компонент доставки готового потока дня в приёмник. Два режима: пакетный
-например в Kafka или файл. В пакетном режиме он отправляет их без пауз,
+(пачкой, без темпа) и живой день.
-в режиме живого дня — с ускорением по времени событий.
+
 **Слепок**:
 Полная выгрузка заказов окна изменяемости, снятая бэкендом на границе суток:
 состояние заказов на этот момент, а не поток их изменений. Опоздавший заказ
 может отсутствовать в ранних слепках; после первого появления ездит до конца
 своего окна.
 **Дата слепка**:
 Дата завершившегося модельного дня, состояние которого снято на исходящей
 границе суток. Одна для всех записей выгрузки; не дата заказа и не время
 отправки сообщения.
 **Время аудита источника**:
 Время создания или последнего изменения строки заказа по часам базы источника.
 В записи слепка это `created_at` и `updated_at`; бизнес-время покупки живёт в
 событии `purchase` отдельно.
 **Судьба заказа**:
 Исход, моменты изменений, вычеркнутая позиция и опоздание заказа — всё
 решается бросками при его рождении и укладывается в окно изменяемости целиком.
 Слепок любого дня — чтение готовой судьбы, а не накопление состояния.
 **Окно изменяемости**:
 Сколько модельных дней заказ ещё может измениться и потому продолжает ездить
 в слепках. Константа мира: семь дней. За окном заказ замёрз, выручка дня
 перестала «дышать».
 **Пакетный забор**:
 Способ приёма топика, при котором данные тянет запрос по команде, а не
 матвью непрерывно. Так стенд принимает заказы: у слепка есть начало и конец,
 и забирать его уместно тогда, когда он собран целиком. Противоположность —
 потоковый приём событий.
 _Избегать_: путать с приёмником и пакетным режимом — те про сторону
 генератора, про отправку; забор — про сторону хранилища, про чтение.
 **Техническая проверка**:
 Проверка, чей оракул — внутренний эталон стенда (паспорт мира), которого у
 настоящего магазина нет. За учебный урок DQ не выдаётся.
 _Избегать_: DQ-проверка — та работает на наблюдаемых данных магазина.
@@ -51,11 +51,9 @@ config-test:
 # того своя дверь и свой конфиг. Версия закреплена, потому что лока в корне
 # нет, а форматтер между версиями меняет вывод — иначе проверка однажды
 # покраснела бы сама, без единой правки в репозитории.
 # Проверка рендера быстрая, не требует стенда и ловит устаревший HTML.
 lint:
-	uvx ruff@0.16.1 check dags infra/superset docs/handbook/architecture-map
+	uvx ruff@0.16.1 check dags infra/superset
-	uvx ruff@0.16.1 format --check dags infra/superset docs/handbook/architecture-map
+	uvx ruff@0.16.1 format --check dags infra/superset
 	uv run docs/handbook/architecture-map/render.py --check
 # --- Наполнение миром ---
@@ -5,156 +5,132 @@
 > курсовая работа. Если вам нужна помощь, обратитесь к автору материалов —
 > ментору [@dementev_dev](https://t.me/dementev_dev).
-Здесь вы будете работать с хранилищем данных небольшого интернет-магазина:
+Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse. Здесь
-загружать и обрабатывать данные в ClickHouse, строить витрины, проверять
+можно проследить весь путь данных: от кликстрима и заказов до витрин, проверок
-качество данных и создавать графики. Стенд рассчитан на тех, кто уже изучил
+и графиков. Это преемник учебного стенда
-основы ClickHouse и хочет попрактиковаться.
+[clickstream-ch-kafka-superset-demo](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo).
-Генератор создает заказы и кликстрим — записи о действиях посетителей
+В стенде подняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka,
-магазина. Данные поступают через Kafka в ClickHouse и проходят четыре слоя
+Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда
-обработки: STG, ODS, DDS и DM. В кластере ClickHouse два шарда и отдельный
+приезжают из генератора и идут по слоям STG → ODS → DDS → DM. `make up`
-ClickHouse Keeper. Airflow управляет загрузкой и обработкой, Superset
+наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы
-показывает отчеты, а Prometheus и Grafana помогают следить за работой стенда.
+разобраться в устройстве, начните с [путеводителя](docs/handbook/README.md), а
-
+учиться — с [уроков](docs/labs/README.md).
 При первом запуске стенд загрузит данные за неделю работы магазина.
 После запуска начните с [путеводителя](docs/handbook/README.md): он объясняет
 устройство хранилища. Затем переходите к [учебным заданиям](docs/labs/README.md).
 ## Быстрый старт
-Для запуска нужны Docker с Compose, `make`, `curl` и `jq`.
+Нужны Docker с Compose и около 8 ГБ памяти, доступной Docker. Это не объём
-Выделите Docker около 8 ГБ оперативной памяти. В Docker Desktop и WSL2
+ноутбука, а то, что отдано самому Docker: в Docker Desktop и WSL2 он живёт
-проверьте лимит памяти виртуальной машины: он может быть меньше, чем общий
+внутри виртуальной машины и получает лишь часть памяти хозяина. Сколько выдано
-объем памяти компьютера. Команда `docker info --format '{{.MemTotal}}'`
+сейчас, в байтах, покажет `docker info --format '{{.MemTotal}}'`. В WSL2 это
-покажет доступный Docker объем в байтах. В WSL2 лимит задается параметром
+поднимается параметром `memory` в файле `.wslconfig` домашнего каталога
-`memory` в файле `.wslconfig` в домашнем каталоге пользователя Windows.
+пользователя Windows; после правки нужен `wsl --shutdown`. Если своей машины не
-После изменения выполните `wsl --shutdown`. Если ресурсов компьютера
+хватает, стенд одинаково хорошо живёт на недорогом VPS.
 недостаточно, стенд можно запустить на VPS.
-По умолчанию должны быть свободны порты
+`make up` нужны `curl` и `jq`: первым он ходит в Airflow, вторым читает
-`23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
+паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны
-и `29092`. Для работы с командами `make` в каталоге `generator/` также
+порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
-понадобится `uv`.
+и `29092`. Всем целям генератора в `generator/` нужен `uv`.
-В каталоге репозитория скопируйте образец настроек:
+Сначала скопируйте настройки стенда:
 ```bash
 cp .env.example .env
 ```
 В `.env` задаются имя экземпляра стенда, внешние порты, учебные логины,
 пароли и ключи. Проверьте `DOCKER_GID`: это числовой идентификатор группы
 `docker` на вашей машине. Узнать его можно командой `getent group docker`.
 Если число отличается от образца, замените значение в `.env`. От этой
 настройки зависит запуск генератора из Airflow.
 Запустите стенд:
 ```bash
 make up
 ```
-Команда запустит службы и дождется загрузки начальных данных. Порядок запуска
+`make up` сам ждет заливки стартового мира; что он делает по шагам и какие
-и проверки результата описаны в [справочнике проверок](docs/architecture/testing.md).
+проверки есть у стенда, описано в [карте
-Если обязательной настройки в `.env` не хватает, Compose сообщит об ошибке.
+проверок](docs/architecture/testing.md).
 Внутренние адреса служб, имена топиков и версии образов заданы в `compose.yaml`
 и Dockerfile.
-Логины и пароли Postgres и Grafana сохраняются при первом запуске в томах
+`.env.example` — образец обязательной локальной настройки. В нём живут имя
-Docker. Простая правка `.env` их не изменит. Чтобы задать новые значения
+экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца
-через `.env`, потребуется `make clean` и повторный `make up`. При этом
+верно не везде — `DOCKER_GID`: у группы `docker` на каждой машине свой номер, и
-будут удалены все локальные данные стенда.
+свой подскажет `getent group docker`. Пока он не сойдётся, стенд работает весь,
 кроме [дагов модельного
 времени](docs/architecture/world.md#даги-модельного-времени). `compose.yaml` не
 дублирует их умолчаниями: если значения нет в `.env`, Compose сразу предложит
 скопировать образец. Внутренние адреса, имена топиков и версии образов описывают
 сам стенд, поэтому записаны литералами в `compose.yaml` и Dockerfile.
 Учётные данные Postgres и Grafana применяются при создании их томов.
 После первого запуска меняйте их только вместе с `make clean`: команда удалит
 все локальные данные стенда, а следующий `make up` создаст их с новыми
 значениями.
 ## Адреса и пароли
 С настройками из `.env.example` порты доступны только с локальной машины:
- узел ClickHouse 1 — `http://127.0.0.1:28123`, нативный порт `29000`;
+- нода 1 — `http://127.0.0.1:28123`, нативный порт `29000`;
- узел ClickHouse 2 — `http://127.0.0.1:28124`, нативный порт `29001`;
+- нода 2 — `http://127.0.0.1:28124`, нативный порт `29001`;
 - Kafka — `127.0.0.1:29092`;
 - Airflow — `http://127.0.0.1:28080`, пользователь `admin`, пароль `airflow`;
 - Superset — `http://127.0.0.1:28088`, пользователь `admin`, пароль `superset`;
 - Prometheus — `http://127.0.0.1:29090`;
 - Grafana — `http://127.0.0.1:23000`, пользователь `admin`, пароль `admin`.
-Подробнее о службах, правах пользователей и изменении настроек —
+Службы, пользователи и роли, применение настроек и результаты сверки
-в [справочнике стенда](docs/architecture/stand.md).
+конфигурации описаны в [справочнике стенда](docs/architecture/stand.md).
-## Добавить данные за следующие дни
+## Сдвинуть мир вперед
-Время в учебном магазине идет отдельно от календарного. В документации оно
+В Airflow запустите даг `world_next_day`: по умолчанию он сыграет один день, а
-называется модельным временем, а сам магазин с его посетителями и заказами —
+в форме запуска можно задать другое число дней. Снимите с паузы `world_live`,
-миром.
+и мир поедет сам в темпе модельного времени. Подробности — в [справочнике
 мира](docs/architecture/world.md#даги-модельного-времени).
-В Airflow запустите `world_next_day`. Это даг — набор связанных задач,
+## Вернуть мир к началу
 которые Airflow выполняет в заданном порядке. Он создаст и загрузит данные
 за следующий день работы магазина. В форме запуска можно задать число дней.
-Чтобы новые данные поступали непрерывно, снимите с паузы даг `world_live`.
+`make rebuild-storage` запустит в Airflow явную пересборку: удалит прикладные
-Он будет запускать генерацию день за днем; один модельный день занимает
+базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему
-около 24 минут. Подробности — в [справочнике генератора и модельного
+и данные заново. Службы и их тома останутся на месте. Перед пересборкой
-времени](docs/architecture/world.md#даги-модельного-времени).
+поставьте `world_live` на паузу и дайте уже начатому шаговому дагу закончить
 день.
-## Восстановить начальные данные
+## Выключить или сбросить целиком
-Если хотите начать заново, поставьте `world_live` на паузу и дождитесь
+`make down` остановит контейнеры без удаления данных. `make clean` удалит весь
-завершения уже запущенного дага генерации. Затем выполните
+стенд вместе с именованными томами и для обычной работы не нужен.
 `make rebuild-storage`.
 Команда удалит прикладные базы ClickHouse, топики и позиции потребителей
 Kafka, затем заново создаст схему хранилища и загрузит начальные данные.
 Службы и их тома останутся на месте.
 ## Остановить или удалить стенд
 `make down` остановит стенд и сохранит данные. Для повторного запуска
 выполните `make up`.
 `make clean` удалит контейнеры и все данные в томах Docker. Для обычного
 завершения работы достаточно `make down`.
 ## Подключиться из DBeaver
 Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост
 `127.0.0.1`, порт `28123`, пользователя `analyst` и пароль из переменной
 `CLICKHOUSE_ANALYST_PASSWORD` в `.env`; в образце это `analyst-26-reader`.
-Для подключения ко второму узлу укажите порт `28124`.
+Ко второй ноде — порт `28124`.
-Пользователь `analyst` может читать данные во всех слоях и справочниках.
+Пользователь `analyst` читает все слои и справочники. Нативные порты `29000` и
-Для заданий с собственными таблицами наблюдений используйте `student` и пароль
+`29001` нужны `clickhouse-client`, но не DBeaver. Остальные пользователи и роли
-из `CLICKHOUSE_STUDENT_PASSWORD` в `.env`. Он читает те же источники, а создавать,
+описаны в [справочнике
-заполнять и удалять таблицы может только в базе `default`.
+стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse).
 Для создания учебных витрин используйте подключение, описанное
 в [инструкции к заданиям](docs/labs/README.md#выполнение-sql-в-dbeaver).
 Нативные порты `29000` и `29001` нужны `clickhouse-client`, но не DBeaver.
 Остальные пользователи и роли описаны в
 [справочнике стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse).
 ## Документация
 - [docs/handbook/](docs/handbook/) — путеводитель по стенду и порядок чтения.
 - [docs/labs/](docs/labs/) — учебные задания с порядком прохождения и
  самопроверкой.
- [docs/specs/](docs/specs/) — требования к стенду и программа обучения.
+- [docs/specs/](docs/specs/) — спеки: источник истины о задуманном.
- [docs/adr/](docs/adr/) — решения об устройстве стенда: что выбрали,
+- [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми
-  какие варианты отклонили и почему.
+  вариантами: почему сделано так, а не иначе.
- [docs/architecture/](docs/architecture/) — технические справочники:
+- [docs/architecture/](docs/architecture/) — рабочие справочники по зонам
-  - [хранилище](docs/architecture/storage.md) — правила именования,
+  ответственности:
-    распределение данных по шардам, прием событий и список таблиц.
+  - [хранилище](docs/architecture/storage.md) — конвенции имён, раскладка по
    шардам, приём событий, карта таблиц.
  - [конвейер](docs/architecture/etl.md) — движение данных между слоями и
    работа дагов.
  - [мир и модельное время](docs/architecture/world.md) — начальные данные,
-    создание данных за следующие дни и управление генератором.
+    ход дней и управление генератором.
  - [стенд](docs/architecture/stand.md) — службы, доступ и настройка.
-  - [проверки](docs/architecture/testing.md) — команды `make` для проверки
+  - [проверки](docs/architecture/testing.md) — что утверждает каждая цель
-    стенда и правила добавления новых проверок.
+    `make` и куда класть новую проверку.
  - [мониторинг](docs/architecture/monitoring/README.md) — сбор метрик и
    устройство дашборда.
  - [Superset](docs/architecture/superset.md) — подключения, наборы данных и
-    автоматическая настройка при запуске.
+    граница автоматической настройки.
 - [docs/research/](docs/research/) — исследования; сейчас это формат
  кликстрима Яндекса, по которому строится модель события.
- [docs/formats/](docs/formats/) — форматы исходных данных, необходимые
+- [docs/formats/](docs/formats/) — описания форматов источников: по ним
-  для их загрузки и обработки. Эти документы собираются из кода командой
+  пишется сторона хранилища. Собираются из кода командой `make docs` в
-  `make docs` в `generator/`; вручную их менять не нужно.
+  `generator/`, руками не правятся.
- [AGENTS.md](AGENTS.md) — правила работы в репозитории для ИИ-агентов.
+- [AGENTS.md](AGENTS.md) — контракт работы в репозитории.
@@ -20,7 +20,6 @@ x-clickhouse-common: &clickhouse-common
    CLICKHOUSE_LIFECYCLE_PASSWORD: ${CLICKHOUSE_LIFECYCLE_PASSWORD:?Скопируйте .env.example в .env}
    CLICKHOUSE_BI_PASSWORD: ${CLICKHOUSE_BI_PASSWORD:?Скопируйте .env.example в .env}
    CLICKHOUSE_ANALYST_PASSWORD: ${CLICKHOUSE_ANALYST_PASSWORD:?Скопируйте .env.example в .env}
    CLICKHOUSE_STUDENT_PASSWORD: ${CLICKHOUSE_STUDENT_PASSWORD:?Добавьте CLICKHOUSE_STUDENT_PASSWORD из .env.example в .env}
    CLICKHOUSE_GRAFANA_PASSWORD: ${CLICKHOUSE_GRAFANA_PASSWORD:?Скопируйте .env.example в .env}
  depends_on:
    clickhouse-keeper:
@@ -1,17 +1,18 @@
-"""Трансформации DDS: заказы, сессии и карта идентичностей.
+"""Трансформации слоя DDS: сборка моделей.
-Запросы рассчитывают заказы и сессии за выбранные дни и записывают результат
+Заказ и сессия собираются заменой дневных партиций. Карта идентичностей
-в промежуточные таблицы. Затем готовые дневные разделы этих таблиц заменяют
+пересчитывается целиком после заказа, потому что читает его текущую модель.
 разделы основных таблиц. Пока идет расчет, читатели видят прежние данные.
-Карта идентичностей пересчитывается целиком после заказов. Новые строки
+Расписания у дага нет и параметров тоже: объём каждого прогона он выводит сам
-добавляются с меткой времени сборки; представление с FINAL выбирает последнюю
+из состояния слоёв и позиции мира, поэтому один и тот же запуск одинаково
-версию каждой строки.
+верен из триггера дневного конвейера, с кнопки менти и после падения
 (docs/architecture/etl.md, «Объём прогона»).
-Даг запускается без расписания и параметров. Даты он выбирает по состоянию
+Заказ и сессия гасят повтор заменой партиции целиком: день собирается в
-таблиц и позиции мира. Новый запуск заново определяет диапазон: наличие даты
+таблицу-двойник и подменяет собой партицию цели. Карта пишет полный набор пар
-не подтверждает полноту дня и не гарантирует повтор его сборки после сбоя.
+новой версией, а точное чтение даёт FINAL. Замена партиции разобрана в
-Подробности — docs/architecture/etl.md, «Объём прогона» и «Идемпотентность».
+sql/dds/order_replace.sql; точное чтение карты описано в
 sql/ddl/50-dds-views.sql.
 """
 from __future__ import annotations
@@ -256,11 +257,16 @@ def _days(first_day: datetime.date, last_day: datetime.date) -> list[str]:
@task
 def replacements(scope: dict[str, object]) -> list[dict[str, object]]:
-    """Подготовить параметры отдельной задачи replace для каждого дня.
+    """Разложить дни в аргументы размноженной задачи замены.
-    expand_kwargs получает список словарей и создает по одному экземпляру
+    Шаг существует ради ограничения Airflow: размножать задачу можно
-    задачи на каждый словарь. Дата подставляется в SQL шаблоном Jinja:
+    только по целому возврату другой задачи — ни по ключу словаря, ни по
-    параметр ClickHouse в ALTER ... PARTITION здесь не поддерживается.
+    карте поверх него. Отсюда отдельный возврат под один список.
    День едет в запрос подстановкой Jinja, а не параметром ClickHouse:
    в ALTER … PARTITION сервер параметр не подставляет — замерено,
    отвечает синтаксической ошибкой. Значение при этом не внешнее, его
    вернул сам ClickHouse запросом объёма.
    """
    return [{"params": {"day": day}} for day in scope["days"]]
@@ -270,8 +276,8 @@ def replacements(scope: dict[str, object]) -> list[dict[str, object]]:
    schedule=None,
    start_date=START_DATE,
    is_paused_upon_creation=False,
-    # Одновременные запуски используют одни промежуточные таблицы.
+    # Два прогона разом собирали бы один и тот же двойник: второй затёр бы
-    # Второй мог бы очистить результат первого до замены партиций.
+    # чужую сборку между вставкой и заменой партиций.
    max_active_runs=1,
    template_searchpath=str(SQL_ROOT),
    tags=["dds"],
@@ -292,7 +298,7 @@ def dds_transform():
    @task_group(group_id="order")
    def order():
-        """Заказ: изменяемые дни последнего слепка и пропущенные дни."""
+        """Заказ: дышащее окно плюс дни, которых в слое ещё нет."""
        @task
        def scope() -> dict[str, object]:
@@ -300,7 +306,8 @@ def dds_transform():
            query = (SQL_ROOT / "dds" / "order_scope.sql").read_text(encoding="utf-8")
            hook = ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION)
            row = hook.get_first(query)
-            # Без заказов ODS расчет невозможен: задача сообщает об ошибке.
+            # Пустой ответ означает пустой источник: собирать нечего, и
            # зеленеть на этом нельзя — прогон встаёт с внятной причиной.
            if row is None:
                raise AirflowException(
                    "в ods.order нет ни одного заказа: собирать нечего; "
@@ -335,9 +342,9 @@ def dds_transform():
            do_xcom_push=False,
        )
-        # На каждый день создается отдельная задача замены партиции.
+        # Замена идёт по партиции за раз — другой формы у операции нет. День
-        # Неудачную замену можно повторить, пока промежуточная таблица
+        # становится отдельной задачей: в интерфейсе видно, сколько дней несёт
-        # сохраняет рассчитанные строки этого запуска.
+        # прогон, а повтор после отказа стоит одного дня, а не всей пересборки.
        replace = SQLExecuteQueryOperator.partial(
            task_id="replace",
            conn_id=CLICKHOUSE_CONNECTION,
@@ -363,8 +370,9 @@ def dds_transform():
                    "проверьте, дошёл ли поток до хранилища"
                )
            first_day, last_day = row
-            # Для каждого прожитого дня уже есть строки сессий.
+            # Пропуск, а не отказ: слой полон по последний прожитый день, а
-            # Новых дней для расчета нет: группа задач будет пропущена.
+            # сегодняшний ещё идёт. Это обычное состояние повторного прогона,
            # и в интерфейсе оно видно пропущенной группой.
            if first_day is None:
                raise AirflowSkipException(
                    f"сессии собраны по {last_day} включительно, "
@@ -1,12 +1,9 @@
 """Трансформации слоя DM: сборка стендовых витрин.
-Даты для расчета выручки берутся из последнего слепка заказов и списка
+Выручка наследует ритм заказов. Сверка соединяет окно заказов с прожитым
-пропущенных дней. Сверка покупок с заказами учитывает также прожитые дни
+хвостом событий. Обе заменяют дневные партиции. Трафик наследует
-событий и дни, где заказ еще не найден. Запросы записывают результаты
+ретроспективность карты идентичностей и пересчитывает всю историю новой
-в промежуточные таблицы, затем заменяют дневные разделы основных таблиц.
+версией. Объем каждого прогона выводится из состояния слоев.
 Трафик пересчитывается за всю историю: новая связь посетителя с пользователем
 магазина меняет число известных пользователей и за прошлые дни.
 """
 from __future__ import annotations
@@ -65,11 +62,10 @@ def _days(first_day: datetime.date, last_day: datetime.date) -> list[str]:
@task
 def replacements(scope: dict[str, object]) -> list[dict[str, object]]:
-    """Подготовить параметры отдельной задачи replace для каждого дня.
+    """Разложить дни в аргументы размноженной задачи замены.
-    expand_kwargs получает список словарей и создает по одному экземпляру
+    Отдельный словарь нужен каждому экземпляру ``expand_kwargs``; тот же
-    задачи на каждый словарь. Дата подставляется в SQL шаблоном Jinja:
+    прием разобран в ``dds_transform.py`` на замене партиций заказов.
    параметр ClickHouse в ALTER ... PARTITION здесь не поддерживается.
    """
    return [{"params": {"day": day}} for day in scope["days"]]
@@ -145,7 +141,7 @@ def dm_transform():
    @task_group(group_id="purchase_vs_orders")
    def purchase_vs_orders():
-        """Сверка: изменяемые заказы, прожитые покупки и дни ожидания заказа."""
+        """Сверка: окно заказов, прожитый хвост и предварительные дни."""
        @task
        def scope() -> dict[str, object]:
@@ -74,11 +74,7 @@ def _publish_summary(
 ) -> list[str]:
    """Записать дневную сводку и вернуть малый срез готовой диагностики."""
    if not summaries:
-        raise AirflowException(
+        raise AirflowException(f"{check_name}: область проверки пуста")
            f"{check_name}: запрос не вернул ни одного дня для проверки; "
            "проверьте наличие данных в источниках сверки. Состав проверок "
            "описан в docs/architecture/dm.md"
        )
    diagnostics: list[str] = []
    context = get_current_context()
@@ -152,10 +148,7 @@ def build_classes_vs_inventory() -> list[str]:
        for mismatch_class, count in day["orders"].items()
    }
    if not expected:
-        raise AirflowException(
+        raise AirflowException("classes_vs_inventory: в паспорте нет закрытых дней")
            "classes_vs_inventory: в data/world-inventory.json нет счетчиков "
            "заказов для закрытых дней; сообщите наставнику"
        )
    query = (SQL_ROOT / "dq" / "classes_vs_inventory.sql").read_text(encoding="utf-8")
    # GROUP BY закономерно не возвращает группу из нуля строк.
@@ -186,9 +179,9 @@ def build_classes_vs_inventory() -> list[str]:
                failed_rows += 1
                actual_text = actual_count if actual_count is not None else "нет ключа"
                details.append(
-                    f"{day} mismatch_class={mismatch_class}: "
+                    f"{day} key={mismatch_class}: "
-                    f"заказов в паспорте={reference_count}, "
+                    f"эталон={reference_count}, "
-                    f"в dm.purchase_vs_orders_v={actual_text}"
+                    f"объект={actual_text}"
                )
        summaries.append((data_date, reference_rows, actual_rows, failed_rows, details))
    return _publish_summary("classes_vs_inventory", summaries)
@@ -201,10 +194,7 @@ def publication_scope() -> list[dict[str, dict[str, str]]]:
        "SELECT DISTINCT data_date FROM dm.dq_summary_stage_dist ORDER BY data_date"
    )
    if not rows:
-        raise AirflowException(
+        raise AirflowException("донор dm.dq_summary пуст: публиковать нечего")
            "dm.dq_summary_stage_dist пуста: нет результатов для записи "
            "в сводку DQ; проверьте журналы задач build_* этого запуска"
        )
    return [{"params": {"day": data_date.isoformat()}} for (data_date,) in rows]
@@ -249,15 +239,10 @@ def assert_check(check_name: str, diagnostics: list[str]) -> None:
        logging.error("%s: %s", check_name, detail)
    summary = "; ".join(
        f"{data_date}: эталонных ключей {reference_rows}, "
-        f"ключей в проверяемом объекте {actual_rows}, "
+        f"фактических {actual_rows}, нарушено {failed_rows}"
        f"отсутствуют или различаются {failed_rows}"
        for data_date, reference_rows, actual_rows, failed_rows in failed_days
    )
-    raise AirflowException(
+    raise AirflowException(f"{check_name}: {summary}")
        f"{check_name}: {summary}. Примеры расхождений — в журнале этой задачи; "
        "итоги по дням — в dm.dq_summary_v. Источники каждой сверки описаны "
        "в docs/architecture/dm.md"
    )
@dag(
@@ -45,10 +45,7 @@ def check_mart(
    """Сверить одну домашнюю витрину с независимым ответом из источника."""
    hook = _clickhouse_hook()
    if not _mart_exists(hook, mart):
-        raise AirflowException(
+        raise AirflowException(f"витрина {mart} не найдена; выполните ТЗ {lab_path}")
            f"витрина {mart} не найдена на узле подключения clickhouse_default; "
            f"проверьте имя и место создания витрины по заданию {lab_path}"
        )
    try:
        query = (SQL_ROOT / sql_name).read_text(encoding="utf-8")
@@ -75,8 +72,7 @@ def check_mart(
    except Exception as error:
        raise AirflowException(
            f"не удалось проверить витрину {mart}: {error}; "
-            f"сверьте имена и типы колонок с заданием {lab_path}. "
+            f"сверьте договор колонок и проверку в ТЗ {lab_path}"
            "Подробности ошибки — в журнале этой задачи"
        ) from error
    failed_rows = sum(summary[3] for summary in summaries)
@@ -97,8 +93,7 @@ def check_mart(
    compared_sides = diagnostics[0]
    raise AirflowException(
        f"витрина {mart} расходится с источником: {days}. "
-        f"Пример сравнения: {compared_sides}. Другие примеры — в журнале этой "
+        f"Пример сравнения: {compared_sides}. Сверьтесь с ТЗ {lab_path}"
        f"задачи. Проверьте расчет для указанных ключей по заданию {lab_path}"
    )
@@ -114,28 +109,28 @@ def homework_check():
    """Дать отдельный результат самопроверки по каждой домашней витрине."""
    check_mart.override(task_id="events_enriched")(
        "dm.events_enriched_v",
-        "docs/labs/1-1-events-enriched.md",
+        "docs/labs/events-enriched.md",
        "events_enriched_vs_dds.sql",
        "events_enriched_scope.sql",
    )
    check_mart.override(task_id="top_pages_daily")(
        "dm.top_pages_daily_v",
-        "docs/labs/1-2-top-pages-daily.md",
+        "docs/labs/top-pages-daily.md",
        "top_pages_daily_vs_dds.sql",
    )
    check_mart.override(task_id="session_overview")(
        "dm.session_overview_v",
-        "docs/labs/1-3-session-overview.md",
+        "docs/labs/session-overview.md",
        "session_overview_vs_dds.sql",
    )
    check_mart.override(task_id="dq_errors_daily")(
        "dm.dq_errors_daily_v",
-        "docs/labs/1-4-dq-errors-daily.md",
+        "docs/labs/dq-errors-daily.md",
        "dq_errors_daily_vs_ods.sql",
    )
    check_mart.override(task_id="utm_effectiveness")(
        "dm.utm_effectiveness_v",
-        "docs/labs/1-5-utm-effectiveness.md",
+        "docs/labs/utm-effectiveness.md",
        "utm_effectiveness_vs_dds.sql",
    )
@@ -1,13 +1,18 @@
-"""Пакетный прием заказов: Kafka → STG → ODS.
+"""Приём заказов: пакетный забор слепка из Kafka в хранилище.
-Шаговый даг модельного времени отправляет слепок, запускает orders_ingest
+Путь Kafka → STG → ODS у заказов один и живёт одним дагом: сначала забор
-и ждет его завершения. Собственного расписания у orders_ingest нет.
+порции в `stg`, затем разбор того же среза в типизированный ODS и в таблицу
-Сначала pull_batch сохраняет порцию сообщений в STG, затем parse_batch
+брака. Расписания у дага нет: его дёргает тот, кто положил слепок в топик, —
-разбирает тот же срез по _load_id в заказы и ошибки.
+шаговый даг модельного времени после проигрыша дня, — и ждёт конца.
-События принимаются непрерывно через материализованные представления.
+Контраст с приёмом событий и есть урок. События тянет матвью, навсегда
-Заказы читаются одним запросом; полнота слепка этим не гарантируется.
+подписанная на чтеца: приём идёт сам, пока идёт поток. Слепок заказов
-Правила и ограничения — docs/architecture/orders/ingestion.md.
+приезжает раз в модельный день целой выгрузкой, у которой есть начало и конец,
 и забирает её запрос по команде. Push против pull — два режима на одном стенде,
 каждый там, где ему место по природе источника.
 Решения и доводы целиком — ADR 0008 (забор) и ADR 0010 (версии в ODS); форма
 перехода — docs/architecture/orders/ingestion.md.
 """
 from __future__ import annotations
@@ -19,7 +24,8 @@ from airflow.sdk import dag
 START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
-# Compose монтирует sql/ по этому пути во все службы Airflow.
+# Запросы лежат файлами в sql/ репозитория, разложенные по слоям хранилища;
 # сюда их монтирует compose — всем службам Airflow сразу.
 SQL_ROOT = "/opt/airflow/sql"
@@ -28,14 +34,15 @@ SQL_ROOT = "/opt/airflow/sql"
    schedule=None,
    start_date=START_DATE,
    is_paused_upon_creation=False,
-    # Один запуск за раз: параллельные чтения разделили бы порцию
+    # Чтец у топика один, и группа потребителей у него одна. Два прогона разом
-    # между разными _load_id.
+    # дрались бы за неё, а слепок разъехался бы по двум _load_id; второй
    # прогон подождёт своей очереди.
    max_active_runs=1,
    template_searchpath=SQL_ROOT,
    tags=["заказы"],
 )
 def orders_ingest():
-    """Сохранить порцию заказов и разобрать ее в ODS."""
+    """Забрать приехавший слепок заказов и разложить его по слоям."""
    pull_batch = SQLExecuteQueryOperator(
        task_id="pull_batch",
        conn_id="clickhouse_default",
@@ -52,8 +59,8 @@ def orders_ingest():
        do_xcom_push=False,
    )
-    # Две вставки parse_batch не образуют транзакцию. Повтор задачи
+    # ClickHouse не даёт транзакции между двумя вставками parse_batch. Один
-    # выполняет обе над тем же срезом STG по _load_id.
+    # task_id сохраняет их порядок и одну точку повтора для неизменного load_id.
    pull_batch >> parse_batch
@@ -146,25 +146,25 @@ def _ingest_orders() -> TriggerDagRunOperator:
            type="integer",
            minimum=1,
            maximum=7,
-            title="Число модельных дней для генерации",
+            title="Сколько дней прожить",
            # description_md рендерится подсказкой прямо в форме запуска
            # (params.rst, Airflow 3.3), чтобы правило было видно сразу.
            description_md=(
-                "Создать данные за следующие 1–7 модельных дней; по умолчанию "
+                "Форма задает только число дней. Номер первого несыгранного "
-                "за один день. События отправляются без пауз. Номер первого дня "
+                "дня шаговый даг берёт из переменной `world_position` (Admin → "
-                "берется из `world_position` (Admin → Variables). Поля Logical "
+                "Variables). Поля Logical date и Run ID нужны самому Airflow "
-                "date и Run ID не меняют выбор дня. После завершения запустите "
+                "и на выбор дня не влияют."
                "`etl_pipeline`, чтобы обновить DDS и витрины DM."
            ),
        )
    },
 )
 def world_next_day():
-    """Создать данные за следующие модельные дни без пауз между событиями.
+    """Прожить следующие дни пачкой, без пауз.
-    Параметр `days` задает число дней: от 1 до 7, по умолчанию 1. Первый день
+    Запускается руками. День по умолчанию один, но разгон вперёд идёт одним
-    берется из `world_position`. После загрузки событий и слепков заказов
+    нажимом, а не десятью: сколько дней играть — параметр запуска. Первый
-    запустите `etl_pipeline` вручную, чтобы обновить DDS и витрины DM.
+    день шаговый даг берёт из `world_position`. Логическая дата прогона на выбор
    дня не влияет.
    """
    @task
@@ -174,10 +174,7 @@ def world_next_day():
        position = first_day + days
        Variable.set(WORLD_POSITION, str(position))
        logging.info(
-            "данные за модельные дни %s–%s отправлены; world_position=%s",
+            "дни %s–%s сыграны; новая позиция — %s", first_day, position - 1, position
            first_day,
            position - 1,
            position,
        )
    first_day = first_unplayed_day()
@@ -213,23 +210,20 @@ def world_next_day():
    tags=TAGS,
 )
 def world_live_day():
-    """Постепенно отправить события за следующий модельный день.
+    """Прожить следующий день в темпе модельного времени.
-    При ускорении ×60 отправка занимает около 24 реальных минут. Номер дня
+    Ускорение ×60: модельные сутки укладываются примерно в двадцать четыре
-    берется из `world_position`; Logical date его не меняет. Затем даг
+    реальные минуты, и суточная волна разворачивается на глазах. Запускается
-    отправляет слепок заказов и ждет его загрузки и завершения `etl_pipeline`.
+    руками; чтобы мир жил так день за днём сам, есть выключатель `world_live`.
-    Для автоматического запуска следующих дней снимите с паузы `world_live`.
+    Следующий день шаговый даг берёт из `world_position`. Логическая дата прогона
    на выбор дня не влияет.
    """
    @task
    def remember_played(first_day: int) -> None:
        """Позиция ставится по сыгранному дню и только по успеху."""
        Variable.set(WORLD_POSITION, str(first_day + 1))
-        logging.info(
+        logging.info("сыгран день %s; новая позиция — %s", first_day, first_day + 1)
            "данные за модельный день %s отправлены; world_position=%s",
            first_day,
            first_day + 1,
        )
    first_day = first_unplayed_day()
    played = _generator("play_day", ["live", "--day", PLAYED_DAY])
@@ -260,12 +254,16 @@ def world_live_day():
    tags=TAGS,
 )
 def world_live():
-    """Автоматически запускать модельные дни, пока даг снят с паузы.
+    """Выключатель: пока включён, мир живёт день за днём.
-    Запускает `world_live_day` и ждет его завершения. Пауза останавливает
+    Своей работы у выключателя нет — он дёргает `world_live_day` и ждёт конца.
-    запуск следующих дней; уже запущенный день завершится. Если он завершился
+    Ожидание тут несущая конструкция, а не вежливость: без него тик шёл бы
-    с ошибкой, этот даг тоже завершится с ошибкой: откройте дочерний запуск
+    независимо от хода дня, лишние прогоны скопились бы очередью, и мир потом
-    и журнал неуспешной задачи.
+    промчался бы по ней без всякого темпа.
    Ждём триггером, а не сенсором: оператор опрашивает тот прогон, который сам
    и создал, и ссылка на дочерний прогон видна прямо отсюда. Упал день —
    краснеет и выключатель.
    """
    TriggerDagRunOperator(
        task_id="trigger_live_day",
@@ -3,11 +3,10 @@
 Дата: 9 августа 2026 года. Статус: принято; роль `monitoring_reader`
 и пользователь `grafana` добавлены 21 августа 2026 года (#114), права
 `bi_reader` расширены до ODS, DDS и DM 25 августа 2026 года (#150).
 Пользователь `student` и роль `student_writer` добавлены 22 сентября 2026 года.
 ## Решение
-У кластера восемь пользователей и семь ролей.
+У кластера семь пользователей и шесть ролей.
 - `default` — с паролем, только служебный: проверки здоровья нод и работа
  изнутри контейнеров. Приложения им не ходят.
@@ -21,10 +20,6 @@
  шире.
 - `analyst` с ролью `analyst_reader` — чтение всех слоёв и справочников. Им
  человек подключается снаружи, из своего клиента.
 - `student` с ролями `analyst_reader` и `student_writer` — то же чтение и
  работа со своими таблицами в `default`: создание, вставка и удаление.
  Сохранение учебных наблюдений не требует прав технической учётной записи
  `etl` на изменение слоёв. Таблицы локальные; работа ведётся на одной ноде.
 - `grafana` с ролью `monitoring_reader` — чтение слоёв, таблиц базы `dic` и
  системных таблиц, `CLUSTER` и `REMOTE`. Им ходит Grafana, и больше никто.
 - `dict` с ролью `dict_reader` — чтение одной базы `dic`, пароля нет. Им
@@ -153,11 +148,6 @@ DDL для матвью приёма выполняется от имени `lif
 ## Что проверено
 Права `student` сверены 22 сентября 2026 года через MCP Context7 и на стенде
 26.3.17.56: создание локальных `MergeTree`, `INSERT SELECT` из DDS и DM,
 чтение и удаление своих таблиц работают. На обеих нодах вставка в STG, ODS,
 DDS, DM и `dic` завершается `ACCESS_DENIED`.
 Сверено 9 августа 2026 года по документации ClickHouse через MCP Context7 и
 на живом стенде 26.3.17.56.
@@ -30,7 +30,7 @@
 `first_matched_at` нет. Запланированные витрины его не читают, а два возможных
 смысла — «первая покупка вообще» и «момент, с которого связь была известна
 хранилищу» — требуют разных исторических моделей. Этот вопрос оставлен
-[самостоятельной работе](../../labs/optional/identity-over-time.md),
+[самостоятельной работе](https://git.dementev.space/ddmitry/clickstream-data-platform/issues/145),
 а текущий стенд не выдаёт один смысл за другой.
 Статус заказа связь не меняет: любой заказ, сопоставленный с событием покупки,
@@ -1,113 +1,134 @@
 # Модель заказа в DDS
-DDS готовит заказ для анализа: выбирает текущее состояние из ODS,
+Учебный результат: менти проектирует бизнес-сущность поверх готового ODS —
-разбирает позиции и переводит время в часовой пояс счетчика. Этот слой
+выбирает зерно, состав строки и способ наполнения — и видит идемпотентность
-показывает, как собрать модель данных для витрин и повторить загрузку
+трансформации, устроенную иначе, чем в приёме: заменой партиции, а не
-без удвоения заказов.
+версиями.
 ## Зерно
-Одна строка — один заказ в последнем известном состоянии, ключ — `order_id`.
+Одна строка — заказ в текущем состоянии, ключ — `order_id`. Модель отвечает
-История изменений здесь не хранится. ODS тоже не служит ее архивом:
+на вопрос «что сейчас известно о заказе»; историю версий не хранит:
-промежуточные версии удаляются при фоновых слияниях.
+читателя у истории нет ни в одной витрине, а ODS её и не обещает —
 промежуточные версии съедают фоновые слияния. «Дыхание» выручки внутри окна
 K живёт на текущем состоянии само: пересборка дня меняет статусы заказов, и
 число дня меняется вместе с ними.
 ## Состав строки
-Поля заказа приходят из `ods.order_v` с именами источника: `order_id`,
+Деловые поля источника переезжают из `ods.order_v` без переименований —
-`user_id`, `status`, `items_total`, `discount`, `delivery`, `total`.
+бэкенд уже говорит в snake_case: `order_id`, `user_id`, `status`, деньги в
-Денежные колонки хранят рубли с копейками в `Decimal(18, 2)`.
+`Decimal` (`items_total`, `discount`, `delivery`, `total`).
-`created_at` и `updated_at` переводятся из UTC в `Europe/Samara`, пояс
+Времена `created_at` и `updated_at` пересчитываются при загрузке в пояс
-счетчика сайта. Из `created_at` в этом поясе вычисляется `order_date` —
+счётчика: DDS обслуживает человека с дашбордом ([дока
-день оформления заказа. Витрины группируют по готовой дате;
+хранилища](../storage.md), «Часовые пояса»). Там же один раз считается
-правило времени общее для [хранилища](../storage.md#часовые-пояса).
+**день заказа** — колонка `order_date`, по образцу `EventDate` у события:
 суточные срезы группируются по готовой дате и пояса не упоминают.
-Строка `items` из ODS разбирается в три массива одной длины:
+Позиции разобраны из сырой строки `items` в три типизированных массива
-
+одной длины — артикул, количество, цена (`Decimal`). Это родная для
-| Колонка | Что хранит |
+ClickHouse денормализация: позиция не живёт без заказа и собственного ключа
-|---|---|
+не имеет, а разворачивает массивы читатель — `ARRAY JOIN` в витрине
-| `item_sku` | Артикулы товаров |
+выручки, с обогащением категорией через `dictGet`
-| `item_quantity` | Количество каждого товара, `UInt32` |
+([мастер-спека](../../specs/2026-07-30-stand-v2-realism.md), раздел 7). Разбор
-| `item_price` | Цены за единицу в рублях, `Decimal(18, 2)` |
+JSON происходит один раз, на границе ODS → DDS, куда его и положила спека
-
+(раздел 2); записывать его параллельными колонками-массивами или `Nested` —
-Элементы с одинаковым номером описывают одну позицию заказа. Витрина
+выбор DDL, не модели.
 выручки разворачивает их через `ARRAY JOIN` и получает категорию товара
 из справочника через `dictGet`. Разбор JSON выполняется один раз
 при загрузке DDS.
 ODS проверяет только то, что `items` — массив. Разбор в DDS не заменяет
 проверку его содержимого: например, некорректное количество может стать
 нулем. Проверку суммы позиций участник добавляет в
 [первом задании ступени 5](../../labs/5-1-order-checks.md).
 ## Движок и наполнение
-`dds.order_rep` — таблица на `ReplicatedMergeTree`, без колонки версии.
+`dds.order_rep` — `ReplicatedMergeTree` без колонки версии: партиция —
-Партиция хранит один `order_date`, ключ сортировки — `order_id`.
+`order_date` (день заказа неизменен), ключ сортировки — `order_id`.
-Запись через `dds.order_dist` распределяет заказы по `cityHash64(order_id)`,
+`dds.order_dist` шардирует по `cityHash64(order_id)`, тем же выражением, что
-как в ODS. Для чтения служит `dds.order_v` с явным списком колонок
+ODS: это единственный устойчивый ключ сущности.
 над `dds.order_dist`; `FINAL` в этом слое не нужен.
-Даг `dds_transform` пересобирает выбранные дни из `ods.order_v`:
+Идемпотентность держит замена партиции, а не версии. Сбор дня — батч после
 прихода слепка: трансформация собирает партицию заново из `ods.order_v` и
 атомарно подменяет. Поэтому каждая строка физической таблицы — ровно один
 заказ, а чтению не нужен `FINAL`. Пока окно K живо, день «дышит» — статусы
 заказов меняются, и партиция дня пересобирается очередным запуском; на выходе
 из окна день замерзает.
-1. [`order_scope.sql`](../../../sql/dds/order_scope.sql) определяет
+Публичная поверхность — `dds.order_v`: обычное представление с явным списком
-   непрерывный отрезок `first_day`…`last_day`. Он включает дни заказов
+деловых и собственных служебных колонок над `dds.order_dist`, без `FINAL`.
-   из последнего слепка и начинается раньше, если в DDS отсутствует
+Роли объектов и доступ следуют общей [конвенции](../storage.md), «Имена
-   день, который есть в ODS.
+объектов».
 2. [`order_rebuild.sql`](../../../sql/dds/order_rebuild.sql) очищает
   промежуточную таблицу `dds.order_stage_rep` и наполняет ее через
   `dds.order_stage_dist`. Это донор: в нем готовится результат,
   пока основная таблица остается доступной для чтения.
 3. [`order_replace.sql`](../../../sql/dds/order_replace.sql) заменяет
   каждую дневную партицию основной таблицы готовой партицией донора.
-Повтор при неизменном ODS дает те же деловые данные без дублей —
+Механика запуска — где собирается партиция и как подменяется на кластере —
-это идемпотентность загрузки. Пока заказы дня входят в семидневное окно
+сюда не входит: это устройство [дневного конвейера](../etl.md).
 источника, их состояние может меняться, и день пересобирается.
 За пределами окна новые состояния не приходят, но пропущенный день
 можно восстановить из ODS. Границы пересборки берутся из данных;
 число семь в SQL хранилища не повторяется.
 Замена атомарна внутри одного шарда: читатель видит прежнюю или новую
 партицию целиком. Замены на двух шардах независимы, поэтому между ними
 запрос через Distributed может увидеть смешанный результат.
 Донор остается до следующей сборки и доступен для диагностики.
 Порядок задач и повторы — в [описании дневного конвейера](../etl.md).
 ## Служебные колонки
-`_load_id` и `_load_ts` показывают, какой запуск DDS собрал строку
+Строка получает `_load_id` и `_load_ts` запуска трансформации, собравшего
-и когда он выполнил вставку. Они одинаковы у строк одной сборки.
+её партицию, — по общей конвенции хранилища. При замене партиции они
-При следующей пересборке эти метки обновятся, даже если заказ не изменился.
+одинаковы у всех строк дня и отвечают на вопрос «каким запуском и когда
 собран этот день».
-`snapshot_date` и метки приема ODS в DDS не переносятся: они описывают
+Ярлыки ODS (`snapshot_date`, `_load_id` приёма, `_load_ts` прибытия) в модель
-получение сообщения источника. Их можно найти в ODS по `order_id`.
+не переезжают. Они описывают наблюдение и доставку строки в ODS. Модель DDS
-В каждом слое служебные колонки относятся к его собственной загрузке.
+хранит текущее деловое состояние заказа. В ODS `snapshot_date` задаёт версию и
 называет последний слепок, в котором источник показал заказ
 ([ADR 0014](../../adr/0014-order-version-snapshot-date.md)). Дату
 наблюдения и координаты доставки читатель спрашивает у ODS по
 `order_id`. Правило слоя:
 **служебные колонки — координаты собственной загрузки слоя; чужие координаты
 спрашиваются у их слоя по ключу сущности**.
-При поиске ошибки начните с `_load_id` в DDS: он указывает на запуск
+Происшествие качества данных расследуется цепочкой, где каждый шаг спрашивает
-сборки. По `order_id` найдите версии заказа в ODS, а по их `_load_id` —
+свой слой на его языке: по `_load_id` строки DDS видно, какой запуск собрал
-соответствующие сырые сообщения в STG и ошибки того же приема.
+день; по `order_id` ODS показывает физические версии и брак — там свой
-В таблице ошибок `order_id` может быть не разобран, поэтому нужное
+`_load_id` приёма связывает годные строки, ошибки и данные STG; дальше читают
-сообщение ищут по `raw` и координатам Kafka.
+STG, пока данные живы. Окно расследования задано сроками хранения: сырые данные
-Сырые сообщения хранятся около трех реальных суток, ошибки — месяц;
+— трое суток, брак — месяц ([дока хранилища](../storage.md)).
 уточнения к срокам — в [справочнике хранилища](../storage.md#срок-жизни-сырых-данных).
 ## Читатели
- `dm.revenue_daily_v` считает выручку по заказам со статусом `paid`,
+- Витрина выручки `dm.revenue_daily_v`: заказы в `paid`, `ARRAY JOIN`
-  разворачивает позиции и дополняет их категорией товара.
+  позиций, категория через `dictGet` (спека, раздел 7).
- `dm.purchase_vs_orders_v` сопоставляет заказ с покупкой на сайте
+- Сверка `dm.purchase_vs_orders_v`: `order_id`, `order_date`, `items_total`,
-  по `order_id`, используя `order_date`, `items_total` и `status`.
+  `status`; соединение — GLOBAL JOIN с обеими сторонами-подзапросами
- `dds.identity_map` связывает идентификаторы посетителей с `user_id`
+  ([исследование соединений](../../research/2026-08-22-distributed-join.md)).
-  через покупки и заказы.
+- Сборка карты идентичностей: пара `order_id` ↔ `user_id`, источник —
  `dds.order_v`.
 ## Не входит
 - Механика запуска трансформации и замены партиций на кластере —
  [дневной конвейер](../etl.md).
 - Контур проверок качества (даг DQ, `dm.dq_summary`) — отдельный разговор
  этапа 4.
 - Инкрементальное наполнение вместо пересборки — техдолг #2.
 ## Отклонённые варианты
 - **Одно динамическое представление вместо физической таблицы.** Рамка стенда —
  показать модель данных, которую хранилище готовит потребителям; урок
  «слой — контракт, а не копия» уже закреплён за `dds.event_v`, а разбор
  позиций и пересчёт времён при каждом чтении собирали бы модель заново на
  лету. Публичное `dds.order_v` поверх готовой физической модели этому доводу
  не противоречит: оно ничего заново не вычисляет.
 - **`ReplacingMergeTree` ещё раз.** Повторил бы механику ODS вторым разом:
  физически хранил бы устаревшие состояния, вернул бы `FINAL`
  и обёртку-представление — а урок версий менти уже отыграл.
 - **Отдельная сущность `dds.order_item`.** Вторая таблица, второй вопрос
  шардирования и `JOIN` там, где хватает `ARRAY JOIN`; нормализация из
  реляционного мира, а не модель под колоночное хранилище. `JOIN` менти
  увидит в сверке, работу с массивами — только здесь.
 - **Зерно «версия заказа» (история).** Читателя нет; ODS историю не
  обещает, а мир при нужде переигрывается генератором.
 - **Перенос ярлыков ODS** — см. «Служебные колонки».
 - **Без модели вовсе: витрины читают `ods.order_v` напрямую.** Разбор JSON
  и пересчёт времён расползлись бы по витринам, а модель данных — то, ради
  чего сущность и строится, — не была бы показана.
 ## Связанные решения
- [ADR 0010](../../adr/0010-order-versions-in-ods.md) — версии заказов в ODS
+- [ADR 0010](../../adr/0010-order-versions-in-ods.md) — версии заказов в
-  и чтение через `ods.order_v`.
+  ODS, устойчивая поверхность `ods.order_v`.
- [Прием заказов](../orders/ingestion.md) — проверки формата и выбор
+- [Приём заказов](../orders/ingestion.md) — граница строгого приёма и
-  актуальной версии.
+  четыре координаты строки ODS.
- [Исследование соединений](../../research/2026-08-22-distributed-join.md) —
+- [Проталкивание условий сквозь
-  почему сверка распределенных источников использует `GLOBAL JOIN`.
+  представления](../../research/2026-08-22-view-predicate-pushdown.md) —
- [Проталкивание условий сквозь представления](../../research/2026-08-22-view-predicate-pushdown.md) —
+  резолюция #128 той же карты: цена `FINAL` и цепочек представлений, фон, на
-  как фильтр запроса влияет на объем чтения ODS.
+  котором здесь выбрана физическая таблица.
@@ -1,124 +1,117 @@
 # Модель сессии в DDS
-Сессия объединяет события одного визита. На стенде вы учитесь определять
+Учебный результат: менти строит расчётную сущность, которой нет в потоке, —
-ее границы по событиям, вычислять устойчивый идентификатор и сверять
+режет события на сессии по правилу визита, чеканит идентификатор и сверяет
-результат с эталоном. Поэтому сборка читает `dds.event_v`, где нет готового
+свою нарезку с эталоном. Стенд здесь играет роль сессионизатора: в бою её
-`VisitID`. Этот идентификатор источника остается в ODS для проверки.
+играет Метрика, которая режет визиты у себя и с октября 2025 отдаёт готовый
 `VisitID` прямо в хитах. Поэтому стенд считает сессии сам, а `VisitID`
 генератора использует только как эталон самопроверки — иначе сборка сессий
 выродилась бы в `GROUP BY` по чужому полю и центральный урок
 слоя пропал бы. Без этого абзаца действия стенда выглядят странно: «зачем
 считать то, что уже дано колонкой».
 ## Зерно
-Зерно описывает, чему соответствует одна строка: здесь это один
+Одна строка — один визит ([CONTEXT.md](../../../CONTEXT.md)): подряд идущие
-[визит](../../../CONTEXT.md#люди-и-события). В него входят подряд идущие
+события одной куки без пауз длиннее 30 минут, не пересекающие границу суток.
-события одного `client_id` без пауз длиннее 30 минут и без перехода через
+В нарезку входят все три типа событий — торговые садятся на свои страницы
-модельную полночь. Пауза ровно в 30 минут новую сессию не открывает.
+и держат сессию наравне с просмотрами. События внутри сессии
-Учитываются все три типа событий: `pageview`, `add_to_cart`, `purchase`.
+упорядочиваются по метке времени события (`UTCEventTime` — опорная колонка
 приёма).
-День сессии `session_date` берется из `event_date` событий DDS — это
+Граница суток проходит по модельному дню счётчика, и он у события уже есть:
-`EventDate` источника, дата по часовому поясу счетчика. У всех событий
+`EventDate` — свойство содержимого. Раз сессия сутки не пересекает, у всех
-одной сессии она одинакова. Пересчитывать ее из времени UTC не нужно.
+её событий `EventDate` один; он и становится **днём сессии** — колонкой
-
+партиции, без пересчёта.
 SQL рассчитывает границы визитов двумя оконными функциями: первая отмечает
 начало нового визита, вторая по этим отметкам присваивает событиям номер
 визита. Обе используют порядок `(event_time, event_id)`: при равном времени
 события идут по идентификатору. Иначе два расчета могли бы по-разному
 упорядочить события и отнести отметку начала к разным строкам.
 ## Идентификатор
-`session_id` вычисляется как `cityHash64(client_id, min(event_time))`.
+Идентификатор сессии в природе не существует: сессия — расчётная сущность,
-При повторной сборке тех же событий посетитель и начало визита остаются
+и id ей чеканит тот, кто сессионизирует. `VisitID` — такой же суррогат,
-прежними, поэтому идентификатор не меняется. Счетчик или случайный UUID
+отчеканенный генератором в роли Метрики; наш — `session_id`,
-выдали бы другие значения.
+детерминированный хеш от пары «кука + начало сессии» (`cityHash64`).
 Детерминированность обязательна: партиция дня пересобирается заменой, и
 повторный прогон обязан отчеканить те же id — счётчик или UUID это правило
 ломают.
-По `session_id` можно сопоставить сессии до и после пересборки и назвать
+`session_id` — не ключ сортировки и не ключ шардирования, а колонка-ручка:
-конкретную строку при разборе расхождения. Он не используется для сортировки
+в соединениях он не участвует — события его не несут, мост к заказам живёт
-или шардирования. У событий этого поля нет; связь с заказами строится
+на событиях. Читатели ручки — лаба сессий (сопоставить свою нарезку со
-по событиям покупки.
+стендовой и назвать расхождение одним числом) и разбор DQ-расхождений.
 ## Состав строки
- `client_id`, `session_id`, `session_date` — посетитель, сессия и ее день.
+Боевой образец — таблица визитов Метрики, парная к нашему формату хита; по
- `started_at`, `finished_at`, `duration_seconds` — время первого и последнего
+ней состав и собран:
  события и разница между ними в секундах. Времена хранятся в часовом поясе
  счетчика.
 - `events_total`, `pageviews`, `cart_adds`, `purchases` — число всех событий
  и счетчики трех типов.
 - `entry_url`, `exit_url` — страницы первого и последнего события.
 - `utm_*` — метки первого события: по ним визит относят к рекламной кампании.
 - `device_category`, `region_city` — устройство и город посетителя.
  На стенде они постоянны для одной куки.
 - `_load_id`, `_load_ts` — идентификатор запуска и время сборки строки.
-В готовом SQL страницы выбираются через `argMin` и `argMax`, а UTM,
+- **ключи и времена**: кука, `session_id`, начало и конец сессии,
-устройство и город — через `argMin`, только по `event_time`. При одинаковом
+  длительность, день сессии. Времена — в поясе счётчика по правилу слоя;
-времени выбор между событиями не определен. Полный порядок окон нарезки
+- **счётчики**: событий всего, просмотров, корзин, покупок;
-сам по себе эту неоднозначность не устраняет. Это ограничение учитывается
+- **страницы**: входная и выходная — как `StartURL`/`EndURL` визита; полного
-в [задании ступени 4](../../labs/4-1-session-pipeline.md).
+  списка страниц нет и у Метрики, топы считаются по событиям;
 - **атрибуция**: UTM-метки первого события сессии — так визит атрибутирует
  Метрика. В v1 витрина брала последнее касание — заменено осознанно;
 - **паспорт куки**: категория устройства (расшифрованная, язык бизнес-модели)
  и город — у куки они постоянны, берутся с первого события;
 - **служебные**: `_load_id` и `_load_ts` собравшего запуска — правило слоя
  ([модель заказа](order.md), «Служебные колонки»).
-В сессии нет суммы выручки: ее считают по заказам магазина. Клиентская
+Осознанные расхождения с образцом: **денег в сессии нет** — визит Метрики
-сумма покупки используется в сверке с заказами и в учебной UTM-витрине.
+несёт клиентскую выручку, у нас деньги считает только бэкенд (спека, раздел
 7), а клиентская сумма живёт в сверке; **целей нет** — их место заняли
 счётчики торговых событий.
 ## Движок и наполнение
-`dds.session_rep` хранит готовые сессии в `ReplicatedMergeTree` без колонки
+`dds.session_rep` — `ReplicatedMergeTree` без колонки версии, по образцу
-версии. При чтении не нужно заново выполнять оконный расчет. Партиция —
+заказа: партиция — день сессии, ключ сортировки — кука и начало сессии.
-раздел таблицы за один `session_date`; ключ сортировки — посетитель
+`dds.session_dist` шардирует по `cityHash64(client_id)`, тем же выражением,
-и начало сессии. Читайте результат через `dds.session_v`: представление
+что события, — это ко-локация с `dds.identity_map_rep` ([дока
-над `dds.session_dist` явно перечисляет деловые и служебные колонки.
+хранилища](../storage.md), «Раскладка по шардам»).
 Совпадение ключа с событиями не случайно: все события куки лежат на одном
 шарде, поэтому сессионизация локальна по природе — капкан смены ключа при
 вставке, который дока хранилища обещает сборкам DDS, у сессий не стреляет.
-Источник сборки — `dds.event_v`. События, сессии и карта идентичностей
+Сборка — дневной батч: хранилище выше ODS по смыслу батчевое, раз второй
-распределены по одному ключу `cityHash64(client_id)`: данные посетителя
+источник приходит раз в сутки. Собирается день, который мир уже прожил, и
-находятся на одном шарде. Роли объектов и правило записи через `_dist`
+собирается один раз и целиком; какой день прожит, слой спрашивает у позиции
-описаны в [справочнике хранилища](../storage.md#раскладка-по-шардам).
+мира ([дневной конвейер](../etl.md), «Объём прогона»). Идемпотентность держит
 замена партиции. В отличие от заказов, где батч пересобирает до K «дышащих»
 дней, у сессии дышащего окна нет: прожитый день самодостаточен (правило
 спеки, раздел 6). Второй раз он соберётся только
 вынужденно — когда упавшая замена оставила позади дыру и хвост от неё накрыл
 соседние дни. Дней в одном прогоне при этом бывает несколько — столько,
 сколько мир успел прожить без слоя. Внутри живого дня
 модель сессии про сегодня честно молчит — «сегодня» смотрят через
 `dds.event_v`; сессия и по смыслу не финальна, пока день не прожит.
-Три SQL-файла выполняются последовательно в группе `session` дага
+Публичная поверхность — `dds.session_v`: обычное представление с явным
-`dds_transform`:
+списком деловых и собственных служебных колонок над `dds.session_dist`.
 Роли объектов и доступ следуют общей [конвенции](../storage.md), «Имена
 объектов».
-1. `session_scope.sql` находит первую дату событий, за которую еще нет
+Источник сборки — `dds.event_v` ([контракт события](event.md)): сессии
-   сессий. Последний день для расчета — первый день событий ODS
+нужны от него ключи нарезки, тип события, страница, UTM и паспорт куки.
-   плюс `world_position` минус один; `world_position` — номер следующего
+Механика запуска — где собирается партиция и как подменяется на кластере —
-   дня для генерации. Так в расчет попадают только полностью
+не входит: это устройство [дневного конвейера](../etl.md).
   прожитые дни. При пустом ODS запрос не возвращает строк и задача падает;
   если пропущенных прожитых дней нет, `first_day` равен `NULL` и группа
   пропускается.
 2. `session_rebuild.sql` очищает промежуточную таблицу
   `dds.session_stage_rep`. Затем рассчитывает сессии выбранных дней
   и записывает строки через `dds.session_stage_dist`. Пока идет расчет,
   в основной таблице остаются прежние данные. Вставка ждет доставки
   строк на шарды благодаря `distributed_foreground_insert = 1`.
 3. `session_replace.sql` заменяет в `dds.session_rep` раздел за каждый
   выбранный день готовым разделом `dds.session_stage_rep`. Для каждого
   дня Airflow создает отдельную задачу `replace`.
 Когда все события завершенного дня приняты в ODS, их набор на стенде
 больше не меняется. Поэтому готовые сессии обычно не пересчитываются. Если пропущен ранний
 день, диапазон включает и все последующие прожитые дни, даже уже собранные.
 Если за день сохранилась хотя бы одна сессия, поиск пропущенных дней
 не обнаружит потерю остальных. Условия повторного запуска и замены
 разделов описаны в [справочнике конвейера](../etl.md#идемпотентность).
 Сессий еще идущего дня в модели нет; его события доступны через
 `dds.event_v`. Перед выбором дней даг ждет завершения доставки событий
 в ODS — см. [готовность источника](../etl.md#готовность-источника).
 ## Сверка с эталоном
-Проверка `sessions_vs_reference` в `dq_check` сравнивает для каждого
+Счётная DQ-проверка с зерном «кука × день»: число сессий нашей нарезки
-посетителя и дня число строк `dds.session_v` с `uniqExact(VisitID)`
+равно `uniqExact(VisitID)` по тем же событиям. Счёт по Distributed ловит и
-из `ods.event_v`. Эталон читается из ODS, потому что `dds.event_v`
+склеенную, и разрезанную сессию — мимо него проходит лишь взаимная
-скрывает `VisitID`.
+компенсация ошибок внутри одной куки за день; эталон в модель не тащим —
-
+строка сессии остаётся нашей, а не генераторной. Поштучное сопоставление
-Нулевое число расхождений подтверждает только число сессий каждого
+границ — материал лабы, где менти разбирает найденное расхождение руками. Дом проверки —
-посетителя за день. Например, ошибочное объединение двух визитов
+контур DQ этапа 4. Сверке нужен `VisitID`, а сборке сессий — нет; контракт
-и разделение другого на два сохранят их общее число. Поэтому в заданиях
+`dds.event_v` его скрывает, и за эталоном проверка идёт в `ods.event_v`
-вы дополнительно сопоставляете границы сессий по исходным событиям и проверяете страницы,
+([контракт события](event.md)).
 UTM, устройство и город.
 ## Читатели
 - Витрина обзора сессий `session_overview_v`: дневные итоги визитов в
  срезе устройств; читает `dds.session_v` и поднимает зерно до дня — состав и довод
-  в ее [ТЗ](../../labs/1-3-session-overview.md) (#135).
+  в ее [ТЗ](../../labs/session-overview.md) (#135).
 - DQ-сверка с эталоном (см. выше).
 - Лаба сессий: менти собирает нарезку сам до знакомства с кодом стенда,
  потом сравнивает — с эталоном и со стендовой.
@@ -1,202 +1,176 @@
 # Слой DM: витрины
-Витрины готовят данные DDS для отчетов и дашбордов. Здесь описаны форма
+Как модель DDS превращается в витрины для потребителя BI: какую форму
-хранения, правила обновления и проверки. Состав колонок задан в
+принимает витрина, кто какие витрины строит и как слой проверяется. Состав
-[спецификации](../specs/2026-07-30-stand-v2-realism.md#витрины-dm)
+колонок каждой витрины задаёт раздел 7 мастер-спеки; здесь — форма,
-и [учебных заданиях](../labs/README.md).
+наполнение и контроль.
-## Таблица или представление
+## Форма: по зерну, не по цене запроса
-Зерно — то, чему соответствует одна строка. Например, в заказах это заказ,
+Витрина, меняющая зерно источника — дневной агрегат, сверка по заказам, —
-а в дневной выручке — день и категория товара. На стенде результат
+материализуется: `dm.<имя>_rep` / `_dist` и публичное `dm.<имя>_v` с явным
-с новым зерном хранится в таблице: отчет читает готовые итоги без
+списком колонок, по общим [конвенциям хранилища](storage.md). Наполняет её
-повторного расчета. Таблицу наполняет `dm_transform`.
+`dm_transform`; ритм и механика пересборки — ниже. Витрина, сохраняющая зерно
 источника — переименование, обогащение строки, — остаётся обычным
 представлением: копию событий ради других имён колонок не держит ни один
 боевой склад.
-У такой витрины есть локальная `_rep`, распределенная `_dist` и публичное
+Правило выбрано учебной целью, а не ценой запроса. На объёмах стенда
-представление `_v` с явным списком колонок. Для обновления по дням
+представлениями обошлось бы всё: условия сквозь цепочку представлений
-нужна промежуточная таблица `_stage_rep`, в которую пишут через `_stage_dist`.
+проходят ([исследование](../research/2026-08-22-view-predicate-pushdown.md)).
-В нее записывают рассчитанные строки, пока основная таблица хранит прежние.
+Но пересборка агрегатов конвейером — производственный паттерн, ради
-Затем дневные разделы основной таблицы заменяют готовыми разделами
+которого стенд и строится, а пара «таблица рядом с представлением»
-промежуточной. Такие разделы называются партициями. Подробности — в
+показывает: форма — решение по роли витрины, у одного слоя законны обе.
 [справочнике хранилища](storage.md#имена-объектов).
-Если запрос только переименовывает или дополняет поля и сохраняет одну
+## Кто строит: стенд и менти
 строку на событие, достаточно обычного представления. Оно выполняет
 запрос при чтении, не хранит вторую копию событий и не требует пересборки.
-На небольших данных стенда и агрегаты могли бы вычисляться при чтении
+Стенд привозит готовыми витрины трёх сюжетов дашборда этапа 8 и
-([исследование](../research/2026-08-22-view-predicate-pushdown.md)).
+инфраструктуру контроля:
 Готовые таблицы нужны в программе для практики загрузки, обновления
 и включения витрин в конвейер.
-## Что готово в стенде, а что остаётся заданием
+- `revenue_daily` — выручка по дням и категориям; образец материализованной
  витрины, на него ссылаются учебные задания;
 - `purchase_vs_orders` — сверка A+C с классами расхождений; зерно — заказ,
  шардирование сохраняет ко-локацию заказов по `cityHash64(order_id)`;
 - `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).
- `revenue_daily` — одна строка на день заказа и категорию товара;
+Дашборд этапа 8 стоит только на витринах стенда: приёмка этапа не зависит
-  образец дневной пересборки для учебных заданий.
+от выполненных домашек. Свой дашборд по витринам менти —
- `purchase_vs_orders` — одна строка на заказ: сопоставление покупки
+[необязательная лаба](../labs/superset-dashboard.md) после этапа 8. Устройство
-  из кликстрима с заказом магазина и класс расхождения.
+стендового дашборда — в [доке зоны Superset](superset.md).
 - `daily_traffic` — одна строка на день: число посетителей и известных
  пользователей с учетом [карты идентичностей](dds/identity.md).
 - `dq_summary` — одна строка на день данных и проверку качества.
 В [заданиях ступени 1](../labs/README.md) вы строите `events_enriched_v`,
 `top_pages_daily`, `session_overview`, `dq_errors_daily` и `utm_effectiveness`.
 Для каждой физической витрины нужно добавить сборку в `dm_transform`.
 Представление `events_enriched_v` отдельной задачи не требует.
 Стендовый дашборд читает готовые витрины и работает до выполнения заданий.
 Дашборд по своим витринам можно собрать в
 [факультативе](../labs/optional/superset-dashboard.md) после ступени 2.
 Устройство стендового дашборда — в [справочнике Superset](superset.md).
 ## Ритм пересборки
-Дни для пересчета выбирают по тому, как меняется источник:
+День витрины пересобирается, пока может измениться его источник, —
 поэтому ритмов три, по числу источников:
- События и сессии прожитого дня на стенде больше не меняются. Витрины
+- **от событий и сессий** — день замерзает сразу; пересборка догоняет
-  по ним рассчитывают показатели от первого пропущенного дня до последнего
+  хвост несобранных дней заменой дневных партиций;
-  прожитого и заменяют дневные партиции.
+- **от заказов** — день дышит, пока входит в последний слепок; пересборка
- Заказы могут меняться в течение семи модельных дней. Последний слепок ODS
+  заменяет партиции этого отрезка, дни за ним закрыты по построению;
-  задает диапазон дат для пересборки; пропущенные дни могут расширить его.
+- **от карты идентичностей** — не замерзает никогда: склейка
- Новая связь в карте идентичностей позволяет определить пользователя
+  ретроспективна, покупка сегодня делает куку известной во всех её прошлых
-  по его прежним визитам: один `client_id` мог встречаться и до покупки,
+  днях, а карта пересчитывается целиком.
  которая связала его с `user_id`.
  Поэтому `daily_traffic`, как и карта, пересчитывается целиком.
-`daily_traffic` каждый раз добавляет всю историю новой версией
+Поэтому `daily_traffic` наследует у своего источника и ритм, и механику:
-в `ReplacingMergeTree(_load_ts)`. Дневных партиций у нее нет, а текущие
+полный пересчёт всех дней каждый прогон в `ReplacingMergeTree(_load_ts)`,
-строки выбирает представление через `FINAL`.
+как у самой карты. Дневных партиций у неё нет: партиция — единица замены,
 а эта витрина заменяется только целиком. На стенде такая работа остается
 быстрой; витрина читает сессии и карту через их публичные договоры.
 Пересчитывать точечно только затронутые дни не из чего: для этого надо
 знать, какие связки новые, а полный пересчёт карты этот след затирает —
 восстановление следа оставлено лабе повышенной сложности (issue #149).
-У `purchase_vs_orders` два источника. Начало диапазона — самая ранняя
+У `purchase_vs_orders` два источника и одна непрерывная пересборка. Заказная
-из трех дат: первая дата оформления заказа в последнем слепке, первый
+сторона задает изменяемое окно последним принятым слепком ODS, событийная —
-пропущенный день и первый день с `awaiting_order` — покупкой, для которой
+последний прожитый день с `purchase`. Левая граница возвращает первую дыру и
-заказ пока не поступил. День ожидания проверяется отдельно: строки за него
+самый ранний день с `awaiting_order`: предварительная строка уже есть в
-уже есть в витрине, поэтому он не считается пропущенным.
+витрине, поэтому поиск отсутствующего дня ее не заметит. Правая граница
-Конец диапазона — более поздняя из последней даты заказов в слепке и последнего
+доходит до более позднего из двух хвостов. Так один прогон догоняет пакетный
-прожитого дня с покупкой. Один запуск пересобирает весь отрезок,
+разгон длиннее K и не оставляет старое ожидание замороженным.
 даже если с предыдущего запуска прошло больше семи модельных дней.
 Для учебной сводки брака действует отдельное правило: дни выбираются
 по времени загрузки, а прежние итоги сохраняются после удаления
 источника по TTL. Оно разобрано в
 [задании `dq_errors_daily`](../labs/1-4-dq-errors-daily.md).
 ## Витрины стенда
-Представления `_v` явно перечисляют поля для отчетов, а также `_load_id`
+Публичные представления перечисляют деловые колонки и координаты запуска
-и `_load_ts` — идентификатор запуска и время записи. Новая колонка
+`_load_id`, `_load_ts` явно. Новая колонка физической таблицы сама в договор не
-физической таблицы появится в представлении только после изменения его SQL.
+попадет.
 ### `dm.revenue_daily_v`
-Одна строка содержит итоги оплаченных заказов за день по категории товара.
+Зерно: день заказа × категория товара. Витрина читает только оплаченные
-Запрос читает `dds.order_v` и разворачивает массивы артикулов, количеств
+заказы из `dds.order_v`, синхронно разворачивает три массива позиций и узнает
-и цен в строки позиций заказа. Артикул, количество и цена с одним индексом
+категорию артикула через `dic.products`. Один заказ с несколькими позициями
-становятся одной строкой. Категория артикула берется из `dic.products`.
+категории считается в `orders` один раз. `units` складывает количество единиц,
 `revenue` складывает цену позиции × количество. Скидка, доставка и итог заказа
 между категориями не делятся. `aov` равен `revenue / orders` в том же срезе и
 хранит два знака после запятой.
-`orders` считает разные заказы: несколько позиций одной категории
+Первый запуск строит всю доступную историю. Следующие берут границы дней из
-в заказе не увеличивают этот счетчик. `units` — сумма количества товаров,
+последнего слепка ODS: только источник знает, какие даты еще может изменить.
-`revenue` — сумма произведений цены на количество. Скидка и доставка
+Пропущенный оплаченный день расширяет левую границу, чтобы частичный отказ
-в нее не входят. `aov` равен `revenue / orders` для того же дня и категории
+не оставил дыру после следующего прогона. Агрегат при этом читает DDS; ODS
-с округлением до двух знаков после запятой.
+отвечает только на вопрос об объеме.
-Первый запуск рассчитывает выручку за всю доступную историю. Следующие
+`dm.revenue_daily_rep` нарезана по `report_date`; день собирается в
-берут диапазон дат оформления заказов из последнего слепка ODS.
+таблице-доноре и заменяется через `REPLACE PARTITION`. Цель и донор шардируются
-Если в DDS есть оплаченные заказы за день, отсутствующий в витрине,
+по `cityHash64(product_category)`. Кроме дня, у витрины только категория, а
-левая граница расширяется до него. Агрегат читает DDS; ODS отвечает
+шесть категорий стартового мира близки по объему. Более сложный составной ключ
-только на вопрос об объеме.
+распределил бы эту маленькую таблицу без нового урока.
 В группе `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_rep`, рассчитывает показатели за выбранные
   дни и записывает строки через `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]`:
+`purchase_id[1]`: контракт источника обещает один номер и одну объявленную
-по формату источника у покупки один номер и одна заявленная сумма.
+сумму, а отдельный счет событий оставляет класс `duplicate_event`
-Отдельный счет событий позволяет обнаружить повтор покупки
+наблюдаемым. Заказы приходят из `dds.order_v`. Обе стороны записаны
-и присвоить класс `duplicate_event`. Заказы берутся из `dds.order_v`.
+подзапросами, затем соединены `FULL OUTER GLOBAL JOIN`: голая левая
-
+Distributed-таблица вернула бы каждый непарный заказ по разу с каждого шарда
 Полное соединение `FULL OUTER GLOBAL JOIN` сохраняет и покупки без заказа,
 и заказы без покупки. Обе стороны записаны подзапросами: при прямом чтении
 левой Distributed-таблицы каждый непарный заказ повторился бы по числу шардов
 ([исследование](../research/2026-08-22-distributed-join.md)).
-Если для строки нет пары, поля отсутствующей стороны получают `NULL`
+Непарная сторона остается `NULL` благодаря `join_use_nulls = 1`. При
-благодаря `join_use_nulls = 1`. При `join_use_nulls = 0` они заполнились бы
+`join_use_nulls = 0` ClickHouse заполнил бы ее нулем или пустой строкой и скрыл
-нулями или пустыми строками, которые сложнее отличить от данных источника.
+отсутствие источника. Клиентская `declared_revenue` и серверная `items_total`
-Клиентская `declared_revenue` и серверная `items_total` сравниваются
+сравниваются как `Decimal(18, 2)`. Классы проверяются по порядку:
 как `Decimal(18, 2)`. Классы проверяются по порядку:
 `awaiting_order` для покупки без заказа, затем `cancelled`, `lost_event`,
 `duplicate_event`, `amount_delta`, `match`. Поэтому отмененный заказ без
 события остается отмененным, а не потерянным.
-Партиции витрины разделены по `order_day`. Основная и промежуточная таблицы
+Витрина нарезана по `order_day`, цель и донор шардируются по
-распределяют строки по `cityHash64(order_id)`. Запрос рассчитывает весь
+`cityHash64(order_id)`. Диапазон собирается в доноре одной вставкой и
-выбранный диапазон и одной вставкой записывает строки в промежуточную
+заменяется по дням. Первичная сборка охватывает всю историю обоих источников;
-таблицу. Затем ее дневные разделы заменяют разделы основной таблицы.
+следующие прогоны идут по двустороннему ритму, описанному выше.
 Первичная сборка охватывает всю историю обоих источников;
 следующие прогоны выбирают дни по правилам обоих источников, описанным выше.
 ### `dm.daily_traffic_v`
 В строке один день. `visitors` считает разные `client_id` из
 `dds.session_v`; `known_users` считает разные `user_id` после левого соединения
 с полной текущей `dds.identity_map_v`. Анонимная сессия остается в витрине.
-Несколько кук, связанных с одним пользователем магазина, учитываются
+Несколько кук одного человека увеличивают `visitors`, но дают одного
-в `visitors` по отдельности, а в `known_users` дают одного пользователя.
+`known_user`, поэтому `known_users <= visitors`.
 Поэтому `known_users <= visitors`.
-Сессии и карта распределены по `client_id`. Однако на ClickHouse 26.3
+Сессии и карта лежат по `client_id`, но публичные `_v` скрывают
-чтение через публичные `_v` с `distributed_product_mode = 'local'`
+`Distributed`-таблицы от локальной подстановки. На ClickHouse 26.3
-не дало локального соединения. Поэтому в запросе явно указан
+`EXPLAIN PLAN` показал чтение обоих шардов на инициаторе: настройка
-`GLOBAL LEFT JOIN`. Он сохраняет сессии без известного пользователя;
+`distributed_product_mode = 'local'` локального соединения не дала. Поэтому
-в `known_users` учитываются только ненулевые `user_id`.
+витрина использует явный `GLOBAL LEFT JOIN` через публичные договоры, а не
-Обновление всей истории новой версией описано в разделе
+подменяет их физическими таблицами. Это дороже по сети, зато граница слоев
-[«Ритм пересборки»](#ритм-пересборки).
+остается явной. Новая связь куки меняет прошлые дни, поэтому каждый запуск
 пишет полную историю новой версией в `ReplacingMergeTree(_load_ts)`, а
 публичное представление выбирает текущие строки через `FINAL`.
 ## `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` — число отсутствующих или различающихся ключей;
 - `status` — `pass` при нуле нарушений, иначе `fail`.
-В `_load_id` и `_load_ts` записаны идентификатор запуска и время расчета
+Служебные `_load_id` и `_load_ts` называют собравший запуск. Представление
-сводки. Даже одно расхождение дает `fail`.
+перечисляет колонки явно. Порогов и промежуточного состояния нет.
 ## Звено DQ конвейера
 Даг `dq_check` стоит в `etl_pipeline` после `dm_transform` и проверяет пять
-правил:
+атомарных договоров:
 - `sessions_vs_reference`: ключ — `client_id` внутри дня, эталон —
  `uniqExact(VisitID)` из `ods.event_v`, объект — число строк
@@ -215,47 +189,43 @@
  сравниваются с прямыми агрегатами `dds.session_v` и
  `dds.identity_map_v`.
-Каждая проверка берет дни и ключи из обоих сравниваемых наборов данных.
+Область каждой проверки выводится из объединения сторон. Полностью потерянный
-Поэтому потерянная строка остается видна на другой стороне сравнения.
+день или ключ поэтому не исчезает из результата. Разные ошибки тоже не могут
-Расхождения считаются по ключам: завышение одного показателя не скроет
+скомпенсировать друг друга общим итогом: `failed_rows` считается после
-занижение другого в общей сумме за день.
+сопоставления деловых ключей.
-`classes_vs_inventory` сравнивает результат с паспортом мира. Это техническая
+`classes_vs_inventory` — техническая растяжка пути от генератора до DM. Она
-проверка доставки и обработки эталонных данных стенда. Она не проверяет
+подтверждает, что до витрины доехал записанный в паспорте мир, но не проверяет
-сам генератор; у настоящего магазина такого эталона нет.
+сам генератор: у настоящего магазина такого оракула нет.
 Четыре SQL-сверки считают дневные итоги в ClickHouse и возвращают Airflow только
-сводку и несколько примеров расхождений. Техническая сверка с паспортом читает небольшой
+сводку и малый срез диагностики. Техническая сверка с паспортом читает небольшой
-файл JSON в Python. Результаты всех пяти проверок записываются в общую
+файл JSON в Python. Все пять сборок пишут в общий донор. После их успеха даг
-промежуточную таблицу. Когда расчеты завершились, ее дневные разделы
+заменяет проверенные дневные партиции. Затем именованные задачи читают
-заменяют разделы `dm.dq_summary_rep`. Затем отдельные задачи читают
+опубликованную сводку и падают при `failed_rows > 0`. Расхождение успевает
-сохраненную сводку и завершаются ошибкой при `failed_rows > 0`.
+сохраниться до красного завершения, а ошибка сборки не затирает прежний
-Так расхождение сохраняется в таблице до отказа задачи. Если сам расчет
+результат. Красная задача печатает не больше двадцати нарушенных ключей за
-не выполнен, прежняя сводка остается на месте. Задача с расхождениями
+проверку со значениями сторон. Для полного списка итоговую агрегацию SQL-сверки
 выводит в журнал не больше двадцати ключей со значениями обеих сторон. Для полного списка итоговую агрегацию SQL-сверки
 заменяют на `SELECT * FROM comparison WHERE failed ORDER BY data_date,
 business_key`.
-Если день исчез из обоих сравниваемых наборов, новый расчет не создаст
+Если после починки день исчез с обеих сторон, его больше нет и в новом доноре.
-для него строк. Даг отдельно удаляет прежний результат за этот день
+Такой день удаляется из сводки отдельно: старая красная строка не должна
-из сводки.
+превращаться в историю попыток.
 ## Даг самопроверки
-`homework_check` запускается вручную и содержит задачу для каждого из
+Домашки контролирует `homework_check` — отдельный даг без расписания: менти
-[пяти заданий по витринам](../labs/README.md). Если витрины нет или значения
+запускает его рукой. По задаче на каждое из
-расходятся с источником, задача завершается ошибкой. Журнал показывает
+[пяти заданий по витринам](../labs/README.md).
-причину и примеры несовпадений. Успех означает, что проверяемые значения
+Задача красная, пока витрины нет или счёт не сходится, и зелёная, когда
-совпали; остальные требования задания вы проверяете сами.
+построено верно; сообщение об ошибке говорит, что не так и куда смотреть. Проверки — инварианты против источников витрины,
 золотые константы не прибиваются. В `dq_summary` даг не пишет: он инструмент
 лабы, а не история качества конвейера.
-Ожидаемые значения рассчитываются по исходным данным текущего стенда.
+Приём проверен на соседнем учебном стенде Airflow + Greenplum:
-Для четырех заданий это события или сессии DDS, для сводки брака —
+валидационный даг с группами проверок по слоям давал менти обратную связь
-таблицы ошибок ODS. Сравнение по деловому ключу учитывает отсутствующие
+по каждому шагу домашки, не трогая рабочий конвейер.
 строки с обеих сторон. Результаты не пишутся в `dq_summary`:
 самопроверка учебных витрин отделена от качества готового конвейера.
 Готовые SQL-проверки открывайте после собственного решения: они содержат
 расчет существенной части задания.
 ## Отклонённые варианты
@@ -263,7 +233,7 @@ business_key`.
  производственный паттерн слоя — пересборка агрегатов — остался бы
  невидим, а `dm_transform` — без работы.
 - **Материализовать всё.** Копия событий ради переименования колонок —
-  лишняя; такой пример приучал бы без нужды дублировать исходные данные.
+  антипаттерн, который менти увёз бы в бой.
 - **Гибрид по цене запроса.** Выбор формы по стоимости, которой на объёмах
  стенда нет: сторож без настоящей опасности.
 - **Проверки домашек в конвейерном звене DQ.** Конвейер стоял бы красным до
@@ -272,8 +242,8 @@ business_key`.
 - **«Жёлтый» статус недостроенной витрины.** У задачи Airflow нет такого
  состояния; изображать его логами — семантика, которую пришлось бы
  расшифровывать. Красное «ещё не построено» честнее.
- **Самопроверка пишет в `dq_summary`.** Результаты учебных попыток смешались бы
+- **Самопроверка пишет в `dq_summary`.** Попытки менти смешались бы с
-  с историей качества конвейера.
+  историей качества конвейера.
 - **Окно заказов для `daily_traffic` — прошлое замерзает.** Дни за окном хранили
  бы число известных на момент закрытия — витрина тихо расходится с картой
  и протаскивает обратно «знание на дату», отвергнутое развилкой карты
@@ -281,10 +251,7 @@ business_key`.
 - **Инкрементальный пересчёт затронутых дней по `first_matched_at`.**
  Производственный ход, но на объёмах стенда его экономия неизмерима, а
  след новых связок требует вернуть колонку, выкинутую в #133. Стал лабой
-  повышенной сложности —
+  повышенной сложности — issue #149.
  [«Как обновлять витрину без полной пересборки»](../labs/optional/incremental-daily-traffic.md).
  В ней новые связи находятся сравнением наблюдений: время покупки
  не заменяет момент обнаружения связи.
 - **Superset поверх DDS без слоя DM.** Терялся бы урок «витрина — контракт
  под потребителя», против раздела 7 спеки.
@@ -1,23 +1,28 @@
 # Дневной конвейер трансформаций
-Даг `etl_pipeline` собирает модель DDS, обновляет витрины DM и проверяет
+Как принятые источники превращаются в модель DDS и витрины DM: кто запускает
-результат. Здесь описаны запуск, выбор дней и запись результата в таблицы.
+трансформации, когда и в каком объёме. Правила самих сущностей — зерно,
-Состав моделей — в [справочниках DDS](dds/README.md) и [DM](dm.md).
+движки, что именно пересобирается — живут в доках слоя
 ([карта модели DDS](dds/README.md)); здесь — только конвейер.
 Дневная сборка вперёд появляется на этапе 4 и остаётся основным режимом
 конвейера. На этапе 5 к ней добавляется партиционная переобработка: запуск
 произвольного прошлого дня по команде.
 ## Форма
-`etl_pipeline` последовательно запускает `dds_transform`, `dm_transform`
+Дневной конвейер на стенде один — даг `etl_pipeline`. Своей работы
-и `dq_check`. Каждый следующий даг начинается после успеха предыдущего.
+у него нет: он дёргает слойные даги последовательно и ждёт каждый —
-Для этого `TriggerDagRunOperator` ждет завершения запущенного им дага.
+`dds_transform`, затем `dm_transform` и `dq_check`. Состав проверок описан в
-Если тот завершился ошибкой, задача ожидания в конвейере тоже завершится
+[доке слоя DM](dm.md).
 ошибкой.
 Поведение проверено через Context7 по документации Airflow 3.x (3.1.6).
-У этих дагов нет расписания. Их вызывает конвейер; для отдельного разбора
+Ждущие вызовы сделаны `TriggerDagRunOperator`. Проверка через Context7 по
-можно запустить даг слоя вручную. У каждого разрешен один активный запуск:
+ближайшей доступной документации Airflow 3.x (версия 3.1.6) подтвердила, что
-два запуска одного дага используют одни промежуточные таблицы и могли бы
+оператор опрашивает точный созданный им прогон и краснеет вслед за потомком.
-стереть результаты друг друга. Расчет каждой модели выполняется отдельной
+
-задачей или группой задач.
+Слойные даги устроены по образцу `orders_ingest`: без расписания, один
 активный прогон, запускаются триггером конвейера или рукой при разборе
 происшествий. Витрины внутри `dm_transform` — отдельные задачи.
 ## Три пути запуска
@@ -29,113 +34,83 @@ world_live_day ───┼─> etl_pipeline ─> dds_transform ─> dm_transfor
 world_next_day ─────> источники без ETL
 ```
- `world_live_day` запускает конвейер после успешной генерации, приема
+- **Живой день.** `world_live_day` дёргает конвейер с ожиданием — последним
-  заказов и обновления `world_position`. Если трансформация упала, день
+  шагом, после установки позиции. Порядок несёт смысл: день сыгран — факт,
-  уже прожит и позиция не откатывается. После исправления причины
+  упавшая трансформация его не отменяет, поэтому позиция ставится раньше; но
-  запустите `etl_pipeline` вручную.
+  зеленеть, не узнав, разложился ли день, шаговый даг не должен ([ADR
- `world_next_day` отправляет дни пачкой и ждет приема заказов, но конвейер
+  0003](../adr/0003-dag-run-state.md)). Такой отказ чинится перезапуском
-  не запускает. После него запустите `etl_pipeline` сами.
+  `etl_pipeline` рукой — перезапуску ничего не нужно помнить, см. «Объём
- `world_initialize` запускает конвейер последним шагом: при успешном
+  прогона».
-  первом `make up` начальные данные уже собраны в DDS и DM.
+- **Разгон пачкой.** `world_next_day` конвейер не дёргает: даги модельного
  времени управляют генератором и только им. После разгона менти запускает
  конвейер сам — и видит, как слои догоняют уехавший вперёд мир.
 - **Рождение мира.** `world_initialize` дёргает конвейер последним шагом:
  `make up` отдаёт стенд с собранными слоями, а не пустые витрины. Уроки
  ручного запуска начинаются со следующих дней.
 ## Объём прогона
-Объем прогона — дни, которые обрабатывает один запуск. Даты передавать
+Параметров у конвейера нет: объём он выводит сам из `world_position` и
-не нужно: даги определяют их по состоянию таблиц и `world_position`.
+состояния слоёв. Сессии догоняют хвост — от первого несобранного дня по
-Например, после генерации семи дней без ETL один запуск рассчитает сессии
+последний прожитый; заказы пересобирают дышащее окно и тот же хвост; карта
-за все семь дней.
+идентичностей пересчитывается целиком; правила витрин — у
 [слоя DM](dm.md).
 Поэтому один и тот же запуск одинаково верен из триггера, с кнопки менти и
 после падения, а разгону на семь дней хватает одного прогона.
-Для расчета сессий выбираются дни от первого, за который в DDS еще нет
+Окно заказов задаёт последний слепок, наблюдаемый в ODS. У каждого заказа
-сессий, до последнего прожитого.
+`snapshot_date` равен последнему слепку, в котором источник его показал.
-`world_position` хранит номер следующего дня для генерации, поэтому
+Трансформация выбирает строки с максимальной `snapshot_date` и берёт среди них
-последний прожитый день равен `min(EventDate) + world_position - 1`.
+минимальный и максимальный `order_date`. Это границы дней, состояние которых
-Начало календаря берется из ODS; события ранних дней там не удаляются по TTL.
+источник ещё может изменить
-Один `max(EventDate)` не годится: события за день есть и во время его
+([ADR 0014](../adr/0014-order-version-snapshot-date.md)). Кроме живого окна,
-генерации, когда последние визиты еще не закончились.
+трансформация закрывает пропуски: находит самый ранний день, представленный в
-Точный запрос — [`session_scope.sql`](../../sql/dds/session_scope.sql).
+ODS и ещё не собранный в DDS, затем при необходимости расширяет до него левую
 границу.
-Для заказов диапазон задает последний принятый слепок ODS. Среди строк
+Позиция мира заказам не отвечает: она говорит, какой день прожит, а не какой
-с максимальной `snapshot_date` выбираются самая ранняя и самая поздняя
+доехал. Прогон дня D везёт слепок дня D − 1, да и ставится позиция раньше
-даты оформления заказа. Состояние заказов за эти дни еще может измениться.
+трансформации, так что после неудачного приёма обгоняет хранилище. Слой обязан
-Если в ODS есть заказы за более ранний день, а в DDS за него нет строк,
+считать объём по тому, что у него есть, а не по тому, что мир о себе заявляет.
 начало диапазона сдвигается до этого дня. Запрос заново рассчитывает
 заказы за все дни выбранного отрезка.
-Позиция мира для выбора дней заказов не подходит: с событиями дня D
+Для сессий границу задаёт `world_position`: она отличает полностью прожитый
-приходит слепок за D−1. Объем рассчитывается по принятым строкам ODS;
+день от ещё идущего. Сами события этой границы не показывают: и посреди дня D,
-их наличие еще не доказывает полноту слепка.
+и сразу после его конца их позднейший день равен D. Если собрать сессии посреди
-
+дня, визит, начатый в 23:50, останется обрезанным: завершённый день слой
-Карта идентичностей пересчитывается целиком. Витрины выбирают дни
+повторно не собирает. Поэтому последний прожитый день равен первому дню
-по своим источникам — см. [ритм пересборки DM](dm.md#ритм-пересборки).
+событий плюс позиция минус один
-Если за день сохранилась хотя бы одна строка, запрос не считает его
+([`sql/dds/session_scope.sql`](../../sql/dds/session_scope.sql)).
-пропущенным. Полноту данных проверяют отдельно.
+Оговорка про «доехал» остаётся в силе и здесь: за хвост потока отвечает не
 позиция, а «Готовность источника».
 ## Готовность источника
-Перед сборкой DDS задача `wait_for_source` последовательно ждет двух
+Первый шаг `dds_transform` проходит два барьера за общий срок в 300 секунд.
-условий:
+Сначала клиент `confluent-kafka` сверяет подтвержденные смещения группы
 `clickstream_hits` с верхними смещениями обоих разделов `hits`. Группа, оба
 раздела и все смещения должны существовать. Суммарное отставание должно стать
 нулевым. Каждый опрос пишет в журнал оба смещения и отставание по разделу.
-1. Группа `clickstream_hits` дочитала оба раздела топика `hits`.
+Только после этого шаг проверяет обе ноды ClickHouse через
-   Подтвержденные смещения сравниваются с верхними смещениями Kafka.
+`clusterAllReplicas`: у `ods.event_dist` в `system.distribution_queue` не
-   Группа и смещения должны существовать, суммарное отставание — равняться нулю.
+должно остаться файлов. Каждый опрос пишет в журнал ноды, число файлов и
-2. В `system.distribution_queue` у `ods.event_dist` не осталось файлов
+`last_exception` очереди. Оба барьера опрашиваются раз в три секунды и делят
-   доставки на шарды. Запрос через `clusterAllReplicas` читает обе ноды.
+один крайний срок. После Kafka срок не отсчитывается заново.
-Опросы идут с паузой в три секунды; на обе стадии задан общий срок
+Зелёный приём заказов о событиях не говорит ничего — топики разные и
-300 секунд. Журнал показывает смещения и отставание Kafka, затем число
+потребители разные. Одного нулевого отставания Kafka тоже мало: чтец мог
-файлов и `last_exception` очереди на каждой ноде. Если готовность не
+подтвердить сообщение раньше, чем Distributed-таблица доставила файл на шард.
-подтверждена за срок ожидания, задача завершается ошибкой.
+Два барьера закрывают обе части пути до того, как сессии выберут свой объем.
 Одного нулевого отставания Kafka мало: сообщение может быть подтверждено,
 пока Distributed-таблица еще доставляет его на шард. Успех `orders_ingest`
 тоже не заменяет эти проверки: у заказов другой топик и потребитель.
 Эти условия проверяют доставку на момент опроса. Они не останавливают
 поступление новых событий и не сверяют содержимое таблиц. Поэтому
 `world_position` отдельно ограничивает сборку сессий прожитыми днями,
 а качество результата проверяет `dq_check`.
 ## Идемпотентность
-Идемпотентность означает, что повторная обработка тех же исходных данных
+Партиция не заменяется простой вставкой. День собирается в таблицу-двойник —
-не добавляет копии деловых строк. Служебные `_load_id` и `_load_ts`
+вставка через Distributed раскладывает строки по шардам, — затем
-при новой сборке меняются.
+`REPLACE PARTITION` на кластере атомарно подменяет кусок каждого шарда. Эта
-
+механика — часть самих трансформаций и строится этапом 4: без неё дневной
-Результат дневного расчета сначала записывается в промежуточную таблицу.
+прогон не повторяем. Сущности, пересчитываемые целиком, идемпотентны и без
-Она нужна, чтобы читатели продолжали видеть прежние данные, пока новые
+замены: полная перезапись в `ReplacingMergeTree` — так живут карта
-еще рассчитываются. Например, для сессий это `dds.session_stage_rep`,
+идентичностей и витрина `daily_traffic` ([слой DM](dm.md)).
 а основная таблица — `dds.session_rep`.
 Задачи выполняются в таком порядке:
 1. `scope` выбирает даты для расчета.
 2. `rebuild` очищает промежуточную таблицу, рассчитывает строки за выбранные
   дни и записывает их через `_stage_dist`. Настройка
   `distributed_foreground_insert = 1` заставляет вставку дождаться
   доставки строк на шарды.
 3. `replace` заменяет в основной таблице раздел за каждый выбранный день
   готовым разделом промежуточной таблицы. Раздел таблицы называется
   партицией; для замены используется `REPLACE PARTITION`.
 Структура и распределение строк по шардам у двух таблиц должны совпадать.
 Замена выполняется на локальных `_rep` с `ON CLUSTER`. На каждом шарде
 читатель видит либо старый, либо новый раздел целиком — это атомарность
 замены. Общей транзакции для двух шардов и всех дней нет: при сбое один
 шард может уже содержать новый результат, а другой — прежний. Повторить
 `replace` можно, пока промежуточная таблица хранит тот же результат;
 копии строк в основной таблице от этого не появятся.
 Новый запуск всего конвейера заново выбирает дни. Он не обязан повторить
 все дни неудачного запуска: если дата уже есть в целевой таблице, поиск
 пропусков ее не выберет. В частности, изменение SQL сессий само по себе
 не заставляет пересчитать заполненные дни. Повторная сборка выбранного
 дня разобрана в [задании ступени 4](../labs/4-1-session-pipeline.md).
 Карта идентичностей и `daily_traffic` обновляются иначе: каждый запуск
 добавляет полный результат новой версией в `ReplacingMergeTree(_load_ts)`.
 Публичные представления читают текущие строки через `FINAL`. Старые версии
 могут физически оставаться до фонового слияния; повторяемость относится
 к результату чтения, а не к числу строк на диске.
 ## Чего конвейер о себе не знает
@@ -1,172 +1,241 @@
-# Прием заказов из Kafka в ODS
+# Приём заказов из Kafka в ODS
-Здесь разобран путь одного заказа: сообщение Kafka сохраняется в STG,
+Учебный результат: менти различает версию бизнес-сущности, наблюдение источника
-проверяется и попадает либо в ODS, либо в таблицу ошибок. Следующие слои
+и запуск загрузки, а затем читает физические версии через явную поверхность
-читают из ODS последнюю принятую версию каждого заказа.
+текущего состояния.
 ## Проблема
 Заказы приезжают полным слепком окна изменяемости, но Kafka передаёт его
 отдельными сообщениями и не сообщает потребителю, где слепок закончился.
 Прямое чтение Kafka Engine возвращает одну порцию без признака полноты.
 Поэтому `snapshot_date` не может служить границей публикации: `REPLACE
 PARTITION` могла бы заменить партицию дня неполным набором строк.
 Одновременно типизированный ODS не должен принимать правдоподобные значения по
 умолчанию из грязного JSON или останавливать весь пакет из-за одной строки.
 ## Цели
 - сохранить пакетный забор как контраст потоковому приёму событий;
 - один раз принять байты в STG и независимо разложить строки на годные и брак;
 - хранить в ODS типизированные версии заказов, не публикуя слепок заменой
  партиции;
 - дать следующим слоям один корректный способ прочитать текущее состояние;
 - оставить код проверки коротким и ограничить его контрактом провода.
 ## Не входит
 - модель заказа в DDS: её зерно, связи, материализация и способ наполнения;
 - проверка полей внутри `items`, переходов статуса и равенств денежных сумм;
 - удаление заказа по отсутствию в следующем слепке;
 - маркер конца слепка, опись ожидаемых строк и транзакция между целями ODS.
 ## Поток данных
-Источник отправляет в топик `orders` дневной слепок: по одному сообщению
+После завершения генератора Airflow один раз читает байтовый Kafka-чтец и
-на заказ. Слепок дня D содержит состояния заказов, оформленных в дни
+записывает полученную порцию в `stg.orders_raw`. Даг зовётся `orders_ingest`, а
-D−6…D, с учетом [задержек первого появления](fate.md).
+запускает его шаговый даг модельного времени, который положил слепок в топик и
-В начале модельного времени окно короче. Выгрузку за D отправляет
+ждёт конца прогона. Все строки получают `_load_id`, равный `run_id` Airflow.
-генератор при запуске дня D+1; подробности — в [описании слепка](snapshot.md).
+`_load_ts` вычисляется при этой записи и дальше переносится без пересчёта.
 Запрос забора лежит в
 [`sql/stg/orders_raw_load.sql`](../../../sql/stg/orders_raw_load.sql):
 `SQLExecuteQueryOperator` задаёт подключение и передаёт `run_id` как параметр
 ClickHouse `load_id`, а преобразование остаётся в SQL своего слоя.
-После отправки шаговый даг модельного времени запускает
+Один следующий `task_id` отвечает за весь переход STG → ODS. Внутри него два
-[`orders_ingest`](../../../dags/orders_ingest.py) и ждет его завершения.
+последовательных `INSERT SELECT` читают неизменный срез по `_load_id`: первый
-У `orders_ingest` нет расписания; его два шага выполняются по порядку:
+пишет годные строки в `ods.order`, второй — брак в `ods.order_errors`.
 Транзакции между запросами нет. При частичном сбое Airflow повторяет весь
 `task_id`; одинаковые исходные строки и служебные метки не вычисляются заново.
 Обе вставки лежат в одном самодостаточном файле
 [`order_parse.sql`](../../../sql/ods/order_parse.sql). Airflow сначала
 шаблонизирует файл, затем делит получившийся SQL на выражения и исполняет их по
 порядку в одной задаче `parse_batch`.
-1. `pull_batch` читает порцию из `stg.orders_raw_kafka` и записывает ее
+Условия запросов взаимодополняющие: один общий предикат определяет годную
-   через `stg.orders_raw_dist`. Содержимое сообщения остается строкой `raw`,
+строку, а ветвь брака использует его буквальное отрицание. Все функции предиката
-   рядом сохраняются координаты Kafka, `_load_id` и `_load_ts`.
+возвращают результат без исключения, а сам предикат всегда заканчивается в
-2. `parse_batch` читает сохраненные строки с этим `_load_id`. Первый
+`true` или `false`, не в `NULL`. Постоянный классификатор между STG и ODS для
-   `INSERT SELECT` пишет годные записи в `ods.order_dist`, второй —
+этого не нужен. Предикат объявлен локальным макросом Jinja внутри
-   остальные в `ods.order_errors_dist`.
+`order_parse.sql` и разворачивается в оба выражения. Макрос убирает
-
+дублирование, но не вводит отдельный фрагмент, который нельзя исполнить
-`_load_id` равен `run_id` Airflow и связывает строки одного запуска.
+самостоятельно.
 `_load_ts` — реальное время записи в STG; при разборе оно переносится
 без пересчета. Запросы лежат в
 [`orders_raw_load.sql`](../../../sql/stg/orders_raw_load.sql) и
 [`order_parse.sql`](../../../sql/ods/order_parse.sql).
 `SQLExecuteQueryOperator` передает `run_id` параметром ClickHouse `load_id`.
 Две вставки разбора используют одно условие годности, записанное макросом
 Jinja внутри `order_parse.sql`. Перед выполнением макрос подставляется
 в оба запроса; ветвь брака берет отрицание этого условия. Оно возвращает
 только истину или ложь и не вызывает исключений на некорректном `raw`.
 Так каждая строка сохраненной порции получает ровно один результат.
 Транзакции между вставками нет: первая может завершиться, а вторая упасть.
 Повтор `parse_batch` выполняет обе вставки над тем же срезом STG.
 Текущее состояние заказа останется прежним, но таблица ошибок может
 получить повторные строки с теми же `_load_id` и координатами Kafka.
 Обе вставки ждут доставки строк на шарды и используют ключ целевой таблицы;
 настройки объяснены в [справочнике хранилища](../storage.md#раскладка-по-шардам).
 ## Граница строгого приёма
-Проверяется одна строка `stg.orders_raw_dist`. Корень JSON должен быть
+Единица решения — одна строка `stg.orders_raw`. Корень должен быть
-объектом с точным набором из одиннадцати ключей:
+JSON-объектом с точным набором ключей: `order_id`, `user_id`, `status`,
-`order_id`, `user_id`, `status`, `created_at`, `updated_at`,
+`created_at`, `updated_at`, `items_total`, `discount`, `delivery`, `total`,
-`items_total`, `discount`, `delivery`, `total`, `items`, `snapshot_date`.
+`items`, `snapshot_date`.
-| Поля | Условия приема |
+Скалярные поля проверяются по типу JSON. Деньги дополнительно обязаны быть
-|---|---|
+строками неотрицательной суммы с ровно двумя знаками после точки — минус в эту
-| `order_id`, `status` | Строки JSON |
+форму не входит; времена — строками RFC 3339 в UTC с обязательными
-| `user_id` | Целое число JSON, которое разбирается в `UInt64` |
+миллисекундами; дата слепка — строкой `YYYY-MM-DD`. `items` проверяется только
-| `created_at`, `updated_at` | Строки UTC с миллисекундами, например `2026-06-01T12:34:56.000Z`; проверяются форма и разбор времени |
+как JSON-массив. Каноническая форма и основания выбора зафиксированы в
-| `items_total`, `discount`, `delivery`, `total` | Неотрицательные суммы в рублях, записанные строками с двумя знаками после точки; проверяется разбор в `Decimal(18, 2)` |
+[исследовании формата](../../research/2026-08-16-order-snapshot-wire-format.md).
 | `snapshot_date` | Строка даты `YYYY-MM-DD`, которая проходит разбор |
 | `items` | Массив JSON; сохраняется целиком в строковой колонке |
-ODS проверяет формат верхнего уровня. Здесь нет проверки допустимых
+Проверять все верхнеуровневые поля здесь уместно: их одиннадцать, и десять
-статусов, их переходов, полей внутри `items` или равенства денежных сумм.
+скалярных значений непосредственно образуют типизированную строку заказа. У
-Позиции разбираются в [DDS](../dds/order.md); проверку их суммы участник
+события из 47 полей проверяются только пять опорных; переносить то сокращение на
-добавляет в [задании ступени 5](../../labs/5-1-order-checks.md).
+малый контракт заказа нет причины. Граница строгости заканчивается на форме
-Основания выбора формата — в [исследовании](../../research/2026-08-16-order-snapshot-wire-format.md).
+провода: содержимое позиций и бизнес-инварианты намеренно остаются ниже.
-Класс ошибки записывается в `error_class` по первому нарушенному условию:
+Контракт источника задаёт частоту: **одной дате соответствует один слепок**. Это
 свойство всего слепка, поэтому предикат одной строки его не проверяет. Вторая
 выгрузка того же дня даст ничью по `snapshot_date`, и выбор строки потеряет
 однозначность. Модельный источник выполняет условие; в настоящей интеграции
 его фиксируют в договоре с источником
 ([ADR 0014](../../adr/0014-order-version-snapshot-date.md)).
-1. `not_an_object` — корень JSON не объект;
+Класс брака выбирается первым совпадением:
 2. `keyset_mismatch` — набор ключей отличается от ожидаемого;
 3. `field_invalid` — тип, форма или разбор значения не прошли проверку.
-Имя поля в класс не входит. Для разбора конкретной ошибки в
+1. `not_an_object`;
-`ods.order_errors_dist` есть исходный `raw`, координаты Kafka и метки загрузки.
+2. `keyset_mismatch`;
 3. `field_invalid`.
 Имя отдельного поля в класс не включается. В таблице ошибок остаются сырой
 текст, метаданные доставки и `_load_id`, поэтому единичный случай можно разобрать
 без постоянной детализации предиката.
 ## Роль ODS
-`ods.order_rep` использует `ReplicatedReplacingMergeTree(snapshot_date)`.
+`ods.order_rep` хранит физически принятые версии в
-Строки с одним ключом сортировки `order_id` считаются версиями одного заказа;
+`ReplacingMergeTree(snapshot_date)`. Ключ сортировки — `order_id`, партиция —
-остается строка с максимальной `snapshot_date`. Партиция —
+день неизменного `created_at`. `ods.order_dist` шардирует по
-`toDate(created_at)` в UTC, ключ шардирования — `cityHash64(order_id)`.
+`cityHash64(order_id)`: только так все версии заказа попадают на один шард и
-Неизменный `created_at` и общий ключ направляют все версии заказа
+`FINAL` даёт корректный результат через распределённую таблицу.
 в одну партицию и на один шард.
-| Колонка | На какой вопрос отвечает |
+Четыре координаты отвечают на разные вопросы:
 |---|---|
 | `snapshot_date` | На конец какого модельного дня источник показал это состояние? |
 | `updated_at` | Когда запись заказа последний раз меняли в магазине? |
 | `_load_id` | Какой запуск Airflow принял сообщение? |
 | `_load_ts` | Когда сообщение записали в STG по реальным часам стенда? |
-Например, заказ не менялся с 1 июня, но входит в слепки за 1 и 2 июня.
+- `snapshot_date` — в слепке какого модельного дня источник показал строку;
-`updated_at` у строк одинаков, а `snapshot_date` различается. ODS оставит
+- `updated_at` — когда строку последний раз меняли в источнике;
-строку за 2 июня вместе с метками ее доставки. Новая дата наблюдения
+- `_load_id` — какой запуск Airflow принял строку;
-нужна DDS для определения окна пересборки, даже если состояние не изменилось.
+- `_load_ts` — когда строка приехала в хранилище.
-Источник выпускает **один слепок на дату**. Повторная отправка дает то же
+Версию выбирает `snapshot_date`: выживает строка с максимальной датой слепка
-содержимое, а более поздний слепок не возвращает устаревшее состояние.
+([ADR 0014](../../adr/0014-order-version-snapshot-date.md)). Поэтому
-Эти условия не проверяются на одной строке при приеме. Если источник
+`snapshot_date` показывает последнее наблюдение заказа. По строкам последней
-пришлет два разных состояния с одной `snapshot_date`, эта колонка
+даты слепка DDS определяет окно пересборки. `_load_id` и `_load_ts` принадлежат
-не позволит определить, какое из них актуально.
+той физической строке, которую сохранило слияние, и описывают её доставку.
 Обоснование версии — [ADR 0014](../../adr/0014-order-version-snapshot-date.md).
-`ods.order_v` читает `ods.order_dist FINAL` и возвращает одну текущую строку
+Схема версий стоит на дисциплине источника: слепок с поздней датой не
-на `order_id`, даже если фоновые слияния еще не убрали старые версии.
+показывает состояния старше. Модельный мир её держит — состояние читается на
-Без `FINAL` физическая таблица может показать несколько строк заказа.
+границе суток, и слепок дня выходит чистой функцией зерна и дня; источник,
-Историю ODS не гарантирует: старые версии постепенно удаляются при слияниях.
+собирающий слепок из отставшей реплики, её ломает. Деловая метка `updated_at`
-Отсутствие заказа в новом слепке не удаляет его из ODS.
+при этом монотонна по слепкам, поэтому выбор по дате слепка даёт тот же ответ,
 что выбор по метке (замер — «Что проверено»). Тихая правка строки — ручным
 `UPDATE` мимо приложения, миграцией — метку не двигает, но следующий слепок
 перекроет её сам, пока заказ в окне изменяемости. За окном источник заказ
 больше не показывает, и там помогает только сверка самих полей, в терминах
 dbt snapshots — стратегия `check` вместо `timestamp`.
-DDS читает `ods.order_v`, переводит времена в пояс счетчика и разбирает
+Обычное чтение `_dist` показывает физически сохранившиеся версии и нужно для
-позиции. Для своей загрузки DDS записывает собственные служебные метки —
+диагностики. Их число зависит от фоновых слияний: ODS не служит архивом истории.
-[модель заказа](../dds/order.md#служебные-колонки).
+`ods.order_v` сохраняет те же источник-ориентированные поля без обогащения
 данными модели, но возвращает одну актуальную версию на `order_id`. Сначала оно
 может быть простым представлением над `_dist FINAL`; способ выбора можно
 заменить, не меняя потребителей.
 Это представление остаётся ответственностью ODS: оно скрывает механику чтения
 версий, но не строит бизнес-модель. DDS читает `ods.order_v` и отдельно решает,
 какие сущности, связи и производные признаки ему нужны. Судьба служебных
 колонок выше ODS решена вместе с моделью DDS: чужие ярлыки туда не переезжают
 ([модель заказа](../dds/order.md)).
 ## Одно чтение Kafka
-Один запуск делает один прямой `SELECT`, без чтения в цикле до пустоты.
+Стандартный слепок содержит около полутора тысяч строк, тогда как предел одной
-Обычный слепок содержит около полутора тысяч строк, а предел порции
+порции на стенде — десятки тысяч сообщений. Поэтому один запуск Airflow делает
-на стенде — десятки тысяч сообщений. Это допущение о размере данных:
+один прямой `SELECT`, без цикла до пустоты и без фиксации конечных офсетов.
 Kafka не сообщает запросу, что прочитан весь слепок.
-Короткая порция оставляет непрочитанные сообщения для следующих запусков.
+Это допущение о размере стенда, а не доказательство полноты слепка. Если Kafka
-Поэтому ODS добавляет версии заказов по мере поступления. Замена партиции
+вернёт короткую порцию, непрочитанный хвост останется в топике и приедет в один
-по `snapshot_date` могла бы опубликовать неполный набор заказов
+из следующих запусков. После отказа от замены партиции это задержка, а не потеря
-([ADR 0010](../../adr/0010-order-versions-in-ods.md)).
+или публикация неполного дня.
-Сбой после чтения опаснее короткой порции. Чтец подтверждает позиции
+Отказ — случай другой, и «хвост дождётся» на него не распространяется. Офсеты
-сообщений в Kafka — офсеты — при прямом чтении. Если последующая вставка
+порции коммитятся в момент чтения, поэтому упавшая вставка уносит прочитанное с
-в STG упадет, эти сообщения уже не будут прочитаны той же группой повторно;
+собой: повторное чтение вернёт ноль, а часть строк может уже лежать на шарде.
-часть из них может успеть записаться на шарды. Позиция модельного времени
+Позиция мира при этом не двигается, и тот же день уедет заново — в STG он
-при неуспехе не продвигается. Повтор шагового дага снова отправит слепок
+окажется частичным дублем, а старый хвост, ушедший той же порцией, не вернётся
-того же дня, но не восстановит старые сообщения других слепков,
+([ADR 0008](../../adr/0008-order-ingestion.md), «Следствия»).
-если они попали в неудачную порцию.
+
-Граница восстановления описана в [ADR 0008](../../adr/0008-order-ingestion.md#следствия).
+## Отклонённые варианты
 - Партиционная идемпотентность — `REPLACE PARTITION snapshot_date` или
  `ReplacingMergeTree` по `(snapshot_date, order_id)`: у потребителя нет
  признака полноты партиции, а дата наблюдения становится частью ключа
  сущности.
 - Обычный `MergeTree` в ODS с дедупликацией только в DDS: навсегда сохраняет
  технические повторы там, где семантика версии уже известна.
 - Маркер, опись, чтение до пустоты или конечные офсеты: добавляют протокол ради
  объёма, который с большим запасом помещается в одну порцию.
 - Два `task_id` или материализованный классификатор: дробят один короткий
  переход слоя, не добавляя транзакционности.
 - Представление текущего состояния в DDS и готовая схема `dds.order` в этой
  задаче: перекладывают механику ODS на следующий слой и преждевременно задают
  модель данных.
 ## Риски и проверка
 - На малой управляемой порции дать по одной строке каждого класса брака и две
  годные версии одного `order_id`. Две цели должны сохранить все непустые
  сообщения, а `ods.order_v` — вернуть новую версию независимо от фонового
  слияния.
 - Повторить переход с тем же `_load_id`: строка в `ods.order_v` и её `_load_ts`
  не должны измениться; версии одного заказа должны остаться на одном шарде и
  в одной партиции. Таблица ошибок может снова записать тот же брак: совпавшие
  `_load_id` и Kafka-координаты показывают повтор задачи.
 ## Что проверено
-Это результаты прежних опытов на стенде; при редактуре они заново
+Переход STG → ODS снят на живом стенде 18 августа 2026 года при исполнении #94.
-не выполнялись.
+Опыты этого раздела прогнаны и подтвердили обещанное: разбиение строк STG на
 годные строки и брак полное и непересекающееся; две версии одного заказа легли в
 одну партицию и на один шард, а `ods.order_v` вернуло позднюю независимо от
 фонового слияния; повтор задачи с тем же `_load_id` строку в `ods.order_v` и её
 `_load_ts` не изменил, а таблица ошибок записала тот же брак второй раз; строки
 опытов убраны. Числа, механика опытов и поведение ClickHouse, на которое всё это
 опирается, — [документ хранилища](../storage.md), «Что проверено».
- 18 августа 2026 года (#93, #94) прямое чтение приняло слепок,
+После исправления
-  а разбор разделил строки на годные и ошибки без потерь и пересечений.
+[#102](https://git.dementev.space/ddmitry/clickstream-data-platform/issues/102)
-  Две версии заказа попали на один шард в одну партицию; `ods.order_v`
+честный прогон дня снят на живом стенде 20 августа 2026 года: все 1694 строки
-  вернул позднюю. Повтор разбора с тем же `_load_id` сохранил текущую строку
+слепка дня 7 приняты, `ods.order_errors` осталась пустой. У заказа
-  и ее `_load_ts`, но повторил ошибки. Подробности —
+`20260608-0007`, который прежде приходил с отрицательным итогом, теперь
-  [справочник хранилища](../storage.md#что-проверено) и
+`5490.00 − 823.50 + 299.00 = 4965.50`.
  [ADR 0008](../../adr/0008-order-ingestion.md#что-проверено).
 - 20 августа после исправления
  [#102](https://git.dementev.space/ddmitry/clickstream-data-platform/issues/102)
  приняты все 1694 строки слепка дня 7 без ошибок. Итог заказа
  `20260608-0007`: `5490.00 − 823.50 + 299.00 = 4965.50`.
 - 21 августа (#124) пересборка через `SQLExecuteQueryOperator` завершила
  `pull_batch` и `parse_batch`; в `system.query_log` осталось по одному
  завершенному запросу `etl` на забор, годные строки и ошибки.
 - 22 августа (#137) во всех 3034 парах с одинаковым `updated_at`
  деловые поля совпали побайтово; по слепкам время изменения не убывало.
 - 26 августа (#165) после двух слепков физическая таблица содержала
  3356 версий 1917 заказов. В `ods.order_v` у всех заказов была дата
  последнего слепка, а деловые поля совпали с `argMax` по `updated_at`
  из сырых данных.
-На ClickHouse `26.3.17.56` отдельно проверены одна порция при прямом
+При исполнении #124 21 августа 2026 года адресная пересборка мира прошла через
-`SELECT` Kafka и выполнение `FINAL` на шардах через Distributed.
+`SQLExecuteQueryOperator`: `pull_batch` и `parse_batch` завершились успешно. В
-При проектировании Context7 был недоступен; чтение сверяли с исходниками
+`system.query_log` на первой ноде осталось ровно по одному завершённому запросу
-той же версии:
+пользователя `etl` для забора в STG, записи годных строк и записи брака.
 Дисциплина источника замерена 22 августа 2026 года при исполнении #137.
 Во всех 3034 парах строк с равным `updated_at` деловые поля совпали
 побайтово, а по слепкам метка ни разу не убывала.
 Текущее состояние проверено на пересобранном мире 26 августа 2026 года при
 исполнении #165. После двух слепков физическая таблица содержала 3356 версий
 1917 заказов. У всех строк `ods.order_v` дата слепка совпала с последним слепком
 заказа; деловые поля совпали с эталоном `argMax` по `updated_at` из сырых
 данных. В обеих сверках расхождений нет.
 Забор из Kafka в STG снят на живом стенде 18 августа 2026 года при исполнении
 #93: одно прямое чтение приносит весь слепок дня, метаданные доставки доступны,
 офсеты коммитятся, а сбой забора не двигает позицию мира. Числа — [ADR
 0008](../../adr/0008-order-ingestion.md), раздел «Что проверено».
 MCP Context7 в сессии проектирования был недоступен. На локальном ClickHouse
 `26.3.17.56` проверено, что прямой `SELECT` Kafka Engine завершается после
 одной порции, а `FINAL` через `Distributed` исполняется на таблицах шардов.
 Поэтому версии одного `order_id` направляются на один шард. Фоновое схлопывание
 `ReplacingMergeTree` и необходимость точного чтения сверены с
 [официальной документацией](https://clickhouse.com/docs/reference/engines/table-engines/mergetree-family/replacingmergetree),
 поведение чтения — с исходниками той же версии
 [`StorageKafka.cpp`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Storages/Kafka/StorageKafka.cpp) и
 [`KafkaSource.cpp`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Storages/Kafka/KafkaSource.cpp).
 Повторная сверка правил версий с документацией — в
 [справочнике хранилища](../storage.md#актуальные-события).
 ## Связанные решения
@@ -22,7 +22,7 @@
 ## Пользователи и роли ClickHouse
-В ClickHouse восемь пользователей и семь ролей:
+В ClickHouse семь пользователей и шесть ролей:
 - `etl` — учётная запись рабочих дагов Airflow; роль `etl_writer` читает и
  пишет слои хранилища;
@@ -33,9 +33,6 @@
  справочники `dic`, а запросы Superset обращаются к публичным `_v`;
 - `analyst` — учётная запись аналитика с правом чтения всех слоёв и
  справочников;
 - `student` — учебная учётная запись: роль `analyst_reader` дает чтение
  источников, а `student_writer` — создание, заполнение и удаление своих
  таблиц в `default`. Записи в слои хранилища у нее нет;
 - `grafana` — учётная запись Grafana; роль `monitoring_reader` читает все слои,
  системные таблицы и данные со всех реплик кластера;
 - `dict` — беспарольная учётная запись словаря товаров с правом чтения базы
@@ -52,9 +49,6 @@ Superset получает пароль `bi`, а Grafana — пароль `grafan
 ## Применение настроек
 Для существующего стенда сначала добавьте `CLICKHOUSE_STUDENT_PASSWORD`
 из `.env.example` в свой `.env`.
 Чтобы применить новые значения ClickHouse из `.env` или изменения файлов в
 `infra/clickhouse/config.d/` и `infra/clickhouse/users.d/`, пересоздайте ноды:
@@ -30,202 +30,223 @@ keeper, Kafka, каркас сервисов. Этап 2 собран: в `sql/d
 ## Имена объектов
-Суффикс показывает назначение объекта:
+Имя объекта заканчивается тем, что это за объект:
 | Суффикс | Что это |
 |---|---|
-| `_rep` | локальная таблица: хранит данные своего шарда, движок семейства `Replicated*` |
+| `_rep` | локальная таблица шарда, движок семейства `Replicated*` |
-| `_dist` | таблица `Distributed`: читает данные шардов и распределяет запись между ними |
+| `_dist` | `Distributed` поверх одноимённой локальной |
-| `_kafka` | таблица на движке `Kafka`: читает сообщения топика |
+| `_kafka` | таблица на движке `Kafka` |
-| `_file` | таблица на движке `File`: читает файл |
+| `_file` | таблица на движке `File` — чтец файла |
-| `_mv` | материализованное представление: обрабатывает вставляемые данные |
+| `_mv` | материализованное представление |
-| `_v` | обычное представление: выполняет сохраненный запрос при чтении |
+| `_v` | обычное представление, публичная поверхность чтения |
-Для запросов к моделям DDS и витринам DM используйте `_v`. Представления
+Суффикс носит каждый физический объект. Голого имени у таблицы не существует:
-явно перечисляют колонки, поэтому добавление поля в физическую таблицу
+запрос к `stg.hits_raw` даёт громкую ошибку «нет такой таблицы» — а под голым
-не меняет набор полей для читателя. У `dds.event_v` нет отдельной таблицы
+именем в документах и разговоре понимается сущность, у которой этих объектов
-DDS: представление читает события ODS.
+несколько. Единственное исключение — словари: у них воплощение одно, шардировать
 нечего, и суффикс ничего не различал бы. В зоне `dic` обе формы стоят рядом и
 правило видно целиком: `dic.products_file` — чтец файла, `dic.products` — сам
 словарь.
-В документации имя без суффикса, например `stg.hits_raw`, обозначает
+Распространённая конвенция, где голое имя означает локальную таблицу, а
-сущность с несколькими объектами. Таблицы с таким именем нет: в запросе
+распределённая получает суффикс `_all`, ошибается иначе: забытый суффикс тихо
-нужно указать суффикс. Исключение — словари ClickHouse: `dic.products`
+возвращает данные одного шарда. Правило спеки «проверки и контрольные суммы —
-обращается к каталогу товаров, а `dic.products_file` читает его файл.
+только по `Distributed`» такую тишину переживает плохо.
-В STG имя берется из топика: `hits_raw`, `orders_raw`. В типизированных
+Второе свойство — в списке по алфавиту объекты группируются по сущности, а не по
-слоях оно называет сущность в единственном числе: `event`, `order`,
+технологии: все четыре объекта топика `hits` стоят рядом, потому что различаются
-`session`. Объекты одной сущности различаются суффиксом и стоят рядом
+хвостом, а не началом имени. Речь про дерево в клиенте и про `ORDER BY name`:
-при сортировке имен по алфавиту.
+порядок выдачи `SHOW TABLES` документация не оговаривает.
-`_rep` и `_dist` нужны для загрузки, диагностики и обслуживания. Роль
+Начало имени — сущность, и берётся она в разных слоях из разных мест. В STG имя
-`bi_reader` может читать их в ODS, DDS и DM, но для обычного анализа
+приходит от транспорта: слой хранит то, что доехало по топику, и зовётся именем
-принято использовать `_v`. Это соглашение о чтении, а не ограничение прав;
+топика — `hits_raw` от `hits`, `orders_raw` от `orders`. В типизированных слоях
-причина широкого доступа описана в
+имя приходит от предметной области и стоит в единственном числе: `event`,
-[ADR 0007](../adr/0007-clickhouse-access.md) и
+`order`, `session`. Граница между «как привезли» и «что это такое»
 проходит по STG, и имена её показывают.
 В DDS публичный договор сущности заканчивается на `_v`. Потребительские запросы
 и витрины называют только представление; `_rep` и `_dist` служат загрузке,
 диагностике и обслуживанию. Представление перечисляет колонки явно, даже если
 его запрос — простая проекция над `_dist`: договор не выдаёт устройство
 кластера и случайно добавленные в физическую таблицу колонки. У события
 физической копии в DDS нет, но правило то же: `dds.event_v` — его публичный
 договор.
 Право доступа здесь намеренно шире договора. Роль `bi_reader` может читать
 любые объекты ODS, DDS и DM, но физические объекты от этого не становятся
 публичной поверхностью. Конвенцию держат явный список колонок, документация и
 ревью, а не запрет на физические таблицы.
 Широкое право принято в [ADR 0007](../adr/0007-clickhouse-access.md): узкая
 граница поверх `Distributed` потребовала бы отдельной механики. Механизм
 ClickHouse и отклонённые варианты записаны в
 [исследовании](../research/2026-08-25-clickhouse-distributed-view-security.md).
 ## Раскладка по шардам
-Шард хранит часть строк. При записи через `_dist` место строки выбирает
+Пишем только в `_dist`. Локальные таблицы остаются для чтения и обслуживания —
-ключ шардирования. При прямой записи в `_rep` она остается на той ноде,
+операций с партициями, ручной переобработки. Правило не про удобство: при записи
-где выполнена вставка. Поэтому данные записывают через `_dist`,
+через распределённую таблицу раскладку определяет ключ шардирования, то есть
-а операции с партициями выполняют на локальных `_rep`.
+свойство данных, а при записи в локальную — то, какая нода случайно выполняла
 код. Отсюда урок стенда: какая нода читала топик, меняется между прогонами
 (видно в колонке `consumer_host`), а куда легли данные — нет.
-У событий ключ — `cityHash64(ClientID)`, у заказов —
+Ключи шардирования: `cityHash64(ClientID)` у событий, `cityHash64(order_id)` у
-`cityHash64(order_id)`, у STG и таблиц ошибок — хеш сырой строки.
+заказов, `cityHash64` сырой строки у STG и у таблицы ошибок. У первых двух хеш
-Хеш распределяет числовые идентификаторы по шардам и направляет одинаковые
+выбран против перекоса: структурированный числовой идентификатор распределяется
-сообщения на один шард. У сырой строки и разобранного события разные
+по остатку от деления неравномерно. У сырого слоя выбора нет — строку иначе не
-ключи: они могут оказаться на разных шардах. Счетчики STG и ODS сравнивают
+разложишь; там хеш даёт другое свойство, одинаковые сообщения ложатся на один
-по всему кластеру через `_dist`, а не отдельно по каждой ноде.
+шард.
-При `INSERT INTO цель_dist SELECT … FROM источник_dist` важна настройка
+Ключи у слоёв разные, и это имеет наблюдаемое следствие: сырая строка и
-`parallel_distributed_insert_select`. При значении `2` и одном кластере
+разобранное из неё событие почти всегда оказываются на разных шардах.
-вставка может выполняться локально на шардах, сохраняя раскладку источника
+Пошардовые счётчики STG и ODS поэтому не сходятся и сходиться не должны —
-вместо ключа цели. Если ключи различаются, укажите
+сверять слои можно только через `_dist`.
 `parallel_distributed_insert_select = 0`: нода, принявшая запрос,
 соберет результат и распределит его по ключу цели. Так сделано в
 [`sql/ods/order_parse.sql`](../../sql/ods/order_parse.sql) и при сборке
 выручки. Неверную раскладку проверяют по `hostName()` и ожидаемому шарду
 строки; общий счет по `_dist` ее не показывает.
-События, `dds.session_dist` и `dds.identity_map_dist` распределены
+Разные ключи у слоёв ставят капкан на вставке `INSERT INTO цель_dist SELECT …
-по `cityHash64(client_id)` (в ODS поле называется `ClientID`). Данные
+FROM источник_dist`. Заводское значение `parallel_distributed_insert_select` —
-одного посетителя лежат вместе — это ко-локация. Заказы DDS и их сверка
+2: если обе таблицы на одном кластере, вставка исполняется локально на каждом
-сохраняют раскладку по `cityHash64(order_id)`. Обычное соединение допускается
+шарде, минуя ключ шардирования цели. Строки наследуют раскладку источника, и
-по ключу ко-локации; для остальных соединений применяется `GLOBAL`.
+ошибки при этом нет — расхождение видно только пересчётом ключей по
-Само совпадение ключей еще не гарантирует локального выполнения запроса
+`hostName()`. Так половина заказов и легла на оба шарда, где
-через представления — пример есть в [описании `daily_traffic`](dm.md#dmdaily_traffic_v).
+`ReplacingMergeTree` через границу шарда дубли не схлопывает (замер — «Что
 проверено», #137). Лекарство — явное `parallel_distributed_insert_select = 0`
 в `SETTINGS` такой вставки: раскладку делает инициатор, по ключу цели
 (`sql/ods/order_parse.sql`). Капкан ждёт и сборки DDS: они тоже будут читать
 `_dist` и писать в `_dist` с другим ключом.
-Для дневной пересборки DDS и DM результат сначала записывают
+Ключи ко-локации названы заранее, потому что на них стоит политика соединений из
-в промежуточную таблицу. Основная таблица в это время остается доступна
+раздела 6 спеки: обычное соединение разрешено только по ключу ко-локации, всё
-для чтения с прежними данными. Например, заказы записываются через
+прочее — через `GLOBAL`. Значит `dds.session_dist` и `dds.identity_map_dist`
-`dds.order_stage_dist` в `dds.order_stage_rep`, затем ее дневные разделы
+шардируются по `cityHash64(client_id)`. Объекты DDS с зерном заказа сохраняют
-заменяют разделы основной `dds.order_rep`.
+ко-локацию по `cityHash64(order_id)`; ключи остальных частей модели и витрин
 появляются вместе с ними.
-У промежуточной и основной таблиц должны совпадать структура, ключи
+Замена партиций не используется для `ods.order`: версии прошлых дней
-партиции и сортировки, первичный ключ и политика хранения. Поэтому
+доливаются, а прямое чтение Kafka не задаёт границы полного слепка ([ADR
-`dds.order_stage_rep` объявлена через `AS dds.order_rep` с совпадающими
+0010](../adr/0010-order-versions-in-ods.md)). Если партиционная пересборка
-ключами. Требования сверены через Context7 с
+понадобится будущим объектам DDS или DM, партиция-донор должна быть заранее
-[документацией ClickHouse](https://clickhouse.com/docs/sql-reference/statements/alter/partition#replace-partition)
+разложена по шардам по тому же ключу. Форму донора следует решать вместе с таким
-для схемы на ClickHouse 26.3. DDL показан в
+объектом, а не переносить на ODS заранее.
 Первым такой донор понадобился заказу DDS, и правило на нём видно целиком:
 `dds.order_stage_rep` объявлен через `AS dds.order_rep` и шардируется тем же
 `cityHash64(order_id)`. Совпадение структуры требует сама операция, а совпадение
 ключа — устройство замены: она идёт по локальным таблицам, шард за шардом, и
 строка, попавшая в доноре не на свой шард, при подмене пропала бы с одного шарда
 и задвоилась на другом. Доводы целиком — в
 [`sql/ddl/45-dds-tables.sql`](../../sql/ddl/45-dds-tables.sql).
 Промежуточная таблица должна также распределять строки по тому же ключу,
 здесь — `cityHash64(order_id)`. `REPLACE PARTITION` копирует раздел между
 локальными таблицами каждого шарда и не перераспределяет строки.
 Поэтому уже в промежуточной таблице заказ должен находиться на нужном шарде.
 Перед заменой вставка с `distributed_foreground_insert = 1` дожидается
 доставки данных на шарды.
 В `ods.order` этот способ не применяется: туда добавляют версии заказов
 из слепков, а актуальные строки выбираются при чтении
 ([ADR 0010](../adr/0010-order-versions-in-ods.md)).
 ## Служебные колонки
-STG сохраняет исходное сообщение в строке `raw` и добавляет сведения
+Собственные колонки не повторяют имён виртуальных. Виртуальные даёт движок:
-о доставке. JSON на этом шаге не разбирается: некорректное содержимое
+`_topic`, `_partition`, `_offset`, `_timestamp` у Kafka, `_shard_num` у
-тоже попадает в таблицу.
+`Distributed` и прочие. Если положить на диск колонку с таким же именем, в
 матвью перестанет читаться, что дано движком, а что положено нами, — а это
 ровно то различие, ради которого метаданные доставки и хранятся. Поэтому они
 ложатся под именами `kafka_topic`, `kafka_partition`, `kafka_offset`,
 `kafka_timestamp`, рядом — `consumer_host`, имя читавшей ноды: виртуальные
 колонки его не несут, а после записи в `Distributed` он уже невосстановим.
-| Колонка STG | Что хранит |
+Типы у них такие: `kafka_topic` и `consumer_host` — `LowCardinality(String)`,
-|---|---|
+значений мало и они повторяются; `kafka_partition` и `kafka_offset` — `UInt64`.
-| `kafka_topic` | Имя топика из виртуальной колонки Kafka `_topic` |
+С `kafka_timestamp` сложнее, и форма его решена на стенде. Меток времени движок
-| `kafka_partition` | Номер партиции из `_partition` |
+даёт две: `_timestamp` — `Nullable(DateTime)`, то есть секунды, и
-| `kafka_offset` | Позицию сообщения внутри партиции из `_offset` |
+`_timestamp_ms` — `Nullable(DateTime64(3))`, миллисекунды. Колонка объявлена
-| `kafka_timestamp` | Метку времени Kafka из `_timestamp_ms`, если она есть |
+`Nullable(DateTime64(3, 'UTC'))` и заполняется из `_timestamp_ms`: у брокера
-| `consumer_host` | Имя ноды, прочитавшей Kafka |
+метка миллисекундная, соседняя `_load_ts` тоже миллисекундная, а сырой слой
-| `_load_ts` | Реальное время записи сообщения в STG |
+хранит приехавшее, и округлять ему нечего. Обнуляемость нужна отдельно от
-| `_load_id` | Только у заказов: `run_id` запуска Airflow, который принял порцию |
+разрядности: брокер метку заполняет не всегда, а необнуляемый тип значил бы либо
 падение приёма на первом сообщении, либо тихие нули за 1970 год.
-Топик, партиция и смещение вместе позволяют найти сообщение Kafka.
+Заполняются все они выражением в `SELECT` матвью приёма, а не `DEFAULT` в
-`kafka_topic` и `consumer_host` имеют тип `LowCardinality(String)`,
+таблице. Для `consumer_host` это обязательно: `DEFAULT hostName()` вычисляется
-`kafka_partition` и `kafka_offset` — `UInt64`.
+на шарде-получателе, то есть назвал бы не ту ноду, которая читала топик, —
-`kafka_timestamp` имеет тип `Nullable(DateTime64(3, 'UTC'))`: сохраняет
+колонка молча отвечала бы на другой вопрос.
 миллисекунды и допускает отсутствие метки.
-Виртуальные колонки предоставляет движок, а колонки STG хранят значения
+Само сообщение лежит в колонке `raw` тем, чем пришло: чтец читает байты и ничего
-на диске. Их имена различаются, чтобы не скрыть виртуальную колонку
+не проверяет, поэтому там оказываются и целые сообщения, и мусор. События ниже
-собственной. Значения вычисляются в запросе приема. В частности,
+разбирают матвью ODS ([ADR 0005](../adr/0005-event-ingestion.md)), заказы —
-`hostName()` должен выполняться на ноде, читающей Kafka:
+пакетный шаг ([ADR 0008](../adr/0008-order-ingestion.md), [ADR
-`DEFAULT hostName()` только в локальной таблице назвал бы шард-получатель.
+0010](../adr/0010-order-versions-in-ods.md)).
-Таблицы STG используют `ReplicatedMergeTree` с
+Движок таблицы STG — обычный `ReplicatedMergeTree`, `ORDER BY (kafka_partition,
-`ORDER BY (kafka_partition, kafka_offset)`. Повторная доставка остается
+kafka_offset)`: разбор полётов идёт от «какое сообщение», другого ключа у
-отдельной строкой; STG нужен в том числе для разбора таких повторов.
+таблицы STG и нет. Замену версий сюда ставить нельзя — она отменила бы свойство
 слоя, ради которого он заведён: повтор доставки в STG обязан быть виден.
-`_load_ts` имеет тип `DateTime64(3, 'UTC')`. При переходе в ODS метка
+Метка времени загрузки зовётся `_load_ts`, тип `DateTime64(3, 'UTC')`. Ставится
-копируется из STG без пересчета. У событий она также выбирает последнюю
+она один раз при записи в STG: для событий — матвью приёма, для дневного слепка
-доставку; у заказов версию задает `snapshot_date`. `_load_id` заказа
+заказов — пакетным шагом. Дальше метка переносится в ODS как есть и отвечает на
-переносится в годную строку ODS и в таблицу ошибок.
+вопрос «когда строка приехала в хранилище», а не «когда её разобрали». В
-У непрерывного потока событий нет запуска Airflow, поэтому `_load_id`
+`ods.event` она же служит колонкой версии `ReplacingMergeTree` и схлопывает
-в его STG и ODS отсутствует.
+повтор доставки. У `ods.order` версию задаёт `snapshot_date` — дата слепка
 источника; `_load_ts` только показывает, когда конкретная строка приехала.
-Время события `UTCEventTime` и дата `EventDate` приходят из счетчика сайта.
+`created_at` и `updated_at` заказа к служебным колонкам хранилища не относятся.
-Поля заказа `created_at` и `updated_at` приходят из базы магазина.
+Они приезжают в сообщении как аудит строки в БД источника и в ODS разбираются в
-Они относятся к модельному времени; `_load_ts` — к реальным часам стенда.
+`DateTime64(3, 'UTC')`; ClickHouse их не создаёт и добавляет рядом собственную
-Например, событие июня можно загрузить в сентябре: его `EventDate`
+`_load_ts`. Совпадение слов «техническое время» не делает эти часы одной осью.
 останется июньской, а `_load_ts` будет сентябрьской.
-События разбираются материализованными представлениями. Автоматической
+Пакетной переобработки у событий в ODS нет: слой наполняют матвью, а не задание
-пакетной переобработки у них нет; сохраненный срез STG можно разобрать
+Airflow. Переделать разобранное руками можно вставкой из STG с фильтром по
-отдельным запросом до истечения срока хранения. При повторной вставке
+`_load_ts` в пределах трёхсуточного окна; ничья по версии разрешается в пользу
-с тем же ключом и `_load_ts` `ReplacingMergeTree` оставляет более поздно
+вставленного позже. Заказы разбирает пакетный шаг из неизменного среза STG по
-вставленную строку. Заказы разбирает задача Airflow по `_load_id`.
+`_load_id`; дневные партиции ODS он не заменяет.
-В DDS метки загрузки уже относятся к собственной сборке слоя —
+
-[пример заказа](dds/order.md#служебные-колонки).
+Имя согласовано с каноном служебных полей соседнего учебного стенда на
 Greenplum, чтобы словарь был общим у двух хранилищ; ведущее подчёркивание у
 технических колонок — распространённая запись,
 её же используют Fivetran, Airbyte и Stitch. С правилом выше это не спорит:
 запрещено совпадать с именами виртуальных колонок, а не носить подчёркивание.
 Общего идентификатора пачки загрузки (`_load_id`) нет. У потока событий нет ни
 пачки, ни `run_id`, и колонка была бы пустой формальностью. У заказов читатель
 назван: `_load_id` равен `run_id` Airflow и переносится из STG в годную строку
 ODS и в таблицу ошибок. Нужен ли он выше ODS, решается вместе с моделью DDS.
 ## Актуальные события
-Повторная отправка события может дать несколько строк в `ods.event_rep`.
+`ods.event_rep` хранит физически принятые версии события в
-Движок `ReplicatedReplacingMergeTree(_load_ts)` считает версиями строки
+`ReplacingMergeTree(_load_ts)`, а `ods.event_dist` служит для записи и
-с одинаковым полным ключом сортировки:
+диагностики доставки. Обычное чтение этой пары может показать несколько строк
-`(CounterID, EventDate, intHash32(ClientID), WatchID)`.
+одного `WatchID`, пока фоновые слияния их не схлопнули.
 При слиянии остается строка с максимальным `_load_ts`, то есть последняя
 доставка. Один `WatchID` обозначает событие, но физический ключ замены шире.
-`ods.event_v` читает `ods.event_dist FINAL`: выбирает актуальную строку
+`ods.event_v` — обычное представление над `ods.event_dist FINAL`. Оно сохраняет
-при выполнении запроса, не дожидаясь фоновых слияний. Поэтому события
+имена, типы и зерно события, но всегда возвращает актуальную версию. Актуальное
-считают через `_v`; число строк в `_dist` зависит от уже прошедших слияний.
+состояние читают через него, а не повторяют `FINAL` в каждом запросе.
-`dds.event_v` использует этот результат, дает колонкам имена в `snake_case`
+`dds.event_v` отвечает за другое: даёт событию язык бизнес-модели, в том
-и расшифровывает коды.
+числе snake_case-имена и расшифровку кодов.
-Выбор по полному `ORDER BY` и максимальной версии, включая чтение с `FINAL`,
+Типы ODS обычно повторяют контракт выгрузки. Денежный `purchaseRevenue` —
-сверен через Context7 с [документацией ClickHouse](https://clickhouse.com/docs/reference/engines/table-engines/mergetree-family/replacingmergetree).
+исключение: источник объявляет `Array(Float64)`, а материализованное
-В стенде закреплена версия 26.3.17.56; `_v` использует `FINAL`, чтобы
+представление ODS разбирает числа сырого JSON сразу в `Array(Decimal(18, 2))`.
-результат не зависел от фоновых слияний.
+DDS наследует этот тип без нового преобразования. Прямой разбор подтвержден
-
+документацией ClickHouse через Context7 и запросом к ClickHouse 26.3; сравнение
-Типы ODS повторяют [описание выгрузки](../formats/clickstream-event.md)
+с сырыми данными подтвердило: копейки всех покупок целы.
 с одним денежным исключением: `purchaseRevenue` объявлен источником
 как `Array(Float64)`, а из JSON разбирается сразу в
 `Array(Decimal(18, 2))`. Это сумма в рублях с копейками; DDS наследует тип.
 `productPrice` содержит округленные целые рубли и не подходит для
 восстановления точной суммы покупки. Прямой разбор `purchaseRevenue`
 проверен на ClickHouse 26.3; результаты сохранены в разделе «Что проверено».
 ## Версии заказов
 Слепки повторяют состояние заказов из семидневного окна источника.
 `ods.order_rep` хранит принятые версии в
-`ReplicatedReplacingMergeTree(snapshot_date)`: ключ сортировки — `order_id`,
+`ReplacingMergeTree(snapshot_date)`: ключ сортировки — `order_id`, партиция —
-партиция — `toDate(created_at)` в UTC. Запись через `ods.order_dist`
+`toDate(created_at)`. `ods.order_dist` шардирует по
-распределяет их по `cityHash64(order_id)`. У всех версий заказа одинаковы
+`cityHash64(order_id)`. Все версии заказа лежат в одной партиции, чтобы их могли
-день создания и шард, поэтому они могут заменять друг друга.
+схлопывать фоновые слияния, и на одном шарде, чтобы распределённый `FINAL`
 выбрал одного победителя.
-`ods.order_v` читает `_dist FINAL` и оставляет строку с максимальной датой
+Физическая пара нужна для загрузки и диагностики. Обычное чтение показывает
-слепка. Дата `snapshot_date` показывает последнее принятое наблюдение,
+версии, которые ещё не убрали фоновые слияния, и не является архивом истории.
-а `updated_at` — время изменения заказа в магазине. У неизменившегося
+`ods.order_v` служит поверхностью точного текущего состояния для следующих
-заказа в следующем слепке дата наблюдения обновится, время изменения — нет.
+слоёв. Представление сохраняет язык источника и не решает, какой станет модель
-
+DDS. `snapshot_date` в нём одновременно дата наблюдения и колонка версии. Она
-Источник выпускает один слепок на дату, а поздний слепок показывает
+не доказывает полноту принятой порции, поэтому ODS не публикует партиции по
-не менее новое состояние. Отсутствие заказа в следующем слепке
+дате слепка. Модель версионного ODS записана в
-не означает удаления. Физическая таблица не служит архивом:
+[ADR 0010](../adr/0010-order-versions-in-ods.md), выбор колонки версии описан в
-старые версии исчезают при фоновых слияниях.
+[ADR 0014](../adr/0014-order-version-snapshot-date.md), пакетный приём описан в
-
+[спецификации приёма заказов](orders/ingestion.md). Контракт следующего слоя
-Прием добавляет версии отдельными строками. `snapshot_date` не доказывает,
+задан в [модели заказа в DDS](dds/order.md).
 что Kafka отдала весь слепок, поэтому партиция по этой дате не заменяется.
 Подробности — [прием заказов](orders/ingestion.md),
 [ADR 0010](../adr/0010-order-versions-in-ods.md) и
 [ADR 0014](../adr/0014-order-version-snapshot-date.md).
 Следующий слой описан в [модели заказа DDS](dds/order.md).
 ## Часовые пояса
@@ -287,148 +308,169 @@ UTC+4), и пересчёт идёт один раз при наполнении
 ## Приём: поток и его свойства
-События принимаются непрерывно. Заказы читает отдельным запросом
+Раздел — про события. У заказов приём устроен иначе: слепок забирает по команде
-даг `orders_ingest` — [описание пакетного приема](orders/ingestion.md).
+даг `orders_ingest`, а не подписанная навсегда матвью — [ADR
-У событий путь такой:
+0008](../adr/0008-order-ingestion.md) и [спецификация приёма
 заказов](orders/ingestion.md).
-```text
+Цепочка одна: чтец топика → матвью → STG → матвью разбора → событие и таблица
-stg.hits_raw_kafka → stg.hits_raw_mv → stg.hits_raw_dist
+ошибок ODS.
                                      ├→ ods.event_mv → ods.event_dist
                                      └→ ods.event_errors_mv → ods.event_errors_dist
 ```
-Таблицы Kafka на обеих нодах используют одну группу `clickstream_hits`.
+Чтец стоит на обеих нодах и читает одной группой потребителей — имя группы
-Ноды делят чтение партиций топика. Разные группы прочитали бы каждая
+`clickstream_hits`, и оно одинаково на обеих нодах по построению: DDL идёт
-свою полную копию потока. Имя группы одинаково в DDL на всем
+`ON CLUSTER` и макросов в имени не содержит. Разные группы дали бы каждой ноде
-`clickstream_cluster`; конфигурация кластера —
+полную копию топика, и это отдельная сцена для лабы, а не рабочий режим. Имя
-`infra/clickhouse/config.d/cluster.xml`.
+кластера в `ON CLUSTER` и в движке `Distributed` — `clickstream_cluster`, оно
 задано в `infra/clickhouse/config.d/cluster.xml`.
-Материализованные представления разбора срабатывают на вставку
+**Источник матвью разбора — `stg.hits_raw_dist`, а не локальная таблица.**
-в `stg.hits_raw_dist`, до распределения строк по шардам.
+У матвью две привязки: источник, на вставку в который она срабатывает, и цель,
-Оба видят вставляемую порцию на той ноде, которая читает Kafka.
+куда пишет. Распределённая таблица — лицо слоя, локальная — его хранилище;
-`stg.hits_raw_mv` создается после них: его подключение запускает
+потребитель слоя цепляется к лицу. Практически это значит, что разбор идёт на
-чтение топика. Если начать чтение раньше, сообщения успеют попасть
+той же ноде, что читала Kafka, в момент вставки первой матвью — до раскладки по
-в STG без разбора в ODS.
+шардам.
-Условие приема проверяет три вещи:
+**Вставка фоновая, и окно потери мы принимаем.** Вставка в распределённую
 таблицу кладёт блок в локальный спул и сразу возвращает управление, а Kafka
 коммитит офсеты по факту работы матвью — то есть по факту записи в спул. Топик
 уже считает сообщение прочитанным, хотя на шарде его ещё нет: умри нода в этом
 промежутке — сообщения не перечитаются.
- корень `raw` — объект JSON;
+Закрывает окно настройка `distributed_foreground_insert = 1`, и на ETL-вставках
- набор верхнеуровневых ключей совпадает с 47 полями формата;
+Airflow она стоит — там это обычный `SETTINGS` у запроса. На пути приёма её нет,
- пять опорных полей, `WatchID`, `VisitID`, `ClientID`, `EventDate`
+и по трём причинам. Вставку выполняет фоновый поток Kafka-движка, своего запроса
-  и `UTCEventTime`, разбираются в ожидаемые типы.
+у него не бывает, так что настройка уровня запроса доехала бы только профилем
 пользователя в конфигурации ноды. Синхронный режим связывает шарды: пока второй
 недоступен, вставка падает, офсеты не коммитятся, и приём встаёт целиком — тогда
 как при фоновом первая нода продолжает принимать и копит спул для соседа.
 Платится при этом не одно ожидание на блок, а три распределённые вставки — STG,
 событие, ошибки, — и все внутри потока-потребителя, что само по себе повод для
 ребаланса по таймауту сессии. Против всего этого — окно в сотню миллисекунд на
 ноутбуке, где мир пересобирается одной командой. Размен не в пользу настройки, а
 компромисс полезнее показать, чем спрятать за галочкой.
-Остальные поля извлекаются по описанию выгрузки без отдельных проверок.
+Ещё одно место, где сырой слой хранит не всё приехавшее: запись с пустым
-Это граница приема: годная строка не означает, что проверен смысл
+значением и запись-надгробие проходят молча, не оставляя строки. Свойство
-всех 47 значений. Подробности — в [ADR 0005](../adr/0005-event-ingestion.md).
+измерено и принято осознанно — подробности в разделе «Что проверено».
-`ods.event_mv` принимает строки, для которых условие истинно,
+**Гарантии нет ни в одну сторону — есть два узких окна.** Окно потери описано
-`ods.event_errors_mv` — для которых оно ложно. Условие не должно
+выше: нода умерла между коммитом офсетов и сбросом спула. Окно дубля
-возвращать `NULL`: такую строку не выбрали бы ни оно, ни его отрицание.
+противоположное: нода умерла после записи на шард, но до коммита офсетов, и при
-Разбор использует функции без исключений на некорректном сообщении,
+перечитывании сообщение приедет второй раз. Сказать про такой приём «хотя бы
-поскольку ошибка материализованного представления прерывает вставку
+один раз» нельзя — это обещало бы, что потерь не бывает, а они возможны.
 и останавливает чтение Kafka до устранения причины.
-### Доставка и повторы
+Дубль ниже по течению ведёт себя по-разному. В ODS его схлопнет
 `ReplacingMergeTree`, а таблицы STG вовсе не устраняют дубли: перезаливка
 модельного дня честно удваивает `count()` в STG, и живёт эта пара до истечения
 срока хранения. Это свойство слоя, а не поломка, — но обещание идемпотентности
 конвейера к сырому слою не относится.
-Вставка в Distributed на этом пути фоновая: блок сначала записывается
+Оговорка к последнему: у семейства `Replicated*` есть своя дедупликация — блок с
-в локальную очередь на диске, затем отправляется на шарды.
+тем же хешем, вставленный повторно, отбрасывается (`insert_deduplicate`).
-Kafka подтверждает обработку после выполнения материализованных
+Удвоение строк STG проходит мимо неё только потому, что при повторном чтении
-представлений, когда данные еще могут находиться в очереди.
+`_load_ts` новый и хеш блока другой. Свойство слоя держится на этом, а не на
-Если после подтверждения потерять ноду вместе с очередью, сообщения
+отсутствии механизма.
 не перечитаются. Возможен и повтор: данные уже записались на шард,
 но подтверждение Kafka не успело сохраниться.
 Поэтому прием не гарантирует доставку каждого сообщения хотя бы один раз.
-В ETL-запросах Airflow `distributed_foreground_insert = 1` дожидается
+**Матвью разбора две, и их условия обязаны делить поток без зазора и без
-записи на шарды. У фонового приема событий этой настройки нет:
+нахлёста.** Одна забирает годные строки в `ods.event_dist`, вторая — брак в
-недоступность одного шарда тогда остановила бы весь прием. В принятом
+`ods.event_errors_dist`. Строка, подошедшая обеим, задвоится; не подошедшая ни
-режиме доступная нода продолжает принимать и накапливает очередь
+одной — исчезнет молча. Держится это формой: второе условие пишется буквальным
-для недоступного шарда. Ограничение сохранено для учебного стенда;
+отрицанием первого, а сам предикат NULL не возвращает ни в одной своей части, —
-подробности и наблюдения — в разделе «Что проверено».
+иначе трёхзначная логика даст строку, которую не возьмёт ни `условие`, ни
 `NOT условие`. Обнуляемый разбор в предикате поэтому есть, но заканчивается
 `IS NOT NULL`, а сравнения дают 0 или 1. Функции предиката не должны и бросать
 исключений: упавшая матвью
 роняет вставку и останавливает потребление до починки
 ([ADR 0005](../adr/0005-event-ingestion.md)).
-В STG повтор сохраняется, в ODS его устраняет выбор актуальной версии.
+Постоянной сверки **слоёв между собой** при этом нет и не должно быть. У сырого
-Хотя `Replicated*` умеет отбрасывать повторно вставленные одинаковые блоки,
+слоя срок жизни трое суток, а ODS хранит всё, поэтому равенство «строки STG =
-при новом чтении Kafka меняется `_load_ts`, а вместе с ним и хеш блока.
+события + ошибки» разъедется само: строки STG истекут раньше, а перезаливка
-Поэтому повторная отправка модельного дня увеличивает число строк STG.
+модельного дня задвоит их, тогда как в ODS тот же повтор схлопнется. Правило,
 красное в норме, учит не смотреть на оповещения ([ADR
 0002](../adr/0002-monitoring-scope.md)). Равенство проверено разовым опытом при
 исполнении #43, на управляемой пачке: отправили N сообщений — получили N строк
 STG и N в сумме событий и ошибок. Постоянной целью такой опыт не становится, и
 почему — в [карте проверок](testing.md), раздел «Интеграционная проверка
 постоянной целью не становится». Счёт актуальных событий идёт через
 `ods.event_v`, которое скрывает `FINAL`: голый `count()` по `ReplacingMergeTree`
 зависит от того, сколько мержей успело пройти, и спека это прямо запрещает
 (раздел 6).
-Пустое значение сообщения и значение `null` не дают строки даже в STG:
+**Постоянная сверка одна, и она другого рода** — не слой против слоя, а ODS
-чтец продвигает позицию Kafka, но не передает строку на разбор.
+против [паспорта мира](../../data/world-inventory.json), лежащего в git (`make
-Генератор таких сообщений не создает. Поведение измерено на стенде
+check-clickhouse`, пришла с #42). Разъехаться сама она не может, и в этом вся
-и описано в разделе «Что проверено».
+разница: паспорт описывает восемь дней стартового мира, счёт обрамлён их датами,
-
+повтор заливки схлопывается в `ods.event_v`, а срок хранения ей не помеха — ODS
-### Что можно сверять
+хранит всё. Обе стороны равенства зафиксированы: одна кодом генератора, другая
-
+файлом в git. У межслойной сверки такой опоры нет ни с одной стороны.
 Для короткого неизменного среза доставки можно проверить баланс:
 число строк STG равно сумме годных строк и ошибок до удаления повторов.
 Постоянно сравнивать полные таблицы так нельзя: STG удаляет старые данные,
 ODS оставляет события и объединяет повторные доставки.
 Счетчики по слоям тогда расходятся при штатной работе.
 `make check-clickhouse` сравнивает актуальные события в `ods.event_v`
 с [паспортом мира](../../data/world-inventory.json) только за восемь
 начальных дней. Эта проверка учитывает повторную отправку через `FINAL`
 и не зависит от срока жизни STG. Границы остальных проверок —
 в [карте проверок](testing.md).
 ## Срок жизни сырых данных
-TTL — правило автоматического удаления старых данных. В обеих таблицах
+Сырые данные в STG живут трое суток реального времени и уходят сами. Трое — это
-STG срок задан как три суток от `_load_ts`, по реальному времени загрузки.
+окно отладки: столько сырые данные хранятся на ноутбуке, чтобы менти успел
-Партиции тоже нарезаны по дню `_load_ts`. Это оставляет короткий период
+разобрать полёты, после чего перестаёт занимать место. Нарезка — по дню
-для поиска ошибок и повторного разбора, после которого данные освобождают
+загрузки, срок — по той же колонке `_load_ts`, снятие — целыми кусками
-место на диске.
+(`ttl_only_drop_parts`). В DDL значение проставлено явно, чтобы поведение не
 зависело от умолчания версии.
-Настройка `ttl_only_drop_parts = 1` удаляет только целые части данных —
+Нарезать сырые данные по модельному дню события было бы соблазнительно — он
-файлы, которые ClickHouse создает при вставках и объединяет при слияниях.
+единица переобработки и он же ключ партиции в ODS, — но чистку это ломает. Кусок
-Часть удаляется, когда срок истек у всех ее строк. Внутри партиции
+снимается целиком, только когда в нём истекли все строки, а в партиции
-дня загрузки возраст строк отличается не более чем на сутки.
+модельного дня лежит приехавшее в разное реальное время: мерж склеит куски
-Поэтому к трем суткам может добавиться до суток ожидания самой свежей
+разного возраста, самая свежая строка удержит весь кусок, и данные переживут
-строки части, а затем ожидание фоновой обработки TTL. Точного времени
+срок неограниченно.
 удаления правило не обещает.
-Модельная дата для TTL не подходит: события июня могут загружаться
+В партиции дня загрузки склейка идёт точно так же, и строки в ней тоже разного
-осенью, и срок от `EventDate` истек бы сразу. Партиция по модельному дню
+возраста — но не более чем на сутки, потому что партицию закрывает календарный
-тоже смешала бы доставки разного возраста: очередная отправка дня могла бы
+день. Отсюда и оценка: сырые данные живут трое суток плюс хвост до суток, а не
-продлевать хранение старых строк после слияния частей.
+ровно трое. Оговорка про сроки: TTL исполняется на мержах, а не по будильнику,
 так что «уходит само» здесь обещано, а «уходит вовремя» — нет.
-Для разбора сохраненных сообщений выбирайте небольшой срез по `_load_ts`.
+Модельного дня среди колонок STG нет вовсе. Он свойство содержимого, а
-Так запрос ограничивает партиции и сохраняет некорректные сообщения,
+содержимое разбирает ODS — там `EventDate` и живёт, ключом партиции. Сырые
-из которых модельную дату извлечь нельзя. `EventDate` появляется
+данные режутся по своим координатам: и разбор полётов, и переобработка фильтруют
-отдельной колонкой только в ODS. В [задании ступени 6](../labs/6-1-event-parsing.md)
+по `_load_ts`, попадая в ключ партиции, а не идя сплошным проходом. Фильтр по
-такой срез разбирается рядом с действующим приемом.
+модельному дню вдобавок пропускал бы битые строки — у них дата не извлекается.
 Две оси времени тут не совпадают намеренно. Ось модельного времени начинается в
 D0 и к реальному календарю не привязана; пакетный режим проигрывает две недели
 модельного мира за минуты реальных. Поэтому у переобработки и у гигиены диска
 разные часы, и обслуживают их разные средства. Декларативный TTL по модельной
 дате был бы просто сломан: он отсчитывает срок от реального «сейчас» и удалял бы
 эталонные дни прямо на входе.
 В бою сырой слой иногда собирают на движке `Null` — тогда он не хранится вовсе.
 Такой вариант отвергнут: на стенде сырые данные нужны для отладки, поэтому окно,
 а не ноль.
 ## Таблица ошибок
-`ods.event_errors_dist` содержит сообщения, отвергнутые разбором событий:
+`ods.event_errors` держит строки, не прошедшие строгий приём, вместе с их сырым
-исходный `raw`, сведения о доставке и класс ошибки `error_class`.
+текстом, метаданными доставки и классом брака. Ключи её собственные, потому что
-Класс имеет тип `LowCardinality(String)` и выбирается по первому
+у брака нет разобранных полей: шардируется `cityHash64` сырой строки —
-нарушенному условию:
+`ClientID` у строки, которая не разобралась, взять неоткуда; нарезается по дню
 загрузки, как и сырые данные; живёт месяц. Дольше сырых данных — намеренно: если
 брак истекает вместе с ними, разбираться к моменту разбирательства будет уже
 нечем. Снятие — целыми кусками (`ttl_only_drop_parts`), как у STG и по той же
 причине: строки в партиции дня загрузки разного возраста не более чем на сутки,
 и куску незачем переживать срок из-за самой свежей строки.
-1. `not_an_object` — корень JSON не объект;
+Класс брака лежит в колонке `error_class` типа `LowCardinality(String)`. Без неё
-2. `keyset_mismatch` — набор ключей не совпал с форматом;
+в таблице копятся строки «что-то не так» без ответа на «что именно», а витрине
-3. `key_field_unparsed` — одно из пяти опорных полей не разобралось.
+качества не на что опереться. Сами классы, их порядок и довод, почему порядок
 обязателен, — в [ADR 0005](../adr/0005-event-ingestion.md).
-Порядок важен: строка вместо объекта нарушает сразу несколько условий,
+Движок — обычный `ReplicatedMergeTree`, без замены версий: схлопывать брак не по
-но получает один класс. Полные условия — в
+чему, у него нет ключа сущности. `ORDER BY` — `(error_class, kafka_partition,
-[ADR 0005](../adr/0005-event-ingestion.md).
+kafka_offset)`: смотрят такую таблицу от класса, а внутри класса — по координатам
 доставки.
-`ods.order_errors_dist` хранит такой же набор сведений и `_load_id`
+`ods.order_errors` держит тот же диагностический минимум и `_load_id`
-запуска приема. Первые два класса совпадают с событиями,
+запуска. У заказов три класса по приоритету: `not_an_object`,
-третий называется `field_invalid`: у заказа проверяются все поля
+`keyset_mismatch`, `field_invalid`. Сырой текст остаётся рядом, поэтому класс не
-верхнего уровня. Точные правила — в [описании приема заказов](orders/ingestion.md#граница-строгого-приёма).
+разрастается до имени отдельного поля. Точная граница приёма — в
-
+[спецификации заказов](orders/ingestion.md).
 Таблицы ошибок используют `ReplicatedMergeTree` без замены версий:
 у некорректного сообщения может не быть разобранного ключа сущности.
 Шард выбирается по `cityHash64(raw)`, ключ сортировки —
 `(error_class, kafka_partition, kafka_offset)`, партиция — день `_load_ts`.
 Начать поиск можно с класса ошибки, затем перейти к сообщениям
 по координатам Kafka.
 Срок хранения — один месяц от `_load_ts`, удаление целыми частями
 с `ttl_only_drop_parts = 1`, как в STG. Ошибка вместе с исходным текстом
 остается доступна дольше остальных сырых сообщений. Повторная обработка
 может добавить тот же брак еще раз; у заказов повтор виден по совпадению
 `_load_id` и координат Kafka.
 ## Справочники
@@ -36,7 +36,7 @@ Airflow. В ClickHouse он не пишет ничего.
 | `metadata.yaml` | версия формата, `1.0.0`; больше в нем ничего нет |
 | `databases/clickhouse.yaml` | подключение к ClickHouse: URI без пароля и постоянный uuid |
 | `datasets/ClickHouse/*.yaml` | три витрины: `revenue_daily_v`, `purchase_vs_orders_v`, `daily_traffic_v` |
-| `charts/*.yaml` | девять графиков: четыре крупных числа, столбики выручки и кольцо долей, сводная таблица сверки, линии трафика и доля известных |
+| `charts/*.yaml` | три графика: столбики выручки, сводная таблица сверки, линии трафика |
 | `dashboards/business_stories.yaml` | дашборд «Бизнес-сюжеты» и раскладка панелей |
 Связаны файлы не путями, а uuid. Датасет называет `database_uuid`, график —
@@ -46,51 +46,20 @@ Airflow. В ClickHouse он не пишет ничего.
 Uuid у стенда розданы рукой: общее начало
 `19600000-0000-4000-8000-`, дальше номер объекта в последнем блоке — `1`–`3`
-у датасетов, `101`–`109` у графиков, `201` у дашборда
+у датасетов, `101`–`103` у графиков, `201` у дашборда
 (`…-000000000101`). Экспорт из интерфейса приносит свои, сгенерированные;
 их заменяют на эти, иначе повторный импорт заведет вторую копию объекта вместо
 обновления первой.
-Датасет несет русские имена колонок, формат чисел и метрики — а график только
+Датасет несет русские имена колонок, формат денег и метрику — а график только
 ссылается на них по имени. Значит, подпись или формат правятся в одном месте, а
-не в каждом графике. Два исключения проверены на живом стенде, Superset 6.1.
+не в каждом графике.
 Подписи оси график берет не из датасета, а из своего `y_axis_format`: без него
 ось выручки уходит в «1.2M». И разрез сводной таблицы подписан именем колонки
 (`mismatch_class`), хотя колонке даты в той же таблице русское имя достается.
 Датасеты объявлены физическими (`schema: dm`, `sql: null`), хотя за именем стоит
 представление ClickHouse. Импорт в источник не ходит и разницы между таблицей и
 представлением не знает, а виртуальный датасет со своим SQL просто повторил бы
 запрос, который уже живет в `sql/ddl/60-dm-views.sql`.
 ## Из чего собран экран
 Четыре строки панелей:
 - ряд крупных чисел — выручка, заказы, средний чек, посетители;
 - выручка по дням и категориям, рядом доля категорий кольцом;
 - сводная сверки purchase и заказов;
 - посетители и известные пользователи, рядом доля известных.
 Правая панель пары отвечает на вопрос «сколько из целого» и берет цвета левой:
 категория окрашена одинаково на столбиках и в кольце, доля известных — как
 линия известных пользователей рядом. Цвет закрепляет `label_colors` в
 `metadata` дашборда. Шесть категорий выписаны в него руками по каталогу
 генератора (`generator/src/clickstream_generator/catalog.py`): седьмая
 останется без закрепленного цвета, пока файл не поправят.
 Средний чек и доля известных считаются метриками датасета —
 `SUM(revenue) / nullIf(SUM(orders), 0)` и то же для доли известных. Знаменатель
 обернут не зря: на периоде без заказов деление Decimal на ноль в ClickHouse —
 не `nan`, а исключение, и панель показала бы ошибку вместо пустоты. У витрины
 выручки есть готовая колонка `aov`, но среднее по ней дало бы другое число:
 день с тремя заказами получил бы тот же вес, что день с тремя сотнями.
 «Период» — единственный фильтр дашборда, тип `filter_time` с пустой целью
 (`targets: [{}]`). Такой фильтр колонку не называет: он подставляет выбранный
 период в то временное условие, которое уже стоит у каждого графика. Поэтому
 сверка сужается по `order_day`, а остальные панели — по `report_date`.
 ## Импорт при каждой инициализации
 Последняя строка `infra/superset/init.sh`:
@@ -183,17 +152,6 @@ superset import-directory /app/import --overwrite
 завершается нулем в любом случае. Поэтому импорт проверяют глазами или
 запросом к API — но не тем, что команда отработала.
 **Знак рубля приходит не из формата валюты.** Символ Superset берет у
 `Intl.NumberFormat` по коду валюты и английской локали стенда: код `RUB`
 печатается как «RUB», а знак «₽» вызов роняет, и форматирование молча
 откатывается к числу без валюты. Поэтому единица стоит в названии панели —
 «Выручка, ₽», — а метрика несет обычный формат `,d`.
 **`label_colors` знает имя ряда, а не подпись.** Для разреза имя ряда — это
 значение колонки («Бытовая техника»), для графика без разреза — имя метрики
 (`known_share`), а не ее русская подпись. Цвет, закрепленный за подписью
 «Доля известных», не применяется.
 **`--overwrite` синхронизирует датасет разрушительно.** Колонки и метрики
 берутся из YAML целиком: добавленная в интерфейсе метрика или подпись колонки
 исчезнет при следующем старте контейнера. Правка датасета — это правка файла.
@@ -205,50 +163,3 @@ superset import-directory /app/import --overwrite
 живое подключение и хранилище пароля. Сами графики и дашборд ни одна цель не
 проверяет: их смотрят глазами после переинициализации. Полная карта целей — в
 [доке проверок](testing.md).
 ## Отклоненные варианты
 Оживить дашборд предложат снова, поэтому отказы записаны с доводами. Замерено
 на живом стенде 7 сентября 2026 года, Superset 6.1.
 **Карта регионов России.** Замысел стоял на клике: щелчок по региону
 перестраивает весь экран. Плагин Country Map кросс-фильтр не отдает вовсе —
 `behaviors` не объявлены, `setDataMask` не вызывается, а щелчок приближает
 карту. Без клика остается картинка, и она рассказывает меньше, чем кажется: 16
 городов стенда сворачиваются в 14 регионов из 83, и больше половины сессий
 приходится на один. Карта отдана факультативу «Добавь названия регионов в
 отчет»: там читатель собирает справочник сам, и она становится наградой за
 него.
 **Регион как общее измерение витрин.** Чтобы фильтр по региону действовал на
 весь экран, регион пришлось бы завести в каждой витрине: Superset датасеты
 между собой не соединяет, а фильтр по колонке, которой нет в датасете панели,
 отбрасывается с причиной `COL_NOT_IN_DATASOURCE`. У заказа географии нет — она
 бралась бы от человека через карту идентичностей и приписывалась бы сущности, у
 которой ее в источнике не было. Вдобавок не сходятся ритмы: витрина от карты
 идентичностей не замерзает никогда, а выручка живет окном последнего слепка
 ([дока DM](dm.md)). Стендовый словарь регионов отклонен раньше и по своей
 причине — он повторил бы урок `dictGet` каталога вторым разом.
 **Кросс-фильтрация между панелями.** Общих измерений у витрин почти нет:
 категория есть только у выручки, а день у сверки называется `order_day` против
 `report_date` у остальных. Клик перестроил бы часть экрана и оставил другую
 нетронутой, а вывод из этого читатель делает про данные, а не про устройство
 витрин. Панель фильтров этой болезнью не болеет — там колонка задается явно для
 каждой витрины, — поэтому фильтр периода дашборду разрешен, а кросс-фильтрация
 нет.
 **Вкладки и блоки «что смотреть».** Вкладки были условным вариантом: их
 заводят, когда экран перестает читаться одним взглядом. Четыре строки панелей
 читаются сразу, поэтому вкладки спрятали бы половину экрана за щелчком без
 выигрыша. Блок с текстом «что смотреть» рядом с панелью означал
 бы, что панель сама себя не объясняет: тогда чинить надо название и подписи, а
 не дописывать к ним пояснение.
 **Пороги и раскраска панелей.** Правило
 [спеки](../specs/2026-07-30-stand-v2-realism.md), раздел 9: на дашборд смотрят
 глазами, красное и зеленое живет в проверках.
 Поводы вернуться к разговору: плагин карты начинает отдавать кросс-фильтр; у
 заказа появляется адрес доставки; витрины получают общее измерение по своей
 причине, не ради дашборда.
@@ -36,13 +36,13 @@
 Стенд нужен трём целям из восьми. Цена — замер, см. «Что проверено».
 `make smoke` и `make check-services` перемерены 28 августа 2026 года,
 `make config-test` — 21 августа, `make check-clickhouse` — 19 августа,
-корневой `make lint` — 3 сентября, `make test` — 30 августа; остальные стоят с
+корневой `make lint` — 9 августа, `make test` — 30 августа; остальные стоят с
 замера 6 августа.
 | Цель | Откуда | Что утверждает | Стенд | Цена |
 |---|---|---|---|---|
 | `make config-test` | корень | Compose разбирается, файлы DAG и дашборды Grafana синтаксически целы, в diff нет пробельных ошибок. О работоспособности не говорит ничего | не нужен | 1 с |
-| `make lint` | корень | Код стенда и сборщик карты отформатированы и проходят ruff; готовый HTML карты соответствует исходникам | не нужен | 0,8 с |
+| `make lint` | корень | Код стенда — `dags/` и `infra/superset/` — отформатирован и проходит ruff | не нужен | 0,4 с |
 | `make smoke` | корень | Стенд **собран**: службы живы, порты отвечают, подключения настроены друг на друга. Вширь и по касательной к каждой службе. Единственная цель, которая здесь правда смоук | нужен | 25 с |
 | `make check-clickhouse` | корень | Всё, что спрашивают **у ClickHouse** и он отвечает сам: макросы, шарды, реплики, путь в keeper, ключ шардирования, очередь распределённых DDL, ответ словаря товаров, счёт событий стартового мира против паспорта | нужен | 24 с |
 | `make check-services` | корень | **Службы работают**: DAG запускается и доходит, топик создаётся и удаляется, Superset логинится и ходит в базу | нужен | 71 с |
@@ -128,7 +128,7 @@ ClickHouse отвечает сразу.
 Правки генератора добавляют к этому `make lint`, `make typecheck` и `make test`
 из каталога `generator/`: стенд им не нужен, а `make test` из них самая
-дорогая. Правки дагов, Superset и карты — корневой `make lint`.
+дорогая. Правки дагов и Superset — корневой `make lint`.
 Двадцать секунд из ее ста семидесяти шести — пересборка восьми модельных дней
 для сверки с паспортом мира (20,5 с из 176,5). Дешевле хеши не сравнить: чтобы
@@ -286,10 +286,6 @@ Kafka по той же причине спрашивают снаружи. Её
 ## Что проверено
 **Перезамер 3 сентября 2026 года при исполнении #222.** `make lint` прошел за
 0,768 секунды; в таблице 0,8 с. `ruff format --check` проверил 13 файлов стенда,
 включая исходники карты, а затем проверка рендера подтвердила свежесть HTML.
 **Калибровка заказной стороны 30 августа 2026 года при исполнении #194.**
 Пересборки эталонного мира не будет (#192), поэтому доли заказной стороны
 сверены замером внутренностей генератора — окно 28 модельных дней,
@@ -478,11 +474,11 @@ shell-версия узкой пересборки за 2 м 25 с пересо
 24 секунды. Это цена всей цели, а не одной новой строки.
 **Замер 9 августа 2026 года при появлении корневого `lint` (#65).** Три прогона
-подряд — 0,39, 0,36 и 0,39 секунды на трех файлах стенда, которые тогда входили в проверку; в таблице 0,4 с. На
+подряд — 0,39, 0,36 и 0,39 секунды на трёх файлах стенда; в таблице 0,4 с. На
 машине с непрогретым кешем первый прогон дороже: `uvx` сначала скачивает ruff.
 Тогда же снято, что двери не перекрываются: `ruff check --show-files` из корня
-перечислял ровно три файла стенда, из `generator/` — только файлы генератора.
+перечисляет ровно три файла стенда, из `generator/` — только файлы генератора.
 Корневой конфиг правила генератору не подменяет: конфиг ищется вверх по дереву
 от файла, и ближний выигрывает.
@@ -98,7 +98,7 @@ DDS складывает свою модель и называет атрибу
 | 41 | `productID` | `Array(String)` | `object` | `product_id` | id товаров события |
 | 42 | `productName` | `Array(String)` | `object` | `product_name` | названия тех же товаров |
 | 43 | `productCategory` | `Array(String)` | `object` | `product_category` | категории тех же товаров |
-| 44 | `productPrice` | `Array(Int64)` | `int64` | `product_price` | цена за штуку, округленная до целых рублей |
+| 44 | `productPrice` | `Array(Int64)` | `int64` | `product_price` | цена за штуку целым числом: деньги генератор считает целыми |
 | 45 | `productQuantity` | `Array(UInt64)` | `uint64` | `product_quantity` | количество штук каждого товара |
 | 46 | `productEventType` | `Array(String)` | `object` | `product_event_type` | действие с товаром: стенд шлёт add и purchase, полный словарь Метрики (detail, remove, impressions) не берём |
 | 47 | `ecommerce` | `String` | `object` | `ecommerce` | сырой JSON события, как отдаёт Метрика — материал лабы про разбор JSON внутри колонки |
@@ -1,49 +1,48 @@
 # Путеводитель по стенду
-Путеводитель объясняет, как данные поступают в хранилище, обрабатываются
+Если вы впервые видите стенд, начните отсюда. Путеводитель подскажет, на что
-и попадают в отчеты. В главах есть короткие примеры, которые можно выполнить
+смотреть и в каком порядке, а за подробностями отправит в справочники. Так вы
-на запущенном стенде перед переходом к учебным заданиям.
+разберетесь в устройстве, прежде чем браться за уроки.
-## Порядок чтения
+## Как читать
-Сначала запустите стенд по [инструкции](../../README.md#быстрый-старт).
+Тропа такая: [словарь понятий](../../CONTEXT.md) → главы путеводителя →
-Затем читайте главы по порядку и выполняйте примеры из них.
+[справочники `docs/architecture/`](../architecture/) →
-Незнакомые термины можно найти в
+[уроки](../labs/README.md).
 [словаре понятий](../../CONTEXT.md), а подробности устройства —
 в [технических справочниках](../architecture/). К ним достаточно обращаться
 по мере необходимости. После путеводителя переходите к
 [учебным заданиям](../labs/README.md).
-## Карта хранилища
+Словарь не надо читать подряд. Возвращайтесь к нему за незнакомым словом.
 Первая статья объясняет хранилище. Следом идет несколько статей об устройстве
 генератора; они понадобятся нескоро.
-[Интерактивная карта](architecture-map.html) показывает путь данных через слои.
+## Главы
 Gitea показывает HTML как текст. Откройте файл из своей копии репозитория
 или скачайте его кнопкой «Raw» и откройте в браузере.
 Сверяйтесь с картой при чтении главы «Хранилище и его слои».
 ## Содержание
 ### [Хранилище и его слои](storage-layers.md)
-Как меняются данные при переходе из Kafka в слои STG, ODS, DDS и DM.
+От события в Kafka до витрины: глава разбирает путь через STG, ODS, DDS и DM
-В конце главы вы посмотрите события, сессии и выручку с помощью SQL.
+и показывает, за что отвечает каждый слой.
-### [Генерация и обработка данных в Airflow](airflow-dags.md)
+### Потоки Airflow и даги модельного времени
-Какие даги создают новые данные, а какие обрабатывают их в хранилище.
+Шаговый даг играет модельный день, а дневной конвейер раскладывает данные по
-Вы сравните содержимое витрин до и после обработки нового дня.
+слоям. Глава поможет увидеть их связь и роль каждого дага. Пока главы нет,
 смотрите [справочник конвейера](../architecture/etl.md) и [справочник мира и
 дагов времени](../architecture/world.md).
-### [Мониторинг в Grafana](monitoring.md)
+### Мониторинг: куда смотреть
-Что показывают панели Grafana и как меняются их показания, пока в стенд
+Свежесть и поток данных, брак и отставание собраны на дашборде «Данные».
-поступают события и заказы. Вы увидите, почему заказы обновляются реже событий.
+Глава научит находить нужную панель и разбирать ее показания. Пока главы
 нет, смотрите [устройство мониторинга](../architecture/monitoring/README.md).
-### [Отчеты в Superset](superset.md)
+### Немного Superset
-Как Superset строит графики по витринам. Вы сравните числа на готовом графике
+Глава покажет, как витрина становится графиком и где проходит граница между
-с результатом SQL и узнаете, какие отчеты сохраняются при перезапуске стенда.
+своими объектами и теми, которые поднимает стенд. Пока главы нет, смотрите
 [справочник Superset](../architecture/superset.md).
-### [Генератор: откуда берутся данные](generator.md)
+### Генератор: откуда берутся данные
-Откуда берутся события и заказы, почему начальные данные повторяются
+Здесь генератор — источник данных, а не предмет изучения. Глава в общих
-и как сверить число загруженных событий с ожидаемым.
+чертах объяснит, откуда берутся события и заказы и в каком виде их получает
 хранилище. Пока главы нет, смотрите [`generator/`](../../generator/) и
 [описание события кликстрима](../formats/clickstream-event.md).
@@ -1,130 +0,0 @@
 # Генерация и обработка данных в Airflow
 Airflow управляет генерацией данных и их обработкой в хранилище. Это разные
 этапы: сначала в Kafka поступают события и заказы за день работы магазина,
 затем по ним рассчитываются данные DDS и витрины DM.
 Даг описывает задачи Airflow и порядок их выполнения.
 ```mermaid
 flowchart LR
    world_initialize --> etl_pipeline
    world_live_day --> etl_pipeline
    manual[ручной запуск] --> etl_pipeline
    etl_pipeline --> dds_transform --> dm_transform --> dq_check
    world_next_day --> sources[источники без ETL]
 ```
 ## Загрузка событий и заказов
 События поступают в топик `hits` и обрабатываются по мере поступления:
 материализованные представления переносят строки из STG в ODS без участия
 Airflow.
 Заказы поступают в топик `orders` раз в модельные сутки одной выгрузкой.
 Она содержит состояние заказов на конец дня и называется слепком.
 Даг `orders_ingest` загружает ее целиком. Такой способ приема называется
 [пакетным](../../CONTEXT.md).
 ## Генерация модельных дней
 В документации миром называется учебный магазин с его посетителями,
 товарами и заказами. Время в нем идет отдельно от календарного.
 Два дага с тегом «жизненный цикл мира» создают начальные данные:
 | Даг | Что делает |
 |---|---|
 | `world_initialize` | Создает начальные данные, если их еще нет |
 | `world_recreate` | Удаляет прикладные данные и создает их заново |
 Для добавления следующих дней есть три дага с тегом «модельное время»:
 | Даг | Что делает |
 |---|---|
 | `world_next_day` | Генерирует данные за следующие дни без пауз между событиями |
 | `world_live_day` | Генерирует данные за следующий день постепенно, примерно за 24 минуты |
 | `world_live` | Запускает `world_live_day` день за днем, пока снят с паузы |
 В переменной Airflow `world_position` хранится номер следующего дня для
 генерации. Например, при значении `8` генератор уже отправил события
 за дни с 0 по 7.
 `world_next_day` и `world_live_day` сначала отправляют события дня D,
 затем — слепок заказов за предыдущий день D−1. Они ждут, пока `orders_ingest`
 загрузит слепок, и только после успешного завершения дня обновляют
 `world_position`. Если генерация или прием данных завершились с ошибкой,
 номер дня остается прежним. Подробности — в [справочнике генератора
 и модельного времени](../architecture/world.md#даги-модельного-времени).
 ## Обработка данных в хранилище
 Даг `etl_pipeline` по очереди запускает `dds_transform`, `dm_transform`
 и `dq_check`, дожидаясь завершения каждого. Они рассчитывают данные DDS,
 обновляют витрины DM и проверяют качество результата.
 При запуске `etl_pipeline` не нужно указывать даты. Дни для обработки
 определяются по `world_position` и по уже загруженным данным в слоях.
 Детали есть в
 [справочнике конвейера](../architecture/etl.md#объём-прогона).
 После `world_next_day` новые события и заказы уже загружены, но данные DDS
 и DM еще не пересчитаны: запустите `etl_pipeline` вручную.
 `world_live_day` запускает его автоматически и ждет завершения. Поэтому
 `world_live_day` может продолжать работу после окончания генерации за день.
 ## Если даг завершился с ошибкой
 Ошибка в `etl_pipeline` не меняет `world_position`: генерация и прием
 данных за день уже завершились. После устранения причины ошибки
 перезапустите конвейер вручную. Даты для повторной обработки он определит сам.
 Кто запускает конвейер, описано в
 [разделе о трех путях запуска](../architecture/etl.md#три-пути-запуска).
 За качество данных отвечают проверки DQ (Data Quality) в даге `dq_check`.
 Если проверка находит расхождение, задача завершается с ошибкой и записывает
 в журнал ключи строк, которые ее не прошли. Состав
 проверок описан в [разделе «Звено DQ
 конвейера»](../architecture/dm.md#звено-dq-конвейера).
 ## Поиск дагов в Airflow
 Даги мира ищите по тегам «модельное время» и «жизненный цикл мира». Остальные
 даги ищите по тегам «заказы», `etl`, `dds`, `dm` и `dq`. `homework_check` с
 тегами `dm` и `labs` проверяет домашние работы; о нем рассказано в учебных
 заданиях.
 ## Один день от генерации до витрин
 Откройте Airflow по адресу из раздела [«Адреса и
 пароли»](../../README.md#адреса-и-пароли). В Admin → Variables найдите
 `world_position` и запомните его значение. Затем запустите `world_next_day`
 на один день по [инструкции из README](../../README.md#добавить-данные-за-следующие-дни). Убедитесь, что
 `orders_ingest` завершился успешно, а в витринах нового дня еще нет.
 Значение `world_position` должно увеличиться на один.
 Запустите `etl_pipeline` вручную и дождитесь его завершения.
 В DBeaver, подключенном по
 [инструкции](../../README.md#подключиться-из-dbeaver), выполните два запроса:
 ```sql
 SELECT report_date, visitors, known_users
 FROM dm.daily_traffic_v
 ORDER BY report_date DESC
 LIMIT 3;
 SELECT report_date, sum(revenue) AS revenue
 FROM dm.revenue_daily_v
 GROUP BY report_date
 ORDER BY report_date DESC
 LIMIT 3;
 ```
 В витрине трафика уже есть новый день, а в выручке последняя дата —
 предыдущий день. Причина в выгрузке заказов: вместе с событиями дня D
 приходит слепок за день D−1. Выручка дня D появится после генерации
 дня D+1 и запуска конвейера.
 ## Следующая глава и справочники
 Детали — в справочниках [конвейера](../architecture/etl.md) и
 [мира](../architecture/world.md). Следующая глава —
 [«Мониторинг в Grafana»](monitoring.md).
@@ -1,9 +0,0 @@
 # Интерактивная карта хранилища
 `map.yaml` хранит слои, узлы, стрелки и тексты карточек.
 `template.html` задает внешний вид и поведение карты.
 `render.py` вкладывает данные в шаблон и пишет файл рядом с главами.
 Правьте исходники, а не `architecture-map.html`.
 Пересоберите карту командой:
 `uv run docs/handbook/architecture-map/render.py`.
 Проверьте свежесть готового файла с флагом `--check`.
@@ -1,693 +0,0 @@
 title: Карта слоев хранилища
 lead: Проследите путь событий и заказов от Kafka до отчетов.
 chapter_url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/handbook/storage-layers.md#user-content-хранилище-и-его-слои
 intro:
  - Выберите объект, чтобы узнать, что он хранит, как его читать и откуда в него поступают данные.
  - Выберите стрелку, чтобы посмотреть способ обработки и открыть SQL-запрос.
  - Для выбранного объекта подсвечиваются все пути, по которым данные поступают в него и используются дальше.
  - Кнопки «События» и «Заказы» выделяют нужный поток. Остальные объекты остаются на месте, но становятся бледнее.
  - Если вы впервые знакомитесь со слоями хранилища, начните с главы по ссылке ниже.
 streams:
  all: Все
  events: События
  orders: Заказы
 dictionary:
  title: Словарь
  caption: справочные данные
 layers:
  - id: kafka
    title: Kafka
    caption: сообщения источников
  - id: stg
    title: STG
    caption: исходные сообщения
  - id: ods
    title: ODS
    caption: данные разобраны по полям
  - id: dds
    title: DDS
    caption: события, заказы и сессии
  - id: dm
    title: DM
    caption: витрины для отчетов
 mechanisms:
  - id: materialized_view
    label: материализованное представление
    line: solid
    rhythm: непрерывно, по мере прихода сообщений
  - id: airflow_dag
    label: даг Airflow
    line: dashed
    rhythm: 'пакетно: раз в модельные сутки (`orders_ingest`) или при каждом запуске конвейера'
  - id: view
    label: представление
    line: dotted
    rhythm: при запросе к представлению, без копирования данных
 nodes:
  - id: kafka_hits
    name: hits
    layer: kafka
    order: 0
    streams: [events]
    what: Топик Kafka с событиями кликстрима. Каждое сообщение содержит одно событие.
    read: "Для просмотра загруженных сообщений используйте `stg.hits_raw_dist`. Таблица `stg.hits_raw_kafka` служит для приема из топика."
    fill:
      - "Генератор отправляет события без пауз в пакетном режиме или постепенно в живом режиме."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-при%D1%91м-поток-и-его-свойства
      - label: Формат
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/formats/clickstream-event.md#user-content-описание-выгрузки-событие-кликстрима
  - id: kafka_orders
    name: orders
    layer: kafka
    order: 1
    streams: [orders]
    what: "Топик Kafka с дневными выгрузками заказов — слепками. Каждый слепок содержит состояние заказов за последние семь модельных дней."
    read: "Для просмотра загруженных сообщений используйте `stg.orders_raw_dist`. Таблица `stg.orders_raw_kafka` служит для приема из топика."
    fill:
      - "После генерации событий дня D источник отправляет слепок заказов за предыдущий день D−1."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/orders/ingestion.md#user-content-поток-данных
      - label: Устройство слепка
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/orders/snapshot.md#user-content-слепок-и-его-доставка
  - id: stg_hits
    name: stg.hits_raw_dist
    layer: stg
    order: 0
    streams: [events]
    what: "Исходное сообщение события и сведения о его доставке из Kafka. Содержимое сохраняется целой строкой, без разбора на поля."
    read: 'Читайте `_dist`: у STG нет представления `_v`, а распределенная таблица показывает оба шарда.'
    parts:
      - "`stg.hits_raw_kafka` — таблица для чтения сообщений топика `hits`."
      - "`stg.hits_raw_rep` — реплицируемая таблица на шарде."
      - "`stg.hits_raw_dist` — распределенная таблица для записи и чтения."
      - "`stg.hits_raw_mv` — материализованное представление, которое записывает сообщения из Kafka в STG."
    fill:
      - '`stg.hits_raw_mv` пишет непрерывно, по мере прихода сообщений.'
      - Строки хранятся не менее трех суток от загрузки. Удаление целыми частями таблицы добавляет до суток к этому сроку; оно выполняется при очередном слиянии по TTL.
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-при%D1%91м-поток-и-его-свойства
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/10-stg-tables.sql
      - label: DDL материализованного представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/40-stg-views.sql
  - id: stg_orders
    name: stg.orders_raw_dist
    layer: stg
    order: 1
    streams: [orders]
    what: "Исходные строки выгрузки заказов, сведения о доставке и идентификатор загруженной партии `_load_id`."
    read: 'Читайте `_dist`: у STG нет представления `_v`, а распределенная таблица показывает оба шарда.'
    parts:
      - "`stg.orders_raw_kafka` — таблица для чтения топика `orders` на первом узле."
      - "`stg.orders_raw_rep` — реплицируемая таблица на шарде."
      - "`stg.orders_raw_dist` — распределенная таблица для записи и чтения."
    fill:
      - Задача `pull_batch` дага `orders_ingest` загружает слепок раз в модельные сутки.
      - Строки хранятся не менее трех суток от загрузки. Удаление целыми частями таблицы добавляет до суток к этому сроку; оно выполняется при очередном слиянии по TTL.
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/orders/ingestion.md#user-content-поток-данных
      - label: DDL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/10-stg-tables.sql
  - id: ods_event
    name: ods.event_v
    layer: ods
    order: 0
    streams: [events]
    what: "События, разобранные на колонки с типами данных. Имена полей сохранены как в источнике."
    read: "Читайте `ods.event_v`: представление использует `FINAL` и возвращает последнюю версию каждого события."
    parts:
      - '`ods.event_rep` — реплицируемая таблица версий события на шарде.'
      - '`ods.event_dist` — распределенная таблица записи и диагностики.'
      - '`ods.event_v` — представление актуального состояния с `FINAL`.'
      - '`ods.event_mv` — материализованное представление для разбора сообщений STG без ошибок.'
    keys:
      - '`WatchID` — тот же идентификатор, что `event_id` в DDS.'
      - '`ClientID` — тот же посетитель, что `client_id` в DDS.'
      - '`EventDate` — тот же день, что `event_date` в DDS.'
    fill:
      - '`ods.event_mv` разбирает строки непрерывно, по мере записи в STG.'
      - '`ReplacingMergeTree(_load_ts)` хранит версии, а `FINAL` выбирает актуальную.'
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-актуальные-события
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/20-ods-tables.sql
      - label: DDL представлений
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/30-ods-views.sql
  - id: ods_event_errors
    name: ods.event_errors_dist
    layer: ods
    order: 1
    streams: [events]
    what: "Сообщения событий, которые не удалось разобрать по правилам ODS. Сохранены исходная строка, класс ошибки и сведения о доставке."
    read: 'Читайте `_dist`: представления `_v` нет, а распределенная таблица показывает ошибки с обоих шардов.'
    parts:
      - '`ods.event_errors_rep` — реплицируемая таблица ошибок на шарде.'
      - '`ods.event_errors_dist` — распределенная таблица чтения и записи.'
      - '`ods.event_errors_mv` — материализованное представление для отбора сообщений STG с ошибками.'
    fill:
      - '`ods.event_errors_mv` пишет непрерывно, по мере записи в STG.'
      - Ошибки хранятся один месяц. Остальные события продолжают загружаться.
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-таблица-ошибок
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/20-ods-tables.sql
      - label: DDL материализованного представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/30-ods-views.sql
  - id: ods_order
    name: ods.order_v
    layer: ods
    order: 2
    streams: [orders]
    what: "Последняя загруженная версия заказа с именами полей из источника. Состав заказа пока хранится как фрагмент JSON."
    read: 'Читайте `ods.order_v`: запрос представления с `FINAL` возвращает последнюю версию по `snapshot_date`.'
    parts:
      - '`ods.order_rep` — реплицируемая таблица версий заказа на шарде.'
      - '`ods.order_dist` — распределенная таблица записи и диагностики.'
      - '`ods.order_v` — представление текущего состояния с `FINAL`.'
    keys:
      - '`order_id` — тот же заказ в `dds.order_v` и `dm.purchase_vs_orders_v`.'
      - '`user_id` — пользователь магазина, который переходит в заказ DDS.'
    fill:
      - Задача `parse_batch` дага `orders_ingest` разбирает загруженный слепок раз в модельные сутки.
      - '`ReplacingMergeTree(snapshot_date)` оставляет версию из последнего принятого слепка.'
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-версии-заказов
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/20-ods-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/30-ods-views.sql
  - id: ods_order_errors
    name: ods.order_errors_dist
    layer: ods
    order: 3
    streams: [orders]
    what: "Строки выгрузки заказов, которые не удалось разобрать по правилам ODS. Сохранены исходная строка, класс ошибки и `_load_id`."
    read: 'Читайте `_dist`: представления `_v` нет, а распределенная таблица показывает ошибки с обоих шардов.'
    parts:
      - '`ods.order_errors_rep` — реплицируемая таблица ошибок на шарде.'
      - '`ods.order_errors_dist` — распределенная таблица чтения и записи.'
    fill:
      - Задача `parse_batch` дага `orders_ingest` сохраняет строки с ошибками при разборе той же выгрузки, из которой загружаются заказы.
      - Ошибки хранятся один месяц. Остальные заказы продолжают загружаться.
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-таблица-ошибок
      - label: DDL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/20-ods-tables.sql
  - id: dds_event
    name: dds.event_v
    layer: dds
    order: 0
    streams: [events]
    what: "События с названиями полей, принятыми в DDS. Например, `WatchID` переименован в `event_id`, а числовой код устройства заменен названием категории."
    read: "Читайте `dds.event_v`: представление возвращает явно перечисленные колонки DDS."
    parts:
      - '`dds.event_v` — только представление над `ods.event_v`; своей таблицы в DDS нет.'
    keys:
      - '`event_id` — тот же идентификатор, что `WatchID` в ODS.'
      - '`client_id` — тот же посетитель, что `ClientID` в ODS; соединяет событие с сессией и картой идентичностей.'
      - '`event_date` — тот же день, что `EventDate` в ODS.'
      - '`purchase_id[1]` — тот же заказ, что `order_id` в DDS и DM.'
    fill:
      - "При запросе к `dds.event_v` данные читаются из актуальных событий ODS. Отдельная загрузка в DDS не нужна."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/event.md#user-content-форма
      - label: DDL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/50-dds-views.sql
  - id: dds_session
    name: dds.session_v
    layer: dds
    order: 1
    streams: [events]
    what: "Сессии, рассчитанные дагом `dds_transform` по событиям посетителя. Новая сессия начинается после паузы дольше 30 минут или при смене модельной даты."
    read: "Читайте `dds.session_v`: здесь есть начало, конец, длительность сессии, показатели событий и служебные поля загрузки."
    parts:
      - '`dds.session_rep` — реплицируемая таблица сессий на шарде.'
      - '`dds.session_dist` — распределенная таблица загрузки и диагностики.'
      - '`dds.session_stage_rep` — промежуточная таблица для пересчета данных по дням на шарде.'
      - '`dds.session_stage_dist` — распределенная таблица для записи и чтения промежуточных данных.'
      - '`dds.session_v` — представление для чтения готовых данных.'
    keys:
      - '`client_id` — тот же посетитель, что в событии DDS и карте идентичностей.'
      - '`session_date` — день, который в `dm.daily_traffic_v` называется `report_date`.'
    fill:
      - "При каждом запуске `dds_transform` выбирает дни от первого пропущенного в DDS до последнего дня с завершенной генерацией."
      - "Задача `session.rebuild` рассчитывает данные в промежуточной таблице (доноре). `session.replace` заменяет ими дневные партиции основной таблицы."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/session.md#user-content-движок-и-наполнение
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/45-dds-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/50-dds-views.sql
  - id: dds_order
    name: dds.order_v
    layer: dds
    order: 2
    streams: [orders]
    what: "Последнее известное состояние заказа, подготовленное для анализа. Артикулы, количества и цены товаров хранятся в массивах; элементы с одинаковым индексом относятся к одной позиции заказа."
    read: "Читайте `dds.order_v`, чтобы получить готовые заказы из основной таблицы."
    parts:
      - '`dds.order_rep` — реплицируемая таблица заказов на шарде.'
      - '`dds.order_dist` — распределенная таблица загрузки и диагностики.'
      - '`dds.order_stage_rep` — промежуточная таблица для пересчета данных по дням на шарде.'
      - '`dds.order_stage_dist` — распределенная таблица для записи и чтения промежуточных данных.'
      - '`dds.order_v` — представление для чтения готовых данных.'
    keys:
      - '`order_id` — тот же заказ, что в ODS, событии покупки и витрине сверки.'
      - '`user_id` — пользователь магазина, который входит в карту идентичностей.'
      - '`item_sku` — тот же артикул, что `sku` в `dic.products`.'
      - '`order_date` — день, который в витринах называется `report_date` или `order_day`.'
    fill:
      - "При каждом запуске `dds_transform` пересчитывает дни заказов из последнего слепка и заполняет пропуски в DDS."
      - "Задача `order.rebuild` рассчитывает данные в промежуточной таблице (доноре). `order.replace` заменяет ими дневные партиции основной таблицы."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/order.md#user-content-движок-и-наполнение
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/45-dds-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/50-dds-views.sql
  - id: dds_identity
    name: dds.identity_map_v
    layer: dds
    order: 3
    streams: [events, orders]
    what: "Связи между посетителем сайта и пользователем магазина. Они появляются, когда событие покупки сопоставлено с заказом по его номеру."
    read: "Читайте `dds.identity_map_v`: представление с `FINAL` возвращает последнюю версию каждой пары посетителя и пользователя."
    parts:
      - '`dds.identity_map_rep` — реплицируемая таблица версий пар на шарде.'
      - '`dds.identity_map_dist` — распределенная таблица записи.'
      - '`dds.identity_map_v` — представление последних версий строк с `FINAL`.'
    keys:
      - "`client_id` — идентификатор посетителя из cookie браузера, как в событии и сессии DDS."
      - "`user_id` — пользователь магазина из заказа DDS."
    fill:
      - "Задача `identity_map` дага `dds_transform` пересчитывает все известные пары после обновления заказов."
      - "При каждом запуске записывается новая версия набора связей."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/identity.md#user-content-сборка
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/45-dds-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/50-dds-views.sql
  - id: dm_daily_traffic
    name: dm.daily_traffic_v
    layer: dm
    order: 0
    streams: [events]
    what: "Число посетителей и известных пользователей за каждый день. Известными считаются пользователи магазина, связанные с посетителями сайта через карту идентичностей."
    read: "Читайте `dm.daily_traffic_v`: представление с `FINAL` возвращает последний результат расчета за каждый день."
    parts:
      - '`dm.daily_traffic_rep` — реплицируемая таблица версий счетчиков.'
      - '`dm.daily_traffic_dist` — распределенная таблица записи.'
      - '`dm.daily_traffic_v` — представление последних версий строк с `FINAL`.'
    keys:
      - '`report_date` — тот же день, что `session_date` в сессии DDS.'
    fill:
      - "Задача `daily_traffic` дага `dm_transform` при каждом запуске пересчитывает всю историю и записывает новую версию."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmdaily_traffic_v
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/55-dm-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/60-dm-views.sql
  - id: dm_revenue
    name: dm.revenue_daily_v
    layer: dm
    order: 1
    streams: [orders]
    what: "Выручка, число заказов и единиц товара за день по категориям. В расчет входят оплаченные заказы."
    read: "Читайте `dm.revenue_daily_v`, чтобы получить готовые показатели по дням и категориям товаров."
    parts:
      - '`dm.revenue_daily_rep` — реплицируемая таблица витрины на шарде.'
      - '`dm.revenue_daily_dist` — распределенная таблица загрузки.'
      - '`dm.revenue_daily_stage_rep` — промежуточная таблица для пересчета данных по дням на шарде.'
      - '`dm.revenue_daily_stage_dist` — распределенная таблица для записи и чтения промежуточных данных.'
      - '`dm.revenue_daily_v` — представление для чтения готовых данных.'
    keys:
      - '`report_date` — тот же день, что `order_date` в заказе DDS.'
      - '`product_category` — категория, найденная по `item_sku` заказа и ключу `sku` словаря.'
    fill:
      - "При каждом запуске `dm_transform` пересчитывает дни заказов из последнего слепка и заполняет пропущенные дни витрины."
      - "Задача `revenue_daily.rebuild` рассчитывает данные в промежуточной таблице (доноре). `revenue_daily.replace` заменяет ими дневные партиции витрины."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmrevenue_daily_v
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/55-dm-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/60-dm-views.sql
  - id: dm_purchase
    name: dm.purchase_vs_orders_v
    layer: dm
    order: 2
    streams: [events, orders]
    what: "Результат сверки покупок из кликстрима с заказами магазина. Для каждого номера заказа указано, совпали ли данные двух источников и какое расхождение найдено."
    read: "Читайте `dm.purchase_vs_orders_v`: если покупка или заказ отсутствует, поля этой стороны содержат `NULL`."
    parts:
      - '`dm.purchase_vs_orders_rep` — реплицируемая таблица сверки на шарде.'
      - '`dm.purchase_vs_orders_dist` — распределенная таблица загрузки.'
      - '`dm.purchase_vs_orders_stage_rep` — промежуточная таблица для пересчета данных по дням на шарде.'
      - '`dm.purchase_vs_orders_stage_dist` — распределенная таблица для записи и чтения промежуточных данных.'
      - '`dm.purchase_vs_orders_v` — представление для чтения готовых данных.'
    keys:
      - "`order_id` — тот же заказ, что `purchase_id[1]` в событии и `order_id` в заказе DDS."
      - "`order_day` — дата заказа; если заказа еще нет, берется дата события покупки."
    fill:
      - "При каждом запуске `dm_transform` пересчитывает дни последнего слепка, добавляет новые дни покупок, заполняет пропуски и повторяет сверку дней с покупками без заказа."
      - "Задача `purchase_vs_orders.rebuild` рассчитывает данные в промежуточной таблице (доноре). `purchase_vs_orders.replace` заменяет ими дневные партиции витрины."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmpurchase_vs_orders_v
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/55-dm-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/60-dm-views.sql
  - id: dm_dq
    name: dm.dq_summary_v
    layer: dm
    order: 3
    streams: [events, orders]
    what: "Последние результаты пяти проверок качества данных за каждый день. Историю запусков можно посмотреть в Airflow."
    read: "Читайте `dm.dq_summary_v`, чтобы увидеть результат каждой проверки за день."
    parts:
      - '`dm.dq_summary_rep` — реплицируемая таблица опубликованной сводки.'
      - '`dm.dq_summary_dist` — распределенная таблица чтения и записи.'
      - '`dm.dq_summary_stage_rep` — промежуточная таблица для результатов всех проверок за день.'
      - '`dm.dq_summary_stage_dist` — распределенная таблица для записи и чтения промежуточных данных.'
      - '`dm.dq_summary_v` — представление для чтения готовых данных.'
    fill:
      - Даг `dq_check` сначала рассчитывает результаты всех пяти проверок в промежуточной таблице, затем заменяет ими дневные партиции сводки.
      - '`sessions_vs_reference` — `sql/dq/sessions_vs_reference.sql`.'
      - '`classes_vs_inventory` — `sql/dq/classes_vs_inventory.sql` и эталонные числа из паспорта мира `data/world-inventory.json`.'
      - '`revenue_daily_vs_dds` — `sql/dq/revenue_daily_vs_dds.sql`.'
      - '`purchase_vs_orders_vs_dds` — `sql/dq/purchase_vs_orders_vs_dds.sql`.'
      - '`daily_traffic_vs_dds` — `sql/dq/daily_traffic_vs_dds.sql`.'
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmdq_summary
      - label: DDL таблиц
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/55-dm-tables.sql
      - label: DDL представления
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/60-dm-views.sql
  - id: dic_products
    name: dic.products
    layer: dic
    order: 0
    streams: [orders]
    what: "Словарь товаров. По артикулу можно получить название, бренд, категорию и цену. Эти данные доступны для расчетов в разных слоях."
    read: "Читайте `dic.products`: к словарю обращаются напрямую, суффикса `_v` у него нет."
    parts:
      - "`dic.products_file` — таблица, которая читает каталог товаров из CSV-файла репозитория."
      - "`dic.products` — словарь в памяти, загруженный из этой таблицы."
    keys:
      - '`sku` — тот же артикул, что `item_sku` в позиции заказа DDS.'
    fill:
      - "ClickHouse обновляет словарь из `dic.products_file` каждые 60–90 секунд согласно настройке `LIFETIME`."
    links:
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-справочники
      - label: DDL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/05-dic-catalog.sql
 edges:
  - id: hits_to_stg
    from: kafka_hits
    to: stg_hits
    mechanism: materialized_view
    streams: [events]
    rhythm: непрерывно, по мере прихода сообщений
    actor: "Таблица `stg.hits_raw_kafka` и материализованное представление `stg.hits_raw_mv`."
    join: "Каждое сообщение Kafka записывается целой строкой, без разбора на поля."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/40-stg-views.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-при%D1%91м-поток-и-его-свойства
  - id: stg_to_event
    from: stg_hits
    to: ods_event
    mechanism: materialized_view
    streams: [events]
    rhythm: непрерывно, по мере прихода сообщений
    actor: Материализованное представление `ods.event_mv` разбирает сообщения без ошибок.
    join: "Материализованное представление разбирает сообщение из STG на колонки с нужными типами данных."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/30-ods-views.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-при%D1%91м-поток-и-его-свойства
  - id: stg_to_event_errors
    from: stg_hits
    to: ods_event_errors
    mechanism: materialized_view
    streams: [events]
    rhythm: непрерывно, по мере прихода сообщений
    actor: "Материализованное представление `ods.event_errors_mv` отбирает сообщения с ошибками."
    join: "Сообщение, которое не удалось разобрать по правилам ODS, сохраняется целиком вместе с классом ошибки."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/30-ods-views.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/storage.md#user-content-таблица-ошибок
  - id: orders_to_stg
    from: kafka_orders
    to: stg_orders
    mechanism: airflow_dag
    streams: [orders]
    rhythm: одной выгрузкой, раз в модельные сутки
    actor: Задача `pull_batch` дага `orders_ingest` читает `stg.orders_raw_kafka`.
    join: "Строки выгрузки сохраняются целиком. Общий `_load_id` позволяет найти все строки одной загрузки."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/stg/orders_raw_load.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/orders/ingestion.md#user-content-одно-чтение-kafka
  - id: stg_to_order
    from: stg_orders
    to: ods_order
    mechanism: airflow_dag
    streams: [orders]
    rhythm: одной выгрузкой, раз в модельные сутки
    actor: Задача `parse_batch` дага `orders_ingest` записывает версии заказов без ошибок разбора.
    join: "Строка разбирается на колонки заказа. Версия определяется датой слепка `snapshot_date`."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ods/order_parse.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/orders/ingestion.md#user-content-граница-строгого-при%D1%91ма
  - id: stg_to_order_errors
    from: stg_orders
    to: ods_order_errors
    mechanism: airflow_dag
    streams: [orders]
    rhythm: одной выгрузкой, раз в модельные сутки
    actor: Задача `parse_batch` дага `orders_ingest` записывает строки с ошибками из загруженной выгрузки.
    join: "Строка с ошибкой сохраняется целиком вместе с классом ошибки и идентификатором загрузки."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ods/order_parse.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/orders/ingestion.md#user-content-граница-строгого-при%D1%91ма
  - id: ods_to_dds_event
    from: ods_event
    to: dds_event
    mechanism: view
    streams: [events]
    rhythm: при запросе к представлению, без копирования данных
    actor: "Представление `dds.event_v` читает данные из `ods.event_v`."
    join: "Колонки события переименовываются по правилам DDS. Данные не копируются в отдельную таблицу."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/ddl/50-dds-views.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/event.md#user-content-форма
  - id: event_to_session
    from: dds_event
    to: dds_session
    mechanism: airflow_dag
    streams: [events]
    rhythm: при каждом запуске `dds_transform`
    actor: Задачи `session.rebuild` и `session.replace` дага `dds_transform`.
    join: "События одного `client_id` за день `event_date` упорядочиваются по времени. Пауза дольше 30 минут начинает новую сессию. Ее `session_id` рассчитывается как `cityHash64(client_id, min(event_time))`."
    links:
      - label: SQL сборки
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dds/session_rebuild.sql
      - label: SQL замены
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dds/session_replace.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/session.md#user-content-движок-и-наполнение
  - id: order_to_dds
    from: ods_order
    to: dds_order
    mechanism: airflow_dag
    streams: [orders]
    rhythm: при каждом запуске `dds_transform`
    actor: Задачи `order.rebuild` и `order.replace` дага `dds_transform`.
    join: "Поля заказа приводятся к типам DDS, а позиции из JSON разбираются в массивы. Дата `order_date` рассчитывается из `created_at`."
    links:
      - label: SQL сборки
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dds/order_rebuild.sql
      - label: SQL замены
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dds/order_replace.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/order.md#user-content-движок-и-наполнение
  - id: event_to_identity
    from: dds_event
    to: dds_identity
    mechanism: airflow_dag
    streams: [events]
    rhythm: при каждом запуске `dds_transform`
    actor: Задача `identity_map` дага `dds_transform` соединяет покупки с заказами.
    join: "Событие покупки соединяется с заказом по `purchase_id[1] = order_id`. В результате связываются посетитель сайта и пользователь магазина."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dds/identity_map_rebuild.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/identity.md#user-content-сборка
  - id: order_to_identity
    from: dds_order
    to: dds_identity
    mechanism: airflow_dag
    streams: [orders]
    rhythm: при каждом запуске `dds_transform`
    actor: Задача `identity_map` дага `dds_transform` соединяет заказы с покупками.
    join: "Заказ соединяется с событием покупки по `order_id = purchase_id[1]`. Из заказа берется `user_id` пользователя магазина."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dds/identity_map_rebuild.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dds/identity.md#user-content-сборка
  - id: session_to_traffic
    from: dds_session
    to: dm_daily_traffic
    mechanism: airflow_dag
    streams: [events]
    rhythm: при каждом запуске `dm_transform`
    actor: Задача `daily_traffic` дага `dm_transform` считает посетителей по сессиям.
    join: "К сессиям присоединяется карта идентичностей по `client_id`, затем данные группируются по `session_date`. Эта дата записывается в `report_date`."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/daily_traffic_rebuild.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmdaily_traffic_v
  - id: identity_to_traffic
    from: dds_identity
    to: dm_daily_traffic
    mechanism: airflow_dag
    streams: [events]
    rhythm: при каждом запуске `dm_transform`
    actor: Задача `daily_traffic` дага `dm_transform` считает известных пользователей по `client_id`.
    join: "`GLOBAL LEFT JOIN` присоединяет карту идентичностей к сессиям по `client_id`. Сессии без известного пользователя тоже участвуют в расчете посетителей."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/daily_traffic_rebuild.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmdaily_traffic_v
  - id: order_to_revenue
    from: dds_order
    to: dm_revenue
    mechanism: airflow_dag
    streams: [orders]
    rhythm: при каждом запуске `dm_transform`
    actor: Задачи `revenue_daily.rebuild` и `revenue_daily.replace` дага `dm_transform`.
    join: "`ARRAY JOIN` разворачивает массивы `item_sku`, `item_quantity`, `item_price` в строки позиций заказа. Выручка считается по оплаченным заказам; `order_date` записывается в `report_date`."
    links:
      - label: SQL сборки
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/revenue_daily_rebuild.sql
      - label: SQL замены
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/revenue_daily_replace.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmrevenue_daily_v
  - id: products_to_revenue
    from: dic_products
    to: dm_revenue
    mechanism: airflow_dag
    streams: [orders]
    rhythm: при каждом запуске `dm_transform`
    actor: "Задача `revenue_daily.rebuild` дага `dm_transform`."
    join: "Функция `dictGet` получает категорию товара по артикулу `item_sku` из заказа. В словаре этому артикулу соответствует ключ `sku`."
    links:
      - label: SQL
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/revenue_daily_rebuild.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmrevenue_daily_v
  - id: event_to_purchase
    from: dds_event
    to: dm_purchase
    mechanism: airflow_dag
    streams: [events]
    rhythm: при каждом запуске `dm_transform`
    actor: Задачи `purchase_vs_orders.rebuild` и `purchase_vs_orders.replace` дага `dm_transform` читают покупки.
    join: "События покупки группируются по номеру `purchase_id[1]`, который получает имя `purchase_order_id`. Дата `event_date` записывается в `purchase_day`. Затем `GLOBAL FULL OUTER JOIN` сопоставляет покупки с заказами по `purchase_order_id = backend_order_id`."
    links:
      - label: SQL сборки
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/purchase_vs_orders_rebuild.sql
      - label: SQL замены
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/purchase_vs_orders_replace.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmpurchase_vs_orders_v
  - id: order_to_purchase
    from: dds_order
    to: dm_purchase
    mechanism: airflow_dag
    streams: [orders]
    rhythm: при каждом запуске `dm_transform`
    actor: Задачи `purchase_vs_orders.rebuild` и `purchase_vs_orders.replace` дага `dm_transform` читают заказы.
    join: "`order_id` заказа получает имя `backend_order_id`, а `purchase_id[1]` покупки — `purchase_order_id`. `GLOBAL FULL OUTER JOIN` соединяет их по `purchase_order_id = backend_order_id`. Покупки без заказа и заказы без покупки сохраняются; поля отсутствующей стороны содержат `NULL`."
    links:
      - label: SQL сборки
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/purchase_vs_orders_rebuild.sql
      - label: SQL замены
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/sql/dm/purchase_vs_orders_replace.sql
      - label: Справочник
        url: https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/architecture/dm.md#user-content-dmpurchase_vs_orders_v
@@ -1,54 +0,0 @@
 # /// script
 # requires-python = ">=3.13"
 # dependencies = ["pyyaml"]
 # ///
 """Собрать интерактивную карту хранилища из YAML и HTML-шаблона."""
 from __future__ import annotations
 import argparse
 import json
 from pathlib import Path
 import yaml
 ROOT = Path(__file__).parent
 SOURCE = ROOT / "map.yaml"
 TEMPLATE = ROOT / "template.html"
 OUTPUT = ROOT.parent / "architecture-map.html"
 MARKER = "/*__MAP_DATA__*/"
 NOTICE = (
    "<!-- Файл собран автоматически. Правьте architecture-map/map.yaml и "
    "template.html, затем выполните uv run "
    "docs/handbook/architecture-map/render.py. -->\n"
 )
 def render() -> str:
    """Подставить данные карты в шаблон без изменения порядка ключей."""
    data = yaml.safe_load(SOURCE.read_text(encoding="utf-8"))
    payload = json.dumps(data, ensure_ascii=False, indent=2)
    template = TEMPLATE.read_text(encoding="utf-8")
    return NOTICE + template.replace(MARKER, payload)
 def main() -> int:
    """Записать карту или проверить, что готовый файл не устарел."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--check", action="store_true", help="проверить готовый файл")
    args = parser.parse_args()
    rendered = render()
    if args.check:
        if not OUTPUT.exists() or OUTPUT.read_text(encoding="utf-8") != rendered:
            print(f"{OUTPUT} устарел; пересоберите карту")
            return 1
        print(f"{OUTPUT} соответствует исходникам")
        return 0
    OUTPUT.write_text(rendered, encoding="utf-8")
    print(f"собрана карта: {OUTPUT}")
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -1,454 +0,0 @@
 <!doctype html>
 <html lang="ru">
 <head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Карта слоев хранилища</title>
  <style>
    :root {
      color-scheme: light;
      --paper: #f7f7f5;
      --panel: #ffffff;
      --ink: #272a2d;
      --muted: #6b7177;
      --line: #8c9298;
      --soft: #e6e8e9;
      --accent: #b54a2a;
      --accent-soft: #f5ded7;
    }
    * { box-sizing: border-box; }
    body {
      margin: 0;
      background: var(--paper);
      color: var(--ink);
      font: 15px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
    }
    header { padding: 22px 26px 12px; }
    h1 { margin: 0 0 5px; font-size: 25px; }
    .lead { margin: 0; color: var(--muted); }
    .controls {
      display: flex;
      flex-direction: column;
      align-items: flex-start;
      gap: 8px;
      padding: 8px 26px 16px;
    }
    .switcher { display: flex; gap: 6px; }
    button {
      border: 1px solid #aeb3b7;
      border-radius: 18px;
      background: var(--panel);
      color: var(--ink);
      padding: 6px 13px;
      font: inherit;
      cursor: pointer;
    }
    button[aria-pressed="true"] {
      border-color: var(--accent);
      background: var(--accent-soft);
      color: #71301e;
    }
    button:focus-visible, [tabindex="0"]:focus-visible {
      outline: 3px solid #d79078;
      outline-offset: 2px;
    }
    .legend { display: flex; flex-wrap: wrap; gap: 15px; color: var(--muted); }
    .legend-item { display: inline-flex; align-items: center; gap: 7px; }
    .legend-line { width: 34px; border-top: 2px solid var(--line); }
    .legend-line.dashed { border-top-style: dashed; }
    .legend-line.dotted { border-top-style: dotted; }
    main {
      display: grid;
      grid-template-columns: minmax(0, 1fr) 350px;
      gap: 16px;
      padding: 0 18px 24px;
      align-items: start;
    }
    .map-scroll {
      overflow-x: auto;
      border: 1px solid #d7d9da;
      border-radius: 10px;
      background: var(--panel);
    }
    svg { display: block; width: 100%; min-width: 980px; height: auto; }
    .layer-title { font-size: 15px; font-weight: 700; text-anchor: middle; }
    .layer-caption { font-size: 11px; fill: var(--muted); text-anchor: middle; }
    .zone-caption { font-size: 12px; fill: var(--muted); }
    .column-guide { stroke: #eef0f1; stroke-width: 1; }
    .edge-line {
      fill: none;
      stroke: var(--line);
      stroke-width: 1.8;
      marker-end: url(#arrowhead);
      transition: opacity .15s, stroke .15s, stroke-width .15s;
    }
    .edge-line.dashed { stroke-dasharray: 8 6; }
    .edge-line.dotted { stroke-dasharray: 2 6; stroke-linecap: round; }
    .edge-hit { fill: none; stroke: transparent; stroke-width: 14; cursor: pointer; }
    .node { cursor: pointer; transition: opacity .15s; }
    .node rect {
      fill: #f1f2f2;
      stroke: #858b90;
      stroke-width: 1.2;
      rx: 7;
      transition: fill .15s, stroke .15s, stroke-width .15s;
    }
    .node text {
      fill: var(--ink);
      font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
      text-anchor: middle;
      pointer-events: none;
    }
    .node .stream-mark { fill: var(--muted); font: 10px system-ui, sans-serif; }
    .is-filtered, .is-context-dim { opacity: .16; }
    .is-path:not(.is-filtered), .is-hover:not(.is-filtered) { opacity: 1; }
    .is-path .edge-line, .edge.is-path .edge-line {
      stroke: var(--accent); stroke-width: 2.8; marker-end: url(#arrowhead-active);
    }
    .node.is-path rect { fill: var(--accent-soft); stroke: var(--accent); stroke-width: 2; }
    .node.is-hover rect { fill: #faefeb; stroke: #d79078; }
    .edge.is-hover .edge-line { stroke: #d79078; stroke-width: 2.2; }
    .node.is-selected rect { stroke-width: 3; }
    .edge.is-selected .edge-line { stroke-width: 4; }
    aside {
      min-height: 470px;
      padding: 20px;
      border: 1px solid #d7d9da;
      border-radius: 10px;
      background: var(--panel);
    }
    @media (max-width: 1530px) { main { grid-template-columns: minmax(0, 1fr); } aside { min-height: 0; } }
    aside h2 { margin: 0 0 3px; font-size: 20px; overflow-wrap: anywhere; }
    .meta { margin: 0 0 18px; color: var(--muted); }
    .card-section { margin-top: 17px; }
    .card-section h3 { margin: 0 0 5px; font-size: 13px; }
    .card-section p { margin: 0; }
    .card-section ul { margin: 5px 0 0; padding-left: 20px; }
    .card-section li + li { margin-top: 5px; }
    code { font: .92em ui-monospace, SFMono-Regular, Consolas, monospace; }
    a { color: #8a351e; text-underline-offset: 2px; }
    .hint { color: var(--muted); font-size: 13px; }
  </style>
 </head>
 <body>
  <header>
    <h1 id="page-title"></h1>
    <p class="lead" id="lead"></p>
  </header>
  <div class="controls">
    <div class="switcher" id="switcher" aria-label="Выбор потока"></div>
    <div class="legend" id="legend" aria-label="Механизмы переноса"></div>
  </div>
  <main>
    <div class="map-scroll">
      <svg id="map" viewBox="0 0 1230 470" role="group" aria-label="Путь данных через слои хранилища"></svg>
    </div>
    <aside id="details" aria-live="polite"></aside>
  </main>
  <script>
    const MAP = /*__MAP_DATA__*/;
    const NS = "http://www.w3.org/2000/svg";
    const state = { stream: "all", selected: null, hovered: null };
    const nodeById = new Map(MAP.nodes.map((node) => [node.id, node]));
    const mechanismById = new Map(MAP.mechanisms.map((item) => [item.id, item]));
    const positions = new Map();
    const svg = document.getElementById("map");
    const details = document.getElementById("details");
    function svgElement(name, attributes = {}) {
      const element = document.createElementNS(NS, name);
      Object.entries(attributes).forEach(([key, value]) => element.setAttribute(key, value));
      return element;
    }
    function layerTitle(layerId) { return MAP.layers.find((layer) => layer.id === layerId)?.title ?? MAP.dictionary.title; }
    function appendRichText(parent, value) {
      value.split("`").forEach((part, index) => {
        const element = index % 2 ? document.createElement("code") : document.createTextNode(part);
        if (index % 2) element.textContent = part;
        parent.append(element);
      });
    }
    function addSection(title, value) {
      if (!value || (Array.isArray(value) && !value.length)) return;
      const section = document.createElement("section");
      section.className = "card-section";
      const heading = document.createElement("h3");
      heading.textContent = title;
      section.append(heading);
      if (Array.isArray(value)) {
        const list = document.createElement("ul");
        value.forEach((item) => {
          const row = document.createElement("li");
          appendRichText(row, item);
          list.append(row);
        });
        section.append(list);
      } else {
        const paragraph = document.createElement("p");
        appendRichText(paragraph, value);
        section.append(paragraph);
      }
      details.append(section);
    }
    function addLinks(links) {
      if (!links?.length) return;
      const section = document.createElement("section");
      section.className = "card-section";
      const heading = document.createElement("h3");
      heading.textContent = "Ссылки";
      const list = document.createElement("ul");
      links.forEach((item) => {
        const row = document.createElement("li");
        const link = document.createElement("a");
        link.href = item.url;
        link.target = "_blank";
        link.rel = "noopener noreferrer";
        link.textContent = item.label;
        row.append(link);
        list.append(row);
      });
      section.append(heading, list);
      details.append(section);
    }
    function renderIntro() {
      details.replaceChildren();
      const heading = document.createElement("h2");
      heading.textContent = "Как пользоваться картой";
      details.append(heading);
      MAP.intro.forEach((line) => {
        const paragraph = document.createElement("p");
        paragraph.textContent = line;
        details.append(paragraph);
      });
      const paragraph = document.createElement("p");
      const link = document.createElement("a");
      link.href = MAP.chapter_url;
      link.target = "_blank";
      link.rel = "noopener noreferrer";
      link.textContent = "Открыть главу «Хранилище и его слои»";
      paragraph.append(link);
      details.append(paragraph);
      const hint = document.createElement("p");
      hint.className = "hint";
      hint.textContent = "Повторный щелчок или Esc снимает выделение.";
      details.append(hint);
    }
    function renderNodeCard(node) {
      details.replaceChildren();
      const heading = document.createElement("h2");
      heading.textContent = node.name;
      const meta = document.createElement("p");
      meta.className = "meta";
      meta.textContent = `${layerTitle(node.layer)} — ${node.streams.map((id) => MAP.streams[id]).join(", ")}`;
      details.append(heading, meta);
      addSection("Что это", node.what);
      addSection("Как читать", node.read);
      addSection("Связанные таблицы и представления", node.parts);
      addSection("Как связать данные", node.keys);
      addSection("Как обновляются данные", node.fill);
      addLinks(node.links);
    }
    function renderEdgeCard(edge) {
      details.replaceChildren();
      const heading = document.createElement("h2");
      heading.textContent = `${nodeById.get(edge.from).name} → ${nodeById.get(edge.to).name}`;
      details.append(heading);
      addSection("Способ обработки", mechanismById.get(edge.mechanism).label);
      addSection("Когда выполняется", edge.rhythm);
      addSection("Что выполняет обработку", edge.actor);
      addSection("Что происходит с данными", edge.join);
      addLinks(edge.links);
    }
    function layoutMap() {
      const nodeWidth = 180;
      const nodeHeight = 48;
      const columnStep = 250;
      MAP.layers.forEach((layer, index) => {
        const x = 20 + index * columnStep;
        MAP.nodes.filter((node) => node.layer === layer.id).forEach((node) => {
          positions.set(node.id, { x, y: 88 + node.order * 70, width: nodeWidth, height: nodeHeight });
        });
      });
      const dicX = 20 + ((MAP.layers.findIndex((layer) => layer.id === "dds") + MAP.layers.findIndex((layer) => layer.id === "dm")) * columnStep) / 2 + nodeWidth / 2 - 130;
      MAP.nodes.filter((node) => node.layer === "dic").forEach((node) => positions.set(node.id, { x: dicX, y: 402 + node.order * 70, width: 260, height: nodeHeight }));
    }
    function edgePath(edge, sameColumnIndex) {
      const source = positions.get(edge.from);
      const target = positions.get(edge.to);
      if (nodeById.get(edge.from).layer === "dic") {
        const x1 = source.x + source.width / 2;
        const y1 = source.y;
        const x2 = target.x;
        const y2 = target.y + target.height / 2;
        return `M ${x1} ${y1} C ${x1} ${y1 - 38}, ${x1} ${y2 + 48}, ${x2} ${y2}`;
      }
      const x1 = source.x + source.width;
      const y1 = source.y + source.height / 2;
      if (source.x === target.x) {
        const route = source.x + source.width + 16 + sameColumnIndex * 18;
        const y2 = target.y + target.height / 2;
        return `M ${x1} ${y1} C ${route} ${y1}, ${route} ${y2}, ${x1} ${y2}`;
      }
      const x2 = target.x;
      const y2 = target.y + target.height / 2;
      const bend = Math.max(18, (x2 - x1) / 2);
      return `M ${x1} ${y1} C ${x1 + bend} ${y1}, ${x2 - bend} ${y2}, ${x2} ${y2}`;
    }
    function drawMap() {
      const defs = svgElement("defs");
      [["arrowhead", "#8c9298"], ["arrowhead-active", "#b54a2a"]].forEach(([id, fill]) => {
        const marker = svgElement("marker", { id, viewBox: "0 0 8 8", refX: "7", refY: "4", markerWidth: "6", markerHeight: "6", orient: "auto" });
        marker.append(svgElement("path", { d: "M 0 0 L 8 4 L 0 8 z", fill }));
        defs.append(marker);
      });
      svg.append(defs);
      MAP.layers.forEach((layer, index) => {
        const center = 110 + index * 250;
        svg.append(svgElement("line", { x1: center, y1: 65, x2: center, y2: 377, class: "column-guide" }));
        const title = svgElement("text", { x: center, y: 28, class: "layer-title" });
        title.textContent = layer.title;
        const caption = svgElement("text", { x: center, y: 47, class: "layer-caption" });
        caption.textContent = layer.caption;
        svg.append(title, caption);
      });
      const dictionaryPosition = positions.get(MAP.nodes.find((node) => node.layer === "dic").id);
      const zone = svgElement("text", { x: dictionaryPosition.x, y: dictionaryPosition.y - 13, class: "zone-caption" });
      zone.textContent = MAP.dictionary.caption;
      svg.append(zone);
      let sameIndex = 0;
      MAP.edges.forEach((edge) => {
        const same = positions.get(edge.from).x === positions.get(edge.to).x;
        const index = same ? sameIndex++ : 0;
        const group = svgElement("g", { class: "edge", "data-id": edge.id, tabindex: "0", role: "button", "aria-label": `${nodeById.get(edge.from).name} — ${nodeById.get(edge.to).name}` });
        const path = edgePath(edge, index);
        const lineClass = `edge-line ${mechanismById.get(edge.mechanism).line}`;
        group.append(svgElement("path", { d: path, class: lineClass }), svgElement("path", { d: path, class: "edge-hit" }));
        bindSelection(group, "edge", edge.id);
        svg.append(group);
      });
      MAP.nodes.forEach((node) => {
        const position = positions.get(node.id);
        const group = svgElement("g", { class: "node", "data-id": node.id, tabindex: "0", role: "button", "aria-label": node.name });
        group.append(svgElement("rect", position));
        const name = svgElement("text", { x: position.x + position.width / 2, y: position.y + 21 });
        name.textContent = node.name;
        const mark = svgElement("text", { x: position.x + position.width / 2, y: position.y + 38, class: "stream-mark" });
        mark.textContent = node.streams.map((id) => MAP.streams[id]).join(" + ");
        group.append(name, mark);
        group.addEventListener("mouseenter", () => { state.hovered = node.id; updateHighlights(); });
        group.addEventListener("mouseleave", () => { state.hovered = null; updateHighlights(); });
        bindSelection(group, "node", node.id);
        svg.append(group);
      });
    }
    function bindSelection(element, type, id) {
      const choose = () => selectItem(type, id);
      element.addEventListener("click", choose);
      element.addEventListener("keydown", (event) => {
        if (event.key === "Enter" || event.key === " ") { event.preventDefault(); choose(); }
      });
    }
    function findReachability(nodeId) {
      const nodes = new Set([nodeId]);
      const edges = new Set();
      const walk = (start, direction) => {
        const queue = [start];
        while (queue.length) {
          const current = queue.shift();
          MAP.edges.forEach((edge) => {
            const matches = direction === "out" ? edge.from === current : edge.to === current;
            if (!matches) return;
            edges.add(edge.id);
            const next = direction === "out" ? edge.to : edge.from;
            if (!nodes.has(next)) { nodes.add(next); queue.push(next); }
          });
        }
      };
      walk(nodeId, "in");
      walk(nodeId, "out");
      return { nodes, edges };
    }
    function selectItem(type, id) {
      const repeated = state.selected?.type === type && state.selected.id === id;
      state.selected = repeated ? null : { type, id };
      if (!state.selected) renderIntro();
      else if (type === "node") renderNodeCard(nodeById.get(id));
      else renderEdgeCard(MAP.edges.find((edge) => edge.id === id));
      updateHighlights();
    }
    function updateHighlights() {
      let activeNodes = new Set();
      let activeEdges = new Set();
      if (state.selected?.type === "node") ({ nodes: activeNodes, edges: activeEdges } = findReachability(state.selected.id));
      if (state.selected?.type === "edge") {
        const edge = MAP.edges.find((item) => item.id === state.selected.id);
        activeNodes = new Set([edge.from, edge.to]);
        activeEdges = new Set([edge.id]);
      }
      const hoverNodes = new Set(state.hovered ? [state.hovered] : []);
      const hoverEdges = new Set();
      if (state.hovered) MAP.edges.forEach((edge) => {
        if (edge.from === state.hovered || edge.to === state.hovered) {
          hoverEdges.add(edge.id); hoverNodes.add(edge.from); hoverNodes.add(edge.to);
        }
      });
      document.querySelectorAll(".node").forEach((element) => {
        const node = nodeById.get(element.dataset.id);
        element.classList.toggle("is-filtered", state.stream !== "all" && !node.streams.includes(state.stream));
        element.classList.toggle("is-context-dim", Boolean(state.selected) && !activeNodes.has(node.id));
        element.classList.toggle("is-path", activeNodes.has(node.id));
        element.classList.toggle("is-hover", hoverNodes.has(node.id));
        element.classList.toggle("is-selected", state.selected?.type === "node" && state.selected.id === node.id);
      });
      document.querySelectorAll(".edge").forEach((element) => {
        const edge = MAP.edges.find((item) => item.id === element.dataset.id);
        element.classList.toggle("is-filtered", state.stream !== "all" && !edge.streams.includes(state.stream));
        element.classList.toggle("is-context-dim", Boolean(state.selected) && !activeEdges.has(edge.id));
        element.classList.toggle("is-path", activeEdges.has(edge.id));
        element.classList.toggle("is-hover", hoverEdges.has(edge.id));
        element.classList.toggle("is-selected", state.selected?.type === "edge" && state.selected.id === edge.id);
      });
    }
    function renderControls() {
      const switcher = document.getElementById("switcher");
      Object.entries(MAP.streams).forEach(([id, label]) => {
        const button = document.createElement("button");
        button.type = "button";
        button.textContent = label;
        button.setAttribute("aria-pressed", String(id === state.stream));
        button.addEventListener("click", () => {
          state.stream = id;
          switcher.querySelectorAll("button").forEach((item) => item.setAttribute("aria-pressed", String(item === button)));
          updateHighlights();
        });
        switcher.append(button);
      });
      const legend = document.getElementById("legend");
      MAP.mechanisms.forEach((item) => {
        const row = document.createElement("span");
        row.className = "legend-item";
        const line = document.createElement("span");
        line.className = `legend-line ${item.line}`;
        const label = document.createElement("span");
        appendRichText(label, `${item.label} — ${item.rhythm}`);
        row.append(line, label);
        legend.append(row);
      });
    }
    document.getElementById("page-title").textContent = MAP.title;
    document.getElementById("lead").textContent = MAP.lead;
    layoutMap();
    drawMap();
    renderControls();
    renderIntro();
    document.addEventListener("keydown", (event) => {
      if (event.key === "Escape" && state.selected) selectItem(state.selected.type, state.selected.id);
    });
  </script>
 </body>
 </html>
@@ -1,70 +0,0 @@
 # Генератор: откуда берутся данные
 Генератор имитирует работу двух систем интернет-магазина. Счетчик
 на сайте отправляет записи о действиях посетителей в топик `hits`. Серверная часть
 магазина раз в модельные сутки выгружает состояние заказов в топик `orders`.
 Эта дневная выгрузка называется слепком.
 ## События сайта и заказы
 Событие содержит сведения о действии посетителя: например, время,
 адрес страницы и идентификатор посетителя. Формат соответствует образцу
 выгрузки Яндекс Метрики. Генератор создает три вида событий: просмотр
 страницы, добавление в корзину и покупку. Все колонки перечислены
 в [описании выгрузки](../formats/clickstream-event.md).
 Заказ содержит сведения о покупке со стороны магазина: товары, суммы
 и состояние заказа. После оформления он еще может измениться, например
 при отмене. Каждый дневной слепок содержит текущее состояние заказов,
 оформленных за последние семь модельных дней. Состав и формат слепка
 разобраны в [отдельном
 справочнике](../architecture/orders/snapshot.md).
 ## Почему начальные данные повторяются
 Случайные решения генератора зависят от заданного числа —
 [зерна генерации](../architecture/generator/seeds.md) — и номера дня.
 При неизменных коде, каталоге товаров и настройках одинаковые зерно и день
 дают одинаковые события. Поэтому при создании стенда вы каждый раз
 получаете те же начальные данные. Повторный `make up` на работающем стенде
 сохраняет уже загруженные данные.
 В файле `data/world-inventory.json` записаны зерно, версия генератора,
 число событий и контрольная сумма за каждый из восьми начальных дней.
 В документации этот файл называется паспортом мира. С ним можно сверить
 результат генерации и проверить, все ли события загрузились в ODS.
 ## Запуск генератора
 На стенде генератором управляют [даги модельного
 времени](airflow-dags.md#генерация-модельных-дней). Его можно запустить и напрямую. Команды
 собраны в [справочнике генератора и модельного
 времени](../architecture/world.md#как-запустить-генератор).
 У генератора два режима. Пакетный отправляет все события дня без пауз.
 В живом режиме события поступают постепенно, как в работающем магазине,
 но время идет ускоренно: модельные сутки занимают около 24 минут.
 ## Сверка с паспортом мира
 Подключитесь из DBeaver по [инструкции](../../README.md#подключиться-из-dbeaver)
 и выполните запрос:
 ```sql
 SELECT EventDate, count() AS events
 FROM ods.event_v
 GROUP BY EventDate
 ORDER BY EventDate;
 ```
 Сравните число событий за каждый из первых восьми дней со значением
 `events` за ту же дату в [паспорте мира](../../data/world-inventory.json).
 Числа должны совпасть. Если вы уже генерировали следующие дни,
 в результате запроса будут дополнительные даты; в паспорте их нет.
 ## Учебные задания и справочники
 Подробнее генератор разобран в [README папки
 `generator/`](../../generator/README.md) и в [справочнике его
 устройства](../architecture/generator/README.md). Теперь можно переходить
 к [учебным заданиям](../labs/README.md).
@@ -1,86 +0,0 @@
 # Мониторинг в Grafana
 В Grafana настроены три дашборда — экрана с показателями и графиками.
 «Данные» показывает загрузку и обработку событий и заказов,
 «Кластер» — состояние узлов и самого ClickHouse, а «Запросы» — выполненные
 запросы и затраченные на них ресурсы.
 На панелях не заданы пороги для цветовых предупреждений: оценивать показания
 вы будете самостоятельно. Качество данных автоматически проверяет
 даг `dq_check`.
 ## Дашборд «Данные»
 «Свежесть» показывает, сколько реального времени прошло с поступления
 последних успешно разобранных событий и заказов. Время поступления хранится
 в колонке `_load_ts` слоя ODS. Показатель для заказов растет весь модельный день
 и снижается, когда поступает очередная дневная выгрузка — слепок.
 Это ожидаемо: заказы загружаются раз в день.
 «Поток» показывает число сырых сообщений в STG за выбранный интервал. «Брак»
 показывает долю строк, которые не удалось разобрать.
 «Сходимость» сравнивает число событий в Kafka и в ClickHouse. Тревожный
 признак — устойчивый разрыв между рядами. Разовое расхождение еще не говорит
 о потере данных: метрики Kafka и строки ClickHouse могут попадать в соседние
 интервалы на графике.
 «Отставание» показывает, сколько сообщений в Kafka еще не прочитано
 потребителями. «Дневной слепок» перечисляет последние десять слепков заказов в
 STG: по нему видно, поступила ли очередная выгрузка.
 Источники и правила чтения всех панелей разобраны в [справочнике дашборда
 «Данные»](../architecture/monitoring/data.md).
 ## Источники показателей
 Grafana получает данные напрямую из ClickHouse и через Prometheus.
 Prometheus собирает метрики с двух узлов ClickHouse, ClickHouse Keeper
 и экспортера Kafka — службы, которая предоставляет метрики Kafka.
 Свежесть считается по ODS: если новые сообщения перестали разбираться,
 показатель будет расти. Число поступивших сообщений берется из STG,
 где сохраняются все сообщения, включая повторы. Для доли брака это число
 сравнивается с числом строк в таблицах ошибок ODS.
 В основных таблицах ODS повторы событий и старые версии заказов удаляются
 при слияниях. Поэтому число строк в них не подходит для подсчета
 всех доставленных сообщений. Подробности — в [разделе о слоях
 панелей](../architecture/monitoring/data.md#почему-слои-у-панелей-разные).
 ## Состояние кластера и запросы
 Открывайте «Кластер», чтобы проверить нагрузку на процессор, использование
 памяти и дисков, число частей таблиц и ход их слияний в ClickHouse. Здесь же
 показаны состояние ClickHouse Keeper и очередь распределенных DDL-команд.
 Устройство панелей описано в [справочнике дашборда
 «Кластер»](../architecture/monitoring/cluster.md).
 «Запросы» поможет найти медленные запросы, ошибки и пользователей,
 чьи запросы потребляют много ресурсов. Как читать панели, объясняет
 [справочник дашборда
 «Запросы»](../architecture/monitoring/queries.md).
 ## Показатели за один модельный день
 Откройте Grafana по адресу из раздела [«Адреса и
 пароли»](../../README.md#адреса-и-пароли), затем дашборд «Данные». Запустите в
 Airflow [`world_live_day`](airflow-dags.md#генерация-модельных-дней): модельный день займет
 около двадцати четырех минут.
 Смотрите свежесть событий и свежесть заказов по отдельности. Пока день идет,
 со времени последнего события проходят секунды, а время с последней
 загрузки заказов растет. После завершения генерации событий отправляется
 слепок заказов. Когда он загружен, показатель свежести заказов снижается.
 Показатель для событий начинает расти: новые события поступят только
 при генерации следующего дня. Даг пока продолжает работу, ожидая завершения
 обработки данных в дневном конвейере.
 ## Следующая глава и справочники
 Устройство мониторинга описано в [техническом
 справочнике](../architecture/monitoring/README.md), панели дашборда «Данные» —
 в [отдельном разделе](../architecture/monitoring/data.md).
 Почему выбраны именно эти показатели, объясняет
 [ADR 0002](../adr/0002-monitoring-scope.md). Следующая глава —
 [«Отчеты в Superset»](superset.md).
@@ -1,70 +1,58 @@
 # Хранилище и его слои
-В Kafka поступают события сайта, или кликстрим, и заказы магазина.
+В хранилище приходят два потока из Kafka: в топике `hits` — события
-Для событий выделен топик `hits`, для заказов — `orders`.
+кликстрима, в `orders` — заказы магазина. Оба проходят один путь: STG → ODS →
-Из Kafka данные проходят четыре слоя хранилища. В STG сообщения сохраняются
+DDS → DM. Каждый слой отвечает на свой вопрос.
 как есть, в ODS разбираются по полям, в DDS из них собираются события,
 заказы и сессии, а в DM — витрины для отчетов.
 ```mermaid
 flowchart LR
    Kafka --> STG --> ODS --> DDS --> DM
 ```
-## Имена таблиц и представлений
+## Как читать имена
-Для обычного чтения выбирайте представления с суффиксом `_v`. Они позволяют
+Для обычного чтения выбирайте объекты с суффиксом `_v`. Это представления:
-менять устройство таблиц, сохраняя привычные запросы к данным.
+их устройство может поменяться, а ваш запрос останется прежним. Суффиксы
-Суффиксы `_rep`, `_dist`, `_kafka` и `_mv` относятся к внутреннему устройству
+`_rep`, `_dist`, `_kafka` и `_mv` относятся к внутреннему
-хранилища. Эти объекты нужны для загрузки, обслуживания и диагностики.
+устройству хранилища. Они нужны для загрузки, обслуживания и диагностики.
-У словаря товаров `dic.products` суффикса нет.
+У словарей есть исключение: у `dic.products` нет суффикса, потому что
 различать нечего — объект один.
 Подробный разбор имен есть в [справочнике
 хранилища](../architecture/storage.md#имена-объектов).
-## STG: исходные сообщения
+## STG: как поступило
-STG — сырой слой. Он сохраняет сообщение целой строкой, без разбора. Вместе
+STG — сырой слой. Он сохраняет сообщение целой строкой, без разбора. Рядом
-с ним записываются сведения о доставке: топик, партиция, смещение и время
+лежат метаданные доставки: топик, партиция, смещение и время приема. Поэтому в
-приема. Содержимое сообщения сохраняется в STG, даже если в нем есть ошибки.
+STG можно увидеть, что именно приехало из Kafka, даже если сообщение
 испорчено.
-Сырые сообщения хранятся трое суток реального времени. В течение этого срока
+Срок хранения — трое суток реального времени. Этого хватает для расследования
-их можно использовать для поиска ошибок и повторной обработки. Затем они
+и повторного разбора, но старые строки не занимают диск вечно. Точное правило
-удаляются по правилу из [справочника
+— в [справочнике
 хранилища](../architecture/storage.md#срок-жизни-сырых-данных).
-## ODS: разбор сообщений
+## ODS: язык источника
-В ODS содержимое сообщения разбирается на колонки с нужными типами данных:
+ODS — слой разобранных данных. Строка получает типы: дата становится датой,
-датами, числами, строками. Колонки сохраняют имена из источника. Например,
+число — числом. Имена полей остаются на языке источника. Например, событие
-в таблице событий есть `WatchID`, `ClientID` и `EventDate`.
+сохраняет колонки `WatchID`, `ClientID` и `EventDate`.
 Испорченное сообщение не останавливает загрузку. Оно попадает в таблицу
-`*_errors` вместе с исходной строкой и классом ошибки. Правильно записанные
+`*_errors` вместе с сырой строкой и классом ошибки. Так брак остается виден, а
-сообщения обрабатываются дальше.
+годные строки продолжают движение.
-## DDS: события, заказы и сессии
+## DDS: язык бизнеса
-DDS — детальный слой: в нем данные подготовлены для анализа событий,
+DDS — детальный слой на языке бизнеса. Здесь есть событие, заказ, сессия и
-заказов и сессий. Здесь же хранится карта идентичностей — таблица связей
+карта идентичностей. Карта связывает посетителя, то есть куку `ClientID`, с
-между идентификатором посетителя `ClientID` и пользователем магазина
+пользователем магазина из заказа.
 из заказа. `ClientID` хранится в cookie браузера: по нему можно узнать
 браузер посетителя, но не всегда самого человека.
-В стенде визитом, или сессией, считают подряд идущие события одного
+Сессия не приходит готовой из Kafka. Стенд сам выделяет ее из последовательных
-`ClientID` без пауз дольше 30 минут. Визит не пересекает границу модельных суток.
+событий одного посетителя. Здесь собраны сущности, с которыми дальше работают
-Модельные сутки — день в календаре учебного магазина. Этот календарь
+аналитики.
 не зависит от текущей даты на вашем компьютере.
-Источник передает готовый идентификатор визита `VisitID` по образцу
+## DM: данные для дашбордов
 Яндекс Метрики. В учебном хранилище сессии рассчитываются заново по времени
 событий; каждой присваивается `session_id`. Поле `VisitID` остается
 эталоном для проверки. Так в заданиях вы сможете самостоятельно определить
 границы сессий и сравнить их с результатом источника.
 Готовые сессии читайте через `dds.session_v`. События для самостоятельного
 расчета доступны в `dds.event_v`: в этом представлении `VisitID` скрыт.
 ## DM: витрины для отчетов
 DM — слой витрин. Витрина — готовый набор показателей для отчета или
 дашборда. Здесь уже посчитаны, например, дневная выручка по категориям и
@@ -74,43 +62,43 @@ DM — слой витрин. Витрина — готовый набор по
 путь расчета. Состав готовых витрин смотрите в [карте
 таблиц](../architecture/storage.md#карта-таблиц).
-## Справочники в базе `dic`
+## Сбоку цепочки: зона `dic`
-В базе `dic` хранятся готовые справочные данные. Они загружаются отдельно
+Зона `dic` стоит вне пути STG → ODS → DDS → DM. В ней живут справочные данные,
-от событий и заказов и могут использоваться в расчетах любого слоя.
+которые хранилище получает готовыми. Ни один слой их не производит, а читать
 может любой.
-Каталог товаров `dic.products` — один из таких справочников. Его ключ `sku` —
+Первый справочник стенда — каталог товаров `dic.products`. Его ключ `sku` —
 артикул товара. По нему можно узнать название, бренд и категорию товара. Как
 устроена зона, смотрите в [разделе о
 справочниках](../architecture/storage.md#справочники).
-## Связь данных между слоями
+## Ключи, по которым слои соединяются
-Идентификаторы позволяют связать данные из разных слоев. При переходе в DDS
+Имена меняются вместе с языком слоя. Таблица показывает исходное имя и то, где
-часть колонок переименовывается: например, `WatchID` становится `event_id`.
+искать тот же смысл дальше.
 В таблице указано, как найти соответствующие колонки и соединить по ним данные.
 | Колонка | Что означает | Что соединяет |
 |---|---|---|
 | `WatchID` | Идентификатор события | Событие ODS с событием DDS, где колонка называется `event_id` |
-| `ClientID` | Идентификатор посетителя из cookie браузера | События ODS с событиями, сессиями и картой идентичностей DDS; в DDS колонка называется `client_id` |
+| `ClientID` | Посетитель, то есть кука | События ODS с событиями, сессиями и картой идентичностей DDS; в DDS колонка называется `client_id` |
 | `order_id` | Идентификатор заказа | Заказ ODS с заказом DDS и витриной сверки `dm.purchase_vs_orders_v` |
 | `sku` | Артикул товара в каталоге | Справочник `dic.products` с позициями заказа DDS, где артикулы лежат в `item_sku`; через категорию товара — с витриной выручки DM |
-| `EventDate` | Дата события в [модельном времени](../../CONTEXT.md), указанная счетчиком сайта в [его часовом поясе](../architecture/storage.md#часовые-пояса) | Событие ODS с событием DDS, где колонка называется `event_date`, и дневными расчетами DM |
+| `EventDate` | День на [оси модельного времени](../../CONTEXT.md), который счетчик сайта проставляет в [своем часовом поясе](../architecture/storage.md#часовые-пояса) | Событие ODS с событием DDS, где колонка называется `event_date`, и дневными расчетами DM |
-Почему идентификатор посетителя не равнозначен человеку, объясняет
+Что здесь значит «посетитель» и чем кука отличается от человека, объясняет
 [словарь понятий](../../CONTEXT.md#язык). Точные имена объектов и полей сверяйте с
 [картой таблиц](../architecture/storage.md#карта-таблиц).
-## Примеры запросов
+## Посмотрите сами
 Подключитесь к ClickHouse по инструкции из разделов [«Адреса и
 пароли»](../../README.md#адреса-и-пароли) и [«Подключиться из
-DBeaver»](../../README.md#подключиться-из-dbeaver). Во всех трех примерах
+DBeaver»](../../README.md#подключиться-из-dbeaver). В обоих примерах
-`2026-06-01` — первый день работы учебного магазина. В документации он
+`2026-06-01` — это D0, первый день [стартового
-обозначается D0; подробнее — в [словаре понятий](../../CONTEXT.md).
+мира](../../CONTEXT.md). Чтобы посмотреть другой день, замените
-Чтобы посмотреть другой день, замените дату в условии.
+эту дату в условии. Первый запрос покажет
-Первый запрос покажет 20 событий за выбранный день:
+события одного модельного дня:
 ```sql
 SELECT
@@ -125,32 +113,7 @@ ORDER BY UTCEventTime
 LIMIT 20;
 ```
-Каждая строка здесь — отдельное действие посетителя.
+Второй запрос покажет готовую выручку по категориям за тот же день:
 Второй запрос покажет 20 сессий того же дня с наибольшим числом событий.
 Сессии рассчитаны по всем событиям дня:
 ```sql
 SELECT
    client_id,
    started_at,
    finished_at,
    events_total,
    pageviews,
    purchases,
    entry_url
 FROM dds.session_v
 WHERE session_date = '2026-06-01'
 ORDER BY events_total DESC
 LIMIT 20;
 ```
 Теперь одна строка представляет целый визит. `events_total` показывает,
 сколько событий в него вошло; начало и конец визита записаны в
 `started_at` и `finished_at`.
 Третий запрос покажет выручку магазина по категориям за тот же день.
 Эта витрина рассчитана по заказам:
 ```sql
 SELECT
@@ -163,13 +126,12 @@ WHERE report_date = '2026-06-01'
 ORDER BY revenue DESC;
 ```
-Здесь одна строка содержит итоги дня для категории товаров.
+Оба запроса читают поверхности `_v`. Первый показывает данные на языке
-Все три запроса читают представления `_v`.
+источника, второй — готовый ответ витрины.
-## Следующая глава и справочники
+## Куда дальше
 Откройте [интерактивную карту](architecture-map.html) из своей копии
 репозитория и проследите путь данных.
 Список объектов, сроки хранения и устройство таблиц — в [справочнике
-хранилища](../architecture/storage.md). Как данные обрабатываются между слоями — в
+хранилища](../architecture/storage.md). Как данные переносят между слоями — в
-следующей главе: [«Генерация и обработка данных в Airflow»](airflow-dags.md).
+следующей главе: [потоки Airflow и даги модельного
 времени](README.md#потоки-airflow-и-даги-модельного-времени).
@@ -1,75 +0,0 @@
 # Отчеты в Superset
 Superset показывает витрины слоя DM в виде графиков. К ClickHouse он
 подключается пользователем `bi`. Дашборд стенда «Бизнес-сюжеты» собран из трех
 витрин:
 | Витрина | Что показывает |
 |---|---|
 | `dm.revenue_daily_v` | Выручку, число заказов и средний чек; выручку по дням и категориям товаров, долю каждой категории |
 | `dm.purchase_vs_orders_v` | Результат сверки покупок из кликстрима с заказами: сколько заказов за день относится к каждому виду расхождения |
 | `dm.daily_traffic_v` | Число посетителей и известных пользователей по дням, долю известных пользователей |
 Известные пользователи — те, кого удалось связать с посетителями сайта
 по заказам. Эти связи хранятся в карте идентичностей DDS.
 Слева от панелей стоит фильтр «Период». Он задает даты сразу для всех панелей.
 ## Как витрина становится графиком
 В Superset сначала создается датасет — описание таблицы или представления,
 из которого будут браться данные. В нем задаются подписи колонок, формат
 чисел и показатели, например средний чек.
 Затем на основе датасета создается график: выбираются показатели и способ
 их отображения. Несколько графиков можно разместить на одном дашборде.
 ## Готовые и собственные отчеты
 Готовые датасеты, графики и дашборд сохранены в файлах репозитория
 и импортируются при каждом `make up`. Если изменить их через интерфейс,
 следующий `make up` заменит изменения версией из файлов без предупреждения.
 Созданные вами датасеты, графики и дашборды хранятся в базе метаданных
 Superset. Импорт их не меняет: они сохраняются после `make up`
 и `make rebuild-storage`. Команда `make clean` удалит их вместе со всеми
 данными стенда. Для учебных отчетов создавайте собственные объекты,
 чтобы повторный запуск не перезаписал вашу работу. Устройство
 импорта описано в [справочнике
 Superset](../architecture/superset.md#импорт-при-каждой-инициализации).
 ## Почему выручка отстает на день
 Последняя дата с выручкой на день раньше последней даты с событиями
 кликстрима. Выгрузка заказов за день D поступает при генерации следующего
 дня D+1, а затем обрабатывается конвейером. Вы уже видели эту разницу
 в [главе об Airflow](airflow-dags.md#один-день-от-генерации-до-витрин). Начальное состояние
 показано в разделе [«Стартовый мир»](../architecture/world.md#стартовый-мир).
 ## Сверка графика с витриной
 Откройте Superset по адресу из раздела [«Адреса и
 пароли»](../../README.md#адреса-и-пароли) и выберите дашборд «Бизнес-сюжеты».
 Найдите график «Посетители и известные пользователи».
 Затем откройте SQL Lab и выполните запрос:
 ```sql
 SELECT report_date, visitors, known_users
 FROM dm.daily_traffic_v
 ORDER BY report_date DESC
 LIMIT 7;
 ```
 Выберите одну дату из результата. На дашборде задайте «Период», в который
 она входит, и обновите график. Наведите указатель на точку этой даты:
 числа посетителей и известных пользователей должны совпасть с `visitors`
 и `known_users` из SQL.
 Как построить собственный отчет, рассказывают [учебные задания](../labs/README.md).
 ## Следующая глава и справочники
 Подключение и настройка Superset описаны в [справочнике
 Superset](../architecture/superset.md), а состав витрин — в [справочнике
 DM](../architecture/dm.md). Следующая глава — [«Генератор: откуда берутся
 данные»](generator.md).
@@ -1,95 +0,0 @@
 # Задание 1: события для анализа, `dm.events_enriched_v`
 Вы подготовите представление с полями для анализа событий. Оно будет
 добавлять вычисляемые поля при чтении, сохраняя одну строку на событие.
 ## Подготовка
 - [«Хранилище и его слои»](../handbook/storage-layers.md).
 - [Выполнение SQL в DBeaver](README.md#выполнение-sql-в-dbeaver): файл для решения
  и подключение с правами на создание витрины.
 ## Данные для анализа событий
 В `dds.event_v` 44 колонки, включая технические поля источника и массивы
 товаров. Для анализа событий в Superset нужны сведения о посетителе и его
 действиях, а также три вычисляемых поля: час события, путь страницы и домен,
 с которого пришел посетитель. Тогда вам не придется
 повторять эти выражения в каждом запросе.
 Витрины следующих заданий читают DDS напрямую. Использовать
 `dm.events_enriched_v` как источник для них не нужно: задания независимы, их
 можно выполнять в любом порядке.
 ## Создание представления
 Создайте обычное представление `CREATE VIEW dm.events_enriched_v`.
 Единственный источник: `dds.event_v`. Каждой строке источника должна
 соответствовать ровно одна строка витрины: одно событие.
 Представление выполняет запрос при чтении и не хранит отдельную копию данных.
 Для него не нужно создавать таблицы или добавлять задачу в `dm_transform`.
 Укажите колонки явно. Иначе новая колонка источника попадет в витрину
 автоматически. Отчет получит ее, даже если вы не собирались менять его набор
 полей.
 | Группа | Колонки |
 |---|---|
 | Время и посетитель | `event_date`, `event_time`, `event_hour`, `client_id`, `event_id` |
 | Действие | `event_type` (`pageview`, `add_to_cart`, `purchase`), `url`, `page_path`, `referer`, `referer_host`, `title` |
 | UTM-метки | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` |
 | Устройство и регион | `device_category`, `browser`, `operating_system`, `region_country`, `region_city` |
 | Товары и покупка | `product_id`, `product_name`, `product_category`, `product_price`, `product_quantity`, `product_event_type`, `purchase_id`, `purchase_revenue`, `purchase_coupon` |
 Три колонки вычислите в представлении. Остальные возьмите из источника без
 изменений, сохранив массивы `product_*`.
 | Колонка | Как считается | Для чего нужна |
 |---|---|---|
 | `event_hour` | `toHour(event_time)` | Анализ событий по часам суток |
 | `page_path` | путь `url` без домена и параметров | Группировка по странице |
 | `referer_host` | домен `referer` | Анализ источников перехода |
 Не добавляйте `_load_id` и `_load_ts`. Их нет и у `dds.event_v`: события в
 DDS читают из ODS без отдельной загрузки. Эти служебные поля указывают на
 запуск, который записал строку на диск. Представление ничего не загружает.
 ## Типичная ошибка
 Не разворачивайте массивы товаров через `ARRAY JOIN`. У события с тремя
 позициями получится три строки вместо одной.
 Главная опасность — потеря событий с пустым массивом товаров: `ARRAY JOIN`
 исключает их из результата. Товары есть только в событиях корзины и покупки.
 Поэтому исчезнет большинство событий — девятнадцать строк из двадцати.
 Запрос выполнится без ошибки, а витрина по имени и составу колонок
 по-прежнему будет выглядеть таблицей событий.
 Сохраните массивы как в источнике. Для анализа отдельных товарных позиций
 нужна отдельная витрина, где одна строка соответствует товарной позиции.
 ## Проверка результата
 После применения DDL откройте Airflow по [адресу из README](../../README.md#адреса-и-пароли),
 найдите даг `homework_check` и запустите его вручную. В новом запуске откройте
 задачу `events_enriched`: она должна завершиться успешно. Если задача
 красная, откройте ее журнал (`Logs`) — там будет причина ошибки, а при
 расхождениях с источником — дни и примеры несовпадений. Задачи еще не
 созданных витрин будут красными; это ожидаемо и не мешает проверке первой.
 Выберите день и прочитайте его события из `dds.event_v` и своей витрины.
 Сопоставьте строки по `event_id` через `FULL OUTER JOIN`.
 Найдите события, которые есть только с одной стороны, и события, у которых
 различаются перенесенные из источника поля. Расхождений должно быть ноль.
 Отдельно сверьте `event_hour`, `page_path` и `referer_host` с теми же
 выражениями, рассчитанными прямо по `dds.event_v`.
 ## Результат работы
 - [ ] у вас есть `dm.events_enriched_v` с явно перечисленными колонками;
 - [ ] вы сверили число строк и набор `event_id` с `dds.event_v` за каждый
      прожитый день; расхождений нет;
 - [ ] проверка `events_enriched` в `homework_check` прошла успешно;
 - [ ] витрина работает без физической таблицы и задачи в `dm_transform`.
@@ -1,116 +0,0 @@
 # Задание 2: показатели страниц по дням, `dm.top_pages_daily`
 В этой работе вы рассчитаете показатели страниц за каждый день и сохраните
 их в таблице. Затем подключите обновление витрины к `dm_transform`:
 новый расчет будет заменять дневные партиции таблицы.
 ## Подготовка
 - [«Хранилище и его слои»](../handbook/storage-layers.md);
 - [«Генерация и обработка данных в Airflow»](../handbook/airflow-dags.md).
 ## Дневные показатели страниц
 По дневным показателям страниц аналитик сравнивает просмотры, посетителей и
 действия с товарами. Добавление в корзину происходит на карточке товара,
 покупка — на странице подтверждения заказа. Отношение добавлений к
 просмотрам карточки показывает ее конверсию.
 Для воронки «просмотр → корзина → покупка» этих данных недостаточно:
 действия происходят на разных страницах, а связи между ними в агрегате нет.
 Путь человека исследуют по событиям или сессиям.
 ## Создание витрины
 Читайте события из `dds.event_v`. В результате нужна одна строка на страницу
 за день. Например, все просмотры одной карточки товара за один день попадут
 в одну строку. Витрина задания 1 для этого расчета не нужна.
 Сохраните рассчитанные показатели в таблице, чтобы отчеты читали готовые
 итоги. Создайте пять объектов:
 - основные таблицы `dm.top_pages_daily_rep` и `dm.top_pages_daily_dist`;
 - промежуточные таблицы `dm.top_pages_daily_stage_rep` и `dm.top_pages_daily_stage_dist`;
 - представление для чтения `dm.top_pages_daily_v`.
 Их назначение и порядок обновления разобраны во вводной:
 [«Создание и обновление витрин»](README.md#создание-и-обновление-витрин).
 Разбейте данные на партиции по дням, чтобы можно было заменить результат
 одного дня целиком.
 ### Состав колонок
 | Колонка | Тип | Значение |
 |---|---|---|
 | `report_date` | `Date` | День события |
 | `page_path` | `LowCardinality(String)` | Путь страницы |
 | `pageviews` | `UInt64` | Число событий `pageview` на странице |
 | `visitors` | `UInt64` | Число разных `client_id` на странице |
 | `cart_adds` | `UInt64` | Число событий `add_to_cart` на странице |
 | `purchases` | `UInt64` | Число событий `purchase` на странице |
 | `_load_id` | `String` | Идентификатор запуска, собравшего день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | Время сборки |
 Вычислите `page_path` из `url`, убрав домен и параметры запроса. Полный
 адрес разделил бы показатели одной страницы на сотни строк. Учитывайте все
 три типа событий, а их счетчики вычисляйте через `countIf`.
 ### Дни для пересчета
 События завершившегося модельного дня больше не меняются. Найдите первый
 такой день, которого еще нет в витрине, и рассчитайте все дни от него до
 последнего завершившегося. Если начать после последнего дня, который уже
 есть в витрине, можно пропустить более ранний день, не загруженный из-за сбоя.
 Как у `revenue_daily`, запишите расчет за все выбранные дни в промежуточную
 таблицу одной вставкой. Затем замените дневные партиции основной таблицы по
 одной. Добавьте запуск этих запросов в `dm_transform`.
 ### Ключ шардирования
 Выберите ключ самостоятельно. У `revenue_daily` строки сгруппированы по дню
 и категории товара; категорий всего шесть. Здесь страниц много, и число
 событий на них сильно различается.
 У основной и промежуточной таблиц используйте одинаковый ключ шардирования.
 Замена партиции не перераспределяет строки между шардами. Подробнее об этом
 в разделе [«Раскладка по шардам»](../architecture/storage.md#раскладка-по-шардам).
 ## Типичная ошибка
 Из-за имени витрины хочется отобрать только просмотры. Но фильтр источника
 по `event_type = 'pageview'` обнулит `cart_adds` и `purchases`, а запрос не
 завершится ошибкой. Конверсия карточек станет нулевой. Проверка одной суммы
 `pageviews` не обнаружит этот фильтр: все просмотры остались на месте.
 Ошибку покажет сверка `purchases` или `cart_adds` с источником, если за день
 были покупки или добавления в корзину.
 Выбирайте проверку под возможную ошибку. Этот подход описан в
 [справочнике проверок](../architecture/testing.md).
 ## Проверка результата
 Рассчитайте те же показатели по `dds.event_v` за выбранный день.
 Сопоставьте результат со строками `dm.top_pages_daily_v` за этот день
 через `FULL OUTER JOIN` по `page_path`. Найдите страницы, которые есть
 только с одной стороны, и строки, где различается хотя бы один из четырех
 счетчиков. Расхождений должно быть ноль.
 Перед полным сравнением проверьте дневные суммы:
 - сумма `pageviews` равна числу событий `pageview` в `dds.event_v`;
 - сумма `purchases` равна числу событий `purchase` в том же источнике.
 Сумма `visitors` по страницам повторно учитывает посетителя, открывшего
 несколько страниц. Число посетителей за день берите из `dm.daily_traffic_v`.
 ## Результат работы
 - [ ] у вас есть пять объектов витрины; промежуточная таблица объявлена через
      `AS` и использует тот же ключ шардирования, что и основная;
 - [ ] в `dm.top_pages_daily_v` явно перечислены колонки, включая
      `_load_id` и `_load_ts`;
 - [ ] ваш запрос сам определяет дни пересборки по состоянию витрины;
 - [ ] проверка `top_pages_daily` в `homework_check` прошла успешно;
 - [ ] вы включили витрину в `dm_transform` и убедились, что повторный
      прогон конвейера не меняет результат.
@@ -1,124 +0,0 @@
 # Задание 3: визиты по устройствам, `dm.session_overview`
 Вы соберете дневные показатели визитов по устройствам. В таблице будут
 храниться суммы и счетчики для расчета средних и долей. Заодно проверите,
 когда сложение числа посетителей по устройствам завышает аудиторию.
 ## Подготовка
 - [«Хранилище и его слои»](../handbook/storage-layers.md);
 - [«Генерация и обработка данных в Airflow»](../handbook/airflow-dags.md).
 ## Показатели визитов
 Витрина нужна, чтобы по дням сравнивать визиты с телефона и компьютера: их
 число, длительность, просмотры страниц и частоту покупок.
 Сессии уже рассчитаны в DDS. Из них вы соберете дневные показатели по
 устройствам. Почему такие итоги хранят в отдельной таблице, объясняет
 [справочник DM](../architecture/dm.md).
 ## Создание витрины
 Читайте готовые сессии из `dds.session_v`. В результате нужна одна строка
 на категорию устройства за день: например, итоги всех визитов с телефонов
 за один день.
 Создайте пять объектов по [общим правилам ступени 1](README.md#создание-и-обновление-витрин):
 - основные таблицы `dm.session_overview_rep` и `dm.session_overview_dist`;
 - промежуточные таблицы `dm.session_overview_stage_rep` и `dm.session_overview_stage_dist`;
 - представление для чтения `dm.session_overview_v`.
 Разбейте данные на партиции по дням.
 ### Состав колонок
 | Колонка | Тип | Значение |
 |---|---|---|
 | `report_date` | `Date` | День сессии |
 | `device_category` | `LowCardinality(String)` | Категория устройства |
 | `sessions` | `UInt64` | Число визитов |
 | `visitors` | `UInt64` | Число разных `client_id` |
 | `bounce_sessions` | `UInt64` | Визиты ровно из одного события |
 | `purchase_sessions` | `UInt64` | Визиты хотя бы с одной покупкой |
 | `duration_seconds_total` | `UInt64` | Суммарная длительность визитов |
 | `events_total` | `UInt64` | Число событий во всех визитах |
 | `pageviews` | `UInt64` | Число просмотров страниц |
 | `cart_adds` | `UInt64` | Число добавлений в корзину |
 | `purchases` | `UInt64` | Число покупок |
 | `_load_id` | `String` | Идентификатор запуска, собравшего день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | Время сборки |
 Возьмите `device_category` из сессии: DDS уже заменил код словом. Из четырех
 категорий встречаются `desktop`, `mobile` и `tablet`. Строку для `tv`
 создавайте только при появлении таких визитов.
 Для расчета средней длительности храните общую длительность и число сессий.
 Готовую среднюю `avg_duration_seconds` сохранять не нужно. Число сессий
 в категориях различается, поэтому среднее из трех средних даст неверный
 ответ за день. Чтобы получить его правильно, разделите сумму
 `duration_seconds_total` на сумму `sessions`. Для доли отказов разделите
 сумму `bounce_sessions` на сумму `sessions`. Усреднение готовых долей тоже
 даст неверный результат.
 ### Дни для пересчета
 Сессии завершившегося модельного дня больше не меняются. Как в задании 2,
 найдите первый завершившийся день, которого еще нет в витрине. Рассчитайте
 все дни от него до последнего завершившегося, запишите их в промежуточную
 таблицу и замените дневные партиции основной. Добавьте задачу в `dm_transform`.
 ### Ключ шардирования
 Выберите ключ самостоятельно. Визитов с планшета мало, с телефонов и
 компьютеров — значительно больше. Если хотите взять хеш только от
 `device_category`, сначала посчитайте строки на каждом шарде. Затем
 объясните, почему такое распределение вас устраивает.
 У основной и промежуточной таблиц должен быть одинаковый ключ шардирования:
 см. [общие правила ступени 1](README.md#создание-и-обновление-витрин).
 ## Число посетителей за день
 Сравните сумму `visitors` по устройствам за день с `dm.daily_traffic_v`. На
 стенде значения совпадут: одному `client_id` всегда соответствует одно
 устройство, поэтому за день он учитывается только в одной категории.
 Это свойство мира стенда; см.
 раздел «Паспорт куки» в [словаре понятий](../../CONTEXT.md).
 Если появятся визиты одного `client_id` с двух устройств, сумма начнет завышать
 аудиторию. Проверки счетчиков по категориям этого не обнаружат. Число
 посетителей дня берите из `dm.daily_traffic_v`, где оно рассчитано для дня
 целиком.
 ## Типичная ошибка
 Повторное выделение визитов из событий может дать другие границы сессий, чем
 в DDS. Используйте готовые сессии из `dds.session_v`. Если общее число
 событий совпало с источником, а число сессий завышено, вероятная причина —
 сборка витрины из событий вместо сессий.
 ## Проверка результата
 Рассчитайте те же показатели по `dds.session_v` за выбранный день.
 Сопоставьте результат со строками `dm.session_overview_v` за этот день
 через `FULL OUTER JOIN` по `device_category`. Найдите категории, которые
 есть только с одной стороны, и строки, где различается хотя бы один
 счетчик. Расхождений должно быть ноль.
 Еще две проверки дневных итогов:
 - сумма `sessions` равна числу строк `dds.session_v` за день — без потерь и
  повторного учета визитов;
 - сумма `events_total` равна сумме `events_total` по сессиям того же дня.
 ## Результат работы
 - [ ] у вас есть пять объектов витрины; промежуточная таблица объявлена через
      `AS` и использует ключ шардирования основной;
 - [ ] вы явно перечислили колонки в `dm.session_overview_v` и собрали
      показатели из готовых сессий `dds.session_v`;
 - [ ] в таблице хранятся суммы и счетчики для расчета средних и долей;
 - [ ] проверка `session_overview` в `homework_check` прошла успешно;
 - [ ] витрина обновляется при запуске `dm_transform`.
@@ -1,113 +0,0 @@
 # Задание 4: ошибки загрузки по дням, `dm.dq_errors_daily`
 Вы соберете дневную сводку ошибок загрузки. Ее итоги должны сохраниться
 и после того, как исходные сообщения будут удалены из хранилища.
 ## Подготовка
 - [«Хранилище и его слои»](../handbook/storage-layers.md);
 - [«Генерация и обработка данных в Airflow»](../handbook/airflow-dags.md).
 ## Ошибки загрузки и их источники
 Если сообщение не удалось разобрать, стенд записывает его в таблицу ошибок.
 Такие строки дальше называются браком. Вы соберете сводку, по которой можно
 увидеть, каких ошибок стало больше и сколько строк забраковано.
 Источники сводки:
 - `ods.event_errors_dist`: ошибки разбора событий;
 - `ods.order_errors_dist`: ошибки разбора выгрузки заказов.
 В этих таблицах есть исходный текст сообщения и сведения о его доставке:
 они пригодятся при поиске причины ошибки. Представлений `_v` у таблиц ошибок
 нет, создавать их для задания не нужно. Чтение локальной таблицы `_rep`
 даст строки только одного шарда из двух, поэтому используйте `_dist`.
 ## Создание сводки
 В результате нужна одна строка на день загрузки, источник и класс ошибки.
 Например, ошибки `field_invalid` в заказах за один день загрузки попадут
 в одну строку с их количеством.
 Создайте пять объектов по [общим правилам ступени 1](README.md#создание-и-обновление-витрин):
 - основные таблицы `dm.dq_errors_daily_rep` и `dm.dq_errors_daily_dist`;
 - промежуточные таблицы `dm.dq_errors_daily_stage_rep` и `dm.dq_errors_daily_stage_dist`;
 - представление для чтения `dm.dq_errors_daily_v`.
 Разбейте данные на партиции по дням загрузки.
 ### Состав колонок
 | Колонка | Тип | Значение |
 |---|---|---|
 | `load_date` | `Date` | День загрузки забракованной строки |
 | `source` | `LowCardinality(String)` | `event` или `order` |
 | `error_class` | `LowCardinality(String)` | Класс брака из таблицы ошибок |
 | `error_rows` | `UInt64` | Число забракованных строк |
 | `_load_id` | `String` | Идентификатор запуска, собравшего день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | Время сборки |
 Вычислите `load_date` как `toDate(_load_ts)` из таблицы ошибок — это
 реальный день приема строки. Модельный день записан внутри исходной строки.
 Ее не удалось разобрать, поэтому надежно получить из нее день не получится.
 Служебная `_load_ts` витрины описывает сборку сводки; ее дата может
 отличаться от `load_date`.
 У событий и заказов свои классы брака. Группируйте строки также по `source`,
 чтобы одноименные классы разных источников не объединялись.
 ### Пересчет и хранение итогов
 Правило `TTL` удаляет строки брака через месяц, сырые данные через трое суток.
 Сводку храните бессрочно: итоги нужны и после удаления исходных строк.
 Получите список дней загрузки, еще имеющихся в источниках. Рассчитайте их
 итоги в промежуточной таблице и замените только эти партиции основной таблицы.
 Более старые итоги сохраните.
 В течение текущих суток ошибки еще поступают: пересчитайте этот день на
 следующем прогоне.
 ### Ключ шардирования
 Выберите ключ самостоятельно. Классов брака у событий и заказов вместе
 меньше десятка. Объясните, насколько существенен перекос при таком объеме.
 У основной и промежуточной таблиц должен быть одинаковый ключ шардирования:
 см. [общие правила ступени 1](README.md#создание-и-обновление-витрин).
 ## Типичная ошибка
 Если заменить всю сводку новым расчетом, исчезнут итоги дней, за которые
 исходные строки уже удалены по `TTL`. Восстановить эти итоги неоткуда.
 ## Проверка результата
 Сопоставляйте строки по `load_date`, `source` и `error_class`. Проверяйте дни,
 оставшиеся хотя бы в одной таблице ошибок. Старые итоги, для которых исходные
 строки уже удалены по `TTL`, сверять не с чем.
 Посчитайте строки прямо в обеих таблицах ошибок и соедините результат с
 `dm.dq_errors_daily_v` через `FULL OUTER JOIN` по этим трем полям. Посчитайте
 строки, которые есть только с одной стороны или у которых различается `error_rows`.
 Расхождений должно быть ноль.
 Сумма `error_rows` по проверяемым дням равна общему числу строк в
 `ods.event_errors_dist` и `ods.order_errors_dist`. Если она примерно вдвое
 меньше, вероятная причина — чтение `_rep` вместо `_dist`.
 Если в источниках нет брака, витрина должна быть пустой. В этом случае
 расхождений тоже ноль и проверка успешна.
 ## Результат работы
 - [ ] у вас есть пять объектов витрины; промежуточная таблица объявлена через
      `AS` и использует ключ шардирования основной;
 - [ ] сводка включает ошибки событий и заказов из таблиц `_dist`;
 - [ ] ваш запрос пересобирает только дни, еще доступные в источниках,
      сохраняя более старые итоги;
 - [ ] проверка `dq_errors_daily` в `homework_check` прошла успешно;
      отсутствие брака тоже дает успешный результат;
 - [ ] витрина обновляется при запуске `dm_transform`.
@@ -1,146 +0,0 @@
 # Задание 5: показатели рекламы, `dm.utm_effectiveness`
 Вы подготовите показатели рекламных каналов по событиям сайта. Суммы покупок
 в этой витрине будут отличаться от выручки по заказам магазина. В конце
 работы вы сравните их и объясните причины расхождения.
 ## Подготовка
 - [«Хранилище и его слои»](../handbook/storage-layers.md);
 - [«Генерация и обработка данных в Airflow»](../handbook/airflow-dags.md).
 ## Покупки по рекламным каналам
 Аналитик сравнивает рекламные каналы по дням: трафик, добавления в корзину,
 покупки и их суммы из событий сайта.
 События сайта показывают действия посетителя и рекламные метки его переходов.
 Заказы магазина служат источником выручки. Но в заказах нет UTM-меток, поэтому
 в этой витрине вы возьмете суммы из событий покупки. Их передает браузер
 посетителя; дальше они называются клиентскими суммами. Приставка `declared_`
 в имени показателя напоминает об этом источнике.
 ## Создание витрины
 Читайте события из `dds.event_v`, без других витрин DM. В результате нужна
 одна строка на день и сочетание трех меток: `utm_source`, `utm_medium`,
 `utm_campaign`. События одного дня с одинаковыми метками попадают в одну группу.
 Создайте пять объектов по [общим правилам ступени 1](README.md#создание-и-обновление-витрин):
 - основные таблицы `dm.utm_effectiveness_rep` и `dm.utm_effectiveness_dist`;
 - промежуточные таблицы `dm.utm_effectiveness_stage_rep` и `dm.utm_effectiveness_stage_dist`;
 - представление для чтения `dm.utm_effectiveness_v`.
 Разбейте данные на партиции по дням.
 ### Состав колонок
 | Колонка | Тип | Значение |
 |---|---|---|
 | `report_date` | `Date` | День события |
 | `utm_source` | `LowCardinality(String)` | Источник кампании |
 | `utm_medium` | `LowCardinality(String)` | Канал кампании |
 | `utm_campaign` | `String` | Имя кампании |
 | `visitors` | `UInt64` | Число разных `client_id` |
 | `pageviews` | `UInt64` | Число просмотров страниц |
 | `add_to_carts` | `UInt64` | Число добавлений в корзину |
 | `purchases` | `UInt64` | Число покупок |
 | `declared_revenue` | `Decimal(18, 2)` | Сумма покупок, заявленная клиентом |
 | `_load_id` | `String` | Идентификатор запуска, собравшего день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | Время сборки |
 Для `declared_revenue` сложите `purchase_revenue[1]` событий `purchase`. В
 параллельных массивах `purchase*` хранятся один номер заказа и
 одна сумма на событие. В сверке `purchase_vs_orders` используют тот же
 индекс.
 Тип `purchase_revenue` — `Array(Decimal(18, 2))`: исходный `Float64`
 преобразован в ODS. Сложение Decimal точное; `CAST` до или после `sum` не
 меняет результат и не нужен. Тип итога — `Decimal(18, 2)`.
 Для `utm_campaign` выбран тип `String`: имен кампаний со временем становится
 много, и затраты на словарь `LowCardinality` перестают окупаться.
 ### Дни для пересчета
 События завершившегося модельного дня больше не меняются. Как в задании 2,
 найдите первый завершившийся день, которого еще нет в витрине. Рассчитайте
 все дни от него до последнего завершившегося, запишите их в промежуточную
 таблицу и замените дневные партиции основной. Добавьте задачу в `dm_transform`.
 ### Ключ шардирования
 Выберите ключ самостоятельно. Если берете хеш одной из трех UTM-колонок,
 посчитайте долю строк с ее самым частым значением и обоснуйте выбор.
 У основной и промежуточной таблиц должен быть одинаковый ключ шардирования:
 см. [общие правила ступени 1](README.md#создание-и-обновление-витрин).
 ## Рекламные метки событий
 Группируйте события по их собственным меткам. Модели «первое касание» и
 «последнее касание» здесь не рассчитываются.
 В `dds.session_v` записаны UTM первого события визита. Распределение по
 каналам может отличаться от этой витрины, и это не означает ошибку в
 расчете. Укажите в отчете, что распределяете по рекламным каналам отдельные
 события. Такое распределение называют атрибуцией.
 ## События без рекламных меток
 Сохраните события без меток: прямой трафик обычно крупнейший канал, и без
 него доля рекламы будет завышена. Если отфильтровать такие строки, дневные
 итоги перестанут сходиться с источником — а по этому совпадению вы
 проверяете сборку. Разница составит вклад исключенных событий.
 Оставьте пустые метки пустыми строками: новое обозначение прямого трафика
 потребовало бы объяснения.
 ## Расхождение с `dm.revenue_daily_v`
 Сравните за один день `sum(declared_revenue)` своей витрины и `sum(revenue)`
 из `dm.revenue_daily_v`. Суммы не сходятся; проверять их равенство не нужно.
 В `revenue_daily` складываются цены позиций, умноженные на количество, без
 скидок и доставки — та же основа, что у клиентской суммы. Расхождение
 объясняется историей заказов, а не способом расчета:
 - событие покупки остается после отмены заказа, а `revenue_daily` учитывает
  только оплаченные заказы;
 - событие покупки может потеряться при доставке, хотя заказ поступил, или
  поступить дважды;
 - клиентская сумма может отличаться от серверной суммы позиций: генератор
  намеренно создает это расхождение у одного-двух заказов из ста.
 Запишите свой вывод в двух-трех фразах. Число расхождений по заказам и их
 причины можно посмотреть в `dm.purchase_vs_orders_v`, где выделены классы
 расхождений.
 ## Проверка результата
 Рассчитайте те же показатели по `dds.event_v` за выбранный день.
 Сопоставьте результат со строками `dm.utm_effectiveness_v` за этот день
 через `FULL OUTER JOIN` по `utm_source`, `utm_medium` и `utm_campaign`.
 Найдите сочетания меток, которые есть только с одной стороны, и строки,
 где различается хотя бы один из пяти показателей. Расхождений должно быть ноль.
 Дополнительно сверьте дневные итоги:
 - суммы `pageviews`, `add_to_carts` и `purchases` равны числу событий
  соответствующих типов в `dds.event_v`;
 - сумма `declared_revenue` равна сумме `purchase_revenue[1]` по всем
  событиям `purchase` того же дня.
 Сумма `visitors` по строкам повторно учитывает одного посетителя,
 приходящего по разным меткам. Для числа посетителей дня она не подходит.
 ## Результат работы
 - [ ] у вас есть пять объектов витрины; промежуточная таблица объявлена через
      `AS` и использует ключ шардирования основной;
 - [ ] строки без UTM-меток сохранены, а `declared_revenue` хранится
      в `Decimal(18, 2)`;
 - [ ] вы записали, почему сумма отличается от `dm.revenue_daily_v`;
 - [ ] проверка `utm_effectiveness` в `homework_check` прошла успешно;
 - [ ] витрина обновляется при запуске `dm_transform`.
@@ -1,94 +0,0 @@
 # Свой график в Superset
 В этой работе вы построите график по своей витрине и проверите числа
 на нем SQL-запросом.
 ## Подготовка
 - [«Отчеты в Superset»](../handbook/superset.md);
 - [задание 3: `dm.session_overview`](1-3-session-overview.md).
 ## График отказов по устройствам
 В задании 3 первой ступени вы собрали витрину `dm.session_overview_v`.
 Теперь покажите, с каких устройств чаще уходят после единственного события.
 Такие визиты в стенде считаются отказами. Постройте столбиковый график доли
 отказов по `device_category` за весь период витрины. Каждый столбик должен
 показывать долю для одной категории устройств.
 ## Настройка графика
 Добавьте представление как источник данных для графиков. В Superset такой
 источник называется физическим датасетом. Выберите подключение `ClickHouse`,
 схему `dm` и объект `session_overview_v`. Задайте русские подписи хотя бы двум
 колонкам:
 - `device_category` — «Категория устройства»;
 - `report_date` — «Дата отчета».
 В редакторе датасета, на вкладке «Metrics», создайте метрику:
 | Поле | Значение |
 |---|---|
 | `Metric Key` | `bounce_share` — ключ метрики и ее SQL-псевдоним |
 | `Label` | «Доля отказов» |
 | `SQL expression` | `SUM(bounce_sessions) / SUM(sessions)` |
 | `D3 format` | `.1%` |
 Выражение делит общее число отказов на общее число сессий. Усреднение дневных
 долей может дать неверный результат: число сессий в разные дни различается.
 Сохраните метрику в датасете, чтобы все будущие графики использовали одно
 выражение, подпись и формат. Это правило описано в
 [справочнике Superset](../architecture/superset.md#дерево-импорта).
 Не используйте вкладку «Custom SQL» конструктора графика. Созданная там
 метрика доступна только этому графику, а нужна метрика датасета.
 Создайте столбиковый график с метрикой «Доля отказов». В поле «X-axis»
 укажите «Категория устройства», а «Dimensions» не заполняйте. Дашборд
 создавать не нужно: сохраненного графика достаточно.
 Для этого задания оставьте период «No filter»: график и проверочный запрос
 ниже считают долю отказов за весь период витрины. Относительный период,
 например «Last week», может дать пустой график: модельный календарь стенда
 отстает от настоящего. Последнюю дату витрины посмотрите в SQL Lab:
 ```sql
 SELECT max(report_date)
 FROM dm.session_overview_v;
 ```
 Стендовые объекты не меняйте. Что переживает `make up`, а что стирает
 `make clean`, описано в главе [«Отчеты в Superset»](../handbook/superset.md#готовые-и-собственные-отчеты).
 ## Проверка результата
 Автоматической проверки этого задания нет. Сверьте числа на графике
 с результатом запроса в SQL Lab:
 ```sql
 SELECT device_category,
       round(100 * sum(bounce_sessions) / sum(sessions), 1) AS bounce_pct
 FROM dm.session_overview_v
 GROUP BY device_category
 ORDER BY device_category;
 ```
 Сверьте с графиком значение для каждой категории. В разделе «Customize»
 включите «Show Value» или наведите указатель на столбик. Запрос возвращает
 проценты с одним знаком, как формат `.1%`, поэтому числа должны совпасть
 один в один.
 ## Результат работы
 - [ ] у вас есть физический датасет `dm.session_overview_v` в подключении
      `ClickHouse`;
 - [ ] в датасете есть метрика «Доля отказов» с выражением
      `SUM(bounce_sessions) / SUM(sessions)` и форматом `.1%`;
 - [ ] колонки `device_category` и `report_date` подписаны «Категория
      устройства» и «Дата отчета»;
 - [ ] сохраненный столбиковый график показывает долю отказов по категориям
      устройств за весь период витрины;
 - [ ] числа на графике совпадают с результатом запроса из SQL Lab;
 - [ ] вы сохранили график отдельно, без создания дашборда и изменения
      стендовых объектов.
@@ -1,95 +0,0 @@
 # Сессии из событий
 Вы самостоятельно объедините события сайта в сессии и сравните их число
 с готовыми визитами источника, обозначенными `VisitID`. Затем найдете
 события, из-за которых расчеты расходятся.
 ## Подготовка
 - [Хранилище и его слои, раздел DDS](../handbook/storage-layers.md#dds-события-заказы-и-сессии);
 - [формат события: Идентификаторы и время](../formats/clickstream-event.md#идентификаторы-и-время).
 ## События и визиты
 Визит, или сессия, объединяет действия посетителя за один заход на сайт.
 По визитам аналитик считает длительность и глубину просмотра.
 В хранилище сессии собираются из отдельных событий.
 ## Расчет сессий
 ### Границы визитов
 В SQL Lab или DBeaver под `analyst` напишите запрос к `ods.event_v`.
 Для своего расчета и эталона возьмите одни и те же строки за все доступные
 дни: для расследования понадобятся события соседних дней.
 Выберите `ClientID`, `UTCEventTime`, `EventDate`, `EventType` и `VisitID`.
 В `dds.event_v` эталонного `VisitID` нет.
 `ClientID` хранится в cookie браузера и обозначает посетителя в событиях
 сайта. Для начала считайте визитом последовательные события одного
 `ClientID`: пауза дольше 30 минут открывает новый визит.
 Учитывайте события всех типов. Упорядочите их по `UTCEventTime`.
 Присвойте каждому событию номер своей сессии внутри `ClientID`.
 Подсказка: оконные функции.
 Днем сессии считайте `EventDate` ее первого события: дата из `UTCEventTime`
 отличается от `EventDate` для части событий, поэтому берите `EventDate`.
 При сверке останутся расхождения из-за еще одной договоренности стенда.
 ### Сверка с эталоном
 Посчитайте по эталонному `VisitID` число визитов каждого `ClientID`
 за модельный день:
 ```sql
 SELECT ClientID, EventDate, uniqExact(VisitID) AS reference_sessions
 FROM ods.event_v
 GROUP BY ClientID, EventDate
 ORDER BY EventDate, ClientID;
 ```
 Посчитайте свои сессии по `ClientID` и дню сессии. Соедините результаты двух
 расчетов через `FULL OUTER JOIN` по этим полям. Учтите строки, которые есть
 только с одной стороны: полное соединение сохранит их в результате.
 Выведите сводку по дням с числом `ClientID`, для которых расчеты разошлись,
 и список этих идентификаторов с днем и обоими значениями. Общая сумма за день
 могла бы скрыть ошибки: для одного посетителя вы посчитали лишнюю сессию,
 для другого пропустили. По списку видно, чьи события нужно исследовать.
 Расхождений будет всего несколько. Если их нет, мир прожил мало дней.
 Прогоните несколько дней через [даги модельного времени](../handbook/airflow-dags.md#генерация-модельных-дней)
 и повторите сверку.
 ### Поиск причины расхождения
 Выберите один `ClientID` с расхождением. Выведите его события за два соседних дня
 с `UTCEventTime`, `EventDate`, `VisitID` и номером своей сессии.
 Сопоставьте сессии через события: общего ключа у двух расчетов нет,
 зато у каждого события есть и `VisitID`, и присвоенный вами номер.
 Найдите два соседних события, между которыми границы визитов разошлись.
 Запишите `ClientID`, день, время обоих событий и причину одним предложением.
 Уточните определение визита и добейтесь нуля расхождений во всех днях.
 ## Проверка результата
 Сохраните исходный и уточненный расчеты, результаты сверки и найденные строки.
 Таблицы и представления создавать не нужно. Задачи в `homework_check`
 для этого задания нет: вы проверяете расчет своим запросом.
 В `sql/dds/session_rebuild.sql` и
 `sql/dq/sessions_vs_reference.sql` лежат готовые запросы расчета сессий и сверки.
 Откройте их после собственного решения и расследования. Сравните запросы
 со своими.
 На ступени 4 вы сравните свой результат с готовыми сессиями стенда
 по `session_id`.
 ## Результат работы
 - [ ] ваш запрос собирает сессии из всех событий `ods.event_v` за все
      доступные дни;
 - [ ] у вас есть сводка расхождений по дням и список `ClientID`, полученные через
      `FULL OUTER JOIN`;
 - [ ] вы объяснили причину одного расхождения и записали `ClientID`, день и два
      события, на которых оно видно;
 - [ ] уточненный расчет дает ноль расхождений во всех днях.
@@ -1,193 +0,0 @@
 # Расчет сессий в стенде
 На прошлой ступени вы рассчитали сессии отдельным запросом. Теперь
 перепишете расчет внутри стенда, запустите его через Airflow и проверите
 результат по исходным событиям.
 ## Подготовка
 - [задание «Сессии из событий»](3-1-sessions-by-hand.md);
 - [модель сессии DDS](../architecture/dds/session.md);
 - [дневной конвейер трансформаций](../architecture/etl.md#объём-прогона);
 - [раскладка по шардам](../architecture/storage.md#раскладка-по-шардам).
 ## Файлы для изменения
 Даг, таблицы сессий и проверка их числа уже созданы.
 Перепишите только три файла:
 - `sql/dds/session_scope.sql`;
 - `sql/dds/session_rebuild.sql`;
 - `sql/dds/session_replace.sql`.
 Удалите из них готовый SQL и напишите свой. Даг `dds_transform` передаст
 параметры и выполнит запросы по порядку. Таблицы уже созданы: основные хранят
 готовые сессии, промежуточные нужны для нового расчета перед заменой данных.
 Запрос `sessions_vs_reference.sql` сравнивает число сессий с `VisitID` из ODS.
 ## Выполнение запросов в Airflow
 Объем прогона — дни, которые соберет один запуск. Его вычисляет первый файл.
 | Файл | Вход | Результат |
 |---|---|---|
 | `session_scope.sql` | `{position:UInt16}` — номер первого еще не прожитого модельного дня | `first_day` и `last_day` |
 | `session_rebuild.sql` | `{first_day:Date}`, `{last_day:Date}`, `{load_id:String}` | Сессии в `dds.session_stage_dist` |
 | `session_replace.sql` | День в `{{ params.day }}` | Партиция дня в `dds.session_rep` |
 `first_day` должен быть первым завершившимся модельным днем, которого еще
 нет в DDS, а `last_day` последним завершившимся днем. Начальную дату возьмите
 из событий ODS: `position` считает дни от нее. Текущий модельный день еще
 не закончен, поэтому сессии за него не рассчитываются.
 Если в ODS нет ни одного события, запрос не возвращает строк. Если все
 завершившиеся дни уже есть в DDS, запрос возвращает строку с `first_day = NULL`.
 Тогда Airflow пропускает группу задач расчета сессий: ее состояние будет `skipped`.
 `session_rebuild.sql` сначала очищает `dds.session_stage_rep` на всем кластере.
 Затем он записывает в `dds.session_stage_dist` расчет за все выбранные дни. Добавьте к
 вставке `SETTINGS distributed_foreground_insert = 1`. Так строки успеют попасть
 на шарды до замены партиций.
 Запрос `session_replace.sql` заменяет партицию в основной `dds.session_rep`
 готовой партицией из промежуточной `dds.session_stage_rep`.
 Операция выполняется на всем кластере, на локальных таблицах каждого шарда.
 Не ставьте точку с запятой в конце `session_scope.sql`. Драйвер добавляет формат
 ответа. С точкой с запятой получится несколько команд, которые ClickHouse
 отклонит. День для замены подставляет шаблон Jinja в Airflow. Параметр
 ClickHouse в `ALTER ... PARTITION` здесь не работает.
 ## Правила расчета сессий
 Источник сборки — `dds.event_v`. Одна строка результата представляет один
 визит. На третьей ступени вы уже получили правила разделения событий на сессии:
 - сессия не пересекает модельные сутки;
 - пауза больше 30 минут открывает новую сессию;
 - в расчете участвуют события всех типов.
 Повторный расчет должен давать тот же результат. При одинаковом времени
 упорядочивайте события по `event_id`: порядок в оконных функциях должен быть
 `(event_time, event_id)`. Один визит должен получать одинаковый `session_id`
 при каждом запуске.
 Вычислите идентификатор как `cityHash64(client_id, min(event_time))`.
 Состав и типы строки заданы в `dds.session_rep`. Заполните начало, конец и
 длительность. Посчитайте все события, просмотры, добавления в корзину и
 покупки. Возьмите входную и выходную страницы, UTM первого события, устройство
 и город. Заполните также служебные колонки из схемы таблицы.
 Пишите через `dds.session_stage_dist`: шард для строки определяется по
 `client_id`. При записи прямо в локальную таблицу он зависел бы от узла,
 который выполнил запрос.
 ## Запуск нового расчета
 Готовые дни повторно не собираются. Чтобы новый SQL точно выполнился, выберите
 последний собранный день:
 ```sql
 SELECT max(session_date)
 FROM dds.session_v;
 ```
 Берите последний день: если удалить более ранний, расчет придется повторить
 и за все последующие завершившиеся дни.
 Сохраните десять строк с идентификатором, границами, длительностью и счетчиками:
 ```sql
 SELECT
    session_id,
    client_id,
    session_date,
    started_at,
    finished_at,
    duration_seconds,
    events_total,
    pageviews,
    cart_adds,
    purchases
 FROM dds.session_v
 WHERE session_date = 'YYYY-MM-DD'
 ORDER BY client_id, started_at, session_id
 LIMIT 10;
 ```
 Создайте в DBeaver подключение к первому узлу по [инструкции из
 README](../../README.md#подключиться-из-dbeaver). Укажите пользователя `etl` и
 пароль `CLICKHOUSE_ETL_PASSWORD` из `.env`. У этой учетной записи есть право
 менять таблицы DDS на кластере. Подставьте найденную дату и удалите только ее
 партицию:
 ```sql
 ALTER TABLE dds.session_rep ON CLUSTER clickstream_cluster
 DROP PARTITION 'YYYY-MM-DD';
 ```
 Откройте Airflow и запустите `etl_pipeline`. В даге `dds_transform` раскройте
 группу `session`: в ней должны выполниться задачи `scope` и `rebuild`, а также
 `replace` для выбранного дня. Если после третьей ступени мир ушел вперед,
 в группе появятся задачи `replace` и для последующих прожитых дней. Следом
 обновятся витрины и выполнится `dq_check`.
 Если прогон дошел до замены, но упал на проверке, ошибочная партиция уже
 находится в DDS. После правки снова удалите тот же день перед следующим
 запуском. Иначе день останется заполненным, а новая сборка для него не
 выполнится.
 ## Проверка результата
 Сначала повторите запрос с десятью строками. `session_id`, границы,
 длительность и счетчики должны совпасть с сохраненным результатом.
 Это проверит, что ваш расчет восстановил те же сессии с теми же идентификаторами.
 Задача `dq_check.sessions_vs_reference` должна стать зеленой. Та же проверка
 видна в хранилище:
 ```sql
 SELECT data_date, reference_rows, actual_rows, failed_rows, status
 FROM dm.dq_summary_v
 WHERE check_name = 'sessions_vs_reference'
 ORDER BY data_date;
 ```
 Эта сверка сравнивает число сессий каждого `client_id` за день с `VisitID`.
 При `failed_rows = 0` число сессий совпало, но их границы, страницы и UTM
 еще могут различаться. Как на третьей ступени, проверьте отдельные сессии.
 Для одного `client_id` выбранного дня найдите начало и конец каждого
 `VisitID` по событиям и сравните с границами строк `dds.session_v`.
 По исходным событиям проверьте страницы, UTM, устройство
 и город. Страницы и UTM не входят в сохраненные десять строк: готовый SQL
 стенда выбирал их через `argMin` и `argMax` только по `event_time`. При равном
 времени ожидаемое значение определяйте по исходным событиям и полному порядку
 `(event_time, event_id)`.
 Проверьте также, на каком шарде лежит каждая строка. Напишите отдельный
 запрос к `dds.session_dist`. Он должен:
 1. получить фактический узел строки через `hostName()`;
 2. определить ожидаемый узел по `cityHash64(client_id)`;
 3. посчитать строки, у которых фактический и ожидаемый узлы не совпали.
 У кластера два равных шарда: остаток 0 соответствует `clickhouse-01`, остаток
 1 — `clickhouse-02`. Сгруппируйте ответ по фактическому узлу. На каждом узле
 число строк на чужом шарде должно быть нулевым. Проверка числа сессий читает
 Distributed-таблицу и такую ошибку не заметит.
 После зеленого результата запустите `etl_pipeline` еще раз, не удаляя
 партицию. Группа сессий должна быть пропущена: все завершившиеся дни уже
 рассчитаны, новых дней и пропусков нет.
 ## Результат работы
 - [ ] вы переписали три файла `sql/dds/session_*.sql`, сохранив даг,
      таблицы и проверку стенда;
 - [ ] ваш расчет восстановил удаленный день, `etl_pipeline` завершился успешно;
 - [ ] вы сверили десять сохраненных строк: `session_id`, границы,
      длительность и счетчики совпали после пересборки;
 - [ ] вы получили ноль расхождений в `sessions_vs_reference` за все
      прожитые дни и вручную сверили границы и поля сессии одного `client_id`;
 - [ ] ваш запрос с `hostName()` не нашел строк на чужом шарде;
 - [ ] повторный прогон без удаления данных пропустил группу сессий.
@@ -1,150 +0,0 @@
 # Проверки качества заказов
 Перед изменением обработки заказов вы добавите две проверки качества данных.
 Затем намеренно испортите один заказ и убедитесь, что проверки обнаружили
 ошибки.
 ## Подготовка
 - [модель заказа DDS](../architecture/dds/order.md);
 - [дневной конвейер](../architecture/etl.md#объём-прогона);
 - [правила проверок](../architecture/testing.md#проверка-которая-не-умеет-краснеть-бесполезна).
 Посмотрите также на устройство одной проверки в [`sql/dq/`](../../sql/dq/)
 и на ее включение в [`dq_check`](../../dags/dq_check.py). Готового ответа для
 двух проверок из этого задания в репозитории нет.
 ## Новые проверки
 Добавьте две проверки и включите их в даг:
 - `sql/dq/order_items_total.sql` проверяет сумму позиций заказа;
 - `sql/dq/orders_vs_ods.sql` сверяет DDS с его источником;
 - `dags/dq_check.py` запускает обе проверки, записывает их результаты в
  `dm.dq_summary` и создает для них отдельные задачи.
 Разбор ODS и сборку DDS вы перепишете в следующих заданиях. Здесь сохраните
 их, даги загрузки, DDL, промежуточные таблицы, Kafka и службы как есть.
 Перед опытами остановите автоматическое движение мира: поставьте `world_live`
 на паузу и дождитесь завершения активных прогонов. До завершения опытов не
 запускайте руками `world_next_day`, `world_live_day`, `world_initialize` и
 `world_recreate`, чтобы новые данные не меняли результат между проверками.
 ## Требования к запросам
 Чтобы `dq_check` мог запустить проверку, ее запрос возвращает по одной строке
 на день с колонками `data_date`, `reference_rows`, `actual_rows`,
 `failed_rows`, `diagnostics`. Даг сохраняет в `dm.dq_summary` только счетчики,
 статус и сведения о запуске. Примеры из `diagnostics` ищите в
 журнале упавшей задачи Airflow. Ограничьте их тем же малым числом, что и
 существующие запросы в `sql/dq/`.
 ### Сумма позиций
 Имя проверки - `order_items_total`. Для каждого заказа из `dds.order_v`
 посчитайте сумму `item_price * item_quantity` и сравните ее с `items_total`.
 В `reference_rows` запишите число заказов со стороны `items_total`,
 в `actual_rows` число заказов со стороны вычисленной суммы, в `failed_rows`
 число заказов, у которых суммы не совпали. На исправных данных первые два
 счетчика равны, а `failed_rows` равен нулю. Для примеров расхождений
 достаточно `order_id`, значения `items_total` и вычисленной суммы позиций.
 Проверка поможет заметить ошибки разбора `items` при переносе заказа
 из ODS в DDS. Скидку, доставку и равенство `total` здесь проверять не нужно.
 ### Полнота заказов в DDS
 Имя проверки - `orders_vs_ods`. Источник модели DDS здесь - текущее состояние
 `ods.order_v`. С ним вы и сравниваете DDS; обращаться к внутреннему состоянию
 генератора для этой проверки не нужно.
 Одним запросом рассчитайте итоги каждого дня заказа в обоих слоях и сравните:
 - число заказов;
 - максимальный `updated_at`.
 День заказа в ODS вычисляйте в `Europe/Samara`, как `order_date` в DDS.
 Проверьте все дни, которые есть хотя бы в одном слое: так вы заметите день,
 целиком пропавший из другого. Перед сравнением приведите времена к одному
 часовому поясу. `reference_rows` содержит число заказов ODS, `actual_rows`
 число заказов DDS. В `failed_rows` запишите 1, если за день расходится
 хотя бы одно значение, и 0, если оба совпали.
 Обе стороны распределены по `order_id`. Дневные агрегаты соедините через
 `GLOBAL FULL OUTER JOIN` с `join_use_nulls = 1`, как в существующих сверках.
 Если строка потерялась при разборе в ODS, она не попадет и в DDS. Эта проверка
 не заметит потерю: данные слоев совпадут. В [следующем задании](5-2-order-parsing.md)
 вы отдельно сравните число исходных строк с числом разобранных заказов
 и ошибок за один запуск, обозначенный `_load_id`.
 ## Проверка на намеренных ошибках
 Сначала запустите `dq_check` на нетронутых данных. Обе новые задачи должны
 завершиться успешно, а в `dm.dq_summary_v` у обоих имен не должно быть
 дней с расхождениями.
 Выберите оплаченный заказ из последнего слепка с непустым массивом позиций и
 сохраните его `order_id` и `order_date`. Подключитесь к первому узлу из DBeaver
 по [инструкции из README](../../README.md#подключиться-из-dbeaver) под
 пользователем `etl`. Прибавьте одну копейку к `items_total` этого заказа в
 локальной таблице `dds.order_rep` на всем кластере:
 ```sql
 ALTER TABLE dds.order_rep ON CLUSTER clickstream_cluster
 UPDATE items_total = items_total + toDecimal64(0.01, 2)
 WHERE order_id = '<order_id>'
 SETTINGS mutations_sync = 2;
 ```
 Затем запустите только `dq_check`. Задача `order_items_total` должна
 завершиться ошибкой, а ее журнал - назвать выбранный заказ.
 `purchase_vs_orders_vs_dds` тоже даст красный результат: сохраненная витрина
 содержит прежний `items_total`.
 Запустите `etl_pipeline`. Текущее окно заказов будет заново собрано из ODS, и
 исходная строка вернется в DDS. Повторный `dq_check` должен дать зеленый
 результат для новой проверки.
 Теперь удалите тот же заказ из `dds.order_rep` на всем кластере:
 ```sql
 ALTER TABLE dds.order_rep ON CLUSTER clickstream_cluster
 DELETE WHERE order_id = '<order_id>'
 SETTINGS mutations_sync = 2;
 ```
 До восстановления снова запустите только `dq_check`. Красный результат нужен
 для `orders_vs_ods`, `purchase_vs_orders_vs_dds` и `revenue_daily_vs_dds` на
 дне оплаченного заказа. Затем запустите `etl_pipeline` и повторите проверку.
 Если `orders_vs_ods` не обнаружил удаление, исправьте запрос до следующего
 задания.
 ## Проверка результата
 В `dm.dq_summary_v` обе новые и пять прежних проверок должны быть успешны:
 ```sql
 SELECT check_name, sum(failed_rows) AS failed_rows, groupUniqArray(status)
 FROM dm.dq_summary_v
 GROUP BY check_name
 ORDER BY check_name;
 ```
 Проверка суммы должна охватывать каждый день `dds.order_v`. Сверка слоев
 должна охватывать объединение дней ODS и DDS, включая дни только одной стороны.
 ## Завершение работы
 После восстановления заказа и успешного `dq_check` можно закончить работу или
 перейти к разбору заказов, оставив модельное время на паузе.
 ## Результат работы
 - [ ] две новые проверки запускаются в `dq_check`, а их дневные результаты
      появляются в `dm.dq_summary`;
 - [ ] вы увидели ошибку каждой проверки после соответствующего изменения
      заказа, а в журнале нашли примеры заказов с расхождениями;
 - [ ] вы восстановили заказ через `etl_pipeline` после обоих опытов;
 - [ ] `order_items_total`, `orders_vs_ods` и пять прежних проверок успешны;
 - [ ] разбор ODS и сборка DDS остались прежними.
@@ -1,182 +0,0 @@
 # Разбор заказов в ODS
 Вы перепишете разбор заказов в ODS. На четырех пробных сообщениях проверите,
 что правильно заполненный заказ и сообщения с ошибками попадают
 в соответствующие таблицы без потерь.
 ## Подготовка
 - [проверки заказов](5-1-order-checks.md);
 - [прием заказов в ODS](../architecture/orders/ingestion.md);
 - [раскладку по шардам](../architecture/storage.md#раскладка-по-шардам);
 - [`orders_ingest`](../../dags/orders_ingest.py);
 - [`order_parse.sql`](../../sql/ods/order_parse.sql).
 ## Порядок работы
 Сначала проведите опыт на готовом `order_parse.sql`. Затем удалите его SQL,
 соберите разбор заново и повторите опыт с другим маркером.
 Сохраните устройство `orders_ingest`, DDL, Kafka, таблиц и преобразований
 DDS. После каждого опыта удалите только добавленные вами строки.
 Перед началом убедитесь, что после [предыдущего задания](5-1-order-checks.md)
 все семь проверок качества прошли успешно. Поставьте `world_live` на паузу, дождитесь
 активных прогонов и до завершения опыта не запускайте `world_next_day`,
 `world_live_day`, `world_initialize` и `world_recreate`. Не запускайте
 `etl_pipeline` между
 отправкой пробной пачки и ее очисткой.
 ## Пробные сообщения
 Сделайте четыре сообщения с общим уникальным маркером:
 1. годную строку с маркером в `order_id`;
 2. JSON-строку вместо объекта - класс `not_an_object`;
 3. объект с лишним ключом - класс `keyset_mismatch`;
 4. объект с точным набором ключей, но строкой в `user_id` - класс
   `field_invalid`.
 `not_an_object` означает, что корень JSON не объект. `keyset_mismatch` означает,
 что у объекта есть лишние верхнеуровневые ключи или не хватает обязательных.
 `field_invalid` означает, что ключи на месте, но значение имеет неверный тип,
 формат или не помещается в заданный тип данных.
 Соберите строки в `/tmp/<маркер>.jsonl`. Заготовка дает одну годную строку и
 по одному примеру каждого класса брака:
 ```bash
 LAB_MARKER="lab5-$(date +%s)"
 LAB_BATCH="/tmp/${LAB_MARKER}.jsonl"
 LAB_DAY="$(
  docker compose exec -T clickhouse-01 sh -lc \
    'clickhouse-client --user etl --password "$CLICKHOUSE_ETL_PASSWORD" \
      --query "SELECT toString(max(snapshot_date)) FROM ods.order_dist"'
 )"
 jq -cn --arg marker "$LAB_MARKER" --arg day "$LAB_DAY" '
  def good($id): {
    order_id: $id, user_id: 1, status: "paid",
    created_at: ($day + "T00:00:00.000Z"),
    updated_at: ($day + "T01:00:00.000Z"),
    items_total: "10.00", discount: "0.00",
    delivery: "0.00", total: "10.00",
    items: [{sku: "lab5", qty: 1, price: "10.00"}],
    snapshot_date: $day
  };
  good($marker),
  ($marker + "-not-an-object"),
  (good($marker + "-keys") + {lab_marker: true}),
  (good($marker + "-field") | .user_id = "broken")
 ' > "$LAB_BATCH"
 ```
 Отправьте файл в обычный топик заказов утилитой из контейнера Kafka:
 ```bash
 docker compose exec -T kafka /opt/kafka/bin/kafka-console-producer.sh \
  --bootstrap-server kafka:9092 --topic orders < "$LAB_BATCH"
 ```
 Запустите `orders_ingest`. Найдите свои строки по маркеру в
 `stg.orders_raw_dist` и сохраните их `_load_id`: это идентификатор запуска,
 который принял сообщения. Он должен быть одинаковым у всех четырех строк.
 ## Проверка готового разбора
 До запуска `etl_pipeline` проверьте строки с найденным `_load_id`:
 - в STG четыре строки;
 - в таблице `ods.order_dist` одна годная строка;
 - в `ods.order_errors_dist` три строки, по одной каждого класса;
 - `STG = годные + брак`;
 - поля заказа в текущей строке `ods.order_v` совпадают с полями из годного
  исходного сообщения; последнюю версию для сравнения выберите через
  `argMax` по `snapshot_date`.
 Считайте строки `ods.order_dist` именно по `_load_id`: представление
 `ods.order_v` оставляет только текущую версию каждого заказа и не показывает,
 сколько строк разобрал запуск. Запрос сверки с `argMax` напишите сами.
 Значения для сравнения извлеките из `raw` пробных сообщений. Отдельно
 сравните `created_at` и `updated_at`: в заготовке они намеренно различаются.
 Проверьте раскладку годной строки через `hostName()` на `ods.order_dist`.
 Узел, на котором лежит строка, должен соответствовать остатку `cityHash64(order_id) % 2`:
 0 - `clickhouse-01`, 1 - `clickhouse-02`.
 ## Удаление пробных сообщений
 Удалите только строки маркера из локальных таблиц:
 ```sql
 ALTER TABLE stg.orders_raw_rep ON CLUSTER clickstream_cluster
 DELETE WHERE position(raw, '<маркер>') > 0
 SETTINGS mutations_sync = 2;
 ALTER TABLE ods.order_rep ON CLUSTER clickstream_cluster
 DELETE WHERE startsWith(order_id, '<маркер>')
 SETTINGS mutations_sync = 2;
 ALTER TABLE ods.order_errors_rep ON CLUSTER clickstream_cluster
 DELETE WHERE position(raw, '<маркер>') > 0
 SETTINGS mutations_sync = 2;
 ```
 В ClickHouse 26.3 мутации выполняются в фоне. С `mutations_sync = 2` команда
 ждет их завершения на всех репликах. Запросами к трем Distributed-таблицам
 убедитесь, что строк маркера не осталось, затем удалите временный файл.
 Группа `clickstream_orders` уже подтвердила эти сообщения, поэтому обычный
 повтор `orders_ingest` их не прочитает. В Kafka они остаются до удаления по
 политике хранения. `world_recreate` удаляет группу и сам топик, поэтому в
 пересозданный мир пробная пачка не переходит.
 Очистка должна закончиться до запуска `etl_pipeline`. Если конвейер все же
 успел собрать временный заказ в DDS, сначала очистите три таблицы выше, затем
 запустите `etl_pipeline`: пересборка текущего окна удалит заказ из DDS и
 обновит витрины.
 ## Собственный разбор заказов
 Удалите готовый SQL из `sql/ods/order_parse.sql` и напишите свой. Чтобы
 `orders_ingest` мог его использовать, сохраните следующие условия:
 - запрос читает строки `stg.orders_raw_dist` с переданным `{load_id:String}`;
 - каждая прочитанная строка попадает ровно в один результат: годный заказ или брак;
 - ошибка в `raw` одной строки не прерывает разбор остальных;
 - годные строки записываются в `ods.order_dist`, остальные - в
  `ods.order_errors_dist`;
 - классы брака и их порядок - `not_an_object`, `keyset_mismatch`,
  `field_invalid`;
 - метки доставки и `_load_id` переходят из STG без пересчета;
 - задача завершается после записи и заказов, и ошибок на шарды через
  Distributed; строки распределяются по ключу соответствующей целевой таблицы.
 Точный набор полей, типы и условия проверки значений описаны в
 [документе приема](../architecture/orders/ingestion.md#граница-строгого-приёма),
 а целевые колонки - в [`20-ods-tables.sql`](../../sql/ddl/20-ods-tables.sql).
 Содержимое `items` сохраните как JSON: его разбирает DDS.
 Повторите опыт с новым маркером. Получите тот же баланс 4 = 1 + 3, те же три
 класса, верную текущую версию заказа по `snapshot_date`, разные значения
 `created_at` и `updated_at` и правильный шард. Затем удалите строки второго
 опыта теми же командами и запустите
 `dq_check`.
 ## Завершение работы
 Убедитесь, что оба маркера отсутствуют в STG, ODS, таблице брака и DDS,
 временные файлы удалены, а семь проверок успешны. Теперь можно перейти к
 сборке DDS, не снимая паузу с модельного времени. Если вы прерываетесь и до
 опыта `world_live` работал, снимите его с паузы.
 ## Результат работы
 - [ ] у вас сохранены результаты до переписывания: четыре строки дали
      один заказ и три класса брака; вы сверили поля текущей версии и шард;
 - [ ] вы переписали `sql/ods/order_parse.sql`, сохранив остальные части стенда;
 - [ ] ваш разбор дал тот же результат на новой пробной пачке;
 - [ ] вы проверили разные значения `created_at` и `updated_at` у годной
      строки в обоих опытах и подтвердили правильный шард через `hostName()`;
 - [ ] строки обоих опытов удалены по их маркерам;
 - [ ] после очистки конвейер и все семь проверок успешны.
@@ -1,132 +0,0 @@
 # Сборка заказов в DDS
 Вы перепишете загрузку заказов из ODS в DDS и выбор дней для пересчета.
 Затем удалите данные за один из прошлых дней и проверите, что ваша
 загрузка восстановила их.
 ## Подготовка
 - [проверки заказов](5-1-order-checks.md);
 - [разбор заказов в ODS](5-2-order-parsing.md);
 - [модель заказа DDS](../architecture/dds/order.md);
 - [дневной конвейер](../architecture/etl.md#объём-прогона);
 - [раскладку по шардам](../architecture/storage.md#раскладка-по-шардам).
 ## Файлы для изменения
 Удалите готовый SQL и перепишите только три файла:
 - `sql/dds/order_scope.sql`;
 - `sql/dds/order_rebuild.sql`;
 - `sql/dds/order_replace.sql`.
 Даг `dds_transform`, DDL, промежуточную таблицу, ODS и обе проверки из первого задания
 оставьте как есть. Перед началом убедитесь, что пробные строки предыдущего
 задания удалены, а семь проверок качества дают зеленый результат.
 Поставьте `world_live` на паузу и дождитесь завершения активных прогонов. До
 завершения опыта не запускайте `world_live_day`, `world_initialize` и
 `world_recreate`. `world_next_day` понадобится только в явно указанном ниже
 случае.
 ## Выполнение запросов в Airflow
 Даг `dds_transform` ожидает от файлов следующие параметры и результаты:
 | Файл | Вход | Результат |
 |---|---|---|
 | `order_scope.sql` | без параметров | одна строка `first_day`, `last_day` |
 | `order_rebuild.sql` | `{first_day:Date}`, `{last_day:Date}`, `{load_id:String}` | выбранные дни в `dds.order_stage_dist` |
 | `order_replace.sql` | день в `{{ params.day }}` | партиция дня в `dds.order_rep` |
 Сначала определите дни, за которые заказы еще могут измениться. Возьмите
 строки с последним `snapshot_date` и найдите минимальную и максимальную
 дату заказа. Этот диапазон далее называется текущим окном источника.
 Затем найдите первый день, который есть в ODS, но отсутствует в DDS.
 Если он раньше начала текущего окна, начните расчет с него. Иначе начните
 с начала окна. Полученная дата станет `first_day`, а конец окна `last_day`.
 Один запуск пересчитывает все дни между ними. Если источник пуст,
 `order_scope.sql` не возвращает строку.
 `order_rebuild.sql` сначала очищает все партиции `dds.order_stage_rep` на
 кластере, затем записывает в `dds.order_stage_dist` весь выбранный отрезок. Он
 читает текущее состояние `ods.order_v`, вычисляет `order_date`, переводит
 времена в `Europe/Samara`, разбирает `items` в три параллельных массива и
 заполняет служебные поля запуска.
 Дождитесь записи всех строк на шарды через Distributed перед заменой партиций.
 Строки должны распределяться по ключу целевой таблицы. Способ рассчитать
 выбранные дни внутри файла выберите сами.
 `order_replace.sql` работает с локальными `dds.order_rep` и
 `dds.order_stage_rep` на всем кластере. `REPLACE PARTITION` заменяет дневную
 партицию основной таблицы готовой партицией из промежуточной. Промежуточная
 партиция при этом сохраняется. Структура, ключи и политика хранения таблиц
 совпадают: DDL создает промежуточную через `AS dds.order_rep`.
 ## Восстановление пропущенного дня
 Найдите самый поздний день DDS перед началом текущего окна ODS. Заказы за этот
 день уже не меняются, поэтому он считается закрытым. Удалив его, вы проверите,
 что ваш запрос заметил пропуск и включил этот день в расчет.
 Если такого дня еще нет, один раз продвиньте мир через `world_next_day`,
 дождитесь `orders_ingest`, затем запустите `etl_pipeline`. После этого снова
 оставьте модельное время неизменным до конца опыта и выберите этот день.
 Сохраните для него число заказов и контрольную сумму их полей, исключив
 служебные `_load_id` и `_load_ts`. Контрольная сумма позволит проверить,
 что после восстановления значения остались прежними. Удалите только
 партицию выбранного дня:
 ```sql
 ALTER TABLE dds.order_rep ON CLUSTER clickstream_cluster
 DROP PARTITION 'YYYY-MM-DD';
 ```
 Сразу запустите `dq_check`, до восстановления партиции. Красный результат
 должны дать `orders_vs_ods` и `purchase_vs_orders_vs_dds`.
 `revenue_daily_vs_dds` тоже даст красный результат, если в партиции были
 оплаченные заказы. `classes_vs_inventory` останется зеленым: до запуска
 `dm_transform` эта проверка читает прежнюю витрину сверки.
 Запустите `etl_pipeline`. В группе `dds_transform.order` значение `first_day`
 должно совпасть с удаленным днем, а задачи `replace` - покрыть непрерывный
 отрезок от него до конца текущего окна. `first_day` ищите в строке про объем
 пересборки в журнале задачи `order.scope` дага `dds_transform`. После успешного
 прогона число заказов и контрольная сумма выбранного дня должны совпасть с
 сохраненными.
 ## Распределение по шардам и повторный запуск
 Напишите отдельный запрос к `dds.order_dist`, который получает фактический
 узел каждой строки через `hostName()`, вычисляет ожидаемый по
 `cityHash64(order_id) % 2` и считает несовпадения по каждому узлу.
 Остаток 0 соответствует `clickhouse-01`, остаток 1 - `clickhouse-02`.
 На обоих узлах число строк на чужом шарде должно быть нулевым.
 Проверки количества строк читают данные со всех шардов через Distributed
 и такую ошибку не обнаруживают.
 Запустите `etl_pipeline` еще раз при неизменном модельном времени. Группа
 заказов снова должна пересобрать текущее изменяемое окно. Контрольные суммы
 полей заказов остаются прежними, а все семь проверок дают зеленый результат.
 ## Завершение работы
 После восстановления партиции и успешных проверок снимите `world_live`
 с паузы, если он работал до упражнения.
 ## Результат работы
 - [ ] вы переписали три файла `sql/dds/order_*.sql`, сохранив остальные
      части стенда;
 - [ ] вы удалили ближайший к окну закрытый день и увидели ошибку проверки до
      восстановления;
 - [ ] ваш расчет выбрал `first_day` с удаленного дня и заменил партиции
      всего отрезка до конца окна;
 - [ ] вы сверили число заказов и контрольную сумму восстановленного дня
      с сохраненными значениями; они совпали;
 - [ ] `order_items_total`, `orders_vs_ods` и пять прежних проверок успешны;
 - [ ] ваш запрос с `hostName()` не нашел заказов на чужом шарде;
 - [ ] после повторного `etl_pipeline` поля заказов остались прежними, проверки прошли.
@@ -1,225 +0,0 @@
 # Разбор сырых событий
 В этой работе вы разберете сохраненные сообщения о событиях в свою таблицу.
 Каждую полученную строку сравните с результатом обработки в стенде.
 ## Подготовка
 - [формат события](../formats/clickstream-event.md);
 - [справочник хранилища](../architecture/storage.md), разделы про имена
  объектов, актуальные события, прием потока и срок жизни сырых данных;
 - [ADR о приеме событий](../adr/0005-event-ingestion.md), раздел с принятым
  решением;
 - схему [`ods.event_rep`](../../sql/ddl/20-ods-tables.sql).
 Готовый стендовый разбор находится в `sql/ddl/30-ods-views.sql`. Откройте его
 после собственной сверки: в нем лежит ответ на основную часть задания.
 ## Порядок работы
 Создайте в базе `default` свою таблицу для правильно заполненных событий.
 Выберите небольшой набор сообщений из `stg.hits_raw_dist`, разберите их
 и загрузите в таблицу одним `INSERT SELECT`. Работайте с первым узлом под
 пользователем `etl`. Затем сравните результат с событиями в ODS.
 Материализованные представления `ods.event_mv` и `ods.event_errors_mv`
 продолжают обрабатывать поступающие сообщения. Оставьте их, STG, ODS, Kafka
 и даги без изменений. Если пересоздать представления на работающем стенде,
 часть сообщений может остаться без обработки.
 Дайте своей таблице имя, которое не пересечется с чужой работой, и запишите
 его вместе с запросами.
 ## Выбор исходных сообщений
 STG хранит строки примерно три дня по `_load_ts`. Эта колонка отмечает время
 поступления в хранилище. Модельный день события лежит в `EventDate`.
 Посмотрите, сколько строк поступило за каждую из последних минут:
 ```sql
 SELECT
    toStartOfMinute(_load_ts) AS minute,
    count() AS rows
 FROM stg.hits_raw_dist
 WHERE _load_ts >= now() - INTERVAL 30 MINUTE
  AND _load_ts < toStartOfMinute(now())
 GROUP BY minute
 ORDER BY minute DESC;
 ```
 Выберите короткий интервал `[slice_from, slice_to)`, который уже закончился и
 дает удобное для построчной проверки число строк. Этот набор строк дальше
 называется срезом. Если за одну минуту пришло слишком много строк,
 сузьте ее точными границами `_load_ts`. Если недавних строк нет, откройте
 Airflow. При включенном `world_live` посмотрите его текущий запуск и дочерний
 `world_live_day`: дождитесь свежих строк от текущего или следующего планового
 запуска, а при ошибке сначала разберите ее причину. Запустите `world_live_day`
 вручную, только если `world_live` стоит на паузе и активного `world_live_day`
 нет. Успешный прогон распределяет события модельного дня по реальным минутам.
 Зафиксируйте до разбора:
 - обе границы с миллисекундами и число строк;
 - минимальный и максимальный `kafka_offset` по каждой паре
  `kafka_topic`, `kafka_partition`.
 Во всех дальнейших запросах читайте `stg.hits_raw_dist` только с этими
 границами. Новые строки с более поздним `_load_ts` в срез не попадут. Повторите
 опыт до удаления исходных строк по TTL; после него прежний срез уже не восстановить из ODS.
 ## Таблица для результата
 Таблица содержит все 47 полей источника с именами и типами
 `ods.event_rep`, а также `_load_ts`. Тип `purchaseRevenue` возьмите из ODS:
 `Array(Decimal(18, 2))`.
 Обработайте повторные доставки так же, как ODS. Возьмите
 `ReplacingMergeTree(_load_ts)`, партицию `EventDate` и полный ключ замены:
 `(CounterID, EventDate, intHash32(ClientID), WatchID)`. Достаточно одной
 локальной таблицы: загрузка и сверка в этом опыте выполняются на одном узле.
 `WatchID` обозначает событие и уникален по
 [правилам генератора](../specs/2026-08-01-generator.md). Но `ReplacingMergeTree`
 считает версиями строки, у которых совпадает весь ключ сортировки.
 Поэтому для загрузки и сверки используйте все четыре части ключа ODS,
 перечисленные выше.
 ## Разбор сообщений
 Для каждой строки среза проверьте те же условия приема, что и на стенде:
 1. корень `raw` — JSON-объект;
 2. набор верхнеуровневых ключей в точности равен 47 ключам формата;
 3. `WatchID`, `VisitID`, `ClientID`, `EventDate` и `UTCEventTime` разбираются
   в ожидаемые типы.
 Напишите разбор, который не прерывает пакет из-за одной грязной строки. Сами
 выберите, как извлечь пять перечисленных полей без ошибки запроса, какие
 выражения вынести в общую часть и где отфильтровать неподходящие строки.
 Эти пять полей дальше называются опорными. Остальные поля извлеките
 по описанию формата.
 Перенесите `_load_ts` из STG без пересчета: это время исходной доставки и
 колонка версии. Время запуска вашего запроса сюда не входит. Вставьте в свою
 таблицу только годные строки выбранного среза.
 Считайте отвергнутые строки прямо в исходном срезе, без отдельной таблицы
 брака. Одним запросом посчитайте:
 - все доставки;
 - строки, прошедшие ваше условие отбора;
 - строки, для которых это условие ложно.
 Проверьте равенство общего числа строк сумме прошедших и отвергнутых. Так каждая
 исходная строка учитывается ровно в одной группе. Если отвергнутые строки есть,
 сохраните их `raw`, `_load_ts` и координаты Kafka. Найдите те же
 координаты в `ods.event_errors_dist` и запишите стендовый `error_class`. Если
 брака нет, так и зафиксируйте: опыт проверил успешную ветвь и выполнение
 условия отбора на этом срезе, но не классификатор ошибок. Подкладывать грязные
 сообщения ради задания не требуется.
 ## Подготовка к сравнению
 ### Повторные доставки
 В STG одна строка представляет доставку. Повтор сообщения остается второй
 строкой. В `ods.event_v` одна строка представляет актуальное событие, потому
 что представление читает физическую таблицу с `FINAL`.
 Свою таблицу тоже читайте с `FINAL`. Число строк должно совпасть с числом
 различных полных ключей среди годных исходных сообщений. Разница между числом
 годных доставок и этим числом показывает повторы в исходном срезе.
 ### События ODS для сравнения
 Теперь нужно найти в ODS события из выбранного среза. Список стройте по
 исходным доставкам: если взять его из своей таблицы, ошибочно отвергнутое
 событие исчезнет с обеих сторон сверки и потеря останется незамеченной.
 Снова возьмите все выбранные строки STG. По координатам Kafka исключите
 доставки, которые есть в `ods.event_errors_dist`. У оставшихся извлеките
 `WatchID` без риска прервать запрос и выберите эти события из свежего
 `ods.event_v`. Свое условие отбора здесь не применяйте: решение о годности
 доставки вы берете из результата стендового разбора.
 `WatchID` связывает доставку с событием в ODS. Для удаления повторов и
 сравнения полей дальше используйте полный физический ключ из схемы таблицы.
 ## Сверка полей
 Соедините свою таблицу и выбранные строки `ods.event_v` через `FULL OUTER
 JOIN` по полному ключу замены. Полное соединение сохраняет строки,
 которых нет на одной из сторон. Найдите три вида расхождений:
 - строка есть только в ODS — вы ее потеряли;
 - строка есть только у вас — вы приняли лишнее или иначе разобрали часть
  ключа;
 - ключ есть с обеих сторон, но различается хотя бы одно из 47 полей.
 ClickHouse по умолчанию заполняет отсутствующую сторону значениями по умолчанию
 для соответствующих типов, например нулем или пустой строкой.
 Включите для сверки `join_use_nulls = 1` или добавьте явный признак присутствия
 в каждую сторону. Не определяйте отсутствие по значениям полей события.
 Сравните все поля явно, включая массивы, `ecommerce` и точное десятичное
 `purchaseRevenue`. Выберите, как показать расхождения, чтобы было видно,
 какие колонки различаются в конкретной строке. Выведите число строк каждого
 из трех видов расхождений. В верном разборе все три числа равны нулю.
 `_load_ts` не входит в 47 полей источника и не проверяет JSON-разбор.
 Проверьте его отдельно. Для каждой строки своей таблицы найдите самую позднюю
 метку доставки того же полного ключа в исходном срезе. Она должна совпасть
 с `_load_ts`, который вы читаете после `FINAL`. С ODS эту метку не сравнивайте: там может
 храниться более поздняя доставка того же события из-за границ среза.
 ## Поиск ошибок разбора
 Если нашлись расхождения, выберите одну строку. Найдите ее ключ в списке,
 который вы получили из STG, и исходное сообщение `raw`. Выведите рядом
 координаты Kafka и `_load_ts`.
 Для измененной строки назовите поля, которые расходятся, и сравните каждое с
 сырой строкой. Для пропавшей или лишней строки проверьте пять опорных полей и
 результат условия отбора. Если координаты доставки есть в
 `ods.event_errors_dist`, посмотрите `error_class`.
 Исправьте разбор, удалите и заново создайте только собственную таблицу, затем
 повторите вставку того же среза. Остановитесь, когда число исходных доставок по
 прежним границам не изменилось, число годных и отвергнутых строк в сумме дает
 число исходных доставок, а построчная сверка не находит расхождений.
 ## Ограничения проверки
 `ods.event_v` — образец для сравнения. Оба разбора могли повторить одну
 ошибку. Для пяти опорных полей у вас есть проверка преобразования в нужный тип
 и исходный JSON. Остальные 42 поля можно вручную сопоставить с `raw`, однако
 второго независимого источника для всех значений на стенде нет.
 ## Сохранение результата и удаление таблицы
 Сохраните DDL таблицы, запрос разбора, границы среза, число исходных, годных
 и отвергнутых строк и итоговую сверку без расхождений. Запишите также, чего
 не подтверждает сравнение с ODS и как TTL ограничивает время для повторения
 опыта. Затем удалите свою таблицу командой `DROP TABLE` с ее точным именем.
 Убедитесь через `system.tables`, что объекта больше нет.
 Данные стенда вы не меняли, поэтому удалять строки из STG, ODS или
 Kafka после опыта не нужно.
 ## Результат работы
 - [ ] у вас сохранены границы выбранного среза, число строк и координаты
      доставки по партициям Kafka;
 - [ ] ваша таблица содержит все 47 полей и `_load_ts` и обрабатывает
      повторы по тем же правилам, что и ODS;
 - [ ] ваш разбор принимает только JSON-объекты с точным набором ключей и
      пятью опорными полями, которые преобразуются в нужные типы;
 - [ ] вы сверили число исходных строк с суммой годных и отвергнутых,
      а найденный брак разобрали по `raw`, координатам и классу ошибки стенда;
 - [ ] вы выбрали события ODS по исходному срезу и таблице ошибок,
      независимо от своей таблицы и условия отбора;
 - [ ] вы сравнили обе стороны по полному физическому ключу через
      `FULL OUTER JOIN`: во всех 47 полях нет расхождений,
      пропавших и лишних строк тоже нет;
 - [ ] вы отдельно проверили перенос `_load_ts` и учли повторные доставки;
 - [ ] вы записали ограничения сравнения с ODS и срок повторения опыта;
 - [ ] после опыта вы удалили свою таблицу, сохранив объекты и данные стенда.
@@ -1,122 +0,0 @@
 # Мониторинг: куда смотреть
 Вы познакомитесь с дашбордами мониторинга и проведете два расследования:
 найдете запросы, которые создают нагрузку, и выясните, почему события сайта
 и заказы обновляются с разной частотой.
 ## Знакомство с дашбордами
 Откройте Grafana и Airflow по адресам из раздела [«Адреса и
 пароли»](../../README.md#адреса-и-пароли). Для первого знакомства в Grafana
 есть три дашборда:
 - «Данные» — путь сообщений от источника до хранилища;
 - «Кластер» — процессор, память, диски и внутренняя работа ClickHouse;
 - «Запросы» — выполненные запросы, затраченные на них ресурсы и ошибки.
 Откройте все три дашборда и запишите по одному вопросу, на который каждый из
 них помогает ответить. «Данные» оставьте открытым в соседней вкладке.
 Проведите два расследования на работающем стенде. Службы останавливать и данные
 портить не понадобится.
 ## Расследование 1. Какие запросы читают больше всего данных
 Начните в спокойный момент: не запускайте одновременно свои тяжелые запросы.
 Откройте дашборд «Запросы». На панели «Тяжёлые запросы: что прочитало больше
 всех» возьмите первую строку.
 Сохраните:
 - начало и конец выбранного периода, время запроса;
 - место запроса в списке, пользователя и узел;
 - текст запроса;
 - длительность, память, число прочитанных и отданных строк.
 По пользователю и тексту определите, кто отправил запрос и для чего. Затем
 найдите запрос одного из трех открытых дашбордов, который прочитал больше всего
 строк. Если это другая строка, сохраните для нее те же поля.
 По тексту найдите панель, которая отправила запрос. Ищите ее среди трех
 дашбордов по названиям колонок, таблиц и показателей. Запишите, зачем запрос
 читает столько строк и согласуется ли это с вопросом, на который отвечает
 панель.
 В меню панели «Кто спрашивает: сколько запросов и какой у них аппетит»
 откройте Inspect, затем Query. Ответьте на два вопроса:
 1. Почему журнал читают сразу с обоих узлов?
 2. Почему при подсчете запросов исключают записи о начале выполнения и
   записи о выполнении частей запроса на шардах?
 Проверьте второе объяснение по панели ошибок: ее фильтр не исключает записи
 шардов. Объясните, на какие разные вопросы отвечают эти две панели
 и зачем им разные условия отбора.
 ## Расследование 2. Как меняется свежесть заказов
 Откройте дашборд «Данные». Панель «Свежесть: сколько прошло с последней
 доехавшей строки» показывает, сколько времени прошло с последней загрузки.
 Истории значений на ней нет. До наблюдения нарисуйте, как, по вашему ожиданию,
 будут меняться эти числа для событий и заказов в течение одного запуска
 `world_live_day`. Отдельно отметьте ожидаемый момент доставки слепка заказов.
 Если `world_live` снят с паузы, наблюдайте его текущий или следующий
 `world_live_day`: новый ручной запуск встанет в очередь. Если `world_live` на
 паузе и активного `world_live_day` нет, запустите один `world_live_day` вручную.
 Модельные сутки занимают около 24 реальных минут.
 Запишите несколько наблюдений до конца дня и сразу после него:
 | Реальное время | Свежесть событий, с | Свежесть заказов, с | Что происходило в Airflow |
 |---|---:|---:|---|
 | | | | |
 Дашборд обновляется раз в минуту, поэтому точного совпадения момента
 доставки с записью наблюдения ждать не нужно. Перенесите рост и сброс
 показателя заказов на свой рисунок. Объясните форму линии: какую метку времени
 вычитает панель из текущего времени, почему число растет и какое событие его
 сбрасывает. Модельную дату наблюдаемого дня подпишите отдельно от реального
 времени наблюдения.
 Подтвердите, что сброс совпал с загрузкой заказов:
 - в Airflow завершился прием слепка `orders_ingest`;
 - на панели «Дневной слепок заказов: какой доехал, когда и после какой паузы»
  появилась новая верхняя строка.
 Если вы начали после доставки, дождитесь следующего дня либо запишите,
 какую часть изменений успели увидеть. Одно текущее значение не доказывает ни рост, ни
 сброс.
 ## Источники показателей
 Не открывая справочник, объясните своими словами:
 - почему время с последней загрузки считают по ODS, а число поступивших сообщений по STG;
 - почему знаменатель доли брака берут из STG;
 - почему числитель и знаменатель доли брака берут за один период.
 Свяжите ответы с тем, что вы видели на панелях. Затем сверьте объяснение с
 [главой о мониторинге](../handbook/monitoring.md) и справочниками дашбордов
 [«Запросы»](../architecture/monitoring/queries.md) и
 [«Данные»](../architecture/monitoring/data.md). Устройство живого дня и
 доставки слепка описано в [главе об Airflow](../handbook/airflow-dags.md).
 ## Результат работы
 - [ ] для каждого из трех дашбордов записан вопрос, на который он отвечает;
 - [ ] у вас сохранены выбранный период, текст и показатели верхнего запроса;
      вы выяснили, кто его отправил и зачем;
 - [ ] вы нашли запрос открытых дашбордов, который прочитал больше всего
      строк, и панель, которая его отправила;
 - [ ] вы можете объяснить, зачем журнал собирают с двух узлов и какие записи
      учитывают при подсчете запросов;
 - [ ] у вас есть прогноз свежести, сделанный до наблюдения, и несколько
      замеров; рост и сброс на рисунке объяснены через время последней доставки;
 - [ ] вы подтвердили доставку заказов в Airflow и на панели слепков,
      подписали модельную дату отдельно от реального времени наблюдений;
 - [ ] вы можете объяснить выбор слоев для свежести, потока и доли брака
      и почему числитель и знаменатель берут за один период;
 - [ ] после наблюдений службы продолжают работать, данные и стендовые
      дашборды остались без изменений.
@@ -1,205 +1,109 @@
-# Учебные задания
+# Учебные задания: витрины слоя DM и дашборд в Superset
-Вы будете достраивать хранилище небольшого интернет-магазина. Стенд уже
+Пять домашних заданий — про витрины слоя DM. Стенд привозит слой
-загружает события сайта и заказы, обрабатывает их и строит несколько отчетов.
+наполовину: витрины трех сюжетов дашборда и контроль качества построены,
-Сначала вы подготовите данные для новых отчетов, затем разберетесь, как
+остальные витрины строит менти. Каждое из них — самостоятельное ТЗ: что за
-работают расчеты и загрузка, и перепишете часть из них.
+витрина, какое у нее зерно, из чего она собирается и как проверить, что
 собралась верно.
-Основная программа состоит из семи ступеней. Проходите их по порядку,
+Шестое задание — необязательная лаба в Superset. В ней менти собирает свой
-факультативы выбирайте по желанию. Перед первым заданием прочитайте главу
+дашборд поверх пяти витрин.
 [«Хранилище и его слои»](../handbook/storage-layers.md) и выполните запросы
 из нее: они покажут данные, с которыми предстоит работать.
-## Порядок заданий
+Общее устройство слоя — [дока DM](../architecture/dm.md). Она отвечает на
 вопросы «почему так», задание отвечает на вопрос «что сделать».
-| Ступень | Задания | Содержание |
+## Порядок
 Задания идут по нарастанию: каждое следующее опирается на то, что уже
 усвоено.
 | № | Результат | Чему учит |
 |---|---|---|
-| 1 | Пять витрин для отчетов | подготовить данные о событиях, страницах, визитах, ошибках загрузки и рекламе; задания перечислены ниже |
+| 1 | [`events_enriched_v`](events-enriched.md) | слой — это контракт, а не копия данных |
-| 2 | [Свой график в Superset](2-1-superset-chart.md) | построить график по своей витрине и проверить числа на нем |
+| 2 | [`top_pages_daily`](top-pages-daily.md) | зерно сменилось — витрина материализуется и встает в конвейер |
-| 3 | [Сессии из событий](3-1-sessions-by-hand.md) | объединить действия посетителя в визиты и сравнить их с визитами источника |
+| 3 | [`session_overview`](session-overview.md) | зерно решает, на какие вопросы витрина уже не ответит |
-| 4 | [Расчет сессий в стенде](4-1-session-pipeline.md) | включить свой расчет в готовую обработку данных и проверить результат |
+| 4 | [`dq_errors_daily`](dq-errors-daily.md) | у брака свой день и свой срок жизни |
-| 5 | [Проверки качества заказов](5-1-order-checks.md)<br>[Разбор заказов в ODS](5-2-order-parsing.md)<br>[Сборка заказов в DDS](5-3-order-pipeline.md) | сначала написать проверки качества, затем с их помощью проверить свою обработку заказов |
+| 5 | [`utm_effectiveness`](utm-effectiveness.md) | `declared_` в имени — предупреждение, а не украшение |
-| 6 | [Разбор сырых событий](6-1-event-parsing.md) | извлечь поля из сообщений и сравнить результат с готовым разбором стенда |
+| 6 | [Свой дашборд в Superset](superset-dashboard.md) — необязательная лаба | свои объекты BI живут отдельно от стендовых |
 | 7 | [Мониторинг: куда смотреть](7-1-monitoring.md) | найти тяжелые запросы и разобраться, почему данные обновляются с разной частотой |
-## Ступень 1: витрины для отчетов
+## Общие правила
-Витрина готовит данные для конкретного отчета. В стенде они находятся в базе
+Они одни для пяти заданий по витринам, поэтому записаны здесь, а не
-`dm`: это слой DM. Витрины выручки, трафика, сверки покупок с заказами и
+повторяются в каждом ТЗ.
 сводка качества уже готовы. Вы добавите еще пять.
-| № | Витрина | Содержание задания |
+**Читать — через `_v`.** Публичный договор сущности DDS — представление с
-|---|---|---|
+суффиксом `_v`: `dds.event_v`, `dds.session_v`. Витрина называет только
-| 1 | [События для анализа: `events_enriched_v`](1-1-events-enriched.md) | выбрать нужные поля и добавить вычисляемые, сохранив одну строку на событие |
+его; физические `_rep` и `_dist` служат загрузке и обслуживанию. Соседнюю
-| 2 | [Показатели страниц по дням: `top_pages_daily`](1-2-top-pages-daily.md) | сохранить итоги в таблице и настроить их обновление через Airflow |
+домашку витрина источником тоже не берет: витрина слоя DM читает договор
-| 3 | [Визиты по устройствам: `session_overview`](1-3-session-overview.md) | хранить суммы и счетчики для расчета средних и долей |
+DDS, и задания остаются независимыми. Исключение одно и оно оговорено в
-| 4 | [Ошибки загрузки по дням: `dq_errors_daily`](1-4-dq-errors-daily.md) | сохранить число ошибок даже после удаления исходных строк |
+задании 4: у таблиц брака публичного договора нет.
 | 5 | [Показатели рекламы: `utm_effectiveness`](1-5-utm-effectiveness.md) | различать суммы покупок из событий сайта и выручку по заказам магазина |
-Начните с [первого задания](1-1-events-enriched.md): для него достаточно
+**Писать — только в `_dist`.** При записи в локальную таблицу раскладку
-одного представления. В заданиях 2–5 понадобятся таблицы и их обновление
+определяет то, какая нода случайно выполняла код, а не свойство данных.
-по дням. К общим правилам ниже возвращайтесь по мере работы.
+Правило и его следствия — [дока хранилища](../architecture/storage.md),
 «Раскладка по шардам».
-## Создание и обновление витрин
+**Форма — по зерну.** Витрина, меняющая зерно источника, материализуется:
 `dm.<имя>_rep` / `_dist`, донор `dm.<имя>_stage_rep` / `_stage_dist` и
 публичное `dm.<имя>_v` с явным списком колонок. Витрина, сохраняющая зерно,
 остается обычным представлением. Довод — [дока DM](../architecture/dm.md),
 «Форма: по зерну, не по цене запроса».
-### Источники данных
+**Ключ шардирования — твое решение.** Ни одно ТЗ ключа не называет.
 Правило выбора и требование к донору — [дока
 хранилища](../architecture/storage.md), «Раскладка по шардам»: донор
 объявляется через `AS <цель>_rep` и шардируется тем же ключом, что цель,
 иначе замена партиции потеряет строку на одном шарде и задвоит на другом.
 Названный ключ надо уметь защитить: почему он не дает перекоса и почему
 более сложный тут ничего не добавляет. Образец такой защиты —
 `dm.revenue_daily_dist` в [`sql/ddl/55-dm-tables.sql`](../../sql/ddl/55-dm-tables.sql).
-События читайте из `dds.event_v`, сессии из `dds.session_v`. Суффикс `_v`
+**Где лежит код.** DDL домашек — свой файл `sql/ddl/70-labs.sql`: он
-обозначает обычное представление: оно выполняет сохраненный запрос при
+применяется после стендовых по порядку имени, и твои объекты не мешаются
-чтении. Такие представления сохраняют привычные имена и состав колонок,
+со стендовыми. У агрегатов рядом со стендовыми ложатся еще три запроса —
-когда внутреннее устройство таблиц меняется.
+`sql/dm/<витрина>_scope.sql` спрашивает у хранилища, какие дни пересобирает
 запуск, `_rebuild.sql` собирает их в донор, `_replace.sql` заменяет
 партицию, — и задача в
 [`dags/dm_transform.py`](../../dags/dm_transform.py). У разминочного
 представления нет ничего из этого: весь его код — одно `CREATE VIEW`.
-Каждая учебная витрина читает готовый источник и не зависит от других
+**Образец на все случаи** — витрина `revenue_daily`: у нее есть все пять
-учебных витрин. В задании 4 источниками служат таблицы ошибок ODS:
+объектов, донор, сборка, замена дневных партиций и задача в конвейере.
-представлений для них нет.
+Списывать с нее устройство можно и нужно; списывать состав колонок — нет,
 он у каждой витрины свой.
-### Таблицы и представления
+## Самопроверка
-В заданиях 2–5 вы группируете исходные строки. Например, в `top_pages_daily`
+Даг `homework_check` запускается рукой, расписания у него нет. Задача
-одна строка содержит итоги для одной страницы за день. То, чему соответствует
+витрины красная, пока витрины нет или счет не сходится, и зеленая, когда
-одна строка, называют **зерном**. На стенде итоги с новым зерном сохраняют
+собрано верно. В сводку качества конвейера `dm.dq_summary` он не пишет:
-в таблицах. Отчеты читают готовые числа.
+это инструмент лабы, а не история качества стенда.
-Новый расчет сначала записывают в промежуточную таблицу. Пока он готовится,
+Проверка пяти заданий по витринам устроена одинаково и золотых констант не
-отчеты читают прежние данные из основной. Затем готовыми разделами
+содержит: рядом с витриной независимым запросом собирается тот же ответ —
-промежуточной таблицы заменяют разделы основной. Раздел называется
+прямо из источника витрины, минуя ее саму. У четырех заданий источник эталона
-**партицией**; в этих заданиях он содержит данные одного дня.
+тот же, что у витрины, `dds.session_v` или `dds.event_v`; у задания 4 это
-Промежуточную таблицу также называют **донором**.
+таблицы брака ODS, потому что в DDS у брака представительства нет. Обе стороны
 соединяются по деловому ключу через `FULL OUTER JOIN`, и считается число строк,
 где стороны разошлись или одной стороны нет. Ноль — зеленый.
 Полное соединение здесь обязательно: при обычном пропавший день или
 пропавший ключ просто не попал бы в результат и остался бы незамечен.
-На примере `top_pages_daily` пять объектов выглядят так:
+Раздел «Как проверить себя» каждого ТЗ по витрине называет деловой ключ и
 сравниваемые величины. Тот же прием в стендовом исполнении — [даг
 `dq_check`](../../dags/dq_check.py) и запросы в [`sql/dq/`](../../sql/dq).
-| Объект | Для чего нужен |
+**Предупреждение.** Запросы самой проверки лежат в `sql/dq/` открыто, и
-|---|---|
+имена называют витрину и роль сверки. Проверка на инвариантах неизбежно
-| `dm.top_pages_daily_rep` | Хранит рассчитанные строки на каждом шарде |
+близка к ответу: чтобы сверить витрину, надо ее пересчитать. Прятать эти
-| `dm.top_pages_daily_dist` | Читает строки со всех шардов и распределяет запись между ними |
+файлы никто не станет — но открыв их до того, как задание сделано, ты
-| `dm.top_pages_daily_stage_rep` | Хранит новый расчет до замены данных в основной таблице |
+обменяешь урок на готовый SQL.
-| `dm.top_pages_daily_stage_dist` | Распределяет запись нового расчета между шардами |
+Смотреть туда стоит после своей сборки: сравнить два решения полезно,
-| `dm.top_pages_daily_v` | Дает отчетам доступ к готовой витрине; явно перечисляет ее колонки |
+списать одно — нет.
-### Распределение по шардам
+## Уборка
-Каждый из двух шардов стенда хранит свою часть данных. Записывайте строки
+Черновики и опыты за собой сносить: правило проверок стенда —
-через таблицы `_dist`: они выбирают шард по ключу шардирования. Прямая запись
+[дока тестирования](../architecture/testing.md). Снесенная витрина обязана
-в `_rep` оставит строки на том узле, где выполнен запрос.
+снова покраснить свою задачу в `homework_check` — если не покраснила,
-
+проверка ничего и не проверяла.
 Ключ для своей витрины выберите сами. Проверьте распределение строк между
 шардами и объясните, почему выбранного ключа достаточно.
 Пример обоснования для `dm.revenue_daily_dist` есть в
 [`sql/ddl/55-dm-tables.sql`](../../sql/ddl/55-dm-tables.sql).
 Создайте промежуточную таблицу через `AS <цель>_rep`, сохранив структуру и
 ключи основной. У обеих таблиц `_dist` должен быть одинаковый ключ
 шардирования: замена партиции выполняется внутри каждого шарда и не
 перераспределяет строки. Подробности есть в разделе
 [«Раскладка по шардам»](../architecture/storage.md#раскладка-по-шардам).
 ### SQL-файлы и запуск расчета
 Команды создания таблиц и представлений (DDL) сохраняйте в
 `sql/ddl/70-labs.sql`. При создании мира этот файл выполняется после
 стендовых файлов. В работающем стенде примените команды сами по инструкции
 ниже: сохранение файла и повторный `make up` их не выполнят.
 Для витрины с таблицами нужны три файла в `sql/dm/`:
 - `<витрина>_scope.sql` определяет, какие дни пересчитать;
 - `<витрина>_rebuild.sql` рассчитывает их и записывает в промежуточную таблицу;
 - `<витрина>_replace.sql` заменяет партицию одного дня в основной таблице.
 Добавьте запуск расчета в [`dags/dm_transform.py`](../../dags/dm_transform.py),
 чтобы витрина обновлялась вместе с остальными. Для представления из задания 1
 достаточно выполнить `CREATE VIEW`.
 Образец этого порядка работы есть у готовой витрины `revenue_daily`.
 Ее таблицы, SQL-файлы и задача Airflow разобраны в
 [справочнике DM](../architecture/dm.md#dmrevenue_daily_v).
 Состав колонок и выбор дней для пересчета берите из своего задания.
 ## Выполнение SQL в DBeaver
 В DBeaver создайте подключение по [инструкции в README](../../README.md#подключиться-из-dbeaver),
 но укажите пользователя `etl` и пароль из `CLICKHOUSE_ETL_PASSWORD` в `.env`.
 Пользователь `analyst` из той инструкции предназначен для чтения;
 у `etl` есть права создавать таблицы и представления в `dm`.
 Создайте файл `sql/ddl/70-labs.sql` и сохраняйте в нем DDL своих витрин.
 Откройте его в SQL-редакторе этого подключения и выполните DDL текущего
 задания. Создавайте объекты с
 `ON CLUSTER clickstream_cluster`, чтобы они появились на обоих узлах;
 образец для представления — [`sql/ddl/60-dm-views.sql`](../../sql/ddl/60-dm-views.sql).
 Сохраненный файл позволит воссоздать ваши объекты при пересборке мира.
 ## Проверка витрин
 В Airflow есть даг `homework_check` с отдельной задачей для каждой учебной
 витрины. Запускайте его вручную: расписания у него нет. Задача завершится
 ошибкой, если витрина еще не создана или ее данные расходятся с ожидаемыми.
 Причину и примеры расхождений ищите в журнале задачи. Проверки еще не
 выполненных заданий тоже будут красными.
 Проверка заново рассчитывает показатели по источнику и сравнивает их с вашей
 витриной. Строки сопоставляются по полям, которые их определяют: например,
 по дню и странице. `FULL OUTER JOIN` позволяет найти и разные значения, и
 строки, которых нет с одной стороны. `INNER JOIN` пропустил бы отсутствующие
 строки. Когда расхождений нет, задача становится зеленой.
 `homework_check` не сохраняет результаты в сводку качества `dm.dq_summary`.
 Запросы проверок лежат в [`sql/dq/`](../../sql/dq/). Откройте их после собственного решения:
 они заново рассчитывают показатели витрины, поэтому содержат ответ на
 существенную часть задания. Сравните свой способ расчета с готовым.
 ## Задания по желанию
 Полный список сюжетов — в разделе
 [«Факультативы — пять разделов»](../specs/2026-09-01-labs-program.md#4-факультативы--пять-разделов)
 программы.
 ### Почему выручка не сходится
 Открывается после ступени 1. Четыре расследования качества данных:
 - [Куда пропали покупки](optional/missing-purchases.md): найти заказы без
  события, выбрать источник витрины и условие проверки полноты.
 - [Почему повтор покупки завышает выручку](optional/duplicate-purchases.md):
  рассчитать выручку с одной строкой на заказ и проверить результат на
  повторных событиях.
 - [Какая позиция объясняет разницу в сумме](optional/order-amount-difference.md):
  разобрать товары заказа без потери точности и найти причину разницы в суммах.
 - [Почему вчерашняя выручка меняется сегодня](optional/revenue-over-time.md):
  определить, за какие дни пересчитывать выручку и какую историю заказов сохранять.
 Первые три работы используют готовые данные. Четвертая продвигает мир через
 Airflow; для нее вы сохраняете состояния заказов после каждого модельного дня.
 ### Данные о посетителях
 Открывается после ступени 1.
 - [Как новые заказы меняют отчет о посетителях](optional/identity-over-time.md):
  сохранить историю связей, сравнить расчеты на прежних сессиях и определить,
  какие сведения нужны для воспроизведения результата.
 ### Отчеты в Superset
 Открывается после ступени 2. Два самостоятельных задания:
 - [Свой дашборд в Superset](optional/superset-dashboard.md): собрать отчет
  из своих витрин и подтвердить выводы запросами.
 - [В DBeaver работает, в Superset нет](optional/superset-missing-object.md):
  выяснить, почему клиенты по-разному видят один объект хранилища.
 ### Загрузка и обновление данных
 Открывается после ступени 1.
 - [Как обновлять витрину без полной пересборки](optional/incremental-daily-traffic.md):
  продолжить работу о связях пользователей, пересчитать затронутые дни
  и проверить повтор незавершенной загрузки. Повышенная сложность.
 ## Удаление временных объектов
 После опытов удаляйте свои временные объекты. Если удалили учебную витрину,
 ее задача в `homework_check` должна снова завершиться ошибкой: отсутствие
 витрины тоже проверяется. Подробнее — в
 [справочнике проверок](../architecture/testing.md).
@@ -0,0 +1,118 @@
 # Задание 4: `dm.dq_errors_daily`
 **Чему учит:** у брака свой день и свой срок жизни. Витрина качества живет
 по времени загрузки, а не по модельному дню, и переживает собственный
 источник — поэтому «пересобрать все» здесь означает «стереть историю».
 ## Роль витрины
 Сводка приемки: сколько строк за день не прошли разбор и по какой причине.
 Читают ее, когда качество потока просело: сначала смотрят, вырос ли класс
 брака, потом идут за сырым текстом в саму таблицу ошибок.
 Витрина отвечает на вопрос «сколько и чего», а не «что именно сломалось».
 Разбирательство с конкретной строкой начинается в `ods.event_errors_dist` и
 `ods.order_errors_dist`, где рядом с классом лежат сырой текст и координаты
 доставки.
 ## Источник: единственное исключение из правила `_v`
 Общее правило домашек — читать через публичный договор `_v`. У таблиц брака
 такого договора нет, и заводить его ради этой витрины не надо: брак — не
 сущность бизнес-модели, а диагностика слоя приема. Читать нужно
 распределенные таблицы напрямую:
 - `ods.event_errors_dist` — брак разбора событий;
 - `ods.order_errors_dist` — брак разбора слепка заказов.
 Именно `_dist`, а не `_rep`: локальная таблица вернет строки одного шарда, и
 витрина тихо покажет половину брака. Ошибки при этом не будет — ошибка
 появится позже, когда по витрине примут решение.
 ## Зерно и форма
 Зерно — **день загрузки × источник × класс брака**. Зерно источника —
 строка брака, значит зерно сменилось и витрина материализуется:
 `dm.dq_errors_daily_rep` / `_dist`, донор `_stage_rep` / `_stage_dist`,
 публичное `dm.dq_errors_daily_v`. Ключ партиции — день загрузки.
 День здесь — `toDate(_load_ts)`, то есть настоящее время, когда строка
 приехала в хранилище, а не модельный день мира. Модельного дня у брака нет
 и быть не может: он живет в содержимом, а содержимое как раз и не
 разобралось.
 ## Состав колонок
 | Колонка | Тип | Что это |
 |---|---|---|
 | `load_date` | `Date` | день загрузки, в который приехал брак |
 | `source` | `LowCardinality(String)` | `event` или `order` |
 | `error_class` | `LowCardinality(String)` | класс брака из таблицы ошибок |
 | `error_rows` | `UInt64` | число забракованных строк |
 | `_load_id` | `String` | запуск, собравший день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
 Две похожие колонки рядом различаются намеренно: `load_date` — про день,
 когда приехал брак, `_load_ts` — про запуск, который собрал витрину. Первая
 деловая, вторая служебная, и совпадать они не обязаны.
 Классы у двух источников свои и не пересекаются по смыслу, поэтому колонка
 `source` в зерне обязательна: без нее одинаковое имя класса у событий и у
 заказов слилось бы в одну строку.
 ## Ритм пересборки: витрина переживает источник
 Таблицы брака живут месяц (`TTL`), сырые данные — трое суток. Витрина живет без
 срока: сводка «сколько брака было в марте» нужна и после того, как сами строки
 марта удалены.
 Отсюда правило прогона: пересобираются **только те дни загрузки, которые
 еще есть в источнике**. Спроси у источника список живых дней и замени
 партиции ровно этих дней. Соблазн «собрать все заново в донор и подменить
 таблицу целиком» здесь стоит дороже обычного: истекшие по `TTL` дни исчезли
 бы из витрины навсегда, а вместе с ними — единственная оставшаяся память о
 них.
 Текущий день загрузки не замерзает до конца суток: поток событий идет, и
 брак в него еще добавится. Это нормально, день просто пересоберется на
 следующем прогоне.
 ## Ключ шардирования
 Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
 шардам». Витрина крошечная: классов брака у событий и заказов вместе меньше
 десятка. Учти это в защите ключа — иногда правильный ответ звучит как
 «перекос здесь ничего не стоит, и вот почему».
 ## Как проверить себя
 Деловой ключ — пара `source` и `error_class` внутри `load_date`. Область
 проверки — дни загрузки, которые еще живы хотя бы в одной таблице ошибок:
 день за границей `TTL` сверять не с чем, и его отсутствие в источнике не
 ошибка.
 Собери прямой счет по обеим таблицам ошибок, соедини с
 `dm.dq_errors_daily_v` полным внешним соединением по ключу и посчитай
 строки, где ключа нет с одной из сторон или где расходится `error_rows`.
 Ноль — зеленый.
 Отдельно: сумма `error_rows` по живым дням равна общему числу строк в
 `ods.event_errors_dist` плюс `ods.order_errors_dist`. Если эта сумма вышла
 примерно вдвое меньше — витрина почти наверняка собрана с `_rep` вместо
 `_dist` и видит один шард из двух.
 **Пустая витрина — верный ответ.** На чистом стенде брака нет, обе стороны
 пусты, расхождений ноль, задача зеленая. Проверка, которая требует хотя бы
 одной строки, на здоровом стенде краснела бы всегда и приучала бы себя
 игнорировать.
 ## Приемка
 - [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
      ключом цели;
 - [ ] источники — `_dist`-таблицы обоих видов брака;
 - [ ] прогон заменяет партиции только живых дней источника и не трогает
      истекшие;
 - [ ] задача `dq_errors_daily` в `homework_check` зеленая — в том числе на
      чистом стенде, где брака нет;
 - [ ] задача витрины добавлена в `dm_transform`.
@@ -0,0 +1,114 @@
 # Задание 1: `dm.events_enriched_v`
 **Чему учит:** слой — это контракт, а не копия данных. Витрина, которая не
 меняет зерно источника, остается представлением, и копии событий ради
 других имен колонок не заводит ни один боевой склад.
 Это разминка. Строк она не хранит, в конвейер не встает, ключа шардирования
 у нее нет. Задача одна: собрать плоское событие для BI и не поддаться
 соблазну разложить его на диск.
 ## Роль витрины
 Договор события в DDS широкий — 44 колонки, почти весь формат выгрузки:
 часть из них технические координаты источника, часть — параллельные массивы
 товаров. Аналитику в Superset нужен плоский набор деловых полей и пара
 производных, которые иначе каждый пишет заново в каждом запросе.
 Витрина отвечает на вопрос «что вообще происходило»: с нее начинают, когда
 надо посмотреть на события глазами человека, а не разбирать широкую строку
 источника.
 Источником для витрин следующих заданий она не служит. Витрина слоя DM
 читает публичный договор DDS — так устроены и стендовые витрины, и потому
 задания независимы: соседнюю домашку можно делать первой, а можно не делать
 вовсе.
 ## Зерно и форма
 Зерно — **событие**: одна строка витрины равна одной строке `dds.event_v`.
 Зерно источника сохранено, значит форма — обычное представление
 `CREATE VIEW dm.events_enriched_v`, без физической таблицы, без донора и
 без задачи в `dm_transform`. Пересобирать нечего.
 Источник — `dds.event_v`, и только он.
 ## Состав колонок
 Явный список обязателен: договор не должен расширяться сам, когда в
 источник добавят колонку.
 **Время и посетитель:** `event_date`, `event_time`, `event_hour`,
 `client_id`, `event_id`.
 **Действие:** `event_type` (`pageview`, `add_to_cart`, `purchase`), `url`,
 `page_path`, `referer`, `referer_host`, `title`.
 **Атрибуция:** `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`,
 `utm_term`.
 **Паспорт визита:** `device_category`, `browser`, `operating_system`,
 `region_country`, `region_city`.
 **Торговый блок, массивами как в источнике:** `product_id`, `product_name`,
 `product_category`, `product_price`, `product_quantity`,
 `product_event_type`, `purchase_id`, `purchase_revenue`, `purchase_coupon`.
 Три колонки в источнике не лежат и считаются здесь:
 | Колонка | Как считается | Зачем |
 |---|---|---|
 | `event_hour` | `toHour(event_time)` | суточный профиль спрашивают в каждом отчете |
 | `page_path` | путь `url` без домена и параметров | группировка по странице без разбора строки в каждом запросе |
 | `referer_host` | домен `referer` | «откуда пришли» одним значением, а не полным адресом |
 Служебных `_load_id` и `_load_ts` у витрины нет, и это не забывчивость. Их
 нет и у `dds.event_v`: событие в DDS не грузят, а читают из ODS, поэтому
 координат собственной загрузки у него не бывает. Служебная колонка называет
 запуск, который положил строку на диск, — здесь на диск никто ничего не
 кладет.
 ## Ловушка задания
 Массивы `product_*` тянет развернуть через `ARRAY JOIN` — так плоская
 таблица становится по-настоящему плоской. Разворачивать нельзя, и вреда
 здесь два.
 Очевидный: у события с тремя позициями получилось бы три строки, зерно
 витрины перестало бы совпадать с зерном источника, а вместе с ним развалилось
 бы и правило формы — такую витрину уже пришлось бы материализовать.
 Неочевидный и куда более разрушительный: `ARRAY JOIN` — соединение
 внутреннее, и строку с пустым массивом он выбрасывает. Торговый блок пуст у
 всех событий, кроме корзин и покупок, то есть у подавляющего большинства.
 Так «плоская таблица событий» превращается в таблицу товарных позиций и
 теряет девятнадцать строк из двадцати — а по имени и по составу колонок она
 по-прежнему выглядит таблицей событий. Ошибка не падает и ничего не
 подсвечивает.
 Массивы едут в договор как есть; разворачивает их тот, кому нужна позиция
 заказа, — и делает это уже в своей витрине, с другим зерном и другим именем.
 ## Как проверить себя
 Деловой ключ — `event_id` внутри дня. Собери прямой ответ из `dds.event_v`
 за тот же день, соедини с витриной полным внешним соединением и посчитай
 строки, где ключа нет с одной из сторон или где различаются значения
 деловых колонок. Ноль — зеленый.
 Отдельно проверяются три производные колонки: `event_hour`, `page_path` и
 `referer_host` должны совпасть с тем же выражением, посчитанным по
 `dds.event_v` на лету.
 Если строк в витрине оказалось в разы меньше, чем в источнике, а остались в
 ней одни корзины и покупки — это развернутые массивы: `ARRAY JOIN` выбросил
 все события с пустым торговым блоком.
 ## Приемка
 - [ ] `dm.events_enriched_v` создано, физических таблиц под ним нет;
 - [ ] список колонок в представлении явный;
 - [ ] число строк и набор `event_id` совпадают с `dds.event_v` за каждый
      прожитый день;
 - [ ] задача `events_enriched` в `homework_check` зеленая;
 - [ ] задачи в `dm_transform` **нет** — и не должно быть.
@@ -1,84 +0,0 @@
 # Почему повтор покупки завышает выручку
 Несколько событий покупки могут относиться к одному заказу. Вы проверите,
 как они завышают сумму, и составите расчет, который учитывает каждый заказ
 один раз.
 Факультатив доступен после ступени 1. Работайте в DBeaver пользователем
 `analyst` по [инструкции](../../../README.md#подключиться-из-dbeaver).
 Дождитесь завершения `etl_pipeline`; оставьте `world_live` на паузе и
 дождитесь уже начатых прогонов, чтобы данные не менялись между запросами.
 ## Расчет по событиям покупки
 В ODS уже устранены повторные доставки событий. Достаточно ли этого,
 чтобы сложить суммы всех `purchase` для витрины заказов? Проверьте на данных.
 Возьмите день, за который уже получены все слепки заказов: его дата должна быть не позднее
 `max(snapshot_date) - 6` из `ods.order_v`. Во всех запросах к `dds.event_v`
 отбирайте этот `event_date` и `event_type = 'purchase'`.
 Номер заказа находится в `purchase_id[1]`, заявленная сумма — в
 `purchase_revenue[1]`. По формату источника у события покупки один номер заказа.
 Сначала посчитайте число событий и сумму всех заявленных сумм. Затем найдите
 номера заказов, которые встречаются несколько раз. Если таких нет, выберите
 другой день с полученными слепками.
 Для двух повторившихся покупок выпишите `event_id`, `client_id`, `event_time`,
 номер заказа и сумму. Сопоставьте число событий и заказов в `dds.order_v`.
 ## Расчет по заказам
 Напишите запрос с одной строкой на номер заказа. Сохраните в результате
 номер, число исходных событий и одну заявленную сумму. До выбора суммы
 проверьте, что во всех событиях заказа она одинакова. Затем посчитайте итог
 дня по результату этого запроса и сравните с расчетом по событиям.
 Проверьте, что номера в результате уникальны, а число строк совпадает с числом
 разных номеров в исходных событиях. Отдельно проверьте свое решение на случае
 двух разных заказов с одинаковой суммой: сколько денег оно учтет?
 ## Заказы с повторными событиями
 Возьмите один повторившийся номер заказа. Сколько денег он добавил в первый
 расчет и сколько — во второй? Подтвердите разность его событиями.
 Повторите расчет для остальных повторившихся номеров. Сохраните таблицу:
 номер заказа, число событий и вклад в разность сумм. Проверьте, объясняют ли
 эти заказы все расхождение за день до копейки.
 Слой ODS убирает повторную доставку одного события по его идентификатору;
 `dds.event_v` читает уже это состояние. Сравните число разных `event_id`
 и число разных номеров заказа в выбранных строках. Почему устранение
 повторов по первому ключу не дало тот же результат, что по второму?
 Подтвердите ответ конкретными идентификаторами.
 После собственного расчета найдите эти заказы в `dm.purchase_vs_orders_v`.
 Если у повторившегося заказа класс отличается от `duplicate_event`, проверьте
 его статус и [порядок присвоения классов](../../architecture/dm.md#dmpurchase_vs_orders_v).
 Класс витрины не заменяет поиск всех повторов в событиях.
 ## Сравнение с выручкой магазина
 Сложите `revenue` из `dm.revenue_daily_v` за тот же `report_date` по всем
 категориям. Эта витрина считает стоимость позиций оплаченных заказов,
 без скидки и доставки.
 Сравните результат с суммой по событиям после устранения повторов. Совпадение не требуется:
 удаление повторов устраняет одну причину расхождения. Найдите хотя бы один
 заказ, который объясняет, почему деньги трекера и магазина все еще могут
 различаться. Для этого сопоставьте события, заказ и готовую сверку.
 Рядом с запросом укажите, чему соответствует одна строка результата
 и какие поля ее определяют. Обоснуйте, где нужна одна строка на событие,
 а где одна на заказ: следует ли ради этого расчета
 удалять повторные покупки из `dds.event_v`? Используйте найденные `event_id`.
 ## Результат работы
 - [ ] сохранен запрос с одной строкой на заказ, числом событий и суммой;
 - [ ] уникальность ключа и полнота набора номеров проверены по источнику;
 - [ ] разность сумм полностью объяснена вкладом лишних событий;
 - [ ] обоснованы ключ расчета и место устранения повторов;
 - [ ] найден случай, показывающий границы расчета денег по трекеру.
@@ -1,144 +0,0 @@
 # Как новые заказы меняют отчет о посетителях
 Вы сохраните историю связей посетителей сайта с покупателями магазина.
 На ее основе проверите, как новые связи меняют старые отчеты и что нужно,
 чтобы повторить прежний расчет.
 Факультатив доступен после ступени 1. Понадобятся Airflow и DBeaver с
 подключением `student` по [инструкции](../../../README.md#подключиться-из-dbeaver).
 Результаты запросов сохраняйте в `default` через одно подключение:
 ваши таблицы будут доступны только на узле этого подключения.
 Если предложенное имя таблицы занято, выберите свое.
 В событиях сайта посетитель обозначен `client_id` из cookie браузера,
 а в заказах покупатель обозначен `user_id`. Сопоставив событие покупки
 с заказом, можно связать эти идентификаторы. Тогда и к прежним визитам
 этого `client_id` можно добавить
 пользователя магазина. Вы проверите, как появление такой связи меняет число
 известных пользователей в отчете за прошедший день.
 ## Связи посетителей с покупателями
 Поставьте `world_live` на паузу, дождитесь завершения начатых прогонов
 генерации и обработки. Запустите `etl_pipeline` и дождитесь успеха.
 На время работы мир будете продвигать вручную; новые дни останутся в стенде.
 Напишите запрос по двум источникам:
 | Источник | Нужные поля |
 |---|---|
 | `dds.event_v` | `event_type`, `event_time`, `client_id`, `purchase_id` |
 | `dds.order_v` | `order_id`, `user_id` |
 В результате нужна одна строка на пару `client_id`, `user_id`. Для каждой пары
 найдите самое раннее время события покупки, которое удалось сопоставить
 с заказом. Назовите эту колонку `first_purchase_at`.
 В событии `purchase` массив `purchase_id` содержит один номер заказа.
 Статус заказа не ограничивайте: отмена покупки не меняет найденную связь
 посетителя с покупателем.
 Источники распределены по разным ключам. Для соединения используйте
 `GLOBAL INNER JOIN`, заключив выборки событий и заказов в подзапросы.
 Устройство источников описано в [карте идентичностей](../../architecture/dds/identity.md).
 Проверьте уникальность пар и совпадение их полного набора с
 `dds.identity_map_v`: одного равенства количества недостаточно.
 Для одной пары покажите номера заказов и события, по которым получили
 `first_purchase_at`.
 ## История связей
 Создайте таблицу:
 ```sql
 CREATE TABLE default.lab_identity_history
 (
    observation_day Date,
    client_id UInt64,
    user_id UInt64,
    first_purchase_at DateTime('Europe/Samara')
 )
 ENGINE = MergeTree
 ORDER BY (observation_day, client_id, user_id);
 ```
 Каждая копия списка должна содержать все найденные пары. В колонку
 `observation_day` запишите последний обработанный день событий:
 ```sql
 SELECT max(event_date) AS observation_day FROM dds.event_v;
 ```
 Обозначим полученную дату **H0**. Она показывает, после обработки какого
 модельного дня сохранен список; календарная дата запуска Airflow здесь
 не используется. Сохраните полный результат своего запроса через
 `INSERT INTO ... SELECT`, добавив H0 в `observation_day` каждой строки.
 Сверьте число записанных строк с результатом исходного запроса и проверьте
 уникальность пар для этой даты.
 Затем дважды выполните последовательность:
 1. Запустите `world_next_day` с `days = 1` и дождитесь успеха.
 2. Запустите `etl_pipeline` и дождитесь успеха.
 3. Получите новую `observation_day`, сохраните полный набор связей и проверьте его.
 Получатся три копии списка: после дней **H0**, **H1** и **H2**.
 Для каждой даты сохраняйте список один раз: обычный `MergeTree`
 не устраняет повторы вставки. Сохраните и проверьте список перед тем,
 как запускать следующий модельный день.
 ## Дата покупки и дата появления связи
 Сравните списки за соседние даты: H0 с H1, затем H1 с H2. Найдите пары,
 которых не было в прежнем списке. Для нескольких таких пар покажите
 `client_id`, `user_id`, `first_purchase_at` и первую `observation_day`,
 в которой пара появилась. Найдите пример, где покупка произошла раньше
 этой даты.
 Для одной такой связи вернитесь к заказу и событию. По данным и
 [порядку доставки заказов](../../architecture/orders/ingestion.md) объясните,
 почему пары не было в прежнем списке. Какие данные понадобились для ее
 появления и когда они стали доступны?
 Для пары, которая присутствовала уже в H0, нельзя определить дату появления:
 у вас нет более ранних копий списка. Для новой пары можно установить
 интервал между двумя сохранениями, но не точное время внутри него.
 ## Пересчет прежних отчетов
 Возьмите один и тот же набор сессий из `dds.session_v` за даты до H0
 включительно. Постройте два дневных расчета:
 - со списком связей на H0;
 - со списком связей на H2.
 Для каждого дня посчитайте посетителей по разным `client_id` и известных
 пользователей по разным `user_id`. Сессии без связи должны остаться в расчете,
 но неизвестный пользователь не должен увеличивать число известных.
 В соединении сессий с вашей таблицей используйте `GLOBAL LEFT JOIN`.
 В таблице связей заранее отберите одну `observation_day`, чтобы копии
 списка за разные дни не смешались.
 Найдите день с разным числом известных пользователей. Проследите изменение
 до конкретных связей и прежних сессий. Проверьте, что число посетителей
 не изменилось, а число известных пользователей не больше числа посетителей.
 Теперь проверьте, можно ли воспроизвести расчет на H0 без сохраненного
 списка за эту дату. Возьмите список на H2 и оставьте только пары,
 у которых `first_purchase_at` приходится на H0 или более ранний день.
 Сравните полный набор пар с копией на H0. Выведите пары, которые есть
 только в одном из списков.
 На примере найденных различий объясните, какие данные нужно сохранять,
 чтобы повторить прежний расчет.
 ## Результат работы
 У вас есть запрос сопоставления посетителей с покупателями, три сохраненных
 списка связей и сравнение двух расчетов на одном наборе сессий. На конкретных
 парах вы можете показать разницу между датой покупки и датой появления пары
 в сохраненном списке, а также объяснить, что нужно для повторения прежнего
 расчета.
 Сохраните SQL и таблицу `lab_identity_history`: они нужны в продолжении
 [«Как обновлять витрину без полной пересборки»](incremental-daily-traffic.md).
 Если продолжать не планируете, удалите свою таблицу через `DROP TABLE`.
@@ -1,152 +0,0 @@
 # Как обновлять витрину без полной пересборки
 Вы настроите обновление витрины только за дни, затронутые новыми данными.
 Затем проверите, можно ли продолжить загрузку, которая успела записать
 лишь часть результатов.
 Факультатив повышенной сложности продолжает работу
 [«Как новые заказы меняют отчет о посетителях»](identity-over-time.md).
 Понадобятся ее запрос сохранения списка связей и таблица `default.lab_identity_history`.
 Работайте под `student` через то же подключение DBeaver.
 Стенд пересчитывает `dm.daily_traffic_v` целиком: новая связь может изменить
 число известных пользователей в старом дне. Вы построите рядом свою витрину,
 которая пересчитывает только затронутые дни и дает тот же результат.
 При обычном продвижении модельного времени появляются новые дни сессий
 и новые связи. Уже найденные пары сохраняются, а сессии прежних дней
 не меняются.
 Удаление данных, исправления старых сессий и пересоздание мира потребовали бы
 другого способа обнаружения изменений.
 ## Витрина и журнал загрузок
 Создайте две локальные таблицы. Если имена заняты, выберите свои.
 ```sql
 CREATE TABLE default.lab_daily_traffic
 (
    report_date Date,
    visitors UInt64,
    known_users UInt64,
    observation_day Date
 )
 ENGINE = ReplacingMergeTree(observation_day)
 ORDER BY report_date;
 CREATE TABLE default.lab_traffic_runs
 (
    observation_day Date
 )
 ENGINE = MergeTree
 ORDER BY observation_day;
 ```
 В витрине одна актуальная строка на день. Для обновления вставляйте полный
 новый результат дня с новой `observation_day`. Читайте витрину с `FINAL`:
 для каждого `report_date` останется строка с максимальной `observation_day`.
 Старые версии могут исчезнуть при слиянии,
 поэтому для воспроизведения прежнего расчета нужна сохраненная история связей.
 В журнал записывайте `observation_day` списка связей, использованного
 для расчета. Добавляйте дату только после записи всех выбранных дней
 и успешной сверки. Максимальная дата в журнале укажет, какой список
 использовался в последней завершенной загрузке.
 ## Первая загрузка
 Убедитесь, что `world_live` стоит на паузе и нет активных прогонов генерации
 и обработки. Запустите `etl_pipeline` и дождитесь успеха. Получите текущую
 `observation_day` способом из первой работы. Если списка за эту дату еще нет
 в вашей истории, сохраните его. Повторно вставлять уже сохраненный список
 не требуется.
 Напишите `INSERT INTO ... SELECT`, который рассчитывает все даты сессий из
 `dds.session_v` со списком связей на текущую дату. Правила результата:
 | Колонка | Что считать |
 |---|---|
 | `report_date` | `session_date` |
 | `visitors` | число разных `client_id` |
 | `known_users` | число разных известных `user_id` |
 | `observation_day` | дата выбранной копии списка связей |
 Сессии без известного пользователя сохраняйте в расчете. Несколько кук одного
 пользователя не должны увеличивать `known_users`. Для соединения с вашей
 таблицей связей используйте `GLOBAL LEFT JOIN`, отобрав одну `observation_day`.
 Построчно сверьте свои `report_date`, `visitors`, `known_users` с
 `dm.daily_traffic_v`. Сверка должна находить лишние и отсутствующие даты
 и различия обоих показателей. Учебную витрину читайте с `FINAL`.
 После совпадения запишите дату наблюдения в журнал один раз.
 ## Выбор дней для пересчета
 Продвиньте мир на один день: `world_next_day` с `days = 1`, затем
 `etl_pipeline`; после каждого запуска дождитесь успеха. Сохраните новый
 список связей запросом из первой работы.
 Обозначим максимальную `observation_day` в журнале **P**, а дату нового
 списка связей — **H**. До записи результата составьте запрос, возвращающий
 даты для пересчета без повторов. Он должен учесть два изменения:
 - в сессиях появились дни, которых еще нет в вашей витрине;
 - в списке на H появились пары, которых не было в списке на P; у этих `client_id`
  есть сессии, в том числе за прежние дни.
 Сначала выведите даты и выберите один прежний день: какая новая пара
 потребовала его пересчета и какие сессии с ней связаны? Рядом посчитайте,
 сколько дат пересчитала бы полная загрузка. Зафиксируйте оба числа;
 равенство тоже возможно, если новые связи затронули всю историю.
 Для сравнения выберите из списка на H пары, у которых день покупки
 по `first_purchase_at` позже P. Совпадет ли результат с новыми парами,
 найденными сравнением списков? Покажите пару, которую ограничение по дате
 покупки пропускает.
 ## Обновление витрины
 Напишите второй `INSERT INTO ... SELECT`. Для выбранных дат он должен
 рассчитать все сессии с полным списком связей на H. Прибавление числа новых
 связей к прежнему `known_users` не заменяет пересчет разных пользователей.
 Вставьте результаты с версией H. Полностью сверьте актуальную учебную витрину
 со стендовой, включая дни, которые не пересчитывали. Только после совпадения
 добавьте H в журнал.
 Без продвижения мира снова определите P по журналу и повторите выбор дат.
 Запрос должен вернуть пустой результат, а витрина — остаться прежней.
 Повторно записывать H в журнал не требуется.
 ## Повтор незавершенной загрузки
 Снова запустите `world_next_day` с `days = 1`, затем `etl_pipeline`,
 дожидаясь успеха каждого. Сохраните новый список связей с его датой H.
 Получите даты для пересчета, но запишите результат только за одну из
 них. Остальные пока не загружайте и дату в журнал не добавляйте.
 Так вы воспроизведете остановку между записями дней, не ломая стенд.
 Снова определите P по журналу, выполните запрос выбора дат и пересчет
 этих дней. Проверьте, что результат совпал со стендовой витриной без очистки
 уже записанных строк. После сверки запишите H в журнал.
 Объясните на этом опыте, почему сохранение нового списка связей еще
 не означает, что витрина обновлена. Что изменится, если записать H в журнал
 до обновления витрины?
 ## Результат работы
 Сохраните SQL первой загрузки, выбора дат, обновления и сверки.
 После двух новых модельных дней ваша витрина совпадает со стендовой,
 повтор без новых данных сохраняет результат, а незавершенную загрузку
 можно продолжить без полной пересборки.
 Сравните число пересчитанных дней с полной загрузкой и перечислите,
 какие дополнительные данные пришлось хранить. Так можно оценить объем работы.
 На небольшом стенде полный пересчет может быть дешевле.
 В вашей реализации поиск связей пока читает всю историю покупок.
 По новым данным обновляется только дневная витрина; такое обновление
 называют инкрементальным.
 После работы удалите свои `lab_daily_traffic`, `lab_traffic_runs` и
 `lab_identity_history` через `DROP TABLE`, если они больше не нужны.
@@ -1,105 +0,0 @@
 # Куда пропали покупки
 Вы сравните покупки из событий сайта с заказами магазина. Найденные
 расхождения помогут выбрать источник для полной витрины заказов.
 Факультатив доступен после ступени 1. В DBeaver подключитесь пользователем
 `analyst` по [инструкции](../../../README.md#подключиться-из-dbeaver).
 Дождитесь завершения `etl_pipeline`; на время расследования оставьте
 `world_live` на паузе и дождитесь уже начатых прогонов.
 ## Выбор дня
 Можно ли построить полную витрину заказов по событиям `purchase`?
 Проверьте это на одном дне: сначала сопоставьте события сайта, затем сверьте
 номера заказов с выгрузкой магазина.
 Слепок заказов содержит их состояние на конец модельного дня. Состояние
 заказа может меняться семь дней, поэтому для окончательного сравнения нужны
 все слепки за этот период. Возьмите день, для которого уже получен последний
 из них. Такой день называется закрытым. Запрос показывает самую позднюю
 подходящую дату:
 ```sql
 SELECT max(snapshot_date) - 6 AS last_closed_day
 FROM ods.order_v;
 ```
 Используйте выбранный день во всех запросах. События отбирайте по
 `dds.event_v.event_date`, заказы — по `dds.order_v.order_date`.
 Сравнивайте все заказы дня, включая отмененные: сейчас вопрос в том,
 зарегистрировал ли магазин заказ, а не в том, был ли он оплачен.
 ## События оформления заказа
 При оформлении заказа посетитель видит страницу подтверждения, а трекер
 отправляет событие покупки. Просмотр страницы и покупка — отдельные события.
 Посчитайте просмотры страницы подтверждения и события покупки:
 - у просмотра `event_type = 'pageview'`, а `url` заканчивается на `/confirmation`;
 - у покупки `event_type = 'purchase'`.
 Вычтите число событий покупки из числа просмотров подтверждения. Сохраните
 оба счетчика и разность. Как соотносились бы эти числа, если бы для каждого
 заказа пришло ровно по одному событию каждого вида? Что можно предположить
 по вашему результату и чего эти два числа еще не доказывают?
 ## Сверка с заказами магазина
 В событии номер заказа находится в `purchase_id[1]`, в заказах — в `order_id`.
 Соберите список заказов выбранного дня, для которых нет события покупки.
 Несколько событий с одним номером заказа должны оставаться одной покупкой.
 Сохраните запрос сверки: на каждый такой заказ он должен возвращать дату,
 номер и статус. Дату задавайте в одном месте, чтобы запрос можно было
 повторить для другого дня.
 Проверьте два равенства:
 - число заказов магазина равно числу разных заказов из событий плюс число
  заказов без события;
 - разность просмотров подтверждения и событий покупки равна числу заказов
  без события.
 Первое равенство проверяет полноту сопоставления источников. Второе связывает
 разность счетчиков с найденными заказами без события. Проверьте, как на него
 влияют повторные покупки.
 Найдите номер заказа с несколькими событиями `purchase`. Для его `client_id`
 выведите события рядом с этими покупками по времени: `event_time`,
 `event_type` и `url`. Найдите просмотры `/confirmation` перед первой
 и повторной покупкой. Посчитайте, сколько повтор добавил просмотров
 подтверждения и сколько — покупок. Изменилась ли от этих добавлений разность
 счетчиков? Подтвердите ответ найденными строками. Второе равенство относится
 к устройству этого стенда; для другого источника его нужно проверять заново.
 Если в выбранном дне повторов нет, возьмите другой закрытый день.
 ## Сравнение с готовой витриной
 Найдите свои заказы без события в `dm.purchase_vs_orders_v` по `order_id`.
 Сравните их `status` и `mismatch_class`. Витрина присваивает заказу один класс,
 хотя причин расхождения может быть несколько. По
 [правилу классификации](../../architecture/dm.md#dmpurchase_vs_orders_v)
 объясните, почему потеря события не всегда попадает в `lost_event`.
 Возьмите один заказ из своего списка и сохраните два запроса: первый находит
 его в магазине, второй показывает отсутствие покупки в трекере.
 ## Выбор источника для витрины
 По результатам сверки укажите источник для витрины, в которой должен быть
 каждый зарегистрированный заказ. Обоснуйте выбор найденными номерами.
 Рядом с запросом запишите, когда его результат можно считать окончательным.
 Что изменится, если запустить его до получения всех слепков выбранного дня?
 Позволяет ли отсутствие события в `dds.event_v` установить место потери —
 до приема в хранилище или при обработке? Какие данные нужны, чтобы это выяснить?
 ## Результат работы
 - [ ] сохранен запрос сверки по дате, возвращающий заказы без события;
 - [ ] оба равенства сходятся, влияние повторного просмотра объяснено;
 - [ ] один случай подтвержден запросами к обоим источникам;
 - [ ] источник витрины выбран по результатам сверки;
 - [ ] указаны условие окончательной проверки и границы ее выводов.
@@ -1,85 +0,0 @@
 # Какая позиция объясняет разницу в сумме
 Вы сравните товары в событии покупки и заказе магазина, чтобы найти причину
 разницы в суммах. При разборе вложенных данных понадобится сохранить точность
 цен до копейки.
 Факультатив доступен после ступени 1. В DBeaver используйте пользователя
 `analyst` из [инструкции подключения](../../../README.md#подключиться-из-dbeaver).
 Дождитесь завершения `etl_pipeline`; оставьте `world_live` на паузе и
 дождитесь уже начатых прогонов.
 ## Выбор заказа
 Суммы покупки в трекере и заказа в магазине различаются. Разберите их позиции
 и проверьте отдельно точность своего запроса и различия между событием и заказом.
 В `dm.purchase_vs_orders_v` выберите один заказ с
 `mismatch_class = 'amount_delta'`. Возьмите закрытый день: `order_day`
 не позднее `max(snapshot_date) - 6` из `ods.order_v`. Сохраните `order_id`,
 `order_day`, `declared_revenue` и `items_total`.
 Найдите этот заказ в `dds.order_v`. Сопоставьте `items_total`, `discount`,
 `delivery` и `total`. Запишите равенство, связывающее эти четыре значения,
 и проверьте его на заказе. С какой суммой магазина следует сравнивать
 `declared_revenue`, если мы ищем расхождение именно в составе корзины?
 Проверьте свой выбор после разбора позиций.
 ## Товарные позиции события и заказа
 Найдите событие покупки в `ods.event_v`: `purchaseID[1]` совпадает с номером
 заказа, `EventDate` — с выбранным днем, `EventType = 'purchase'`.
 Откройте поле `ecommerce`. Внутри JSON массив `purchase.products` содержит
 товары из события покупки с полями `id`, `price` и `quantity`.
 Разверните этот массив в строки и получите артикул, точную цену, количество
 и стоимость каждой позиции. Для разбора пригодятся `JSONExtractArrayRaw`
 и `JSONExtract`, для разворачивания массива — `ARRAY JOIN`.
 Деньги извлекайте как `Decimal` с двумя знаками после запятой.
 С другой стороны используйте массивы `item_sku`, `item_price` и
 `item_quantity` заказа в `dds.order_v`. Элементы с одним индексом относятся
 к одной позиции; при разворачивании сохраняйте эту связь.
 Сопоставьте позиции по артикулу так, чтобы остались видны товары,
 присутствующие только с одной стороны. Для каждой позиции сравните наличие,
 цену и количество. Что различается и сколько это добавляет к расхождению
 сумм?
 Сохраните запрос сверки для выбранных даты и номера заказа; в результате
 оставьте артикул, значения с обеих сторон и разность стоимостей позиций.
 ## Проверка сумм
 Подтвердите три равенства:
 - сумма стоимостей клиентских позиций равна `declared_revenue`;
 - сумма стоимостей позиций магазина равна `items_total`;
 - сумма расхождений по позициям равна
  `declared_revenue - items_total`.
 Затем сравните точные цены из JSON с готовым массивом `productPrice`
 события. Пересчитайте стоимость клиентской корзины по этому массиву:
 сойдется ли она с `declared_revenue` до копейки? Найдите цены, на которых
 результаты различаются, и сверьте наблюдение с
 [форматом выгрузки](../../formats/clickstream-event.md). Если все цены
 выбранной корзины целые, возьмите еще один заказ с расхождением и дробной ценой.
 Какие строки подтверждают найденное расхождение? Есть ли в источниках
 сведения о том, почему оно возникло? Отделите наблюдения от предположений.
 ## Поля для точного расчета
 Укажите рядом с запросом, откуда брать цену, каким типом ее читать и по какому
 ключу сопоставлять позиции. Подтвердите выбор результатами обеих сверок:
 суммы разобранных позиций с суммой своего источника и позиций двух источников
 между собой. Какой результат укажет на ошибку вашего разбора, а какой
 потребует искать причину выше — в данных, которые получил запрос?
 ## Результат работы
 - [ ] сохранен запрос сверки позиций, не теряющий товары без пары;
 - [ ] все три равенства сходятся до копейки;
 - [ ] найден пример потери точности в готовом массиве цен;
 - [ ] выбор полей, типа денег и ключа сопоставления подтвержден расчетами;
 - [ ] расхождение источников сверки отделено от ошибки своего разбора и различия
      между стоимостью корзины и итогом со скидкой и доставкой.
@@ -1,191 +0,0 @@
 # Почему вчерашняя выручка меняется сегодня
 Вы проследите, как опоздавшие заказы и смена статусов меняют выручку
 за прошедший день. По этим наблюдениям определите, какие дни пересчитывать
 и какую историю заказов сохранять.
 Факультатив доступен после ступени 1. Понадобятся Airflow и DBeaver с
 подключением `student` по [инструкции](../../../README.md#подключиться-из-dbeaver).
 Пользователь `student` может читать данные стенда и записывать ваши наблюдения
 в базу `default`.
 Вы будете наблюдать один день оформления заказов, продвигая мир по одному
 модельному дню. Проверьте, можно ли при загрузке выручки каждый раз считать
 только новый день. Новые данные останутся в стенде.
 ## Подготовка
 Поставьте `world_live` на паузу. Дождитесь завершения начатых прогонов
 генерации и обработки, затем запустите `etl_pipeline` и дождитесь успеха.
 Так исходное наблюдение будет снято после обновления витрин.
 Узнайте последний день событий и дату последнего полученного слепка:
 ```sql
 SELECT
    (SELECT max(event_date) FROM dds.event_v) AS event_day,
    (SELECT max(snapshot_date) FROM ods.order_v) AS snapshot_day;
 ```
 День `event_day` обозначим **D**. Наблюдайте именно его до конца работы.
 Дата слепка, по которому сделано очередное наблюдение, будет **S**.
 Это модельные даты магазина. Календарная дата запуска Airflow день D не задает.
 Слепок содержит состояние заказов на конец модельных суток и доставляется
 при следующем запуске генератора. Поэтому покупки последнего завершившегося
 дня уже видны в событиях, а их заказов в
 хранилище еще нет. Проверьте это для D в `dds.order_v` и
 `dm.purchase_vs_orders_v`.
 ## Таблицы для истории заказов
 Представление `dds.order_v` показывает текущее состояние заказов, а сырые слепки
 хранятся ограниченное время. Сохраните историю в двух своих таблицах: потом
 вы сможете сравнивать наблюдения обычными SQL-запросами в том же DBeaver.
 Выполните DDL ниже. Это локальные таблицы на узле вашего подключения;
 всю работу выполняйте через одно подключение. Если имена уже заняты вашей
 прошлой работой, выберите другие и используйте их в дальнейших запросах.
 ```sql
 CREATE TABLE default.lab_order_history
 (
    order_date Date,
    snapshot_date Date,
    order_id String,
    status String,
    items_total Decimal(18, 2)
 )
 ENGINE = MergeTree
 ORDER BY (order_date, snapshot_date, order_id);
 CREATE TABLE default.lab_revenue_history
 (
    order_date Date,
    snapshot_date Date,
    revenue Decimal(18, 2),
    awaiting_order_ids Array(String)
 )
 ENGINE = MergeTree
 ORDER BY (order_date, snapshot_date);
 ```
 ## Первое наблюдение
 Напишите два `INSERT INTO ... SELECT` с явным списком колонок назначения:
 | Куда записать | Что взять из стенда |
 |---|---|
 | `default.lab_order_history` | По строке на заказ дня D из `dds.order_v`: `order_date`, `order_id`, `status`, `items_total`; добавьте дату наблюдения S |
 | `default.lab_revenue_history` | Одну строку с D, S, суммой `revenue` за `report_date = D` из `dm.revenue_daily_v` и массивом номеров `awaiting_order` за `order_day = D` из `dm.purchase_vs_orders_v` |
 Во втором запросе сумму и массив получите отдельными агрегатами, чтобы
 заказы не умножили строки выручки при соединении. Для массива пригодится
 `groupArray(order_id)`. Дату S берите из `max(snapshot_date)` в `ods.order_v`.
 Сначала выполните части `SELECT` отдельно и проверьте результаты, затем
 сохраните их. До первого слепка заказов дня D еще нет: в таблицу заказов
 строки не добавятся, но в таблице итогов должна появиться строка с нулевой
 выручкой. Она зафиксирует, что наблюдение сделано.
 Каждую пару D и S сохраняйте один раз: повторный `INSERT` добавит копии строк.
 После записи проверьте, что на эту пару приходится одна строка итогов,
 а число заказов и число разных `order_id` совпадают с `dds.order_v` за D.
 Выручка этой витрины — стоимость позиций оплаченных заказов без скидки и
 доставки. Для каждого сохраненного наблюдения посчитайте число заказов по
 статусам и сумму `items_total` только у `paid`. Эта сумма должна сходиться
 с сохраненной выручкой, сложенной по всем категориям.
 ## Наблюдения за следующие дни
 Для каждого следующего наблюдения:
 1. Запустите `world_next_day` с `days = 1` и дождитесь успеха.
 2. Запустите `etl_pipeline` и дождитесь успеха: `world_next_day` сам витрины
   не обновляет.
 3. Повторите два запроса сохранения с новой датой S и проверьте записанные строки.
 Во всех запросах остается прежний день D. За один запуск добавляйте один
 день, чтобы сохранить промежуточные состояния. Пакетный `world_next_day`
 отправляет события без пауз; ждать 24 минуты живого дня здесь не нужно.
 Продолжайте до слепка **D + 7** включительно. Заказы дня D могут меняться
 семь дней, от D до D + 6. Этот период называется окном изменяемости.
 Последний шаг нужен для сравнения состояния в конце окна и после него.
 От исходного наблюдения потребуется восемь однодневных запусков.
 ## Изменения заказов и выручки
 Для сравнения прочитайте `default.lab_order_history` дважды: в одном
 подзапросе отберите прежнюю S, в другом — новую; день D остается общим.
 Соедините состояния по `order_id`, сохранив и заказы без пары. Итоги для этих
 же D и S возьмите из `default.lab_revenue_history`. Найдите:
 - заказы, отсутствовавшие в первом слепке D, но появившиеся в следующем;
 - переходы из `created` в `paid`;
 - отмены заказов, для которых раньше был виден статус `paid`.
 Первый слепок, полученный на следующий день, — обычная доставка заказов.
 Опоздавшими здесь считаются те, которых не было уже в этом слепке.
 Покажите на нескольких номерах, как они исчезают из `awaiting_order`.
 Выберите два соседних наблюдения, между которыми хотя бы один заказ перешел
 из `paid` в `cancelled`. Разложите изменение выручки по заказам.
 Составьте таблицу: номер заказа, прежний и новый статусы, вклад в выручку
 до и после изменения. Вклад определите по правилу расчета витрины, указанному
 выше; учтите и заказы, которых еще не было в первом наблюдении. Сумма
 изменений вкладов должна совпасть с изменением `revenue` до копейки.
 Покажите на этих наблюдениях, какой результат остался бы в витрине,
 если бы конвейер после первого расчета обрабатывал только новые дни заказов.
 Достаточно ли добавлять в старый день только опоздавшие заказы? Проверьте
 свой ответ на найденных изменениях статусов.
 ## Требования к истории заказов
 Возьмите отмененный заказ, у которого в вашей истории был статус `paid`.
 Укажите два наблюдения, доказывающих, что он был оплачен, а затем отменен.
 Теперь возьмите отмененный заказ, для которого ни в одном вашем наблюдении
 нет `paid`. Проверьте утверждение «этот заказ никогда не был оплачен»:
 что известно о его состоянии между двумя слепками? Достаточно ли сохраненных
 наблюдений для такого вывода?
 Сформулируйте требования к данным для двух задач: восстановить состояние
 витрины на момент прошлого расчета и узнать, был ли заказ когда-либо оплачен.
 Какие сведения для каждой задачи должен передавать источник и сохранять
 хранилище? Проверьте, каких нужных сведений нет в ваших таблицах наблюдений.
 ## Правило пересчета витрины
 Сравните сохраненные состояния при S = D + 6 и S = D + 7: состав заказов,
 их статусы, суммы и выручку. Какой слепок последним мог изменить заказы дня D
 и каким прогоном он доставлен? Укажите наблюдение, после которого отчет
 можно считать окончательным. Было бы достаточно совпадения двух соседних
 сумм, если бы окно еще не закончилось?
 Запишите правило выбора дней для пересчета после очередного слепка.
 Считайте, что начальная история уже загружена и ежедневные прогоны не
 пропускались. Укажите, по какой дате определяются границы, какие дни нужно
 пересчитать и когда день можно перестать включать в расчет. Подтвердите
 правило своими наблюдениями, включая опоздание и отмену.
 После собственных выводов сверьтесь с описанием
 [слепка и его доставки](../../architecture/orders/snapshot.md#слепок-и-его-доставка)
 и [границ истории отмен](../../architecture/orders/fate.md#судьба-заказа).
 ## Результат работы
 - [ ] сохранена последовательность наблюдений одного дня D с датами слепков S;
 - [ ] на опоздавших заказах и изменениях статусов показаны ошибки загрузки
      только новых дней или только новых заказов;
 - [ ] изменение выручки между наблюдениями сходится с изменением вкладов заказов;
 - [ ] для одного отмененного заказа найдены два наблюдения: с оплатой и с отменой;
 - [ ] сформулированы требования к истории расчетов и истории оплаты;
 - [ ] правило пересчета и момент закрытия дня обоснованы наблюдениями
      и правилом доставки слепков.
 После работы оставьте `world_live` на паузе либо верните автоматическое
 продвижение, если пользовались им до наблюдения. Таблицы истории останутся
 для повторной проверки выводов. Когда они больше не нужны, удалите только
 свои `default.lab_order_history` и `default.lab_revenue_history`.
@@ -1,112 +0,0 @@
 # Свой дашборд в Superset
 Из своих витрин вы соберете отчет о поведении посетителей: подберете графики
 и разместите их на одном экране так, чтобы отчет можно было понять
 без ваших пояснений.
 Это задание раздела «Отчеты в Superset». Его можно пройти после ступени 2,
 когда готовы витрины ступени 1.
 ## Отчет о поведении посетителей
 Соберите обзор трафика и поведения посетителей. Он должен отвечать на три
 вопроса: что происходило в магазине, какие страницы, устройства и рекламные
 каналы дали результат, были ли ошибки приема данных.
 Стендовый дашборд «Бизнес-сюжеты» собран из готовых витрин. Свой дашборд
 соберите из пяти витрин, которые вы построили в заданиях. Копировать раскладку
 стендового дашборда не нужно: выберите форму, в которой ответы читаются без
 пояснений рядом с экраном.
 ## Отдельный дашборд для задания
 Не добавляйте графики в стендовый дашборд и не правьте его датасеты. При
 инициализации Superset импорт с `--overwrite` заменит ручные правки стендовых
 объектов файлами из репозитория. `make up` свой дашборд не стирает; срок жизни
 таких объектов описан в [справочнике Superset](../../architecture/superset.md), «Импорт
 при каждой инициализации».
 Используйте свои датасеты и графики, соберите из них свой дашборд.
 Назовите его, например, «Мои витрины DM».
 ## Датасеты
 Датасет `session_overview_v`, его метрика доли отказов и график уже готовы
 после [ступени 2](../2-1-superset-chart.md). Используйте их здесь. Добавьте
 недостающие датасеты, чтобы в подключении `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`. Среднее по готовым
 долям для такого графика не подходит.
 Названия графиков, осей и показателей должны объяснять экран без чтения SQL.
 ## Период отчета
 Выберите явный период из модельного календаря и задайте его в графиках
 поведения посетителей. Последнюю доступную дату посмотрите в своих витринах.
 Относительный период вроде `Last week` отсчитывается от настоящего времени
 и может дать пустой экран.
 Ошибки приема считаются по `load_date`, дню загрузки, а поведение посетителей
 по модельному времени. Для панели ошибок выберите период загрузки отдельно
 и укажите его в подписи. Общий фильтр времени для всего дашборда не требуется.
 ## Проверка результата
 Автоматической проверки этого задания нет. Числа вы сверите запросами,
 а понятность графиков проверите по подписям.
 Откройте список дашбордов и проверьте:
 - «Бизнес-сюжеты» остался отдельным стендовым дашбордом;
 - ваш дашборд открывается без ошибок и содержит график от каждого из пяти
  датасетов;
 - подписи, единицы измерения и легенды читаются без обращения к SQL;
 - прямой трафик не исчез из графика UTM, а заявленная выручка не выдана за
  серверную;
 - пустой график ошибок нормален, если в таблицах брака сейчас нет строк.
 По готовому экрану запишите три коротких вывода за выбранный период:
 - какой рекламный канал дал больше покупок;
 - какая страница получила больше просмотров;
 - у какой категории устройств выше доля отказов.
 Для каждого вывода укажите период и число, на которое опираетесь. Проверьте
 его запросом к своей витрине в SQL Lab с тем же периодом и способом расчета.
 Сохраните запросы рядом с выводами. При равенстве значений назовите всех
 лидеров. Если данных нет, это тоже результат: подтвердите отсутствие строк
 запросом.
 Проверьте, можно ли найти эти ответы по одним подписям графиков. Если есть
 возможность, попросите другого человека прочитать экран без ваших пояснений.
 ## Результат работы
 - [ ] у вас есть пять датасетов по представлениям витрин заданий 1–5;
 - [ ] вы собрали свой дашборд, сохранив стендовые объекты без изменений;
 - [ ] на дашборде есть хотя бы один график от каждой витрины;
 - [ ] вы проверили, что графики и подписи понятны по вопросам из раздела выше;
 - [ ] вы записали три вывода и сверили числа с SQL; в отчете указаны периоды
      поведения посетителей и ошибок приема.
@@ -1,70 +0,0 @@
 # В DBeaver работает, в Superset нет
 Вы создадите представление, которое читается из DBeaver, но недоступно
 в Superset. Затем найдете причину и исправите ее.
 Факультатив доступен после [ступени 2](../2-1-superset-chart.md).
 Свой дашборд для опыта не нужен. Используйте готовую витрину стенда
 `dm.daily_traffic_v`.
 ## Подготовка
 В DBeaver подключитесь к первому узлу пользователем `etl`, как описано
 в разделе [«Выполнение SQL в DBeaver»](../README.md#выполнение-sql-в-dbeaver).
 Для опыта создайте отдельное представление:
 ```sql
 CREATE VIEW dm.bi_node_probe_v AS
 SELECT * FROM dm.daily_traffic_v;
 ```
 Запрос выполнится успешно. Теперь проверьте, откуда можно прочитать
 созданное представление. Начните с того же подключения:
 ```sql
 SELECT count() FROM dm.bi_node_probe_v;
 ```
 Повторите запрос в SQL Lab Superset, выбрав подключение `ClickHouse`.
 Сохраните текст ошибки.
 ## Поиск причины
 Выясните, к каким серверам обращаются DBeaver и Superset. Адреса подключения
 показывают настройки клиентов, а имя ответившего сервера можно спросить
 запросом `SELECT hostName()`.
 Проверьте наличие `dm.bi_node_probe_v` на обоих узлах. Для второго узла
 заведите подключение DBeaver с портом из
 [README](../../../README.md#подключиться-из-dbeaver). Запишите, где объект
 есть, и объясните, почему успешного создания в первом подключении оказалось
 недостаточно.
 Исправьте DDL так, чтобы представление появилось на обоих узлах. Подключение
 Superset должно остаться прежним. Сохраните исправленный DDL и повторите
 исходный запрос в обоих клиентах.
 Если застряли, прочитайте раздел «Устройство зоны» в
 [справочнике Superset](../../architecture/superset.md#устройство-зоны) и
 [описание распределенного DDL ClickHouse](https://clickhouse.com/docs/reference/statements/distributed-ddl).
 ## Проверка результата
 В обоих клиентах запрос к вашему представлению должен вернуть столько же
 строк, сколько `SELECT count() FROM dm.daily_traffic_v`. Сравнивайте результаты
 при завершенном прогоне конвейера, пока мир не продвигается.
 Объясните причину ошибки через три факта: куда пришел DDL, куда пришел
 запрос Superset и на каких узлах существовало представление.
 После опыта удалите только `dm.bi_node_probe_v` на обоих узлах. Не включайте
 его в постоянный DDL домашних витрин: это временный объект расследования.
 ## Результат работы
 - [ ] у вас сохранены успешный запрос из DBeaver и ошибка из SQL Lab;
 - [ ] вы можете объяснить, к каким серверам подключены клиенты, где было
      создано представление и почему Superset его не видел;
 - [ ] у вас есть исправленный DDL; оба клиента возвращают столько же строк,
      сколько исходная витрина;
 - [ ] после опыта вы удалили учебное представление с обоих узлов.
@@ -0,0 +1,121 @@
 # Задание 3: `dm.session_overview`
 **Чему учит:** агрегат хранит слагаемые, а не готовые средние и доли.
 Среднее по строкам витрины не складывается никогда, а уникальных нельзя
 складывать даже тогда, когда на сегодняшних данных сумма сходится.
 ## Роль витрины
 Дневной портрет визитов в разрезе устройств: сколько было сессий, какие они
 были длинные, сколько страниц смотрели и как часто доходили до покупки.
 Вопрос витрины — «как люди ходят по магазину с телефона и с настольного
 компьютера, и чем эти визиты отличаются».
 Сессия на стенде — расчетная сущность, ее уже нарезал слой DDS. Собирать
 визиты заново из событий не нужно и нельзя: это была бы вторая нарезка,
 которая тихо разойдется с первой.
 Витрина с таким именем была и на прошлом стенде, но зерно у нее сменилось,
 и сменилось не по вкусу. Там визитов как сущности не было, и витрина
 нарезала их сама, строкой на визит. Здесь визит — сущность слоя DDS, и
 витрина, повторяющая его зерно, оказалась бы обычным представлением по
 [правилу формы](../architecture/dm.md): копией сессий с другими именами
 колонок. Чтобы задание осталось про дневной агрегат, витрина поднялась на
 зерно выше — до дня и среза.
 ## Зерно и форма
 Зерно — **день сессии × категория устройства**. Источник —
 `dds.session_v`, у него зерно визита, значит зерно сменилось и витрина
 материализуется: `dm.session_overview_rep` / `_dist`, донор `_stage_rep` /
 `_stage_dist`, публичное `dm.session_overview_v`. Ключ партиции — день.
 Категория устройства взята из сессии как есть: у куки она постоянна, и слой
 DDS уже перевел код источника в слово. Словарь расшифровки шире, чем мир
 стенда: слов в нем четыре, а встречаются три — `desktop`, `mobile` и
 `tablet`. Строку под `tv` заводить незачем, она возникнет сама, если такие
 визиты появятся.
 ## Состав колонок
 | Колонка | Тип | Что это |
 |---|---|---|
 | `report_date` | `Date` | день сессии |
 | `device_category` | `LowCardinality(String)` | категория устройства |
 | `sessions` | `UInt64` | число визитов |
 | `visitors` | `UInt64` | число разных `client_id` |
 | `bounce_sessions` | `UInt64` | визиты ровно из одного события |
 | `purchase_sessions` | `UInt64` | визиты, в которых была хотя бы одна покупка |
 | `duration_seconds_total` | `UInt64` | суммарная длительность визитов |
 | `events_total` | `UInt64` | событий во всех визитах |
 | `pageviews` | `UInt64` | просмотров страниц |
 | `cart_adds` | `UInt64` | добавлений в корзину |
 | `purchases` | `UInt64` | покупок |
 | `_load_id` | `String` | запуск, собравший день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
 Средней длительности и доли отказов в витрине нет намеренно. Хранить
 `avg_duration_seconds` было бы удобнее ровно один раз — пока смотрят одну
 строку. Тот, кто захочет среднее по дню целиком, сложит средние по трем
 устройствам и получит неправду: средние не складываются, они взвешиваются.
 Пара «`duration_seconds_total` и `sessions`» дает верный ответ на любом
 срезе, а деление стоит потребителю один вызов. То же и с долей отказов:
 храним `bounce_sessions` и `sessions`, долю считает тот, кто спрашивает.
 С `visitors` история тоньше, и в ней главная ловушка задания. Складывать
 уникальных по строкам нельзя: один и тот же посетитель, попавший в две
 строки, будет посчитан дважды. Проверь на стенде — и увидишь, что сумма
 `visitors` по устройствам за день **сходится** с `dm.daily_traffic_v`.
 Это не отменяет правила, а показывает, откуда берется совпадение: в мире
 стенда устройство приписано куке на всю жизнь ([словарь
 понятий](../../CONTEXT.md), «Паспорт куки»), поэтому одна кука лежит ровно
 в одной строке дня, и пересекаться строкам не в чем.
 Совпадение это — свойство мира, а не свойство витрины. Появятся визиты
 одной куки с двух устройств — сумма поедет, и ни одна проверка об этом не
 скажет: отчет просто начнет тихо завышать аудиторию. Отсюда правило,
 которое стоит унести с задания: складывать уникальных нельзя даже там, где
 сегодня получается. Число посетителей дня спрашивают у
 `dm.daily_traffic_v`, где оно посчитано на своем зерне.
 ## Ритм пересборки
 Источник — сессии: день замерзает, как только прожит. Объем прогона тот же,
 что в задании 2, — хвост от первого несобранного прожитого дня; механика та
 же: донор и замена дневных партиций.
 ## Ключ шардирования
 Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
 шардам». Здесь у измерения всего три встречающихся значения, и распределены
 они неровно: планшеты — тонкая полоса, а телефоны и настольные машины держат
 основную массу. Прежде чем брать хеш от одного `device_category`, посчитай,
 сколько строк ляжет на каждый шард, и назови, чем тебя устраивает результат.
 ## Как проверить себя
 Деловой ключ — `device_category` внутри дня. Собери прямой агрегат из
 `dds.session_v` за день, соедини с `dm.session_overview_v` полным внешним
 соединением и посчитай строки, где ключа нет с одной из сторон или где
 расходится любой счетчик. Ноль — зеленый.
 Две проверки покрупнее ловят грубую ошибку сразу:
 - сумма `sessions` за день равна числу строк `dds.session_v` этого дня:
  ни один визит не потерян и ни один не задвоен;
 - сумма `events_total` за день равна сумме `events_total` по сессиям того
  же дня.
 Если суммы событий сходятся, а сумма сессий больше числа визитов — почти
 наверняка витрина собрана из событий, а не из сессий.
 ## Приемка
 - [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
      ключом цели;
 - [ ] `dm.session_overview_v` перечисляет колонки явно;
 - [ ] источник витрины — `dds.session_v`, своей нарезки визитов в ней нет;
 - [ ] средних и долей в физической таблице нет;
 - [ ] задача `session_overview` в `homework_check` зеленая;
 - [ ] задача витрины добавлена в `dm_transform`.
@@ -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;
 - [ ] создан отдельный дашборд, стендовые объекты не изменены;
 - [ ] каждая витрина представлена хотя бы одним графиком;
 - [ ] дашборд проверен глазами по разделу выше.
@@ -0,0 +1,114 @@
 # Задание 2: `dm.top_pages_daily`
 **Чему учит:** зерно сменилось — значит витрина материализуется, живет
 дневными партициями и встает в конвейер. Первая настоящая витрина: пять
 объектов, донор, замена партиции, задача в `dm_transform`.
 ## Роль витрины
 Популярность страниц по дням: сколько раз страницу открыли, сколько разных
 посетителей ее видели и что на ней делали кроме просмотра.
 Торговое событие садится на ту страницу, где случилось: корзина — на
 карточку товара, покупка — на страницу подтверждения заказа. Поэтому у
 карточки товара рядом стоят просмотры и корзины, и их отношение —
 конверсия карточки — главный вопрос к этой витрине: какие товары кладут в
 корзину, едва открыв, а какие смотрят и уходят.
 Воронки «просмотр → корзина → покупка» здесь нет и быть не может: корзина и
 покупка живут на разных страницах, и связать их шаги в одну цепочку на
 зерне страницы не из чего. Путь одного человека собирают из событий или из
 сессий, а витрина страниц отвечает про страницу.
 ## Зерно и форма
 Зерно — **день события × страница**. Источник — события, у него зерно
 события, значит зерно сменилось и витрина материализуется:
 `dm.top_pages_daily_rep` / `_dist`, донор `_stage_rep` / `_stage_dist`,
 публичное `dm.top_pages_daily_v`.
 Страница — это `page_path`, путь `url` без домена и параметров запроса;
 считается он здесь же, из колонки `url` источника. Полный адрес в зерно не
 берется: с параметрами запроса одна и та же страница рассыпалась бы на
 сотни строк, и витрина перестала бы отвечать на свой вопрос.
 Ключ партиции — день: он же единица пересборки.
 Источник — `dds.event_v`, публичный договор события. Витрина задания 1
 источником не служит: витрина слоя DM читает договор DDS, как и стендовые
 витрины, и не зависит от того, выполнена ли соседняя домашка.
 ## Состав колонок
 | Колонка | Тип | Что это |
 |---|---|---|
 | `report_date` | `Date` | день события |
 | `page_path` | `LowCardinality(String)` | путь страницы |
 | `pageviews` | `UInt64` | число событий `pageview` на странице |
 | `visitors` | `UInt64` | число разных `client_id` на странице |
 | `cart_adds` | `UInt64` | число событий `add_to_cart` на странице |
 | `purchases` | `UInt64` | число событий `purchase` на странице |
 | `_load_id` | `String` | запуск, собравший день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
 Счетчики условные: строку дают все три типа событий, а различает их
 `countIf`. Отфильтровать источник по `event_type = 'pageview'`, как
 подсказывает имя витрины, — значит получить витрину из одних просмотров:
 страницы останутся на месте, а `cart_adds` и `purchases` у всех строк
 обнулятся. Ошибка тихая: витрина выглядит собранной, и главный ее вопрос —
 конверсия карточки — молча отвечает «ноль везде».
 ## Ритм пересборки
 Источник — события: день замерзает сразу, как только прожит. Значит
 пересобирать нужно только то, что еще не собрано: хвост дней, которых в
 витрине нет, — от первого несобранного прожитого дня до последнего
 прожитого. Готовые дни трогать незачем, а вот дыру, оставленную частичным
 отказом, объем прогона обязан подобрать: ищи не последний собранный день, а
 первый несобранный.
 Механика — сборка отрезка в донор одной вставкой и замена дневных партиций
 по одной, как у `revenue_daily`.
 ## Ключ шардирования
 Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
 шардам». Подумай, чем эта витрина отличается от `revenue_daily`: там кроме
 дня было одно измерение из шести близких по объему значений, здесь —
 страницы, которых много и которые по популярности очень неровные.
 ## Как проверить себя
 Деловой ключ — `page_path` внутри дня. Собери прямой агрегат из
 `dds.event_v` за день, соедини с `dm.top_pages_daily_v` полным внешним
 соединением по ключу и посчитай строки, где ключа нет с одной из сторон или
 где расходится любой из четырех счетчиков. Ноль — зеленый.
 Две проверки попроще, ими удобно ловить грубую ошибку до полного
 соединения:
 - сумма `pageviews` за день равна числу событий `pageview` этого дня в
  `dds.event_v`;
 - сумма `purchases` за день равна числу событий `purchase` этого дня.
 Проверки ловят разное. Фильтр `WHERE event_type = 'pageview'` первая из них
 пропускает: отбор строк по типу не меняет счет событий того же типа.
 Расхождение покажет только вторая — вместе с `cart_adds` обнулятся и
 `purchases`. Проверку выбирают по тому, умеет ли она покраснеть на твоей
 ошибке, а не по тому, как быстро она пишется: [проверка, которая не умеет
 краснеть, бесполезна](../architecture/testing.md).
 `visitors` складывать по строкам нельзя: один посетитель ходит по разным
 страницам и в сумме посчитается несколько раз. Число посетителей дня
 спрашивают у `dm.daily_traffic_v`, а не у этой витрины.
 ## Приемка
 - [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
      ключом цели;
 - [ ] `dm.top_pages_daily_v` перечисляет колонки явно, включая `_load_id` и
      `_load_ts`;
 - [ ] объем прогона выводится из состояния витрины, а не задается руками;
 - [ ] задача `top_pages_daily` в `homework_check` зеленая;
 - [ ] задача витрины добавлена в `dm_transform`, повторный прогон конвейера
      результат не меняет.
@@ -0,0 +1,150 @@
 # Задание 5: `dm.utm_effectiveness`
 **Чему учит:** приставка `declared_` в имени колонки — предупреждение, а не
 украшение. Она говорит: это заявка клиента, а не деньги отчетности. Урок
 здесь дает конфликт: суммы не сойдутся, и раскапывать почему предстоит
 самому.
 Правило стенда: **поведение и атрибуцию считаем по трекеру, деньги — по
 бэкенду**. Эта витрина — единственное разрешенное исключение: атрибуции по
 UTM у бэкенда нет, метки живут только в кликстриме. Раз считать иначе
 нечем, клиентская сумма берется, но называется своим именем.
 ## Роль витрины
 Эффективность рекламных каналов по дням: сколько трафика привел канал,
 сколько корзин и покупок в нем случилось и на какую сумму эти покупки, по
 словам клиента.
 ## Атрибуция: по событию, а не по визиту
 Метки едут на каждом событии, и витрина группирует события по их
 собственным меткам. Модели «первое касание» или «последнее касание» здесь
 нет: их построение — отдельная тема, а это витрина трафика по меткам.
 `dds.session_v` при этом несет UTM первого события визита, и ответ «какой
 канал привел» из сессии и из этой витрины будет разным. Это не
 ошибка ни одной из сторон — это два разных вопроса, и в отчете их надо
 различать.
 ## Прямой трафик из витрины не выбрасывается
 Соблазн отфильтровать строки без меток велик: витрина же про рекламу.
 Отфильтровать нельзя по двум причинам. Первая деловая: прямой трафик —
 обычно самый крупный «канал» магазина, и отчет, где его нет, врет о доле
 рекламы. Вторая техническая: как только часть событий выпала, итог витрины
 перестал сходиться с итогом источника, и проверить сборку стало нечем.
 Пустые метки остаются пустыми строками, как в источнике. Своего слова для
 «прямого захода» витрина не изобретает: чем меньше выдуманных значений, тем
 меньше расшифровывать читателю.
 ## Зерно и форма
 Зерно — **день события × `utm_source` × `utm_medium` × `utm_campaign`**.
 Зерно источника — событие, значит витрина материализуется:
 `dm.utm_effectiveness_rep` / `_dist`, донор `_stage_rep` / `_stage_dist`,
 публичное `dm.utm_effectiveness_v`. Ключ партиции — день.
 Источник — `dds.event_v`, публичный договор события: витрина слоя DM читает
 договор DDS, а не соседнюю витрину.
 ## Состав колонок
 | Колонка | Тип | Что это |
 |---|---|---|
 | `report_date` | `Date` | день события |
 | `utm_source` | `LowCardinality(String)` | источник кампании |
 | `utm_medium` | `LowCardinality(String)` | канал кампании |
 | `utm_campaign` | `String` | имя кампании |
 | `visitors` | `UInt64` | число разных `client_id` |
 | `pageviews` | `UInt64` | просмотров страниц |
 | `add_to_carts` | `UInt64` | добавлений в корзину |
 | `purchases` | `UInt64` | покупок |
 | `declared_revenue` | `Decimal(18, 2)` | выручка покупок глазами клиента |
 | `_load_id` | `String` | запуск, собравший день |
 | `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
 `declared_revenue` складывает `purchase_revenue[1]` событий `purchase`.
 Индекс не описка: блок `purchase*` едет параллельными массивами, и у события
 покупки в них ровно один элемент — контракт источника обещает один номер
 заказа и одну объявленную сумму на событие. Тем же индексом берет свою
 сторону стендовая сверка `purchase_vs_orders`.
 Приводить тип не нужно: в договоре `purchase_revenue` уже
 `Array(Decimal(18, 2))`. `Float64` эта сумма была только в выгрузке
 источника, и ODS перевел ее в точные деньги на приеме — сложение Decimal
 точное, и где стоит `CAST`, до или после `sum`, на результат не влияет.
 Витрина просто хранит то, что сложила, в `Decimal(18, 2)`.
 `utm_campaign` оставлена обычной строкой: имен кампаний со временем
 становится много, и словарь `LowCardinality` на растущем множестве
 перестает окупаться.
 ## Ритм пересборки
 Источник — события: день замерзает сразу. Объем прогона и механика те же,
 что в задании 2: хвост несобранных дней, донор, замена дневных партиций.
 ## Ключ шардирования
 Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
 шардам». Зерно здесь составное, из трех колонок, и решение «взять хеш от
 одной из них» надо защищать отдельно: назови, какая доля строк придется на
 самое частое значение выбранной колонки.
 ## Конфликт, ради которого витрина и написана
 Собери за один и тот же день две суммы: `sum(declared_revenue)` из своей
 витрины и `sum(revenue)` из `dm.revenue_daily_v`. Они не сойдутся, и это
 верное поведение обеих витрин.
 Базы у двух сумм при этом сравнимые: `revenue_daily` складывает цену позиций
 на количество и ни скидки, ни доставки в себя не берет — ровно то, что видит
 клиент. Значит все расхождение до копейки объясняется тем, что случилось с
 заказом, а не тем, как считали деньги. Ищи ответы среди таких причин:
 - отмененный заказ из кликстрима никуда не девается: событие покупки
  случилось, а `revenue_daily` считает только оплаченные;
 - событие покупки может потеряться по дороге, а заказ при этом доехать —
  и наоборот, событие приехать дважды;
 - клиент назвал сумму, отличную от серверной суммы позиций: генератор
  делает это намеренно у одного-двух заказов из ста.
 Как эти же расхождения выглядят на зерне заказа, показывает стендовая
 витрина `dm.purchase_vs_orders_v` с ее классами расхождений: это готовый
 ответ на вопрос «а сколько именно и из-за чего». Запиши свой вывод —
 в двух-трех фразах, своими словами.
 Проверять сходимость этих двух сумм не нужно и нельзя: они и не должны
 сходиться.
 ## Как проверить себя
 Деловой ключ — тройка `utm_source`, `utm_medium`, `utm_campaign` внутри
 дня. Собери прямой агрегат из `dds.event_v` за день, соедини с
 `dm.utm_effectiveness_v` полным внешним соединением и посчитай строки, где
 ключа нет с одной из сторон или где расходится любая из пяти величин. Ноль —
 зеленый.
 Две проверки покрупнее ловят самые частые ошибки:
 - сумма `pageviews`, `add_to_carts` и `purchases` за день равна числу
  событий соответствующего типа в `dds.event_v` за тот же день;
 - сумма `declared_revenue` за день равна сумме `purchase_revenue[1]` по всем
  событиям `purchase` этого дня.
 Обе не сойдутся, если прямой трафик отфильтрован, и разойдутся ровно на его
 долю — по этому следу отфильтрованные строки и находят. `visitors`, как и в
 задании 3, по строкам не складывается: один посетитель приходит по разным
 меткам.
 ## Приемка
 - [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
      ключом цели;
 - [ ] строки без UTM-меток в витрине остались;
 - [ ] `declared_revenue` хранится в `Decimal(18, 2)`;
 - [ ] расхождение с `dm.revenue_daily_v` объяснено письменно;
 - [ ] задача `utm_effectiveness` в `homework_check` зеленая;
 - [ ] задача витрины добавлена в `dm_transform`.
@@ -116,7 +116,7 @@
 **17. Свой дашборд в Superset (готовая необязательная лаба).**  
 Урок: пользовательские объекты BI хранятся отдельно от стендовых и переживают перезапуск. Стендовые объекты при импорте перезаписываются.  
-Материал: `docs/labs/optional/superset-dashboard.md`, `docs/architecture/superset.md`.\
+Материал: `docs/labs/superset-dashboard.md`, `docs/architecture/superset.md`.  
 Форма: построить свое.  
 Проверка: глазами — счетного инварианта у раскладки панелей нет.
@@ -276,4 +276,4 @@
 STG и прием событий нельзя отдавать в форме «удали и перепиши»: код там служит несущей частью стенда. Для этих участков подходят расследования и форма «собери рядом».
-У всех счетных проверок остается общая дыра — раскладка по шардам. Поэтому пересчет ключа по `hostName()` должен входить в ТЗ каждого вычитания отдельной строкой.
+У всех счетных проверок остается общая дыра — раскладка по шардам. Поэтому пересчет ключа по `hostName()` должен входить в ТЗ каждого вычитания отдельной строкой.
@@ -40,24 +40,6 @@
 - *расследование* — данные уже лежат на стенде или стенд намеренно ломается, а
  менти ищет причину и объясняет ее.
 ### Как писать задания
 Пишите для учащегося: объясняйте, чему он научится, зачем нужны действия
 и как понять результат. Историю разработки оставляйте за пределами задания.
 Начинайте задание коротким описанием предстоящей работы. Заголовки должны
 называть содержание разделов: «Подготовка», «Создание витрины», «Проверка
 результата». Шаблонные вопросы «Чему учит» и «Что сделать» не нужны.
 Раздел проверки описывает действия для проверки и поиска ошибок.
 Раздел результата перечисляет итог работы и то, что учащийся теперь может
 объяснить. Если проверка уже встроена в шаги упражнения, повторять ее
 отдельным разделом не нужно.
 Структуру выбирайте по содержанию. Образцы — задания
 про [дашборд Superset](../labs/optional/superset-dashboard.md) и
 [расследование подключения](../labs/optional/superset-missing-object.md).
 ## 3. Основная программа — семь ступеней
 ### Ступень 1. Построй пять витрин слоя DM
@@ -82,7 +64,7 @@
 ступени предстоит написать при реализации программы. Полный собственный дашборд
 остается факультативом в разделе «Superset и BI».
-### Ступень 3. Нарежьте сессии сами
+### Ступень 3. Нарежь сессии сам
 До того как открыть стендовый SQL нарезки сессий в DDS, менти самостоятельно
 делит события на визиты. Сначала он сравнивает число своих сессий с эталоном
@@ -93,7 +75,7 @@
 Форма — построить свое по ТЗ и провести расследование. Обратная связь состоит
 из счетной сверки с `VisitID` и ручного сопоставления границ.
-### Ступень 4. Перепишите нарезку стенда
+### Ступень 4. Перепиши нарезку стенда
 Менти удаляет и заново пишет SQL нарезки сессий DDS: расчет объема, пересборку
 и замену. Урок — изменить расчетную сущность внутри готового конвейера и
@@ -104,7 +86,7 @@
 Форма — вычитание. Обратную связь дают `dq_check` и поштучная сверка,
 построенная на третьей ступени.
-### Ступень 5. Научите проверки замечать ошибки в заказах
+### Ступень 5. Сначала сторож, потом ломай: заказы
 Сначала менти строит две недостающие DQ-проверки. Первая утверждает равенство
 «цена × количество = items_total». Вторая сверяет слой с источником по дням. Их
@@ -153,106 +135,47 @@
 ## 4. Факультативы — пять разделов
-Ниже перечислены сюжеты, их уроки и принятые решения по форме заданий. Исходный
+Ниже перечислены только названия сюжетов и их уроки. Материал, формы и способы
-материал и способы проверки — в
+проверки остаются в [инвентаризации](../research/2026-08-31-labs-inventory.md).
 [инвентаризации](../research/2026-08-31-labs-inventory.md).
 ### Почему выручка не сходится
-Этот раздел рекомендован первым из факультативов и открывается после ступени
+Этот раздел рекомендован первым из факультативов. Он открывается после ступени
-1 основной программы. Шесть сюжетов собраны в четыре лабораторные: три
+1 основной программы: материал живет на стенде с этапа 6.
 расследования готовых данных и одно наблюдение во времени. Опоздания,
 изменение выручки и история отмен используют одну историю заказов, поэтому
 для них выбрана общая работа вместо трех отдельных.
-Результат расследования — запрос сверки и инженерное решение, подтвержденное
+- **Почему трекер недосчитывает покупки (#186).** Разрыв воронки подтверждений
-данными: выбор источника, ключа, полей для точного расчета или правила
+  показывает потерянные события и границу доверия к двум источникам.
-пересчета и хранения истории. Объяснение суммы служит проверкой решения.
+- **Почему повтор покупки завышает выручку (#187).** Движок убирает технический
-Вариант закончить работы только объяснением показателей отклонен: он
+  дубль строки, а повтор одной покупки приходится находить по деловому ключу.
-смещал акцент в анализ отчетов. Постройка новых DAG и подключение проверок
+- **Какая позиция объясняет разницу в сумме.** Расхождение суммы нужно
-к конвейеру оставлены основной программе, чтобы факультативы не повторяли
+  разложить до конкретной вычеркнутой позиции и объяснить до копейки.
-ее задания.
+- **Был ли отмененный заказ оплачен.** Текущее состояние не заменяет историю, а
-
+  некоторые различия после истечения срока хранения сырых данных уже не
- **[Куда пропали покупки](../labs/optional/missing-purchases.md) (#186).**
+  восстановить.
-  Сверка по номерам заказов обосновывает источник витрины и условие
+- **Когда отчет за день можно считать окончательным (#188).** Отчет за день
-  окончательной проверки полноты. Счетчики событий помогают обнаружить
+  становится окончательным лишь после того, как источник больше не может
-  расхождение, но не устанавливают место потери.
+  изменить этот день.
- **[Почему повтор покупки завышает выручку](../labs/optional/duplicate-purchases.md) (#187).**
+- **Почему выручка за день еще меняется.** Внутри окна изменяемости выручка
-  Учащийся собирает расчет с одной строкой на заказ, проверяет ключ и полноту
+  движется, а после закрытия дня фиксируется.
  набора номеров, отличает его зерно от зерна исходных событий.
 - **[Какая позиция объясняет разницу в сумме](../labs/optional/order-amount-difference.md).**
  Сверка позиций обосновывает выбор исходных полей и типа денег, отделяет
  ошибку собственного разбора от различия данных события и заказа.
 - **[Почему вчерашняя выручка меняется сегодня](../labs/optional/revenue-over-time.md) (#188).**
  Наблюдение опозданий и смены статусов обосновывает правило пересчета при
  ежедневной загрузке без пропусков. Учащийся определяет момент закрытия дня
  и требования к истории для воспроизведения расчета и проверки факта оплаты.
 В четвертой лабораторной выбрано собственное наблюдение: учащийся продвигает
 мир по одному дню через Airflow и сохраняет результаты после обновления витрин
 в две локальные таблицы ClickHouse под `student`: состояния заказов и итоги
 наблюдений. Сравнение выполняется SQL-запросами в том же подключении DBeaver.
 Учащийся может писать только в `default`; источники доступны ему на чтение.
 Отдельная строка итогов фиксирует и наблюдение без заказов. Экспорт в CSV
 отклонен как основной способ: он требовал неописанного перехода к другому
 инструменту или обратному импорту файлов.
 Готовые слепки и сочетание готового примера с собственным наблюдением
 отклонены: нужную историю можно получить на стенде и самому увидеть,
 как новые данные меняют уже рассчитанный отчет.
 День считается закрытым после получения и обработки последнего слепка
 семидневного окна изменяемости; этот слепок доставляется следующим модельным
 днем. Одного совпадения сумм в соседних наблюдениях для такого вывода
 недостаточно. История отмен тоже имеет границу: оплата и отмена между двумя
 дневными слепками могут остаться невидимыми. Отсутствие наблюдаемой оплаты
 не доказывает, что оплаты не было.
 ### Тонкий анализ данных
 Открывается после ступени 1 основной программы.
- **[Как новые заказы меняют отчет о посетителях](../labs/optional/identity-over-time.md) (#145).**
+- **Что мы знали о пользователе в тот день (#145).** Текущее знание и знание на
-  Учащийся собирает связи с подтверждающими покупками и сохраняет три
+  дату дают разные отчеты; сведения из будущего меняют прошлое.
  ежедневных наблюдения. На одном наборе прежних сессий сравнивает расчет
  с прежними и новыми связями, выбирает историю для воспроизведения расчета.
 - **Добавь названия регионов в отчет (#143).** Менти собирает свой словарь по
  образцу каталога и обогащает отчет через `dictGet`.
 Работа о связях продолжается в инженерном разделе лабораторной про
 инкрементальный `daily_traffic`. В обеих учащийся продвигает мир через
 `world_next_day` и `etl_pipeline`, сохраняет наблюдения под `student` в
 свои локальные таблицы `default` и сравнивает их SQL-запросами.
 Время первой подтверждающей покупки и время обнаружения связи разделены.
 Минимум времени `purchase` не принят за границу появления новых связей:
 заказ может поступить позже события. Нужные изменения определяются по
 разности сохраненных наборов пар. Ежедневное наблюдение ограничивает момент
 появления связи интервалом; для пар начального наблюдения более ранняя
 история неизвестна. История сессий в этом опыте растет без исправлений
 прошлых дней, а связи не отзываются — поэтому сохраненных наборов связей
 достаточно для сравнения расчетов на прежних сессиях.
 ### Superset и BI
 Открывается после ступени 2 основной программы.
- **[Свой дашборд](../labs/optional/superset-dashboard.md).** Менти использует
+- **Свой дашборд.** Готовая лаба
-  результат ступени 2, собирает отчет из пяти своих витрин и подтверждает
+  [`docs/labs/superset-dashboard.md`](../labs/superset-dashboard.md) учит
-  выводы запросами. Пользовательские объекты остаются отдельно от стендовых.
+  хранить пользовательские объекты отдельно от стендовых.
- **[В DBeaver работает, в Superset нет](../labs/optional/superset-missing-object.md).**
+- **Почему дашборд не видит объект на второй ноде.** Забытый `ON CLUSTER` может
-  Менти создает отдельное представление на первой ноде и расследует ошибку
+  остаться незаметным до тех пор, пока дашборд не обратится ко второй ноде.
  чтения из Superset, подключенного ко второй. Опыт заканчивается объяснением,
  исправлением DDL и удалением учебного объекта.
 Задания самостоятельны: расследование использует готовую витрину стенда.
 Отсутствие объекта проверяется в SQL Lab, поскольку создание физического
 датасета может остановиться раньше, чем появится график. Чтение только одного
 шарда остается материалом инженерного раздела: это отдельная причина
 неполного результата, которую добавление `ON CLUSTER` само по себе не устраняет.
 Технический опыт проверен 2026-09-13 на ClickHouse 26.3.17.56: локальное
 представление недоступно пользователю `bi` на второй ноде; после создания
 на кластере обе ноды возвращают тот же счет, что исходная витрина.
 ### Инженерия стенда
@@ -287,28 +210,9 @@
 - **Что будет, если день заменился не на всех шардах.** Замена дня завершается
  отдельно на каждом шарде, поэтому целостность результата подтверждает
  отдельная сверка.
- **[Как обновлять витрину без полной пересборки](../labs/optional/incremental-daily-traffic.md)
+- **Как обновлять витрину без полной пересборки (#149) — повышенная
-  (#149) — повышенная сложность.** Продолжение работы о связях пользователей:
+  сложность.** Экономия на пересчете требует хранить историю изменений, которую
-  учащийся строит свою витрину, выбирает затронутые дни по новым сессиям
+  полная пересборка стирает.
  и связям, сверяет весь результат с `dm.daily_traffic_v`. Журнал успешных
  загрузок позволяет повторить опыт с частично записанным результатом.
 Инкрементальная работа начинается с полной загрузки текущего состояния,
 затем охватывает два новых модельных дня. Обновление собственной витрины
 выполнено вставкой версий в `ReplacingMergeTree`, чтение — с `FINAL`.
 Это оставляет права `student` прежними и не требует менять конвейер стенда.
 Версия — дата наблюдения; ключ — день отчета. История связей хранится
 отдельно от версий витрины. Выбор опирается на
 [договор движка](https://clickhouse.com/docs/engines/table-engines/mergetree-family/replacingmergetree):
 максимальная версия по ключу и удаление прежних версий при слияниях.
 DDL, обновление вставкой и чтение с `FINAL` проверены под `student`
 на ClickHouse 26.3.17.56.
 Полный пересчет остается эталоном, а экономия оценивается числом выбранных
 дней. На малом объеме ускорение не обещано. Поиск связей продолжает читать
 историю источников целиком; инкрементальным становится расчет дневной витрины.
 Полная замена стендового ETL отклонена: для учебного сравнения достаточно
 своей витрины и журнала рядом с работающим конвейером.
 ### Что делать, когда стенд сломался
@@ -1,95 +1,98 @@
-# Генератор событий и заказов
+# Генератор кликстрима
-Генератор создает данные двух источников интернет-магазина. Счетчик сайта
+Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по
-отправляет в топик Kafka `hits` события: просмотр страницы, добавление товара
+образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения —
-в корзину и покупку. Серверная часть магазина выгружает в `orders` дневной
+спека [«Генератор (этап 2)»](../docs/specs/2026-08-01-generator.md).
 слепок — состояние заказов, оформленных за последние семь модельных дней.
 Оба источника работают; хранилище принимает события непрерывно, заказы —
 по команде Airflow.
-Событие описывает отдельное действие посетителя. Заказ после оформления
+События уже есть и уже уезжают: день-функция отдаёт по паре (зерно, D)
-может измениться, например перейти в статус `paid` или `cancelled`.
+упорядоченный поток трёх видов — просмотр страницы, корзина, покупка, —
-Поэтому один `order_id` встречается в нескольких слепках. Часть заказов
+канонический сериализатор превращает его в JSON, а проигрыватель гонит в файл
-впервые появляется с задержкой в один или два дня; конец семидневного окна
+или в Kafka. Клиентская сторона на этом целая. Второй источник строится:
-от этого не сдвигается. Правила изменений и задержек — в
+день отдаёт и заказы бэкенда — проекцию своих покупок с деньгами магазина, —
-[описании судьбы заказа](../docs/architecture/orders/fate.md).
+а судьба заказа и отправка слепка идут следующими тикетами.
 Слепок снимается на конец модельного дня и отправляется на следующий день.
 Команда `snapshot --day 1` отправляет слепок дня 0, а `snapshot --day 0`
 не отправляет ничего: до начала модели заказов нет. События и слепки
 отправляются отдельными запусками генератора.
 ## Как это работает
-Зерно генерации задает случайные выборы: какие посетители придут,
+Корневое зерно ветвится на подпотоки, из них складываются когорты, аудитория
-какие страницы откроют и что купят. При неизменных коде, каталоге
+дня, визиты, строки событий и заказы. План поднимает состав мира по требованию,
-и настройках одинаковые зерно и номер дня дают одинаковые данные.
+а день-функция проживает один день без накопленного состояния. Код этой
-День можно рассчитать без генерации всех предыдущих дней.
+цепочки, ее схема и запуск D0 собраны в
-
+[путеводителе](../docs/architecture/generator/README.md).
 Сначала рассчитываются посещения и покупки. Из покупки получаются событие
 `purchase` со стороны сайта и заказ со стороны магазина. Номер связывает
 их: `purchaseID` в событии соответствует `order_id` заказа. Суммы могут
 различаться: магазин учитывает скидку, доставку и удаленные позиции.
 Деньги генератор считает целыми копейками; в JSON заказа это строки
 в рублях с двумя знаками после точки, например `"1289.99"`.
 Готовые записи превращаются в JSON и отправляются в файл или Kafka:
 одна запись занимает одну строку файла или одно сообщение. Событие содержит
 47 полей по [описанию выгрузки](../docs/formats/clickstream-event.md),
 запись заказа — поля [формата слепка](../docs/architecture/orders/snapshot.md#запись-на-проводе).
 Подробное устройство генератора разобрано в
 [техническом справочнике](../docs/architecture/generator/README.md).
 ## Что где лежит
-Все перечисленные модули находятся в `src/clickstream_generator/`.
+- `src/clickstream_generator/world.py` — конфигурация мира: все его числа
-
+  одним местом. Правка любого — смена мира; крутить их и предлагается.
-| Модули | Назначение |
+- `src/clickstream_generator/seeds.py` — иерархия зёрен: кто из какого
-|---|---|
+  подпотока берёт случайность. На ней держится весь детерминизм.
-| `world.py`, `seeds.py`, `plan.py` | Настройки мира, случайные выборы и план посещений |
+- `src/clickstream_generator/plan.py` — план состава: кто есть в мире в
-| `reference.py`, `catalog.py` | Устройства, города, источники трафика и каталог товаров |
+  день D. Когорты, приток, двухкуковые пары, паспорта кук, человек за кукой
-| `day.py`, `commerce.py` | Визиты, события сайта и покупки |
+  и счётчики — до генерации событий.
-| `orders.py` | Состояние заказов на дату слепка, изменения и задержки |
+- `src/clickstream_generator/weights.py` — выбор по целым весам: один приём
-| `serialize.py`, `player.py`, `sinks.py` | Запись JSON и отправка в файл или Kafka |
+  на весь генератор, чтобы дисциплина целочисленной случайности не жила
-| `cli.py` | Команды и параметры запуска |
+  копиями.
-| `schema.py`, `schema_doc.py` | Описания колонок события и сборка документа выгрузки |
+- `src/clickstream_generator/reference.py` — справочники: устройства,
-| `inventory.py` | Сборка паспорта мира с контрольными суммами и счетчиками |
+  города, источники трафика, карта сайта. Таблицы-литералы: доля живёт в
-
+  строке, которой принадлежит.
-Тесты в `tests/` проверяют формат, правила модели и повторяемость данных.
+- `src/clickstream_generator/catalog.py` — каталог товаров из
-Описание выгрузки и [паспорт мира](../data/world-inventory.json) собираются
+  `data/catalog/products.csv`, общего у генератора и словаря ClickHouse.
-из кода; вручную их не редактируют.
+- `src/clickstream_generator/day.py` — день-функция: визиты, страницы,
  атрибуция, устройство и гео. Там же правила резки визитов и шов, на
  который садятся торговые события; прожитый день отдаёт обе половины —
  поток событий и заказы.
 - `src/clickstream_generator/commerce.py` — торговые события: что легло в
  корзину, что из этого куплено, деньги, номера заказов и сырой `ecommerce`.
  Своя случайность, поэтому правка торговли трафик не двигает.
 - `src/clickstream_generator/orders.py` — заказы бэкенда: вторая проекция
  покупки. Личность покупателя и деньги магазина — скидка по промокоду,
  доставка, итог; своя случайность, ветвящаяся по дню рождения заказа.
 - `src/clickstream_generator/ids.py` — номера событий: неповторяющиеся и
  ниже 2^53. Обещание одно на обе половины дня, поэтому и живёт отдельно.
 - `src/clickstream_generator/serialize.py` — канонический сериализатор:
  единственное место, где событие целиком превращается в JSON. Порядок ключей,
  все 47 колонок всегда и форма на проводе — ISO-8601.
 - `src/clickstream_generator/sinks.py` — приёмники: файл (одно событие — одна
  строка) и Kafka (одно событие — одно сообщение). Про содержимое они не
  знают; там же довод, почему у сообщения нет ключа.
 - `src/clickstream_generator/player.py` — проигрыватель: гонит дни в приёмник
  пачкой или с темпом живого дня. Состояния не хранит.
 - `src/clickstream_generator/cli.py` — интерфейс запуска: параметры
  аргументами или окружением, логи в стандартный вывод, итог кодом возврата.
 - `src/clickstream_generator/schema.py` — контракт схемы: чистые данные о
  колонках выгрузки. Собственность генератора; из него выводятся сам
  генератор, его валидация и описание выгрузки в доках.
 - `src/clickstream_generator/schema_doc.py` — сборка «описания выгрузки»
  ([`docs/formats/clickstream-event.md`](../docs/formats/clickstream-event.md))
  из контракта. Документ руками не правят — пересобирают.
 - `src/clickstream_generator/inventory.py` — сборка паспорта мира
  ([`data/world-inventory.json`](../data/world-inventory.json)): шапка паспорта
  и хеши восьми дней, которыми наполняется стенд, плюс счётчики классов
  расхождений по заказам для дней с закрытым окном. Руками не правят —
  пересобирают целью `make inventory`.
 - `tests/` — инварианты контракта, свежесть описания и обещания мира:
  чистота от зерна, приток, гарантия двухкуковых пар, форма суточной волны
  и сборка визитов по задокументированным правилам. Там же побайтовое
  обещание, доведённое до диска: два прогона дня в файл дают тот же файл, а
  строк в нём ровно столько, сколько событий.
 ## Команды
-Для запуска из каталога `generator/` используйте
+Проиграть день — раздел [«Как запустить
-`uv run python -m clickstream_generator <команда>`. Справку можно открыть
+генератор»](../docs/architecture/world.md#как-запустить-генератор)
-через `--help`, в том числе после имени команды.
+справочника мира и `--help`.
-| Команда | Что отправляет | Особые параметры |
+Из этого каталога — цели генератора живут здесь, а не в корне:
 |---|---|---|
 | `batch` | События дня без пауз | `--limit N` ограничивает число событий за весь запуск |
 | `live` | События постепенно, с ускорением | `--speed X`, по умолчанию 60: сутки занимают около 24 минут |
 | `snapshot` | Слепок заказов предыдущего дня | `--day D` задает день отправки |
 Для всех команд нужны номер дня `--day` и приемник: `--file` либо
 `--brokers` вместе с `--topic`. Общие параметры `--seed` и `--days`
 задают зерно и число последовательных дней. Параметры можно передать
 и через окружение; имена и примеры собраны в
 [справочнике запуска](../docs/architecture/world.md#как-запустить-генератор).
 Прямой запуск генератора не продвигает сохраненную позицию времени стенда —
 ей управляют [даги модельного времени](../docs/handbook/airflow-dags.md#генерация-модельных-дней).
 Из каталога `generator/` доступны:
 - `make test` — тесты генератора;
- `make lint` — проверка кода и форматирования через ruff;
+- `make lint` — ruff: проверка и формат;
- `make typecheck` — проверка типов через ty;
+- `make typecheck` — ty: проверка типов;
- `make demo` — показать стадии расчета первого дня, D0;
+- `make demo` — пройти стадии канонического D0 на одном экране;
 - `make docs` — пересобрать описание выгрузки;
 - `make inventory` — пересобрать паспорт мира.
-В корне `make lint` проверяет даги, код Superset и сборку карты архитектуры.
+В корне репозитория `make lint` тоже есть, но он про код стенда — даги и
-Корневые `make generate-batch` и `make generate-live` запускают события
+Superset. Одноимённые цели за разными дверями охватывают разное:
-через контейнер генератора. Состав проверок — в
+[карта проверок](../docs/architecture/testing.md).
-[карте проверок](../docs/architecture/testing.md).
+
-Python и зависимости запускаются через `uv`; версии закреплены в `uv.lock`.
+Python и зависимости — через `uv`, версии закреплены в `uv.lock`: на этом
 держится обещание побайтовой воспроизводимости (спека, раздел 2).
@@ -420,7 +420,7 @@ COLUMNS: tuple[Column, ...] = (
        numpy_dtype="int64",
        normalized_name="product_price",
        group=ColumnGroup.ECOMMERCE,
-        comment="цена за штуку, округленная до целых рублей",
+        comment="цена за штуку целым числом: деньги генератор считает целыми",
    ),
    Column(
        name="productQuantity",
@@ -61,11 +61,6 @@
                <query>GRANT SELECT ON system.settings</query>
            </grants>
        </analyst_reader>
        <student_writer>
            <grants>
                <query>GRANT SELECT, INSERT, CREATE TABLE, DROP TABLE ON default.*</query>
            </grants>
        </student_writer>
        <monitoring_reader>
            <grants>
                <query>GRANT SELECT ON stg.*</query>
@@ -118,14 +113,6 @@
                <query>GRANT analyst_reader</query>
            </grants>
        </analyst>
        <student>
            <password from_env="CLICKHOUSE_STUDENT_PASSWORD"/>
            <quota>default</quota>
            <grants>
                <query>GRANT analyst_reader</query>
                <query>GRANT student_writer</query>
            </grants>
        </student>
        <grafana>
            <password from_env="CLICKHOUSE_GRAFANA_PASSWORD"/>
            <quota>default</quota>
@@ -11,7 +11,7 @@
  "panels": [
    {
      "type": "timeseries",
-      "title": "Процессор: сколько ядер использует узел",
+      "title": "Процессор: сколько ядер занимает нода",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -51,7 +51,7 @@
    },
    {
      "type": "timeseries",
-      "title": "Память: использование и лимит узла",
+      "title": "Память: сколько нода занимает и сколько ей отведено",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -114,7 +114,7 @@
    },
    {
      "type": "timeseries",
-      "title": "Диски: скорость чтения и записи узла",
+      "title": "Диски: сколько нода читает и пишет",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -154,7 +154,7 @@
    },
    {
      "type": "table",
-      "title": "Части таблиц: количество и среднее число строк в части",
+      "title": "Части: сколько их у таблицы и по сколько строк в каждой",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -199,7 +199,7 @@
    },
    {
      "type": "timeseries",
-      "title": "Слияния: число объединенных частей",
+      "title": "Слияния: сколько частей они съедают",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -280,12 +280,11 @@
          "min": 0
        },
        "overrides": []
-      },
+      }
      "description": "Узлы дерева Keeper (znode) — записи со служебными данными координации ClickHouse."
    },
    {
      "type": "table",
-      "title": "Распределенный DDL: результаты команд на узлах кластера",
+      "title": "Распределённый DDL: что прошло по кластеру и чем кончилось",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -11,7 +11,7 @@
  "panels": [
    {
      "type": "stat",
-      "title": "Свежесть: время с последней загрузки в ODS",
+      "title": "Свежесть: сколько прошло с последней доехавшей строки",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -48,7 +48,7 @@
    },
    {
      "type": "table",
-      "title": "Брак: доля строк с ошибками разбора",
+      "title": "Брак: сколько приехавшего не разобралось",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -72,28 +72,11 @@
          "format": 1,
          "rawSql": "SELECT\n    source AS \"Источник\",\n    countIf(NOT is_error) AS \"Приехало\",\n    countIf(is_error) AS \"Из них в брак\",\n    100 * countIf(is_error) / countIf(NOT is_error) AS \"Доля брака, %\"\nFROM\n(\n    SELECT 'события' AS source, 0 AS is_error, _load_ts FROM stg.hits_raw_dist\n    UNION ALL\n    SELECT 'события', 1, _load_ts FROM ods.event_errors_dist\n    UNION ALL\n    SELECT 'заказы', 0, _load_ts FROM stg.orders_raw_dist\n    UNION ALL\n    SELECT 'заказы', 1, _load_ts FROM ods.order_errors_dist\n)\nWHERE $__timeFilter(_load_ts)\nGROUP BY source\nORDER BY source"
        }
-      ],
+      ]
      "fieldConfig": {
        "defaults": {},
        "overrides": [
          {
            "matcher": {
              "id": "byName",
              "options": "Приехало"
            },
            "properties": [
              {
                "id": "displayName",
                "value": "Загружено в STG"
              }
            ]
          }
        ]
      }
    },
    {
      "type": "table",
-      "title": "Дневной слепок заказов: дата и время загрузки",
+      "title": "Дневной слепок заказов: какой доехал, когда и после какой паузы",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -117,28 +100,11 @@
          "format": 1,
          "rawSql": "SELECT\n    \"Слепок\",\n    \"Доехал\",\n    dateDiff('second', prev, \"Доехал\") AS \"После прошлого, с\",\n    \"Строк\"\nFROM\n(\n    SELECT\n        JSONExtractString(raw, 'snapshot_date') AS \"Слепок\",\n        max(_load_ts) AS \"Доехал\",\n        count() AS \"Строк\",\n        -- Обнуляемый тип нужен, чтобы у самого раннего слепка пауза осталась\n        -- пустой, а не превратилась в разницу с началом эпохи.\n        lagInFrame(toNullable(max(_load_ts))) OVER (ORDER BY \"Слепок\") AS prev\n    FROM stg.orders_raw_dist\n    GROUP BY \"Слепок\"\n)\nORDER BY \"Слепок\" DESC\nLIMIT 10"
        }
-      ],
+      ]
      "fieldConfig": {
        "defaults": {},
        "overrides": [
          {
            "matcher": {
              "id": "byName",
              "options": "Доехал"
            },
            "properties": [
              {
                "id": "displayName",
                "value": "Время загрузки"
              }
            ]
          }
        ]
      }
    },
    {
      "type": "timeseries",
-      "title": "Поток: число сообщений, загруженных в STG",
+      "title": "Поток: сколько строк приезжает в сырой слой",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -170,7 +136,7 @@
    },
    {
      "type": "timeseries",
-      "title": "Сходимость: число событий в Kafka и ClickHouse",
+      "title": "Сходимость: произведено в Kafka против приземлившегося в ClickHouse",
      "datasource": {
        "type": "datasource",
        "uid": "-- Mixed --"
@@ -195,7 +161,7 @@
          },
          "editorMode": "code",
          "expr": "sum(kafka_topic_partition_current_offset{topic=\"hits\"}) - sum(kafka_topic_partition_current_offset{topic=\"hits\"} offset $__interval)",
-          "legendFormat": "поступило в Kafka",
+          "legendFormat": "произведено в Kafka",
          "range": true
        },
        {
@@ -221,7 +187,7 @@
            "properties": [
              {
                "id": "displayName",
-                "value": "загружено в ClickHouse"
+                "value": "приземлилось в ClickHouse"
              }
            ]
          }
@@ -231,7 +197,7 @@
    },
    {
      "type": "timeseries",
-      "title": "Отставание чтения из Kafka: число непрочитанных сообщений",
+      "title": "Отставание чтения из Kafka: непрочитанных сообщений",
      "datasource": {
        "type": "prometheus",
        "uid": "prometheus"
@@ -11,7 +11,7 @@
  "panels": [
    {
      "type": "table",
-      "title": "Запросы с наибольшим числом прочитанных строк",
+      "title": "Тяжёлые запросы: что прочитало больше всех",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -56,7 +56,7 @@
    },
    {
      "type": "table",
-      "title": "Пользователи: число запросов и потребление ресурсов",
+      "title": "Кто спрашивает: сколько запросов и какой у них аппетит",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -93,10 +93,6 @@
              {
                "id": "unit",
                "value": "bytes"
              },
              {
                "id": "displayName",
                "value": "Максимальная память запроса"
              }
            ]
          }
@@ -105,7 +101,7 @@
    },
    {
      "type": "table",
-      "title": "Ошибки выполнения запросов",
+      "title": "Ошибки: на чём запросы споткнулись",
      "datasource": {
        "type": "grafana-clickhouse-datasource",
        "uid": "clickhouse"
@@ -132,20 +128,7 @@
      ],
      "fieldConfig": {
        "defaults": {},
-        "overrides": [
+        "overrides": []
          {
            "matcher": {
              "id": "byName",
              "options": "Чем кончилось"
            },
            "properties": [
              {
                "id": "displayName",
                "value": "Ошибка"
              }
            ]
          }
        ]
      }
    }
  ]
@@ -1,19 +0,0 @@
 slice_name: Средний чек, ₽
 description: null
 certified_by: null
 certification_details: null
 viz_type: big_number_total
 params:
  viz_type: big_number_total
  metric: avg_check
  adhoc_filters:
  - expressionType: SIMPLE
    subject: report_date
    operator: TEMPORAL_RANGE
    comparator: No filter
    clause: WHERE
  header_font_size: 0.3
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000106
 version: 1.0.0
 dataset_uuid: 19600000-0000-4000-8000-000000000001
@@ -1,19 +0,0 @@
 slice_name: Заказы
 description: null
 certified_by: null
 certification_details: null
 viz_type: big_number_total
 params:
  viz_type: big_number_total
  metric: orders
  adhoc_filters:
  - expressionType: SIMPLE
    subject: report_date
    operator: TEMPORAL_RANGE
    comparator: No filter
    clause: WHERE
  header_font_size: 0.3
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000105
 version: 1.0.0
 dataset_uuid: 19600000-0000-4000-8000-000000000001
@@ -1,19 +0,0 @@
 slice_name: Выручка, ₽
 description: null
 certified_by: null
 certification_details: null
 viz_type: big_number_total
 params:
  viz_type: big_number_total
  metric: revenue
  adhoc_filters:
  - expressionType: SIMPLE
    subject: report_date
    operator: TEMPORAL_RANGE
    comparator: No filter
    clause: WHERE
  header_font_size: 0.3
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000104
 version: 1.0.0
 dataset_uuid: 19600000-0000-4000-8000-000000000001
@@ -1,19 +0,0 @@
 slice_name: Посетители
 description: null
 certified_by: null
 certification_details: null
 viz_type: big_number_total
 params:
  viz_type: big_number_total
  metric: visitors
  adhoc_filters:
  - expressionType: SIMPLE
    subject: report_date
    operator: TEMPORAL_RANGE
    comparator: No filter
    clause: WHERE
  header_font_size: 0.3
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000107
 version: 1.0.0
 dataset_uuid: 19600000-0000-4000-8000-000000000003
@@ -1,31 +0,0 @@
 slice_name: Доля известных пользователей
 description: null
 certified_by: null
 certification_details: null
 viz_type: echarts_timeseries_line
 params:
  viz_type: echarts_timeseries_line
  x_axis: report_date
  metrics:
  - known_share
  groupby: []
  adhoc_filters:
  - expressionType: SIMPLE
    subject: report_date
    operator: TEMPORAL_RANGE
    comparator: No filter
    clause: WHERE
  row_limit: 10000
  seriesType: line
  show_legend: false
  rich_tooltip: true
  show_value: false
  markerEnabled: true
  markerSize: 6
  y_axis_format: .1%
  x_axis_time_format: '%d.%m'
  tooltipTimeFormat: '%d.%m.%Y'
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000109
 version: 1.0.0
 dataset_uuid: 19600000-0000-4000-8000-000000000003
@@ -1,4 +1,4 @@
-slice_name: Сверка событий покупки и заказов
+slice_name: Сверка purchase и заказов
 description: null
 certified_by: null
 certification_details: null
@@ -6,9 +6,9 @@ viz_type: pivot_table_v2
 params:
  viz_type: pivot_table_v2
  groupbyRows:
  - mismatch_class
  groupbyColumns:
  - order_day
  groupbyColumns:
  - mismatch_class
  metrics:
  - order_count
  adhoc_filters:
@@ -23,7 +23,8 @@ params:
  colOrder: key_a_to_z
  order_desc: true
  row_limit: 10000
-  date_format: '%d.%m.%Y'
+  valueFormat: SMART_NUMBER
  date_format: smart_date
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000102
 version: 1.0.0
@@ -1,4 +1,4 @@
-slice_name: Выручка по дням и категориям, ₽
+slice_name: Выручка по дням и категориям
 description: null
 certified_by: null
 certification_details: null
@@ -20,13 +20,10 @@ params:
  stack: Stack
  orientation: vertical
  show_legend: true
  legendType: plain
  legendOrientation: bottom
  rich_tooltip: true
  show_value: false
-  y_axis_format: ',d'
+  y_axis_format: ',.2f'
-  x_axis_time_format: '%d.%m'
+  x_axis_time_format: smart_date
  tooltipTimeFormat: '%d.%m.%Y'
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000101
 version: 1.0.0
@@ -1,29 +0,0 @@
 slice_name: Доля категорий в выручке
 description: null
 certified_by: null
 certification_details: null
 viz_type: pie
 params:
  viz_type: pie
  groupby:
  - product_category
  metric: revenue
  adhoc_filters:
  - expressionType: SIMPLE
    subject: report_date
    operator: TEMPORAL_RANGE
    comparator: No filter
    clause: WHERE
  row_limit: 10000
  sort_by_metric: true
  donut: true
  innerRadius: 30
  outerRadius: 70
  show_labels: true
  labels_outside: false
  label_type: percent
  show_legend: false
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000108
 version: 1.0.0
 dataset_uuid: 19600000-0000-4000-8000-000000000001
@@ -17,16 +17,12 @@ params:
    comparator: No filter
    clause: WHERE
  row_limit: 10000
-  seriesType: line
+  seriesType: echarts_timeseries_line
  show_legend: true
  legendOrientation: bottom
  rich_tooltip: true
  show_value: false
  markerEnabled: true
  markerSize: 6
  y_axis_format: ',d'
-  x_axis_time_format: '%d.%m'
+  x_axis_time_format: smart_date
  tooltipTimeFormat: '%d.%m.%Y'
 cache_timeout: null
 uuid: 19600000-0000-4000-8000-000000000103
 version: 1.0.0
@@ -19,79 +19,9 @@ position:
    parents:
    - ROOT_ID
    children:
    - ROW-kpi
    - ROW-revenue
    - ROW-pvo
    - ROW-traffic
  ROW-kpi:
    id: ROW-kpi
    type: ROW
    parents:
    - ROOT_ID
    - GRID_ID
    children:
    - CHART-kpi-revenue
    - CHART-kpi-orders
    - CHART-kpi-avg-check
    - CHART-kpi-visitors
    meta:
      background: BACKGROUND_TRANSPARENT
  CHART-kpi-revenue:
    id: CHART-kpi-revenue
    type: CHART
    parents:
    - ROOT_ID
    - GRID_ID
    - ROW-kpi
    children: []
    meta:
      chartId: 4
      height: 20
      width: 3
      sliceName: Выручка, ₽
      uuid: 19600000-0000-4000-8000-000000000104
  CHART-kpi-orders:
    id: CHART-kpi-orders
    type: CHART
    parents:
    - ROOT_ID
    - GRID_ID
    - ROW-kpi
    children: []
    meta:
      chartId: 5
      height: 20
      width: 3
      sliceName: Заказы
      uuid: 19600000-0000-4000-8000-000000000105
  CHART-kpi-avg-check:
    id: CHART-kpi-avg-check
    type: CHART
    parents:
    - ROOT_ID
    - GRID_ID
    - ROW-kpi
    children: []
    meta:
      chartId: 6
      height: 20
      width: 3
      sliceName: Средний чек, ₽
      uuid: 19600000-0000-4000-8000-000000000106
  CHART-kpi-visitors:
    id: CHART-kpi-visitors
    type: CHART
    parents:
    - ROOT_ID
    - GRID_ID
    - ROW-kpi
    children: []
    meta:
      chartId: 7
      height: 20
      width: 3
      sliceName: Посетители
      uuid: 19600000-0000-4000-8000-000000000107
  ROW-revenue:
    id: ROW-revenue
    type: ROW
@@ -100,7 +30,6 @@ position:
    - GRID_ID
    children:
    - CHART-revenue
    - CHART-revenue-share
    meta:
      background: BACKGROUND_TRANSPARENT
  CHART-revenue:
@@ -114,23 +43,9 @@ position:
    meta:
      chartId: 1
      height: 50
-      width: 8
+      width: 12
-      sliceName: Выручка по дням и категориям, ₽
+      sliceName: Выручка по дням и категориям
      uuid: 19600000-0000-4000-8000-000000000101
  CHART-revenue-share:
    id: CHART-revenue-share
    type: CHART
    parents:
    - ROOT_ID
    - GRID_ID
    - ROW-revenue
    children: []
    meta:
      chartId: 8
      height: 50
      width: 4
      sliceName: Доля категорий в выручке
      uuid: 19600000-0000-4000-8000-000000000108
  ROW-pvo:
    id: ROW-pvo
    type: ROW
@@ -151,9 +66,9 @@ position:
    children: []
    meta:
      chartId: 2
-      height: 44
+      height: 50
      width: 12
-      sliceName: Сверка событий покупки и заказов
+      sliceName: Сверка purchase и заказов
      uuid: 19600000-0000-4000-8000-000000000102
  ROW-traffic:
    id: ROW-traffic
@@ -163,7 +78,6 @@ position:
    - GRID_ID
    children:
    - CHART-traffic
    - CHART-known-share
    meta:
      background: BACKGROUND_TRANSPARENT
  CHART-traffic:
@@ -177,57 +91,15 @@ position:
    meta:
      chartId: 3
      height: 50
-      width: 6
+      width: 12
      sliceName: Посетители и известные пользователи
      uuid: 19600000-0000-4000-8000-000000000103
  CHART-known-share:
    id: CHART-known-share
    type: CHART
    parents:
    - ROOT_ID
    - GRID_ID
    - ROW-traffic
    children: []
    meta:
      chartId: 9
      height: 50
      width: 6
      sliceName: Доля известных пользователей
      uuid: 19600000-0000-4000-8000-000000000109
 metadata:
  color_scheme: supersetColors
  label_colors:
    Товары для дома: '#1FA8C9'
    Текстиль: '#454E7C'
    Посуда: '#5AC189'
    Бытовая техника: '#FF7F44'
    Детские товары: '#E04355'
    Одежда и обувь: '#A868B7'
    visitors: '#1FA8C9'
    known_users: '#454E7C'
    known_share: '#454E7C'
  cross_filters_enabled: false
  chart_configuration: {}
  expanded_slices: {}
  default_filters: '{}'
-  native_filter_configuration:
+  native_filter_configuration: []
  - id: NATIVE_FILTER-period
    name: Период
    filterType: filter_time
    type: NATIVE_FILTER
    targets:
    - {}
    controlValues:
      enableEmptyFilter: false
    defaultDataMask:
      extraFormData: {}
      filterState: {}
      ownState: {}
    cascadeParentIds: []
    scope:
      rootPath:
      - ROOT_ID
      excluded: []
    description: ''
 theme_uuid: null
 version: 1.0.0
@@ -36,15 +36,6 @@ metrics:
  currency: null
  extra: null
  warning_text: null
 - metric_name: known_share
  verbose_name: Доля известных пользователей
  metric_type: null
  expression: SUM(known_users) / nullIf(SUM(visitors), 0)
  description: null
  d3format: .1%
  currency: null
  extra: null
  warning_text: null
 columns:
 - column_name: _load_ts
  verbose_name: Время загрузки
@@ -55,7 +55,7 @@ columns:
  datetime_format: null
  extra: null
 - column_name: declared_revenue
-  verbose_name: Заявленная сумма покупки из события
+  verbose_name: Выручка purchase
  is_dttm: false
  is_active: true
  type: NULLABLE(DECIMAL(18, 2))
@@ -120,7 +120,7 @@ columns:
  datetime_format: null
  extra: null
 - column_name: order_id
-  verbose_name: Номер заказа
+  verbose_name: Заказ
  is_dttm: false
  is_active: true
  type: STRING
@@ -23,26 +23,10 @@ metrics:
  metric_type: null
  expression: SUM(revenue)
  description: null
-  d3format: ',d'
+  d3format: ',.2f'
-  currency: null
+  currency:
-  extra: null
+    symbol: ₽
-  warning_text: null
+    symbolPosition: suffix
 - metric_name: orders
  verbose_name: Заказы
  metric_type: null
  expression: SUM(orders)
  description: null
  d3format: ',d'
  currency: null
  extra: null
  warning_text: null
 - metric_name: avg_check
  verbose_name: Средний чек
  metric_type: null
  expression: SUM(revenue) / nullIf(SUM(orders), 0)
  description: null
  d3format: ',d'
  currency: null
  extra: null
  warning_text: null
 columns:
@@ -60,7 +44,7 @@ columns:
  datetime_format: null
  extra: null
 - column_name: aov
-  verbose_name: Средний чек за день и категорию
+  verbose_name: Средний чек
  is_dttm: false
  is_active: true
  type: DECIMAL(18, 2)
@@ -125,7 +109,7 @@ columns:
  datetime_format: null
  extra: null
 - column_name: units
-  verbose_name: Продано единиц товара
+  verbose_name: Товары
  is_dttm: false
  is_active: true
  type: UINT64
@@ -24,10 +24,10 @@ compose() {
 next_step() {
    case "$DAG_ID" in
        world_initialize)
-            printf 'проверьте состояние запуска в Airflow и журнал задачи с ошибкой; после устранения причины повторите make up'
+            printf 'посмотрите журнал; повторите make up, а для недействительного мира — make rebuild-storage'
            ;;
-        world_recreate) printf 'проверьте состояние запуска в Airflow и журнал задачи с ошибкой; после устранения причины повторите make rebuild-storage' ;;
+        world_recreate) printf 'устраните причину и повторите make rebuild-storage' ;;
-        *) printf 'проверьте состояние запуска в Airflow и журнал задачи с ошибкой; после устранения причины повторите команду' ;;
+        *) printf 'проверьте журнал дага и повторите команду' ;;
    esac
 }
@@ -67,7 +67,7 @@ for ((attempt = 1; attempt <= ATTEMPTS; attempt++)); do
 done
 jq -e --arg dag_id "$DAG_ID" '.dag_id == $dag_id' \
    >/dev/null 2>&1 <<<"$dag" || \
-    fail "даг ${DAG_ID} не появился в API за $((ATTEMPTS * PAUSE_SECONDS)) с; проверьте ошибки импорта в Airflow и журнал службы airflow-dag-processor"
+    fail "даг ${DAG_ID} не появился за $((ATTEMPTS * PAUSE_SECONDS)) с; $(next_step)"
 # GET читает DagModel по идентификатору, а POST запуска принимает только запись
 # с `is_stale = false`. На холодном старте GET уже может видеть даг, пока POST
@@ -105,7 +105,7 @@ for ((attempt = 1; attempt <= TRIGGER_ATTEMPTS; attempt++)); do
    fail "Airflow не запустил даг ${DAG_ID}: HTTP ${http_status}${detail:+: ${detail}}; $(next_step)"
 done
 ((triggered == 1)) || \
-    fail "даг ${DAG_ID} не стал доступен для запуска за $((TRIGGER_ATTEMPTS * PAUSE_SECONDS)) с; проверьте ошибки импорта в Airflow и журнал службы airflow-dag-processor"
+    fail "даг ${DAG_ID} не стал доступен для запуска за $((TRIGGER_ATTEMPTS * PAUSE_SECONDS)) с; $(next_step)"
 run_id="$(jq -r '.dag_run_id // empty' <<<"$response")"
 state="$(jq -r '.state // "queued"' <<<"$response")"
 [[ -n "$run_id" ]] || fail "Airflow не вернул идентификатор запуска ${DAG_ID}"
@@ -121,7 +121,7 @@ for ((attempt = 1; attempt <= ATTEMPTS; attempt++)); do
    state="$(jq -r '.state // empty' <<<"$response" 2>/dev/null || true)"
    case "$state" in
        success)
-            printf 'УСПЕХ: даг %s, запуск %s, состояние success.\n' "$DAG_ID" "$run_id"
+            printf 'ЗЕЛЁНО: даг %s, запуск %s, состояние success.\n' "$DAG_ID" "$run_id"
            exit 0
            ;;
        failed)
@@ -1,20 +1,49 @@
-- Локальная таблица события.
+-- ODS: типизированное событие и таблица ошибок разбора.
 -- Поля следуют docs/formats/clickstream-event.md; purchaseRevenue хранится
 -- в Decimal для точного счета денег. Правила приема — ADR 0005.
 -- ReplacingMergeTree оставляет последнюю доставку по _load_ts среди строк
 -- с одинаковым полным ORDER BY. Метка переносится из STG без пересчета.
 -- Она не входит в ключ сортировки или партиции: иначе повторные доставки
 -- не считались бы версиями одной строки. Для чтения служит ods.event_v с FINAL.
 --
-- Партиция EventDate хранит модельный день события. CounterID на стенде
+-- Состав, имена и типы колонок списаны с «описания выгрузки»
-- постоянен, EventDate постоянна внутри партиции; дальнейшая сортировка —
+-- (docs/formats/clickstream-event.md) — так же, как в бою хранилище пишут по
-- по intHash32(ClientID) и WatchID. WatchID отличает события посетителя:
+-- документации источника. Модуль контракта генератора здесь не читается:
-- без него они заменяли бы друг друга.
+-- граница «трекер | хранилище» проходит по документу.
--
+-- Механика приёма и три класса брака — ADR 0005, конвенции имён, служебных
-- SAMPLE BY использует то же выражение, что ключ сортировки, и отбирает
+-- колонок и сроков — docs/architecture/storage.md.
 -- посетителей целиком. Sign всегда равен 1: поле сохранено по формату
 -- источника, но исправлений парой −1/+1 генератор не отправляет.
 -- Локальная таблица события.
 --
 -- Движок ReplacingMergeTree, колонка версии — _load_ts. Работа у версии ровно
 -- одна: схлопнуть повтор доставки. Метка не ставится здесь заново, а
 -- переносится из stg.hits_raw как есть — колонка отвечает на вопрос «когда
 -- строка приехала в хранилище», а не «когда её разобрали». У повтора
 -- содержимое то же самое, отличается только метка, поэтому какая из двух
 -- строк переживёт мерж, безразлично.
 --
 -- Колонка версии не входит ни в ключ партиции, ни в ключ сортировки, и это
 -- не случайность: попади она туда — версии одной строки лягут в разные куски
 -- или в разные места ключа и не встретятся при мерже, то есть дедупликация
 -- перестанет работать молча.
 --
 -- PARTITION BY EventDate — по дню события, а не по месяцу, как у Метрики.
 -- Отступление осознанное: дневная партиция здесь единица переобработки, и
 -- переиграть день X значит заменить одну партицию. Месячная партиция тянула
 -- бы за собой тридцать чужих дней.
 --
 -- ORDER BY вырожден, и это учебный факт, а не недосмотр: CounterID на стенде
 -- константа (сайт один), EventDate константа внутри своей партиции — обе
 -- головные колонки ключа не различают ни одной строки. Реальная сортировка
 -- идёт по посетителю и событию: intHash32(ClientID), WatchID. Ключ написан в
 -- боевой форме «по сайту за период по посетителю» — на стенде она
 -- вырождается, в бою нет. Хвост WatchID работает ещё и на дедупликацию: без
 -- него ReplacingMergeTree схлопнул бы в одну строку все события посетителя за
 -- день.
 --
 -- SAMPLE BY intHash32(ClientID) — по тому же выражению, что стоит в ключе
 -- сортировки (иначе семплирование не разрешено). Семплирование берёт целиком
 -- посетителей, а не события вразнобой, поэтому SAMPLE 0.1 не портит
 -- uniq-метрики.
 --
 -- Sign всегда равен 1: это колонка формата, взятая без механики. В бою
 -- исправление записи шлют парой −1/+1 и считают через sum(Sign) поверх
 -- CollapsingMergeTree; наш генератор исправлений не шлёт, поэтому колонка
 -- есть, а механики за ней нет.
 CREATE TABLE IF NOT EXISTS ods.event_rep ON CLUSTER clickstream_cluster
 (
    WatchID UInt64,
@@ -71,24 +100,36 @@ PARTITION BY EventDate
 ORDER BY (CounterID, EventDate, intHash32(ClientID), WatchID)
 SAMPLE BY intHash32(ClientID);
-- Запись и диагностика через Distributed; актуальные события — в ods.event_v.
+-- Лицо слоя: пишем и читаем через него. Ключ шардирования —
-- cityHash64(ClientID) распределяет посетителей равномернее, чем остаток
+-- cityHash64(ClientID), а не сырой ClientID: структурированный числовой
-- самого структурированного идентификатора. События посетителя лежат вместе.
+-- идентификатор перекашивает остаток по модулю числа шардов, хеш — нет.
-- STG распределен по хешу raw, поэтому сообщение и разобранное событие могут
+-- События одной куки при этом остаются на одном шарде, и сессионизация со
-- лежать на разных шардах. Общие счетчики сравнивают через _dist.
+-- склейкой идентичностей ниже по течению живут локально.
-
+--
 -- У STG ключ другой (хеш строки), поэтому сырая строка и разобранное из неё
 -- событие почти всегда лежат на разных шардах. Пошардовые счётчики слоёв
 -- сходиться не должны — сверять слои можно только через _dist.
 CREATE TABLE IF NOT EXISTS ods.event_dist ON CLUSTER clickstream_cluster
 AS ods.event_rep
 ENGINE = Distributed('clickstream_cluster', 'ods', 'event_rep', cityHash64(ClientID));
-- Ошибки разбора: исходный текст, класс и сведения о доставке.
+-- Локальная таблица ошибок разбора.
 -- У сообщения может не быть разобранного ClientID, поэтому шардирование —
 -- по cityHash64(raw), партиция — по реальному дню загрузки.
 -- ORDER BY группирует ошибки по классу и координатам Kafka.
 --
-- Замены версий нет: надежного ключа события у брака может не быть.
+-- Сырой текст сообщения, метаданные доставки и класс брака. Разобранных полей
-- TTL сохраняет ошибки месяц, дольше трехсуточного срока STG.
+-- у брака нет по определению: строка сюда попала как раз потому, что не
-
+-- разобралась.
 --
 -- Движок — обычный ReplicatedMergeTree, без замены версий: у брака нет ключа
 -- сущности, схлопывать его не по чему.
 --
 -- Ключи собственные. Шардирование — cityHash64(raw): ClientID у неразобранной
 -- строки взять неоткуда. ORDER BY (error_class, kafka_partition,
 -- kafka_offset): такую таблицу смотрят от класса брака, а внутри класса — по
 -- координатам доставки. Нарезка по дню загрузки, как у STG: модельного дня
 -- у брака тоже нет.
 --
 -- Срок жизни — месяц, вдесятеро дольше сырых данных. Истеки брак вместе с ними —
 -- к моменту разбирательства не осталось бы ни того, ни другого.
 CREATE TABLE IF NOT EXISTS ods.event_errors_rep ON CLUSTER clickstream_cluster
 (
    raw String,
@@ -1,6 +1,8 @@
-- Актуальные события: FINAL выбирает последнюю доставку по _load_ts,
+-- ODS: каноническое чтение актуальных событий.
-- не дожидаясь фоновых слияний. Поля и типы остаются как в ods.event_dist.
+--
-
+-- Представление сохраняет поля и зерно ods.event_dist, но скрывает FINAL от
 -- потребителя. Поэтому физическая таблица остаётся местом диагностики
 -- доставленных версий, а точное чтение получает одно имя.
 CREATE VIEW IF NOT EXISTS ods.event_v ON CLUSTER clickstream_cluster
 AS
 SELECT *
@@ -23,24 +25,69 @@ AS
 SELECT *
 FROM ods.order_dist FINAL;
-- Разбор STG в события и ошибки. Два представления используют одинаковое
+-- ODS: разбор STG в событие и в таблицу ошибок.
 -- условие годности; второе берет его отрицание. Условие дает только 0 или 1:
 -- NULL не выбрала бы ни одна ветвь. Функции разбора не вызывают исключений
 -- на некорректном raw, чтобы одно сообщение не прервало прием.
 --
-- Оба представления срабатывают на вставку в stg.hits_raw_dist,
+-- Матвью две, и вместе они обязаны делить поток без зазора и без нахлёста:
-- до распределения по шардам. Порядок SELECT совпадает с целевой таблицей.
+-- строка, подошедшая обеим, задвоится, а не подошедшая ни одной — исчезнет
 -- молча. Держится это формой: годность считает один и тот же предикат из трёх
 -- частей, а вторая матвью берёт его буквальное отрицание.
 --
-- Прием проверяет объект JSON, точный набор ключей и разбор пяти полей:
+-- Отсюда два запрета на выражения предиката, и оба серьёзные.
 -- WatchID, VisitID, ClientID, EventDate, UTCEventTime. Остальные поля
 -- извлекаются по формату без отдельной проверки. Граница — ADR 0005.
 -- arraySort с обеих сторон позволяет сравнить ключи независимо от порядка.
 --
-- UTCEventTime приходит строкой вида "2026-06-01T12:34:56Z". Ее разбирает
+-- Первый: ни одна его часть не возвращает NULL. Трёхзначная логика дала бы
-- parseDateTimeOrNull с явной маской: JSONExtract в DateTime такую форму
+-- строку, которую не берёт ни «условие», ни «NOT условие», — и потерялась бы
-- не принимает, а BestEffort допускает неполные даты. Пояс UTC указан
+-- она бесшумно. Поэтому сравнения здесь дают 0 или 1, а разбор в Nullable
-- отдельно, потому что Z в маске проверяется как буква. EventDate приходит
+-- заканчивается IS NOT NULL.
-- как "2026-06-01" и разбирается через JSONExtract.
+--
 -- Второй: ни одна его часть не бросает исключений. Упавшая матвью роняет
 -- вставку, офсеты не коммитятся, и потребление топика встаёт до починки —
 -- это единственное, на чём сейчас держится правило репозитория «грязные
 -- записи не валят пайплайн». Поэтому приведение Nullable к необнуляемому типу
 -- (assumeNotNull) стоит только в списке колонок, за предикатом, который NULL
 -- уже отсёк, а в самом предикате живут только функции семейства
 -- JSONExtract/*OrNull. Довод целиком — ADR 0005.
 --
 -- Источник у обеих — stg.hits_raw_dist, лицо слоя, а не локальная таблица:
 -- потребитель цепляется к лицу, а матвью с источником-Distributed срабатывает
 -- на вставку именно в распределённую таблицу, до раскладки по шардам.
 --
 -- Порядок колонок в SELECT совпадает с порядком в целевой таблице.
 -- Годное событие: строка, прошедшая строгий приём.
 --
 -- Строгий приём — это три вопроса: объект ли это JSON, тот ли набор ключей,
 -- разбираются ли в свой тип пять опорных колонок. Почему именно так — почему
 -- объект, а не валидность; почему сверка ключей заменяет сорок семь проверок
 -- на присутствие; почему опорных пять, а не сорок семь — ADR 0005, «Решение».
 --
 -- arraySort ниже стоит с обеих сторон, и убирать его нельзя: без обёртки сорок
 -- семь CamelCase-имён пришлось бы держать ровно в байтовом порядке, а сбой
 -- порядка увёл бы в брак вообще всё, и молча (ADR 0005).
 --
 -- Метка времени — единственная из пяти, кого разбирает не JSONExtract, и это
 -- измеренная необходимость, а не вкус. На проводе UTCEventTime уезжает в
 -- ISO-8601 с суффиксом зоны — «2026-06-01T12:34:56Z» (спека генератора,
 -- раздел 4), а JSONExtract с типом DateTime такую строку не берёт и отдаёт
 -- NULL. Оставь его здесь — и в брак уехали бы все события до единого.
 --
 -- Формат назван буквально, а не отдан parseDateTimeBestEffort, и вот почему.
 -- Best-effort понимает десяток записей и на непонятной не краснеет, а
 -- достраивает недостающее: обрезанное «20:00:21» он превращает в первое
 -- января текущего года. Такая строка прошла бы строгий приём с тихо неверным
 -- временем — ровно с той порчей, ради которой класс key_field_unparsed и
 -- заведён. Источник у топика один и шлёт одну запись, так что широта здесь не
 -- нужна вовсе, а стоит она отключённой проверкой. Замеры — ADR 0005,
 -- «Что проверено».
 --
 -- Третьим аргументом назван пояс — 'UTC'. Суффикс Z маска сверяет как букву и
 -- выбрасывает, зоны из строки не берёт вовсе, поэтому без имени функция читала
 -- бы показания часов по поясу сессии, а тот по умолчанию серверный. Тип
 -- колонки этого не чинит: разбор отдаёт готовое число, и колонка кладёт его
 -- как есть — пояс приёмника решал бы судьбу строки, а не числа.
 -- Правило и замер — docs/architecture/storage.md, «Часовые пояса».
 --
 -- EventDate в такой подпорке не нуждается: дата уезжает как «2026-06-01», и
 -- JSONExtract её берёт.
 CREATE MATERIALIZED VIEW IF NOT EXISTS ods.event_mv ON CLUSTER clickstream_cluster
 TO ods.event_dist
@@ -107,8 +154,10 @@ SELECT
    JSONExtract(raw, 'GoalsReached', 'Array(UInt32)') AS GoalsReached,
    JSONExtract(raw, 'ParsedParamsKey1', 'Array(String)') AS ParsedParamsKey1,
    JSONExtract(raw, 'purchaseID', 'Array(String)') AS purchaseID,
-    -- purchaseRevenue приходит числом рублей и разбирается сразу в Decimal.
+    -- Выгрузка несет JSON-числа типа Float64, но деньги хранятся в Decimal.
-    -- Прямой разбор сверяли через Context7 и на ClickHouse 26.3 (#155).
+    -- JSONExtract разбирает их сразу, без промежуточного двоичного числа:
    -- синтаксис подтвержден документацией ClickHouse через Context7 и
    -- запросом к стендовому ClickHouse 26.3 при исполнении #155.
    JSONExtract(raw, 'purchaseRevenue', 'Array(Decimal(18, 2))') AS purchaseRevenue,
    JSONExtract(raw, 'purchaseCurrency', 'Array(String)') AS purchaseCurrency,
    JSONExtract(raw, 'purchaseCoupon', 'Array(String)') AS purchaseCoupon,
@@ -119,16 +168,25 @@ SELECT
    JSONExtract(raw, 'productQuantity', 'Array(UInt64)') AS productQuantity,
    JSONExtract(raw, 'productEventType', 'Array(String)') AS productEventType,
    JSONExtract(raw, 'ecommerce', 'String') AS ecommerce,
-    -- _load_ts остается временем исходной доставки и версией события.
+    -- Метка загрузки переносится из STG как есть, а не ставится заново:
    -- она отвечает на вопрос «когда строка приехала в хранилище». Поставь
    -- здесь now64(3) — и колонка версии молча ответила бы на другой вопрос.
    _load_ts
 FROM stg.hits_raw_dist
 WHERE is_object AND keys_match AND key_fields_parsed;
-- Ошибки: отрицание того же условия годности.
+-- Брак: буквальное отрицание того же предиката.
-- Класс определяется первым нарушенным условием. Например, JSON-строка
+--
-- не проходит и проверку объекта, и проверку ключей, но получает not_an_object.
+-- Классы брака пересекаются, поэтому проверяются по порядку, а в error_class
-- Условие повторено рядом с запросом, без отдельной функции ClickHouse.
+-- пишется первый совпавший. Скаляр проваливает и проверку на объект, и сверку
-
+-- ключей — JSONExtractKeys от него даёт пустой массив (измерено на стенде
 -- 7 августа 2026 года), — и без объявленного порядка попал бы то в один
 -- класс, то в другой.
 --
 -- Предикат повторён здесь дословно, и это выбор, а не безвыходность: назвать
 -- его один раз на две матвью позволил бы CREATE FUNCTION. Отвергнуто — условие
 -- разбора ушло бы за имя, в отдельный объект со своей жизнью, и слой перестал
 -- бы читаться по своему же DDL.
 CREATE MATERIALIZED VIEW IF NOT EXISTS ods.event_errors_mv ON CLUSTER clickstream_cluster
 TO ods.event_errors_dist
 AS
@@ -1,16 +1,26 @@
-- Прием событий из Kafka в STG.
+-- STG: матвью приёма — из чтеца в таблицу STG.
 -- Подключение этого представления запускает чтение топика. Поэтому файл 40
 -- применяется после таблиц и представлений разбора из файлов 20 и 30:
 -- иначе часть сообщений сохранится в STG, но не попадет в ODS.
 --
-- Запись через stg.hits_raw_dist распределяет сообщения по ключу таблицы.
+-- Номер 40, а не 11, и пропуск в нумерации намеренный. Файлы 20-ods-tables.sql
-- Она фоновая; возможную потерю при сбое описывает раздел «Приём»
+-- и 30-ods-views.sql приносит #43, и матвью приёма обязана создаваться после
-- в docs/architecture/storage.md.
+-- матвью разбора: Kafka-движок начинает читать топик ровно тогда, когда к нему
 -- привязывают первую матвью. Создай её раньше разбора — и всё, что доедет в
 -- зазоре, ляжет в STG и не попадёт в ODS никуда, ни в событие, ни в ошибки.
 -- На пустом топике зазор безвреден, поэтому первый прогон о нём не скажет:
 -- проснётся он, когда тома ClickHouse снесены, а данные Kafka целы, то есть на
 -- обычной отладке. Нумерацию здесь не «приводить в порядок».
 --
-- Сведения о доставке вычисляются здесь, на ноде чтения Kafka.
+-- Пишем в stg.hits_raw_dist, а не в локальную таблицу: раскладку по шардам
-- DEFAULT hostName() только в локальной таблице назвал бы шард-получатель.
+-- обязан определять ключ шардирования, а не то, какая нода случайно читала
-- Порядок SELECT совпадает с порядком колонок цели.
+-- топик. Вставка при этом фоновая — окно потери принято осознанно, довод
-
+-- целиком в docs/architecture/storage.md, раздел «Приём».
 --
 -- Служебные колонки заполняются выражением здесь, а не DEFAULT в таблице.
 -- Для consumer_host это обязательно: проверено на стенде 5 августа 2026 года —
 -- DEFAULT hostName() вычисляется на шарде-получателе и назвал бы не ту ноду,
 -- которая читала топик. hostName() в SELECT снимается на вставляющей ноде,
 -- то есть отвечает ровно на нужный вопрос.
 --
 -- Порядок колонок в SELECT совпадает с порядком в целевой таблице.
 CREATE MATERIALIZED VIEW IF NOT EXISTS stg.hits_raw_mv ON CLUSTER clickstream_cluster
 TO stg.hits_raw_dist
 AS
@@ -1,9 +1,21 @@
-- Сборка выбранных дней в донор перед заменой партиций DDS.
+-- DDS: сборка дней заказа в таблицу-двойник перед заменой партиций.
 -- Донор очищается в начале: иначе новые строки добавились бы к прежним.
 -- После сборки он остается для диагностики до следующего запуска.
 --
-- DROP PARTITION ALL доступен роли etl через ALTER; отдельного права
+-- Двойник очищается целиком в начале сборки, а не в конце: собранное остаётся
-- TRUNCATE у нее нет (ADR 0007). Весь отрезок дней собирается одной вставкой.
+-- лежать до следующего запуска, и разбор происшествия видит ровно то, чем
 -- подменили день. Очистка обязана быть первой ещё и по делу — вставка поверх
 -- прежних строк удвоила бы день в доноре, а REPLACE PARTITION перенёс бы
 -- удвоение в цель.
 --
 -- Дни собираются одной вставкой, а не по дню за раз: источник читается один
 -- раз на весь отрезок. Кто раскладывает строки по шардам — вставка через
 -- Distributed, ключ cityHash64(order_id) — разобрано в DDL двойника.
 --
 -- Чистит двойник DROP PARTITION ALL, а не TRUNCATE: последнее — отдельное
 -- право, роли etl оно не выдано, а снятие всех партиций
 -- входит в ALTER, который у неё есть (ADR 0007). Замерено: TRUNCATE отвечает
 -- ролью etl кодом 497, DROP PARTITION ALL проходит. Расширять права ради
 -- операции, для которой уже есть разрешённая форма, значило бы платить
 -- доступом за синоним.
 ALTER TABLE dds.order_stage_rep ON CLUSTER clickstream_cluster DROP PARTITION ALL;
@@ -25,13 +37,18 @@ INSERT INTO dds.order_stage_dist
    _load_id,
    _load_ts
 )
-- Разбор позиций из JSON: цена в строке сразу превращается в Decimal.
+-- Позиции разбираются здесь один раз, на границе ODS → DDS. Цена на проводе —
-- ODS проверил только тип массива items. Неверное содержимое здесь может
+-- строка с двумя знаками, и JSONExtract читает её прямо в Decimal: замерено на
-- дать значения по умолчанию: qty вида "oops" и пропущенная цена дают 0,
+-- живом слепке, промежуточный toDecimal64 не нужен.
-- скаляр вместо объекта выпадает из массива. Наблюдения —
+--
-- docs/architecture/storage.md, «Что проверено».
+-- Разбор по типу молчалив, и знать об этом надо заранее. Строгий приём ODS
-- Проверку суммы позиций участник добавляет в docs/labs/5-1-order-checks.md.
+-- проверил только, что items — массив, внутрь он не смотрел; здесь тоже никто
-
+-- не смотрит. Замерено: qty вида "oops" даёт 0, пропущенная цена даёт 0,
 -- скаляр вместо объекта выпадает из массива целиком. На каноническом слепке
 -- генератора такого не бывает, и сумма «цена × количество» сходится с
 -- items_total у всех заказов, но сходится она по свойству источника, а не
 -- потому, что её здесь кто-то проверяет. Постоянное место такой проверки —
 -- контур DQ этапа 4; пока она делается руками при приёмке.
 WITH JSONExtract(
        items, 'Array(Tuple(sku String, qty UInt32, price Decimal(18, 2)))'
    ) AS lines
@@ -39,7 +56,8 @@ SELECT
    order_id,
    user_id,
    status,
-    -- День и время в Europe/Samara: витрины используют готовые колонки.
+    -- День заказа и оба времени переезжают в пояс счётчика: DDS обслуживает
    -- человека с дашбордом, и пояс называется здесь в последний раз.
    toDate(toTimeZone(created_at, 'Europe/Samara')),
    toTimeZone(created_at, 'Europe/Samara'),
    toTimeZone(updated_at, 'Europe/Samara'),
@@ -50,17 +68,22 @@ SELECT
    arrayMap(line -> line.sku, lines),
    arrayMap(line -> line.qty, lines),
    arrayMap(line -> line.price, lines),
-    -- Метки этой сборки DDS, общие для всех вставляемых строк.
+    -- Координаты запуска, собравшего день: у всех строк дня они одни.
    {load_id:String},
    now64(3, 'UTC')
 FROM ods.order_v
 WHERE toDate(toTimeZone(created_at, 'Europe/Samara'))
        BETWEEN {first_day:Date} AND {last_day:Date}
-    -- Дополнительный фильтр сокращает чтение партиций ODS по UTC.
+    -- Вторая граница не меняет отбор, а открывает источнику отсечение
-    -- Модельные сутки Europe/Samara пересекают две даты UTC, поэтому
+    -- партиций: ODS нарезан по toDate(created_at) в UTC, и условие на
-    -- левая граница берется на день раньше. Точный отбор — условием выше.
+    -- вычисленный день заказа для этого ключа непрозрачно — сервер прочёл бы
    -- все партиции. Сутки пояса счётчика ложатся ровно на две даты UTC,
    -- поэтому день слева берётся с запасом.
    AND toDate(created_at) BETWEEN {first_day:Date} - 1 AND {last_day:Date}
-- Ждем доставки на шарды и распределяем строки по ключу цели
+-- Тот же ноль, что в приёме заказов: заводская двойка исполнила бы вставку
-- (docs/architecture/storage.md, «Раскладка по шардам»).
+-- локально на каждом шарде, минуя ключ шардирования цели, и строки унаследовали
 -- бы раскладку источника. Ключи ODS и DDS здесь совпадают, и раскладка вышла бы
 -- верной — но по совпадению, а не по контракту (docs/architecture/storage.md,
 -- «Раскладка по шардам», капкан #137).
 SETTINGS distributed_foreground_insert = 1,
    parallel_distributed_insert_select = 0;
@@ -1,16 +1,28 @@
-- Замена одного дня DDS готовой партицией донора.
+-- DDS: подмена одного дня заказов собранной партицией двойника.
 -- Повтор при неизменном источнике сохраняет деловые данные без дублей.
 --
-- ON CLUSTER выполняет замену на обеих нодах по локальным таблицам.
+-- Это и есть идемпотентность слоя. Повтор прогона безопасен, а «дыхание»
-- Донор и цель имеют одинаковую структуру и ключ шардирования
+-- статусов внутри окна выражается сменой всей партиции, а не правкой строк.
 -- (sql/ddl/45-dds-tables.sql); REPLACE PARTITION строки не перераспределяет.
 -- Замена атомарна внутри шарда. Между заменами на разных шардах читатель
 -- может увидеть часть прежних и часть новых данных. После сбоя этот период
 -- длится до успешного повтора. Пустая партиция донора удаляет день из цели.
 --
-- День подставляет Jinja: параметры ClickHouse в ALTER ... PARTITION
+-- Замена идёт по локальным таблицам, шард за шардом: ON CLUSTER рассылает её
-- не поддерживаются в закрепленной версии 26.3. Значение получено
+-- на обе ноды, а по Distributed то же самое не работает — операции с
-- из результата order_scope.sql; замер — docs/architecture/storage.md.
+-- партициями отвечают кодом 48 (docs/architecture/storage.md, «Что
-
+-- проверено»). Правильность пошардовой замены держится на том, что двойник
 -- шардирован тем же ключом, что цель, — см. sql/ddl/45-dds-tables.sql.
 --
 -- Отсюда граница обещания: атомарность здесь пошардовая. Внутри шарда подмена
 -- мгновенна — читатель видит либо прежний день целиком, либо новый; но две
 -- локальные замены независимы, и в зазоре между ними чтение через Distributed
 -- соберёт ответ из нового дня одного шарда и прежнего дня другого. Зазор
 -- короткий, а отказ одной из двух замен растягивает его до повторного прогона.
 --
 -- Пустая партиция двойника — законный случай, а не сбой: день, в котором
 -- заказов нет, снимает день из цели, и слой перестаёт показывать то, чего в
 -- источнике больше нет.
 --
 -- День подставляет Jinja, а не параметр ClickHouse: в ALTER … PARTITION
 -- сервер параметров не подставляет — замерено, отвечает синтаксической
 -- ошибкой. Общее правило репозитория «параметры передаются отдельно, а не
 -- строкой» здесь не нарушено по существу: значение пришло из ответа самого
 -- ClickHouse на запрос объёма, а не снаружи стенда.
 ALTER TABLE dds.order_rep ON CLUSTER clickstream_cluster
 REPLACE PARTITION '{{ params.day }}' FROM dds.order_stage_rep;
@@ -1,17 +1,37 @@
-- Дни пересборки заказов: first_day и last_day, обе границы включены.
+-- DDS: объём пересборки заказов — с какого дня по какой собирает этот запуск.
 -- Текущее окно — дни оформления заказов из последнего snapshot_date.
 -- Если в DDS нет дня, который есть в ODS, отрезок расширяется до первого
 -- такого дня. Это восстанавливает пропуски даже за пределами текущего окна.
 --
-- Дата слепка у актуальной версии показывает последнее наблюдение заказа
+-- Параметров у дага нет: объём он выводит сам из состояния слоёв
-- (ADR 0014). Поэтому окно берется из данных, без копирования константы
+-- (docs/architecture/etl.md, «Объём прогона»). Ответ — две даты, границы
-- генератора. FINAL здесь не нужен: created_at одинаков у всех версий,
+-- непрерывного отрезка; список дней между ними разворачивает даг. Пустой
-- а строки последнего слепка сохраняются при слияниях.
+-- источник даёт пустой ответ, и даг на нём останавливается с внятной ошибкой
 -- вместо зелёного прогона, собравшего ничего.
 --
-- Пустой ODS не дает строки результата; даг завершится ошибкой.
+-- Файл кончается без точки с запятой: даг читает его целиком и шлёт одним
-- Точка с запятой в конце не нужна: клиент дописывает FORMAT ответа.
+-- запросом, дописывая формат ответа, — точка с запятой сделала бы из этого
-- Порядок пересборки — docs/architecture/etl.md, «Объём прогона».
+-- мультизапрос, который ClickHouse не принимает.
-
+--
 -- Объём складывается из двух частей. Первая — дышащее окно: дни, которые нёс
 -- последний слепок, то есть те, чьё состояние источник ещё может изменить.
 -- Вторая — хвост от первого дня, которого в слое нет: первая сборка застаёт
 -- слой пустым и собирает весь стартовый мир, а после разгона мира пачкой слой
 -- догоняет уехавший вперёд источник.
 --
 -- **Хвост считается от первого недостающего дня, а не от последнего
 -- собранного.** Разница не косметическая: замены партиций идут отдельными
 -- задачами и падают порознь, поэтому упавший день оставляет дыру, пока
 -- соседние дни собираются дальше. Считай мы прогресс по максимуму собранного
 -- дня, дыра позади окна не заросла бы никогда, а прогоны продолжали бы
 -- зеленеть над щербатым слоем. Цена честного ответа — проход по дню заказа
 -- в ODS.
 --
 -- Окно читается из ярлыка слепка, а не вычисляется вычитанием окна
 -- изменяемости: у выжившей строки snapshot_date — последний слепок, который
 -- нёс этот заказ (ADR 0014). Поэтому оба края окна знает сам источник, а
 -- копии его константы на стороне стенда больше нет.
 --
 -- FINAL не нужен ни здесь, ни ниже: время рождения заказа у всех его версий
 -- одно, а строки последнего слепка несут максимум колонки версии — мерж
 -- оставляет как раз их.
 WITH
    (SELECT max(snapshot_date) FROM ods.order_dist) AS last_snapshot,
    (
@@ -24,9 +44,10 @@ WITH
        FROM ods.order_dist
        WHERE snapshot_date = last_snapshot
    ) AS window_end,
-    -- GLOBAL NOT IN сравнивает дни со всем DDS. Локальное сравнение могло бы
+    -- GLOBAL обязателен: обе таблицы распределённые, и обычный NOT IN сверял
-    -- счесть день пропущенным, если его заказы находятся на соседнем шарде.
+    -- бы дни источника с локальной частью слоя на каждом шарде — день, чьи
-    -- minOrNull возвращает NULL, когда пропущенных дней нет.
+    -- заказы легли на соседний шард, показался бы недостающим.
    -- minOrNull отличает «дыр нет» от даты по умолчанию.
    (
        SELECT minOrNull(day)
        FROM (
@@ -36,7 +57,7 @@ WITH
        WHERE day GLOBAL NOT IN (SELECT order_date FROM dds.order_dist)
    ) AS first_missing_day
 SELECT
-    -- Начало окна или первый пропущенный день, если он раньше.
+    -- Дыр нет — начинаем с окна; есть — с первой из них, если она старше окна.
    least(window_start, coalesce(first_missing_day, window_start)) AS first_day,
    window_end AS last_day
 WHERE (SELECT count() FROM ods.order_dist) > 0
@@ -1,20 +1,35 @@
-- DDS: расчет сессий за дни от first_day до last_day включительно.
+-- DDS: нарезка событий на визиты и сборка дней в таблицу-двойник.
 -- Сначала очищаем промежуточную таблицу session_stage_rep, затем записываем
 -- в нее рассчитанные строки через session_stage_dist. Основная session_rep
 -- остается прежней до выполнения session_replace.sql.
 --
-- Первое окно помечает событие единицей, если с предыдущего события того же
+-- Двойник очищается целиком в начале, дни собираются одной вставкой на весь
-- посетителя за тот же день прошло больше 1800 секунд. Второе окно суммирует
+-- отрезок — по правилу заказа (sql/dds/order_rebuild.sql).
 -- эти единицы: получается номер визита для каждого посетителя за день.
 -- PARTITION BY (client_id, event_date) считает каждый модельный день отдельно:
 -- события разных дней не попадут в одну сессию даже при короткой паузе.
 -- Учитываются все типы событий.
 --
-- У первого события lagInFrame возвращает его собственное время: разница
+-- Нарезка — центральный расчёт слоя, и стоит она на двух окнах подряд.
-- равна нулю, opens_visit = 0, и первый visit_no тоже равен нулю.
+-- Первое спрашивает у каждого события, сколько прошло с предыдущего события
-- Оба окна используют (event_time, event_id), чтобы при равном времени
+-- той же куки в тот же день, и ставит единицу там, где пауза длиннее
-- отметка начала и номер визита относились к одним событиям.
+-- таймаута: это шов между визитами. Второе считает нарастающий итог этих
-- Порог 1800 секунд — правило визита; он не передается параметром.
+-- единиц — номер визита внутри дня куки. Дальше визит становится обычной
 -- группировкой.
 --
 -- Границу суток окна не проверяют: она уже в разбиении PARTITION BY
 -- (client_id, event_date), поэтому визит через полночь не склеится и при
 -- короткой паузе. Так правило визита ложится в запрос целиком: одна кука,
 -- один день, паузы не длиннее таймаута (CONTEXT.md, «Визит»).
 --
 -- Первое событие куки за день сравнивается само с собой — третий аргумент
 -- lagInFrame. Паузы у него нет, шов ему не нужен, и номер первого визита
 -- получается нулём: номера различают визиты внутри дня куки, а не считают их
 -- от единицы.
 --
 -- Порядок в окнах полный — метка времени и event_id. Окна считаются двумя
 -- разными сортировками (видно в EXPLAIN PIPELINE), и при равных метках они
 -- вправе разойтись: шов достался бы одной строке, а нарастающий итог другой,
 -- и сессия разъехалась бы надвое.
 --
 -- Тридцать минут написаны числом, а не приехали параметром: это правило
 -- аналитики, а не константа мира. Генератор режет визиты тем же порогом;
 -- разойдись эти два числа — увидит счётная сверка с VisitID
 -- (docs/architecture/dds/session.md, «Сверка с эталоном»).
 ALTER TABLE dds.session_stage_rep ON CLUSTER clickstream_cluster DROP PARTITION ALL;
 INSERT INTO dds.session_stage_dist
@@ -78,8 +93,8 @@ WITH
        FROM seams
    )
 SELECT
-    -- Идентификатор зависит от посетителя и начала визита.
+    -- Чекан визита: кука и его начало. Время входит в хеш секундой эпохи,
-    -- Повторная сборка тех же событий дает тот же session_id.
+    -- поэтому id держится за содержание сессии, а не за порядок сборки.
    cityHash64(client_id, min(event_time)),
    client_id,
    event_date,
@@ -92,10 +107,8 @@ SELECT
    countIf(event_type = 'purchase'),
    argMin(url, event_time),
    argMax(url, event_time),
-    -- UTM, устройство и город берутся по минимальному event_time.
+    -- Атрибуция и паспорт куки берутся с первого события визита. У паспорта
-    -- Как и у страниц выше, при равном времени выбор между событиями
+    -- любое событие дало бы то же: устройство и город у куки постоянны.
    -- не определен: event_id в эти argMin/argMax не входит.
    -- Устройство и город на стенде постоянны для одной куки.
    argMin(utm_source, event_time),
    argMin(utm_medium, event_time),
    argMin(utm_campaign, event_time),
@@ -107,7 +120,12 @@ SELECT
    now64(3, 'UTC')
 FROM numbered
 GROUP BY client_id, event_date, visit_no
-- Источник и цель распределены по cityHash64(client_id): локальная вставка
+-- Капкана parallel_distributed_insert_select здесь нет, и это выигрыш
-- сохраняет нужную раскладку, parallel_distributed_insert_select менять
+-- ко-локации: ключ шардирования у источника и цели один — cityHash64 от
-- не требуется. Перед заменой партиций ждем доставки строк на шарды.
+-- куки, — поэтому визит ляжет туда же, где лежали его события, исполнись
 -- вставка хоть на инициаторе, хоть локально на шардах. Заказу приходится
 -- называть ноль вслух: совпадение ключей у него случайное
 -- (sql/dds/order_rebuild.sql). Здесь выбор сделан обратный и он тоже
 -- осознанный: настройку не называть, чтобы не притворяться, будто её значение
 -- что-то решает.
 SETTINGS distributed_foreground_insert = 1;
@@ -1,11 +1,11 @@
-- DDS: заменяем раздел session_rep за выбранный день готовым разделом
+-- DDS: подмена одного дня сессий собранной партицией двойника.
 -- промежуточной session_stage_rep. Раздел таблицы называется партицией.
 -- ON CLUSTER выполняет замену на локальных таблицах каждого шарда.
 -- На одном шарде раздел меняется целиком; общей транзакции для кластера нет.
 -- Повтор с теми же строками session_stage_rep не добавляет копий в session_rep.
 --
-- Дату из session_scope.sql подставляет Jinja: параметр ClickHouse в
+-- Механика и доводы целиком — sql/dds/order_replace.sql: замена идёт по
-- ALTER ... PARTITION здесь не поддерживается. Поиск дней следующего
+-- локальным таблицам, шард за шардом, атомарность пошардовая, день
-- запуска не обнаружит неполный день, если часть его строк уже есть в DDS.
+-- подставляет Jinja, потому что параметров ALTER … PARTITION не берёт.
 --
 -- Разница одна, и она про отказ. Несобранный день заказа вернуло бы в работу
 -- следующее окно; сессиям возвращать нечем, и упавшая замена оставляет дыру
 -- до тех пор, пока её не найдёт счёт хвоста (sql/dds/session_scope.sql).
 ALTER TABLE dds.session_rep ON CLUSTER clickstream_cluster
 REPLACE PARTITION '{{ params.day }}' FROM dds.session_stage_rep;
@@ -1,31 +1,50 @@
-- DDS: дни для сборки сессий, от first_day до last_day включительно.
+-- DDS: объём пересборки сессий — какие дни собирает этот запуск.
 -- Без событий ODS строк в ответе нет; NULL в first_day — дней для расчета нет.
 --
-- position — номер следующего дня для генерации. Последний прожитый день
+-- Ответ — две даты, границы непрерывного отрезка; список дней между ними
-- равен min(EventDate) + position - 1. В отличие от max(EventDate), эта
+-- разворачивает даг. Пустой ответ означает пустой источник. Пустой первый
-- граница исключает еще идущий день. Ранние события ODS не удаляются по TTL,
+-- день — что собирать нечего: все прожитые дни уже в слое, и прогон честно
-- поэтому min(EventDate) сохраняет начало модельного календаря.
+-- пропускает сборку.
 --
-- До этого запроса даг ждет чтения hits и опустошения очереди ods.event_dist.
+-- Файл кончается без точки с запятой: почему — sql/dds/order_scope.sql.
 -- Позиция мира сама по себе не подтверждает доставку событий.
 --
-- Точки с запятой в конце нет: драйвер добавляет FORMAT к этому запросу.
+-- Правый край — последний прожитый день, и знает его только позиция мира.
 -- События живой день от прожитого не отличают: и посреди дня D, и сразу после
 -- его конца max(EventDate) = D. А разница несущая — визит, начатый в 23:50,
 -- посреди дня ещё идёт, и собранная сессия оказалась бы обрезанной навсегда:
 -- пересобирать замёрзший день слой не станет
 -- (docs/architecture/dds/session.md, «Движок и наполнение»).
 --
 -- Позиция — номер первого несыгранного дня, счётчик прожитого. Своей копии
 -- начала оси стенд из-за неё не заводит: начало он спрашивает у данных, и
 -- дата дня N в них — константа, начало оси плюс N. Держится якорь на том, что
 -- ранние дни из ods.event не исчезают: срок жизни назначен сырым данным и таблицам
 -- ошибок, самому событию — нет (sql/ddl/20-ods-tables.sql).
 --
 -- За «доехал» позиция не отвечает — только за «прожит». Перед расчётом объёма
 -- первый шаг дага дожидается хвоста потока и очереди доставки: иначе
 -- недожеванный хвост заморозил бы недособранный день
 -- (docs/architecture/etl.md, «Готовность источника»).
 WITH
    (SELECT min(EventDate) FROM ods.event_dist) AS first_source_day,
    first_source_day + ({position:UInt16} - 1) AS last_lived_day,
-    -- Ищем первую дату событий ODS, за которую еще нет сессий DDS.
+    -- Хвост считается от первой дыры, а не от последнего собранного дня:
-    -- Поиск после max(session_date) пропустил бы более раннюю потерянную дату.
+    -- замены партиций падают порознь, и счёт по максимуму собранного дня
-    -- Если за день есть хотя бы одна сессия, он уже не считается пропущенным.
+    -- дыру позади себя не заметил бы (доводы целиком — sql/dds/order_scope.sql).
-    -- GLOBAL берет даты сессий со всех шардов.
+    -- У сессий это единственный способ дыру найти: дышащего окна, которое
-    -- minOrNull возвращает NULL, если пропусков нет.
+    -- пересобрало бы день заодно, здесь нет.
    --
    -- GLOBAL обязателен: обе таблицы распределённые, и обычный NOT IN сверял
    -- бы дни источника с локальной частью слоя на каждом шарде.
    -- minOrNull отличает «дыр нет» от даты по умолчанию.
    (
        SELECT minOrNull(day)
        FROM (SELECT DISTINCT EventDate AS day FROM ods.event_dist)
        WHERE day GLOBAL NOT IN (SELECT session_date FROM dds.session_dist)
    ) AS first_missing_day
 SELECT
-    -- Отсутствующий день попадет в сборку только после его завершения.
+    -- Живой день в слое отсутствует всегда, и работой это не считается:
    -- дырой он станет, только когда мир его проживёт.
    if(first_missing_day <= last_lived_day, first_missing_day, NULL) AS first_day,
    last_lived_day AS last_day
-- FINAL не нужен: повтор доставки не меняет начало календаря и набор дат.
+-- FINAL не нужен: повтор доставки не двигает ни край оси, ни набор дней.
 WHERE (SELECT count() FROM ods.event_dist) > 0
@@ -1,10 +1,7 @@
-- DM: расчет выручки за дни от first_day до last_day включительно.
+-- DM: сборка выручки в донор перед заменой дневных партиций.
-- DROP PARTITION ALL очищает промежуточную revenue_daily_stage_rep.
+-- DROP PARTITION ALL очищает локальные таблицы на каждом узле; причина не
-- Затем INSERT записывает по одной строке итогов на день и категорию товара.
+-- применять TRUNCATE разобрана в соседнем sql/dds/order_rebuild.sql.
-- Основная revenue_daily_rep остается прежней до revenue_daily_replace.sql.
+
 -- В расчет входят только оплаченные заказы. ARRAY JOIN превращает артикул,
 -- количество и цену с одним индексом в массивах в одну строку позиции заказа.
 -- Причина выбора DROP вместо TRUNCATE — в sql/dds/order_rebuild.sql.
 ALTER TABLE dm.revenue_daily_stage_rep ON CLUSTER clickstream_cluster
 DROP PARTITION ALL;
@@ -25,8 +22,8 @@ SELECT
    orders,
    units,
    CAST(revenue, 'Decimal(18, 2)'),
-    -- Делим с шестью знаками после запятой, затем округляем до копеек.
+    -- Обычное деление Decimal усекает доли копейки вместо округления;
-    -- Так дробная часть сохраняется до округления среднего чека.
+    -- запас масштаба сохраняет их до денежного результата.
    CAST(
        round(divideDecimal(revenue, toDecimal128(orders, 0), 6), 2),
        'Decimal(18, 2)'
@@ -52,8 +49,7 @@ FROM
        report_date,
        product_category
 )
-- Источник распределен по заказу, цель — по категории. Значение 0 оставляет
+-- Источник лежит по заказу, цель — по категории. Ноль заставляет инициатор
-- итоговую агрегацию и распределение по ключу цели на ноде, принявшей запрос.
+-- слить частичные агрегаты и разложить готовые строки по ключу цели.
 -- distributed_foreground_insert = 1 ждет доставки строк перед заменой.
 SETTINGS distributed_foreground_insert = 1,
    parallel_distributed_insert_select = 0;
@@ -1,9 +1,8 @@
-- DM: заменяем раздел revenue_daily_rep за выбранный день готовым разделом
+-- DM: подмена одного дня выручки готовой партицией донора.
-- промежуточной revenue_daily_stage_rep. Раздел таблицы называется партицией.
+--
-- Дату из revenue_daily_scope.sql подставляет Jinja: параметр ClickHouse
+-- День приходит из результата revenue_daily_scope.sql, а не от пользователя.
-- в ALTER ... PARTITION здесь не поддерживается.
+-- Jinja нужна потому, что ClickHouse не подставляет параметр в PARTITION.
-- ON CLUSTER выполняет замену на локальных таблицах каждого шарда.
+-- Замена идет на локальной таблице ON CLUSTER: граница атомарности и повтор
-- На одном шарде раздел меняется целиком; общей транзакции для кластера нет.
+-- разобраны на таком же шаге в sql/dds/order_replace.sql.
 -- Повтор с теми же строками промежуточной таблицы не добавляет копий в основной.
 ALTER TABLE dm.revenue_daily_rep ON CLUSTER clickstream_cluster
 REPLACE PARTITION '{{ params.day }}' FROM dm.revenue_daily_stage_rep;
@@ -1,11 +1,14 @@
-- DM: диапазон пересборки выручки, first_day и last_day включительно.
+-- DM: объем пересборки выручки.
 -- Последний слепок ODS задает даты оформления заказов, которые еще могут
 -- измениться. Саму выручку считаем по DDS; ODS нужен только для выбора дат.
 -- Левая граница расширяется до первого дня с оплаченными заказами DDS,
 -- которого нет в витрине. Так первый запуск охватывает историю выручки.
 -- По наличию даты нельзя обнаружить частично заполненный день.
 --
-- Точки с запятой в конце нет: драйвер добавляет FORMAT к этому запросу.
+-- Последний слепок ODS называет дни, состояние которых источник еще может
 -- изменить. Сам агрегат читает только DDS; ODS здесь нужен лишь для границ.
 -- Первый запуск и повтор после частичного отказа расширяют левую границу до
 -- первого дня оплаченных заказов, которого еще нет в витрине.
 -- Почему хвост начинается с первого пропуска и чем за это платит ODS,
 -- разобрано в sql/dds/order_scope.sql.
 --
 -- Файл кончается без точки с запятой: даг читает его одним запросом и ждет
 -- одну строку с границами.
 WITH
    (SELECT max(snapshot_date) FROM ods.order_dist) AS last_snapshot,
    (
@@ -21,7 +24,8 @@ WITH
    (
        SELECT minOrNull(report_date)
        FROM (SELECT DISTINCT order_date AS report_date FROM dds.order_v WHERE status = 'paid')
-        -- GLOBAL собирает список дней витрины со всех шардов.
+        -- Правая сторона тоже распределенная: GLOBAL собирает множество дней
        -- на инициаторе и не превращает запрос в запрещенное двойное чтение.
        WHERE report_date GLOBAL NOT IN (
            SELECT report_date FROM dm.revenue_daily_dist
        )
@@ -29,7 +33,7 @@ WITH
 SELECT
    least(window_start, coalesce(first_missing_day, window_start)) AS first_day,
    window_end AS last_day
-- Для выбора диапазона нужны заказы в ODS, для расчета — в DDS.
+-- Без ODS неизвестно окно. Без готового DDS донор останется пустым, а замена
-- Эта проверка наличия строк не подтверждает полноту источников.
+-- сотрет уже собранные дни выручки. Поэтому для прогона нужны оба источника.
 WHERE (SELECT count() FROM dds.order_v) > 0
    AND (SELECT count() FROM ods.order_dist) > 0
@@ -1,15 +1,24 @@
-- Разбор сохраненной порции заказов: сначала годные версии, затем ошибки.
+-- Разбор одного среза заказов: сначала годные версии, затем брак.
 -- Макрос Jinja подставляет одно условие годности в обе вставки.
 -- Вторая вставка берет его отрицание, чтобы каждая строка получила результат.
 -- Условие должно давать только 0 или 1 и не вызывать исключений на неверном raw.
 --
-- Проверяются одиннадцать полей верхнего уровня. Внутри items поля не проверяются;
+-- Обе вставки должны делить один предикат. Локальный макрос Jinja
-- позиции разбирает DDS, а равенства сумм проверяются отдельно.
+-- разворачивает его в каждое выражение до того, как оператор разделит файл по
-- Точные правила — docs/architecture/orders/ingestion.md, «Граница строгого приёма».
+-- точкам с запятой. Так контракт остаётся рядом с запросами и не становится
 -- третьим SQL-файлом, который нельзя исполнить самостоятельно.
 --
 -- Строгий приём проверяет форму провода и ничего сверх неё. Ключей одиннадцать,
 -- и проверяются все: десять скалярных значений прямо образуют типизированную
 -- строку заказа. Внутрь items приём не смотрит — содержимое позиций, переходы
 -- статуса и равенства сумм остаются ниже этой границы
 -- (docs/architecture/orders/ingestion.md, «Граница строгого приёма»).
 --
 -- У общего предиката два обязательных свойства. Он всегда даёт 0 или 1, не
 -- NULL: иначе строку не возьмут ни условие, ни его отрицание. И он не бросает
 -- исключений на произвольном raw: одна грязная строка не должна ронять весь
 -- переход, ради этого и существует таблица брака.
 {% macro order_wire_contract() %}
 WITH
-    -- Время источника: UTC, ровно три знака долей секунды.
+    -- Каноническое время провода: UTC, ровно три знака долей секунды.
    'yyyy-MM-dd\'T\'HH:mm:ss.SSS\'Z\'' AS ts_mask,
    JSONType(raw) = 'Object' AS is_object,
    arraySort(JSONExtractKeys(raw)) = arraySort([
@@ -19,14 +28,15 @@ WITH
    ]) AS keys_match,
    JSONType(raw, 'order_id') = 'String'
        AND JSONType(raw, 'status') = 'String'
-        -- JSONType различает Int64 и UInt64; принимаются оба, если значение
+        -- Целое у JSONType зовётся двумя именами, и нужны оба: с одним
-        -- разбирается в UInt64, в том числе идентификаторы больше 2^63−1.
+        -- Int64 законный идентификатор за 2^63 уехал бы в брак.
        AND JSONType(raw, 'user_id') IN ('Int64', 'UInt64')
        AND JSONExtract(raw, 'user_id', 'Nullable(UInt64)') IS NOT NULL
        AND JSONType(raw, 'items') = 'Array'
-        -- Регулярное выражение проверяет точную форму, включая ведущие нули.
+        -- Форму держит регулярка, реальность — разбор, и порознь они дырявы:
-        -- Разбор проверяет само время: например, отвергает 30 февраля.
+        -- маска берёт «2026-6-3T…» без ведущих нулей, а регулярка пропускает
-        -- Замеры функций — docs/architecture/storage.md, «Что проверено».
+        -- 30 февраля. Обе половины измерены — docs/architecture/storage.md,
        -- «Что проверено».
        AND arrayAll(k ->
                JSONType(raw, k) = 'String'
                AND match(JSONExtractString(raw, k),
@@ -34,8 +44,9 @@ WITH
                AND parseDateTime64InJodaSyntaxOrNull(
                    JSONExtractString(raw, k), ts_mask, 'UTC') IS NOT NULL,
            ['created_at', 'updated_at'])
-        -- Сумма в рублях: строка с двумя знаками после точки, без минуса.
+        -- Деньги — строка с ровно двумя знаками после точки. Регулярка держит
-        -- После проверки формы проверяется возможность разбора в Decimal.
+        -- форму, разбор — вместимость: у строки из двадцати девяток форма
        -- хороша, а в Decimal(18, 2) она не влезает.
        AND arrayAll(k ->
                JSONType(raw, k) = 'String'
                AND match(JSONExtractString(raw, k), '^\\d+\\.\\d{2}$')
@@ -49,9 +60,11 @@ WITH
    is_object AND keys_match AND fields_valid AS row_is_valid
 {% endmacro %}
-- Годные строки сохраненного среза по _load_id запуска приема.
+-- Годные версии заказа. Срез читается по _load_id — тому же, что проставил
-- WHERE исключает строки с NULL в разобранных полях; assumeNotNull
+-- забор: разбор идёт по неизменной порции, а не по «всему, что появилось».
-- приводит оставшиеся значения к типам целевой таблицы.
+--
 -- Разобранные значения берёт assumeNotNull: обнуляемый разбор стоит за
 -- предикатом, который NULL уже отсёк, и приведение здесь не может упасть.
 INSERT INTO ods.order_dist
 {{ order_wire_contract() }}
@@ -68,25 +81,30 @@ SELECT
    assumeNotNull(toDecimal64OrNull(JSONExtractString(raw, 'discount'), 2)) AS discount,
    assumeNotNull(toDecimal64OrNull(JSONExtractString(raw, 'delivery'), 2)) AS delivery,
    assumeNotNull(toDecimal64OrNull(JSONExtractString(raw, 'total'), 2)) AS total,
-    -- items сохраняется строкой JSON для разбора позиций в DDS.
+    -- items кладётся сырым фрагментом JSON, а не разобранной структурой.
    JSONExtractRaw(raw, 'items') AS items,
    toDate(assumeNotNull(parseDateTimeInJodaSyntaxOrNull(
        JSONExtractString(raw, 'snapshot_date'),
        'yyyy-MM-dd', 'UTC'))) AS snapshot_date,
-    -- _load_ts остается временем приема в STG; _load_id связывает с исходной порцией.
+    -- Метки запуска и прибытия переносятся как есть. Поставь здесь now64(3) —
    -- и _load_ts молча ответила бы на другой вопрос: «когда разобрали».
    _load_id,
    _load_ts
 FROM stg.orders_raw_dist
 WHERE _load_id = {load_id:String} AND row_is_valid
-- Ноль заставляет распределить результат по ключу цели. При значении 2
+-- Заводская двойка parallel_distributed_insert_select исполняет вставку из
-- вставка может сохранить раскладку STG, где ключ — raw, вместо order_id.
+-- Distributed в Distributed локально на каждом шарде, минуя ключ шардирования
-- Подробнее — docs/architecture/storage.md, «Раскладка по шардам».
+-- цели, — так заказы и расползлись по обоим шардам. Ноль отдаёт раскладку
 -- инициатору, по ключу цели. Капкан целиком — docs/architecture/storage.md,
 -- «Раскладка по шардам».
 SETTINGS distributed_foreground_insert = 1,
    parallel_distributed_insert_select = 0;
-- Ошибки: тот же срез и отрицание условия годности.
+-- Брак: тот же срез и буквальное отрицание того же предиката.
-- Класс определяется первым нарушенным условием: например, JSON-строка
+--
-- не проходит и проверку объекта, и проверку ключей, но получает not_an_object.
+-- Классы перекрываются, поэтому проверяются по порядку, а в error_class идёт
 -- первый совпавший: скаляр проваливает и проверку на объект, и сверку ключей —
 -- без объявленного порядка он попал бы то в один класс, то в другой.
 INSERT INTO ods.order_errors_dist
 {{ order_wire_contract() }}
@@ -106,6 +124,7 @@ SELECT
    _load_ts
 FROM stg.orders_raw_dist
 WHERE _load_id = {load_id:String} AND NOT row_is_valid
-- Та же настройка: распределяем строки по ключу целевой таблицы ошибок.
+-- Тот же ноль: ключ брака сегодня совпадает с ключом STG, и локальная
 -- запись легла бы верно — но по совпадению, а не по контракту.
 SETTINGS distributed_foreground_insert = 1,
    parallel_distributed_insert_select = 0;
@@ -1,11 +1,15 @@
-- Порция сообщений заказов из Kafka в STG, без разбора JSON.
+-- Забор порции слепка заказов из Kafka в STG.
 -- Один SELECT читает одну порцию; непрочитанное остается до следующего запуска.
 -- Полнота слепка не проверяется. Если после чтения вставка упадет, подтвержденные
 -- сообщения уже не перечитаются (docs/architecture/orders/ingestion.md).
 --
-- stream_like_engine_allow_direct_select разрешает прямое чтение Kafka;
+-- Забор — один прямой SELECT, без цикла до пустоты: одна порция ClickHouse
-- kafka_commit_on_select включен в sql/ddl/10-stg-tables.sql.
+-- берёт десятки тысяч сообщений, а слепок дня — порядка полутора тысяч строк.
-- distributed_foreground_insert = 1 ждет записи на шарды до завершения задачи.
+-- Короткая порция оставит хвост до следующего прогона, а отказ после чтения
 -- унесёт прочитанное с собой: офсеты коммитятся в момент чтения. Граница
 -- целиком — ADR 0008, «Следствия».
 --
 -- stream_like_engine_allow_direct_select разрешает читать чтеца запросом; вторая
 -- половина пары объявлена на самой таблице (sql/ddl/10-stg-tables.sql).
 -- distributed_foreground_insert = 1 — конвенция ETL-вставок стенда: задача не
 -- должна зеленеть раньше, чем строки легли на шарды.
 INSERT INTO stg.orders_raw_dist
 SELECT