doc: README для DOCS/HISTORY, polygon-docs/, +.venv в gitignore

2026-07-31 20:39:48 +04:00
parent 633537a775
commit 6978d13d0e
7 changed files with 850 additions and 0 deletions
@@ -0,0 +1,103 @@
+# Ссылки: генератор YAML (tf_provider)
+
+Репозиторий Terraform-провайдера Nubes: `~/tf_provider`
+
+## Как генерируются STANDS YAML
+
+| Файл | Описание |
+|------|----------|
+| `~/tf_provider/README.md` | Общий пайплайн: 4 шага генерации провайдера |
+| `~/tf_provider/docs/README.md` | **Главный индекс документации.** Формат токенов (не протухают), DDoS-Guard заголовки, Gateway URL |
+| `~/tf_provider/docs/HOWTO_ADD_NEW_SERVICE.md` | Как добавить сервис: `services_list.txt` → `01_generate_yamls.sh` → API → YAML |
+| `~/tf_provider/docs/ARCHITECTURE_NEW.md` | Архитектура: слои (core/provider/resources_gen/yaml), метод Виталия без instanceUid |
+| `~/tf_provider/docs/70_api/api-discovery-algorithms.md` | **Ключевой документ.** Алгоритм получения параметров: `/instanceOperations/default/{id}` → `cfsParams` с `dataDescriptor`, `valueList`, `isModifiable` |
+
+## Критические API-эндпоинты (метод Виталия)
+
+Цепочка из 3 запросов — получение ВСЕХ параметров сервиса без создания инстанса:
+
+1. `GET /api/v1/svc/services` → найти `svcId` по имени
+2. `GET /api/v1/svc/services/{svcId}` → найти `svcOperationId` операции (create: `{svc.operations[?operation=="create"].svcOperationId}`)
+3. `GET /api/v1/svc/instanceOperations/default/{svcOperationId}` → **все cfsParams**: `dataDescriptor` (подполя map-fixed), `valueList`, `isModifiable`, `isSensitive`, `regex`, ...
+
+### Почему `/instanceOperations/default/{id}` а не `/serviceOperation/{id}`:
+
+| Данные | `/serviceOperation/{id}` | `/instanceOperations/default/{id}` |
+|--------|--------------------------|-------------------------------------|
+| ID, code, тип, isRequired | ✅ | ✅ |
+| `valueList` (допустимые значения) | ❌ | ✅ |
+| `dataDescriptor` (подполя map-fixed) | ❌ | ✅ |
+| `isModifiable` | ❌ | ✅ |
+| `regex`, `maxLength`, `minValue`... | ❌ | ✅ |
+| `isSensitive` | ❌ | ✅ |
+
+### Формат valueList:
+
+- Для **верхнеуровневых** параметров: JSON-массив `["false", "true"]`
+- Для **подполей** dataDescriptor: comma-separated строка `"1,3,5,7"`
+
+## Где взять реальные ответы API (для сверки мока)
+
+```bash
+# Токены (НЕ протухают до декабря 2026):
+~/tf_provider/secrets/test.token
+~/tf_provider/secrets/dev.token
+~/tf_provider/secrets/prod.token
+
+# Проверить дату токена:
+python3 -c "
+import json,base64
+t=open('$HOME/tf_provider/secrets/test.token').read().split('.')
+d=json.loads(base64.urlsafe_b64decode(t[1]+'=='))
+from datetime import datetime,timezone
+print(datetime.fromtimestamp(d['exp'],tz=timezone.utc))
+"
+
+# Пример curl (test стенд):
+curl -s --max-time 10 \
+  -H "Authorization: Bearer $(cat ~/tf_provider/secrets/test.token)" \
+  -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
+  -H "Referer: https://deck-test.ngcloud.ru/" \
+  "https://lk-api-gateway-test.ngcloud.ru/api/v1/svc/instanceOperations/default/<opId>"
+```
+
+### ⛔ DDoS-Guard: ВСЕГДА нужны 3 заголовка
+
+**Без них — 403 Forbidden даже с валидным токеном.**
+
+```bash
+-H "Authorization: Bearer $TOKEN"
+-H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36"
+-H "Referer: https://deck-{stand}.ngcloud.ru/"
+```
+
+### URL стендов (Gateway)
+
+| Стенд | Gateway URL | Referer |
+|-------|-------------|---------|
+| test | `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc` | `https://deck-test.ngcloud.ru/` |
+| dev | `https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc` | `https://deck-dev.ngcloud.ru/` |
+| prod | `https://lk-api-gateway.ngcloud.ru/api/v1/svc` | `https://deck.ngcloud.ru/` |
+
+## Сгенерированные YAML (все стенды)
+
+| Стенд | Сервисов | Путь |
+|-------|----------|------|
+| dev | 50 | `~/tf_provider/generated/dev/resources_yaml/` |
+| test | 48 | `~/tf_provider/generated/test/resources_yaml/` |
+| prod | 46 | `~/tf_provider/generated/prod/resources_yaml/` |
+
+44 сервиса идентичны на всех трёх стендах.
+
+## Поток данных: API → polygon
+
+```
+API Nubes (реальный)
+  → 01_generate_yamls.sh
+  → ~/tf_provider/generated/test/resources_yaml/*.yaml
+  → копируются в STANDS/test/resources_yaml/ (autotest)
+  → from_stands.py конвертирует
+  → polygon/site/services/*.yaml
+  → config_loader.py загружает при старте
+  → polygon эмулирует /instanceOperations/default/{id}
+```