feat: add versioned all-available source export catalog

This commit is contained in:
Aleksandr Meshchryakov
2026-10-22 21:30:18 +02:00
parent 1ffdcd0aaf
commit 63872e86fe
28 changed files with 5754 additions and 240 deletions

View File

@@ -1,5 +1,8 @@
# Выгрузка за все годы
Новый каталог `all_available` описан отдельно: [контракт и эксплуатация](source-export-catalog-operations.md). Эта страница сохраняет описание прежнего scope.
Годовая задача `organizations.tasks.refresh_source_record_export_artifacts` сохраняет прежнее поведение.
Новая задача `organizations.tasks.refresh_all_years_source_record_export_artifacts` собирает все доступные записи каждого поддерживаемого источника без ограничения по году, включая все финансовые строки. Для источников с заменяемыми snapshot выгружается текущее опубликованное состояние: удалённые прежние snapshot не восстанавливаются.

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,144 @@
# Каталог all_available: эксплуатация и проверка
Контракт: [исходное задание](source-data-export-api-spec.md). Новая область включает все
опубликованные записи канонического хранилища всех 22 групп, включая финансовые строки
прошлых лет. Legacy годовой API, `--all-years` и их storage не изменены.
Фронтенд в эту реализацию не входит.
Фактические результаты локальных проверок: [QA report](source-export-catalog-verification.md).
## Подготовка контура
1. Применить миграции `python src/manage.py migrate --noinput`.
2. `SOURCE_EXPORT_DIRECTORY` должен указывать на **приватный persistent volume**, одинаково
смонтированный в web/worker. Он не должен быть внутри `MEDIA_ROOT` и не должен иметь
публичный nginx/static alias. Default — `PROJECT_ROOT/private-source-exports`; для
контейнеров его обязательно заменить общим persistent mount до первой сборки.
В `docker-compose.dev.yml` уже предусмотрен общий `./data/source-exports`
(host override `SOURCE_EXPORT_HOST_DIRECTORY`): worker пишет, web читает через `:ro`.
Bootstrap/cleanup команды в таком режиме выполнять в worker, не в web.
3. До полного запуска измерить объём канонических данных, свободное место и запас для
минимум двух поколений каждой группы, spools/staging и параллельных сборок. Тесты на
синтетических данных не заменяют эту проверку. При необходимости сначала собрать одну группу.
4. Запустить сборку. Проверить `last_build`, counts, размеры, контрольные суммы, загрузку
одного файла и ZIP через тот же origin `/api`, который использует браузер.
5. После проверки включить зарегистрированную миграцией **отключённую по умолчанию** задачу
Beat `organizations:source-export-catalog:nightly-msk` (06:30 Europe/Moscow, после annual).
`SOURCE_EXPORT_AUTOBUILD=true` дополнительно включает enqueue после публикации snapshot.
При изменении данных во время сборки Celery повторяет сборку после завершения текущей.
Без Beat использовать command в штатном таймере контура.
```sh
python src/manage.py build_source_export_catalog --source-group government_procurements
python src/manage.py build_source_export_catalog
python src/manage.py build_source_export_catalog --verify-only
python src/manage.py build_source_export_catalog --cleanup-only
```
Команда продолжает остальные группы при ошибке одной и завершается ненулевым кодом,
если хотя бы одна группа не обработана. Новый current публикуется транзакционно только
после готовых checksums/manifest и atomic rename. Ошибка сохраняет старый current.
Сборка сортирует канонический snapshot по `(source,record_type,uid)` на локальном диске
SQLite с индексом вместо неограниченного RAM sort/PostgreSQL sort; financial lines
упорядочены `(year,form_code,line_code,id)`. Финансы JSON-only; CSV/XLSX fallback в новом API нет.
## Лимиты
Django settings (при необходимости задать в настройках контура):
| Setting | Default |
| --- | --- |
| `SOURCE_EXPORT_TARGET_FILE_BYTES` | 256 MiB |
| `SOURCE_EXPORT_MAX_FILE_BYTES` | 512 MiB |
| `SOURCE_EXPORT_ROWS_PER_PART` | 100000 |
| `SOURCE_RECORD_EXPORT_XLSX_ROWS_PER_FILE` | 100000, совместимый верхний предел |
| `SOURCE_EXPORT_MIN_FREE_BYTES` | 1 GiB, резерв проверяется между batch/render |
| `SOURCE_EXPORT_DISK_BUDGET_BYTES` | 0 (нет дополнительной квоты; filesystem capacity + reserve) |
| `SOURCE_EXPORT_GENERATIONS_TO_KEEP` | 2, минимум 2 и минимум 24 часа |
| `SOURCE_EXPORT_METADATA_RATE` | 120/min/user |
| `SOURCE_EXPORT_TICKET_RATE` | 30/min/user |
| `SOURCE_EXPORT_MAX_STREAMS_PER_USER` | 3 |
| `SOURCE_EXPORT_MAX_STREAMS` | 20, общий shared limiter |
`SOURCE_EXPORT_DISABLED_GROUPS` — env, группы через запятую; они остаются в каталоге
как unavailable/disabled. Настройки лимитов не являются query/body параметрами API.
Данные по всем форматам одной части одинаковы; при превышении фактического byte limit
делятся все варианты. Запись, которая сама превышает лимит, приводит к failed build.
Метаданные, tickets, locks и leases — общая БД PostgreSQL. Tokens — capability с 256 битами
энтропии; новый внутренний namespace `se1_` отделён от legacy. В БД хранится только digest,
issuer, selectors и срок. Ticket TTL 300 секунд, lease 360; stream lease 10 минут с
обновлением раз в 30 секунд (в том числе во время блокировки socket write). Claim и admission
атомарны относительно cleanup. В SQLite unit tests renewal thread отключён; проверку
распределённых locks/leases следует выполнять на PostgreSQL.
## Native download
Пример selector (UUID брать из GET detail):
```http
POST /api/v2/organization-source-records/export-ticket/
Authorization: Bearer <admin-token>
Content-Type: application/json
{"selection_kind":"file","source_group":"government_procurements","generation_id":"<generation-uuid>","part_id":"<part-uuid>","format":"json"}
```
Для всего источника использовать `selection_kind: source_archive`, без `part_id`.
Полученный `ticket` передать только в body HTML form POST `export-download/`.
Не помещать capability в URL/analytics/logs. Native download не требует Bearer;
перед выдачей байтов сервер повторно проверяет active/admin issuer. Новое поколение
не меняет уже выданный ticket. ZIP включает `records/<file_name>` всех частей нужного
формата и публичный `manifest.json`. ZIP64, ZIP_STORED, без полного ZIP spool/Blob.
Binary route: `proxy_buffering off`, `proxy_request_buffering off`, `gzip off` и достаточный
read/send timeout. Ответ включает `X-Accel-Buffering: no`, `Accept-Ranges: none`, nosniff,
private/no-store. Настроить FD limit под количество частей, так как выбранные файлы открываются
до HTTP 200. HTML error page/login redirect вместо JSON ошибки недопустимы.
## Контроль
Регулярный `--verify-only` проверяет размеры и sha256 и помечает повреждённые поколения
storage_unavailable. GET и download не перечитывают гигабайты ради checksum. Перед download
проверяются размеры/типы/безопасные пути всех выбранных файлов. При повреждении нужен новый
успешный build, а не замена байтов существующего generation.
Метрики/алерты контура следует привязать к structured log событиям
`source_export_build_success`, `source_export_build_failed`,
`source_export_download_complete`, `source_export_download_failed`, а также shared-volume
free bytes, возрасту `SourceExportGeneration`, `SourceExportState.last_build` и живым
`SourceExportLease`. Audit не содержит capability. Следить за возрастом >36h,
failed builds, ENOSPC, длительностью build, bytes sent/aborts, количеством streams.
До приёмки контура отдельно необходимы реальный all-history build/capacity, PostgreSQL
конкурентные запросы, native browser через proxy и нагрузочное испытание: два файла параллельно
и ZIP >=5 GiB, p95 каталога <=1s, RSS прирост <=64 MiB/stream. Успешный unit test или generated
client не подтверждает состояние живого стенда. Страница frontend пока не подключена.
## Локальные контрактные и нагрузочные проверки
```sh
SOURCE_EXPORT_RUNTIME_FIXTURES=/tmp/source-export-runtime.json PYTHONPATH=src uv run pytest tests/apps/organizations/test_source_export_catalog.py
cd tools/openapi
bun build.mjs --check
bun run apigen
bun run type-check
bun check-source-export-runtime.mjs /tmp/source-export-runtime.json
```
Для отдельного транспортного прогона из корня backend:
```sh
SOURCE_EXPORT_TRANSPORT_LOAD=1 SOURCE_EXPORT_TRANSPORT_REPORT=/tmp/source-export-transport.json PYTHONPATH=src uv run pytest tests/apps/organizations/test_source_export_transport.py
```
Тест действительно читает 5.5 GiB и формирует ZIP64 потоком, одновременно читает два
файла по 512 MiB и запрашивает каталог. Источник — sparse synthetic binary, выходной ZIP
не накапливается в RAM или на диске. Это проверка транспорта и ORM metadata, без HTTP proxy,
браузера и реальных предметных файлов. Она не подменяет нагрузочную приёмку контура.
`test_source_export_postgres.py` проверяет два одновременных native POST одного ticket;
его запуск требует отдельного PostgreSQL test settings и в SQLite явно пропускается.
У Orval/Zod для export-ticket включён strict mode: иначе legacy вариант union с тремя
полями способен принять новый ответ и silently strip selection fields. Generated файлы
не патчатся. Canonical timestamps публикуются в UTC с `Z`, поддерживаемым generated validator.

