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

Пересборка корневого README: четыре блока и адресация читателя #216

New Issue
Closed
opened 2026-09-02 22:11:45 +03:00 by ddmitry · 2 comments
ddmitry commented 2026-09-02 22:11:45 +03:00
Owner
Copy link
Copy source

Part of #206

Цель

Корневой README становится лицом репозитория по раскладке, принятой
резолюцией #211: четыре блока сверху вниз — промо, «куда я попал», типовые
действия, ссылки. Мертвые разделы умирают, слово «менти» уходит из README и
docs/handbook/README.md, хвосты #212 и #214 закрываются. Справочники не
переписываются: README на них ссылается.

Раскладка

Строки — по README на коммите e56b238.

1. Промо-блок цитатой (>) сразу под заголовком. Образец — README стенда
airflow-greenplum того же автора:

Этот стенд можно использовать самостоятельно, но он также является
курсовой работой плана обучения Data Engineering Roadmap.
Нужна помощь? Обратитесь к автору материалов — ментору @dementev_dev.

Отличия: ссылка на план — https://de.dementev.space (не замороженный GitHub);
фразу построить по-русски, а не копировать «является курсовой работой».
Смысл: стендом можно пользоваться самостоятельно, он же курсовая работа
плана обучения; за помощью — к ментору.

2. Куда я попал. Шапка (строки 3–11) с нейтральной адресацией вместо
«для менти, который…» — в духе «Этот стенд — для изучения и экспериментов
с кликстримом и ClickHouse: здесь можно проследить весь путь данных…».
Плюс одна фраза о составе и пути данных, выжатая из «Статуса» (17–26):
кластер ClickHouse из двух шардов с keeper, Kafka, Airflow, Superset,
Prometheus и Grafana; события кликстрима и заказы бэкенда идут из генератора
через Kafka по слоям STG → ODS → DDS → DM. Без схемы. Ссылки на путеводитель
и уроки остаются здесь.

