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

148 lines
13 KiB
Markdown
Raw Permalink 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.
# Выгрузка каждого источника отдельными файлами по годам
Уточнение пользователя от 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.
Годы добавляются в архив последовательно. Если **все части года выбранного формата**
помещаются в отдельный 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`:
```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
`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 закупок содержит:
```text
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 прежние — теперь они автоматически готовят годовые части:
```sh
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. [Общая эксплуатация](source-export-catalog-operations.md).
Результаты проверок: [годовой QA report](source-export-year-partitions-verification.md).