add: documentation

docs/help/architecture-and-methods.md

@@ -0,0 +1,56 @@
+# Архитектура и методы (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` только при совпадении ключевых параметров.