<!-- ⛔ LEGACY: deck-api.ngcloud.ru ЗАКРЫВАЕТСЯ. Актуальный API: lk-api-gateway.ngcloud.ru/api/v1/svc -->
# Матрица состояний ресурсов в облаке ngcloud

## Основные параметры состояния

### 1. В структуре инстанса (instance object)

Каждый ресурс имеет следующие флаги:

| Параметр | Тип | Возможные значения | Описание |
|----------|-----|------------------|---------|
| `explainedStatus` | string | `running`, (другие?) | Основной объяснительный статус |
| `isCreated` | boolean | `true`, `false` | Был ли инстанс создан |
| `isDeleted` | boolean | `true`, `false` | Отмечен ли как удаленный |
| `isSuspended` | boolean | `true`, `false` | Приостановлен ли |
| `operationIsInProgress` | boolean | `true`, `false` | Идет ли корректная операция |
| `operationIsPending` | boolean | `true`, `false` | Есть ли ожидающие операции |
| `uptime` | number | >= 0 | Время работы в секундах (0, если не создан) |

### 2. Структура state (instanceState object)

```json
{
  "state": {
    "instanceStateUid": "uuid",
    "version": 1,          // версия состояния
    "dtState": "timestamp", // дата состояния
    "isTest": boolean
  }
}
```

### 3. Операции (operations array)

```json
{
  "operation": "create|modify|delete|suspend|resume",
  "dtSubmit": "timestamp",
  "dtStart": null,        // null если еще не началась
  "dtFinish": null,       // null если еще не закончилась
  "isSuccessful": null|true|false,  // null если не выполнялась
  "isInProgress": boolean,
  "isPending": boolean,
  "submitResult": "201|..."  // HTTP статус результата отправки
}
```

---

## МАТРИЦА СОСТОЯНИЙ

### ✅ СОСТОЯНИЕ: АКТИВНЫЙ РАБОЧИЙ ИНСТАНС (RUNNING)
```
isCreated=true
isDeleted=false
isSuspended=false
explainedStatus="running"
operationIsInProgress=false
operationIsPending=false
uptime > 0
state.version >= 1
```
**Значение:** Ресурс создан, работает, нет выполняющихся операций

---

### 🔄 СОСТОЯНИЕ: СОЗДАНИЕ В ПРОЦЕССЕ (CREATING)
```
isCreated=true (или может быть false на ранних стадиях)
isDeleted=false
isSuspended=false
operationIsInProgress=true
operationIsPending=false
state.version = 1
operations[0].operation = "create"
operations[0].isSuccessful = null (еще не завершено)
operations[0].dtStart != null
operations[0].dtFinish = null
```
**Значение:** Операция создания выполняется

---

### ⏸️ СОСТОЯНИЕ: ПРИОСТАНОВЛЕН (SUSPENDED)
```
isCreated=true
isDeleted=false
isSuspended=true
explainedStatus="suspended" (или может быть другое)
operationIsInProgress=false
```
**Значение:** Ресурс создан, но приостановлен (власт нет - suspend)

---

### ⏸️ СОСТОЯНИЕ: ПРИОСТАНОВКА В ПРОЦЕССЕ (SUSPENDING)
```
isCreated=true
isSuspended=false (еще не приостановлен)
operationIsInProgress=true
operations[last].operation = "suspend"
operations[last].isSuccessful = null
```
**Значение:** Операция приостановки выполняется

---

### ▶️ СОСТОЯНИЕ: ВОЗОБНОВЛЕНИЕ В ПРОЦЕССЕ (RESUMING)
```
isCreated=true
isSuspended=true (еще приостановлен)
operationIsInProgress=true
operations[last].operation = "resume"
operations[last].isSuccessful = null
```
**Значение:** Операция возобновления выполняется

---

### ❌ СОСТОЯНИЕ: НЕ СОЗДАН (NOT CREATED)
```
isCreated=false
isDeleted=false
isSuspended=false
state = null или пуст
uptime = 0
version = null или отсутствует
```
**Значение:** Ресурс был определен в коде, но никогда не создавался в облаке

