Generate Sphinx docs in markdown

SRV/docs/_build/markdown/api/services/arp_service.md

@@ -0,0 +1,55 @@
+# ARP Service
+
+Сервис низкоуровневого ARP-сканирования локальной сети.
+
+Назначение:
+
+- Обнаружение активных узлов в пределах сетей хоста путём широковещательных ARP‑запросов от имени выбранного интерфейса.
+- Помощь сервисам более высокого уровня (например, IPService) при проверке занятости адресов перед применением конфигураций.
+
+Особенности реализации:
+
+- Определяет подключённые сети интерфейса через netifaces и строит CIDR для сканирования.
+- Формирует ARP‑пакеты с помощью scapy (Ether/ARP) и отправляет их с таймаутом.
+- Добавляет локальный адрес интерфейса в результирующий список клиентов.
+
+Требования/ограничения:
+
+- Для отправки ARP‑кадров могут потребоваться повышенные привилегии или capability на сырой сокет.
+
+### *class* services.arp_service.NetworkScanner(interface=None, translations: Translations = Depends(translations_dependency))
+
+Bases: `object`
+
+Инициализация сетевого сканера.
+
+Предоставляет методы для сканирования сети с использованием ARP-запросов и
+вывода информации о клиентах.
+
+#### print_clients(clients)
+
+Выводит список адресов клиентов в формате таблицы.
+
+* **Parameters:**
+  **clients** (*List* *[**dict* *]*) – Список словарей с ключами “ip” и “mac”,
+  представляющих клиентов.
+
+Выводит IP-адреса и MAC-адреса в отсортированном по IP порядке.
+
+#### scan_network(attempts=3, timeout=2)
+
+Сканирует сеть для обнаружения активных клиентов.
+
+* **Parameters:**
+  * **attempts** (*int* *,* *optional*) – Количество попыток отправки ARP-запросов.
+    По умолчанию 3.
+  * **timeout** (*int* *,* *optional*) – Таймаут ожидания ответа в секундах.
+    По умолчанию 2.
+* **Returns:**
+  Список словарей с ключами “ip” и “mac”, представляющих
+  : обнаруженных клиентов, включая локальные IP-адреса.
+* **Return type:**
+  List[dict]
+
+#### NOTE
+Учитывает локальные IP-адреса интерфейса и удаляет дубликаты.

SRV/docs/_build/markdown/api/services/auth_service.md

@@ -0,0 +1,35 @@
+# Auth Service
+
+### *class* services.auth_service.AuthService(translations: Translations = Depends(translations_dependency))
+
+Bases: `object`
+
+Сервис для регистрации, авторизации и управления сессиями
+
+#### create_access_token(data: dict) → str
+
+Создаёт токен
+
+#### get_current_user(token: str = Depends(OAuth2PasswordBearer)) → UserResponse
+
+Получает текущего пользователя по токену
+
+#### get_user_by_session(client_id: str) → dict
+
+Получает пользователя и токен по client_id
+
+#### login(user: UserLogin, client_id: str) → dict
+
+Авторизует пользователя, создаёт сессию и возвращает токен
+
+#### logout(client_id: str)
+
+Выполняет выход из системы, удаляя последнюю сессию для client_id
+
+#### register(user: UserCreate) → UserResponse
+
+Регистрирует нового пользователя
+
+#### verify_token(token: str) → dict | None
+
+Проверяет токен

SRV/docs/_build/markdown/api/services/connect_service.md

