# Запрос на глубокий анализ — Terraform Provider for Nubes Cloud

## Контекст

Проект — **Terraform Provider** для облачной платформы **Nubes Cloud** (Taffy/Deck API). 
Провайдер написан на Go с использованием `terraform-plugin-framework` (SDK v2).

**Версия:** 5.0.52  
**Тип:** Universal Provider — один core-движок, ресурсы генерируются из YAML-спек.

---

## Структура проекта

### Папки (корень: `/home/naeel/tf_provider/`)

```
internal/
├── core/               # Универсальный клиент API (client.go, instance_ops.go, instance_lookup.go)
├── provider/           # Реализация провайдера и НЕ-сгенерированных ресурсов (VM, Edge, VDC, VApp, Postgres, S3 и др.)
├── generated/          # Сгенерированные bolvan-ресурсы
└── registrykeys/       # Ключи для GPG-подписи

universal_rebuild/      # Новая универсальная архитектура (ядро, генераторы, YAML-спеки)
├── internal/
│   ├── core/           # Универсальный клиент (client.go) — v6 API flow
│   ├── provider/       # Конфиг провайдера
│   ├── resources_core/ # CRUD-логика (crud.go), хелперы, валидация, реф-параметры
│   └── resources_gen/  # АВТОМАТИЧЕСКИ СГЕНЕРИРОВАННЫЕ ресурсы (~100 файлов)
├── tools/
│   ├── gen/            # Go-генератор (читает YAML → генерирует ресурсы + registry.go)
│   ├── gen_v2/         # Версия 2 генератора
│   ├── service_params_gen/  # YAML-генератор (API → YAML)
│   ├── docs_template_gen/   # Генератор документации
│   └── service_spec_gen/    # Генератор спек
└── resources_yaml/     # YAML-спеки (сейчас только embed.go — встраиваются в бинарник)

devops/                 # Скрипты сборки и деплоя
├── config/
│   ├── services_list.txt           # Список всех сервисов (30+ строк)
│   └── operation_timeouts.json     # Таймауты операций по сервисам
├── 01_generate_yamls.sh           # Шаг 1: YAML из API
├── 02_generate_resources_and_docs*.sh  # Шаг 2: генерация Go + docs
└── 03_build_and_upload_provider.sh     # Шаг 3: сборка + публикация

docs/                   # Документация
├── 00_overview/        # Обзор
├── 20_discovery/       # Discovery сервисов
├── 30_registry/        # Реестр ресурсов
├── 40_analysis/        # Анализы и форензика
├── 50_history/         # История (23 файла — пошагово весь процесс разработки)
├── 60_strategy/        # Стратегия и философия провайдера
├── 70_api/             # API-документация и дампы
└── help/               # Справка
```

---

## Что уже сделано и известно

### Архитектура API (Taffy/Deck)

**Базовый URL:** `https://deck-api.ngcloud.ru/api/v1/index.cfm`

**Жизненный цикл операции:**
1. `POST /instances` — создать placeholder инстанса → получаем `instanceUid`
2. `POST /instanceOperations` — создать операцию (create/modify/suspend/resume/delete) → `instanceOperationUid`
3. `GET /instanceOperations/{uid}?fields=cfsParams` — получить схему параметров
4. `POST /instanceOperationCfsParams` — отправить значения параметров (каждый параметр по `svcOperationCfsParamId`)
5. `GET /instanceOperations/{uid}/validate-cfs` — валидация
6. `POST /instanceOperations/{uid}/run` — запуск операции
7. `GET /instanceOperations/{uid}` — поллинг до `dtFinish` (критерий завершения)

**Получение состояния инстанса:** `GET /instances/{instanceUid}` → `explainedStatus`, `isDeleted`, `availableOperations`

**Получение списка инстансов:** `GET /instances?page=N&size=100`

