From f1254ce79d91af60159d6f508bc3c0bb72edcbaf Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Wed, 5 Aug 2026 21:31:32 +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=D1=83=D0=B4=D0=B0=D0=BB=D0=B5=D0=BD=D0=B0=20?= =?UTF-8?q?=D0=BA=D0=B0=D0=BA=20=D0=BE=D1=82=D1=80=D0=B0=D0=B1=D0=BE=D1=82?= =?UTF-8?q?=D0=B0=D0=B2=D1=88=D0=B0=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - список «чего не переоткрывать» устарел за день: снятая настройка синхронной вставки и прежняя раскладка DDL остались в нём как принятые решения, а документ, утверждающий решённым переехавшее, — ловушка. - Что: - удалён .scratch/handoffs/2026-08-04-storage-conventions.md; содержание живёт в ADR 0005 и 0006, доке хранилища и тикетах #37 и #43. - Проверка: - make config-test Co-Authored-By: Claude Opus 5 --- .../2026-08-04-storage-conventions.md | 91 ------------------- 1 file changed, 91 deletions(-) delete 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 deleted file mode 100644 index 27a591e..0000000 --- a/.scratch/handoffs/2026-08-04-storage-conventions.md +++ /dev/null @@ -1,91 +0,0 @@ -# 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` — для ревью изменений перед приёмкой.