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