# Интеграция верификатора в SOC-проект

Документ описывает перенос пользовательского интерфейса верификатора в проект на Django со структурой `SOC/apps`, `SOC/templates` и `SOC/static`. Цель — развернуть модуль без конфликтов с другими приложениями и обеспечить автономную загрузку статики.

## Предпосылки и окружение
- Проект содержит каталог `SOC` с подпапками `apps`, `templates`, `static` и служебными файлами `manage.py`, `asgi.py`, `wsgi.py`.
- Доступно подключение внешних библиотек через CDN или локальное хранение загруженных файлов.
- В конфигурации допускается установка собственного базового URL для статики и выделенного каталога для собранных файлов.

## Сетевая схема и адресация
- Внутренний домен `example1.com` доступен из локальной сети и проксирует все запросы к префиксу `/ext/` на DMZ-сервер `example2.com`.
- Django и UI верификатора размещены на `example2.com` и обслуживают интерфейс по адресу `https://example2.com/ext/admin/verificator/ui/` (через прокси из локалки — `https://example1.com/ext/admin/verificator/ui/`).
- API рекомендуется публиковать по пути `https://example2.com/ext/api/verificator/` (и через прокси — `https://example1.com/ext/api/verificator/`), чтобы сохранять общий префикс `/ext/` и изоляцию от остальных сервисов.

## Структура модуля
- Каталог `SOC/apps/verificator` включает модель, административный класс и обработчик страницы, работающие изолированно от остальных приложений.
- Шаблон размещён в `SOC/templates/verificator` и использует переменные `STATIC_BASE` и `VENDOR_BASE` для переключения между локальными ресурсами и CDN.
- Статические файлы находятся в `SOC/static/verificator`; при необходимости там создаётся подпапка `vendor` для локально загруженных зависимостей и `icons` для вспомогательных изображений.

## Подготовка путей и настройки
- В модуле настроек требуется добавить каталог `SOC/apps` в переменную поиска модулей Python, чтобы приложение было доступно под коротким именем.
- Список установленных приложений должен содержать запись `verificator`; благодаря добавленному пути не требуется указывать префикс `SOC.apps` в импортах и настройках.
- Для публикации статики следует использовать URL `/ext/static/` и корневой каталог `assets`, сохранив каталог исходных файлов `SOC/static` в перечне директорий поиска.

## Маршрутизация и API
- Маршрут интерфейса регистрируется в общем файле маршрутов, подключая обработчик из короткого пути приложения. Путь `/verificator/` открывает страницу без пересечения с остальными модулями и отражается наружу как `https://example2.com/ext/admin/verificator/ui/`.
- При подключении REST/HTTP API используйте базовый префикс `/ext/api/verificator/`, чтобы любой вызов автоматически проходил через внешний прокси и не конфликтовал с существующими API-путями проекта.
- В административной панели доступны элементы для просмотра страницы и её встраивания в iframe; они используют те же настройки путей и не требуют дополнительных разрешений.

## Работа со статикой и зависимостями
- При использовании CDN переменная `VENDOR_BASE` указывает на внешний источник и применяется в шаблоне и скриптах для загрузки Bootstrap, Gridstack и Bootstrap Icons.
- Для локальной работы служебный скрипт `scripts/download_vendor_assets.py` сохраняет зависимости в `SOC/static/verificator/vendor` и подготавливает иконку MalwareBazaar в `SOC/static/verificator/icons`; после загрузки собранные файлы доступны по новому статическому URL.
- Перед публикацией рекомендуется выполнить сборку статики в каталог `assets`, чтобы настроенный URL `/ext/static/` обслуживал все ресурсы без обращений к CDN.

## Nginx-прокси
### DMZ-сервер `example2.com`
Размещаем отдельный серверный блок, обслуживающий только префикс `/ext/`, чтобы не затронуть остальные проекты на хосте:

```
server {
    listen 443 ssl;
    server_name example2.com;

    # Статика собранного проекта
    location /ext/static/ {
        alias /var/www/example2/assets/;
        access_log off;
        expires 30d;
    }

    # UI и API верификатора
    location /ext/ {
        proxy_pass http://127.0.0.1:8000$request_uri;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Статический префикс `/ext/static/` совпадает с настройками Django (`STATIC_URL` и `STATIC_ROOT`), а общий блок `/ext/` отдаёт UI (`/ext/admin/verificator/ui/`) и API (`/ext/api/verificator/`). Остальные серверные блоки продолжают обслуживать прочие домены и приложения.

### Внутренний сервер `example1.com`
Создаём прокси-блок, который пробрасывает только префикс `/ext/` в DMZ, не затрагивая остальной трафик локального портала:

```
server {
    listen 443 ssl;
    server_name example1.com;

    location /ext/ {
        proxy_pass https://example2.com$request_uri;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

За счёт единого префикса `/ext/` UI и API доступны из локальной сети по тому же пути, что и во внешнем контуре, без перехвата остальных маршрутов портала.

## Проверка интеграции
- После переноса запустите сервер разработки и откройте путь `/verificator/`, чтобы убедиться в корректной загрузке шаблона и тем оформления.
- В административной панели проверьте отображение встроенной версии интерфейса в iframe и корректность логов рендеринга.
- Убедитесь, что внешний путь `https://example1.com/ext/admin/verificator/ui/` открывается через прокси, а вызовы к `https://example1.com/ext/api/verificator/` достигают Django без ошибок 404/502.
- Выполните автоматические тесты и убедитесь, что сервисные скрипты завершаются без ошибок при загрузке внешних зависимостей.

## Типичные ошибки
- Если интерфейс не загружается из-за ошибки `app_label`, необходимо убедиться, что каталог `SOC/apps` добавлен в переменную поиска модулей и приложение подключено под именем `verificator`.
- При получении ошибок 404 для статики проверьте соответствие фактического каталога сборки и базового URL `/ext/static/`, а также наличие загруженных зависимостей в каталоге `vendor`.
