196 lines
18 KiB
Markdown
196 lines
18 KiB
Markdown
# ФССП 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.
|