# 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:** [Согласованная спецификация](../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 - Раздел отсутствует в тарифе: явный отказ доступа, а не 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. - [ ] Добавить регрессию: ```python 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. - [ ] Добавить регрессию: ```python 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. - [ ] Добавить регрессию: ```python 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; без публикации релиза или внешних сообщений.