@@ -0,0 +1,71 @@
+# Connect Service
+
+Сервис управления подключениями Wi‑Fi через nmcli.
+
+Назначение:
+
+- Предоставляет операции подключения/отключения к точкам доступа и проверки текущего статуса, ориентируясь на системный NetworkManager.
+
+Поведение:
+
+- Автоматически определяет активный Wi‑Fi‑интерфейс.
+- Валидирует наличие SSID в листинге перед подключением и интерпретирует частые ошибки nmcli (неверный пароль, отсутствующая сеть и т.п.).
+
+Ограничения:
+
+- Требуются права для управления сетевыми соединениями в системе.
+- В окружениях без NetworkManager команды nmcli будут недоступны.
+
+### *class* services.connect_service.WifiConnectionService(translations: Translations = Depends(translations_dependency))
+
+Bases: `object`
+
+Сервис для управления подключением к Wi-Fi сетям с использованием nmcli.
+
+Предоставляет методы для подключения, отключения и проверки статуса Wi-Fi соединений.
+
+#### connect(ssid: str, password: str) → Tuple[bool, str | None]
+
+Подключается к Wi-Fi сети по SSID и паролю.
+
+* **Parameters:**
+  * **ssid** (*str*) – Идентификатор сети Wi-Fi.
+  * **password** (*str*) – Пароль для подключения.
+* **Returns:**
+  Кортеж (успех, сообщение об ошибке).
+  : - Успех: (True, None).
+    - Ошибка: (False, сообщение об ошибке).
+* **Return type:**
+  Tuple[bool, Optional[str]]
+* **Raises:**
+  * **subprocess.CalledProcessError** – Если команда nmcli завершилась с ошибкой.
+  * **Exception** – Если произошла неизвестная ошибка при выполнении.
+
+#### disconnect(ssid: str) → Tuple[bool, str | None]
+
+Отключается от Wi-Fi сети по указанному SSID.
+
+* **Parameters:**
+  **ssid** (*str*) – Идентификатор сети Wi-Fi для отключения.
+* **Returns:**
+  Кортеж (успех, сообщение об ошибке).
+  : - Успех: (True, None или сообщение, если подключение не найдено).
+    - Ошибка: (False, сообщение об ошибке).
+* **Return type:**
+  Tuple[bool, Optional[str]]
+* **Raises:**
+  * **subprocess.CalledProcessError** – Если команда nmcli завершилась с ошибкой.
+  * **Exception** – Если произошла неизвестная ошибка при выполнении.
+
+#### get_status() → Tuple[bool, str | None]
+
+Проверяет статус текущего подключения к Wi-Fi.
+
+* **Returns:**
+  Кортеж (успех, SSID или сообщение об ошибке).
+  : - Успех: (True, SSID текущей сети).
+    - Ошибка или отсутствие подключения: (False, сообщение об ошибке).
+* **Return type:**
+  Tuple[bool, Optional[str]]
+* **Raises:**
+  **Exception** – Если произошла ошибка при выполнении команды nmcli.

SRV/docs/_build/markdown/api/services/firewalld_service.md

@@ -0,0 +1,72 @@
+# Firewalld Service
+
+Сервис для управления firewalld через D‑Bus.
+
+Назначение:
+
+- Обёртка над интерфейсами org.fedoraproject.FirewallD1 для выполнения типовых операций по зонам: просмотр/изменение дефолтной зоны, добавление и удаление сервисов, портов, источников, перезагрузка конфигурации.
+
+Примечания:
+
+- Используется pydbus.SystemBus для доступа к системной шине.
+- Методы генерируют дружелюбные исключения при ошибках, содержащие контекст операции.
+
+### *class* services.firewalld_service.FirewalldService
+
+Bases: `object`
+
+#### add_port(zone: str, port: int, protocol: str, timeout: int | None = 0) → None
+
+Add a port to a zone.
+
+#### add_service(zone: str, service: str, timeout: int | None = 0) → None
+
+Add a service to a zone.
+
+#### add_source(zone: str, source: str) → None
+
+Add a source to a zone.
+
+#### get_default_zone() → str
+
+Get the default zone.
+
+#### get_ports(zone: str) → List[str]
+
+Get list of ports in a zone.
+
+#### get_services(zone: str) → List[str]
+
+Get list of services in a zone.
+
+#### get_sources(zone: str) → List[str]
+
+Get list of sources in a zone.
+
+#### get_zone_settings(zone: str) → Dict
+
+Get all settings for a zone.
+
+#### get_zones() → List[str]
+
+Get list of all zones.
+
+#### reload() → None
+
+Reload firewall rules.
+
+#### remove_port(zone: str, port: int, protocol: str) → None
+
+Remove a port from a zone.
+
+#### remove_service(zone: str, service: str) → None
+
+Remove a service from a zone.
+
+#### remove_source(zone: str, source: str) → None
+
+Remove a source from a zone.
+
+#### set_default_zone(zone: str) → None
+
+Set the default zone.

SRV/docs/_build/markdown/api/services/ip_service.md

