Прослойка обращений к серверу¶

Обзор¶

Файл frontend-react/src/api/client.ts содержит единственный модуль, через который пользовательский интерфейс общается с серверной частью. Все обращения проходят через экземпляр библиотеки Axios с общими настройками. Модуль экспортирует восемь групп методов, каждая из которых соответствует определённой предметной области.

Базовый адрес определяется переменной окружения VITE_API_URL. В режиме разработки значение пустое --- Vite проксирует запросы на серверную часть. В рабочем окружении nginx выполняет ту же роль.

Общий экземпляр Axios¶

const api = axios.create({
  baseURL: API_URL,
  headers: { 'Content-Type': 'application/json' },
  withCredentials: true,
})

Все методы групп используют этот экземпляр. Заголовок Content-Type переопределяется на multipart/form-data для методов загрузки файлов.

jobsApi --- задания обработки¶

Обращается к серверным адресам /api/jobs/.

Метод	Серверный адрес	Назначение
`list(params?)`	`GET /api/jobs/`	Получить список заданий. Необязательные параметры: `limit`, `status`
`get(id)`	`GET /api/jobs/{id}`	Получить одно задание по идентификатору
`create(file)`	`POST /api/jobs/`	Создать задание, загрузив файл (`multipart/form-data`)
`checkDuplicate(filename, file_size)`	`POST /api/jobs/check-duplicate`	Проверить, нет ли уже задания с таким именем файла и размером
`process(id)`	`POST /api/jobs/{id}/process`	Запустить обработку задания
`reprocess(id)`	`POST /api/jobs/{id}/reprocess`	Повторно обработать задание
`delete(id)`	`DELETE /api/jobs/{id}`	Удалить задание
`export(id)`	формирует ссылку на `GET /api/jobs/{id}/export`	Получить ссылку для скачивания результатов
`startQueue()`	`POST /api/jobs/queue/start`	Возобновить обработку очереди
`pauseQueue()`	`POST /api/jobs/queue/pause`	Приостановить обработку очереди
`clearQueue()`	`POST /api/jobs/queue/clear`	Очистить очередь ожидающих заданий
`resetStuck()`	`POST /api/jobs/queue/reset-stuck`	Сбросить зависшие задания обратно в очередь
`cancelAll()`	`POST /api/jobs/queue/cancel-all`	Отменить все задания в очереди
`cancel(id)`	`POST /api/jobs/{id}/cancel`	Отменить конкретное задание
`folderStats()`	`GET /api/jobs/folder-stats`	Получить статистику по папкам
`batchOverview()`	`GET /api/jobs/batch-overview`	Получить сводку по текущим партиям обработки

documentsApi --- документы¶

Обращается к серверным адресам /api/documents/.

Метод	Серверный адрес	Назначение
`list(params?)`	`GET /api/documents/`	Получить список документов. Фильтры: `job_id`, `doc_type`, `group_id`, `ungrouped`, `has_error`
`get(id)`	`GET /api/documents/{id}`	Получить один документ по идентификатору
`markError(id, comment?)`	`PATCH /api/documents/{id}/error`	Отметить документ как ошибочный с необязательным комментарием
`clearError(id)`	`PATCH /api/documents/{id}/error`	Снять отметку об ошибке
`viewUrl(id)`	формирует ссылку на `GET /api/documents/{id}/view`	Получить ссылку для просмотра в браузере
`downloadUrl(id)`	формирует ссылку на `GET /api/documents/{id}/download`	Получить ссылку для скачивания
`previewUrl(id)`	формирует ссылку на `GET /api/documents/{id}/preview`	Получить ссылку для предпросмотра изображения
`getDownloadUrl(id)`	`GET /api/documents/{id}/download-url`	Получить подписанную ссылку на скачивание (устаревший способ)
`getPreviewUrl(id)`	`GET /api/documents/{id}/preview-url`	Получить подписанную ссылку на предпросмотр (устаревший способ)
`getStatsByType(job_id?)`	`GET /api/documents/stats/by-type`	Получить статистику по типам документов
`search(params)`	`GET /api/documents/search`	Найти документы по тексту. Параметры: `q`, `doc_type`, `has_error`, `skip`, `limit`
`searchCount(params)`	`GET /api/documents/search/count`	Получить количество результатов поиска
`getRegistries(id)`	`GET /api/documents/{id}/registries`	Получить список реестров, в которых встречается документ
`updateFields(id, data)`	`PATCH /api/documents/{id}/fields`	Вручную изменить поля документа: данные из содержимого (`from_content`) или из имени файла (`from_filename`)
`revertField(id, fieldPath)`	`POST /api/documents/{id}/fields/revert`	Отменить ручное изменение поля и вернуть исходное значение

