Перейти к содержанию

Структура серверной части

Обзор

Серверная часть расположена в каталоге backend/app/ и построена на платформе FastAPI. Она отвечает за приём запросов от пользовательского интерфейса, обработку документов, управление данными и взаимодействие с внешними сервисами.

Каталоги и их назначение

backend/app/
├── main.py              # Точка входа: создание приложения, подключение маршрутов
├── config.py            # Настройки из переменных окружения
├── celery_app.py        # Настройка фоновой очереди задач (Celery)
├── tasks.py             # Описание фоновых задач (поиск по реестру, импорт)
├── api/
│   └── routes/          # Серверные маршруты (REST-адреса)
├── core/
│   ├── database.py      # Подключение к базе данных MongoDB
│   └── storage.py       # Подключение к хранилищу файлов MinIO
├── models/              # Внутренние модели данных
├── schemas/             # Схемы запросов и ответов (Pydantic)
└── services/            # Сервисы с логикой обработки

main.py --- точка входа

Создаёт экземпляр приложения FastAPI и выполняет начальную подготовку при запуске:

  1. Подключается к базе данных MongoDB.
  2. Подключается к хранилищу файлов MinIO и создаёт необходимые хранилища, если их ещё нет.
  3. Запускает обработку задач, которые остались незавершёнными после предыдущего перезапуска.
  4. Если включён пакетный режим обработки --- запускает фоновый процесс проверки готовности пакетов.
  5. Подключает все группы маршрутов.

При остановке приложение корректно завершает фоновые процессы и закрывает соединение с базой данных.

Также здесь настроена политика междоменных запросов (CORS): разрешены обращения с боевого домена, локального Docker-контейнера и сервера разработки Vite.

config.py --- настройки

Все настройки приложения считываются из переменных окружения. Подробное описание каждой переменной --- в разделе Конфигурация.

celery_app.py --- фоновая очередь

Настраивает приложение Celery для выполнения длительных задач в отдельном процессе. Использует Redis в качестве брокера и хранилища результатов.

При запуске фонового обработчика автоматически сбрасывает зависшие задачи:

  • реестры в промежуточных статусах (searching, exporting, importing) возвращаются в состояние configured;
  • задания обработки в статусе processing возвращаются в pending;
  • незавершённые импорты папок отмечаются как failed;
  • прерванные импорты с Яндекс.Диска возобновляются с того места, на котором остановились.

tasks.py --- фоновые задачи

Содержит определения задач, которые выполняются в фоновом обработчике Celery:

  • поиск совпадений по реестру;
  • импорт данных с Яндекс.Диска.

Это самый большой файл серверной части --- в нём сосредоточена логика фоновых операций.

api/routes/ --- серверные маршруты

Каждый файл отвечает за группу REST-адресов:

Файл Префикс Назначение
jobs.py /api/jobs Задания на обработку документов
documents.py /api/documents Работа с распознанными документами
groups.py /api/groups Группы связанных документов
archive.py /api/archive Дерево папок и загрузка файлов
registries.py /api/registries Реестры и сверка
registry_templates.py /api/registry-templates Шаблоны настройки реестров
templates.py /api/templates Шаблоны типов документов
settings.py /api/settings Настройки программы

Подробное описание каждой группы маршрутов --- в разделе «Серверные маршруты».

core/ --- подключения к хранилищам

Два файла, обеспечивающих связь с внешними хранилищами:

  • database.py --- асинхронное подключение к MongoDB через библиотеку Motor, создание индексов при запуске;
  • storage.py --- подключение к MinIO (S3-совместимому хранилищу), операции загрузки, скачивания, удаления файлов.

Подробнее --- в разделе Хранилища данных.

models/ --- модели данных

Внутренние модели, описывающие структуру документов в базе данных:

Файл Назначение
job.py Задание на обработку (исходный файл)
document.py Распознанный документ с извлечёнными полями
template.py Шаблон типа документа

schemas/ --- схемы запросов и ответов

Схемы Pydantic, определяющие формат входящих и исходящих данных для каждой группы маршрутов:

Файл Назначение
job.py Создание задания, ответ со списком заданий
document.py Ответ с данными документа, запрос на редактирование
group.py Ответ с данными группы
archive.py Запросы на загрузку, создание папки, перенос файлов
registry.py Создание реестра, настройка маппинга, запуск поиска
settings.py Чтение и обновление настроек
template.py Управление шаблонами

services/ --- сервисы с логикой обработки

Основная логика приложения вынесена в отдельные сервисы:

Файл Назначение
pdf_processor.py Преобразование PDF в изображения страниц
segmentation.py Разделение страниц на отдельные документы
claude_client.py Отправка запросов на распознавание к Claude
gcp_vision.py Распознавание текста через GCP Vision (резервный вариант)
batch_service.py Формирование и отправка пакетов запросов к Claude
batch_worker.py Фоновый процесс проверки готовности пакетов
workload_manager.py Управление параллельностью и ограничение потребления памяти
matching.py Сопоставление документа со строкой реестра по правилам
grouping.py Группировка связанных документов по баллам совпадения
date_utils.py Разбор и сравнение неоднозначных дат
oilfield_utils.py Извлечение названий месторождений из текста
registry_import.py Импорт строк реестра из файла Excel в базу
registry_search.py Поиск совпадений документов по данным реестра
contract_filename_parser.py Извлечение данных договора из имени файла

Жизненный цикл приложения

При запуске серверная часть проходит следующие этапы:

  1. Чтение настроек из переменных окружения.
  2. Подключение к MongoDB, создание индексов в коллекциях.
  3. Подключение к MinIO, создание хранилищ (uploads, documents, previews, originals).
  4. Запуск необработанных заданий, оставшихся от предыдущего сеанса.
  5. Если включён пакетный режим --- запуск фонового наблюдателя за пакетами.
  6. Начало приёма входящих запросов.

При остановке:

  1. Остановка фонового наблюдателя за пакетами (если был запущен).
  2. Закрытие соединения с MongoDB.