Версия заказа в ODS — дата слепка: привести код и документы к ADR 0014 #165

New Issue

2026-08-26T13:37:49+03:00

ddmitry commented

2026-08-26 13:37:49 +03:00

Из развилки #163 (part of #6). Решение принято и записано в
ADR 0014 —
там доводы, границы допущения и отклонённые варианты. Тикет их не дублирует:
здесь только объём работ.

Цель

Привести код и документы к ADR 0014: версия ods.order_rep —
snapshot_date вместо updated_at. Слой становится детерминированным,
объём пересборки DDS читается из данных, константа K уходит со стенда.

Что войдёт

DDL. sql/ddl/20-ods-tables.sql: колонка версии движка и переписанный
комментарий «четырёх координат». Смена версии не применяется ALTER и не
подхватывается живым миром (DDL исполняется при рождении, CREATE IF NOT EXISTS): правка вступает в силу через make rebuild-storage, это строка
процедуры — сторожей в скрипты решение #163 не заводит.
Объём пересборки. sql/dds/order_scope.sql: дышащее окно — дни,
которые нёс последний слепок (отбор по snapshot_date = max(snapshot_date);
FINAL не нужен — слияние сохраняет максимум даты по построению). Снять K
со стенда: якорь x-order-window-days и ORDER_WINDOW_DAYS из
compose.yaml, константу из dags/dds_transform.py, параметр
window_days из запроса.
Комментарии SQL, аргументирующие от жребия: order_scope.sql,
order_rebuild.sql, 45-dds-tables.sql (упоминание версии по
updated_at), 30-ods-views.sql (кто задаёт версию под FINAL).
Документы тем же PR.
- orders/ingestion.md: «Роль ODS» — ярлык из жребия становится фактом;
  условие «одна дата — один слепок» — в границу строгого приёма; замер
  произвола ярлыков перенесён основанием в ADR 0014.
- etl.md: «Объём прогона» — абзацы «они отвечают не на тот вопрос»
  снимаются вместе с причиной; в «Чего конвейер о себе не знает» пункты
  «окно K разъехалось» и «пустой свежий день» заменяются одним более
  узким: потеря строк последнего слепка (частичный отказ вставки после
  коммита офсетов) молча сужает окно.
