Files
mostovik-backend/docs/source-export-year-partitions.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

13 KiB
Raw Permalink Blame History

Выгрузка каждого источника отдельными файлами по годам

Уточнение пользователя от 2026-10-22 заменяет правило единого набора за все годы в исходном задании. Фронтенд не изменяется.

Изменение схемы от 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. Годы добавляются в архив последовательно. Если все части года выбранного формата помещаются в отдельный ZIP до 99 МБ, этот год сохраняется целиком: при нехватке места в текущем ZIP он полностью переносится в следующий. Только год, который сам превышает лимит, разрешено распределять между архивами по готовым частям. Правило считается отдельно для CSV/XLSX/JSON; набор записей соответствующих частей не меняется. Например, пять годов по 20 МБ: первый ZIP содержит 2021–2024 (~80 МБ), следующий — 2025; ZIP не дополняется фиктивными байтами до лимита.

Имя ZIP показывает реальный диапазон: public-procurements-2021-2024-json-archive-000001.zip; один год — public-procurements-2025-json-archive-000002.zip. Номер сохраняет уникальность при нескольких архивах одного большого года. Поле archives.years содержит точный список лет, включая пропуски внутри диапазона. Новые manifest v5 помечены внутренним archive_packing: "whole_year"; прежние поколения доступны, но stale до пересборки. Публичные selectors и структура API не меняются.

Размер архива проверяется перед атомарной публикацией. Слишком большая одиночная запись даёт 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:

{"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 organizations:source-export-catalog:nightly-msk: ежедневно 06:30 Europe/Moscow. Она также сбрасывает one_off и частные args/kwargs, чтобы задача запускала весь registry. Источники, явно отключённые конфигурацией SOURCE_EXPORT_DISABLED_GROUPS, сохраняют свой статус disabled; по умолчанию отключённых нет. Источник без данных публикует empty manifest, а не фиктивные файлы. Регистрация расписания в коде не доказывает его запуск на сервере: для этого нужны выкладка, migrate, общий private volume, работающие worker и Beat.

Определение года и полнота

  • Для обычной записи год — первая самостоятельная последовательность из четырёх цифр в record_date (1..9999). Поддерживаются, например, 2024-12-31 и 31.12.2024.
  • Если record_date пустая, используется год created_at в TIME_ZONE сервиса.
  • Непустая дата без распознаваемого года сохраняется в undated, metadata year: null. Она не получает вымышленный год и не пропадает из выгрузки.
  • У финансов год определяется каждой строкой financial_lines.year. В годовую проекцию исходной записи входят только финансовые строки этого года. Один исходный UID может законно присутствовать в нескольких годах. Финансовая запись без строк сохраняется по общему правилу даты; неподдерживаемые значения года финансовых строк попадают в undated.
  • Нет ограничения текущим годом. Полный snapshot источника читается один раз; сортировка на диске — (year partition, source, record_type, uid). Все годы публикуются атомарно одним неизменяемым generation источника. Ошибка любого года сохраняет прежний current.

Файлы и API

Например, ZIP закупок содержит:

2024/public-procurements-2024-part-000001.xlsx
2024/public-procurements-2024-part-000002.xlsx
2025/public-procurements-2025-part-000001.xlsx
undated/public-procurements-undated-part-000001.xlsx
manifest.json

Один ZIP источника включает все годы и все части выбранного формата, независимо от страницы metadata. Отдельная кнопка файла сохраняет только одну выбранную годовую часть. Финансы остаются JSON-only. Лимиты размера, одинаковые записи во всех variants части, checksums, защищённые tickets, retention и leases сохраняются.

Public catalog schema_version: "2", внутренний manifest version: 4. data_scope по-прежнему all_available — охватывает все доступные годы.

Поле Семантика
summary/detail partitioning year; для сохранённых прежних generation — none
dataset key records_2024, records_2025, records_undated
dataset/part year Числовой год; null у undated и прежних generation без разбиения
dataset export_schema_version "2", годовая файловая проекция
part part_number, parts_count Нумерация и количество частей внутри года/dataset
source records_count Уникальные исходные записи источника
source exported_records_count Сумма годовых проекций; может быть больше unique count финансов
dataset/part records_count Только записи этого dataset/этой части; не сумма variants

Порядок страниц (dataset_key, part_number), форматы и части каждого года согласованы. Description example ссылается на фактический годовой dataset. Недатированные записи имеют отдельный dataset и находятся в конце списка. Пустые годы не создаются искусственно.

Сохранённые manifest v3, их metadata и выданные tickets остаются читаемыми; bytes старого поколения не заменяются годовой выгрузкой. У старых parts/datasets API возвращает year=null. Legacy synchronous annual export и его задачи/storage не изменены.

Свежесть и повтор Celery-сборки учитывают версию данных конкретной группы: обновление вакансий не пересобирает неизменившиеся госзакупки или арбитраж. Изменение самой группы во время snapshot/render требует повторной сборки; массовая нормализация без указания группы инвалидирует все группы. Старые поколения с глобальной версией остаются доступными и помечаются stale до новой сборки.

Проверка и запуск

Команда и Celery entrypoint прежние — теперь они автоматически готовят годовые части:

python src/manage.py migrate --noinput
python src/manage.py build_source_export_catalog
python src/manage.py build_source_export_catalog --verify-only

В dev Compose команды сборки/cleanup выполнять в worker: web имеет read-only mount private artifacts. Общая эксплуатация.

Результаты проверок: годовой QA report.