gitadmin/dzentra_bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
dzentra_bot/docs/migrations/build_035.md

20 KiB
Raw Permalink Blame History

Build 035 — Перевод market runtime на Quotes Feed

Статус: Завершён
Подсистема: Market Data
Контур: Market Data Acquisition / Quotes Feed / Market Runtime
Проект: Dzentra
Язык документации: Русский

1. Цель Build

Цель Build 035 — перевести существующий WebSocket market runtime с самостоятельного legacy parsing рыночных сообщений на канонический контур обработки котировок, созданный в предыдущих Build.

До Build 035 runtime самостоятельно извлекал цены из WebSocket-сообщений Dzengi и передавал примитивные значения в legacy facade:

Dzengi WebSocket message
        ↓
legacy runtime parsing
        ↓
float price / bid / ask
        ↓
MarketPriceCache.set_price()
        ↓
Quote Store

После Build 035 рабочий runtime-путь использует специализированный WebSocket-адаптер и каноническую модель Quote:

Dzengi WebSocket message
        ↓
ExchangeWebSocketClient
        ↓
DzengiWebSocketQuoteAdapter
        ↓
canonical Quote
        ↓
MarketPriceCache.set_quote()
        ↓
Quote Store

Таким образом, WebSocket runtime больше не выполняет собственное преобразование транспортного формата Dzengi в набор примитивных ценовых значений.

2. Предпосылки

Build 035 опирается на результаты предыдущих этапов миграции.

Build 027

Создана каноническая модель:

Quote

Build 028

Созданы:

REST quote schema validation
REST quote parser
REST quote value validation

Build 029

Созданы:

REST quote mapper
DzengiQuoteDocumentHandler

Build 030

Создан полный REST Quotes Feed:

Dzengi REST ticker/24hr
        ↓
DzengiQuoteDocumentSource
        ↓
QuotesFeed
        ↓
QuoteAcquisitionService
        ↓
canonical Quote

Build 031

Новый REST Quotes Feed подключён под legacy ExchangeService facade.

Build 032

Создан канонический:

Quote Store

Build 033

MarketPriceCache переведён на использование Quote Store как внутреннего хранилища.

Build 034

Создан специализированный контур обработки WebSocket-котировок:

Dzengi WebSocket message
        ↓
schema validation
        ↓
parser
        ↓
value validation
        ↓
mapper
        ↓
DzengiWebSocketQuoteAdapter
        ↓
canonical Quote

Build 035 подключает этот контур к существующему market runtime.

3. Архитектурная проблема до Build 035

До Build 035 существовало несколько независимых путей обработки котировок.

REST-контур уже использовал каноническую модель:

REST ticker/24hr
        ↓
Quotes Feed
        ↓
Quote
        ↓
Quote Store

Но WebSocket runtime продолжал самостоятельно разбирать транспортные сообщения.

market_stream.py

Рабочий путь имел вид:

WebSocket message
        ↓
_payload_from_message()
        ↓
_extract_market_event()
        ↓
float price / bid / ask
        ↓
MarketPriceCache.set_price()

market_data_runner.py

Рабочий путь имел вид:

WebSocket message
        ↓
_extract_depth_payload()
        ↓
_extract_best_price()
        ↓
float midpoint
        ↓
MarketPriceCache.set_price()

Таким образом, логика понимания формата Dzengi WebSocket существовала одновременно:

в новом DzengiWebSocketQuoteAdapter
в market_stream.py
в market_data_runner.py

Это нарушало архитектурную границу:

transport-specific parsing
        ↓
только adapter layer

4. Архитектурный результат

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

ExchangeWebSocketClient
        ↓
decoded WebSocket message
        ↓
DzengiWebSocketQuoteAdapter
        ↓
canonical Quote
        ↓
MarketPriceCache compatibility facade
        ↓
Quote Store

Runtime больше не должен самостоятельно знать:

как устроены payload / Payload
как извлекается symbolName
как извлекаются bids / asks
какие варианты depth item поддерживает Dzengi
как вычисляется canonical last_price
как преобразуется timestamp

Эта ответственность принадлежит:

src/market_data/acquisition/adapters/dzengi/websocket.py

и связанному с ним контуру:

schema validation
parser
value validation
mapper

5. Изменённые production-файлы

В рамках Build 035 изменены:

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

6. Изменённые тестовые файлы

Расширены существующие тесты:

tests/unit/integrations/exchange/test_market_cache.py
tests/unit/integrations/exchange/test_market_stream.py
tests/unit/integrations/exchange/test_market_data_runner.py

Новые тестовые файлы не создавались.

7. Расширение MarketPriceCache

В MarketPriceCache добавлен новый метод:

@classmethod
def set_quote(
    cls,
    quote: Quote,
    *,
    runtime_key: str = "default",
) -> None:
    ...

Его задача — принять уже готовый канонический объект:

Quote

