Merge pull request 'docs(labs): история связей и инкрементальное обновление витрины' (#256) from labs/identity-incremental into main

Reviewed-on: #256

.env.example

@@ -10,6 +10,7 @@ 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

AGENTS.md

@@ -46,15 +46,10 @@
 
 ## Кому что поручать
 
-Читатель здесь не побочный потребитель, а тот, ради кого стенд существует:
+Автор задачи сам пишет и редактирует код, комментарии и документы, если
-код, комментарии и документы и есть продукт. Поэтому всё, что человек будет
+владелец не задал другое распределение работы.
-читать и разбирать, пишет модель с чувством меры — сейчас это Opus. Codex
-берёт техническую работу без вкусовых решений: миграции, разбор журналов и
-объёмного вывода, обход репозитория, повторяющиеся правки. Там его запас
-лимитов работает на нас, а экономить их на читаемом коде — экономия ложная:
-переписывать выйдет дороже, чем сразу написать хорошо.
 
-Делить работу между ними стоит не целыми задачами, а подзадачами, и решать
+Делить работу стоит не целыми задачами, а подзадачами, и решать
 это при планировании. Вкусовая часть идёт первой: она задаёт форму, имена и
 границы, под которые механическая потом подстраивается.
 

README.md

@@ -121,6 +121,9 @@ Kafka, затем заново создаст схему хранилища и
 Для подключения ко второму узлу укажите порт `28124`.
 
 Пользователь `analyst` может читать данные во всех слоях и справочниках.
+Для заданий с собственными таблицами наблюдений используйте `student` и пароль
+из `CLICKHOUSE_STUDENT_PASSWORD` в `.env`. Он читает те же источники, а создавать,
+заполнять и удалять таблицы может только в базе `default`.
 Для создания учебных витрин используйте подключение, описанное
 в [инструкции к заданиям](docs/labs/README.md#как-применить-свой-ddl).
 Нативные порты `29000` и `29001` нужны `clickhouse-client`, но не DBeaver.

compose.yaml

@@ -20,6 +20,7 @@ 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:

dags/dq_check.py

@@ -74,7 +74,11 @@ def _publish_summary(
 ) -> list[str]:
     """Записать дневную сводку и вернуть малый срез готовой диагностики."""
     if not summaries:
-        raise AirflowException(f"{check_name}: область проверки пуста")
+        raise AirflowException(
+            f"{check_name}: запрос не вернул ни одного дня для проверки; "
+            "проверьте наличие данных в источниках сверки. Состав проверок "
+            "описан в docs/architecture/dm.md"
+        )
 
     diagnostics: list[str] = []
     context = get_current_context()
@@ -148,7 +152,10 @@ def build_classes_vs_inventory() -> list[str]:
         for mismatch_class, count in day["orders"].items()
     }
     if not expected:
-        raise AirflowException("classes_vs_inventory: в паспорте нет закрытых дней")
+        raise AirflowException(
+            "classes_vs_inventory: в data/world-inventory.json нет счетчиков "
+            "заказов для закрытых дней; сообщите наставнику"
+        )
 
     query = (SQL_ROOT / "dq" / "classes_vs_inventory.sql").read_text(encoding="utf-8")
     # GROUP BY закономерно не возвращает группу из нуля строк.
@@ -179,9 +186,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} key={mismatch_class}: "
+                    f"{day} mismatch_class={mismatch_class}: "
-                    f"эталон={reference_count}, "
+                    f"заказов в паспорте={reference_count}, "
-                    f"объект={actual_text}"
+                    f"в dm.purchase_vs_orders_v={actual_text}"
                 )
         summaries.append((data_date, reference_rows, actual_rows, failed_rows, details))
     return _publish_summary("classes_vs_inventory", summaries)
@@ -194,7 +201,10 @@ 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("донор dm.dq_summary пуст: публиковать нечего")
+        raise AirflowException(
+            "dm.dq_summary_stage_dist пуста: нет результатов для записи "
+            "в сводку DQ; проверьте журналы задач build_* этого запуска"
+        )
     return [{"params": {"day": data_date.isoformat()}} for (data_date,) in rows]
 
 
@@ -239,10 +249,15 @@ 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}, нарушено {failed_rows}"
+        f"ключей в проверяемом объекте {actual_rows}, "
+        f"отсутствуют или различаются {failed_rows}"
         for data_date, reference_rows, actual_rows, failed_rows in failed_days
     )
-    raise AirflowException(f"{check_name}: {summary}")
+    raise AirflowException(
+        f"{check_name}: {summary}. Примеры расхождений — в журнале этой задачи; "
+        "итоги по дням — в dm.dq_summary_v. Источники каждой сверки описаны "
+        "в docs/architecture/dm.md"
+    )
 
 
 @dag(

dags/homework_check.py

@@ -45,7 +45,10 @@ def check_mart(
     """Сверить одну домашнюю витрину с независимым ответом из источника."""
     hook = _clickhouse_hook()
     if not _mart_exists(hook, mart):
-        raise AirflowException(f"витрина {mart} не найдена; выполните ТЗ {lab_path}")
+        raise AirflowException(
+            f"витрина {mart} не найдена на узле подключения clickhouse_default; "
+            f"проверьте имя и место создания витрины по заданию {lab_path}"
+        )
 
     try:
         query = (SQL_ROOT / sql_name).read_text(encoding="utf-8")
@@ -72,7 +75,8 @@ 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)
@@ -93,7 +97,8 @@ def check_mart(
     compared_sides = diagnostics[0]
     raise AirflowException(
         f"витрина {mart} расходится с источником: {days}. "
-        f"Пример сравнения: {compared_sides}. Сверьтесь с ТЗ {lab_path}"
+        f"Пример сравнения: {compared_sides}. Другие примеры — в журнале этой "
+        f"задачи. Проверьте расчет для указанных ключей по заданию {lab_path}"
     )
 
 

dags/orders_ingest.py

@@ -1,18 +1,13 @@
-"""Приём заказов: пакетный забор слепка из Kafka в хранилище.
+"""Пакетный прием заказов: Kafka → STG → ODS.
 
-Путь Kafka → STG → ODS у заказов один и живёт одним дагом: сначала забор
+Шаговый даг модельного времени отправляет слепок, запускает orders_ingest
-порции в `stg`, затем разбор того же среза в типизированный ODS и в таблицу
+и ждет его завершения. Собственного расписания у orders_ingest нет.
-брака. Расписания у дага нет: его дёргает тот, кто положил слепок в топик, —
+Сначала 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
@@ -24,8 +19,7 @@ from airflow.sdk import dag
 
 START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
 
-# Запросы лежат файлами в sql/ репозитория, разложенные по слоям хранилища;
+# Compose монтирует sql/ по этому пути во все службы Airflow.
-# сюда их монтирует compose — всем службам Airflow сразу.
 SQL_ROOT = "/opt/airflow/sql"
 
 
@@ -34,15 +28,14 @@ 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",
@@ -59,8 +52,8 @@ def orders_ingest():
         do_xcom_push=False,
     )
 
-    # ClickHouse не даёт транзакции между двумя вставками parse_batch. Один
+    # Две вставки parse_batch не образуют транзакцию. Повтор задачи
-    # task_id сохраняет их порядок и одну точку повтора для неизменного load_id.
+    # выполняет обе над тем же срезом STG по _load_id.
     pull_batch >> parse_batch
 
 

dags/world_control.py

@@ -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 → "
+                "за один день. События отправляются без пауз. Номер первого дня "
-                "Variables). Поля Logical date и Run ID нужны самому Airflow "
+                "берется из `world_position` (Admin → Variables). Поля Logical "
-                "и на выбор дня не влияют."
+                "date и Run ID не меняют выбор дня. После завершения запустите "
+                "`etl_pipeline`, чтобы обновить DDS и витрины DM."
             ),
         )
     },
 )
 def world_next_day():
-    """Прожить следующие дни пачкой, без пауз.
+    """Создать данные за следующие модельные дни без пауз между событиями.
 
-    Запускается руками. День по умолчанию один, но разгон вперёд идёт одним
+    Параметр `days` задает число дней: от 1 до 7, по умолчанию 1. Первый день
-    нажимом, а не десятью: сколько дней играть — параметр запуска. Первый
+    берется из `world_position`. После загрузки событий и слепков заказов
-    день шаговый даг берёт из `world_position`. Логическая дата прогона на выбор
+    запустите `etl_pipeline` вручную, чтобы обновить DDS и витрины DM.
-    дня не влияет.
     """
 
     @task
@@ -174,7 +174,10 @@ def world_next_day():
         position = first_day + days
         Variable.set(WORLD_POSITION, str(position))
         logging.info(
-            "дни %s–%s сыграны; новая позиция — %s", first_day, position - 1, position
+            "данные за модельные дни %s–%s отправлены; world_position=%s",
+            first_day,
+            position - 1,
+            position,
         )
 
     first_day = first_unplayed_day()
@@ -210,20 +213,23 @@ def world_next_day():
     tags=TAGS,
 )
 def world_live_day():
-    """Прожить следующий день в темпе модельного времени.
+    """Постепенно отправить события за следующий модельный день.
 
-    Ускорение ×60: модельные сутки укладываются примерно в двадцать четыре
+    При ускорении ×60 отправка занимает около 24 реальных минут. Номер дня
-    реальные минуты, и суточная волна разворачивается на глазах. Запускается
+    берется из `world_position`; Logical date его не меняет. Затем даг
-    руками; чтобы мир жил так день за днём сам, есть выключатель `world_live`.
+    отправляет слепок заказов и ждет его загрузки и завершения `etl_pipeline`.
-    Следующий день шаговый даг берёт из `world_position`. Логическая дата прогона
+    Для автоматического запуска следующих дней снимите с паузы `world_live`.
-    на выбор дня не влияет.
     """
 
     @task
     def remember_played(first_day: int) -> None:
         """Позиция ставится по сыгранному дню и только по успеху."""
         Variable.set(WORLD_POSITION, str(first_day + 1))
-        logging.info("сыгран день %s; новая позиция — %s", first_day, first_day + 1)
+        logging.info(
+            "данные за модельный день %s отправлены; world_position=%s",
+            first_day,
+            first_day + 1,
+        )
 
     first_day = first_unplayed_day()
     played = _generator("play_day", ["live", "--day", PLAYED_DAY])
@@ -254,16 +260,12 @@ def world_live_day():
     tags=TAGS,
 )
 def world_live():
-    """Выключатель: пока включён, мир живёт день за днём.
+    """Автоматически запускать модельные дни, пока даг снят с паузы.
 
