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