build 059.1-059.2: add websocket OHLC transport and schema validation

docs/migrations/build_059_1.md

@@ -0,0 +1,223 @@
+# Build 059.1 — WebSocket OHLC Transport Model
+
+**Проект:** Dzentra
+
+**Подсистема:** Market Data Acquisition
+
+**Этап:** 059.1
+
+**Статус:** Completed
+
+---
+
+# Цель
+
+Начать интеграцию WebSocket OHLC Market Data Dzengi без изменения существующего
+REST Candles Feed.
+
+На данном этапе реализуется исключительно транспортная модель входящего
+WebSocket-события.
+
+Никакой parser, validation, mapping или runtime-интеграция ещё не
+добавляются.
+
+---
+
+# Причина изменения
+
+Во время Build 058 было экспериментально подтверждено, что Dzengi публикует
+закрытые свечи через отдельный WebSocket endpoint:
+
+```
+destination = OHLCMarketData.subscribe
+```
+
+После успешной подписки сервер начинает отправлять события
+
+```
+destination = ohlc.event
+```
+
+Каждое событие содержит завершённую свечу без объёма.
+
+Следовательно использовать существующую модель Candle невозможно, поскольку
+она требует наличие volume.
+
+Необходимо отдельное транспортное представление события.
+
+---
+
+# Реализовано
+
+Добавлена новая immutable transport model
+
+```
+DzengiWebSocketOhlcEvent
+```
+
+в
+
+```
+src/market_data/acquisition/adapters/dzengi/models.py
+```
+
+---
+
+# Структура модели
+
+Модель содержит только поля,
+которые реально присутствуют в runtime-сообщении Dzengi.
+
+```
+symbol
+interval
+candle_type
+
+open_time
+
+open_price
+high_price
+low_price
+close_price
+```
+
+Все числовые поля используют существующий тип
+
+```
+DzengiRawNumeric
+```
+
+что полностью соответствует остальным transport-моделям адаптера.
+
+---
+
+# Почему это transport model
+
+Данная модель не является внутренней моделью системы.
+
+Она не содержит:
+
+- Decimal
+
+- datetime
+
+- volume
+
+- source
+
+- timezone
+
+- внутренних типов Dzentra
+
+Модель лишь отражает формат,
+в котором сообщение приходит от биржи.
+
+Все предметные преобразования будут выполняться
+на последующих этапах.
+
+---
+
+# Почему нельзя использовать Candle
+
+Во время исследования Build 058 было подтверждено:
+
+WebSocket OHLC не содержит volume.
+
+Каноническая модель
+
+```
+Candle
+```
+
+обязательно содержит
+
+```
+volume
+```
+
+Следовательно создание Candle непосредственно из WebSocket-события
+нарушило бы архитектурный контракт подсистемы.
+
+---
+
+# Архитектурное решение
+
+Архитектура остаётся прежней:
+
+```
+WebSocket
+
+↓
+
+Transport Model
+
+↓
+
+Schema Validation
+
+↓
+
+Parser
+
+↓
+
+Value Validation
+
+↓
+
+Internal Close Event
+
+↓
+
+REST reconciliation
+
+↓
+
+Canonical Candle
+```
+
+Таким образом WebSocket остаётся источником уведомления
+о закрытии свечи,
+
+а REST остаётся источником канонической OHLCV-свечи.
+
+---
+
+# Совместимость
+
+Изменение полностью обратно совместимо.
+
+Не изменены:
+
+- REST Candles Feed
+
+- Quote Feed
+
+- ExchangeService
+
+- runtime
+
+- Market Analysis
+
+- Trading
+
+---
+
+# Проверка
+
+Выполнено:
+
+```
+python -m compileall \
+src/market_data/acquisition/adapters/dzengi/models.py
+```
+
+Импорт модели успешно выполняется.
+
+---
+
+# Итог
+
+Build 059.1 завершает создание транспортного слоя
+для будущей интеграции WebSocket OHLC,
+не затрагивая существующую архитектуру получения свечей.