Merge pull request #1 from dementev-dev/feature/mkdocs-site
feat(site): MkDocs Material сайт с деплоем на GitHub Pages
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
name: Deploy MkDocs to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.x"
|
||||
|
||||
- run: pip install mkdocs-material==9.6.14 mkdocs-same-dir==0.1.3
|
||||
|
||||
- run: mkdocs build --strict
|
||||
|
||||
- uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: site/
|
||||
|
||||
deploy:
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
steps:
|
||||
- id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
@@ -1,3 +1,5 @@
|
||||
.env
|
||||
.idea
|
||||
.internal/
|
||||
site/
|
||||
tmp
|
||||
@@ -1,9 +1,12 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Project Structure & Module Organization
|
||||
- Root `README.md` describes the learning roadmap (RU).
|
||||
- Root `README.md` describes the learning roadmap (RU) and serves as the main page of the MkDocs site.
|
||||
- `dwh-modeling/` contains the article and demo DWH model; SQL lives in `dwh-modeling/sql` as ordered scripts `01_...sql`–`09_...sql` (07–09 are homework DDL, template and solution).
|
||||
- `postgres-bookings/` is a Dockerized PostgreSQL + demo “bookings” DB; start it first, then apply DWH scripts against the `demo` database.
|
||||
- `mkdocs.yml` — MkDocs Material config; `docs_dir: .` (repo root = site root). Excluded dirs: `project/`, `postgres-bookings/`, `.github/`, `.claude/`.
|
||||
- `.github/workflows/deploy-site.yml` — CI/CD: push to `main` → build → deploy to GitHub Pages.
|
||||
- `project/` — PRD and ADR (excluded from site).
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
- Start demo Postgres:
|
||||
@@ -20,6 +23,45 @@
|
||||
- SQL files: keep numeric prefixes (`01_`, `02_`, …) to reflect execution order and use descriptive suffixes like `ddl_*` / `dml_*`.
|
||||
- Shell: target `bash`, prefer simple, POSIX-friendly constructs; mirror the style of existing scripts in `postgres-bookings/`.
|
||||
|
||||
## Markdown Style (dual-compatible: GitHub + MkDocs Material)
|
||||
|
||||
All `.md` files MUST render correctly on both GitHub and the MkDocs Material site. Follow these rules:
|
||||
|
||||
**Headings:**
|
||||
- `README.md` (root): start from `##` (H2). Do NOT use `#` (H1) — MkDocs uses H1 as page title, multiple H1s break the right-sidebar TOC.
|
||||
- `dwh-modeling/*.md`: may use `#` (H1) since each file is a separate page on the site.
|
||||
|
||||
**Lists:**
|
||||
- Always leave a **blank line before the first list item** after a paragraph, heading, or any non-list text. Python-Markdown (MkDocs) requires this; GitHub tolerates its absence but blank lines don't hurt.
|
||||
- Use **4-space indentation** for nested lists (not 2-space). GitHub supports both, Python-Markdown requires 4.
|
||||
- Example:
|
||||
```markdown
|
||||
Some introductory text:
|
||||
|
||||
- Item one
|
||||
- Item two
|
||||
- Nested item (4 spaces)
|
||||
```
|
||||
|
||||
**Links:**
|
||||
- Internal links: always use **relative paths to `.md` files**: `[text](dwh-modeling/SCD.md)`. MkDocs resolves them automatically.
|
||||
- Anchor links: use lowercase slugs with single hyphens. Avoid em-dash `—` in headings (it produces `--` in MkDocs slugs vs `-` on GitHub). Use commas or colons instead.
|
||||
|
||||
**Special characters in headings:**
|
||||
- OK: colons `:`, commas `,`, parentheses `()`, guillemets `«»` — stripped equally by both platforms.
|
||||
- Avoid: em-dash `—`, en-dash `–` — slug behavior differs between GitHub and MkDocs.
|
||||
|
||||
## MkDocs Site Commands
|
||||
- Local preview (user starts, ask user to run via `!`):
|
||||
`uv run --with 'mkdocs-material==9.6.14' --with 'mkdocs-same-dir==0.1.3' mkdocs serve`
|
||||
- Build with strict validation (catches broken links/anchors):
|
||||
`uv run --with 'mkdocs-material==9.6.14' --with 'mkdocs-same-dir==0.1.3' mkdocs build --strict`
|
||||
- Visual check via Playwright (when `mkdocs serve` is running on port 8000):
|
||||
`npx playwright screenshot --viewport-size='1280,800' 'http://127.0.0.1:8000/#anchor' /path/to/screenshot.png`
|
||||
Then read the screenshot with the Read tool to inspect rendering. Use `--viewport-size='1280,2000'` for tall pages.
|
||||
- Kill stuck dev server: `lsof -ti :8000 | xargs kill`
|
||||
- Site URL: `https://dementev-dev.github.io/de-roadmap/`
|
||||
|
||||
## Testing Guidelines
|
||||
- There is no dedicated test framework; treat SQL scripts as executable documentation.
|
||||
- For `dwh-modeling/sql`, run scripts sequentially and rerun `04_validation.sql` after changes to ensure the demo model still loads and basic checks pass.
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
# О роадмапе
|
||||
## О роадмапе
|
||||
|
||||
Этот роадмап — конспект моих подходов к обучению Data Engineering.
|
||||
Он подойдёт тем, кто хочет:
|
||||
|
||||
- системно войти в профессию с нуля или близкого к нулю уровня;
|
||||
- закрыть пробелы в базе (SQL, Git, Python, DWH, Airflow, Greenplum);
|
||||
- подготовиться к собеседованиям и первым рабочим задачам.
|
||||
@@ -9,7 +10,7 @@
|
||||
Роадмап можно проходить самостоятельно или вместе со мной в формате менторства.
|
||||
Если хотите идти с поддержкой ментора — напишите в Telegram: [@dementev_dev](https://t.me/dementev_dev).
|
||||
|
||||
## Оглавление
|
||||
### Оглавление
|
||||
|
||||
- [Основные знания](#основные-знания) — Git, SQL, Python, методологии, Docker
|
||||
- [Практика и инструменты](#практика-и-инструменты) — Airflow, Greenplum, курсовая работа
|
||||
@@ -19,26 +20,29 @@
|
||||
- [Дополнительные материалы](#дополнительные-материалы)
|
||||
|
||||
Рекомендуемый способ использования:
|
||||
|
||||
- двигаться по разделам последовательно, не перепрыгивая через базу;
|
||||
- выполнять практику и домашки, а не только смотреть материалы;
|
||||
- возвращаться к разделам по мере появления реальных задач.
|
||||
|
||||
---
|
||||
|
||||
# Основные знания
|
||||
## Основные знания
|
||||
|
||||
[[к оглавлению]](#оглавление)
|
||||
|
||||
## Git и базовые инструменты
|
||||
### Git и базовые инструменты
|
||||
|
||||
### База по Git
|
||||
#### База по Git
|
||||
Что такое контроль версий, когда используется, ПОЧЕМУ и как мы в обучении будем использовать.
|
||||
Как создать репозиторий на GitHub, сохранять в нем изменения.
|
||||
|
||||
- [Что такое Git для Начинающих / GitHub за 30 минут / Git Уроки - Youtube](https://www.youtube.com/watch?v=VJm_AjiTEEc)
|
||||
- [Git: Конфликты для Начинающих // Git Cherry Pick, Git Revert, Git Reset - Youtube](https://www.youtube.com/watch?v=F7FnnfnB9YY)
|
||||
- Книга [Pro Git](https://git-scm.com/book/ru/v2) - читать главу 1
|
||||
|
||||
### Основы Markdown
|
||||
#### Основы Markdown
|
||||
|
||||
- [Язык Markdown и файл README | Git и GitHub для начинающих - Youtube](https://www.youtube.com/watch?v=8lEDTrr-G4U)
|
||||
- [Markdown и его возможности: простой способ оформления текста](https://kurshub.ru/journal/blog/markdown-chto-eto/)
|
||||
- [Синтаксис Markdown: подробная шпаргалка для веб-разработчиков / Skillbox Media](https://skillbox.ru/media/code/yazyk-razmetki-markdown-shpargalka-po-sintaksisu-s-primerami/)
|
||||
@@ -46,14 +50,15 @@
|
||||
Домашки по остальным темам тренируемся делать в Git, там же пишем документацию.
|
||||
|
||||
**Когда блок Git и базовые инструменты считаем пройденным:**
|
||||
|
||||
- вы уверенно создаёте репозиторий, коммитите изменения и отправляете их на GitHub;
|
||||
- имеете представление о работе с ветками: создание, переключение, что такое merge/PR и разруливание простых конфликтов;
|
||||
- оформляете базовую документацию в Markdown (README, заголовки, списки, ссылки, кодовые блоки).
|
||||
|
||||
## Базы данных: SQL и моделирование данных
|
||||
### Базы данных: SQL и моделирование данных
|
||||
|
||||
SQL и моделирование данных специально идут рядом: сначала учимся уверенно извлекать данные запросами, затем — понимать и проектировать структуру данных, чтобы ETL/витрины были осмысленными.
|
||||
### База по SQL
|
||||
#### База по SQL
|
||||
Книга: [PostgreSQL. Основы языка SQL](https://postgrespro.ru/education/books/sqlprimer) - Глава 1 "Введение в базы данных и SQL" + ДЗ
|
||||
|
||||
Бесплатный тренажер: [Интерактивный тренажер по SQL – Stepik](https://stepik.org/course/63054/promo)
|
||||
@@ -65,7 +70,7 @@ SQL и моделирование данных специально идут р
|
||||
|
||||
Для дальнейшей тренировки и поддержания уровня можно использовать [Database - LeetCode](https://leetcode.com/problem-list/database/). Хорошая подборка задачек: [SQL 50 - Study Plan - LeetCode](https://leetcode.com/studyplan/top-sql-50/)
|
||||
|
||||
### Повышение знаний SQL
|
||||
#### Повышение знаний SQL
|
||||
|
||||
Смотрим курс от Postgres Pro [DEV1](https://postgrespro.ru/education/courses/DEV1)
|
||||
Темы - от "Введение" до "SQL" включительно, "Управление доступом", "Резервное копирование". Для лучшего усваивания материала проделываем все примеры и домашние задания из конспектов лекция.
|
||||
@@ -74,6 +79,7 @@ SQL и моделирование данных специально идут р
|
||||
Для развития навыков инженера будет полезно лабораторные работы делать не в виртуальной машине, а в docker контейнере. Предложенный (не обязательный) вариант - в каталоге `postgres-bookings` репозитория.
|
||||
|
||||
Для дальнейшего закрепления материала - читаем книгу [PostgreSQL. Основы языка SQL](https://postgrespro.ru/education/books/sqlprimer)
|
||||
|
||||
- Глава 8 - Индексы + ДЗ
|
||||
- Глава 9 - Транзакции
|
||||
- Глава 10 - Повышение производительности + ДЗ
|
||||
@@ -81,9 +87,10 @@ SQL и моделирование данных специально идут р
|
||||
Вопросы оптимизации запросов хорошо описаны в курсе [QPT](https://postgrespro.ru/education/courses/QPT) от Postgres Pro. Полученные навыки применимы для работы в том числе с Greenplum, и частично, другими БД.
|
||||
На момент написания, видеолекции были доступны только для старой версии Postgres 13, но ее вполне достаточно.
|
||||
|
||||
### Моделирование данных
|
||||
#### Моделирование данных
|
||||
Понимание того, **как устроены данные и зачем они нужны**, — ключ к качественным ETL-процессам.
|
||||
Мы кратко разбираем:
|
||||
|
||||
- Основные подходы: нормализованные (3NF) vs денормализованные (звезда, снежинка)
|
||||
- Что такое staging, marts, слои raw / clean / business
|
||||
- Как проектировать таблицы под конкретные сценарии использования
|
||||
@@ -91,6 +98,7 @@ SQL и моделирование данных специально идут р
|
||||
Цель — не стать архитектором, а **уметь читать и объяснять структуру данных**, чтобы писать осмысленные запросы и трансформации.
|
||||
|
||||
Материалы (включая демо DWH-модель из этого репозитория):
|
||||
|
||||
- Мартин Клеппман — «Высоконагруженные приложения» - Глава 2: Модели данных и языки запросов. - Для понимания, чем реляционная модель (SQL) отличается от документной (NoSQL) и графовой, и почему для аналитики мы всё ещё любим таблицы
|
||||
(Важно: не перепутайте главу 2 с Частью 2 про распределенные данные!).
|
||||
- [Яндекс Практикум: что такое нормализация, простыми словами (для самых начинающих)](https://practicum.yandex.ru/blog/chto-takoe-normalizaciya-dannyh/)
|
||||
@@ -100,99 +108,101 @@ SQL и моделирование данных специально идут р
|
||||
- (Опционально) Ральф Кимбалл — «Инструментарий хранения и анализа данных» (The Data Warehouse Toolkit) - первые 3 главы
|
||||
- Практика по моделированию статусов клиента: [домашка STG → ODS → DDS → DM](dwh-modeling/Homework_Customer_Status_DDS_DM.md)
|
||||
- Еще про Data Vault:
|
||||
- Конспект и примеры из этого репозитория: [DataVault.md](dwh-modeling/DataVault.md)
|
||||
- [DataVault за 10 минут - Youtube](https://www.youtube.com/watch?v=9oQs_wJ045I)
|
||||
- Статья [«Что такое Data Vault: моделирование КХД для архитектора Big Data»](https://bigdataschool.ru/blog/what-is-data-vault/) — обзор, плюсы/минусы, контекст применения.
|
||||
- [Гибкие методологии проектирования Data Vault и Anchor Modeling | Евгений Ермаков | karpov.courses](https://www.youtube.com/watch?v=fNGIOb8SJvU)
|
||||
- Лекция в рамках курса по DWH: именно [«Основы Data Vault, создаем первую модель»](https://www.youtube.com/watch?v=65b99XCuiR4) — хороший формат: теория + пример.
|
||||
- Доклад - практический пример: [Денис Лукьянов — Data Vault 2.0. Когда внедрять, проблемы применения при построении DWH на Greenplum](https://www.youtube.com/watch?v=oGwQbeP5iss)
|
||||
- Конспект и примеры из этого репозитория: [DataVault.md](dwh-modeling/DataVault.md)
|
||||
- [DataVault за 10 минут - Youtube](https://www.youtube.com/watch?v=9oQs_wJ045I)
|
||||
- Статья [«Что такое Data Vault: моделирование КХД для архитектора Big Data»](https://bigdataschool.ru/blog/what-is-data-vault/) — обзор, плюсы/минусы, контекст применения.
|
||||
- [Гибкие методологии проектирования Data Vault и Anchor Modeling | Евгений Ермаков | karpov.courses](https://www.youtube.com/watch?v=fNGIOb8SJvU)
|
||||
- Лекция в рамках курса по DWH: именно [«Основы Data Vault, создаем первую модель»](https://www.youtube.com/watch?v=65b99XCuiR4) — хороший формат: теория + пример.
|
||||
- Доклад - практический пример: [Денис Лукьянов — Data Vault 2.0. Когда внедрять, проблемы применения при построении DWH на Greenplum](https://www.youtube.com/watch?v=oGwQbeP5iss)
|
||||
- Хорошее общее введение в модели данных дано в статье и докладе от Yandex: [Как мы внедрили свою модель хранения данных — highly Normalized hybrid Model. Доклад Яндекса](https://habr.com/ru/companies/yandex/articles/557140/)
|
||||
|
||||
**Когда блок «Базы данных» считаем пройденным:**
|
||||
|
||||
- вы уверенно пишете запросы с JOIN, агрегатами, подзапросами и CTE;
|
||||
- можете подробно объяснить план запроса в Postgres, понимаете где планировщик отработал корректно, а где - есть возможность улучшить;
|
||||
- можете объяснить простую модель данных (3NF/звезда) и прочитать схему DWH;
|
||||
- решаете типовые задачи уровня SQL live-coding без долгих пауз.
|
||||
|
||||
|
||||
## Python
|
||||
### Python
|
||||
|
||||
- Если совсем не знакомы с Python, начинаем с курса ["Поколение Python": курс для начинающих – Stepik](https://stepik.org/course/58852/info)
|
||||
- Изучаем глубже и "оттачиваем" live coding: ["Поколение Python": курс для продвинутых – Stepik](https://stepik.org/course/68343/info)
|
||||
- Продолжение "базы", спрашиваемой на собеседованиях, по Python: ["Поколение Python": курс для профессионалов](https://stepik.org/course/82541/promo). Курс очень полезный, но платный. Вместо него можно почитать "продвинутые" темы дальше.
|
||||
- "Продвинутые" темы:
|
||||
- [Полезные функции](https://pyneng.readthedocs.io/ru/latest/book/10_useful_functions/index.html)
|
||||
- [Работа с файлами в формате CSV, JSON, YAML](https://pyneng.readthedocs.io/ru/latest/book/17_serialization/index.html)
|
||||
- [Итераторы, итерируемые объекты и генераторы](https://pyneng.readthedocs.io/ru/latest/book/13_iterator_generator/index.html)
|
||||
- [Декораторы Python: пошаговое руководство](https://habr.com/ru/companies/otus/articles/727590/)
|
||||
- Работа с датой/временем: https://django.fun/docs/python/3.10/library/datetime/
|
||||
- [Полезные функции](https://pyneng.readthedocs.io/ru/latest/book/10_useful_functions/index.html)
|
||||
- [Работа с файлами в формате CSV, JSON, YAML](https://pyneng.readthedocs.io/ru/latest/book/17_serialization/index.html)
|
||||
- [Итераторы, итерируемые объекты и генераторы](https://pyneng.readthedocs.io/ru/latest/book/13_iterator_generator/index.html)
|
||||
- [Декораторы Python: пошаговое руководство](https://habr.com/ru/companies/otus/articles/727590/)
|
||||
- Работа с датой/временем: https://django.fun/docs/python/3.10/library/datetime/
|
||||
- ООП
|
||||
- [Tproger: «ООП простыми словами»](https://tproger.ru/experts/oop-in-simple-words)
|
||||
- Введение в [ООП](https://metanit.com/python/tutorial/7.1.php)
|
||||
- [Яндекс Учебник: «Объектная модель Python: классы, поля и методы»](https://education.yandex.ru/handbook/python/article/obuektnaya-model-python-klassy-polya-i-metody)
|
||||
- [Real Python: OOP in Python (tutorial)](https://realpython.com/python3-object-oriented-programming/)
|
||||
- [Tproger: «ООП простыми словами»](https://tproger.ru/experts/oop-in-simple-words)
|
||||
- Введение в [ООП](https://metanit.com/python/tutorial/7.1.php)
|
||||
- [Яндекс Учебник: «Объектная модель Python: классы, поля и методы»](https://education.yandex.ru/handbook/python/article/obuektnaya-model-python-klassy-polya-i-metody)
|
||||
- [Real Python: OOP in Python (tutorial)](https://realpython.com/python3-object-oriented-programming/)
|
||||
- Виртуальные окружения (venv) — изолируют зависимости проекта; настройте перед установкой Jupyter и библиотек
|
||||
- [Habr: как настроить виртуальное окружение](https://habr.com/ru/articles/889670/)
|
||||
- [SkillFactory: Виртуальные окружения в Python](https://blog.skillfactory.ru/venv-virtualnoe-okruzhenie-v-python/)
|
||||
- [Habr: как настроить виртуальное окружение](https://habr.com/ru/articles/889670/)
|
||||
- [SkillFactory: Виртуальные окружения в Python](https://blog.skillfactory.ru/venv-virtualnoe-okruzhenie-v-python/)
|
||||
- Jupyter Lab
|
||||
- [Блог Практикума: «Что такое Jupyter Notebook: как установить и открыть»](https://practicum.yandex.ru/blog/chto-takoe-jupyter-notebook/)
|
||||
- Готовая реализация Jupyter Lab, включающая в себя Spark, в Docker: https://github.com/dementev-dev/jupyter-spark-docker
|
||||
- [Блог Практикума: «Что такое Jupyter Notebook: как установить и открыть»](https://practicum.yandex.ru/blog/chto-takoe-jupyter-notebook/)
|
||||
- Готовая реализация Jupyter Lab, включающая в себя Spark, в Docker: https://github.com/dementev-dev/jupyter-spark-docker
|
||||
- Pandas
|
||||
- [GeeksforGeeks: “Why Pandas is Used in Python”](https://www.geeksforgeeks.org/pandas/why-pandas-is-used-in-python/)
|
||||
- [Skillbox: «Для чего нужна библиотека Pandas»](https://skillbox.ru/media/code/rabotaem-s-pandas-osnovnye-ponyatiya-i-realnye-dannye/)
|
||||
- [Official: “10 minutes to pandas”](https://pandas.pydata.org/docs/user_guide/10min.html)
|
||||
- [Хабр (RUVDS): «Моя шпаргалка по pandas»](https://habr.com/ru/companies/ruvds/articles/494720/)
|
||||
- [Tproger: «Наглядная шпаргалка по операциям с DataFrame»](https://tproger.ru/articles/pandas-data-wrangling-cheatsheet)
|
||||
- [GeeksforGeeks: “Why Pandas is Used in Python”](https://www.geeksforgeeks.org/pandas/why-pandas-is-used-in-python/)
|
||||
- [Skillbox: «Для чего нужна библиотека Pandas»](https://skillbox.ru/media/code/rabotaem-s-pandas-osnovnye-ponyatiya-i-realnye-dannye/)
|
||||
- [Official: “10 minutes to pandas”](https://pandas.pydata.org/docs/user_guide/10min.html)
|
||||
- [Хабр (RUVDS): «Моя шпаргалка по pandas»](https://habr.com/ru/companies/ruvds/articles/494720/)
|
||||
- [Tproger: «Наглядная шпаргалка по операциям с DataFrame»](https://tproger.ru/articles/pandas-data-wrangling-cheatsheet)
|
||||
|
||||
Полезно, но дороговато и не обязательно: хорошее комбо SQL + Python — ["Поколение Python": профи + ООП + SQL – Stepik](https://stepik.org/course/233341/promo?search=7181036958)
|
||||
|
||||
Цель — уверенно решать простые задачи на Python в формате live-coding; дальше эти навыки пригодятся для создания DAG Airflow.
|
||||
|
||||
**Когда блок Python считаем пройденным:**
|
||||
|
||||
- вы без подсказок пишете небольшие скрипты с циклами, функциями, обработкой ошибок и работой с коллекциями;
|
||||
- умеете читать и модифицировать чужой код, в том числе с использованием pandas и DataFrame;
|
||||
- уверенно проходите простой live-coding по Python для DE: прочитать CSV/JSON, отфильтровать, сгруппировать данные и посчитать агрегаты.
|
||||
- можете отвечать как на простые вопросы собеседований (циклы, списки, словари), так и продвинутые (итераторы, декораторы, управление памятью, базовые понятия ООП)
|
||||
|
||||
## Методологии разработки
|
||||
### Методологии разработки
|
||||
|
||||
> **Зачем это разработчику?**
|
||||
> 1. **Работа в команде.** Вам нужно понимать «правила игры». Почему задачи двигаются именно так? Зачем мы встречаемся каждое утро на 15 минут? Почему нельзя просто взять задачу из середины списка?
|
||||
> 2. **Собеседование и «легенда».** Когда вас спросят: «Как строилась работа в вашей прошлой команде?», вы должны ответить грамотно. Использование правильной терминологии (спринты, груминг, ретроспектива, WIP-лимиты) — это маркер профессионализма. Это показывает, что вы не просто писали код в вакууме, а были частью налаженного процесса.
|
||||
|
||||
### 1. Основы и сравнение подходов
|
||||
#### 1. Основы и сравнение подходов
|
||||
Для начала нужно понять глобальную разницу между жестким планированием (Waterfall) и гибкой разработкой (Agile).
|
||||
|
||||
- [Waterfall или Agile, Scrum или Kanban: что выбрать](https://habr.com/ru/companies/kaiten/articles/906006/) — *Базовая статья. Читать внимательно, закрывает вопросы и по Waterfall, и по выбору пути.*
|
||||
- [Agile, Scrum, Kanban - обзор, отличия, мифы](https://www.youtube.com/watch?v=LhA5aWjHTJw) — *Видео для закрепления. Помогает разложить кашу в голове по полочкам.*
|
||||
|
||||
### 2. Agile: Философия гибкости
|
||||
#### 2. Agile: Философия гибкости
|
||||
Agile — это не метод, а философия. Scrum и Kanban — это инструменты этой философии.
|
||||
|
||||
- [Scrum vs Kanban: отличия и разница Agile методов](https://kaiten.ru/blog/kanban-vs-scrum/) — *Сравнение двух главных фреймворков. Важно понять, где заканчивается один и начинается другой.*
|
||||
|
||||
### 3. Scrum (Скрам)
|
||||
#### 3. Scrum (Скрам)
|
||||
Используется, когда мы создаем продукт и работаем спринтами (циклами).
|
||||
*Часто встречается в продуктовых командах, где DE работает в связке с Backend/Frontend.*
|
||||
|
||||
- [Методология Scrum: принципы, ценности, этапы](https://kaiten.ru/blog/chto-takoie-scrum-i-kak-ispolzovat/)
|
||||
|
||||
### 4. Kanban (Канбан)
|
||||
#### 4. Kanban (Канбан)
|
||||
Используется для управления потоком задач и поддержки.
|
||||
*Наиболее популярен в Data Engineering и DevOps, так как данные поступают непрерывно, и их сложно «запереть» в двухнедельный спринт.*
|
||||
|
||||
- [Канбан: метод, инструменты и принципы](https://kaiten.ru/blog/cto-takoe-kanban/)
|
||||
|
||||
### Практика: Как это выглядит в жизни
|
||||
#### Практика: Как это выглядит в жизни
|
||||
|
||||
Теория — это хорошо, но на работе вы увидите конкретный интерфейс (Jira или Yandex Tracker). Важно понимать, куда нажимать и как двигать задачи.
|
||||
|
||||
#### 1. Jira (Мировой стандарт)
|
||||
##### 1. Jira (Мировой стандарт)
|
||||
Самый популярный инструмент. Скорее всего, вы столкнетесь именно с ним.
|
||||
* [Как работать с Jira на реальных проектах](https://www.youtube.com/watch?v=oPgm-fsHVfM) (15 мин) — *Отличное видео, где показывают базу: как создать задачу, как перетащить её по доске (Kanban) и что писать в комментариях. Смотреть с 04:00, где начинается практика.*
|
||||
* [Создание и настройка Scrum-досок в JIRA](https://www.youtube.com/watch?v=u-u8NRyApUs) — *Если хотите увидеть, как выглядит Спринт и Бэклог изнутри.*
|
||||
|
||||
#### 2. Yandex Tracker (Российский стандарт)
|
||||
##### 2. Yandex Tracker (Российский стандарт)
|
||||
Активно внедряется в крупных компаниях РФ. Логика та же, но интерфейс другой.
|
||||
* [Начало работы в Яндекс.Трекере](https://www.youtube.com/watch?v=pdlYiijjn70) (3 мин) — *Супер-короткий официальный гайд. За 3 минуты показывают всё: очереди, доски, карточки.*
|
||||
* [Настройка процесса разработки в Tracker](https://www.youtube.com/watch?v=EdKlYJR2ph0&t=397s)** (c 06:37) — *Более глубокий разбор: как выглядит очередь задач разработчика и жизненный цикл тикета.*
|
||||
@@ -201,100 +211,113 @@ Agile — это не метод, а философия. Scrum и Kanban — э
|
||||
> Не бойтесь кнопок. Главное правило любого трекера: **«Взял задачу в работу — переведи статус в In Progress»**. Это сигнал команде, что вы заняты и вас лучше не отвлекать.
|
||||
|
||||
**Когда блок «Методологии разработки» считаем пройденным:**
|
||||
|
||||
- вы в общих чертах можете объяснить разницу Waterfall vs Agile и Scrum vs Kanban;
|
||||
- знаете основные мероприятия Scrum (planning / daily / review / retro) и что от вас ожидается на каждом;
|
||||
- умеете работать с трекером (Jira/Tracker): создать/уточнить задачу, взять в работу, корректно двигать статусы и оставлять понятные комментарии;
|
||||
- умеете своевременно сообщать о блокерах и уточнять требования, если задача «не бьётся» или в ней не хватает входных данных.
|
||||
|
||||
## Технические навыки
|
||||
### Технические навыки
|
||||
|
||||
#### Продвинутый Git
|
||||
|
||||
### Продвинутый Git
|
||||
- Сжатый, но емкий видеогайд: [GIT, GitHub, GitLab. Полный АКТУАЛЬНЫЙ гайд ЗА ПОЛТОРА ЧАСА. Без этого выгонят с работы - Youtube](https://www.youtube.com/watch?v=0Y-fneoUIO8)
|
||||
- Книга: [Pro Git](https://git-scm.com/book/ru/v2) - главы
|
||||
- 2 Основы Git
|
||||
- 3 Ветвление в Git
|
||||
- 5 Распределённый Git
|
||||
- 6 GitHub
|
||||
- 2 Основы Git
|
||||
- 3 Ветвление в Git
|
||||
- 5 Распределённый Git
|
||||
- 6 GitHub
|
||||
- [Курс работы с Git и GitLab - ЭФКО ЦПР | YouTube плейлист](https://www.youtube.com/playlist?list=PLbf8m52BvqlFlblJqQKPuEU26pwgqe7zK). Настоятельно рекомендую проделать за лектором все те действия что он показывает.
|
||||
|
||||
Целевой уровень знания - понимание процесса GitFlow. Как создать ветку, влить изменения в другие ветки. Понимание, зачем.
|
||||
На собесах обычно не спрашивают, но нужно в работе.
|
||||
|
||||
### Docker
|
||||
#### Docker
|
||||
|
||||
- Курс https://karpov.courses/docker
|
||||
|
||||
Основное предназначение для нас - учебные стенды, где мы разбираем и тренируемся с разными технологиями. На работе - иногда пригождается. На собесах спрашивают редко.
|
||||
|
||||
### Запись встреч
|
||||
#### Запись встреч
|
||||
OBS Studio
|
||||
|
||||
- Руководство по OBS: [OBS Studio - Настройка ОБС для Записи Игр и Стрима | Настройка Микрофона в Обс и т.д - Youtube](https://www.youtube.com/watch?v=bj8VEphZ65U)
|
||||
- [Как записывать собеседования](https://docs.google.com/document/d/1qd8uRYlAaZp9c5zpvCVBOvYQCEukGHI9PEPjnjahI1k/)
|
||||
|
||||
**Когда блок технических навыков считаем пройденным:**
|
||||
|
||||
- вы понимаете базовый GitFlow: как организована работа с ветками в команде и как ваши коммиты попадают в прод;
|
||||
- используете Docker для учебных стендов: запускаете контейнеры, смотрите логи и при необходимости перезапускаете сервисы;
|
||||
- при необходимости умеете настроить запись экрана/созвонов, чтобы сохранять материалы обучения.
|
||||
|
||||
---
|
||||
|
||||
# Практика и инструменты
|
||||
## Практика и инструменты
|
||||
|
||||
[[к оглавлению]](#оглавление)
|
||||
|
||||
## Airflow
|
||||
### Airflow
|
||||
Apache Airflow — инструмент для оркестрации ETL-процессов.
|
||||
|
||||
Мы используем его для:
|
||||
|
||||
- планирования задач,
|
||||
- отслеживания зависимостей между шагами,
|
||||
- визуализации статуса выполнения.
|
||||
|
||||
Материалы:
|
||||
|
||||
- [Учебник по Airflow](https://github.com/dementev-dev/airflow-manual)
|
||||
|
||||
**Когда блок Airflow считаем пройденным:**
|
||||
|
||||
- вы можете объяснить, что такое DAG, задачи, операторы и сенсоры, и как между ними задаются зависимости;
|
||||
- на базе учебного стенда подготавливаете, отлаживаете и запускаете свои DAG'и с расписанием и несколькими шагами (например, загрузка данных и последующие трансформации);
|
||||
- уверенно смотрите логи, находите место падения и понимаете, как перезапустить задачу.
|
||||
|
||||
## Greenplum
|
||||
### Greenplum
|
||||
Разбираем, чем Greenplum отличается от PostgreSQL и зачем нужны MPP-хранилища.
|
||||
|
||||
### Фундаментальная теория
|
||||
#### Фундаментальная теория
|
||||
Прежде чем нажимать кнопки, нужно понять "физику" больших данных. Почему обычный Postgres начинает тормозить?
|
||||
|
||||
- Мартин Клеппман, "Высоконагруженные приложения":
|
||||
- Глава 1. Надежность, масштабируемость. (Разбираемся, чем вертикальное масштабирование отличается от горизонтального).
|
||||
- Глава 3 (только конец главы). Читаем разделы:
|
||||
- Глава 1. Надежность, масштабируемость. (Разбираемся, чем вертикальное масштабирование отличается от горизонтального).
|
||||
- Глава 3 (только конец главы). Читаем разделы:
|
||||
- «Обработка транзакций или аналитика?» (OLTP or OLAP?) — ключевое различие нагрузок.
|
||||
- «Хранение по столбцам» — почему аналитика требует другого способа записи данных на диск.
|
||||
- Зачем: Это объясняет, почему Greenplum устроен именно так. Без этого вы будете пытаться работать с ним как с обычным Postgres.
|
||||
|
||||
### Знакомство с Greenplum
|
||||
#### Знакомство с Greenplum
|
||||
Теперь, понимая теорию, смотрим, как это реализовано в конкретном инструменте.
|
||||
|
||||
- Простое введение: [Greenplum | Что это такое и как оно работает? - Youtube](https://www.youtube.com/watch?v=rLG9Z_HcKPY)
|
||||
- [Визуализатор распределения Greenplum](https://gpskew.rzvde.pro/)
|
||||
|
||||
**Курс Yandex по Greenplum** — основной учебный курс, рекомендуется пройти целиком:
|
||||
|
||||
- [Бесплатный курс Yandex Cloud по Greenplum](https://yandex.cloud/ru/training/greenplum)
|
||||
- Практику по курсу удобно делать на стенде [airflow-dwh-gp-lab](https://github.com/dementev-dev/airflow-greenplum) — `make up` поднимает рабочий Greenplum с PXF, не нужен облачный кластер.
|
||||
- Стенд покрывает основные темы курса: типы таблиц (heap / appendonly), политики дистрибуции, сжатие, PXF, анализ планов выполнения (`EXPLAIN`).
|
||||
- Единственное ограничение: cloud-специфичные темы (тема 2 курса — развёртывание в Yandex Cloud) на локальном стенде не покрыты.
|
||||
|
||||
Дополнительно:
|
||||
|
||||
- [Учебный курс по Greenplum от datafinder](https://datafinder.ru/products/uchebnyy-kurs-po-greenplum) — отдельные главы для углубления.
|
||||
|
||||
**Когда блок Greenplum считаем пройденным:**
|
||||
|
||||
- вы понимаете, как данные распределяются по сегментам, что такое skew и как его увидеть;
|
||||
- на базе стенда `airflow-dwh-gp-lab` можете загружать и выгружать данные в Greenplum, выполнять запросы и разбирать планы выполнения (`EXPLAIN`);
|
||||
- можете объяснить, в чём практическая разница между MPP-хранилищем и одиночным Postgres на уровне типичных задач DE и собеседований.
|
||||
|
||||
## Курсовая работа
|
||||
### Курсовая работа
|
||||
Курсовая работа — важный майлстоун роадмапа: ваш первый end-to-end data-проект. После неё у вас есть ключевые технические навыки для старта карьеры в Data Engineering.
|
||||
|
||||
Курсовая выполняется на том же стенде [airflow-dwh-gp-lab](https://github.com/dementev-dev/airflow-greenplum), который вы уже использовали для практики по Greenplum.
|
||||
|
||||
**Что внутри:**
|
||||
|
||||
- Стенд содержит DWH с реализованным эталонным срезом (STG → ODS → DDS → DM) — это ваш образец для подражания.
|
||||
- Задача — довести DWH до полного, реализовав недостающие загрузки по аналогии с эталоном.
|
||||
- Есть готовый план от аналитика (ТЗ с маппингами и бизнес-правилами) — не нужно придумывать, что делать.
|
||||
@@ -302,11 +325,12 @@ Apache Airflow — инструмент для оркестрации ETL-про
|
||||
- Ветка `main` — рабочая (с заготовками для реализации), ветка `solution` — эталон для сверки.
|
||||
|
||||
**Когда блок курсовой работы считаем пройденным:**
|
||||
|
||||
- все загрузки реализованы, DWH заполняется полностью (STG → ODS → DDS → DM);
|
||||
- автоматическая проверка (валидационный DAG) проходит без ошибок;
|
||||
- вы можете на собеседовании за 5–10 минут рассказать архитектуру проекта, его цели и показать ключевые части кода.
|
||||
|
||||
## Понятие сложности алгоритмов
|
||||
### Понятие сложности алгоритмов
|
||||
В Data Engineering редко требуется писать сложные алгоритмы, но важно понимать, как оценивать эффективность кода:
|
||||
|
||||
- в SQL — через объём сканируемых данных, типы JOIN’ов, использование индексов;
|
||||
@@ -316,15 +340,16 @@ Apache Airflow — инструмент для оркестрации ETL-про
|
||||
|
||||
---
|
||||
|
||||
# Карьера и менторство
|
||||
## Карьера и менторство
|
||||
|
||||
[[к оглавлению]](#оглавление)
|
||||
|
||||
## Менторство по этому роадмапу
|
||||
### Менторство по этому роадмапу
|
||||
|
||||
Если вы нашли этот роадмап в интернете и хотите пройти его не в одиночку, а с поддержкой ментора, можно присоединиться ко мне.
|
||||
|
||||
**Что даёт менторство:**
|
||||
|
||||
- структурный план прохождения роадмапа под вашу ситуацию;
|
||||
- разбор вопросов по SQL / DWH / Airflow и другим темам из этого документа;
|
||||
- разбор домашних заданий и код-ревью;
|
||||
@@ -335,36 +360,37 @@ Apache Airflow — инструмент для оркестрации ETL-про
|
||||
Просто напишите мне в Telegram: [@dementev_dev](https://t.me/dementev_dev)
|
||||
со словами «Хочу пройти роадмап с ментором» — дальше всё обсудим.
|
||||
|
||||
## Подготовка к собеседованиям
|
||||
### Подготовка к собеседованиям
|
||||
Цель блока — сформировать «опыт от 2 лет» и уметь корректно его показать в резюме и на собеседовании.
|
||||
|
||||
### Помощь в подготовке резюме
|
||||
#### Помощь в подготовке резюме
|
||||
|
||||
- Видео от ОМ по составлению резюме
|
||||
- [Как накрутить опыт в резюме | «Ультимативный гайд» @digital_ninja](https://www.youtube.com/watch?v=EPuogJuYsvY)
|
||||
- [Как писать резюме, чтобы его читали - доклад - Boosty](https://boosty.to/m0rtymerr/posts/71b02a6b-8116-466a-b945-b2ed793abd8f)
|
||||
- [Как грамотно продать себя на собеседовании / Созвон сообщества - Boosty](https://boosty.to/m0rtymerr/posts/7289cd23-60c6-4010-bb1c-a5b28dac399a)
|
||||
- [Как накрутить опыт в резюме | «Ультимативный гайд» @digital_ninja](https://www.youtube.com/watch?v=EPuogJuYsvY)
|
||||
- [Как писать резюме, чтобы его читали - доклад - Boosty](https://boosty.to/m0rtymerr/posts/71b02a6b-8116-466a-b945-b2ed793abd8f)
|
||||
- [Как грамотно продать себя на собеседовании / Созвон сообщества - Boosty](https://boosty.to/m0rtymerr/posts/7289cd23-60c6-4010-bb1c-a5b28dac399a)
|
||||
- Практика: совместная работа над резюме — ментор помогает переработать опыт, сформировать убедительную карьерную историю и подготовиться к вопросам по ней.
|
||||
|
||||
### Поиск работы и собеседования
|
||||
#### Поиск работы и собеседования
|
||||
|
||||
- [Как подтвердить опыт без трудовой / Хабр против работяг](https://www.youtube.com/watch?v=GHqABzA1zi8)
|
||||
- Видео по прохождению собеседований из сообщества ОМ — *в подготовке*
|
||||
- Практика: мок-собеседования с ментором — тренировка ответов, разбор слабых мест, психологическая подготовка к реальным интервью.
|
||||
|
||||
### Помощь с прохождением испытательного срока
|
||||
#### Помощь с прохождением испытательного срока
|
||||
|
||||
- [Как успешно пройти испытательный срок в IT | «Ультимативный гайд» c @digital_ninja - Youtube](https://www.youtube.com/watch?v=r1lWP5rYVdk)
|
||||
- [Испытательный срок - доклад - Boosty](https://boosty.to/m0rtymerr/posts/40e7f17e-022b-495c-8d03-dabbe4383b8e)
|
||||
|
||||
**Когда блок подготовки к собеседованиям считаем пройденным:**
|
||||
|
||||
- у вас есть актуальное резюме под DE с понятными примерами проектов вместо «пустого» опыта;
|
||||
- вы умеете искать и отбирать вакансии на HH и Habr Карьера, адаптируя отклики под конкретную позицию;
|
||||
- вы прошли хотя бы пару мок-собеседований, получили обратную связь и по результатам доработали резюме и стратегию поиска.
|
||||
|
||||
---
|
||||
|
||||
# Расширенные навыки
|
||||
## Расширенные навыки
|
||||
Эти темы выходят за рамки базового минимума для старта в Data Engineering, но дают более полное представление об экосистеме.
|
||||
Их цель — понимать, зачем и когда используется тот или иной инструмент, а не осваивать его на уровне администратора или DevOps-инженера.
|
||||
|
||||
@@ -380,48 +406,53 @@ Apache Airflow — инструмент для оркестрации ETL-про
|
||||
Практика ограничивается минимальным рабочим примером (запуск в Docker, простой пайплайн или SQL-модель).
|
||||
Этого достаточно, чтобы уверенно говорить об инструменте на собеседовании и понимать его место в архитектуре — а всё остальное при необходимости осваивается уже на проекте.
|
||||
|
||||
## ClickHouse
|
||||
### ClickHouse
|
||||
Бесплатный курс https://yandex.cloud/ru/training/clickhouse
|
||||
Платный курс [ClickHouse для аналитика – Stepik](https://stepik.org/course/100210/promo?search=6551441002)
|
||||
|
||||
## Streaming (NiFi + Kafka)
|
||||
### Streaming (NiFi + Kafka)
|
||||
NiFi — визуальный конструктор потоков данных, Kafka — распределённая очередь сообщений. Вместе они закрывают типичный сценарий: принять данные, буферизовать, доставить в хранилище.
|
||||
|
||||
Материалы:
|
||||
|
||||
- [Apache NiFi с нуля за 3 часа (Youtube-плейлист)](https://youtube.com/playlist?list=PL4MpKy3QjNp_rOEEibc4Ro8UK4g8vLX6_&si=W_hidjHmBOZ_aUfS) — первые 4 видео, дальше — по желанию
|
||||
- [Лучший Гайд по Kafka для Начинающих За 1 Час (Youtube)](https://www.youtube.com/watch?v=hbseyn-CfXY)
|
||||
|
||||
Практика — на стенде [nifi-kafka-postgres-lab](https://github.com/dementev-dev/nifi-kafka-postgres-lab) (Docker Compose с NiFi, Kafka и Postgres):
|
||||
|
||||
- настраиваем в NiFi простой генератор данных и поток в Postgres;
|
||||
- строим поток NiFi → Kafka → NiFi → Postgres.
|
||||
|
||||
## Lakehouse (Spark, Iceberg, Trino)
|
||||
### Lakehouse (Spark, Iceberg, Trino)
|
||||
|
||||
> Секция в разработке. Lakehouse — отдельное направление в DE, построенное на разделении compute и storage, открытых табличных форматах (Iceberg, Delta) и движках распределённой обработки (Spark, Trino). Этот роадмап фокусируется на классическом DWH-стеке, поэтому полноценный блок пока не готов — ниже только отправные точки для самостоятельного изучения.
|
||||
|
||||
- [DataLearn: «Что такое Apache Spark»](https://youtu.be/Tl9YzC-dQLI) — введение в Spark с нуля, ~40 минут
|
||||
- Стенд для экспериментов: [mini-lakehouse-lab](https://github.com/dementev-dev/mini-lakehouse-lab) (Spark + Iceberg + Trino + MinIO)
|
||||
|
||||
## dbt
|
||||
### dbt
|
||||
dbt (data build tool) — инструмент для трансформации данных в хранилище.
|
||||
|
||||
Мы рассматриваем его как альтернативу «ручному» написанию сложных CTE и для понимания современного подхода к моделированию данных как кода.
|
||||
|
||||
Материалы:
|
||||
|
||||
- [dbt quickstart (официальный гайд)](https://docs.getdbt.com/guides/manual-install?step=1)
|
||||
- [Перевод документации dbt на русский](https://docs.getdbt.tech/)
|
||||
|
||||
Практика:
|
||||
|
||||
- Клонировать [jaffle-shop](https://github.com/dbt-labs/jaffle-shop), установить dbt-duckdb, прогнать `dbt build`, `dbt test`, `dbt docs generate && dbt docs serve` — этого достаточно, чтобы увидеть весь цикл.
|
||||
|
||||
**Когда блок расширенных навыков считаем пройденным:**
|
||||
|
||||
- вы можете на собеседовании кратко объяснить, когда уместны Streaming (NiFi/Kafka), ClickHouse, Lakehouse-стек и dbt, и чем они дополняют базовый стек (Postgres, Airflow, Greenplum);
|
||||
- понимаете типичные сценарии: потоковые интеграции и очереди (NiFi + Kafka), аналитические витрины и отчёты на ClickHouse, Lakehouse-архитектура (Spark/Iceberg/Trino), трансформации данных как код (dbt);
|
||||
- не боитесь увидеть эти инструменты в описании вакансии и можете поддержать содержательный разговор об их месте в архитектуре.
|
||||
|
||||
---
|
||||
|
||||
# Софт скиллы
|
||||
## Софт скиллы
|
||||
|
||||
[[к оглавлению]](#оглавление)
|
||||
|
||||
@@ -431,12 +462,12 @@ dbt (data build tool) — инструмент для трансформации
|
||||
|
||||
---
|
||||
|
||||
# Дополнительные материалы
|
||||
## Дополнительные материалы
|
||||
|
||||
[[к оглавлению]](#оглавление)
|
||||
|
||||
- [ananevsyu/SandBox_DB_public: Песочница для изучения различных технологий связанных с инженерией данных](https://gitflic.ru/project/ananevsyu/sandbox_db_public)
|
||||
- Клон проекта [dementev_dev/sandbox_db_public-форк](https://gitflic.ru/project/dementev_dev/sandbox_db_public-fork)
|
||||
- Клон проекта [dementev_dev/sandbox_db_public-форк](https://gitflic.ru/project/dementev_dev/sandbox_db_public-fork)
|
||||
- [System Design. Разбор книги "Высоконагруженные приложения". Глава 1 - Youtube](https://www.youtube.com/watch?v=owjrIB_5go8) — отличный видео-конспект первой главы Клеппмана на русском.
|
||||
- [Индексы в БД - Youtube](https://www.youtube.com/watch?v=DyqtBiDrz3g)
|
||||
- [Spark + Iceberg in 1 Hour - Memory Tuning, Joins, Partition - Youtube](https://www.youtube.com/watch?v=3R-SLYK-P_0)
|
||||
@@ -448,6 +479,7 @@ dbt (data build tool) — инструмент для трансформации
|
||||
- [Книга. Введение в Apache Kafka для системных аналитиков и проектировщиков интеграций](https://systems.education/kafka)
|
||||
- [Перевод документации dbt на русский язык](https://docs.getdbt.tech/)
|
||||
|
||||
## Записи ОМ
|
||||
### Записи ОМ
|
||||
|
||||
- [Как пройти собеседование на программиста | Ультимативный гайд с @om_nazarov - Youtube](https://www.youtube.com/watch?v=tzSdiYZ52kI)
|
||||
- [Как стать программистом в 2025 | «Ультимативный гайд» с @om_nazarov](https://www.youtube.com/watch?v=6151ekTOl38)
|
||||
|
||||
@@ -52,9 +52,9 @@ customer_id,status,event_ts,_load_id,_load_ts
|
||||
Чтобы не тратить время на DDL, структуры таблиц для домашки уже подготовлены в `dwh-modeling/sql`:
|
||||
|
||||
- `07_ddl_hw_customer_status.sql` — создаёт дополнительные таблицы:
|
||||
- `stg.customer_status_raw` — сырые события о статусе клиента;
|
||||
- `ods.customer_status` — очищенные и типизированные события;
|
||||
- `dds.dim_customer_status` — измерение статусов клиента в формате **SCD Type 2**.
|
||||
- `stg.customer_status_raw` — сырые события о статусе клиента;
|
||||
- `ods.customer_status` — очищенные и типизированные события;
|
||||
- `dds.dim_customer_status` — измерение статусов клиента в формате **SCD Type 2**.
|
||||
- `08_dml_hw_customer_status_template.sql` — шаблон DML-скрипта с подсказками и заготовками блоков.
|
||||
|
||||
Перед началом работы:
|
||||
@@ -127,9 +127,9 @@ SELECT * FROM stg.customer_status_raw LIMIT 10;
|
||||
В файле `08_dml_hw_customer_status_template.sql` найдите заготовку блока ODS и допишите SQL:
|
||||
|
||||
- привести:
|
||||
- `customer_id` → `INT`,
|
||||
- `status` → `VARCHAR(20)` (можно оставить как есть),
|
||||
- `event_ts` и `_load_ts` → `TIMESTAMP`;
|
||||
- `customer_id` → `INT`,
|
||||
- `status` → `VARCHAR(20)` (можно оставить как есть),
|
||||
- `event_ts` и `_load_ts` → `TIMESTAMP`;
|
||||
- аккуратно обработать возможные пустые значения (если бы они были);
|
||||
- заполнить `_load_id` и `_load_ts` в `ods.customer_status`.
|
||||
|
||||
@@ -234,8 +234,8 @@ cat dwh-modeling/data/customer_status_events_increment.csv | ./postgres-bookings
|
||||
|
||||
- ориентируйтесь на пример из `03_demo_increment.sql` для `dds.dim_customer`;
|
||||
- важно:
|
||||
- корректно «закрыть» старую актуальную строку (заполнить `valid_to` датой начала новой версии);
|
||||
- вставить новую строку с `valid_to = NULL`.
|
||||
- корректно «закрыть» старую актуальную строку (заполнить `valid_to` датой начала новой версии);
|
||||
- вставить новую строку с `valid_to = NULL`.
|
||||
|
||||
Эта часть особенно полезна, если вы хотите почувствовать, как SCD2 живёт в реальном DWH.
|
||||
|
||||
|
||||
+26
-17
@@ -3,28 +3,30 @@
|
||||
|
||||
## Оглавление
|
||||
|
||||
- [Что вы уже умеете — и что узнаете здесь](#что-вы-уже-умеете-и-что-узнаете-здесь)
|
||||
- [Что вы уже умеете, и что узнаете здесь](#что-вы-уже-умеете-и-что-узнаете-здесь)
|
||||
- [1. Введение: почему нельзя просто SELECT из базы заказов?](#1-введение-почему-нельзя-просто-select-из-базы-заказов)
|
||||
- [2. Учебный пример: интернет-магазин](#2-учебный-пример-интернет-магазин)
|
||||
- [3. Зачем делить DWH на слои?](#3-зачем-делить-dwh-на-слои)
|
||||
- [4. Путешествие данных: от STG до DM](#4-путешествие-данных-от-stg-до-dm)
|
||||
- [5. Базовые понятия: факты, измерения, SCD](#5-базовые-понятия-факты-измерения-scd)
|
||||
- [6. Модели данных для слоя DDS: 4 подхода — и когда какой выбрать](#6-модели-данных-для-слоя-dds-4-подхода-и-когда-какой-выбрать)
|
||||
- [6. Модели данных для слоя DDS: 4 подхода, и когда какой выбрать](#6-модели-данных-для-слоя-dds-4-подхода-и-когда-какой-выбрать)
|
||||
- [7. Практикум: как собрать первую витрину](#7-практикум-как-собрать-первую-витрину)
|
||||
- [8. Как выбрать модель данных? Советы от практиков](#8-как-выбрать-модель-данных-советы-от-практиков)
|
||||
- [9. Эксплуатация: качество данных — это не «опция»](#9-эксплуатация-качество-данных-это-не-опция)
|
||||
- [10. Заключение: главное — понимать «почему»](#10-заключение-главное-понимать-почему)
|
||||
- [9. Эксплуатация: качество данных, это не «опция»](#9-эксплуатация-качество-данных-это-не-опция)
|
||||
- [10. Заключение: главное, понимать «почему»](#10-заключение-главное-понимать-почему)
|
||||
- [Приложения](#приложения)
|
||||
|
||||
---
|
||||
|
||||
## Что вы уже умеете — и что узнаете здесь
|
||||
## Что вы уже умеете, и что узнаете здесь
|
||||
|
||||
✅ Уже знаете:
|
||||
|
||||
- `SELECT`, `JOIN`, `GROUP BY`;
|
||||
- как посчитать сумму/среднее/количество по таблице.
|
||||
|
||||
🆕 Узнаете в этой статье:
|
||||
|
||||
- **слои хранилища** (STG → ODS → DDS → DM) и *зачем они нужны*;
|
||||
- **факты и измерения** — основные кирпичики аналитики;
|
||||
- **SCD Type 2** — как хранить историю изменений клиента (например, смену email или города);
|
||||
@@ -32,6 +34,7 @@
|
||||
- **четыре модели данных**: 3NF, Звезда (Star), Data Vault, Anchor Modeling — и когда какую использовать.
|
||||
|
||||
⛔ **Не будем говорить** здесь о:
|
||||
|
||||
- физическом хранении (партиции, индексы, ClickHouse-движки);
|
||||
- распределённых кластерах (Kafka, Spark, Airflow — это отдельный курс);
|
||||
- настройке производительности (`EXPLAIN`, кэши и т.п.).
|
||||
@@ -47,6 +50,7 @@
|
||||
Вы идёте в базу заказов — и… не находите email. Он в CRM. Идёте в CRM — там нет сумм заказов. Возвращаетесь в заказы — сумма есть, но *только текущая цена товара*. А в 2023 году цена была другой!
|
||||
|
||||
Знакомо? Это — **проблема OLTP-систем** (оперативного учёта):
|
||||
|
||||
- **CRM**, **склад**, **платёжка** — это разные базы;
|
||||
- каждая оптимизирована под *быструю запись операций* («добавить заказ», «списать товар»);
|
||||
- историю там не хранят — email меняется «в лоб»: старое значение перезаписывается.
|
||||
@@ -75,6 +79,7 @@
|
||||
| `promos` | Маркетинг | Акции: `promo_id`, `code` |
|
||||
|
||||
⚠️ Обратите внимание:
|
||||
|
||||
- `customer_id = 101` в одном месяце — `a@ex.com`, в другом — `b@ex.com`;
|
||||
- цена на товар `9001` (Phone) в январе — 100 ₽, в феврале — 110 ₽;
|
||||
- `order_items` содержит `price_at_sale` — *цену в момент покупки*, а не текущую.
|
||||
@@ -145,8 +150,8 @@ flowchart TD
|
||||
- Таблицы: `stg.orders_raw`, `stg.customers_raw`;
|
||||
- Структура — *точно как в источнике* (может быть `VARCHAR` даже у дат);
|
||||
- Добавлены технические поля:
|
||||
- `_load_id` — идентификатор загрузки;
|
||||
- `_load_ts` — время получения данных;
|
||||
- `_load_id` — идентификатор загрузки;
|
||||
- `_load_ts` — время получения данных;
|
||||
- Главное правило: **неизменяемость**. Если пришла новая порция — либо добавляем новые строки, либо *полностью перезагружаем* слой (идемпотентность).
|
||||
|
||||
> 💡 *Пример:* `stg.orders_raw` содержит `"2024-01-10"` как строку — это нормально. Главное — не потерять оригинал.
|
||||
@@ -157,10 +162,10 @@ flowchart TD
|
||||
|
||||
- Таблицы: `ods.orders`, `ods.customers`;
|
||||
- Здесь:
|
||||
- привели `order_date` к типу `DATE`;
|
||||
- убрали заказы без клиента (`customer_id IS NULL` → ошибка или флаг);
|
||||
- привели телефоны к формату `79991112233`;
|
||||
- проверили email на валидность (регуляркой или простой проверкой).
|
||||
- привели `order_date` к типу `DATE`;
|
||||
- убрали заказы без клиента (`customer_id IS NULL` → ошибка или флаг);
|
||||
- привели телефоны к формату `79991112233`;
|
||||
- проверили email на валидность (регуляркой или простой проверкой).
|
||||
- **Но!** Не объединяем клиента из CRM и клиента из заказов — это будет позже.
|
||||
- Пока — никакой бизнес-логики. Только *техническая* очистка.
|
||||
- Дедупликация: если два раза пришёл один и тот же заказ — оставляем один (по `order_id + _load_ts`).
|
||||
@@ -197,6 +202,7 @@ flowchart TD
|
||||
### **DM (Data Mart / Gold/ «Витрины»)** — «готово к употреблению»
|
||||
|
||||
Здесь — таблицы и представления для конкретных задач:
|
||||
|
||||
- `dm.mart_daily_sales` — ежедневные продажи по товарам и сегментам;
|
||||
- `dm.mart_customer_360` — полный портрет клиента: сколько потратил, когда заходил, какие товары любит.
|
||||
|
||||
@@ -210,12 +216,13 @@ flowchart TD
|
||||
> *«10 января 2024 года клиент из Москвы (сегмент Premium) купил Phone за 100 ₽»*.
|
||||
|
||||
В DWH это разложится на:
|
||||
|
||||
- **Факт (Fact)** — событие, которое можно измерить: *покупка*.
|
||||
Хранится в `fact_sales`: `quantity = 1`, `amount = 100`.
|
||||
- **Измерения (Dimensions)** — *контекст* факта:
|
||||
- `dim_date` → 10 января 2024;
|
||||
- `dim_customer` → Москва, Premium;
|
||||
- `dim_product` → Phone.
|
||||
- `dim_date` → 10 января 2024;
|
||||
- `dim_customer` → Москва, Premium;
|
||||
- `dim_product` → Phone.
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
@@ -262,6 +269,7 @@ erDiagram
|
||||
### SCD Type 2 — как хранить историю
|
||||
|
||||
Клиент №101:
|
||||
|
||||
- с 1 янв по 15 мая — `email = a@ex.com`, `city = Москва`;
|
||||
- с 16 мая — `email = b@ex.com`, `city = Москва`;
|
||||
- с 1 окт — `email = b@ex.com`, `city = Санкт-Петербург`.
|
||||
@@ -287,7 +295,7 @@ AND (dim_customer.valid_to IS NULL OR fact_sales.order_date < dim_customer.valid
|
||||
|
||||
---
|
||||
|
||||
## 6. Модели данных для слоя DDS: 4 подхода — и когда какой выбрать
|
||||
## 6. Модели данных для слоя DDS: 4 подхода, и когда какой выбрать
|
||||
|
||||
В DDS мы можем хранить данные по-разному. Это не «правильно/неправильно», а **выбор под задачу**.
|
||||
|
||||
@@ -431,6 +439,7 @@ WHERE c.city = 'Москва'
|
||||
|
||||
💡 **Главная мысль:**
|
||||
идентичность, связи и атрибуты живут **в разных таблицах**, поэтому:
|
||||
|
||||
- историю проще хранить;
|
||||
- новые источники проще прикручивать;
|
||||
- меньше шансов «сломать» старые отчёты.
|
||||
@@ -663,7 +672,7 @@ GROUP BY d.date_actual, p.product_name,
|
||||
|
||||
---
|
||||
|
||||
## 9. Эксплуатация: качество данных — это не «опция»
|
||||
## 9. Эксплуатация: качество данных, это не «опция»
|
||||
|
||||
Самая красивая архитектура бессмысленна, если в `mart_daily_sales` — нули.
|
||||
Поэтому в каждом слое — **контроль качества (DQ, Data Quality)**.
|
||||
@@ -706,7 +715,7 @@ SELECT 'OK' WHERE EXISTS (
|
||||
|
||||
---
|
||||
|
||||
## 10. Заключение: главное — понимать «почему»
|
||||
## 10. Заключение: главное, понимать «почему»
|
||||
|
||||
Хранилище данных — это не про «крутые технологии», а про **мышление**:
|
||||
|
||||
|
||||
@@ -283,6 +283,7 @@ LEFT JOIN current_customers c ON n.customer_id = c.customer_id
|
||||
|
||||
###### Шаг 3: Вставка новых версий
|
||||
Для подходящих записей создаём новую версию:
|
||||
|
||||
- `uuid()` — генерируем уникальный ключ для новой версии
|
||||
- `current_date` - функция, возвращающая текущую даты
|
||||
- `COALESCE(n.effective_date, current_date)` — устанавливаем дату начала действия новой версии
|
||||
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
site_name: "DE Roadmap — Data Engineering с нуля до middle"
|
||||
site_url: https://dementev-dev.github.io/de-roadmap/
|
||||
site_description: "Роадмап по Data Engineering: SQL, Python, Airflow, Greenplum и далее"
|
||||
site_author: Dmitry Dementev
|
||||
|
||||
repo_url: https://github.com/dementev-dev/de-roadmap
|
||||
repo_name: dementev-dev/de-roadmap
|
||||
|
||||
docs_dir: .
|
||||
site_dir: site
|
||||
|
||||
exclude_docs: |
|
||||
project/
|
||||
postgres-bookings/
|
||||
.github/
|
||||
.claude/
|
||||
site/
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
COMMIT_RULES.md
|
||||
LICENSE
|
||||
.gitignore
|
||||
mkdocs.yml
|
||||
dwh-modeling/TODO.md
|
||||
|
||||
nav:
|
||||
- Роадмап: README.md
|
||||
- Моделирование данных:
|
||||
- Введение: dwh-modeling/README.md
|
||||
- SCD: dwh-modeling/SCD.md
|
||||
- Data Vault: dwh-modeling/DataVault.md
|
||||
- "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
language: ru
|
||||
palette:
|
||||
- scheme: default
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Тёмная тема
|
||||
- scheme: slate
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Светлая тема
|
||||
features:
|
||||
- navigation.top
|
||||
- navigation.tracking
|
||||
- search.suggest
|
||||
- search.highlight
|
||||
- toc.follow
|
||||
- content.code.copy
|
||||
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
slugify: !!python/object/apply:pymdownx.slugs.slugify
|
||||
kwds:
|
||||
case: lower
|
||||
permalink: true
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
- pymdownx.highlight
|
||||
- attr_list
|
||||
|
||||
plugins:
|
||||
- same-dir
|
||||
- search:
|
||||
lang: ru
|
||||
+350
@@ -0,0 +1,350 @@
|
||||
# ADR: Архитектура сайта de-roadmap
|
||||
|
||||
> Архитектурный документ. Проектные цели и требования — в [PRD](./PRD.md).
|
||||
|
||||
---
|
||||
|
||||
## 1. Ключевые архитектурные требования
|
||||
|
||||
Из PRD вытекают четыре жёстких ограничения, определяющих выбор инструментов:
|
||||
|
||||
1. **Сайт опционален.** Репозиторий должен полноценно работать без сайта. Удалили конфиг — всё как было.
|
||||
2. **Dual-compatible links.** Внутренние ссылки между `.md` файлами должны работать и на GitHub, и на сайте.
|
||||
3. **Один файл = один источник правды.** Не должно быть копий или генерируемых `.md`. Редактируем один раз — рендерится везде.
|
||||
4. **Zero-effort deploy.** Push в `main` → сайт обновился. Без ручных шагов, без локальной сборки.
|
||||
|
||||
---
|
||||
|
||||
## 2. Выбор генератора статического сайта
|
||||
|
||||
### Рассмотренные варианты
|
||||
|
||||
| Критерий | MkDocs Material | Docusaurus | Hugo | Astro |
|
||||
|----------|----------------|------------|------|-------|
|
||||
| Язык/экосистема | Python | Node.js (React) | Go | Node.js |
|
||||
| Порог входа | Минимальный — `pip install`, один YAML | Средний — npm, React-компоненты | Средний — Go templates | Высокий — фреймворк |
|
||||
| Поддержка Markdown «как есть» | Отличная, расширения через плагины | Хорошая, но MDX-ориентирован | Хорошая, но shortcodes вместо стандартного MD | Хорошая |
|
||||
| Навигация по длинной странице | TOC sidebar из коробки | Есть, но заточен под многостраничность | Зависит от темы | Зависит от темы |
|
||||
| Поиск | Встроенный (lunr.js), работает offline | Algolia (внешний сервис) или плагин | Нет из коробки | Нет из коробки |
|
||||
| Тёмная тема | Из коробки, переключатель | Из коробки | Зависит от темы | Зависит от темы |
|
||||
| GitHub Pages деплой | Одна команда / готовый Action | Готовый Action | Готовый Action | Готовый Action |
|
||||
| Dual-compatible links | Поддерживает с настройкой `use_directory_urls` | Преобразует ссылки, может ломать GitHub | Преобразует ссылки | Преобразует ссылки |
|
||||
| Один мейнтейнер, Python-стек | ✅ Идеально | ❌ Node.js | ⚠️ Go, но бинарник | ❌ Node.js |
|
||||
|
||||
### Решение: MkDocs Material
|
||||
|
||||
**Почему:**
|
||||
|
||||
- Python-based — совпадает со стеком автора, `pip install` и готово.
|
||||
- Лучшая из коробки поддержка длинных страниц с TOC — именно наш сценарий.
|
||||
- Встроенный поиск без внешних сервисов.
|
||||
- Самый простой конфиг — один `mkdocs.yml`.
|
||||
- Крупнейшее комьюнити среди генераторов документации, активно развивается.
|
||||
- Dual-compatible links решаемы (см. раздел 4).
|
||||
|
||||
**Почему не Docusaurus:** Node.js-зависимость, ориентирован на многостраничные доки с MDX-компонентами — overkill для «красивый рендер Markdown». Преобразование ссылок может конфликтовать с GitHub-форматом.
|
||||
|
||||
**Почему не Hugo:** Быстрый, но Go-шаблоны сложнее отлаживать. Нет встроенного поиска. Для нашего объёма контента скорость сборки не критична.
|
||||
|
||||
**Почему не Astro:** Полноценный веб-фреймворк — избыточен. Подошёл бы, если бы мы строили маркетинговый сайт с интерактивом, но это не текущая цель.
|
||||
|
||||
---
|
||||
|
||||
## 3. Структура файлов
|
||||
|
||||
### Решение открытого вопроса: `docs/` vs корень репо
|
||||
|
||||
**Решение: `docs_dir: .` (корень репо = корень сайта), с исключениями.**
|
||||
|
||||
Причина: не создаём отдельную папку `docs/`, не дублируем и не перемещаем файлы. MkDocs умеет работать с корнем репо как источником, исключая ненужное.
|
||||
|
||||
```yaml
|
||||
# mkdocs.yml (в корне репо)
|
||||
docs_dir: .
|
||||
```
|
||||
|
||||
### Решение открытого вопроса: README.md как index
|
||||
|
||||
**Решение: плагин `awesome-pages` или конфигурация `nav` с явным указанием.**
|
||||
|
||||
MkDocs по умолчанию ищет `index.md`. Но мы хотим сохранить `README.md` (GitHub его рендерит на главной репо). Есть два пути:
|
||||
|
||||
- **Вариант A:** Симлинк `docs/index.md → ../README.md`. Но мы не используем `docs/`.
|
||||
- **Вариант B (выбран):** В `mkdocs.yml` явно указать `README.md` как главную:
|
||||
|
||||
```yaml
|
||||
nav:
|
||||
- Роадмап: README.md
|
||||
- Моделирование данных:
|
||||
- Введение: dwh-modeling/README.md
|
||||
- SCD: dwh-modeling/SCD.md
|
||||
- Data Vault: dwh-modeling/DataVault.md
|
||||
- "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
|
||||
```
|
||||
|
||||
MkDocs Material корректно обрабатывает `README.md` файлы — рендерит их как `index.html` соответствующей директории.
|
||||
|
||||
### Исключения из сборки
|
||||
|
||||
Файлы и папки, которые не должны попасть на сайт:
|
||||
|
||||
```yaml
|
||||
exclude_docs: |
|
||||
project/ # проектная документация (PRD, ADR)
|
||||
postgres-bookings/ # скрипты стенда (не контент сайта)
|
||||
AGENTS.md # конфигурация для AI-агентов
|
||||
LICENSE # лицензия (есть в footer)
|
||||
.gitignore
|
||||
```
|
||||
|
||||
### Итоговая структура репо
|
||||
|
||||
```
|
||||
de-roadmap/
|
||||
├── mkdocs.yml ← конфиг сайта (единственный новый файл в корне)
|
||||
├── README.md ← главная страница сайта И главная страница GitHub
|
||||
├── dwh-modeling/
|
||||
│ ├── README.md ← подстраница «Введение в DWH»
|
||||
│ ├── SCD.md ← подстраница
|
||||
│ ├── DataVault.md ← подстраница
|
||||
│ └── Homework_*.md ← подстраница
|
||||
├── postgres-bookings/ ← исключён из сайта
|
||||
├── project/ ← PRD, ADR — исключены из сайта
|
||||
│ ├── PRD.md
|
||||
│ └── ADR.md
|
||||
├── .github/
|
||||
│ └── workflows/
|
||||
│ └── deploy-site.yml ← CI/CD pipeline
|
||||
├── AGENTS.md ← исключён из сайта
|
||||
└── LICENSE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Стратегия ссылок (Dual Compatibility)
|
||||
|
||||
### Проблема
|
||||
|
||||
GitHub рендерит ссылки вида `[текст](dwh-modeling/SCD.md)` как переход к файлу.
|
||||
MkDocs по умолчанию преобразует `.md` → `.html` и может менять структуру URL.
|
||||
|
||||
### Решение
|
||||
|
||||
Комбинация настроек MkDocs:
|
||||
|
||||
```yaml
|
||||
use_directory_urls: true # /dwh-modeling/SCD/ вместо /dwh-modeling/SCD.html
|
||||
```
|
||||
|
||||
И ссылки в Markdown пишем **всегда как относительные пути к `.md` файлам**:
|
||||
|
||||
```markdown
|
||||
<!-- Это работает и на GitHub, и в MkDocs -->
|
||||
[Теория про SCD](dwh-modeling/SCD.md)
|
||||
[Введение в DWH](dwh-modeling/README.md)
|
||||
```
|
||||
|
||||
MkDocs Material автоматически резолвит `.md` ссылки в правильные URL сайта.
|
||||
|
||||
### Кириллические якоря
|
||||
|
||||
GitHub генерирует якоря из кириллических заголовков с URL-encoding:
|
||||
`## Базы данных` → `#базы-данных`
|
||||
|
||||
MkDocs Material по умолчанию делает то же самое через расширение `toc`:
|
||||
|
||||
```yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
slugify: !!python/object/apply:pymdownx.slugs.slugify
|
||||
kwds:
|
||||
case: lower
|
||||
permalink: true
|
||||
```
|
||||
|
||||
**Риск:** поведение может различаться на edge cases (спецсимволы, эмодзи в заголовках). Митигация — на этапе MVP протестировать все существующие якорные ссылки в README.
|
||||
|
||||
---
|
||||
|
||||
## 5. CI/CD Pipeline
|
||||
|
||||
### GitHub Actions Workflow
|
||||
|
||||
```yaml
|
||||
# .github/workflows/deploy-site.yml
|
||||
name: Deploy MkDocs to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch: # ручной запуск для отладки
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.x'
|
||||
|
||||
- run: pip install mkdocs-material
|
||||
|
||||
- run: mkdocs build --strict
|
||||
# --strict: падает на warnings (битые ссылки, отсутствующие файлы)
|
||||
|
||||
- uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: site/
|
||||
|
||||
deploy:
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
steps:
|
||||
- id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
### Что даёт `--strict`
|
||||
|
||||
Сборка упадёт, если:
|
||||
- Есть ссылка на несуществующий `.md` файл.
|
||||
- Есть битый якорь.
|
||||
- Есть warning от MkDocs.
|
||||
|
||||
Это наш автотест ссылок — бесплатно, в CI.
|
||||
|
||||
---
|
||||
|
||||
## 6. Конфигурация MkDocs Material
|
||||
|
||||
### Минимальный `mkdocs.yml` для MVP
|
||||
|
||||
```yaml
|
||||
site_name: "DE Roadmap — Data Engineering с нуля до middle"
|
||||
site_url: https://dementev-dev.github.io/de-roadmap/
|
||||
site_description: "Роадмап по Data Engineering: SQL, Python, Airflow, Greenplum и далее"
|
||||
site_author: Dmitry Dementev
|
||||
|
||||
repo_url: https://github.com/dementev-dev/de-roadmap
|
||||
repo_name: dementev-dev/de-roadmap
|
||||
|
||||
docs_dir: .
|
||||
site_dir: site
|
||||
|
||||
# Исключаем из сборки
|
||||
exclude_docs: |
|
||||
project/
|
||||
postgres-bookings/
|
||||
AGENTS.md
|
||||
LICENSE
|
||||
.gitignore
|
||||
.github/
|
||||
site/
|
||||
|
||||
nav:
|
||||
- Роадмап: README.md
|
||||
- Моделирование данных:
|
||||
- Введение: dwh-modeling/README.md
|
||||
- SCD: dwh-modeling/SCD.md
|
||||
- Data Vault: dwh-modeling/DataVault.md
|
||||
- "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
language: ru
|
||||
palette:
|
||||
- scheme: default
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Тёмная тема
|
||||
- scheme: slate
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Светлая тема
|
||||
features:
|
||||
- navigation.top # кнопка «наверх»
|
||||
- navigation.tracking # URL обновляется при скролле
|
||||
- search.suggest # подсказки в поиске
|
||||
- search.highlight # подсветка найденного
|
||||
- toc.follow # TOC следит за скроллом
|
||||
- content.code.copy # кнопка копирования кода
|
||||
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
- admonition # сворачиваемые блоки (Спринт 2)
|
||||
- pymdownx.details # для <details>
|
||||
- pymdownx.superfences # вложенные блоки кода
|
||||
- pymdownx.highlight # подсветка синтаксиса
|
||||
- attr_list # атрибуты для элементов
|
||||
|
||||
plugins:
|
||||
- search:
|
||||
lang: ru
|
||||
```
|
||||
|
||||
### Что уже включено в MVP (бесплатно с Material)
|
||||
|
||||
- Тёмная/светлая тема с переключателем.
|
||||
- Полнотекстовый поиск на русском.
|
||||
- TOC (оглавление) в правом sidebar.
|
||||
- Кнопка «наверх» на длинной странице.
|
||||
- URL обновляется при скролле (можно дать ссылку на конкретный раздел).
|
||||
- Подсветка синтаксиса в блоках кода.
|
||||
- Кнопка копирования кода.
|
||||
- Ссылка на GitHub-репозиторий в шапке.
|
||||
|
||||
---
|
||||
|
||||
## 7. Кастомный домен (Спринт 2)
|
||||
|
||||
Домен `dementev.space` уже есть. Для подключения:
|
||||
|
||||
1. Создать CNAME-запись: `roadmap.dementev.space → dementev-dev.github.io`.
|
||||
2. Добавить файл `CNAME` в корень репо с содержимым `roadmap.dementev.space`.
|
||||
3. В `mkdocs.yml` обновить `site_url`.
|
||||
4. Включить HTTPS в настройках GitHub Pages.
|
||||
|
||||
---
|
||||
|
||||
## 8. Риски и митигации
|
||||
|
||||
| Риск | Митигация |
|
||||
|------|-----------|
|
||||
| `docs_dir: .` подхватывает лишние файлы | `exclude_docs` со списком исключений; `--strict` ловит проблемы |
|
||||
| Кириллические якоря ведут себя по-разному | Тестируем все якорные ссылки из README при первом деплое |
|
||||
| `README.md` содержит GitHub-специфичный синтаксис | Проверяем рендер; при необходимости используем MkDocs-совместимые альтернативы |
|
||||
| Зависимость от `mkdocs-material` | Активный проект (30k+ stars), Python-пакет; при необходимости — заморозить версию в `requirements.txt` |
|
||||
| `exclude_docs` — относительно новая фича MkDocs | Альтернатива: `.mkdocsignore` или плагин `mkdocs-exclude`; протестировать на MVP |
|
||||
|
||||
---
|
||||
|
||||
## 9. Порядок действий (Спринт 1)
|
||||
|
||||
1. Создать ветку `feature/site`.
|
||||
2. Добавить `mkdocs.yml` в корень репо.
|
||||
3. Добавить `.github/workflows/deploy-site.yml`.
|
||||
4. Добавить `project/PRD.md` и `project/ADR.md`.
|
||||
5. Проверить локально: `pip install mkdocs-material && mkdocs serve`.
|
||||
6. Протестировать все внутренние ссылки и якоря.
|
||||
7. При необходимости — адаптировать ссылки для dual compatibility.
|
||||
8. Merge в `main` → автодеплой → проверить `https://dementev-dev.github.io/de-roadmap/`.
|
||||
9. Включить GitHub Pages (Settings → Pages → Source: GitHub Actions).
|
||||
+168
@@ -0,0 +1,168 @@
|
||||
# PRD: Сайт для de-roadmap
|
||||
|
||||
> Проектный документ. Техническая архитектура — в отдельном ADR.
|
||||
|
||||
---
|
||||
|
||||
## 1. Контекст и мотивация
|
||||
|
||||
### Текущее состояние
|
||||
|
||||
Роадмап по Data Engineering живёт как GitHub-репозиторий ([dementev-dev/de-roadmap](https://github.com/dementev-dev/de-roadmap)):
|
||||
|
||||
- Основной контент — монолитный `README.md` (~700 строк) с полным учебным планом.
|
||||
- Дополнительные материалы — в подпапках (`dwh-modeling/`, `postgres-bookings/`): теория DWH-моделирования, SCD, Data Vault, домашние задания, скрипты.
|
||||
- 109 коммитов, контент активно развивается.
|
||||
- Основной поток менти приходит через маркетплейс ОМ (Осознанная Меркантильность) — платформу менторства с системой отзывов, ранжированием менторов и модерацией. Участие платное (абонентская плата + аукцион за позицию в выдаче).
|
||||
- Роадмап изначально создавался для себя — как конспект подходов к обучению. Со временем стал использоваться и для менти (удобная структура прохождения), и на ознакомительных созвонах с лидами из ОМ (демонстрация программы и подхода к обучению).
|
||||
- Отдельного маркетингового продвижения роадмапа не было, органических приходов «по ссылке из интернета» — ноль. Сайта ментора тоже пока нет — приходить некуда.
|
||||
|
||||
### Проблема
|
||||
|
||||
GitHub README — рабочий, но не презентабельный формат:
|
||||
|
||||
- Нет удобной навигации по длинному документу (только ручной скролл или оглавление-ссылки).
|
||||
- Выглядит как «техническая документация», а не как продукт ментора.
|
||||
- GitHub README плохо индексируется поисковыми системами — роадмап в таком виде даже потенциально не может привлекать органический трафик и «продавать сам себя».
|
||||
- Неудобно давать ссылку потенциальному менти — GitHub-интерфейс отвлекает (issues, commits, файловое дерево).
|
||||
- Нет мобильной адаптации контента (GitHub на телефоне — страдание).
|
||||
|
||||
### Чего НЕ решаем этим проектом
|
||||
|
||||
- **Лидогенерацию и воронку продаж.** Основной поток тёплых лидов идёт через маркетплейс ОМ, и конкурировать с ним по объёму нереалистично — даже топовые менторы не добирают сравнимое количество лидов из других источников. В перспективе сайт может стать элементом маркетинговой воронки (Habr → сайт → менторство), но это отдалённая цель, не влияющая на текущие решения. Сейчас сайт — витрина экспертизы, а не маркетинговый инструмент.
|
||||
- **Масштабирование менторского бизнеса.** Сейчас приоритет — выпустить текущих менти, а не набрать новых.
|
||||
- **Создание LMS / интерактивного курса.** Формат остаётся «структурированный текст + ссылки», без трекинга прогресса и автопроверок.
|
||||
|
||||
---
|
||||
|
||||
## 2. Цели
|
||||
|
||||
| # | Цель | Метрика успеха |
|
||||
|---|------|----------------|
|
||||
| 1 | Удобная читаемая версия роадмапа | Сайт с навигацией, поиском, мобильной версией |
|
||||
| 2 | Репозиторий остаётся полностью рабочим без сайта | Все `.md` файлы читаемы на GitHub, ссылки между ними работают |
|
||||
| 3 | Минимальные накладные расходы на поддержку | Обновил `.md` → запушил → сайт обновился автоматически |
|
||||
| 4 | Презентабельный вид для демонстрации на созвонах | Ссылка, которую удобно показать лиду из ОМ при обсуждении программы |
|
||||
|
||||
---
|
||||
|
||||
## 3. Целевая аудитория
|
||||
|
||||
**Основная:** менти (текущие и потенциальные) — джуны и переходящие в DE из смежных областей. Приходят по рекомендации из ОМ или по прямой ссылке от ментора. Им нужно быстро оценить объём программы и найти нужный раздел.
|
||||
|
||||
**Вторичная:** коллеги-инженеры, которые наткнулись на репозиторий через GitHub/поиск. Для них важна полнота контента и техническая достоверность, а не «продающие» элементы.
|
||||
|
||||
---
|
||||
|
||||
## 4. Требования
|
||||
|
||||
### 4.1. Обязательные (MVP)
|
||||
|
||||
**Контент и структура:**
|
||||
|
||||
- [ ] Главная страница сайта = полный текст текущего `README.md` (одна длинная страница, не разбиваем).
|
||||
- [ ] Подстраницы из существующих `.md` файлов (`dwh-modeling/README.md`, `SCD.md`, `DataVault.md`, домашки).
|
||||
- [ ] Автоматическое оглавление (Table of Contents) по заголовкам H2/H3 на главной странице.
|
||||
- [ ] Внутренние ссылки работают и на GitHub, и на сайте (dual-compatible links).
|
||||
|
||||
**Навигация:**
|
||||
|
||||
- [ ] Боковая панель с разделами сайта (основной README + подразделы).
|
||||
- [ ] Оглавление текущей страницы (правый sidebar / TOC).
|
||||
- [ ] Полнотекстовый поиск по сайту.
|
||||
|
||||
**Деплой:**
|
||||
|
||||
- [ ] Автоматическая сборка и публикация при пуше в `main`.
|
||||
- [ ] Бесплатный хостинг (GitHub Pages).
|
||||
|
||||
**Совместимость с репо:**
|
||||
|
||||
- [ ] Все `.md` файлы остаются читаемыми на GitHub «как есть».
|
||||
- [ ] `README.md` в корне репо продолжает рендериться на главной странице репозитория.
|
||||
- [ ] Добавление сайта не ломает существующую структуру — если удалить конфиг сайта, репо работает как раньше.
|
||||
|
||||
### 4.2. Желательные (Спринт 2+)
|
||||
|
||||
- [ ] Кастомный домен (например, `roadmap.dementev.space`).
|
||||
- [ ] Тёмная тема (переключатель light/dark).
|
||||
- [ ] Сворачиваемые блоки (collapsible sections / admonitions) для длинных списков материалов.
|
||||
- [ ] Кнопка «Написать в Telegram» (floating или в footer) — не агрессивный CTA, просто удобство.
|
||||
- [ ] Иконки/бейджи для статуса разделов (пройден / в процессе / не начат) — пока декоративные, без бэкенда.
|
||||
- [ ] Яндекс.Метрика или аналогичная аналитика (понимать, сколько людей заходят).
|
||||
|
||||
### 4.3. Явно НЕ делаем
|
||||
|
||||
- Разбивку основного README на отдельные страницы.
|
||||
- Интерактивный трекинг прогресса менти.
|
||||
- Систему авторизации / личный кабинет.
|
||||
- Блог или раздел новостей (для этого есть Telegram-канал).
|
||||
- SEO-оптимизацию и маркетинговые landing pages.
|
||||
|
||||
---
|
||||
|
||||
## 5. Ограничения
|
||||
|
||||
- **Бюджет: 0 ₽** (кроме домена, если решим подключить кастомный — `dementev.space` уже есть).
|
||||
- **Время на поддержку: минимальное.** Рабочий процесс = «редактирую `.md` → push → сайт обновляется». Не должно быть отдельного шага сборки, ручного деплоя или npm-зависимостей, требующих обновления.
|
||||
- **Стек автора: Python-first.** Решение на Python-тулинге предпочтительнее, чем на Node.js/Ruby (проще отлаживать при необходимости).
|
||||
- **Один мейнтейнер.** Сайт поддерживает один человек — сложность решения должна быть соответствующей.
|
||||
|
||||
---
|
||||
|
||||
## 6. Итерации
|
||||
|
||||
### Спринт 1 — MVP: «Сайт, который просто работает»
|
||||
|
||||
**Scope:**
|
||||
|
||||
- Конфигурация генератора статического сайта.
|
||||
- CI/CD pipeline (GitHub Actions → GitHub Pages).
|
||||
- Главная страница = README.
|
||||
- Подстраницы из `dwh-modeling/`.
|
||||
- Фикс внутренних ссылок для dual compatibility.
|
||||
|
||||
**Definition of Done:**
|
||||
|
||||
- Сайт доступен по URL `https://dementev-dev.github.io/de-roadmap/`.
|
||||
- Все ссылки внутри README работают и на сайте, и на GitHub.
|
||||
- При пуше в `main` сайт автоматически пересобирается за < 2 минут.
|
||||
- Контент на GitHub выглядит ровно так же, как до добавления сайта.
|
||||
|
||||
### Спринт 2 — «Удобство и навигация»
|
||||
|
||||
**Scope:**
|
||||
|
||||
- Кастомный домен.
|
||||
- Тёмная тема.
|
||||
- Сворачиваемые блоки для длинных секций.
|
||||
- Кнопка «Написать ментору» (Telegram).
|
||||
- Базовая аналитика.
|
||||
|
||||
### Спринт 3 — «Контент и визуал» (по необходимости)
|
||||
|
||||
**Scope:**
|
||||
|
||||
- Визуальная карта роадмапа (интерактивная диаграмма прохождения).
|
||||
- Страница «О менторе» / «Отзывы выпускников» (когда будут выпускники).
|
||||
- Расширение контента: новые разделы роадмапа → автоматически появляются на сайте.
|
||||
|
||||
---
|
||||
|
||||
## 7. Риски
|
||||
|
||||
| Риск | Вероятность | Влияние | Митигация |
|
||||
|------|-------------|---------|-----------|
|
||||
| Ссылки ломаются при конвертации (GitHub vs сайт) | Средняя | Высокое | Стратегия dual-compatible links в ADR; автотест ссылок в CI |
|
||||
| Кириллические якоря рендерятся по-разному | Средняя | Среднее | Тестирование конкретного генератора; при необходимости — латинские id |
|
||||
| Генератор сайта перестаёт поддерживаться | Низкая | Среднее | Контент в plain Markdown — миграция на другой генератор за день |
|
||||
| Накладные расходы на поддержку растут | Низкая | Среднее | Принцип «сайт опционален»: если мешает — удаляем конфиг, репо работает |
|
||||
| GitHub Pages ограничения (bandwidth, размер) | Очень низкая | Низкое | Для статического сайта с текстом — не актуально |
|
||||
|
||||
---
|
||||
|
||||
## 8. Открытые вопросы
|
||||
|
||||
1. **Домен.** Использовать GitHub Pages URL или сразу подключить кастомный домен? Можно решить в Спринте 2.
|
||||
2. **README.md в корне vs docs/.** Оставляем README.md в корне (GitHub его рендерит) и используем его же как `index.md` для сайта, или делаем симлинк / копию? → Решение в ADR.
|
||||
3. **Структура `docs/` директории.** Нужно ли вообще создавать `docs/`, или генератор может работать прямо с корнем репо? → Решение в ADR.
|
||||
Reference in New Issue
Block a user