From e71171124e6e61667f392c641476f55ec93e09d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Fri, 24 Jul 2026 16:39:33 +0400
Subject: [PATCH] Docs: operation stages API + README links

---
 DOCS/api-operation-stages.md | 85 ++++++++++++++++++++++++++++++++++++
 README.md                    |  6 +++
 2 files changed, 91 insertions(+)
 create mode 100644 DOCS/api-operation-stages.md

diff --git a/DOCS/api-operation-stages.md b/DOCS/api-operation-stages.md
new file mode 100644
index 0000000..6786da6
--- /dev/null
+++ b/DOCS/api-operation-stages.md
@@ -0,0 +1,85 @@
+# Стадии выполнения операции (stages)
+
+## Эндпоинт
+
+```
+GET /instanceOperations/{operationUid}
+```
+
+## Поле `stages`
+
+В ответе `instanceOperation.stages` — массив объектов-стадий. Каждая стадия:
+
+| Поле | Тип | Описание |
+|------|-----|---------|
+| `instanceOperationStageUid` | UUID | UID стадии |
+| `stage` | string | Название (напр. `"2. Основной процесс"`) |
+| `isSuccessful` | bool/null | `true`/`false`/`null` (ещё не завершена) |
+| `dtStart` | datetime | Начало |
+| `dtFinish` | datetime/null | Окончание (`null` — ещё идёт) |
+| `duration` | float | Секунды (пересчитывается пока идёт: `729.2`) |
+| `stageMsg` | JSON-string/null | Детальные логи этапа |
+
+## Пример
+
+Запрос:
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" -H "User-Agent: Mozilla/5.0" \
+  "https://lk-api-gateway-test.ngcloud.ru/api/v1/svc/instanceOperations/{opUid}"
+```
+
+Ответ (фрагмент):
+```json
+{
+  "instanceOperation": {
+    "instanceOperationUid": "a955a902-...",
+    "operation": "create",
+    "isInProgress": false,
+    "isSuccessful": true,
+    "duration": 27.89,
+    "stages": [
+      {
+        "instanceOperationStageUid": "f88e28c9-...",
+        "stage": "1. Валидация",
+        "isSuccessful": true,
+        "dtStart": "2026-07-24T15:21:57.373+0300",
+        "dtFinish": "2026-07-24T15:22:01.804+0300",
+        "duration": 4.4,
+        "stageMsg": "[[\"Определение ресурсной платформы\",\"...\"],...]"
+      },
+      {
+        "stage": "2. Основной процесс",
+        "isSuccessful": true,
+        "duration": 14.1,
+        "stageMsg": "[[\"Установка сервиса\",\"...\"],...]"
+      },
+      {
+        "stage": "3. Проверки",
+        "isSuccessful": true,
+        "duration": 0.3
+      },
+      {
+        "stage": "4. Хранилище секретов",
+        "isSuccessful": null,
+        "dtFinish": null,
+        "duration": 729.2
+      }
+    ]
+  }
+}
+```
+
+## Использование для автотестов
+
+Для отображения прогресса в UI:
+
+1. Отправить операцию → получить `opUid`
+2. Поллинг: `GET /instanceOperations/{opUid}` каждые 2-3 секунды
+3. Пока `isInProgress == true` — показывать стадии из `stages[]`
+4. Когда `isInProgress == false` — проверить `isSuccessful`
+
+`stageMsg` содержит **JSON-строку** с массивом `[[заголовок, текст], ...]`. Можно распарсить и показать пользователю.
+
+## Открытие 2026-07-24
+
+Обнаружено при анализе ответа API во время сессии тестирования dummy-сервиса. Ранее поле `stages` пропускалось из-за большого размера ответа.
diff --git a/README.md b/README.md
index 5677376..4730954 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,12 @@
 
 Автотесты операций сервисов облачной платформы Nubes.
 
+## Документация API
+
+- [Обращение к API облака](DOCS/api-access.md) — эндпоинты, curl-примеры
+- [Полный поток CREATE](DOCS/api-create-flow.md) — схема, параметры, все ошибки
+- [Стадии выполнения операций](DOCS/api-operation-stages.md) — `stages[]` в ответе API
+
 ## Структура
 
 - `STANDS/` — YAML-конфигурации сервисов по стендам (dev, test)