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,
+не затрагивая существующую архитектуру получения свечей.

docs/migrations/build_059_2.md

@@ -0,0 +1,420 @@
+# Build 059.2 — WebSocket OHLC Schema Validation
+
+**Проект:** Dzentra
+
+**Подсистема:** Market Data Acquisition
+
+**Этап:** 059.2
+
+**Статус:** Completed
+
+---
+
+# Цель
+
+Добавить структурную (schema) валидацию сообщений
+Dzengi WebSocket OHLC Market Data.
+
+На данном этапе выполняется исключительно проверка структуры
+полученного JSON.
+
+Никакой parser, предметная проверка значений,
+Decimal, datetime или mapping во внутренние модели
+ещё не выполняются.
+
+---
+
+# Причина изменения
+
+Во время Build 058 было подтверждено,
+что WebSocket OHLC использует отдельный runtime-протокол.
+
+После подписки
+
+```
+OHLCMarketData.subscribe
+```
+
+биржа начинает отправлять события
+
+```
+destination = ohlc.event
+```
+
+с payload следующего вида:
+
+```json
+{
+  "symbol": "BTC/USD_LEVERAGE",
+  "interval": "1m",
+  "type": "classic",
+  "t": 1784224740000,
+  "o": 63992.0,
+  "h": 64032.55,
+  "l": 63984.0,
+  "c": 64032.55
+}
+```
+
+До данного Build
+никакой schema validation
+для подобных сообщений в проекте не существовало.
+
+---
+
+# Реализовано
+
+Добавлена отдельная схема проверки
+WebSocket OHLC сообщений.
+
+Добавлены:
+
+```
+ValidatedWebSocketOhlcDocument
+```
+
+и
+
+```
+validate_dzengi_websocket_ohlc_schema()
+```
+
+в файл
+
+```
+src/market_data/acquisition/validation/schema.py
+```
+
+---
+
+# Проверяемые элементы
+
+Проверяется исключительно структура документа.
+
+Проверяются:
+
+- JSON object
+
+- наличие payload
+
+- наличие symbol
+
+- наличие interval
+
+- наличие type
+
+- наличие timestamp
+
+- наличие open
+
+- наличие high
+
+- наличие low
+
+- наличие close
+
+Никакие значения ещё не интерпретируются.
+
+Например,
+
+```
+t
+```
+
+может быть любым объектом.
+
+Его корректность будет проверяться
+на этапе Value Validation.
+
+---
+
+# Поддерживаемые оболочки
+
+Schema validator поддерживает все известные варианты,
+которые уже используются в проекте
+для остальных WebSocket Feed.
+
+Поддерживаются:
+
+## Без оболочки
+
+```json
+{
+    ...
+}
+```
+
+---
+
+## payload
+
+```json
+{
+    "payload": {
+        ...
+    }
+}
+```
+
+---
+
+## Payload
+
+```json
+{
+    "Payload": {
+        ...
+    }
+}
+```
+
+---
+
+## Двойная вложенность
+
+```json
+{
+    "payload": {
+        "payload": {
+            ...
+        }
+    }
+}
+```
+
+Такая логика полностью соответствует
+реализованной ранее
+для Quotes Feed.
+
+---
+
+# Что НЕ проверяется
+
+Schema Validation намеренно
+не проверяет:
+
+- формат символа
+
+- существование инструмента
+
+- допустимость интервала
+
+- допустимость типа свечи
+
+- положительность цен
+
+- порядок OHLC
+
+- timestamp
+
+Все перечисленные проверки
+относятся к следующему слою архитектуры
+(Value Validation).
+
+---
+
+# Новые исключения
+
+Добавлено специализированное исключение
+
+```
+CandleWebSocketSchemaError
+```
+
+в
+
+```
+src/market_data/acquisition/exceptions.py
+```
+
+Это исключение используется исключительно
+для структурных ошибок WebSocket OHLC.
+
+Ошибки структуры
+отделены
+от ошибок:
+
+- REST Candles
+
+- Quotes Feed
+
+- Instrument Feed
+
+---
+
+# Архитектурное разделение
+
+После Build 059.2
+конвейер имеет следующий вид:
+
+```
+WebSocket
+
+↓
+
+Schema Validation
+
+↓
+
+Parser
+
+↓
+
+Value Validation
+
+↓
+
+Mapping
+```
+
+Таким образом
+каждый слой
+остаётся полностью независимым.
+
+---
+
+# Unit Tests
+
+Добавлен новый файл
+
+```
+tests/unit/market_data/acquisition/validation/test_websocket_ohlc_schema.py
+```
+
+Проверяются:
+
+- корректное сообщение
+
+- отсутствие payload
+
+- отсутствие symbol
+
+- отсутствие interval
+
+- отсутствие type
+
+- отсутствие t
+
+- отсутствие o
+
+- отсутствие h
+
+- отсутствие l
+
+- отсутствие c
+
+- некорректный JSON object
+
+- вложенные payload
+
+- вложенные Payload
+
+- двойная вложенность
+
+- различные допустимые варианты структуры
+
+Всего реализовано:
+
+```
+20 unit tests
+```
+
+---
+
+# Проверка
+
+Выполнено:
+
+```bash
+python -m compileall \
+src/market_data/acquisition/exceptions.py \
+src/market_data/acquisition/validation/schema.py \
+tests/unit/market_data/acquisition/validation/test_websocket_ohlc_schema.py
+```
+
+Успешно.
+
+---
+
+Выполнено:
+
+```bash
+python -m pytest -q \
+tests/unit/market_data/acquisition/validation/test_websocket_ohlc_schema.py
+```
+
+Результат:
+
+```
+20 passed
+```
+
+---
+
+Выполнена регрессия
+всех schema validation:
+
+```bash
+python -m pytest -q \
+tests/unit/market_data/acquisition/validation/test_schema.py \
+tests/unit/market_data/acquisition/validation/test_quote_schema.py \
+tests/unit/market_data/acquisition/validation/test_candle_schema.py \
+tests/unit/market_data/acquisition/validation/test_websocket_quote_schema.py \
+tests/unit/market_data/acquisition/validation/test_websocket_ohlc_schema.py
+```
+
+Результат:
+
+```
+80 passed
+```
+
+---
+
+Также выполнено:
+
+```bash
+git diff --check
+```
+
+Ошибок форматирования не обнаружено.
+
+---
+
+# Совместимость
+
+Изменение полностью обратно совместимо.
+
+Не изменены:
+
+- REST Candles Feed
+
+- Quotes Feed
+
+- ExchangeService
+
+- runtime
+
+- Market Analysis
+
+- Trading
+
+---
+
+# Итог
+
+Build 059.2 завершает создание полноценного
+структурного слоя проверки сообщений
+Dzengi WebSocket OHLC.
+
+После данного этапа
+проект способен безопасно принимать
+и структурно валидировать
+входящие сообщения `ohlc.event`,
+не выполняя их предметной интерпретации.
+
+Следующим этапом является Build 059.3 —
+Parser, который будет преобразовывать
+структурно проверенный документ
+в транспортную модель
+`DzengiWebSocketOhlcEvent`.