doc: 54 устаревших файла -> LEGACY.*, README обновлён

Актуальные (4): ARCHITECTURE.md, howto-flask-nubes.md, polygon-plan.md, sonnet-app-autotest-review-v1.2.39.md Всё остальное — исторические артефакты v1.0.x/v1.1.x, старые ревью, промпты.
2026-08-04 08:28:06 +04:00
parent 8d111a05e1
commit 4e899b8d36
54 changed files with 30 additions and 95 deletions
@@ -0,0 +1,108 @@
+# Обращение к API облака
+
+## Базовые URL
+
+| Стенд | URL |
+|-------|-----|
+| dev | `https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc` |
+| test | `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc` |
+| prod | `https://lk-api-gateway.ngcloud.ru/api/v1/svc` |
+
+## Аутентификация
+
+Bearer-токен в заголовке: `Authorization: Bearer <TOKEN>`
+
+Токены лежат в `secrets/`:
+- `secrets/dev.token`
+- `secrets/test.token`
+- `secrets/prod.token`
+
+## ⚠️ ОБЯЗАТЕЛЬНО: User-Agent
+
+**Без `User-Agent: Mozilla/5.0` вернёт Forbidden!** DDoS-Guard блокирует curl по умолчанию.
+
+## Примеры curl
+
+```bash
+URL="https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc"
+TOKEN=$(tr -d '\n' < secrets/dev.token)
+UA="Mozilla/5.0"
+
+# Список сервисов
+curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services | jq '.results[] | {svcId, svc}'
+
+# Детали сервиса (все операции)
+curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services/90 | jq '.svc.operations[] | {svcOperationId, operation}'
+
+# Полные параметры операции (valueList, dataDescriptor, isModifiable)
+curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/instanceOperations/default/19 | jq '.svcOperation.cfsParams[]'
+```
+
+## Получение параметров сервиса (как в YAML-генераторе)
+
+3 шага:
+
+```bash
+URL="https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc"
+TOKEN=$(tr -d '\n' < secrets/dev.token)
+UA="Mozilla/5.0"
+
+# Шаг 1: найти svcId по имени
+curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services | jq '.results[] | select(.svc == "PostgreSQL") | .svcId'
+
+# Шаг 2: найти svcOperationId для операции "create"
+curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services/90 | jq '.svc.operations[] | select(.operation == "create") | .svcOperationId'
+
+# Шаг 3: получить параметры (с valueList, dataDescriptor)
+curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/instanceOperations/default/19 | jq '.svcOperation.cfsParams[]'
+```
+
+## Ключевые эндпоинты
+
+| Метод | Путь | Назначение |
+|-------|------|------------|
+| GET | `/services` | Список сервисов |
+| GET | `/services/{svcId}` | Детали + операции |
+| GET | `/instances` | Инстансы пользователя |
+| GET | `/instanceOperations/default/{svcOperationId}` | **Полные параметры** (valueList, dataDescriptor, isModifiable) |
+## Эндпоинты (полный список)
+
+| Метод | Путь | Назначение |
+|-------|------|------------|
+| GET | `/services` | Список сервисов |
+| GET | `/services/{svcId}` | Детали + операции |
+| GET | `/instances?pageSize=200&page=N` | Инстансы (пагинация!) |
+| GET | `/instanceOperations/default/{svcOperationId}` | **Полные параметры** (valueList, dataDescriptor, isModifiable) |
+| POST | `/instances` | Создать инстанс → Location: instanceUid |
+| POST | `/instanceOperations` | Создать операцию → Location: opUid |
+| POST | `/instanceOperationCfsParams` | Задать параметр операции |
+| POST | `/instanceOperations/{opUid}/run` | **Запустить операцию** (обязательно!) |
+
+## Поток CREATE
+
+См. подробный документ: [`api-create-flow.md`](api-create-flow.md)
+
+```
+1. GET  /services/{svcId}                          → svcOperationId для "create"
+2. GET  /instanceOperations/default/{svcOpId}      → параметры
+3. POST /instances                                  → instanceUid (из Location)
+4. POST /instanceOperations                         → opUid (из Location)
+5. POST /instanceOperationCfsParams (×N)            → задать параметры
+6. POST /instanceOperations/{opUid}/run            → ЗАПУСК
+7. GET  /instances?pageSize=200 (поллинг)           → ждать running
+```
+
+## ⚠️ Важно
+
+- `/instanceOperations/default/{id}` даёт **полные** параметры (valueList, dataDescriptor, isModifiable)
+- `/serviceOperation/{id}` даёт **базовые** параметры (без valueList и dataDescriptor) — НЕ использовать
+- Все параметры `--max-time 10` обязательны — чтобы не висло
+- Токен **без** переносов строк: `tr -d '\n'`
+- **UUID в Location — uppercase** (не lowercase как в БД)
+- **displayName должен быть уникальным** — добавлять timestamp
+- **`/run` обязателен!** Без него операция не стартует (auto-start только в UI)
+- **Array параметры — JSON-строка:** `"[\"test\"]"`, не голый массив
+- **Все paramValue — строки:** даже числа и булевы
+- **Пустое тело = `{}`:** никогда не слать `null` (DDoS-Guard режет)
+- **Пагинация:** инстансов может быть >200, проверять page=1, page=2...
+- **DDoS-Guard:** с локальной машины может не работать, curl через ВМ 213 (`ssh naeel@5.172.178.213`)