@@ -0,0 +1,61 @@
+# IP Service
+
+Сервис проверки и применения IP‑настроек через NetworkManager (D‑Bus).
+
+Назначение:
+
+- Перед применением конфигурации проверяет занятость IP адреса, сканируя сегмент сети средствами ARP (через NetworkScanner).
+- Применяет изменения профиля подключения через sdbus_async.networkmanager и выполняет переподключение интерфейса.
+
+Требования/ограничения:
+
+- Доступ к системной шине D‑Bus и права на изменения сетевых профилей.
+- Структура входных данных должна соответствовать схеме ipv4_updates для корректного обновления вложенных полей у профиля.
+
+### *class* services.ip_service.IPService
+
+Bases: `object`
+
+Сервис проверки доступности IP-адреса и применения настроек сети.
+
+Предоставляет асинхронные методы для проверки занятости IP-адреса с использованием
+ARP-сканирования и применения настроек через NetworkManager.
+
+#### *async* apply_ip_config(args: Dict[str, Any], translations: Translations = Depends(translations_dependency)) → None
+
+Применяет проверенные настройки IP к указанному соединению.
+
+Перезапускает шину D-Bus, обновляет настройки соединения через NetworkManager,
+отключает и переподключает устройство к сети.
+
+* **Parameters:**
+  * **args** (*Dict* *[**str* *,* *Any* *]*) – Словарь с данными, включая:
+    - “connection_id” (str): Идентификатор соединения.
+    - “ipv4_updates” (Dict): Обновления настроек IPv4.
+  * **translations** (*Translations*) – Объект переводов.
+* **Raises:**
+  * **ValueError** – Если соединение с указанным ID не найдено.
+  * **RuntimeError** – Если устройство для интерфейса не найдено.
+
+#### NOTE
+Требуются права для изменения настроек через NetworkManager.
+
+#### *async* check_ip_config(args: Dict[str, Any], translations: Translations = Depends(translations_dependency)) → Dict[str, Any]
+
+Проверяет доступность IP-адреса перед его применением.
+
+Выполняет ARP-сканирование сети для проверки, занят ли указанный IP-адрес.
+Перезапускает шину D-Bus перед выполнением.
+
+* **Parameters:**
+  * **args** (*Dict* *[**str* *,* *Any* *]*) – Словарь с данными, включая “ipv4_updates”
+    с полем “ipv4.address-data” для нового IP-адреса.
+  * **translations** (*Translations*) – Объект переводов.
+* **Returns:**
+  Словарь с ключами:
+  : - ”available” (bool): Доступен ли IP-адрес.
+    - ”message” (str): Сообщение о результате проверки.
+* **Return type:**
+  Dict[str, Any]
+* **Raises:**
+  **Exception** – Если произошла ошибка при сканировании ARP.

SRV/docs/_build/markdown/api/services/network_service.md

