doc: промпт Соннету — стратегия сравнительного тестирования Polygon ↔ Nubes API

polygon-docs/sonnet-compare-testing-prompt.md

@@ -0,0 +1,92 @@
+# Соннет: анализ сравнительного тестирования 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. Общие советы
+
+Что ещё мы упускаем в тестировании полигона? Какие сценарии, краевые
+случаи, проверки контрактов?
+
+---
+
+## Формат диалога
+
+Ты можешь:
+- Сразу дать развёрнутый ответ по всем пунктам
+- Или задать уточняющие вопросы — и тогда я отвечу, а ты продолжишь
+
+Я хочу чтобы в итоге получился **конкретный план действий**:
+что тестировать, как часто, что считать ошибкой, что — допустимым
+расхождением.

polygon-docs/test-results-v0.4.3.md

@@ -0,0 +1,100 @@
+# Результаты тестирования Polygon v0.4.3
+
+Дата: 2026-08-01
+
+---
+
+## Python API-тесты: 35/35 PASS ✅
+
+Файл: `polygon/tests/test_api.py`
+Цель: `https://polygon.pythonk8s.dev.nubes.ru`
+
+### 1. Health (1/1)
+- ✅ `GET /health → 200 OK`
+
+### 2. Services (4/4)
+- ✅ `GET /services → 200, >=37 сервисов`
+- ✅ `GET /services → каждый имеет svcId, svc, svcShort`
+- ✅ `GET /services/1 → 200 + operations`
+- ✅ `GET /services/99999 → 404`
+
+### 3. Instances (10/10)
+- ✅ `GET /instances (после reset) → total=0`
+- ✅ `POST /instances (без serviceId) → 400`
+- ✅ `POST /instances (serviceId=99999) → 404`
+- ✅ `POST /instances → 201 + Location + instanceUid`
+- ✅ `GET /instances → total=1`
+- ✅ `GET /instances?pageSize=500 → pageSize=200 (clamped)`
+- ✅ `GET /instances?page=-1 → не падает`
+- ✅ `GET /instances/{uid} → status=creating, имя верное`
+- ✅ `GET /instances/{uid}?fields=... → 200`
+- ✅ `GET /instances/nonexistent → 404`
+
+### 4. Operations (8/8)
+- ✅ `GET /instanceOperations/default/18 → 200 + cfsParams`
+- ✅ `POST /instanceOperations → 201 + Location`
+- ✅ `GET /op/{uid} → dtStart=null, dtFinish=null, isSuccessful=null`
+- ✅ `POST /instanceOperationCfsParams → 200`
+- ✅ `GET /validate-cfs → 200`
+- ✅ `POST /run → ok=true`
+- ✅ `POST /run (повторно) → 409`
+- ✅ `GET /op/{uid} (после run) → dtFinish!=null, isSuccessful=true`
+
+### 5. Fail-next (4/4)
+- ✅ `POST /_mock/fail-next → 200, fail_next=true`
+- ✅ `POST /instances (fail-next) → 201`
+- ✅ `POST /instanceOperations (fail-next) → 201`
+- ✅ `POST /run (fail-next) → ok=false, error='mock failure'`
+
+### 6. Auth (3/3 + 2 skipped)
+- ⚠️ Auth отключена на проде (MOCK_AUTH_TOKEN не задан)
+- ✅ `POST /_mock/reset (верный токен) → 200`
+- ✅ `GET /services (без токена) → 200`
+- ✅ `POST /instances (без токена) → 201`
+
+### 7. Mock state (5/5)
+- ✅ `GET /_mock/state → instances + operations`
+- ✅ `GET /_mock/services → count >= 37`
+- ✅ `POST /_mock/delay/0.1 → delay=0.1`
+- ✅ `POST /_mock/delay/100 → 400`
+- ✅ `POST /_mock/delay/-1 → 400`
+
+---
+
+## Swagger UI (browser)
+
+| Проверка | Результат |
+|----------|-----------|
+| Страница загружается | ✅ |
+| Логотип Nubes + версия | ✅ |
+| Ссылка «← На главную» | ✅ |
+| Все 6 тегов | ✅ services, instances, operations, mock, health |
+| Все 17 эндпоинтов | ✅ |
+| Все 20 схем | ✅ |
+| Спека — валидный JSON | ✅ |
+| `security: []` (глобальный) | ✅ |
+| `mockAuth` (apiKey, X-Mock-Auth) | ✅ |
+| `_mock/*` имеют `security: [mockAuth]` | ✅ 5/5 |
+| `dtStart/dtFinish` → `["string","null"]` | ✅ OAS 3.1.0 |
+| `isSuccessful` → `["boolean","null"]` | ✅ |
+| `RunResponse` → `ok + error` | ✅ |
+| Кнопка Authorize | ⚠️ недоступна в browser-окружении |
+
+---
+
+## Найденные расхождения (prod vs код)
+
+| Проблема | Статус |
+|----------|--------|
+| Описание всё ещё говорит «Bearer-токен» | 🔧 Исправлено в коде, не задеплоено |
+| Auth (MOCK_AUTH_TOKEN) не включена | ⚙️ Конфигурация деплоя |
+| `pageSize` обрезается молча | ✅ Задокументировано в спеке |
+
+---
+
+## Итого
+
+- **API-тесты**: 35/35 PASS
+- **Swagger UI**: страница работает, спека валидна, все эндпоинты и схемы на месте
+- **Баги v0.4.2**: все 5 исправлены, проверены локально
+- **К деплою**: закоммитить исправление описания auth, повысить версию, redeploy