drhider/History/upload-integration/2026-09-15-upload-platform-integration-plan.md

План интеграции upload-platform (v0.2.2) в drhider

Дата: 2026-09-15
Статус: План составлен, ожидает команды на выполнение
Целевой сервис: drhider (Managed Flask на платформе Штурвал)
Источник модуля: upload-platform/ (релиз v0.2.2, commit df0576a)

---

1. Контекст и цели

В drhider (v0.0.77) модуль загрузки upload/ зафиксирован в промежуточном состоянии:

• Фронтенд Слоя 1 использует устаревшую табличную вёрстку с ручным парсингом ZIP без поддержки древовидного сворачивания.
• Слой 2 работает по смешанной схеме, в то время как в upload-platform v0.2.2 реализован и протестирован чистый пофайловый транзит (Streaming transit: PUT \to POST /api/upload_refs \to исходящий pull в RAM \to немедленный DELETE \to repeat).

Цель интеграции:
Заменить устаревшие наработки в upload/ и site/templates/index.html на проверенную автономную версию upload-platform v0.2.2 без нарушения бизнес-логики обфускации (Слой 3: LLM, SSE-стриминг, генерация ZIP).

---

2. Границы ответственности слоёв

┌────────────────────────────────────────────────────────────────────────┐
│                              БРАУЗЕР                                   │
│  [ Слой 1: FilePicker ] ──► [ Слой 2: uploadViaVM ]                    │
└─────────────────────────────────────┬──────────────────────────────────┘
                                      │ 1. PUT файл
                                      ▼
                       ┌─────────────────────────────┐
                       │   ВМ-буфер (RAM WebDAV)     │
                       └──────────────┬──────────────┘
                                      │ 3. Исходящий GET (pull в RAM)
                                      │ 4. DELETE с ВМ
                                      ▼
┌────────────────────────────────────────────────────────────────────────┐
│                           FLASK BACKEND                                │
│  [ Слой 2: Blueprint upload_refs ] ──► [ RAM-сессия: add_file ]        │
│                                                   │                    │
│  [ Слой 3: drhider engine ] ◄─────────────────────┘ get_files(sid)     │
│  (SSE-прогресс, обфускация, mapping, download)                        │
└────────────────────────────────────────────────────────────────────────┘

• Слой 1 (Фронтенд): инициализация через FilePicker.initFilePicker(). Полностью изолирован от транспорта. Возвращает список объектов File через picker.getFiles().
• Слой 2 (Фронтенд + Бэкенд): uploadViaVM передаёт файлы по одному через буфер на ВМ в RAM сессии Flask.
• Слой 3 (drhider): логика обфускации забирает готовые файлы из upload.backend.session.get_files(sid) и запускает существующий пайплайн (/api/drhider/<sid>).

---

3. Этапы интеграции

Этап 1. Синхронизация модуля ядра (upload/)

1. Заменить содержимое upload/ в корне drhider на актуальную версию из upload-platform/upload/:
   • upload/backend/: актуальные upload_refs/ (поддержка httpxTransport, безопасный pull, санитизация safe_name) и session/ (хранилище в RAM, TTL, блокировки).
   • upload/frontend/: чистые ES-модули (index.js, table/, upload/, zip/ на базе fflate).
2. Скопировать готовые бандлы из upload-platform/dist/ в site/static/dist/ (или настроить прямую раздачу из upload/frontend через main_bp.py).

Этап 2. Проверка и настройка бэкенда (site/routes/)

1. Проверить регистрацию Blueprint в site/routes/__init__.py:

   app.register_blueprint(create_upload_refs_blueprint({
       "apiPrefix": "/api",
       "vmUploadPrefix": "https://contracts.kube5s.ru/drhider-upload/",
       "maxFileBytes": 50 * 1024 * 1024,
       "maxSessionBytes": 500 * 1024 * 1024,
       "ttlSeconds": 30 * 60,
       "pullRetries": 3,
       "pullRetryDelay": 2,
   }))
   

2. Убедиться, что site/routes/api_bp.py бесшовно использует сессии из обновлённого upload.backend.session.

Этап 3. Обновление пользовательского интерфейса (site/templates/index.html)

1. Заменить устаревшую ручную вёрстку таблицы и инпутов на контейнер для монтирования Слой 1:

   <div id="file-picker-container"></div>
   

2. Подключить модуль initFilePicker и сконфигурировать фильтрацию по .pdf, .doc, .docx, .txt, .md.
3. Модифицировать обработчик кнопки «🛡️ Обфусцировать»:
   • Вызов uploadViaVM(files, { vmUploadUrl, backendUploadUrl, onFileStatus, onProgress }).
   • По завершении загрузки всех файлов — автоматический переход к Стек/Фазе 2: запуск SSE-стрима /api/drhider/<sid>.
4. Сохранить существующий трёхсекционный рендер обработки (Готово / Обрабатывается / Ожидают) и индикацию ETA/статистики LLM.

Этап 4. Тестирование и валидация

1. Автономные тесты модуля upload:
   • Запуск pytest для upload/ внутри drhider.
2. Интеграционные тесты drhider:
   • Запуск существующих тестов tests/test_builder.py, tests/test_extractor.py, tests/test_replacer.py, tests/test_scanner.py.
3. Ручная/Smoke проверка сквозного цикла:
   • Выбор одиночного документа, папки и архива ZIP.
   • Проверка пофайловой загрузки через буфер и немедленного удаления с ВМ.
   • Проверка успешного прохождения двухпроходной обфускации и скачивания результирующего архива.

---

4. Контрольные точки (Definition of Done)

• Все тесты pytest tests/ завершаются успешно (PASS).
• Отсутствуют временные файлы на диске (всё в RAM).
• Не нарушена логика отмены (cancel) и работы со стримами SSE.
• Сборка и синтаксис проверены через py_compile.
• Документ с отчётом о завершении зафиксирован в History/upload-integration/.