### Список сервисов (30+)
Сервисы с service_id от 1 до 150:
- Инфраструктурные: vcOrg(19), vc_vdc(21), vc_nsxt(22), vc_vm(23/27/28), vapp(26), vcexternalip(25), vcVdcGroup(29)
- Базы данных: postgres(90), mariadb(115), mongodb(92), redis(91), clickhouse(120), vmpostgre(32), kafka(116)
- Хранилища: s3(12), s3bucket(13)
- Приложения: nextcloud(50), superset(81), harbor(82), flask(89), lucee(94), nodejs(95), pgadmin(96), nodered(97), http(98), gitea(99), rabbitmq(93), nifi(117), openwhisk(100)
- DNS: dnszone(110), dnsrecord(111)
- K8s: k8s_sthutrval_cluster(150)
- Прочее: dummy(1), template(2), tenant(112), vcComplex(113), GiteaComplex(114), akhq(119), valoTenant(149)

### Lifecycle-логика (для сервисов с suspend/resume)
- **Флаги:** `adopt_existing_on_create` (default: false), `suspend_on_destroy` (default: true)
- **Apply/Create:** проверка облака по `resource_name` → статус-матрица принятия решений
- **Destroy:** по умолчанию suspend, при `suspend_on_destroy=false` — только state
- **Modify:** через `RunInstanceOperationUniversal` с params по `svcOperationCfsParamId`
- **Replace:** запрещён для suspend-сервисов

### Проблемы, известные из истории
1. **Case-sensitivity имён** (docs/60_strategy/terraform_case_sensitivity_fix.md)
2. **Ref-параметры и валидация на adopt** (docs/60_strategy/adopt_ref_validation.md)
3. **VApp UID inconsistency / displayName resolve bug** (история 23)
4. **Subresource generation** — не все подресурсы корректно генерируются
5. **Params normalisation** — CamelCase → snake_case может ломаться
6. **Postgres immutables** — некоторые параметры нельзя менять после создания (ForceNew)
7. **Operation timeouts** — разные сервисы требуют разных таймаутов
8. **Deleted instances** — определение deleted через `explainedStatus` и `isDeleted`
9. **Валидация статусов** — `not created`, `pending`, `failed` должны блокировать adopt
10. **ResourceAlreadyExists diagnostics** — обязательны два варианта в сообщении

### Архитектура universal_rebuild (ключевые особенности)
- **Ядро (core)**: UniversalClient — универсальный клиент, `CreateGenericInstanceUniversalV6`, `RunInstanceOperationUniversal`, `FindInstanceByDisplayName`
- **Resources_core**: `CreateResource`, `UpdateResource`, `DeleteResource`, `RunOperationByCode` — обёртки CRUD с timeout override
- **Resources_gen**: ~100 автогенерированных файлов ресурсов (все сервисы)
- **Генераторы**: `service_params_gen` → YAML, `gen/gen_v2` → Go код, `docs_template_gen` → документация
- **YAML-спеки**: сейчас встраиваются через embed.go, но есть YAML-генератор

### Генерация (devops pipeline)
1. `01_generate_yamls.sh` — получает YAML из API для всех сервисов из `services_list.txt`
2. `02_generate_resources_and_docs*.sh` — запускает Go-генератор + docs-генератор
3. `03_build_and_upload_provider.sh` — сборка под 3 ОС + GPG-подпись + загрузка в S3
4. `04_build_and_publish_docs.sh` — сборка mkdocs + публикация в S3

### Документация
- MkDocs Material theme
- Документация генерируется из тех же YAML-спек
- Публикуется в S3 bucket `terraform-registry`

---

## Что НУЖНО изучить подробно

### 1. API: неизвестные эндпойнты и возможности
- Есть ли другие эндпойнты, кроме задокументированных?
- Как работает `/services/{svcId}/default` (deprecated — что вместо)?
- Есть ли batch-операции?
- Пагинация: какие лимиты? Есть ли курсор?
- Rate limiting: есть ли? Какие лимиты?
- Есть ли эндпойнт для массового получения всех инстансов с параметрами?

