--- 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 страницы «Выгрузка данных из источников» Назначение: самодостаточное задание 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 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 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 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--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 внутри `/` безопасны и не пересекаются. Дополнительно `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: `-part-000001.`; 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//generations//`. Новые 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 должны совпадать.