docs(orders): спека превращена в принятый живой набор architecture/orders
Зачем: датированная спека — событие истории, а устройство компонента — живой документ; большое полотно плохо грузится и агентом, и человеком (ADR 0011). Что: вычитание #84 слито с переустройством формы: набор docs/architecture/orders/ — индекс README и семь файлов по частям устройства (нарезка по правилу «семь плюс-минус два»); датированные файлы удалены, ссылки перенацелены, AGENTS.md дополнен правилом подпапки. Приёмка владельцем #88 пройдена, черновой статус снят из README. Проверка: холодная сверка миграции свежим тредом — потерь решений нет; обход относительных ссылок набора — битых нет. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -7,7 +7,7 @@
|
||||
партиция топика и отсутствие матвью. Отменены граница «одно чтение — полный
|
||||
слепок», замена партиции `snapshot_date`, ODS без дедупликации и готовая схема
|
||||
`dds.order` с `argMax`. Действующая форма STG → ODS описана в
|
||||
[спецификации приёма заказов](../specs/2026-08-16-order-ingestion.md).
|
||||
[спецификации приёма заказов](../architecture/orders/ingestion.md).
|
||||
|
||||
## Решение
|
||||
|
||||
@@ -17,8 +17,8 @@
|
||||
прочитанное в `stg.orders_raw_dist`, разбирает его в типизированный слепок и
|
||||
заменяет партицию дня в `ods.order_snapshot`. Тот же даг проигрывает модельный
|
||||
день генератором, поэтому переливается ровно то, что он положил в топик.
|
||||
Уточнение со сдвигом отправки, решённым позже (#71, [спека
|
||||
заказов](../specs/2026-08-16-orders.md), раздел 2): даг, играющий день D, в
|
||||
Уточнение со сдвигом отправки, решённым позже (#71, [слепок и его
|
||||
доставка](../architecture/orders/snapshot.md)): даг, играющий день D, в
|
||||
штатном прогоне кладёт и забирает слепок дня D−1 — слепок предыдущего дня, а
|
||||
не сыгранного. После падения между шагами в топике может ждать и хвост
|
||||
прежних слепков; забор принимает всё приехавшее.
|
||||
|
||||
@@ -34,4 +34,4 @@
|
||||
Малый объём позволяет оставить одно чтение на запуск как проверяемое
|
||||
эксплуатационное допущение, а не границу полноты. Полный контракт разбора,
|
||||
граница брака и поведение повторов заданы в
|
||||
[спецификации приёма заказов](../specs/2026-08-16-order-ingestion.md).
|
||||
[спецификации приёма заказов](../architecture/orders/ingestion.md).
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# ADR 0011. Устройство компонента — связный набор живых документов
|
||||
|
||||
Дата: 16 августа 2026 года. Статус: принято.
|
||||
|
||||
## Решение
|
||||
|
||||
Детальное устройство крупного компонента живёт в `docs/architecture/`
|
||||
подпапкой: индекс `README.md` — целевая картина и указатели — и отдельный
|
||||
файл на каждую часть устройства. Имена — слаги без дат; набор правится по
|
||||
мере постройки, как и остальные справочники этой папки.
|
||||
|
||||
Первый такой набор — [заказы бэкенда](../architecture/orders/README.md),
|
||||
собранный из спеки этапа 3 и спеки приёма. Датированные файлы
|
||||
`2026-08-16-orders.md` и `2026-08-16-order-ingestion.md` удалены, ссылки на
|
||||
них перенацелены; историю держит git.
|
||||
|
||||
## Почему
|
||||
|
||||
**Спека и базовая документация — разные жанры, а файл был один.** Спека —
|
||||
событие: проект изменения с датой в имени, замерзающий после приёмки. Но
|
||||
собранная спека заказов сразу стала и детальным устройством сервиса — тем
|
||||
документом, по которому этап 3 будут строить и с которым потом сверяться.
|
||||
Живому устройству дата в имени врёт, а замерзать ему нельзя.
|
||||
|
||||
**Один большой документ плохо читается обоими читателями.** Агент, строящий
|
||||
судьбу заказа, вынужден везти в контексте формат провода и приём; человек
|
||||
листает пятьсот строк ради одного раздела. Индекс с файлами по частям даёт
|
||||
обоим одно и то же: загружается только нужная часть, а карта целого — один
|
||||
экран.
|
||||
|
||||
**Долговечно только то, что в git.** Резолюции развилок живут в трекере, а
|
||||
трекер долговечным хранилищем не считается. Поэтому решения — вместе с
|
||||
отклонёнными вариантами при каждом правиле — лежат в файлах набора; ссылки
|
||||
на тикеты остаются вежливостью, не записью.
|
||||
|
||||
## Следствия
|
||||
|
||||
- `docs/specs/` остаётся событиям: мастер-спека и спека генератора живут как
|
||||
есть; переводить ли их в живую форму — отдельное решение, когда встанет.
|
||||
- Раздел «Структура» в AGENTS.md обновлён тем же коммитом.
|
||||
- Ссылки из ADR 0008 и 0010, мастер-спеки, спеки генератора, исследования
|
||||
формата и доки хранилища перенацелены на набор.
|
||||
Reference in New Issue
Block a user