groupsApi --- группы документов¶

Обращается к серверным адресам /api/groups/.

Метод	Серверный адрес	Назначение
`list(params?)`	`GET /api/groups/`	Получить список групп. Фильтры: `job_id`, `review_status`, `skip`, `limit`
`get(id)`	`GET /api/groups/{id}`	Получить одну группу
`getStats(job_id?)`	`GET /api/groups/stats`	Получить статистику по группам
`confirm(id)`	`POST /api/groups/{id}/confirm`	Подтвердить группу
`ungroup(id)`	`DELETE /api/groups/{id}`	Разгруппировать --- удалить группу и вернуть документы в несгруппированное состояние

archiveApi --- файловый архив¶

Обращается к серверным адресам /api/archive/. Это самая большая группа, охватывающая управление файлами, импорт с Яндекс.Диска и контрактный импорт.

Работа с файлами и папками¶

Метод	Серверный адрес	Назначение
`getTree(path?)`	`GET /api/archive/tree`	Получить дерево файлов и папок
`getTreeChildren(path?, skip?, limit?)`	`GET /api/archive/tree/children`	Получить содержимое папки с постраничной загрузкой
`getUnprocessedCount()`	`GET /api/archive/unprocessed-count`	Получить количество необработанных файлов
`getStats()`	`GET /api/archive/stats`	Получить общую статистику архива
`getFile(id)`	`GET /api/archive/file/{id}`	Получить сведения о файле
`createFolder(path)`	`POST /api/archive/folder`	Создать новую папку
`uploadFile(file, path)`	`POST /api/archive/upload-file`	Загрузить один файл в указанную папку
`uploadZip(file, basePath, onProgress?)`	`POST /api/archive/upload-zip`	Загрузить архив и распаковать в указанную папку. Тайм-аут --- 10 минут. Поддерживает отслеживание прогресса загрузки
`uploadZipFromPath(filePath, basePath)`	`POST /api/archive/upload-zip-from-path`	Распаковать архив, уже доступный серверу по указанному пути. Тайм-аут --- 1 час
`viewFile(id)`	формирует ссылку на `GET /api/archive/file/{id}/view`	Получить ссылку для просмотра файла
`downloadFile(id)`	формирует ссылку на `GET /api/archive/file/{id}/download`	Получить ссылку для скачивания файла
`deleteFile(id)`	`DELETE /api/archive/file/{id}`	Удалить файл
`deleteFolder(path)`	`DELETE /api/archive/folder`	Удалить папку
`downloadFolder(path)`	формирует ссылку на `GET /api/archive/download-folder`	Получить ссылку для скачивания папки целиком
`moveItem(sourcePath, targetPath)`	`PUT /api/archive/move`	Переместить файл или папку

Обработка файлов¶

Метод	Серверный адрес	Назначение
`processFile(id)`	`POST /api/archive/process/{id}`	Отправить файл на обработку
`processFolder(path)`	`POST /api/archive/process-folder`	Отправить все файлы в папке на обработку
`startFolderProcessing(path, maxConcurrent?)`	`POST /api/archive/process-folder/start`	Запустить фоновую обработку папки с ограничением числа одновременных заданий
`getFolderProcessingStatus(processId)`	`GET /api/archive/process-folder/status/{processId}`	Получить состояние фоновой обработки папки
`getActiveFolderProcessing()`	`GET /api/archive/process-folder/active`	Получить список активных фоновых обработок папок

Импорт с Яндекс.Диска¶

Метод	Серверный адрес	Назначение
`browseYandex(publicUrl, path?)`	`GET /api/archive/yandex/browse`	Просмотреть содержимое общедоступной ссылки Яндекс.Диска
`importYandex(publicUrl, selectedPaths, basePath?)`	`POST /api/archive/import-yandex`	Синхронный импорт выбранных файлов (устаревший способ)
`startYandexImport(publicUrl, selectedPaths, basePath?)`	`POST /api/archive/import-yandex/start`	Запустить фоновый импорт через Celery
`getYandexImportStatus(importId)`	`GET /api/archive/import-yandex/status/{importId}`	Получить состояние фонового импорта
`getActiveYandexImports()`	`GET /api/archive/import-yandex/active`	Получить список активных импортов
`getRecentYandexImports()`	`GET /api/archive/import-yandex/recent`	Получить список недавних импортов
`resumeYandexImport(importId)`	`POST /api/archive/import-yandex/resume/{importId}`	Возобновить прерванный импорт
`getYandexImportHistory(skip?, limit?, status?)`	`GET /api/archive/import-yandex/history`	Получить историю всех импортов с Яндекс.Диска

