diff --git a/HISTORY/50_docs/2026-10-02_crud_docs_page_and_manual_pages_pipeline.md b/HISTORY/50_docs/2026-10-02_crud_docs_page_and_manual_pages_pipeline.md new file mode 100644 index 0000000..9fb0c91 --- /dev/null +++ b/HISTORY/50_docs/2026-10-02_crud_docs_page_and_manual_pages_pipeline.md @@ -0,0 +1,88 @@ +# 2026-10-02 — Страница CRUD-стенда на сайте + как публикуются ручные страницы + +> Команды владельца: «пропиши это на сайт документации» → «как сделать чтобы подобные +> разработанные вручную страницы заливались тоже, при генерации документации? посмотри» +> → «документируй это / и чтобы было понятно где искать! в ридми хистори пропиши». + +## Зачем эта запись + +Зафиксировать три вещи: (1) правки README стенда `TEST_STAND/CRUD/` по замечаниям владельца, +(2) переписанную страницу сайта `docs/curated/crud/three_apps.md`, (3) разбор пайплайна — +какие **ручные** страницы вообще попадают на сайт документации и как добавить остальные. +Плюс собственные ошибки в формулировках (раздел 4) — по приказу документировать всё. + +## 1. Правки README стенда (`TEST_STAND/CRUD/README.md`) + +Три круга правок: + +| Коммит | Что сделано | +|---|---| +| `5fdbc31` | Из раздела «Как это устроено» убрано «(разделение ответственности, decoupling)»: это термины про модули кода, а не про состояния Terraform. Написано прямо — «два отдельных файла состояния Terraform». Добавлен факт, который ранее был скрыт: связь `pg/` → `apps/` идёт через файл `apps/creds.json`, поэтому после смены хоста или пароля его нужно обновить и повторить `apply` в `apps/` | +| `6ef003b` | Формулировка была однобокой — говорилось только про удаление. Владелец поймал: «И дестрой И апплай !!! почему только УДАЛЯЕТ?». Теперь явно: `terraform apply` и `terraform destroy` в `apps/` меняют только приложения; `terraform apply` и `terraform destroy` в `pg/` меняют только базу | +| `5674b86`, `b8f5238` | Добавлен раздел «Справка: выходные параметры `pg/`»: состав шести выходов, вид JSON (`{sensitive, type, value}` — поэтому в `apps/locals.tf` берётся `.value`), таблица «выход → переменная окружения» для Flask / Node.js / Lucee. Сначала раздел вставлен в шаг 2, затем по команде владельца перенесён в конец файла (в шаге 2 он мешал последовательности трёх шагов) | + +Все факты сверены чтением файлов: `pg/outputs.tf`, `pg/main.tf`, `pg/postgres.tf`, +`pg/postgres_user_db.tf`, `apps/locals.tf`, `apps/lucee.tf`, `apps/flask.tf`, `apps/nodejs.tf`. + +## 2. Страница сайта: `docs/curated/crud/three_apps.md` (коммит `ab9f7d2`) + +Страница описывала **старую схему** и была неверна. Что изменено: + +| Было | Стало | +|---|---| +| «всё в одной папке, нужны два `apply`» | два каталога (`pg/` + `apps/`) и три шага: `pg/` → `terraform output -json > ../apps/creds.json` → `apps/` | +| пароль читался из `vault_secrets` кластера через `try(...)` | пароль — выход подресурса `nubes_postgres_user` (см. `HISTORY/20_releases/2026-10-01_release_subresource_password_output.md`) | +| имена `crud-lucee` / `crud-flask` / `crud-nodejs` | `lucee-crud` / `flask-crud` / `nodejs-crud` | +| путь `TEST_STAND/CRUD/locals.tf` | `TEST_STAND/CRUD/apps/locals.tf` | +| «состояние на 2026-10-01: все 6 ресурсов созданы, сервисы `running`» | снято (непроверяемое утверждение в документации) | +| «Аналог — `DEV_STAND/CRUD/`» | сказано прямо, что там **старая плоская схема** (`flask.tf`, `lucee.tf`, … в одной папке, без `pg/`+`apps/`) | + +Добавлены разделы «Структура манифестов» и «Справка: выходные параметры `pg/`» — те же, что +в README стенда. Сохранены проверенные особенности примера: `adopt_existing_on_create`, +`keep_on_destroy`, уникальность доменов, `postgres_conf` (`paramName`/`paramValue`), нехватка +ёмкости `realm`. Добавлен факт про `SERVICE_NAME` (значение колонки `created_by`). + +Проверено: 191 строка; строк с открывающим `` ``` `` — 16, то есть блоки кода парные. + +## 3. Как ручные страницы попадают на сайт (разбор; изменений не делал) + +| Факт | Источник | +|---|---| +| В сборку копируются только `docs/30_registry/*`, `docs/curated/*` и картинки `docs/diagrams/` (`.svg`, `.png`) | `TOOLS/scripts/04_build_and_publish_docs.sh:157-173` | +| Каталог `docs/` целиком в сборку **не** идёт — по явному запрету в коде | `TOOLS/scripts/04_build_and_publish_docs.sh:94` | +| `docs_dir` для MkDocs — это `generated/<стенд>/docs` | `TOOLS/scripts/04_build_and_publish_docs.sh:95-98` | +| Меню задаёт `nav`, внутренние разделы вырезаны `exclude_docs` | `mkdocs.yml:52`, `mkdocs.yml:4-15` | +| Плейсхолдеры `{{VERSION}}`, `{{NAMESPACE}}`, `{{NUBES_API_ENDPOINT}}`, `{{DASHBOARD_URL}}`, `{{PROVIDER_SOURCE}}`, `{{REGISTRY_HOST}}` подставляются во **все** `.md` внутри `docs_dir`, включая скопированные вручную | `TOOLS/scripts/04_build_and_publish_docs.sh:182-198` | +| Публикация: `./scripts/publish-docs.sh site `; отдельная страница — `scripts/publish-doc-page.sh` | `TOOLS/scripts/04_build_and_publish_docs.sh:344` | + +Отсюда два способа публиковать «подобные» (написанные вручную) страницы: + +- **A. Держать страницу в `docs/curated/` или `docs/30_registry/` и добавить строку в `nav`.** + Правок кода не требуется — именно так сделано с CRUD-стендом: страница уже была в `nav` + (`mkdocs.yml:64`), потребовалась только перезапись её содержимого. +- **B. Оставить файл на месте** (например `TEST_STAND/*/README.md`, `HOW_TO/*`) и добавить в `04` + ещё одно правило копирования — скажем, `TEST_STAND/*/README.md` → + `generated/<стенд>/docs/stands/<имя>.md`, плюс строки в `nav`. Тогда README уезжает на сайт + автоматически, без дублирования текста. + +**Вариант B не делался** — правка `04` и `mkdocs.yml` ждёт отдельной команды владельца +(вопрос задан, ответа ещё не было). Публикацию сайта не запускал: это деплой, только по команде. + +## 4. Мои ошибки в этой работе + +- Разделение `pg/` + `apps/` назвал «разделение ответственности, decoupling» — терминологически + неверно (это про модули кода) и заумно. Владелец: «пиши ПРАВИЛЬНО, не надо натягивать заумности». + Верное объяснение — два отдельных файла состояния; причина разнесения — разные жизненные циклы. +- Написал «`terraform destroy` в `apps/` удаляет только приложения», забыв про `apply` — + формулировка однобокая. +- В README скрыл факт, что связь между состояниями **ручная** (файл `creds.json`), и подал это + как полную независимость. + +## Связанные документы + +- `HISTORY/60_stands/2026-07-21_crud_stand_three_apps.md` — исходный CRUD-стенд (три приложения). +- `HISTORY/60_stands/2026-10-01_test_crud_pg_create_failure.md` — сбои создания `nubes_postgres.main_pg` в TEST. +- `HISTORY/50_docs/2026-09-02_full_docs_pipeline_analysis.md` — разбор пайплайна документации. +- `HISTORY/50_docs/2026-10-02_s3_static_website_docs_hosting.md` — хостинг документации из S3 (тот же день). +- `DOCS_PIPELINE/README.md` — актуальное описание сборки и публикации. +- Правленые файлы: `TEST_STAND/CRUD/README.md`, `docs/curated/crud/three_apps.md`. diff --git a/HISTORY/README.md b/HISTORY/README.md index db8f6fd..5c02981 100644 --- a/HISTORY/README.md +++ b/HISTORY/README.md @@ -15,11 +15,11 @@ | [`20_releases/`](20_releases/) | Заливки версий в реестр, чистки реестра, нумерация версий | 8 | | [`30_provider/`](30_provider/) | Ядро провайдера: архитектура, модификаторы, UUID, nested-атрибуты | 6 | | [`40_generator/`](40_generator/) | Генератор YAML/спеки, формат MAN, dev-генератор | 3 | -| [`50_docs/`](50_docs/) | Документация: пайплайн сборки, навигация, ссылки, публикация, хостинг | 9 | +| [`50_docs/`](50_docs/) | Документация: пайплайн сборки, навигация, ссылки, публикация, хостинг | 10 | | [`60_stands/`](60_stands/) | Стенды и примеры: CRUD, FullPipe, Штурвал, TEST_STAND | 7 | | [`70_infra/`](70_infra/) | Инфраструктура: реестр, API Gateway, DDoS-Guard, VPN/213, зеркала | 4 | | [`90_llm/`](90_llm/) | Диалоги и промпты с LLM, не привязанные к одной теме | 36 | -| Итого | | **75** | +| Итого | | **76** | ### Соглашения @@ -88,6 +88,7 @@ | `2026-09-03_docs_upload_pipeline_verified.md` | Проверенный pipeline публикации документации | | `2026-09-03_test_prod_docs_published.md` | Публикация документации TEST и PROD | | `2026-10-02_s3_static_website_docs_hosting.md` | Хостинг документации: S3 static website на RGW — находки и версии развития (V0→V1→V2) | +| `2026-10-02_crud_docs_page_and_manual_pages_pipeline.md` | Страница CRUD-стенда на сайте: правки README стенда, переписанная `docs/curated/crud/three_apps.md`, разбор «какие ручные страницы попадают на сайт и как добавить остальные» (`04:157-173`, `mkdocs.yml:52`) | ## 60_stands — стенды и примеры