From d0c20f42a04a7850471cc48bb5132cec0dcc6576 Mon Sep 17 00:00:00 2001 From: Repinoid Date: Fri, 2 Oct 2026 08:05:12 +0300 Subject: [PATCH] =?UTF-8?q?docs(history):=20=D0=B7=D0=B0=D0=BF=D0=B8=D1=81?= =?UTF-8?q?=D1=8C=20=D0=BE=20=D0=BF=D1=80=D0=B0=D0=B2=D0=BA=D0=B0=D1=85=20?= =?UTF-8?q?=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D0=B8=20CRUD=20+=20=D0=BE=D0=B3=D0=BB=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D0=B5=20=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=BE=20HISTORY/50=5Fdocs/2026-10-02=5Fcrud=5Fdocs?= =?UTF-8?q?=5Fpage=5Fand=5Fmanual=5Fpages=5Fpipeline.md:=20-=20=D0=BF?= =?UTF-8?q?=D1=80=D0=B0=D0=B2=D0=BA=D0=B8=20README=20=D1=81=D1=82=D0=B5?= =?UTF-8?q?=D0=BD=D0=B4=D0=B0=20(5fdbc31=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5?= =?UTF-8?q?=D0=BB=20=C2=AB=D0=9A=D0=B0=D0=BA=20=D1=8D=D1=82=D0=BE=20=D1=83?= =?UTF-8?q?=D1=81=D1=82=D1=80=D0=BE=D0=B5=D0=BD=D0=BE=C2=BB=20=D0=B1=D0=B5?= =?UTF-8?q?=D0=B7=20=D0=BD=D0=B0=D1=82=D1=8F=D0=BD=D1=83=D1=82=D1=8B=D1=85?= =?UTF-8?q?=20=D1=82=D0=B5=D1=80=D0=BC=D0=B8=D0=BD=D0=BE=D0=B2,=20=20=206e?= =?UTF-8?q?f003b=20apply+destroy,=205674b86/b8f5238=20=D1=81=D0=BF=D1=80?= =?UTF-8?q?=D0=B0=D0=B2=D0=BA=D0=B0=20=D0=BF=D0=BE=20=D0=B2=D1=8B=D1=85?= =?UTF-8?q?=D0=BE=D0=B4=D0=B0=D0=BC=20pg=20=D0=B8=20=D0=BF=D0=B5=D1=80?= =?UTF-8?q?=D0=B5=D0=BD=D0=BE=D1=81=20=D0=B2=20=D0=BA=D0=BE=D0=BD=D0=B5?= =?UTF-8?q?=D1=86);=20-=20=D0=BF=D0=B5=D1=80=D0=B5=D0=BF=D0=B8=D1=81=D0=B0?= =?UTF-8?q?=D0=BD=D0=BD=D0=B0=D1=8F=20=D1=81=D1=82=D1=80=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D1=86=D0=B0=20=D1=81=D0=B0=D0=B9=D1=82=D0=B0=20curated/crud/th?= =?UTF-8?q?ree=5Fapps.md=20(ab9f7d2):=20=D1=82=D0=B0=D0=B1=D0=BB=D0=B8?= =?UTF-8?q?=D1=86=D0=B0=20=C2=AB=D0=B1=D1=8B=D0=BB=D0=BE=20->=20=D1=81?= =?UTF-8?q?=D1=82=D0=B0=D0=BB=D0=BE=C2=BB;=20-=20=D1=80=D0=B0=D0=B7=D0=B1?= =?UTF-8?q?=D0=BE=D1=80=20=D0=BF=D0=B0=D0=B9=D0=BF=D0=BB=D0=B0=D0=B9=D0=BD?= =?UTF-8?q?=D0=B0:=20=D1=87=D1=82=D0=BE=20=D0=BA=D0=BE=D0=BF=D0=B8=D1=80?= =?UTF-8?q?=D1=83=D0=B5=D1=82=D1=81=D1=8F=20=D0=B2=20docs=5Fdir=20(04:157-?= =?UTF-8?q?173),=20=D0=B7=D0=B0=D0=BF=D1=80=D0=B5=D1=82=20=D0=B8=D1=81?= =?UTF-8?q?=D0=BF=D0=BE=D0=BB=D1=8C=D0=B7=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20?= =?UTF-8?q?docs/=20=20=20=D1=86=D0=B5=D0=BB=D0=B8=D0=BA=D0=BE=D0=BC=20(04:?= =?UTF-8?q?94),=20docs=5Fdir=20=3D=20generated/<=D1=81=D1=82=D0=B5=D0=BD?= =?UTF-8?q?=D0=B4>/docs=20(04:95-98),=20nav/exclude=5Fdocs=20=20=20(mkdocs?= =?UTF-8?q?.yml:52=20=D0=B8=204-15),=20=D0=BF=D0=BE=D0=B4=D1=81=D1=82?= =?UTF-8?q?=D0=B0=D0=BD=D0=BE=D0=B2=D0=BA=D0=B0=20=D0=BF=D0=BB=D0=B5=D0=B9?= =?UTF-8?q?=D1=81=D1=85=D0=BE=D0=BB=D0=B4=D0=B5=D1=80=D0=BE=D0=B2=20(04:18?= =?UTF-8?q?2-198),=20=D0=BF=D1=83=D0=B1=D0=BB=D0=B8=D0=BA=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D1=8F=20(04:344);=20=20=20=D0=B4=D0=B2=D0=B0=20=D1=81?= =?UTF-8?q?=D0=BF=D0=BE=D1=81=D0=BE=D0=B1=D0=B0=20=D0=BF=D1=83=D0=B1=D0=BB?= =?UTF-8?q?=D0=B8=D0=BA=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20=D1=80=D1=83=D1=87?= =?UTF-8?q?=D0=BD=D1=8B=D0=B5=20=D1=81=D1=82=D1=80=D0=B0=D0=BD=D0=B8=D1=86?= =?UTF-8?q?=D1=8B:=20A=20(=D0=B2=20docs/curated=20+=20nav=20=E2=80=94=20?= =?UTF-8?q?=D1=81=D0=B4=D0=B5=D0=BB=D0=B0=D0=BD=D0=BE)=20=D0=B8=20=20=20B?= =?UTF-8?q?=20(=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82=D1=8C=20=D0=BA?= =?UTF-8?q?=D0=BE=D0=BF=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BD=D0=B8=D0=B5=20?= =?UTF-8?q?=D0=B2=2004=20=E2=80=94=20=D0=9D=D0=95=20=D1=81=D0=B4=D0=B5?= =?UTF-8?q?=D0=BB=D0=B0=D0=BD=D0=BE,=20=D0=B6=D0=B4=D1=91=D1=82=20=D0=BA?= =?UTF-8?q?=D0=BE=D0=BC=D0=B0=D0=BD=D0=B4=D1=8B);=20-=20=D1=80=D0=B0=D0=B7?= =?UTF-8?q?=D0=B4=D0=B5=D0=BB=20=C2=AB=D0=9C=D0=BE=D0=B8=20=D0=BE=D1=88?= =?UTF-8?q?=D0=B8=D0=B1=D0=BA=D0=B8=C2=BB:=20=D0=BD=D0=B5=D0=B2=D0=B5?= =?UTF-8?q?=D1=80=D0=BD=D1=8B=D0=B9=20=D1=82=D0=B5=D1=80=D0=BC=D0=B8=D0=BD?= =?UTF-8?q?=20decoupling,=20=D0=BE=D0=B4=D0=BD=D0=BE=D0=B1=D0=BE=D0=BA?= =?UTF-8?q?=D0=B0=D1=8F=20=D1=84=D0=BE=D1=80=D0=BC=D1=83=D0=BB=D0=B8=D1=80?= =?UTF-8?q?=D0=BE=D0=B2=D0=BA=D0=B0=20=D0=BF=D1=80=D0=BE=20destroy,=20=20?= =?UTF-8?q?=20=D1=81=D0=BA=D1=80=D1=8B=D1=82=D1=8B=D0=B9=20=D1=84=D0=B0?= =?UTF-8?q?=D0=BA=D1=82=20=D0=BF=D1=80=D0=BE=20=D1=80=D1=83=D1=87=D0=BD?= =?UTF-8?q?=D0=BE=D0=B9=20creds.json.=20HISTORY/README.md:=20=D1=81=D1=82?= =?UTF-8?q?=D1=80=D0=BE=D0=BA=D0=B0=20=D0=BD=D0=BE=D0=B2=D0=BE=D0=B9=20?= =?UTF-8?q?=D0=B7=D0=B0=D0=BF=D0=B8=D1=81=D0=B8=20=D0=B2=2050=5Fdocs,=20?= =?UTF-8?q?=D1=81=D1=87=D1=91=D1=82=D1=87=D0=B8=D0=BA=D0=B8=209->10=20?= =?UTF-8?q?=D0=B8=2075->76.=20=D0=9F=D1=80=D0=BE=D0=B2=D0=B5=D1=80=D0=B5?= =?UTF-8?q?=D0=BD=D0=BE:=20=D0=B2=2050=5Fdocs=2010=20=D1=84=D0=B0=D0=B9?= =?UTF-8?q?=D0=BB=D0=BE=D0=B2,=20=D0=B2=D1=81=D0=B5=D0=B3=D0=BE=2076=20?= =?UTF-8?q?=D1=84=D0=B0=D0=B9=D0=BB=D0=BE=D0=B2=20(=D0=BA=D1=80=D0=BE?= =?UTF-8?q?=D0=BC=D0=B5=20README),=20=D1=81=D1=87=D1=91=D1=82=D1=87=D0=B8?= =?UTF-8?q?=D0=BA=D0=B8=20=D1=81=D0=BE=D0=B2=D0=BF=D0=B0=D0=BB=D0=B8.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...rud_docs_page_and_manual_pages_pipeline.md | 88 +++++++++++++++++++ HISTORY/README.md | 5 +- 2 files changed, 91 insertions(+), 2 deletions(-) create mode 100644 HISTORY/50_docs/2026-10-02_crud_docs_page_and_manual_pages_pipeline.md 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 — стенды и примеры