<!-- ⛔ LEGACY: deck-api.ngcloud.ru ЗАКРЫВАЕТСЯ. Актуальный API: lk-api-gateway.ngcloud.ru/api/v1/svc -->
# Архитектура и методы (CRUD)

## 1. Актуальная архитектура (универсальный rebuild)
- Ядро: universal_rebuild/internal/core (универсальный клиент API, общий flow операций).
- Провайдер: universal_rebuild/internal/provider (schema, конфигурация, подключение ресурсов).
- YAML-спеки сервисов: universal_rebuild/resources_yaml (источник истины).
- Генератор Go-ресурсов: universal_rebuild/tools/gen (читает YAML, генерирует ресурсы и реестр).

Ключевое правило: новая логика — только новые функции/файлы. Существующий Go-код не менять без согласования.

## 2. Источник параметров (discovery)
Параметры сервиса извлекаются через proxy endpoint API:
- /index.cfm?endpoint=/services/{svcId}
- /index.cfm?endpoint=/serviceOperation/{svcOperationId}
- (опц.) /index.cfm?endpoint=/param-value-list/{svcOperationCfsParamId}

Схема: сервис → операции → CFS параметры → YAML → генерация Go.

## 3. Универсальный Create (7 шагов)
1) POST /instances → instanceUid
2) POST /instanceOperations (create) → instanceOperationUid
3) GET /instanceOperations/{uid}?fields=cfsParams
4) POST /instanceOperationCfsParams для каждого параметра
5) GET /instanceOperations/{uid}/validate-cfs
6) POST /instanceOperations/{uid}/run с payload {}
7) Polling до завершения операции

Критично: параметры отправляются все, включая дефолты, иначе бэкенд может упасть на валидации.

## 4. Read/Adopt
- При isDeleted или explainedStatus=deleted — state очищается.
- При статусе `running` adopt допускается только при `adopt_existing_on_create=true`.
- При статусе `suspend` допускается `resume` только при совпадении основных параметров.
- Предупреждения показываются только на create и не мешают managed ресурсам.

## 5. Update/Modify
- IDs параметров на modify отличаются от create.
- Нельзя хардкодить ID, нужно получать manifest операции и строить маппинг.
- Если modify отсутствует в availableOperations — выдавать ясную ошибку.

## 6. Polling (железные правила)
- Завершение операции определяется только по dtFinish.
- После dtFinish результат определяется isSuccessful.
- Для VM применяется двойной контроль: статус операции + статус инстанса (ERROR/STOPPED).

## 7. Нормализация типов
- map/json → "{}"
- list/array → "[]"
- Пустые строки в JSON-параметрах запрещены (валидаторы на plan).

## 8. Soft Delete и карантин
- Для тяжёлых ресурсов delete часто заменён на suspend с периодом удержания.
- Для сервисов с `suspend`/`resume` действует флаг `suspend_on_destroy`:
	- `true` (default) -> выполнять `suspend`;
	- `false` -> удалять только из Terraform state (без API-вызова).
- Повторный apply при `suspend` может выполнять `resume` только при совпадении ключевых параметров.