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

221 lines
18 KiB
Markdown
Raw 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.
# Биржи: единый источник 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:<verified vendor ID>`.
- 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:<vendor security ID>`.
- 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.