build 039: complete Quotes Feed migration foundation

docs/market_intelligence/builds/build-006-common-models.md

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