feat: partition all source exports by year and enable nightly builds

This commit is contained in:
Aleksandr Meshchryakov
2026-10-22 21:45:29 +02:00
parent 63872e86fe
commit 2002e80196
13 changed files with 672 additions and 87 deletions

View File

@@ -0,0 +1,84 @@
# Выгрузка каждого источника отдельными файлами по годам
Уточнение пользователя от 2026-10-22 заменяет правило единого набора за все годы
в исходном [задании](source-data-export-api-spec.md). Фронтенд не изменяется.
Ночная задача `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 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).