From 9bf1bb215ccd61783b55a45910201e71f1697449 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Sun, 2 Aug 2026 06:37:36 +0400
Subject: [PATCH] =?UTF-8?q?doc:=20=D1=80=D0=B0=D0=B7=D0=B2=D1=91=D1=80?=
 =?UTF-8?q?=D0=BD=D1=83=D1=82=D0=BE=D0=B5=20=D0=BE=D0=B1=D1=8A=D1=8F=D1=81?=
 =?UTF-8?q?=D0=BD=D0=B5=D0=BD=D0=B8=D0=B5=20=E2=80=94=20=D0=BE=D1=82=D0=BA?=
 =?UTF-8?q?=D1=83=D0=B4=D0=B0=20YAML,=20=D0=B7=D0=B0=D1=87=D0=B5=D0=BC=20f?=
 =?UTF-8?q?rom=5Fstands.py,=20=D0=BA=D0=BE=D0=B3=D0=B4=D0=B0=20=D0=B7?=
 =?UTF-8?q?=D0=B0=D0=BF=D1=83=D1=81=D0=BA=D0=B0=D1=82=D1=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 50da03b..227b9c4 100644
--- a/README.md
+++ b/README.md
@@ -49,17 +49,62 @@ cd site && python app.py                          # порт 5000
 pytest tests/ -v                                  # 19 тестов
 ```
 
-## Обновление YAML из terraform
+## Откуда берутся сервисы (YAML)
 
-**Вручную** — при каждом изменении в `~/tf_provider/generated/`:
+Polygon эмулирует API Nubes. Чтобы знать какие сервисы, операции и параметры
+существуют — он читает YAML-конфиги. Но Nubes генерит YAML в **другом формате**,
+неудобном для полигона. Поэтому есть двухэтапный процесс:
+
+```
+~/tf_provider/generated/{dev,test,prod}/resources_yaml/*.yaml   ← источник (терраформ)
+        │
+        │  from_stands.py  —  конвертация формата, дедупликация, нормализация
+        │  Запускается ВРУЧНУЮ при изменении терраформ-репы
+        │
+        ▼
+polygon/site/services/{dev,test,prod}/*.yaml   ← скоммичены в git-репу полигона
+        │
+        │  config/loader.py  —  загрузка ВСЕХ YAML в память при старте
+        │
+        ▼
+Память Flask-процесса  (~0.7 MB на 3 стенда)
+```
+
+### Почему нельзя читать терраформ-формат напрямую?
+
+Терраформ-формат хранит параметры **внутри** операций, с дубликатами.
+Например параметр `resourceRealm` повторяется в create, modify и delete —
+три копии одного и того же.
+
+Полигону нужен плоский список **уникальных** параметров (`cfsParams`),
+плюс индекс «какой параметр к какой операции» (`cfsParamsByOp`).
+Плюс `stateParams` (дефолты для create), `stateOut` (subresource-ключи),
+раскодированные HTML-entities (`&quot;` → `"`).
+
+Всё это делает `from_stands.py` **один раз**, а не на лету при каждом запросе.
+
+### Когда запускать обновление?
+
+Когда терраформ-репа обновилась (добавили/удалили сервис, изменили параметры) —
+нужно перегенерить YAML и передеплоить полигон:
 
 ```bash
 cd site
 python from_stands.py ~/tf_provider/generated/dev/resources_yaml  services/dev
 python from_stands.py ~/tf_provider/generated/test/resources_yaml services/test
 python from_stands.py ~/tf_provider/generated/prod/resources_yaml services/prod
-cd .. && git add services/ && git commit -m "regenerate YAML" && git push
-# → редеплоить через Nubes
+
+cd ..
+git add services/
+git commit -m "regenerate YAML from terraform (добавлен сервис X)"
+git push
+# → редеплоить polygon через Nubes UI
+```
+
+### Как проверить что всё загрузилось?
+
+```bash
+curl https://polygon.pythonk8s.dev.nubes.ru/dev/api/v1/svc/services | python3 -m json.tool | head -20
 ```
 
 ## API (17 эндпоинтов)