### 2. Параметры сервисов (svcOperationCfsParamId)
Для каждого сервиса:
- Полный список `cfsParams` (все операции: create, modify, suspend, resume, delete, action)
- Какие параметры required, какие optional, какие read-only (outputs)
- Какие параметры имеют `refSvcId` (ссылки на другие сервисы)
- Какие параметры имеют `valueList` (выпадающие списки)
- DataType: какие бывают (string, boolean, list, uuid, int, float, json?)
- Default values — откуда берутся?
- Какие параметры immutable (create-only)
- Какие параметры зависят от других (dependency chain)

### 3. Статусы и состояния инстансов
- Все возможные значения `explainedStatus`
- Все возможные значения `isDeleted`
- Матрица переходов (state machine):
  - `creating` → `running`
  - `running` → `suspend` → `running`
  - `running` → `deleted`
  - `failed` → ?
  - `not created` → ?
- Что происходит при `pending` / `operation in progress`?
- Как долго длятся типичные операции?

### 4. Операции (kinds и их семантика)
- `kind: instance` — полный CRUD
- `kind: subresource` — операции внутри инстанса (create_user, delete_database и т.д.)
- `kind: action` — одноразовые операции (restart, redeploy, recovery)
- Для каждого сервиса: какие subresource и action операции доступны?
- Как subresource идентифицируются? (через parent instanceUid? свой instanceUid?)
- Есть ли операции, которые не вписываются в схему?

### 5. Схема YAML-спек
- Нужно восстановить формат YAML для примера одного-двух сервисов (dummy, postgres, s3bucket)
- Какие поля обязательны? Какие опциональны?
- Как описываются operations с kind-ами?
- Как описываются timeout-ы?
- Как описываются outputs?
- Как описываются service_man (руководство пользователя)?
- Как описываются lifecycle-правила (suspend_on_destroy, adopt_existing_on_create)?

### 6. Ошибки и проблемы продакшена
- Все известные баги из истории (23 файла в docs/50_history/)
- Какие ресурсы сейчас не работают? (VApp UID, Postgres immutables и т.д.)
- Какие тесты падают или неполны?
- Есть ли проблемы с GPG-ключами / реестром?
- Есть ли проблемы с S3-публикацией?

### 7. Тестовое покрытие
- Какие тесты написаны в `universal_rebuild/internal/resources_core/`?
- Есть ли интеграционные тесты с реальным API?
- Какие тесты нужны, но отсутствуют?
- Есть ли моки для API?

### 8. Безопасность
- Как управляются токены? Какой механизм refresh?
- Есть ли поддержка разных эндпойнтов (prod/dev)?
- Как обрабатываются чувствительные данные (пароли БД, ключи)?
- Есть ли валидация входящих параметров на injection?

### 9. Производительность
- Сколько времени занимает типичный apply?
- Есть ли узкие места в поллинге?
- Оптимальные интервалы поллинга для разных операций?
- Есть ли кэширование?

### 10. Документация (MkDocs)
- Как генерируется документация из YAML?
- Как работает шаблонизация?
- Что надо исправить/дополнить?

---

## Формат ответа

Пожалуйста, предоставь детальный анализ по каждому из 10 пунктов. Для каждого пункта:
1. **Текущее понимание** (что уже известно из контекста)
2. **Пробелы в знаниях** (чего не хватает)
3. **Гипотезы** (что можно предположить на основе имеющихся данных)
4. **Что нужно сделать** (конкретные шаги: какие файлы прочитать, какие API вызвать, какие тесты запустить)
5. **Риски** (какие проблемы могут возникнуть)

Особое внимание удели:
- Формату YAML-спек (п.5) — это основа всей генерации
- Полному списку cfsParams для топ-10 сервисов (п.2)
- Матрице состояний (п.3) — критично для lifecycle-логики
- Ошибкам из истории (п.6) — чтобы не повторять

Если для какого-то пункта информации в предоставленном контексте недостаточно — укажи это и предложи, где искать недостающие данные (какие файлы прочитать, какие curl-запросы выполнить).

**Важно:** Ничего НЕ ДЕЛАЙ в файловой системе. Никаких изменений кода, файлов, конфигов. Только анализ.