# Universal Rebuild — Архитектура и рабочая цепочка (актуально)

Документ для нового чата: описывает, как устроено «универсальное ядро», как формируются YAML‑спеки сервисов и как генерируются Go‑ресурсы. Учитывает ошибки/уроки из текущего чата.

---

## 0) Базовые правила работы
- Не менять существующий Go‑код без явного согласования.
- Новая логика — только новые функции/файлы (если не было явного разрешения на правку).
- Все операции с облаком — read‑only, если отдельно не разрешено создание/удаление.
- Для токенов: новый `access_token` сохранять в `/home/naeel/terra/HH-MM-SS.token`.

---

## 1) Архитектура (слои)

### 1.1 Универсальное ядро (core)
**Папка:** `universal_rebuild/internal/core`
- `client.go` — универсальный клиент API и общий flow операций.
- **Критерий завершения операции:** `dtFinish` (см. комментарии в коде). Логику запрещено менять без согласования.

### 1.2 Провайдер (provider)
**Папка:** `universal_rebuild/internal/provider`
- Конфигурация провайдера, получение токена, подключение ресурсов через реестр.

### 1.3 Сгенерированные ресурсы
**Папка:** `universal_rebuild/internal/resources_gen`
- Автогенерируемые ресурсы Terraform по YAML‑спецификациям.
- `registry.go` (генерируется) — регистрирует все ресурсы.
- `crud.go` — общие CRUD‑хелперы (создание/modify/delete). Этот файл **не генерируется**, его нужно сохранять.

### 1.4 YAML‑спеки ресурсов
**Папка:** `universal_rebuild/resources_yaml`
- YAML для каждого сервиса. Источник истины для генератора ресурсов.
- Формат включает `create.params`, `modify.params`, `lifecycle`.

### 1.5 Генераторы
- **YAML‑генератор без instanceUid**
  - `universal_rebuild/tools/service_params_gen/main.go`
  - Получает параметры сервиса напрямую через `/index.cfm?endpoint=...`.
- **Go‑генератор**
  - `universal_rebuild/tools/gen/main.go`
  - Читает YAML и генерирует ресурсы + `registry.go`.

---

## 2) Как получить параметры сервиса (без instanceUid)

Источник описан в:
- `docs/40_analysis/har/discovery/service_parameters_fetch.md`

API‑цепочка:
1) `GET /api/v1/index.cfm?endpoint=/services/{svcId}`
   - даёт список операций сервиса (`operations`)
2) `GET /api/v1/index.cfm?endpoint=/serviceOperation/{svcOperationId}`
   - даёт `cfsParams` (id, code, type, required, default, valueList, refSvcId, func)
3) (опц.) `GET /api/v1/index.cfm?endpoint=/param-value-list/{svcOperationCfsParamId}`

**Почему так:** прямых эндпойнтов на список параметров по `service_id` нет. Параметры извлекаются из описаний операций.

---

## 3) YAML‑генерация (service_params_gen)

**Файл:** `universal_rebuild/tools/service_params_gen/main.go`

Входные переменные:
- `NUBES_API_TOKEN` (если не задан — берётся из `test_universal/terraform.tfvars`)
- `NUBES_API_ENDPOINT` (по умолчанию `https://deck-api.ngcloud.ru/api/v1/index.cfm`)
- `NUBES_SERVICE_ID` (обязателен)
- `NUBES_SERVICE_NAME` (опц.)
- `NUBES_OUTPUT` (опц.)

Пример:
```bash
cd /home/naeel/terra/universal_rebuild
NUBES_SERVICE_ID=1 NUBES_SERVICE_NAME=dummy go run ./tools/service_params_gen/main.go
```

Результат:
- `/home/naeel/terra/universal_rebuild/resources_yaml/dummy.yaml`

---

## 4) Go‑генерация (tools/gen)

**Файл:** `universal_rebuild/tools/gen/main.go`

Что делает:
- читает все YAML из `resources_yaml/`
- генерирует ресурсы в `internal/resources_gen/`
- генерирует `registry.go`

Команда:
```bash
cd /home/naeel/terra/universal_rebuild
go run ./tools/gen/main.go
```

---

## 5) Build

```bash
cd /home/naeel/terra/universal_rebuild
go build -o terraform-provider-nubes
```

---

## 6) Важные нюансы и ошибки (из опыта чата)

### 6.1 resourceRealm
- `resourceRealm` **должен задаваться пользователем в .tf**, если параметр required.
- Нельзя автоподставлять `serviceName` как realm: API отклонит (пример с Postgres).

### 6.2 Warnings о дубликатах
- Предупреждение о `RESOURCE WITH SAME NAME EXISTS` должно появляться только на create (когда state.ID отсутствует).
- Для managed ресурсов (ID уже есть) предупреждения быть не должно.

### 6.3 Deleted ресурсы
- Если `explainedStatus=deleted` или `isDeleted=true` → ресурс считается отсутствующим, state должен очищаться.

### 6.4 Имена параметров
- Генератор может создавать «разбитые» snake_case для CamelCase (например `resource_c_p_u`).
- Это ожидаемо, но если критично — нужен отдельный маппинг (по согласованию).

---

## 7) Проверенная цепочка (dummy)

1) YAML:
```bash
NUBES_SERVICE_ID=1 NUBES_SERVICE_NAME=dummy go run ./tools/service_params_gen/main.go
```
2) Go‑код:
```bash
go run ./tools/gen/main.go
```
3) Build:
```bash
go build -o terraform-provider-nubes
```

---

## 8) Что делать дальше
- Повторять пункты 3–5 для каждого сервиса:
  - `NUBES_SERVICE_ID=13 NUBES_SERVICE_NAME=bucket`
  - `NUBES_SERVICE_ID=90 NUBES_SERVICE_NAME=postgres`
- Проверять YAML на корректность required‑параметров, `resourceRealm` и defaults.
- Поднимать ресурсы в `.tf` и тестировать: create / modify / suspend / delete.

---

## 9) Где искать доп. материалы
- Архитектура (старые, но полезные):
  - `docs/ai_universal_provider_gen.md`
  - `docs/00_overview/ai_universal_provider_gen.md`
- API discovery:
  - `docs/40_analysis/har/discovery/service_parameters_fetch.md`

---

**Короткая формула:**
`API (services → serviceOperation)` → `YAML` → `Go resources + registry` → `build` → `tests`.

---

## 10) Политика удаления (карантин)
- Многие инстансы **нельзя удалять сразу**: из-за возможных данных действует **2‑недельный карантин**.
- **Dummy** подпадает под эту политику.
- Для `nubes_dummy` при **destroy** или удалении из манифеста выполняется **`suspend`**, а не `delete`.
- При `apply`, если инстанс dummy в состоянии **suspend**, выполняется **`resume`**.