Files

T

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

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

2026-08-04 00:21:43 +03:00

7.0 KiB

Raw Blame History

Handoff: конвенции хранилища и приём событий (#37)

Дата: 4 августа 2026 года. Ветка: docs/37-storage-conventions.

Что это было

Сессия началась с вопроса «хватает ли информации, чтобы взять #37 в работу». Оказалось, что нет: тикет молча опирался на конвенции хранилища, которых в проекте не существовало. Дальше шёл грилинг пяти развилок, затем два холодных ревью — по линии дефектов и по линии уместности, — затем правки по их находкам.

Кода не написано ни строки. Итог сессии — принятые решения и приведённые в соответствие постановки.

Где лежат решения

Ничего из перечисленного здесь не пересказывается — читать по адресам:

docs/adr/0005-event-ingestion.md — как принимаем события: чтец читает топик байтами, разбор идёт функциями в матвью ODS. Там же отвергнутые варианты и цена решения.
docs/adr/0006-object-naming.md — суффикс вида в именах объектов.
docs/architecture/storage.md — рабочий справочник: конвенции имён и служебных колонок, раскладка по шардам, путь в keeper, срок жизни сырья, свойства приёма, раскладка файлов DDL, карта таблиц.
docs/specs/2026-07-30-stand-v2-realism.md — правлены разделы 6, 7, 9, 11, «Витрины DM» и опорные точки для лекций.
docs/specs/2026-08-01-generator.md — раздел 4 получил контракт транспорта «одно событие — одно сообщение Kafka».
Тикеты #37 и #43 переписаны целиком; у каждого сверху комментарий с разбором того, что изменилось против исходной постановки, — читать tea issues 37 --comments.

Коммит с документами — 319db30, он же единственный на ветке помимо этого файла.

Чего не переоткрывать

Всё ниже прошло грилинг с веером вариантов и записано с доводами. Если решение кажется странным — сначала прочитать довод, а не начинать заново:

имена объектов: суффикс вида, а не префикс и не _all;
служебная колонка загрузки _load_ts, метаданные доставки без ведущего подчёркивания;
нарезка сырья по дню загрузки, а не по модельному дню; TTL трое суток;
модельного дня в STG нет вовсе;
формат чтеца RawBLOB, режим kafka_handle_error_mode не используется;
строгий приём: сверка набора ключей плюс Nullable на пяти опорных колонках, не на сорока семи;
источник матвью разбора — stg.hits_raw_dist, пишем только в _dist, distributed_foreground_insert = 1;
путь в keeper /clickhouse/tables/{shard}/{database}/{table}, без {uuid}.

Что осталось

По убыванию веса:

Проверки на живом стенде, две из них внесены в раздел 11 мастер-спеки: RawBLOB даёт ровно одну строку на сообщение; форма именованного кортежа в JSONExtract с Nullable-членами. Не внесены, но всплыли в ревью: как make up --wait поведёт себя с одноразовым сервисом, у которого нет зависимых долгоживущих (существующие airflow-init и superset-init переживают --wait только за счёт зависимостей), и как аккуратнее навесить distributed_foreground_insert на путь приёма — это настройка уровня запроса, вероятно через профиль пользователя в конфиге.
PR не открыт. Ветка запушена, тело PR писать с английским Closes #NN, иначе Gitea задачу не закроет (см. docs/agents/issue-tracker.md).
Третий холодный проход — по желанию владельца. Оба документа переписаны после ревью существенно, а разделы про keeper, таблицу ошибок и свойства приёма ревьюеры не видели вовсе.
Реализация #37 — собственно этап, ради которого всё затевалось.

Что стоит знать про ход работы

Владелец правит рекомендации по существу и часто оказывается прав: из пяти развилок три пересматривались по его возражениям. Предлагать вариант с доводом, а не спрашивать «как сделать», — и быть готовым, что довод разберут.
Спека не выбита в камне: менять её аргументированно можно и нужно, но обсуждая с владельцем, а не молча.
Трекер — Gitea, только через tea, при проблемах с прокси префикс NO_PROXY='*'. Тикеты читать с --comments: хвосты живут там.
Сверка спорных API ClickHouse — через MCP Context7 до кода, не после.

Suggested skills

brainstorm-with-docs — если всплывёт новая развилка. Именно им шла эта сессия; формат «веер вариантов, потом конвергенция» владельцу привычен.
claude-subagent-playbook — когда #37 пойдёт в реализацию: конвейер с делегированием механической части и слепым ревью.
conventional-commits — обязателен при любом коммите в этом репозитории.
code-review — для ревью изменений перед приёмкой.

7.0 KiB Raw Blame History Unescape Escape