build 039: complete Quotes Feed migration foundation

docs/market_intelligence/builds/build-017-trading-layer-architecture.md

@@ -0,0 +1,325 @@
+# 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
+```