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

20 KiB
Raw Blame History

Checko: лизинг, сообщения, лицензии 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: Существующий CheckoClient обеспечивает транспорт. Отдельные section adapters нормализуют проверенные ответы в SourceRecordInput; snapshot worker публикует только завершённые организации и сохраняет остальные. 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

  • Раздел отсутствует в тарифе: явный отказ доступа, а не verified empty (Tasks 1–2).
  • Повторный refresh/ошибка/гонка worker: один месячный claim, без освобождения при ошибке (Task 3).
  • Обрыв/зацикливание пагинации: организация не публикуется частично (Task 2).
  • Половина организаций пропущена: старые данные сохранены, job явно partial, full last_success не меняется (Task 3).
  • Повторный ID с другими данными/отсутствие ID: проверенная identity либо отказ (Task 2).

File map

Create:

  • src/apps/parsers/checko_sections.py: три section adapters; client-only transport, нормализация/identity.
  • src/apps/parsers/checko_section_snapshots.py: canonical population, claims, staging, scope publication/counters.
  • src/organizations/checko_section_payload_serializers.py: типизированные payloads.
  • tests/apps/parsers/test_checko_sections.py, test_checko_section_snapshots.py.
  • tests/apps/organizations/test_checko_section_contract.py.
  • tests/fixtures/checko_sections/, docs/sources/checko-sections.md.

Modify:

  • src/apps/parsers/clients/checko/client.py, schemas/common.py, schemas/requests.py, schemas/responses.py внутри того же client package: только verified upstream additions.
  • src/apps/parsers/models.py: ParserLoadLog/CheckoCollectionAttempt sources.
  • src/organizations/models.py, source_groups.py: LeasingExtension, CompanyMessageExtension, CompanyLicenseExtension.
  • src/apps/parsers/source_registry.py, source_cards.py, tasks_registry_snapshots.py, views.py, serializers.py.
  • src/organizations/serializers.py, source_record_query.py, source_record_export.py.
  • tools/openapi/source-record-extensions.json, штатные backend generated outputs и model/disabled-schedule migrations.
  • Existing tests: tests/apps/parsers/test_checko_collection.py, test_refresh_concurrency.py, test_source_registry.py, backend OpenAPI/runtime suites.
  • Не переписывать tasks.py и существующие платные collectors целиком.

Task 1: Проверить API и тариф без выдуманных маршрутов

Files: Create docs/sources/checko-sections.md, tests/fixtures/checko_sections/. Interfaces: produces exact route/method/request/response/pagination/limit mapping для каждого раздела.

  • Проверить актуальную официальную документацию и тарифный доступ. CompanyData.licenses использовать только после проверки семантики; BankruptcyMessage не считать общими сообщениями.
  • Для каждого раздела зафиксировать exact upstream call, request type/ключи, envelope, поля, provider ID, timestamps, pagination/terminal markers, максимальное число pages/records и API-limit behavior. Численные пределы выбрать из документации, записать до implementation.
  • Сначала использовать документацию и существующие обезличенные примеры. Если нужны новые платные запросы — подготовить ограниченный перечень организация/раздел/число calls, показать расход и получить разрешение на этот конкретный сбор. Не читать/печатать ключ для планирования.
  • Подготовить обезличенные success/empty/denied/rate-limit/multipage fixtures; удалить request credentials и реальные персональные сведения. Licenses: confirmed number/date/start/end/authority/activities.
  • Если leasing/messages API недоступен: зафиксировать blocker; не создавать fake endpoints и не объявлять readiness. Разрабатывать доступный раздел отдельно. Финальный mapping/source-specific payload schema утверждается на evidence, как требует spec.
  • Commit docs: verify Checko section API contracts, только docs и fixtures.

Task 2: Нормализованные section adapters

Files:

  • Create: src/apps/parsers/checko_sections.py
  • Modify: verified Checko client/schema additions из File map
  • Test: tests/apps/parsers/test_checko_sections.py

Interfaces:

  • Consumes: existing CheckoClient, Organization, verified schemas Task 1.

  • Produces: collect_checko_section(client: CheckoClient, *, organization: Organization, source: str) -> Iterator[SourceRecordInput].

  • Accepted sources ровно checko_leasing, checko_messages, checko_licenses.

  • Iterator exhaustion означает подтверждённое полное получение; access/transport/pagination failures raise SnapshotValidationError. Raw schemas/client methods добавлять только по Task 1.

  • Добавить регрессию:

