18 KiB
ФССП Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Публиковать один полный источник ИП из двух открытых выгрузок в контракте Глеба. Architecture: Небольшие модули разделяют чтение CSV и оркестрацию двух артефактов. Нормализованные SourceRecordInput проходят существующий staging; manifest является артефактом объединённой публикации. Tech Stack: Python, Django 3.2, DRF, Celery, requests, Decimal, pytest; существующие зависимости. Spec: Согласованная спецификация.
Global Constraints
- Только
mostovik-backend, веткаdev; frontend остаётся без изменений. - Не изменять StateCorp, root deployment, submodule pointers и пользовательские
.env. - Только канонические организации; точные идентификаторы, ведущие нули, стабильные UUID.
- Использовать существующие artifacts/staging/publish/jobs/export; не писать legacy records.
- Расписания disabled до полной dev-приёмки. Не выполнять main/customer deploy.
- Секреты и платные запросы не входят в fixtures, логи и обычные тесты.
- Команды ниже выполняются из
/Users/avm/projects/Work/ecos/mostovik-backend. - Сначала перечитать текущий Git diff; сохранять несвязанные изменения. Миграции генерировать штатно и проверять зависимости на текущем HEAD.
Review Focus
- Оборванный второй файл: прежний общий snapshot и last_success сохраняются (Task 3).
- Кавычки/переносы и переставленные заголовки: CSV читается корректно; неизвестная структура отклоняется (Task 2).
- Дубликаты ИП с разными наблюдениями: детерминированная разрешённая политика либо отказ; никаких случайных перезаписей (Task 3).
- Отрицательный/нулевой долг и будущая дата: сохраняются без исправления (Tasks 2, 4).
- Неоднозначный ИНН/организация вне реестра: quarantine/skip, без создания организации (Task 3).
File map
Create:
src/apps/parsers/fssp_csv.py: заголовки, потоковый CSV, нормализация полей.src/apps/parsers/fssp_snapshot.py: discovery, download, два входа, manifest, staging/publication.src/organizations/fssp_payload_serializers.py: типизированный контракт Глеба.tests/apps/parsers/test_fssp_csv.py,test_fssp_snapshot.py,test_fssp_refresh.py.tests/apps/organizations/test_fssp_contract.py.tests/fixtures/fssp/: обезличенные малые CSV и паспорта/mapping.docs/sources/fssp.md: каналы, headers, ограничения и результаты фактической приёмки.
Modify:
src/apps/parsers/models.py,src/organizations/models.py,src/organizations/source_groups.py: enums и EnforcementProceedingExtension.src/apps/parsers/source_registry.py,source_cards.py,tasks_registry_snapshots.py,views.py,serializers.py: refresh/run/cards/job.src/organizations/serializers.py,source_record_query.py,source_record_export.py: payload/filter/order/export.src/settings/base.py: серверные публичные каналы/лимиты, без чтения секрета.tools/openapi/source-record-extensions.jsonи штатно генерируемые backend OpenAPI outputs.- Штатно создаваемые миграции в
src/organizations/migrations/,src/apps/parsers/migrations/; имена фиксирует makemigrations на текущем HEAD.
Task 1: Подтвердить два канала и зафиксировать mapping
Files: Create docs/sources/fssp.md, tests/fixtures/fssp/.
Interfaces: produces документированную таблицу «исходный header → payload», отдельную для каждого паспорта; downstream читает только эти fixtures.
- Прочитать свежий документ ECOS и дополнение Глеба, затем официальные паспорта обоих наборов. Зафиксировать URL паспорта, exact dataset ID, актуальную дату, URL файла, разрешённые HTTPS hosts, кодировку, delimiter, все headers, семантику статуса и пересечения наборов.
- Скачать публичные inputs потоково с проверкой redirects; записать checksum/размер отдельно от малых обезличенных fixtures. Ограничение на файл выбрать по текущему официальному размеру с запасом и записать конкретное значение; размер Глеба 1 954 126 197 байт не считать подтверждением обоих каналов.
- Получить fixtures: нормальная строка, quoted multiline, zero/negative debt, amount due отдельно, отсутствующие даты, дубль, unknown header, truncated stream. Не сохранять реальный полный реестр в Git.
- Gate: оба паспорта и mapping подтверждены. Если один недоступен — отметить точную причину; продолжать локальный контракт, но не включать refresh/расписание и не объявлять реальный сбор готовым. Не придумывать статус ended из имени файла.
git add docs/sources/fssp.md tests/fixtures/fssp; commitdocs: verify FSSP datasets and mappings.
Task 2: Потоковое чтение и денежная семантика
Files:
- Create:
src/apps/parsers/fssp_csv.py - Test:
tests/apps/parsers/test_fssp_csv.py - Fixtures:
tests/fixtures/fssp/
Interfaces:
-
Produces:
iter_fssp_records(handle: TextIO, *, dataset: str) -> Iterator[SourceRecordInput]. -
dataset— один из двух verified IDs Task 1;external_idоснован на ИНН/номере ИП; org пока разрешает Task 3. -
Unknown headers/повреждённая CSV →
SnapshotValidationError; читается csv.reader, не материализованный список. -
Добавить регрессию:
def test_signed_debt_and_multiline_preserved():
with fixture_csv("signed_multiline.csv") as handle:
row = next(iter_fssp_records(handle, dataset=verified_dataset_id))
assert row.amount == Decimal("-12.50")
assert row.payload["debt_amount"] == "-12.50"
assert row.payload["claim_amount"] == "250.00"
assert row.payload["origin_kind"] == "open_data_csv"
assert row.payload["queried_inn"] is None
# fixture_csv и verified_dataset_id определить в этом test module по Task 1.
# Дополнительные tests: reordered_headers, unknown_headers, zero_not_null,
# quoted_newline, missing_date, future_document_date, raw_17_columns.
def test_unknown_headers_rejected():
with fixture_csv("unknown_headers.csv") as handle:
with pytest.raises(SnapshotValidationError):
next(iter_fssp_records(handle, dataset=verified_dataset_id))
def test_future_document_date_is_preserved():
with fixture_csv("future_date.csv") as handle:
row = next(iter_fssp_records(handle, dataset=verified_dataset_id))
assert row.payload["document_date"] == "2099-01-01"
assert "future_document_date" in row.payload["parse_warnings"]
- Запустить
PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_fssp_csv.py -q. До реализации ожидается FAIL: отсутствует iter_fssp_records. - Реализовать указанную сигнатуру; сохранить все 17 raw значений, остальные обязательные поля и warnings из текущего frontend контракта. Record date = initiated_on, amount = debt_amount. Суммы Decimal, не float; будущая дата только warning. Конфигурация reader и mapping определены Task 1.
- Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов.
- Проверить scoped diff и выполнить
git commit -m 'feat: normalize streaming FSSP CSV records', добавляя только перечисленные файлы этого task.
Task 3: Два входа и атомарная публикация
Files:
- Create:
src/apps/parsers/fssp_snapshot.py - Modify:
src/apps/parsers/models.py,src/organizations/models.py,src/organizations/source_groups.py,src/settings/base.py - Create: штатные model migrations
- Test:
tests/apps/parsers/test_fssp_snapshot.py
Interfaces:
-
Consumes: Task 2 iterator;
OwnOrganizationIndex.resolve(*, inn, ogrn, kpp="", okpo=""),stable_registry_uid(source, external_id),stage_records(rows),publish_snapshot(artifact, *, on_publish=None, ...). -
Produces:
refresh_fssp_enforcement_proceedings(*, load_batch: int, uploaded_by_id: int | None = None, on_publish: Callable[[ParserSourceArtifact, SnapshotResult], None] | None = None, on_progress: Callable[[int, int, int, int], None] | None = None) -> tuple[ParserSourceArtifact, SnapshotResult]. -
Source/group/type:
fssp_enforcement_proceedings/enforcement_proceedings/enforcement_proceeding. -
Возвращаемый artifact — aggregate manifest, metadata содержит два input artifact IDs, checksums, даты и counters.
-
Добавить регрессию:
def test_second_input_failure_preserves_snapshot():
before = list(OrganizationSourceRecord.objects.values_list("uid", "payload"))
with mock_second_download_failure():
with pytest.raises(SnapshotValidationError):
refresh_fssp_enforcement_proceedings(load_batch=2)
assert list(OrganizationSourceRecord.objects.values_list("uid", "payload")) == before
# Создать canonical org + прошлую запись в setup, network patches в этом module.
# Дополнительные tests: repeat_uuid_stable, two_inputs_manifest,
# duplicate_conflict_rejected, ambiguous_inn_quarantined, foreign_inn_skipped,
# no_new_organizations_or_legacy_writes, staging_chunks_at_most_500,
# failed_download_rejected, published_empty_distinct_from_failed.
def test_conflicting_duplicate_blocks_publication():
before = published_fssp_rows()
with conflicting_input_fixtures():
with pytest.raises(SnapshotValidationError):
refresh_fssp_enforcement_proceedings(load_batch=2)
assert published_fssp_rows() == before
def test_noncanonical_rows_do_not_create_organizations():
before = Organization.objects.count()
artifact, result = refresh_with_foreign_and_ambiguous_inn()
assert Organization.objects.count() == before
assert result.skipped == 1
assert result.quarantined == 1
# Helpers здесь patch actual two downloads; conflict fixture не имеет
# разрешённого паспортом правила приоритета.
- Запустить
PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_fssp_snapshot.py -q. До реализации ожидается FAIL: нет refresh/extension/enum. - Загрузить оба inputs на диск через registry_http/save_artifact_file; проверять EOF/заявленную длину, schema и duplicate identity до publish. Stage только применимые/diagnostic rows batches <= SNAPSHOT_CHUNK_SIZE=500; дедупликацию большого набора выполнить в staging/БД, без полного dict всех строк. Добавить EnforcementProceedingExtension по существующему паттерну. Применить документированное правило конфликта Task 1; если паспорт не разрешает конфликт, reject aggregate. Финализатор вызвать внутри существующей транзакции publication.
- Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов.
- Проверить scoped diff и выполнить
git commit -m 'feat: publish complete FSSP snapshots atomically', добавляя только перечисленные файлы этого task.
Task 4: Публичный контракт, запуск и экспорт
Files:
- Create:
src/organizations/fssp_payload_serializers.py - Modify: все integration files File map,
tools/openapi/source-record-extensions.json - Test:
tests/apps/parsers/test_fssp_refresh.py,tests/apps/organizations/test_fssp_contract.py - Extend:
tests/apps/parsers/test_refresh_concurrency.py,tests/apps/organizations/test_openapi_runtime_fixtures.py
Interfaces:
-
Consumes: refresh Task 3, existing
_run_snapshot(task, *, source, refresh, requested_by_id, track_progress=False, mode=None) -> dict. -
Produces: Celery
parse_fssp_enforcement_proceedings(self, *, requested_by_id: int | None = None) -> dict, task nameparsers.fssp_enforcement_proceedings.refresh. -
FsspEnforcementProceedingPayloadSerializerDRF fields exactly current Gleb contract; source card slugfssp-enforcement-proceedings. -
Добавить регрессию:
def test_source_mapping_is_exact():
descriptor = get_source_group_descriptor("fssp_enforcement_proceedings")
assert descriptor.source_group == "enforcement_proceedings"
assert descriptor.record_type == "enforcement_proceeding"
# Additional fixture-driven tests:
# list_detail_export_same_uid_and_signed_amount; required_payload_keys_nullable;
# record_date_equals_initiated_on; amount_equals_debt_not_claim;
# each frontend-documented filter/order; permission_denied; concurrent_refresh_409;
# failed_job_keeps_last_success_and_export_tickets; progress_and_manifest_counts.
# Load current Gleb schema read-only; copy its assertions into backend tests.
- Запустить
PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_fssp_refresh.py tests/apps/organizations/test_fssp_contract.py tests/apps/parsers/test_refresh_concurrency.py -q. До реализации ожидается FAIL: новый source mapping/refresh/payload отсутствует. - Зарегистрировать source/card/group/task, расширить refresh concurrency guard для нового source. Добавить serializer discriminator/filter/order/export и backend runtime fixtures; source-specific signed money не менять у других групп. Public refresh не принимает file URL/path. Disabled schedule migration принадлежит этому task. Построить OpenAPI штатно по общему validation guide, не редактировать frontend.
- Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов.
- Проверить scoped diff и выполнить
git commit -m 'feat: expose FSSP source APIs and exports', добавляя только перечисленные файлы этого task.
Task 5: Фактическая dev-приёмка
Files: Update docs/sources/fssp.md.
Interfaces: consumes refresh Task 3 и API Task 4; produces evidence report и readiness verdict.
- Выполнить общий validation guide из
2026-10-05-source-implementation.md. - Отдельно ограничить dev-контур и согласовать любые изменения удалённой БД; локальные unit tests не требуют этого. Выполнить полный реальный проход обоих inputs, включая большой CSV, без customer deployment.
- Зафиксировать checksums, даты, размеры, input/matched/skipped/quarantined/published counters, wall time, peak RSS и max staging batch. Сопоставить manifest/job/API/export; повторный импорт сохраняет UUID. Рост числа CSV строк не должен линейно увеличивать память reader/staging; память canonical index учитывать отдельно.
- Оставить schedule disabled; обозначить точный остаток при недоступности одного input. Commit только evidence/doc. Не заменять реальный acceptance синтетическим PASS.