docs(generator): путеводитель по генератору #48

New Issue

2026-08-02T16:25:36+03:00

ddmitry commented

2026-08-02 16:25:36 +03:00

Зачем

Генератор компактен, но нетривиален: многое в нём — соглашения, а не
конструкции. Из кода не выводятся чтением ни дерево зёрен и запрет менять
порядок бросков, ни ленивость мира, ни причина целочисленной случайности.
Спека это частично объясняет, но она отвечает «почему выбрано так», а не «как
это работает»: решение и путеводитель — разные жанры. Стенд учебный, и человек,
который откроет генератор впервые, сейчас разбирается сам.

Тикет заведён при исполнении #39 по замечанию владельца, прочитавшего код.
Отложен намеренно: торговые события (#40) и запуск снаружи (#41) поменяют и
вход, и середину, а путеводитель, написанный до них, придётся переписывать
дважды.

Что сделать

Документ-путеводитель по генератору: рассказ по цепочке зерно → подпотоки →
когорты → аудитория дня → визиты → строки событий, с ссылками в модули вместо
пересказа их содержимого.

Разобрать то, что чтением кода не берётся:

дерево зёрен: зачем подпотоки и почему порядок бросков внутри подпотока —
часть контракта, а не деталь реализации;
ленивость мира: когорта по требованию, предыстория до D0, окно активности —
отсюда «любой день собирается сам по себе»;
паспорт куки: почему устройство и город приписывает план, а не день;
целочисленная случайность: почему не берутся готовые распределения numpy и
что за арифметика в weights.py;
шов между днём и торговыми событиями;
сутки в поясе счётчика и следствие toDate(UTCEventTime) ≠ EventDate.

Плюс две вещи, которые для учебного стенда весят больше текста:

картинка цепочки (mermaid — Gitea его рисует);
запускаемый пример, собирающий день и показывающий промежуточные стадии:
когорта, аудитория, визиты, строки. Читатель должен увидеть мир, а не только
прочитать про него.

Критерии приёмки

Путеводитель написан и лежит по конвенции docs/ — папки для этого
жанра пока нет, место и имя решаются в тикете и записываются в AGENTS.md.
Все шесть тем выше разобраны; ни одна не пересказывает спеку, а ссылается
на неё.
Картинка цепочки есть и открывается в Gitea.
Пример запускается одной командой, отрабатывает на канонических зерне и
дне, вывод помещается на экран.
Пример сторожится тестом или целью make: документ, который перестал
работать, хуже отсутствующего.
README.md генератора ссылается на путеводитель, раздел «Как это
работает» в нём при этом остаётся коротким.

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

generator/README.md — раздел «Как это работает»: путеводитель его
разворачивает, а не повторяет.
docs/specs/2026-08-01-generator.md — разделы 1, 2, 9.
docs/specs/2026-07-30-stand-v2-realism.md — разделы 1.1–1.2, 3, 5.
CONTEXT.md — словарь: термины путеводителя должны совпадать с ним.

Границы

Документ описывает генератор, а не весь стенд.
Решения не переоткрываются: путеводитель объясняет принятое, а спорное
выносит вопросом владельцу.
Код генератора правится только если пример этого требует; поведение мира не
меняется.

Зависимость

Берётся после #41: до него неизвестны и вход генератора, и способ запуска.

## Зачем Генератор компактен, но нетривиален: многое в нём — соглашения, а не конструкции. Из кода не выводятся чтением ни дерево зёрен и запрет менять порядок бросков, ни ленивость мира, ни причина целочисленной случайности. Спека это частично объясняет, но она отвечает «почему выбрано так», а не «как это работает»: решение и путеводитель — разные жанры. Стенд учебный, и человек, который откроет генератор впервые, сейчас разбирается сам. Тикет заведён при исполнении #39 по замечанию владельца, прочитавшего код. Отложен намеренно: торговые события (#40) и запуск снаружи (#41) поменяют и вход, и середину, а путеводитель, написанный до них, придётся переписывать дважды. ## Что сделать Документ-путеводитель по генератору: рассказ по цепочке зерно → подпотоки → когорты → аудитория дня → визиты → строки событий, с ссылками в модули вместо пересказа их содержимого. Разобрать то, что чтением кода не берётся: - дерево зёрен: зачем подпотоки и почему порядок бросков внутри подпотока — часть контракта, а не деталь реализации; - ленивость мира: когорта по требованию, предыстория до D0, окно активности — отсюда «любой день собирается сам по себе»; - паспорт куки: почему устройство и город приписывает план, а не день; - целочисленная случайность: почему не берутся готовые распределения numpy и что за арифметика в `weights.py`; - шов между днём и торговыми событиями; - сутки в поясе счётчика и следствие `toDate(UTCEventTime) ≠ EventDate`. Плюс две вещи, которые для учебного стенда весят больше текста: - **картинка** цепочки (mermaid — Gitea его рисует); - **запускаемый пример**, собирающий день и показывающий промежуточные стадии: когорта, аудитория, визиты, строки. Читатель должен увидеть мир, а не только прочитать про него. ## Критерии приёмки - [ ] Путеводитель написан и лежит по конвенции `docs/` — папки для этого жанра пока нет, место и имя решаются в тикете и записываются в AGENTS.md. - [ ] Все шесть тем выше разобраны; ни одна не пересказывает спеку, а ссылается на неё. - [ ] Картинка цепочки есть и открывается в Gitea. - [ ] Пример запускается одной командой, отрабатывает на канонических зерне и дне, вывод помещается на экран. - [ ] Пример сторожится тестом или целью `make`: документ, который перестал работать, хуже отсутствующего. - [ ] `README.md` генератора ссылается на путеводитель, раздел «Как это работает» в нём при этом остаётся коротким. ## Сначала прочитать - `generator/README.md` — раздел «Как это работает»: путеводитель его разворачивает, а не повторяет. - `docs/specs/2026-08-01-generator.md` — разделы 1, 2, 9. - `docs/specs/2026-07-30-stand-v2-realism.md` — разделы 1.1–1.2, 3, 5. - `CONTEXT.md` — словарь: термины путеводителя должны совпадать с ним. ## Границы - Документ описывает генератор, а не весь стенд. - Решения не переоткрываются: путеводитель объясняет принятое, а спорное выносит вопросом владельцу. - Код генератора правится только если пример этого требует; поведение мира не меняется. ## Зависимость Берётся после #41: до него неизвестны и вход генератора, и способ запуска.

ddmitry added the needs-triage label 2026-08-02 16:25:36 +03:00

ddmitry commented

2026-08-02 16:28:47 +03:00

Хвост из #39 (2026-08-02)

В generator/README.md появился раздел «Как это работает» — цепочка от зерна до строк событий, ленивость мира, правило порядка бросков, причина целочисленной случайности. Раздел помечен черновым: по сути он верен, но на понятность читателем со стороны не выверен.

Отсюда два пункта в этот тикет:

выверить язык раздела и снять пометку «черновой»;
проверить, что раздел и путеводитель не расходятся и не повторяют друг друга: раздел остаётся коротким входом, путеводитель разворачивает.

Судить понятность должен тот, кто устройство генератора в голове не держит: автор текста — худший судья собственной понятности.

Хвост из #39 (2026-08-02) В `generator/README.md` появился раздел «Как это работает» — цепочка от зерна до строк событий, ленивость мира, правило порядка бросков, причина целочисленной случайности. Раздел помечен черновым: по сути он верен, но на понятность читателем со стороны не выверен. Отсюда два пункта в этот тикет: - выверить язык раздела и снять пометку «черновой»; - проверить, что раздел и путеводитель не расходятся и не повторяют друг друга: раздел остаётся коротким входом, путеводитель разворачивает. Судить понятность должен тот, кто устройство генератора в голове не держит: автор текста — худший судья собственной понятности.

ddmitry referenced this issue from a commit

2026-08-02 16:30:24 +03:00

docs(generator): README — черновой раздел «Как это работает»

ddmitry referenced this issue

2026-08-02 16:30:52 +03:00

feat(generator): день-функция — трафик, визиты и просмотры страниц #49

ddmitry referenced this issue

2026-08-07 20:15:33 +03:00

Этап 2: DDL и генератор #4

ddmitry added a new dependency 2026-08-07 20:20:58 +03:00

#63 Часовые пояса: конвенция для абсолютного времени и производных дат

Sign in to join this conversation.