82 lines
5.5 KiB
Markdown
82 lines
5.5 KiB
Markdown
# Матрица файловых выгрузок внешних данных 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) * размер поколения` плюс запас файловой системы.
|