Files
mostovik-backend/docs/source-export-year-partitions.md
2026-10-22 21:45:29 +02:00

85 lines
6.5 KiB
Markdown
Raw 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). Фронтенд не изменяется.
Ночная задача `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).