Files

T

ddadmin 6655326caa docs(all): реструктурирована документация — docs/internal/ заменён на design/, reference/, archive/, plans/

- Зачем:
  - docs/internal/ превратился в свалку: дизайн-документы, ревью, планы и справочники лежали вперемешку.
  - архивные планы были неотличимы от живых документов.
- Что:
  - docs/internal/ удалён; файлы распределены по docs/design/, docs/reference/, docs/archive/, docs/plans/, docs/assignment/.
  - educational-tasks.md убран из корня в архив (устарел).
  - обновлены все перекрёстные ссылки в AGENTS.md, TODO.md, README.md, docs/README.md и внутри design/reference/.
  - актуализированы architecture_review.md (статус DM-слоя), db_schema.md (DM-слой), TESTING.md, dag_execution_order.md, pxf_bookings.md.
  - добавлены заглушки docs/assignment/README.md и docs/plans/README.md.
- Проверка:
  - make test && make lint
  - rg 'docs/internal' --glob '!docs/archive/*' — должно быть пусто.

2026-03-10 23:02:41 +03:00

13 KiB

Raw Blame History

План ревизии документации

Статус: ЧЕРНОВИК v3 | Дата: 2026-03-10 Контекст: перед Этапом 2 (подготовка main) нужно навести порядок в docs/

Проблемы

docs/internal/ — свалка: дизайн-документы, планы, ревью, баг-трекеры, стандарты
3 архивных плана лежат рядом с живыми документами (неотличимы)
3 осиротевших документа (никто не ссылается)
educational-tasks.md в корне — устарел (раздел 2.2 говорит «ODS/DDS/DM будут позже»)
5 документов содержат устаревшие фрагменты
docs/README.md не знает про несколько живых документов

Принципы

Архив замораживается. Файлы в docs/archive/ не правим — ссылки внутри них могут быть битыми, это ожидаемо. Они сохраняются как исторические артефакты.
Активные планы живут в docs/plans/, после выполнения переезжают в docs/archive/.
Студенческий entry point не должен исчезать: пока analyst_spec.md (Этап 3) не создан, в docs/assignment/ будет заглушка README.md со ссылкой на эталонный срез для самостоятельного изучения.

Фаза 1. Структура каталогов

Создать новые каталоги:

docs/design/       — дизайн-документы, стандарты, архитектура
docs/reference/    — техническая справка, баг-трекеры, бенчмарки
docs/plans/        — активные планы работ
docs/archive/      — выполненные планы, закрытые ревью
docs/assignment/   — заглушка README.md (подготовка для Этапа 3)

Фаза 2. Перемещение файлов

В `docs/archive/` (4 файла)

Откуда	Файл	Причина
корень	`educational-tasks.md`	Устарел, заменён `assignment_design.md`
`docs/internal/`	`stg_naming_unification_plan.md`	Выполнен
`docs/internal/`	`dim_routes_denormalization_plan.md`	Выполнен
`docs/internal/`	`bookings_stg_code_review.md`	Все замечания закрыты

В `docs/plans/` (1 файл)

Откуда	Файл	Примечание
`docs/internal/`	`docs_restructuring_plan.md`	Этот план — активный; после выполнения → `docs/archive/`

В `docs/design/` (9 файлов из `docs/internal/`)

Файл	Роль
`PRD.md`	Стратегия продукта
`assignment_design.md`	Дизайн курсового задания
`naming_conventions.md`	Стандарт нейминга (единый источник)
`db_schema.md`	Схема БД всех слоёв DWH
`bookings_stg_design.md`	Дизайн STG-слоя
`bookings_ods_design.md`	Дизайн ODS-слоя
`bookings_dds_design.md`	Дизайн DDS-слоя
`bookings_dm_design.md`	Дизайн DM-слоя
`architecture_review.md`	Архитектурные решения (ADR)

В `docs/reference/` (5 файлов из `docs/internal/`)

