tf_provider/docs/help/architecture-and-methods.md

Архитектура и методы (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 только при совпадении ключевых параметров.