dzentra_bot/docs/migrations/build_060_5.md

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 конвейер выглядел следующим образом:

REST JSON
        │
        ▼
Schema Validation
        │
        ▼
ValidatedRestAggTradesDocument
        │
        ▼
REST Parser
        │
        ▼
tuple[DzengiRestAggTrade]

После Build 060.5:

REST JSON
        │
        ▼
Schema Validation
        │
        ▼
ValidatedRestAggTradesDocument
        │
        ▼
REST Parser
        │
        ▼
tuple[DzengiRestAggTrade]
        │
        ▼
REST Trade Value Validation
        │
        ▼
tuple[DzengiRestAggTrade]

Следующим этапом станет:

Mapper
        │
        ▼
Canonical Trade

---

Архитектурная ответственность

Value Validation отвечает исключительно за проверку допустимости значений transport-моделей.

Validator:

• не изменяет transport-модель;
• не выполняет mapping;
• не преобразует данные в canonical-модель;
• не нормализует значения;
• не возвращает преобразованные объекты.

При успешной проверке функция завершается без результата.

При обнаружении ошибки выбрасывается специализированное исключение.

---

Добавлено новое исключение

Файл:

src/market_data/acquisition/exceptions.py

Добавлено:

TradeValueError

Назначение:

• ошибки проверки допустимости значений REST Trade transport-моделей.

---

Новый публичный API

Файл:

src/market_data/acquisition/validation/values.py

Добавлена функция:

validate_rest_agg_trade_values(
    trades: tuple[DzengiRestAggTrade, ...],
) -> None

Ответственность функции:

• проверить все transport-модели;
• при первой ошибке выбросить TradeValueError;
• при отсутствии ошибок успешно завершиться.

---

Внутренняя архитектура

Реализация построена по тому же принципу, что уже используется для Instrument, Quote и Candle.

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.

---

Диагностика ошибок

Все сообщения содержат полный путь до ошибочного поля.

Примеры:

$[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:

68 passed

Полная регрессия проекта:

1072 passed

Дополнительно выполнено:

python -m compileall src

Результат:

OK

Также выполнено:

git diff --check

Ошибок форматирования не обнаружено.

---

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

После завершения Build 060.5 REST Trades получили полностью независимый трехуровневый pipeline проверки данных.

REST JSON
        │
        ▼
Schema Validation
        │
        ▼
ValidatedRestAggTradesDocument
        │
        ▼
REST Parser
        │
        ▼
tuple[DzengiRestAggTrade]
        │
        ▼
REST Trade Value Validation
        │
        ▼
tuple[DzengiRestAggTrade]

Каждый этап отвечает исключительно за собственную область ответственности.

Следующий Build (060.6) впервые переведет transport-модели в внутреннюю каноническую модель Trade, независимую от конкретной биржи.