# 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**