docs(storage): конвенции хранилища и приём событий перед этапом 2 #52

2026-08-05T22:08:02+03:00

ddmitry commented

2026-08-05 22:08:02 +03:00

Решения, которые #37 и #43 молча предполагали, а в репозитории их не было.
Кода нет — только документы.

Что вошло

ADR 0005 — приём событий: чтец читает топик байтами, разбор идёт
функциями в матвью ODS. Там же отвергнутые варианты и цена решения.
ADR 0006 — имена объектов: суффикс вида (_rep, _dist, _kafka,
_mv, _v).
docs/architecture/storage.md — рабочий справочник зоны: имена,
служебные колонки, раскладка по шардам, путь в keeper, срок жизни сырья,
свойства приёма, раскладка файлов DDL, карта таблиц и раздел «Что проверено».
Правки мастер-спеки и спеки генератора: пять опорных колонок названы
поимённо, источник матвью разбора выправлен, четыре витрины переименованы
под конвенцию, форма дат на проводе зафиксирована (ISO-8601), развилка по
приёму заказов помечена нерешённой.
README и AGENTS.md: каталоги docs/adr/ и docs/architecture/
перестали быть недостижимыми, у нового каталога появилось правило имён.

Как проверялось

Три холодных ревью в разных линзах — механика приёма, полнота конвенций, связь
с окружением. Затем сверка каждого утверждения о поведении ClickHouse с
документацией через MCP Context7: 38 утверждений, два опровергнуты и
исправлены. Затем ещё два прохода: связность внесённых правок и тикеты как
наряд на работу — последний вскрыл, что #41 с сериализатором идёт позже #43,
чьи проверки стоят на реальных событиях.

Что осталось непроверенным

Пять утверждений о поведении ClickHouse помечены в доке хранилища как взятые по
памяти — документация их не описывает. Закрывает их стенд: четыре опыта
поручены в #37, пятый в #43, каждый с записью результата обратно в документ.

Тикеты

#37 и #43 остаются открытыми: этот PR их ставит, а не выполняет.

Решения, которые #37 и #43 молча предполагали, а в репозитории их не было. Кода нет — только документы. ## Что вошло - **ADR 0005** — приём событий: чтец читает топик байтами, разбор идёт функциями в матвью ODS. Там же отвергнутые варианты и цена решения. - **ADR 0006** — имена объектов: суффикс вида (`_rep`, `_dist`, `_kafka`, `_mv`, `_v`). - **`docs/architecture/storage.md`** — рабочий справочник зоны: имена, служебные колонки, раскладка по шардам, путь в keeper, срок жизни сырья, свойства приёма, раскладка файлов DDL, карта таблиц и раздел «Что проверено». - **Правки мастер-спеки и спеки генератора**: пять опорных колонок названы поимённо, источник матвью разбора выправлен, четыре витрины переименованы под конвенцию, форма дат на проводе зафиксирована (ISO-8601), развилка по приёму заказов помечена нерешённой. - **README и AGENTS.md**: каталоги `docs/adr/` и `docs/architecture/` перестали быть недостижимыми, у нового каталога появилось правило имён. ## Как проверялось Три холодных ревью в разных линзах — механика приёма, полнота конвенций, связь с окружением. Затем сверка каждого утверждения о поведении ClickHouse с документацией через MCP Context7: 38 утверждений, два опровергнуты и исправлены. Затем ещё два прохода: связность внесённых правок и тикеты как наряд на работу — последний вскрыл, что #41 с сериализатором идёт позже #43, чьи проверки стоят на реальных событиях. ## Что осталось непроверенным Пять утверждений о поведении ClickHouse помечены в доке хранилища как взятые по памяти — документация их не описывает. Закрывает их стенд: четыре опыта поручены в #37, пятый в #43, каждый с записью результата обратно в документ. ## Тикеты #37 и #43 остаются открытыми: этот PR их ставит, а не выполняет.

ddmitry added 5 commits 2026-08-05 22:08:04 +03:00

docs(storage): приняты решения по приёму событий и именам 319db308bf

- Зачем:
  - тикет #37 молча опирался на конвенции хранилища, которых в проекте не
    было; без них #43 и следующие этапы разъехались бы в именах, служебных
    колонках и механике приёма.
