319 lines
18 KiB
Markdown
319 lines
18 KiB
Markdown
# Запрос на полный анализ 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`)
|