Build 060.7: implement REST Trade Adapter

docs/migrations/build_060_5.md

@@ -0,0 +1,328 @@
+# Build 060.5 — REST Trade Value Validation
+
+## Цель
+
+Реализовать слой проверки допустимости значений (`Value Validation`) для REST aggTrades после завершения этапов структурной проверки (`Schema Validation`) и преобразования в transport-модели (`REST Parser`).
+
+Build завершает третий этап конвейера обработки REST Trades и обеспечивает, что все transport-модели содержат только корректные значения перед передачей в Mapper.
+
+---
+
+# Место Build в общей архитектуре
+
+До Build 060.5 конвейер выглядел следующим образом:
+
+```text
+REST JSON
+        │
+        ▼
+Schema Validation
+        │
+        ▼
+ValidatedRestAggTradesDocument
+        │
+        ▼
+REST Parser
+        │
+        ▼
+tuple[DzengiRestAggTrade]
+```
+
+После Build 060.5:
+
+```text
+REST JSON
+        │
+        ▼
+Schema Validation
+        │
+        ▼
+ValidatedRestAggTradesDocument
+        │
+        ▼
+REST Parser
+        │
+        ▼
+tuple[DzengiRestAggTrade]
+        │
+        ▼
+REST Trade Value Validation
+        │
+        ▼
+tuple[DzengiRestAggTrade]
+```
+
+Следующим этапом станет:
+
+```text
+Mapper
+        │
+        ▼
+Canonical Trade
+```
+
+---
+
+# Архитектурная ответственность
+
+Value Validation отвечает исключительно за проверку допустимости значений transport-моделей.
+
+Validator:
+
+- не изменяет transport-модель;
+- не выполняет mapping;
+- не преобразует данные в canonical-модель;
+- не нормализует значения;
+- не возвращает преобразованные объекты.
+
+При успешной проверке функция завершается без результата.
+
+При обнаружении ошибки выбрасывается специализированное исключение.
+
+---
+
+# Добавлено новое исключение
+
+Файл:
+
+```text
+src/market_data/acquisition/exceptions.py
+```
+
+Добавлено:
+
+```python
+TradeValueError
+```
+
+Назначение:
+
+- ошибки проверки допустимости значений REST Trade transport-моделей.
+
+---
+
+# Новый публичный API
+
+Файл:
+
+```text
+src/market_data/acquisition/validation/values.py
+```
+
+Добавлена функция:
+
+```python
+validate_rest_agg_trade_values(
+    trades: tuple[DzengiRestAggTrade, ...],
+) -> None
+```
+
+Ответственность функции:
+
+- проверить все transport-модели;
+- при первой ошибке выбросить `TradeValueError`;
+- при отсутствии ошибок успешно завершиться.
+
+---
+
+# Внутренняя архитектура
+
+Реализация построена по тому же принципу, что уже используется для Instrument, Quote и Candle.
+
+```text
+validate_rest_agg_trade_values()
+                │
+                ▼
+    _validate_rest_agg_trade()
+                │
+                ├────────────► _trade_positive_int()
+                ├────────────► _trade_positive_decimal()
+                └────────────► _trade_decimal()
+```
+
+Каждая helper-функция отвечает только за одну проверку.
+
+---
+
+# Проверяемые поля
+
+## aggregate_trade_id
+
+Проверяется:
+
+- тип int (bool исключается);
+- значение больше нуля.
+
+---
+
+## price
+
+Проверяется:
+
+- успешное преобразование в Decimal;
+- конечность числа;
+- значение больше нуля.
+
+Поддерживаются значения:
+
+- str
+- int
+- float
+
+---
+
+## quantity
+
+Проверяется аналогично полю price.
+
+---
+
+## timestamp
+
+Проверяется:
+
+- тип int (bool исключается);
+- значение больше нуля.
+
+---
+
+## buyer_is_maker
+
+Дополнительная проверка отсутствует.
+
+Корректность типа bool уже гарантируется предыдущим этапом — REST Parser.
+
+---
+
+# Что НЕ входит в Value Validation
+
+Build сознательно не выполняет:
+
+- преобразование transport-моделей;
+- mapping;
+- создание Canonical Trade;
+- преобразование чисел в Decimal для дальнейшей обработки;
+- проверку возраста сделки;
+- проверку порядка timestamp;
+- проверку последовательности aggregateTradeId;
+- проверку дубликатов.
+
+Все перечисленные задачи относятся к последующим слоям Acquisition Pipeline.
+
+---
+
+# Диагностика ошибок
+
+Все сообщения содержат полный путь до ошибочного поля.
+
+Примеры:
+
+```text
+$[0].price должно быть больше нуля.
+
+$[1].quantity должно быть корректным числом.
+
+$[2].timestamp должно быть целым числом больше нуля.
+```
+
+Такой формат полностью соответствует существующей архитектуре Validation Layer.
+
+---
+
+# Unit Tests
+
+Добавлены тесты для:
+
+## Позитивных сценариев
+
+- одна корректная сделка;
+- несколько корректных сделок;
+- пустой tuple;
+- строковые числовые значения;
+- int;
+- float;
+- оба значения buyer_is_maker.
+
+---
+
+## Негативных сценариев
+
+Проверяются:
+
+- aggregate_trade_id ≤ 0;
+- timestamp ≤ 0;
+- price ≤ 0;
+- quantity ≤ 0;
+- NaN;
+- Infinity;
+- -Infinity;
+- некорректные числовые строки;
+- корректное формирование пути ошибки.
+
+---
+
+# Результаты проверки
+
+Target tests:
+
+```text
+68 passed
+```
+
+Полная регрессия проекта:
+
+```text
+1072 passed
+```
+
+Дополнительно выполнено:
+
+```text
+python -m compileall src
+```
+
+Результат:
+
+```text
+OK
+```
+
+Также выполнено:
+
+```text
+git diff --check
+```
+
+Ошибок форматирования не обнаружено.
+
+---
+
+# Архитектурный результат Build
+
+После завершения Build 060.5 REST Trades получили полностью независимый трехуровневый pipeline проверки данных.
+
+```text
+REST JSON
+        │
+        ▼
+Schema Validation
+        │
+        ▼
+ValidatedRestAggTradesDocument
+        │
+        ▼
+REST Parser
+        │
+        ▼
+tuple[DzengiRestAggTrade]
+        │
+        ▼
+REST Trade Value Validation
+        │
+        ▼
+tuple[DzengiRestAggTrade]
+```
+
+Каждый этап отвечает исключительно за собственную область ответственности.
+
+Следующий Build (060.6) впервые переведет transport-модели в внутреннюю каноническую модель `Trade`, независимую от конкретной биржи.