Маршруты заданий обработки

Группа маршрутов /api/jobs отвечает за управление заданиями --- задачами на обработку загруженных файлов PDF и TIFF. Каждое задание проходит жизненный цикл от создания до получения результатов.

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

Жизненный цикл задания

Задание может находиться в одном из пяти состояний:

Состояние	Описание
pending	Файл загружен, ожидает начала обработки
processing	Обработка запущена (распознавание, сегментация, классификация)
completed	Обработка завершена успешно
failed	Обработка завершилась с ошибкой
cancelled	Обработка отменена пользователем

Создание и проверка дубликатов

POST /api/jobs/check-duplicate

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

Параметры запроса:

Параметр	Тип	Описание
filename	строка	Имя файла
file_size	число	Размер файла в байтах

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

POST /api/jobs/

Создаёт новое задание обработки. Принимает файл PDF или TIFF.

Что происходит при создании:

1. Проверяется, что формат файла поддерживается (PDF или TIFF).
2. Если загружен TIFF --- файл автоматически преобразуется в PDF.
3. Файл сохраняется в хранилище MinIO (в корзину uploads).
4. В базе данных создаётся запись со состоянием pending.

Ответ возвращает идентификатор задания, имя файла, размер и состояние.

Получение списка и сведений о заданиях

GET /api/jobs/

Возвращает список заданий с постраничным выводом. Сортировка --- по дате создания, от новых к старым.

Параметры запроса:

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

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

GET /api/jobs/{job_id}

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

GET /api/jobs/{job_id}/documents

Возвращает список документов, извлечённых из задания. Для каждого документа указаны тип, подтип, диапазон страниц, уверенность распознавания, извлечённые данные, принадлежность к группе.

Просмотр и выгрузка файлов

GET /api/jobs/{job_id}/view

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

GET /api/jobs/{job_id}/export

Выгружает результаты обработки в виде ZIP-архива. Доступно только для заданий с состоянием completed.

Состав архива:

• metadata.json --- сведения о задании (имя файла, число страниц, число документов, даты).
• statistics.json --- распределение документов по типам и подтипам.
• documents.json --- подробный перечень всех извлечённых документов с данными.
• groups.json --- перечень групп документов.
• documents/ --- папка с PDF-файлами отдельных документов. Имя каждого файла складывается из типа, подтипа и диапазона страниц.

Управление обработкой

POST /api/jobs/{job_id}/process

Запускает обработку конкретного задания через фоновый обработчик Celery. Допускается только для заданий в состоянии pending или failed.

POST /api/jobs/{job_id}/reprocess

Повторная обработка задания. Удаляет ранее извлечённые документы и группы, сбрасывает состояние в pending и запускает обработку заново. Если исходный файл из корзины uploads был удалён при очистке, система восстанавливает его из архива.

Нельзя повторно обработать задание, которое сейчас в состоянии processing.

POST /api/jobs/{job_id}/cancel

Отменяет конкретное задание. Если обработка запущена через Celery --- отзывает задачу. Обновляет состояние в базе данных на cancelled. Если задание связано с файлом в архиве --- обновляет и его состояние.

DELETE /api/jobs/{job_id}

Полностью удаляет задание и все связанные данные:

• группы документов из базы данных;
• извлечённые документы из базы данных;
• запись задания;
• файлы из хранилища MinIO (из корзин uploads, documents, previews).

Управление очередью

Группа адресов /api/jobs/queue/ позволяет управлять общей очередью обработки.

POST /api/jobs/queue/start

Запускает очередь, если она не запущена. Находит первое задание в состоянии pending и отправляет его на обработку. Если обработка уже идёт --- сообщает об этом без повторного запуска.

Поведение зависит от режима обработки:

• В немедленном режиме (sync) --- запускает одно задание через Celery, следующее начнётся автоматически после завершения текущего.
• В пакетном режиме (batch) --- ожидающие задания подхватываются фоновым процессом batch_submission_worker самостоятельно.

POST /api/jobs/queue/pause

Приостанавливает очередь. Все задания в состоянии processing переводятся обратно в pending. Новые задания не запускаются. Файлы в архиве, связанные с этими заданиями, тоже возвращаются в состояние ожидания.

POST /api/jobs/queue/reset-stuck

Сбрасывает «застрявшие» задания. Все задания в состоянии processing переводятся в pending, после чего очередь перезапускается. Полезно, когда обработка зависла из-за сбоя.

POST /api/jobs/queue/clear

Удаляет все задания в состоянии pending из очереди. Связанные файлы в архиве возвращаются в состояние ожидания. Задания, которые уже обрабатываются, не затрагиваются.

POST /api/jobs/queue/cancel-all

Полная отмена всех активных и ожидающих заданий:

1. Очищает очередь Celery.
2. Отзывает все выполняющиеся задачи Celery с принудительным завершением.
3. Переводит все задания со состояниями pending и processing в cancelled.
4. Обновляет соответствующие файлы в архиве.

Импорт с Яндекс.Диска не затрагивается --- он управляется отдельно.

Статистика и обзор

GET /api/jobs/folder-stats

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

• общее количество заданий;
• количество по каждому состоянию (completed, processing, pending, failed);
• суммарное число найденных документов и страниц;
• средняя и суммарная длительность обработки завершённых заданий.

Результат отсортирован по количеству активных заданий (в обработке и ожидании) в убывающем порядке. Используется на экране «Очередь обработки» для отображения прогресса по папкам.

GET /api/jobs/batch-overview

Возвращает подробный обзор пакетной обработки. Включает:

• список активных пакетов с их состоянием в сервисе Claude (обрабатывается / завершён), количеством запросов и датой отправки;
• задания, ожидающие отправки (pending);
• задания, находящиеся на этапе подготовки (распознавание текста) --- в состоянии processing, но ещё без привязки к пакету;
• последние десять завершённых заданий;
• общие счётчики по каждому состоянию.