Files
mostovik-backend/docs/superpowers/plans/2026-10-05-fssp.md
2026-10-05 15:11:19 +02:00

18 KiB
Raw Permalink Blame History

ФССП 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; commit docs: 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 name parsers.fssp_enforcement_proceedings.refresh.

  • FsspEnforcementProceedingPayloadSerializer DRF fields exactly current Gleb contract; source card slug fssp-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.