- dds/order.md, «Служебные колонки»: правило «чужие ярлыки не переезжают»
  остаётся, его довод меняется со «жребия» на «читателя нет» (наследство
  #85 не переоткрывать).
- storage.md: «Версии заказов», контраст с событием в «Служебных
  колонках», «Что проверено» (строка про FINAL и поздний updated_at).
- Мастер-спека и orders/README.md: упоминания версии по updated_at.
- docs/research/2026-08-16-order-snapshot-wire-format.md: точечная
  приписка «вывод о колонке версии пересмотрен ADR 0014», текст не
  переписывать — документ историчен.

Границы — не трогать

Механика пересборки #151: двойник, REPLACE PARTITION, DROP PARTITION ALL, пошардовая замена, вся сборка order_rebuild.sql.
Хвост «от первой дыры» в order_scope.sql — он про состояние слоя DDS.
Слепые пятна «полузамена на одном шарде» и «брак в items» в etl.md.
Генератор: ORDER_WINDOW_DAYS в world.py — владелец числа, остаётся.
Журнал загрузок — не здесь (границы #163).

Кому что

Переписывание доводов в доках и комментариях — Opus. Codex — механический
обход упоминаний по списку, пересборка мира, прогон замеров по брифу.

Сначала прочитать

docs/adr/0014-order-version-snapshot-date.md — решение целиком;
резолюция развилки в #163 (комментарий при закрытии) — условия ревью;
sql/ddl/20-ods-tables.sql и sql/dds/order_scope.sql — что меняется;
docs/architecture/etl.md, «Объём прогона» — что снимается.

Проверка

make lint; на стенде make rebuild-storage, затем make smoke,
make check-clickhouse, make check-services зелёные.
Движок ods.order_rep на стенде — ReplacingMergeTree(snapshot_date)
(system.tables.engine_full), мир пересобран.
Замер правдивости ярлыка: после нескольких слепков snapshot_date
каждой строки ods.order_v равен последнему слепку, который нёс её
заказ.
ods.order_v построчно совпадает с эталоном argMax по updated_at
из сырья: деловое содержимое сменой версии не изменилось.
Прогон dds_transform без K: объём равен дням последнего слепка плюс
дырам слоя; повтор прогона делового содержимого не меняет.
Греп по репозиторию: не осталось текста, называющего updated_at
колонкой версии ods.order.

Из развилки #163 (part of #6). Решение принято и записано в [ADR 0014](https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/adr/0014-order-version-snapshot-date.md) — там доводы, границы допущения и отклонённые варианты. Тикет их не дублирует: здесь только объём работ. ## Цель Привести код и документы к ADR 0014: версия `ods.order_rep` — `snapshot_date` вместо `updated_at`. Слой становится детерминированным, объём пересборки DDS читается из данных, константа K уходит со стенда. ## Что войдёт - **DDL.** `sql/ddl/20-ods-tables.sql`: колонка версии движка и переписанный комментарий «четырёх координат». Смена версии не применяется `ALTER` и не подхватывается живым миром (DDL исполняется при рождении, `CREATE IF NOT EXISTS`): правка вступает в силу через `make rebuild-storage`, это строка процедуры — сторожей в скрипты решение #163 не заводит. - **Объём пересборки.** `sql/dds/order_scope.sql`: дышащее окно — дни, которые нёс последний слепок (отбор по `snapshot_date = max(snapshot_date)`; `FINAL` не нужен — слияние сохраняет максимум даты по построению). Снять K со стенда: якорь `x-order-window-days` и `ORDER_WINDOW_DAYS` из `compose.yaml`, константу из `dags/dds_transform.py`, параметр `window_days` из запроса. - **Комментарии SQL, аргументирующие от жребия:** `order_scope.sql`, `order_rebuild.sql`, `45-dds-tables.sql` (упоминание версии по `updated_at`), `30-ods-views.sql` (кто задаёт версию под `FINAL`). - **Документы тем же PR.** - `orders/ingestion.md`: «Роль ODS» — ярлык из жребия становится фактом; условие «одна дата — один слепок» — в границу строгого приёма; замер произвола ярлыков перенесён основанием в ADR 0014. - `etl.md`: «Объём прогона» — абзацы «они отвечают не на тот вопрос» снимаются вместе с причиной; в «Чего конвейер о себе не знает» пункты «окно K разъехалось» и «пустой свежий день» заменяются одним более узким: потеря строк последнего слепка (частичный отказ вставки после коммита офсетов) молча сужает окно. - `dds/order.md`, «Служебные колонки»: правило «чужие ярлыки не переезжают» остаётся, его довод меняется со «жребия» на «читателя нет» (наследство #85 не переоткрывать). - `storage.md`: «Версии заказов», контраст с событием в «Служебных колонках», «Что проверено» (строка про `FINAL` и поздний `updated_at`). - Мастер-спека и `orders/README.md`: упоминания версии по `updated_at`. - `docs/research/2026-08-16-order-snapshot-wire-format.md`: точечная приписка «вывод о колонке версии пересмотрен ADR 0014», текст не переписывать — документ историчен. ## Границы — не трогать - Механика пересборки #151: двойник, `REPLACE PARTITION`, `DROP PARTITION ALL`, пошардовая замена, вся сборка `order_rebuild.sql`. - Хвост «от первой дыры» в `order_scope.sql` — он про состояние слоя DDS. - Слепые пятна «полузамена на одном шарде» и «брак в items» в `etl.md`. - Генератор: `ORDER_WINDOW_DAYS` в `world.py` — владелец числа, остаётся. - Журнал загрузок — не здесь (границы #163). ## Кому что Переписывание доводов в доках и комментариях — Opus. Codex — механический обход упоминаний по списку, пересборка мира, прогон замеров по брифу. ## Сначала прочитать - `docs/adr/0014-order-version-snapshot-date.md` — решение целиком; - резолюция развилки в #163 (комментарий при закрытии) — условия ревью; - `sql/ddl/20-ods-tables.sql` и `sql/dds/order_scope.sql` — что меняется; - `docs/architecture/etl.md`, «Объём прогона» — что снимается. ## Проверка - [ ] `make lint`; на стенде `make rebuild-storage`, затем `make smoke`, `make check-clickhouse`, `make check-services` зелёные. - [ ] Движок `ods.order_rep` на стенде — `ReplacingMergeTree(snapshot_date)` (`system.tables.engine_full`), мир пересобран. - [ ] Замер правдивости ярлыка: после нескольких слепков `snapshot_date` каждой строки `ods.order_v` равен последнему слепку, который нёс её заказ. - [ ] `ods.order_v` построчно совпадает с эталоном `argMax` по `updated_at` из сырья: деловое содержимое сменой версии не изменилось. - [ ] Прогон `dds_transform` без K: объём равен дням последнего слепка плюс дырам слоя; повтор прогона делового содержимого не меняет. - [ ] Греп по репозиторию: не осталось текста, называющего `updated_at` колонкой версии `ods.order`.

ddmitry added the ready-for-agent label 2026-08-26 13:37:59 +03:00

ddmitry referenced this issue from a commit

2026-08-26 13:38:50 +03:00

docs(adr): версия заказа в ODS пересмотрена на дату слепка

ddmitry referenced this issue

2026-08-26 13:39:25 +03:00

Координаты доставки в ODS: ярлык, которому нельзя верить #163

ddmitry self-assigned this 2026-08-26 13:59:04 +03:00

ddmitry referenced this issue

2026-08-26 16:12:16 +03:00

feat(dds): модель сессии и нарезка визитов окнами #166

ddmitry referenced this issue from a commit