---

### 🗑️ СОСТОЯНИЕ: УДАЛЕН (DELETED)
```
isDeleted=true
isCreated=true (был когда-то создан)
state.version может быть или не быть
```
**Значение:** Ресурс был удален, может оставаться в истории

---

### 🔄 СОСТОЯНИЕ: УДАЛЕНИЕ В ПРОЦЕССЕ (DELETING)
```
isCreated=true
isDeleted=false (еще не отмечен как удаленный)
operationIsInProgress=true
operations[last].operation = "delete"
operations[last].isSuccessful = null
```
**Значение:** Операция удаления выполняется

---

### 🔧 СОСТОЯНИЕ: ИЗМЕНЕНИЕ В ПРОЦЕССЕ (MODIFYING)
```
isCreated=true
isDeleted=false
operationIsInProgress=true
operations[last].operation = "modify"
operations[last].isSuccessful = null
```
**Значение:** Конфигурация ресурса изменяется

---

### ⏳ СОСТОЯНИЕ: ОПЕРАЦИЯ ОЖИДАЕТ (PENDING)
```
operationIsPending=true
operationIsInProgress=false
operations[last].dtStart = null (еще не началась, но создана)
operations[last].isSuccessful = null
```
**Значение:** Операция создана, но еще не началась (в очереди)

---

### ⚠️ СОСТОЯНИЕ: ОШИБКА ОПЕРАЦИИ (OPERATION_FAILED)
```
operations[last].isSuccessful=false
operations[last].dtFinish != null
operations[last].errorLog != null
operationIsInProgress=false
```
**Значение:** Последняя операция завершилась с ошибкой

---

### 🔀 СОСТОЯНИЕ: ГИБРИДНОЕ/ПЕРЕХОДНОЕ (HYBRID)

**Противоречивые комбинации указывают на переходное состояние:**
- `operationIsInProgress=true` + `operations[last].dtStart=null` → операция только создана, еще не началась
- `isCreated=true` + `operationIsPending=true` → есть ожидающая операция
- `state.version=null` + `isCreated=true` → некорректное состояние

---

## АЛГОРИТМ ОПРЕДЕЛЕНИЯ СОСТОЯНИЯ

### На уровне API (GET /api/v1/index.cfm/instances/{uid})

```python
def get_instance_state(instance_data):
    """
    instance_data = {
        'isCreated': bool,
        'isDeleted': bool,
        'isSuspended': bool,
        'explainedStatus': str,
        'operationIsInProgress': bool,
        'operationIsPending': bool,
        'uptime': float,
        'state': {...} or null,
        'operations': [...]
    }
    """
    
    # Шаг 1: Проверка удаления
    if instance_data['isDeleted']:
        return 'DELETED'
    
    # Шаг 2: Проверка создания
    if not instance_data['isCreated']:
        return 'NOT_CREATED'
    
    # Шаг 3: Проверка операции в процессе
    if instance_data['operationIsInProgress']:
        last_op = instance_data['operations'][-1] if instance_data['operations'] else None
        if last_op:
            operation_type = last_op.get('operation', 'unknown')
            return f'{operation_type.upper()}_IN_PROGRESS'
    
    # Шаг 4: Проверка ожидающей операции
    if instance_data['operationIsPending']:
        last_op = instance_data['operations'][-1] if instance_data['operations'] else None
        if last_op and not last_op.get('dtStart'):
            return 'OPERATION_PENDING'
    
    # Шаг 5: Проверка приостановки
    if instance_data['isSuspended']:
        return 'SUSPENDED'
    
    # Шаг 6: Проверка основного статуса
    if instance_data['explainedStatus'] == 'running':
        return 'RUNNING'
    
    # Шаг 7: Проверка ошибок в операциях
    if instance_data['operations']:
        last_op = instance_data['operations'][-1]
        if last_op.get('isSuccessful') == False:
            return 'OPERATION_FAILED'
    
    return 'UNKNOWN'
```

---