@@ -0,0 +1,195 @@
+# Network Service
+
+Сервис чтения сетевого состояния через NetworkManager (D‑Bus).
+
+Назначение:
+
+- Предоставляет асинхронные методы для сборки унифицированных моделей сетевых интерфейсов (Ethernet/Wi‑Fi), их IP‑конфигураций, а также получения имени хоста. Используется API‑слоем для визуализации и управления.
+
+Особенности:
+
+- Фильтрация loopback и явно неактивных интерфейсов.
+- Адаптация данных D‑Bus в pydantic‑модели (NetworkInterface, WiFiDevice, NetworkInterfacesContainer).
+
+### *class* services.network_service.NetworkService(translations: Translations = Depends(translations_dependency))
+
+Bases: `object`
+
+Сервис для взаимодействия с NetworkManager через D-Bus.
+
+Предоставляет асинхронные методы для получения информации о сетевых интерфейсах,
+их конфигурациях IP, Wi-Fi и состояниях.
+
+#### *async* get_activated_interfaces(initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface]
+
+Получает список активных сетевых интерфейсов.
+
+* **Parameters:**
+  **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных
+  координат (x, y) для интерфейсов. По умолчанию None.
+* **Returns:**
+  Список активных интерфейсов (state == “100”).
+* **Return type:**
+  List[NetworkInterface]
+
+#### *async* get_activated_interfaces_container(initial_positions: Dict[str, Tuple[int, int]] = None, container_x: int = 0, container_y: int = 0) → NetworkInterfacesContainer
+
+Получает объект, содержащий список активных интерфейсов и координаты контейнера.
+
+* **Parameters:**
+  * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных
+    координат (x, y) для интерфейсов. По умолчанию None.
+  * **container_x** (*int* *,* *optional*) – Координата X контейнера. По умолчанию 0.
+  * **container_y** (*int* *,* *optional*) – Координата Y контейнера. По умолчанию 0.
+* **Returns:**
+  Объект с активными интерфейсами и координатами.
+* **Return type:**
+  NetworkInterfacesContainer
+
+#### *async* get_connection_name(device: sdbus_async.networkmanager.NetworkDeviceGeneric) → str
+
+Извлекает имя соединения (GENERAL.CONNECTION) для устройства.
+
+* **Parameters:**
+  **device** (*NetworkDeviceGeneric*) – Объект устройства NetworkManager.
+* **Returns:**
+  Имя соединения или “unknown” в случае ошибки.
+* **Return type:**
+  str
+* **Raises:**
+  **Exception** – Если произошла ошибка при получении настроек соединения.
+
+#### *async* get_deactivated_interfaces(initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface]
+
+Получает список неактивных сетевых интерфейсов.
+
+* **Parameters:**
+  **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных
+  координат (x, y) для интерфейсов. По умолчанию None.
+* **Returns:**
+  Список интерфейсов с state != “100”.
+* **Return type:**
+  List[NetworkInterface]
+
+#### *async* get_deactivated_interfaces_container(initial_positions: Dict[str, Tuple[int, int]] = None, container_x: int = 0, container_y: int = 0) → NetworkInterfacesContainer
+
+Получает объект, содержащий список неактивных интерфейсов и координаты контейнера.
+
+* **Parameters:**
+  * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных
+    координат (x, y) для интерфейсов. По умолчанию None.
+  * **container_x** (*int* *,* *optional*) – Координата X контейнера. По умолчанию 0.
+  * **container_y** (*int* *,* *optional*) – Координата Y контейнера. По умолчанию 0.
+* **Returns:**
+  Объект с неактивными интерфейсами и координатами.
+* **Return type:**
+  NetworkInterfacesContainer
+
+#### *async* get_hostname() → Dict[str, str]
+
+Возвращает имя хоста из команды hostname в формате JSON.
+
+* **Returns:**
+  Словарь с ключом “hostname” и значением имени хоста.
+* **Return type:**
+  Dict[str, str]
+* **Raises:**
+  **RuntimeError** – Если произошла ошибка при выполнении команды hostname
+      или обработке вывода.
+
+#### *async* get_interfaces_by_state(state: str, initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface]
+
+Получает список интерфейсов по указанному состоянию.
+
+* **Parameters:**
+  * **state** (*str*) – Состояние интерфейса (например, “100” для активных).
+  * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных
+    координат (x, y) для интерфейсов. По умолчанию None.
+* **Returns:**
+  Список интерфейсов с указанным состоянием.
+* **Return type:**
+  List[NetworkInterface]
+
+#### *async* get_interfaces_container(state: str | None = None, initial_positions: Dict[str, Tuple[int, int]] = None, container_x: int = 0, container_y: int = 0) → NetworkInterfacesContainer
+
+Получает объект, содержащий список интерфейсов и координаты контейнера.
+
+* **Parameters:**
+  * **state** (*Optional* *[**str* *]* *,* *optional*) – Состояние интерфейсов (например, “100”).
+    По умолчанию None (все интерфейсы).
+  * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных
+    координат (x, y) для интерфейсов. По умолчанию None.
+  * **container_x** (*int* *,* *optional*) – Координата X контейнера. По умолчанию 0.
+  * **container_y** (*int* *,* *optional*) – Координата Y контейнера. По умолчанию 0.
+* **Returns:**
+  Объект с интерфейсами и координатами контейнера.
+* **Return type:**
+  NetworkInterfacesContainer
+
+#### *async* get_ip_config(device: sdbus_async.networkmanager.NetworkDeviceGeneric, ip_version: str) → List[IndividualIPConfig]
+
+Получает конфигурацию IP для устройства.
+
+* **Parameters:**
+  * **device** (*NetworkDeviceGeneric*) – Объект устройства NetworkManager.
+  * **ip_version** (*str*) – Версия IP (“4” или “6”).
+* **Returns:**
+  Список конфигураций IP, включая адреса и маршруты.
+* **Return type:**
+  List[IndividualIPConfig]
+* **Raises:**
+  **Exception** – Если произошла ошибка при получении данных IP.
+
+#### *async* get_ip_method(device: sdbus_async.networkmanager.NetworkDeviceGeneric, ip_type: str) → str
+
+Получает метод IP (например, “auto”, “manual”) для указанного устройства.
+
+* **Parameters:**
+  * **device** (*NetworkDeviceGeneric*) – Объект устройства NetworkManager.
+  * **ip_type** (*str*) – Тип IP (например, “ipv4” или “ipv6”).
+* **Returns:**
+  Метод IP или “unknown” в случае ошибки.
+* **Return type:**
+  str
+* **Raises:**
+  **Exception** – Если произошла ошибка при получении настроек соединения.
+
+#### *async* get_network_interfaces(initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface | WiFiDevice]
+
+Получает список сетевых интерфейсов.
+
+* **Parameters:**
+  **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных
+  координат (x, y) для интерфейсов. По умолчанию None (используются (100, 100)).
+* **Returns:**
+  Список объектов интерфейсов,
+  : включая Wi-Fi устройства.
+* **Return type:**
+  List[Union[NetworkInterface, WiFiDevice]]
+
+Исключает интерфейсы типа LOOPBACK и неактивные состояния (state == “10”).
+
+#### *async* get_network_interfaces_container(initial_positions: Dict[str, Tuple[int, int]] | None = None) → NetworkInterfacesContainer
+
+Получает контейнер с сетевыми интерфейсами и координатами контейнера.
+
+* **Parameters:**
+  **initial_positions** (*Optional* *[**Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *]* *,* *optional*) – Словарь начальных координат (x, y) для интерфейсов. По умолчанию None.
+* **Returns:**
+  Объект с интерфейсами и координатами (0, 0).
+* **Return type:**
+  NetworkInterfacesContainer
+
+#### *async* get_wifi_info(wifi_device: sdbus_async.networkmanager.NetworkDeviceWireless) → Dict[str, str | int | None]
+
+Получает информацию о Wi-Fi устройстве.
+
+* **Parameters:**
+  **wifi_device** (*NetworkDeviceWireless*) – Объект Wi-Fi устройства NetworkManager.
+* **Returns:**
+  Словарь с данными Wi-Fi (SSID, BSSID,
+  : bitrate, strength, frequency, mode), где значения могут быть None.
+* **Return type:**
+  Dict[str, Optional[Union[str, int]]]
+* **Raises:**
+  **Exception** – Если произошла ошибка при получении данных точки доступа.

