ddmitry/clickstream-data-platform
1
0 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Глава путеводителя «Хранилище и его слои» #218

New Issue
Closed
opened 2026-09-02 22:50:10 +03:00 by ddmitry · 1 comment
ddmitry commented 2026-09-02 22:50:10 +03:00
Owner
Copy link
Copy source

Part of #206

Цель

Первая глава путеводителя: docs/handbook/storage-layers.md. Читатель проходит путь данных от сообщения Kafka до витрины и понимает, за что отвечает каждый слой и по каким колонкам слои соединяются. Глава ведет в справочники, а не пересказывает их. Форма главы — образец для следующих глав путеводителя.

Скелет главы (порядок разделов зафиксирован)

  1. Вводка. В хранилище два потока из Kafka: события кликстрима (топик hits) и заказы магазина (топик orders). Путь один: STG → ODS → DDS → DM. Одна простая mermaid-схема пути.
  2. Как читать имена. Читают через объекты с суффиксом _v; остальные суффиксы (_rep, _dist, _kafka, _mv) — устройство, о нем — в справочнике. Коротко, без таблицы всех суффиксов.
  3. Слои по одному. По разделу на STG, ODS, DDS, DM: за что отвечает, что в нем лежит, одна деталь-крючок. STG — «как привезли», сырая строка с метаданными доставки, живет трое суток. ODS — типизировано, язык источника, брак уходит в таблицы *_errors. DDS — язык бизнеса: событие, заказ, сессия, карта идентичностей; сессию стенд режет из событий сам. DM — витрины под дашборды.
  4. Сбоку цепочки. Зона dic и словарь товаров: его никто из слоев не производит, читают все. Два абзаца.
  5. Ключи, по которым слои соединяются. Маленькая таблица колонок: WatchID, ClientID, order_id, sku, EventDate — что означает и какие слои соединяет. Семантика — по справочнику хранилища и CONTEXT.md (посетитель — кука, ClientID).
  6. Посмотрите сами. Два коротких SELECT по _v-поверхностям: например, события одного дня из ods.event_v и выручка по категориям из dm.revenue_daily_v. Подключение — ссылкой на «Адреса и пароли» корневого README.
  7. Куда дальше. Справочник хранилища за подробностями; следующая глава — потоки Airflow.

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

  • docs/handbook/storage-layers.md написан по скелету; детали устройства — ссылками в справочники, не пересказом.
  • Каждая колонка таблицы ключей существует в схеме (sql/ddl/) и названа словом из CONTEXT.md.
  • Оба SELECT обращаются только к _v-поверхностям и синтаксически верны; прогон на живом стенде — за оркестратором на приёмке.
  • docs/handbook/README.md: раздел «Будущие главы» становится «Главы», аннотация первой ведет в файл главы, у остальных остается «Пока главы нет…».
  • Адресация — «вы», как в README путеводителя; слова «менти» в тексте нет; буквы «ё» в новом тексте нет; тире «—» и кавычки-елочки, как в соседних документах.
  • Все относительные ссылки главы и README путеводителя целы.

Границы

  • Справочники docs/architecture/, CONTEXT.md, DDL и код не правятся.
  • Коммит не делается: коммитит оркестратор.

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

  1. docs/handbook/README.md — тон, адресация, аннотация будущей главы.
  2. docs/architecture/storage.md — фактура: слои, имена, ключи, сроки жизни.
  3. CONTEXT.md — словарь: посетитель, человек, пользователь магазина, сырые данные.
  4. Корневой README, разделы «Адреса и пароли» и «Подключиться из DBeaver» — как читатель выполнит SELECT.

Проверка

Из корня репозитория, обе команды дают пустой вывод:

for f in docs/handbook/README.md docs/handbook/storage-layers.md; do
  d=$(dirname "$f")
  grep -oE '\]\(([^)]+)\)' "$f" | sed -E 's/^\]\(//; s/\)$//; s/#.*$//' \
    | grep -vE '^(https?:|$)' | sort -u \
    | while read -r p; do [ -e "$d/$p" ] || echo "$f -> $p MISSING"; done
