Маршруты файлового архива

Группа маршрутов /api/archive отвечает за хранение оригиналов загруженных файлов в виде иерархической файловой структуры. Архив позволяет загружать файлы по одному или пачками (ZIP-архивы), просматривать дерево папок, перемещать и переименовывать элементы, запускать обработку, а также импортировать файлы с Яндекс.Диска и через контрактный импорт по именам файлов.

Исходный файл: backend/app/api/routes/archive.py.

Загрузка файлов

POST /api/archive/upload-zip

Загружает ZIP-архив с сохранением внутренней структуры папок.

Параметры формы:

Параметр	Тип	Описание
file	файл	ZIP-архив (обязательный)
base_path	строка	Базовый путь, куда положить содержимое (например, Электронный архив/2009)

Что происходит при загрузке:

1. Архив сохраняется во временный файл на диске (потоковая запись блоками по 10 МБ).
2. Проверяется, что файл является корректным ZIP (первые два байта --- PK).
3. Из архива извлекаются только поддерживаемые файлы (PDF и TIFF). Системные файлы macOS (__MACOSX) пропускаются.
4. Имена файлов с кириллицей декодируются корректно: если флаг UTF-8 не установлен, имя перекодируется из CP437 в CP866.
5. Файлы TIFF автоматически преобразуются в PDF.
6. Каждый файл проверяется на дубликат (совпадение пути и размера). Дубликаты пропускаются.
7. Файл загружается в хранилище MinIO (в корзину originals).
8. В коллекции archive_files создаётся запись со статусом pending.

Ответ содержит: количество добавленных файлов, список созданных папок, количество пропущенных дубликатов, общий размер.

POST /api/archive/upload-zip-from-path

Аналогичен upload-zip, но принимает путь к ZIP-файлу на сервере вместо загрузки через браузер. Предназначен для очень больших файлов (4 ГБ и более), которые невозможно загрузить через HTTP.

Параметр	Тип	Описание
file_path	строка	Путь к файлу на сервере
base_path	строка	Базовый путь в архиве

POST /api/archive/upload-file

Загружает один файл PDF или TIFF в указанную папку.

Параметр	Тип	Описание
file	файл	PDF или TIFF (обязательный)
path	строка	Путь к папке, например 2009/Январь/Акты

Если файл с таким путём и размером уже существует, возвращается ошибка 409.

Просмотр дерева архива

GET /api/archive/tree

Возвращает полное дерево папок и файлов. Учитывает как реальные папки (созданные из путей файлов), так и пустые папки-маркеры из коллекции archive_folders.

Параметр	Тип	Описание
path	строка	Базовый путь (пустой --- корень)

Ответ содержит рекурсивное дерево (tree), а также статистику: общее количество файлов, общий размер, количество файлов со статусом pending и completed.

Ограничение

Этот адрес загружает до 10 000 файлов за один запрос. Для больших архивов используйте ленивую загрузку через /tree/children.

GET /api/archive/tree/children

Возвращает непосредственных потомков указанной папки без рекурсии. Используется для ленивой загрузки дерева в интерфейсе.

Параметр	Тип	По умолчанию	Описание
path	строка	---	Путь к папке
skip	число	0	Пропустить N файлов (папки возвращаются все)
limit	число	50	Максимальное количество файлов

Папки возвращаются со счётчиками: общее число файлов, ожидающие обработки, обработанные, отменённые, с ошибкой, общий размер. Пустые папки-маркеры включаются отдельно.

Ответ содержит: путь, массив потомков (children), количество папок и файлов, общее число файлов, признак наличия следующей страницы (has_more).

Внутри используется конвейер агрегации MongoDB ($facet), который разделяет результаты на файлы (с постраничным выводом) и папки (сгруппированные по первому сегменту пути).

Получение списка и статистики

GET /api/archive/files

Возвращает плоский список файлов в архиве.

Параметр	Тип	По умолчанию	Описание
path	строка	---	Фильтр по пути (совпадение начала)
status	строка	---	Фильтр по статусу (pending, processing, completed, failed)
skip	число	0	Сколько записей пропустить
limit	число	100	Максимальное количество записей

GET /api/archive/unprocessed-count

Возвращает количество файлов в архиве, у которых нет связанного задания обработки (job_id равен null).

GET /api/archive/stats

Возвращает статистику архива: общее количество файлов, общий размер, количество файлов в каждом статусе (pending, processing, completed, failed), список всех папок.

Операции с файлами и папками

GET /api/archive/file/{file_id}

Возвращает подробные сведения о файле. Если файл обработан (есть job_id), дополнительно возвращаются данные задания (состояние, число найденных документов, групп, страниц) и список извлечённых документов.

GET /api/archive/file/{file_id}/view

Отдаёт PDF-файл для просмотра в браузере (заголовок Content-Disposition: inline).

GET /api/archive/file/{file_id}/download

Отдаёт PDF-файл для скачивания (заголовок Content-Disposition: attachment).

DELETE /api/archive/file/{file_id}

Удаляет файл из архива (запись в базе данных).

GET /api/archive/download-folder

Скачивает папку как ZIP-архив с сохранением внутренней структуры. Файлы загружаются из MinIO и упаковываются в архив с относительными путями.

Параметр	Тип	Описание
path	строка	Путь к папке (обязательный)