и записать его в существующее внутреннее хранилище через compatibility facade.

Цепочка:

canonical Quote
        ↓
MarketPriceCache.set_quote()
        ↓
Quote Store

8. Сохранение канонического Quote без повторного mapping

До Build 035 при наличии уже готового Quote потенциально мог возникнуть лишний цикл:

Quote
        ↓
float values
        ↓
MarketPriceCache.set_price()
        ↓
создание нового Quote
        ↓
Quote Store

После Build 035 используется прямой путь:

Quote
        ↓
MarketPriceCache.set_quote()
        ↓
Quote Store

При этом не требуется:

преобразовывать Decimal в float
повторно создавать Quote
повторно вычислять received_at
повторно преобразовывать exchange_timestamp
изменять source

Таким образом, сохраняется исходный канонический объект.

9. Сохранение legacy set_price()

Существующий публичный метод:

MarketPriceCache.set_price()

не удалён.

Это необходимо для сохранения обратной совместимости существующего бота и legacy-потребителей.

После Build 035 его архитектурная роль:

legacy primitive values
        ↓
MarketPriceCache.set_price()
        ↓
canonical Quote
        ↓
MarketPriceCache.set_quote()
        ↓
Quote Store

Таким образом, set_price() остаётся compatibility entry point, а непосредственная запись готового канонического объекта выполняется через:

set_quote()

10. Перевод market_stream.py

Рабочий WebSocket-путь market_stream.py переведён на:

ExchangeWebSocketClient.stream_depth()
        ↓
DzengiWebSocketQuoteAdapter.map_message()
        ↓
Quote
        ↓
MarketPriceCache.set_quote()

Новый runtime-путь больше не использует legacy-функцию:

_extract_market_event()

для обработки рабочих WebSocket-сообщений.

11. Проверка символа в market_stream.py

После получения канонического Quote выполняется проверка соответствия символа ожидаемому инструменту.

Концептуально:

requested symbol
        ↕
Quote.symbol

Если сообщение относится к другому инструменту, оно не должно записываться в runtime namespace.

Это предотвращает сохранение чужой котировки в контексте текущего WebSocket-потока.

12. Обработка невалидных сообщений в market_stream.py

Ошибка обработки отдельного WebSocket-сообщения не должна немедленно завершать весь market stream.

Ошибки канонического Acquisition-контура отдельного сообщения обрабатываются внутри цикла:

invalid WebSocket message
        ↓
DzengiWebSocketQuoteAdapter
        ↓
MarketDataAcquisitionError
        ↓
сообщение пропускается
        ↓
stream продолжает работу

При этом сетевые, transport и connection errors не маскируются этим механизмом и продолжают обрабатываться существующим reconnect-контуром.

13. Перевод MarketDataRunner

Основной WebSocket runtime в:

MarketDataRunner._run_websocket()

переведён с самостоятельного извлечения:

best_bid
best_ask

на канонический путь:

raw WebSocket payload
        ↓
DzengiWebSocketQuoteAdapter.map_message()
        ↓
Quote

После успешного mapping готовый объект записывается:

Quote
        ↓
MarketPriceCache.set_quote(
    runtime_key=context.runtime_key
)
        ↓
Quote Store

14. Runtime isolation

Сохраняется существующая изоляция runtime-контекстов через:

runtime_key

Примеры существующих runtime:

auto
debug_auto
default

При записи через:

MarketPriceCache.set_quote()

используется соответствующий:

context.runtime_key

Таким образом, котировки разных runtime не смешиваются.

15. Bid и ask после перехода на Quote

До Build 035 MarketDataRunner самостоятельно извлекал:

best_bid
best_ask

из сырого WebSocket payload.

После Build 035 эти значения берутся из уже проверенного канонического объекта:

Quote.bid_price
Quote.ask_price

Для legacy logging boundary при необходимости допускается преобразование:

Decimal → float

Но внутренний канонический объект остаётся основанным на:

Decimal

16. Last price для depth-сообщений

Согласно контракту Build 034 для WebSocket depth-сообщений:

last_price = midpoint(best_bid, best_ask)

После Build 035 runtime больше не должен самостоятельно повторять этот расчёт.

Он получает готовое значение:

Quote.last_price

из DzengiWebSocketQuoteAdapter.

Таким образом, правило определения last_price имеет одну каноническую реализацию.

17. Сохранение invalid payload semantics

До Build 035 MarketDataRunner поддерживал счётчик последовательных невалидных WebSocket-сообщений.

Существующая семантика сохранена:

invalid message
        ↓
invalid_payload_count += 1

Успешный Quote:

valid Quote
        ↓
invalid_payload_count = 0

После пяти последовательных невалидных сообщений:

5 consecutive invalid messages
        ↓
RuntimeError
        ↓
существующий fallback-контур

Таким образом, Build 035 не изменяет существующую политику деградации runtime.

18. REST fallback

