# Запрос на полный анализ autotest — для нового чата с агентом

Дата: 2026-07-30
Версия: v1.1.48

---

## 1. ЧТО ЭТО ЗА ПРОЕКТ

**autotest** — веб-приложение для автоматизированного тестирования сервисов платформы Nubes (Cloud Director). Позволяет запускать операции (create/modify/delete/suspend/resume/redeploy) над инстансами сервисов через Nubes REST API, отслеживать статус, вести историю запусков.

Приложение запущено на тестовом стенде: `atest.pythonk8s.dev.nubes.ru`

**Стек:**
- Backend: Flask 3.0 + gunicorn (multi-worker)
- DB: PostgreSQL 17 (Zalando Operator), схемы: `runs`, `scenario_runs`, `scenario_definitions` (pending)
- Frontend: ванильный JS (один файл `app.js`, 550 строк), Jinja2-шаблон
- Nubes REST API: `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc`
- Аутентификация: JWT-токен (cookie или env), автоопределение стенда (dev/test)
- Деплой: Nubes pythonk8s, кластер iot-naeel

**Автор:** naeel (tazetdinovn@gmail.com, WZ03709)
**Репозитории:**
- `https://gitea.services.ngcloud.ru/forcloud/app-autotest` — код приложения
- `https://gitea.services.ngcloud.ru/forcloud/autotest` — документация, YAML-описания сервисов

---

## 2. АРХИТЕКТУРА — ФАЙЛЫ И ИХ РОЛИ

### site/app.py — точка входа
Flask-приложение, регистрирует blueprint'ы:
- `main_bp` — главная страница, токен, инфраструктура
- `api_test_bp` — основной API (run/params/status/log/history)
- `api_scenario_bp` — API сценариев (run/status/CRUD — pending)
- `api_bp` — **УДАЛЁН в v1.1.45** (legacy: /api/run, /api/status, /api/config)
- VERSION — меняется при КАЖДОМ изменении

### site/api/http_client.py — HTTP-клиент
- `HttpClient` — обёртка над requests.Session
- GET: `raise_for_status()` → `.json()`, пустой ответ → `{}`
- POST: `json=data`, извлекает Location-заголовок → `_location` в ответе
- `raw_delete(url)` — DELETE без auth (для CMDB API)
- `detect_endpoint(token)` — автоопределение стенда (dev→test)
- `stand_name(endpoint)` — "dev"/"test" по URL

### site/api/auth.py — аутентификация
- `get_token()` — из cookie или env
- `get_client()` — HttpClient с автостендом
- `get_client_id()` — ClientID из JWT
- `get_stand()` — "dev"/"test"
- `get_token_info()` — {email, company, client_id}

### site/routes/main.py — главная страница
- `GET/POST /` — Jinja2-рендер: организация, инфраструктура, сервисы, форма токена
- `GET /api/operations/<svc_id>` — cloud-first инстансы + tracked-fallback
- `_resolve_instance_status()` — explainedStatus из облака или "creating" из трекера

### site/routes/api_test.py — ОСНОВНОЙ API (400 строк)
Эндпоинты:
- `GET /api/services` — список сервисов
- `GET /api/instances/list` — все инстансы
- `GET /api/params/<op_id>[?instanceUid=xxx]` — параметры операции (текущие или шаблон)
- `POST /api/test` — запуск операции (CREATE или non-CREATE)
- `GET /api/test/status/<op_uid>` — поллинг
- `GET /api/log` — логи
- `GET /api/history` — история из БД

Ключевые функции:
- `_send_params_terraform()` — шаги 3-7 Terraform (cfsParams → resolveRefSvc → send → validate)
- `_normalize_value()` — normalizeUniversalValueV6 (Terraform-equivalent)
- `_resolve_ref_svc()` — автоподстановка UUID инстанса для refSvcId-параметров
- `_finish_op()` — фоновый поллинг до dtFinish, сохранение в БД
- `_redact_params()` — замена secret/password/token на ***
- `_unique_display_name()` — проверка на дубликат + суффикс
- `_find_uid(resp)` — извлечение UUID из вложенных dict
- `_uid_from_location(loc)` — извлечение UUID из Location-заголовка

