Docs: operation stages API + README links

2026-07-24 16:39:33 +04:00
parent d5ccf61f84
commit e71171124e
2 changed files with 91 additions and 0 deletions
@@ -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` пропускалось из-за большого размера ответа.