dzentra_bot/docs/migrations/build_056.md

# Build 056 — Финальная архитектурная верификация OHLCV Feed

## Статус

**Завершён**

---

## Цель Build

Выполнить финальную архитектурную проверку миграции OHLCV Feed и документально подтвердить, что:

- legacy-модели `Kline` и `KlineBatch` полностью удалены;
- legacy API `get_klines()` полностью удалён;
- compatibility helper `_kline_from_candle()` полностью удалён;
- неиспользуемый файл `indicators_legacy.py` полностью удалён;
- активный production-код использует только каноническую модель `Candle`;
- получение OHLCV выполняется только через канонический слой `Market Data Acquisition`;
- обратная зависимость `Market Data → Trading` отсутствует;
- полный regression suite проходит успешно.

Build 056 не изменяет production-код.

---

## Исходное состояние

До Build 056 были завершены следующие этапы:

```text
Build 044 — создан канонический Candles Feed foundation
Build 045 — добавлен CandlesFeedRegistry
Build 046 — добавлен CandlesAcquisitionService
Build 047 — ExchangeService переключён на канонический Candles Feed
Build 048 — вычислительные потребители Market Analysis переведены на Candle
Build 049 — добавлен публичный ExchangeService.get_candles()
Build 050 — MarketAnalysisService переключён на get_candles()
Build 051 — HTF-анализ переключён на get_candles()
Build 052 — выполнен аудит legacy OHLCV
Build 053 — удалён indicators_legacy.py
Build 054 — удалены get_klines() и _kline_from_candle()
Build 055 — удалены Kline и KlineBatch
```

Build 056 является финальной проверкой завершённой миграции.

---

## Объём Build

В Build 056 добавляется только документация:

```text
docs/migrations/build_056.md
```

Production-код и тесты не изменяются.

---

## Контроль полного отсутствия legacy OHLCV

Выполнена команда:

```bash
grep -RIn \
  --exclude-dir="__pycache__" \
  --exclude="*.pyc" \
  -E "\bKlineBatch\b|\bKline\b|get_klines|_kline_from_candle|indicators_legacy" \
  src tests
```

Результат:

```text
пусто
```

Это подтверждает полное отсутствие:

```text
Kline
KlineBatch
get_klines
_kline_from_candle
indicators_legacy
```

в исходном коде и тестах.

---

## Контроль использования канонической модели Candle

Выполнена команда:

```bash
grep -RIn \
  --exclude-dir="__pycache__" \
  --exclude="*.pyc" \
  "models\.candle import Candle" \
  src tests
```

Каноническая модель используется в:

```text
src/market_data/acquisition/service.py
src/market_data/acquisition/protocol.py
src/market_data/acquisition/feeds/candles_feed.py
src/market_data/acquisition/adapters/dzengi/mapper.py
src/market_data/acquisition/handlers/candles_handler.py
src/integrations/exchange/service.py
src/trading/market_analysis/indicators/volatility.py
src/trading/market_analysis/structure.py
src/trading/market_analysis/quality.py
```

Также она используется в специализированных unit-тестах Acquisition, Exchange Integration и Market Analysis.

---

## Контроль production-вызовов get_candles()

Выполнена команда:

```bash
grep -RIn \
  --exclude-dir="__pycache__" \
  --exclude="*.pyc" \
  "\.get_candles(" \
  src tests
```

Production-вызовы обнаружены в:

```text
src/trading/market_analysis/service.py
src/trading/market_analysis/htf.py
```

Фактические production-точки:

```text
MarketAnalysisService — один вызов
HTF volatility — один вызов
HTF trend — один вызов
```

Остальные вызовы находятся в специализированных тестах канонического API.

---

## Контроль REST-точки OHLCV

Выполнена команда:

```bash
grep -RIn \
  --exclude-dir="__pycache__" \
  --exclude="*.pyc" \
  '"/api/v1/klines"' \
  src tests
```

Результат:

```text
src/market_data/acquisition/adapters/dzengi/rest.py
tests/unit/market_data/acquisition/adapters/dzengi/test_candle_rest.py
```

В production-коде REST endpoint существует только в:

```text
src/market_data/acquisition/adapters/dzengi/rest.py
```

Второе совпадение находится в unit-тесте канонического REST adapter.

Следовательно, прямое получение OHLCV вне `Market Data Acquisition` отсутствует.

---

## Контроль отсутствия обратной зависимости Market Data → Trading

Выполнена команда:

```bash
grep -RIn \
  --exclude-dir="__pycache__" \
  --exclude="*.pyc" \
  "from src.trading\|import src.trading" \
  src/market_data
```

