add: HAR traces

2026-06-30 15:46:41 +04:00
parent 1a52506fb1
commit 250a8a6be2
940 changed files with 14409 additions and 0 deletions
@@ -0,0 +1,226 @@
+# Запрос на глубокий анализ — 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-запросы выполнить).
+
+**Важно:** Ничего НЕ ДЕЛАЙ в файловой системе. Никаких изменений кода, файлов, конфигов. Только анализ.