# Матрица файловых выгрузок внешних данных 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/`.

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

Во время скачивания таблицы `external_data` не читаются: endpoint упаковывает
готовые файлы последнего ночного поколения. При отсутствии поколения 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` различает тип строки. Все строки
содержат реквизиты организации, включая ОКПО.

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

Физических 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 сортировки;
2. создаёт компактный JSON-массив и переиспользует его как готовый JSON;
3. потоково формирует CSV и write-only XLSX;
4. атомарно публикует `current.json` только после готовности всей матрицы;
5. при ошибке удаляет staging и продолжает отдавать предыдущее поколение;
6. сохраняет текущее и предыдущее поколения по умолчанию.

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

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

Первое поколение можно сформировать вручную:

```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 распределённой блокировки |
| `SOURCE_RECORD_EXPORT_XLSX_ROWS_PER_FILE` | `100000` | Строк данных в одной XLSX-части |
| `SOURCE_RECORD_EXPORT_DOWNLOAD_TICKET_TTL_SECONDS` | `300` | Срок действия download-ticket |

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