Зачем: помочь начинающему инженеру проследить событие и версию заказа
от генератора до хранилища, включая ошибки и повторные поступления.
Что: обновлены вводная генератора, справочники приема и модели заказа,
разделы хранилища и комментарии SQL и дага. Сохранены технические условия;
исполняемый код, схемы и поведение стенда не изменены.
Проверка: make lint, git diff --check, 142 локальные ссылки и справка CLI.
SQL без комментариев и Python AST без строк документации совпали
с исходными. Генерация данных и сброс состояния не выполнялись.
Refs #250
Зачем: выражения «собираются в донор» и «публикуются дни» требовали
знать устройство конвейера до чтения объяснения.
Что: описаны назначение промежуточных таблиц и последовательность
расчета, записи и замены разделов. Перечитаны остальные объяснения:
выбор дней, разворачивание позиций заказа, проверка сессий и повтор запуска.
Проверка: make lint, git diff --check, локальные ссылки и якоря.
SQL без комментариев и AST обоих дагов без строк документации не изменились.
Refs: #249
Зачем: читателю ступеней 1–4 нужно проследить выбор дней, расчет строки
и публикацию результата без расшифровки метафор.
Что: согласованы справочники DM, сессий, ETL и два раздела хранилища
с комментариями шести SQL-примеров. Уточнены ограничения повторного
запуска и выбора атрибутов при равном времени событий.
Проверка: make lint, git diff --check, локальные Markdown-ссылки и якоря.
SQL без комментариев совпадает; AST Python без строк документации совпадает.
Исторические разделы и материалы вне границ задачи сохранены.
Refs: #249
Зачем: понимать термины стенда без изучения устройства генератора.
Что: понятия сгруппированы по учебным темам, определения упрощены;
уточнены идентификаторы, модельное время и повторный запуск стенда.
Проверка: сохранены все 43 прежних термина; проверены 11 входящих
и 6 внутренних ссылок, якорь «Язык» и git diff --check.
Зачем: помочь учащемуся понять назначение объектов и обработку данных по стрелкам карты.
Что: вычитаны карточки и подписи, пояснены термины, удалены повторы. Описания обработки уточнены по SQL, HTML пересобран.
Проверка: сохранены 17 объектов и 17 стрелок, проверены 85 ссылок. В Chromium проверены карточки, фильтры, подсветка, Escape и отображение при ширине 1920 и 1280 пикселей. make lint и git diff --cached --check прошли.
Зачем: помочь учащемуся понять путь данных и работу служб перед выполнением заданий.
Что: вычитаны оглавление и пять глав, пояснены термины, убраны внутренние метафоры и повторы. Уточнены пояснения к SQL и показателям мониторинга.
Проверка: 62 локальные ссылки и 6 входящих ссылок на разделы проверены; 8 блоков SQL и схем сохранены. git diff --cached --check прошел.
Зачем: помочь учащемуся понять назначение стенда и порядок работы с ним.
Что: убраны внутренние метафоры, пояснены термины, настройка перенесена перед запуском. Обновлена ссылка из путеводителя и удалена ссылка на предыдущий стенд.
Проверка: команды, адреса и пароли сохранены; 24 ссылки README и входящие ссылки на разделы проверены. git diff --cached --check прошел.
Зачем: сделать задания понятнее учащемуся и сохранить правила для будущих работ.
Что: объединены три коммита ветки docs/labs-human-language с сохранением истории через merge --no-ff.
Проверка: рабочее дерево чистое перед слиянием, origin/main входит в локальную main, итоговый diff прошел git diff --check. Ссылки и сохранность технических примеров проверены при редактуре.
Зачем: оставить только необходимые ориентиры для автора учебного текста.
Что: раздел сокращен до трех согласованных абзацев, ссылки на оба образца сохранены.
Проверка: git diff --check прошел; проверен diff единственного измененного файла.
Зачем: убрать механические повторы в итогах и избежать ложных расхождений при проверке графика Superset.
Что: уточнены правила итоговых списков и название задания о проверках заказов. В разборе событий разделены учет повторных доставок и выбор событий ODS для сравнения. Первый график Superset и проверочный SQL используют весь период витрины.
Проверка: git diff --check, локальные ссылки и переходы к измененным заголовкам прошли. Блоки кода и таблицы требований сохранены. Согласованность периода графика с SQL проверена по тексту; повторный проход через интерфейс Superset не выполнялся.
Зачем: помочь менти понять действия, проверить результат и оценить освоенное умение.
Что: вычитаны 13 заданий основной программы и общий индекс. Итоговые списки обращены к учащемуся, убраны история разработки и повторы. Правила учебного текста записаны в программе, из AGENTS.md добавлена ссылка.
Проверка: git diff --check, локальные ссылки и ссылки на измененные заголовки прошли. Блоки кода и таблицы требований совпадают с исходными. Упражнения на стенде повторно не выполнялись: изменен только текст.
Зачем: дать менти два самостоятельных задания по BI после ступени 2.
Что: обновлено ТЗ дашборда, добавлен опыт с объектом на одной ноде, уточнены программа и индекс. Формулировки обращены к учащемуся.
Проверка: локальные ссылки и git diff --check прошли. На ClickHouse 26.3.17.56 воспроизведены ошибка чтения со второй ноды и исправление; учебный объект удален. Полный проход через интерфейс Superset не выполнялся.
- Зачем:
- экран отвечал только графиками: итога за период не было, доли категорий
читались по высоте столбиков, а известные пользователи лежали на нуле
рядом с посетителями.
- Что:
- добавлены ряд крупных чисел (выручка, заказы, средний чек, посетители),
кольцо долей категорий и линия доли известных пользователей;
- средний чек и доля известных заведены метриками датасетов, знаменатель
через `nullIf`: на пустом периоде деление Decimal на ноль в ClickHouse
роняет панель;
- фильтр «Период» сужает все панели, включая сверку по `order_day`;
- `label_colors` закрепляет цвет за категорией и за рядами трафика;
- деньги без копеек, единица в названии панели; подписи дат читаются как
даты; сводная сверки развернута классами по строкам и уместилась без
прокрутки;
- обновлены справочник Superset и глава путеводителя.
- Проверка:
- `make lint`;
- `superset import-directory /app/import --overwrite` на живом стенде, экран
снят в браузере: девять панелей отрисованы, цвет категории одинаков на
столбиках и в кольце;
- период 03.06–06.06 сузил все панели, включая сводную по `order_day`;
- `SUM(revenue) / nullIf(SUM(orders), 0)` на периоде без заказов возвращает
NULL, без `nullIf` — исключение 153.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Зачем:
- карту регионов и кросс-фильтрацию предложат снова, а доводы против них
стоили двух линий ревью и замеров на живом стенде.
- Что:
- в docs/architecture/superset.md добавлен раздел «Отклоненные варианты»:
карта регионов, регион как общее измерение витрин, кросс-фильтрация между
панелями, пороги на панелях.
- к каждому отказу записаны проверенные факты и поводы вернуться к разговору.
- Проверка:
- `git diff --check`.
- `grep -rn "0018" docs` — ссылок на неоставленный ADR нет.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Зачем:
- сохранить ясный и естественный стиль текстов проекта.
- Что:
- в CLAUDE.md добавлены требования к лёгкости чтения и отказу от манерной прозы.
- Проверка:
- проверен diff CLAUDE.md.
- Зачем:
- дать учащемуся воспроизводимый путь от своего DDL до первой проверки витрины.
- Что:
- уточнено применение `sql/ddl/70-labs.sql` в работающем стенде через подключение `etl`.
- добавлены указания запуска `homework_check` и чтения журнала для `events_enriched`.
- Проверка:
- `git diff --check`.
- `make config-test` — зелёный.
- Зачем:
- эксплуатационные улучшения не должны становиться самостоятельной целью учебного проекта.
- Что:
- поддержка стенда ограничена сохранением учебного пути и учебными задачами.
- зафиксировано отсутствие отдельной эксплуатационной ценности.
- Проверка:
- git diff --check.
- Зачем:
- агентам нужен точный портрет читателя и проверяемый результат обучения.
- Что:
- описана подготовка начинающих инженеров данных перед работой со стендом.
- зафиксирована цель: освоить общепринятые приёмы и суметь построить похожее хранилище.
- добавлена ссылка на программу учебных заданий.
- Проверка:
- git diff --check.
- Зачем:
- объяснение формы витрин читалось искусственно и использовало неуместное слово «менти».
- Что:
- выбор таблицы или представления объяснён через конкретные действия в задании.
- слово «менти» убрано из dm.md и AGENTS.md.
- описание факультатива и ссылка на раздел DM приведены к новому тексту.
- Проверка:
- git diff --check.
- проверено отсутствие слова «менти» в изменённых документах и наличие целей ссылок.
- Зачем:
- расположение файла должно отличать задания основной программы от факультативов.
- Что:
- существующее ТЗ Superset перенесено в `docs/labs/optional/`, ссылки обновлены.
- правило размещения записано в `AGENTS.md`.
- выбор формы витрин объяснен учебной целью стенда.
- Проверка:
- `git diff --check`.
- проверены все упоминания `superset-dashboard` и относительные ссылки.
- Зачем:
- Завершить ТЗ основной программы расследованиями нагрузки и свежести данных.
- Что:
- Добавлено ТЗ ступени 7 с наблюдением запросов Grafana и доставки слепка заказов.
- В индексе лаб открыта ссылка на последнее задание программы.
- Проверка:
- Проверены относительные ссылки, git diff --check и соответствие панелям стенда.
- Зачем:
- сделать постановку ступени 6 понятнее после редакторского ревью, сохранив её учебный договор и границы.
- Что:
- оставлена свобода выбрать форму разбора без навязывания Nullable и готовой схемы 0/1.
- уточнены пакетная обработка, баланс годных строк, модельное и ручное время и убрана лишняя персонификация.
- Проверка:
- проверены SHA256, `git diff --check` и изменение только `docs/labs/6-1-event-parsing.md`.
- Зачем:
- ступени 6 не хватало ТЗ для пакетного разбора сырого среза рядом с живым приемом.
- Что:
- добавлено задание с одной собственной таблицей, строгим входом и сверкой всех 47 полей с ODS.
- индекс основной программы дополнен ссылкой на ступень 6 и актуальным статусом ступени 7.
- Проверка:
- выполнен `git diff --check`, проверены локальные ссылки и договор задания по DDL STG и ODS.
- Зачем:
- одно длинное ТЗ заставляло одновременно держать в голове три самостоятельных опыта и их очистку.
- Что:
- проверки, разбор ODS и сборка DDS разнесены по трем последовательным заданиям.
- уточнены границы учебной реализации, место диагностики и выбор закрытого дня.
- оглавление ступени 5 дополнено ссылками на все три задания.
- Проверка:
- проверены ссылки, пробная пачка jq, кластерные мутации и отсутствие ошибок пробелов в diff.
- Зачем:
- менти нужен наблюдаемый опыт, в котором проверки защищают изменение конвейера заказов.
- Что:
- добавлено ТЗ ступени 5 с договорами DQ, управляемыми ошибками и восстановлением.
- в оглавление лабораторных работ добавлена ссылка на новое задание.
- Проверка:
- проверены локальные ссылки, пробная пачка jq и отсутствие ошибок пробелов в diff.
- Зачем:
- связать четвертую ступень с результатом третьей и сделать пересборку проверяемой.
- Что:
- уточнены переход от третьей ступени, договор с дагом и синхронная вставка в донор;
- ограничен сохраненный срез строк и вынесена независимая проверка атрибутов;
- упрощены формулировки и исправлены инструкции по DBeaver и удалению партиции.
- Проверка:
- git diff --check;
- проверены ссылки документа и якорь README#подключиться-из-dbeaver.
- узкая повторная вычитка Claude Opus одобрила все девять исправлений.
- Зачем:
- учащийся меняет расчет сессии внутри готового конвейера и проверяет результат внешним эталоном.
- Что:
- добавлено ТЗ ступени 4 с договором трех SQL-файлов, адресным прогоном и самопроверкой.
- индекс лаб ведет на задание; будущими остаются ступени 5–7.
- Проверка:
- make lint, относительные ссылки и git diff --check прошли.
- запрос размещения сессий по шардам проверен на стенде под analyst; данные не изменялись.
- выполнены независимое ревью, writing-for-agents, ai-text-lint и литературная вычитка.
- Зачем:
- ТЗ ступени 3 отправляет в главу за определением визита и доводом, почему
стенд считает сессии сам; раздел давал о сессии одно предложение.
- Что:
- в разделе «DDS: язык бизнеса» описаны договоренность о визите, роль
Метрики и эталон VisitID, session_id и чтение через dds.session_v.
- в «Посмотрите сами» добавлен запрос сессий дня между примерами ODS и DM,
итоговая фраза переписана на три запроса.
- Проверка:
- make lint; запрос к dds.session_v выполнен на стенде под analyst.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- программа лаб (спека 2026-09-01) требует ТЗ ступени 3: своя нарезка
визитов против эталона VisitID и расследование расхождения по строкам.
- Что:
- создан docs/labs/3-1-sessions-by-hand.md: нарезка по куке и паузе
30 минут над ods.event_v, сверка на зерне кука × день через
FULL OUTER JOIN, расследование одной разошедшейся куки.
- в docs/labs/README.md строка 3 программы ведет на ТЗ, фраза про будущие
ТЗ сдвинута на ступени 4–7.
- Проверка:
- make lint; запрос эталона выполнен на стенде под analyst.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- в docs/labs/ будет много заданий; номер ступени и номер задания в имени
делают папку оглавлением программы и избавляют от поиска по README (#230).
- Что:
- шесть ТЗ переименованы через git mv: 1-1…1-5 для ступени 1,
2-1-superset-chart.md для ступени 2; факультатив superset-dashboard.md
остался без номера.
- обновлены ссылки в docs/labs/README.md, 2-1-superset-chart.md,
docs/architecture/dds/session.md и пути в dags/homework_check.py.
- правило имен для docs/labs/ в AGENTS.md переписано под S-N-slug.
- Проверка:
- make lint; скрипт обхода относительных ссылок в docs/ и AGENTS.md —
битых нет.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- владелец при чтении PR #229 отметил образы в таблице программы
(«счет показывает проблему», «построить сторожей») и оборот
«запускается рукой».
- Что:
- ячейки «Чему учит» ступеней 3 и 5 переписаны как навыки, без образов.
- «запускается рукой» заменено на «запускается руками».
- Проверка:
- grep по «ё», «менти», словам-законам по docs/labs/*.md молчит.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- владелец при чтении забраковал прозу ТЗ ступени 1: образы вместо
утверждений, заголовки-метафоры, договоренности стенда поданы как
законы. Тикет #228.
- Что:
- пять ТЗ (задания 1–5) написаны заново по форме ТЗ ступени 2:
содержание, колонки, формулы, самопроверка и приемка сохранены.
- раздел README лаб «Общие правила ступени 1» переименован в «Как принято
на ступени 1» и переписан как выбор с доводом; точечно поправлены
«Самопроверка» и таблица ступени 1.
- Проверка:
- grep по «ё», «менти», формам «ты» и словам-законам по docs/labs/*.md
молчит (единственное «правило» — в нетронутом разделе «Уборка»).
- скрипт ссылок и якорей из #226 печатает пусто; git diff --check чист.
- сверка имен в обратных кавычках и чекбоксов старых и новых файлов —
без расхождений.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- README и путеводитель обращаются к читателю на «вы», а ТЗ в docs/labs/
были на «ты»; после пересборки индекса смесь стала заметна.
- Что:
- во всех восьми файлах docs/labs/ местоимения, глаголы и повелительное
наклонение переведены во второе лицо множественного числа.
- названия ступеней в таблице README оставлены как в спеке.
- Проверка:
- grep по формам «ты/твой», 'ё' и 'менти' по docs/labs/ молчит;
git diff --check чистый; ревью диффа свежей сессией.
- Зачем:
- программа лаб принята спекой, но индекс docs/labs/ показывал только
пять витрин и дашборд; ступень 2 не имела ТЗ (#226).
- Что:
- новое ТЗ docs/labs/superset-chart.md: один столбиковый график доли
отказов по устройствам поверх dm.session_overview_v, метрика в датасете.
- docs/labs/README.md: семь ступеней основной программы и пять разделов
факультативов; правила пяти витрин помечены как правила ступени 1.
- шапка docs/labs/superset-dashboard.md: факультатив раздела «Superset и BI».
- Проверка:
- grep 'ё' и 'менти' по трем файлам молчат; скрипт ссылок из тикета
печатает пусто; git diff --check чистый.
Closes#226
- Зачем:
- читатель карты видит ключи переноса данных, не переходя к карточкам узлов.
- Что:
- для 17 стрелок добавлено поле «Как соединяет», сверенное с SQL.
- раздел выведен в карточке стрелки и пересобрана карта.
- Проверка:
- uv run docs/handbook/architecture-map/render.py --check.
- make lint.
- make typecheck && make test в generator/.
ddadmin
ddmitry