done
grep -n "менти\|ё" docs/handbook/storage-layers.md
Part of #206 ## Цель Первая глава путеводителя: `docs/handbook/storage-layers.md`. Читатель проходит путь данных от сообщения Kafka до витрины и понимает, за что отвечает каждый слой и по каким колонкам слои соединяются. Глава ведет в справочники, а не пересказывает их. Форма главы — образец для следующих глав путеводителя. ## Скелет главы (порядок разделов зафиксирован) 1. **Вводка.** В хранилище два потока из Kafka: события кликстрима (топик `hits`) и заказы магазина (топик `orders`). Путь один: STG → ODS → DDS → DM. Одна простая mermaid-схема пути. 2. **Как читать имена.** Читают через объекты с суффиксом `_v`; остальные суффиксы (`_rep`, `_dist`, `_kafka`, `_mv`) — устройство, о нем — в справочнике. Коротко, без таблицы всех суффиксов. 3. **Слои по одному.** По разделу на STG, ODS, DDS, DM: за что отвечает, что в нем лежит, одна деталь-крючок. STG — «как привезли», сырая строка с метаданными доставки, живет трое суток. ODS — типизировано, язык источника, брак уходит в таблицы `*_errors`. DDS — язык бизнеса: событие, заказ, сессия, карта идентичностей; сессию стенд режет из событий сам. DM — витрины под дашборды. 4. **Сбоку цепочки.** Зона `dic` и словарь товаров: его никто из слоев не производит, читают все. Два абзаца. 5. **Ключи, по которым слои соединяются.** Маленькая таблица колонок: `WatchID`, `ClientID`, `order_id`, `sku`, `EventDate` — что означает и какие слои соединяет. Семантика — по справочнику хранилища и CONTEXT.md (посетитель — кука, `ClientID`). 6. **Посмотрите сами.** Два коротких SELECT по `_v`-поверхностям: например, события одного дня из `ods.event_v` и выручка по категориям из `dm.revenue_daily_v`. Подключение — ссылкой на «Адреса и пароли» корневого README. 7. **Куда дальше.** Справочник хранилища за подробностями; следующая глава — потоки Airflow. ## Критерии приёмки - [ ] `docs/handbook/storage-layers.md` написан по скелету; детали устройства — ссылками в справочники, не пересказом. - [ ] Каждая колонка таблицы ключей существует в схеме (`sql/ddl/`) и названа словом из CONTEXT.md. - [ ] Оба SELECT обращаются только к `_v`-поверхностям и синтаксически верны; прогон на живом стенде — за оркестратором на приёмке. - [ ] `docs/handbook/README.md`: раздел «Будущие главы» становится «Главы», аннотация первой ведет в файл главы, у остальных остается «Пока главы нет…». - [ ] Адресация — «вы», как в README путеводителя; слова «менти» в тексте нет; буквы «ё» в новом тексте нет; тире «—» и кавычки-елочки, как в соседних документах. - [ ] Все относительные ссылки главы и README путеводителя целы. ## Границы - Справочники `docs/architecture/`, CONTEXT.md, DDL и код не правятся. - Коммит не делается: коммитит оркестратор. ## Сначала прочитать 1. `docs/handbook/README.md` — тон, адресация, аннотация будущей главы. 2. `docs/architecture/storage.md` — фактура: слои, имена, ключи, сроки жизни. 3. CONTEXT.md — словарь: посетитель, человек, пользователь магазина, сырые данные. 4. Корневой README, разделы «Адреса и пароли» и «Подключиться из DBeaver» — как читатель выполнит SELECT. ## Проверка Из корня репозитория, обе команды дают пустой вывод: for f in docs/handbook/README.md docs/handbook/storage-layers.md; do d=$(dirname "$f") grep -oE '\]\(([^)]+)\)' "$f" | sed -E 's/^\]\(//; s/\)$//; s/#.*$//' \ | grep -vE '^(https?:|$)' | sort -u \ | while read -r p; do [ -e "$d/$p" ] || echo "$f -> $p MISSING"; done done grep -n "менти\|ё" docs/handbook/storage-layers.md
ddmitry added the wayfinder:task label 2026-09-02 22:50:20 +03:00
ddmitry self-assigned this 2026-09-02 22:50:20 +03:00
ddmitry commented 2026-09-02 23:14:46 +03:00
Author
Owner
Copy link
Copy source

