# Build №006 — Common Models

## Файл

```text
app/src/trading/market_intelligence/common/models.py
```

---

# Назначение

Создание единого архитектурного контракта результатов работы всех аналитических движков платформы.

Данный файл определяет общий формат обмена данными между Engine и является центральной моделью подсистемы **Market Intelligence**.

Любой аналитический движок платформы должен использовать данный контракт независимо от своей предметной области.

---

# Реализовано

Созданы базовые модели:

- `EngineMetric`
- `EngineDiagnostics`
- `EngineEvaluationMeta`
- `EngineDependencyResult`
- `EngineContext`
- `EngineResult`

Все модели реализованы как неизменяемые (`frozen=True`) dataclass с использованием `slots=True`.

---

# Назначение моделей

## EngineMetric

Описывает одну измеряемую характеристику, рассчитанную движком.

Примеры:

- сила движения;
- процент волатильности;
- ширина спреда;
- длительность волны.

Метрика не является торговым решением.

---

## EngineDiagnostics

Хранит техническую диагностику выполнения движка.

Используется для:

- журналирования;
- диагностики;
- проверки качества работы;
- анализа ошибок.

Диагностика полностью отделена от пользовательского интерфейса.

---

## EngineEvaluationMeta

Содержит служебную информацию о расчёте.

Например:

- название движка;
- версия движка;
- время выполнения;
- длительность расчёта;
- возраст входных данных.

---

## EngineDependencyResult

Представляет результат другого аналитического движка в компактной форме.

Используется для построения зависимостей между Engine без прямых импортов.

---

## EngineContext

Определяет единый входной контракт любого аналитического движка.

Контекст содержит только данные, необходимые для анализа рынка.

Контекст не содержит информации о:

- позициях;
- балансе;
- исполнении;
- торговых приказах;
- пользовательском интерфейсе.

---

## EngineResult

Является единым результатом работы любого Engine.

Содержит:

- состояние выполнения;
- оценки;
- уровень уверенности;
- направление рынка;
- режим рынка;
- фазу рынка;
- диагностическую информацию;
- рассчитанные метрики;
- служебные сведения.

EngineResult описывает только результат анализа рынка.

EngineResult не содержит торговых решений.

---

# Архитектурные решения

Во время реализации приняты следующие решения.

## Единый контракт

Все аналитические движки используют один и тот же тип результата.

Это позволяет Coordinator работать с любым Engine одинаковым образом.

---

## Разделение ответственности

Контракт разделён на независимые части:

- входные данные (`EngineContext`);
- результат анализа (`EngineResult`);
- диагностика (`EngineDiagnostics`);
- служебные сведения (`EngineEvaluationMeta`);
- зависимости (`EngineDependencyResult`);
- отдельные измеряемые показатели (`EngineMetric`).

---

## Независимость от торговли

Контракт не содержит:

- открытия позиции;
- закрытия позиции;
- управления ордерами;
- расчёта размера позиции;
- информации о балансе;
- информации о бирже.

Market Intelligence остаётся исключительно аналитическим уровнем платформы.

---

## Независимость движков

Ни один Engine не импортирует другой Engine напрямую.

Передача результатов между движками осуществляется через `EngineDependencyResult`.

Это исключает циклические зависимости и упрощает масштабирование платформы.

---

## Минимальный контекст

Engine получает только необходимые входные данные.

Контекст не превращается в универсальное хранилище состояния платформы.

Это позволяет каждому Engine работать независимо.

---

## Иммутабельность

Все модели объявлены как неизменяемые (`frozen=True`).

После формирования результата он больше не изменяется.

Это обеспечивает:

- предсказуемость;
- безопасную передачу между компонентами;
- стабильное журналирование;
- корректное сравнение результатов.

---

# Compile Check

```text
PASSED
```

---

# Architecture Review

```text
PASSED
```

---

# Domain Review

```text
PASSED
```

---

# Обязательные замечания

Нет.

---

# Рекомендации

В дальнейшем рекомендуется дополнить архитектуру следующими сущностями после появления соответствующей практической необходимости:

- идентификатор результата (`result_id`);
- источник рыночных данных (`data_source`);
- время окончания актуальности результата (`expires_at`).

До появления реальной потребности данные поля не добавляются.

Это соответствует принципу **No Premature Abstractions**.

---

# Статус

```text
ACCEPTED
```

---

# Итоги Build

Build №006 завершил проектирование единого контракта аналитических движков.

Начиная с данного Build все новые Engine должны возвращать результат исключительно через `EngineResult`.

Создание собственных моделей результатов внутри отдельных Engine запрещается.

`common/models.py` становится единым источником истины для архитектуры результатов Market Intelligence.