Маршруты настроек¶
Группа маршрутов /api/settings отвечает за управление настройками приложения. Настройки делятся на три области: общие параметры обработки, глобальные поля поиска для реестров и словарь месторождений.
Исходный файл: backend/app/api/routes/settings.py.
Хранение настроек в базе данных¶
Все настройки хранятся в коллекции settings базы данных MongoDB. Каждая область настроек --- отдельный документ с фиксированным идентификатором:
| Идентификатор документа | Область |
|---|---|
app_settings |
Общие параметры: режим обработки, модель распознавания, размер партии, приостановка обработки |
search_fields |
Глобальные поля поиска для реестров |
oilfields |
Словарь месторождений с ключевыми словами |
При первом обращении, если документ ещё не существует, он создаётся автоматически со значениями по умолчанию.
Общие настройки приложения¶
GET /api/settings¶
Возвращает текущие настройки вместе со списком доступных моделей распознавания.
Поля ответа:
| Поле | Тип | Описание |
|---|---|---|
processing_mode |
строка | Режим обработки: sync (немедленная) или batch (пакетная, дешевле на 50 %) |
claude_model |
строка | Идентификатор модели Claude для анализа документов |
batch_size |
число | Количество страниц на один запрос (от 5 до 50, по умолчанию 20) |
available_models |
массив | Список доступных моделей с названием, описанием, стоимостью и скоростью |
Доступные модели распознавания:
| Идентификатор | Название | Стоимость ввода | Стоимость вывода | Скорость |
|---|---|---|---|---|
claude-haiku-4-5-20251001 |
Claude Haiku 4.5 | 1 $/млн | 5 $/млн | быстрая |
claude-sonnet-4-20250514 |
Claude Sonnet 4 | 3 $/млн | 15 $/млн | средняя |
claude-opus-4-20250514 |
Claude Opus 4 | 15 $/млн | 75 $/млн | медленная |
По умолчанию используется модель Haiku --- самая быстрая и дешёвая. Для сложных документов можно переключиться на Sonnet или Opus.
PATCH /api/settings¶
Обновляет настройки приложения. Принимает только те поля, которые нужно изменить --- остальные сохраняют текущее значение.
Допустимые поля:
| Поле | Тип | Описание |
|---|---|---|
processing_mode |
строка | sync или batch |
claude_model |
строка | Идентификатор модели из списка доступных |
batch_size |
число | Количество страниц на запрос (5--50) |
batch_worker_paused |
логическое | Приостановить обработку документов |
Изменения применяются сразу для новых заданий. Задания, которые уже находятся в обработке, продолжают работать с настройками, действовавшими на момент их запуска.
Возвращает обновлённые настройки в том же формате, что и GET /api/settings.
POST /api/settings/reset¶
Сбрасывает все общие настройки к значениям по умолчанию: режим sync, модель Haiku, размер партии 20, обработка не приостановлена.
Возвращает настройки после сброса.
Управление приостановкой обработки¶
GET /api/settings/processing-status¶
Возвращает текущее состояние приостановки обработки.
Ответ:
{"paused": false}
POST /api/settings/pause-processing¶
Переключает состояние приостановки: если обработка идёт --- ставит на паузу, если стоит на паузе --- возобновляет.
Ответ:
{"paused": true}
Приостановка влияет на фоновую обработку документов: пока флаг batch_worker_paused установлен, обработчик не берёт новые задания из очереди.
Глобальные поля поиска для реестров¶
Поля поиска определяют, какие абстрактные поля доступны при настройке реестра (номер, дата, контрагент, сумма и так далее), какие поля документов проверяются при поиске совпадений и по каким образцам программа автоматически распознаёт заголовки столбцов Excel.
Структура поля поиска¶
| Свойство | Тип | Описание |
|---|---|---|
id |
строка | Уникальный идентификатор (латиница, snake_case) |
label |
строка | Отображаемое название на русском языке |
document_fields |
массив строк | Пути к полям документа для сопоставления (например, from_content.number, normalized.date) |
detect_patterns |
массив строк | Образцы для автоопределения в заголовках Excel (например, номер, №, дата) |
default_weight |
число | Вес по умолчанию при создании правила сопоставления (0--100) |
default_method |
строка | Метод сравнения по умолчанию: exact (точное), fuzzy (приблизительное) или range (диапазонное) |
При первом обращении к полям поиска система создаёт набор из шести полей по умолчанию: «Номер документа», «Дата документа», «Контрагент», «Сумма», «Договор» и «СПП-элемент».
GET /api/settings/search-fields¶
Возвращает список всех глобальных полей поиска.
Ответ:
| Поле | Тип | Описание |
|---|---|---|
items |
массив | Массив полей поиска |
total |
число | Общее количество полей |
POST /api/settings/search-fields¶
Создаёт новое поле поиска. Идентификатор должен быть уникальным, состоять из строчных латинских букв и подчёркиваний.
Тело запроса --- все свойства из таблицы «Структура поля поиска».
При попытке создать поле с уже занятым идентификатором возвращается ошибка 400. При указании несуществующего пути к полю документа в document_fields также возвращается ошибка 400.
GET /api/settings/search-fields/{field_id}¶
Возвращает одно поле поиска по его идентификатору. Если поле не найдено --- ошибка 404.
PUT /api/settings/search-fields/{field_id}¶
Обновляет поле поиска. Принимает только те свойства, которые нужно изменить. Идентификатор поля изменить нельзя --- он задаётся при создании.
Если поле не найдено --- ошибка 404. Если в document_fields указан несуществующий путь --- ошибка 400.
DELETE /api/settings/search-fields/{field_id}¶
Удаляет поле поиска. Возвращает пустой ответ со статусом 204. Если поле не найдено --- ошибка 404.
GET /api/settings/document-fields¶
Возвращает список всех допустимых путей к полям документа, которые можно использовать в document_fields при создании или редактировании полей поиска. Этот справочный адрес помогает узнать, какие поля доступны для привязки.
Ответ:
| Поле | Тип | Описание |
|---|---|---|
items |
массив | Массив объектов с описанием каждого поля документа |
total |
число | Общее количество полей |
Словарь месторождений¶
Словарь содержит названия месторождений и ключевые слова для их поиска в тексте документов. При обработке документа программа ищет упоминания этих ключевых слов и записывает в документ каноническое название месторождения.
Структура записи месторождения¶
| Свойство | Тип | Описание |
|---|---|---|
id |
строка | Уникальный идентификатор (генерируется автоматически из названия путём транслитерации) |
name |
строка | Каноническое название месторождения (до 100 символов) |
keywords |
массив строк | Ключевые слова для поиска в тексте: варианты написания, сокращения, номера лицензий |
При первом обращении к словарю система создаёт набор из 16 месторождений по умолчанию, разделённых на три группы по номерам лицензий.
GET /api/settings/oilfields¶
Возвращает список всех месторождений.
Ответ:
| Поле | Тип | Описание |
|---|---|---|
items |
массив | Массив записей месторождений |
total |
число | Общее количество записей |
POST /api/settings/oilfields¶
Создаёт новое месторождение. Идентификатор генерируется автоматически из названия через транслитерацию кириллицы в латиницу. Если такой идентификатор уже занят, к нему добавляется числовой суффикс (_1, _2 и так далее).
Тело запроса:
| Поле | Тип | Описание |
|---|---|---|
name |
строка | Название месторождения |
keywords |
массив строк | Ключевые слова для поиска (не менее одного) |
GET /api/settings/oilfields/{oilfield_id}¶
Возвращает одно месторождение по идентификатору. Если не найдено --- ошибка 404.
PUT /api/settings/oilfields/{oilfield_id}¶
Обновляет месторождение. Принимает только те свойства, которые нужно изменить. Идентификатор не меняется.
Если не найдено --- ошибка 404.
DELETE /api/settings/oilfields/{oilfield_id}¶
Удаляет месторождение. Возвращает пустой ответ со статусом 204. Если не найдено --- ошибка 404.
Внутренние вспомогательные функции¶
Модуль содержит две функции, используемые другими частями серверной части:
get_app_settings()--- возвращает текущие общие настройки из базы данных; вызывается в обработчиках маршрутов и в сервисе обработки для определения режима работы и выбранной модели.get_oilfields_for_prompt()--- возвращает список месторождений для включения в запрос к Claude; вызывается вclaude_client.pyиbatch_service.pyпри формировании подсказки для распознавания документов.