build 059.6: map websocket OHLC close events

2026-07-17 09:59:11 +03:00
parent 5c7ecf9340
commit 85e9662f5b
4 changed files with 1158 additions and 0 deletions
--- a/docs/migrations/build_059_6.md
+++ b/docs/migrations/build_059_6.md
@@ -0,0 +1,797 @@
+# Build 059.6 — WebSocket OHLC Mapper
+
+**Проект:** Dzentra
+**Подсистема:** Market Data Acquisition
+**Этап:** 059.6
+**Статус:** Completed
+
+---
+
+# Цель
+
+Реализовать преобразование проверенного WebSocket OHLC-события Dzengi во внутреннюю модель Dzentra:
+
+```text
+CandleCloseEvent
+```
+
+Mapper должен стать последней стадией обработки WebSocket-сообщения перед передачей события во внутренний runtime.
+
+---
+
+# Причина изменения
+
+После завершения Build 059.5 система уже содержит:
+
+```text
+Raw WebSocket JSON
+        ↓
+Schema Validation
+        ↓
+ValidatedWebSocketOhlcDocument
+        ↓
+Parser
+        ↓
+DzengiWebSocketOhlcEvent
+        ↓
+Value Validation
+```
+
+Однако transport-модель адаптера:
+
+```text
+DzengiWebSocketOhlcEvent
+```
+
+не должна использоваться за пределами слоя интеграции с Dzengi.
+
+Для внутренних компонентов требуется полностью source-independent модель:
+
+```text
+CandleCloseEvent
+```
+
+Build 059.6 добавляет именно этот переход.
+
+---
+
+# Реализовано
+
+Изменены файлы:
+
+```text
+src/market_data/acquisition/adapters/dzengi/mapper.py
+src/market_data/acquisition/exceptions.py
+```
+
+Создан файл:
+
+```text
+tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_ohlc_mapper.py
+```
+
+---
+
+# Новый mapper
+
+Добавлена функция:
+
+```text
+map_dzengi_websocket_ohlc_to_candle_close_event()
+```
+
+Назначение функции:
+
+```text
+DzengiWebSocketOhlcEvent
+        ↓
+CandleCloseEvent
+```
+
+Mapper предполагает, что ранее уже были выполнены:
+
+- schema validation;
+- parsing;
+- value validation.
+
+Повторная проверка предметной корректности данных не выполняется.
+
+---
+
+# Выполняемые преобразования
+
+Mapper выполняет только преобразования типов.
+
+## Timestamp
+
+Поле:
+
+```text
+t
+```
+
+преобразуется из:
+
+```text
+int (milliseconds)
+```
+
+в:
+
+```text
+datetime (UTC)
+```
+
+---
+
+## OHLC
+
+Поля:
+
+```text
+o
+h
+l
+c
+```
+
+преобразуются из:
+
+```text
+str | int | float
+```
+
+в:
+
+```text
+Decimal
+```
+
+Все вычисления внутри runtime далее выполняются только с использованием `Decimal`.
+
+---
+
+## received_at
+
+Mapper принимает дополнительный аргумент:
+
+```text
+received_at
+```
+
+Тип:
+
+```text
+datetime
+```
+
+Обязательное требование:
+
+```text
+timezone-aware datetime
+```
+
+Naive datetime считается ошибкой mapper.
+
+---
+
+## source
+
+Mapper автоматически устанавливает источник:
+
+```text
+dzengi_websocket_ohlc
+```
+
+Тем самым внутренние модели больше не зависят от транспортного контракта адаптера.
+
+---
+
+# Новый тип ошибки
+
+Добавлено исключение:
+
+```text
+CandleWebSocketMappingError
+```
+
+Исключение используется исключительно на этапе mapping.
+
+Это позволяет разделить ошибки различных стадий обработки.
+
+Схема обработки стала следующей:
+
+```text
+Transport
+        ↓
+CandleTransportError
+
+Schema
+        ↓
+CandleWebSocketSchemaError
+
+Parser
+        ↓
+CandleWebSocketParseError
+
+Value Validation
+        ↓
+CandleWebSocketValueError
+
+Mapper
+        ↓
+CandleWebSocketMappingError
+```
+
+Таким образом каждая стадия имеет собственный независимый контракт ошибок.
+
+---
+
+# Почему не используется CandleMappingError
+
+В проекте уже существует:
+
+```text
+CandleMappingError
+```
+
+Однако он относится исключительно к REST Candles Feed.
+
+REST mapper строит:
+
+```text
+Canonical Candle
+```
+
+WebSocket mapper строит:
+
+```text
+CandleCloseEvent
+```
+
+Это разные сущности.
+
+Использование общего исключения привело бы к смешиванию двух различных контрактов.
+
+Поэтому был введён отдельный тип ошибки.
+
+---
+
+# Использование существующих helper-функций
+
+В mapper уже присутствуют helper-функции для REST-свечей.
+
+Например:
+
+```text
+_required_candle_decimal()
+```
+
+Они намеренно не переиспользуются.
+
+Причина:
+
+они выбрасывают:
+
+```text
+CandleMappingError
+```
+
+WebSocket mapper обязан выбрасывать:
+
+```text
+CandleWebSocketMappingError
+```
+
+Поэтому были реализованы отдельные helper-функции.
+
+---
+
+# Новые helper-функции
+
+Добавлены:
+
+```text
+_required_websocket_ohlc_decimal()
+
+_websocket_ohlc_timestamp_ms_to_utc_datetime()
+
+_require_websocket_ohlc_aware_datetime()
+```
+
+Они полностью изолированы от REST mapper.
+
+Это исключает смешивание различных источников данных и их контрактов.
+
+---
+
+# Преобразование времени
+
+Поле:
+
+```text
+t
+```
+
+содержит Unix timestamp в миллисекундах.
+
+Mapper преобразует его через:
+
+```python
+datetime.fromtimestamp(
+    value / 1000,
+    tz=timezone.utc,
+)
+```
+
+В результате:
+
+```text
+open_time
+```
+
+становится объектом:
+
+```text
+datetime UTC
+```
+
+Внутренние слои больше не работают с миллисекундными timestamp.
+
+---
+
+# Преобразование Decimal
+
+Каждое поле:
+
+```text
+open
+high
+low
+close
+```
+
+проходит преобразование:
+
+```text
+str | int | float
+        ↓
+Decimal
+```
+
+Дополнительно проверяется:
+
+- корректность числа;
+- конечность значения.
+
+---
+
+# Контракт mapper
+
+Mapper не выполняет:
+
+- schema validation;
+- parsing;
+- value validation;
+- REST reconciliation;
+- получение объёма;
+- создание канонической `Candle`.
+
+Единственная задача mapper:
+
+```text
+построить внутреннюю модель
+CandleCloseEvent
+из уже проверенного
+DzengiWebSocketOhlcEvent
+```
+
+---
+
+# Что mapper НЕ делает
+
+Mapper намеренно не выполняет следующие действия.
+
+## Не создаёт volume
+
+Фактический runtime-контракт Dzengi содержит:
+
+```text
+symbol
+interval
+type
+t
+o
+h
+l
+c
+```
+
+Поля:
+
+```text
+volume
+```
+
+не существует.
+
+Поэтому mapper не должен:
+
+- подставлять `0`;
+- использовать `None`;
+- вычислять объём самостоятельно.
+
+Полный объём будет получен позднее через REST reconciliation.
+
+---
+
+## Не создаёт Candle
+
+Mapper не строит:
+
+```text
+Candle
+```
+
+Причина проста.
+
+Каноническая модель требует:
+
+```text
+volume
+```
+
+которого WebSocket не содержит.
+
+Следовательно единственным корректным результатом mapper является:
+
+```text
+CandleCloseEvent
+```
+
+---
+
+## Не выполняет REST reconciliation
+
+Build 059.6 заканчивается на построении внутреннего события.
+
+Дальнейший pipeline выглядит следующим образом:
+
+```text
+CandleCloseEvent
+        ↓
+REST reconciliation
+        ↓
+Canonical Candle
+```
+
+Сам reconciliation будет реализован отдельным этапом.
+
+---
+
+# Поддерживаемые типы свечей
+
+Mapper сохраняет значение:
+
+```text
+candle_type
+```
+
+без изменения.
+
+Поддерживаемые runtime-значения:
+
+```text
+classic
+heikin-ashi
+```
+
+Mapper не интерпретирует содержимое свечи.
+
+Он лишь переносит значение в внутреннюю модель.
+
+---
+
+# Обработка received_at
+
+Поле:
+
+```text
+received_at
+```
+
+не вычисляется автоматически.
+
+Оно передаётся извне.
+
+Это решение позволяет:
+
+- использовать единый момент получения сообщения;
+- исключить влияние задержек внутри mapper;
+- обеспечить единый источник времени для всей системы.
+
+Mapper только проверяет:
+
+```text
+timezone-aware datetime
+```
+
+Naive datetime приводит к ошибке:
+
+```text
+CandleWebSocketMappingError
+```
+
+---
+
+# Конвейер после Build 059.6
+
+После завершения этапа полный pipeline выглядит следующим образом:
+
+```text
+Raw WebSocket message
+        ↓
+Schema Validation
+        ↓
+ValidatedWebSocketOhlcDocument
+        ↓
+Parser
+        ↓
+DzengiWebSocketOhlcEvent
+        ↓
+Value Validation
+        ↓
+Mapper
+        ↓
+CandleCloseEvent
+```
+
+На этом Build 059.6 завершается.
+
+Следующий этап добавит использование новой модели внутри runtime.
+
+---
+
+# Unit Tests
+
+Создан файл:
+
+```text
+tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_ohlc_mapper.py
+```
+
+Проверяются:
+
+- построение `CandleCloseEvent`;
+- преобразование всех полей;
+- преобразование timestamp;
+- преобразование числовых типов в `Decimal`;
+- сохранение `received_at`;
+- поддержка `heikin-ashi`;
+- обрезка пробелов у symbol;
+- проверка timezone-aware datetime;
+- ошибка при невозможности преобразовать timestamp;
+- ошибка при некорректном Decimal;
+- ошибка при бесконечных значениях (`NaN`, `Infinity`);
+- отсутствие создания `volume`.
+
+Всего выполнено:
+
+```text
+16 tests
+```
+
+---
+
+# Проверка синтаксиса
+
+Выполнена команда:
+
+```bash
+python -m compileall \
+  src/market_data/acquisition/exceptions.py \
+  src/market_data/acquisition/adapters/dzengi/mapper.py \
+  tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_ohlc_mapper.py
+```
+
+Результат:
+
+```text
+успешно
+```
+
+---
+
+# Целевые тесты
+
+Выполнена команда:
+
+```bash
+python -m pytest -q \
+  tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_ohlc_mapper.py
+```
+
+Результат:
+
+```text
+16 passed
+```
+
+---
+
+# Регрессия mapper
+
+Выполнена команда:
+
+```bash
+python -m pytest -q \
+  tests/unit/market_data/acquisition/adapters/dzengi/test_mapper.py \
+  tests/unit/market_data/acquisition/adapters/dzengi/test_quote_mapper.py \
+  tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_quote_mapper.py \
+  tests/unit/market_data/acquisition/adapters/dzengi/test_candle_mapper.py \
+  tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_ohlc_mapper.py
+```
+
+Результат:
+
+```text
+52 passed
+```
+
+---
+
+# Дополнительная регрессия
+
+Выполнена команда:
+
+```bash
+python -m pytest -q \
+  tests/unit/market_data/acquisition/models \
+  tests/unit/market_data/acquisition/validation/test_websocket_ohlc_values.py
+```
+
+Результат:
+
+```text
+126 passed
+```
+
+---
+
+# Проверка форматирования
+
+Выполнена команда:
+
+```bash
+git diff --check
+```
+
+Ошибок форматирования не обнаружено.
+
+---
+
+# Изменённые файлы
+
+```text
+src/market_data/acquisition/adapters/dzengi/mapper.py
+
+src/market_data/acquisition/exceptions.py
+```
+
+Создан файл:
+
+```text
+tests/unit/market_data/acquisition/adapters/dzengi/test_websocket_ohlc_mapper.py
+```
+
+Документация:
+
+```text
+docs/migrations/build_059_6.md
+```
+
+---
+
+# Совместимость
+
+Build 059.6 полностью обратно совместим.
+
+Не изменены:
+
+- REST Candles Feed;
+- REST Candle mapper;
+- Quote mapper;
+- Instrument mapper;
+- ExchangeService;
+- runtime;
+- Trading;
+- Market Analysis;
+- каноническая модель `Candle`.
+
+Новый mapper пока не используется существующим runtime и не влияет на работу действующего торгового бота.
+
+---
+
+# Архитектурное значение
+
+Build 059.6 завершает формирование полного внутреннего конвейера преобразования WebSocket OHLC.
+
+После этого этапа система имеет чёткое разделение уровней ответственности:
+
+```text
+Transport Layer
+        │
+        ▼
+DzengiWebSocketOhlcEvent
+        │
+        ▼
+Validation Layer
+        │
+        ▼
+Mapper Layer
+        │
+        ▼
+CandleCloseEvent
+```
+
+Каждый уровень отвечает только за собственную задачу:
+
+| Уровень | Ответственность |
+|---------|-----------------|
+| Schema Validation | Проверка структуры входящего сообщения |
+| Parser | Построение transport-модели |
+| Value Validation | Проверка допустимости значений |
+| Mapper | Преобразование transport-модели во внутреннюю модель |
+| Runtime | Использование внутренней модели |
+
+Такое разделение соответствует общей архитектуре Dzentra и исключает смешивание обязанностей между слоями.
+
+---
+
+# Ограничения этапа
+
+Build 059.6 намеренно **не реализует**:
+
+- подписку на WebSocket;
+- публикацию события в runtime;
+- REST reconciliation;
+- получение объёма свечи;
+- создание канонической `Candle`;
+- проверку соответствия REST и WebSocket OHLC;
+- восстановление после разрыва соединения;
+- повторную синхронизацию истории свечей.
+
+Все перечисленные задачи относятся к последующим этапам Build 059.
+
+---
+
+# Итог
+
+Build 059.6 добавляет полноценный mapper:
+
+```text
+DzengiWebSocketOhlcEvent
+        ↓
+CandleCloseEvent
+```
+
+В результате система получила:
+
+- источник-независимую внутреннюю модель события закрытия свечи;
+- корректное преобразование timestamp в `datetime (UTC)`;
+- преобразование цен в `Decimal`;
+- собственный контракт ошибок (`CandleWebSocketMappingError`);
+- полную изоляцию WebSocket-контракта Dzengi от внутренних компонентов Dzentra;
+- набор unit-тестов, подтверждающих корректность преобразования и обработки ошибок.
+
+После Build 059.6 цепочка обработки WebSocket OHLC стала полностью завершённой вплоть до внутреннего события Dzentra.
+
+---
+
+# Следующий этап
+
+```text
+Build 059.7 — WebSocket Adapter
+```
+
+На этом этапе новый mapper будет встроен в адаптер получения рыночных данных, чтобы при поступлении подтверждённого WebSocket OHLC-сообщения формировался `CandleCloseEvent`, который затем сможет быть передан в механизм REST reconciliation.