Маршруты групп документов

Группа маршрутов /api/groups отвечает за управление группами документов --- объединениями нескольких документов, которые относятся к одному событию (например, акт, счёт и накладная по одной поставке). Группировка выполняется автоматически при обработке файла, но пользователь может создавать группы вручную, подтверждать их или разгруппировывать.

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

Статусы проверки группы

Статус	Описание
pending	Группа создана автоматически и ожидает проверки пользователем
confirmed	Пользователь подтвердил, что документы сгруппированы правильно
rejected	Группа отклонена (разгруппирована)

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

GET /api/groups/

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

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

Параметр	Тип	По умолчанию	Описание
job_id	строка	---	Показать только группы из указанного задания
review_status	строка	---	Фильтр по статусу проверки (pending, confirmed, rejected)
skip	число	0	Сколько записей пропустить
limit	число	50	Максимальное количество записей

Каждая группа в ответе содержит: идентификатор, идентификатор задания, список идентификаторов документов, идентификатор основного документа, номер, дату, контрагента, сумму, типы документов в группе, сведения о способе группировки (метод, уверенность, критерии), статус проверки, дату подтверждения, дату создания.

GET /api/groups/stats

Возвращает сводную статистику группировки.

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

Параметр	Тип	Описание
job_id	строка	Ограничить подсчёт одним заданием

Ответ содержит:

• total_groups --- общее количество групп;
• confirmed_groups --- количество подтверждённых групп;
• pending_groups --- количество групп, ожидающих проверки;
• rejected_groups --- количество отклонённых групп;
• ungrouped_documents --- количество документов, не входящих ни в одну группу.

Подсчёт выполняется с помощью агрегации MongoDB: сначала группы считаются по статусам, затем отдельным запросом подсчитываются документы с пустым полем group_id.

Просмотр группы

GET /api/groups/{group_id}

Возвращает группу вместе с полными данными каждого входящего в неё документа. Помимо стандартных полей группы, ответ содержит массив documents с подробностями: тип, подтип, диапазон страниц, ориентация, уверенность, извлечённые данные (from_content, from_filename, normalized), принадлежность к группе, признак основного документа, пути к файлам.

Создание группы вручную

POST /api/groups/

Позволяет пользователю объединить документы в группу вручную.

Тело запроса:

Поле	Тип	Описание
job_id	строка	Идентификатор задания
document_ids	список строк	Идентификаторы документов (минимум 2)
primary_document_id	строка	Идентификатор основного документа (необязательно, выбирается автоматически)

Проверки перед созданием:

1. Все документы должны существовать в базе.
2. Ни один из документов не должен входить в другую группу.
3. В группе должно быть не менее двух документов.

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

Группы, созданные вручную, сразу получают статус confirmed и метод группировки manual с уверенностью 1.0.

Подтверждение и разгруппировка

POST /api/groups/{group_id}/confirm

Подтверждает группу --- пользователь согласен с тем, что документы сгруппированы правильно. Внутри вызывается функция confirm_group из сервиса группировки, которая обновляет статус в базе данных.

DELETE /api/groups/{group_id}

Удаляет группу и освобождает документы (разгруппировка). Документы остаются в базе, но помечаются как негруппированные --- у них очищается поле group_id. Внутри вызывается функция reject_group из сервиса группировки.

Смена основного документа

PUT /api/groups/{group_id}/primary/{document_id}

Назначает другой документ из группы основным. Основной документ определяет реквизиты группы: номер, дату, контрагента и сумму.

Что происходит при смене:

1. Проверяется, что указанный документ входит в группу.
2. В записи группы обновляются поля primary_document_id, number, date, contractor, amount --- из содержимого нового основного документа.
3. У всех документов группы сбрасывается признак is_primary, затем у нового основного документа этот признак устанавливается.