Сделано в PR #219 (ждет слияния владельцем; Closes #218 закроет тикет сам).

Глава. docs/handbook/storage-layers.md по скелету постановки: путь STG → ODS → DDS → DM с mermaid-схемой, правило чтения через _v, слои по одному с деталью-крючком, зона dic, таблица ключей (WatchID, ClientID, order_id, sku, EventDate) с переименованиями DDS, два SELECT и «Куда дальше». Оба SELECT прогнаны оркестратором на живом стенде от analyst: события дня D0 читаются, выручка по категориям ранжируется. README путеводителя: раздел «Главы», аннотация первой ведет в файл, заглушки остальных на месте.

Конвейер. Проза — Sol (gpt-5.6-sol), саморевью 2/2. Слепое ревью Opus: 0 блокеров, 2 minor, 3 nit. Вычитка прозы Opus (ai-text-lint + оптика литературного русского): 16 находок. Итого 21 внесена, 3 отклонены с доводами (параллелизм разделов и заголовок «Главы» — требования скелета; роли суффиксов — три документированные роли). Перепроверки обеих линий: все закрыто; две новые находки перепроверок (мертвые якоря на CONTEXT.md, две прозаические в добавленных фразах) закрыты узкими правками тем же исполнителем.

Приемка. Оркестратор вернул словарю «статьи» (унификация «глав» зацепила абзац про CONTEXT.md в README путеводителя) и срезал повтор зачина в разделе DDS. Поправки владельца по ходу: заголовок «STG: как поступило» вместо «как привезли», фраза про посетителя переформулирована.

Дальше по очереди #208: глава «Потоки Airflow и даги модельного времени».

Сделано в PR #219 (ждет слияния владельцем; Closes #218 закроет тикет сам). **Глава.** `docs/handbook/storage-layers.md` по скелету постановки: путь STG → ODS → DDS → DM с mermaid-схемой, правило чтения через `_v`, слои по одному с деталью-крючком, зона `dic`, таблица ключей (`WatchID`, `ClientID`, `order_id`, `sku`, `EventDate`) с переименованиями DDS, два SELECT и «Куда дальше». Оба SELECT прогнаны оркестратором на живом стенде от `analyst`: события дня D0 читаются, выручка по категориям ранжируется. README путеводителя: раздел «Главы», аннотация первой ведет в файл, заглушки остальных на месте. **Конвейер.** Проза — Sol (gpt-5.6-sol), саморевью 2/2. Слепое ревью Opus: 0 блокеров, 2 minor, 3 nit. Вычитка прозы Opus (ai-text-lint + оптика литературного русского): 16 находок. Итого 21 внесена, 3 отклонены с доводами (параллелизм разделов и заголовок «Главы» — требования скелета; роли суффиксов — три документированные роли). Перепроверки обеих линий: все закрыто; две новые находки перепроверок (мертвые якоря на CONTEXT.md, две прозаические в добавленных фразах) закрыты узкими правками тем же исполнителем. **Приемка.** Оркестратор вернул словарю «статьи» (унификация «глав» зацепила абзац про CONTEXT.md в README путеводителя) и срезал повтор зачина в разделе DDS. Поправки владельца по ходу: заголовок «STG: как поступило» вместо «как привезли», фраза про посетителя переформулирована. **Дальше по очереди #208:** глава «Потоки Airflow и даги модельного времени».
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
No labels wayfinder:task
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ddmitry (Dmitry Dementiev)
No Assignees ddmitry
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ddmitry/clickstream-data-platform#218