Файл	Роль
`pxf_bookings.md`	PXF: настройка, проблемы
`bookings_tz.md`	Источник bookings-db
`bookings_db_issues.md`	Известные проблемы bookings-db
`bookings_generation_benchmark.md`	Бенчмарк генерации
`qa-plan.md`	План отладки пайплайна

Итог: docs/internal/ опустеет → удалить.

Фаза 3. Обновление перекрёстных ссылок

Категория A. Корневые и публичные файлы (ссылаются на `docs/internal/`)

Файл	Ссылок	Детали замен
`AGENTS.md`	2	строки 15, 45: `docs/internal/naming_conventions.md` → `docs/design/naming_conventions.md`
`TODO.md`	6	строки 6, 7, 43: → `docs/design/`; строка 121: → `docs/reference/pxf_bookings.md`; строка 128: → `docs/reference/bookings_db_issues.md`; строка 141: → `docs/archive/dim_routes_denormalization_plan.md`
`docs/README.md`	7	строки 18-24: все `internal/` → `design/` или `reference/*`
`docs/bookings_to_gp_stage.md`	2	строка 151: → `reference/pxf_bookings.md`; строка 156: → `archive/bookings_stg_code_review.md`
`docs/stack.md`	1	строка 85: → `reference/pxf_bookings.md`

Категория B. Файлы внутри `docs/design/` и `docs/reference/`

Полный реестр ссылок с docs/internal/ в файлах, которые переедут в design/ или reference/. Все требуют обновления — либо кросс-каталожные пути, либо display-тексты.

B1. Кросс-каталожные ссылки (ссылка ведёт в другой каталог — путь сломается):

Файл (→ design/)	Строка	Ссылка	Новый путь
`db_schema.md`	426	`bookings_tz.md` (отн.)	`../reference/bookings_tz.md`
`db_schema.md`	427	`pxf_bookings.md` (отн.)	`../reference/pxf_bookings.md`
`db_schema.md`	425	`bookings_stg_code_review.md` (отн.)	`../archive/bookings_stg_code_review.md`
`bookings_stg_design.md`	5	`docs/internal/bookings_tz.md`	`../reference/bookings_tz.md`
`bookings_stg_design.md`	130	`docs/internal/bookings_tz.md`	`../reference/bookings_tz.md`
`bookings_stg_design.md`	131	`docs/internal/pxf_bookings.md`	`../reference/pxf_bookings.md`

Файл (→ reference/)	Строка	Ссылка	Новый путь
`qa-plan.md`	10	`docs/internal/bookings_db_issues.md`	`bookings_db_issues.md` (тот же каталог)

B2. Внутрикаталожные, но с полным путём docs/internal/... (путь не сломается для ссылок с относительным target, но display-текст устареет):

Файл (→ design/)	Строки	Что обновить
`PRD.md`	209	`docs/internal/naming_conventions.md` → `docs/design/naming_conventions.md`
`bookings_ods_design.md`	48	display-текст `docs/internal/naming_conventions.md` → `docs/design/naming_conventions.md`
`bookings_dds_design.md`	8	`docs/internal/bookings_ods_design.md` → `docs/design/bookings_ods_design.md`
`bookings_dds_design.md`	185	display-текст `docs/internal/naming_conventions.md` → `docs/design/naming_conventions.md`
`bookings_dds_design.md`	828-829	`docs/internal/bookings_dds_design.md`, `docs/internal/db_schema.md` → `docs/design/...`
`bookings_dds_design.md`	945	`docs/internal/db_schema.md` → `docs/design/db_schema.md`
`bookings_dm_design.md`	279	`docs/internal/db_schema.md` → `docs/design/db_schema.md`
`bookings_dm_design.md`	283, 291	`docs/internal/bookings_dm_design.md` → `docs/design/bookings_dm_design.md`
`bookings_dm_design.md`	395	`docs/internal/naming_conventions.md` → `docs/design/naming_conventions.md`
`db_schema.md`	26	display-текст `docs/internal/naming_conventions.md` → `docs/design/naming_conventions.md`
`db_schema.md`	421-423	display-тексты `docs/internal/bookings_*_design.md` → `docs/design/...`
`architecture_review.md`	70	`docs/internal/bookings_dm_design.md` → `docs/design/bookings_dm_design.md`
`architecture_review.md`	146	`docs/internal/distribution_strategy.md` → удалить путь (файл не существует, оставить как текстовый backlog-пункт без ссылки)

