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

196 lines
18 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.
# ФССП 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:** [Согласованная спецификация](../specs/2026-10-05-fssp-checko-exchanges-design.md).
## 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, не материализованный список.
- [ ] Добавить регрессию:
```python
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.
- [ ] Добавить регрессию:
```python
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`.
- [ ] Добавить регрессию:
```python
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.