SRV/docs/_build/markdown/api/services/settings_service.md

@@ -0,0 +1,43 @@
+# Settings Service
+
+### *class* services.settings_service.SettingsService(translations: Translations = Depends(translations_dependency))
+
+Bases: `object`
+
+Сервис для управления настройками и очистки данных сети.
+
+#### clear_all_data() → bool
+
+Очищает данные узлов всех подсетей и точек доступа Wi-Fi.
+
+* **Returns:**
+  True, если очистка успешна.
+* **Return type:**
+  bool
+* **Raises:**
+  **Exception** – Если произошла ошибка при записи в один из файлов.
+
+#### clear_subnet(subnet: str | None = None) → bool
+
+Очищает данные узлов подсети в указанном файле или во всех файлах.
+
+* **Parameters:**
+  **subnet** (*Optional* *[**str* *]*) – Подсеть в формате CIDR (например, “10.1.1.0/24”).
+  Если None, очищает все подсети.
+* **Returns:**
+  True, если очистка успешна.
+* **Return type:**
+  bool
+* **Raises:**
+  **Exception** – Если произошла ошибка при записи в файл.
+
+#### clear_wifi() → bool
+
+Очищает данные точек доступа Wi-Fi в файле wifi.json.
+
+* **Returns:**
+  True, если очистка успешна.
+* **Return type:**
+  bool
+* **Raises:**
+  **Exception** – Если произошла ошибка при записи в файл.

SRV/docs/_build/markdown/api/services/subnet_service.md