Категория C. Ссылки на `educational-tasks.md`

Файл	Действие
`README.md` (корень)	Заменить ссылку на `educational-tasks.md` → `docs/assignment/`
`docs/README.md`	Заменить ссылку на `educational-tasks.md` → `assignment/`

Категория D. Файлы в `docs/archive/` — НЕ ТРОГАЕМ

Архивные файлы замораживаются. Ссылки внутри них могут быть битыми — это ожидаемо.

Комментарий в SQL

sql/dm/sales_report_ddl.sql строка 52: naming_conventions.md (без пути) — оставить как есть (комментарий, не ссылка; путь и так неточный).

Фаза 4. Актуализация содержания

Файл (новый путь)	Что сделать
`docs/design/architecture_review.md`	DM завершён (5/5 витрин), пометить выполненные P2; строка 146 — убрать путь к несуществующему `distribution_strategy.md`, оставить как текстовый backlog-пункт
`docs/design/db_schema.md`	Добавить DM-слой, убрать выполненный TODO
`TESTING.md`	Убрать артефакт «Docker-стенд не запускался»
`docs/dag_execution_order.md`	Добавить все 4 DDL DAG-а
`docs/reference/pxf_bookings.md`	Исправить нумерацию разделов (7→9→8→10 → последовательную)

Фаза 5. Обновление индексов и заглушка assignment

`docs/README.md`

Переписать структуру: разделы по каталогам (design/, reference/, plans/, archive/, assignment/). Включить ранее пропущенные документы: db_schema.md, dag_execution_order.md, e2e-etl-test-protocol.md, agent-dag-testing.md.

`README.md` (корень)

Заменить ссылку на educational-tasks.md → docs/assignment/, проверить остальные.

`docs/assignment/README.md` (новый файл)

Временная заглушка:

Указание, что курсовые задания появятся в Этапе 3
Ссылка на эталонный срез (DAG-и STG→ODS→DDS→DM) для самостоятельного изучения
Ссылка на docs/design/assignment_design.md для менторов

Фаза 6. Финальная проверка

Шаги выполняются строго по порядку:

make test — тесты проходят
make lint — стиль кода
Удалить пустой каталог docs/internal/
Перенести план из docs/plans/ в docs/archive/docs_restructuring_plan.md
grep по internal/ в живых .md файлах (rg --glob '!docs/archive/*') — нет битых ссылок
grep по educational-tasks в живых .md файлах (rg --glob '!docs/archive/*') — нет битых ссылок

Порядок выполнения

Фазы 1→2→3 делаются вместе (иначе ссылки будут битыми). Фаза 4 — независима, можно параллельно. Фаза 5 — после всех перемещений. Фаза 6 — в конце.

Что это даёт следующим этапам

Этап	Как помогает
Этап 2 (подготовка main)	Чистая структура — понятно, что удалять, что оставлять
Этап 3 (ТЗ от аналитика)	Готовый каталог `docs/assignment/` с заглушкой, место для `analyst_spec.md`
Этап 4 (валидационный DAG)	`docs/reference/qa-plan.md` — рядом с другими справочными
Этап 5 (ветка solution)	Архив отделён — не попадёт в ветку solution

13 KiB Raw Blame History Unescape Escape

План ревизии документации

Проблемы

Принципы

Фаза 1. Структура каталогов

Фаза 2. Перемещение файлов

В docs/archive/ (4 файла)

В docs/plans/ (1 файл)

В docs/design/ (9 файлов из docs/internal/)

В docs/reference/ (5 файлов из docs/internal/)