### site/routes/api_scenario.py — API СЦЕНАРИЕВ (90 строк)
- `GET /api/scenarios` — список из config.yaml (должен быть переключён на БД)
- `POST /api/scenario/run` — запуск (создаёт запись ДО потока, возвращает run_id + 202)
- `GET /api/scenario/run/<int:run_id>` — статус конкретного запуска
- `GET /api/scenario/status` — последние 10 запусков (legacy, должен уйти)

### site/operations/scenario.py — ЯДРО СЦЕНАРИЕВ (290 строк)
- `run_scenario()` — главный исполнитель:
  1. service имя → svc_id (из config.yaml services)
  2. operation имя → svcOperationId (GET /services/{id})
  3. param коды → numeric IDs (GET /instanceOperations/default/{opId})
  4. create: новый инстанс; остальные: переиспользовать instance_map
  5. POST /instances → POST /instanceOperations → _send_params_terraform → run → poll
  6. Сохранить в runs (RUNNING до API, финальный после) + scenario_runs
- `_resolve_service()` — поиск svc_id по символическому имени
- `_resolve_params()` — symbolic codes → numeric IDs
- `_find_uid()`, `_uid_from_location()` — ДУБЛИКАТЫ из api_test.py (!)
- `_save_scenario_run()` — UPDATE scenario_runs
- `_create_scenario_run()` — INSERT scenario_runs

### site/operations/get_params.py — параметры с текущими значениями
- `get_params_with_current_values()` — смержить state.params инстанса с шаблоном операции
- `_normalize_value_list()` — CSV-строка/массив → list

### site/operations/get_services.py — сервисы
- `get_services()` — GET /services → все сервисы
- `get_service_detail()` — GET /services/{id} → детали + операции

### site/operations/get_instances.py — инстансы
- `get_organization()` — инстанс с serviceId=19
- `get_instances()` — GET /instances?pageSize=500 → все инстансы

### site/operations/service_list.py — разрешённые сервисы
- `load_service_ids(stand)` — чтение `config/services_{stand}.txt`

### site/operations/tracker.py — трекер инстансов (файловый)
- JSON-файлы в /tmp/: `instances-{clientId}-{stand}.json`
- fcntl.flock для multi-worker safety
- Используется как КРАТКОСРОЧНЫЙ fallback (инстанс создан, но облако ещё не показывает)

### site/db/pool.py — connection pool
- Lazy-init ThreadedConnectionPool (1-5)
- `_ensure_schema()` → `init_db()` после успешного коннекта
- ENV: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE

### site/db/init_db.py — схема БД
- Таблица `runs` — история операций (id, client_id, stand, svc_id, op_name, status, duration, params JSONB, stages JSONB, scenario_run_id, step_number)
- Таблица `scenario_runs` — запуски сценариев (id, scenario_name, status, current_step, total_steps, duration, error_log)
- Миграции: ALTER TABLE ADD COLUMN IF NOT EXISTS
- **НЕТ** таблицы `scenario_definitions` — её ещё предстоит создать

### site/db/save_run.py — сохранение в БД
- `save_run()` — INSERT в runs
- Принимает опциональные `scenario_run_id` + `step_number` (добавлены в v1.1.48)

### site/runner.py — LEGACY (будет удалён)
- Старый механизм запуска тестов из config.yaml
- Используется только `load_config()` из него

### site/static/app.js — ФРОНТЕНД (550 строк)
- Глобальное состояние: svcInstances, selectedInst, selectedOp, pollTimer, currentSvcId, busy, AUTOTEST_PREFIX
- selectService(), toggleInstance(), startCreate(), runOp(), showParams(), executeOp()
- Поллинг: setFinishedState(), showStages(), stopPoll(), refreshInstances()
- История: toggleHistory(), loadHistory()
- Сценарии: toggleScenario(), loadScenarios(), runScenario(), stopScenarioPoll()
- Хелперы: _esc() (HTML-escape), validateJson()
- Логи: toggleLog(), startLogPoll()

### site/static/style.css — стили
### site/templates/index.html — Jinja2-шаблон
- Три колонки: инфраструктура | сервисы | инстансы+операции+параметры
- Секции: история (сворачиваемая), сценарии (сворачиваемая)
- window.APP: version, stand, hasUserToken, firstServiceId