View File

@@ -0,0 +1,62 @@
# Проверка каталога all_available — 2026-10-22
Реализация backend в `dev`; frontend, реальные базы и серверы контуров не изменялись.
[Операционная инструкция](source-export-catalog-operations.md),
[исходное задание](source-data-export-api-spec.md).
## Выполненные проверки
| Проверка | Фактический результат |
| --- | --- |
| Полный pytest backend с opt-in transport load | 2078 passed, 47 skipped, 13 warnings |
| После финальных guards: новый + legacy экспорт на SQLite | 59 passed |
| Новый каталог и конкурентный native POST на PostgreSQL 15.19 | 35 passed |
| Полный migration graph на изолированном PostgreSQL | PASS; новые 5 таблиц, schedule disabled |
| Migration drift `makemigrations --check --dry-run` | Нет изменений |
| Canonical OpenAPI generation и `build.mjs --check` | PASS |
| Orval apigen и TypeScript type-check, включая union ticket selectors | PASS |
| Generated Zod — новые фактические ответы API | 5 passed без потери полей |
| Generated Zod — прежние runtime fixtures | 48 passed |
| Ruff / Black затронутых Python-файлов, Django check | PASS |
| Compose dev `config --quiet`, `git diff --check` | PASS |
Полный прогон предшествовал двум финальным guard tests; затем они и весь новый каталог
повторно проверены targeted SQLite/PostgreSQL прогонами. Skipped не считаются PASS.
PostgreSQL integration tests пропускаются в основном SQLite-прогоне и выполнены отдельно.
Первый PostgreSQL прогон выявил закрытие outer TestCase transaction тестовым helper при
ручном `response.close()`; helper исправлен по стандартному test-client signal handling,
повторный прогон прошёл. Production connection handling этим исправлением не менялся.
На PostgreSQL два одновременно отправленных form POST одного ticket дали ровно 200/410.
Отдельный тест реальным SQL и независимым connection проверил продление stream lease и
обнаружение его потери. Только timer этого теста ускорен; DB checks не подменяются mocks.
PostgreSQL запускался в отдельном временном локальном контейнере, привязанном к loopback.
## Синтетический snapshot
- source_group: `government_procurements`
- generation_id: `8c4f4096-14c9-4256-9dcb-0e209b7b493e`
- records: 3; fixture содержит 2024, 2025, 2026 годы
- части: 2; варианты XLSX/CSV/JSON одной части содержат одинаковые UID
- registry/adapters: все 22 группы и все зарегистрированные подисточники
- финансовые строки: fixture 2022 и 2023, JSON-only без fallback
- pagination/ZIP: отдельный тест с 51 частью проверяет обе страницы и весь архив
Данные синтетические; capability tokens в этот отчёт не включены.
## Локальный transport load
Фактически обработаны 5905582210 bytes ZIP64 (5.5 GiB плюс framing),
одновременно два file reader по 536870912 bytes.
Рост peak RSS всего тестового процесса: 13631488 bytes.
Catalog samples: 57; p95 0.000748 seconds.
Источник — sparse synthetic binary, полный ZIP не сохраняется на диск или в RAM.
Это не измерение сети, браузера, proxy или предметного full-history build.
## Осталось для приёмки контура
Реальный all-history объём/время и capacity; persistent volume на контуре;
через-origin native browser flow и proxy buffering/timeouts; реальные HTTP p95/RSS,
alerts/log ingestion и включение nightly/autobuild после проверки capacity.
Новые runtime migrations, build и deployment на dev-сервере этим локальным прогоном
не выполнялись. Фронт не подключался; его файлы не изменялись.

View File

@@ -1,5 +1,8 @@
# Матрица файловых выгрузок источников
Новый каталог `all_available` описан отдельно: [контракт и эксплуатация](source-export-catalog-operations.md). Эта страница сохраняет описание прежнего scope.
## Пользовательский контракт
Frontend отправляет администраторский