Files
mostovik-backend/docs/source-data-export-api-spec.md
2026-10-22 21:45:29 +02:00

1202 lines
111 KiB
Markdown
Raw Permalink 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.
---
template_id: source-backend-api
template_version: 1
source_id: 'shared-source-data-export'
source_name: 'Выгрузка готовых файлов существующих источников'
document_status: review
change_scope: extension
observed_at: '2026-10-21'
---
# Backend API страницы «Выгрузка данных из источников»
> Уточнение 2026-10-22: внутри каждого источника требуются отдельные годовые файлы.
> Правила partitioning, API v2 и включённого nightly schedule описаны в
> [актуальном дополнении](source-export-year-partitions.md); они имеют приоритет
> над прежними правилами datasets/parts ниже.
Назначение: самодостаточное задание backend-разработчику для подключения страницы
`/admin/source-data-export`. Страница уже реализована на моках: каталог источников,
раскрываемое описание и JSON-пример, отдельные части файлов, выбор формата у каждой части
и скачивание всего источника кнопкой в заголовке.
Документ следует 19 разделам `templates/backend-api.template.md`. Это расширение общей
подсистемы экспорта существующих источников, а не регистрация нового предметного источника.
Передавать backend-разработчику следует этот файл целиком. Все новые URL, DTO и ограничения
ниже — целевые требования, а не утверждение об их наличии в production.
Статус `review` означает готовность задания к техническому согласованию. Реализация,
публикация OpenAPI и контрактная приёмка ещё не выполнены; это отражено в checklist §17.
## Принципы документа
- Использовать существующие source registry, канонические записи и сборщик файлов.
- Подготовка CSV/XLSX/JSON выполняется фоновой задачей. Открытие страницы и скачивание
читают метаданные и готовые файлы без повторного парсинга внешних систем.
- Гигабайтные данные сохраняет штатный download manager браузера. Frontend не получает
весь файл через Axios/fetch Blob и не собирает ZIP в JavaScript.
- Каталог привязан к неизменяемому поколению выгрузки. После обновления поколения уже
показанный файл нельзя молча заменить другим содержимым.
- Разбивать нужно все крупные форматы, включая JSON и CSV; ограничение только XLSX
не решает задачу скачивания больших наборов.
- Публиковать фактически доступные форматы. Выбранный XLSX не может возвращаться как JSON.
- Пустой источник, ещё не подготовленный источник и техническая ошибка имеют разные состояния.
- Полнота означает все опубликованные записи, сохранённые в системе, включая прошлые годы.
Неподдерживаемые источники и пропущенные записи нельзя скрывать за успешной выгрузкой.
- Runtime API, manifest, OpenAPI и контрактные тесты описывают один согласованный контракт.
## 1. Назначение и область реализации
### Пользовательские сценарии
| Сценарий | Ожидаемый результат |
| --------------------------------- | ----------------------------------------------------------------------------- |
| Открыть страницу | Получить все зарегистрированные источники и состояние их файлов |
| Раскрыть источник | Получить состав, происхождение, поля, JSON-пример и первую страницу частей |
| Посмотреть следующие части | Постранично читать тот же snapshot, без дубликатов и пропусков |
| Выбрать формат части | Выбрать готовый вариант той же логической части |
| Скачать часть | Сохранить один CSV/XLSX/JSON без ZIP-обёртки |
| Скачать источник | Получить ZIP со всеми частями выбранного формата, включая невидимые страницы |
| Обновить страницу | Увидеть последнее опубликованное поколение и время актуальности данных |
| Открыть устаревшую страницу | Скачать сохранённое поколение либо получить явное требование обновить каталог |
| Нет данных / идёт сборка / ошибка | Показать точное состояние и доступность предыдущей успешной выгрузки |
### Границы
В scope входят каталог, metadata, подготовка всех частей, одноразовые tickets, потоковое
скачивание, хранение поколений, RBAC, observability, OpenAPI и тесты. Имеющиеся парсеры,
upload, обогащение организаций и предметные DTO переиспользуются.
Новые кнопки запуска парсеров, произвольные пользовательские фильтры записей, ручная
загрузка файлов на этой странице и вычисление новых финансовых показателей не требуются.
Полнота не означает восстановление удалённых данных, чтение quarantine или повторный обход
upstream: экспортируется всё доступное опубликованное содержимое канонического хранилища.
Моковые четыре файла и названия «Рентабельность и ликвидность» — демонстрация интерфейса.
Backend не должен создавать фиктивные файлы, дублировать один dataset или рассчитывать
неописанную сводную таблицу ради соответствия числу плиток в макете.
## 2. Нормативные ссылки и аудит текущих контрактов
Проверено по локальному frontend `7847228` с рабочими изменениями новой страницы,
локальному backend `66fcacc` и локальному `openapi.json`. Live runtime не опрашивался;
backend перед началом реализации сверяет это задание со своей актуальной веткой.
| Источник сведений | Что сверять |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `docs/info/backend-endpoints-main-page-from-mocks.md` | Общие API/envelope и правила согласованности |
| `docs/source-integration/templates/backend-api.template.md` | Структура этого задания |
| `docs/source-integration/backend-openapi-contract-recovery.md` | Canonical OpenAPI 3, генерация Orval |
| `docs/source-integration/backend-testing-8-10-amendments.md`, §12 | Native form download, ошибки существующего экспорта |
| `src/pages/main/ui/SourceDataExportPage/` | Готовая композиция UI |
| `src/pages/main/model/source-data-export/` | Временные mocks и скачивание в браузере |
| `src/pages/main/model/reference-data/exportReferenceDataSourceRecords.ts` | Существующий ticket → HTML form flow |
| `src/pages/main/ui/MainPage/MainPageSettingsDialog/components/ReferenceDataSourcesExportCard.vue` | Соответствие slug → source group |
| `src/shared/config/hiddenSources.ts` | Текущая продуктовая видимость источников |
| `openapi.json`, `orval.config.ts` | Опубликованные схемы и конфигурация генерации |
| `src/shared/api/generated-api/`, `src/shared/model/generated-zod/` | Generated API и runtime-схемы |
| Backend: `src/organizations/source_record_export.py` | Сборщик, manifest, части, ticket, streaming ZIP |
| Backend: `src/organizations/views.py`, `serializers.py` | Экспортные actions и проверки запроса |
| Backend: `src/organizations/tasks.py`, `management/commands/build_source_record_exports.py` | Фоновая и первоначальная сборка |
| Backend: `docs/source-record-export-matrix-ru.md` | Фактическая текущая матрица форматов и ограничение по году |
### Точки сверки по каждому активному endpoint
Проверить URL/method, admin permissions, operationId, schema, MIME, ошибки и фактический
native-download flow. Новый API не должен конфликтовать с `{uid}` route: статические actions
`export-catalog`, `export-ticket`, `export-download`, `export` регистрируются раньше detail.
### Подтверждённые расхождения и требуемые изменения
| ID | Сейчас по локальному коду | Требуется |
| --------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `EXP-001` | Нет каталога готовых частей для страницы | Два GET endpoint §7 |
| `EXP-002` | Сборщик содержит девять групп; локальный frontend OpenAPI перечисляет 22 | Общий registry/adapters для всех 22; первые 16 покрывают текущую страницу |
| `EXP-003` | Поколение ограничено текущим годом, финансовые строки также фильтруются по году | Новый явно обозначенный scope `all_available`; старый годовой контракт сохранить |
| `EXP-004` | Финансы имеют только JSON; запрос XLSX/CSV молча подменяется JSON | Для новой страницы честный `supported_formats`, неподдерживаемый формат → 409 |
| `EXP-005` | На части разбивается только XLSX, по 100 000 строк | Согласованные части всех поддерживаемых форматов с ограничением размера |
| `EXP-006` | `records_count` каждой XLSX-части заполнен общим count группы | Считать строки именно части, отдельно хранить общее число записей |
| `EXP-007` | Ticket хранит sources/format/time; при download снова выбирается current generation | Зафиксировать generation/part/artifact и lease при выдаче ticket |
| `EXP-008` | Ticket потребляется через `cache.get` + `cache.delete` | Атомарное одноразовое потребление, исключающее конкурентный повтор |
| `EXP-009` | Нет привязки ticket к пользователю, выдавшему запрос | Хранить issuer и проверять его текущую активность/роль перед выдачей байтов |
| `EXP-010` | Хранятся два поколения без учёта открытых скачиваний | Retention + leases на tickets/streams, §13 |
| `EXP-011` | Manifest v2 содержит filesystem `relative_path`, нет публичных UUID/sha256 | Публичные DTO без путей, manifest для нового scope с version и checksum |
Текущее наличие `export-ticket`/`export-download` и их MIME подтверждено локальным OpenAPI.
Старые утверждения об их отсутствии из ранних шаблонов к этому заданию не применяются.
## 3. Идентификаторы источника
Технический `source_id: shared-source-data-export` относится только к документу.
Новый parser source/source group для этой страницы не создаётся. API принимает существующий
`source_group`, а не frontend slug, route name или `tableKey`.
| № | Источник / существующий slug | `source_group` | Parser sources / состав |
| --: | --------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 1 | Финансово-экономические показатели / `financial-indicators` | `financial_indicators` | `fns_reports` |
| 2 | Государственные закупки по 44-ФЗ и 223-ФЗ / `public-procurements` | `government_procurements` | `procurements_44fz`, `procurements_223fz`; также сохранённые `procurements`, `contracts` той же группы |
| 3 | Производители и продукция России / `manufacturers-and-products` | `industrial_production` | `industrial`, `manufactures`, `industrial_products` |
| 4 | Плановые проверки Генпрокуратуры России / `planned-inspections` | `planned_inspections` | `inspections` |
| 5 | Сведения о процедурах банкротства / `bankruptcy-procedures` | `bankruptcy` | `fedresurs_bankruptcy` |
| 6 | Недобросовестные поставщики ГОЗ / `defense-unreliable-suppliers` | `defense_suppliers` | `unfair_suppliers`, `fas_goz` |
| 7 | Арбитражные дела / `arbitration-cases` | `arbitration` | `arbitration` |
| 8 | Реестры по информационной безопасности ФСТЭК России / `information-security-registries` | `security_registries` | `fstec` |
| 9 | Вакансии Работа России / `labor-vacancies` | `vacancies` | Все опубликованные adapters группы, включая `trudvsem` |
| 10 | ГосЭДО: Глобальный адресный справочник / `gosedo-global-address-directory` | `electronic_document_exchange` | `gosedo_address_directory` |
| 11 | Новости СМИ / `mass-media` | `media_mentions` | `media_news` |
| 12 | Зарубежные санкции / `ropk-sanctions` | `sanctions` | `ropk_sanctions` |
| 13 | Реестр участников бюджетного процесса / `budget-process-registry` | `budget_process_registry` | `budget_ubpandnubp` |
| 14 | Реестр субъектов МСП — получателей поддержки / `sme-support-recipients-registry` | `government_support` | `fns_sme_support_recipients` |
| 15 | Реестр организаций в составе СРО / `sro-membership-check` | `sro_membership` | `sro_membership_check` |
| 16 | Документы интегрированных структур / `integrated-structure-documents` | `integrated_structure_documents` | Parser `integrated_structure_documents`, records `integrated_structures` |
| 17 | Федресурс: сведения о юридических лицах / `fedresurs-company-profile` | `fedresurs_company_profile` | `fedresurs_company_profile` |
| 18 | Исполнительные производства ФССП / `fssp-enforcement-proceedings` | `enforcement_proceedings` | `fssp_enforcement_proceedings` |
| 19 | Лизинг / `checko-leasing` | `leasing` | `checko_leasing` |
| 20 | Сообщения организаций / `checko-messages` | `company_messages` | `checko_messages` |
| 21 | Лицензии организаций / `checko-licenses` | `company_licenses` | `checko_licenses` |
| 22 | Биржевая активность / `stock-exchange-activity` | `stock_exchange_activity` | `stock_exchange_activity`, включает СПБ и MOEX |
Первые 16 — обязательный набор уже сделанной страницы. Остальные шесть также регистрируются
в общем API; их показ регулируется существующим frontend feature flag. Скрытый пункт меню
не считается проверкой прав. В production registry должен явно различать разрешённый,
отключённый и ещё не подготовленный источник; зарегистрированную группу нельзя молча исключить
из ответа из-за отсутствия файлов. `export_enabled=false` отражается состоянием `unavailable`.
Состав выбирается по source_group канонических записей. Перечень parser sources в таблице
поясняет состав, а не ограничивает экспорт hardcoded allowlist, которая потеряет сохранённые
legacy records или дополнительные опубликованные adapters той же группы.
Порядок стабилен по `(order, source_group)`, title совпадает с продуктовым каталогом.
Существующие алиасы parser source не переименовывать. Добавление нового источника в будущем
включает регистрацию export adapter и metadata в том же registry.
## 4. Обязательный контракт организации
API каталога возвращает metadata файлов, а не новые предметные записи. Формат уже
существующих records не меняется. Наименование, ИНН, ОГРН, ОКПО берутся из канонических
`organization.name`, `organization.inn`, `organization.ogrn`, `organization.okpo`.
Файловый adapter может использовать существующие заголовки `Наименование`, `ИНН`, `ОГРН`,
`КПП`, `ОКПО` и развёрнутые `payload.*`. Это проекция тех же данных, а не второй справочник.
Сохранить UID записи, `source`, `source_group`, `record_type`, даты, decimal precision,
вложенные финансовые строки и source-specific поля согласно действующему adapter.
Пустые исторические идентификаторы обрабатывать по действующей спецификации конкретного
источника и фиксировать quality counters. Этот экспорт не должен самовольно отбрасывать
такие опубликованные записи, подставлять выдуманные идентификаторы или запускать enrichment.
Quarantine, credentials и закрытые технические поля в экспорт не включаются.
Моковый объект `{organization_card, section, record_name, data}` не является новым
каноническим DTO. JSON-пример на странице должен описывать фактическую schema файлов.
## 5. Матрица endpoint и решение по реализации
Все URL относительны к тому же backend-origin, который используется frontend `/api`.
| Endpoint | Решение | Назначение |
| ------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------ |
| `GET /api/v2/organization-source-records/export-catalog/` | Добавить | Сводный каталог источников без списка всех файлов |
| `GET /api/v2/organization-source-records/export-catalog/{source_group}/` | Добавить | Описание, JSON-пример и страница логических частей |
| `POST /api/v2/organization-source-records/export-ticket/` | Расширить совместимо | Выбор одного файла или архива одного источника с pinned generation |
| `POST /api/v2/organization-source-records/export-download/` | Расширить совместимо | Native form → один файл либо ZIP по ticket |
| `POST /api/v2/organization-source-records/export/` | Сохранить legacy | Старый синхронный API, новая страница его не вызывает |
| `GET /api/v1/sources/`, `GET /api/v1/sources/{slug}/` | Переиспользовать | Registry и labels существующих источников |
| `GET /api/v1/parsers/dashboard/` | Без нового контракта | Существующее состояние парсинга |
| `GET /api/v2/organization-source-records/`, detail | Без нового контракта | Каноническое содержимое готовых файлов |
| Existing refresh/run/upload/jobs/logs | Без нового пользовательского flow | Действуют по исходным спецификациям, см. §8–11 |
Новые GET actions нужны, поскольку source cards и records list не описывают готовые
физические файлы, их поколения, размер, checksum и поддерживаемые варианты одной части.
Создавать отдельные URL для каждого из 22 предметных источников не требуется.
Смежный inventory, без новых зависимостей страницы: `GET /api/v1/sources/statuses/`,
`GET /api/v1/parsers/sources/`, `GET/POST /api/v1/parsers/schedules/*`,
`GET /api/v1/parsers/load-logs/`, `GET /api/v1/parsers/records/`, `GET /api/v1/jobs/`,
`POST /api/v1/jobs/{task_id}/control/`, `GET /api/v1/jobs/{task_id}/stream/`.
## 6. Общий паттерн описания endpoint
GET и выдача ticket: Bearer access token, активный пользователь с ролью `admin`.
Binary download: короткоживущий capability ticket в теле обычной HTML-формы, §12.2.
Новые GET используют envelope `{success, data, errors, meta}`: все четыре ключа required,
`errors=null` при успехе. Catalog `meta=null`; detail `meta.pagination` — именованный DTO.
Ticket сохраняет существующий top-level формат без envelope.
Общие типы: timestamp ISO 8601 UTC, идентификаторы строками, UUID в формате UUID,
счётчики и размеры — integer `0..9007199254740991`, bytes без display-форматирования.
Nullable-поле передаётся явно как `null`. JSON-примеры ниже синтетические, но полные по форме.
### Общая ошибка новых запросов
`SourceExportError`: все пять полей required, `field` nullable. Пример `409`:
```json
{
"detail": "Выбранный формат отсутствует в этом поколении выгрузки.",
"code": "source_export_format_unavailable",
"field": "format",
"retryable": false,
"request_id": "ee38bd55-9ad4-43dd-a636-19d3fac0b4b9"
}
```
Конкретные code/status и действия frontend зафиксированы в §15; та же schema используется
для остальных бизнес-ошибок, меняются значения. Auth middleware может возвращать стандартный
`401 {"detail":"Учётные данные не предоставлены."}`: это отдельная named auth schema.
У legacy-запросов сохранить существующие error DTO, не менять общий API скрыто.
## 7. Каталог источников
### 7.1 `GET /api/v1/sources/`
Request/response не меняются. Registry карточек — источник существующих slug/title/order,
но export metadata хранится отдельно от состояния парсера. Источник без выгрузки остаётся
в export-каталоге со своим состоянием. Объединение 44-ФЗ/223-ФЗ и других подисточников
в группы выполняется по §3, не по совпадению пользовательских названий.
### 7.2 `GET /api/v1/sources/{slug}/`
Request/response не меняются. Не добавлять в source detail полный manifest или массив
содержимого файлов. Перечень export parts запрашивается отдельным action ниже.
### 7.3 `GET /api/v2/organization-source-records/export-catalog/`
Request:
```http
GET /api/v2/organization-source-records/export-catalog/
Authorization: Bearer <admin-token>
Accept: application/json
```
Query-параметров в v1 нет; неизвестный query → `400 source_export_invalid_request`.
Список малый: все зарегистрированные группы без пагинации, включая ещё не готовые.
Содержимое records, variants и binary здесь не возвращается.
Response `200 application/json`. Полный пример тестового registry с одним источником:
```json
{
"success": true,
"data": {
"schema_version": "1",
"catalog_revision": "20261021T023000Z-1",
"sources": [
{
"source_group": "government_procurements",
"source_slug": "public-procurements",
"title": "Государственные закупки по 44-ФЗ и 223-ФЗ",
"order": 2,
"export_enabled": true,
"state": "ready",
"unavailable_reason": null,
"generation_id": "11111111-1111-4111-8111-111111111111",
"generated_at": "2026-10-21T02:30:00Z",
"data_as_of": "2026-10-21T02:00:00Z",
"data_scope": "all_available",
"records_count": 3,
"parts_count": 1,
"supported_formats": ["xlsx", "csv", "json"],
"default_format": "xlsx",
"is_stale": false,
"last_build": {
"state": "success",
"started_at": "2026-10-21T02:00:00Z",
"finished_at": "2026-10-21T02:30:00Z",
"error_code": null
}
}
]
},
"errors": null,
"meta": null
}
```
В production `sources` содержит все 22 зарегистрированные группы; массив из одного
элемента выше — JSON fixture, не разрешение реализовать только закупки.
`SourceExportCatalogResponse.data`: `schema_version`, `catalog_revision`, `sources` required,
не nullable. Версия API-формы `"1"` отличается от внутренней версии filesystem manifest.
Все поля `SourceExportSourceSummary` required:
| Поле | Тип / nullable | Правило |
| -------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `source_group` | Existing source group enum / нет | Ровно одна запись на группу §3 |
| `source_slug` | string / нет | Существующий slug, не новый frontend route |
| `title` | string / нет | Непустое продуктовое название |
| `order` | integer ≥ 0 / нет | Стабильный порядок |
| `export_enabled` | boolean / нет | Настройка registry, не наличие файлов |
| `state` | `ready, empty, not_ready, building, unavailable` / нет | Правила §13 |
| `unavailable_reason` | `disabled, adapter_missing, build_failed, storage_unavailable` / да | Причина unavailable, в других состояниях null |
| `generation_id` | UUID / да | Последнее полностью опубликованное поколение группы |
| `generated_at` | date-time / да | Завершение его публикации |
| `data_as_of` | date-time / да | Snapshot данных, не время GET или выдачи ticket |
| `data_scope` | enum `all_available` / нет | Включая сохранённые прошлые годы |
| `records_count` | integer ≥ 0 / да | Уникальные исходные записи группы, не сумма по форматам |
| `parts_count` | integer ≥ 0 / да | Число логических частей, не физических variants |
| `supported_formats` | unique array `xlsx,csv,json` / нет | Пересечение форматов всех частей текущего поколения |
| `default_format` | format enum / да | Входит в supported_formats; порядок предпочтения XLSX → CSV → JSON |
| `is_stale` | boolean / нет | Данные новее snapshot, возраст больше 36 часов или последняя сборка failed |
| `last_build` | `SourceExportBuildSummary` / нет | Последняя попытка сборки, включая неудачную |
`SourceExportBuildSummary` имеет required `state` (`idle,queued,running,success,failed`),
`started_at: date-time|null`, `finished_at: date-time|null`, `error_code: string|null`.
Для `idle` timestamps/error null; для failed — публичный безопасный code, без traceback.
Отсутствие опубликованного поколения: nullable snapshot/count поля null, formats `[]`.
Состояние `empty`: опубликован пустой snapshot, counts `0`, formats `[]`, default null.
Источник с ошибкой первой сборки остаётся в списке: `state=unavailable`,
`last_build.state=failed`. Если есть старый пригодный snapshot — `state=ready|empty`,
`is_stale=true`, скачивание доступно; last_build сообщает об ошибке новой попытки.
Если нет ни одной готовой выгрузки, каталог всё равно возвращает `200` с полным registry
и состояниями. `503` применяется к недоступности самого metadata-сервиса, а не к пустой БД.
Headers: `Cache-Control: private, no-store`, `X-Request-ID`. `catalog_revision` стабилен,
пока не изменились registry, опубликованные поколения или build states; время запроса
само по себе не меняет revision. Ошибки: `401,403,429,503,500`, schema §6/§15.
### 7.4 `GET /api/v2/organization-source-records/export-catalog/{source_group}/`
Request:
```http
GET /api/v2/organization-source-records/export-catalog/government_procurements/?generation_id=11111111-1111-4111-8111-111111111111&page=1&page_size=50
Authorization: Bearer <admin-token>
Accept: application/json
```
| Параметр | Тип | Required | Default / ограничение |
| --------------------- | ------------- | ---------------------- | ---------------------------------------------------------- |
| `source_group` path | Existing enum | Да | Только registry §3 |
| `generation_id` query | UUID | Нет на первой странице | Пропуск выбирает current generation; page > 1 требует UUID |
| `page` | integer | Нет | 1, минимум 1 |
| `page_size` | integer | Нет | 50; диапазон 1..200 |
Каждая следующая страница использует полученный generation_id. Неизвестные параметры,
нечисловые/отрицательные значения и недопустимый размер → `400`; произвольный sort, search,
`format` или фильтры записей здесь не поддерживаются. Все variants одной части возвращаются
вместе, смена формата не требует запроса нового списка.
Response `200 application/json`, полный пример одной части с тремя готовыми форматами:
```json
{
"success": true,
"data": {
"source_group": "government_procurements",
"generation_id": "11111111-1111-4111-8111-111111111111",
"current_generation_id": "11111111-1111-4111-8111-111111111111",
"state": "ready",
"unavailable_reason": null,
"generated_at": "2026-10-21T02:30:00Z",
"data_as_of": "2026-10-21T02:00:00Z",
"data_scope": "all_available",
"description": {
"composition": "Извещения о закупках и заключённые контракты по 44-ФЗ и 223-ФЗ.",
"origin": "Единая информационная система в сфере закупок; опубликованные записи системы.",
"fields": "Наименование; ИНН; ОГРН; КПП; ОКПО; UID; источник; тип и предмет записи; даты; сумма; статус; предметные поля закупки.",
"example_dataset_key": "records",
"example_is_synthetic": true,
"example_record": {
"Наименование": "АО «Пример»",
"ИНН": "7700000000",
"ОГРН": "1027700000000",
"КПП": "770001001",
"ОКПО": "00000001",
"uid": "77777777-7777-4777-8777-777777777777",
"source_group": "government_procurements",
"source": "procurements_44fz",
"record_type": "procurement_44fz",
"external_id": "0173100000125000001",
"title": "Поставка промышленного оборудования",
"record_date": "2025-10-01",
"amount": "2450000.00",
"status": "published",
"url": "https://example.org/procurements/1",
"load_batch": 42,
"created_at": "2025-10-01T08:00:00Z",
"updated_at": "2026-10-20T08:00:00Z"
}
},
"datasets": [
{
"key": "records",
"title": "Государственные закупки по 44-ФЗ и 223-ФЗ",
"export_schema_version": "1",
"records_count": 3,
"parts_count": 1
}
],
"files": [
{
"part_id": "22222222-2222-4222-8222-222222222222",
"dataset_key": "records",
"title": "Государственные закупки по 44-ФЗ и 223-ФЗ",
"part_number": 1,
"parts_count": 1,
"records_count": 3,
"default_format": "xlsx",
"variants": [
{
"artifact_id": "33333333-3333-4333-8333-333333333333",
"format": "xlsx",
"file_name": "public-procurements-part-000001.xlsx",
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size_bytes": 8192,
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
{
"artifact_id": "44444444-4444-4444-8444-444444444444",
"format": "csv",
"file_name": "public-procurements-part-000001.csv",
"mime_type": "text/csv; charset=utf-8",
"size_bytes": 2560,
"sha256": "1123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
{
"artifact_id": "55555555-5555-4555-8555-555555555555",
"format": "json",
"file_name": "public-procurements-part-000001.json",
"mime_type": "application/json; charset=utf-8",
"size_bytes": 4096,
"sha256": "2123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
]
}
]
},
"errors": null,
"meta": {
"pagination": {
"page": 1,
"page_size": 50,
"total_count": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}
}
```
Catalog §7.3 и detail §7.4 описывают одно тестовое поколение. В реальных ответах
supported_formats и варианты одного generation также обязаны совпадать.
Все поля `SourceExportSourceDetail` из примера required. `generation_id`,
`current_generation_id`, `generated_at`, `data_as_of`, `unavailable_reason` nullable;
остальные не nullable.
При чтении сохранённого старого поколения `generation_id != current_generation_id` допустимо:
состояние и description/files описывают именно выбранный snapshot. Для запроса current без
поколения возвращаются metadata registry, `datasets=[]`, `files=[]` и состояние §13.
`SourceExportDescription`: три непустые строки для UI; `example_dataset_key: string|null`,
`example_is_synthetic: boolean`, `example_record: object|null`. Пример — одна JSON-запись
реальной export schema, не текст с многоточием. Максимум 32 КиБ UTF-8 и глубина 20;
использовать небольшой репрезентативный schema-valid пример, если реальная запись больше.
В этом случае `example_is_synthetic=true`. При отсутствии примера оба nullable поля null.
Пример нельзя получать чтением многогигабайтного JSON при каждом GET.
`SourceExportDataset`: все пять полей required, не nullable. `key` стабилен в группе,
`export_schema_version` меняется при изменении формы файла; счётчики относятся к dataset.
В первой реализации одна группа обычно имеет один dataset `records`, содержащий все её
подисточники. Дополнительный dataset разрешён только при наличии реального адаптера и
описанной бизнес-семантики; frontend не выводит его из имени файла.
`SourceExportPart`: все поля required, не nullable. UUID `part_id` уникален в generation,
`dataset_key` ссылается на datasets; `part_number` нумеруется с 1 внутри dataset,
`parts_count` — общее число его частей; `records_count` — число строк именно этой части.
`variants` непустой, format уникален; `default_format` присутствует в variants.
При одной части title не содержит «часть 1», при нескольких добавляется «— часть N из M».
Таким образом закупки с небольшим объёмом имеют одну плитку; большие закупки разбиваются
по реальному объёму. Число один из мока не является искусственным ограничением данных.
`SourceExportArtifact`: все шесть полей required, не nullable; `artifact_id` UUID,
`format` enum `xlsx|csv|json`, `file_name` безопасный basename, `mime_type` по §12.2,
`size_bytes` integer ≥ 1, `sha256` — 64 lowercase hex characters от готового файла.
part_id и artifact_id создаются при сборке; не вычисляются из индекса текущей страницы.
`SourceExportPagination`: все поля required, integer/boolean не nullable.
`total_count` — все логические части группы; `total_pages=max(1,ceil(total_count/page_size))`.
Для пустого источника page=1, total_count=0, total_pages=1, flags=false; page за пределами
диапазона → `400 source_export_invalid_page`. Порядок фиксирован по `(dataset_key,part_number)`.
Header download использует все datasets/parts выбранного поколения, а не только data.files
текущей страницы. Неизвестная группа → 404, удалённое ранее известное поколение → 409,
принадлежность поколения другой группе → 404. Ошибки и cache headers — §6/§15.
## 8. Dashboard парсеров
### 8.1 `GET /api/v1/parsers/dashboard/`
Request/response не меняются. Dashboard остаётся источником операционной статистики парсеров.
`registry_enrichment_analytics.source_coverage[].organizations_count` и
`population.active_registry_organizations` описывают количество организаций ОПК, а не файлов.
Значения `/sources[].organizations_count` также нельзя подменять export records_count.
Полный исторический экспорт закономерно может содержать больше записей, чем текущая
таблица или аналитика dashboard. Время data_as_of делает эту разницу объяснимой.
## 9. Записи источника
### 9.1 `GET /api/v2/organization-source-records/`
Request/response существующей таблицы не меняются. Экспорт строится из того же canonical
источника данных с теми же правилами доступа и публикации, но scope all_available включает
все сохранённые даты и все record types внутри группы. Не копировать page/page_size из UI
или фильтр текущего года из старого export builder.
Snapshot должен включать связанные финансовые строки всех сохранённых лет. Для групп
закупок, промышленности и ГОЗ проверять полноту каждого подисточника §3. Если какая-либо
зарегистрированная группа не поддержана сборщиком, вернуть unavailable и блокировать
приёмку этой группы; нельзя считать отсутствие adapter пустым набором.
### 9.2 `GET /api/v2/organization-source-records/{uid}/`
Request/response не меняются. Сохранённый UID в выгрузке относится к той же предметной записи.
Вложения интегрированных структур остаются отдельным существующим attachment-контрактом;
архив данной страницы содержит экспортные CSV/XLSX/JSON, а не все RTF/бинарные вложения.
Добавлять бинарные вложения в состав ZIP можно только отдельным расширением контракта.
### Snapshot и полнота
Публикуется согласованный snapshot данных каждой группы с `data_as_of`.
Допустимы существующий immutable published batch либо readonly repeatable-read snapshot
при потоковом создании spool. Простой cutoff updated_at без сохранения версий недостаточен:
изменившаяся после cutoff запись не должна потеряться или попасть частично.
При нескольких запросах/financial prefetch все читают один snapshot.
После spool дальнейшая сериализация не перечитывает изменяющиеся records.
Count вычисляется при перечислении входа и сверяется с суммой counts частей. При наличии
нескольких datasets основной `records` dataset определяет records_count группы;
производные datasets считаются отдельно и не увеличивают общий count исходных записей.
## 10. Refresh и фоновые задачи
### 10.1 `POST /api/v1/sources/{slug}/refresh/`
Request/response не меняются: это обновление исходных данных, не сборка выгрузки.
После успешной публикации source batch пометить snapshot соответствующей группы stale
и поставить idempotent/coalesced export build после commit транзакции. Для новой страницы
не запускать parser refresh из GET или кнопки скачивания.
### 10.2 `POST /api/v1/parsers/run/{source_key}/`
Request/response не меняются. Parser key, refresh key и task_ids остаются текущими.
Export builder не обращается к upstream и не имитирует новый parser source.
Существующий nightly task `organizations.tasks.refresh_source_record_export_artifacts`
и management command расширяются общими adapters с явным параметром scope. Legacy default
сохраняется, new scope `all_available` выпускает отдельные версии manifest/artifacts.
Плановая сверка — ежедневно в 05:30 Europe/Moscow, как у текущего nightly schedule.
Триггер после загрузки дополняет расписание; отсутствие первого поколения устраняется
первоначальной management command после деплоя. Перезапуск одного источника не блокирует
публикацию остальных; last_build ведётся отдельно по группе.
### 10.3 `GET /api/v1/jobs/{task_id}/`
Request/response не меняются. Если backend регистрирует export build в существующих jobs,
использовать отдельный task_name, не выдуманный parser source. Каталог содержит компактный
last_build; frontend не обязан опрашивать job для каждой карточки.
UI-статусы парсера «Выполняется»/«Обновлено» сохраняются по старому контракту;
export states не подменяют успешность парсинга.
### 10.4 `POST /api/v1/parsers/upload/{source_key}/` (условный)
Новый upload не требуется. Request/response действующих загрузок сохраняются.
Для интегрированных структур действует multipart `archive` (ZIP), для СМИ/санкций —
существующий `file`, а не устаревшие workbook/attachments из раннего документа.
Сборка export начинается после успешного опубликованного результата upload.
## 11. История обновлений
### 11.1 `GET /api/v1/system/logs/`
Request/response существующей истории парсеров не меняются. Создание download ticket
не создаёт фиктивную запись загрузки источника и не обновляет дату парсинга.
Export observability хранится в отдельном существующем audit/logger либо типизированном
расширении событий: actor, source_group, generation_id, selection_kind, format, count,
bytes sent, outcome, request_id; ticket и абсолютный storage path в лог не пишутся.
### 11.2 `GET /api/v1/system/logs/{id}/`
Request/response не меняются. Для ошибок сборки наружу выдаётся безопасный error_code,
подробная внутренняя диагностика доступна backend по request_id/build id.
Начало выдачи файла, полная передача байтов и оборванное соединение — разные события;
backend и frontend не утверждают, что браузер гарантированно сохранил файл на диск.
### 11.3 `GET /api/v1/system/logs/export/`
Request/response не меняются. Выгрузка истории обновлений и готовые файлы источников —
разные назначения; новый поток не использует log-export как file endpoint.
## 12. Выгрузка данных источника
Canonical flow новой страницы: metadata GET → authenticated POST export-ticket → native
form POST export-download. Backend формирует один физический файл либо ZIP из готовых
артефактов; браузер пишет ответ на диск. Не использовать client-side ExcelJS/JSZip из мока.
### 12.1 `POST /api/v2/organization-source-records/export-ticket/`
Request headers:
```http
POST /api/v2/organization-source-records/export-ticket/
Authorization: Bearer <admin-token>
Content-Type: application/json
```
Request schema — `oneOf` трёх **непересекающихся** вариантов. В каждом запрещены неизвестные
поля; обязательность и nullable перечислены ниже. Нельзя одновременно передать `sources`
и `selection_kind`, `part_id` в source_archive или только часть обязательных selector-полей.
**A. Одна часть — `SourceExportFileTicketRequest`:**
```json
{
"selection_kind": "file",
"source_group": "government_procurements",
"generation_id": "11111111-1111-4111-8111-111111111111",
"part_id": "22222222-2222-4222-8222-222222222222",
"format": "xlsx"
}
```
Все пять полей required, не nullable. `selection_kind` — singleton enum `file`,
группа и UUID проверяются как единый связанный набор, format выбирает готовый variant части.
Ответ содержит basename/mime/size именно этого artifact; файл не оборачивается в ZIP.
**B. Весь источник — `SourceExportArchiveTicketRequest`:**
```json
{
"selection_kind": "source_archive",
"source_group": "government_procurements",
"generation_id": "11111111-1111-4111-8111-111111111111",
"format": "xlsx"
}
```
Все четыре поля required, не nullable. В ZIP входят все datasets и все их части указанного
формата в указанном поколении. `part_id`, page/page_size и массив частичных files не допускаются.
При одном файле ZIP также остаётся ZIP: семантика кнопки заголовка не меняется.
Если запрошенного формата нет хотя бы у одной части, `409 source_export_format_unavailable`;
архив с неполным составом или молчаливой заменой формата запрещён.
**C. Старый запрос — `OrganizationSourceRecordExportRequest`:**
```json
{
"sources": ["government_procurements"],
"format": "xlsx"
}
```
Сохраняет прежние group enum, response shape, scope текущего календарного года, финансовый
JSON fallback и ошибки. Новая страница его не вызывает. Legacy default не должен внезапно
скачивать все годы; новый all_available manifest нельзя неявно подставить legacy-клиенту.
При расширении request serializer явное ветвление формата обязательно.
**Response новой страницы `201 application/json`, `SourceExportSelectionTicket`:**
```json
{
"ticket": "bV7k8nC0sD2fG4hJ6lP8qR0tU2wX4yZ6aB8cD0eF2gH",
"file_name": "public-procurements-part-000001.xlsx",
"expires_in": 300,
"selection_kind": "file",
"source_group": "government_procurements",
"generation_id": "11111111-1111-4111-8111-111111111111",
"format": "xlsx",
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size_bytes": 8192,
"parts_count": 1
}
```
Все десять полей required; только `size_bytes` nullable для streaming ZIP, остальные не nullable.
Для source_archive selection_kind меняется, MIME `application/zip`, `parts_count` — число
выбранных data artifacts; file_name вида `public-procurements-<generation_id>-xlsx.zip`.
При невозможности вычислить точный ZIP-size заранее возвращается null, а не сумма файлов
под видом точного Content-Length. Для file size_bytes точно совпадает с variant.
Имена короткие, ASCII basename, без путей; допускается UTF-8 display filename по §12.2.
Response legacy сохраняет прежние `ticket`, `file_name`, `expires_in` и не обязывает старый
frontend обрабатывать новые поля. OpenAPI описывает legacy/new response как named schemas.
Для response oneOf legacy schema должна иметь `additionalProperties: false`, как и новая:
ответ с selection_kind не должен одновременно удовлетворять обеим веткам. У legacy response
по-прежнему ровно три поля. Новая ветка содержит все десять полей примера.
### Проверки и содержимое ticket
Перед `201` выполнить admin RBAC, проверку всех selectors, поколения, complete manifest,
непустого набора, доступности выбранных файлов и их declared sizes. Не строить файлы,
не создавать ZIP на диске и не перечитывать всю БД ради выдачи ticket.
В серверном хранилище ticket сохранить:
- hash/token key, issuer_user_id, выданную роль, issued_at, expires_at;
- versioned request kind, source_group, scope `all_available`, pinned generation_id;
- selection_kind, выбранный format, part/artifact UUID и полный состав архива из manifest;
- ожидаемые basename/MIME/sizes/checksums, lease_id, file_name и audit/request id.
Ticket — случайный непрозрачный token не менее 256 бит энтропии; TTL 300 секунд.
Он даёт право на конкретное скачивание: обычная form не умеет передать Bearer из памяти SPA.
issuer_user_id позволяет повторно проверить активность и роль владельца, но **не доказывает**,
что предъявитель формы — тот же пользователь. Сам ticket является секретным capability:
не включать его в URL, history, referer, analytics, серверные логи или persistent frontend storage.
При выдаче взять generation lease и сохранить его вместе с ticket. Исчезновение поколения
между metadata и выдачей ticket → `409 source_export_generation_gone`; frontend перечитывает
каталог и явно повторяет действие пользователя. Нельзя заменить его новым поколением.
Ошибка ticket storage → `503 source_export_ticket_unavailable`, `Retry-After: 5`.
Ошибки выдачи: `400,401,403,404,409,429,503,500` по §15. Состояние building/not_ready —
бизнес-ошибка `409` с retryable=true; GET каталога при этом продолжает возвращать `200`.
Header `Cache-Control: private, no-store` обязателен для любого ticket response.
### 12.2 `POST /api/v2/organization-source-records/export-download/`
Request — обычная same-origin HTML form, `FormParser` принимает urlencoded body:
```http
POST /api/v2/organization-source-records/export-download/
Content-Type: application/x-www-form-urlencoded
ticket=bV7k8nC0sD2fG4hJ6lP8qR0tU2wX4yZ6aB8cD0eF2gH
```
Body schema `SourceRecordExportDownloadRequest`: единственное required поле ticket, string
непустое до 128 символов, whitespace не trim; malformed → 400. Параметры source/group/path,
format и selection из form не принимаются: они уже зафиксированы на сервере.
Endpoint может принимать запрос без Authorization header исключительно по валидному ticket.
Проверить issuer всё ещё активен/admin, generation доступно и lease действителен.
Семантика legacy tickets сохраняется отдельной веткой; новые tickets атомарно поглощаются
через Redis GETDEL/Lua либо transactional row lock. `get` → `delete` двумя действиями
недопустим: два параллельных POST не должны получить два успешных потока.
После успешного claim закрепить stream lease, открыть/проверить все selected artifacts,
и только затем посылать `200`. Ticket поглощается при принятии скачивания, а не после
прочтения последнего байта. Если клиент оборвал загрузку, frontend получает новый ticket
для той же части. TTL ticket ограничивает начало запроса, а не длительность активного потока.
**Response файла `200`:**
```http
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="public-procurements-part-000001.xlsx"
Content-Length: 8192
Cache-Control: private, no-store
Accept-Ranges: none
X-Content-Type-Options: nosniff
```
Тело — точные байты XLSX artifact, а не JSON/envelope/base64. CSV:
`text/csv; charset=utf-8`; JSON: `application/json; charset=utf-8`. При UTF-8 basename
передавать корректный RFC 5987 `filename*` плюс безопасный ASCII filename fallback.
Файл отправляется FileResponse/stream с ограниченным буфером; ETag при его использовании
равен checksum данного неизменяемого artifact, не текущей записи registry.
**Response архива `200`:**
```http
Content-Type: application/zip
Content-Disposition: attachment; filename="public-procurements-11111111-1111-4111-8111-111111111111-xlsx.zip"
Cache-Control: private, no-store
Accept-Ranges: none
X-Content-Type-Options: nosniff
```
Тело — streaming ZIP64 (`ZIP_STORED`, chunk около 1 МиБ), без промежуточного полного ZIP
и без ложного Content-Length. Записи ZIP идут по dataset_key/part_number, paths внутри
`<dataset_key>/<file_name>` безопасны и не пересекаются. Дополнительно `manifest.json`
содержит публичный состав, scope, snapshot, schemas, counts, sizes и sha256. `parts_count`
в ticket не включает manifest. Internal manifest с storage paths в архив не копируется.
Range/resume в этой версии не поддерживается: Range не приводит к `206`, выдаётся полный
`200` с `Accept-Ranges: none`. После обрыва скачивается заново только нужная часть по новому
ticket; UI не обещает возобновление потока. При добавлении resume потребуется отдельный
auth/range контракт, не повторное использование одноразового ticket.
Ошибки до отправки заголовков: `400,403,410,429,503,500`, JSON schema §6/§15.
После начала binary-потока JSON-ошибку в тело не дописывать: оборвать соединение, записать
download_failed и освободить lease. Браузер должен видеть неполную загрузку, а не валидный
на вид архив с отброшенными entries.
Frontend может сохранить текущий hidden iframe/form подход. Для native form он не может
надёжно прочитать HTTP-ошибку cross-document download и не знает момент сохранения на диск.
Основные ошибки выявляются до `201`; в UI допустимо только «Скачивание началось» и повторное
получение ticket. Backend обязан вернуть безопасную JSON-ошибку, а не HTML login/traceback.
### 12.3 `POST /api/v2/organization-source-records/export/`
Request/response старого synchronous API сохраняются: `{sources,format}` → streaming ZIP
из legacy scope. Новый selector `file|source_archive` здесь не поддерживается и даёт 400.
Новая страница всегда использует ticket-flow, даже если у маленького файла возможен Blob.
Удалять существующий endpoint или менять scope старого потребителя в рамках задачи нельзя.
### Форматы, разбиение и содержимое файлов
1. Разбивать канонический вход на логические части **до** формирования форматов. Для всех
variants одного part_id набор UID/строк и part_number одинаковы. Предел определяется
самым крупным поддерживаемым variant; XLSX может потребовать более раннего разбиения.
2. Цель — до 256 МиБ на файл; жёсткий предел — 512 МиБ. XLSX дополнительно ограничен
100 000 строками данных по умолчанию и никогда не превышает лимит листа Excel.
Это конфигурируемые backend limits, а не аргументы пользователя.
3. Перед публикацией проверить **фактический** размер каждого готового variant, включая
header/JSON framing/XLSX ZIP overhead. При превышении переподелить соответствующий part
для всех variants. Если одна неделимая запись превышает предел, сборка группы завершается
failed с code `source_export_record_too_large`; предыдущий snapshot сохраняется.
4. Порядок входа — стабильный `(source,record_type,uid)` с подходящими индексами/keyset scan.
Для financial lines сохранять стабильный `(year,form_code,line_code,id)` внутри записи.
Не применять OFFSET по многомиллионному набору, не делать полный RAM sort.
5. Каждая JSON-часть — самостоятельный UTF-8 JSON array; её можно разобрать без остальных
частей. Это не NDJSON и не разрезанный байтовый диапазон общего JSON. Nested JSON
сохраняется по текущему adapter/schema; смена сериализации требует export_schema_version.
6. CSV — UTF-8 BOM, разделитель запятая, quoting по текущему CSV adapter; каждый part имеет
одинаковый header для dataset. XLSX — валидный `.xlsx`, текстовые ИНН/ОГРН/ОКПО/КПП,
без потери ведущих нулей и decimal precision. Формулы из внешних строк не исполняются;
действуют общие правила защиты spreadsheet exports.
7. Поддержка форматов: сохранить фактический JSON-only adapter финансов, пока CSV/XLSX для
него отдельно не реализованы и не протестированы; остальные группы поставляются с
CSV/XLSX/JSON на основе существующих DTO/adapters. В новой странице отсутствует fallback.
Форматы публикуются только целиком для dataset, случайный пропуск одного variant — failed.
8. Названия файлов стабильны внутри generation: `<source-stem>-part-000001.<format>`;
UUID не заменяется вычислением frontend. Расширение всегда соответствует реальному MIME.
9. Источник без строк получает published empty manifest и `files=[]`, а не четыре пустых
файла. Counts групп/частей/физических variants хранятся раздельно. Один исходный record
с финансовыми lines считается одной записью, если adapter не объявляет отдельный dataset.
10. Существующую нормализацию/санитизацию экспортных данных сохранить. Новые секретные
provenance/storage fields не должны попасть ни в файлы, ни в JSON-пример.
## 13. Статусы и жизненный цикл
### Публикация и хранение
Новая область storage отделена от legacy annual files логически и физически, например
`SOURCE_RECORD_EXPORT_DIRECTORY/all-available/<source_group>/generations/<generation_id>/`.
Новые manifest имеют `version: 3`, `data_scope: all_available`, source_group, generation_id,
generated_at, data_as_of, datasets, parts, variants, реальные per-part counts, sizes и sha256.
UUID generation относится к **одной группе и одному scope**. Legacy `current.json` v2 не
перезаписывается manifest другой версии без migration/backward-compatible reader.
Общий registry указывает current_generation каждой группы; global catalog_revision меняется
атомарно при изменении опубликованного metadata. Нельзя сканировать все файлы и вычислять
sha256 на каждом GET: metadata индексируется в БД/manifest cache при публикации.
Порядок сборки: distributed lock на `(group,scope)` → consistent snapshot/spool → staging
`.building-*` → все части/форматы → checksums/count validation → immutable manifest → atomic
rename/current pointer switch. Ошибка оставляет предыдущий pointer и убирает staging.
Сборка одной группы не создаёт неполное общее поколение остальных источников.
Lock должен иметь owner token и продление; освобождение только compare-and-delete своим
владельцем. Текущий фиксированный lock TTL не должен позволить второму worker опубликовать
конкурирующее поколение после долгой сборки. Повторы после одного batch coalesce; при новых
данных во время build ставится следующий build, чтобы stale snapshot не считался актуальным.
Успешная генерация хранится не менее 24 часов, минимум два последних успешных поколения
каждой группы; current сохраняется всегда. Retention считает bytes/disk budget и проверяет
leases. Ticket lease действует TTL+60 секунд; active stream lease продлевается каждые
60 секунд с TTL 10 минут. Окончание/обрыв освобождает lease; crash освобождается по TTL.
Поколение с живым ticket/stream нельзя удалить при cleanup или deployment.
При claim ticket переводить lease в active stream атомарно относительно cleanup. Все
selected artifacts проверяются до HTTP 200. Storage missing/corrupt → 503, snapshot помечается
unavailable; checksum проверяется при публикации/фоновой проверке, не полным чтением перед
каждым download. Появление более нового current не влияет на уже выданный pinned ticket.
### Состояния API
| Ситуация | `state` | Snapshot / скачивание |
| ------------------------------------------ | ------------------- | ------------------------------------------------------ |
| Первая сборка ещё не запланирована | `not_ready` | generation=null, counts=null, files=[] |
| Первая сборка queued/running | `building` | generation=null, files=[] |
| Успешный snapshot, есть записи | `ready` | Все части/форматы доступны |
| Успешный snapshot, нет записей | `empty` | generation есть, counts=0, files=[] |
| Новая сборка идёт поверх старой | `ready` или `empty` | Старое поколение доступно; is_stale по данным/возрасту |
| Новая сборка упала, старое пригодно | `ready` или `empty` | Старое поколение доступно, last_build.failed |
| Нет пригодного snapshot, ошибка/отключение | `unavailable` | Скачивание блокируется, причина безопасна |
Для `unavailable` поле `unavailable_reason` summary/detail содержит enum
`disabled|adapter_missing|build_failed|storage_unavailable`, в остальных состояниях null.
Backend не смешивает отсутствие данных (`empty`)
с отсутствием adapter или ошибкой storage. `last_build.error_code` уточняет build failure.
Удалённый старый generation при metadata/ticket request → 409 generation_gone, повтор
current-запроса возвращает новое поколение. Валидный ticket обеспечивает lease; его snapshot
не может штатно исчезнуть. Если storage повреждён аварийно, download → 503, без нового файла
под старым именем. Новогодняя смена календаря не инвалидирует scope all_available.
## 14. Согласованность данных между endpoint
- source_group, source_slug и title определяются общим registry, а не копиями моков.
- Summary counts описывают current snapshot; pinned detail может описывать сохранённый
предыдущий snapshot. Frontend сравнивает generation_id, а не только название источника.
- Детальный список, ticket и bytes ответа относятся к одному generation и scope.
- Сумма part.records_count dataset равна dataset.records_count; source.records_count
равен count основного dataset. Нельзя умножать count на количество форматов.
- source.parts_count = сумма datasets.parts_count; meta.pagination.total_count равен
количеству всех логических частей группы, не размеру текущей страницы.
- Все variants части содержат те же записи; supported_formats соответствует полной матрице.
- Выбранный format, extension, MIME, Content-Disposition и bytes ответа совпадают.
- Header ZIP включает все части выбранного формата, а не первую страницу и не выбранные
форматы индивидуальных плиток. Независимый выбор формата плитки не меняет header selector.
- description.example_record соответствует export_schema_version; это пример файловой
проекции, а не обещание повторить временный mock DTO.
- generated_at/data_as_of не обновляются при скачивании, не заменяют parser last_updated_at.
- Старый annual экспорт и новый all_available имеют разные явно описанные scopes;
сравнивать их counts как будто это один набор запрещено.
## 15. Ошибки, доступ, производительность и ограничения
### Матрица доступа
| Действие | Anonymous | Обычный user | Активный admin |
| -------------------------- | ----------------------------------------- | ------------------------------------- | ------------------------------------- |
| Catalog/detail | 401 | 403 | 200 |
| Выдать ticket | 401 | 403 | 201 при доступном выборе |
| Download без ticket | 400 | 400 | 400 |
| Download с валидным ticket | Capability; повторная проверка issuer | Capability; повторная проверка issuer | Capability; повторная проверка issuer |
| Build/cleanup | Только internal worker/management command | Нет | Нет нового UI endpoint |
Download не доверяет роли из form/cookie; возможность выполнить запрос определяется
capability и актуальными правами issuer. Если issuer заблокирован или лишён admin,
вернуть 403 и поглотить ticket. Публичная раздача файла по `/media/...` без этих проверок
недопустима. Защитить также filesystem alias/nginx location, а не только DRF route.
### Ошибки новых запросов
Все строки используют `SourceExportError` §6, кроме стандартной auth schema 401.
GET возвращает обычный каталог состояний вместо ошибки, если проблема только в готовности группы.
| HTTP | `code` | Где / действие frontend |
| ---- | ------------------------------------ | ------------------------------------------------------------------------ |
| 400 | `source_export_invalid_request` | Неизвестный параметр/неполный selector; исправить запрос |
| 400 | `source_export_invalid_page` | Некорректная пагинация; первая страница того же поколения |
| 400 | `source_export_ticket_malformed` | Неверная форма ticket; получить новый |
| 403 | `source_export_forbidden` | Нет admin/issuer лишён прав/экспорт отключён; не повторять автоматически |
| 404 | `source_export_source_not_found` | Неизвестная группа |
| 404 | `source_export_part_not_found` | Часть/поколение не принадлежат выбранной группе |
| 409 | `source_export_generation_gone` | Устаревшее удалённое поколение; обновить каталог, повторить осознанно |
| 409 | `source_export_not_ready` | Первая сборка; retryable=true, Retry-After: 30 |
| 409 | `source_export_empty` | Нет файлов; отключить кнопку |
| 409 | `source_export_format_unavailable` | Формат не опубликован; использовать варианты metadata |
| 410 | `source_export_ticket_expired` | Ticket истёк/уже использован/не существует; выдать новый |
| 429 | `source_export_rate_limited` | Retry-After, не повторять циклически |
| 503 | `source_export_metadata_unavailable` | Registry/metadata storage недоступен; Retry-After: 30 |
| 503 | `source_export_ticket_unavailable` | Ticket cache недоступен; Retry-After: 5 |
| 503 | `source_export_artifact_unavailable` | Повреждён/недоступен готовый файл; Retry-After: 30 |
| 500 | `source_export_internal_error` | Безопасная ошибка с request_id |
`retryable=true` только для not_ready, rate_limited и временных 503. Все остальные false.
Файл не найден при аварии storage и устаревшее generation — разные ошибки. Смешанный selector
не должен уходить в legacy ветку. Имеющий правильную форму неизвестный UUID generation
возвращает 404; известное ранее опубликованное, но удалённое поколение — 409, metadata
tombstone сохраняется минимум 30 дней. Ответ не раскрывает существование чужих артефактов.
### Производительность и эксплуатация
- Catalog и страницы metadata не читают канонические records, binary artifacts или всю FS.
На горячем metadata cache p95 GET ≤ 1 секунды; выдача ticket ≤ 2 секунд без подготовки ZIP.
- Целевые limits: metadata page_size ≤ 200, example ≤ 32 КиБ; никакого binary/base64 в JSON.
- Стриминг не зависит по памяти от общего размера: чтение около 1 МиБ за раз; прибавка RSS
на активное скачивание ≤ 64 МиБ при испытании на архиве ≥ 5 ГиБ. ZIP64 обязателен.
- Минимальный load-test: два параллельных скачивания частей и один ZIP ≥ 5 ГиБ. Каталог
продолжает отвечать; лимиты worker/proxy и число соединений согласованы с инфраструктурой.
- Rate limits по умолчанию: GET metadata 120/min/user; ticket 30/min/user;
активных streams 3/user, 20/instance с общим shared limiter. Превышение → 429 до headers,
Retry-After: 10 для concurrency и до сброса окна для request rate. Все limits конфигурируемы.
- Браузер и backend за одним origin; если используются разные origins, отдельно настроить
CORS для metadata/ticket и form-action CSP. Базовая приёмка использует same-origin `/api`.
- Proxy buffering для binary выключен, auto gzip не меняет размеры/checksums, idle timeout
продлевается при передаче чанков. Не создавать временный гигабайтный proxy cache.
- Web и worker видят общий persistent volume/object storage с одинаковыми permissions.
Доступность volume, свободное место, длительность build, возраст snapshot, failed builds,
bytes sent/aborted streams и leases должны иметь metrics/alerts.
- Disk budget учитывает current, retained, staging и spool для all-history. При нехватке
места build завершается безопасно, current не удаляется и частичный manifest не публикуется.
- Не допускать path traversal/symlink escape, CRLF в filename и произвольных URL/file paths
в selectors. UUID проверяются через manifest/registry с allowlist group/scope.
## 16. Требования к OpenAPI и generated-клиенту
Canonical схема публикуется backend через `/openapi.json` (OpenAPI 3), существующий
командный адрес — `https://so1-admin.dev.nii-ecos.ru/openapi.json`. Legacy Swagger export
`/?format=openapi` не используется для frontend generation.
Обязательные stable operationId:
| Method/path | operationId |
| ---------------------------------------- | ---------------------------------------------------------- |
| GET `.../export-catalog/` | `v2_organization_source_records_export_catalog_list` |
| GET `.../export-catalog/{source_group}/` | `v2_organization_source_records_export_catalog_read` |
| POST `.../export-ticket/` | Сохранить `v2_organization_source_records_export_ticket` |
| POST `.../export-download/` | Сохранить `v2_organization_source_records_export_download` |
| POST `.../export/` | Сохранить `v2_organization_source_records_export` |
Использовать существующий Organizations tag без переименования generated tag-файлов.
Named components: SourceExportCatalogResponse, SourceExportSourceSummary,
SourceExportBuildSummary, SourceExportSourceDetailResponse, SourceExportSourceDetail,
SourceExportDescription, SourceExportDataset, SourceExportPart, SourceExportArtifact,
SourceExportPagination, SourceExportError, SourceExportFileTicketRequest,
SourceExportArchiveTicketRequest, SourceExportSelectionTicket, SourceRecordExportDownloadRequest.
Legacy request/ticket/error components сохранить.
Для каждого object указать required и nullable ровно по таблицам. Для UUID — format uuid,
дат — date-time; positive sizes/counts и enum описать constraints. `description.example_record`
разрешает JSON object с `additionalProperties` только как иллюстрацию разных файловых схем,
остальные metadata DTO не публиковать как нетипизированный object/unknown/void.
Содержимое файлов — binary; file downloads имеют три MIME, archives — application/zip.
У download error responses application/json, body `application/x-www-form-urlencoded`;
requestBody не должен ошибочно требовать JSON для обычной HTML-формы.
Request ticket — oneOf legacy/file/source_archive с singleton selection_kind и запретом
лишних полей; response — legacy/new named variants. Проверить, что Orval реально генерирует
пригодные union types и function signature; не оставлять discriminator только в prose.
### Подключение frontend после реализации backend
1. Обновить локальный `openapi.json` с canonical host и выполнить:
```bash
bun run apigen
bun run type-check
bun run contracts:check
bun run test:contract
```
2. Владелец новых GET и расширенных ticket/download контрактов — `pages/main`.
Зарегистрировать endpoints в `src/shared/api/contracts/owners.json` одновременно
с добавлением реальных `*.contract.spec.ts`; generated-файлы вручную не исправлять.
3. Заменить `SOURCE_DATA_EXPORT_MOCKS` запросом catalog. Существующие hidden source flags
применить к source_slug/source_group; отсутствие файлов не скрывает разрешённый источник.
4. При раскрытии карточки загружать detail с catalog generation_id. Обработать страницы
файлов; query key включает source_group/generation_id/page/page_size. Смена поколения
сбрасывает pages/part selection; не склеивать snapshots в один список.
5. Поля UI: id ← source_group/part_id, title ← backend title, composition/origin/fields ←
description, JSON ← example_record, форматы плитки ← variants, header ← supported_formats.
Индивидуальный выбор не должен изменять общий selector. Недоступные форматы не показывать.
6. Убрать `records` из runtime view model файла: они не загружаются в браузер. Удалить
mock download через ExcelJS/JSZip; отдельная часть и ZIP используют POST ticket + form.
Иконка/название файла обновляются по фактическому variant, не предположению по индексу.
7. Добавить состояния not_ready/building/empty/unavailable/stale и disabled controls.
После 409 generation_gone заново запросить catalog/detail. Не стартовать новый download
автоматически после замены snapshot без понятного действия пользователя.
8. Перенести готовые backend fixtures в mock E2E, покрыть pagination, JSON-only finance,
one-file закупки, разные selectors и live contract download. Только после приёмки удалить
временные mock data; структуру карточек и общие стили сохранять.
Генерация API не выполняется из выдуманных frontend DTO: backend сначала публикует schema
и проходит свои тесты. Обновлять live клиент или включать неподтверждённые API в рамках
подготовки этого задания не требуется.
## 17. Backend-тесты и acceptance criteria
### Минимальная матрица backend/contract tests
| ID | Проверка | Ожидаемый результат |
| --------- | -------------------------------------------------------- | ------------------------------------------------------------------------- |
| `EXP-T01` | Registry всех групп §3 | 22 записи без дублей; исходные slug/group не переименованы |
| `EXP-T02` | Права metadata и ticket | Anonymous 401, user 403, admin success |
| `EXP-T03` | Нет первой генерации | Catalog 200 с not_ready/building, ticket 409 |
| `EXP-T04` | Пустой источник | empty, counts=0, files=[], ticket 409 empty |
| `EXP-T05` | Обе ветки закупок | В файлах присутствуют 44-ФЗ и 223-ФЗ, в малой fixture одна плитка |
| `EXP-T06` | Подисточники промышленности/ГОЗ/вакансий | Нет потерянного adapter или record type |
| `EXP-T07` | Годы и финансовые lines | Записи минимум двух лет входят в all_available; legacy scope не изменился |
| `EXP-T08` | JSON-only finance | Catalog/parts показывают JSON; запрос XLSX новой формы → 409 |
| `EXP-T09` | Пагинация > 50 частей | Нет пропусков/дублей, counts и meta.pagination точны |
| `EXP-T10` | Неверные page/page_size/UUID/extra params | Документированный 400/404, нет 500 |
| `EXP-T11` | Изменение current между страницами | Pinned generation сохраняет тот же состав |
| `EXP-T12` | Разбиение CSV/JSON/XLSX | Каждый файл ≤ limit, JSON отдельно парсится, CSV имеет header |
| `EXP-T13` | Матрица вариантов части | Одинаковые UID/counts across formats, уникальные artifact UUID |
| `EXP-T14` | Counts | Per-part count точен, сумма не умножается на число форматов |
| `EXP-T15` | Single file selector | Exact MIME/name/Content-Length/sha256, без ZIP-обёртки |
| `EXP-T16` | Header selector при > 1 странице | ZIP содержит все части/manifest и только выбранный format |
| `EXP-T17` | Обновление current после выдачи ticket | Скачиваются bytes указанного старого generation |
| `EXP-T18` | Два одновременных POST одного ticket | Ровно один 200, второй 410 |
| `EXP-T19` | Expired/malformed/used ticket | 410/400/410, без выдачи файла |
| `EXP-T20` | Issuer заблокирован/лишён admin | 403, ticket больше не используется |
| `EXP-T21` | Cleanup при ticket/active stream | Generation не удаляется; после lease допускается retention |
| `EXP-T22` | Оборванная передача | Lease освобождён, audit failed; новый ticket позволяет повтор части |
| `EXP-T23` | Missing/corrupt file | До headers 503; нет неполного успешного ZIP |
| `EXP-T24` | Ошибка build, ENOSPC, lock timeout | Current сохранён, last_build.failed, другие группы доступны |
| `EXP-T25` | Пустые исторические identifiers / decimal / leading zero | Существующие данные не пропадают и не искажаются |
| `EXP-T26` | Extra selectors, чужие UUID, paths, symlinks | Ошибка до чтения произвольного файла |
| `EXP-T27` | Native browser form с Bearer SPA | Download работает без Bearer header, ticket не попадает в URL |
| `EXP-T28` | ZIP ≥ 5 ГиБ / несколько streams | ZIP64, bounded RSS, metadata доступно, rate limits работают |
| `EXP-T29` | Legacy regression | Старый sources/format ticket/download/export и годовой scope работают |
| `EXP-T30` | OpenAPI / generated code | JSON examples schema-valid; DTO не void; apigen/type-check успешны |
Большие fixtures генерируются потоково тестовым инструментом; нельзя объявлять load-test
пройденным только по маленькому архиву или моковому Content-Length. Внутренние unit tests
проверяют builders и locks, integration — реальные manifests/tickets/storage, E2E — браузер.
### Backend acceptance criteria
- [ ] Все 22 группы зарегистрированы; 16 групп новой страницы имеют рабочие adapters и
корректные ready/empty snapshots на тестовом опубликованном наборе. Отключённые остальные
группы явно описаны unavailable, их включение не требует нового frontend кода.
- [ ] GET catalog/detail, все metadata DTO и состояния работают по §7.
- [ ] Для scope all_available нет скрытого ограничения текущим годом или текущей страницей.
- [ ] JSON/CSV/XLSX делятся на ограниченные по размеру части без потерь/дублирования записей.
- [ ] Финансовые форматы и реальные datasets соответствуют capabilities, нет фиктивных плиток.
- [ ] Single-file и source-archive selector работают через authenticated ticket + native form.
- [ ] Download стабильно привязан к generation, одноразовое потребление ticket атомарно.
- [ ] Retention/cleanup учитывают tickets, active streams, staging и disk budget.
- [ ] Права issuer проверяются, прямые публичные ссылки на файлы отсутствуют.
- [ ] Большие файлы не буферизуются целиком ни на backend, ни в proxy, ни в JS frontend.
- [ ] MIME, filename, counts, schema versions и checksums проверены тестами.
- [ ] Старые экспортные endpoints и прежний annual scope проходят regression suite.
- [ ] Canonical OpenAPI опубликован, request/response examples валидируются по schemas.
- [ ] `bun run apigen`, `bun run type-check`, `bun run test:contract` проходят после подключения
frontend к реализованному стенду; временные DTO не патчатся вместо исправления schema.
- [ ] Переданы фактические curl/form примеры, fixture минимум двух лет, generation id,
результаты backend tests/load-test и deployment инструкция с первым запуском сборки.
## 18. Чего backend не должен возвращать
- Содержимое гигабайтных файлов внутри catalog/detail, base64 или массив всех records.
- Фиктивные XLSX/CSV при реальном JSON, неописанные derived datasets и копии файлов ради UI.
- Display-размеры «1,5 ГБ», локализованные даты и CSS/HTML вместо структурированных metadata.
- Абсолютные/относительные storage paths, raw internal manifest, credentials или stack traces.
- Постоянные публичные URLs на source artifacts; capability ticket в query string.
- Другое поколение под ранее выбранным generation_id или другой формат под тем же выбором.
- Архив из только первой страницы частей либо частично доступных artifacts с HTTP 200.
- Count всего источника в поле records_count одной части или сумму одинаковых записей по форматам.
- Ошибку парсера, замаскированную под empty export, или успешность сборки на основании одних mocks.
- UI-only route names/tableKey как новые идентификаторы источника.
## 19. Решения и открытые вопросы
### Зафиксированные решения для реализации
| ID | Решение |
| --------- | --------------------------------------------------------------------------------------- |
| `EXP-D01` | Расширяется существующая export subsystem, новые предметные источники не создаются |
| `EXP-D02` | Новая страница экспортирует all_available, старый annual API сохраняет scope |
| `EXP-D03` | Первые 16 групп обязательны; общий registry заранее поддерживает все 22 |
| `EXP-D04` | Финансы исходно JSON-only; UI получает фактические capabilities |
| `EXP-D05` | Кнопка части скачивает файл; кнопка заголовка — ZIP всех частей выбранного формата |
| `EXP-D06` | Один dataset `records` по умолчанию; несколько плиток возникают из реального разбиения |
| `EXP-D07` | Администраторский доступ, same-origin ticket/form flow, 300 секунд на начало скачивания |
| `EXP-D08` | Pinned immutable generations, атомарные tickets, leases для cleanup |
| `EXP-D09` | Лимит файла 512 МиБ, цель 256 МиБ; пагинация metadata 50/200 |
| `EXP-D10` | Range/resume не обещается; после обрыва повторяется отдельная часть |
Открытых продуктовых решений, которые нужно угадывать при реализации, в этом задании нет.
До приёмки backend обязан предоставить фактические сведения по стенду:
| Проверка | Ответственный | Срок | Критерий закрытия |
| -------------------------------------------------------------- | ------------------------ | ---------------------- | --------------------------------------------------------------------- |
| Актуальная backend-ветка и наличие всех source models/adapters | Backend | До разработки adapters | Сверка с §2–3, зарегистрированные группы не потеряны |
| Объём all-history и capacity persistent storage | Backend + инфраструктура | До первого full build | Измеренный размер/время, запас под spool/staging/retention |
| Read isolation и индексы для стабильного полного прохода | Backend + DBA | До нагрузочной приёмки | Snapshot без пропусков, нет неограниченного RAM/disk sort |
| Shared volume/cache/proxy configuration | Backend + инфраструктура | До выкладки | Worker и web видят те же files/tickets, native stream не буферизуется |
Эти проверки не разрешают уменьшить scope до одного года, выкинуть группы или изменить
публичный контракт без обновления задания. `ready` ставится только после §17 и закрытия
блокирующих результатов проверок; schema/runtime/tests должны совпадать.