# 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
```