From 10611b1d9640536f4dd84d5ab0b53c6b6bfeaac7 Mon Sep 17 00:00:00 2001 From: Aleksandr Meshchryakov Date: Mon, 5 Oct 2026 15:11:19 +0200 Subject: [PATCH] docs: plan FSSP Checko and unified exchange implementation --- .../plans/2026-10-05-checko-sections.md | 211 +++++++++++++++++ .../superpowers/plans/2026-10-05-exchanges.md | 220 ++++++++++++++++++ docs/superpowers/plans/2026-10-05-fssp.md | 195 ++++++++++++++++ .../plans/2026-10-05-source-implementation.md | 162 +++++++++++++ ...2026-10-05-fssp-checko-exchanges-design.md | 2 +- 5 files changed, 789 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/plans/2026-10-05-checko-sections.md create mode 100644 docs/superpowers/plans/2026-10-05-exchanges.md create mode 100644 docs/superpowers/plans/2026-10-05-fssp.md create mode 100644 docs/superpowers/plans/2026-10-05-source-implementation.md diff --git a/docs/superpowers/plans/2026-10-05-checko-sections.md b/docs/superpowers/plans/2026-10-05-checko-sections.md new file mode 100644 index 0000000..8bc073d --- /dev/null +++ b/docs/superpowers/plans/2026-10-05-checko-sections.md @@ -0,0 +1,211 @@ +# 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; без публикации релиза или внешних сообщений. diff --git a/docs/superpowers/plans/2026-10-05-exchanges.md b/docs/superpowers/plans/2026-10-05-exchanges.md new file mode 100644 index 0000000..df4817b --- /dev/null +++ b/docs/superpowers/plans/2026-10-05-exchanges.md @@ -0,0 +1,220 @@ +# Биржи: единый источник 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:** Объединить СПБ и MOEX в один источник биржевой активности канонических организаций. +**Architecture:** СПБ XLSX и MOEX ISS/официальный экспорт имеют отдельные адаптеры. Один snapshot coordinator сохраняет input artifacts и публикует общий manifest только после полного завершения обоих каналов; биржа — поле записи. +**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 + +- emitent_id без ИНН mapping: никакого сопоставления по названию или неподтверждённому ID (Task 3). +- Одинаковый ISIN на двух биржах: две записи, независимые стабильные UUID (Task 4). +- Неполный/изменённый XLSX: явный отказ, не пустой успешный snapshot (Task 2). +- Сбой MOEX после успешного СПБ: предыдущий объединённый snapshot сохраняется (Task 4). +- Несовпадающие даты/единицы yield/duration/trading: provenance и nullable values, без смешивания с amount (Tasks 3, 5). + +--- + +## File map + +Create: +- `src/apps/parsers/exchange_spb.py`: официальный discovery/download и read-only XLSX. +- `src/apps/parsers/exchange_moex.py`: ISS pagination, verified issuer linkage, параметры/trading/duration. +- `src/apps/parsers/exchange_snapshot.py`: два adapter inputs, staging, manifest/publication. +- `src/organizations/exchange_payload_serializers.py`: общий typed instrument payload. +- `tests/apps/parsers/test_exchange_spb.py`, `test_exchange_moex.py`, `test_exchange_snapshot.py`. +- `tests/apps/organizations/test_exchange_contract.py`. +- `tests/fixtures/exchanges/`, `docs/sources/exchanges.md`. + +Modify: +- `src/apps/parsers/models.py`, `src/organizations/models.py`, `source_groups.py`: одна группа/extension/source. +- `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`. +- `src/settings/base.py`: проверенные публичные hosts/лимиты. +- `tools/openapi/source-record-extensions.json`, штатные generated outputs/migrations. +- Existing source cards/concurrency/metadata/OpenAPI/runtime tests. + +### Task 1: Проверить официальные каналы и единицы + +**Files:** Create `docs/sources/exchanges.md`, `tests/fixtures/exchanges/`. +**Interfaces:** produces точную схему XLSX headers, ISS blocks/cursors, issuer-INN mapping и duration/yield units. + +- [ ] Использовать свежий документ ECOS 01.10.2026. Проверить официальную текущую страницу СПБ listing и правило выбора самого нового файла по опубликованной дате, не порядку HTML links. Зафиксировать actual XLSX, дату, headers и vendor security ID. +- [ ] Проверить официальный ISS reference и actual response: instrument reference/parameters/trading results; найти подтверждённую связь issuer ID с ИНН. Записать exact routes/params/blocks/columns/cursors и terminal condition; emitent_id не трактовать как ИНН. +- [ ] Для облигаций подтвердить official issuer-INN selection, duration/currentyield и calculation date. Если ISS их не даёт — проверить официальный export /ru/bondization/durations, его формат/колонки/единицы. +- [ ] Зафиксировать для каждого числового поля original units, decimal scale, date и null semantics; выбрать и записать конкретные page/request/file limits по наблюдаемому каналу. Подготовить небольшие обезличенные success/empty/multipage/invalid-header/issuer-mismatch fixtures. +- [ ] При отсутствующей связи с ИНН/недоступной дюрации зафиксировать blocker; не подставлять нули и не переключать провайдера. Работу по подтверждённому adapter можно продолжать, общий источник не ready. +- [ ] Commit `docs: verify exchange source mappings and units`, docs/fixtures only. + +### Task 2: СПБ: read-only XLSX + +**Files:** +- Create: `src/apps/parsers/exchange_spb.py` +- Test: `tests/apps/parsers/test_exchange_spb.py` +- Fixtures: `tests/fixtures/exchanges/` + +**Interfaces:** +- Produces: `iter_spb_records(handle: BinaryIO) -> Iterator[SourceRecordInput]`. +- Produces: `download_spb_artifact(*, load_batch: int, uploaded_by_id: int | None = None) -> ParserSourceArtifact`. +- Record source `stock_exchange_activity`, type `exchange_instrument`, payload.exchange=`spb`; external_id=`spb:`. +- Invalid workbook/unknown required headers raise SnapshotValidationError. + +- [ ] Добавить регрессию: +```python +def test_spb_preserves_inn_and_vendor_identity(): + with fixture_xlsx("listing.xlsx") as handle: + row = next(iter_spb_records(handle)) + assert row.inn == "0123456789" + assert row.external_id == "spb:fixture-security-1" + assert row.payload["exchange"] == "spb" + assert row.amount is None + +# Define fixture_xlsx in this module; generate synthetic workbook in fixture setup. +# Additional: latest_by_date_not_link_order, read_only_iteration, +# missing_or_changed_headers_rejected, invalid_xlsx_rejected, +# missing_inn_diagnostic, genuine_empty_requires_valid_headers, +# no_name_matching, redirect_host_rejected, size_bound_enforced. + +def test_unknown_workbook_headers_rejected(): + with fixture_xlsx("unknown_headers.xlsx") as handle: + with pytest.raises(SnapshotValidationError): + next(iter_spb_records(handle)) +``` +- [ ] Запустить `PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_exchange_spb.py -q`. До реализации ожидается FAIL: СПБ adapter отсутствует. +- [ ] Реализовать обе сигнатуры; download через existing registry_http/save_artifact_file. Читать openpyxl.load_workbook(read_only=True, data_only=True), rows iterator, закрывать workbook. Не переводить строковый ИНН через int; числовая Excel cell требует строго проверяемой длины, нельзя добавлять ведущие нули догадкой. Original provenance сохранять в artifact/payload; skipped/malformed диагностика доступна coordinator. +- [ ] Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов. +- [ ] Проверить scoped diff и выполнить `git commit -m 'feat: ingest verified SPB listing workbook'`, добавляя только перечисленные файлы этого task. + +### Task 3: MOEX: issuer mapping и instrument observations + +**Files:** +- Create: `src/apps/parsers/exchange_moex.py` +- Test: `tests/apps/parsers/test_exchange_moex.py` + +**Interfaces:** +- Consumes: verified Task 1 blocks/mapping, `OwnOrganizationIndex`, existing registry_http session. +- Produces: `iter_moex_records(*, organization_index: OwnOrganizationIndex, artifact: ParserSourceArtifact) -> Iterator[SourceRecordInput]`. +- source/type as Task 2; payload.exchange=`moex`, external_id=`moex:`. +- ParserSourceArtifact сохраняет manifest исходных reference/trading/duration responses с checksum/date; raw files через existing private artifact storage. Unknown mapping/pagination failure raises SnapshotValidationError. + +- [ ] Добавить регрессию: +```python +def test_internal_issuer_id_cannot_match_inn(): + rows = list(iter_moex_records( + organization_index=canonical_index, artifact=moex_artifact)) + assert all(row.organization_uid != wrong_issuer_org.uid for row in rows) + +# Patch HTTP with Task 1 fixtures: emitent_id numerically matches unrelated org INN, +# actual confirmed mapping points to another issuer; define setup here. +# Additional: all_cursor_pages, incomplete_cursor_rejected, +# multiple_bonds_one_issuer, exact_inn_mapping, leading_zero_identifier, +# nullable_yield_not_zero, duration_units_and_calculation_date, +# trading_date_separate_from_download_date, incompatible_observation_dates, +# downloaded_raw_response_checksums, bounded_request_limit. + +def test_metric_dates_and_units_remain_distinct(): + row = next(iter_moex_records(organization_index=canonical_index, + artifact=moex_artifact)) + assert row.amount is None + assert row.payload["duration"]["calculated_on"] == "2026-10-01" + assert row.payload["yield"]["calculated_on"] == "2026-10-02" + assert row.payload["yield"]["value"] is None + +# Synthetic fixtures явно задают разные даты; duration/yield — +# проектируемая normalized envelope, raw units mapping подтверждает Task 1. +``` +- [ ] Запустить `PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_exchange_moex.py -q`. До реализации ожидается FAIL: MOEX adapter отсутствует. +- [ ] Реализовать указанную сигнатуру по mapping Task 1. Получить справочник с bounded pagination, отобрать canonical emitters, присоединить параметры и trading observations каждой бумаги, dated duration/yield. Денежные значения Decimal → строки, проценты/цена/дюрация имеют собственные поля+единицы. Разные calculation dates не представлять как одно синхронное наблюдение. При неизвестном обязательном block/mapping reject, необязательное подтверждённо отсутствующее поле nullable. Не строить внутридневной мониторинг. +- [ ] Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов. +- [ ] Проверить scoped diff и выполнить `git commit -m 'feat: collect MOEX issuer-linked instruments and metrics'`, добавляя только перечисленные файлы этого task. + +### Task 4: Один snapshot, две биржи + +**Files:** +- Create: `src/apps/parsers/exchange_snapshot.py` +- Modify: `src/apps/parsers/models.py`, `src/organizations/models.py`, `src/organizations/source_groups.py`, `src/settings/base.py` +- Test: `tests/apps/parsers/test_exchange_snapshot.py` +- Create: штатные migrations + +**Interfaces:** +- Consumes: adapters Tasks 2–3, existing OwnOrganizationIndex/stage_records/publish_snapshot. +- Produces: `refresh_stock_exchange_activity(*, 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]`. +- source/group/type=`stock_exchange_activity/stock_exchange_activity/exchange_instrument`; model `StockExchangeActivityExtension`. +- Возвращаемый artifact aggregate manifest: input artifacts и dates/checksums/counters отдельно по бирже. + +- [ ] Добавить регрессию: +```python +def test_same_isin_on_two_exchanges_stays_two_records(): + artifact, result = refresh_with_same_isin_two_exchanges() + rows = OrganizationSourceRecord.objects.filter(source="stock_exchange_activity") + assert result.published == 2 + assert {row.payload["exchange"] for row in rows} == {"moex", "spb"} + assert len(set(rows.values_list("uid", flat=True))) == 2 + +# Setup/helpers patch actual adapters here. +# Additional: moex_failure_preserves_combined_snapshot, +# repeat_import_stable_uuids, duplicate_vendor_id_conflict_rejected, +# foreign_org_skipped_and_counted, ambiguous_org_quarantined, +# no_new_org_or_legacy_writes, manifest_two_adapter_counters, +# staging_bounded_500, publication_rollback. + +def test_second_adapter_failure_preserves_unified_snapshot(): + before = published_exchange_rows() + with failing_moex_adapter(): + with pytest.raises(SnapshotValidationError): + refresh_stock_exchange_activity(load_batch=2) + assert published_exchange_rows() == before + +# Helpers определить здесь; СПБ mock успешно завершает проверенный fixture. +``` +- [ ] Запустить `PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_exchange_snapshot.py -q`. До реализации ожидается FAIL: coordinator/source model отсутствует. +- [ ] Сохранить отдельные raw artifacts и aggregate manifest. Stream normalized inputs в staging, resolve только exact canonical identity; validate оба adapters до одного publish_snapshot. stable_registry_uid(source, external_id) включает exchange-prefixed key, не ISIN. Reject сохраняет оба provenance и прошлую публикацию; model/enums одна группа, не две. +- [ ] Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов. +- [ ] Проверить scoped diff и выполнить `git commit -m 'feat: publish unified exchange activity snapshots'`, добавляя только перечисленные файлы этого task. + +### Task 5: Общий API/export и фактическая приёмка + +**Files:** +- Create: `src/organizations/exchange_payload_serializers.py` +- Modify: остальные integration files File map, `tools/openapi/source-record-extensions.json` +- Test: `tests/apps/organizations/test_exchange_contract.py`, source cards/concurrency/runtime fixtures +- Update: `docs/sources/exchanges.md` + +**Interfaces:** +- Produces: `ExchangeInstrumentPayloadSerializer` с exchange enum moex|spb и полями Task 1. +- Normalized `duration` и `yield`: объект `{value: str | null, unit: str | null, calculated_on: str | null}`; unit определяется verified mapping Task 1, provenance хранится отдельно. Envelope nullable, когда наблюдение полностью отсутствует; date ISO YYYY-MM-DD. +- Celery `parse_stock_exchange_activity(self, *, requested_by_id: int | None = None) -> dict`; task `parsers.stock_exchange_activity.refresh`; card slug `stock-exchange-activity`. +- Consumes Task 4 refresh via existing _run_snapshot; export использует existing ticket/archive flow. + +- [ ] Добавить регрессию: +```python +def test_exact_unified_source(): + descriptor = get_source_group_descriptor("stock_exchange_activity") + assert descriptor.source_group == "stock_exchange_activity" + assert descriptor.record_type == "exchange_instrument" + cards = [card for card in SOURCE_CARD_DEFINITIONS + if card.slug == "stock-exchange-activity"] + assert len(cards) == 1 + +# Additional: list_detail_export_match_both_exchanges; units_dates_nullable; +# instrument_type_specific_fields; invalid_exchange_rejected; +# one_job_and_total_counts; failed_adapter_keeps_last_success_and_tickets; +# permission_denied/concurrent_409; existing_groups_unchanged. +``` +- [ ] Запустить `PYTHONPATH=src uv run --no-sync pytest tests/apps/organizations/test_exchange_contract.py tests/apps/parsers/test_refresh_concurrency.py -q`. До реализации ожидается FAIL: единый card/contract отсутствует. +- [ ] Добавить одну карточку, один task, source registry/group/payload/discriminator; фильтры exchange/instrument kind и ordering по проверенным полям с nulls. Export сохраняет метрики отдельно от amount. Disabled schedule, backend OpenAPI по общему guide. После unit/contract gates выполнить реальный полный dev-проход обоих публичных adapters; зафиксировать manifests, counters, RSS/time, issuer mapping и API/export. Remote DB mutations требуют отдельно ограниченного контура. Недоступный adapter сохраняет источник not-ready. +- [ ] Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов. +- [ ] Проверить scoped diff и выполнить `git commit -m 'feat: expose unified exchange activity APIs and exports'`, добавляя только перечисленные файлы этого task. diff --git a/docs/superpowers/plans/2026-10-05-fssp.md b/docs/superpowers/plans/2026-10-05-fssp.md new file mode 100644 index 0000000..a7290af --- /dev/null +++ b/docs/superpowers/plans/2026-10-05-fssp.md @@ -0,0 +1,195 @@ +# ФССП 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:** Небольшие модули разделяют чтение CSV и оркестрацию двух артефактов. Нормализованные SourceRecordInput проходят существующий staging; manifest является артефактом объединённой публикации. +**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 + +- Оборванный второй файл: прежний общий snapshot и last_success сохраняются (Task 3). +- Кавычки/переносы и переставленные заголовки: CSV читается корректно; неизвестная структура отклоняется (Task 2). +- Дубликаты ИП с разными наблюдениями: детерминированная разрешённая политика либо отказ; никаких случайных перезаписей (Task 3). +- Отрицательный/нулевой долг и будущая дата: сохраняются без исправления (Tasks 2, 4). +- Неоднозначный ИНН/организация вне реестра: quarantine/skip, без создания организации (Task 3). + +--- + +## File map + +Create: +- `src/apps/parsers/fssp_csv.py`: заголовки, потоковый CSV, нормализация полей. +- `src/apps/parsers/fssp_snapshot.py`: discovery, download, два входа, manifest, staging/publication. +- `src/organizations/fssp_payload_serializers.py`: типизированный контракт Глеба. +- `tests/apps/parsers/test_fssp_csv.py`, `test_fssp_snapshot.py`, `test_fssp_refresh.py`. +- `tests/apps/organizations/test_fssp_contract.py`. +- `tests/fixtures/fssp/`: обезличенные малые CSV и паспорта/mapping. +- `docs/sources/fssp.md`: каналы, headers, ограничения и результаты фактической приёмки. + +Modify: +- `src/apps/parsers/models.py`, `src/organizations/models.py`, `src/organizations/source_groups.py`: enums и EnforcementProceedingExtension. +- `src/apps/parsers/source_registry.py`, `source_cards.py`, `tasks_registry_snapshots.py`, `views.py`, `serializers.py`: refresh/run/cards/job. +- `src/organizations/serializers.py`, `source_record_query.py`, `source_record_export.py`: payload/filter/order/export. +- `src/settings/base.py`: серверные публичные каналы/лимиты, без чтения секрета. +- `tools/openapi/source-record-extensions.json` и штатно генерируемые backend OpenAPI outputs. +- Штатно создаваемые миграции в `src/organizations/migrations/`, `src/apps/parsers/migrations/`; имена фиксирует makemigrations на текущем HEAD. + +### Task 1: Подтвердить два канала и зафиксировать mapping + +**Files:** Create `docs/sources/fssp.md`, `tests/fixtures/fssp/`. +**Interfaces:** produces документированную таблицу «исходный header → payload», отдельную для каждого паспорта; downstream читает только эти fixtures. + +- [ ] Прочитать свежий документ ECOS и дополнение Глеба, затем официальные паспорта обоих наборов. Зафиксировать URL паспорта, exact dataset ID, актуальную дату, URL файла, разрешённые HTTPS hosts, кодировку, delimiter, все headers, семантику статуса и пересечения наборов. +- [ ] Скачать публичные inputs потоково с проверкой redirects; записать checksum/размер отдельно от малых обезличенных fixtures. Ограничение на файл выбрать по текущему официальному размеру с запасом и записать конкретное значение; размер Глеба 1 954 126 197 байт не считать подтверждением обоих каналов. +- [ ] Получить fixtures: нормальная строка, quoted multiline, zero/negative debt, amount due отдельно, отсутствующие даты, дубль, unknown header, truncated stream. Не сохранять реальный полный реестр в Git. +- [ ] Gate: оба паспорта и mapping подтверждены. Если один недоступен — отметить точную причину; продолжать локальный контракт, но не включать refresh/расписание и не объявлять реальный сбор готовым. Не придумывать статус ended из имени файла. +- [ ] `git add docs/sources/fssp.md tests/fixtures/fssp`; commit `docs: verify FSSP datasets and mappings`. + +### Task 2: Потоковое чтение и денежная семантика + +**Files:** +- Create: `src/apps/parsers/fssp_csv.py` +- Test: `tests/apps/parsers/test_fssp_csv.py` +- Fixtures: `tests/fixtures/fssp/` + +**Interfaces:** +- Produces: `iter_fssp_records(handle: TextIO, *, dataset: str) -> Iterator[SourceRecordInput]`. +- `dataset` — один из двух verified IDs Task 1; `external_id` основан на ИНН/номере ИП; org пока разрешает Task 3. +- Unknown headers/повреждённая CSV → `SnapshotValidationError`; читается csv.reader, не материализованный список. + +- [ ] Добавить регрессию: +```python +def test_signed_debt_and_multiline_preserved(): + with fixture_csv("signed_multiline.csv") as handle: + row = next(iter_fssp_records(handle, dataset=verified_dataset_id)) + assert row.amount == Decimal("-12.50") + assert row.payload["debt_amount"] == "-12.50" + assert row.payload["claim_amount"] == "250.00" + assert row.payload["origin_kind"] == "open_data_csv" + assert row.payload["queried_inn"] is None + +# fixture_csv и verified_dataset_id определить в этом test module по Task 1. +# Дополнительные tests: reordered_headers, unknown_headers, zero_not_null, +# quoted_newline, missing_date, future_document_date, raw_17_columns. + +def test_unknown_headers_rejected(): + with fixture_csv("unknown_headers.csv") as handle: + with pytest.raises(SnapshotValidationError): + next(iter_fssp_records(handle, dataset=verified_dataset_id)) + +def test_future_document_date_is_preserved(): + with fixture_csv("future_date.csv") as handle: + row = next(iter_fssp_records(handle, dataset=verified_dataset_id)) + assert row.payload["document_date"] == "2099-01-01" + assert "future_document_date" in row.payload["parse_warnings"] +``` +- [ ] Запустить `PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_fssp_csv.py -q`. До реализации ожидается FAIL: отсутствует iter_fssp_records. +- [ ] Реализовать указанную сигнатуру; сохранить все 17 raw значений, остальные обязательные поля и warnings из текущего frontend контракта. Record date = initiated_on, amount = debt_amount. Суммы Decimal, не float; будущая дата только warning. Конфигурация reader и mapping определены Task 1. +- [ ] Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов. +- [ ] Проверить scoped diff и выполнить `git commit -m 'feat: normalize streaming FSSP CSV records'`, добавляя только перечисленные файлы этого task. + +### Task 3: Два входа и атомарная публикация + +**Files:** +- Create: `src/apps/parsers/fssp_snapshot.py` +- Modify: `src/apps/parsers/models.py`, `src/organizations/models.py`, `src/organizations/source_groups.py`, `src/settings/base.py` +- Create: штатные model migrations +- Test: `tests/apps/parsers/test_fssp_snapshot.py` + +**Interfaces:** +- Consumes: Task 2 iterator; `OwnOrganizationIndex.resolve(*, inn, ogrn, kpp="", okpo="")`, `stable_registry_uid(source, external_id)`, `stage_records(rows)`, `publish_snapshot(artifact, *, on_publish=None, ...)`. +- Produces: `refresh_fssp_enforcement_proceedings(*, 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]`. +- Source/group/type: `fssp_enforcement_proceedings/enforcement_proceedings/enforcement_proceeding`. +- Возвращаемый artifact — aggregate manifest, metadata содержит два input artifact IDs, checksums, даты и counters. + +- [ ] Добавить регрессию: +```python +def test_second_input_failure_preserves_snapshot(): + before = list(OrganizationSourceRecord.objects.values_list("uid", "payload")) + with mock_second_download_failure(): + with pytest.raises(SnapshotValidationError): + refresh_fssp_enforcement_proceedings(load_batch=2) + assert list(OrganizationSourceRecord.objects.values_list("uid", "payload")) == before + +# Создать canonical org + прошлую запись в setup, network patches в этом module. +# Дополнительные tests: repeat_uuid_stable, two_inputs_manifest, +# duplicate_conflict_rejected, ambiguous_inn_quarantined, foreign_inn_skipped, +# no_new_organizations_or_legacy_writes, staging_chunks_at_most_500, +# failed_download_rejected, published_empty_distinct_from_failed. + +def test_conflicting_duplicate_blocks_publication(): + before = published_fssp_rows() + with conflicting_input_fixtures(): + with pytest.raises(SnapshotValidationError): + refresh_fssp_enforcement_proceedings(load_batch=2) + assert published_fssp_rows() == before + +def test_noncanonical_rows_do_not_create_organizations(): + before = Organization.objects.count() + artifact, result = refresh_with_foreign_and_ambiguous_inn() + assert Organization.objects.count() == before + assert result.skipped == 1 + assert result.quarantined == 1 + +# Helpers здесь patch actual two downloads; conflict fixture не имеет +# разрешённого паспортом правила приоритета. +``` +- [ ] Запустить `PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_fssp_snapshot.py -q`. До реализации ожидается FAIL: нет refresh/extension/enum. +- [ ] Загрузить оба inputs на диск через registry_http/save_artifact_file; проверять EOF/заявленную длину, schema и duplicate identity до publish. Stage только применимые/diagnostic rows batches <= SNAPSHOT_CHUNK_SIZE=500; дедупликацию большого набора выполнить в staging/БД, без полного dict всех строк. Добавить EnforcementProceedingExtension по существующему паттерну. Применить документированное правило конфликта Task 1; если паспорт не разрешает конфликт, reject aggregate. Финализатор вызвать внутри существующей транзакции publication. +- [ ] Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов. +- [ ] Проверить scoped diff и выполнить `git commit -m 'feat: publish complete FSSP snapshots atomically'`, добавляя только перечисленные файлы этого task. + +### Task 4: Публичный контракт, запуск и экспорт + +**Files:** +- Create: `src/organizations/fssp_payload_serializers.py` +- Modify: все integration files File map, `tools/openapi/source-record-extensions.json` +- Test: `tests/apps/parsers/test_fssp_refresh.py`, `tests/apps/organizations/test_fssp_contract.py` +- Extend: `tests/apps/parsers/test_refresh_concurrency.py`, `tests/apps/organizations/test_openapi_runtime_fixtures.py` + +**Interfaces:** +- Consumes: refresh Task 3, existing `_run_snapshot(task, *, source, refresh, requested_by_id, track_progress=False, mode=None) -> dict`. +- Produces: Celery `parse_fssp_enforcement_proceedings(self, *, requested_by_id: int | None = None) -> dict`, task name `parsers.fssp_enforcement_proceedings.refresh`. +- `FsspEnforcementProceedingPayloadSerializer` DRF fields exactly current Gleb contract; source card slug `fssp-enforcement-proceedings`. + +- [ ] Добавить регрессию: +```python +def test_source_mapping_is_exact(): + descriptor = get_source_group_descriptor("fssp_enforcement_proceedings") + assert descriptor.source_group == "enforcement_proceedings" + assert descriptor.record_type == "enforcement_proceeding" + +# Additional fixture-driven tests: +# list_detail_export_same_uid_and_signed_amount; required_payload_keys_nullable; +# record_date_equals_initiated_on; amount_equals_debt_not_claim; +# each frontend-documented filter/order; permission_denied; concurrent_refresh_409; +# failed_job_keeps_last_success_and_export_tickets; progress_and_manifest_counts. +# Load current Gleb schema read-only; copy its assertions into backend tests. +``` +- [ ] Запустить `PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_fssp_refresh.py tests/apps/organizations/test_fssp_contract.py tests/apps/parsers/test_refresh_concurrency.py -q`. До реализации ожидается FAIL: новый source mapping/refresh/payload отсутствует. +- [ ] Зарегистрировать source/card/group/task, расширить refresh concurrency guard для нового source. Добавить serializer discriminator/filter/order/export и backend runtime fixtures; source-specific signed money не менять у других групп. Public refresh не принимает file URL/path. Disabled schedule migration принадлежит этому task. Построить OpenAPI штатно по общему validation guide, не редактировать frontend. +- [ ] Повторить ту же команду. Ожидается PASS, без реальных upstream-запросов. +- [ ] Проверить scoped diff и выполнить `git commit -m 'feat: expose FSSP source APIs and exports'`, добавляя только перечисленные файлы этого task. + +### Task 5: Фактическая dev-приёмка + +**Files:** Update `docs/sources/fssp.md`. +**Interfaces:** consumes refresh Task 3 и API Task 4; produces evidence report и readiness verdict. + +- [ ] Выполнить общий validation guide из `2026-10-05-source-implementation.md`. +- [ ] Отдельно ограничить dev-контур и согласовать любые изменения удалённой БД; локальные unit tests не требуют этого. Выполнить полный реальный проход обоих inputs, включая большой CSV, без customer deployment. +- [ ] Зафиксировать checksums, даты, размеры, input/matched/skipped/quarantined/published counters, wall time, peak RSS и max staging batch. Сопоставить manifest/job/API/export; повторный импорт сохраняет UUID. Рост числа CSV строк не должен линейно увеличивать память reader/staging; память canonical index учитывать отдельно. +- [ ] Оставить schedule disabled; обозначить точный остаток при недоступности одного input. Commit только evidence/doc. Не заменять реальный acceptance синтетическим PASS. diff --git a/docs/superpowers/plans/2026-10-05-source-implementation.md b/docs/superpowers/plans/2026-10-05-source-implementation.md new file mode 100644 index 0000000..c642faf --- /dev/null +++ b/docs/superpowers/plans/2026-10-05-source-implementation.md @@ -0,0 +1,162 @@ +# ФССП → 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:** Каждый домен имеет самостоятельные adapters, fixtures и готовность. Общие API/jobs/export/OpenAPI изменяются последовательно, с регрессиями предыдущих доменов; единый новый ingestion framework не вводится. +**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 + +- Shared registry/discriminator теряет ранее добавленную группу: regression suite всех завершённых доменов (Integration Task). +- Generated contract расходится с runtime JSON: backend Orval/Zod gate сравнивает исходные ответы без потери ключей (Integration Task). +- Публикация вызывает stale exports: snapshot revision/ticket generation тестируются штатными export suites (Integration Task). +- Миграция включает сбор или меняет legacy schema: reviewed migration plan, disabled schedules и no-legacy tests (Integration Task). +- Нет фактического upstream доступа: отдельно status implemented/verified/ready; mocks не доказывают readiness (каждый acceptance task). + +--- + +## Стартовое состояние и порядок + +Согласованная письменная спецификация утверждена пользователем 5 октября 2026. +Backend branch `dev`, spec commit `764556f`; frontend `dev` обновлён до `74c0c3e`. +Это исходные проверенные ревизии, исполнителю повторно проверить live Git состояние. + +1. [ФССП](2026-10-05-fssp.md): паспорта двух входов → reader → aggregate snapshot → API → full dev acceptance. +2. [Checko](2026-10-05-checko-sections.md): доступ/API → adapters → monthly claims/scoped publish → API/completeness → paid dev acceptance. +3. [Биржи](2026-10-05-exchanges.md): verified channels/units → SPB/MOEX → combined snapshot → one API/export → full dev acceptance. +4. Integration Task ниже, затем отчёт готовности и пакет backend-контрактов для Глеба. Отправка Глебу не входит в этот план. + +Если upstream gate блокируется, фиксировать доказательство и продолжать независимый доступный slice. +Не выдавать blocked source за ready. Не публиковать dummy data на реальном source API. +Реализация не требует изменения frontend. Сгенерированный backend TypeScript находится только в backend tools. + +## Shared file ownership + +Доменные планы меняют общие файлы только после предыдущего: +`models.py` в обоих Django apps, `source_groups.py`, `source_registry.py`, +`source_cards.py`, `tasks_registry_snapshots.py`, parser `views.py/serializers.py`, +organization `serializers.py/source_record_query.py/source_record_export.py`, +`tools/openapi/source-record-extensions.json`, backend generated outputs. + +Domain-specific payload serializers и adapters не объединять в один огромный модуль. +Новые модели/choices добавлять штатными migrations, последовательные номера назначает +`makemigrations` на фактическом HEAD. Не переписывать применённые migrations. +Раздел Checko partial completion — единственное расширение общей job/card семантики; +прежние источники считаются full без нового metadata, backward compatibility тестируется. + +После model changes каждого domain task выполнить +`PYTHONPATH=src uv run --no-sync python src/manage.py makemigrations organizations parsers --name _sources --settings=settings.test`, +где domain ровно fssp/checko_sections/exchanges. Review включает автоматически назначенные +имена, зависимости и disabled schedule data migration. Не применять это к удалённой БД. +Commit step в каждом task: сначала `git add` точного списка его новых/изменённых файлов +и generated migration files, затем указанное сообщение; никогда `git add .`. + +## Integration Task: Проверки и совместимость + +**Files:** +- Modify: `tests/apps/organizations/test_openapi_runtime_fixtures.py`, `tools/openapi/source-record-extensions.json`. +- Extend: `tests/apps/organizations/test_canonical_openapi.py`, `test_source_record_export.py`, `test_source_export_snapshot_contract.py`. +- Extend: `tests/apps/parsers/test_snapshot_public_contract.py`, `test_snapshot_refresh_api.py`, `test_refresh_concurrency.py`, `test_snapshot_metadata.py`. +- Update: три `docs/sources/` документа; generated files только через build. + +**Interfaces:** +- Consumes три утверждённых domain plans; list/detail/contracts из serializers. +- Produces five discriminated source/group/type variants, runtime fixtures и readiness report. +- Рендер JSON → generated Zod validator → JSON: данные не теряются, не заменяются defaults. +- Legacy источники сохраняют прежние source IDs/permissions/money semantics. + +- [ ] Добавить cases пяти новых источников в runtime fixture generator. Для каждого list/detail: signed/null FSSP, empty/null Checko, две биржи с одним ISIN. Cases 400/403/404/409 добавить в документированный runtime flow соответствующих операций. +- [ ] Добавить contract assertion: +```python +def test_new_source_groups_in_canonical_schema(): + document = load_canonical_document() + for group in ("enforcement_proceedings", "leasing", "company_messages", + "company_licenses", "stock_exchange_activity"): + assert group in serialized_source_record_variants(document) + +# Helpers определить в существующем test module по структуре generated document; +# считать только list/detail source-record variants, не произвольное упоминание строки. +``` +- [ ] Запустить pytest runtime/canonical suites до regeneration: ожидается FAIL отсутствующих variants. +- [ ] Обновить serializers/annotations/variant extensions и штатно собрать контракт. Expected PASS по командам ниже; никаких frontend generators. +- [ ] Выполнить scoped diff review: exact identifiers, stable identities, failure rollback, nullable/signed data, permissions, no secrets, schedules disabled, exports pinned generations. Не включать прежние грязные файлы. +- [ ] Commit `test: verify integrated source runtime contracts` с точным списком изменённых tests/OpenAPI outputs/docs. + +## Validation commands + +В каждом домене сначала адресные pytest из его tasks. На integration boundary: + +```sh +PYTHONPATH=src uv run --no-sync python src/manage.py check --settings=settings.test +PYTHONPATH=src uv run --no-sync python src/manage.py makemigrations --check --dry-run --settings=settings.test +PYTHONPATH=src uv run --no-sync python src/manage.py migrate --plan --settings=settings.test +uv run --no-sync ruff check src +uv run --no-sync ruff format src --check +PYTHONPATH=src uv run --no-sync pytest tests/apps/parsers/test_snapshot_public_contract.py tests/apps/parsers/test_snapshot_refresh_api.py tests/apps/parsers/test_refresh_concurrency.py tests/apps/parsers/test_snapshot_metadata.py tests/apps/organizations/test_source_record_export.py tests/apps/organizations/test_source_export_snapshot_contract.py -q +PYTHONPATH=src uv run --no-sync python src/manage.py generate_swagger tools/openapi/swagger.json --overwrite --format=json --settings=settings.test +``` + +Из `tools/openapi`, существующие locked dependencies, без изменения lockfile: +```sh +bun install --frozen-lockfile --ignore-scripts +bun build.mjs +bun run apigen +bun run type-check +bun build.mjs --check +``` + +Из backend root: +```sh +OPENAPI_RUNTIME_FIXTURES=/tmp/mostovik-sources-runtime.json PYTHONPATH=src uv run --no-sync pytest tests/apps/organizations/test_canonical_openapi.py tests/apps/organizations/test_openapi_runtime_fixtures.py -q +PYTHONPATH=src uv run --no-sync pytest tests --ignore=tests/test_api_inventory_e2e.py -q +git diff --check +``` + +Из `tools/openapi`: `bun run contract-check /tmp/mostovik-sources-runtime.json`. + +Expected: exit 0, Django no issues/no pending model changes; Ruff clean; +pytest passed, OpenAPI validated, runtime validator preserves all original fields. +Сохранять фактические exit codes и errors: unavailable dependency/runtime ≠ PASS. +Перед broad suite подтвердить отсутствие live upstream и business DB в test config; +`test_checko_e2e.py` проверен: локальный TestHTTPServer, платных вызовов не делает. +`tests/test_api_inventory_e2e.py` проверять отдельно после проверки его isolated dependencies; +пропуск фиксировать в отчёте, не считать PASS. + +## Runtime acceptance and handoff + +Миграции на удалённой БД, paid Checko collection и любой выпуск — отдельные конкретные действия +в ограниченном dev-контуре. Текущий план их не выполняет автоматически. Перед таким действием +подготовить commands/scope/расход и проверить имеющееся разрешение; запросить только недостающий scope. + +Для каждого источника зафиксировать: +- implemented: код и адресные regression tests; +- verified: fixture/schema/OpenAPI/runtime/export checks; +- ready: реальный полный dev-сбор, checksum/date/counts/time/memory и доступный upstream. +Один источник бирж ready только при обоих adapters; Checko разделы имеют независимые verdicts. + +Пакет для frontend: source/group/type, endpoint operations, generated backend OpenAPI, +обезличенные list/detail/export examples, job counters и limitations. Не отправлять в Telegram, +не генерировать frontend client и не заявлять готовность UI. Не пушить/деплоить main/customer +без отдельного разрешённого этапа. + +## Self-review completed + +Планы покрывают spec sections 4–9: identity/quarantine, two-input provenance/rollback, +signed money/frontend contract, monthly claims/partial scope, exchange mapping/units, +permissions/concurrency/last_success/export/runtime contract. Upstream uncertainties spec §10 +вынесены в первые gates каждого domain plan. Все Review Focus условия привязаны к regressions. +Сигнатуры adapters и refresh workers указаны; внешние поля/маршруты определяются проверенным +mapping до implementation, а не догадкой. Продуктовый код в фазе планирования не меняется. diff --git a/docs/superpowers/specs/2026-10-05-fssp-checko-exchanges-design.md b/docs/superpowers/specs/2026-10-05-fssp-checko-exchanges-design.md index b6f9090..30c02f3 100644 --- a/docs/superpowers/specs/2026-10-05-fssp-checko-exchanges-design.md +++ b/docs/superpowers/specs/2026-10-05-fssp-checko-exchanges-design.md @@ -1,7 +1,7 @@ # ФССП, Checko и биржи: проектирование backend Mostovik Дата: 5 октября 2026, Europe/Madrid. -Статус: схема согласована пользователем; письменная спецификация ожидает проверки. +Статус: схема и письменная спецификация согласованы пользователем 5 октября 2026. Рабочая ветка: `dev`. База исследования: backend `fedd2e0`, frontend `74c0c3e`. ## 1. Цель и границы