From dedb6c6739ccd21f437e7894d16e895d70e9ff68 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Tue, 4 Aug 2026 00:21:43 +0300 Subject: [PATCH] =?UTF-8?q?docs(handoff):=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B4?= =?UTF-8?q?=D0=B0=D1=87=D0=B0=20=D0=BA=D0=BE=D0=BD=D1=82=D0=B5=D0=BA=D1=81?= =?UTF-8?q?=D1=82=D0=B0=20=D0=BF=D0=BE=20=D0=BA=D0=BE=D0=BD=D0=B2=D0=B5?= =?UTF-8?q?=D0=BD=D1=86=D0=B8=D1=8F=D0=BC=20=D1=85=D1=80=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=BB=D0=B8=D1=89=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - работа над #37 продолжится в новой сессии, а решения сессии разбросаны по двум ADR, доке хранилища, двум спекам и двум тикетам; свежему агенту нужен один вход с указателями и списком того, что переоткрывать не надо. - Что: - добавлен .scratch/handoffs/2026-08-04-storage-conventions.md: указатели на артефакты, перечень принятых развилок, открытые хвосты и особенности работы с трекером. - Проверка: - make config-test --- .../2026-08-04-storage-conventions.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 .scratch/handoffs/2026-08-04-storage-conventions.md diff --git a/.scratch/handoffs/2026-08-04-storage-conventions.md b/.scratch/handoffs/2026-08-04-storage-conventions.md new file mode 100644 index 0000000..27a591e --- /dev/null +++ b/.scratch/handoffs/2026-08-04-storage-conventions.md @@ -0,0 +1,91 @@ +# 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}`. + +## Что осталось + +По убыванию веса: + +1. **Проверки на живом стенде**, две из них внесены в раздел 11 мастер-спеки: + `RawBLOB` даёт ровно одну строку на сообщение; форма именованного кортежа в + `JSONExtract` с `Nullable`-членами. Не внесены, но всплыли в ревью: как + `make up --wait` поведёт себя с одноразовым сервисом, у которого нет + зависимых долгоживущих (существующие `airflow-init` и `superset-init` + переживают `--wait` только за счёт зависимостей), и как аккуратнее навесить + `distributed_foreground_insert` на путь приёма — это настройка уровня + запроса, вероятно через профиль пользователя в конфиге. +2. **PR не открыт.** Ветка запушена, тело PR писать с английским `Closes #NN`, + иначе Gitea задачу не закроет (см. `docs/agents/issue-tracker.md`). +3. **Третий холодный проход** — по желанию владельца. Оба документа переписаны + после ревью существенно, а разделы про keeper, таблицу ошибок и свойства + приёма ревьюеры не видели вовсе. +4. **Реализация #37** — собственно этап, ради которого всё затевалось. + +## Что стоит знать про ход работы + +- Владелец правит рекомендации по существу и часто оказывается прав: из пяти + развилок три пересматривались по его возражениям. Предлагать вариант с + доводом, а не спрашивать «как сделать», — и быть готовым, что довод разберут. +- Спека не выбита в камне: менять её аргументированно можно и нужно, но + обсуждая с владельцем, а не молча. +- Трекер — Gitea, только через `tea`, при проблемах с прокси префикс + `NO_PROXY='*'`. Тикеты читать с `--comments`: хвосты живут там. +- Сверка спорных API ClickHouse — через MCP Context7 до кода, не после. + +## Suggested skills + +- `brainstorm-with-docs` — если всплывёт новая развилка. Именно им шла эта + сессия; формат «веер вариантов, потом конвергенция» владельцу привычен. +- `claude-subagent-playbook` — когда #37 пойдёт в реализацию: конвейер с + делегированием механической части и слепым ревью. +- `conventional-commits` — обязателен при любом коммите в этом репозитории. +- `code-review` — для ревью изменений перед приёмкой.