From 7bf61d8f746f2a973d153df17ec688f8db121b5b Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 22 Sep 2026 09:20:48 -0400 Subject: [PATCH] =?UTF-8?q?docs(labs):=20=D0=B7=D0=B0=D1=84=D0=B8=D0=BA?= =?UTF-8?q?=D1=81=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BD=D0=BE=20=D1=80=D0=B0?= =?UTF-8?q?=D0=B7=D0=B2=D0=B8=D1=82=D0=B8=D0=B5=20=D1=83=D1=87=D0=B5=D0=B1?= =?UTF-8?q?=D0=BD=D0=BE=D0=B9=20=D0=BF=D1=80=D0=BE=D0=B3=D1=80=D0=B0=D0=BC?= =?UTF-8?q?=D0=BC=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Описаны аудитория, обязательная лабораторная по приему справочника, предложения по закрытию пробелов и критерии подготовки заданий. Оценка и ссылки на учебный код относятся к main. Проверка: новые ссылки сверены по локальным веткам, git diff --cached --check пройден. --- AGENTS.md | 5 + docs/README.md | 1 + docs/design/assignment_design.md | 19 +-- docs/design/labs_development.md | 197 +++++++++++++++++++++++++++++++ 4 files changed, 208 insertions(+), 14 deletions(-) create mode 100644 docs/design/labs_development.md diff --git a/AGENTS.md b/AGENTS.md index bd05319..6da37bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -74,6 +74,11 @@ - `make clean` удаляет тома — предупреждайте студентов, что данные пропадут. ## Для агента (особенности аудитории) + +При создании и пересмотре лабораторных сначала прочитайте +[развитие лабораторных](docs/design/labs_development.md): аудитория, +принятые решения и критерии заданий. + - Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике. - Избегайте больших рефакторингов и сложных паттернов — студенты только начинают. - Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»). diff --git a/docs/README.md b/docs/README.md index d3f79cd..22c6df7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ - [Архитектурные решения (ADR)](design/architecture_review.md) - [PRD: стратегия курсовой](design/PRD.md) - [Дизайн задания](design/assignment_design.md) +- [Развитие лабораторных: аудитория, решения и критерии заданий](design/labs_development.md) ## Справочники (`reference/`) diff --git a/docs/design/assignment_design.md b/docs/design/assignment_design.md index 13d18db..774892c 100644 --- a/docs/design/assignment_design.md +++ b/docs/design/assignment_design.md @@ -156,18 +156,9 @@ bookings_validate --- -## 6. Бэклог: идеи для будущих итераций +## 6. Развитие лабораторных -### PXF-практикум (замена STG-заданий) - -После переноса всего STG-слоя в эталон (см. `docs/plans/2026-03-11_routes-to-reference.md`) -студенты не практикуются в создании PXF external tables и загрузке сырых данных. -Это важный навык для DE — нужно компенсировать отдельным заданием. - -Варианты: -- **Новый источник данных**: подключить CSV/JSON-файл (например, справочник городов - или курсов валют) через PXF и загрузить в отдельную STG-таблицу -- **Мини-задание «подключи внешний справочник»**: студент создаёт PXF external table - для существующей таблицы источника и сравнивает результат с эталонной STG -- **Лабораторная работа**: отдельное упражнение на создание external table + - сравнение форматов (TEXT vs CUSTOM), профилей PXF, обработку типов +Перед добавлением или пересмотром заданий прочитайте +[заметку о развитии лабораторных](labs_development.md): там зафиксированы +аудитория, решение по PXF-практикуму, предложения по обязательному циклу +и общие критерии подготовки заданий. diff --git a/docs/design/labs_development.md b/docs/design/labs_development.md new file mode 100644 index 0000000..e0d1700 --- /dev/null +++ b/docs/design/labs_development.md @@ -0,0 +1,197 @@ +# Развитие лабораторных работ + +Рабочая заметка для автора программы, 22 сентября 2026 года. +Документ хранится в ветке `solution`; оценка программы и ссылки +на действующие задания и код относятся к учебной ветке `main`. +Приоритет — закрыть пробелы обязательного цикла. Принятое решение о новой +лабораторной записано отдельно от предложений, которые еще обсуждаются. +Действующий маршрут и требования находятся в [учебных заданиях](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/docs/assignment/README.md) +и [ТЗ](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/docs/assignment/analyst_spec.md). + +## Аудитория и цель + +Студент хорошо изучил PostgreSQL и прошел 16-часовой курс Greenplum от Яндекса. +Теперь ему нужна практика применения этих знаний в работе Data Engineer. +Стенд служит учебным пособием, похожим на небольшое хранилище компании: +здесь есть источники, связанные слои данных, загрузки и потребители. + +Программа должна дать опыт подключения источника, построения загрузок +и моделей, оркестрации, проверки результата и восстановления после ошибок. +Знакомые SQL-инструменты студент применяет к инженерным задачам и объясняет +свои решения на данных. Разнообразие работ определяется новыми действиями +и решениями; дополнительная витрина полезна, если она дает такой опыт. + +Подготовка по Airflow пока не задана. Первые необходимые действия в UI +нужно сопровождать короткой инструкцией или ссылкой на нее. Самостоятельное +написание задач и зависимостей вводится явно в соответствующей работе. + +## Метод и рост самостоятельности + +Стенд учебный: его можно ломать и восстанавливать. Готовая реализация +позволяет сначала увидеть работающую цепочку, а затем самостоятельно +реализовать выбранный участок. Полнота эталона при первом запуске +не ограничивает состав лабораторных. + +Этот прием уже используется в +[программе Clickstream](https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/docs/specs/2026-09-01-labs-program.md): +при «вычитании» студент удаляет готовую реализацию и пишет свою; +при работе «собери рядом» сравнивает свою реализацию с работающей; +при расследовании находит и устраняет причину подготовленной ошибки. +Можно также расширять стенд новым источником или объектом по ТЗ. + +Границу самостоятельной работы определяет навык: в задании по SQL можно +оставить готовый DAG, а в задании по оркестрации — готовые SQL-скрипты. +Вычитание дает способ выделить участок для работы; самостоятельность +обеспечивают решения, которые студент принимает и проверяет: + +1. В первых работах даны требования к результату, близкий пример и готовая + проверка. Студент выбирает реализацию и испытывает ее на заданных случаях. +2. Дальше студент обосновывает способ загрузки или устройство таблицы, + пишет собственные проверки и показывает, какие ошибки они обнаруживают. +3. В работах на диагностику даны симптом и критерий восстановления. + Студент сам находит причину, выбирает исправление и подтверждает результат. + +Так помощь постепенно сокращается, а ответственность растет. +Заранее оставлять заглушки во всех учебных участках не требуется. +В частности, зависимость ODS от общего STG-батча объясняет +[готовый STG в текущей программе](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/docs/assignment/analyst_spec.md#почему-stg-слой-уже-реализован), +но позволяет временно разобрать его в отдельной работе. + +## Принято: прием справочника входит в обязательную программу + +Добавить лабораторную **«Восстановите прием справочника из источника»**. +Она закрывает практику подключения через PXF и загрузки полного снимка +в STG, которые сейчас даны готовыми. + +Предлагаемый объем: восстановить внешнюю таблицу для существующего +справочника Postgres, написать его загрузку в STG и проверить передачу +полей, ключей и меток батча. Студент должен различить повтор загрузки +в том же батче и получение нового снимка. Результат должен снова +участвовать в действующей цепочке ODS → DDS → DM. + +Конкретный справочник, состав удаляемых файлов, место в маршруте и проверки +еще предстоит выбрать. Кандидат — `airports`: рядом есть +[внешняя и внутренняя таблицы](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/sql/stg/airports_ddl.sql), +[загрузка снимка](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/sql/stg/airports_load.sql) и +[преобразование в ODS](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/sql/ods/airports_load.sql). + +## Покрытие обязательного цикла + +Оценка основана на текущем ТЗ и коде. Наличие готового примера или главы +для чтения учитывается отдельно от самостоятельной реализации. + +| Участок | Что студент делает сейчас | Что стоит добавить | +|---|---|---| +| PXF и снимок STG | Запускает готовую цепочку | Принятая лабораторная по приему справочника | +| Инкремент STG | Использует готовый отбор по дате источника | Самостоятельную загрузку новых данных и проверку границы отбора | +| Снимки ODS | Реализует `airplanes`, `seats` и их DQ | Сохранить задания; использовать их после знакомства с приемом данных | +| Инкремент ODS | Использует готовые загрузки | Обработку новых ключей и изменений уже полученных строк | +| Измерения DDS | Реализует SCD1 и SCD2 | Сохранить существующий блок | +| Факт DDS | Читает пример и запускает готовую сборку | Самостоятельную сборку факта с ключами измерений | +| Витрины DM | Реализует четыре витрины с разными способами пересчета | Сохранить существующий блок; сначала закрыть пробелы ниже DM | +| DDL и физическая организация | Получает готовые таблицы, типы и ключи распределения | Написать DDL одного объекта и проверить выбор распределения опытом; предложение раскрыто ниже | +| Airflow | Запускает готовые DAG; задачи уже подключены к SQL | Самостоятельное включение загрузок и проверок в DAG | +| DQ и повторяемость | Пишет `*_dq.sql`; для ODS проверяет повтор; пользуется `bookings_validate` | Обязательные опыты на обнаружение ошибки, идемпотентность и восстановление после сбоя | + +## Предложения по оставшимся пробелам + +Следующие изменения пока не утверждены как обязательные лабораторные. + +1. **Загрузите новые и измененные данные: STG → ODS.** Кандидат — + `bookings`: [прием в STG](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/sql/stg/bookings_load.sql) и + [обновление ODS](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/sql/ods/bookings_load.sql). Проверить первую + загрузку, следующую пачку, повтор и отсутствие новых данных. + Для изменения существующего ключа подготовить новую версию в STG: + текущий отбор источника по `book_date` сам по себе не подхватывает + исправления старых бронирований. Различие времени события и времени + загрузки — часть учебного результата. Разделение на две работы зависит + от объема самостоятельного SQL. +2. **Соберите факт продаж.** После измерений восстановить + [загрузку факта](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/sql/dds/fact_flight_sales_load.sql): сохранить + зерно `(ticket_no, flight_id)`, подобрать ключи измерений и версию + маршрута на дату рейса, обработать обновления и повторный запуск. + Проверить покрытие ключей, значения и отсутствие размножения строк. + Простого совпадения количества строк недостаточно. +3. **Организуйте загрузку в Airflow и восстановите ее после сбоя.** + Использовать уже написанный SQL, самостоятельно связать задачи загрузки + и DQ. На подготовленном входе вызвать сбой, определить состояние данных + и завершить обработку повторным запуском. Генератор управляется отдельно: + его повтор продвигает источник на новый день и меняет условия опыта. +4. **Проверьте физическую организацию таблицы в Greenplum.** Предлагается + включить в обязательный цикл компактный опыт: написать DDL, сравнить + два варианта распределения одних данных, посмотреть строки по сегментам + и планы одного запроса, обосновать выбор. Результат запроса должен + совпадать в обоих вариантах. Наличие нескольких сегментов и достаточный + для наблюдения объем нужно проверить при подготовке работы. Место опыта + еще не выбрано; кандидат — задание по факту. Подробную оптимизацию + можно развить в факультативах. + +## Предлагаемые переходы между работами + +Порядок обсуждения новых работ: прием справочника → инкремент STG/ODS → +сборка факта → оркестрация и восстановление. Между ними остаются +существующие задания на снимки ODS, измерения и витрины. Точное место +новых работ, включая опыт с распределением, еще обсуждается. + +Для встраивания в маршрут предлагаются следующие границы: + +| Новая работа | Состояние перед началом | Результат для продолжения | +|---|---|---| +| Прием справочника | Пройден быстрый старт, работает эталонная цепочка до `sales_report`; выбран участок для вычитания | Собственная загрузка получает новый снимок STG, который участвует в общем батче справочников и принимается ODS | +| Инкремент STG/ODS | Разобраны прием снимка и существующие задания ODS; подготовлены таблицы и входные пачки | Собственные загрузки дают ожидаемое текущее состояние ODS после всех проверочных случаев | +| Сборка факта | Реализованы и проверены измерения DDS | Факт построен собственным SQL, проверены ключи и значения; на нем можно выполнять задания DM | +| Оркестрация и восстановление | SQL выбранного участка реализован и проверен | DAG выполняет загрузку и DQ в нужном порядке; после подготовленного сбоя обработка завершается с ожидаемыми данными | + +Готовность оценивается по нужному этапу: на исходной `main` часть таблиц +еще является заданием, поэтому проход всех проверок будущих слоев +не может быть условием начала первой работы. Действующие особенности +запусков и состояния слоев описаны в [порядке выполнения DAG](https://git.dementev.space/ddmitry/airflow-greenplum/src/branch/main/docs/dag_execution_order.md). + +Предложения основаны на чтении исходников; воспроизводимость новых +сценариев на стенде еще не проверялась. + +## Как подготовить лабораторную + +Эти критерии общие для обязательных работ и факультативов. Перед написанием +инструкции определите: + +- **Навык:** рабочая ситуация, новое действие или решение DE и его отличие + от уже пройденных работ. +- **Вход:** необходимые задания, состояние таблиц и загрузок, подготовка + данных и способ воспроизвести ситуацию. +- **Самостоятельная часть:** что студент получает готовым, что пишет + или меняет сам и какие решения должен обосновать. +- **Результат:** что будет работать после задания и по каким наблюдениям + студент сможет это подтвердить. +- **Проверочные случаи:** конкретные данные или события, ожидаемый результат + каждого случая и способ обнаружить неверное решение. +- **Выход:** что сохраняется для следующей работы и как получить нужное + состояние стенда после опыта или перерыва. + +Для инкремента получение новых строк из источника и применение уже +полученных изменений в ODS проверяются отдельно. Для собственной DQ-проверки +нужны отказ на известной ошибке и успех после исправления. Сверка с готовой +реализацией подтверждает совпадение поведения; проверки по источнику +подтверждают полноту и бизнес-правила. + +Полная пересборка стенда допустима. Адресное восстановление требуется там, +где оно само является предметом работы. При пересборке инструкция должна +объяснять, как снова применить сохраненные файлы решения и получить +состояние для продолжения. + +Лабораторная готова к выдаче, когда все ее проверочные случаи пройдены +на стенде из описанного начального состояния, проверки обнаружили +предусмотренные ошибки, а заявленный выход позволяет продолжить маршрут. +Команды и результаты проверки сохраняются вместе с изменением задания. +Текстовая вычитка и проверка ссылок подтверждают только качество документа. + +## Основа для будущих факультативов + +Факультативы расширяют опыт за пределами обязательного набора. При генерации +кандидатов используйте общие критерии выше и указывайте, после каких +обязательных работ доступен каждый сюжет. + +Направления для последующей генерации: изменения схемы источника, +опоздавшие данные, история и пересчеты, углубленная оптимизация запросов +Greenplum, свежесть данных, разграничение доступа, новые способы приема. +Это исходные темы для отбора, а не утвержденный список заданий.