docs(ingestion): упростить объяснения источников и приема данных #250

New Issue

2026-09-13T20:32:39+03:00

ddmitry commented

2026-09-13 20:32:39 +03:00

Режим выполнения

Редактуру выполняет Codex самостоятельно, без субагентов. Рекомендуемый reasoning effort: medium. Словарь рекомендуется выполнить первым: его определения станут опорой для остальных материалов.

Чему учит

Прослеживать путь события и версии заказа от генератора до таблиц хранилища и объяснять, как обрабатываются ошибки и повторные поступления.

Работа

Объединить материалы ступеней 5–6 с вводной генератора: они описывают одни и те же два источника. Сверять текст с обработкой данных, а комментарии к SQL — со справочником.

Границы прохода:

generator/README.md: вводная, обзор устройства и команды. Убрать устаревшее утверждение, что второй источник и отправка снимков заказов еще строятся. Подробности реализации раскрывать ссылками на существующие документы.
docs/architecture/orders/ingestion.md: поток данных, правила приема, роль ODS, чтение Kafka.
docs/architecture/dds/order.md: действующая модель и наполнение.
docs/architecture/storage.md: разделы о служебных колонках, актуальных событиях, версиях заказов, приеме потока, сроке жизни сырых данных и таблице ошибок. Разделы об именах и шардах относятся к задаче о витринах и сессиях.
Комментарии к примерам приема и сборки: sql/stg/orders_raw_load.sql, sql/ods/order_parse.sql, sql/dds/order_{scope,rebuild,replace}.sql, относящиеся к приему событий части sql/ddl/{20-ods-tables,30-ods-views,40-stg-views}.sql и пояснения dags/orders_ingest.py.

Не переписывать все устройство генератора и заказов. Сгенерированный docs/formats/clickstream-event.md использовать для сверки, вручную не редактировать.

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

Вводная генератора описывает оба действующих источника и соответствует текущим командам.
Понятны различия события и снимка заказов, сырого сообщения и разобранной записи, времени события и времени загрузки.
Можно проследить, куда попадает некорректная запись и как выбирается актуальная версия; термины объяснены через конкретные поля и действия.
Сохранены фактические правила снимков, задержек, окна пересчета, денежных единиц, хранения сырья и обработки ошибок.
Код, SQL, схемы и поведение стенда не изменены; решения самостоятельных заданий не добавлены.

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

CONTEXT.md, задания ступеней 5–6 из docs/labs/README.md, docs/handbook/generator.md, docs/handbook/storage-layers.md, затем перечисленные справочники и исходники. Команды сверять с generator/src/clickstream_generator/cli.py и обоими Makefile.

Связанная задача о worker: #183 . Не включать сюда массовое переименование терминов.

Проверка

git diff --check; проверить ссылки и соответствие команд исходникам. Сравнить SQL без комментариев. Если менялся Python, выполнить корневой make lint и проверить отсутствие изменений логики. Не генерировать новые дни и не сбрасывать состояние стенда ради вычитки.

Общие границы

Это продолжение редактуры материалов для начинающего инженера данных. Образцы языка — корневой README, главы docs/handbook/ и задания docs/labs/. Писать простым русским языком; термины объяснять при первом употреблении. Не упрощать технический смысл и не подменять объяснение образными оборотами.

Уже вычитанные лабораторные, handbook и карту не переписывать. Исторические спеки, ADR и внутренние инструкции не входят в задачу. Перед приемкой сделать проход на сокращение: убрать повторы и пояснения, которые не помогают пройти учебную программу. Имена объектов, технические условия и полезные примеры сохранить.

