dzentra_bot/docs/migrations/build_023.md

Build 023 — Миграция runtime-потребителей на канонический Instrument Reference

Статус: ✅ Завершён
Дата: 2026-07-12
Подсистема: Exchange Integration
Этап: Instrument Reference Migration

---

Цель Build

Перевести runtime-компоненты получения рыночных данных на использование канонического справочника инструментов (Instrument Reference), полностью отказавшись от любых зависимостей от legacy-проекций ExchangeSymbol.

Build является логическим продолжением Build 022 и завершает миграцию всех runtime-потребителей ExchangeService.

---

Причина изменений

После завершения Build 022 основная логика ExchangeService уже использовала новый механизм:

Instrument Store
        ↓
get_instruments()
        ↓
validate_symbol()

Однако требовалось убедиться, что runtime-компоненты также используют исключительно новый контракт и не имеют скрытых зависимостей от legacy-моделей.

Проверке подлежали:

• market_stream.py
• market_data_runner.py

---

Выполненный анализ

Проведён аудит файлов:

src/integrations/exchange/market_stream.py
src/integrations/exchange/market_data_runner.py

Проверено использование:

• validate_symbol()
• normalized_symbol
• symbol_info
• get_exchange_symbols()
• ExchangeSymbol
• Instrument

---

Результаты анализа

Установлено следующее.

Market Stream

Используется:

validation = service.validate_symbol(...)

После успешной проверки используется:

validation.normalized_symbol

Объект symbol_info нигде не читается.

Модель ExchangeSymbol не используется.

Получение списка инструментов напрямую отсутствует.

---

Market Data Runner

Используется:

validation = ExchangeService().validate_symbol(...)

После успешной проверки используется:

validation.normalized_symbol

При ошибке валидации сохраняется безопасный fallback:

исходный symbol

Обращений к:

• symbol_info
• ExchangeSymbol
• get_exchange_symbols()

не обнаружено.

---

Изменения Production-кода

Изменения Production-кода не потребовались.

Build подтвердил, что оба runtime-компонента уже полностью соответствуют новой архитектуре Instrument Reference.

---

Добавлены Unit-тесты

Создан:

tests/unit/integrations/exchange/test_market_stream.py

Проверяются следующие сценарии.

Использование normalized_symbol

Проверяется, что WebSocket запускается для канонического символа.

---

Отсутствие зависимости от symbol_info

Проверяется отсутствие чтения:

validation.symbol_info

---

Обработка невалидного символа

Проверяется, что:

• WebSocket не создаётся;
• используется результат validate_symbol().

---

Exchange Disabled

Проверяется, что при отключённой бирже:

• ExchangeService не создаётся;
• runtime сразу завершается.

---

Использованы синхронные тесты через:

asyncio.run(...)

что позволило избежать зависимости проекта от pytest-asyncio.

---

Проверка Market Data Runner

Подтверждены существующие тесты:

tests/unit/integrations/exchange/test_market_data_runner.py

Проверяется:

• использование validate_symbol();
• использование normalized_symbol;
• отсутствие зависимости от symbol_info;
• fallback при ошибке;
• fallback при invalid symbol.

---

Проверка компиляции

Выполнено:

python -m py_compile \
  src/integrations/exchange/market_stream.py \
  src/integrations/exchange/market_data_runner.py \
  tests/unit/integrations/exchange/test_market_stream.py \
  tests/unit/integrations/exchange/test_market_data_runner.py

Результат:

Ошибок нет.

---

Проверка целевого набора тестов

Выполнено:

python -m pytest \
  tests/unit/integrations/exchange/test_market_stream.py \
  tests/unit/integrations/exchange/test_market_data_runner.py \
  tests/unit/integrations/exchange/test_service_validate_symbol.py \
  tests/unit/integrations/exchange/test_service_symbol_runtime_status.py \
  -q

Результат:

61 passed

---

Полный Regression Suite

Выполнено:

python -m pytest -q

Результат:

471 passed

---

Финальный аудит зависимостей

Выполнено:

grep -RIn \
  --exclude-dir="__pycache__" \
  --exclude="*.pyc" \
  -E "validate_symbol|symbol_info|get_instruments|get_exchange_symbols|ExchangeSymbol|Instrument" \
  src/integrations/exchange/market_stream.py \
  src/integrations/exchange/market_data_runner.py \
  tests/unit/integrations/exchange/test_market_stream.py \
  tests/unit/integrations/exchange/test_market_data_runner.py

Подтверждено:

Production-код использует только:

validate_symbol()

через:

normalized_symbol

Прямых зависимостей от:

• ExchangeSymbol
• get_exchange_symbols()
• symbol_info
• Instrument

не обнаружено.

---

Архитектурный итог

После Build 023 runtime-компоненты полностью используют канонический путь работы с инструментами:

Instrument Reference
        │
        ▼
Instrument Store
        │
        ▼
get_instruments()
        │
        ▼
validate_symbol()
        │
        ▼
normalized_symbol
        │
        ▼
Market Stream
Market Data Runner

Legacy-проекция ExchangeSymbol больше не участвует в работе runtime-компонентов.

---

Итог Build

Build 023 полностью завершён.

Подтверждено:

• runtime-компоненты используют канонический Instrument Reference;
• используется единая точка валидации символов через validate_symbol();
• используется только normalized_symbol;
• отсутствуют зависимости от ExchangeSymbol и symbol_info;
• Production-код соответствует новой архитектуре без дополнительных изменений;
• добавлены Unit-тесты для market_stream.py;
• подтверждена корректность market_data_runner.py;
• полный Regression Suite успешно пройден (471 passed).

Статус Build: ✅ Завершён.