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