feat: configure export year window and publish ZIP archives under 99 MB
All checks were successful
Mostovik Backend CI/CD / Tests and lint (push) Successful in 4m1s
Mostovik Backend CI/CD / Build linux/amd64 release images (push) Successful in 4m9s
Mostovik Backend CI/CD / Deploy and verify internal main (push) Has been skipped
Mostovik Backend CI/CD / Deploy dev (push) Successful in 3m5s

This commit is contained in:
Aleksandr Meshchryakov
2026-11-03 10:02:04 +01:00
parent a7bf5412e9
commit f0a0266495
12 changed files with 1018 additions and 55 deletions

View File

@@ -52,8 +52,8 @@ Django settings (при необходимости задать в настро
| Setting | Default |
| --- | --- |
| `SOURCE_EXPORT_TARGET_FILE_BYTES` | 256 MiB |
| `SOURCE_EXPORT_MAX_FILE_BYTES` | 512 MiB |
| `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 |
@@ -147,3 +147,17 @@ SOURCE_EXPORT_TRANSPORT_LOAD=1 SOURCE_EXPORT_TRANSPORT_REPORT=/tmp/source-export
У 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. Ночная задача и расписание не меняются.

View File

@@ -0,0 +1,47 @@
# Окно лет и ZIP до 99 МБ: проверка 2026-11-03
Локальная реализация в backend `dev`. Фронт, dev-сервер и ночные задания на сервере
не изменялись; push/выкладка и первая сборка реальных данных в этот этап не входят.
## Проверки
- Основной backend-набор `PYTHONPATH=src uv run pytest -q --tb=short`:
**2102 passed, 49 skipped**, exit 0. После него добавлены ещё две проверки каталога
и параметризация PostgreSQL race-теста; окончательная целевая проверка ниже включает их.
- Окончательный каталог: **54 passed**, exit 0.
- Изолированный PostgreSQL 15 с настоящими миграциями, каталог + snapshot contract +
concurrent tickets: **74 passed**, exit 0. В том числе схема/seed `0023`, repeatable-read,
публикация при ingestion и два конкурентных native POST одного ticket — для обычного
файла и для нового готового ZIP. Тестовый контейнер удалён после прогона.
- Canonical OpenAPI build и `--check`, Orval generation, TypeScript `type-check` — exit 0.
Generated Zod: **5 реальных API-ответов** без потери полей, включая новый archives detail
и ticket готового ZIP.
- Ruff, format check, Django system check, `makemigrations --check --dry-run` и
`git diff --check` — exit 0.
Полный набор включает пропуски opt-in transport load и PostgreSQL-only тестов на SQLite;
они не считаются PASS. PostgreSQL-only проверки выполнены отдельно. Длительная нагрузка
через публичный proxy и browser/UI в этом этапе не запускались.
## Проверенные сценарии
- Окно 2021–2026, изменение глубины из БД, смена календарного года, created_at fallback,
исключение старых/будущих/неопределимых лет без удаления исходных записей.
- Финансовые проекции содержат только свой год; unique source count отличается от
количества включённых годовых проекций.
- Самостоятельный ZIP **ровно 99 000 000 байт** с реальными заголовками и manifest;
превышение на один байт отклоняется. Использован локальный sparse synthetic fixture.
- Несколько архивов, несколько лет в одном архиве, большой год, согласованные варианты
CSV/XLSX/JSON, CRC/SHA-256 и отсутствие потерь/дубликатов.
- Несколько уровней рекурсивного разбиения с разными временными spool paths: исправлена
коллизия имён `.left`/`.right` при повторном делении.
- Слишком большая одиночная запись: понятная ошибка, прежний current сохраняется,
staging удаляется. Изменение настройки во время render не меняет captured policy.
- archive_id обязателен для v5; неизвестный ID и несовпадающий формат отклоняются.
Tickets закреплены за поколением; v3/v4 и прежняя streaming ZIP схема доступны.
- Verify обнаруживает повреждение готового ZIP; retention/leases и ночной dispatch всех
22 источников продолжают работать по существующим правилам.
Эксплуатация и контракт: [годовые выгрузки](source-export-year-partitions.md),
[операции](source-export-catalog-operations.md). Готовые ZIP_STORED дополнительно занимают
место рядом с исходными частями; это нужно учитывать перед будущей серверной сборкой.

View File

@@ -3,6 +3,48 @@
Уточнение пользователя от 2026-10-22 заменяет правило единого набора за все годы
в исходном [задании](source-data-export-api-spec.md). Фронтенд не изменяется.
## Изменение схемы от 2026-11-03
Для новых поколений manifest v5 действует окно годов и несколько самостоятельных ZIP.
В админке **Организации → Настройки выгрузки источников** поле «Глубина выгрузки, лет»
по умолчанию равно 5. Включаются годы от текущего минус глубина до текущего включительно
(2021–2026 в 2026 году); 0 означает только текущий год. Текущий год определяется в TIME_ZONE
сервиса. Старые, будущие и неопределимые годы исключаются из выгрузки, исходные записи
не удаляются. Пустая дата сохраняет прежний fallback на год created_at. У финансов
отбираются проекции и строки показателей внутри этого окна; records_count считает
уникальные включённые исходные записи, exported_records_count — их годовые проекции.
Настройка читается один раз при начале сборки источника. Параметры фиксируются в
`export_policy`: years_back, min_year, max_year, archive_max_bytes. Изменение настройки
или календарного года помечает существующее поколение stale до следующей сборки.
Каждый ZIP одного формата содержит папки годов и manifest.json и не превышает
**99 000 000 байт** вместе со служебными данными ZIP. ZIP_STORED, самостоятельные архивы,
не многотомный ZIP. Большой год делится по границам записей; один архив может включать
несколько лет. Файлы частей согласованы по записям между форматами. Финансы — JSON-only.
Размер архива проверяется перед атомарной публикацией. Слишком большая одиночная запись
даёт `source_export_record_too_large`, прежнее current поколение сохраняется.
Detail API дополнен `export_policy` (null для прежних поколений) и `archives` (пустой
список для прежних поколений). Каждый элемент содержит archive_id, artifact_id,
archive_number/archives_count (внутри формата), format, years, file_name, mime_type,
size_bytes, sha256 и part_ids. Список архивов полный, независимо от страницы files.
Для manifest v5 selector `source_archive` требует `archive_id`:
```json
{"selection_kind":"source_archive","source_group":"government_procurements","generation_id":"<UUID>","archive_id":"<UUID>","format":"json"}
```
Отсутствие archive_id — 400, неизвестный ID — 404, неверный формат — 409. Ticket выдаёт
точный размер и имя готового ZIP; download стримит его с Content-Length. Выданный ticket
закрепляет поколение и архив; leases/retention сохраняются. Старые manifest v3/v4 и их
архивные tickets используют прежний streaming ZIP без archive_id. Отдельные file tickets
работают по прежнему selector. Public schema_version остаётся 2 с добавленными полями.
Фронт в этой задаче не меняется; клиенту для новых архивов нужен выбор archive_id.
Далее описана исходная схема v4; правила полноты всех лет и одного ZIP относятся
к прежним поколениям. Определение года, годовые проекции и структура папок сохранены.
Ночная задача `organizations.tasks.refresh_source_export_catalog` обрабатывает весь
registry из 22 источников и все доступные годы их канонических опубликованных данных.
Миграция `0021_enable_yearly_partitioned_exports` включает recurring Beat schedule