## РЕКОМЕНДУЕМЫЕ ЗАПРОСЫ К API

### Получить список ресурсов определенного типа

```bash
GET /api/v1/index.cfm/instances?fields=instanceConfigDtCreated,instanceUid,displayName,svc,uptime,explainedStatus,svcExtendedName,updaterLogin,updaterShortname,operationIsInProgress,operationIsPending,monitoringUrl&search={resource_name}&isAuxiliary=false&isDeleted=false
```

### Получить полную информацию о ресурсе

```bash
GET /api/v1/index.cfm/instances/{instance_uid}?fields=instanceConfigDtCreated,instanceUid,displayName,descr,svc,state,operations,availableOperations,uptime,isDeleted,updaterLogin,updaterShortname,explainedStatus,man,dependencies,dependentInstances,svcExtendedName
```

### Выполнить операцию

```bash
POST /api/v1/index.cfm/instanceOperations
Content-Type: application/json

{
  "instanceUid": "uuid",
  "operation": "create|modify|delete|suspend|resume"
}
```

### Получить статус операции

```bash
GET /api/v1/index.cfm/instanceOperations/{operation_uid}?fields=instanceOperationUid,instanceUid,state,stages,cfsParams,isSuccessful,dtCreated,dtUpdated,dtStart,dtFinish,operation,svcOperationId,svc,displayName,submitResult,duration,errorLog,updaterShortname,man,nestedRefData,isInProgress,isPending,dtSubmit
```

---

## ПРИМЕРЫ ИЗ HAR

### Пример 1: RUNNING инстанс
```json
{
  "displayName": "Newly Added",
  "isCreated": true,
  "isDeleted": false,
  "isSuspended": false,
  "explainedStatus": "running",
  "operationIsInProgress": false,
  "operationIsPending": false,
  "uptime": 1102.739073,
  "state": {
    "instanceStateUid": "48bfdbc5-e8fc-4286-8098-d6ab7f6de50e",
    "version": 2
  }
}
```

### Пример 2: CREATE_IN_PROGRESS инстанс
```json
{
  "displayName": "ttst00",
  "isCreated": true,
  "isDeleted": false,
  "isSuspended": false,
  "explainedStatus": "running",
  "operationIsInProgress": false,
  "operationIsPending": true,
  "uptime": 0,
  "operations": [
    {
      "operation": "modify",
      "dtSubmit": "2026-01-22T19:30:21.790+0300",
      "dtStart": null,
      "dtFinish": null,
      "isSuccessful": null,
      "isInProgress": false,
      "isPending": true
    }
  ]
}
```

### Пример 3: DELETE_IN_PROGRESS инстанс
```json
{
  "displayName": "ttt0-terraform",
  "isCreated": true,
  "isDeleted": false,
  "isSuspended": false,
  "operations": [
    {
      "operation": "delete",
      "dtSubmit": "2026-01-22T19:28:24.720+0300",
      "dtStart": null,
      "dtFinish": null,
      "isSuccessful": null
    }
  ]
}
```

---

## СВОДНАЯ ТАБЛИЦА ВОЗМОЖНЫХ СОСТОЯНИЙ

| Состояние | isCreated | isDeleted | isSuspended | operationIsInProgress | Описание |
|-----------|-----------|-----------|-------------|----------------------|---------|
| NOT_CREATED | false | false | false | false | Еще не создан |
| CREATING | true | false | false | true | Создание выполняется |
| RUNNING | true | false | false | false | Работает нормально |
| MODIFYING | true | false | false | true | Конфигурация изменяется |
| SUSPENDING | true | false | false | true | Приостановка выполняется |
| SUSPENDED | true | false | true | false | Приостановлен |
| RESUMING | true | false | true | true | Возобновление выполняется |
| DELETING | true | false | false | true | Удаление выполняется |
| DELETED | true | true | - | - | Удален |
| OPERATION_PENDING | true | false | - | false | Есть ожидающая операция |
| OPERATION_FAILED | true | false | - | false | Операция завершилась ошибкой |