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

Build №006 — Common Models

Файл

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

PASSED

---

Architecture Review

PASSED

---

Domain Review

PASSED

---

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

Нет.

---

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

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

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

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

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

---

Статус

ACCEPTED

---

Итоги Build

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

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

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

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