Покрытие кода docstrings

SRV/services/subnet_service.py

@@ -44,7 +44,20 @@ def get_subnet_service(translations: Translations = Depends(get_translations()))
 class NetworkScanner:
     """Класс для сканирования подсети с использованием ARP-запросов.
 
-    Выполняет отправку ARP-запросов для обнаружения устройств в указанной подсети.
+    Назначение:
+        Обнаруживает активные устройства в локальной сети, отправляя широковещательные
+        ARP‑запросы по указанной подсети и собирая ответы (IP, MAC).
+
+    Детали реализации:
+        - Использует `scapy` (`Ether` + `ARP`) для генерации пакетов и `srp` для
+          отправки/получения на канальном уровне от имени заданного интерфейса.
+        - Таймаут ожидания ответа короткий (2 секунды), ориентирован на интерактивные
+          сценарии UI.
+
+    Ограничения и замечания:
+        - Требуются права для отправки низкоуровневых пакетов (capabilities/root).
+        - В сетях с фильтрацией широковещания количество обнаруженных устройств
+          может быть ограничено.
     """
     def __init__(self, interface: str, translations: Translations):
         """Инициализирует сканер сети.
@@ -74,6 +87,10 @@ class NetworkScanner:
         Raises:
             Exception: Если произошла ошибка сканирования.
         """
+        try:
+            arp = ARP(pdst=subnet)
+        except Exception as e:
+            logger.error(f"Error checking status: {str(e)}")
         try:
             arp = ARP(pdst=subnet)
             ether = Ether(dst="ff:ff:ff:ff:ff:ff")
@@ -87,7 +104,14 @@ class NetworkScanner:
 class PortScanner:
     """Класс для сканирования открытых портов на устройствах.
 
-    Предоставляет функциональность для проверки доступности портов, пока не реализована.
+    Назначение:
+        Плейсхолдер для будущего функционала активного сканирования TCP/UDP‑портов
+        у обнаруженных узлов. В текущей версии возвращает пустой список.
+
+    План развития:
+        - Добавить неблокирующее сканирование наиболее распространённых портов
+          (22, 80, 443 и т.д.) с ограничением по времени.
+        - Настраиваемые профили глубины и скорости сканирования.
     """
     def __init__(self, interface: str, translations: Translations):
         """Инициализирует сканер портов.
@@ -117,7 +141,15 @@ class PortScanner:
 class DeviceInfoCollector:
     """Класс для сбора информации об устройствах, включая вендоров и хостнеймы.
 
-    Использует внешние сервисы (MacLookup, NBTSCAN, DNS) для получения данных.
+    Источники данных:
+        - MacLookup: сопоставление префикса MAC (OUI) с названием производителя.
+        - DNS: `gethostbyaddr` с малым таймаутом для обратного разрешения имени.
+        - NetBIOS (nbtscan): опрос сегмента сети для извлечения NetBIOS‑имён.
+
+    Политика кэширования:
+        - Результаты `get_vendor` кэшируются с помощью `functools.lru_cache`.
+        - Результаты `nbtscan` аккумулируются в словарях `nbtscan_cache`/`nbtscan_results`
+          на время жизни экземпляра.
     """
     def __init__(self, translations: Translations):
         """Инициализирует коллектор информации об устройствах.
@@ -213,7 +245,15 @@ class DeviceInfoCollector:
 class DeviceStorage:
     """Класс для хранения и управления данными об устройствах.
 
-    Обеспечивает загрузку и сохранение данных в JSON-файлы.
+    Формат файла подсети:
+        JSON‑структура вида
+        {
+          "devices": [Device, ...]
+        }
+
+    Политика очистки:
+        - Метод `_clean_old_devices` удаляет оффлайн‑устройства, не наблюдавшиеся
+          более 7 дней, чтобы поддерживать актуальность списка.
     """
     def __init__(self, base_path: str = "storage/subnets", translations: Translations = None):
         """Инициализирует хранилище устройств.
@@ -331,7 +371,19 @@ class DeviceStorage:
 class SubnetService:
     """Сервис для сканирования подсетей и управления устройствами.
 
-    Объединяет функциональность сканирования, сбора информации и хранения данных.
+    Роль сервиса:
+        Объединяет сетевое сканирование (ARP), сбор дополнительной информации
+        (вендор, хостнейм), слияние с кэшем предыдущих результатов и персистентное
+        хранение данных по подсетям. Предоставляет вспомогательные операции для
+        локального узла и работы с заметками устройств.
+
+    Поток выполнения скана (`scan_subnet`):
+        1) Определение подсети (вручную или авто по интерфейсу).
+        2) Загрузка ранее сохранённых устройств подсети.
+        3) Добавление локального устройства (если принадлежит подсети).
+        4) ARP‑сканирование и параллельная обработка узлов (обогащение данных).
+        5) Маркировка оффлайн‑узлов из кэша, не встреченных в текущем скане.
+        6) Сортировка по IP и сохранение объединённого списка в JSON.
     """
     def __init__(self, translations: Translations):
         """Инициализирует сервис подсети.