3. Типовые действия — то, что делают, не уходя дальше README. Каждое —
свой подраздел, порядок такой:

  • Поднять и проверить. Требования (30–43), копирование .env.example и
    команды подъема и проверок (45–58), абзац про .env и DOCKER_GID
    (60–68), про учетные данные Postgres и Grafana с make clean (70–73).
    Текст сохраняется, режется только повтор: два соседних абзаца со ссылкой
    на testing.md (75–81) сливаются в один из двух-трех предложений.
  • Адреса и пароли интерфейсов — список (108–116) как есть. Заголовок
    раздела новый; ссылка в docs/architecture/stand.md (строка 7) на якорь
    README.md#состав-и-доступ переводится на новый якорь.
  • Сдвинуть мир на день или включить живой ход. Два-три предложения:
    запустить даг world_next_day (по умолчанию один день, в форме запуска
    можно задать число); снять с паузы world_live — мир поедет сам в темпе
    модельного времени. Ссылка на docs/architecture/world.md#даги-модельного-времени.
    Таблицы дагов в README нет.
  • Вернуть мир к началу — абзац о make rebuild-storage и паузе
    world_live (83–89); make down и make clean из него уходят в
    следующий пункт.
  • Выключить и полный сброс — make down останавливает контейнеры без
    удаления данных; make clean удаляет весь стенд вместе с томами и для
    обычной работы не нужен.
  • Подключиться из DBeaver. Отдельный раздел: искать будут все. Драйвер
    ClickHouse в DBeaver ходит по JDBC через HTTP-порт (сверено с
    документацией ClickHouse: jdbc:ch:http://host:8123): хост 127.0.0.1,
    порт 28123 (нода 1; 28124 — нода 2), пользователь analyst, пароль
    из .env (переменная CLICKHOUSE_ANALYST_PASSWORD, в образце
    analyst-26-reader). analyst читает все слои и справочники (stand.md,
    «Пользователи и роли»). Нативные порты 29000/29001 — для
    clickhouse-client, DBeaver'у не нужны. За ролями — ссылка на stand.md.

4. Документация (137–155) остается последним разделом. Пункт
docs/architecture/ перечисляет справочники поименно с одной фразой на
каждый: хранилище (storage.md), конвейер (etl.md), мир и модельное
время (world.md), стенд (stand.md), проверки (testing.md),
мониторинг (monitoring/README.md), Superset (superset.md). Хвост #212:
stand.md и world.md здесь появляются впервые.

Умирают: «Статус» (13–26; одна фраза уходит в блок 2), «Что здесь
будет» (121–129; все пять пунктов сделаны), «Чем отличается от
предшественника» (131–135; шапка уже говорит «преемник»),
заголовки-якоря «Стартовый мир», «Как позвать генератор», «Даги
модельного времени» (91–104; оставлены в #212 ради якорей, на них никто
не ссылается — проверено grep -rn "README.md#").

Хвосты соседних тикетов

  • docs/architecture/world.md, раздел «Как запустить генератор»: фраза
    «так генератор позовёт даг этапа 5» устарела — даги есть. Заменить на
    «так его запускают даги модельного времени». Одна фраза, остальной текст
    не трогать.
  • docs/handbook/README.md, строка 46: «Для менти генератор здесь —
    источник данных» → без слова «менти» (например: «Здесь генератор —
    источник данных, а не предмет изучения»).

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

  • README состоит из четырех блоков в порядке промо → куда я попал →
    типовые действия → документация; разделов «Статус», «Что здесь
    будет», «Чем отличается от предшественника» и трех заголовков-якорей
    нет.
  • Промо-цитата ведет на https://de.dementev.space и на ментора.
  • Ни один факт «Быстрого старта» не потерян: требования, порты,
    команды, DOCKER_GID, учетные данные Postgres и Grafana,
    make rebuild-storage, make down, make clean на месте.
  • Адреса и пароли интерфейсов в README; stand.md ссылается на их новый
    якорь.
  • Раздел про DBeaver есть; порт и пользователь верны (сверено с
    .env.example и stand.md).
  • Раздел «Документация» называет все семь справочников, включая
    stand.md и world.md.
  • grep -n "менти" README.md docs/handbook/README.md пуст; обращение
    к читателю — «вы».
  • Фраза про «даг этапа 5» в world.md заменена.
  • Скрипт ссылок из #212 пуст; make config-test зеленый.
  • В сохраненном тексте тире и елочки не тронуты; в новом тексте «ё» не
    пишется (правило репозитория с 2026-08-26).
  • Новая проза прошла ai-text-lint и оптику литературного русского
    свежей сессией.

Границы

  • Справочники не править, кроме одной фразы в world.md и одной ссылки
    в stand.md.
  • Главы путеводителя не писать, интерактивную карту не начинать.
  • Код, DDL, Makefile, .env.example не трогать.
  • Смысл сохраняемых абзацев не менять: сжатие — только слияние повторов.

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

  • Резолюция #211 (комментарий) — раскладка; резолюции #212 и #214 — хвосты.
  • README.md целиком; docs/handbook/README.md.
  • docs/architecture/stand.md («Пользователи и роли», строка 7) и
    world.md («Даги модельного времени»).
  • AGENTS.md, раздел «Язык».

Кто пишет

Структура, заголовки и бриф — Fable. Новый русский текст (промо, «куда я
попал», связки типовых действий, DBeaver, аннотации справочников) — Sol
через codex exec; перенос сохраняемых абзацев и правка ссылок — тем же
прогоном. Приемка — оркестратор: ai-text-lint, оптика литературного
русского, ссылки своими глазами.

Проверка

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

for f in README.md docs/handbook/README.md docs/architecture/testing.md \
         docs/architecture/stand.md docs/architecture/world.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 "менти" README.md docs/handbook/README.md
make config-test
Part of #206 ## Цель Корневой README становится лицом репозитория по раскладке, принятой резолюцией #211: четыре блока сверху вниз — промо, «куда я попал», типовые действия, ссылки. Мертвые разделы умирают, слово «менти» уходит из README и `docs/handbook/README.md`, хвосты #212 и #214 закрываются. Справочники не переписываются: README на них ссылается. ## Раскладка Строки — по README на коммите e56b238. **1. Промо-блок** цитатой (`>`) сразу под заголовком. Образец — README стенда airflow-greenplum того же автора: > Этот стенд можно использовать самостоятельно, но он также является > курсовой работой плана обучения [Data Engineering Roadmap](https://github.com/dementev-dev/de-roadmap). > Нужна помощь? Обратитесь к автору материалов — ментору [@dementev_dev](https://t.me/dementev_dev). Отличия: ссылка на план — https://de.dementev.space (не замороженный GitHub); фразу построить по-русски, а не копировать «является курсовой работой». Смысл: стендом можно пользоваться самостоятельно, он же курсовая работа плана обучения; за помощью — к ментору. **2. Куда я попал.** Шапка (строки 3–11) с нейтральной адресацией вместо «для менти, который…» — в духе «Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse: здесь можно проследить весь путь данных…». Плюс одна фраза о составе и пути данных, выжатая из «Статуса» (17–26): кластер ClickHouse из двух шардов с keeper, Kafka, Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда идут из генератора через Kafka по слоям STG → ODS → DDS → DM. Без схемы. Ссылки на путеводитель и уроки остаются здесь. **3. Типовые действия** — то, что делают, не уходя дальше README. Каждое — свой подраздел, порядок такой: - *Поднять и проверить.* Требования (30–43), копирование `.env.example` и команды подъема и проверок (45–58), абзац про `.env` и `DOCKER_GID` (60–68), про учетные данные Postgres и Grafana с `make clean` (70–73). Текст сохраняется, режется только повтор: два соседних абзаца со ссылкой на testing.md (75–81) сливаются в один из двух-трех предложений. - *Адреса и пароли интерфейсов* — список (108–116) как есть. Заголовок раздела новый; ссылка в `docs/architecture/stand.md` (строка 7) на якорь `README.md#состав-и-доступ` переводится на новый якорь. - *Сдвинуть мир на день или включить живой ход.* Два-три предложения: запустить даг `world_next_day` (по умолчанию один день, в форме запуска можно задать число); снять с паузы `world_live` — мир поедет сам в темпе модельного времени. Ссылка на `docs/architecture/world.md#даги-модельного-времени`. Таблицы дагов в README нет. - *Вернуть мир к началу* — абзац о `make rebuild-storage` и паузе `world_live` (83–89); `make down` и `make clean` из него уходят в следующий пункт. - *Выключить и полный сброс* — `make down` останавливает контейнеры без удаления данных; `make clean` удаляет весь стенд вместе с томами и для обычной работы не нужен. - *Подключиться из DBeaver.* Отдельный раздел: искать будут все. Драйвер ClickHouse в DBeaver ходит по JDBC через HTTP-порт (сверено с документацией ClickHouse: `jdbc:ch:http://host:8123`): хост `127.0.0.1`, порт `28123` (нода 1; `28124` — нода 2), пользователь `analyst`, пароль из `.env` (переменная `CLICKHOUSE_ANALYST_PASSWORD`, в образце `analyst-26-reader`). `analyst` читает все слои и справочники (stand.md, «Пользователи и роли»). Нативные порты `29000`/`29001` — для `clickhouse-client`, DBeaver'у не нужны. За ролями — ссылка на stand.md. **4. Документация** (137–155) остается последним разделом. Пункт `docs/architecture/` перечисляет справочники поименно с одной фразой на каждый: хранилище (`storage.md`), конвейер (`etl.md`), мир и модельное время (`world.md`), стенд (`stand.md`), проверки (`testing.md`), мониторинг (`monitoring/README.md`), Superset (`superset.md`). Хвост #212: stand.md и world.md здесь появляются впервые. **Умирают:** «Статус» (13–26; одна фраза уходит в блок 2), «Что здесь будет» (121–129; все пять пунктов сделаны), «Чем отличается от предшественника» (131–135; шапка уже говорит «преемник»), заголовки-якоря «Стартовый мир», «Как позвать генератор», «Даги модельного времени» (91–104; оставлены в #212 ради якорей, на них никто не ссылается — проверено `grep -rn "README.md#"`). ## Хвосты соседних тикетов - `docs/architecture/world.md`, раздел «Как запустить генератор»: фраза «так генератор позовёт даг этапа 5» устарела — даги есть. Заменить на «так его запускают даги модельного времени». Одна фраза, остальной текст не трогать. - `docs/handbook/README.md`, строка 46: «Для менти генератор здесь — источник данных» → без слова «менти» (например: «Здесь генератор — источник данных, а не предмет изучения»). ## Критерии приемки - [x] README состоит из четырех блоков в порядке промо → куда я попал → типовые действия → документация; разделов «Статус», «Что здесь будет», «Чем отличается от предшественника» и трех заголовков-якорей нет. - [x] Промо-цитата ведет на https://de.dementev.space и на ментора. - [x] Ни один факт «Быстрого старта» не потерян: требования, порты, команды, `DOCKER_GID`, учетные данные Postgres и Grafana, `make rebuild-storage`, `make down`, `make clean` на месте. - [x] Адреса и пароли интерфейсов в README; stand.md ссылается на их новый якорь. - [x] Раздел про DBeaver есть; порт и пользователь верны (сверено с `.env.example` и stand.md). - [x] Раздел «Документация» называет все семь справочников, включая stand.md и world.md. - [x] `grep -n "менти" README.md docs/handbook/README.md` пуст; обращение к читателю — «вы». - [x] Фраза про «даг этапа 5» в world.md заменена. - [x] Скрипт ссылок из #212 пуст; `make config-test` зеленый. - [x] В сохраненном тексте тире и елочки не тронуты; в новом тексте «ё» не пишется (правило репозитория с 2026-08-26). - [x] Новая проза прошла ai-text-lint и оптику литературного русского свежей сессией. ## Границы - Справочники не править, кроме одной фразы в world.md и одной ссылки в stand.md. - Главы путеводителя не писать, интерактивную карту не начинать. - Код, DDL, Makefile, `.env.example` не трогать. - Смысл сохраняемых абзацев не менять: сжатие — только слияние повторов. ## Сначала прочитать - Резолюция #211 (комментарий) — раскладка; резолюции #212 и #214 — хвосты. - README.md целиком; docs/handbook/README.md. - docs/architecture/stand.md («Пользователи и роли», строка 7) и world.md («Даги модельного времени»). - AGENTS.md, раздел «Язык». ## Кто пишет Структура, заголовки и бриф — Fable. Новый русский текст (промо, «куда я попал», связки типовых действий, DBeaver, аннотации справочников) — Sol через `codex exec`; перенос сохраняемых абзацев и правка ссылок — тем же прогоном. Приемка — оркестратор: ai-text-lint, оптика литературного русского, ссылки своими глазами. ## Проверка Из корня репозитория, обе первые команды дают пустой вывод: for f in README.md docs/handbook/README.md docs/architecture/testing.md \ docs/architecture/stand.md docs/architecture/world.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 "менти" README.md docs/handbook/README.md make config-test
ddmitry added the wayfinder:task label 2026-09-02 22:11:45 +03:00
ddmitry self-assigned this 2026-09-02 22:11:45 +03:00
ddmitry commented 2026-09-02 22:27:56 +03:00
Author
Owner
Copy link
Copy source

Поправка владельца по ходу работы (2026-09-02): в «Быстром старте» человеку достаточно двух команд — cp .env.example .env и make up. Прогон проверок (make smoke, make check-clickhouse, make check-services, make config-test, make lint) из README уходит: это инструмент роботов и разработки, читателю он не нужен. Остается одна фраза со ссылкой на карту проверок.

Поправка владельца по ходу работы (2026-09-02): в «Быстром старте» человеку достаточно двух команд — `cp .env.example .env` и `make up`. Прогон проверок (`make smoke`, `make check-clickhouse`, `make check-services`, `make config-test`, `make lint`) из README уходит: это инструмент роботов и разработки, читателю он не нужен. Остается одна фраза со ссылкой на карту проверок.
ddmitry commented 2026-09-02 22:37:52 +03:00
Author
Owner
Copy link
Copy source

Сделано в PR #217 (ждет слияния владельцем).

README. Четыре блока по резолюции #211: промо-цитата со ссылкой на план обучения (https://de.dementev.space) и ментора; «куда я попал» с нейтральной адресацией и одной фразой о составе, пути данных и стартовом мире; типовые действия плоскими разделами — «Быстрый старт», «Адреса и пароли», «Сдвинуть мир вперед», «Вернуть мир к началу», «Выключить или сбросить целиком», «Подключиться из DBeaver» (JDBC по HTTP-порту 28123, пользователь analyst, пароль из .env; сверено с документацией ClickHouse); «Документация» называет семь справочников вложенным списком. Умерли «Статус», «Что здесь будет», «Чем отличается от предшественника» и три заголовка-якоря.

Поправка владельца по ходу работы. «Быстрый старт» для человека — две команды: cp .env.example .env и make up. Проверки (make smoke, check-*, config-test, lint) из README ушли: это инструмент роботов; осталась одна фраза со ссылкой на карту проверок. Требования сжаты до curl и jq для make up, списка портов и uv для генератора.

Хвосты закрыты. world.md: «так генератор позовёт даг этапа 5» → «так генератор запускают даги модельного времени». stand.md и ADR 0007 ведут на «Адреса и пароли» (ADR правлен только в указателе). Путеводитель: «Для менти генератор…» → «Здесь генератор — источник данных, а не предмет изучения».

Ревью. Sol (gpt-5.6-sol) писал, саморевью 1/1. Слепое ревью Opus (craftsman): 0 блокеров, 2 minor, 3 nit — закрыты; на перепроверке одна новая находка (curl нужен make up) закрыта. Вычитка прозы Opus через ai-text-lint и оптику литературного русского: 15 находок, 9 внесены (калька «объединяет с», Kafka дважды в одной фразе, шов склеенных абзацев, «число дней», параллелизм заголовков, вложенный список справочников и др.), 6 отклонены: три — формулировки промо повторяют образец владельца из airflow-greenplum, две — фраза «для изучения и экспериментов…» и безадресность взяты из резолюции #211, одна — «явная пересборка» термин и замороженный текст.

Не тронуто. Потолок в семь дней у world_next_day в README не назван: читатель, набравший 30, увидит ошибку формы — это и есть урок (замечание ревьюера, не находка).

Дальше по очереди #208 и #211: главы путеводителя, затем интерактивная карта.

Сделано в PR #217 (ждет слияния владельцем). **README.** Четыре блока по резолюции #211: промо-цитата со ссылкой на план обучения (https://de.dementev.space) и ментора; «куда я попал» с нейтральной адресацией и одной фразой о составе, пути данных и стартовом мире; типовые действия плоскими разделами — «Быстрый старт», «Адреса и пароли», «Сдвинуть мир вперед», «Вернуть мир к началу», «Выключить или сбросить целиком», «Подключиться из DBeaver» (JDBC по HTTP-порту 28123, пользователь `analyst`, пароль из `.env`; сверено с документацией ClickHouse); «Документация» называет семь справочников вложенным списком. Умерли «Статус», «Что здесь будет», «Чем отличается от предшественника» и три заголовка-якоря. **Поправка владельца по ходу работы.** «Быстрый старт» для человека — две команды: `cp .env.example .env` и `make up`. Проверки (`make smoke`, `check-*`, `config-test`, `lint`) из README ушли: это инструмент роботов; осталась одна фраза со ссылкой на карту проверок. Требования сжаты до `curl` и `jq` для `make up`, списка портов и `uv` для генератора. **Хвосты закрыты.** world.md: «так генератор позовёт даг этапа 5» → «так генератор запускают даги модельного времени». stand.md и ADR 0007 ведут на «Адреса и пароли» (ADR правлен только в указателе). Путеводитель: «Для менти генератор…» → «Здесь генератор — источник данных, а не предмет изучения». **Ревью.** Sol (gpt-5.6-sol) писал, саморевью 1/1. Слепое ревью Opus (craftsman): 0 блокеров, 2 minor, 3 nit — закрыты; на перепроверке одна новая находка (`curl` нужен `make up`) закрыта. Вычитка прозы Opus через ai-text-lint и оптику литературного русского: 15 находок, 9 внесены (калька «объединяет с», Kafka дважды в одной фразе, шов склеенных абзацев, «число дней», параллелизм заголовков, вложенный список справочников и др.), 6 отклонены: три — формулировки промо повторяют образец владельца из airflow-greenplum, две — фраза «для изучения и экспериментов…» и безадресность взяты из резолюции #211, одна — «явная пересборка» термин и замороженный текст. **Не тронуто.** Потолок в семь дней у `world_next_day` в README не назван: читатель, набравший 30, увидит ошибку формы — это и есть урок (замечание ревьюера, не находка). **Дальше по очереди #208 и #211:** главы путеводителя, затем интерактивная карта.
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#216