# Архитектура app-autotest — полное описание v1.2.43, 04.08.2026 --- ## 1. Обзор Flask 3.1 + vanilla JS + PostgreSQL (psycopg2). Веб-приложение для автоматического тестирования сервисов облачной платформы Nubes через REST API. **Два режима работы:** - Эмуляция — всё в Polygon (мок-сервер, без реальной инфраструктуры) - Облако — реальный Nubes API (dev/test, автоопределение по JWT) **Ручной режим:** сервис -> операция (create/modify/delete/suspend/resume/redeploy) -> параметры -> запуск -> поллинг. **Сценарный режим:** последовательность шагов с передачей контекста, редактор через модальный UI, хранение в БД. **Деплой:** Nubes pythonk8s managed service, gunicorn --workers 2. **URL:** https://atest.pythonk8s.dev.nubes.ru **Полигон:** https://polygon.pythonk8s.dev.nubes.ru **Репозиторий:** https://gitea.services.ngcloud.ru/forcloud/app-autotest.git (master) ### Ключевые принципы 1. Единый HttpClient — auth.py:get_client(), одна точка для обоих режимов. 2. Изоляция по (client_id, stand) — все таблицы БД, трекер, сценарии. 3. Cloud-first + tracker-fallback — инстансы сначала из API, трекер для только что созданных. 4. Multi-worker safety — /tmp файлы защищены fcntl.flock, _op_results под threading.Lock. 5. Защита от XSS — _esc() на всех данных из API перед innerHTML. --- ## 2. Структура файлов ``` app-autotest/ ├── requirements.txt ├── site/ │ ├── app.py # Точка входа: VERSION, blueprints, /health │ ├── api/ │ │ ├── http_client.py # HttpClient, detect_endpoint, stand_name │ │ ├── auth.py # get_client(), get_mode(), get_stand(), токены, cookie │ │ └── utils.py # find_uid(), uid_from_location() │ ├── operations/ │ │ ├── executor.py # ЕДИНЫЙ запуск: create->params->run │ │ ├── poll.py # poll_until_done() │ │ ├── scenario.py # run_scenario() — шаги с резолвингом │ │ ├── terraform.py # send_params_terraform() — нормализация │ │ ├── tracker.py # JSON-файловый кеш /tmp/instances-*.json (flock) │ │ ├── get_instances.py # GET /instances с пагинацией │ │ ├── get_params.py # Параметры с ТЕКУЩИМИ значениями из state.params │ │ ├── get_services.py # GET /services │ │ └── service_list.py # services_{stand}.txt фильтр │ ├── db/ │ │ ├── pool.py # ThreadedConnectionPool(1,5) │ │ ├── init_db.py # CREATE TABLE + миграции + idx_one_running │ │ ├── save_run.py # Ручной UPSERT (UPDATE -> INSERT) │ │ └── scenario_defs.py # CRUD + lock_check │ ├── routes/ │ │ ├── main.py # GET/POST /, set_mode, api_operations │ │ ├── api_test.py # /api/test, /api/params, /api/log, _finish_op │ │ ├── api_scenario_run.py # /api/scenario/run, /api/scenario/status │ │ ├── api_scenario_defs.py# CRUD /api/scenario/definitions │ │ ├── api_scenario.py # [ДУБЛИКАТ] Не зарегистрирован │ │ └── api.py # [LEGACY] /api/run │ ├── static/ │ │ ├── app.js # Инициализация: startLogPoll(), selectService() │ │ ├── style.css # Дизайн-система Nubes │ │ └── js/ │ │ ├── utils.js # _esc(), validateJson(), logPoll, relativeTime() │ │ ├── views.js # switchView() │ │ ├── instances.js # selectService(), toggleInstance() │ │ ├── operations.js # startCreate(), runOp(), showParams() │ │ ├── params-render.js# renderParamRow(), collectParams() │ │ ├── history.js # toggleHistory(), loadHistory() │ │ ├── scenario-list.js# toggleScenario(), runScenario(), поллинг │ │ ├── scenario-form.js# showScenarioEditor() │ │ ├── scenario-create.js, scenario-edit.js, scenario-delete.js │ │ ├── icons.js # SVG-иконки │ │ └── snackbar.js # showSnackbar() │ └── templates/ │ └── index.html # Весь UI: сайдбар, виды, лог-панель ├── tests/ │ ├── conftest.py # app_client, polygon_server фикстуры │ ├── test_api_scenario_run.py# 3 теста: 503, 409, unique violation │ ├── test_db_scenario_defs.py# 2 теста: lock_check None │ ├── test_polygon_integration.py# 15 интеграционных тестов │ ├── test_static_regressions.py# 2 статических теста │ └── README.md └── secrets/ ├── dev.token └── test.token ``` --- ## 3. Система режимов — auth.py Центральный модуль. Все роуты получают HttpClient ТОЛЬКО через функции этого модуля. ### Переменные окружения | Переменная | По умолчанию | Назначение | |-----------|-------------|-----------| | NUBES_API_ENDPOINT | lk-api-gateway-test.../api/v1/svc | Реальный API | | NUBES_API_TOKEN | (пусто) | Сервисный JWT-токен | | POLYGON_ENDPOINT | (пусто) | URL полигона. Если задан -> селектор режима | ### Cookie | Cookie | По умолчанию | Допустимые значения | |--------|-------------|-------------------| | mode | "polygon" | "polygon", "cloud" | | polygon_stand | "test" | "dev", "test", "prod" | | token | (пусто) | JWT пользователя | Все cookie: httponly=True, samesite=Strict, secure=True, max_age=1 год. ### Функции get_mode() -> "polygon" | "cloud" Без POLYGON_ENDPOINT -> всегда "cloud" Из cookie, whitelist-валидация get_polygon_stand() -> "dev" | "test" | "prod" Из cookie, whitelist-валидация get_token() -> JWT-строка Эмуляция: только NUBES_API_TOKEN (env) Облако: cookie "token" -> NUBES_API_TOKEN _cached_detect(token) -> URL эндпоинта (кеш в flask.g) Вызывает detect_endpoint() только при первом обращении за запрос Устраняет двойной HTTP-запрос (get_client + get_stand) get_client() -> HttpClient Эмуляция: polygon_url.replace("/api/v1/svc", "/{stand}/api/v1/svc") Облако: _cached_detect(token) get_stand() -> "polygon_test" | "dev" | "test" | "mock" Эмуляция: "polygon_" + get_polygon_stand() Облако: stand_name(_cached_detect(token)) ### URL полигона POLYGON_ENDPOINT = https://polygon.pythonk8s.dev.nubes.ru/api/v1/svc Стенд ВСТАВЛЯЕТСЯ перед /api/v1/svc: DEV: https://polygon.../dev/api/v1/svc TEST: https://polygon.../test/api/v1/svc PROD: https://polygon.../prod/api/v1/svc --- ## 4. HTTP-клиент — http_client.py HttpClient — обёртка над requests.Session: - Заголовки: Authorization: Bearer, User-Agent: Mozilla/5.0 (DDoS-Guard) - get(path) -> raise_for_status() -> .json(), таймаут 10с - post(path, data) -> r.ok, JSON, Location -> UUID, таймаут 30с - raw_delete(url) -> DELETE без авторизации (CMDB) STANDS = [dev, test URL] detect_endpoint(token) — пробует dev->test, returns URL where results != None stand_name(endpoint) — ТОЧНОЕ сравнение URL -> "dev"/"test"/"?" --- ## 5. Режимы работы и разделы БД | Режим | Сервисы | Инстансы | Стенд в БД | |--------|---------|----------|-----------| | Эмуляция | Полигон | Полигон | polygon_{dev|test|prod} | | Облако | Реальный API | Реальный API | dev / test | Облако (2 стенда): dev, test Эмуляция (3 стенда): polygon_dev, polygon_test, polygon_prod PROD в облаке недоступен — только через эмуляцию. ### Сервис-листы load_service_ids(stand) обрезает префикс polygon_: polygon_test -> test -> services_test.txt polygon_dev -> dev -> services_dev.txt polygon_prod -> prod -> services_prod.txt (не existe -> пустой set -> все сервисы) В шаблоне: если список пуст — показываются все сервисы. --- ## 6. Роуты ### main.py GET/POST / — главная страница action=save — сохранить токен в cookie action=clear — удалить cookie action=set_mode — сохранить mode + polygon_stand в cookie polygon_stand: из формы, иначе из cookie (Облако->Эмуляция) Валидация: mode in {polygon,cloud}, stand in {dev,test,prod} Загрузка: mode=="polygon" or active_token Единый client = get_client() GET /api/operations/ — операции + autotest-инстансы Cloud-first + tracker-fallback, дедупликация ### api_test.py — ручной режим GET /api/services — список сервисов GET /api/instances/list — все инстансы GET /api/params/[?instanceUid=xxx] — параметры (шаблон или текущие) POST /api/test — запуск операции, возвращает opUid Валидация: serviceId(int>0), operation, svcOperationId(int>0), UUID(36), params(dict) CREATE: _unique_display_name() + execute_operation() non-CREATE: execute_operation() delete: CMDB -> fallback API delete Фон: _finish_op() — поллинг + save_run + tracker_remove GET /api/test/status/ — статус (_op_results -> API) GET /api/log — последние 200 строк из /tmp/app-autotest.log GET /api/history — последние 50 записей из runs (client_id + stand) ### api_scenario_run.py — сценарии GET /api/scenarios — список определений POST /api/scenario/run — запуск lock_check -> None(503), False(409) INSERT scenario_runs status=RUNNING (partial unique index) UniqueViolation(pgcode 23505) -> 409 Фон: run_scenario(client, steps, cid, stand, ...) GET /api/scenario/run/ — статус GET /api/scenario/status — последние 10 запусков ### api_scenario_defs.py — CRUD GET/POST /api/scenario/definitions — список/создать GET/PUT/DELETE /api/scenario/definitions/ — один/обновить/удалить PUT: оптимистичная блокировка (version -> 409) DELETE: мягкое (is_active=FALSE) --- ## 7. Операции ### executor.py execute_operation() — единый запуск: 1. CREATE: POST /instances -> instanceUid -> tracker_add -> POST /instanceOperations -> opUid 2. non-CREATE: POST /instanceOperations -> opUid 3. send_params_terraform() — нормализация, refSvcId, validate-cfs 4. POST /run -> запуск ### scenario.py run_scenario() — для каждого шага: 1. get_service_detail() -> svcOperationId 2. GET /instanceOperations/default/{id} -> резолв параметров 3. Резолвинг instance_uid: явный uid > instance_ref > service_id 4. execute_operation() 5. save_run(RUNNING) 6. poll_until_done() 7. save_run(final) — UPDATE существующей строки 8. tracker_remove() после успешного delete 9. _save_scenario_run() — прогресс ### tracker.py JSON-файловый кеш: /tmp/instances-{clientId}-{stand}.json fcntl.flock(LOCK_EX|LOCK_NB) + retry 2s add/remove/list_all — атомарные операции --- ## 8. База данных ### pool.py ThreadedConnectionPool(1,5), ленивый init в каждом воркере _ensure_schema() -> init_db() при первом обращении ### Таблицы runs — история операций: id, created_at, client_id, stand, user_email, svc_id, svc_name, op_name, svc_op_id, op_uid, instance_uid, display_name, status, duration_sec, error_log, params(JSONB), stages(JSONB), app_version, scenario_run_id, step_number, instance_meta(JSONB) Индексы: client_stand, instance, created, op_uid(UNIQUE WHERE NOT NULL) scenario_runs — запуски сценариев: id, client_id, stand, scenario_name, status, current_step, total_steps, instance_bindings(JSONB), duration_sec, error_log Partial UNIQUE INDEX: (client_id, stand) WHERE status='RUNNING' scenario_definitions — определения: id, client_id, stand, name, steps(JSONB), version, is_active UNIQUE: (client_id, stand, LOWER(name)) Seed: client_id="" AND stand="" — видны всем ### save_run.py Ручной UPSERT: 1. UPDATE runs SET ... WHERE op_uid = %s 2. Если rowcount == 0 -> INSERT --- ## 9. Фронтенд Сайдбар (192px, flex column): sidebar-nav (flex:0) — кнопки видов Селектор режима (радиокнопки, только при POLYGON_ENDPOINT) sidebar-bottom — версия, email, токен (disabled в эмуляции) Виды: workbench, overview, history-view, scenarios-view, logs-view JS модули (12 файлов): utils.js — _esc(), startLogPoll(), relativeTime() views.js — switchView() instances.js — selectService(), toggleInstance() operations.js — startCreate(), runOp(), executeOp() history.js — toggleHistory(), loadHistory() scenario-list.js — runScenario(), поллинг (5 ошибок -> стоп) scenario-form.js — редактор сценариев Защита от XSS: _esc(s) -> &, ", < o.operation: JS-escape + HTML-escape escName: \\, \', " --- ## 10. Nubes API — эндпоинты GET /services — список GET /services/{id} — детали + операции GET /instances — все (пагинация) GET /instances/{uid} — детали + state.params GET /instanceOperations/default/{id} — шаблон cfsParams POST /instances — создать -> 201 + Location POST /instanceOperations — создать операцию -> 201 + Location POST /instanceOperationCfsParams — установить параметр GET /.../validate-cfs — валидация POST /.../run — запустить GET /.../{uid}?fields=... — поллинг --- ## 11. Безопасность Гонки: _op_results — threading.Lock(), pop(k,None) idx_one_running — partial unique index (атомарный lock) Tracker — fcntl.flock, атомарное read->mutate->write save_run — ручной UPSERT без индекса Cookie: httponly, samesite=Strict, secure, 1 год Валидация: serviceId: int>0, instanceUid: UUID(36), svcOperationId: int>0 params: dict, mode: {polygon,cloud}, stand: {dev,test,prod} --- ## 12. Тесты 22 теста: python3 -m pytest tests/ -v test_api_scenario_run.py — 3 теста (503, 409, unique violation) test_db_scenario_defs.py — 2 теста (lock_check None) test_polygon_integration.py — 15 тестов (полный цикл с полигоном) test_static_regressions.py — 2 теста (DDL, escName) --- ## 13. История версий (v1.2.28 -> v1.2.43) 1.2.28 — исходная (03.08) 1.2.29 — фикс сервисов при POLYGON_ENDPOINT 1.2.30 — селектор режима/стенда 1.2.31 — фикс URL полигона 1.2.35 — sidebar-nav flex:0 + форма по центру 1.2.36 — tracker_remove в сценариях + логи 1.2.39 — ручной UPSERT 1.2.40 — код-ревью #1: _esc() для o.operation 1.2.41 — код-ревью #2: кеш detect_endpoint 1.2.42 — код-ревью #3: whitelist mode/stand 1.2.43 — код-ревью #5,#6,#8,#9,#10: finally, stand_name, индекс, flush