docs(orders): устройство заказов переехало в живой набор architecture/orders

Зачем: собранная спека заказов стала базовой документацией сервиса, а
жанр спеки-события ей мал: дата в имени врёт, целиком в контекст агента
она не влезает, а трекер с резолюциями долговечным хранилищем не
считается. Решение владельца — держать детальное устройство компонента
связным набором живых документов (ADR 0011) и совместить переезд с
проходом на вычитание (#84).

Что: docs/architecture/orders/ — индекс README и файлы по частям
устройства: проекция, слепок и доставка, судьба, классы расхождений,
опись, мост к склейке, стартовый мир, правила кода; спека приёма
переехала в ingestion.md без содержательных правок. Резы вычитания по
итогам двух слепых линий: тела разделов о проводе и приёме сведены к
указателям на мастер-спеку, исследование формата и ADR (порядок строк
слепка — единственное правило, оставшееся на месте); замеры канонического
зерна и повторы-пояснения срезаны; списки отклонённых вариантов сохранены
как долговечная запись. Датированные файлы удалены, ссылки из мастер-спеки,
спеки генератора, ADR 0008/0010, исследования формата и storage.md
перенацелены; раздел «Структура» AGENTS.md дополнен правилом подпапки.

Проверка: grep по репозиторию не находит ссылок на удалённые файлы;
все относительные ссылки внутри набора разрешаются в существующие файлы;
впереди холодная сверка «ни одно решение не потеряно» и приёмка #88.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-16 23:50:13 +03:00
co-authored by Claude Fable 5
parent b9f570fc40
commit 0d9a83d6af
19 changed files with 498 additions and 573 deletions
+3 -3
View File
@@ -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 — слепок предыдущего дня, а
не сыгранного. После падения между шагами в топике может ждать и хвост
прежних слепков; забор принимает всё приехавшее.
+1 -1
View File
@@ -34,4 +34,4 @@
Малый объём позволяет оставить одно чтение на запуск как проверяемое
эксплуатационное допущение, а не границу полноты. Полный контракт разбора,
граница брака и поведение повторов заданы в
[спецификации приёма заказов](../specs/2026-08-16-order-ingestion.md).
[спецификации приёма заказов](../architecture/orders/ingestion.md).
+42
View File
@@ -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, мастер-спеки, спеки генератора, исследования
формата и доки хранилища перенацелены на набор.