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

212 lines
20 KiB
Markdown
Raw Permalink 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.
# 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; без публикации релиза или внешних сообщений.