Files
mostovik-backend/docs/source-export-catalog-operations.md
Aleksandr Meshchryakov f64bd5f664
Some checks failed
Mostovik Backend CI/CD / Build linux/amd64 release images (push) Has been cancelled
Mostovik Backend CI/CD / Deploy dev (push) Has been cancelled
Mostovik Backend CI/CD / Deploy and verify internal main (push) Has been cancelled
Mostovik Backend CI/CD / Tests and lint (push) Has been cancelled
fix: scope export freshness and retries to each source group
2026-10-22 22:36:43 +02:00

150 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Каталог all_available: эксплуатация и проверка
Контракт: [исходное задание](source-data-export-api-spec.md). Новая область включает все
опубликованные записи канонического хранилища всех 22 групп, включая финансовые строки
прошлых лет. Legacy годовой API, `--all-years` и их storage не изменены.
Фронтенд в эту реализацию не входит.
Актуальные правила годовых файлов: [year partitions](source-export-year-partitions.md).
Фактические результаты локальных проверок: [QA report](source-export-year-partitions-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. Миграция `0021` включает Beat задачу `organizations:source-export-catalog:nightly-msk`
на 06:30 Europe/Moscow. До применения подготовить shared storage и capacity.
`SOURCE_EXPORT_AUTOBUILD=true` дополнительно включает enqueue после публикации snapshot.
При изменении данных **собираемой группы** во время сборки Celery повторяет её после
завершения текущей. Ingestion другой группы не запускает повтор и не помечает готовый
экспорт stale. Общие агрегаты сохраняют прежнюю глобальную cache version; массовые
операции без указанной группы консервативно инвалидируют все экспорты.
Без 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 по `(year,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.