REST fallback не потребовал изменения.

К моменту Build 035 REST-путь уже использует новый Quotes Feed:

Dzengi REST ticker/24hr
        ↓
DzengiQuoteDocumentSource
        ↓
QuotesFeed
        ↓
QuoteAcquisitionService
        ↓
canonical Quote
        ↓
MarketPriceCache facade
        ↓
Quote Store

После Build 035 WebSocket и REST-пути сходятся на одной канонической модели:

                    WebSocket
                        ↓
            DzengiWebSocketQuoteAdapter
                        ↓
                      Quote
                        ↓
                    Quote Store
                        ↑
                      Quote
                        ↑
               REST Quotes Feed
                        ↑
                       REST

19. Что намеренно не изменялось

В Build 035 не изменялись:

src/integrations/exchange/ws_client.py
src/market_data/acquisition/adapters/dzengi/websocket.py
src/market_data/acquisition/models/quote.py
src/storage/quote_store.py

Причина:

  • ws_client.py уже имеет достаточный transport-only контракт;
  • WebSocket-адаптер завершён в Build 034;
  • каноническая модель Quote не требует расширения;
  • Quote Store уже предоставляет необходимый контракт хранения.

20. Legacy parsing helpers

После перевода рабочего runtime-пути некоторые legacy helper-функции больше не являются частью основного пути обработки котировок.

В частности:

market_stream.py:
    _extract_market_event()

market_data_runner.py:
    _extract_best_price()

Они не удалены в Build 035.

Это намеренное решение.

Окончательная очистка legacy parsing относится к последующему этапу:

Build 039 — Удаление legacy quote parsing и MarketPriceCache

Build 035 меняет рабочий runtime-путь, но не выполняет преждевременную очистку compatibility layer.

21. Обратная совместимость

Build 035 сохраняет работоспособность существующего бота.

Не удалены:

MarketPriceCache
MarketPriceCache.set_price()
legacy read APIs
runtime_key isolation
REST fallback
существующие runtime lifecycle contracts

Это соответствует принятому принципу миграции Dzentra:

новый контур создаётся
        ↓
существующие потребители постепенно переключаются
        ↓
legacy удаляется только после завершения миграции

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

Выполнена команда:

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

Результат:

успешно

23. Специализированные тесты

Выполнена команда:

python -m pytest \
  tests/unit/integrations/exchange/test_market_cache.py \
  tests/unit/integrations/exchange/test_market_stream.py \
  tests/unit/integrations/exchange/test_market_data_runner.py \
  tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_quote_adapter.py \
  -q

Результат:

33 passed in 0.13s

24. Полная регрессия

Выполнена команда:

python -m pytest -q

Результат:

608 passed in 0.29s

Количество тестов до Build 035:

602 passed

Количество тестов после Build 035:

608 passed

Добавлено:

6 тестов

Полная регрессия подтверждает отсутствие обнаруженных регрессий в существующем коде проекта.

25. Итог Build

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

Реализованы:

подключение DzengiWebSocketQuoteAdapter к market_stream
подключение DzengiWebSocketQuoteAdapter к MarketDataRunner
передача canonical Quote непосредственно в compatibility facade
добавление MarketPriceCache.set_quote()
сохранение legacy MarketPriceCache.set_price()
сохранение runtime_key isolation
сохранение invalid payload semantics
сохранение REST fallback
сохранение обратной совместимости

Подтверждён новый рабочий WebSocket-путь:

ExchangeWebSocketClient
        ↓
DzengiWebSocketQuoteAdapter
        ↓
canonical Quote
        ↓
MarketPriceCache.set_quote()
        ↓
Quote Store

26. Архитектурное состояние после Build 035

После завершения Build 035 Dzentra имеет два канонических пути получения текущей котировки.

WebSocket

Dzengi WebSocket
        ↓
ExchangeWebSocketClient
        ↓
DzengiWebSocketQuoteAdapter
        ↓
Quote
        ↓
MarketPriceCache compatibility facade
        ↓
Quote Store

REST

Dzengi REST ticker/24hr
        ↓
DzengiQuoteDocumentSource
        ↓
QuotesFeed
        ↓
QuoteAcquisitionService
        ↓
Quote
        ↓
MarketPriceCache compatibility facade
        ↓
Quote Store

Таким образом, оба transport-пути приводят данные к единой канонической модели:

Quote

до передачи их потребителям.

27. Следующий Build

Следующий этап:

Build 036 — Перевод read-only и UI-потребителей

Его задача — определить и перевести read-only и UI-потребителей текущей рыночной котировки с legacy-представлений на канонический Quote и новый контур хранения там, где это архитектурно обосновано.

Build 036 должен выполняться без изменения execution semantics и без преждевременного удаления legacy compatibility layer.

Execution-потребители остаются отдельным последующим этапом миграции.

Reference in New Issue View Git Blame Copy Permalink