Files
mostovik-backend/docs/source-record-export-matrix-ru.md
Aleksandr Meshchryakov b4f3a21ad6
Some checks failed
Mostovik Backend CI/CD / Tests and lint (pull_request) Failing after 3m47s
Mostovik Backend CI/CD / Build linux/amd64 release images (pull_request) Has been skipped
Mostovik Backend CI/CD / Deploy dev (pull_request) Has been skipped
Mostovik Backend CI/CD / Deploy and verify internal main (pull_request) Has been skipped
fix: group JSON source exports by organization
2026-09-27 10:29:17 +02:00

141 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Матрица файловых выгрузок источников
## Пользовательский контракт
Frontend отправляет администраторский
`POST /api/v2/organization-source-records/export-ticket/` с массивом `sources`
и выбранным `format`. В ответ он получает короткоживущий одноразовый ticket и
передаёт его обычной HTML-формой в
`POST /api/v2/organization-source-records/export-download/`. Поэтому браузер
сохраняет потоковый ZIP напрямую на диск, не удерживая весь архив как Blob в
JavaScript. Ticket передаётся в теле формы, не попадает в URL и после первого
запроса становится недействительным.
Имя скачиваемого архива формируется по выбранным источникам и времени создания
запроса: `<source-stem>_YYYYMMDD_HHMMSS.zip`, а для нескольких источников их
имена соединяются через `__`. Это же имя возвращается в `file_name` при выдаче
ticket и затем используется в `Content-Disposition`.
Совместимый администраторский
`POST /api/v2/organization-source-records/export/` по-прежнему сразу возвращает
тот же ZIP API-клиентам. Крупный XLSX может состоять из нескольких файлов
`*-part-001.xlsx`, `*-part-002.xlsx` и далее.
При скачивании endpoint не читает таблицы записей источников и не строит CSV,
XLSX или JSON заново. Он упаковывает файлы последнего полностью опубликованного
ночного поколения и сразу потоково отправляет ZIP без временной копии всего
архива. Поэтому `Content-Length` у ответа отсутствует. Если ни одного поколения
ещё нет, API отвечает `503` с кодом `source_export_not_ready`.
Каждое поколение содержит только текущий календарный год в timezone сервиса.
Для записей с предметной датой год определяется по ней, для записей без такой
даты — по `created_at`, для финансовых отчётов — по году `financial_lines`.
Вложенные финансовые строки других лет исключаются. После смены года поколение
прошлого года не раздаётся: до первой успешной сборки нового года API отвечает
`503 source_export_not_ready`.
## Матрица
| Группа API | Файл | CSV | XLSX | JSON |
|---|---|:---:|:---:|:---:|
| `financial_indicators` | `financial-indicators` | — | — | да |
| `government_procurements` | `public-procurements` | да | да | да |
| `industrial_production` | `manufacturers-and-products` | да | да | да |
| `planned_inspections` | `planned-inspections` | да | да | да |
| `bankruptcy` | `bankruptcy-procedures` | да | да | да |
| `defense_suppliers` | `defense-unreliable-suppliers` | да | да | да |
| `arbitration` | `arbitration-cases` | да | да | да |
| `security_registries` | `information-security-registries` | да | да | да |
| `vacancies` | `labor-vacancies` | да | да | да |
Итого формируется 25 логических артефактов: один JSON для финансовых показателей
и по три формата для остальных восьми групп. Физических файлов может быть
больше из-за разбиения крупных XLSX. Если финансовые показатели выбраны вместе
с другим форматом, в ZIP для них всё равно включается JSON.
CSV и XLSX начинают строку организации с полей `Наименование`, `ИНН`, `ОГРН`,
`КПП`, `ОКПО`, после которых следуют поля исходной записи и развёрнутого
`payload`. JSON каждого источника — массив организаций с `okpo` и массивом
записей под ключом группы API. Например, `bankruptcy-procedures.json`:
```json
[{"okpo":"12345678","bankruptcy":[{"uid":"...","source_group":"bankruptcy","payload.case_number":"..."}]}]
```
Записи одной организации собираются вместе независимо от порядка чтения из БД.
`ОКПО` переносится из записи в `okpo` оболочки; остальные поля записи остаются
в прежнем виде. При отсутствии ОКПО экспортируется `null`, а для группировки
используются ИНН, ОГРН и наименование, чтобы не смешивать разные организации.
Вложенные финансовые строки `financial_lines` сохраняются внутри финансовой
записи. При выборе нескольких источников ZIP содержит отдельный JSON-файл для
каждого. Все записи текущего года включаются в публичные файлы, а техническое
наименование внешнего поставщика нейтрализуется. Исходные значения в БД
сохраняются для работы интеграции и дедупликации.
## Ночная генерация
Celery Beat запускает
`organizations.tasks.refresh_source_record_export_artifacts` ежедневно в
`05:30 Europe/Moscow`, после ежедневного обновления organization sources в
`04:30`.
Генератор:
1. читает каждую группу из БД один раз без глобальной сортировки миллионов строк;
выборка текущего года использует функциональный индекс по году строковой
`record_date`, а записи без предметной даты — индекс `created_at`;
2. пишет плоский spool на диск, затем группирует JSON по ОКПО через временный
дисковый индекс SQLite без накопления всех строк в памяти;
3. потоково создаёт CSV и XLSX из того же spool;
4. разбивает XLSX по умолчанию по 100 000 строк на отдельные файлы, ограничивая временный XML и не превышая лимит Excel;
5. записывает размеры файлов, номера частей и календарный `export_year` в manifest;
6. атомарно переключает `current.json` только после готовности всей матрицы;
7. сохраняет текущее и предыдущее поколения по умолчанию.
При ошибке незавершённое поколение удаляется, а download endpoint продолжает
отдавать предыдущую успешную версию.
### Расчёт диска
Атомарная публикация требует одновременно хранить уже опубликованные поколения
и одно новое поколение в staging. Во время группировки JSON дополнительно
создаётся временная база SQLite размером порядка исходного spool. Минимальный
запас под артефакты рассчитывается как
`(SOURCE_RECORD_EXPORT_GENERATIONS_TO_KEEP + 1) * размер поколения`, плюс
spool, временная база SQLite и рабочий запас файловой системы. Исторический снимок dev от 2026-08-03 до
ограничения по году занимал 16,55 ГБ (54 физических файла); актуальный размер
годового поколения нужно брать из `total_size` результата команды сборки.
Временная копия целого ZIP при скачивании не создаётся.
На локальном снимке от 2026-08-04 поколение за 2026 год содержит 122 582 записи
и занимает 809 768 139 байт (772,3 MiB) для всей матрицы из 25 файлов. Архив со
всеми источниками оценивается в 410,1 MiB для JSON, 289,9 MiB для CSV и
72,3 MiB для XLSX; ZIP использует `ZIP_STORED`, поэтому к сумме файлов
добавляется только небольшой служебный overhead.
## Хранение и первый запуск
Каталог задаётся через `SOURCE_RECORD_EXPORT_DIRECTORY`, по умолчанию —
`media/source-record-exports`. Он должен быть общим read-write volume для web и
Celery worker. В Docker Compose используется `./media:/app/media`.
После первого развёртывания готовое поколение можно создать сразу, не ожидая
ночного расписания. После обновления формата JSON поколения с manifest версии 2
не раздаются: до первой успешной сборки версии 3 API возвращает
`503 source_export_not_ready`. Запустите команду ниже после развёртывания,
чтобы восстановить доступность выгрузок сразу:
```bash
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 распределённой блокировки Celery |
| `SOURCE_RECORD_EXPORT_XLSX_ROWS_PER_FILE` | `100000` | Максимум строк данных в одной XLSX-части |
| `SOURCE_RECORD_EXPORT_DOWNLOAD_TICKET_TTL_SECONDS` | `300` | Срок действия одноразового browser-download ticket |