build 056: finalize canonical OHLCV architecture verification

docs/migrations/build_056.md

@@ -0,0 +1,435 @@
+# 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`.