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

```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`, независимую от конкретной биржи.