feat(module-1): доработаны материалы модуля 1 и удалён legacy-ноутбук
- Зачем: - нужен воспроизводимый вход в курс и единое место хранения планов по модулям. - Что: - добавлены `plans/README.md`, living plan Модуля 1, `START_HERE.md` и канонический ноутбук `01_environment_and_smoke_test.ipynb`, а `cluster_smoke.py` расширен до reusable helper и CLI smoke test. - уточнены onboarding-материалы и окружение: добавлены Spark UI в `README.md`, ресурсы хоста и креды MinIO в `START_HERE.md`, использован `NB_GID` в `jupyter/Dockerfile`, в ноутбуке усилены самостоятельные задания и добавлены `cell id`, а пояснения в `cluster_smoke.py` переведены на русский для студентов. - обновлены `README.md`, `AGENTS.md` и archive howto, удалены устаревшие `spark-basic-test.ipynb` и `03_partitioning_and_schema_evolution.ipynb`. - Проверка: - `python3 -m py_compile src/spark/cluster_smoke.py src/spark/__init__.py`. - `docker compose build spark-master` и `docker compose build jupyter`. - `docker compose up -d`, `docker compose exec jupyter python3 -c "from spark.cluster_smoke import create_spark_session, run_cluster_smoke; spark=create_spark_session(app_name='module-01-validation'); print(run_cluster_smoke(spark)); spark.stop()"` и `docker compose exec jupyter jupyter nbconvert --to notebook --execute /opt/work/01_environment_and_smoke_test.ipynb --output-dir /tmp --output module1-validation-2.ipynb`.
This commit is contained in:
@@ -0,0 +1,16 @@
|
||||
# Планы работ
|
||||
|
||||
Этот каталог хранит внутренние рабочие планы по развитию учебного курса.
|
||||
|
||||
## Правила хранения
|
||||
|
||||
- Формат: `living docs`.
|
||||
- История изменений хранится в git.
|
||||
- Именование файлов: `module-NN-<english-slug-from-module-title>.md`.
|
||||
- В каждом плане фиксируются `Статус` и `Последнее обновление`.
|
||||
|
||||
## Оглавление
|
||||
|
||||
| Модуль | План | Статус | Целевые артефакты | Обновлён |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1. Вход в стенд и базовая диагностика | [module-01-environment-and-basic-diagnostics.md](./module-01-environment-and-basic-diagnostics.md) | Ready for validation | `START_HERE.md`, `notebooks/01_environment_and_smoke_test.ipynb`, `src/spark/cluster_smoke.py` | 2026-03-06 |
|
||||
@@ -0,0 +1,67 @@
|
||||
# Модуль 1. Вход в стенд и базовая диагностика
|
||||
|
||||
**Статус:** `Ready for validation`
|
||||
**Последнее обновление:** `2026-03-06`
|
||||
|
||||
## Цель
|
||||
|
||||
Дать студенту безопасный и воспроизводимый вход в курс: он должен сам поднять локальный стенд, открыть основные веб-интерфейсы, выполнить Spark smoke test и понять первый маршрут диагностики проблем.
|
||||
|
||||
## Результат для студента
|
||||
|
||||
После прохождения модуля студент:
|
||||
|
||||
- поднимает стенд командами `docker compose build` и `docker compose up -d`;
|
||||
- проверяет состояние контейнеров через `docker compose ps`;
|
||||
- открывает `Spark UI`, `MinIO Console`, `Trino UI` и `JupyterLab`;
|
||||
- запускает smoke test Spark-кластера и понимает, что именно он проверяет;
|
||||
- знает, куда смотреть при первичной диагностике через логи и UI.
|
||||
|
||||
## Deliverables
|
||||
|
||||
- `plans/README.md` как индекс всех рабочих планов;
|
||||
- `START_HERE.md` как канонический вход в курс до первого ноутбука;
|
||||
- `notebooks/01_environment_and_smoke_test.ipynb` как канонический ноутбук Модуля 1;
|
||||
- `src/spark/cluster_smoke.py` как общий helper и CLI smoke test;
|
||||
- обновлённые ссылки и инструкции в `README.md` и `AGENTS.md`.
|
||||
|
||||
## План работ
|
||||
|
||||
1. Создать каталог `plans/` и зафиксировать в нём правила хранения и индекс.
|
||||
2. Подготовить `START_HERE.md` с prerequisites, запуском, проверкой сервисов, входом в Jupyter и reset/restart шагами.
|
||||
3. Расширить `src/spark/cluster_smoke.py` до reusable helper с функцией `run_cluster_smoke(spark) -> dict` и CLI `main()`.
|
||||
4. Собрать `notebooks/01_environment_and_smoke_test.ipynb` по схеме `объяснение -> демонстрация -> самостоятельное повторение -> checkpoint`.
|
||||
5. Перенести полезное содержимое из старого `spark-basic-test.ipynb` в новый ноутбук и убрать старый артефакт из активного маршрута.
|
||||
6. Обновить `README.md` и `AGENTS.md`, чтобы новый вход и новый ноутбук стали каноническими.
|
||||
7. Прогнать валидацию: smoke script должен проходить синтаксическую проверку, а ноутбук должен быть валидным `ipynb`.
|
||||
|
||||
## Checkpoint
|
||||
|
||||
Студент должен уметь:
|
||||
|
||||
- показать результат `docker compose ps`;
|
||||
- открыть `Spark UI`, `MinIO Console`, `Trino UI` и `JupyterLab`;
|
||||
- выполнить smoke test и объяснить, что он подтвердил;
|
||||
- назвать роли `MinIO`, `PostgreSQL`, `Spark`, `Trino` и `Jupyter`;
|
||||
- описать первый шаг диагностики, если не поднимается `trino` или `spark-master`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `START_HERE.md` позволяет поднять стенд с нуля без обращения к `docs/archive/legacy_howto.md`;
|
||||
- `notebooks/01_environment_and_smoke_test.ipynb` можно выполнить сверху вниз в поднятом Jupyter-окружении;
|
||||
- один и тот же smoke helper используется из CLI и из ноутбука;
|
||||
- в репозитории остаётся один канонический вход в Модуль 1;
|
||||
- `plans/README.md` позволяет быстро найти модульный план и понять его статус.
|
||||
|
||||
## Риски
|
||||
|
||||
- Старые ссылки на `spark-basic-test.ipynb` могут остаться в инструкциях и создавать путаницу.
|
||||
- Если smoke test будет слишком сложным, он перестанет быть быстрым диагностическим шагом.
|
||||
- Если в ноутбуке окажутся host-level команды, студент может ошибочно пытаться запускать `docker compose` внутри Jupyter.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- загрузка raw-данных;
|
||||
- разбор internals `Iceberg`;
|
||||
- запросы к `Trino` как отдельная практика;
|
||||
- `schema evolution`, `time travel`, `compaction`, `vacuum`.
|
||||
Reference in New Issue
Block a user