feat: partition all source exports by year and enable nightly builds
This commit is contained in:
@@ -10,6 +10,11 @@ observed_at: '2026-10-21'
|
||||
|
||||
# Backend API страницы «Выгрузка данных из источников»
|
||||
|
||||
> Уточнение 2026-10-22: внутри каждого источника требуются отдельные годовые файлы.
|
||||
> Правила partitioning, API v2 и включённого nightly schedule описаны в
|
||||
> [актуальном дополнении](source-export-year-partitions.md); они имеют приоритет
|
||||
> над прежними правилами datasets/parts ниже.
|
||||
|
||||
Назначение: самодостаточное задание backend-разработчику для подключения страницы
|
||||
`/admin/source-data-export`. Страница уже реализована на моках: каталог источников,
|
||||
раскрываемое описание и JSON-пример, отдельные части файлов, выбор формата у каждой части
|
||||
|
||||
@@ -4,7 +4,8 @@
|
||||
опубликованные записи канонического хранилища всех 22 групп, включая финансовые строки
|
||||
прошлых лет. Legacy годовой API, `--all-years` и их storage не изменены.
|
||||
Фронтенд в эту реализацию не входит.
|
||||
Фактические результаты локальных проверок: [QA report](source-export-catalog-verification.md).
|
||||
Актуальные правила годовых файлов: [year partitions](source-export-year-partitions.md).
|
||||
Фактические результаты локальных проверок: [QA report](source-export-year-partitions-verification.md).
|
||||
|
||||
## Подготовка контура
|
||||
|
||||
@@ -21,12 +22,13 @@
|
||||
синтетических данных не заменяют эту проверку. При необходимости сначала собрать одну группу.
|
||||
4. Запустить сборку. Проверить `last_build`, counts, размеры, контрольные суммы, загрузку
|
||||
одного файла и ZIP через тот же origin `/api`, который использует браузер.
|
||||
5. После проверки включить зарегистрированную миграцией **отключённую по умолчанию** задачу
|
||||
Beat `organizations:source-export-catalog:nightly-msk` (06:30 Europe/Moscow, после annual).
|
||||
5. Миграция `0021` включает Beat задачу `organizations:source-export-catalog:nightly-msk`
|
||||
на 06:30 Europe/Moscow. До применения подготовить shared storage и capacity.
|
||||
`SOURCE_EXPORT_AUTOBUILD=true` дополнительно включает enqueue после публикации snapshot.
|
||||
При изменении данных во время сборки Celery повторяет сборку после завершения текущей.
|
||||
Без Beat использовать command в штатном таймере контура.
|
||||
|
||||
|
||||
```sh
|
||||
python src/manage.py build_source_export_catalog --source-group government_procurements
|
||||
python src/manage.py build_source_export_catalog
|
||||
@@ -37,7 +39,7 @@ python src/manage.py build_source_export_catalog --cleanup-only
|
||||
Команда продолжает остальные группы при ошибке одной и завершается ненулевым кодом,
|
||||
если хотя бы одна группа не обработана. Новый current публикуется транзакционно только
|
||||
после готовых checksums/manifest и atomic rename. Ошибка сохраняет старый current.
|
||||
Сборка сортирует канонический snapshot по `(source,record_type,uid)` на локальном диске
|
||||
Сборка сортирует канонический snapshot по `(year,source,record_type,uid)` на локальном диске
|
||||
SQLite с индексом вместо неограниченного RAM sort/PostgreSQL sort; financial lines
|
||||
упорядочены `(year,form_code,line_code,id)`. Финансы JSON-only; CSV/XLSX fallback в новом API нет.
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Проверка каталога all_available — 2026-10-22
|
||||
# Проверка первоначального каталога all_available — 2026-10-22
|
||||
|
||||
Это исторический отчёт для коммита `63872e8`. Последующее разбиение по годам
|
||||
описано в [дополнении](source-export-year-partitions.md).
|
||||
|
||||
Реализация backend в `dev`; frontend, реальные базы и серверы контуров не изменялись.
|
||||
[Операционная инструкция](source-export-catalog-operations.md),
|
||||
|
||||
43
docs/source-export-year-partitions-verification.md
Normal file
43
docs/source-export-year-partitions-verification.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Проверка годовых файлов источников — 2026-10-22
|
||||
|
||||
[Правила и контракт](source-export-year-partitions.md). Изменения только в backend `dev`;
|
||||
frontend и серверы контуров не изменялись. Первоначальный отчёт `63872e8` сохранён отдельно.
|
||||
|
||||
| Проверка | Фактический результат |
|
||||
| --- | --- |
|
||||
| Полный backend pytest с transport load | 2086 passed, 48 skipped, 13 warnings |
|
||||
| Итоговый каталог + конкурентный download/leases на PostgreSQL 15.19 | 42 passed |
|
||||
| Full migration graph на PostgreSQL | PASS |
|
||||
| 0021 forward/reverse/forward, enabled recurring schedule и Beat change counter | PASS |
|
||||
| Migration drift / Django check / Ruff / Black / diff check | PASS |
|
||||
| OpenAPI build + freshness, Orval apigen + TypeScript | PASS |
|
||||
| Generated Zod: новые actual API responses | 5 passed |
|
||||
| Generated Zod: прежние runtime responses | 48 passed |
|
||||
|
||||
Полный прогон предшествовал окончательному scheduler notification guard; после него
|
||||
итоговый каталог/миграция повторно проверены отдельным PostgreSQL прогоном. Skipped не PASS:
|
||||
в основном SQLite-прогоне PostgreSQL-specific проверки пропускаются и выполняются отдельно.
|
||||
|
||||
Проверены:
|
||||
|
||||
- Все 22 источника: через ночной task entrypoint с синтетическими данными 2020/2021 годов
|
||||
подготовлены 22 независимых поколения с обоими годами. Clock-trigger на реальном стенде
|
||||
этой проверкой не подтверждается.
|
||||
- В одном файле не смешиваются годы. Parts нумеруются внутри года; ZIP содержит папки годов.
|
||||
- Разбиение oversized variant сохраняет тот же год и те же UID во всех CSV/XLSX/JSON.
|
||||
- Финансовый UID с показателями двух лет присутствует в двух годовых проекциях, каждая
|
||||
содержит только свои financial lines. Unique и projected counts не смешиваются.
|
||||
- Пустая дата: год created_at в TIME_ZONE сервиса, независимо от активной timezone.
|
||||
Нераспознаваемые даты/невалидный финансовый год не теряются и попадают в undated.
|
||||
- JSON-only финансы, записи без financial lines, пустые источники, пагинация 51 части,
|
||||
pinned tickets/старые manifest v3, ошибки хранилища, cleanup/leases и legacy annual API.
|
||||
- Миграция включает recurring 06:30 Europe/Moscow, очищает one_off, expires/start_time
|
||||
и частные args/kwargs; явно обновляет Beat change counter историческими migration models.
|
||||
|
||||
Локальный transport test реально обработал 5905582210 bytes ZIP64, два
|
||||
параллельных file reader по 536870912 bytes; peak RSS growth
|
||||
11436032 bytes. Это synthetic transport/metadata, не HTTP proxy/browser
|
||||
и не замер full-history объёма на dev. Ограничения эксплуатации в общей инструкции сохраняются.
|
||||
|
||||
Временный PostgreSQL был изолированным локальным контейнером на loopback. Реальные миграции,
|
||||
Beat, worker, private volume и первая сборка на dev-сервере требуют выкладки этой версии.
|
||||
84
docs/source-export-year-partitions.md
Normal file
84
docs/source-export-year-partitions.md
Normal 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).
|
||||
Reference in New Issue
Block a user