feat: add market data architecture and complete migration through build 039

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

@@ -0,0 +1,257 @@
+# Architecture Decision Record 008
+
+# Engine Metadata Separation
+
+Статус: **Accepted**
+
+Версия: **1.0**
+
+---
+
+# Контекст
+
+Подсистема **Market Intelligence** строится как долгосрочная аналитическая платформа, состоящая из множества независимых специализированных Engine.
+
+Ожидается, что со временем количество Engine будет постепенно увеличиваться.
+
+Каждый Engine должен быть независимым компонентом, который можно:
+
+- зарегистрировать;
+- проверить;
+- документировать;
+- подключить к Runtime;
+- использовать Coordinator;
+- заменить новой реализацией.
+
+До начала реализации Runtime было необходимо определить единый способ описания любого Engine.
+
+---
+
+# Проблема
+
+Наивная реализация предполагает, что Runtime работает непосредственно с экземпляром Engine.
+
+Например:
+
+```python
+engine.run(context)
+```
+
+При таком подходе Runtime ничего не знает о самом Engine до его создания.
+
+Это приводит к нескольким проблемам.
+
+Runtime не может заранее определить:
+
+- имя Engine;
+- назначение Engine;
+- зависимости Engine;
+- поддерживаемые таймфреймы;
+- минимальные требования к данным;
+- совместимость версии;
+- возможность регистрации Engine.
+
+В результате описание Engine смешивается с его логикой.
+
+По мере роста количества Engine подобная архитектура становится всё менее масштабируемой.
+
+---
+
+# Решение
+
+Каждый Engine разделяется на две полностью независимые части.
+
+```text
+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 получает:
+
+```text
+EngineContext
+```
+
+и возвращает
+
+```text
+EngineResult
+```
+
+Logic не должна хранить архитектурную информацию о себе.
+
+Она не отвечает за:
+
+- регистрацию;
+- описание возможностей;
+- зависимости;
+- документацию;
+- совместимость.
+
+Эти сведения находятся исключительно в Metadata.
+
+---
+
+# Immutable Metadata
+
+Metadata является полностью неизменяемой структурой.
+
+После создания Metadata запрещается изменять её содержимое.
+
+Runtime рассматривает Metadata как константу.
+
+Engine не имеет права изменять собственное описание во время выполнения.
+
+---
+
+# Metadata Access
+
+Metadata должна быть доступна инфраструктуре платформы без создания экземпляра Engine.
+
+Runtime, Registry и Coordinator должны иметь возможность получить полное описание Engine до начала его выполнения.
+
+Предпочтительной реализацией является хранение Metadata как неизменяемого атрибута класса Engine.
+
+Например:
+
+```python
+TrendEngine.metadata
+```
+
+или отдельной неизменяемой структуры:
+
+```python
+TREND_ENGINE_METADATA
+```
+
+Создание экземпляра Engine исключительно для получения Metadata не допускается.
+
+Это позволяет Runtime:
+
+- регистрировать Engine;
+- строить граф зависимостей;
+- проверять совместимость;
+- формировать документацию;
+- анализировать архитектуру платформы;
+
+без запуска аналитических алгоритмов.
+
+---
+
+# Причины принятия решения
+
+Разделение Metadata и Logic обеспечивает:
+
+- единый способ описания Engine;
+- независимость инфраструктуры от реализации Engine;
+- возможность автоматической регистрации Engine;
+- возможность построения графа зависимостей;
+- возможность автоматического формирования документации;
+- возможность проверки совместимости;
+- упрощение тестирования;
+- упрощение сопровождения.
+
+---
+
+# Последствия
+
+После принятия настоящего решения любой новый Engine обязан состоять из двух независимых частей:
+
+```text
+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.