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

site/operations/get_instances.py

@@ -1,5 +1,10 @@
 """
 Операции с инстансами Nubes — получение списка и организации через API.
+
+Используется:
+  - main.py → отображение инфраструктуры на главной
+  - api_test.py → список инстансов для выбора
+  - scenario.py → поиск refSvcId-инстансов
 """
 
 from api.http_client import HttpClient
@@ -7,10 +12,17 @@ from api.http_client import HttpClient
 
 def get_instances(client):
     """GET /instances с пагинацией → ВСЕ инстансы пользователя.
-    
-    pageSize=200 — максимум за один запрос.
-    Остановка по len(batch) < pageSize (НЕ доверяет total — бывали баги).
-    Возвращает полный list[dict]."""
+
+    pageSize=200 — максимум за один запрос (API лимит).
+    Остановка по len(batch) < pageSize — НЕ доверяет total из ответа.
+
+    Почему не доверяем total:
+      Бывали баги где API возвращал total=500, а реально инстансов 3.
+      Проверка по размеру страницы надёжнее.
+
+    Returns:
+        list[dict] — каждый dict содержит instanceUid, displayName, serviceId,
+                     svc, explainedStatus, instanceConfigDtCreated и др."""
     results = []
     page = 1
     page_size = 200
@@ -18,8 +30,8 @@ def get_instances(client):
         data = client.get("/instances", params={"pageSize": page_size, "page": page})
         batch = data.get("results", []) or []
         results.extend(batch)
-        # Если страница неполная — данные закончились.
-        # Не проверяем total, потому что API иногда врёт про total.
+        # Если страница неполная — данных больше нет.
+        # Это надёжнее чем проверка page * pageSize >= total.
         if len(batch) < page_size:
             break
         page += 1
@@ -28,8 +40,12 @@ def get_instances(client):
 
 def get_organization(client):
     """Первый инстанс с serviceId=19 (Организация).
-    
-    Организация всегда одна на пользователя. Используется в UI: название, статус, ClientID."""
+
+    Организация всегда одна на пользователя — это его «корневой» инстанс.
+    Используется в UI: название организации, статус, ClientID.
+
+    Returns:
+        dict или None — инстанс организации или None если не найден."""
     for inst in get_instances(client):
         if inst.get("serviceId") == 19:
             return inst