dzentra_bot/docs/market_intelligence/decisions/decision-008-engine-metadata-separation.md

Architecture Decision Record 008

Engine Metadata Separation

Статус: Accepted

Версия: 1.0

---

Контекст

Подсистема Market Intelligence строится как долгосрочная аналитическая платформа, состоящая из множества независимых специализированных Engine.

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

Каждый Engine должен быть независимым компонентом, который можно:

• зарегистрировать;
• проверить;
• документировать;
• подключить к Runtime;
• использовать Coordinator;
• заменить новой реализацией.

До начала реализации Runtime было необходимо определить единый способ описания любого Engine.

---

Проблема

Наивная реализация предполагает, что Runtime работает непосредственно с экземпляром Engine.

Например:

engine.run(context)

При таком подходе Runtime ничего не знает о самом Engine до его создания.

Это приводит к нескольким проблемам.

Runtime не может заранее определить:

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

В результате описание Engine смешивается с его логикой.

По мере роста количества Engine подобная архитектура становится всё менее масштабируемой.

---

Решение

Каждый Engine разделяется на две полностью независимые части.

Engine

├── Metadata
└── Logic

Metadata описывает Engine.

Logic реализует анализ рынка.

Runtime работает с Metadata.

Engine выполняет только аналитический алгоритм.

---

Engine Metadata

Metadata представляет собой неизменяемое описание Engine.

Metadata должна содержать всю информацию, необходимую инфраструктуре платформы.

Например:

• имя Engine;
• версия Engine;
• отображаемое имя;
• краткое описание;
• зависимости;
• поддерживаемые таймфреймы;
• минимальные требования к входным данным;
• дополнительные возможности Engine.

Metadata не содержит вычисляемых значений.

Metadata не зависит от состояния рынка.

Metadata не изменяется во время выполнения Engine.

---

Engine Logic

Logic содержит исключительно алгоритм анализа.

Logic получает:

EngineContext

и возвращает

EngineResult

Logic не должна хранить архитектурную информацию о себе.

Она не отвечает за:

• регистрацию;
• описание возможностей;
• зависимости;
• документацию;
• совместимость.

Эти сведения находятся исключительно в Metadata.

---

Immutable Metadata

Metadata является полностью неизменяемой структурой.

После создания Metadata запрещается изменять её содержимое.

Runtime рассматривает Metadata как константу.

Engine не имеет права изменять собственное описание во время выполнения.

---

Metadata Access

Metadata должна быть доступна инфраструктуре платформы без создания экземпляра Engine.

Runtime, Registry и Coordinator должны иметь возможность получить полное описание Engine до начала его выполнения.

Предпочтительной реализацией является хранение Metadata как неизменяемого атрибута класса Engine.

Например:

TrendEngine.metadata

или отдельной неизменяемой структуры:

TREND_ENGINE_METADATA

Создание экземпляра Engine исключительно для получения Metadata не допускается.

Это позволяет Runtime:

• регистрировать Engine;
• строить граф зависимостей;
• проверять совместимость;
• формировать документацию;
• анализировать архитектуру платформы;

без запуска аналитических алгоритмов.

---

Причины принятия решения

Разделение Metadata и Logic обеспечивает:

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

---

Последствия

После принятия настоящего решения любой новый Engine обязан состоять из двух независимых частей:

Metadata

↓

Logic

Создание Engine без Metadata считается нарушением архитектурного стандарта платформы.

---

Влияние на Runtime

Runtime работает исключительно через Metadata.

Runtime не должен получать архитектурную информацию путём анализа реализации Engine.

Все инфраструктурные механизмы используют Metadata как единственный источник архитектурного описания Engine.

---

Влияние на Registry

Engine Registry использует Metadata для:

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

Registry не анализирует реализацию Engine.

---

Влияние на Coordinator

Coordinator использует Metadata для определения порядка выполнения Engine.

Coordinator не должен знать внутреннее устройство конкретного Engine.

---

Совместимость

Настоящее решение является обязательным для всех существующих и будущих Engine подсистемы Market Intelligence.

Изменение данного правила допускается только посредством нового Architecture Decision Record.

---

Статус решения

Настоящее решение принято как долгосрочный архитектурный стандарт платформы Dzentra Market Intelligence.

Все последующие Runtime и Engine Build должны соответствовать данному ADR.