# Соннет: анализ сравнительного тестирования Polygon ↔ реальный Nubes API

> Адресат: Claude Sonnet 4.6 (новый чат)
> ⛔ Режим: **диалог**. Задавай встречные вопросы если нужно уточнение.
> ⛔ НЕ редактировать файлы. Только анализ и советы в чат.

---

## Контекст

**Polygon** (v0.5.4) — эмулятор REST API облачной платформы Nubes.
3 стенда: dev (37 сервисов), test (37), prod (35). YAML-конфиги генерируются
из терраформ-репы (`~/tf_provider/generated/{dev,test,prod}/resources_yaml/`).

**Реальное API**:
- `https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc`
- `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc`
- `https://lk-api-gateway.ngcloud.ru/api/v1/svc`

Токены в `secrets/{dev,test,prod}.token`.

## Что сделано

Написан скрипт `compare_test.py` который сравнивает read-only эндпоинты
полигона и реального API:
- `GET /services` — список сервисов
- `GET /services/{id}` — операции (svcOperationId, operation, kind, action)
- `GET /instanceOperations/default/{id}` — cfsParams (id, код, dataType, isRequired)

Первый прогон показал:
- **dev**: операции совпадают, но у 2 параметров `dataType: None` вместо `"string"`
- **test**: аналогично
- **prod**: чисто, расхождений нет

Также обнаружено что реальный API возвращает HTML-entities в dataType
(`integer >= 0`), а полигон — чистый текст (`integer >= 0`).
Полигон здесь правильнее реального API.

## Ключевой нюанс: идеология стендов

Стенды НЕ идентичны. **Dev опережает test, test опережает prod**.
Новые сервисы и параметры появляются сначала в dev, потом через какое-то
время попадают в test, и только затем в prod. Поэтому:

- Если в dev-полигоне и dev-реальном API есть расхождения — это может быть
  нормально (реальный API уже обновился, а YAML в полигоне — ещё нет)
- Если в prod есть расхождения — скорее всего баг в генерации YAML
- Нужно различать «допустимое отставание» и «реальный баг»

## Что нужно от тебя

### 1. Стратегия сравнительного тестирования

Как правильно сравнивать полигон с реальным API учитывая что:
- Стенды могут и должны отличаться
- YAML генерируется не в реальном времени, а батчами из терраформа
- Некоторые сервисы есть в реальном API но НЕ в терраформе (их не тестируем)

Что должно считаться PASS, а что FAIL? Какие допуски?

### 2. Какие ещё эндпоинты сравнивать?

Сейчас сравниваются 3 read-only эндпоинта. Какие ещё можно безопасно
сравнять? Что ещё есть в реальном API такого что полигон должен
повторять один-в-один?

### 3. Периодичность и автоматизация

Как часто запускать сравнение? При каких событиях (изменение терраформа,
деплой полигона)? Должно ли это быть частью CI?

### 4. dataType: None

В `from_stands.py` для некоторых параметров dataType падает в None
(хотя дефолт "string"). Где конкретно искать причину?

### 5. Общие советы

Что ещё мы упускаем в тестировании полигона? Какие сценарии, краевые
случаи, проверки контрактов?

---

## Формат диалога

Ты можешь:
- Сразу дать развёрнутый ответ по всем пунктам
- Или задать уточняющие вопросы — и тогда я отвечу, а ты продолжишь

Я хочу чтобы в итоге получился **конкретный план действий**:
что тестировать, как часто, что считать ошибкой, что — допустимым
расхождением.

---

## Ответ Соннета (2026-08-02)

### 4. dataType: None — первопричина найдена

`dict.get(key, default)` возвращает `default` **только если ключ отсутствует**.
Если в YAML написано `data_type: null` — ключ *есть*, значение — `None`,
дефолт `"string"` не срабатывает.

### Мои ответы

**Q4.1 — data_type: null в YAML?** Проверил — в терраформ-YAML нет
`data_type: null`. Реальный API возвращает `dataType: null` для параметра
`nestedRefExample` (param 396). Полигон возвращает `"string"` — он ПРАВИЛЬНО
применяет дефолт там, где реальный API отдаёт null. Это не баг полигона,
а улучшение.

**Q4.2 — _convert_sub_params?** Та же уязвимость потенциально есть, но не
проявляется — sub_params всегда имеют data_type.

**Q1.1 — частота регенерации YAML?** ВРУЧНУЮ. `from_stands.py` запускается
человеком когда он вспомнит. Никакого cron/webhook.

**Q1.2 — лаг от реального API до YAML?** Непредсказуемо. От часов до недель.
Зависит от того когда кто-то запустит `from_stands.py`.

**Q1.3 — потребитель результатов?** Разработчик. Ему нужно знать «полигон
устарел, перегенери YAML», а не «полигон сломан».

**Q2.1 — дополнительные эндпоинты в реальном API?** Не проверял. Надо
сравнить полный список эндпоинтов.

**Q2.2 — lifecycle поля?** Не сравниваются в текущем compare_test.py. Надо
добавить.