def test_license_identity_ignores_mutable_expiry():
    first = list(collect_checko_section(client_with_license_fixture("license.json"),
        organization=canonical_org, source="checko_licenses"))
    later = list(collect_checko_section(client_with_license_fixture("renewed.json"),
        organization=canonical_org, source="checko_licenses"))
    assert first[0].external_id == later[0].external_id
    assert first[0].record_type == "company_license"

# Fixtures/client mock/canonical_org определить в этом module.
# Additional: all_pages_collected, denied_not_empty, genuine_empty,
# repeated_cursor_rejected, max_pages_rejected, conflicting_id_rejected,
# missing_id_verified_composite_identity, messages_not_bankruptcy,
# nullable_dates_and_activities, no_float_money_or_fake_fields.

def test_denied_is_not_verified_empty():
    with pytest.raises(SnapshotValidationError):
        list(collect_checko_section(denied_client, organization=canonical_org,
                                   source="checko_messages"))

def test_repeated_cursor_is_not_complete():
    with pytest.raises(SnapshotValidationError):
        list(collect_checko_section(repeated_cursor_client,
                                   organization=canonical_org,
                                   source="checko_leasing"))

def test_conflicting_provider_identity_is_rejected():
    with pytest.raises(SnapshotValidationError):
        list(collect_checko_section(conflicting_id_client,
                                   organization=canonical_org,
                                   source="checko_messages"))

# Определить эти client fixtures здесь по обезличенным ответам Task 1.
  • Запустить PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_checko_sections.py -q. До реализации ожидается FAIL: collect_checko_section отсутствует.
  • Реализовать указанную сигнатуру. Ключ leasing/messages provider ID + org; license provider ID либо org/номер/орган/дата выдачи. Одинаковые данные можно дедуплицировать, конфликтующие reject. Pagination заканчивается только documented marker; клиент сохраняет текущий timeout/proxy/error handling. Payload содержит только confirmed fields, provenance и fetched_at.
  • Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов.
  • Проверить scoped diff и выполнить git commit -m 'feat: normalize verified Checko sections', добавляя только перечисленные файлы этого task.

Task 3: Claims и scoped snapshot

Files:

  • Create: src/apps/parsers/checko_section_snapshots.py
  • Modify: src/apps/parsers/models.py, src/organizations/models.py, src/organizations/source_groups.py
  • Test: tests/apps/parsers/test_checko_section_snapshots.py, test_checko_collection.py
  • Create: штатные migrations

Interfaces:

  • Consumes: Task 2 iterator; existing claim_monthly_collection(*, organization_id: str, source: str, at=None) -> CheckoCollectionAttempt | None, finish_collection(attempt, *, records_count: int, error=None) -> None.

  • Produces: refresh_checko_section(*, source: str, 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].

  • publish_snapshot(..., scope_organization_ids=successful_ids, preserve_organization_ids=unfinished_ids).

  • Artifact metadata completeness=full|partial, counters organizations_total/updated/empty/preserved/failed/quota_skipped; суммы категорий проверяются. skipped claims не вызывают upstream.

  • Добавить регрессию:

def test_failed_or_claimed_organization_keeps_previous_records():
    before = records_for(unfinished_org)
    artifact, result = refresh_with_one_success_and_one_quota_skip()
    assert records_for(unfinished_org) == before
    assert artifact.metadata["completeness"] == "partial"
    assert artifact.metadata["quota_skipped"] == 1

# Define setup/helpers here using actual refresh and patched adapter.
# Additional: concurrent_claim_one_winner, error_claim_never_released,
# three_sources_independent_claims, empty_success_clears_only_its_org,
# pagination_error_discards_org_staging, repeated_ids_stable,
# no_new_org_or_legacy_write, no_successful_scope_no_publish,
# publication_failure_rolls_back_scope, complete_counter_partition.

def test_error_does_not_release_monthly_claim():
    first = claim_monthly_collection(organization_id=str(canonical_org.uid),
                                    source="checko_leasing")
    finish_collection(first, records_count=0, error="fixture failure")
    second = claim_monthly_collection(organization_id=str(canonical_org.uid),
                                     source="checko_leasing")
    assert second is None
  • Запустить PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_checko_section_snapshots.py tests/apps/parsers/test_checko_collection.py -q. До реализации ожидается FAIL: нет новых claim sources/refresh/extension.
  • Claim до первого запроса, finish после полного получения или ошибки; не сбрасывать claim. Неполные staging строки организации исключить перед publish. Использовать точную canonical eligibility и bounded staging=500. Обновить enums и три extension models. Если ни одна организация не завершена, сохранить rejected artifact с counters и raise SnapshotValidationError("no_completed_organizations"); не публиковать fake snapshot. Snapshot публикации и counts строятся только на successful scope.
  • Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов.
  • Проверить scoped diff и выполнить git commit -m 'feat: publish quota-safe Checko section snapshots', добавляя только перечисленные файлы этого task.

