Files
mostovik-backend/docs/source-export-catalog-operations.md
Aleksandr Meshchryakov d6d1c8112a
All checks were successful
Mostovik Backend CI/CD / Tests and lint (push) Successful in 2m48s
Mostovik Backend CI/CD / Build linux/amd64 release images (push) Successful in 2m51s
Mostovik Backend CI/CD / Deploy and verify internal main (push) Has been skipped
Mostovik Backend CI/CD / Deploy dev (push) Successful in 2m21s
fix: keep fitting export years together and name ZIP year ranges
2026-11-03 14:48:13 +01:00

171 lines
14 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; для v5 ограничивается также ZIP cap 99 000 000 bytes |
| `SOURCE_EXPORT_MAX_FILE_BYTES` | 512 MiB; для v5 каждый файл должен помещаться в ZIP 99 000 000 bytes с manifest |
| `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.
## Окно лет и готовые ZIP (manifest v5)
После migrate `0023_source_export_settings` в Django admin доступна singleton-настройка
«Глубина выгрузки, лет» (по умолчанию 5). Применяется при следующей сборке, без рестарта.
Подробный контракт и исключение старых/будущих/неопределимых годов:
[source-export-year-partitions.md](source-export-year-partitions.md).
Сборка дополнительно сохраняет готовые ZIP каждого формата до 99 000 000 байт.
При расчёте диска учитывать и исходные CSV/XLSX/JSON части, и ZIP_STORED-копии их содержимого,
а также staging и retained generations. Все файлы остаются в приватном generation directory.
`--verify-only` проверяет размеры и SHA-256 как частей, так и ZIP. Cleanup удаляет их
вместе с поколением, защищённым действующими leases. Ночная задача и расписание не меняются.
Уточнение упаковки: год, который целиком помещается в ZIP выбранного формата,
не разделяется между архивами даже при нескольких исходных частях. При нехватке
остатка он целиком уходит в следующий ZIP; только большой год >99 МБ делится.
Имена ZIP включают диапазон лет. После обновления builder прежний packing помечается
stale; штатная пересборка публикует новое immutable поколение, сохраняя старые tickets.