@@ -0,0 +1,272 @@
+# Subnet Service
+
+### *class* services.subnet_service.DeviceInfoCollector(translations: Translations)
+
+Bases: `object`
+
+Класс для сбора информации об устройствах, включая вендоров и хостнеймы.
+
+Источники данных:
+: - MacLookup: сопоставление префикса MAC (OUI) с названием производителя.
+  - DNS: gethostbyaddr с малым таймаутом для обратного разрешения имени.
+  - NetBIOS (nbtscan): опрос сегмента сети для извлечения NetBIOS‑имён.
+
+Политика кэширования:
+: - Результаты get_vendor кэшируются с помощью functools.lru_cache.
+  - Результаты nbtscan аккумулируются в словарях nbtscan_cache/nbtscan_results
+    на время жизни экземпляра.
+
+#### get_hostname(ip: str) → str | None
+
+Получает хостнейм для указанного IP-адреса.
+
+Пробует сначала DNS, затем NetBIOS.
+
+* **Parameters:**
+  **ip** (*str*) – IP-адрес устройства.
+* **Returns:**
+  Хостнейм или None, если не удалось определить.
+* **Return type:**
+  Optional[str]
+
+#### get_vendor(mac: str) → str
+
+Получает вендора устройства по MAC-адресу.
+
+Использует кэширование для повышения производительности.
+
+* **Parameters:**
+  **mac** (*str*) – MAC-адрес устройства.
+* **Returns:**
+  Название вендора или “Неизвестный” в случае ошибки.
+* **Return type:**
+  str
+
+#### scan_nbtscan(subnet: str) → None
+
+Сканирует подсеть с помощью nbtscan для получения хостнеймов.
+
+Сохраняет результаты в кэш и логирует процесс.
+
+* **Parameters:**
+  **subnet** (*str*) – Подсеть в формате CIDR.
+
+### *class* services.subnet_service.DeviceStorage(base_path: str = 'storage/subnets', translations: Translations = None)
+
+Bases: `object`
+
+Класс для хранения и управления данными об устройствах.
+
+Формат файла подсети:
+
+```default
+{
+  "devices": [Device, ...]
+}
+```
+
+Политика очистки:
+
+- Метод \_clean_old_devices удаляет оффлайн‑устройства, не наблюдавшиеся более 7 дней,
+  чтобы поддерживать актуальность списка.
+
+#### get_subnet_file(subnet: str) → Path
+
+Возвращает путь к файлу для конкретной подсети.
+
+Заменяет символы ‘/’ на ‘_’ для корректного имени файла.
+
+* **Parameters:**
+  **subnet** (*str*) – Подсеть в формате CIDR.
+* **Returns:**
+  Путь к файлу.
+* **Return type:**
+  Path
+
+#### load_devices(subnet: str) → Dict[str, Device]
+
+Загружает устройства для указанной подсети.
+
+Читает данные из JSON-файла и фильтрует устаревшие устройства.
+
+* **Parameters:**
+  **subnet** (*str*) – Подсеть в формате CIDR.
+* **Returns:**
+  Словарь устройств с MAC как ключом.
+* **Return type:**
+  Dict[str, Device]
+
+#### save_devices(subnet: str, devices: List[Device]) → None
+
+Сохраняет устройства для указанной подсети.
+
+Записывает данные в JSON-файл.
+
+* **Parameters:**
+  * **subnet** (*str*) – Подсеть в формате CIDR.
+  * **devices** (*List* *[**Device* *]*) – Список устройств для сохранения.
+* **Raises:**
+  **Exception** – Если произошла ошибка при сохранении.
+
+### *class* services.subnet_service.NetworkScanner(interface: str, translations: Translations)
+
+Bases: `object`
+
+Класс для сканирования подсети с использованием ARP-запросов.
+
+Назначение:
+: Обнаруживает активные устройства в локальной сети, отправляя широковещательные
+  ARP‑запросы по указанной подсети и собирая ответы (IP, MAC).
+
+Детали реализации:
+: - Использует scapy (Ether + ARP) для генерации пакетов и srp для
+    отправки/получения на канальном уровне от имени заданного интерфейса.
+  - Таймаут ожидания ответа короткий (2 секунды), ориентирован на интерактивные
+    сценарии UI.
+
+Ограничения и замечания:
+: - Требуются права для отправки низкоуровневых пакетов (capabilities/root).
+  - В сетях с фильтрацией широковещания количество обнаруженных устройств
+    может быть ограничено.
+
+#### scan(subnet: str) → List[Tuple[str, str]]
+
+Сканирует подсеть с использованием ARP-запросов.
+
+Отправляет ARP-пакеты для обнаружения активных устройств и возвращает
+список кортежей (IP, MAC).
+
+* **Parameters:**
+  **subnet** (*str*) – Подсеть в формате CIDR (например, “10.1.1.0/24”).
+* **Returns:**
+  Список кортежей (IP-адрес, MAC-адрес) обнаруженных устройств.
+* **Return type:**
+  List[Tuple[str, str]]
+* **Raises:**
+  **Exception** – Если произошла ошибка сканирования.
+
+### *class* services.subnet_service.PortScanner(interface: str, translations: Translations)
+
+Bases: `object`
+
+Класс для сканирования открытых портов на устройствах.
+
+Назначение:
+: Плейсхолдер для будущего функционала активного сканирования TCP/UDP‑портов
+  у обнаруженных узлов. В текущей версии возвращает пустой список.
+
+План развития:
+: - Добавить неблокирующее сканирование наиболее распространённых портов
+    (22, 80, 443 и т.д.) с ограничением по времени.
+  - Настраиваемые профили глубины и скорости сканирования.
+
+#### scan(ip: str) → List[str]
+
+Сканирует открытые порты на указанном IP-адресе.
+
+Пока возвращает пустой список, так как функциональность не реализована.
+
+* **Parameters:**
+  **ip** (*str*) – IP-адрес устройства для сканирования.
+* **Returns:**
+  Список открытых портов (пока пустой).
+* **Return type:**
+  List[str]
+
+### *class* services.subnet_service.SubnetService(translations: Translations)
+
+Bases: `object`
+
+Сервис для сканирования подсетей и управления устройствами.
+
+Роль сервиса:
+: Объединяет сетевое сканирование (ARP), сбор дополнительной информации
+  (вендор, хостнейм), слияние с кэшем предыдущих результатов и персистентное
+  хранение данных по подсетям. Предоставляет вспомогательные операции для
+  локального узла и работы с заметками устройств.
+
+Поток выполнения скана (scan_subnet):
+: 1. Определение подсети (вручную или авто по интерфейсу).
+  2. Загрузка ранее сохранённых устройств подсети.
+  3. Добавление локального устройства (если принадлежит подсети).
+  4. ARP‑сканирование и параллельная обработка узлов (обогащение данных).
+  5. Маркировка оффлайн‑узлов из кэша, не встреченных в текущем скане.
+  6. Сортировка по IP и сохранение объединённого списка в JSON.
+
+#### add_note(mac: str, note: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None]
+
+Добавляет заметку для устройства по MAC-адресу.
+
+Привязывает заметку к устройству, если оно существует.
+
+* **Parameters:**
+  * **mac** (*str*) – MAC-адрес устройства.
+  * **note** (*str*) – Текст заметки.
+  * **translations** (*Translations*) – Объект переводов для текущего языка.
+* **Returns:**
+  Кортеж (успех, результат),
+  : где результат содержит код ошибки/успеха и данные.
+* **Return type:**
+  Tuple[bool, Optional[Tuple[str, Dict]]]
+
+#### delete_note(mac: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None]
+
+Удаляет заметку для устройства по MAC-адресу.
+
+Удаляет привязанную заметку, если она существует.
+
+* **Parameters:**
+  * **mac** (*str*) – MAC-адрес устройства.
+  * **translations** (*Translations*) – Объект переводов для текущего языка.
+* **Returns:**
+  Кортеж (успех, результат),
+  : где результат содержит код ошибки/успеха и данные.
+* **Return type:**
+  Tuple[bool, Optional[Tuple[str, Dict]]]
+
+#### scan_subnet(subnet: str | None = None) → SubnetScanResult
+
+Сканирует указанную подсеть и возвращает результаты.
+
+Выполняет ARP-сканирование, собирает информацию о устройствах и сохраняет данные.
+
+* **Parameters:**
+  **subnet** (*Optional* *[**str* *]*) – Подсеть в формате CIDR (например, “10.1.1.0/24”).
+  Если None или пустая строка, определяется автоматически.
+* **Returns:**
+  Объект с результатами сканирования, содержащий список
+  : устройств или сообщение об ошибке.
+* **Return type:**
+  SubnetScanResult
+* **Raises:**
+  **Exception** – Если произошла ошибка сканирования.
+
+#### update_note(mac: str, note: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None]
+
+Обновляет заметку для устройства по MAC-адресу.
+
+Изменяет существующую заметку, если она есть.
+
+* **Parameters:**
+  * **mac** (*str*) – MAC-адрес устройства.
+  * **note** (*str*) – Новый текст заметки.
+  * **translations** (*Translations*) – Объект переводов для текущего языка.
+* **Returns:**
+  Кортеж (успех, результат),
+  : где результат содержит код ошибки/успеха и данные.
+* **Return type:**
+  Tuple[bool, Optional[Tuple[str, Dict]]]
+
+### services.subnet_service.get_subnet_service(translations: Translations = Depends(translations_dependency))
+
+Фабричная функция для создания экземпляра SubnetService.
+
+Использует зависимости FastAPI для получения объекта переводов и возвращает
+экземпляр SubnetService с текущей локализацией.
+
+* **Parameters:**
+  **translations** (*Translations*) – Объект переводов для текущего языка.
+* **Returns:**
+  Экземпляр сервиса для работы с подсетями.
+* **Return type:**
+  SubnetService

