# Build 014.1 — Engine Base Contracts / Engine Protocol

**Engineering Build Document**

---

# Контроль документа

| Свойство | Значение |
|----------|-----------|
| Build | 014.1 |
| Название | Engine Base Contracts / Engine Protocol |
| Статус | **Accepted** |
| Подсистема | Market Intelligence |
| Layer | Engine |
| Тип | Architecture + Implementation |
| Версия | 1.0 |
| Язык | Русский |

---

# Причина появления Build

После завершения проектирования **Engine Layer Architecture** началась разработка Runtime Layer.

Во время проектирования было выявлено, что Runtime не может зависеть от конкретных аналитических движков.

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

Настоящий Build вводит данный контракт.

---

# Цель Build

Создать минимальный контракт любого аналитического движка платформы **Market Intelligence**.

Контракт должен позволять Runtime взаимодействовать с любым Engine без знания его внутренней реализации.

---

# Architecture

Каждый Engine обязан предоставлять два обязательных элемента:

```text
EngineProtocol
├── get_metadata()
└── analyze(context)
```

Назначение методов:

- `get_metadata()` — предоставляет описание Engine без создания экземпляра.
- `analyze()` — выполняет анализ рыночного контекста и возвращает единый результат.

Engine не содержит Runtime-инфраструктуры и не определяет порядок выполнения других Engine.

---

# Architecture Review

Проверка показала соответствие архитектурным принципам проекта.

Подтверждено:

- Engine остаются независимыми друг от друга.
- Metadata полностью отделена от аналитической логики.
- Runtime сможет работать исключительно через контракт.
- Coordinator не зависит от реализации Engine.
- AutoTrade не затрагивается.

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

---

# Architecture Decision (ADR)

## Решение

Ввести единый контракт:

```text
EngineProtocol
```

## Статус

**Accepted**

## Обоснование

Runtime и будущий Coordinator должны работать с любым аналитическим движком посредством единого интерфейса.

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

Поэтому контракт включает:

- `get_metadata()`;
- `analyze(context)`.

## Последствия

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

- Runtime зависит только от `EngineProtocol`;
- новые Engine могут свободно добавляться в платформу;
- архитектурные зависимости остаются однонаправленными;
- Engine Layer получает единый официальный контракт.

---

# Build Design

Создан файл:

```text
app/src/trading/market_intelligence/engine/protocol.py
```

Файл содержит исключительно Protocol.

Он не содержит:

- реализации;
- аналитической логики;
- Runtime;
- Coordinator;
- Registry;
- инфраструктуры исполнения.

---

# Implementation

Реализован следующий контракт:

```python
class EngineProtocol(Protocol):

    @classmethod
    def get_metadata(cls) -> EngineMetadata:
        ...

    async def analyze(
        self,
        context: EngineContext,
    ) -> EngineResult:
        ...
```

Контракт использует только общие модели Common Layer:

- EngineContext;
- EngineMetadata;
- EngineResult.

---

# Compile Check

Проверено:

- файл успешно импортируется;
- отсутствуют циклические зависимости;
- используются только модели Common Layer;
- контракт не зависит от Runtime;
- контракт не зависит от Coordinator.

Build успешно проходит Compile Check.

---

# Domain Review

Проверено соответствие предметной области.

EngineProtocol:

- описывает исключительно контракт аналитического Engine;
- не содержит аналитической логики;
- не содержит Runtime;
- не содержит Coordinator;
- не содержит торговой логики;
- не зависит от конкретных Engine.

Контракт признан соответствующим архитектуре платформы.

---

# Documentation

В рамках Build обновлены:

- Build History;
- Runtime Contract;
- Engine Layer Architecture;
- Common Models Documentation.

---

# Acceptance

Build считается завершённым.

Выполнены:

- ✅ Architecture
- ✅ Architecture Review
- ✅ Architecture Decision (ADR)
- ✅ Build Design
- ✅ Implementation
- ✅ Compile Check
- ✅ Domain Review
- ✅ Documentation
- ✅ Acceptance

Статус Build:

**Accepted**

---

# Итоги Build

В результате Build 014.1:

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

---

# Следующий Build

```text
Build 014.2

Engine Base

engine/base.py
```