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

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.

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

analyze(context)
        │
        ▼
_validate_context(context)
        │
        ▼
_analyze_impl(context)
        │
        ▼
_normalize_result(result)
        │
        ▼
EngineResult

Публичной точкой входа является только метод:

analyze(context)

Вся предметная аналитика выполняется исключительно внутри:

_analyze_impl(context)

---

Architecture Review

В ходе проверки подтверждено:

• BaseEngine не содержит аналитической логики;
• Runtime не переносится внутрь Engine;
• Coordinator не зависит от реализации Engine;
• Engine продолжают оставаться полностью независимыми;
• Metadata остаётся отделённой от аналитической логики;
• Runtime сможет использовать единый жизненный цикл всех Engine.

Архитектурное решение признано корректным.

---

Architecture Decision (ADR)

Решение

Принято использовать инфраструктурный базовый класс:

BaseEngine

вместо минимального абстрактного класса.

Статус

Accepted

Обоснование

Платформа проектируется как система, включающая большое количество специализированных аналитических движков.

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

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

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

Последствия

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

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

---

Build Design

Создан файл:

app/src/trading/market_intelligence/engine/base.py

Класс содержит только инфраструктурные механизмы.

В его состав входят:

• получение EngineMetadata;
• единый метод analyze();
• базовая проверка входного контекста;
• защищённый метод _analyze_impl();
• нормализация результата;
• безопасное формирование результата при ошибке.

---

Implementation

Реализованы следующие элементы:

BaseEngine
├── ENGINE_METADATA
├── get_metadata()
├── analyze()
├── _validate_context()
├── _analyze_impl()
├── _normalize_result()
└── _build_error_result()

Все методы снабжены комментариями на русском языке в соответствии со стандартом проекта.

---

Compile Check

Проверка выполнена командой:

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

Build 014.3

Engine Exceptions

engine/exceptions.py