- Что:
  - ADR 0005: топик читается байтами в STG, разбор идёт функциями в матвью
    ODS; строгий приём — сверка набора ключей плюс Nullable на пяти опорных
    колонках.
  - ADR 0006: суффикс вида в именах объектов (_rep, _dist, _kafka, _mv, _v).
  - docs/architecture/storage.md: конвенции имён и служебных колонок, путь в
    keeper, раскладка по шардам, срок жизни сырья, свойства приёма, раскладка
    файлов DDL и карта таблиц.
  - спеки приведены в соответствие: механизм строгого приёма, имена объектов,
    контракт транспорта «одно событие — одно сообщение Kafka», три проверки
    при исполнении.
- Проверка:
  - make config-test

docs(handoff): передача контекста по конвенциям хранилища dedb6c6739

- Зачем:
  - работа над #37 продолжится в новой сессии, а решения сессии разбросаны по
    двум ADR, доке хранилища, двум спекам и двум тикетам; свежему агенту нужен
    один вход с указателями и списком того, что переоткрывать не надо.
- Что:
  - добавлен .scratch/handoffs/2026-08-04-storage-conventions.md: указатели на
    артефакты, перечень принятых развилок, открытые хвосты и особенности
    работы с трекером.
- Проверка:
  - make config-test

docs(storage): конвенции и приём событий выправлены после ревью 31b274175a

- Зачем:
  - три холодных ревью и сверка с документацией ClickHouse нашли противоречия
    между докой, ADR и спекой: исполнитель #37 получал два разных ответа на
    один вопрос, а два утверждения о движке оказались неверными.
- Что:
  - раскладка файлов DDL перестроена — сначала таблицы, матвью приёма
    последней: иначе часть событий тихо минует ODS.
  - синхронная вставка снята с пути приёма: настройка недостижима для потока
    Kafka-движка и связывает шарды; на ETL-вставках осталась.
  - у таблицы ошибок появился класс брака с порядком проверки, у сырья и
    ошибок названы движки и ключи сортировки.
  - в доку добавлен раздел «Что проверено»: сверенное с документацией,
    проверяемое на стенде и сказанное по памяти разведены.
  - в спеке выправлены источник матвью разбора, пять опорных колонок, имена
    четырёх витрин и ссылка на несуществующую цель make.
- Проверка:
  - make config-test
  - grep по устаревшим именам файлов DDL и витрин — пусто

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs(handoff): передача контекста удалена как отработавшая f1254ce79d

- Зачем:
  - список «чего не переоткрывать» устарел за день: снятая настройка
    синхронной вставки и прежняя раскладка DDL остались в нём как принятые
    решения, а документ, утверждающий решённым переехавшее, — ловушка.
- Что:
  - удалён .scratch/handoffs/2026-08-04-storage-conventions.md; содержание
    живёт в ADR 0005 и 0006, доке хранилища и тикетах #37 и #43.
- Проверка:
  - make config-test

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs(storage): связность восстановлена, форма дат на проводе задана 923ebad80e

- Зачем:
  - холодное ревью связности нашло девять мест, где вставленный текст спорит с
    соседним; отдельно вскрылось, что представление дат в JSON не зафиксировано
    нигде, а #43 обязан его знать раньше, чем #41 напишет сериализатор.
- Что:
  - гарантия приёма переписана: после снятия синхронной вставки «хотя бы один
    раз» стало неправдой — есть и окно потери, и окно дубля.
  - критерий выбора пяти опорных колонок приведён к списку, который он
    порождает; `CounterID` оговорён отдельно.
  - «переобработки у ODS нет вовсе» смягчено до пакетной: ручная вставка из
    сырья в пределах окна возможна.
  - в спеку генератора добавлена форма дат на проводе — ISO-8601, с доводом от
    читаемости слоя сырья.
  - убраны осиротевшая фраза про порядок сервисов, дубль порядка классов брака,
    устаревшая датировка сверки и ещё три следа вставок.
- Проверка:
  - make config-test

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

ddmitry merged commit a0144e0fff into main

2026-08-05 22:09:41 +03:00

ddmitry deleted branch docs/37-storage-conventions

2026-08-05 22:09:42 +03:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ddmitry/clickstream-data-platform#52