Обзор системы ============== Назначение ---------- TVIP Provisioning Service — это система автоматической конфигурации TVIP-приставок через механизм provisioning. Сервис обрабатывает запросы от приставок, управляет конфигурациями и предоставляет API для администрирования. Принцип работы -------------- Общая схема работы ~~~~~~~~~~~~~~~~~~ 1. TVIP-приставка делает запрос ``/prov/tvip_provision.xml`` с заголовком ``Mac-Address`` 2. Backend проверяет наличие устройства в базе данных 3. Если устройство отсутствует — создаётся новая запись и возвращается дефолтная конфигурация 4. Если устройство существует — возвращается его кастомная конфигурация или дефолтная 5. Администратор может управлять конфигурациями через API или веб-интерфейс Диаграмма взаимодействия ~~~~~~~~~~~~~~~~~~~~~~~~~ .. mermaid:: sequenceDiagram participant T as TVIP Приставка participant P as Provision Service participant D as PostgreSQL participant F as Frontend Note over T: Первое обращение T->>P: GET /prov/tvip_provision.xml P->>D: Проверка устройства D-->>P: Не найдено P->>D: Создание записи P->>D: Получение дефолтного конфига D-->>P: XML конфигурация P-->>T: Возврат дефолтного конфига Note over T: Последующие запросы T->>P: GET /prov/tvip_provision.xml P->>D: Поиск конфигурации D-->>P: Кастомный/дефолтный конфиг P-->>T: Возврат конфига Note over F: Администрирование F->>P: GET /api/devices P-->>F: Список устройств F->>P: PUT /api/default/config/replace P->>D: Обновление дефолтного конфига F->>P: PUT /api/devices/{mac}/config/replace P->>D: Обновление конфига устройства F->>P: POST /api/devices/{mac}/config/reset P->>D: Сброс конфига к дефолту Архитектурные принципы ---------------------- Clean Architecture ~~~~~~~~~~~~~~~~~~ Проект построен на основе **Clean Architecture** с чётким разделением на слои: * **Domain Layer** — доменные сущности, value objects, интерфейсы репозиториев * **Application Layer** — use cases с бизнес-логикой * **Infrastructure Layer** — реализация репозиториев, БД, DI * **Presentation Layer** — REST API endpoints Dependency Injection ~~~~~~~~~~~~~~~~~~~~ Используется встроенный механизм FastAPI ``Depends()`` для инжекции зависимостей. Провайдеры зарегистрированы в ``infrastructure/di/injection.py``. Repository Pattern ~~~~~~~~~~~~~~~~~~ Абстракция доступа к данным через интерфейсы репозиториев позволяет легко заменять реализацию хранилища. Технологический стек -------------------- Backend ~~~~~~~ * **Python 3.9+** — язык программирования * **FastAPI** — веб-фреймворк для REST API * **SQLAlchemy 2.0** — ORM для работы с PostgreSQL * **Pydantic** — валидация данных * **asyncpg** — асинхронный драйвер для PostgreSQL * **xmltodict** — сериализация конфигураций в XML * **pydash** — работа с вложенными структурами (dot notation) * **Uvicorn** — ASGI сервер Frontend ~~~~~~~~ * **React 18** — UI библиотека * **Vite** — сборщик и dev сервер * **Axios** — HTTP клиент * **React Router** — маршрутизация Инфраструктура ~~~~~~~~~~~~~~ * **PostgreSQL** — СУБД * **Docker** — контейнеризация * **Docker Compose** — оркестрация контейнеров * **Nginx** — reverse proxy * **Supervisord** — управление процессами в контейнере Форматы данных -------------- XML конфигурация ~~~~~~~~~~~~~~~~ TVIP-приставки получают конфигурацию в формате XML. Корневой элемент — ````. Пример структуры: .. code-block:: xml Dot notation ~~~~~~~~~~~~ Для API используется формат **dot notation** — плоское представление XML структуры с точками для навигации по иерархии. Атрибуты обозначаются префиксом ``@``. Пример: .. code-block:: json { "provision.@reload": "86400", "provision.operator.@name": "MyOperator", "provision.time.@tz": "Europe/Moscow", "provision.time.@ntp": "pool.ntp.org", "provision.tv_protocols.@default": "stalker", "provision.tv_protocols.protocol.@type": "stalker", "provision.tv_protocols.protocol.@server": "http://portal.example.com" } Метаданные устройства ~~~~~~~~~~~~~~~~~~~~~~ Система хранит следующую информацию об устройствах: * **MAC-адрес** — уникальный идентификатор (формат ``XX:XX:XX:XX:XX:XX``) * **IP-адрес** — последний известный IP * **Модель приставки** — строка из заголовка ``tvip-model`` * **Время последней активности** — последний запрос конфигурации * **ID кастомной конфигурации** — ссылка на индивидуальную конфигурацию (если установлена) Сценарии использования ----------------------- Базовое развертывание ~~~~~~~~~~~~~~~~~~~~~ Для типичного развертывания требуется: 1. Настроить DNS или hosts файл для перенаправления ``tvipupdate.net`` на IP сервера 2. Запустить систему через Docker Compose 3. Настроить дефолтную конфигурацию через API или веб-интерфейс 4. TVIP-приставки автоматически получат конфигурацию при подключении Управление устройствами ~~~~~~~~~~~~~~~~~~~~~~~~ * Просмотр списка зарегистрированных устройств * Фильтрация по IP, модели, времени активности * Настройка индивидуальной конфигурации для конкретной приставки * Сброс к дефолтной конфигурации Управление конфигурациями ~~~~~~~~~~~~~~~~~~~~~~~~~~ * Получение и изменение дефолтной конфигурации * Частичное обновление параметров (PATCH-like через PUT с dot notation) * Полная замена конфигурации * Экспорт/импорт конфигураций Мониторинг ~~~~~~~~~~ * Отслеживание активности устройств (Требует реализации) * Проверка времени последнего обращения * Аудит изменений конфигураций (Требует реализации) Ограничения и требования ------------------------- Сетевые требования ~~~~~~~~~~~~~~~~~~ * TVIP-приставки должны иметь доступ к серверу на порту **7373** (или 80/443 при использовании nginx) * Необходима подмена DNS записи ``tvipupdate.net`` или настройка hosts файла на приставках Производительность ~~~~~~~~~~~~~~~~~~ Точное оценивание нагрузки зависит от количества устройств и частоты запросов. Пока что не было возможность провести полноценное тестирование под нагрузкой. (Все тесты упирались в железо. Поэтому количестро rps невозможно указать.) Но из рекомендаций можно выделить следующее: * PostgreSQL должна быть настроена для работы с большим количеством одновременных подключений * Рекомендуется использовать connection pooling * Для высоконагруженных систем рассмотреть масштабирование backend через Kubernetes Безопасность ~~~~~~~~~~~~ * API не имеет встроенной аутентификации (рекомендуется настроить на уровне nginx) * База данных должна быть доступна только внутри Docker сети * Рекомендуется использовать HTTPS для production окружения Следующие шаги -------------- * :doc:`developer-guide/getting-started` — быстрый старт для разработчиков * :doc:`deployment/index` — инструкции по развертыванию * :doc:`api/index` — полная документация REST API * :doc:`architecture/index` — детальное описание архитектуры