docs(handoff): передача контекста удалена как отработавшая
- Зачем:
- список «чего не переоткрывать» устарел за день: снятая настройка
синхронной вставки и прежняя раскладка 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>
This commit is contained in:
Claude Opus 5
@@ -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` — для ревью изменений перед приёмкой.
|
|
||||||
Reference in New Issue
Block a user