-    Своей работы у выключателя нет — он дёргает `world_live_day` и ждёт конца.
+    Запускает `world_live_day` и ждет его завершения. Пауза останавливает
-    Ожидание тут несущая конструкция, а не вежливость: без него тик шёл бы
+    запуск следующих дней; уже запущенный день завершится. Если он завершился
-    независимо от хода дня, лишние прогоны скопились бы очередью, и мир потом
+    с ошибкой, этот даг тоже завершится с ошибкой: откройте дочерний запуск
-    промчался бы по ней без всякого темпа.
+    и журнал неуспешной задачи.
-
-    Ждём триггером, а не сенсором: оператор опрашивает тот прогон, который сам
-    и создал, и ссылка на дочерний прогон видна прямо отсюда. Упал день —
-    краснеет и выключатель.
     """
     TriggerDagRunOperator(
         task_id="trigger_live_day",

docs/adr/0007-clickhouse-access.md

@@ -3,10 +3,11 @@
 Дата: 9 августа 2026 года. Статус: принято; роль `monitoring_reader`
 и пользователь `grafana` добавлены 21 августа 2026 года (#114), права
 `bi_reader` расширены до ODS, DDS и DM 25 августа 2026 года (#150).
+Пользователь `student` и роль `student_writer` добавлены 22 сентября 2026 года.
 
 ## Решение
 
-У кластера семь пользователей и шесть ролей.
+У кластера восемь пользователей и семь ролей.
 
 - `default` — с паролем, только служебный: проверки здоровья нод и работа
   изнутри контейнеров. Приложения им не ходят.
@@ -20,6 +21,10 @@
   шире.
 - `analyst` с ролью `analyst_reader` — чтение всех слоёв и справочников. Им
   человек подключается снаружи, из своего клиента.
+- `student` с ролями `analyst_reader` и `student_writer` — то же чтение и
+  работа со своими таблицами в `default`: создание, вставка и удаление.
+  Сохранение учебных наблюдений не требует прав технической учётной записи
+  `etl` на изменение слоёв. Таблицы локальные; работа ведётся на одной ноде.
 - `grafana` с ролью `monitoring_reader` — чтение слоёв, таблиц базы `dic` и
   системных таблиц, `CLUSTER` и `REMOTE`. Им ходит Grafana, и больше никто.
 - `dict` с ролью `dict_reader` — чтение одной базы `dic`, пароля нет. Им
@@ -148,6 +153,11 @@ 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.
 

docs/architecture/dds/identity.md

@@ -30,7 +30,7 @@
 `first_matched_at` нет. Запланированные витрины его не читают, а два возможных
 смысла — «первая покупка вообще» и «момент, с которого связь была известна
 хранилищу» — требуют разных исторических моделей. Этот вопрос оставлен
-[самостоятельной работе](https://git.dementev.space/ddmitry/clickstream-data-platform/issues/145),
+[самостоятельной работе](../../labs/optional/identity-over-time.md),
 а текущий стенд не выдаёт один смысл за другой.
 
 Статус заказа связь не меняет: любой заказ, сопоставленный с событием покупки,

docs/architecture/dds/order.md

@@ -1,134 +1,113 @@
 # Модель заказа в DDS
 
-Учебный результат: менти проектирует бизнес-сущность поверх готового ODS —
+DDS готовит заказ для анализа: выбирает текущее состояние из ODS,
-выбирает зерно, состав строки и способ наполнения — и видит идемпотентность
+разбирает позиции и переводит время в часовой пояс счетчика. Этот слой
-трансформации, устроенную иначе, чем в приёме: заменой партиции, а не
+показывает, как собрать модель данных для витрин и повторить загрузку
-версиями.
+без удвоения заказов.
 
 ## Зерно
 
-Одна строка — заказ в текущем состоянии, ключ — `order_id`. Модель отвечает
+Одна строка — один заказ в последнем известном состоянии, ключ — `order_id`.
-на вопрос «что сейчас известно о заказе»; историю версий не хранит:
+История изменений здесь не хранится. ODS тоже не служит ее архивом:
-читателя у истории нет ни в одной витрине, а ODS её и не обещает —
+промежуточные версии удаляются при фоновых слияниях.
-промежуточные версии съедают фоновые слияния. «Дыхание» выручки внутри окна
-K живёт на текущем состоянии само: пересборка дня меняет статусы заказов, и
-число дня меняется вместе с ними.
 
 ## Состав строки
 
-Деловые поля источника переезжают из `ods.order_v` без переименований —
+Поля заказа приходят из `ods.order_v` с именами источника: `order_id`,
-бэкенд уже говорит в snake_case: `order_id`, `user_id`, `status`, деньги в
+`user_id`, `status`, `items_total`, `discount`, `delivery`, `total`.
-`Decimal` (`items_total`, `discount`, `delivery`, `total`).
+Денежные колонки хранят рубли с копейками в `Decimal(18, 2)`.
 
-Времена `created_at` и `updated_at` пересчитываются при загрузке в пояс
+`created_at` и `updated_at` переводятся из UTC в `Europe/Samara`, пояс
-счётчика: DDS обслуживает человека с дашбордом ([дока
+счетчика сайта. Из `created_at` в этом поясе вычисляется `order_date` —
-хранилища](../storage.md), «Часовые пояса»). Там же один раз считается
+день оформления заказа. Витрины группируют по готовой дате;
-**день заказа** — колонка `order_date`, по образцу `EventDate` у события:
+правило времени общее для [хранилища](../storage.md#часовые-пояса).
-суточные срезы группируются по готовой дате и пояса не упоминают.
 
-Позиции разобраны из сырой строки `items` в три типизированных массива
+Строка `items` из ODS разбирается в три массива одной длины:
-одной длины — артикул, количество, цена (`Decimal`). Это родная для
+
-ClickHouse денормализация: позиция не живёт без заказа и собственного ключа
+| Колонка | Что хранит |
-не имеет, а разворачивает массивы читатель — `ARRAY JOIN` в витрине
+|---|---|
-выручки, с обогащением категорией через `dictGet`
+| `item_sku` | Артикулы товаров |
-([мастер-спека](../../specs/2026-07-30-stand-v2-realism.md), раздел 7). Разбор
+| `item_quantity` | Количество каждого товара, `UInt32` |
-JSON происходит один раз, на границе ODS → DDS, куда его и положила спека
+| `item_price` | Цены за единицу в рублях, `Decimal(18, 2)` |
-(раздел 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: это единственный устойчивый ключ сущности.
+как в ODS. Для чтения служит `dds.order_v` с явным списком колонок
+над `dds.order_dist`; `FINAL` в этом слое не нужен.
 
-Идемпотентность держит замена партиции, а не версии. Сбор дня — батч после
+Даг `dds_transform` пересобирает выбранные дни из `ods.order_v`:
-прихода слепка: трансформация собирает партицию заново из `ods.order_v` и
-атомарно подменяет. Поэтому каждая строка физической таблицы — ровно один
-заказ, а чтению не нужен `FINAL`. Пока окно K живо, день «дышит» — статусы
-заказов меняются, и партиция дня пересобирается очередным запуском; на выходе
-из окна день замерзает.
 
-Публичная поверхность — `dds.order_v`: обычное представление с явным списком
+1. [`order_scope.sql`](../../../sql/dds/order_scope.sql) определяет
-деловых и собственных служебных колонок над `dds.order_dist`, без `FINAL`.
+   непрерывный отрезок `first_day`…`last_day`. Он включает дни заказов
-Роли объектов и доступ следуют общей [конвенции](../storage.md), «Имена
+   из последнего слепка и начинается раньше, если в DDS отсутствует
-объектов».
+   день, который есть в 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` запуска трансформации, собравшего
+`_load_id` и `_load_ts` показывают, какой запуск DDS собрал строку
-её партицию, — по общей конвенции хранилища. При замене партиции они
+и когда он выполнил вставку. Они одинаковы у строк одной сборки.
-одинаковы у всех строк дня и отвечают на вопрос «каким запуском и когда
+При следующей пересборке эти метки обновятся, даже если заказ не изменился.
-собран этот день».
 
-Ярлыки ODS (`snapshot_date`, `_load_id` приёма, `_load_ts` прибытия) в модель
+`snapshot_date` и метки приема ODS в DDS не переносятся: они описывают
-не переезжают. Они описывают наблюдение и доставку строки в ODS. Модель DDS
+получение сообщения источника. Их можно найти в ODS по `order_id`.
-хранит текущее деловое состояние заказа. В ODS `snapshot_date` задаёт версию и
+В каждом слое служебные колонки относятся к его собственной загрузке.
-называет последний слепок, в котором источник показал заказ
-([ADR 0014](../../adr/0014-order-version-snapshot-date.md)). Дату
-наблюдения и координаты доставки читатель спрашивает у ODS по
-`order_id`. Правило слоя:
-**служебные колонки — координаты собственной загрузки слоя; чужие координаты
-спрашиваются у их слоя по ключу сущности**.
 
-Происшествие качества данных расследуется цепочкой, где каждый шаг спрашивает
+При поиске ошибки начните с `_load_id` в DDS: он указывает на запуск
-свой слой на его языке: по `_load_id` строки DDS видно, какой запуск собрал
+сборки. По `order_id` найдите версии заказа в ODS, а по их `_load_id` —
-день; по `order_id` ODS показывает физические версии и брак — там свой
+соответствующие сырые сообщения в STG и ошибки того же приема.
-`_load_id` приёма связывает годные строки, ошибки и данные STG; дальше читают
+В таблице ошибок `order_id` может быть не разобран, поэтому нужное
-STG, пока данные живы. Окно расследования задано сроками хранения: сырые данные
+сообщение ищут по `raw` и координатам Kafka.
-— трое суток, брак — месяц ([дока хранилища](../storage.md)).
+Сырые сообщения хранятся около трех реальных суток, ошибки — месяц;
+уточнения к срокам — в [справочнике хранилища](../storage.md#срок-жизни-сырых-данных).
 
 ## Читатели
 
-- Витрина выручки `dm.revenue_daily_v`: заказы в `paid`, `ARRAY JOIN`
+- `dm.revenue_daily_v` считает выручку по заказам со статусом `paid`,
-  позиций, категория через `dictGet` (спека, раздел 7).
+  разворачивает позиции и дополняет их категорией товара.
-- Сверка `dm.purchase_vs_orders_v`: `order_id`, `order_date`, `items_total`,
+- `dm.purchase_vs_orders_v` сопоставляет заказ с покупкой на сайте
-  `status`; соединение — GLOBAL JOIN с обеими сторонами-подзапросами
+  по `order_id`, используя `order_date`, `items_total` и `status`.
-  ([исследование соединений](../../research/2026-08-22-distributed-join.md)).
+- `dds.identity_map` связывает идентификаторы посетителей с `user_id`
-- Сборка карты идентичностей: пара `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) — версии заказов в
+- [ADR 0010](../../adr/0010-order-versions-in-ods.md) — версии заказов в ODS
-  ODS, устойчивая поверхность `ods.order_v`.
+  и чтение через `ods.order_v`.
-- [Приём заказов](../orders/ingestion.md) — граница строгого приёма и
+- [Прием заказов](../orders/ingestion.md) — проверки формата и выбор
-  четыре координаты строки ODS.
+  актуальной версии.
-- [Проталкивание условий сквозь
+- [Исследование соединений](../../research/2026-08-22-distributed-join.md) —
-  представления](../../research/2026-08-22-view-predicate-pushdown.md) —
+  почему сверка распределенных источников использует `GLOBAL JOIN`.
-  резолюция #128 той же карты: цена `FINAL` и цепочек представлений, фон, на
+- [Проталкивание условий сквозь представления](../../research/2026-08-22-view-predicate-pushdown.md) —
-  котором здесь выбрана физическая таблица.
+  как фильтр запроса влияет на объем чтения ODS.

docs/architecture/dm.md

@@ -281,7 +281,10 @@ business_key`.
 - **Инкрементальный пересчёт затронутых дней по `first_matched_at`.**
   Производственный ход, но на объёмах стенда его экономия неизмерима, а
   след новых связок требует вернуть колонку, выкинутую в #133. Стал лабой
-  повышенной сложности — issue #149.
+  повышенной сложности —
+  [«Как обновлять витрину без полной пересборки»](../labs/optional/incremental-daily-traffic.md).
+  В ней новые связи находятся сравнением наблюдений: время покупки
+  не заменяет момент обнаружения связи.
 - **Superset поверх DDS без слоя DM.** Терялся бы урок «витрина — контракт
   под потребителя», против раздела 7 спеки.
 

docs/architecture/orders/ingestion.md

@@ -1,241 +1,172 @@
-# Приём заказов из Kafka в ODS
+# Прием заказов из Kafka в ODS
 
-Учебный результат: менти различает версию бизнес-сущности, наблюдение источника
+Здесь разобран путь одного заказа: сообщение Kafka сохраняется в STG,
-и запуск загрузки, а затем читает физические версии через явную поверхность
+проверяется и попадает либо в ODS, либо в таблицу ошибок. Следующие слои
-текущего состояния.
+читают из ODS последнюю принятую версию каждого заказа.
-
-## Проблема
-
-Заказы приезжают полным слепком окна изменяемости, но Kafka передаёт его
-отдельными сообщениями и не сообщает потребителю, где слепок закончился.
-Прямое чтение Kafka Engine возвращает одну порцию без признака полноты.
-Поэтому `snapshot_date` не может служить границей публикации: `REPLACE
-PARTITION` могла бы заменить партицию дня неполным набором строк.
-
-Одновременно типизированный ODS не должен принимать правдоподобные значения по
-умолчанию из грязного JSON или останавливать весь пакет из-за одной строки.
-
-## Цели
-
-- сохранить пакетный забор как контраст потоковому приёму событий;
-- один раз принять байты в STG и независимо разложить строки на годные и брак;
-- хранить в ODS типизированные версии заказов, не публикуя слепок заменой
-  партиции;
-- дать следующим слоям один корректный способ прочитать текущее состояние;
-- оставить код проверки коротким и ограничить его контрактом провода.
-
-## Не входит
-
-- модель заказа в DDS: её зерно, связи, материализация и способ наполнения;
-- проверка полей внутри `items`, переходов статуса и равенств денежных сумм;
-- удаление заказа по отсутствию в следующем слепке;
-- маркер конца слепка, опись ожидаемых строк и транзакция между целями ODS.
 
 ## Поток данных
 
-После завершения генератора Airflow один раз читает байтовый Kafka-чтец и
+Источник отправляет в топик `orders` дневной слепок: по одному сообщению
-записывает полученную порцию в `stg.orders_raw`. Даг зовётся `orders_ingest`, а
+на заказ. Слепок дня D содержит состояния заказов, оформленных в дни
-запускает его шаговый даг модельного времени, который положил слепок в топик и
+D−6…D, с учетом [задержек первого появления](fate.md).
-ждёт конца прогона. Все строки получают `_load_id`, равный `run_id` Airflow.
+В начале модельного времени окно короче. Выгрузку за D отправляет
-`_load_ts` вычисляется при этой записи и дальше переносится без пересчёта.
+генератор при запуске дня D+1; подробности — в [описании слепка](snapshot.md).
-Запрос забора лежит в
-[`sql/stg/orders_raw_load.sql`](../../../sql/stg/orders_raw_load.sql):
-`SQLExecuteQueryOperator` задаёт подключение и передаёт `run_id` как параметр
-ClickHouse `load_id`, а преобразование остаётся в SQL своего слоя.
 
-Один следующий `task_id` отвечает за весь переход STG → ODS. Внутри него два
+После отправки шаговый даг модельного времени запускает
-последовательных `INSERT SELECT` читают неизменный срез по `_load_id`: первый
+[`orders_ingest`](../../../dags/orders_ingest.py) и ждет его завершения.
-пишет годные строки в `ods.order`, второй — брак в `ods.order_errors`.
+У `orders_ingest` нет расписания; его два шага выполняются по порядку:
-Транзакции между запросами нет. При частичном сбое 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`.
-`true` или `false`, не в `NULL`. Постоянный классификатор между STG и ODS для
+2. `parse_batch` читает сохраненные строки с этим `_load_id`. Первый
-этого не нужен. Предикат объявлен локальным макросом Jinja внутри
+   `INSERT SELECT` пишет годные записи в `ods.order_dist`, второй —
-`order_parse.sql` и разворачивается в оба выражения. Макрос убирает
+   остальные в `ods.order_errors_dist`.
-дублирование, но не вводит отдельный фрагмент, который нельзя исполнить
+
-самостоятельно.
+`_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`. Корень должен быть
+Проверяется одна строка `stg.orders_raw_dist`. Корень JSON должен быть
-JSON-объектом с точным набором ключей: `order_id`, `user_id`, `status`,
+объектом с точным набором из одиннадцати ключей:
-`created_at`, `updated_at`, `items_total`, `discount`, `delivery`, `total`,
+`order_id`, `user_id`, `status`, `created_at`, `updated_at`,
-`items`, `snapshot_date`.
+`items_total`, `discount`, `delivery`, `total`, `items`, `snapshot_date`.
 
-Скалярные поля проверяются по типу JSON. Деньги дополнительно обязаны быть
+| Поля | Условия приема |
-строками неотрицательной суммы с ровно двумя знаками после точки — минус в эту
+|---|---|
-форму не входит; времена — строками RFC 3339 в UTC с обязательными
+| `order_id`, `status` | Строки JSON |
-миллисекундами; дата слепка — строкой `YYYY-MM-DD`. `items` проверяется только
+| `user_id` | Целое число JSON, которое разбирается в `UInt64` |
-как JSON-массив. Каноническая форма и основания выбора зафиксированы в
+| `created_at`, `updated_at` | Строки UTC с миллисекундами, например `2026-06-01T12:34:56.000Z`; проверяются форма и разбор времени |
-[исследовании формата](../../research/2026-08-16-order-snapshot-wire-format.md).
+| `items_total`, `discount`, `delivery`, `total` | Неотрицательные суммы в рублях, записанные строками с двумя знаками после точки; проверяется разбор в `Decimal(18, 2)` |
+| `snapshot_date` | Строка даты `YYYY-MM-DD`, которая проходит разбор |
+| `items` | Массив JSON; сохраняется целиком в строковой колонке |
 
-Проверять все верхнеуровневые поля здесь уместно: их одиннадцать, и десять
+ODS проверяет формат верхнего уровня. Здесь нет проверки допустимых
-скалярных значений непосредственно образуют типизированную строку заказа. У
+статусов, их переходов, полей внутри `items` или равенства денежных сумм.
-события из 47 полей проверяются только пять опорных; переносить то сокращение на
+Позиции разбираются в [DDS](../dds/order.md); проверку их суммы участник
-малый контракт заказа нет причины. Граница строгости заканчивается на форме
+добавляет в [задании ступени 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`;
+Имя поля в класс не входит. Для разбора конкретной ошибки в
-2. `keyset_mismatch`;
+`ods.order_errors_dist` есть исходный `raw`, координаты Kafka и метки загрузки.
-3. `field_invalid`.
-
-Имя отдельного поля в класс не включается. В таблице ошибок остаются сырой
-текст, метаданные доставки и `_load_id`, поэтому единичный случай можно разобрать
-без постоянной детализации предиката.
 
 ## Роль ODS
 
-`ods.order_rep` хранит физически принятые версии в
+`ods.order_rep` использует `ReplicatedReplacingMergeTree(snapshot_date)`.
-`ReplacingMergeTree(snapshot_date)`. Ключ сортировки — `order_id`, партиция —
+Строки с одним ключом сортировки `order_id` считаются версиями одного заказа;
-день неизменного `created_at`. `ods.order_dist` шардирует по
+остается строка с максимальной `snapshot_date`. Партиция —
-`cityHash64(order_id)`: только так все версии заказа попадают на один шард и
+`toDate(created_at)` в UTC, ключ шардирования — `cityHash64(order_id)`.
-`FINAL` даёт корректный результат через распределённую таблицу.
+Неизменный `created_at` и общий ключ направляют все версии заказа
+в одну партицию и на один шард.
 
-Четыре координаты отвечают на разные вопросы:
+| Колонка | На какой вопрос отвечает |
+|---|---|
+| `snapshot_date` | На конец какого модельного дня источник показал это состояние? |
+| `updated_at` | Когда запись заказа последний раз меняли в магазине? |
+| `_load_id` | Какой запуск Airflow принял сообщение? |
+| `_load_ts` | Когда сообщение записали в STG по реальным часам стенда? |
 
-- `snapshot_date` — в слепке какого модельного дня источник показал строку;
+Например, заказ не менялся с 1 июня, но входит в слепки за 1 и 2 июня.
-- `updated_at` — когда строку последний раз меняли в источнике;
+`updated_at` у строк одинаков, а `snapshot_date` различается. ODS оставит
-- `_load_id` — какой запуск Airflow принял строку;
+строку за 2 июня вместе с метками ее доставки. Новая дата наблюдения
-- `_load_ts` — когда строка приехала в хранилище.
+нужна DDS для определения окна пересборки, даже если состояние не изменилось.
 
-Версию выбирает `snapshot_date`: выживает строка с максимальной датой слепка
+Источник выпускает **один слепок на дату**. Повторная отправка дает то же
-([ADR 0014](../../adr/0014-order-version-snapshot-date.md)). Поэтому
+содержимое, а более поздний слепок не возвращает устаревшее состояние.
-`snapshot_date` показывает последнее наблюдение заказа. По строкам последней
+Эти условия не проверяются на одной строке при приеме. Если источник
-даты слепка DDS определяет окно пересборки. `_load_id` и `_load_ts` принадлежат
+пришлет два разных состояния с одной `snapshot_date`, эта колонка
-той физической строке, которую сохранило слияние, и описывают её доставку.
+не позволит определить, какое из них актуально.
+Обоснование версии — [ADR 0014](../../adr/0014-order-version-snapshot-date.md).
 
-Схема версий стоит на дисциплине источника: слепок с поздней датой не
+`ods.order_v` читает `ods.order_dist FINAL` и возвращает одну текущую строку
-показывает состояния старше. Модельный мир её держит — состояние читается на
+на `order_id`, даже если фоновые слияния еще не убрали старые версии.
-границе суток, и слепок дня выходит чистой функцией зерна и дня; источник,
+Без `FINAL` физическая таблица может показать несколько строк заказа.
-собирающий слепок из отставшей реплики, её ломает. Деловая метка `updated_at`
+Историю ODS не гарантирует: старые версии постепенно удаляются при слияниях.
-при этом монотонна по слепкам, поэтому выбор по дате слепка даёт тот же ответ,
+Отсутствие заказа в новом слепке не удаляет его из ODS.
-что выбор по метке (замер — «Что проверено»). Тихая правка строки — ручным
-`UPDATE` мимо приложения, миграцией — метку не двигает, но следующий слепок
-перекроет её сам, пока заказ в окне изменяемости. За окном источник заказ
-больше не показывает, и там помогает только сверка самих полей, в терминах
-dbt snapshots — стратегия `check` вместо `timestamp`.
 
-Обычное чтение `_dist` показывает физически сохранившиеся версии и нужно для
+DDS читает `ods.order_v`, переводит времена в пояс счетчика и разбирает
-диагностики. Их число зависит от фоновых слияний: ODS не служит архивом истории.
+позиции. Для своей загрузки DDS записывает собственные служебные метки —
-`ods.order_v` сохраняет те же источник-ориентированные поля без обогащения
+[модель заказа](../dds/order.md#служебные-колонки).
-данными модели, но возвращает одну актуальную версию на `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)
+  а разбор разделил строки на годные и ошибки без потерь и пересечений.
-честный прогон дня снят на живом стенде 20 августа 2026 года: все 1694 строки
+  Две версии заказа попали на один шард в одну партицию; `ods.order_v`
-слепка дня 7 приняты, `ods.order_errors` осталась пустой. У заказа
+  вернул позднюю. Повтор разбора с тем же `_load_id` сохранил текущую строку
-`20260608-0007`, который прежде приходил с отрицательным итогом, теперь
+  и ее `_load_ts`, но повторил ошибки. Подробности —
-`5490.00 − 823.50 + 299.00 = 4965.50`.
+  [справочник хранилища](../storage.md#что-проверено) и
+  [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`
+  из сырых данных.
 
-При исполнении #124 21 августа 2026 года адресная пересборка мира прошла через
+На ClickHouse `26.3.17.56` отдельно проверены одна порция при прямом
-`SQLExecuteQueryOperator`: `pull_batch` и `parse_batch` завершились успешно. В
+`SELECT` Kafka и выполнение `FINAL` на шардах через Distributed.
-`system.query_log` на первой ноде осталось ровно по одному завершённому запросу
+При проектировании Context7 был недоступен; чтение сверяли с исходниками
-пользователя `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#актуальные-события).
 
 ## Связанные решения
 

docs/architecture/stand.md

@@ -22,7 +22,7 @@
 
 ## Пользователи и роли ClickHouse
 
-В ClickHouse семь пользователей и шесть ролей:
+В ClickHouse восемь пользователей и семь ролей:
 
 - `etl` — учётная запись рабочих дагов Airflow; роль `etl_writer` читает и
   пишет слои хранилища;
@@ -33,6 +33,9 @@
   справочники `dic`, а запросы Superset обращаются к публичным `_v`;
 - `analyst` — учётная запись аналитика с правом чтения всех слоёв и
   справочников;
+- `student` — учебная учётная запись: роль `analyst_reader` дает чтение
+  источников, а `student_writer` — создание, заполнение и удаление своих
+  таблиц в `default`. Записи в слои хранилища у нее нет;
 - `grafana` — учётная запись Grafana; роль `monitoring_reader` читает все слои,
   системные таблицы и данные со всех реплик кластера;
 - `dict` — беспарольная учётная запись словаря товаров с правом чтения базы
@@ -49,6 +52,9 @@ Superset получает пароль `bi`, а Grafana — пароль `grafan
 
 ## Применение настроек
 
+Для существующего стенда сначала добавьте `CLICKHOUSE_STUDENT_PASSWORD`
+из `.env.example` в свой `.env`.
+
 Чтобы применить новые значения ClickHouse из `.env` или изменения файлов в
 `infra/clickhouse/config.d/` и `infra/clickhouse/users.d/`, пересоздайте ноды:
 

docs/architecture/storage.md

@@ -122,112 +122,110 @@ DDS: представление читает события ODS.
 
 ## Служебные колонки
 
-Собственные колонки не повторяют имён виртуальных. Виртуальные даёт движок:
+STG сохраняет исходное сообщение в строке `raw` и добавляет сведения
-`_topic`, `_partition`, `_offset`, `_timestamp` у Kafka, `_shard_num` у
+о доставке. JSON на этом шаге не разбирается: некорректное содержимое
-`Distributed` и прочие. Если положить на диск колонку с таким же именем, в
+тоже попадает в таблицу.
-матвью перестанет читаться, что дано движком, а что положено нами, — а это
-ровно то различие, ради которого метаданные доставки и хранятся. Поэтому они
-ложатся под именами `kafka_topic`, `kafka_partition`, `kafka_offset`,
-`kafka_timestamp`, рядом — `consumer_host`, имя читавшей ноды: виртуальные
-колонки его не несут, а после записи в `Distributed` он уже невосстановим.
 
-Типы у них такие: `kafka_topic` и `consumer_host` — `LowCardinality(String)`,
+| Колонка STG | Что хранит |
-значений мало и они повторяются; `kafka_partition` и `kafka_offset` — `UInt64`.
+|---|---|
-С `kafka_timestamp` сложнее, и форма его решена на стенде. Меток времени движок
+| `kafka_topic` | Имя топика из виртуальной колонки Kafka `_topic` |
-даёт две: `_timestamp` — `Nullable(DateTime)`, то есть секунды, и
+| `kafka_partition` | Номер партиции из `_partition` |
-`_timestamp_ms` — `Nullable(DateTime64(3))`, миллисекунды. Колонка объявлена
+| `kafka_offset` | Позицию сообщения внутри партиции из `_offset` |
-`Nullable(DateTime64(3, 'UTC'))` и заполняется из `_timestamp_ms`: у брокера
+| `kafka_timestamp` | Метку времени Kafka из `_timestamp_ms`, если она есть |
-метка миллисекундная, соседняя `_load_ts` тоже миллисекундная, а сырой слой
+| `consumer_host` | Имя ноды, прочитавшей Kafka |
-хранит приехавшее, и округлять ему нечего. Обнуляемость нужна отдельно от
+| `_load_ts` | Реальное время записи сообщения в STG |
-разрядности: брокер метку заполняет не всегда, а необнуляемый тип значил бы либо
+| `_load_id` | Только у заказов: `run_id` запуска Airflow, который принял порцию |
-падение приёма на первом сообщении, либо тихие нули за 1970 год.
 
-Заполняются все они выражением в `SELECT` матвью приёма, а не `DEFAULT` в
+Топик, партиция и смещение вместе позволяют найти сообщение Kafka.
-таблице. Для `consumer_host` это обязательно: `DEFAULT hostName()` вычисляется
+`kafka_topic` и `consumer_host` имеют тип `LowCardinality(String)`,
-на шарде-получателе, то есть назвал бы не ту ноду, которая читала топик, —
+`kafka_partition` и `kafka_offset` — `UInt64`.
-колонка молча отвечала бы на другой вопрос.
+`kafka_timestamp` имеет тип `Nullable(DateTime64(3, 'UTC'))`: сохраняет
+миллисекунды и допускает отсутствие метки.
 
-Само сообщение лежит в колонке `raw` тем, чем пришло: чтец читает байты и ничего
+Виртуальные колонки предоставляет движок, а колонки STG хранят значения
-не проверяет, поэтому там оказываются и целые сообщения, и мусор. События ниже
+на диске. Их имена различаются, чтобы не скрыть виртуальную колонку
-разбирают матвью ODS ([ADR 0005](../adr/0005-event-ingestion.md)), заказы —
+собственной. Значения вычисляются в запросе приема. В частности,
-пакетный шаг ([ADR 0008](../adr/0008-order-ingestion.md), [ADR
+`hostName()` должен выполняться на ноде, читающей Kafka:
-0010](../adr/0010-order-versions-in-ods.md)).
+`DEFAULT hostName()` только в локальной таблице назвал бы шард-получатель.
 
-Движок таблицы STG — обычный `ReplicatedMergeTree`, `ORDER BY (kafka_partition,
+Таблицы STG используют `ReplicatedMergeTree` с
-kafka_offset)`: разбор полётов идёт от «какое сообщение», другого ключа у
+`ORDER BY (kafka_partition, kafka_offset)`. Повторная доставка остается
-таблицы STG и нет. Замену версий сюда ставить нельзя — она отменила бы свойство
+отдельной строкой; STG нужен в том числе для разбора таких повторов.
-слоя, ради которого он заведён: повтор доставки в STG обязан быть виден.
 
-Метка времени загрузки зовётся `_load_ts`, тип `DateTime64(3, 'UTC')`. Ставится
+`_load_ts` имеет тип `DateTime64(3, 'UTC')`. При переходе в ODS метка
-она один раз при записи в STG: для событий — матвью приёма, для дневного слепка
+копируется из STG без пересчета. У событий она также выбирает последнюю
-заказов — пакетным шагом. Дальше метка переносится в ODS как есть и отвечает на
+доставку; у заказов версию задает `snapshot_date`. `_load_id` заказа
-вопрос «когда строка приехала в хранилище», а не «когда её разобрали». В
+переносится в годную строку ODS и в таблицу ошибок.
-`ods.event` она же служит колонкой версии `ReplacingMergeTree` и схлопывает
+У непрерывного потока событий нет запуска Airflow, поэтому `_load_id`
-повтор доставки. У `ods.order` версию задаёт `snapshot_date` — дата слепка
+в его STG и ODS отсутствует.
-источника; `_load_ts` только показывает, когда конкретная строка приехала.
 
-`created_at` и `updated_at` заказа к служебным колонкам хранилища не относятся.
+Время события `UTCEventTime` и дата `EventDate` приходят из счетчика сайта.
-Они приезжают в сообщении как аудит строки в БД источника и в ODS разбираются в
+Поля заказа `created_at` и `updated_at` приходят из базы магазина.
-`DateTime64(3, 'UTC')`; ClickHouse их не создаёт и добавляет рядом собственную
+Они относятся к модельному времени; `_load_ts` — к реальным часам стенда.
-`_load_ts`. Совпадение слов «техническое время» не делает эти часы одной осью.
+Например, событие июня можно загрузить в сентябре: его `EventDate`
+останется июньской, а `_load_ts` будет сентябрьской.
 
-Пакетной переобработки у событий в ODS нет: слой наполняют матвью, а не задание
+События разбираются материализованными представлениями. Автоматической
-Airflow. Переделать разобранное руками можно вставкой из STG с фильтром по
+пакетной переобработки у них нет; сохраненный срез STG можно разобрать
-`_load_ts` в пределах трёхсуточного окна; ничья по версии разрешается в пользу
+отдельным запросом до истечения срока хранения. При повторной вставке
-вставленного позже. Заказы разбирает пакетный шаг из неизменного среза STG по
+с тем же ключом и `_load_ts` `ReplacingMergeTree` оставляет более поздно
-`_load_id`; дневные партиции ODS он не заменяет.
+вставленную строку. Заказы разбирает задача Airflow по `_load_id`.
-
+В 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`.
-`ReplacingMergeTree(_load_ts)`, а `ods.event_dist` служит для записи и
+Движок `ReplicatedReplacingMergeTree(_load_ts)` считает версиями строки
-диагностики доставки. Обычное чтение этой пары может показать несколько строк
+с одинаковым полным ключом сортировки:
-одного `WatchID`, пока фоновые слияния их не схлопнули.
+`(CounterID, EventDate, intHash32(ClientID), WatchID)`.
+При слиянии остается строка с максимальным `_load_ts`, то есть последняя
+доставка. Один `WatchID` обозначает событие, но физический ключ замены шире.
 
-`ods.event_v` — обычное представление над `ods.event_dist FINAL`. Оно сохраняет
+`ods.event_v` читает `ods.event_dist FINAL`: выбирает актуальную строку
-имена, типы и зерно события, но всегда возвращает актуальную версию. Актуальное
+при выполнении запроса, не дожидаясь фоновых слияний. Поэтому события
-состояние читают через него, а не повторяют `FINAL` в каждом запросе.
+считают через `_v`; число строк в `_dist` зависит от уже прошедших слияний.
-`dds.event_v` отвечает за другое: даёт событию язык бизнес-модели, в том
+`dds.event_v` использует этот результат, дает колонкам имена в `snake_case`
-числе snake_case-имена и расшифровку кодов.
+и расшифровывает коды.
 
-Типы ODS обычно повторяют контракт выгрузки. Денежный `purchaseRevenue` —
+Выбор по полному `ORDER BY` и максимальной версии, включая чтение с `FINAL`,
-исключение: источник объявляет `Array(Float64)`, а материализованное
+сверен через Context7 с [документацией ClickHouse](https://clickhouse.com/docs/reference/engines/table-engines/mergetree-family/replacingmergetree).
-представление ODS разбирает числа сырого JSON сразу в `Array(Decimal(18, 2))`.
+В стенде закреплена версия 26.3.17.56; `_v` использует `FINAL`, чтобы
-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` хранит принятые версии в
-`ReplacingMergeTree(snapshot_date)`: ключ сортировки — `order_id`, партиция —
+`ReplicatedReplacingMergeTree(snapshot_date)`: ключ сортировки — `order_id`,
-`toDate(created_at)`. `ods.order_dist` шардирует по
+партиция — `toDate(created_at)` в UTC. Запись через `ods.order_dist`
-`cityHash64(order_id)`. Все версии заказа лежат в одной партиции, чтобы их могли
+распределяет их по `cityHash64(order_id)`. У всех версий заказа одинаковы
-схлопывать фоновые слияния, и на одном шарде, чтобы распределённый `FINAL`
+день создания и шард, поэтому они могут заменять друг друга.
-выбрал одного победителя.
 
-Физическая пара нужна для загрузки и диагностики. Обычное чтение показывает
+`ods.order_v` читает `_dist FINAL` и оставляет строку с максимальной датой
-версии, которые ещё не убрали фоновые слияния, и не является архивом истории.
+слепка. Дата `snapshot_date` показывает последнее принятое наблюдение,
-`ods.order_v` служит поверхностью точного текущего состояния для следующих
+а `updated_at` — время изменения заказа в магазине. У неизменившегося
-слоёв. Представление сохраняет язык источника и не решает, какой станет модель
+заказа в следующем слепке дата наблюдения обновится, время изменения — нет.
-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). Контракт следующего слоя
+
-задан в [модели заказа в DDS](dds/order.md).
+Прием добавляет версии отдельными строками. `snapshot_date` не доказывает,
+что 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).
 
 ## Часовые пояса
 
@@ -289,169 +287,148 @@ UTC+4), и пересчёт идёт один раз при наполнении
 
 ## Приём: поток и его свойства
 
-Раздел — про события. У заказов приём устроен иначе: слепок забирает по команде
+События принимаются непрерывно. Заказы читает отдельным запросом
-даг `orders_ingest`, а не подписанная навсегда матвью — [ADR
+даг `orders_ingest` — [описание пакетного приема](orders/ingestion.md).
-0008](../adr/0008-order-ingestion.md) и [спецификация приёма
+У событий путь такой:
-заказов](orders/ingestion.md).
 
-Цепочка одна: чтец топика → матвью → STG → матвью разбора → событие и таблица
+```text
-ошибок ODS.
+stg.hits_raw_kafka → stg.hits_raw_mv → stg.hits_raw_dist
+                                      ├→ ods.event_mv → ods.event_dist
+                                      └→ ods.event_errors_mv → ods.event_errors_dist
+```
 
-Чтец стоит на обеих нодах и читает одной группой потребителей — имя группы
+Таблицы Kafka на обеих нодах используют одну группу `clickstream_hits`.
-`clickstream_hits`, и оно одинаково на обеих нодах по построению: DDL идёт
+Ноды делят чтение партиций топика. Разные группы прочитали бы каждая
-`ON CLUSTER` и макросов в имени не содержит. Разные группы дали бы каждой ноде
+свою полную копию потока. Имя группы одинаково в DDL на всем
-полную копию топика, и это отдельная сцена для лабы, а не рабочий режим. Имя
+`clickstream_cluster`; конфигурация кластера —
-кластера в `ON CLUSTER` и в движке `Distributed` — `clickstream_cluster`, оно
+`infra/clickhouse/config.d/cluster.xml`.
-задано в `infra/clickhouse/config.d/cluster.xml`.
 
-**Источник матвью разбора — `stg.hits_raw_dist`, а не локальная таблица.**
+Материализованные представления разбора срабатывают на вставку
-У матвью две привязки: источник, на вставку в который она срабатывает, и цель,
+в `stg.hits_raw_dist`, до распределения строк по шардам.
-куда пишет. Распределённая таблица — лицо слоя, локальная — его хранилище;
+Оба видят вставляемую порцию на той ноде, которая читает Kafka.
-потребитель слоя цепляется к лицу. Практически это значит, что разбор идёт на
+`stg.hits_raw_mv` создается после них: его подключение запускает
-той же ноде, что читала Kafka, в момент вставки первой матвью — до раскладки по
+чтение топика. Если начать чтение раньше, сообщения успеют попасть
-шардам.
+в STG без разбора в ODS.
 
-**Вставка фоновая, и окно потери мы принимаем.** Вставка в распределённую
+Условие приема проверяет три вещи:
-таблицу кладёт блок в локальный спул и сразу возвращает управление, а Kafka
-коммитит офсеты по факту работы матвью — то есть по факту записи в спул. Топик
-уже считает сообщение прочитанным, хотя на шарде его ещё нет: умри нода в этом
-промежутке — сообщения не перечитаются.
 
-Закрывает окно настройка `distributed_foreground_insert = 1`, и на ETL-вставках
+- корень `raw` — объект JSON;
-Airflow она стоит — там это обычный `SETTINGS` у запроса. На пути приёма её нет,
+- набор верхнеуровневых ключей совпадает с 47 полями формата;
-и по трём причинам. Вставку выполняет фоновый поток Kafka-движка, своего запроса
+- пять опорных полей, `WatchID`, `VisitID`, `ClientID`, `EventDate`
-у него не бывает, так что настройка уровня запроса доехала бы только профилем
+  и `UTCEventTime`, разбираются в ожидаемые типы.
-пользователя в конфигурации ноды. Синхронный режим связывает шарды: пока второй
-недоступен, вставка падает, офсеты не коммитятся, и приём встаёт целиком — тогда
-как при фоновом первая нода продолжает принимать и копит спул для соседа.
-Платится при этом не одно ожидание на блок, а три распределённые вставки — STG,
-событие, ошибки, — и все внутри потока-потребителя, что само по себе повод для
-ребаланса по таймауту сессии. Против всего этого — окно в сотню миллисекунд на
-ноутбуке, где мир пересобирается одной командой. Размен не в пользу настройки, а
-компромисс полезнее показать, чем спрятать за галочкой.
 
-Ещё одно место, где сырой слой хранит не всё приехавшее: запись с пустым
+Остальные поля извлекаются по описанию выгрузки без отдельных проверок.
-значением и запись-надгробие проходят молча, не оставляя строки. Свойство
+Это граница приема: годная строка не означает, что проверен смысл
-измерено и принято осознанно — подробности в разделе «Что проверено».
+всех 47 значений. Подробности — в [ADR 0005](../adr/0005-event-ingestion.md).
 
-**Гарантии нет ни в одну сторону — есть два узких окна.** Окно потери описано
+`ods.event_mv` принимает строки, для которых условие истинно,
-выше: нода умерла между коммитом офсетов и сбросом спула. Окно дубля
+`ods.event_errors_mv` — для которых оно ложно. Условие не должно
-противоположное: нода умерла после записи на шард, но до коммита офсетов, и при
+возвращать `NULL`: такую строку не выбрали бы ни оно, ни его отрицание.
-перечитывании сообщение приедет второй раз. Сказать про такой приём «хотя бы
+Разбор использует функции без исключений на некорректном сообщении,
-один раз» нельзя — это обещало бы, что потерь не бывает, а они возможны.
+поскольку ошибка материализованного представления прерывает вставку
+и останавливает чтение Kafka до устранения причины.
 
-Дубль ниже по течению ведёт себя по-разному. В ODS его схлопнет
+### Доставка и повторы
-`ReplacingMergeTree`, а таблицы STG вовсе не устраняют дубли: перезаливка
-модельного дня честно удваивает `count()` в STG, и живёт эта пара до истечения
-срока хранения. Это свойство слоя, а не поломка, — но обещание идемпотентности
-конвейера к сырому слою не относится.
 
-Оговорка к последнему: у семейства `Replicated*` есть своя дедупликация — блок с
+Вставка в Distributed на этом пути фоновая: блок сначала записывается
-тем же хешем, вставленный повторно, отбрасывается (`insert_deduplicate`).
+в локальную очередь на диске, затем отправляется на шарды.
-Удвоение строк STG проходит мимо неё только потому, что при повторном чтении
+Kafka подтверждает обработку после выполнения материализованных
-`_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 его устраняет выбор актуальной версии.
-слоя срок жизни трое суток, а ODS хранит всё, поэтому равенство «строки STG =
+Хотя `Replicated*` умеет отбрасывать повторно вставленные одинаковые блоки,
-события + ошибки» разъедется само: строки STG истекут раньше, а перезаливка
+при новом чтении Kafka меняется `_load_ts`, а вместе с ним и хеш блока.
-модельного дня задвоит их, тогда как в ODS тот же повтор схлопнется. Правило,
+Поэтому повторная отправка модельного дня увеличивает число строк STG.
-красное в норме, учит не смотреть на оповещения ([ADR
-0002](../adr/0002-monitoring-scope.md)). Равенство проверено разовым опытом при
-исполнении #43, на управляемой пачке: отправили N сообщений — получили N строк
-STG и N в сумме событий и ошибок. Постоянной целью такой опыт не становится, и
-почему — в [карте проверок](testing.md), раздел «Интеграционная проверка
-постоянной целью не становится». Счёт актуальных событий идёт через
-`ods.event_v`, которое скрывает `FINAL`: голый `count()` по `ReplacingMergeTree`
-зависит от того, сколько мержей успело пройти, и спека это прямо запрещает
-(раздел 6).
 
-**Постоянная сверка одна, и она другого рода** — не слой против слоя, а ODS
+Пустое значение сообщения и значение `null` не дают строки даже в STG:
-против [паспорта мира](../../data/world-inventory.json), лежащего в git (`make
+чтец продвигает позицию Kafka, но не передает строку на разбор.
-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).
 
 ## Срок жизни сырых данных
 
-Сырые данные в STG живут трое суток реального времени и уходят сами. Трое — это
+TTL — правило автоматического удаления старых данных. В обеих таблицах
-окно отладки: столько сырые данные хранятся на ноутбуке, чтобы менти успел
+STG срок задан как три суток от `_load_ts`, по реальному времени загрузки.
-разобрать полёты, после чего перестаёт занимать место. Нарезка — по дню
+Партиции тоже нарезаны по дню `_load_ts`. Это оставляет короткий период
-загрузки, срок — по той же колонке `_load_ts`, снятие — целыми кусками
+для поиска ошибок и повторного разбора, после которого данные освобождают
-(`ttl_only_drop_parts`). В DDL значение проставлено явно, чтобы поведение не
+место на диске.
-зависело от умолчания версии.
 
-Нарезать сырые данные по модельному дню события было бы соблазнительно — он
+Настройка `ttl_only_drop_parts = 1` удаляет только целые части данных —
-единица переобработки и он же ключ партиции в ODS, — но чистку это ломает. Кусок
+файлы, которые ClickHouse создает при вставках и объединяет при слияниях.
-снимается целиком, только когда в нём истекли все строки, а в партиции
+Часть удаляется, когда срок истек у всех ее строк. Внутри партиции
-модельного дня лежит приехавшее в разное реальное время: мерж склеит куски
+дня загрузки возраст строк отличается не более чем на сутки.
-разного возраста, самая свежая строка удержит весь кусок, и данные переживут
+Поэтому к трем суткам может добавиться до суток ожидания самой свежей
-срок неограниченно.
+строки части, а затем ожидание фоновой обработки TTL. Точного времени
+удаления правило не обещает.
 
-В партиции дня загрузки склейка идёт точно так же, и строки в ней тоже разного
+Модельная дата для TTL не подходит: события июня могут загружаться
-возраста — но не более чем на сутки, потому что партицию закрывает календарный
+осенью, и срок от `EventDate` истек бы сразу. Партиция по модельному дню
-день. Отсюда и оценка: сырые данные живут трое суток плюс хвост до суток, а не
+тоже смешала бы доставки разного возраста: очередная отправка дня могла бы
-ровно трое. Оговорка про сроки: TTL исполняется на мержах, а не по будильнику,
+продлевать хранение старых строк после слияния частей.
-так что «уходит само» здесь обещано, а «уходит вовремя» — нет.
 
-Модельного дня среди колонок STG нет вовсе. Он свойство содержимого, а
+Для разбора сохраненных сообщений выбирайте небольшой срез по `_load_ts`.
-содержимое разбирает ODS — там `EventDate` и живёт, ключом партиции. Сырые
+Так запрос ограничивает партиции и сохраняет некорректные сообщения,
-данные режутся по своим координатам: и разбор полётов, и переобработка фильтруют
+из которых модельную дату извлечь нельзя. `EventDate` появляется
-по `_load_ts`, попадая в ключ партиции, а не идя сплошным проходом. Фильтр по
+отдельной колонкой только в ODS. В [задании ступени 6](../labs/6-1-event-parsing.md)
-модельному дню вдобавок пропускал бы битые строки — у них дата не извлекается.
+такой срез разбирается рядом с действующим приемом.
-
-Две оси времени тут не совпадают намеренно. Ось модельного времени начинается в
-D0 и к реальному календарю не привязана; пакетный режим проигрывает две недели
-модельного мира за минуты реальных. Поэтому у переобработки и у гигиены диска
-разные часы, и обслуживают их разные средства. Декларативный TTL по модельной
-дате был бы просто сломан: он отсчитывает срок от реального «сейчас» и удалял бы
-эталонные дни прямо на входе.
-
-В бою сырой слой иногда собирают на движке `Null` — тогда он не хранится вовсе.
-Такой вариант отвергнут: на стенде сырые данные нужны для отладки, поэтому окно,
-а не ноль.
 
 ## Таблица ошибок
 
-`ods.event_errors` держит строки, не прошедшие строгий приём, вместе с их сырым
+`ods.event_errors_dist` содержит сообщения, отвергнутые разбором событий:
-текстом, метаданными доставки и классом брака. Ключи её собственные, потому что
+исходный `raw`, сведения о доставке и класс ошибки `error_class`.
-у брака нет разобранных полей: шардируется `cityHash64` сырой строки —
+Класс имеет тип `LowCardinality(String)` и выбирается по первому
-`ClientID` у строки, которая не разобралась, взять неоткуда; нарезается по дню
+нарушенному условию:
-загрузки, как и сырые данные; живёт месяц. Дольше сырых данных — намеренно: если
-брак истекает вместе с ними, разбираться к моменту разбирательства будет уже
-нечем. Снятие — целыми кусками (`ttl_only_drop_parts`), как у STG и по той же
-причине: строки в партиции дня загрузки разного возраста не более чем на сутки,
-и куску незачем переживать срок из-за самой свежей строки.
 
-Класс брака лежит в колонке `error_class` типа `LowCardinality(String)`. Без неё
+1. `not_an_object` — корень JSON не объект;
-в таблице копятся строки «что-то не так» без ответа на «что именно», а витрине
+2. `keyset_mismatch` — набор ключей не совпал с форматом;
-качества не на что опереться. Сами классы, их порядок и довод, почему порядок
+3. `key_field_unparsed` — одно из пяти опорных полей не разобралось.
-обязателен, — в [ADR 0005](../adr/0005-event-ingestion.md).
 
-Движок — обычный `ReplicatedMergeTree`, без замены версий: схлопывать брак не по
+Порядок важен: строка вместо объекта нарушает сразу несколько условий,
-чему, у него нет ключа сущности. `ORDER BY` — `(error_class, kafka_partition,
+но получает один класс. Полные условия — в
-kafka_offset)`: смотрят такую таблицу от класса, а внутри класса — по координатам
+[ADR 0005](../adr/0005-event-ingestion.md).
-доставки.
 
-`ods.order_errors` держит тот же диагностический минимум и `_load_id`
+`ods.order_errors_dist` хранит такой же набор сведений и `_load_id`
-запуска. У заказов три класса по приоритету: `not_an_object`,
+запуска приема. Первые два класса совпадают с событиями,
-`keyset_mismatch`, `field_invalid`. Сырой текст остаётся рядом, поэтому класс не
+третий называется `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.
 
 ## Справочники
 

docs/formats/clickstream-event.md

@@ -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 внутри колонки |

docs/labs/README.md

@@ -124,13 +124,29 @@ DM](../architecture/dm.md).
 
 ### Почему выручка не сходится
 
-Открывается после ступени 1. Расхождения между источниками, повторы
+Открывается после ступени 1. Четыре расследования качества данных:
-покупок и день, после которого отчет можно считать окончательным.
+
+- [Куда пропали покупки](optional/missing-purchases.md): найти заказы без
+  события, выбрать источник витрины и условие проверки полноты.
+- [Почему повтор покупки завышает выручку](optional/duplicate-purchases.md):
+  выбрать зерно и ключ расчета, проверить его на повторных событиях.
+- [Какая позиция объясняет разницу в сумме](optional/order-amount-difference.md):
+  разобрать позиции без потери точности и локализовать расхождение источников.
+- [Почему вчерашняя выручка меняется сегодня](optional/revenue-over-time.md):
+  обосновать окно пересчета витрины и требования к истории заказов.
+
+Первые три работы используют готовые данные. Четвертая продвигает мир через
+Airflow; для нее вы сохраняете состояния заказов после каждого модельного дня.
 
 ### Тонкий анализ данных
 
-Открывается после ступени 1. Знание о пользователе на дату и обогащение
+Открывается после ступени 1.
-отчета своим словарем.
+
+- [Как новые заказы меняют отчет о посетителях](optional/identity-over-time.md):
+  сохранить историю связей, сравнить расчеты на прежних сессиях и определить,
+  какие сведения нужны для воспроизведения результата.
+
+Обогащение отчета своим словарем регионов пока описано только в программе.
 
 ### Superset и BI
 
@@ -146,6 +162,10 @@ DM](../architecture/dm.md).
 Открывается после ступени 1. Прием и хранение данных, раскладка по шардам,
 повторная обработка дня и обновление витрин.
 
+- [Как обновлять витрину без полной пересборки](optional/incremental-daily-traffic.md):
+  продолжить работу о связях пользователей, пересчитать затронутые дни
+  и проверить повтор незавершенной загрузки. Повышенная сложность.
+
 ### Что делать, когда стенд сломался
 
 Открывается после ступени 7. Поломки стенда и инструкции по восстановлению

docs/labs/optional/duplicate-purchases.md

@@ -0,0 +1,82 @@
+# Почему повтор покупки завышает выручку
+
+**Чему учит:** выбрать зерно и ключ расчета, чтобы повторные события
+не умножали денежную сумму.
+
+Факультатив доступен после ступени 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`.
+
+## Что должно получиться
+
+- [ ] сохранен запрос с одной строкой на заказ, числом событий и суммой;
+- [ ] уникальность ключа и полнота набора номеров проверены по источнику;
+- [ ] разность сумм полностью объяснена вкладом лишних событий;
+- [ ] обоснованы ключ расчета и место устранения повторов;
+- [ ] найден случай, показывающий границы расчета денег по трекеру.

docs/labs/optional/identity-over-time.md

@@ -0,0 +1,141 @@
+# Как новые заказы меняют отчет о посетителях
+
+**Чему учит:** сохранять историю связей посетителей с покупателями
+и использовать ее для воспроизведения прежнего расчета.
+
+Факультатив доступен после ступени 1. Понадобятся Airflow и DBeaver с
+подключением `student` по [инструкции](../../../README.md#подключиться-из-dbeaver).
+Результаты запросов сохраняйте в `default` через одно подключение:
+ваши таблицы будут доступны только на узле этого подключения.
+Если предложенное имя таблицы занято, выберите свое.
+
+В событиях сайта посетитель обозначен кукой `client_id`, а в заказах
+покупатель — `user_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`.

docs/labs/optional/incremental-daily-traffic.md

@@ -0,0 +1,150 @@
+# Как обновлять витрину без полной пересборки
+
+**Чему учит:** выбирать дни для пересчета по новым данным, проверять результат
+и повторять незавершенную загрузку.
+
+Факультатив повышенной сложности продолжает работу
+[«Как новые заказы меняют отчет о посетителях»](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; у этих кук
+  есть сессии, в том числе за прежние дни.
+
+Сначала выведите даты и выберите один прежний день: какая новая пара
+потребовала его пересчета и какие сессии с ней связаны? Рядом посчитайте,
+сколько дат пересчитала бы полная загрузка. Зафиксируйте оба числа;
+равенство тоже возможно, если новые связи затронули всю историю.
+
+Для сравнения выберите из списка на 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`, если они больше не нужны.

docs/labs/optional/missing-purchases.md

@@ -0,0 +1,102 @@
+# Куда пропали покупки
+
+**Чему учит:** проверить полноту данных по независимому источнику и выбрать
+источник для витрины заказов.
+
+Факультатив доступен после ступени 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` установить место потери —
+до приема в хранилище или при обработке? Какие данные нужны, чтобы это выяснить?
+
+## Что должно получиться
+
+- [ ] сохранен запрос сверки по дате, возвращающий заказы без события;
+- [ ] оба равенства сходятся, влияние повторного просмотра объяснено;
+- [ ] один случай подтвержден запросами к обоим источникам;
+- [ ] источник витрины выбран по результатам сверки;
+- [ ] указаны условие окончательной проверки и границы ее выводов.

docs/labs/optional/order-amount-difference.md

@@ -0,0 +1,84 @@
+# Какая позиция объясняет разницу в сумме
+
+**Чему учит:** разобрать вложенные данные без потери точности и локализовать
+расхождение двух источников до товарной позиции.
+
+Факультатив доступен после ступени 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). Если все цены
+выбранной корзины целые, возьмите еще один заказ с расхождением и дробной ценой.
+
+Какие строки подтверждают найденное расхождение? Есть ли в источниках
+сведения о том, почему оно возникло? Отделите наблюдения от предположений.
+
+## Выберите поля для точного расчета
+
+Укажите рядом с запросом, откуда брать цену, каким типом ее читать и по какому
+ключу сопоставлять позиции. Подтвердите выбор результатами обеих сверок:
+суммы разобранных позиций с суммой своего источника и позиций двух источников
+между собой. Какой результат укажет на ошибку вашего разбора, а какой
+потребует искать причину выше — в данных, которые получил запрос?
+
+## Что должно получиться
+
+- [ ] сохранен запрос сверки позиций, не теряющий товары без пары;
+- [ ] все три равенства сходятся до копейки;
+- [ ] найден пример потери точности в готовом массиве цен;
+- [ ] выбор полей, типа денег и ключа сопоставления подтвержден расчетами;
+- [ ] расхождение источников сверки отделено от ошибки своего разбора и различия
+      между стоимостью корзины и итогом со скидкой и доставкой.

docs/labs/optional/revenue-over-time.md

@@ -0,0 +1,188 @@
+# Почему вчерашняя выручка меняется сегодня
+
+**Чему учит:** обосновать окно пересчета витрины и требования к истории
+заказов по наблюдаемым опозданиям и изменениям статусов.
+
+Факультатив доступен после ступени 1. Понадобятся Airflow и DBeaver с
+подключением `student` по [инструкции](../../../README.md#подключиться-из-dbeaver).
+Он читает данные стенда и записывает ваши наблюдения в базу `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`.
+
+## Подготовьте место для наблюдений
+
+Публичное представление заказа показывает текущее состояние, а сырые слепки
+хранятся ограниченное время. Сохраните историю в двух своих таблицах: потом
+вы сможете сравнивать наблюдения обычными 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`.

docs/specs/2026-09-01-labs-program.md

@@ -149,38 +149,85 @@
 
 ## 4. Факультативы — пять разделов
 
-Ниже перечислены только названия сюжетов и их уроки. Материал, формы и способы
+Ниже перечислены сюжеты, их уроки и принятые решения по форме заданий. Исходный
-проверки остаются в [инвентаризации](../research/2026-08-31-labs-inventory.md).
+материал и способы проверки — в
+[инвентаризации](../research/2026-08-31-labs-inventory.md).
 
 ### Почему выручка не сходится
 
-Этот раздел рекомендован первым из факультативов. Он открывается после ступени
+Этот раздел рекомендован первым из факультативов и открывается после ступени
-1 основной программы: материал живет на стенде с этапа 6.
+1 основной программы. Шесть сюжетов собраны в четыре лабораторные: три
+расследования готовых данных и одно наблюдение во времени. Опоздания,
+изменение выручки и история отмен используют одну историю заказов, поэтому
+для них выбрана общая работа вместо трех отдельных.
 
-- **Почему трекер недосчитывает покупки (#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 основной программы.
 
-- **Что мы знали о пользователе в тот день (#145).** Текущее знание и знание на
+- **[Как новые заказы меняют отчет о посетителях](../labs/optional/identity-over-time.md) (#145).**
-  дату дают разные отчеты; сведения из будущего меняют прошлое.
+  Учащийся собирает связи с подтверждающими покупками и сохраняет три
+  ежедневных наблюдения. На одном наборе прежних сессий сравнивает расчет
+  с прежними и новыми связями, выбирает историю для воспроизведения расчета.
 - **Добавь названия регионов в отчет (#143).** Менти собирает свой словарь по
   образцу каталога и обогащает отчет через `dictGet`.
 
+Работа о связях продолжается в инженерном разделе лабораторной про
+инкрементальный `daily_traffic`. В обеих учащийся продвигает мир через
+`world_next_day` и `etl_pipeline`, сохраняет наблюдения под `student` в
+свои локальные таблицы `default` и сравнивает их SQL-запросами.
+
+Время первой подтверждающей покупки и время обнаружения связи разделены.
+Минимум времени `purchase` не принят за границу появления новых связей:
+заказ может поступить позже события. Нужные изменения определяются по
+разности сохраненных наборов пар. Ежедневное наблюдение ограничивает момент
+появления связи интервалом; для пар начального наблюдения более ранняя
+история неизвестна. История сессий в этом опыте растет без исправлений
+прошлых дней, а связи не отзываются — поэтому сохраненных наборов связей
+достаточно для сравнения расчетов на прежних сессиях.
+
 ### Superset и BI
 
 Открывается после ступени 2 основной программы.
@@ -236,9 +283,28 @@
 - **Что будет, если день заменился не на всех шардах.** Замена дня завершается
   отдельно на каждом шарде, поэтому целостность результата подтверждает
   отдельная сверка.
-- **Как обновлять витрину без полной пересборки (#149) — повышенная
+- **[Как обновлять витрину без полной пересборки](../labs/optional/incremental-daily-traffic.md)
-  сложность.** Экономия на пересчете требует хранить историю изменений, которую
+  (#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 отклонена: для учебного сравнения достаточно
+своей витрины и журнала рядом с работающим конвейером.
 
 ### Что делать, когда стенд сломался
 

generator/README.md

@@ -1,98 +1,95 @@
-# Генератор кликстрима
+# Генератор событий и заказов
 
-Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по
+Генератор создает данные двух источников интернет-магазина. Счетчик сайта
-образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения —
+отправляет в топик Kafka `hits` события: просмотр страницы, добавление товара
-спека [«Генератор (этап 2)»](../docs/specs/2026-08-01-generator.md).
+в корзину и покупку. Серверная часть магазина выгружает в `orders` дневной
+слепок — состояние заказов, оформленных за последние семь модельных дней.
+Оба источника работают; хранилище принимает события непрерывно, заказы —
+по команде Airflow.
 
-События уже есть и уже уезжают: день-функция отдаёт по паре (зерно, D)
+Событие описывает отдельное действие посетителя. Заказ после оформления
-упорядоченный поток трёх видов — просмотр страницы, корзина, покупка, —
+может измениться, например перейти в статус `paid` или `cancelled`.
-канонический сериализатор превращает его в JSON, а проигрыватель гонит в файл
+Поэтому один `order_id` встречается в нескольких слепках. Часть заказов
-или в 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/world.py` — конфигурация мира: все его числа
+Все перечисленные модули находятся в `src/clickstream_generator/`.
-  одним местом. Правка любого — смена мира; крутить их и предлагается.
+
-- `src/clickstream_generator/seeds.py` — иерархия зёрен: кто из какого
+| Модули | Назначение |
-  подпотока берёт случайность. На ней держится весь детерминизм.
+|---|---|
-- `src/clickstream_generator/plan.py` — план состава: кто есть в мире в
+| `world.py`, `seeds.py`, `plan.py` | Настройки мира, случайные выборы и план посещений |
-  день D. Когорты, приток, двухкуковые пары, паспорта кук, человек за кукой
+| `reference.py`, `catalog.py` | Устройства, города, источники трафика и каталог товаров |
-  и счётчики — до генерации событий.
+| `day.py`, `commerce.py` | Визиты, события сайта и покупки |
-- `src/clickstream_generator/weights.py` — выбор по целым весам: один приём
+| `orders.py` | Состояние заказов на дату слепка, изменения и задержки |
-  на весь генератор, чтобы дисциплина целочисленной случайности не жила
+| `serialize.py`, `player.py`, `sinks.py` | Запись JSON и отправка в файл или Kafka |
-  копиями.
+| `cli.py` | Команды и параметры запуска |
-- `src/clickstream_generator/reference.py` — справочники: устройства,
+| `schema.py`, `schema_doc.py` | Описания колонок события и сборка документа выгрузки |
-  города, источники трафика, карта сайта. Таблицы-литералы: доля живёт в
+| `inventory.py` | Сборка паспорта мира с контрольными суммами и счетчиками |
-  строке, которой принадлежит.
+
-- `src/clickstream_generator/catalog.py` — каталог товаров из
+Тесты в `tests/` проверяют формат, правила модели и повторяемость данных.
-  `data/catalog/products.csv`, общего у генератора и словаря ClickHouse.
+Описание выгрузки и [паспорт мира](../data/world-inventory.json) собираются
-- `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/` используйте
-генератор»](../docs/architecture/world.md#как-запустить-генератор)
+`uv run python -m clickstream_generator <команда>`. Справку можно открыть
-справочника мира и `--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` тоже есть, но он про код стенда — даги и
+В корне `make lint` проверяет даги, код Superset и сборку карты архитектуры.
-Superset. Одноимённые цели за разными дверями охватывают разное:
+Корневые `make generate-batch` и `make generate-live` запускают события
-[карта проверок](../docs/architecture/testing.md).
+через контейнер генератора. Состав проверок — в
-
+[карте проверок](../docs/architecture/testing.md).
-Python и зависимости — через `uv`, версии закреплены в `uv.lock`: на этом
+Python и зависимости запускаются через `uv`; версии закреплены в `uv.lock`.
-держится обещание побайтовой воспроизводимости (спека, раздел 2).

generator/src/clickstream_generator/schema.py

@@ -420,7 +420,7 @@ COLUMNS: tuple[Column, ...] = (
         numpy_dtype="int64",
         normalized_name="product_price",
         group=ColumnGroup.ECOMMERCE,
-        comment="цена за штуку целым числом: деньги генератор считает целыми",
+        comment="цена за штуку, округленная до целых рублей",
     ),
     Column(
         name="productQuantity",

infra/clickhouse/users.d/access.xml

@@ -61,6 +61,11 @@
                 <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>
@@ -113,6 +118,14 @@
                 <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>

infra/grafana/provisioning/dashboards/cluster.json

@@ -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,11 +280,12 @@
           "min": 0
         },
         "overrides": []
-      }
+      },
+      "description": "Узлы дерева Keeper (znode) — записи со служебными данными координации ClickHouse."
     },
     {
       "type": "table",
-      "title": "Распределённый DDL: что прошло по кластеру и чем кончилось",
+      "title": "Распределенный DDL: результаты команд на узлах кластера",
       "datasource": {
         "type": "grafana-clickhouse-datasource",
         "uid": "clickhouse"

infra/grafana/provisioning/dashboards/data.json

@@ -11,7 +11,7 @@
   "panels": [
     {
       "type": "stat",
-      "title": "Свежесть: сколько прошло с последней доехавшей строки",
+      "title": "Свежесть: время с последней загрузки в ODS",
       "datasource": {
         "type": "grafana-clickhouse-datasource",
         "uid": "clickhouse"
@@ -48,7 +48,7 @@
     },
     {
       "type": "table",
-      "title": "Брак: сколько приехавшего не разобралось",
+      "title": "Брак: доля строк с ошибками разбора",
       "datasource": {
         "type": "grafana-clickhouse-datasource",
         "uid": "clickhouse"
@@ -72,11 +72,28 @@
           "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"
@@ -100,11 +117,28 @@
           "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": "Поток: сколько строк приезжает в сырой слой",
+      "title": "Поток: число сообщений, загруженных в STG",
       "datasource": {
         "type": "grafana-clickhouse-datasource",
         "uid": "clickhouse"
@@ -136,7 +170,7 @@
     },
     {
       "type": "timeseries",
-      "title": "Сходимость: произведено в Kafka против приземлившегося в ClickHouse",
+      "title": "Сходимость: число событий в Kafka и ClickHouse",
       "datasource": {
         "type": "datasource",
         "uid": "-- Mixed --"
@@ -161,7 +195,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
         },
         {
@@ -187,7 +221,7 @@
             "properties": [
               {
                 "id": "displayName",
-                "value": "приземлилось в ClickHouse"
+                "value": "загружено в ClickHouse"
               }
             ]
           }
@@ -197,7 +231,7 @@
     },
     {
       "type": "timeseries",
-      "title": "Отставание чтения из Kafka: непрочитанных сообщений",
+      "title": "Отставание чтения из Kafka: число непрочитанных сообщений",
       "datasource": {
         "type": "prometheus",
         "uid": "prometheus"

infra/grafana/provisioning/dashboards/queries.json

@@ -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,6 +93,10 @@
               {
                 "id": "unit",
                 "value": "bytes"
+              },
+              {
+                "id": "displayName",
+                "value": "Максимальная память запроса"
               }
             ]
           }
@@ -101,7 +105,7 @@
     },
     {
       "type": "table",
-      "title": "Ошибки: на чём запросы споткнулись",
+      "title": "Ошибки выполнения запросов",
       "datasource": {
         "type": "grafana-clickhouse-datasource",
         "uid": "clickhouse"
@@ -128,7 +132,20 @@
       ],
       "fieldConfig": {
         "defaults": {},
-        "overrides": []
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Чем кончилось"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Ошибка"
+              }
+            ]
+          }
+        ]
       }
     }
   ]

infra/superset/import/charts/purchase_vs_orders.yaml

@@ -1,4 +1,4 @@
-slice_name: Сверка purchase и заказов
+slice_name: Сверка событий покупки и заказов
 description: null
 certified_by: null
 certification_details: null

infra/superset/import/dashboards/business_stories.yaml

@@ -153,7 +153,7 @@ position:
       chartId: 2
       height: 44
       width: 12
-      sliceName: Сверка purchase и заказов
+      sliceName: Сверка событий покупки и заказов
       uuid: 19600000-0000-4000-8000-000000000102
   ROW-traffic:
     id: ROW-traffic

infra/superset/import/datasets/ClickHouse/daily_traffic_v.yaml

@@ -37,7 +37,7 @@ metrics:
   extra: null
   warning_text: null
 - metric_name: known_share
-  verbose_name: Доля известных
+  verbose_name: Доля известных пользователей
   metric_type: null
   expression: SUM(known_users) / nullIf(SUM(visitors), 0)
   description: null

infra/superset/import/datasets/ClickHouse/purchase_vs_orders_v.yaml

@@ -55,7 +55,7 @@ columns:
   datetime_format: null
   extra: null
 - column_name: declared_revenue
-  verbose_name: Выручка purchase
+  verbose_name: Заявленная сумма покупки из события
   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

infra/superset/import/datasets/ClickHouse/revenue_daily_v.yaml

@@ -125,7 +125,7 @@ columns:
   datetime_format: null
   extra: null
 - column_name: units
-  verbose_name: Товары
+  verbose_name: Продано единиц товара
   is_dttm: false
   is_active: true
   type: UINT64

scripts/run-dag.sh

@@ -24,10 +24,10 @@ compose() {
 next_step() {
     case "$DAG_ID" in
         world_initialize)
-            printf 'посмотрите журнал; повторите make up, а для недействительного мира — make rebuild-storage'
+            printf 'проверьте состояние запуска в Airflow и журнал задачи с ошибкой; после устранения причины повторите make up'
             ;;
-        world_recreate) printf 'устраните причину и повторите make rebuild-storage' ;;
+        world_recreate) printf 'проверьте состояние запуска в Airflow и журнал задачи с ошибкой; после устранения причины повторите make rebuild-storage' ;;
-        *) printf 'проверьте журнал дага и повторите команду' ;;
+        *) printf 'проверьте состояние запуска в Airflow и журнал задачи с ошибкой; после устранения причины повторите команду' ;;
     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} не появился за $((ATTEMPTS * PAUSE_SECONDS)) с; $(next_step)"
+    fail "даг ${DAG_ID} не появился в API за $((ATTEMPTS * PAUSE_SECONDS)) с; проверьте ошибки импорта в Airflow и журнал службы airflow-dag-processor"
 
 # 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)) с; $(next_step)"
+    fail "даг ${DAG_ID} не стал доступен для запуска за $((TRIGGER_ATTEMPTS * PAUSE_SECONDS)) с; проверьте ошибки импорта в Airflow и журнал службы airflow-dag-processor"
 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)

sql/ddl/20-ods-tables.sql

@@ -1,49 +1,20 @@
--- ODS: типизированное событие и таблица ошибок разбора.
---
--- Состав, имена и типы колонок списаны с «описания выгрузки»
--- (docs/formats/clickstream-event.md) — так же, как в бою хранилище пишут по
--- документации источника. Модуль контракта генератора здесь не читается:
--- граница «трекер | хранилище» проходит по документу.
--- Механика приёма и три класса брака — ADR 0005, конвенции имён, служебных
--- колонок и сроков — docs/architecture/storage.md.
-
 -- Локальная таблица события.
+-- Поля следуют docs/formats/clickstream-event.md; purchaseRevenue хранится
+-- в Decimal для точного счета денег. Правила приема — ADR 0005.
+-- ReplacingMergeTree оставляет последнюю доставку по _load_ts среди строк
+-- с одинаковым полным ORDER BY. Метка переносится из STG без пересчета.
+-- Она не входит в ключ сортировки или партиции: иначе повторные доставки
+-- не считались бы версиями одной строки. Для чтения служит ods.event_v с FINAL.
 --
--- Движок ReplacingMergeTree, колонка версии — _load_ts. Работа у версии ровно
+-- Партиция EventDate хранит модельный день события. CounterID на стенде
--- одна: схлопнуть повтор доставки. Метка не ставится здесь заново, а
+-- постоянен, EventDate постоянна внутри партиции; дальнейшая сортировка —
--- переносится из stg.hits_raw как есть — колонка отвечает на вопрос «когда
+-- по intHash32(ClientID) и WatchID. WatchID отличает события посетителя:
--- строка приехала в хранилище», а не «когда её разобрали». У повтора
+-- без него они заменяли бы друг друга.
--- содержимое то же самое, отличается только метка, поэтому какая из двух
--- строк переживёт мерж, безразлично.
 --
--- Колонка версии не входит ни в ключ партиции, ни в ключ сортировки, и это
+-- SAMPLE BY использует то же выражение, что ключ сортировки, и отбирает
--- не случайность: попади она туда — версии одной строки лягут в разные куски
+-- посетителей целиком. Sign всегда равен 1: поле сохранено по формату
--- или в разные места ключа и не встретятся при мерже, то есть дедупликация
+-- источника, но исправлений парой −1/+1 генератор не отправляет.
--- перестанет работать молча.
+
---
--- 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,
@@ -100,36 +71,24 @@ PARTITION BY EventDate
 ORDER BY (CounterID, EventDate, intHash32(ClientID), WatchID)
 SAMPLE BY intHash32(ClientID);
 
--- Лицо слоя: пишем и читаем через него. Ключ шардирования —
+-- Запись и диагностика через Distributed; актуальные события — в ods.event_v.
--- cityHash64(ClientID), а не сырой ClientID: структурированный числовой
+-- cityHash64(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,

sql/ddl/30-ods-views.sql

@@ -1,8 +1,6 @@
--- ODS: каноническое чтение актуальных событий.
+-- Актуальные события: FINAL выбирает последнюю доставку по _load_ts,
---
+-- не дожидаясь фоновых слияний. Поля и типы остаются как в ods.event_dist.
--- Представление сохраняет поля и зерно ods.event_dist, но скрывает FINAL от
+
--- потребителя. Поэтому физическая таблица остаётся местом диагностики
--- доставленных версий, а точное чтение получает одно имя.
 CREATE VIEW IF NOT EXISTS ods.event_v ON CLUSTER clickstream_cluster
 AS
 SELECT *
@@ -25,69 +23,24 @@ AS
 SELECT *
 FROM ods.order_dist FINAL;
 
--- ODS: разбор STG в событие и в таблицу ошибок.
+-- Разбор STG в события и ошибки. Два представления используют одинаковое
+-- условие годности; второе берет его отрицание. Условие дает только 0 или 1:
+-- NULL не выбрала бы ни одна ветвь. Функции разбора не вызывают исключений
+-- на некорректном raw, чтобы одно сообщение не прервало прием.
 --
--- Матвью две, и вместе они обязаны делить поток без зазора и без нахлёста:
+-- Оба представления срабатывают на вставку в stg.hits_raw_dist,
--- строка, подошедшая обеим, задвоится, а не подошедшая ни одной — исчезнет
+-- до распределения по шардам. Порядок SELECT совпадает с целевой таблицей.
--- молча. Держится это формой: годность считает один и тот же предикат из трёх
--- частей, а вторая матвью берёт его буквальное отрицание.
 --
--- Отсюда два запрета на выражения предиката, и оба серьёзные.
+-- Прием проверяет объект JSON, точный набор ключей и разбор пяти полей:
+-- WatchID, VisitID, ClientID, EventDate, UTCEventTime. Остальные поля
+-- извлекаются по формату без отдельной проверки. Граница — ADR 0005.
+-- arraySort с обеих сторон позволяет сравнить ключи независимо от порядка.
 --
--- Первый: ни одна его часть не возвращает NULL. Трёхзначная логика дала бы
+-- UTCEventTime приходит строкой вида "2026-06-01T12:34:56Z". Ее разбирает
--- строку, которую не берёт ни «условие», ни «NOT условие», — и потерялась бы
+-- parseDateTimeOrNull с явной маской: JSONExtract в DateTime такую форму
--- она бесшумно. Поэтому сравнения здесь дают 0 или 1, а разбор в Nullable
+-- не принимает, а BestEffort допускает неполные даты. Пояс UTC указан
--- заканчивается IS NOT NULL.
+-- отдельно, потому что Z в маске проверяется как буква. EventDate приходит
---
+-- как "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
@@ -154,10 +107,8 @@ SELECT
     JSONExtract(raw, 'GoalsReached', 'Array(UInt32)') AS GoalsReached,
     JSONExtract(raw, 'ParsedParamsKey1', 'Array(String)') AS ParsedParamsKey1,
     JSONExtract(raw, 'purchaseID', 'Array(String)') AS purchaseID,
-    -- Выгрузка несет JSON-числа типа Float64, но деньги хранятся в Decimal.
+    -- purchaseRevenue приходит числом рублей и разбирается сразу в Decimal.
-    -- JSONExtract разбирает их сразу, без промежуточного двоичного числа:
+    -- Прямой разбор сверяли через Context7 и на ClickHouse 26.3 (#155).
-    -- синтаксис подтвержден документацией 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,
@@ -168,25 +119,16 @@ SELECT
     JSONExtract(raw, 'productQuantity', 'Array(UInt64)') AS productQuantity,
     JSONExtract(raw, 'productEventType', 'Array(String)') AS productEventType,
     JSONExtract(raw, 'ecommerce', 'String') AS ecommerce,
-    -- Метка загрузки переносится из STG как есть, а не ставится заново:
+    -- _load_ts остается временем исходной доставки и версией события.
-    -- она отвечает на вопрос «когда строка приехала в хранилище». Поставь
-    -- здесь now64(3) — и колонка версии молча ответила бы на другой вопрос.
     _load_ts
 FROM stg.hits_raw_dist
 WHERE is_object AND keys_match AND key_fields_parsed;
 
--- Брак: буквальное отрицание того же предиката.
+-- Ошибки: отрицание того же условия годности.
---
+-- Класс определяется первым нарушенным условием. Например, JSON-строка
--- Классы брака пересекаются, поэтому проверяются по порядку, а в error_class
+-- не проходит и проверку объекта, и проверку ключей, но получает not_an_object.
--- пишется первый совпавший. Скаляр проваливает и проверку на объект, и сверку
+-- Условие повторено рядом с запросом, без отдельной функции 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

sql/ddl/40-stg-views.sql

@@ -1,26 +1,16 @@
--- STG: матвью приёма — из чтеца в таблицу STG.
+-- Прием событий из Kafka в STG.
+-- Подключение этого представления запускает чтение топика. Поэтому файл 40
+-- применяется после таблиц и представлений разбора из файлов 20 и 30:
+-- иначе часть сообщений сохранится в STG, но не попадет в ODS.
 --
--- Номер 40, а не 11, и пропуск в нумерации намеренный. Файлы 20-ods-tables.sql
+-- Запись через stg.hits_raw_dist распределяет сообщения по ключу таблицы.
--- и 30-ods-views.sql приносит #43, и матвью приёма обязана создаваться после
+-- Она фоновая; возможную потерю при сбое описывает раздел «Приём»
--- матвью разбора: Kafka-движок начинает читать топик ровно тогда, когда к нему
+-- в docs/architecture/storage.md.
--- привязывают первую матвью. Создай её раньше разбора — и всё, что доедет в
--- зазоре, ляжет в STG и не попадёт в ODS никуда, ни в событие, ни в ошибки.
--- На пустом топике зазор безвреден, поэтому первый прогон о нём не скажет:
--- проснётся он, когда тома ClickHouse снесены, а данные Kafka целы, то есть на
--- обычной отладке. Нумерацию здесь не «приводить в порядок».
 --
--- Пишем в stg.hits_raw_dist, а не в локальную таблицу: раскладку по шардам
+-- Сведения о доставке вычисляются здесь, на ноде чтения Kafka.
--- обязан определять ключ шардирования, а не то, какая нода случайно читала
+-- 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

sql/dds/order_rebuild.sql

@@ -1,21 +1,9 @@
--- 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;
 
@@ -37,18 +25,13 @@ INSERT INTO dds.order_stage_dist
     _load_id,
     _load_ts
 )
--- Позиции разбираются здесь один раз, на границе ODS → DDS. Цена на проводе —
+-- Разбор позиций из JSON: цена в строке сразу превращается в Decimal.
--- строка с двумя знаками, и JSONExtract читает её прямо в Decimal: замерено на
+-- ODS проверил только тип массива items. Неверное содержимое здесь может
--- живом слепке, промежуточный toDecimal64 не нужен.
+-- дать значения по умолчанию: qty вида "oops" и пропущенная цена дают 0,
---
+-- скаляр вместо объекта выпадает из массива. Наблюдения —
--- Разбор по типу молчалив, и знать об этом надо заранее. Строгий приём ODS
+-- docs/architecture/storage.md, «Что проверено».
--- проверил только, что items — массив, внутрь он не смотрел; здесь тоже никто
+-- Проверку суммы позиций участник добавляет в docs/labs/5-1-order-checks.md.
--- не смотрит. Замерено: qty вида "oops" даёт 0, пропущенная цена даёт 0,
+
--- скаляр вместо объекта выпадает из массива целиком. На каноническом слепке
--- генератора такого не бывает, и сумма «цена × количество» сходится с
--- items_total у всех заказов, но сходится она по свойству источника, а не
--- потому, что её здесь кто-то проверяет. Постоянное место такой проверки —
--- контур DQ этапа 4; пока она делается руками при приёмке.
 WITH JSONExtract(
         items, 'Array(Tuple(sku String, qty UInt32, price Decimal(18, 2)))'
     ) AS lines
@@ -56,8 +39,7 @@ SELECT
     order_id,
     user_id,
     status,
-    -- День заказа и оба времени переезжают в пояс счётчика: DDS обслуживает
+    -- День и время в Europe/Samara: витрины используют готовые колонки.
-    -- человека с дашбордом, и пояс называется здесь в последний раз.
     toDate(toTimeZone(created_at, 'Europe/Samara')),
     toTimeZone(created_at, 'Europe/Samara'),
     toTimeZone(updated_at, 'Europe/Samara'),
@@ -68,22 +50,17 @@ 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.
-    -- партиций: ODS нарезан по toDate(created_at) в UTC, и условие на
+    -- Модельные сутки Europe/Samara пересекают две даты 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;

sql/dds/order_replace.sql

@@ -1,28 +1,16 @@
--- DDS: подмена одного дня заказов собранной партицией двойника.
+-- Замена одного дня DDS готовой партицией донора.
+-- Повтор при неизменном источнике сохраняет деловые данные без дублей.
 --
--- Это и есть идемпотентность слоя. Повтор прогона безопасен, а «дыхание»
+-- ON CLUSTER выполняет замену на обеих нодах по локальным таблицам.
--- статусов внутри окна выражается сменой всей партиции, а не правкой строк.
+-- Донор и цель имеют одинаковую структуру и ключ шардирования
+-- (sql/ddl/45-dds-tables.sql); REPLACE PARTITION строки не перераспределяет.
+-- Замена атомарна внутри шарда. Между заменами на разных шардах читатель
+-- может увидеть часть прежних и часть новых данных. После сбоя этот период
+-- длится до успешного повтора. Пустая партиция донора удаляет день из цели.
 --
--- Замена идёт по локальным таблицам, шард за шардом: ON CLUSTER рассылает её
+-- День подставляет Jinja: параметры ClickHouse в ALTER ... PARTITION
--- на обе ноды, а по Distributed то же самое не работает — операции с
+-- не поддерживаются в закрепленной версии 26.3. Значение получено
--- партициями отвечают кодом 48 (docs/architecture/storage.md, «Что
+-- из результата order_scope.sql; замер — 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;

sql/dds/order_scope.sql

@@ -1,37 +1,17 @@
--- DDS: объём пересборки заказов — с какого дня по какой собирает этот запуск.
+-- Дни пересборки заказов: first_day и last_day, обе границы включены.
+-- Текущее окно — дни оформления заказов из последнего snapshot_date.
+-- Если в DDS нет дня, который есть в ODS, отрезок расширяется до первого
+-- такого дня. Это восстанавливает пропуски даже за пределами текущего окна.
 --
--- Параметров у дага нет: объём он выводит сам из состояния слоёв
+-- Дата слепка у актуальной версии показывает последнее наблюдение заказа
--- (docs/architecture/etl.md, «Объём прогона»). Ответ — две даты, границы
+-- (ADR 0014). Поэтому окно берется из данных, без копирования константы
--- непрерывного отрезка; список дней между ними разворачивает даг. Пустой
+-- генератора. FINAL здесь не нужен: created_at одинаков у всех версий,
--- источник даёт пустой ответ, и даг на нём останавливается с внятной ошибкой
+-- а строки последнего слепка сохраняются при слияниях.
--- вместо зелёного прогона, собравшего ничего.
 --
--- Файл кончается без точки с запятой: даг читает его целиком и шлёт одним
+-- Пустой ODS не дает строки результата; даг завершится ошибкой.
--- запросом, дописывая формат ответа, — точка с запятой сделала бы из этого
+-- Точка с запятой в конце не нужна: клиент дописывает FORMAT ответа.
--- мультизапрос, который ClickHouse не принимает.
+-- Порядок пересборки — docs/architecture/etl.md, «Объём прогона».
---
+
--- Объём складывается из двух частей. Первая — дышащее окно: дни, которые нёс
--- последний слепок, то есть те, чьё состояние источник ещё может изменить.
--- Вторая — хвост от первого дня, которого в слое нет: первая сборка застаёт
--- слой пустым и собирает весь стартовый мир, а после разгона мира пачкой слой
--- догоняет уехавший вперёд источник.
---
--- **Хвост считается от первого недостающего дня, а не от последнего
--- собранного.** Разница не косметическая: замены партиций идут отдельными
--- задачами и падают порознь, поэтому упавший день оставляет дыру, пока
--- соседние дни собираются дальше. Считай мы прогресс по максимуму собранного
--- дня, дыра позади окна не заросла бы никогда, а прогоны продолжали бы
--- зеленеть над щербатым слоем. Цена честного ответа — проход по дню заказа
--- в ODS.
---
--- Окно читается из ярлыка слепка, а не вычисляется вычитанием окна
--- изменяемости: у выжившей строки snapshot_date — последний слепок, который
--- нёс этот заказ (ADR 0014). Поэтому оба края окна знает сам источник, а
--- копии его константы на стороне стенда больше нет.
---
--- FINAL не нужен ни здесь, ни ниже: время рождения заказа у всех его версий
--- одно, а строки последнего слепка несут максимум колонки версии — мерж
--- оставляет как раз их.
 WITH
     (SELECT max(snapshot_date) FROM ods.order_dist) AS last_snapshot,
     (
@@ -44,10 +24,9 @@ WITH
         FROM ods.order_dist
         WHERE snapshot_date = last_snapshot
     ) AS window_end,
-    -- GLOBAL обязателен: обе таблицы распределённые, и обычный NOT IN сверял
+    -- GLOBAL NOT IN сравнивает дни со всем DDS. Локальное сравнение могло бы
-    -- бы дни источника с локальной частью слоя на каждом шарде — день, чьи
+    -- счесть день пропущенным, если его заказы находятся на соседнем шарде.
-    -- заказы легли на соседний шард, показался бы недостающим.
+    -- minOrNull возвращает NULL, когда пропущенных дней нет.
-    -- minOrNull отличает «дыр нет» от даты по умолчанию.
     (
         SELECT minOrNull(day)
         FROM (
@@ -57,7 +36,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

sql/ods/order_parse.sql

@@ -1,24 +1,15 @@
--- Разбор одного среза заказов: сначала годные версии, затем брак.
+-- Разбор сохраненной порции заказов: сначала годные версии, затем ошибки.
+-- Макрос Jinja подставляет одно условие годности в обе вставки.
+-- Вторая вставка берет его отрицание, чтобы каждая строка получила результат.
+-- Условие должно давать только 0 или 1 и не вызывать исключений на неверном raw.
 --
--- Обе вставки должны делить один предикат. Локальный макрос Jinja
+-- Проверяются одиннадцать полей верхнего уровня. Внутри items поля не проверяются;
--- разворачивает его в каждое выражение до того, как оператор разделит файл по
+-- позиции разбирает 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([
@@ -28,15 +19,14 @@ WITH
     ]) AS keys_match,
     JSONType(raw, 'order_id') = 'String'
         AND JSONType(raw, 'status') = 'String'
-        -- Целое у JSONType зовётся двумя именами, и нужны оба: с одним
+        -- JSONType различает Int64 и UInt64; принимаются оба, если значение
-        -- Int64 законный идентификатор за 2^63 уехал бы в брак.
+        -- разбирается в UInt64, в том числе идентификаторы больше 2^63−1.
         AND JSONType(raw, 'user_id') IN ('Int64', 'UInt64')
         AND JSONExtract(raw, 'user_id', 'Nullable(UInt64)') IS NOT NULL
         AND JSONType(raw, 'items') = 'Array'
-        -- Форму держит регулярка, реальность — разбор, и порознь они дырявы:
+        -- Регулярное выражение проверяет точную форму, включая ведущие нули.
-        -- маска берёт «2026-6-3T…» без ведущих нулей, а регулярка пропускает
+        -- Разбор проверяет само время: например, отвергает 30 февраля.
-        -- 30 февраля. Обе половины измерены — docs/architecture/storage.md,
+        -- Замеры функций — docs/architecture/storage.md, «Что проверено».
-        -- «Что проверено».
         AND arrayAll(k ->
                 JSONType(raw, k) = 'String'
                 AND match(JSONExtractString(raw, k),
@@ -44,9 +34,8 @@ 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}$')
@@ -60,11 +49,9 @@ 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() }}
@@ -81,30 +68,25 @@ 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, а не разобранной структурой.
+    -- items сохраняется строкой JSON для разбора позиций в DDS.
     JSONExtractRaw(raw, 'items') AS items,
     toDate(assumeNotNull(parseDateTimeInJodaSyntaxOrNull(
         JSONExtractString(raw, 'snapshot_date'),
         'yyyy-MM-dd', 'UTC'))) AS snapshot_date,
-    -- Метки запуска и прибытия переносятся как есть. Поставь здесь now64(3) —
+    -- _load_ts остается временем приема в STG; _load_id связывает с исходной порцией.
-    -- и _load_ts молча ответила бы на другой вопрос: «когда разобрали».
     _load_id,
     _load_ts
 FROM stg.orders_raw_dist
 WHERE _load_id = {load_id:String} AND row_is_valid
--- Заводская двойка parallel_distributed_insert_select исполняет вставку из
+-- Ноль заставляет распределить результат по ключу цели. При значении 2
--- Distributed в Distributed локально на каждом шарде, минуя ключ шардирования
+-- вставка может сохранить раскладку STG, где ключ — raw, вместо order_id.
--- цели, — так заказы и расползлись по обоим шардам. Ноль отдаёт раскладку
+-- Подробнее — docs/architecture/storage.md, «Раскладка по шардам».
--- инициатору, по ключу цели. Капкан целиком — docs/architecture/storage.md,
--- «Раскладка по шардам».
 SETTINGS distributed_foreground_insert = 1,
     parallel_distributed_insert_select = 0;
 
--- Брак: тот же срез и буквальное отрицание того же предиката.
+-- Ошибки: тот же срез и отрицание условия годности.
---
+-- Класс определяется первым нарушенным условием: например, JSON-строка
--- Классы перекрываются, поэтому проверяются по порядку, а в error_class идёт
+-- не проходит и проверку объекта, и проверку ключей, но получает not_an_object.
--- первый совпавший: скаляр проваливает и проверку на объект, и сверку ключей —
--- без объявленного порядка он попал бы то в один класс, то в другой.
 
 INSERT INTO ods.order_errors_dist
 {{ order_wire_contract() }}
@@ -124,7 +106,6 @@ 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;

sql/stg/orders_raw_load.sql

@@ -1,15 +1,11 @@
--- Забор порции слепка заказов из Kafka в STG.
+-- Порция сообщений заказов из Kafka в STG, без разбора JSON.
+-- Один SELECT читает одну порцию; непрочитанное остается до следующего запуска.
+-- Полнота слепка не проверяется. Если после чтения вставка упадет, подтвержденные
+-- сообщения уже не перечитаются (docs/architecture/orders/ingestion.md).
 --
--- Забор — один прямой SELECT, без цикла до пустоты: одна порция ClickHouse
+-- stream_like_engine_allow_direct_select разрешает прямое чтение Kafka;
--- берёт десятки тысяч сообщений, а слепок дня — порядка полутора тысяч строк.
+-- 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