SRV/docs/_build/markdown/api/services/ufw_service.md

@@ -0,0 +1,108 @@
+# UFW Service
+
+### *class* services.ufw_service.UFWService
+
+Bases: `object`
+
+Сервис взаимодействия с UFW (Uncomplicated Firewall).
+
+Назначение:
+: - Чтение статуса и списка правил брандмауэра.
+  - Добавление, удаление и массовая обработка правил с поддержкой диапазонов портов,
+    комментариев и выбором протоколов.
+
+Детали реализации:
+: - Команды выполняются через sudo ufw …; вывод парсится в модели pydantic.
+  - Для операций удаления соблюдается порядок с конца, чтобы не нарушать нумерацию.
+
+#### add_rules(rules: List[UFWRule]) → dict
+
+Добавляет правила UFW.
+
+* **Parameters:**
+  **rules** – Список правил для добавления
+* **Returns:**
+  Результат добавления правил
+* **Return type:**
+  dict
+
+#### add_rules_base(rules: List[UFWRule], direction: str = '') → bool
+
+Базовый метод для добавления правил UFW.
+
+* **Parameters:**
+  * **rules** – Список правил для добавления
+  * **direction** – Направление трафика (“in” или “out”)
+* **Returns:**
+  True если все правила были успешно добавлены, False в противном случае
+* **Return type:**
+  bool
+
+#### add_ufw_in_rules(rules: List[UFWRule]) → bool
+
+Добавляет входящие (in) правила UFW.
+
+* **Parameters:**
+  **rules** (*List* *[**UFWRule* *]*) – Список правил для добавления
+* **Returns:**
+  True если все правила были успешно добавлены, False в противном случае
+* **Return type:**
+  bool
+
+#### add_ufw_out_rules(rules: List[UFWRule]) → bool
+
+Добавляет исходящие (out) правила UFW.
+
+* **Parameters:**
+  **rules** (*List* *[**UFWRule* *]*) – Список правил для добавления
+* **Returns:**
+  True если все правила были успешно добавлены, False в противном случае
+* **Return type:**
+  bool
+
+#### delete_rules(rule_numbers: List[int]) → dict
+
+Удаляет правила UFW по их номерам.
+
+* **Parameters:**
+  **rule_numbers** (*List* *[**int* *]*) – Список номеров правил для удаления
+* **Returns:**
+  Результат операции удаления
+* **Return type:**
+  dict
+
+#### disable_ufw() → bool
+
+Выключает UFW.
+
+* **Returns:**
+  True если успешно выключен, False в противном случае
+* **Return type:**
+  bool
+
+#### enable_ufw() → bool
+
+Включает UFW.
+
+* **Returns:**
+  True если успешно включен, False в противном случае
+* **Return type:**
+  bool
+
+#### get_ufw_rules() → UFWRulesResponse
+
+Получает список правил UFW.
+
+* **Returns:**
+  Объект, содержащий статус UFW и список правил
+* **Return type:**
+  UFWRulesResponse
+
+#### get_ufw_status() → UFWStatus
+
+Проверяет статус UFW.
+
+* **Returns:**
+  Объект с информацией о статусе UFW
+* **Return type:**
+  UFWStatus

