docs(handbook): упрощен язык путеводителя

Зачем: начинающим ученикам трудно читать главы без пояснений терминов
и ожидаемого результата примеров.

Что: уточнены заголовки и объяснения в пяти главах и вводной, добавлена
сверка графика с SQL, обновлены ссылки из заданий и документации генератора.

Проверка: SQL и команды сохранены, локальные ссылки проверены;
git diff --check пройден. Ревью смысла Sol 6.1 high замечаний не выявило,
новые пояснения дополнительно сверены с кодом и настройками.

docs/handbook/README.md

@@ -4,9 +4,11 @@
 и попадают в отчеты. В главах есть короткие примеры, которые можно выполнить
 на запущенном стенде перед переходом к учебным заданиям.
 
-## Как читать
+## Порядок чтения
 
-Читайте главы в порядке ниже. Незнакомые термины можно найти в
+Сначала запустите стенд по [инструкции](../../README.md#быстрый-старт).
+Затем читайте главы по порядку и выполняйте примеры из них.
+Незнакомые термины можно найти в
 [словаре понятий](../../CONTEXT.md), а подробности устройства —
 в [технических справочниках](../architecture/). К ним достаточно обращаться
 по мере необходимости. После путеводителя переходите к
@@ -19,27 +21,27 @@ Gitea показывает HTML как текст. Откройте файл и
 или скачайте его кнопкой «Raw» и откройте в браузере.
 Сверяйтесь с картой при чтении главы «Хранилище и его слои».
 
-## Главы
+## Содержание
 
 ### [Хранилище и его слои](storage-layers.md)
 
 Как меняются данные при переходе из Kafka в слои STG, ODS, DDS и DM.
 В конце главы вы посмотрите события, сессии и выручку с помощью SQL.
 
-### [Потоки Airflow и даги модельного времени](airflow-dags.md)
+### [Генерация и обработка данных в Airflow](airflow-dags.md)
 
 Какие даги создают новые данные, а какие обрабатывают их в хранилище.
-Вы запустите генерацию и обработку за день и посмотрите результат в витринах.
+Вы сравните содержимое витрин до и после обработки нового дня.
 
-### [Мониторинг: куда смотреть](monitoring.md)
+### [Мониторинг в Grafana](monitoring.md)
 
 Что показывают панели Grafana и как меняются их показания, пока в стенд
-поступают события и заказы.
+поступают события и заказы. Вы увидите, почему заказы обновляются реже событий.
 
-### [Немного Superset](superset.md)
+### [Отчеты в Superset](superset.md)
 
-Как Superset строит графики по витринам и что происходит с вашими отчетами
-при перезапуске стенда.
+Как Superset строит графики по витринам. Вы сравните числа на готовом графике
+с результатом SQL и узнаете, какие отчеты сохраняются при перезапуске стенда.
 
 ### [Генератор: откуда берутся данные](generator.md)
 

docs/handbook/airflow-dags.md

@@ -1,19 +1,20 @@
-# Потоки Airflow и даги модельного времени
+# Генерация и обработка данных в Airflow
 
 Airflow управляет генерацией данных и их обработкой в хранилище. Это разные
 этапы: сначала в Kafka поступают события и заказы за день работы магазина,
 затем по ним рассчитываются данные DDS и витрины DM.
+Даг описывает задачи Airflow и порядок их выполнения.
 
 ```mermaid
 flowchart LR
     world_initialize --> etl_pipeline
     world_live_day --> etl_pipeline
-    manual[запуск рукой] --> etl_pipeline
+    manual[ручной запуск] --> etl_pipeline
     etl_pipeline --> dds_transform --> dm_transform --> dq_check
     world_next_day --> sources[источники без ETL]
 ```
 
-## Два потока входят по-разному
+## Загрузка событий и заказов
 
 События поступают в топик `hits` и обрабатываются по мере поступления:
 материализованные представления переносят строки из STG в ODS без участия
@@ -24,7 +25,7 @@ Airflow.
 Даг `orders_ingest` загружает ее целиком. Такой способ приема называется
 [пакетным](../../CONTEXT.md).
 
-## Даги мира
+## Генерация модельных дней
 
 В документации миром называется учебный магазин с его посетителями,
 товарами и заказами. Время в нем идет отдельно от календарного.
@@ -54,7 +55,7 @@ Airflow.
 номер дня остается прежним. Подробности — в [справочнике генератора
 и модельного времени](../architecture/world.md#даги-модельного-времени).
 
-## Дневной конвейер
+## Обработка данных в хранилище
 
 Даг `etl_pipeline` по очереди запускает `dds_transform`, `dm_transform`
 и `dq_check`, дожидаясь завершения каждого. Они рассчитывают данные DDS,
@@ -84,20 +85,21 @@ Airflow.
 проверок описан в [разделе «Звено DQ
 конвейера»](../architecture/dm.md#звено-dq-конвейера).
 
-## Как найти в интерфейсе
+## Поиск дагов в Airflow
 
 Даги мира ищите по тегам «модельное время» и «жизненный цикл мира». Остальные
 даги ищите по тегам «заказы», `etl`, `dds`, `dm` и `dq`. `homework_check` с
 тегами `dm` и `labs` проверяет домашние работы; о нем рассказано в учебных
 заданиях.
 
-## Посмотрите сами
+## Один день от генерации до витрин
 
 Откройте Airflow по адресу из раздела [«Адреса и
 пароли»](../../README.md#адреса-и-пароли). В Admin → Variables найдите
-`world_position`. Затем запустите `world_next_day` на один день по [инструкции
-из README](../../README.md#добавить-данные-за-следующие-дни). Убедитесь, что
+`world_position` и запомните его значение. Затем запустите `world_next_day`
+на один день по [инструкции из README](../../README.md#добавить-данные-за-следующие-дни). Убедитесь, что
 `orders_ingest` завершился успешно, а в витринах нового дня еще нет.
+Значение `world_position` должно увеличиться на один.
 Запустите `etl_pipeline` вручную и дождитесь его завершения.
 
 В DBeaver, подключенном по
@@ -121,8 +123,8 @@ LIMIT 3;
 приходит слепок за день D−1. Выручка дня D появится после генерации
 дня D+1 и запуска конвейера.
 
-## Куда дальше
+## Следующая глава и справочники
 
 Детали — в справочниках [конвейера](../architecture/etl.md) и
-[мира](../architecture/world.md). Следующая глава — [«Мониторинг: куда
-смотреть»](monitoring.md).
+[мира](../architecture/world.md). Следующая глава —
+[«Мониторинг в Grafana»](monitoring.md).

docs/handbook/generator.md

@@ -5,7 +5,7 @@
 магазина раз в модельные сутки выгружает состояние заказов в топик `orders`.
 Эта дневная выгрузка называется слепком.
 
-## Что он производит
+## События сайта и заказы
 
 Событие содержит сведения о действии посетителя: например, время,
 адрес страницы и идентификатор посетителя. Формат соответствует образцу
@@ -20,11 +20,11 @@
 разобраны в [отдельном
 справочнике](../architecture/orders/snapshot.md).
 
-## Почему данные всегда одни и те же
+## Почему начальные данные повторяются
 
 Случайные решения генератора зависят от заданного числа —
 [зерна генерации](../architecture/generator/seeds.md) — и номера дня.
-При неизменных настройках и версии генератора одинаковые зерно и день
+При неизменных коде, каталоге товаров и настройках одинаковые зерно и день
 дают одинаковые события. Поэтому при создании стенда вы каждый раз
 получаете те же начальные данные. Повторный `make up` на работающем стенде
 сохраняет уже загруженные данные.
@@ -34,10 +34,10 @@
 В документации этот файл называется паспортом мира. С ним можно сверить
 результат генерации и проверить, все ли события загрузились в ODS.
 
-## Кто его запускает
+## Запуск генератора
 
 На стенде генератором управляют [даги модельного
-времени](airflow-dags.md#даги-мира). Его можно запустить и напрямую. Команды
+времени](airflow-dags.md#генерация-модельных-дней). Его можно запустить и напрямую. Команды
 собраны в [справочнике генератора и модельного
 времени](../architecture/world.md#как-запустить-генератор).
 
@@ -45,7 +45,7 @@
 В живом режиме события поступают постепенно, как в работающем магазине,
 но время идет ускоренно: модельные сутки занимают около 24 минут.
 
-## Посмотрите сами
+## Сверка с паспортом мира
 
 Подключитесь из DBeaver по [инструкции](../../README.md#подключиться-из-dbeaver)
 и выполните запрос:
@@ -62,7 +62,7 @@ ORDER BY EventDate;
 Числа должны совпасть. Если вы уже генерировали следующие дни,
 в результате запроса будут дополнительные даты; в паспорте их нет.
 
-## Куда дальше
+## Учебные задания и справочники
 
 Подробнее генератор разобран в [README папки
 `generator/`](../../generator/README.md) и в [справочнике его

docs/handbook/monitoring.md

@@ -1,20 +1,19 @@
-# Мониторинг: куда смотреть
+# Мониторинг в Grafana
 
-В Grafana настроены три дашборда. «Данные» показывает загрузку и обработку
-событий и заказов, «Кластер» — состояние узлов и самого ClickHouse,
-а «Запросы» — выполненные запросы и затраченные на них ресурсы.
+В Grafana настроены три дашборда — экрана с показателями и графиками.
+«Данные» показывает загрузку и обработку событий и заказов,
+«Кластер» — состояние узлов и самого ClickHouse, а «Запросы» — выполненные
+запросы и затраченные на них ресурсы.
 
-Prometheus собирает метрики с двух узлов ClickHouse, ClickHouse Keeper
-и экспортера Kafka — службы, которая предоставляет метрики Kafka.
-Grafana получает данные из Prometheus и напрямую из ClickHouse.
 На панелях не заданы пороги для цветовых предупреждений: оценивать показания
 вы будете самостоятельно. Качество данных автоматически проверяет
 даг `dq_check`.
 
 ## Дашборд «Данные»
 
-«Свежесть» показывает, сколько времени прошло с последнего события и с
-последнего заказа в ODS. Показатель для заказов растет весь модельный день
+«Свежесть» показывает, сколько реального времени прошло с поступления
+последних успешно разобранных событий и заказов. Время поступления хранится
+в колонке `_load_ts` слоя ODS. Показатель для заказов растет весь модельный день
 и снижается, когда поступает очередная дневная выгрузка — слепок.
 Это ожидаемо: заказы загружаются раз в день.
 
@@ -33,7 +32,11 @@ STG: по нему видно, поступила ли очередная выг
 Источники и правила чтения всех панелей разобраны в [справочнике дашборда
 «Данные»](../architecture/monitoring/data.md).
 
-## Почему у панелей разные источники
+## Источники показателей
+
+Grafana получает данные напрямую из ClickHouse и через Prometheus.
+Prometheus собирает метрики с двух узлов ClickHouse, ClickHouse Keeper
+и экспортера Kafka — службы, которая предоставляет метрики Kafka.
 
 Свежесть считается по ODS: если новые сообщения перестали разбираться,
 показатель будет расти. Число поступивших сообщений берется из STG,
@@ -45,7 +48,7 @@ STG: по нему видно, поступила ли очередная выг
 всех доставленных сообщений. Подробности — в [разделе о слоях
 панелей](../architecture/monitoring/data.md#почему-слои-у-панелей-разные).
 
-## Два других дашборда
+## Состояние кластера и запросы
 
 Открывайте «Кластер», чтобы проверить нагрузку на процессор, использование
 памяти и дисков, число частей таблиц и ход их слияний в ClickHouse. Здесь же
@@ -58,11 +61,11 @@ STG: по нему видно, поступила ли очередная выг
 [справочник дашборда
 «Запросы»](../architecture/monitoring/queries.md).
 
-## Посмотрите сами
+## Показатели за один модельный день
 
 Откройте Grafana по адресу из раздела [«Адреса и
 пароли»](../../README.md#адреса-и-пароли), затем дашборд «Данные». Запустите в
-Airflow [`world_live_day`](airflow-dags.md#даги-мира): модельный день займет
+Airflow [`world_live_day`](airflow-dags.md#генерация-модельных-дней): модельный день займет
 около двадцати четырех минут.
 
 Смотрите свежесть событий и свежесть заказов по отдельности. Пока день идет,
@@ -73,11 +76,11 @@ Airflow [`world_live_day`](airflow-dags.md#даги-мира): модельны
 при генерации следующего дня. Даг пока продолжает работу, ожидая завершения
 обработки данных в дневном конвейере.
 
-## Куда дальше
+## Следующая глава и справочники
 
 Устройство мониторинга описано в [техническом
 справочнике](../architecture/monitoring/README.md), панели дашборда «Данные» —
 в [отдельном разделе](../architecture/monitoring/data.md).
 Почему выбраны именно эти показатели, объясняет
 [ADR 0002](../adr/0002-monitoring-scope.md). Следующая глава —
-[«Немного Superset»](superset.md).
+[«Отчеты в Superset»](superset.md).

docs/handbook/storage-layers.md

@@ -1,16 +1,17 @@
 # Хранилище и его слои
 
-В хранилище приходят два потока из Kafka: в топике `hits` — события
-кликстрима, в `orders` — заказы магазина. Оба проходят один путь: STG → ODS →
-DDS → DM. В STG сообщения сохраняются как есть, в ODS разбираются по полям,
-в DDS из них собираются события, заказы и сессии, а в DM — витрины для отчетов.
+В Kafka поступают события сайта, или кликстрим, и заказы магазина.
+Для событий выделен топик `hits`, для заказов — `orders`.
+Из Kafka данные проходят четыре слоя хранилища. В STG сообщения сохраняются
+как есть, в ODS разбираются по полям, в DDS из них собираются события,
+заказы и сессии, а в DM — витрины для отчетов.
 
 ```mermaid
 flowchart LR
     Kafka --> STG --> ODS --> DDS --> DM
 ```
 
-## Как читать имена
+## Имена таблиц и представлений
 
 Для обычного чтения выбирайте представления с суффиксом `_v`. Они позволяют
 менять устройство таблиц, сохраняя привычные запросы к данным.
@@ -20,7 +21,7 @@ flowchart LR
 Подробный разбор имен есть в [справочнике
 хранилища](../architecture/storage.md#имена-объектов).
 
-## STG: как поступило
+## STG: исходные сообщения
 
 STG — сырой слой. Он сохраняет сообщение целой строкой, без разбора. Вместе
 с ним записываются сведения о доставке: топик, партиция, смещение и время
@@ -31,7 +32,7 @@ STG — сырой слой. Он сохраняет сообщение цело
 удаляются по правилу из [справочника
 хранилища](../architecture/storage.md#срок-жизни-сырых-данных).
 
-## ODS: язык источника
+## ODS: разбор сообщений
 
 В ODS содержимое сообщения разбирается на колонки с нужными типами данных:
 датами, числами, строками. Колонки сохраняют имена из источника. Например,
@@ -41,7 +42,7 @@ STG — сырой слой. Он сохраняет сообщение цело
 `*_errors` вместе с исходной строкой и классом ошибки. Правильно записанные
 сообщения обрабатываются дальше.
 
-## DDS: язык бизнеса
+## DDS: события, заказы и сессии
 
 DDS — детальный слой: в нем данные подготовлены для анализа событий,
 заказов и сессий. Здесь же хранится карта идентичностей — таблица связей
@@ -51,6 +52,8 @@ DDS — детальный слой: в нем данные подготовле
 
 В стенде визитом, или сессией, считают подряд идущие события одного
 `ClientID` без пауз дольше 30 минут. Визит не пересекает границу модельных суток.
+Модельные сутки — день в календаре учебного магазина. Этот календарь
+не зависит от текущей даты на вашем компьютере.
 
 Источник передает готовый идентификатор визита `VisitID` по образцу
 Яндекс Метрики. В учебном хранилище сессии рассчитываются заново по времени
@@ -61,7 +64,7 @@ DDS — детальный слой: в нем данные подготовле
 Готовые сессии читайте через `dds.session_v`. События для самостоятельного
 расчета доступны в `dds.event_v`: в этом представлении `VisitID` скрыт.
 
-## DM: данные для дашбордов
+## DM: витрины для отчетов
 
 DM — слой витрин. Витрина — готовый набор показателей для отчета или
 дашборда. Здесь уже посчитаны, например, дневная выручка по категориям и
@@ -71,7 +74,7 @@ DM — слой витрин. Витрина — готовый набор по
 путь расчета. Состав готовых витрин смотрите в [карте
 таблиц](../architecture/storage.md#карта-таблиц).
 
-## Справочные данные: зона `dic`
+## Справочники в базе `dic`
 
 В базе `dic` хранятся готовые справочные данные. Они загружаются отдельно
 от событий и заказов и могут использоваться в расчетах любого слоя.
@@ -81,7 +84,7 @@ DM — слой витрин. Витрина — готовый набор по
 устроена зона, смотрите в [разделе о
 справочниках](../architecture/storage.md#справочники).
 
-## Сквозные ключи
+## Связь данных между слоями
 
 Идентификаторы позволяют связать данные из разных слоев. При переходе в DDS
 часть колонок переименовывается: например, `WatchID` становится `event_id`.
@@ -99,7 +102,7 @@ DM — слой витрин. Витрина — готовый набор по
 [словарь понятий](../../CONTEXT.md#язык). Точные имена объектов и полей сверяйте с
 [картой таблиц](../architecture/storage.md#карта-таблиц).
 
-## Посмотрите сами
+## Примеры запросов
 
 Подключитесь к ClickHouse по инструкции из разделов [«Адреса и
 пароли»](../../README.md#адреса-и-пароли) и [«Подключиться из
@@ -122,6 +125,8 @@ ORDER BY UTCEventTime
 LIMIT 20;
 ```
 
+Каждая строка здесь — отдельное действие посетителя.
+
 Второй запрос покажет 20 сессий того же дня с наибольшим числом событий.
 Сессии рассчитаны по всем событиям дня:
 
@@ -140,7 +145,12 @@ ORDER BY events_total DESC
 LIMIT 20;
 ```
 
-Третий запрос покажет готовую выручку по категориям за тот же день:
+Теперь одна строка представляет целый визит. `events_total` показывает,
+сколько событий в него вошло; начало и конец визита записаны в
+`started_at` и `finished_at`.
+
+Третий запрос покажет выручку магазина по категориям за тот же день.
+Эта витрина рассчитана по заказам:
 
 ```sql
 SELECT
@@ -153,13 +163,13 @@ WHERE report_date = '2026-06-01'
 ORDER BY revenue DESC;
 ```
 
+Здесь одна строка содержит итоги дня для категории товаров.
 Все три запроса читают представления `_v`.
 
-## Куда дальше
+## Следующая глава и справочники
 
 Откройте [интерактивную карту](architecture-map.html) из своей копии
 репозитория и проследите путь данных.
 Список объектов, сроки хранения и устройство таблиц — в [справочнике
 хранилища](../architecture/storage.md). Как данные обрабатываются между слоями — в
-следующей главе: [потоки Airflow и даги модельного
-времени](airflow-dags.md).
+следующей главе: [«Генерация и обработка данных в Airflow»](airflow-dags.md).

docs/handbook/superset.md

@@ -1,4 +1,4 @@
-# Немного Superset
+# Отчеты в Superset
 
 Superset показывает витрины слоя DM в виде графиков. К ClickHouse он
 подключается пользователем `bi`. Дашборд стенда «Бизнес-сюжеты» собран из трех
@@ -24,7 +24,7 @@ Superset показывает витрины слоя DM в виде графи
 Затем на основе датасета создается график: выбираются показатели и способ
 их отображения. Несколько графиков можно разместить на одном дашборде.
 
-## Стендовые объекты и ваши
+## Готовые и собственные отчеты
 
 Готовые датасеты, графики и дашборд сохранены в файлах репозитория
 и импортируются при каждом `make up`. Если изменить их через интерфейс,
@@ -43,13 +43,14 @@ Superset](../architecture/superset.md#импорт-при-каждой-иниц
 Последняя дата с выручкой на день раньше последней даты с событиями
 кликстрима. Выгрузка заказов за день D поступает при генерации следующего
 дня D+1, а затем обрабатывается конвейером. Вы уже видели эту разницу
-в [главе об Airflow](airflow-dags.md#посмотрите-сами). Начальное состояние
+в [главе об Airflow](airflow-dags.md#один-день-от-генерации-до-витрин). Начальное состояние
 показано в разделе [«Стартовый мир»](../architecture/world.md#стартовый-мир).
 
-## Посмотрите сами
+## Сверка графика с витриной
 
 Откройте Superset по адресу из раздела [«Адреса и
 пароли»](../../README.md#адреса-и-пароли) и выберите дашборд «Бизнес-сюжеты».
+Найдите график «Посетители и известные пользователи».
 Затем откройте SQL Lab и выполните запрос:
 
 ```sql
@@ -59,9 +60,14 @@ ORDER BY report_date DESC
 LIMIT 7;
 ```
 
-Как построить свой отчет, рассказывают [учебные задания](../labs/README.md).
+Выберите одну дату из результата. На дашборде задайте «Период», в который
+она входит, и обновите график. Наведите указатель на точку этой даты:
+числа посетителей и известных пользователей должны совпасть с `visitors`
+и `known_users` из SQL.
 
-## Куда дальше
+Как построить собственный отчет, рассказывают [учебные задания](../labs/README.md).
+
+## Следующая глава и справочники
 
 Подключение и настройка Superset описаны в [справочнике
 Superset](../architecture/superset.md), а состав витрин — в [справочнике