## Режим выполнения Редактуру выполняет Codex самостоятельно, без субагентов. Рекомендуемый reasoning effort: `medium`. Словарь рекомендуется выполнить первым: его определения станут опорой для остальных материалов. ## Чему учит Прослеживать путь события и версии заказа от генератора до таблиц хранилища и объяснять, как обрабатываются ошибки и повторные поступления. ## Работа Объединить материалы ступеней 5–6 с вводной генератора: они описывают одни и те же два источника. Сверять текст с обработкой данных, а комментарии к SQL — со справочником. Границы прохода: - `generator/README.md`: вводная, обзор устройства и команды. Убрать устаревшее утверждение, что второй источник и отправка снимков заказов еще строятся. Подробности реализации раскрывать ссылками на существующие документы. - `docs/architecture/orders/ingestion.md`: поток данных, правила приема, роль ODS, чтение Kafka. - `docs/architecture/dds/order.md`: действующая модель и наполнение. - `docs/architecture/storage.md`: разделы о служебных колонках, актуальных событиях, версиях заказов, приеме потока, сроке жизни сырых данных и таблице ошибок. Разделы об именах и шардах относятся к задаче о витринах и сессиях. - Комментарии к примерам приема и сборки: `sql/stg/orders_raw_load.sql`, `sql/ods/order_parse.sql`, `sql/dds/order_{scope,rebuild,replace}.sql`, относящиеся к приему событий части `sql/ddl/{20-ods-tables,30-ods-views,40-stg-views}.sql` и пояснения `dags/orders_ingest.py`. Не переписывать все устройство генератора и заказов. Сгенерированный `docs/formats/clickstream-event.md` использовать для сверки, вручную не редактировать. ## Критерии приемки - [x] Вводная генератора описывает оба действующих источника и соответствует текущим командам. - [x] Понятны различия события и снимка заказов, сырого сообщения и разобранной записи, времени события и времени загрузки. - [x] Можно проследить, куда попадает некорректная запись и как выбирается актуальная версия; термины объяснены через конкретные поля и действия. - [x] Сохранены фактические правила снимков, задержек, окна пересчета, денежных единиц, хранения сырья и обработки ошибок. - [x] Код, SQL, схемы и поведение стенда не изменены; решения самостоятельных заданий не добавлены. ## Сначала прочитать `CONTEXT.md`, задания ступеней 5–6 из `docs/labs/README.md`, `docs/handbook/generator.md`, `docs/handbook/storage-layers.md`, затем перечисленные справочники и исходники. Команды сверять с `generator/src/clickstream_generator/cli.py` и обоими Makefile. Связанная задача о worker: https://git.dementev.space/ddmitry/clickstream-data-platform/issues/183 . Не включать сюда массовое переименование терминов. ## Проверка `git diff --check`; проверить ссылки и соответствие команд исходникам. Сравнить SQL без комментариев. Если менялся Python, выполнить корневой `make lint` и проверить отсутствие изменений логики. Не генерировать новые дни и не сбрасывать состояние стенда ради вычитки. ## Общие границы Это продолжение редактуры материалов для начинающего инженера данных. Образцы языка — корневой README, главы `docs/handbook/` и задания `docs/labs/`. Писать простым русским языком; термины объяснять при первом употреблении. Не упрощать технический смысл и не подменять объяснение образными оборотами. Уже вычитанные лабораторные, handbook и карту не переписывать. Исторические спеки, ADR и внутренние инструкции не входят в задачу. Перед приемкой сделать проход на сокращение: убрать повторы и пояснения, которые не помогают пройти учебную программу. Имена объектов, технические условия и полезные примеры сохранить.

ddmitry added the ready-for-agent label 2026-09-13 20:32:39 +03:00

ddmitry self-assigned this 2026-09-13 22:26:04 +03:00

ddmitry referenced this issue from a commit

2026-09-13 23:33:08 +03:00

docs(ingestion): упрощены объяснения источников и приема данных

ddmitry referenced this issue from a commit

2026-09-13 23:33:08 +03:00

docs(ingestion): влита редактура приема данных (#250)

ddmitry closed this issue

2026-09-13 23:33:08 +03:00

Sign in to join this conversation.