SRV/docs/_build/markdown/api/services/wifi_service.md

@@ -0,0 +1,61 @@
+# Wifi Service
+
+### *class* services.wifi_service.WifiService(translations: Translations = Depends(translations_dependency))
+
+Bases: `object`
+
+Сервис для сканирования текущих Wi‑Fi точек доступа и заметок.
+
+Источники данных:
+: - pywifi для базового сканирования и получения списка AP.
+  - iw dev <iface> scan для уточнения частоты, сигнала и безопасности.
+  - MacLookup для определения вендора по BSSID.
+
+Политики:
+: - Выбор лучшего AP по SSID по уровню сигнала.
+  - Кэширование определения вендора.
+  - Сохранение SSID даже без заметок для будущих операций.
+
+#### add_note(ssid: str, note: str) → Tuple[bool, str | None]
+
+Добавляет заметку к сети Wi-Fi по SSID.
+
+#### delete_note(ssid: str) → Tuple[bool, str | None]
+
+Удаляет заметку сети Wi-Fi по SSID.
+
+#### get_vendor(mac: str) → str
+
+Определяет вендора по MAC-адресу с использованием кэширования.
+
+#### scan_wifi(timeout: int = 30) → WifiScanResult
+
+Сканирует текущие Wi-Fi точки доступа.
+
+#### update_note(ssid: str, note: str) → Tuple[bool, str | None]
+
+Обновляет заметку сети Wi-Fi по SSID.
+
+### *class* services.wifi_service.WifiStorage(storage_path: str = 'storage/wifi/wifi.json', translations: Translations = Depends(translations_dependency))
+
+Bases: `object`
+
+Класс для хранения данных о Wi‑Fi сетях и их заметках по SSID.
+
+Формат:
+: {
+  : “networks”: [{“ssid”: str, “note”: Optional[str]}]
+  <br/>
+  }
+
+Поведение:
+: - Создаёт директорию хранения при инициализации, ведёт логирование путей.
+  - Валидация структуры при чтении, безопасная запись с Unicode и отступами.
+
+#### load_notes() → Dict[str, str | None]
+
+Загружает заметки по SSID из файла хранения.
+
+#### save_notes(notes: Dict[str, str | None]) → None
+
+Сохраняет заметки по SSID в файл.