Маршруты шаблонов реестров

Группа маршрутов /api/registry-templates отвечает за управление шаблонами настройки реестров. Шаблоны позволяют сохранить и переиспользовать настройки: параметры разбора Excel, привязку полей, настройки поиска и образцы для автоматического определения подходящего шаблона.

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

Назначение шаблонов

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

Структура шаблона

Каждый шаблон содержит:

• Имя (name) --- уникальное название для удобства выбора.
• Настройки разбора (parsing) --- номер строки заголовков, первая строка данных, столбцы для заполнения пропусков сверху вниз.
• Привязка полей (fields) --- список полей с указанием: идентификатор поля, индекс столбца, метод сравнения, вес, признак использования для поиска.
• Настройки поиска (search_config) --- минимальный балл совпадения.
• Образцы автоопределения (auto_detect) --- списки образцов для автоматического подбора шаблона по имени файла и заголовкам столбцов.
• Счётчик использования (usage_count) --- сколько раз шаблон был применён.
• Дата последнего использования (last_used).

Получение списка шаблонов

GET /api/registry-templates

Возвращает список шаблонов с постраничным выводом. Сортировка --- по частоте использования (популярные первыми), затем по дате создания.

Параметр	Тип	По умолчанию	Описание
skip	число	0	Сколько записей пропустить
limit	число	50	Максимальное количество (до 100)
search	строка	---	Поиск по имени шаблона (без учёта регистра)

Создание и редактирование

POST /api/registry-templates

Создаёт новый шаблон. Имя должно быть уникальным. При попытке создать шаблон с уже занятым именем возвращается ошибка 400.

GET /api/registry-templates/{template_id}

Возвращает шаблон по идентификатору.

PUT /api/registry-templates/{template_id}

Обновляет шаблон. Все поля необязательны --- обновляются только переданные. При переименовании проверяется уникальность нового имени.

DELETE /api/registry-templates/{template_id}

Удаляет шаблон.

Автоматический подбор шаблона

GET /api/registry-templates/suggest

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

Параметр	Тип	Описание
filename	строка	Имя файла реестра
headers	строка	Заголовки столбцов через запятую

Хотя бы один из параметров должен быть указан.

Алгоритм подбора:

1. Для каждого шаблона проверяются образцы из auto_detect.
2. Если образец из filename_patterns найден в имени файла --- к баллу добавляется 0.4.
3. Если образец из header_patterns найден среди заголовков --- к баллу добавляется 0.2.
4. Итоговый балл ограничивается единицей.
5. Шаблоны без совпавших образцов не включаются в результат.

Каждый элемент ответа содержит: данные шаблона, итоговый балл (match_score), список совпавших образцов (matched_patterns) с указанием типа (filename или header).

Счётчик использования

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