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

163 lines
13 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:** Каждый домен имеет самостоятельные 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 <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:
```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, а не догадкой. Продуктовый код в фазе планирования не меняется.