20 KiB
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, countersorganizations_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; без публикации релиза или внешних сообщений.