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
150 lines
12 KiB
Markdown
150 lines
12 KiB
Markdown
# Каталог 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.
|