Контрактный импорт по именам файлов¶

Метод	Серверный адрес	Назначение
`previewContractImport(folderPath)`	`POST /api/archive/import-contracts/preview`	Предварительный просмотр: какие поля извлекутся из имён файлов
`startContractImport(folderPath)`	`POST /api/archive/import-contracts/start`	Запустить контрактный импорт
`getContractImportStatus(importId)`	`GET /api/archive/import-contracts/status/{importId}`	Получить состояние контрактного импорта
`getActiveContractImports()`	`GET /api/archive/import-contracts/active`	Получить список активных контрактных импортов

Статусы папок¶

Метод	Серверный адрес	Назначение
`getFolderStatuses()`	`GET /api/archive/folder-statuses`	Получить статусы всех папок
`setFolderStatus(path, status)`	`PUT /api/archive/folder-status`	Установить статус папки

registriesApi --- реестры¶

Обращается к серверным адресам /api/registries/. Методы организованы по этапам работы мастера настройки реестра.

Общие действия¶

Метод	Серверный адрес	Назначение
`list(params?)`	`GET /api/registries`	Получить список реестров. Фильтры: `skip`, `limit`, `status`
`get(id)`	`GET /api/registries/{id}`	Получить один реестр
`upload(file, onProgress?)`	`POST /api/registries/upload`	Загрузить файл Excel. Поддерживает отслеживание прогресса загрузки
`delete(id)`	`DELETE /api/registries/{id}`	Удалить реестр
`getMatchMethods()`	`GET /api/registries/match-methods`	Получить список доступных способов сравнения

Шаг 1 мастера: выбор листа и разметка¶

Метод	Серверный адрес	Назначение
`getPreview(id, params)`	`GET /api/registries/{id}/preview`	Предварительный просмотр данных листа Excel. Параметры: `sheet_name`, `header_row`, `data_start_row`, `fill_down_columns`, `column_header_row`, `skip_rows_containing`, `required_column_index`, `min_filled_cells`, `limit`
`saveParsing(id, sheetName, config)`	`POST /api/registries/{id}/parsing`	Сохранить настройки разметки листа: номер строки заголовка, начало данных, колонки для заполнения пропусков и другие параметры

Шаг 2 мастера: привязка полей¶

Метод	Серверный адрес	Назначение
`detectFields(id)`	`GET /api/registries/{id}/detect-fields`	Автоматически определить соответствие колонок Excel полям документа
`saveFields(id, fields)`	`POST /api/registries/{id}/fields`	Сохранить привязку колонок к полям. Для каждого поля указывается: идентификатор поля, номер колонки, название колонки, участвует ли в поиске, вес, способ сравнения (`exact`, `fuzzy`, `range`) и допуск для диапазона

Правила сопоставления¶

Метод	Серверный адрес	Назначение
`getMatchingRules(id)`	`GET /api/registries/{id}/rules`	Получить список правил сопоставления
`saveMatchingRules(id, rules, ruleMode?)`	`POST /api/registries/{id}/rules`	Сохранить правила. Каждое правило содержит набор полей с весами и способами сравнения, минимальный балл совпадения, признак включения. Параметр `rule_mode` определяет режим: `first_match` (первое совпавшее правило) или `all_matches` (все правила)
`deleteMatchingRule(id, ruleId)`	`DELETE /api/registries/{id}/rules/{ruleId}`	Удалить правило
`toggleMatchingRule(id, ruleId)`	`PATCH /api/registries/{id}/rules/{ruleId}/toggle`	Включить или выключить правило

Импорт и поиск¶

Метод	Серверный адрес	Назначение
`startImport(id, force?)`	`POST /api/registries/{id}/import`	Запустить импорт строк реестра в базу данных. Параметр `force` --- повторный импорт поверх существующих данных
`startSearch(id)`	`POST /api/registries/{id}/search`	Запустить поиск совпадений для строк реестра
`getTaskStatus(id)`	`GET /api/registries/{id}/status`	Получить состояние текущей фоновой задачи (импорт или поиск)

Результаты¶

