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

2026-07-14 09:58:16 +03:00
parent 26deb861bc
commit a996f2f797
443 changed files with 80452 additions and 1335 deletions
--- a/docs/market_intelligence/runtime/architecture.md
+++ b/docs/market_intelligence/runtime/architecture.md
@@ -0,0 +1,588 @@
+# Runtime Architecture
+
+Версия документа: **1.0**
+
+Статус: **Architecture Specification**
+
+---
+
+# Назначение документа
+
+Настоящий документ определяет архитектуру Runtime Layer подсистемы **Market Intelligence**.
+
+Runtime Layer является инфраструктурным уровнем платформы и обеспечивает единый механизм выполнения аналитических Engine.
+
+Документ описывает:
+
+- место Runtime в архитектуре;
+- обязанности Runtime;
+- жизненный цикл выполнения Engine;
+- взаимодействие Runtime с Common;
+- взаимодействие Runtime с Coordinator;
+- устройство Runtime Layer.
+
+Настоящий документ является официальной спецификацией Runtime.
+
+---
+
+# Назначение Runtime
+
+Runtime существует для того, чтобы каждый аналитический Engine выполнялся одинаковым способом.
+
+Любой Engine должен:
+
+- получать одинаковый входной объект;
+- проходить одинаковые проверки;
+- возвращать одинаковый результат;
+- безопасно обрабатывать ошибки;
+- одинаково взаимодействовать с Coordinator.
+
+Именно Runtime обеспечивает эту унификацию.
+
+---
+
+# Место Runtime в архитектуре
+
+Архитектура Market Intelligence имеет многоуровневую структуру.
+
+```text
+Common Layer
+        ↓
+Runtime Layer
+        ↓
+Engine Layer
+        ↓
+Coordinator Layer
+        ↓
+Execution Layer
+```
+
+Каждый уровень знает только о соседнем уровне.
+
+Это исключает прямые зависимости между аналитическими движками и системой исполнения сделок.
+
+---
+
+# Основная ответственность Runtime
+
+Runtime отвечает исключительно за инфраструктуру выполнения Engine.
+
+В его обязанности входят:
+
+- запуск Engine;
+- единый контракт Engine;
+- единый жизненный цикл выполнения;
+- обработка исключений;
+- валидация входных данных;
+- валидация результата;
+- регистрация Engine;
+- управление зависимостями;
+- формирование безопасного результата при ошибке.
+
+---
+
+# Что Runtime никогда не делает
+
+Runtime никогда не:
+
+- анализирует рынок;
+- рассчитывает индикаторы;
+- определяет тренды;
+- принимает торговые решения;
+- открывает позиции;
+- закрывает позиции;
+- рассчитывает размер сделки;
+- взаимодействует с биржей;
+- изменяет состояние AutoTrade.
+
+Runtime является исключительно инфраструктурным уровнем.
+
+---
+
+# Структура Runtime
+
+Runtime состоит из следующих компонентов.
+
+```text
+runtime/
+
+├── protocol.py
+├── metadata.py
+├── registry.py
+├── dependencies.py
+├── runner.py
+├── validation.py
+└── base.py
+```
+
+Каждый компонент имеет единственную область ответственности.
+
+---
+
+---
+
+## Общая архитектура Engine
+
+Каждый аналитический Engine подсистемы **Market Intelligence** состоит из двух независимых частей.
+
+```text
+Engine
+
+├── Metadata
+└── Logic
+```
+
+Разделение Metadata и Logic является обязательным архитектурным стандартом платформы.
+
+Обе части имеют разные зоны ответственности и не должны смешиваться между собой.
+
+---
+
+# Engine Metadata
+
+Metadata представляет собой неизменяемое архитектурное описание Engine.
+
+Metadata существует независимо от выполнения аналитического алгоритма.
+
+Runtime может работать с Metadata без создания экземпляра Engine.
+
+Metadata используется инфраструктурой платформы.
+
+---
+
+## Metadata содержит
+
+Metadata может включать:
+
+- официальное имя Engine;
+- отображаемое имя;
+- версию;
+- краткое описание;
+- категорию Engine;
+- список зависимостей;
+- поддерживаемые таймфреймы;
+- минимальные требования к данным;
+- поддерживаемые возможности;
+- дополнительные архитектурные свойства.
+
+Metadata не содержит вычисляемых результатов анализа.
+
+---
+
+# Immutable Metadata
+
+Metadata является полностью неизменяемой структурой.
+
+После создания Metadata запрещается изменять её содержимое.
+
+Metadata должна быть реализована как immutable-объект.
+
+Например:
+
+```text
+EngineMetadata
+
+↓
+
+frozen dataclass
+```
+
+Во время выполнения Engine Metadata никогда не изменяется.
+
+---
+
+# Engine Logic
+
+Logic представляет собой реализацию аналитического алгоритма.
+
+Logic отвечает исключительно за анализ рынка.
+
+Logic получает:
+
+```text
+EngineContext
+```
+
+и возвращает:
+
+```text
+EngineResult
+```
+
+Logic не должна:
+
+- хранить описание Engine;
+- выполнять регистрацию;
+- объявлять собственные зависимости во время выполнения;
+- изменять Metadata;
+- принимать инфраструктурные решения Runtime.
+
+---
+
+# Runtime использует Metadata
+
+Runtime взаимодействует с Engine через Metadata.
+
+До запуска Engine Runtime может определить:
+
+- существует ли Engine;
+- совместима ли версия;
+- какие зависимости необходимы;
+- поддерживается ли выбранный таймфрейм;
+- можно ли запускать Engine в текущей конфигурации.
+
+Runtime не должен получать эти сведения путём анализа реализации Engine.
+
+---
+
+# Registry использует Metadata
+
+Engine Registry работает исключительно с Metadata.
+
+Registry отвечает за:
+
+- регистрацию Engine;
+- поиск Engine;
+- проверку уникальности;
+- построение графа зависимостей;
+- предоставление списка доступных Engine.
+
+Registry не анализирует алгоритм работы Engine.
+
+---
+
+# Coordinator использует Metadata
+
+Coordinator использует Metadata для определения порядка выполнения Engine.
+
+Metadata позволяет определить зависимости между Engine ещё до начала анализа рынка.
+
+Благодаря этому Coordinator не зависит от внутреннего устройства конкретного Engine.
+
+---
+
+# Разделение ответственности
+
+Зоны ответственности распределяются следующим образом.
+
+```text
+Metadata
+
+↓
+
+Описание Engine
+
+↓
+
+Runtime / Registry / Coordinator
+
+
+Logic
+
+↓
+
+Анализ рынка
+
+↓
+
+EngineResult
+```
+
+Metadata отвечает за архитектурное описание.
+
+Logic отвечает за вычисления.
+
+Runtime отвечает за выполнение.
+
+Coordinator отвечает за оркестрацию.
+
+---
+
+# Архитектурное правило
+
+Каждый новый Engine обязан состоять из двух независимых частей:
+
+```text
+Metadata
+
+↓
+
+Logic
+```
+
+Создание Engine без Metadata считается нарушением архитектурного стандарта платформы.
+
+Настоящее правило является обязательным для всех существующих и будущих Engine подсистемы **Market Intelligence**.
+
+---
+
+# protocol.py
+
+Определяет единый контракт аналитического Engine.
+
+Любой Engine обязан реализовывать данный контракт.
+
+Минимальный контракт включает:
+
+- имя Engine;
+- версию Engine;
+- метод выполнения анализа;
+- тип результата.
+
+Наличие общего протокола позволяет Runtime запускать любой Engine одинаковым способом.
+
+---
+
+# base.py
+
+Содержит базовую реализацию Engine.
+
+Базовый класс предоставляет:
+
+- общие свойства Engine;
+- единый жизненный цикл;
+- стандартную обработку ошибок;
+- вспомогательные методы;
+- безопасное создание результата.
+
+Базовый класс не содержит аналитических алгоритмов.
+
+---
+
+# runner.py
+
+Runner отвечает за выполнение одного Engine.
+
+Последовательность работы Runner:
+
+```text
+получение Engine
+
+↓
+
+валидация EngineContext
+
+↓
+
+запуск Engine
+
+↓
+
+получение EngineResult
+
+↓
+
+валидация результата
+
+↓
+
+возврат результата Coordinator
+```
+
+Runner является главным защитным механизмом Runtime.
+
+---
+
+# registry.py
+
+Registry хранит перечень зарегистрированных Engine.
+
+Основные задачи Registry:
+
+- регистрация Engine;
+- поиск Engine;
+- предотвращение повторной регистрации;
+- получение списка доступных Engine.
+
+Registry не выполняет Engine.
+
+---
+
+# dependencies.py
+
+Dependency Layer описывает связи между Engine.
+
+Он определяет:
+
+- какие Engine могут выполняться независимо;
+- какие Engine используют результаты других Engine;
+- допустимый порядок выполнения;
+- отсутствие циклических зависимостей.
+
+На первом этапе Runtime выполняет только описание зависимостей.
+
+---
+
+# validation.py
+
+Runtime Validation отвечает за проверку выполнения Engine.
+
+Проверяются:
+
+- корректность EngineContext;
+- корректность EngineResult;
+- соблюдение Runtime Contract;
+- отсутствие запрещённых полей;
+- полнота результата.
+
+Runtime Validation использует Common Validation и не дублирует её.
+
+---
+
+# Жизненный цикл выполнения Engine
+
+Каждый Engine проходит одинаковый цикл.
+
+```text
+EngineContext
+        ↓
+Runtime Validation
+        ↓
+Engine Runner
+        ↓
+Engine Execution
+        ↓
+Engine Result
+        ↓
+Runtime Validation
+        ↓
+Coordinator
+```
+
+Ни один этап не должен пропускаться.
+
+---
+
+# Обработка ошибок
+
+Любое исключение должно оставаться внутри Runtime.
+
+Runtime обязан вернуть корректный EngineResult даже при ошибке Engine.
+
+Типичная схема выглядит следующим образом.
+
+```text
+Engine
+
+↓
+
+Exception
+
+↓
+
+Runner
+
+↓
+
+Diagnostics
+
+↓
+
+EngineResult(ERROR)
+
+↓
+
+Coordinator
+```
+
+Ошибка одного Engine не должна останавливать выполнение остальных.
+
+---
+
+# Работа с зависимостями
+
+Engine никогда не обращается напрямую к другому Engine.
+
+Вместо этого Runtime передаёт результаты зависимых Engine через EngineContext.
+
+Таким образом достигаются:
+
+- независимость компонентов;
+- тестируемость;
+- отсутствие циклических зависимостей;
+- возможность повторного использования Engine.
+
+---
+
+# Взаимодействие с Common
+
+Runtime использует Common как единственный источник базовых сущностей.
+
+Используются:
+
+- EngineContext;
+- EngineResult;
+- EngineScore;
+- EngineConfidence;
+- EngineDiagnostics;
+- Validation;
+- Checks;
+- Payload Builder;
+- Snapshot Builder;
+- Event Builder.
+
+Runtime не создаёт собственные версии этих моделей.
+
+---
+
+# Взаимодействие с Coordinator
+
+Coordinator никогда не запускает Engine напрямую.
+
+Вместо этого он использует Runtime.
+
+```text
+Coordinator
+
+↓
+
+Runner
+
+↓
+
+Engine
+
+↓
+
+EngineResult
+
+↓
+
+Coordinator
+```
+
+Это позволяет сохранить единый жизненный цикл выполнения.
+
+---
+
+# Масштабируемость
+
+Архитектура Runtime должна позволять:
+
+- добавлять новые Engine;
+- изменять порядок выполнения;
+- вводить новые проверки;
+- расширять механизм зависимостей;
+- добавлять параллельное выполнение.
+
+При этом существующие Engine не должны изменяться.
+
+---
+
+# Основной архитектурный принцип
+
+Runtime развивается независимо от Engine.
+
+Добавление нового Engine не должно требовать изменения Runtime.
+
+Изменение Runtime допускается только при изменении самого механизма выполнения Engine.
+
+---
+
+# Заключение
+
+Runtime Layer является центральным инфраструктурным компонентом подсистемы **Market Intelligence**.
+
+Он обеспечивает единый способ выполнения аналитических Engine и гарантирует соблюдение архитектурных контрактов платформы.
+
+Настоящий документ является официальной архитектурной спецификацией Runtime Layer.