Files
state-corp-backend/docs/source-record-export-matrix-ru.md
2026-09-27 10:27:47 +02:00

8.9 KiB
Raw Blame History

Матрица файловых выгрузок внешних данных State Corp

Пользовательский контракт

Администраторский frontend отправляет POST /api/v2/organization-source-records/export-ticket/ с массивом sources и форматом. Backend проверяет последнее полностью опубликованное поколение и возвращает короткоживущий одноразовый ticket. Затем frontend передаёт ticket в теле обычной HTML-формы на POST /api/v2/organization-source-records/export-download/.

Имя скачиваемого архива формируется по выбранным источникам и времени создания запроса: <source-stem>_YYYYMMDD_HHMMSS.zip, а для нескольких источников их имена соединяются через __. Значение file_name из ticket и итоговый Content-Disposition совпадают.

Браузер получает потоковый ZIP напрямую, без многогигабайтного Blob в JavaScript. Ticket не попадает в URL и после первого запроса становится недействительным. Совместимый администраторский endpoint POST /api/v2/organization-source-records/export/ сразу возвращает тот же ZIP для API-клиентов.

Во время скачивания таблицы external_data не читаются: endpoint упаковывает готовые файлы последнего ночного поколения. При отсутствии поколения API возвращает 503 с кодом source_export_not_ready.

Каждое поколение содержит только текущий календарный год в timezone сервиса. Для моделей с предметной датой год определяется по ней, для моделей без такой даты — по created_at, для финансовых отчётов — по году строк отчёта. Строки других лет из финансового отчёта не выгружаются. После смены года старое поколение не раздаётся: до успешной сборки нового года API отвечает 503 source_export_not_ready.

Матрица

Группа API Таблицы State Corp Файл CSV XLSX JSON
financial_indicators FinancialReport, FinancialReportLine financial-indicators — — да
government_procurements PublicProcurement public-procurements да да да
industrial_production IndustrialProduct, IndustrialCertificate, ManufacturerRegistryEntry manufacturers-and-products да да да
planned_inspections ProsecutorCheck planned-inspections да да да
bankruptcy BankruptcyProcedure bankruptcy-procedures да да да
defense_suppliers DefenseUnreliableSupplier defense-unreliable-suppliers да да да
arbitration ArbitrationCase arbitration-cases да да да
security_registries InformationSecurityRegistryEntry information-security-registries да да да
vacancies LaborVacancy labor-vacancies да да да

Итого формируется 25 логических артефактов. Финансовые показатели всегда выгружаются в JSON с вложенным массивом financial_lines. Промышленная группа объединяет три таблицы, а поле record_type различает тип строки. CSV и XLSX сохраняют плоские строки с реквизитами организации и полями payload.*. JSON каждого источника использует тот же контракт, что и Mostovik: массив организаций с okpo и массивом записей под ключом группы API. Например:

[{"okpo":"12345678","bankruptcy":[{"uid":"...","source_group":"bankruptcy","payload.case_number":"..."}]}]

ОКПО переносится из записи в okpo оболочки; остальные поля записи остаются в прежнем виде. Записи одной организации собираются вместе независимо от порядка чтения таблиц. При отсутствии ОКПО экспортируется null, а для группировки используются ИНН, ОГРН и наименование. При выборе нескольких источников ZIP содержит отдельный JSON-файл для каждого.

Все записи текущего года включаются в публичные файлы, а техническое наименование внешнего поставщика нейтрализуется. Исходные значения в БД сохраняются для работы интеграции и дедупликации.

Физических XLSX-файлов может быть больше: по умолчанию один файл содержит не более 100 000 строк данных и получает суффикс -part-001, -part-002 и далее.

Ночная генерация

Celery Beat запускает apps.external_data.tasks.refresh_source_record_export_artifacts ежедневно в 05:30 Europe/Moscow.

Генератор:

  1. читает каждую нормализованную таблицу один раз без model-level сортировки; предметные даты и fallback по created_at индексированы;
  2. создаёт плоский spool и группирует JSON по ОКПО через временный дисковый индекс SQLite, без загрузки всех строк в память;
  3. потоково формирует CSV и write-only XLSX из того же spool;
  4. записывает календарный export_year в manifest;
  5. атомарно публикует current.json только после готовности всей матрицы;
  6. при ошибке удаляет staging и продолжает отдавать предыдущее поколение того же года;
  7. сохраняет текущее и предыдущее поколения по умолчанию.

Web и Celery worker должны использовать общий read-write volume /app/media.

Первый запуск и настройки

Первое поколение можно сформировать вручную. После обновления формата JSON поколения с manifest версии 2 не раздаются: до первой успешной сборки версии 3 API возвращает 503 source_export_not_ready. Запустите команду ниже после развёртывания, чтобы восстановить доступность выгрузок сразу:

PYTHONPATH=src uv run python src/manage.py build_source_record_exports
Настройка Значение по умолчанию Назначение
SOURCE_RECORD_EXPORT_DIRECTORY media/source-record-exports Общий каталог поколений
SOURCE_RECORD_EXPORT_GENERATIONS_TO_KEEP 2 Число успешных поколений
SOURCE_RECORD_EXPORT_LOCK_TTL_SECONDS 21600 TTL распределённой блокировки
SOURCE_RECORD_EXPORT_XLSX_ROWS_PER_FILE 100000 Строк данных в одной XLSX-части
SOURCE_RECORD_EXPORT_DOWNLOAD_TICKET_TTL_SECONDS 300 Срок действия download-ticket

Для атомарной генерации требуется свободное место не меньше (GENERATIONS_TO_KEEP + 1) * размер поколения плюс исходный spool, временная база SQLite размером порядка spool и рабочий запас файловой системы.

На локальном снимке от 2026-08-04 поколение за 2026 год содержит 1 962 записи и занимает 4 738 872 байта (4,52 MiB) для всей матрицы. Архив со всеми источниками оценивается в 2,49 MiB для JSON, 1,59 MiB для CSV и 0,44 MiB для XLSX; к сумме добавляется небольшой служебный overhead ZIP.