Хранилища данных

Серверная часть использует два внешних хранилища: базу данных MongoDB для структурированных сведений и хранилище MinIO для файлов.

MongoDB

Подключение

Подключение к MongoDB выполняется через асинхронную библиотеку Motor. При запуске приложения создаётся единственный экземпляр клиента, который используется всеми маршрутами и сервисами.

Адрес и имя базы данных задаются переменными MONGODB_URL и MONGODB_DATABASE (подробнее --- в разделе Конфигурация).

При подключении автоматически создаются индексы во всех коллекциях для ускорения частых запросов.

Коллекции

Коллекция	Назначение	Основные индексы
jobs	Задания на обработку (каждый загруженный файл)	status, created_at
documents	Распознанные документы с извлечёнными полями	job_id, doc_type, (job_id + page_start)
templates	Шаблоны типов документов	doc_type, (doc_type + doc_subtype)
archive_files	Записи о файлах в архиве	path, status, (path + file_size)
archive_folders	Записи о папках в архиве	path
folder_processing	Состояние обработки папок	process_id, status, folder_path
registries	Реестры (загруженные файлы Excel)	(создаются при использовании)
registry_rows	Строки реестров с данными сопоставления	registry_id, (registry_id + status)
settings	Настройки программы (единственный документ app_settings)	(без специальных индексов)
yandex_imports	Записи об импортах с Яндекс.Диска	(создаются при использовании)

Как используются коллекции

jobs --- каждый загруженный PDF-файл создаёт одно задание. Задание проходит через статусы: pending (ожидает обработки) → processing (обрабатывается) → completed (завершено) или error (ошибка). В задании хранятся имя исходного файла, путь в хранилище, количество страниц, время создания и обновления.

documents --- результат обработки задания. Один PDF-файл может содержать несколько документов. Для каждого хранятся: тип и подтип документа, извлечённые поля (номер, дата, контрагент, сумма и другие), номера страниц, ссылки на изображения страниц в MinIO.

registries --- каждый загруженный файл Excel создаёт один реестр. В реестре хранятся: имя файла, настройки маппинга (какие колонки Excel соответствуют каким полям документа), правила сопоставления, статус обработки, статистика по совпадениям.

registry_rows --- строки реестра с исходными и приведёнными значениями. Для каждой строки хранятся: ссылка на реестр, исходные значения ячеек, приведённые значения, найденные совпадения с документами, балл совпадения, статус подтверждения.

settings --- единственный документ с идентификатором app_settings, содержащий текущий режим обработки, выбранную модель распознавания, список полей для поиска, список месторождений с ключевыми словами.

Доступ из разных частей системы

• Серверная часть (FastAPI) обращается к MongoDB асинхронно через библиотеку Motor. Все операции неблокирующие.
• Фоновый обработчик (Celery) работает в отдельном процессе и использует синхронный драйвер PyMongo. При запуске обработчика выполняется сброс зависших задач (подробнее --- в разделе Структура серверной части).

MinIO

Подключение

MinIO --- S3-совместимое хранилище объектов. Серверная часть подключается к нему через официальную библиотеку minio.

При запуске создаются два клиента:

• Внутренний --- для операций загрузки и скачивания файлов. Использует внутренний адрес контейнера (MINIO_ENDPOINT).
• Публичный --- для формирования временных ссылок на скачивание. Использует публичный адрес (MINIO_PUBLIC_ENDPOINT), чтобы подпись ссылки была действительна при обращении из браузера пользователя.

Все операции с MinIO выполняются в отдельном пуле из четырёх потоков, чтобы синхронные вызовы библиотеки не блокировали асинхронный цикл обработки событий FastAPI.

Хранилища (buckets)

Хранилище	Назначение
uploads	Исходные загруженные PDF-файлы. Файл попадает сюда сразу после загрузки пользователем
documents	Изображения отдельных страниц после разделения PDF. Каждая страница сохраняется как отдельное изображение
previews	Миниатюры страниц для быстрого предпросмотра в интерфейсе
originals	Архив оригиналов файлов. Используется при работе с деревом папок архива

Все четыре хранилища создаются автоматически при первом запуске приложения, если их ещё не существует.

Операции с файлами

Серверная часть предоставляет набор асинхронных функций для работы с MinIO:

Операция	Описание
Загрузка файла	Сохраняет данные в указанное хранилище, возвращает путь вида bucket/object_name
Скачивание файла	Возвращает содержимое файла в виде массива байтов
Получение временной ссылки	Формирует ссылку на скачивание, действующую 24 часа. Используется для просмотра оригиналов в браузере
Удаление файла	Удаляет один файл из хранилища
Удаление по префиксу	Удаляет все файлы с заданным префиксом (например, все страницы одного задания)
Список файлов	Возвращает список имён файлов в хранилище с заданным префиксом
Проверка существования	Проверяет, существует ли файл, без скачивания его содержимого

Путь файла в хранилище

Файлы организованы по идентификатору задания. Например, для задания с идентификатором abc123:

• исходный PDF: uploads/abc123.pdf
• изображение страницы 1: documents/abc123/page_001.png
• миниатюра страницы 1: previews/abc123/page_001.png