# Build 017 — Trading Layer Architecture

**Engineering Architecture Document**

---

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

| Свойство | Значение |
|----------|-----------|
| Build | 017 |
| Название | Trading Layer Architecture |
| Статус | **Accepted** |
| Подсистема | Trading |
| Тип | Architecture |
| Версия | 1.0 |
| Язык | Русский |

---

# Цель Build

Утвердить архитектуру Trading Layer как самостоятельного слоя платформы Dzentra.

Build не содержит реализации кода и фиксирует место Trading Layer в общей архитектуре системы.

---

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

После завершения Coordinator Layer аналитическая часть платформы заканчивается формированием объекта:

```text
CoordinatorResult
```

Дальнейшая задача платформы — принять торговое решение на основе уже готовой аналитики.

Поэтому вводится отдельный слой Trading Layer.

---

# Архитектурная роль

Trading Layer располагается между аналитической подсистемой Market Intelligence и слоем исполнения сделок.

Архитектурная цепочка выглядит следующим образом:

```text
Market Data
        │
        ▼
Market Intelligence
        │
        ▼
CoordinatorResult
        │
        ▼
Trading Layer
        │
        ▼
TradingDecision
        │
        ▼
Execution Layer
```

Таким образом Trading Layer полностью отделяет аналитическую часть платформы от исполнения торговых операций.

---

# Вход Trading Layer

Единственным входом является:

```text
CoordinatorResult
```

Trading Layer не обращается напрямую к:

- Engine;
- Runtime;
- Coordinator internals;
- Market Data.

Вся аналитическая информация поступает исключительно через публичную модель `CoordinatorResult`.

---

# Выход Trading Layer

Результатом работы Trading Layer станет:

```text
TradingDecision
```

Модель `TradingDecision` будет разработана в последующих Build.

На данном этапе фиксируется только её архитектурная роль.

---

# Ответственность Trading Layer

Trading Layer отвечает за:

- интерпретацию аналитического состояния рынка;
- применение торговых правил;
- выбор торгового действия;
- формирование итогового `TradingDecision`.

---

# Trading Layer не отвечает за

Следующие задачи находятся вне ответственности Trading Layer:

- анализ рыночных данных;
- запуск Engine;
- выполнение Runtime;
- внутреннюю работу Coordinator;
- исполнение ордеров;
- управление биржевым API;
- работу с Telegram;
- управление позициями;
- управление портфелем.

---

# Архитектурная структура

Trading Layer повторяет архитектурный шаблон Runtime Layer и Coordinator Layer.

Предварительная структура:

```text
trading/

├── common/
│
├── models.py
├── protocol.py
├── exceptions.py
├── validation.py
├── rules.py
└── service.py
```

---

# Ответственность компонентов

## models.py

Содержит модели Trading Layer.

Например:

- TradingDecision;
- диагностические модели;
- служебные структуры.

---

## protocol.py

Определяет официальный публичный контракт Trading Layer.

Будущий интерфейс:

```python
async def decide(
    coordinator_result: CoordinatorResult,
) -> TradingDecision:
    ...
```

---

## exceptions.py

Содержит собственную иерархию исключений Trading Layer.

Не использует исключения Coordinator Layer.

---

## validation.py

Проверяет корректность входного `CoordinatorResult`.

Не содержит торговых правил.

---

## rules.py

Центральный компонент Trading Layer.

Отвечает за:

- интерпретацию аналитики;
- применение торговых правил;
- выбор итогового торгового решения;
- формирование `TradingDecision`.

---

## service.py

Единая публичная точка входа Trading Layer.

Связывает:

```text
Validation
        │
        ▼
Rules
```

и предоставляет единый API внешним слоям платформы.

---

# Ограничения зависимостей

Trading Layer не должен иметь прямых зависимостей от:

- Engine Layer;
- Runtime internals;
- Coordinator internals;
- Exchange API;
- Telegram;
- базы данных;
- EventBus.

Взаимодействие с аналитической подсистемой осуществляется исключительно через `CoordinatorResult`.

---

# Architecture Review

Проверка подтвердила:

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

**Статус:** ✅ Passed

---

# Architecture Decision (ADR)

Принято решение выделить принятие торговых решений в отдельный слой платформы.

Trading Layer использует исключительно результат Coordinator и формирует независимый объект `TradingDecision`, который в дальнейшем станет входом для Execution Layer.

**Статус:** Accepted

---

# Последовательность Build 017.x

План дальнейшего развития Trading Layer:

```text
017      Trading Layer Architecture

017.1    Trading Models
017.2    Trading Protocol
017.3    Trading Exceptions
017.4    Trading Validation
017.5    Trading Rules
017.6    Trading Service
```

---

# Acceptance

Build завершён.

Выполнены:

- ✅ Development Strategy
- ✅ Architecture Design
- ✅ Architecture Review
- ✅ Architecture Decision (ADR)
- ✅ Build Design
- ✅ Documentation

Build не содержит реализации программного кода, поэтому этапы Implementation и Compile Check не требуются.

Статус Build:

```text
Accepted
```

---

# Итог

Build 017 открывает новый этап развития платформы Dzentra.

Если Build 013–016 сформировали аналитическую подсистему **Market Intelligence**, то начиная с Build 017 начинается построение **Trading Layer** — подсистемы принятия торговых решений.

Это завершает проектирование аналитической части платформы и создаёт фундамент для разработки профессиональной системы управления торговлей.

---

# Следующий Build

```text
Build 017.1

Trading Models

trading/common/models.py
```