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

13 KiB
Raw Blame History

ФССП → 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: Согласованная спецификация.

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. ФССП: паспорта двух входов → reader → aggregate snapshot → API → full dev acceptance.
  2. Checko: доступ/API → adapters → monthly claims/scoped publish → API/completeness → paid dev acceptance.
  3. Биржи: 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 <domain>_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:

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:

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:

bun install --frozen-lockfile --ignore-scripts
bun build.mjs
bun run apigen
bun run type-check
bun build.mjs --check

Из backend root:

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, а не догадкой. Продуктовый код в фазе планирования не меняется.