Результат:

```text
пусто
```

Это подтверждает соблюдение направленности зависимостей:

```text
Market Data
    ↓
Market Intelligence / Trading
```

и отсутствие обратной связи:

```text
Market Data
    ✕
Trading
```

---

## Контроль канонического Candles pipeline

Выполнена команда:

```bash
grep -RIn \
  --exclude-dir="__pycache__" \
  --exclude="*.pyc" \
  "CandlesAcquisitionService\|CandlesFeedRegistry\|DzengiCandlesDocumentSource\|DzengiCandlesDocumentHandler\|CandlesFeed" \
  src tests
```

Подтверждены следующие production-компоненты:

```text
DzengiCandlesDocumentSource
DzengiCandlesDocumentHandler
CandlesFeed
CandlesFeedProtocol
CandlesFeedRegistry
CandlesAcquisitionService
```

Также подтверждено их специализированное unit-покрытие.

---

## Финальная архитектура OHLCV

После завершения миграции production-путь выглядит следующим образом:

```text
Dzengi REST API
    ↓
DzengiCandlesDocumentSource
    ↓
schema validation
    ↓
parser
    ↓
value validation
    ↓
mapper
    ↓
Candle
    ↓
DzengiCandlesDocumentHandler
    ↓
CandlesFeed
    ↓
CandlesFeedRegistry
    ↓
CandlesAcquisitionService
    ↓
ExchangeService.get_candles()
    ↓
MarketAnalysisService
    ↓
HTF volatility / HTF trend
    ↓
Market Analysis calculations
```

Единственная внутренняя модель OHLCV:

```text
src.market_data.acquisition.models.candle.Candle
```

---

## Проверка компиляции

Выполнена команда:

```bash
python -m compileall \
  src/market_data/acquisition \
  src/integrations/exchange \
  src/trading/market_analysis
```

Компиляция завершена успешно.

Ошибок синтаксиса и импорта не обнаружено.

---

## Полный regression suite

Выполнена команда:

```bash
python -m pytest -q
```

Результат:

```text
779 passed in 3.22s
```

Регрессий не обнаружено.

---

## Проверка Git

Выполнены команды:

```bash
git status
git log --oneline -12
git diff --check
```

Результат:

```text
working tree clean
git diff --check — чисто
```

Текущий последний commit перед Build 056:

```text
39f156c build 055: remove legacy Kline models
```

---

## Подтверждённые архитектурные свойства

После финальной проверки подтверждено:

1. В проекте существует только одна каноническая модель OHLCV — `Candle`.
2. REST endpoint `/api/v1/klines` локализован в адаптере Dzengi.
3. Parsing, schema validation, value validation и mapping находятся в `Market Data Acquisition`.
4. Acquisition pipeline доступен через `CandlesAcquisitionService`.
5. Exchange Integration предоставляет публичный `get_candles()`.
6. Market Analysis и HTF используют `get_candles()`.
7. Legacy API и legacy-модели полностью удалены.
8. Обратная зависимость `Market Data → Trading` отсутствует.
9. Полный test suite проходит.
10. Рабочее дерево чистое.

---

## Что намеренно не выполнялось

Build 056 не включает:

- изменение production-кода;
- изменение тестов;
- изменение торговой логики;
- изменение вычислительных алгоритмов;
- изменение структуры каталогов;
- дополнительный refactoring unrelated-компонентов;
- переименование существующих диагностических причин;
- изменение API Dzengi.

---

## Критерии завершения

Build 056 считается завершённым, поскольку:

- grep по legacy OHLCV полностью пустой;
- канонический `Candle` используется во всех активных слоях;
- production-вызовы выполняются через `get_candles()`;
- REST endpoint локализован в каноническом адаптере;
- обратная зависимость `Market Data → Trading` отсутствует;
- канонический pipeline полностью присутствует;
- compileall проходит;
- полный regression suite проходит;
- Git-состояние чистое.

---

## Итог

**Build 056 завершён успешно.**

Миграция OHLCV Feed полностью завершена.

Удалены:

```text
Kline
KlineBatch
get_klines()
_kline_from_candle()
indicators_legacy.py
```

Активная система использует:

```text
Candle
CandlesFeed
CandlesFeedRegistry
CandlesAcquisitionService
ExchangeService.get_candles()
```

Итоговые проверки:

```text
Legacy grep — пусто
Compileall — успешно
Full test suite — 779 passed
git diff --check — чисто
```

OHLCV Feed теперь полностью соответствует утверждённой архитектуре `Market Data Acquisition`.