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