dzentra_bot/docs/migrations/build_059_2.md

# 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`.