Метод	Серверный адрес	Назначение
`getRows(id, params?)`	`GET /api/registries/{id}/rows`	Получить строки реестра с результатами. Фильтры: `status`, `rule_id`, `search`, `score_min`, `score_max`, `sort_by`, `sort_order`, `column_filters`, `has_warnings`
`getColumnValues(id, params)`	`GET /api/registries/{id}/column-values`	Получить уникальные значения колонки для построения фильтра
`getRow(id, rowNumber)`	`GET /api/registries/{id}/rows/{rowNumber}`	Получить одну строку реестра
`confirmMatch(id, rowNumber, documentId)`	`POST /api/registries/{id}/rows/{rowNumber}/confirm`	Подтвердить совпадение вручную, указав идентификатор документа
`unconfirmMatch(id, rowNumber)`	`DELETE /api/registries/{id}/rows/{rowNumber}/confirm`	Отменить ручное подтверждение совпадения

Выгрузка¶

Метод	Серверный адрес	Назначение
`startExport(id, includePdfs?)`	`POST /api/registries/{id}/export`	Запустить подготовку выгрузки. Параметр `include_pdfs` --- включить файлы найденных документов
`downloadExportUrl(id)`	формирует ссылку на `GET /api/registries/{id}/export/download`	Получить ссылку для скачивания выгрузки

Устаревший метод¶

Метод	Серверный адрес	Назначение
`saveSearchConfig(id, config)`	`POST /api/registries/{id}/search-config`	Сохранить настройки поиска (заменён правилами сопоставления)
`getSheetData(id, sheetName, params?)`	`GET /api/registries/{id}/preview`	Обёртка для совместимости, вызывает тот же адрес, что и `getPreview`

registryTemplatesApi --- шаблоны реестров¶

Обращается к серверным адресам /api/registry-templates/.

Метод	Серверный адрес	Назначение
`list(params?)`	`GET /api/registry-templates`	Получить список шаблонов. Фильтры: `skip`, `limit`, `search`
`get(id)`	`GET /api/registry-templates/{id}`	Получить один шаблон
`create(data)`	`POST /api/registry-templates`	Создать шаблон. Включает настройки разметки, привязку полей, настройки поиска и правила автоматического определения (по имени файла и заголовкам)
`update(id, data)`	`PUT /api/registry-templates/{id}`	Обновить шаблон
`delete(id)`	`DELETE /api/registry-templates/{id}`	Удалить шаблон
`suggest(params)`	`GET /api/registry-templates/suggest`	Подобрать подходящий шаблон по имени файла или заголовкам колонок

settingsApi --- настройки¶

Обращается к серверным адресам /api/settings/.

Общие настройки¶

Метод	Серверный адрес	Назначение
`get()`	`GET /api/settings`	Получить текущие настройки
`update(data)`	`PATCH /api/settings`	Обновить настройки: режим обработки (`sync` или `batch`), модель распознавания, размер партии
`reset()`	`POST /api/settings/reset`	Сбросить настройки к значениям по умолчанию

Поля для поиска¶

Метод	Серверный адрес	Назначение
`getSearchFields()`	`GET /api/settings/search-fields`	Получить список полей, доступных для сопоставления
`createSearchField(data)`	`POST /api/settings/search-fields`	Создать поле поиска: идентификатор, название, привязанные поля документа, образцы для определения, вес и способ сравнения по умолчанию
`updateSearchField(id, data)`	`PUT /api/settings/search-fields/{id}`	Обновить поле поиска
`deleteSearchField(id)`	`DELETE /api/settings/search-fields/{id}`	Удалить поле поиска
`resetSearchFields()`	`POST /api/settings/search-fields/reset`	Сбросить поля к значениям по умолчанию
`getDocumentFields()`	`GET /api/settings/document-fields`	Получить список всех полей, которые могут быть в документе

Состояние обработки¶

Метод	Серверный адрес	Назначение
`getProcessingStatus()`	`GET /api/settings/processing-status`	Получить текущее состояние обработки
`togglePauseProcessing()`	`POST /api/settings/processing/toggle-pause`	Переключить приостановку обработки

Месторождения¶

Метод	Серверный адрес	Назначение
`getOilfields()`	`GET /api/settings/oilfields`	Получить список месторождений
`createOilfield(data)`	`POST /api/settings/oilfields`	Добавить месторождение: название и необязательные псевдонимы
`updateOilfield(id, data)`	`PUT /api/settings/oilfields/{id}`	Обновить месторождение
`deleteOilfield(id)`	`DELETE /api/settings/oilfields/{id}`	Удалить месторождение
`resetOilfields()`	`POST /api/settings/oilfields/reset`	Сбросить месторождения к значениям по умолчанию

healthApi --- проверка состояния¶

Метод	Серверный адрес	Назначение
`check()`	`GET /health`	Проверить состояние серверной части
`root()`	`GET /`	Корневой адрес серверной части