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

111 KiB
Raw Permalink Blame History

template_id, template_version, source_id, source_name, document_status, change_scope, observed_at
template_id template_version source_id source_name document_status change_scope observed_at
source-backend-api 1 shared-source-data-export Выгрузка готовых файлов существующих источников review extension 2026-10-21

Backend API страницы «Выгрузка данных из источников»

Уточнение 2026-10-22: внутри каждого источника требуются отдельные годовые файлы. Правила partitioning, API v2 и включённого nightly schedule описаны в актуальном дополнении; они имеют приоритет над прежними правилами 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:

{
  "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:

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 с одним источником:

{
  "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:

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, полный пример одной части с тремя готовыми форматами:

{
  "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:

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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:

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:

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 и выполнить:

    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 должны совпадать.