docs(glossary): четыре термина переименованы, world.md и stand.md вычитаны

- Зачем:
  - справочники читает человек со стороны, а «пульт мира», «опись мира»,
    «работник» и «сырьё» звучали шуткой или калькой времён разработки
    (тикет #214, выбор владельца).
- Что:
  - CONTEXT.md: статьи «Паспорт мира», «Даги модельного времени»,
    «Шаговый даг», «Сырые данные», старые слова в строках «Избегать»;
    пометки в ADR 0005, 0008, 0009 без переписывания решений.
  - замены по README, справочникам, путеводителю, лабам, спекам,
    комментариям дагов и SQL, тегу дага и панели Grafana; имена в коде
    не тронуты.
  - world.md и stand.md: 35 находок вычитки внесены, регистр выровнен.
- Проверка:
  - make config-test; make lint в корне и в generator/; make test в
    generator/ (437 passed); скрипт ссылок из #212 пуст; grep старых
    слов вне ADR, research и CONTEXT.md пуст.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014QBCtU38qSHg5DvgtnKXcW
This commit is contained in:
ddadminandClaude Fable 5.1 committed 2026-09-02 16:46:50 +03:00
1 parent 86ad8afaf2
commit 59d8c83b17
54 files changed
+794 -776

No files matched your search

+7 -7
View File
@@ -1,6 +1,6 @@
-- STG: чтецы топиков hits и orders, таблицы сырья обоих источников.
-- STG: чтецы топиков hits и orders, таблицы STG обоих источников.
--
-- Слой сырья ничего не интерпретирует: сообщение ложится строкой, как пришло,
-- Сырой слой ничего не интерпретирует: сообщение ложится строкой, как пришло,
-- рядом с метаданными доставки. Довод целиком — ADR 0005, конвенции колонок и
-- сроков — docs/architecture/storage.md.
@@ -30,9 +30,9 @@ SETTINGS
kafka_group_name = 'clickstream_hits',
kafka_format = 'RawBLOB';
-- Локальная таблица сырья.
-- Локальная таблица STG.
--
-- Движок именно ReplicatedMergeTree, не Replacing: повтор доставки в сырье
-- Движок именно ReplicatedMergeTree, не Replacing: повтор доставки в STG
-- обязан быть виден — ради этого слой и заведён.
--
-- Служебные колонки не повторяют имён виртуальных (_topic, _partition,
@@ -45,7 +45,7 @@ SETTINGS
-- колонки _timestamp_ms, а не из _timestamp. Измерено на стенде 5 августа
-- 2026 года: _timestamp — Nullable(DateTime), то есть секунды; _timestamp_ms —
-- Nullable(DateTime64(3)). Взяты миллисекунды: у брокера метка миллисекундная,
-- _load_ts рядом тоже миллисекундная, а слой сырья хранит то, что приехало, и
-- _load_ts рядом тоже миллисекундная, а сырой слой хранит то, что приехало, и
-- округлять ему нечего. Обнуляемость обязательна: метку брокер заполняет не
-- всегда, а необнуляемый тип дал бы либо падение приёма, либо тихий 1970 год.
--
@@ -115,8 +115,8 @@ SETTINGS
kafka_format = 'RawBLOB',
kafka_commit_on_select = 1;
-- Локальная таблица сырья заказов. Колонки, типы, ключ, нарезка и срок жизни —
-- те же, что у сырья событий, и по тем же доводам: docs/architecture/storage.md.
-- Локальная таблица STG заказов. Колонки, типы, ключ, нарезка и срок жизни —
-- те же, что у STG событий, и по тем же доводам: docs/architecture/storage.md.
--
-- Своя колонка здесь одна — _load_id, идентификатор пачки загрузки: он равен
-- run_id прогона Airflow, который забрал порцию, и по нему разбор в ODS читает
+3 -3
View File
@@ -106,7 +106,7 @@ SAMPLE BY intHash32(ClientID);
-- События одной куки при этом остаются на одном шарде, и сессионизация со
-- склейкой идентичностей ниже по течению живут локально.
--
-- У сырья ключ другой (хеш строки), поэтому сырая строка и разобранное из неё
-- У STG ключ другой (хеш строки), поэтому сырая строка и разобранное из неё
-- событие почти всегда лежат на разных шардах. Пошардовые счётчики слоёв
-- сходиться не должны — сверять слои можно только через _dist.
CREATE TABLE IF NOT EXISTS ods.event_dist ON CLUSTER clickstream_cluster
@@ -125,10 +125,10 @@ ENGINE = Distributed('clickstream_cluster', 'ods', 'event_rep', cityHash64(Clien
-- Ключи собственные. Шардирование — 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
(
+2 -2
View File
@@ -25,7 +25,7 @@ AS
SELECT *
FROM ods.order_dist FINAL;
-- ODS: разбор сырья в событие и в таблицу ошибок.
-- ODS: разбор STG в событие и в таблицу ошибок.
--
-- Матвью две, и вместе они обязаны делить поток без зазора и без нахлёста:
-- строка, подошедшая обеим, задвоится, а не подошедшая ни одной — исчезнет
@@ -168,7 +168,7 @@ SELECT
JSONExtract(raw, 'productQuantity', 'Array(UInt64)') AS productQuantity,
JSONExtract(raw, 'productEventType', 'Array(String)') AS productEventType,
JSONExtract(raw, 'ecommerce', 'String') AS ecommerce,
-- Метка загрузки переносится из сырья как есть, а не ставится заново:
-- Метка загрузки переносится из STG как есть, а не ставится заново:
-- она отвечает на вопрос «когда строка приехала в хранилище». Поставь
-- здесь now64(3) — и колонка версии молча ответила бы на другой вопрос.
_load_ts
+2 -2
View File
@@ -1,10 +1,10 @@
-- STG: матвью приёма — из чтеца в сырьё.
-- STG: матвью приёма — из чтеца в таблицу STG.
--
-- Номер 40, а не 11, и пропуск в нумерации намеренный. Файлы 20-ods-tables.sql
-- и 30-ods-views.sql приносит #43, и матвью приёма обязана создаваться после
-- матвью разбора: Kafka-движок начинает читать топик ровно тогда, когда к нему
-- привязывают первую матвью. Создай её раньше разбора — и всё, что доедет в
-- зазоре, ляжет в сырьё и не попадёт в ODS никуда, ни в событие, ни в ошибки.
-- зазоре, ляжет в STG и не попадёт в ODS никуда, ни в событие, ни в ошибки.
-- На пустом топике зазор безвреден, поэтому первый прогон о нём не скажет:
-- проснётся он, когда тома ClickHouse снесены, а данные Kafka целы, то есть на
-- обычной отладке. Нумерацию здесь не «приводить в порядок».
+1 -1
View File
@@ -17,7 +17,7 @@
-- Позиция — номер первого несыгранного дня, счётчик прожитого. Своей копии
-- начала оси стенд из-за неё не заводит: начало он спрашивает у данных, и
-- дата дня N в них — константа, начало оси плюс N. Держится якорь на том, что
-- ранние дни из ods.event не исчезают: срок жизни назначен сырью и таблицам
-- ранние дни из ods.event не исчезают: срок жизни назначен сырым данным и таблицам
-- ошибок, самому событию — нет (sql/ddl/20-ods-tables.sql).
--
-- За «доехал» позиция не отвечает — только за «прожит». Перед расчётом объёма
+2 -2
View File
@@ -1,8 +1,8 @@
-- DQ: стендовая сторона технической растяжки от описи мира.
-- DQ: стендовая сторона технической растяжки от паспорта мира.
--
-- Эталонные счётчики читает Airflow из world-inventory.json: у настоящего
-- магазина такого оракула нет. Запрос возвращает только наблюдаемую сторону;
-- Python-задача сопоставляет ее с пятью счетчиками закрытого дня из описи.
-- Python-задача сопоставляет ее с пятью счетчиками закрытого дня из паспорта.
SELECT
order_day AS data_date,
mismatch_class,
+1 -1
View File
@@ -124,7 +124,7 @@ SELECT
_load_ts
FROM stg.orders_raw_dist
WHERE _load_id = {load_id:String} AND NOT row_is_valid
-- Тот же ноль: ключ брака сегодня совпадает с ключом сырья, и локальная
-- Тот же ноль: ключ брака сегодня совпадает с ключом STG, и локальная
-- запись легла бы верно — но по совпадению, а не по контракту.
SETTINGS distributed_foreground_insert = 1,
parallel_distributed_insert_select = 0;
+1 -1
View File
@@ -1,4 +1,4 @@
-- Забор порции слепка заказов из Kafka в сырьё STG.
-- Забор порции слепка заказов из Kafka в STG.
--
-- Забор — один прямой SELECT, без цикла до пустоты: одна порция ClickHouse
-- берёт десятки тысяч сообщений, а слепок дня — порядка полутора тысяч строк.