docs(course): integrate Spark setup into the module flow

plans/course-roadmap.md

@@ -36,28 +36,13 @@ Iceberg-таблицы. Результаты проверок и их огран
 
 ### 2. Добавить практику «Как настроен Spark в нашем стенде»
 
-**Статус:** готово к ревью по #2; зависимость #1 закрыта, её итог прочитан. Практика добавлена в начало модуля 3, PRD, программа и справочные материалы обновлены.
-
-**Результат:** проверены демонстрация, заполненный шаблон и контрольное решение, повторные ячейки, настоящий перезапуск ядра, временная Iceberg-таблица и весь raw-ingest. Машинный прогон — 4 минуты 10 секунд; время самостоятельного прохождения студентом ещё не измерено. Подробности и ограничения — в [отчёте проверки](issue-2-spark-session-validation.md).
+**Статус:** на ревью, [MR #4](https://git.dementev.space/ddmitry/mini-lakehouse-lab/pulls/4).
 
 **Задача:** [#2 — практика базовой настройки SparkSession](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/2).
 
-Практику разместить в начале модуля 3. Ориентир — 20–30 минут; фактическую длительность проверить при прохождении.
+В модуле 3 студент готовит Spark-сессию, проверяет подключение и затем переходит к загрузке и чтению Taxi. Содержание и checkpoint описаны в [программе](../docs/course_program.md#модуль-3-raw-данные-и-первое-чтение-в-spark).
 
-Студент должен научиться:
-
-- объяснять роли `SparkSession`, `SparkContext`, driver и executors на примере стенда;
-- читать код с `master`, `appName` и `getOrCreate`;
-- находить источник настройки: конфигурационный файл, параметры запуска или код;
-- проверять фактический master и выбранные настройки каталога Iceberg и MinIO;
-- различать настройки, меняемые во время работы, и настройки, требующие нового запуска;
-- понимать, что повторное выполнение ячейки может использовать уже существующую сессию.
-
-**Практика и checkpoint:** студент заполняет небольшой шаблон создания сессии, задаёт подключение к кластеру и имя приложения, использует подготовленные настройки каталога, проверяет фактическое подключение и читает небольшую учебную Iceberg-таблицу. Таблица должна создаваться самой практикой: демонстрационные таблицы модуля 2 могут быть удалены при его завершении. Студент объясняет, какие настройки он задал сам, какие предоставил стенд и что потребуется повторить в новом ядре.
-
-При реализации обновить learning outcomes и scope в PRD, содержание и checkpoint модуля 3 в программе, ноутбук и связанные справочные материалы. Сохранить структуру из восьми модулей.
-
-**Граница темы:** базовая настройка подключения и жизненный цикл сессии. Подробный подбор памяти, числа executors, shuffle и GC остаётся за рамками этой доработки.
+Код проверен на стенде, включая перезапуск ядра и полный raw-ingest. Замеры и ограничения проверки сохранены в [отчете](issue-2-spark-session-validation.md).
 
 ### 3. Собрать замечания по оставшейся части курса
 

plans/issue-2-spark-session-validation.md

@@ -89,3 +89,7 @@ Hadoop S3A оставил шесть нулевых маркеров `data/` и
 - проверка ноутбука через `nbformat.validate` и синтаксиса Python-ячеек через AST;
 - относительные ссылки изменённых документов и ноутбука;
 - сохранение восьми модулей и маршрута README → START_HERE → программа → ноутбук.
+
+После редакторской правки по ревью повторно проверены ссылки, нумерация разделов
+и синтаксис Python. Все исполняемые ячейки, их порядок и контрольное решение
+совпадают с проверенной версией. Стенд повторно не запускался.

plans/module-03-raw-ingest-and-first-read.md

@@ -1,23 +1,22 @@
 # Модуль 3. Raw-данные и первое чтение в Spark
 
-**Статус:** `Ready for review` — код проверен на стенде, время самостоятельного прохождения студентом пока не измерено
+**Статус:** `Ready for review`
 **Последнее обновление:** `2026-09-15`
 
-Дополнение: [#2 — практика настройки SparkSession](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/2), после закрытой [#1](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/1). Новая практика входит в модуль 3; структура курса остаётся из восьми модулей.
+**Задача:** [#2](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/2).
 
 Результаты прогона и ограничения: [проверка #2](issue-2-spark-session-validation.md).
 
 ## Цель
 
-Научить студента полному циклу работы с raw-данными в Lakehouse: доставка заранее скачанного PARQUET-датасета в raw-зону MinIO, чтение raw-данных через Spark, проверка схемы, типов и базового качества. Студент должен понять, зачем нужен raw-слой и почему raw-данные не следует «чинить на месте».
+Научить студента подключаться к Spark-кластеру и работать с raw-данными: загружать заранее скачанный PARQUET-датасет в MinIO, читать его через Spark и проверять схему, типы и базовое качество. Студент должен понять, зачем нужен raw-слой и почему raw-данные не следует «чинить на месте».
 
 ## Результат для студента
 
 После прохождения модуля студент:
 
-- создаёт Spark-сессию для кластера, различает настройки из кода, параметров запуска и общего файла;
-- проверяет фактический master, имя приложения, настройки каталога и чтение собственной временной Iceberg-таблицы;
-- объясняет повторное использование контекста, остановку сессии и перезапуск ядра; меняет часовой пояс с восстановлением исходного значения;
+- создает сессию для кластера с подготовленным каталогом, проверяет настройки и понимает их источники;
+- различает повторный вызов builder-а, остановку сессии и перезапуск ядра;
 - понимает, как локальный data bundle попадает в raw-зону MinIO;
 - умеет загружать PARQUET-файлы в MinIO программно через `boto3`;
 - умеет читать raw-данные из MinIO через Spark (`spark.read.parquet` по `s3a://` пути);
@@ -88,63 +87,58 @@ volumes:
 
 ## Структура ноутбука
 
-### Секция 0: Введение
-- **[md]** Заголовок, цели модуля, prerequisite (data bundle из `START_HERE.md`). Таблица-сравнение: «Классический DWH: данные уже внутри СУБД» vs «Lakehouse: данные нужно явно доставить в storage».
+### Секция 0: Перед стартом
+- **[md]** Связь с модулем 2, цели работы с Taxi и условия старта: работающий стенд, скачанный data bundle, новое ядро.
 
-### Секция 0.1: Как настроен Spark в нашем стенде
+### Секция 1: Как настроен Spark в нашем стенде
+- **[md]** SparkSession, SparkContext, driver и executors, local и кластер; источники настроек и подготовленный каталог.
+- **[code]** Создание сессии, фактический master и несекретные настройки. Изменение часового пояса с восстановлением. Повторный builder сохраняет контекст; `stop()` позволяет создать приложение с новым именем.
 
-- **Объяснение:** SparkSession, SparkContext, driver в Jupyter, executors на worker-ах; master, appName, getOrCreate; local и кластер. Источники настроек и подготовленный доступ к Iceberg/MinIO.
-- **Демонстрация:** сессия с master из общего файла, вычисление суммы 0…9, вывод выбранных несекретных настроек. Изменение `spark.sql.session.timeZone` и восстановление в `finally`.
-- **Новый запуск:** повторный builder с другим appName сохраняет фактическое имя контекста; после `stop()` новый контекст получает новое имя.
-- **Самостоятельное повторение:** заполнить адрес кластера, имя приложения и builder; контрольное решение в раскрывающемся блоке. Повторить ячейку и проверить неизменный applicationId.
-- **Проверка каталога:** создать собственную Iceberg-таблицу с уникальным именем, прочитать `[0, 1]`, удалить только её через `DROP TABLE … PURGE` в `finally`. Учебные таблицы других модулей не используются.
-- **Checkpoint:** проверить master и appName, объяснить источники настроек и место вычислений. После удаления временной таблицы перезапустить ядро, повторить заполненный шаблон и проверку Iceberg, затем продолжить raw-ingest.
-- **Длительность:** ориентир 20–30 минут; на модуль целиком около 2 часов. Замер машинного выполнения и ограничения проверки фиксируются отдельно от оценки времени студента.
+### Секция 2: Подключись к Spark самостоятельно
+- **[code]** Шаблон подключения и контрольное решение. Проверка master и appName, запись и чтение `[0, 1]` из собственной временной таблицы, удаление в `finally`.
+- **[md]** После удаления таблицы перезапустить ядро, повторить заполненный шаблон и проверки. Оставить сессию для чтения Taxi.
 
-### Секция 0.2: Подготовка к raw-ingest
-
-- Импорты, MinIO-клиент, пути и вспомогательные функции исходного урока. Сессия продолжает работать после checkpoint настройки.
-
-### Секция 1: Проверка data bundle
+### Секция 3: Проверка data bundle
+- **[code]** Импорты, MinIO-клиент, пути и вспомогательные функции для работы с файлами.
 - **[md]** Зачем проверяем; почему не скачиваем из интернета в ноутбуке (воспроизводимость, сетевые ограничения, разделение ответственности onboarding vs практика).
-- **[code]** `os.listdir("/opt/data/nyc_taxi")`, вывод файлов с размерами, assert на наличие PARQUET-файлов и `taxi_zone_lookup.csv` — оба нужны для полного прохождения модуля (включая самостоятельное задание в Секции 6). Понятное сообщение с отсылкой к `START_HERE.md` при отсутствии любого из компонентов.
+- **[code]** `os.listdir("/opt/data/nyc_taxi")`, вывод файлов с размерами, assert на наличие PARQUET-файлов и `taxi_zone_lookup.csv` — оба нужны для полного прохождения модуля (включая самостоятельное задание в Секции 8). Понятное сообщение с отсылкой к `START_HERE.md` при отсутствии любого из компонентов.
 
-### Секция 2: Загрузка в raw-зону MinIO
+### Секция 4: Загрузка в raw-зону MinIO
 - **[md]** Что такое raw-зона, параллель с stg-слоем в Greenplum, конвенция путей, почему raw не чинится «на месте».
 - **[code]** Демонстрация: перед загрузкой проверяем через `s3.head_object()`, существует ли уже объект с таким ключом. Три ветки: (1) объект не существует — загружаем через `boto3.upload_file()`; (2) объект существует и размер совпадает с локальным файлом — пропускаем с пометкой «already exists, skipping»; (3) объект существует, но размер отличается — **fail fast** с понятной ошибкой (raise), без перезаписи. Это обеспечивает идемпотентность и подкрепляет принцип «raw не перезаписывается». В markdown-пояснении перед ячейкой явно объяснить: повторный запуск безопасен, уже загруженные файлы не перетираются, а конфликт размеров сигнализирует о проблеме с данными.
 - **[code]** Верификация: `s3.list_objects_v2()` — листинг raw-зоны.
 - **[md]** Данные теперь в storage. Spark может читать их напрямую по `s3a://` пути; для Trino потребуется зарегистрированная таблица (это будет в Модулях 4 и 6).
 
-### Секция 3: Первое чтение в Spark
-- **[md]** Разница `spark.read.parquet("s3a://...")` (raw-файлы) vs `spark.table(...)` (управляемая Iceberg-таблица). Мы пока на этапе raw, Iceberg-таблица появится в Модуле 4.
-- **[code]** Чтение через сессию, созданную в секции 0.1; повторная инициализация не нужна.
+### Секция 5: Первое чтение в Spark
+- **[md]** Разница `spark.read.parquet("s3a://...")` (raw-файлы) vs `spark.table(...)` (управляемая Iceberg-таблица). Проверочная таблица удалена; таблицу поездок создаем в Модуле 4.
+- **[code]** Чтение через сессию, созданную в секции 2; повторная инициализация не нужна.
 - **[code]** Чтение одного файла: `spark.read.parquet("s3a://lakehouse/raw/nyc_taxi/yellow_tripdata_2024-01.parquet")`.
 - **[code]** Чтение всех файлов wildcard: `yellow_tripdata_*.parquet` (без привязки к конкретному году в wildcard, чтобы код работал с любыми скачанными файлами).
 
-### Секция 4: Проверка схемы
+### Секция 6: Проверка схемы
 - **[md]** Зачем проверять схему: в классическом DWH схема задана DDL, в raw — вычитывается из файлов. Что может пойти не так: разные типы в разных файлах, неожиданные nullable-поля.
 - **[code]** `.printSchema()`.
 - **[code]** Колонки и типы в удобном формате (`.dtypes`).
 - **[code]** Null-анализ ключевых колонок (`VendorID`, `tpep_pickup_datetime`, `passenger_count`, `trip_distance`, `total_amount`) — количество и доля null в каждой.
 - **[md]** Обсуждение: null в raw — норма, не исправляем на месте. Очистка — задача bronze/silver слоев (Модули 4-5).
 
-### Секция 5: Базовые метрики и аномалии
+### Секция 7: Базовые метрики и аномалии
 - **[md]** Цель: быстро понять диапазоны значений, выявить очевидные проблемы.
 - **[code]** `.describe()` на числовых колонках.
 - **[code]** Поиск аномалий: отрицательные `fare_amount`, нулевая дистанция с ненулевой суммой, `total_amount > $1000`, pickup за пределами ожидаемого диапазона дат (определяется динамически из имён файлов, а не хардкодится).
 - **[md]** Аномалии в реальных данных — норма, а не баг загрузки. Задача raw — сохранить как есть.
 
-### Секция 6: Самостоятельное задание
+### Секция 8: Самостоятельное задание
 - **[md]** Инструкция: (1) прочитать `taxi_zone_lookup.csv` из raw-зоны через Spark, (2) вывести схему + 10 строк, (3) посчитать количество зон по borough, (4) найти топ-5 pickup locations и join с зонами, (5) найти ещё одну аномалию или интересный паттерн в данных.
 - **[code]** 4 пустых ячейки с `# Ваш код: ...`.
 
-### Секция 7: Почему raw-слой важен
+### Секция 9: Почему raw-слой важен
 - **[md]** Мини-лекция (3-5 абзацев): raw = неизменяемый архив; параллель с stg/ods в Greenplum; почему не скачиваем в ноутбуке; почему не чиним на месте (можно перестроить bronze/silver заново); в Lakehouse raw-файлы лежат в storage отдельно от compute — Spark читает их напрямую, а для Trino потребуется оформить данные в таблицу.
 
-### Секция 8: Checkpoint
-- **[md]** Вопросы для самопроверки: (1) показать файлы в raw-зоне MinIO, (2) какая схема у Yellow Taxi — сколько колонок, (3) какие колонки содержат null — это баг или норма, (4) зачем raw-слой, если данные потом трансформируются, (5) почему не скачиваем из ноутбука, (6) что произойдёт, если NYC TLC изменит формат файла.
+### Секция 10: Checkpoint
+- **[md]** Вопросы об источниках настроек, месте выполнения заданий и новом ядре; затем самопроверка по данным: (1) показать файлы в raw-зоне MinIO, (2) какая схема у Yellow Taxi — сколько колонок, (3) какие колонки содержат null — это баг или норма, (4) зачем raw-слой, если данные потом трансформируются, (5) почему не скачиваем из ноутбука, (6) что произойдёт, если NYC TLC изменит формат файла.
 
-### Секция 9: Завершение
+### Секция 11: Завершение
 - **[md]** «Мы намеренно не удаляем raw-данные из MinIO. В Модуле 4 мы будем использовать их для создания bronze-слоя.»
 - **[code]** `spark.stop()`.
 
@@ -184,7 +178,7 @@ volumes:
 ## Риски
 
 - **Размер данных.** 3 месяца Yellow Taxi — примерно 120-150 MB (~40-50 MB на файл). Комфортно для стенда с 10 GB RAM. Extended (12 месяцев, ~600 MB) может замедлить Spark, но не должен вызывать падения.
-- **Студент забыл скачать данные.** Assert в Секции 1 с понятным сообщением и ссылкой на `START_HERE.md`.
+- **Студент забыл скачать данные.** Assert в Секции 3 с понятным сообщением и ссылкой на `START_HERE.md`.
 - **NYC TLC изменит формат/URL.** Ноутбук использует wildcard `yellow_tripdata_*.parquet` без привязки к году. Инструкция в `START_HERE.md` фиксирует конкретные файлы 2024-01..03, но если URL станут недоступны — потребуется обновление инструкции.
 - **Директория `data/` не существует.** Docker volume mount создаст пустую директорию, assert в ноутбуке поймает отсутствие файлов.
 - **Пересоздание контейнера.** Добавление volume в `docker-compose.yml` требует пересоздания контейнера `jupyter` (`docker compose up -d` достаточно — Docker пересоздаст только изменённый сервис). После этого bind mount уже работает: новые файлы в `./data` видны сразу без дополнительных перезапусков. Указать явно в инструкции.