doc: типовой сценарий — 8 шагов с jq, поиск сервиса/операции/параметров

polygon-docs/POLYGON-FULL.md

@@ -260,6 +260,75 @@ def _set_stand():
 | POST | `/api/v1/svc/_mock/delay/{s}` | Задать задержку операций (max 5s) | `{delay: N}` |
 | POST | `/api/v1/svc/_mock/fail-next` | Следующая операция упадёт (one-shot) | `{fail_next: true}` |
 
+### Типовой сценарий: создать инстанс и запустить операцию
+
+Это основной флоу, который повторяет логику реального облачного API.
+Все примеры — с jq для наглядности, но работают и с `python3 -m json.tool`.
+
+**Шаг 1. Узнать ID сервиса по имени:**
+
+```bash
+curl -s "$URL/services" | jq '.results[] | select(.svc == "НазваниеСервиса") | .svcId'
+```
+
+**Шаг 2. Узнать ID операции у этого сервиса:**
+
+```bash
+curl -s "$URL/services/$SVC_ID" | jq '.svc.operations[] | select(.operation == "create") | .svcOperationId'
+```
+
+**Шаг 3. Получить список входных параметров (cfsParams):**
+
+```bash
+curl -s "$URL/instanceOperations/default/$OP_ID" | jq '.svcOperation.cfsParams[] | {svcOperationCfsParamId, svcOperationCfsParam, dataType, valueList, isRequired}'
+```
+
+Ответ показывает для каждого параметра: числовой ID, код, тип данных, список допустимых значений (если есть), обязательность.
+
+**Шаг 4. Создать инстанс:**
+
+```bash
+curl -s -X POST "$URL/instances" \
+  -H "Content-Type: application/json" \
+  -d '{"serviceId": '$SVC_ID', "displayName": "мой тестовый инстанс"}' \
+  | jq '.instanceUid'
+```
+
+**Шаг 5. Создать операцию:**
+
+```bash
+curl -s -X POST "$URL/instanceOperations" \
+  -H "Content-Type: application/json" \
+  -d '{"instanceUid": "'$INST_UID'", "operation": "create", "svcOperationId": '$OP_ID'}' \
+  | jq '.instanceOperationUid'
+```
+
+**Шаг 6. Установить параметры (повторить для каждого):**
+
+```bash
+curl -s -X POST "$URL/instanceOperationCfsParams" \
+  -H "Content-Type: application/json" \
+  -d '{"instanceOperationUid": "'$OP_UID'", "svcOperationCfsParamId": '$PARAM_ID', "paramValue": "значение"}'
+```
+
+**Шаг 7. Проверить валидацию и запустить:**
+
+```bash
+# Проверить что все параметры валидны (200 = OK)
+curl -s -o /dev/null -w "%{http_code}" "$URL/instanceOperations/$OP_UID/validate-cfs"
+
+# Запустить операцию (будет ждать DELAY секунд)
+curl -s -X POST "$URL/instanceOperations/$OP_UID/run" | jq '{ok, error}'
+```
+
+**Шаг 8. Проверить результат:**
+
+```bash
+curl -s "$URL/instanceOperations/$OP_UID?fields=dtFinish,isSuccessful" | jq '.instanceOperation | {dtFinish, isSuccessful}'
+```
+
+Полигон полностью повторяет эту последовательность: те же эндпоинты, те же поля, те же статус-коды (201 при создании, 409 при повторном run, 404 при несуществующем ресурсе).
+
 ### Валидация входных данных
 
 - `serviceId` — только integer > 0 (строка/float/отрицательное → 400)