Task 4: Три контракта и честная завершённость

Files:

  • Create: src/organizations/checko_section_payload_serializers.py
  • Modify: integration files File map и tools/openapi/source-record-extensions.json
  • Test: tests/apps/organizations/test_checko_section_contract.py, source cards/registry/concurrency tests

Interfaces:

  • Produces Celery tasks: parse_checko_leasing(self, *, requested_by_id: int | None = None) -> dict, parse_checko_messages(self, *, requested_by_id: int | None = None) -> dict, parse_checko_licenses(self, *, requested_by_id: int | None = None) -> dict.

  • Task names parsers.checko_leasing.refresh, parsers.checko_messages.refresh, parsers.checko_licenses.refresh.

  • Each wrapper binds source and passes Task 3 refresh through existing _run_snapshot.

  • Для no-completed failure _run_snapshot связывает rejected artifact по source/load_batch и возвращает его counters в bounded job result; ошибка не двигает full last_success. Не сохранять HTTP internals.

  • DRF payload serializers: CheckoLeasingPayloadSerializer, CheckoMessagePayloadSerializer, CheckoLicensePayloadSerializer; exact fields come from Task 1 mapping.

  • Добавить регрессию:

def test_three_independent_groups():
    expected = {
        "checko_leasing": ("leasing", "leasing_contract"),
        "checko_messages": ("company_messages", "company_message"),
        "checko_licenses": ("company_licenses", "company_license"),
    }
    for source, (group, kind) in expected.items():
        descriptor = get_source_group_descriptor(source)
        assert (descriptor.source_group, descriptor.record_type) == (group, kind)

# Additional: partial_job_visible_with_counts, full_last_success_not_advanced_by_partial,
# previous_export_ticket_works, list_detail_export_match,
# source_card_slugs_match_spec, permissions/concurrent_409,
# empty_null_fields_and_discriminators, existing_sources_unchanged.

def test_partial_pass_does_not_move_full_last_success():
    before = read_card_full_last_success("checko-leasing")
    run_partial_refresh_task()
    assert read_card_full_last_success("checko-leasing") == before
    assert read_last_job_result()["completeness"] == "partial"

# Helpers здесь вызывают реальные SourceCardService/task interfaces с mocked HTTP.
  • Запустить PYTHONPATH=src uv run --no-sync pytest tests/apps/organizations/test_checko_section_contract.py tests/apps/parsers/test_source_registry.py tests/apps/parsers/test_refresh_concurrency.py -q. До реализации ожидается FAIL: три source mappings/контракта отсутствуют.
  • Добавить card slugs checko-leasing/checko-messages/checko-licenses, group/type, task registration и concurrency guard. В _complete_snapshot_job сохранить partial metadata; source_cards выбирает full last_success отдельно от последней partial попытки. Существующая job status success может означать завершение частичного прохода только с явно видимым completeness/counts. Изменение publisher/query не должно скрывать обновлённые successful org records. Расширить filters/order/export/runtime fixtures. Existing test запрета строки checko во всей metadata адаптировать к утверждённым machine IDs; ключи API не менять ради этого теста, display copy соблюдать текущую provider-neutral конвенцию. Генерация OpenAPI и disabled schedules по общему guide.
  • Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов.
  • Проверить scoped diff и выполнить git commit -m 'feat: expose Checko section APIs and completion counters', добавляя только перечисленные файлы этого task.

Task 5: Ограниченная фактическая приёмка

Files: Update docs/sources/checko-sections.md. Interfaces: consumes Tasks 1–4; produces per-source evidence и тарифная readiness.

  • Выполнить общий validation guide. test_checko_e2e.py использует локальный HTTP server и безопасен для обычного suite; отдельные реальные платные пробы не входят в pytest.
  • Подготовить dev-only paid collection с точным canonical scope, числом calls/pages и квотой; выполнить только в явно разрешённом контуре. При уже занятой месячной claim использовать будущий период/другую разрешённую организацию, не обнулять claims.
  • Для каждого доступного раздела подтвердить полный разрешённый обход, даты, artifact checksum, counts, result completeness, API/export. Ошибочные/quota orgs сохраняют данные. Полный dev-обход популяции — отдельный критерий готовности, ограниченная проба его не заменяет.
  • Зафиксировать недоступные разделы и остаток, сохранить disabled schedules. Commit evidence; без публикации релиза или внешних сообщений.