13 KiB
Каталог all_available: эксплуатация и проверка
Контракт: исходное задание. Новая область включает все
опубликованные записи канонического хранилища всех 22 групп, включая финансовые строки
прошлых лет. Legacy годовой API, --all-years и их storage не изменены.
Фронтенд в эту реализацию не входит.
Актуальные правила годовых файлов: year partitions.
Фактические результаты локальных проверок: QA report.
Подготовка контура
- Применить миграции
python src/manage.py migrate --noinput. 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 overrideSOURCE_EXPORT_HOST_DIRECTORY): worker пишет, web читает через:ro. Bootstrap/cleanup команды в таком режиме выполнять в worker, не в web.- До полного запуска измерить объём канонических данных, свободное место и запас для минимум двух поколений каждой группы, spools/staging и параллельных сборок. Тесты на синтетических данных не заменяют эту проверку. При необходимости сначала собрать одну группу.
- Запустить сборку. Проверить
last_build, counts, размеры, контрольные суммы, загрузку одного файла и ZIP через тот же origin/api, который использует браузер. - Миграция
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 в штатном таймере контура.
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):
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 пока не подключена.
Локальные контрактные и нагрузочные проверки
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:
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.
Сборка дополнительно сохраняет готовые ZIP каждого формата до 99 000 000 байт.
При расчёте диска учитывать и исходные CSV/XLSX/JSON части, и ZIP_STORED-копии их содержимого,
а также staging и retained generations. Все файлы остаются в приватном generation directory.
--verify-only проверяет размеры и SHA-256 как частей, так и ZIP. Cleanup удаляет их
вместе с поколением, защищённым действующими leases. Ночная задача и расписание не меняются.