build 039: complete Quotes Feed migration foundation

docs/market_intelligence/builds/build-012-common-timeframes.md

@@ -0,0 +1,226 @@
+# Build 012 — Common Timeframes
+
+**Build ID:** 012
+
+**Component:** `common/timeframes.py`
+
+**Status:** ✅ Accepted
+
+**Development Process:** v2.0
+
+---
+
+# Цель Build
+
+Создать единый архитектурный слой описания таймфреймов, который будет использоваться всеми будущими Engine подсистемы Market Intelligence.
+
+До данного Build информация о таймфреймах существовала только внутри отдельных модулей старой системы анализа рынка.
+
+Это затрудняло повторное использование логики и не позволяло создать единый контракт для многоуровневого анализа.
+
+Настоящий Build переносит описание таймфреймов в слой Common и делает его независимым от реализации конкретных аналитических движков.
+
+---
+
+# Реализованные компоненты
+
+Добавлен новый файл:
+
+```text
+common/timeframes.py
+```
+
+В рамках Build реализованы:
+
+- модель `Timeframe`;
+- единый реестр поддерживаемых таймфреймов;
+- архитектурные роли таймфреймов;
+- карта переходов к старшему таймфрейму;
+- функции поиска и проверки таймфреймов;
+- преобразование модели в диагностический payload.
+
+---
+
+# Архитектурные решения
+
+## Единая модель Timeframe
+
+Каждый временной интервал представлен неизменяемым объектом `Timeframe`.
+
+Модель содержит только архитектурное описание интервала:
+
+- имя;
+- длительность;
+- роль;
+- описание.
+
+Модель не содержит торговой логики.
+
+---
+
+## Централизованный реестр
+
+Все поддерживаемые интервалы собраны в одном месте.
+
+На текущем этапе поддерживаются:
+
+```text
+1m
+5m
+15m
+1h
+4h
+1d
+1w
+```
+
+Это создаёт единый источник истины для всей платформы.
+
+---
+
+## Архитектурные роли
+
+Каждому таймфрейму назначается роль:
+
+- LOWER;
+- PRIMARY;
+- CONFIRMATION;
+- HIGHER.
+
+Роль используется будущими движками при построении многоуровневого анализа.
+
+---
+
+## Карта старших таймфреймов
+
+Добавлена централизованная карта переходов:
+
+```text
+1m  → 5m
+5m  → 1h
+15m → 1h
+1h  → 4h
+4h  → 1d
+1d  → 1w
+```
+
+На текущем этапе она полностью совместима с существующей реализацией `MarketAnalysisService`, где рабочий интервал `5m` использует старший `1h`.
+
+---
+
+## Независимость от существующего анализа рынка
+
+Файл не использует:
+
+- `MarketAnalysisService`;
+- `ExchangeService`;
+- старые модели;
+- AutoTrade.
+
+Таким образом создаётся самостоятельный фундамент для новой подсистемы Market Intelligence без изменения существующего поведения бота.
+
+---
+
+# Реализованные функции
+
+Добавлены следующие функции:
+
+- `get_timeframe()`
+- `require_timeframe()`
+- `is_supported_timeframe()`
+- `get_higher_timeframe()`
+- `get_timeframes_by_role()`
+- `timeframe_to_payload()`
+
+Все функции являются детерминированными и не имеют побочных эффектов.
+
+---
+
+# Compile Check
+
+Статус:
+
+```text
+PASSED
+```
+
+Проверка:
+
+```bash
+python -m compileall src/trading/market_intelligence/common/timeframes.py
+```
+
+Результат:
+
+```text
+Compiling 'src/trading/market_intelligence/common/timeframes.py'...
+```
+
+Ошибок компиляции не обнаружено.
+
+---
+
+# Architecture Review
+
+**Статус:** ✅ Passed
+
+Проверено:
+
+- отсутствие циклических зависимостей;
+- отсутствие торговой логики;
+- независимость от Runtime;
+- независимость от Exchange;
+- независимость от AutoTrade;
+- соответствие архитектуре Common Layer.
+
+Замечаний нет.
+
+---
+
+# Domain Review
+
+**Статус:** ✅ Passed
+
+Проверено:
+
+- корректность терминологии;
+- соответствие философии Market Intelligence;
+- отсутствие принятия торговых решений;
+- корректное разделение понятий "таймфрейм" и "анализ рынка".
+
+Замечаний нет.
+
+---
+
+# Engineering Review
+
+Положительные результаты Build:
+
+- создан единый источник истины для таймфреймов;
+- устранено дублирование будущих определений;
+- подготовлен фундамент для Multi-Timeframe Engine;
+- сохранена совместимость с существующей системой анализа рынка.
+
+Build не оказывает влияния на работу действующего торгового бота.
+
+---
+
+# Документация
+
+В рамках Build подготовлены:
+
+- `common/timeframes.py`;
+- `build-012-common-timeframes.md`;
+- обновление `build_history.md`.
+
+---
+
+# Итог
+
+Build успешно завершил создание единого слоя описания таймфреймов.
+
+Следующие аналитические движки смогут использовать единый контракт работы с временными интервалами без зависимости от устаревшей реализации `market_analysis`.
+
+---
+
+**Итоговый статус Build:** ✅ **Accepted**