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

docs/market_intelligence/builds/build-014-2-engine-base.md

@@ -0,0 +1,272 @@
+# Build 014.2 — Engine Base / BaseEngine
+
+**Engineering Build Document**
+
+---
+
+# Контроль документа
+
+| Свойство | Значение |
+|----------|-----------|
+| Build | 014.2 |
+| Название | Engine Base / BaseEngine |
+| Статус | **Accepted** |
+| Подсистема | Market Intelligence |
+| Layer | Engine |
+| Тип | Architecture + Implementation |
+| Версия | 1.0 |
+| Язык | Русский |
+
+---
+
+# Причина появления Build
+
+После введения официального контракта `EngineProtocol` возникла необходимость определить единый жизненный цикл выполнения всех аналитических движков.
+
+Без общего базового класса каждый Engine был бы вынужден самостоятельно реализовывать:
+
+- обработку ошибок;
+- проверку входного контекста;
+- формирование служебной metadata;
+- единый жизненный цикл анализа.
+
+Это неизбежно привело бы к дублированию инфраструктурного кода и постепенному расхождению поведения различных Engine.
+
+---
+
+# Цель Build
+
+Создать инфраструктурный базовый класс `BaseEngine`, который определяет единый жизненный цикл выполнения любого Engine, не включая аналитическую логику.
+
+---
+
+# Architecture
+
+`BaseEngine` представляет собой инфраструктурный шаблон выполнения.
+
+Он отвечает исключительно за организацию жизненного цикла Engine.
+
+Общая модель выглядит следующим образом:
+
+```text
+analyze(context)
+        │
+        ▼
+_validate_context(context)
+        │
+        ▼
+_analyze_impl(context)
+        │
+        ▼
+_normalize_result(result)
+        │
+        ▼
+EngineResult
+```
+
+Публичной точкой входа является только метод:
+
+```text
+analyze(context)
+```
+
+Вся предметная аналитика выполняется исключительно внутри:
+
+```text
+_analyze_impl(context)
+```
+
+---
+
+# Architecture Review
+
+В ходе проверки подтверждено:
+
+- BaseEngine не содержит аналитической логики;
+- Runtime не переносится внутрь Engine;
+- Coordinator не зависит от реализации Engine;
+- Engine продолжают оставаться полностью независимыми;
+- Metadata остаётся отделённой от аналитической логики;
+- Runtime сможет использовать единый жизненный цикл всех Engine.
+
+Архитектурное решение признано корректным.
+
+---
+
+# Architecture Decision (ADR)
+
+## Решение
+
+Принято использовать инфраструктурный базовый класс:
+
+```text
+BaseEngine
+```
+
+вместо минимального абстрактного класса.
+
+## Статус
+
+**Accepted**
+
+## Обоснование
+
+Платформа проектируется как система, включающая большое количество специализированных аналитических движков.
+
+Общая инфраструктура должна быть реализована один раз и использоваться всеми Engine.
+
+Это позволяет:
+
+- устранить дублирование кода;
+- унифицировать жизненный цикл выполнения;
+- обеспечить одинаковое поведение всех Engine;
+- уменьшить вероятность архитектурных расхождений.
+
+## Последствия
+
+После принятия решения:
+
+- все Engine наследуются от BaseEngine;
+- Runtime работает через единый жизненный цикл;
+- аналитическая логика полностью остаётся в конкретных Engine;
+- изменение инфраструктуры выполняется централизованно.
+
+---
+
+# Build Design
+
+Создан файл:
+
+```text
+app/src/trading/market_intelligence/engine/base.py
+```
+
+Класс содержит только инфраструктурные механизмы.
+
+В его состав входят:
+
+- получение EngineMetadata;
+- единый метод `analyze()`;
+- базовая проверка входного контекста;
+- защищённый метод `_analyze_impl()`;
+- нормализация результата;
+- безопасное формирование результата при ошибке.
+
+---
+
+# Implementation
+
+Реализованы следующие элементы:
+
+```text
+BaseEngine
+├── ENGINE_METADATA
+├── get_metadata()
+├── analyze()
+├── _validate_context()
+├── _analyze_impl()
+├── _normalize_result()
+└── _build_error_result()
+```
+
+Все методы снабжены комментариями на русском языке в соответствии со стандартом проекта.
+
+---
+
+# Compile Check
+
+Проверка выполнена командой:
+
+```bash
+python -m compileall src/trading/market_intelligence
+```
+
+Результат:
+
+- успешно скомпилирован `engine/base.py`;
+- успешно скомпилирован `engine/protocol.py`;
+- отсутствуют синтаксические ошибки;
+- отсутствуют циклические импорты;
+- успешно компилируется весь пакет `market_intelligence`.
+
+Дополнительно после Code Review внесено улучшение:
+`EngineEvaluationMeta.calculated_at` теперь заполняется при нормализации результата и при формировании error-result.
+
+Повторный Compile Check выполнен успешно.
+
+**Статус:** ✅ Passed
+
+---
+
+# Domain Review
+
+Проверено соответствие предметной области.
+
+`BaseEngine`:
+
+- не содержит аналитической логики;
+- не принимает торговых решений;
+- не взаимодействует с Runtime;
+- не взаимодействует с Coordinator;
+- не зависит от AutoTrade;
+- не обращается к другим Engine;
+- не содержит инфраструктуры Telegram, БД или API.
+
+Класс полностью соответствует архитектурной роли инфраструктурной основы Engine Layer.
+
+**Статус:** ✅ Passed
+
+---
+
+# Documentation
+
+В рамках Build обновлены:
+
+- Build History;
+- Runtime Contract;
+- Engine Layer Architecture.
+
+---
+
+# Acceptance
+
+Build считается завершённым.
+
+Выполнены:
+
+- ✅ Architecture
+- ✅ Architecture Review
+- ✅ Architecture Decision (ADR)
+- ✅ Build Design
+- ✅ Implementation
+- ✅ Compile Check
+- ✅ Domain Review
+- ✅ Documentation
+- ✅ Acceptance
+
+Статус Build:
+
+**Accepted**
+
+---
+
+# Итоги Build
+
+В результате Build 014.2:
+
+- создан инфраструктурный базовый класс Engine Layer;
+- определён единый жизненный цикл выполнения Engine;
+- устранено дублирование общей инфраструктуры;
+- подготовлена основа для реализации всех специализированных аналитических движков платформы.
+
+---
+
+# Следующий Build
+
+```text
+Build 014.3
+
+Engine Exceptions
+
+engine/exceptions.py
+```