Рефакторинг API-слоя, операций и БД

site/db/save_run.py

@@ -1,5 +1,13 @@
 """
-Сохранение результатов тестов в БД.
+Сохранение результатов тестов в БД (таблица runs).
+
+Вызывается после КАЖДОЙ операции:
+  - Ручной режим: _finish_op() в api_test.py
+  - Сценарный режим: run_scenario() в scenario.py (после каждого шага)
+
+Сохраняет ВСЕ параметры запроса и ответа — для истории и анализа ошибок.
+Секретные поля (password, token, ...) маскируются через redact_params().
+instance_meta — полный JSON ответа GET /instances/{uid} (для post-mortem анализа).
 """
 
 import json
@@ -11,8 +19,31 @@ def save_run(client_id, stand, user_email, svc_id, svc_name, op_name, svc_op_id,
              error_log, params, stages, app_version,
              scenario_run_id=None, step_number=None, instance_meta=None):
     """Сохранить один запуск в таблицу runs.
-    Опционально: scenario_run_id + step_number для шагов сценария.
-    instance_meta — JSONB с полной информацией об инстансе."""
+
+    Эта функция — единственная точка записи в runs.
+    Вызывается и из ручного режима, и из сценариев.
+
+    Args:
+        client_id:       str — ClientID пользователя
+        stand:           str — "dev"/"test"
+        user_email:      str — email из JWT
+        svc_id:          int — ID сервиса
+        svc_name:        str — имя сервиса (из ответа poll)
+        op_name:         str — "create"/"modify"/"delete"/"suspend"/"resume"/"redeploy"
+        svc_op_id:       int — числовой ID операции
+        op_uid:          str — UUID операции
+        instance_uid:    str — UUID инстанса
+        display_name:    str — displayName инстанса
+        status:          str — "OK"/"FAIL"/"TIMEOUT"/"RUNNING"
+        duration_sec:    float — длительность операции
+        error_log:       str — текст ошибки (если FAIL)
+        params:          dict — параметры операции (уже маскированные)
+        stages:          list — этапы выполнения
+        app_version:     str — версия приложения
+        scenario_run_id: int|None — ID запуска сценария
+        step_number:     int|None — номер шага в сценарии
+        instance_meta:   dict|None — полная информация об инстансе (JSONB)
+    """
     conn = get_conn()
     if not conn:
         print("[DB] save_run SKIP: no connection", flush=True)
@@ -30,10 +61,12 @@ def save_run(client_id, stand, user_email, svc_id, svc_name, op_name, svc_op_id,
             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 и stages — JSONB: сериализуем в JSON-строку
             json.dumps(params) if params else None,
             json.dumps(stages) if stages else None,
             app_version,
             scenario_run_id, step_number,
+            # instance_meta — тоже JSONB
             json.dumps(instance_meta) if instance_meta else None,
         ))
         conn.commit()
@@ -43,4 +76,4 @@ def save_run(client_id, stand, user_email, svc_id, svc_name, op_name, svc_op_id,
         print(f"[DB] save_run error: {e}", flush=True)
         conn.rollback()
     finally:
-        put_conn(conn)
+        put_conn(conn)  # ВСЕГДА возвращаем соединение в пул