# 2026-07-02 — Миграция с deck-api на API Gateway (lk-api-gateway)

## Контекст

Старый API: `https://deck-api-{stand}.ngcloud.ru/api/v1/index.cfm?endpoint=/services/123`
Новый API Gateway: `https://lk-api-gateway-{stand}.ngcloud.ru/api/v1/svc/services/123`

Ответы JSON идентичны. Различается только формат URL:
- Старый: proxy через `index.cfm?endpoint=`
- Новый: прямые REST-пути

Цель: перевести TEST-стенд на новый Gateway, сохранив совместимость со старым для dev/prod.

## Архитектурное решение

Авто-детект режима по наличию `index.cfm` в URL:
- Есть `index.cfm` → старый proxy (`?endpoint=`)
- Нет `index.cfm` → новый REST (прямая конкатенация пути)

Один env-параметр `NUBES_API_ENDPOINT` управляет всем.

## Изменения (11 файлов)

### 1. Генератор YAML: `universal_rebuild/tools/service_spec_gen/generate_service_spec.go`
- `normalizeAPIEndpoint()` — убрано принудительное добавление `/index.cfm`, теперь только trim trailing slash
- `getViaProxy()` → `callAPI()` — авто-детект: если `index.cfm` в URL → `?endpoint=`, иначе → прямая конкатенация `{base}{path}`
- Добавлен метод `isProxyAPI()` для детекта
- Обновлён комментарий с документированием двух режимов

### 2. Ядро провайдера: `universal_rebuild/internal/core/client.go`
- Добавлены `isProxyAPI()` и `buildURL(path string) string` — единая точка конструирования URL
- Заменены все 4 места с хардкодом `?endpoint=`:
  - `FindExistingInstances` (пагинированный поиск, строка ~515)
  - `GetInstanceState` (строка ~590)
  - `GetInstanceStateRaw` (строка ~637)
  - `doRequest` (POST/PUT/GET, строки ~838-853)

### 3. Оркестратор YAML: `devops/01_generate_yamls.sh`
- Убрана принудительная нормализация `if [[ "$API_ENDPOINT" != */index.cfm ]]` → автоматическая
- Python-скрипт: авто-детект `"index.cfm" in endpoint` → `?endpoint=` vs прямой путь

### 4. Генератор документации: `devops/02_generate_resources_and_docs_v2.sh`
- Добавлена передача `-api-endpoint "$DOCS_API_ENDPOINT"` в `docs_template_gen_v2`
- Нормализация: если нет ни `index.cfm`, ни `/svc` → дописать `/index.cfm` (обратная совместимость)

### 5. Публикация доков: `devops/04_build_and_publish_docs.sh`
- `normalize_api_endpoint()` — убрано принудительное `/index.cfm`, только trim

### 6. Корневой скрипт: `01_generate_yamls.sh` (корень)
- Python-скрипт: такой же авто-детект, как в devops/01

### 7-8. Шаблоны документации: `docs_template_gen_v2/main.go` + `docs_template_gen/main.go`
- Добавлен флаг `-api-endpoint` (default: старый deck-api)
- Все хардкоды `api_endpoint = "https://deck-api...index.cfm"` заменены на `fmt.Sprintf`
- Проброшено через `writeResourceDocs` → `buildExamplePage` → `exampleBlock` → `buildSubresourceExamplePage`

### 9-10. Провайдеры: `internal/provider/provider.go` + `universal_rebuild/internal/provider/provider.go`
- Добавлен `TODO(api-gateway)` комментарий над дефолтным `apiEndpoint`
- Сам дефолт не менялся (runtime провайдера теперь использует `core.buildURL()`)

### 11. Профиль TEST: `devops/profiles/test/profile.env`
- `NUBES_API_ENDPOINT` → `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc`

### Бонус: версия в бинарник
- `devops/build-provider.sh`: `go build` теперь с `-ldflags "-X main.version=${VERSION}"` — версия из профиля вшивается в бинарник (раньше всегда была из main.go)

## Анализ пайплайна (попутно)

Полный пайплайн: `services_list.txt` → `01_generate_yamls.sh` → `02_generate_resources_and_docs_v2.sh` → `03_build_and_upload_provider.sh` → `04_build_and_publish_docs.sh`.

Найденные проблемы (не исправлялись, зафиксированы):
- `main.go` Address = `nubes-test` (только для test, для prod нужно `nubes`)
- Нет сборки под `darwin/arm64` (Apple Silicon)
- Корневой `01_generate_yamls.sh` ссылается на несуществующий `service_params_gen`
- Кросс-стадийная валидация отсутствует (сбои 01 не видны в 02)

## Оставшиеся `deck-api` в коде

Только как **значения по умолчанию** (переопределяются через `NUBES_API_ENDPOINT`):
- `service_spec_gen/generate_service_spec.go:150` — `getenvDefault("NUBES_API_ENDPOINT", "https://deck-api...")`
- `devops/01_generate_yamls.sh:108` — `${NUBES_API_ENDPOINT:-https://deck-api...}`
- `devops/02_generate_resources_and_docs_v2.sh:95` — аналогично
- `devops/04_build_and_publish_docs.sh:13,87` — аналогично
- `docs_template_gen_v2/main.go:91` — flag default
- `docs_template_gen/main.go:81` — flag default
- `internal/provider/provider.go:105` + `universal_rebuild/...` — с TODO

Хардкодов в теле функций/примеров больше нет.

## Для перехода dev/prod

Достаточно поменять одну строку в `profile.env`:
```
NUBES_API_ENDPOINT="https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc"   # dev
NUBES_API_ENDPOINT="https://lk-api-gateway.ngcloud.ru/api/v1/svc"       # prod
```

Всё остальное — авто-детект.