### site/config.yaml — конфигурация
- services: маппинг name → service_id
- scenarios: один сценарий dummy_test (create → delete)
- **Проблема:** сценарии в контейнере, требуют redeploy для изменения

### STANDS/dev/resources_yaml/ — YAML-описания сервисов (50+ файлов)
- Полные описания: name, service_id, outputs, operations с параметрами (коды, типы, valueList, sub_params)
- Используются ТОЛЬКО как документация, код их не читает

### DOCS/ — документация
- ARCHITECTURE-FULL.md — полный обзор
- sol-answers.md — 14 ответов Sol (MVP-план)
- sol-scenario-editor.md — ответы Sol по редактору сценариев

---

## 3. ПОТОК ОПЕРАЦИИ CREATE (Terraform parity)

1. POST /instances → `instance_uid` из Location-заголовка `./UUID`
2. POST /instanceOperations → `op_uid` из Location-заголовка
3. GET /instanceOperations/{op_uid}?fields=cfsParams → шаблон параметров
4. _resolve_ref_svc → автоподстановка UUID для refSvcId-параметров
5. POST /instanceOperationCfsParams → отправить пользовательские параметры
6. POST /instanceOperationCfsParams → дослать неотправленные (с normalize)
7. GET /instanceOperations/{op_uid}/validate-cfs → валидация
8. POST /instanceOperations/{op_uid}/run → запуск
9. Поллинг GET /instanceOperations/{op_uid}?fields=dtFinish,... → dtFinish

---

## 4. ТЕКУЩЕЕ СОСТОЯНИЕ (v1.1.48)

### Работает:
- ✅ Ручной запуск операций (create/modify/delete/suspend/resume/redeploy)
- ✅ Terraform-совместимая отправка параметров (9 шагов)
- ✅ Поллинг с этапами (⏳/✅/❌)
- ✅ История в БД (runs)
- ✅ Лог-панель (fcntl.flock, ротация)
- ✅ HTML-escape (statusError, d.error, логи, currentSvcName)
- ✅ Redact secrets перед сохранением
- ✅ Валидация входов (UUID, int, dict)
- ✅ refSvcId — верхнеуровневый + в dataDescriptor
- ✅ Убран legacy api_bp

### Частично работает:
- ⚠️ Сценарии — запуск есть, но источник = config.yaml (redeploy для правки)
- ⚠️ save_run пишет scenario_run_id + step_number (v1.1.48), но не протестировано
- ⚠️ run_id возвращается клиенту (v1.1.48), поллинг по конкретному запуску

### Не работает / pending:
- ❌ Редактор сценариев в UI (нужна таблица scenario_definitions + CRUD API + UI)
- ❌ Сценарии требуют redeploy для изменения (запечены в config.yaml)
- ❌ Дубликаты _find_uid / _uid_from_location в scenario.py и api_test.py
- ❌ scenario.py не протестирован на полный цикл create→delete
- ❌ seed из config.yaml в БД при первом старте не реализован
- ❌ Нет сервисных токенов (runner использует персональный токен)
- ❌ Нет блокировки параллельных запусков сценариев

---

## 5. КЛЮЧЕВЫЕ НАХОДКИ ИЗ HAR-ТРАССИРОВКИ

POST /instances:
- Request: `{"serviceId":1,"displayName":"dummy-11255555","descr":""}`
- Response: status 201, body `{}`, Location: `./CDEBB216-E5EB-4C09-8736-7E5F01A4EE12`
- **UUID ТОЛЬКО в Location-заголовке**, тело ответа — пустой объект `{}`

POST /instanceOperations:
- Request: `{"instanceUid":"...","operation":"create"}`
- Response: также Location-заголовок с opUid

**Следствие:** `_find_uid(resp)` никогда не найдёт UUID в теле ответа (тело пустое). UUID всегда в Location. `_uid_from_location(resp.get("_location",""))` — ЕДИНСТВЕННЫЙ работающий метод извлечения.

**Но:** `_find_uid` нужен для других ответов API (get instanceOperation), где UUID внутри `instanceOperation.instanceOperationUid`.

---

## 6. РЕКОМЕНДАЦИИ SOL (2026-07-30)

### По редактору сценариев (sol-scenario-editor.md):

