Схемы запросов и ответов¶
Серверная часть использует библиотеку Pydantic для описания формата входящих запросов и исходящих ответов. Ниже перечислены все схемы, сгруппированные по предметной области.
Задания обработки¶
Определены в backend/app/schemas/job.py.
JobStatus¶
Перечисление допустимых состояний задания:
| Значение | Описание |
|---|---|
pending |
Ожидает обработки |
processing |
Обрабатывается |
completed |
Обработка завершена |
failed |
Обработка завершилась ошибкой |
UsageResponse¶
Статистика использования помощника Claude при обработке.
| Поле | Тип | Описание |
|---|---|---|
input_tokens |
int | Количество входных токенов |
output_tokens |
int | Количество выходных токенов |
total_tokens |
int | Общее количество токенов |
model |
str или null | Использованная модель |
requests_count |
int | Количество запросов |
prompt |
str или null | Текст подсказки |
JobResponse¶
Ответ с полной информацией о задании. Возвращается при чтении одного задания или списка заданий.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
id |
str | да | Идентификатор задания |
filename |
str | да | Имя файла |
file_size |
int | да | Размер файла |
status |
str | да | Текущее состояние |
progress |
int | нет | Прогресс от 0 до 100 |
total_pages |
int или null | нет | Общее число страниц |
processed_pages |
int | нет | Обработанных страниц |
documents_found |
int | нет | Найденных документов |
groups_created |
int | нет | Созданных групп |
from_filename |
object или null | нет | Данные из имени файла |
warnings |
список строк или null | нет | Предупреждения |
error |
str или null | нет | Текст ошибки |
usage |
UsageResponse или null | нет | Статистика использования |
created_at |
datetime | да | Время создания |
started_at |
datetime или null | нет | Время начала обработки |
completed_at |
datetime или null | нет | Время завершения |
duration_seconds |
float или null | нет | Длительность в секундах |
batch_id |
str или null | нет | Идентификатор пакетного запроса |
batch_status |
str или null | нет | Состояние пакетного запроса |
folder_path |
str или null | нет | Путь к папке архива |
JobUpdate¶
Запрос обновления задания. Все поля необязательные — передаются только изменяемые.
| Поле | Тип | Описание |
|---|---|---|
status |
JobStatus или null | Новое состояние |
progress |
int или null | Новый прогресс |
total_pages |
int или null | Общее число страниц |
processed_pages |
int или null | Обработанных страниц |
documents_found |
int или null | Найденных документов |
error |
str или null | Текст ошибки |
Документы¶
Определены в backend/app/schemas/document.py.
DocumentResponse¶
Полная информация о распознанном документе.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
id |
str | да | Идентификатор документа |
job_id |
str или null | нет | Ссылка на задание |
doc_title |
str или null | нет | Заголовок документа |
doc_type |
str | да | Тип документа |
doc_subtype |
DocumentSubtype или null | нет | Подтип (цвет бумаги, качество) |
page_start |
int | нет | Первая страница |
page_end |
int | нет | Последняя страница |
source |
str или null | нет | Источник |
orientation |
str | нет | Ориентация (portrait или landscape) |
rotation |
int | нет | Угол поворота (0, 90, 180, 270) |
confidence |
float | нет | Уверенность распознавания |
from_content |
FromContent или null | нет | Данные из содержимого |
from_filename |
FromFilename или null | нет | Данные из имени файла |
from_postprocess |
FromPostprocess или null | нет | Данные из постобработки |
normalized |
NormalizedData или null | нет | Приведённые данные |
group_id |
str или null | нет | Ссылка на группу |
is_primary |
bool | нет | Основной в группе |
sync_error |
bool | нет | Расхождение данных |
sync_error_details |
список строк или null | нет | Детали расхождений |
has_error |
bool | нет | Помечен ошибкой |
error_comment |
str или null | нет | Комментарий к ошибке |
error_marked_at |
datetime или null | нет | Время отметки |
manual_edits |
словарь ManualEdit или null | нет | Ручные правки |
raw_text |
str или null | нет | Распознанный текст |
file_path |
str или null | нет | Путь к файлу в MinIO |
preview_path |
str или null | нет | Путь к предпросмотру |
created_at |
datetime | да | Время создания |
DocumentCreate¶
Запрос создания документа (используется внутри сервера при обработке).
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
job_id |
str | да | Ссылка на задание |
doc_title |
str или null | нет | Заголовок |
doc_type |
str | да | Тип документа |
doc_subtype |
DocumentSubtype или null | нет | Подтип |
page_start |
int | да | Первая страница |
page_end |
int | да | Последняя страница |
orientation |
str | нет | Ориентация (по умолчанию portrait) |
rotation |
int | нет | Угол поворота (по умолчанию 0) |
confidence |
float | нет | Уверенность (по умолчанию 0) |
from_content |
FromContent или null | нет | Данные из содержимого |
from_filename |
FromFilename или null | нет | Данные из имени файла |
from_postprocess |
FromPostprocess или null | нет | Данные из постобработки |
normalized |
NormalizedData или null | нет | Приведённые данные |
sync_error |
bool | нет | Расхождение данных |
sync_error_details |
список строк или null | нет | Детали расхождений |
raw_text |
str или null | нет | Распознанный текст |
DocumentListResponse¶
Список документов с разбивкой на страницы.
| Поле | Тип | Описание |
|---|---|---|
items |
список DocumentResponse | Документы на текущей странице |
total |
int | Общее количество документов |
page |
int | Номер текущей страницы |
per_page |
int | Количество на странице |
DocumentStats¶
Статистика документов по типам.
| Поле | Тип | Описание |
|---|---|---|
doc_type |
str | Тип документа |
doc_subtype |
str или null | Подтип |
count |
int | Количество |
avg_confidence |
float или null | Средняя уверенность |
MarkErrorRequest¶
Запрос на отметку ошибки в документе.
| Поле | Тип | Описание |
|---|---|---|
has_error |
bool | Пометить ошибку (по умолчанию true) |
comment |
str или null | Комментарий к ошибке |
DocumentFieldUpdate¶
Запрос обновления полей документа вручную.
| Поле | Тип | Описание |
|---|---|---|
from_content |
object или null | Новые значения полей из содержимого |
from_filename |
object или null | Новые значения полей из имени файла |
from_postprocess |
object или null | Новые значения из постобработки |
Группы документов¶
Определены в backend/app/schemas/group.py.
DocumentGroupResponse¶
Ответ с информацией о группе.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
id |
str | да | Идентификатор группы |
job_id |
str | да | Ссылка на задание |
document_ids |
список строк | да | Идентификаторы документов |
primary_document_id |
str | да | Идентификатор основного документа |
number |
str или null | нет | Номер основного документа |
date |
str или null | нет | Дата основного документа |
contractor |
str или null | нет | Контрагент |
amount |
float или null | нет | Сумма |
document_types |
список строк | нет | Типы документов в группе |
grouping |
GroupingInfo | да | Способ группировки |
review_status |
str | нет | Состояние проверки: pending, confirmed, rejected |
confirmed_at |
datetime или null | нет | Время подтверждения |
created_at |
datetime | да | Время создания |
GroupingInfo¶
Сведения о том, как и почему документы объединены в группу.
| Поле | Тип | Описание |
|---|---|---|
method |
str | Способ: auto или manual |
confidence |
float | Уверенность от 0 до 1 |
criteria |
GroupingCriteria | Критерии группировки |
GroupingCriteria¶
| Поле | Тип | Описание |
|---|---|---|
number_match |
bool | Совпадение номера |
date_match |
bool | Точное совпадение даты |
date_approximate |
bool | Приблизительное совпадение даты (разница в один день) |
contractor_match |
bool | Совпадение контрагента |
contractor_similarity |
float | Коэффициент схожести контрагентов |
same_pdf |
bool | Документы из одного файла |
pages_nearby |
bool | Документы расположены рядом |
fallback_applied |
bool | Применено запасное правило (нет номера, но рядом) |
DocumentGroupCreate¶
Запрос ручного создания группы.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
job_id |
str | да | Ссылка на задание |
document_ids |
список строк | да | Идентификаторы документов |
primary_document_id |
str или null | нет | Основной документ (если не указан — выбирается автоматически) |
GroupListResponse¶
Список групп с разбивкой на страницы.
| Поле | Тип | Описание |
|---|---|---|
items |
список DocumentGroupResponse | Группы |
total |
int | Общее количество |
page |
int | Номер страницы |
per_page |
int | Количество на странице |
GroupStats¶
Статистика группировки.
| Поле | Тип | Описание |
|---|---|---|
total_groups |
int | Всего групп |
confirmed_groups |
int | Подтверждённых |
pending_groups |
int | Ожидающих проверки |
rejected_groups |
int | Отклонённых |
ungrouped_documents |
int | Документов без группы |
Файловый архив¶
Определены в backend/app/schemas/archive.py.
ArchiveFileResponse¶
Информация о файле в архиве.
| Поле | Тип | Описание |
|---|---|---|
id |
str | Идентификатор |
path |
str | Полный путь в дереве архива |
filename |
str | Имя файла |
file_size |
int | Размер |
minio_path |
str | Путь в хранилище MinIO |
status |
str | Состояние: pending, processing, completed, failed |
job_id |
str или null | Ссылка на задание обработки |
created_at |
datetime | Время добавления |
processed_at |
datetime или null | Время обработки |
FolderNode¶
Узел дерева папок. Рекурсивная структура — каждый узел может содержать дочерние узлы.
| Поле | Тип | Описание |
|---|---|---|
name |
str | Имя папки или файла |
path |
str | Полный путь |
type |
str | Тип узла: folder или file |
children |
список FolderNode | Дочерние узлы |
file_id |
str или null | Идентификатор файла (только для файлов) |
file_size |
int или null | Размер файла |
status |
str или null | Состояние обработки |
job_id |
str или null | Ссылка на задание |
ArchiveTreeResponse¶
Полное дерево файлов архива.
| Поле | Тип | Описание |
|---|---|---|
tree |
список FolderNode | Корневые узлы дерева |
total_files |
int | Общее число файлов |
total_size |
int | Общий размер |
pending_files |
int | Ожидающих обработки |
processed_files |
int | Обработанных |
ArchiveUploadResponse¶
Результат загрузки файлов в архив.
| Поле | Тип | Описание |
|---|---|---|
files_added |
int | Добавлено файлов |
folders_created |
список строк | Созданные папки |
skipped_duplicates |
int | Пропущено дубликатов |
total_size |
int | Общий размер добавленных файлов |
ArchiveStatsResponse¶
Статистика архива.
| Поле | Тип | Описание |
|---|---|---|
total_files |
int | Всего файлов |
total_size |
int | Общий размер |
pending_files |
int | Ожидающих |
processing_files |
int | В обработке |
completed_files |
int | Обработанных |
failed_files |
int | С ошибками |
folders |
список строк | Список папок |
Реестры¶
Определены в backend/app/schemas/registry.py.
RegistryResponse¶
Полная информация о реестре.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
id |
str | да | Идентификатор |
filename |
str | да | Имя файла на сервере |
original_filename |
str | да | Исходное имя файла |
file_size |
int | да | Размер файла |
file_path |
str | да | Путь в MinIO |
sheets |
список SheetInfo | да | Информация о листах Excel |
sheet_name |
str или null | нет | Выбранный лист |
parsing |
ParsingConfig | нет | Настройки разбора |
fields |
список RegistryField | нет | Привязки полей (устаревшее) |
search_config |
SearchConfig | нет | Настройки поиска (устаревшее) |
matching_rules |
список MatchingRule | нет | Правила сопоставления |
rule_mode |
str | нет | Режим: first_match или all_matches |
template_id |
str или null | нет | Ссылка на шаблон |
status |
str | нет | Состояние реестра |
stats |
RegistryStats | нет | Статистика |
filtered_rows_data |
список объектов | нет | Отфильтрованные строки |
current_task_id |
str или null | нет | Текущая фоновая задача |
task_progress |
int | нет | Прогресс задачи |
task_error |
str или null | нет | Ошибка задачи |
export_path |
str или null | нет | Путь к файлу выгрузки |
created_at |
datetime | да | Время создания |
updated_at |
datetime или null | нет | Время обновления |
RegistryUpdate¶
Запрос обновления реестра. Все поля необязательные.
| Поле | Тип | Описание |
|---|---|---|
sheet_name |
str или null | Выбранный лист |
parsing |
ParsingConfig или null | Настройки разбора |
matching_rules |
список MatchingRule или null | Правила сопоставления |
rule_mode |
str или null | Режим применения правил |
template_id |
str или null | Ссылка на шаблон |
status |
str или null | Новое состояние |
RegistryRowResponse¶
Строка реестра с результатами поиска.
| Поле | Тип | Описание |
|---|---|---|
id |
str | Идентификатор строки |
registry_id |
str | Ссылка на реестр |
row_number |
int | Порядковый номер в Excel |
raw_data |
object | Исходные данные по индексам колонок |
mapped_data |
object | Привязанные данные по идентификаторам полей |
normalized |
object | Приведённые значения |
matches |
список RowMatch | Найденные совпадения |
best_score |
float | Лучший балл совпадения |
status |
str | Состояние: pending, matched, no_match, confirmed |
has_warnings |
bool | Наличие предупреждений |
RowMatch¶
Совпадение документа для строки реестра.
| Поле | Тип | Описание |
|---|---|---|
document_id |
str | Идентификатор документа |
score |
float | Балл от 0 до 1 |
field_scores |
object | Баллы по каждому полю |
matched_values |
object | Совпавшие значения |
confirmed |
bool | Подтверждено пользователем |
rule_ids |
список строк | Идентификаторы правил |
rule_names |
список строк | Названия правил |
warnings |
список объектов | Предупреждения |
source |
str или null | Источник документа |
RegistryRowsResponse¶
Список строк реестра с разбивкой на страницы.
| Поле | Тип | Описание |
|---|---|---|
items |
список RegistryRowResponse | Строки |
total |
int | Общее количество |
page |
int | Номер страницы |
pages |
int | Всего страниц |
stats |
RegistryStats | Статистика реестра |
ConfirmMatchRequest¶
Запрос на подтверждение совпадения.
| Поле | Тип | Описание |
|---|---|---|
document_id |
str | Идентификатор подтверждаемого документа |
PreviewRequest¶
Запрос предварительного просмотра данных листа Excel.
| Поле | Тип | Описание |
|---|---|---|
sheet_name |
str | Название листа |
header_row |
int | Номер строки с заголовками |
data_start_row |
int | Номер первой строки данных |
fill_down_columns |
список int | Колонки для заполнения пропусков |
limit |
int | Количество строк для предпросмотра (от 1 до 100) |
PreviewResponse¶
Ответ с предварительным просмотром данных.
| Поле | Тип | Описание |
|---|---|---|
sheet_name |
str | Название листа |
headers |
список строк | Заголовки |
rows |
список списков | Данные строк |
total_rows |
int | Общее количество строк в листе |
column_indices |
список int | Соответствие отфильтрованных индексов исходным |
filtered_rows |
int | Количество отфильтрованных строк |
filtered_rows_data |
список списков | Данные отфильтрованных строк |
Настройки¶
Определены в backend/app/schemas/settings.py.
ProcessingMode¶
Перечисление режимов обработки:
| Значение | Описание |
|---|---|
sync |
Мгновенная обработка (дороже) |
batch |
Пакетная обработка (дешевле на 50 %, с задержкой) |
ClaudeModel¶
Перечисление доступных моделей Claude:
| Значение | Название | Описание |
|---|---|---|
claude-haiku-4-5-20251001 |
Claude Haiku 4.5 | Быстрая и дешёвая модель для типовых задач |
claude-sonnet-4-20250514 |
Claude Sonnet 4 | Баланс качества и стоимости |
claude-opus-4-20250514 |
Claude Opus 4 | Максимальное качество для сложных документов |
AppSettings¶
Настройки приложения.
| Поле | Тип | Описание |
|---|---|---|
processing_mode |
ProcessingMode | Режим обработки (по умолчанию sync) |
claude_model |
ClaudeModel | Модель Claude (по умолчанию Haiku) |
batch_size |
int | Количество страниц на запрос (от 5 до 50, по умолчанию 20) |
batch_worker_paused |
bool | Обработка приостановлена (по умолчанию нет) |
AppSettingsUpdate¶
Запрос обновления настроек. Все поля необязательные.
| Поле | Тип | Описание |
|---|---|---|
processing_mode |
ProcessingMode или null | Режим обработки |
claude_model |
ClaudeModel или null | Модель |
batch_size |
int или null | Количество страниц на запрос |
batch_worker_paused |
bool или null | Приостановить обработку |
SearchFieldCreate¶
Создание глобального поля поиска.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
id |
str | да | Уникальный идентификатор (латиница, snake_case, до 50 символов) |
label |
str | да | Отображаемое название (до 100 символов) |
document_fields |
список строк | да | Пути к полям документа |
detect_patterns |
список строк | нет | Образцы для автоопределения |
default_weight |
int | нет | Вес по умолчанию от 0 до 100 (по умолчанию 25) |
default_method |
str | нет | Способ сравнения по умолчанию (по умолчанию exact) |
SearchFieldUpdate¶
Обновление поля поиска. Все поля необязательные.
| Поле | Тип | Описание |
|---|---|---|
label |
str или null | Название |
document_fields |
список строк или null | Пути к полям |
detect_patterns |
список строк или null | Образцы для автоопределения |
default_weight |
int или null | Вес |
default_method |
str или null | Способ сравнения |
OilfieldCreate¶
Создание записи месторождения.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
name |
str | да | Название (до 100 символов) |
keywords |
список строк | да | Ключевые слова для поиска |
OilfieldUpdate¶
Обновление месторождения. Все поля необязательные.
| Поле | Тип | Описание |
|---|---|---|
name |
str или null | Название |
keywords |
список строк или null | Ключевые слова |
Шаблоны документов¶
Определены в backend/app/schemas/template.py.
TemplateResponse (шаблоны документов)¶
Информация о шаблоне типа документа.
| Поле | Тип | Описание |
|---|---|---|
id |
str | Идентификатор |
doc_type |
str | Тип документа |
doc_subtype |
str или null | Подтип |
description |
str или null | Описание |
example_doc_id |
str или null | Идентификатор документа-примера |
fields |
object | Области интереса |
count |
int | Количество документов этого типа |
created_at |
datetime | Время создания |
updated_at |
datetime | Время обновления |
TemplateCreate (шаблоны документов)¶
Создание шаблона типа документа.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
doc_type |
str | да | Тип документа |
doc_subtype |
str или null | нет | Подтип |
description |
str или null | нет | Описание |
example_doc_id |
str или null | нет | Документ-пример |
fields |
object или null | нет | Области интереса |
Шаблоны реестров¶
Определены в backend/app/schemas/registry.py (раздел шаблонов).
TemplateResponse (шаблоны реестров)¶
Информация о сохранённом шаблоне реестра.
| Поле | Тип | Описание |
|---|---|---|
id |
str | Идентификатор |
name |
str | Название шаблона |
parsing |
ParsingConfig | Настройки разбора |
fields |
список RegistryField | Привязки полей |
search_config |
SearchConfig | Настройки поиска |
auto_detect |
AutoDetectConfig | Настройки автоопределения |
usage_count |
int | Количество использований |
last_used |
datetime или null | Последнее использование |
created_at |
datetime | Время создания |
TemplateSuggestion¶
Предложение шаблона при загрузке нового реестра.
| Поле | Тип | Описание |
|---|---|---|
template |
TemplateResponse | Шаблон |
match_score |
float | Уверенность в совпадении от 0 до 1 |
matched_patterns |
список строк | Сработавшие образцы |
TaskStatusResponse¶
Состояние фоновой задачи импорта или поиска.
| Поле | Тип | Описание |
|---|---|---|
task_id |
str | Идентификатор задачи |
status |
str | Состояние: pending, running, completed, failed |
progress |
int | Прогресс от 0 до 100 |
message |
str или null | Сообщение |
error |
str или null | Текст ошибки |
started_at |
datetime или null | Время запуска |
completed_at |
datetime или null | Время завершения |
ColumnValuesResponse¶
Уникальные значения колонки (для фильтрации в таблице результатов).
| Поле | Тип | Описание |
|---|---|---|
values |
список строк | Уникальные значения |
total |
int | Общее количество |
has_more |
bool | Есть ещё значения за пределами выборки |