Маршруты реестров¶
Группа маршрутов /api/registries отвечает за полный жизненный цикл реестра --- от загрузки файла Excel до выгрузки итоговых результатов сверки. Работа с реестром ведётся последовательно через мастер настройки: загрузка → выбор листа и настройка разбора → привязка полей → настройка правил сопоставления → импорт строк → запуск поиска → подтверждение совпадений → выгрузка.
Исходный файл: backend/app/api/routes/registries.py.
Жизненный цикл реестра¶
| Статус | Описание |
|---|---|
draft |
Файл загружен, но лист не выбран и поля не настроены |
configured |
Настройки поиска сохранены, можно запускать импорт |
importing |
Идёт импорт строк реестра из Excel в базу данных |
searching |
Идёт поиск документов для строк реестра |
completed |
Поиск завершён, результаты доступны |
exporting |
Идёт подготовка выгрузки результатов |
Загрузка и список реестров¶
POST /api/registries/upload¶
Загружает файл реестра в формате Excel (.xlsx или .xls). Файлы .xls (Excel 97--2003) автоматически преобразуются в .xlsx при загрузке --- при этом сохраняются данные, объединённые ячейки и применяется базовое форматирование.
Что происходит при загрузке:
- Имя файла проверяется на расширение. При необходимости исправляется кодировка (CP1251 → UTF-8).
- Файл сохраняется в хранилище MinIO (в корзину
documents). - Из файла извлекается информация о листах: имя, количество строк и столбцов (только непустых), заголовки.
- В базе данных создаётся запись со статусом
draft.
GET /api/registries/¶
Возвращает список реестров с постраничным выводом. Сортировка --- по дате создания, от новых к старым.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
skip |
число | 0 | Сколько записей пропустить |
limit |
число | 20 | Максимальное количество записей |
status |
строка | --- | Фильтр по статусу |
GET /api/registries/{registry_id}¶
Возвращает подробные сведения о реестре: настройки разбора, привязку полей, правила сопоставления, статистику, состояние текущей задачи.
DELETE /api/registries/{registry_id}¶
Удаляет реестр и все связанные данные: файл из MinIO, записи строк из коллекции registry_rows, ссылки из шаблонов.
GET /api/registries/match-methods¶
Возвращает справочник доступных методов сравнения полей с описанием каждого.
Мастер настройки: шаг 1 --- выбор листа и разбор¶
GET /api/registries/{registry_id}/preview¶
Предварительный просмотр данных листа с учётом настроек разбора. Используется на первом шаге мастера.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
sheet_name |
строка | --- | Название листа (обязательный) |
header_row |
число | 1 | Номер строки с заголовками |
data_start_row |
число | 2 | Номер первой строки данных |
fill_down_columns |
строка | --- | Индексы столбцов для заполнения пропусков сверху вниз, через запятую |
column_header_row |
строка | --- | JSON с переопределением строк заголовков для отдельных столбцов |
skip_rows_containing |
строка | --- | Слова для фильтрации строк через запятую (например, ИТОГО,стр.) |
required_column_index |
число | --- | Индекс обязательного столбца (строки с пустым значением будут отфильтрованы) |
min_filled_cells |
число | 0 | Минимальное количество заполненных ячеек в строке |
limit |
число | 10 | Количество строк для предпросмотра |
Ответ содержит: название листа, заголовки, строки данных, общее количество строк, индексы непустых столбцов, количество отфильтрованных строк и их примеры.
Механизм заполнения пропусков сверху вниз (fill down) заменяет пустые ячейки в указанных столбцах значением последней непустой ячейки выше --- это полезно для реестров с объединёнными ячейками.
POST /api/registries/{registry_id}/parsing¶
Сохраняет настройки разбора и выбранный лист.
| Параметр | Тип | Описание |
|---|---|---|
sheet_name |
строка (в строке запроса) | Название выбранного листа |
| тело запроса | ParsingConfig |
Настройки: номер строки заголовков, первая строка данных, столбцы для заполнения пропусков, индекс столбца суммы и другие |
Если указан индекс столбца суммы (sum_column_index) и строки уже импортированы, выполняется пересчёт общей суммы.
Мастер настройки: шаг 2 --- привязка полей¶
GET /api/registries/{registry_id}/detect-fields¶
Автоматическое определение полей по заголовкам столбцов. Использует образцы из глобальных настроек поиска (search_fields). Для каждого заголовка перебираются образцы, и при совпадении возвращается предложение с идентификатором поля, индексом столбца, уверенностью (0.8 --- точное совпадение, 0.6 --- частичное), предлагаемым весом и методом сравнения.
POST /api/registries/{registry_id}/fields¶
Сохраняет привязку столбцов Excel к полям документов.
Тело запроса --- список полей, каждое содержит: идентификатор поля, индекс столбца, метод сравнения, вес, признак использования для поиска.
Проверки:
- Хотя бы одно поле должно быть помечено для поиска (
use_for_search). - Сумма весов полей поиска должна быть больше нуля.
- Один столбец не может использоваться в нескольких полях.
Правила сопоставления¶
Правила сопоставления позволяют задать несколько наборов полей с разными весами и минимальными баллами. Это нужно, когда один и тот же реестр содержит строки с разной структурой данных (например, у части строк есть номер договора, а у части --- только дата и контрагент).
GET /api/registries/{registry_id}/rules¶
Возвращает все правила сопоставления реестра. Если правила ещё не созданы, но поля привязаны, автоматически создаётся одно правило из существующих полей (миграция со старого формата).
POST /api/registries/{registry_id}/rules¶
Сохраняет все правила сопоставления. Полностью заменяет существующий список.
| Параметр | Тип | Описание |
|---|---|---|
| тело запроса | список MatchingRule |
Правила с полями, весами и минимальными баллами |
rule_mode |
строка (в строке запроса) | Режим: first_match (остановиться на первом совпадении) или all_matches (искать все) |
Проверки:
- Должно быть хотя бы одно активное правило.
- У каждого активного правила должно быть хотя бы одно поле для поиска с ненулевым весом.
Для обратной совместимости из всех правил собираются уникальные поля и сохраняются в поле fields реестра. Если строки уже импортированы, запускается фоновая задача rebuild_mapped_data_task для пересборки привязанных данных.
DELETE /api/registries/{registry_id}/rules/{rule_id}¶
Удаляет правило по идентификатору. Нельзя удалить последнее активное правило.
PATCH /api/registries/{registry_id}/rules/{rule_id}/toggle¶
Включает или выключает правило. Должно оставаться хотя бы одно активное правило.
Мастер настройки: шаг 3 --- настройки поиска¶
POST /api/registries/{registry_id}/search-config¶
Сохраняет настройки поиска (минимальный балл). После сохранения статус реестра меняется на configured.
Устаревший адрес
Рекомендуется использовать правила сопоставления (POST /rules), которые включают минимальный балл в каждом правиле.
Проверяется, что предыдущие шаги выполнены: выбран лист и привязаны поля.
Импорт и поиск¶
POST /api/registries/{registry_id}/import¶
Запускает импорт строк реестра из Excel в базу данных. Это фоновая задача Celery (import_registry_rows_task).
| Параметр | Тип | Описание |
|---|---|---|
force |
логическое | При true удаляет существующие результаты и реимпортирует |
Необходимое условие: выбран лист (настройки разбора сохранены).
Статус реестра меняется на importing, возвращается task_id для отслеживания.
POST /api/registries/{registry_id}/search¶
Запускает поиск документов для строк реестра. Это фоновая задача Celery (search_registry_task).
Проверки:
- Импорт не должен быть в процессе (защита от параллельного запуска).
- Строки должны быть импортированы.
Статус реестра меняется на searching.
GET /api/registries/{registry_id}/status¶
Возвращает статус текущей фоновой задачи (импорт или поиск): идентификатор задачи, состояние (pending, running, completed, failed), прогресс (0--100), сообщение или ошибку.
Строки и результаты¶
GET /api/registries/{registry_id}/rows¶
Возвращает строки реестра с постраничным выводом, фильтрами и сортировкой.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
skip |
число | 0 | Сколько записей пропустить |
limit |
число | 50 | Максимальное количество (до 200) |
status |
строка | --- | Фильтр: pending, matched, no_match, confirmed |
rule_id |
строка | --- | Показать только строки, найденные этим правилом |
search |
строка | --- | Поиск по привязанным и исходным данным |
score_min |
дробное | --- | Минимальный балл совпадения |
score_max |
дробное | --- | Максимальный балл совпадения |
sort_by |
строка | row_number |
Сортировка: row_number, best_score, sum, has_warnings |
sort_order |
число | 1 | Направление: 1 (по возрастанию), -1 (по убыванию) |
column_filters |
строка | --- | JSON-фильтры по столбцам |
has_warnings |
логическое | --- | Фильтр по предупреждениям |
Каждая строка содержит: номер строки, исходные данные (raw_data), привязанные данные (mapped_data), приведённые данные (normalized), список совпадений (matches), лучший балл, статус, признак предупреждений.
Ответ также включает статистику реестра и распределение баллов по диапазонам: 100, 90--99, 80--89, 60--79, ниже 60.
Поиск ведётся по привязанным полям (doc_number, doc_date, contractor, amount, contract) и по всем столбцам исходных данных (до 50 столбцов).
GET /api/registries/{registry_id}/column-values¶
Возвращает уникальные значения столбца с постраничным выводом и поиском. Используется для построения выпадающих списков фильтров.
| Параметр | Тип | Описание |
|---|---|---|
field_id |
строка | Идентификатор поля из mapped_data |
column_indices |
строка | Индексы столбцов raw_data через запятую (запасной вариант) |
search |
строка | Поиск по значениям |
Поддерживает перекрёстную фильтрацию: при передаче column_filters уникальные значения подсчитываются только для строк, прошедших все фильтры.
GET /api/registries/{registry_id}/rows/{row_number}¶
Возвращает конкретную строку реестра по номеру.
Подтверждение совпадений¶
POST /api/registries/{registry_id}/rows/{row_number}/confirm¶
Подтверждает совпадение для строки. Пользователь указывает идентификатор документа, который считает правильным совпадением. Остальные совпадения помечаются как неподтверждённые. Статус строки меняется на confirmed.
| Поле тела запроса | Тип | Описание |
|---|---|---|
document_id |
строка | Идентификатор подтверждаемого документа |
После подтверждения пересчитываются: количество подтверждённых строк в статистике реестра, сумма найденных строк (found_sum, если задан столбец суммы).
DELETE /api/registries/{registry_id}/rows/{row_number}/confirm¶
Отменяет подтверждение. Со всех совпадений строки снимается отметка подтверждения. Статус строки возвращается к matched (если есть совпадения) или no_match.
Выгрузка результатов¶
POST /api/registries/{registry_id}/export¶
Запускает подготовку выгрузки через фоновую задачу Celery (export_registry_task). Создаётся ZIP-архив, содержащий:
results.xlsx--- таблица Excel с результатами поиска;documents/--- папка с PDF-файлами найденных документов (еслиinclude_pdfs=true);metadata.json--- метаданные выгрузки.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
include_pdfs |
логическое | true |
Включить PDF-файлы в архив |
Статус реестра меняется на exporting. Нельзя запустить повторную выгрузку, пока предыдущая не завершена.
GET /api/registries/{registry_id}/download¶
Скачивает оригинальный файл реестра (Excel). Поддерживает кириллицу в имени файла.
GET /api/registries/{registry_id}/export/download¶
Скачивает готовый ZIP-архив с результатами выгрузки. Доступен только после завершения выгрузки.