POST /api/archive/folder

Создаёт пустую папку. В базе данных сохраняется маркер в коллекции archive_folders.

PUT /api/archive/move

Перемещает файл или папку. Если перемещается папка, все файлы и вложенные маркеры папок обновляются с новым базовым путём.

Параметр	Тип	Описание
source_path	строка	Исходный путь
target_path	строка	Целевой путь

PUT /api/archive/rename

Переименовывает файл или папку. При переименовании папки обновляются пути всех вложенных файлов и маркеров.

Параметр	Тип	Описание
path	строка	Путь к элементу
new_name	строка	Новое имя

DELETE /api/archive/folder

Удаляет папку и все файлы в ней.

Запуск обработки

POST /api/archive/process/{file_id}

Запускает обработку одного файла из архива. Создаёт задание обработки (Job), копирует файл в корзину uploads, запускает фоновую задачу Celery и обновляет статус файла в архиве на queued.

Обработка доступна только для файлов со статусом pending, failed или cancelled.

POST /api/archive/process-folder

Запускает обработку всех необработанных файлов в папке (рекурсивно). Для каждого файла создаётся отдельное задание. Параметр max_concurrent (по умолчанию 1) ограничивает количество немедленно запущенных фоновых задач.

POST /api/archive/process-folder/start

Запускает фоновую обработку папки через отдельную задачу Celery (process_folder_task). В отличие от process-folder, HTTP-запрос возвращается мгновенно, а обработка идёт в фоне. Возвращает process_id для отслеживания.

Если папка уже обрабатывается, возвращается ошибка 409.

GET /api/archive/process-folder/status/{process_id}

Возвращает статус фоновой обработки папки: состояние, прогресс (текущий файл, всего файлов), результат, ошибку, даты создания и завершения.

GET /api/archive/process-folder/active

Возвращает список активных обработок папок (со статусами pending и processing). Используется для отображения индикатора в интерфейсе.

Импорт с Яндекс.Диска

GET /api/archive/yandex/browse

Получает структуру файлов и папок по публичной ссылке на Яндекс.Диск. Используется для отображения проводника выбора файлов. Поддерживает пагинацию: при большом количестве элементов в папке загружаются все страницы автоматически.

Параметр	Тип	Описание
public_url	строка	Публичная ссылка на Яндекс.Диск
path	строка	Путь внутри публичной ссылки

POST /api/archive/import-yandex

Синхронный импорт выбранных файлов с Яндекс.Диска. Рекурсивно собирает все PDF и TIFF файлы из указанных путей, скачивает их и загружает в архив. Файлы TIFF преобразуются в PDF. Дубликаты по пути в архиве пропускаются.

Параметр	Тип	Описание
public_url	строка	Публичная ссылка на Яндекс.Диск
selected_paths	список строк	Пути к выбранным файлам или папкам
base_path	строка	Целевая папка в архиве

POST /api/archive/import-yandex/start

Запускает фоновый импорт с Яндекс.Диска через задачу Celery (import_yandex_task). Возвращает import_id для отслеживания прогресса. Параметры аналогичны синхронному импорту.

POST /api/archive/import-yandex/resume/{import_id}

Возобновляет прерванный импорт. Работает для импортов со статусом timeout, failed или downloading. Если список файлов (pending_files) уже собран, продолжает с текущего блока. Иначе запускает сбор файлов заново.

GET /api/archive/import-yandex/status/{import_id}

Возвращает текущий статус импорта: состояние, прогресс, результат, ошибку, даты.

GET /api/archive/import-yandex/active

Возвращает список активных импортов (статусы pending, collecting, downloading, timeout, failed). Используется для отображения баннера в интерфейсе.

GET /api/archive/import-yandex/recent

Возвращает недавно завершённые импорты (за последние 5 минут) со статусами completed или failed. Используется для показа уведомлений.

GET /api/archive/import-yandex/history

Возвращает полную историю всех импортов с Яндекс.Диска с постраничным выводом.

Параметр	Тип	По умолчанию	Описание
skip	число	0	Сколько записей пропустить
limit	число	50	Максимальное количество записей
status	строка	---	Фильтр по статусу

Контрактный импорт по именам файлов

Контрактный импорт позволяет извлечь реквизиты договоров (номер, дата, контрагент) из имён файлов по определённым образцам и записать их как данные документов.

POST /api/archive/import-contracts/preview

Предварительный просмотр результатов разбора имён файлов в указанной папке. Не записывает данные в базу --- только показывает, какие файлы удалось разобрать и какие данные извлечены.

Параметр	Тип	Описание
path	строка	Путь к папке

POST /api/archive/import-contracts/start

Запускает фоновый контрактный импорт через задачу Celery (import_contracts_task). Возвращает import_id.

GET /api/archive/import-contracts/status/{import_id}

Возвращает статус контрактного импорта: прогресс, результат, ошибку.

GET /api/archive/import-contracts/active

Возвращает список активных и недавно завершённых контрактных импортов (за последние 5 минут).

Управление статусами папок

GET /api/archive/folder-statuses

Возвращает словарь статусов папок в виде {путь: статус}.

PUT /api/archive/folder-status

Устанавливает или удаляет статус папки.

Параметр	Тип	Описание
path	строка	Путь к папке
status	строка	Статус: to_process, skip, done или пусто (для удаления)