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

Build 006.1 — Common Models Extension / EngineMetadata

Engineering Build Document

---

Контроль документа

Свойство	Значение
Build	006.1
Название	Common Models Extension / EngineMetadata
Статус	Accepted
Подсистема	Market Intelligence
Layer	Common
Тип	Architecture Extension
Версия	1.0
Язык	Русский

---

Причина появления Build

Во время проектирования Engine Layer было обнаружено, что базовый контракт Engine требует наличия модели, описывающей сам Engine как архитектурный компонент.

Первоначально предполагалось, что данная модель относится к Engine Layer.

Однако архитектурный анализ показал, что она используется значительно шире.

Модель необходима для:

• Engine Layer;
• Runtime Layer;
• будущего Registry;
• будущего Coordinator;
• построения графа зависимостей;
• диагностики;
• документации.

Следовательно, данная модель является частью Common Layer, а не Engine Layer.

Для сохранения чистоты архитектуры было принято решение выпустить отдельный Build 006.1 вместо изменения уже принятого Build 006.

---

Цель Build

Добавить в Common Layer новую базовую модель:

EngineMetadata

которая описывает Engine как компонент платформы, а не результат его работы.

---

Архитектурное решение

Модель размещается в:

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

а не в:

app/src/trading/market_intelligence/engine/

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

---

Architecture Decision (ADR)

Решение

Добавить модель EngineMetadata в Common Layer.

Статус

Accepted

Обоснование

Во время проектирования Engine Layer было установлено, что описание Engine используется не только самим Engine, но и Runtime, Registry, Coordinator и другими архитектурными компонентами.

Следовательно, EngineMetadata является общим контрактом платформы и должна располагаться в common.models.

Размещение модели в Engine Layer привело бы к неправильному направлению архитектурных зависимостей и нарушило бы принцип повторного использования общих моделей.

Последствия

После принятия решения:

• Engine Layer использует EngineMetadata из Common Layer;
• Runtime зависит только от общих контрактов;
• Coordinator сможет получать описание Engine без знания его реализации;
• архитектурные зависимости остаются однонаправленными.

---

Состав модели

@dataclass(frozen=True, slots=True)
class EngineMetadata:
    # Описание Engine как компонента платформы.
    # Metadata не содержит аналитической логики и не является результатом анализа.
    # Она используется Runtime, Registry, Coordinator и документацией.
    name: EngineName
    version: EngineVersion
    description: str = ""
    supported_timeframes: tuple[TimeframeName, ...] = ()
    required_dependencies: tuple[EngineName, ...] = ()
    optional_dependencies: tuple[EngineName, ...] = ()
    enabled_by_default: bool = True

---

Обоснование полей

name

Уникальное имя Engine.

Используется Registry, Coordinator и журналированием.

---

version

Версия реализации Engine.

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

---

description

Краткое описание назначения Engine.

Используется документацией, диагностикой и интерфейсами разработчика.

---

supported_timeframes

Перечень поддерживаемых таймфреймов.

Позволяет Coordinator определить применимость Engine для конкретного анализа.

---

required_dependencies

Перечень обязательных зависимостей.

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

---

optional_dependencies

Перечень необязательных зависимостей.

Их отсутствие не запрещает выполнение Engine, но может снизить качество анализа.

---

enabled_by_default

Признак регистрации Engine по умолчанию.

Позволяет включать или отключать Engine без изменения Runtime.

---

Что Build НЕ добавляет

Build сознательно не включает:

• Runtime;
• Registry;
• Coordinator;
• Dependency Graph;
• порядок запуска Engine;
• приоритеты выполнения;
• настройки Runtime;
• timeout;
• retry;
• cache policy;
• аналитическую логику.

Эти возможности относятся к следующим Build.

---

Архитектурные последствия

После появления EngineMetadata становится возможным построение базового контракта Engine Layer.

Новая зависимость архитектуры выглядит следующим образом:

Common Layer
│
├── EngineContext
├── EngineResult
├── EngineDependencyResult
└── EngineMetadata

        ▲

Engine Layer
│
├── EngineProtocol
└── Engine Implementation

        ▲

Runtime Layer

        ▲

Coordinator Layer

---

Итоги Build

В результате Build 006.1:

• Common Layer получил новый общий контракт платформы;
• устранён архитектурный пробел, обнаруженный при проектировании Engine Layer;
• подготовлена основа для реализации EngineProtocol;
• Runtime сможет использовать единый контракт Engine без знания конкретных реализаций.

---

Acceptance

Build считается завершённым после выполнения:

• ✅ Architecture Review
• ✅ Architecture Decision (ADR)
• ✅ Build Design
• ✅ Implementation
• ✅ Compile Check
• ✅ Domain Review
• ✅ Documentation
• ✅ Acceptance

---

Следующий Build

Build 014

Engine Base Contracts

engine/protocol.py