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
148 lines
13 KiB
Markdown
148 lines
13 KiB
Markdown
# Выгрузка каждого источника отдельными файлами по годам
|
||
|
||
Уточнение пользователя от 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).
|