1. **Структура steps:** JSONB, поле `resource` для связи create→modify→delete одного инстанса
2. **Параметры:** выпадающие списки из живого API (сервис→операции→коды), кеш на время сессии
3. **Seed:** marker `scenario_seed_v1=completed`, `INSERT ON CONFLICT DO NOTHING`, отдельный `scenario_seed.yaml`
4. **UI:** модальное окно, кнопки вверх/вниз, мягкое удаление (is_active=false)
5. **Валидация:** при сохранении + при запуске, невалидный не запускать
6. **Критические дыры:**
   - run_id до потока (✅ исправлено v1.1.48)
   - GET /api/scenario/run/<id> (✅ добавлен v1.1.48)
   - save_run пишет scenario_run_id/step_number (✅ исправлено v1.1.48)
   - TIMEOUT: op_data инициализировать (✅ исправлено v1.1.48)
   - RUNNING до API (✅ исправлено v1.1.48)
   - Блокировка параллельных запусков (pending)
   - version в definitions для optimistic locking (pending)
   - Сервисные токены (pending)

---

## 7. ЧТО НУЖНО ОТ АГЕНТА

### Проанализировать и ответить:

1. **Общая архитектура** — оценить, найти слабые места, предложить улучшения

2. **Дублирование кода** — `_find_uid` и `_uid_from_location` есть и в api_test.py и в scenario.py. Вынести в общий модуль? Куда?

3. **scenario_definitions** — спроектировать таблицу:
   - Поля: id, client_id, stand, name, steps JSONB, version, is_active, created_at, updated_at, updated_by
   - Индексы: UNIQUE(client_id, stand, lower(name))
   - API CRUD: какие именно эндпоинты, какие проверки
   - Seed: как именно импортировать из scenario_seed.yaml при первом старте

4. **UI редактора сценариев:**
   - Модальное окно: структура HTML
   - JS-логика: загрузка списка, создание/редактирование/удаление
   - Выпадающие списки: сервисы из GET /api/services, операции из GET /api/operations/{svcId}, параметры из GET /api/params/{opId}
   - Валидация на фронте перед отправкой

5. **Runner** — нужно ли что-то менять в `run_scenario()`? Он сейчас берёт шаги из config.yaml, должен из БД. Также нужно сохранять snapshot шагов в scenario_runs.

6. **Безопасность:**
   - CRUD сценариев: проверка client_id+stand
   - Optimistic locking (version)
   - Блокировка параллельных запусков (HTTP 409)

7. **Что ещё критично упущено?** — любые дыры, которые не покрыты текущим планом

8. **Приоритетный порядок реализации:**
   - Что делать сначала, что потом
   - Что можно выпустить в v1.1.49, что отложить

### НЕ ДЕЛАТЬ:
- Не писать код (только анализ и план)
- Не трогать git
- Не менять файлы

---

## 8. ФАЙЛЫ ДЛЯ АНАЛИЗА (читать в этом порядке)

1. `app-autotest/site/app.py`
2. `app-autotest/site/api/http_client.py`
3. `app-autotest/site/api/auth.py`
4. `app-autotest/site/routes/main.py`
5. `app-autotest/site/routes/api_test.py` (самый важный)
6. `app-autotest/site/routes/api_scenario.py`
7. `app-autotest/site/operations/scenario.py`
8. `app-autotest/site/operations/get_params.py`
9. `app-autotest/site/operations/get_services.py`
10. `app-autotest/site/operations/get_instances.py`
11. `app-autotest/site/operations/tracker.py`
12. `app-autotest/site/operations/service_list.py`
13. `app-autotest/site/db/pool.py`
14. `app-autotest/site/db/init_db.py`
15. `app-autotest/site/db/save_run.py`
16. `app-autotest/site/runner.py`
17. `app-autotest/site/config.yaml`
18. `app-autotest/site/static/app.js`
19. `app-autotest/site/templates/index.html`
20. `app-autotest/site/static/style.css`
21. `development/dummycreate.har` (HAR-трассировка CREATE)
22. `DOCS/ARCHITECTURE-FULL.md`
23. `DOCS/sol-answers.md`
24. `DOCS/sol-scenario-editor.md`
25. `app-autotest/site/config/services_test.txt`
26. Любой YAML из `STANDS/dev/resources_yaml/` (например `1_dummy.yaml`, `115_mariadb.yaml`)