build 039: complete Quotes Feed migration foundation
This commit is contained in:
115
docs/market_intelligence/README.md
Normal file
115
docs/market_intelligence/README.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Market Intelligence
|
||||
|
||||
Документация подсистемы **Market Intelligence** проекта **Dzentra**.
|
||||
|
||||
---
|
||||
|
||||
# Назначение
|
||||
|
||||
Market Intelligence является аналитическим уровнем платформы.
|
||||
|
||||
Его задача — понимать текущее поведение рынка.
|
||||
|
||||
Market Intelligence не открывает сделки, не закрывает позиции и не управляет ордерами.
|
||||
|
||||
Он отвечает только на вопрос:
|
||||
|
||||
> **Что сейчас происходит с рынком?**
|
||||
|
||||
Все торговые решения принимаются верхними уровнями архитектуры платформы.
|
||||
|
||||
---
|
||||
|
||||
# Главная цель
|
||||
|
||||
Перевести Dzentra от модели
|
||||
|
||||
```text
|
||||
бот принимает решения по индикаторам
|
||||
```
|
||||
|
||||
к модели
|
||||
|
||||
```text
|
||||
профессиональная автономная торговая платформа,
|
||||
состоящая из специализированных аналитических движков
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Структура документации
|
||||
|
||||
| Документ | Назначение |
|
||||
|----------|------------|
|
||||
| `architecture_principles.md` | Архитектурные принципы Market Intelligence |
|
||||
| `runtime_contract.md` | Контракт работы всех Engine |
|
||||
| `build_history.md` | Общая история Build |
|
||||
| `builds/` | Полная документация каждого Build |
|
||||
| `decisions/` | Архитектурные решения |
|
||||
| `reviews/` | Compile Check, Architecture Review и Domain Review |
|
||||
| `common/` | Документация общего слоя |
|
||||
| `engines/` | Документация отдельных Engine |
|
||||
| `diagrams/` | Архитектурные схемы |
|
||||
| `glossary/` | Словарь терминов |
|
||||
| `roadmap/` | План развития платформы |
|
||||
|
||||
---
|
||||
|
||||
# Текущий фокус
|
||||
|
||||
Сейчас реализуется фундамент:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/
|
||||
```
|
||||
|
||||
Этот слой определяет единый язык для всех будущих Engine.
|
||||
|
||||
---
|
||||
|
||||
# Статус Common
|
||||
|
||||
| Файл | Статус |
|
||||
|------|---------|
|
||||
| enums.py | ✅ Accepted |
|
||||
| types.py | ✅ Accepted |
|
||||
| constants.py | ✅ Accepted |
|
||||
| reasons.py | ✅ Accepted |
|
||||
| scores.py | ✅ Accepted |
|
||||
| models.py | ✅ Accepted |
|
||||
| validation.py | ⏳ Planned |
|
||||
| checks.py | ⏳ Planned |
|
||||
| payloads.py | ⏳ Planned |
|
||||
| snapshots.py | ⏳ Planned |
|
||||
| events.py | ⏳ Planned |
|
||||
| timeframes.py | ⏳ Planned |
|
||||
|
||||
---
|
||||
|
||||
# Жизненный цикл разработки
|
||||
|
||||
```text
|
||||
Architecture Design
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Compile Check
|
||||
↓
|
||||
Architecture Review
|
||||
↓
|
||||
Domain Review
|
||||
↓
|
||||
Documentation Update
|
||||
↓
|
||||
User Confirmation
|
||||
↓
|
||||
Build Closed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Долгосрочная цель
|
||||
|
||||
Создать профессиональную аналитическую платформу, которую можно развивать годами без деградации архитектуры.
|
||||
|
||||
Добавление нового Engine не должно требовать переписывания уже существующих Engine.
|
||||
1610
docs/market_intelligence/architecture_principles.md
Normal file
1610
docs/market_intelligence/architecture_principles.md
Normal file
File diff suppressed because it is too large
Load Diff
296
docs/market_intelligence/build_history.md
Normal file
296
docs/market_intelligence/build_history.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Build History
|
||||
|
||||
Данный документ является общей историей разработки подсистемы **Market Intelligence**.
|
||||
|
||||
Каждый Build представляет собой логически завершённый этап развития архитектуры.
|
||||
|
||||
Подробное описание каждого Build хранится в каталоге:
|
||||
|
||||
```text
|
||||
docs/market_intelligence/builds/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Статусы Build
|
||||
|
||||
| Статус | Значение |
|
||||
|--------|----------|
|
||||
| ⏳ Planned | Build ещё не начат |
|
||||
| 🚧 In Progress | Build находится в разработке |
|
||||
| ✅ Accepted | Build полностью завершён |
|
||||
| 🔄 Replaced | Build заменён более новой реализацией |
|
||||
| ❌ Rejected | Build отклонён |
|
||||
|
||||
---
|
||||
|
||||
# История Build
|
||||
|
||||
| Build | Компонент | Статус | Документ |
|
||||
|------:|-----------|:------:|----------|
|
||||
| 001 | Common / Enums | ✅ | `build-001-common-enums.md` |
|
||||
| 002 | Common / Types | ✅ | `build-002-common-types.md` |
|
||||
| 003 | Common / Constants | ✅ | `build-003-common-constants.md` |
|
||||
| 004 | Common / Reasons | ✅ | `build-004-common-reasons.md` |
|
||||
| 005 | Common / Scores | ✅ | `build-005-common-scores.md` |
|
||||
| 006 | Common / Models | ✅ | `build-006-common-models.md` |
|
||||
| 006.1 | Common / Models Extension (EngineMetadata) | ✅ | `build-006-1-common-models-engine-metadata.md` |
|
||||
| 007 | Common / Validation | ✅ | `build-007-common-validation.md` |
|
||||
| 008 | Common / Checks | ✅ | `build-008-common-checks.md` |
|
||||
| 009 | Common / Payloads | ✅ | `build-009-common-payloads.md` |
|
||||
| 010 | Common / Snapshots | ✅ | `build-010-common-snapshots.md` |
|
||||
| 011 | Common / Events | ✅ | `build-011-common-events.md` |
|
||||
| 012 | Common / Timeframes | ✅ | `build-012-common-timeframes.md` |
|
||||
| 013 | Engine Layer Architecture | ✅ | `build-013-engine-layer-architecture.md` |
|
||||
| 014.1 | Engine Base Contracts / Engine Protocol | ✅ | `build-014-1-engine-protocol.md` |
|
||||
| 014.2 | Engine Base / BaseEngine | ✅ | `build-014-2-engine-base.md` |
|
||||
| 014.3 | Engine Exceptions | ✅ | `build-014-3-engine-exceptions.md` |
|
||||
| 015.1 | Common Models Extension / RuntimeResult | ✅ | `build-015-1-common-models-runtime-result.md` |
|
||||
| 015.2 | Runtime Layer / Runtime Protocol | ✅ | `build-015-2-runtime-protocol.md` |
|
||||
| 015.3 | Common Models Extension / EngineRegistration | ✅ | `build-015-3-common-models-engine-registration.md` |
|
||||
| 015.4 | Runtime Layer / Runtime Registry | ✅ | `build-015-4-runtime-registry.md` |
|
||||
| 015.5 | Runtime Layer / Runtime Core | ✅ | `build-015-5-runtime-core.md` |
|
||||
| 015.6 | Runtime Layer / Runtime Dependencies | ✅ | `build-015-6-runtime-dependencies.md` |
|
||||
| 015.7 | Runtime Layer / Runtime Validation | ✅ | `build-015-7-runtime-validation.md` |
|
||||
| 015.8 | Runtime Layer / Runtime Service | ✅ | `build-015-8-runtime-service.md` |
|
||||
| 016 | Coordinator Layer Architecture | ✅ | `build-016-coordinator-layer-architecture.md` |
|
||||
| 016.1 | Common Models Extension / CoordinatorResult | ✅ | `build-016-1-common-models-coordinator-result.md` |
|
||||
| 016.2 | Coordinator Layer / Coordinator Protocol | ✅ | `build-016-2-coordinator-protocol.md` |
|
||||
| 016.3 | Coordinator Layer / Coordinator Exceptions | ✅ | `build-016-3-coordinator-exceptions.md` |
|
||||
| 016.4 | Coordinator Layer / Coordinator Validation | ✅ | `build-016-4-coordinator-validation.md` |
|
||||
| 016.5 | Coordinator Layer / Coordinator Rules | ✅ | `build-016-5-coordinator-rules.md` |
|
||||
| 016.6 | Coordinator Layer / Coordinator Service | ✅ | `build-016-6-coordinator-service.md` |
|
||||
| 017 | Trading Layer Architecture | ✅ | `build-017-trading-layer-architecture.md` |
|
||||
| 017.1 | Trading Layer / Trading Models | ✅ | `build-017-1-trading-models.md` |
|
||||
| 017.2 | Trading Layer / Trading Protocol | ✅ | `build-017-2-trading-protocol.md` |
|
||||
| 017.3 | Trading Layer / Trading Exceptions | ✅ | `build-017-3-trading-exceptions.md` |
|
||||
| 017.4 | Trading Layer / Trading Validation | ✅ | `build-017-4-trading-validation.md` |
|
||||
| 017.5 | Trading Layer / Trading Rules | ✅ | `build-017-5-trading-rules.md` |
|
||||
| 017.6 | Trading Layer / Trading Service | ✅ | `build-017-6-trading-service.md` |
|
||||
| 017.7 | Trading Boundary Correction | ✅ | `build-017-7-trading-boundary-correction.md` |
|
||||
|
||||
---
|
||||
|
||||
# Текущий прогресс Common
|
||||
|
||||
| Компонент | Готовность |
|
||||
|-----------|-----------:|
|
||||
| Enums | 100% |
|
||||
| Types | 100% |
|
||||
| Constants | 100% |
|
||||
| Reasons | 100% |
|
||||
| Scores | 100% |
|
||||
| Models | 100% |
|
||||
| Validation | 100% |
|
||||
| Checks | 100% |
|
||||
| Payloads | 100% |
|
||||
| Snapshots | 100% |
|
||||
| Events | 100% |
|
||||
| Timeframes | 100% |
|
||||
|
||||
> Build 015.1 расширил Common Layer новой моделью RuntimeResult без изменения его архитектурной структуры.
|
||||
> Build 015.3 расширил Common Layer новой моделью `EngineRegistration`, необходимой для реализации Runtime Registry, без изменения архитектуры Common Layer.
|
||||
|
||||
**Common Layer завершён полностью.**
|
||||
|
||||
---
|
||||
|
||||
# Текущий прогресс Runtime
|
||||
|
||||
| Компонент | Готовность |
|
||||
|-----------|-----------:|
|
||||
| Runtime Architecture | 100% |
|
||||
| Runtime Models | ✅ Completed |
|
||||
| Protocol | ✅ Completed |
|
||||
| Registry | ✅ Completed |
|
||||
| Runner | ✅ Completed |
|
||||
| Runtime Exceptions | ✅ Completed |
|
||||
| Dependencies | ✅ Completed |
|
||||
| Runtime Validation | ✅ Completed |
|
||||
| Runtime Service | ✅ Completed |
|
||||
|
||||
> Build 015.5 реализовал `RuntimeRunner` — компонент Runtime Layer, отвечающий исключительно за создание экземпляра зарегистрированного Engine и вызов его метода `analyze()`.
|
||||
>
|
||||
> Во время Code Review Build 015.5 обнаружено частичное дублирование контрактов `EngineProtocol` и `EngineTypeProtocol`. Для обеспечения корректной статической типизации в `EngineTypeProtocol` добавлен метод `analyze()`. Архитектурное объединение контрактов не входит в Build 015.5 и может быть рассмотрено отдельным Build после завершения Runtime Layer.
|
||||
>
|
||||
> Build 015.6 реализовал `RuntimeDependencies`, отвечающий за проверку обязательных зависимостей Engine и построение порядка их выполнения посредством топологической сортировки. Компонент не выполняет Engine и не содержит аналитической логики.
|
||||
|
||||
> Build 015.7 реализовал `RuntimeValidation` — централизованный компонент проверки готовности Runtime Layer. Компонент валидирует Registry и Metadata зарегистрированных Engine, а проверку зависимостей делегирует `RuntimeDependencies`, сохраняя принцип единственной ответственности.
|
||||
>
|
||||
> Во время Code Review подтверждено, что проверка повторной регистрации Engine в текущей реализации `RuntimeRegistry` практически недостижима из-за хранения регистраций в словаре. Тем не менее данная проверка сохранена как часть публичного контракта `RuntimeValidation` для обеспечения устойчивости архитектуры при возможном изменении внутренней реализации Registry.
|
||||
|
||||
---
|
||||
|
||||
# Текущий прогресс Coordinator
|
||||
|
||||
| Компонент | Готовность |
|
||||
|-----------|-----------:|
|
||||
| Coordinator Architecture | ✅ Completed |
|
||||
| Coordinator Models | ✅ Completed |
|
||||
| Protocol | ✅ Completed |
|
||||
| Exceptions | ✅ Completed |
|
||||
| Validation | ✅ Completed |
|
||||
| Rules | ✅ Completed |
|
||||
| Service | ✅ Completed |
|
||||
|
||||
|
||||
> Build 016 утвердил архитектуру Coordinator Layer и определил его место между Runtime Layer и будущим Trading Layer.
|
||||
> Build не содержит реализации компонентов и фиксирует только архитектурные решения.
|
||||
|
||||
> Build 016.1 расширил Common Layer новой межслойной моделью `CoordinatorResult`, а также моделями `CoordinatorDiagnostics` и `CoordinatorEvaluationMeta`. Coordinator Layer получил официальный выходной контракт без нарушения архитектурных границ Common Layer.
|
||||
|
||||
> Build 016.2 добавил официальный публичный контракт `CoordinatorProtocol`, завершив формирование базового интерфейса Coordinator Layer. Контракт определяет единственную точку входа Coordinator и отделяет внешний API слоя от его будущей реализации.
|
||||
|
||||
> Build 016.3 добавил собственную иерархию исключений Coordinator Layer (`CoordinatorError`, `InvalidCoordinatorResultError`, `CoordinatorValidationError`, `CoordinatorExecutionError`). Coordinator окончательно отделён от Runtime Layer в части обработки ошибок и получил собственное пространство исключений.
|
||||
|
||||
> Build 016.4 добавил компонент `CoordinatorValidation`, выполняющий предварительную проверку входного `RuntimeResult`. Validation отделён от правил согласования и обеспечивает корректность входных данных до начала работы Coordinator Layer.
|
||||
|
||||
> Build 016.5 реализовал компонент `CoordinatorRules`, отвечающий за преобразование `RuntimeResult` в `CoordinatorResult`. На текущем этапе создан базовый каркас согласования результатов Engine без реализации сложных механизмов весов, разрешения конфликтов и вероятностных моделей. Архитектура подготовлена к постепенному развитию правил согласования по мере появления специализированных Engine.
|
||||
|
||||
> Build 016.6 завершил построение Coordinator Foundation, реализовав `CoordinatorService` — единую публичную точку входа Coordinator Layer. Service инкапсулирует `CoordinatorValidation` и `CoordinatorRules`, обеспечивая единый жизненный цикл обработки `RuntimeResult` и формирование итогового `CoordinatorResult`.
|
||||
|
||||
---
|
||||
|
||||
# Текущий прогресс Decision
|
||||
|
||||
| Компонент | Готовность |
|
||||
|-----------|-----------:|
|
||||
| Decision Architecture | ✅ Completed |
|
||||
| Models | ✅ Completed |
|
||||
| Protocol | ✅ Completed |
|
||||
| Exceptions | ✅ Completed |
|
||||
| Validation | ✅ Completed |
|
||||
| Rules | ✅ Completed |
|
||||
| Service | ✅ Completed |
|
||||
|
||||
> Build 017 утвердил архитектуру Trading Layer как самостоятельной подсистемы платформы Dzentra. Trading Layer использует `CoordinatorResult` как единственный аналитический вход и формирует `TradingDecision` — независимый объект, описывающий итоговое торговое решение. Реализация компонентов Trading Layer начинается с Build 017.1.
|
||||
|
||||
> Build 017.1 расширил Common Layer моделями Trading Layer. Добавлены `TradingDiagnostics`, `TradingEvaluationMeta` и `TradingDecision`. `TradingDecision` становится официальным выходным контрактом Trading Layer и одновременно входным контрактом для будущих слоёв Execution, Risk и Portfolio. Модель намеренно содержит только общие характеристики торгового решения без конкретных торговых действий, размеров позиции или планов исполнения.
|
||||
|
||||
> Build 017.2 реализовал `TradingProtocol` — официальный публичный контракт Trading Layer. Trading Layer теперь имеет единый интерфейс взаимодействия: принимает `CoordinatorResult` и возвращает `TradingDecision`. Контракт полностью изолирован от Runtime, Coordinator internals, биржевой инфраструктуры и содержит исключительно описание публичного API без реализации.
|
||||
|
||||
> Build 017.3 сформировал собственое пространство исключений Trading Layer. Добавлены `TradingError`, `InvalidTradingDecisionError`, `TradingValidationError` и `TradingExecutionError`. Иерархия полностью изолирована от Runtime Layer и Coordinator Layer и станет единым механизмом обработки ошибок для будущих компонентов Validation, Rules и Service.
|
||||
|
||||
> Build 017.4 реализовал `TradingValidation` — компонент предварительной проверки входного `CoordinatorResult`. Validation использует только публичный контракт Coordinator (`is_usable` и `has_errors`), не зависит от внутренних статусов Coordinator и отделяет проверку входных данных от бизнес-логики Trading Layer. Это стало первым архитектурным улучшением по сравнению с Coordinator Foundation, усилив слабую связанность между слоями.
|
||||
|
||||
> Build 017.5 реализовал `TradingRules` — центральный компонент Trading Layer, отвечающий за преобразование `CoordinatorResult` в `TradingDecision`. На этапе Foundation Rules формирует только базовый объект `TradingDecision` без реализации торговых стратегий, расчёта риска, управления позицией или исполнения сделок. Это обеспечивает стабильный публичный контракт и позволяет в дальнейшем расширять бизнес-логику без изменения архитектуры слоя.
|
||||
|
||||
> Build 017.6 завершил построение Trading Foundation. Реализован `TradingService` — единая публичная точка входа Trading Layer, объединяющая `TradingValidation` и `TradingRules`. Внешние компоненты платформы взаимодействуют с Trading Layer исключительно через `TradingProtocol`, что завершает формирование единого архитектурного стандарта для слоя.
|
||||
|
||||
---
|
||||
|
||||
## Архитектурная коррекция
|
||||
|
||||
| Build | Описание | Статус |
|
||||
|-------:|----------|:------:|
|
||||
| 017.7 | Перенос Trading Foundation из `market_intelligence` в самостоятельный слой `decision` | ✅ |
|
||||
|
||||
---
|
||||
|
||||
# Общий прогресс архитектуры Dzentra
|
||||
|
||||
| Layer | Состояние |
|
||||
|--------|----------|
|
||||
| Common Foundation | ✅ Completed |
|
||||
| Engine Foundation | ✅ Completed |
|
||||
| Runtime Foundation | ✅ Completed |
|
||||
| Coordinator Foundation | ✅ Completed |
|
||||
| Decision Foundation | ✅ Completed |
|
||||
| Execution Architecture | ⏳ Planned |
|
||||
|
||||
> Build 017 сформировал фундамент будущего Decision Layer. Build 017.7 завершил архитектурную декомпозицию, выделив Decision в самостоятельную подсистему, полностью отделённую от Market Intelligence.
|
||||
|
||||
> Начиная с Build 017.4 в Dzentra закрепляется принцип взаимодействия между слоями исключительно через публичные контракты. Trading Layer использует свойства `CoordinatorResult.is_usable` и `CoordinatorResult.has_errors`, не анализируя внутренние статусы Coordinator. Это снижает связанность подсистем и позволяет изменять внутреннюю реализацию Coordinator без изменения Trading Layer.
|
||||
|
||||
> Build 017.6 завершил формирование Trading Foundation. Платформа Dzentra теперь имеет три полностью реализованных базовых слоя: Runtime Foundation, Coordinator Foundation и Trading Foundation. Все они построены по единому архитектурному шаблону (`Protocol → Validation → Rules → Service`), что обеспечивает единообразие разработки, тестирования и дальнейшего развития системы.
|
||||
|
||||
> Build 017.7 завершил архитектурную декомпозицию платформы. Trading Foundation был выделен в самостоятельный слой `src/trading/decision`, полностью отделённый от `market_intelligence`. Это восстановило принцип единственной ответственности: Market Intelligence отвечает исключительно за анализ рынка, а Decision Layer — за принятие торгового решения.
|
||||
|
||||
---
|
||||
|
||||
# Итоговая схема платформы
|
||||
|
||||
После Build 017.7 верхнеуровневая архитектура Dzentra выглядит следующим образом:
|
||||
|
||||
```text
|
||||
Market Data
|
||||
│
|
||||
▼
|
||||
Market Intelligence
|
||||
│
|
||||
├── Common
|
||||
├── Engine
|
||||
├── Runtime
|
||||
└── Coordinator
|
||||
│
|
||||
▼
|
||||
Decision
|
||||
│
|
||||
├── Models
|
||||
├── Protocol
|
||||
├── Validation
|
||||
├── Rules
|
||||
└── Service
|
||||
│
|
||||
▼
|
||||
Execution
|
||||
│
|
||||
▼
|
||||
Exchange
|
||||
```
|
||||
|
||||
Данная схема отражает окончательное разделение ответственности между анализом рынка, принятием торгового решения и будущим слоем исполнения.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная веха
|
||||
|
||||
Build 017.7 завершает первый крупный этап разработки Dzentra.
|
||||
|
||||
Полностью реализованы фундаментальные слои платформы:
|
||||
|
||||
• Common Foundation
|
||||
• Engine Foundation
|
||||
• Runtime Foundation
|
||||
• Coordinator Foundation
|
||||
• Decision Foundation
|
||||
|
||||
Во всех слоях используется единый архитектурный стандарт:
|
||||
|
||||
Protocol
|
||||
↓
|
||||
Validation
|
||||
↓
|
||||
Rules
|
||||
↓
|
||||
Service
|
||||
|
||||
Это означает, что дальнейшие подсистемы (Execution, Risk, Portfolio и другие) будут строиться по уже утверждённому шаблону, без изменения существующих публичных контрактов.
|
||||
|
||||
Следующий этап развития платформы — построение Execution Layer, который станет первым потребителем `TradingDecision` и будет отвечать за преобразование торгового решения в конкретные действия по исполнению.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 018
|
||||
|
||||
Execution Layer Architecture
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Правило сопровождения
|
||||
|
||||
После завершения каждого Build обязательно выполняются следующие этапы:
|
||||
|
||||
1. Compile Check (если есть исходный код).
|
||||
2. Architecture Review.
|
||||
3. Domain Review.
|
||||
4. Documentation Review.
|
||||
5. Обновление документации Build.
|
||||
6. Обновление Build History.
|
||||
7. Подтверждение пользователем завершения Build.
|
||||
|
||||
Только после завершения полного жизненного цикла допускается переход к следующему Build.
|
||||
77
docs/market_intelligence/builds/build-001-common-enums.md
Normal file
77
docs/market_intelligence/builds/build-001-common-enums.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# Build №001 — Common Enums
|
||||
|
||||
## Файл
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/enums.py
|
||||
```
|
||||
|
||||
## Назначение
|
||||
|
||||
Создание единого набора перечислений, используемых всеми аналитическими движками Market Intelligence.
|
||||
|
||||
Файл определяет общий язык состояний, статусов, уровней уверенности, ролей таймфреймов и этапов обработки.
|
||||
|
||||
---
|
||||
|
||||
## Реализовано
|
||||
|
||||
Добавлены перечисления:
|
||||
|
||||
- `MarketDirection`
|
||||
- `MarketBias`
|
||||
- `MarketPhase`
|
||||
- `MarketRegime`
|
||||
- `MarketQuality`
|
||||
- `EngineStatus`
|
||||
- `ConfidenceLevel`
|
||||
- `SignalFreshness`
|
||||
- `RiskLevel`
|
||||
- `TimeframeRole`
|
||||
- `CheckStatus`
|
||||
- `ProcessingStage`
|
||||
|
||||
---
|
||||
|
||||
## Архитектурные решения
|
||||
|
||||
- перечисления не содержат торговой логики;
|
||||
- перечисления не принимают торговых решений;
|
||||
- значения используются только для описания состояния рынка и работы движков;
|
||||
- проверки движков описываются через смысловые этапы обработки, а не через имена файлов;
|
||||
- добавлен `ConfidenceLevel` для человекочитаемой интерпретации числовой уверенности;
|
||||
- добавлен `SKIPPED` для корректного описания намеренно пропущенных проверок.
|
||||
|
||||
---
|
||||
|
||||
## Compile Check
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Architecture Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Domain Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
## Рекомендации
|
||||
|
||||
В будущем `ProcessingStage` можно расширить, если появится реальная необходимость. До этого перечисление не расширяется заранее.
|
||||
|
||||
## Статус
|
||||
|
||||
```text
|
||||
ACCEPTED
|
||||
```
|
||||
96
docs/market_intelligence/builds/build-002-common-types.md
Normal file
96
docs/market_intelligence/builds/build-002-common-types.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Build №002 — Common Types
|
||||
|
||||
## Файл
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/types.py
|
||||
```
|
||||
|
||||
## Назначение
|
||||
|
||||
Создание общего набора типовых алиасов для подсистемы Market Intelligence.
|
||||
|
||||
Файл определяет единый типовой контракт для будущих Engine, payload, диагностики и результатов анализа.
|
||||
|
||||
---
|
||||
|
||||
## Реализовано
|
||||
|
||||
Добавлены типы:
|
||||
|
||||
- `SymbolName`
|
||||
- `TimeframeName`
|
||||
- `EngineName`
|
||||
- `EngineVersion`
|
||||
- `ReasonCode`
|
||||
- `ReasonText`
|
||||
- `ScoreValue`
|
||||
- `ConfidenceValue`
|
||||
- `ProbabilityValue`
|
||||
- `WeightValue`
|
||||
- `AgeSeconds`
|
||||
- `DurationMs`
|
||||
- `MetricsDict`
|
||||
- `PayloadDict`
|
||||
- `ContextDict`
|
||||
- `MarketData`
|
||||
- `DependencyResults`
|
||||
- `DiagnosticMessages`
|
||||
- `DiagnosticValue`
|
||||
|
||||
Повторно используются существующие типы проекта:
|
||||
|
||||
- `JsonDict`
|
||||
- `JsonList`
|
||||
|
||||
из:
|
||||
|
||||
```text
|
||||
src.core.types
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Архитектурные решения
|
||||
|
||||
- используется существующий `core.types` как единый источник истины;
|
||||
- не создаются дубли `JsonDict` и `JsonList`;
|
||||
- файл не зависит от runtime, execution, Telegram, Journal, EventBus или Exchange;
|
||||
- файл не содержит торговой логики;
|
||||
- комментарии объясняют назначение типов, а не синтаксис Python.
|
||||
|
||||
---
|
||||
|
||||
## Compile Check
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Architecture Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Domain Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
## Рекомендации
|
||||
|
||||
`DependencyResults` временно использует `Any`. После появления `EngineResult` в `common/models.py` рекомендуется заменить значение словаря на специализированный тип результата движка.
|
||||
|
||||
В будущем допускается переход от универсальных словарей `PayloadDict`, `MetricsDict`, `ContextDict` к специализированным `TypedDict`, если это потребуется для усиления типизации.
|
||||
|
||||
## Статус
|
||||
|
||||
```text
|
||||
ACCEPTED
|
||||
```
|
||||
126
docs/market_intelligence/builds/build-003-common-constants.md
Normal file
126
docs/market_intelligence/builds/build-003-common-constants.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Build №003 — Common Constants
|
||||
|
||||
## Файл
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/constants.py
|
||||
```
|
||||
|
||||
## Назначение
|
||||
|
||||
Создание общего набора архитектурных констант Market Intelligence.
|
||||
|
||||
Файл определяет безопасные диапазоны значений, ограничения диагностики, базовые настройки свежести данных и защитные ограничения аналитического слоя.
|
||||
|
||||
---
|
||||
|
||||
## Реализовано
|
||||
|
||||
Добавлены группы констант:
|
||||
|
||||
- диапазоны `score`;
|
||||
- диапазоны `confidence`;
|
||||
- диапазоны `probability`;
|
||||
- диапазоны `weight`;
|
||||
- значения по умолчанию;
|
||||
- пороги человекочитаемой оценки;
|
||||
- время устаревания аналитического результата;
|
||||
- время жизни аналитического сигнала;
|
||||
- ограничения количества зависимостей Engine;
|
||||
- ограничения количества метрик;
|
||||
- ограничения количества предупреждений и ошибок;
|
||||
- базовая конфигурация таймфреймов;
|
||||
- запрещённые торговые поля.
|
||||
|
||||
---
|
||||
|
||||
## Архитектурные решения
|
||||
|
||||
- `common/constants.py` содержит только архитектурные ограничения платформы;
|
||||
- файл не содержит параметров технических индикаторов;
|
||||
- файл не содержит параметров торговых стратегий;
|
||||
- файл не содержит настроек открытия или закрытия сделок;
|
||||
- константы не зависят от конкретного Engine;
|
||||
- `FORBIDDEN_TRADING_FIELDS` вводит защиту границ между аналитикой и торговыми действиями.
|
||||
|
||||
---
|
||||
|
||||
## Compile Check
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Architecture Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Domain Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
## Post Review Notes
|
||||
|
||||
### Решение №001
|
||||
|
||||
Архитектурные константы должны содержать только ограничения платформы.
|
||||
|
||||
В `common/constants.py` запрещается размещать:
|
||||
|
||||
- параметры технических индикаторов;
|
||||
- параметры торговых стратегий;
|
||||
- настройки открытия и закрытия сделок;
|
||||
- параметры биржи;
|
||||
- параметры управления позицией.
|
||||
|
||||
Такие константы должны размещаться внутри соответствующих Engine.
|
||||
|
||||
### Решение №002
|
||||
|
||||
Константы должны быть сгруппированы по смысловым разделам:
|
||||
|
||||
```text
|
||||
Score
|
||||
Confidence
|
||||
Probability
|
||||
Runtime
|
||||
Diagnostics
|
||||
Architecture
|
||||
Timeframes
|
||||
Safety
|
||||
```
|
||||
|
||||
### Решение №003
|
||||
|
||||
Таймфреймы являются частью конфигурации платформы, а не жёстким ограничением архитектуры.
|
||||
|
||||
`DEFAULT_TIMEFRAMES` описывает базовую конфигурацию первого этапа Market Intelligence.
|
||||
|
||||
### Решение №004
|
||||
|
||||
Возраст результата анализа и возраст торгового сигнала являются разными понятиями.
|
||||
|
||||
- `DEFAULT_STALE_AFTER_SECONDS` — когда аналитический результат считается устаревшим.
|
||||
- `DEFAULT_SIGNAL_TTL_SECONDS` — когда влияние аналитического сигнала начинает уменьшаться.
|
||||
|
||||
### Решение №005
|
||||
|
||||
Константы, относящиеся только к одному Engine, не должны находиться в `common/constants.py`.
|
||||
|
||||
Они должны переноситься в каталог соответствующего Engine.
|
||||
|
||||
---
|
||||
|
||||
## Статус
|
||||
|
||||
```text
|
||||
ACCEPTED
|
||||
```
|
||||
101
docs/market_intelligence/builds/build-004-common-reasons.md
Normal file
101
docs/market_intelligence/builds/build-004-common-reasons.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Build №004 — Common Reasons
|
||||
|
||||
## Файл
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/reasons.py
|
||||
```
|
||||
|
||||
## Назначение
|
||||
|
||||
Создание единого реестра машинных кодов причин `ReasonCode`.
|
||||
|
||||
Файл определяет стандартный словарь причин, который используется будущими Engine для диагностики, payload, snapshot, событий и журналирования.
|
||||
|
||||
---
|
||||
|
||||
## Реализовано
|
||||
|
||||
Добавлен класс:
|
||||
|
||||
```text
|
||||
ReasonCode
|
||||
```
|
||||
|
||||
Он содержит группы причин для следующих областей:
|
||||
|
||||
- Common;
|
||||
- Data;
|
||||
- Engine Runtime;
|
||||
- Validation;
|
||||
- Market State;
|
||||
- Structure;
|
||||
- Trend;
|
||||
- Momentum;
|
||||
- Volatility;
|
||||
- Wave;
|
||||
- Cycle;
|
||||
- Liquidity;
|
||||
- Regime;
|
||||
- Confidence;
|
||||
- Signal Aging;
|
||||
- Timeframe.
|
||||
|
||||
---
|
||||
|
||||
## Архитектурные решения
|
||||
|
||||
- движки публикуют стандартизированные коды причин;
|
||||
- движки не формируют человекочитаемый текст;
|
||||
- причины отделены от пользовательского интерфейса;
|
||||
- причины не содержат торговых действий;
|
||||
- единый словарь причин используется всеми Engine платформы;
|
||||
- причины описывают состояние рынка или состояние работы движка.
|
||||
|
||||
---
|
||||
|
||||
## Compile Check
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Architecture Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Domain Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
## Рекомендации
|
||||
|
||||
После завершения базовых моделей рекомендуется реализовать отдельный слой формирования человекочитаемых объяснений.
|
||||
|
||||
Возможное имя файла:
|
||||
|
||||
```text
|
||||
common/reason_texts.py
|
||||
```
|
||||
|
||||
или:
|
||||
|
||||
```text
|
||||
common/explanations.py
|
||||
```
|
||||
|
||||
Этот слой будет преобразовывать `ReasonCode` в понятные сообщения для журнала, интерфейса и отчётов.
|
||||
|
||||
## Статус
|
||||
|
||||
```text
|
||||
ACCEPTED
|
||||
```
|
||||
88
docs/market_intelligence/builds/build-005-common-scores.md
Normal file
88
docs/market_intelligence/builds/build-005-common-scores.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Build №005 — Common Scores
|
||||
|
||||
## Файл
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/scores.py
|
||||
```
|
||||
|
||||
## Назначение
|
||||
|
||||
Создание единого слоя оценок для Market Intelligence.
|
||||
|
||||
Файл определяет общий способ работы с:
|
||||
|
||||
- score;
|
||||
- confidence;
|
||||
- probability;
|
||||
- weight;
|
||||
- weighted score;
|
||||
- score breakdown.
|
||||
|
||||
---
|
||||
|
||||
## Реализовано
|
||||
|
||||
Добавлены функции:
|
||||
|
||||
- `clamp_score`
|
||||
- `clamp_confidence`
|
||||
- `clamp_probability`
|
||||
- `clamp_weight`
|
||||
- `classify_score_quality`
|
||||
- `classify_confidence_level`
|
||||
|
||||
Добавлены модели:
|
||||
|
||||
- `EngineScore`
|
||||
- `EngineConfidence`
|
||||
- `ProbabilityScore`
|
||||
- `WeightedScore`
|
||||
- `ScoreBreakdown`
|
||||
|
||||
---
|
||||
|
||||
## Архитектурные решения
|
||||
|
||||
- все числовые оценки приводятся к безопасным диапазонам;
|
||||
- score всегда работает в диапазоне `0...100`;
|
||||
- confidence всегда работает в диапазоне `0...1`;
|
||||
- probability всегда работает в диапазоне `0...100`;
|
||||
- weight всегда работает в диапазоне `0...1`;
|
||||
- числовые значения получают человекочитаемую интерпретацию;
|
||||
- итоговая оценка может объясняться через `ScoreBreakdown`;
|
||||
- файл не содержит торговых решений.
|
||||
|
||||
---
|
||||
|
||||
## Compile Check
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Architecture Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Domain Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
## Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
## Рекомендации
|
||||
|
||||
После появления `common/validation.py` часть проверок диапазонов может быть повторно использована в механизме валидации EngineResult и Payload.
|
||||
|
||||
## Статус
|
||||
|
||||
```text
|
||||
ACCEPTED
|
||||
```
|
||||
@@ -0,0 +1,268 @@
|
||||
# Build 006.1 — Common Models Extension / EngineMetadata
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
## Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 006.1 |
|
||||
| Название | Common Models Extension / EngineMetadata |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Common |
|
||||
| Тип | Architecture Extension |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
## Причина появления Build
|
||||
|
||||
Во время проектирования **Engine Layer** было обнаружено, что базовый контракт Engine требует наличия модели, описывающей сам Engine как архитектурный компонент.
|
||||
|
||||
Первоначально предполагалось, что данная модель относится к Engine Layer.
|
||||
|
||||
Однако архитектурный анализ показал, что она используется значительно шире.
|
||||
|
||||
Модель необходима для:
|
||||
|
||||
- Engine Layer;
|
||||
- Runtime Layer;
|
||||
- будущего Registry;
|
||||
- будущего Coordinator;
|
||||
- построения графа зависимостей;
|
||||
- диагностики;
|
||||
- документации.
|
||||
|
||||
Следовательно, данная модель является частью **Common Layer**, а не Engine Layer.
|
||||
|
||||
Для сохранения чистоты архитектуры было принято решение выпустить отдельный Build 006.1 вместо изменения уже принятого Build 006.
|
||||
|
||||
---
|
||||
|
||||
## Цель Build
|
||||
|
||||
Добавить в Common Layer новую базовую модель:
|
||||
|
||||
```text
|
||||
EngineMetadata
|
||||
```
|
||||
|
||||
которая описывает Engine как компонент платформы, а не результат его работы.
|
||||
|
||||
---
|
||||
|
||||
## Архитектурное решение
|
||||
|
||||
Модель размещается в:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/models.py
|
||||
```
|
||||
|
||||
а не в:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/engine/
|
||||
```
|
||||
|
||||
поскольку является общим контрактом платформы.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Decision (ADR)
|
||||
|
||||
### Решение
|
||||
|
||||
Добавить модель `EngineMetadata` в Common Layer.
|
||||
|
||||
### Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
### Обоснование
|
||||
|
||||
Во время проектирования Engine Layer было установлено, что описание Engine используется не только самим Engine, но и Runtime, Registry, Coordinator и другими архитектурными компонентами.
|
||||
|
||||
Следовательно, `EngineMetadata` является общим контрактом платформы и должна располагаться в `common.models`.
|
||||
|
||||
Размещение модели в Engine Layer привело бы к неправильному направлению архитектурных зависимостей и нарушило бы принцип повторного использования общих моделей.
|
||||
|
||||
### Последствия
|
||||
|
||||
После принятия решения:
|
||||
|
||||
- Engine Layer использует `EngineMetadata` из Common Layer;
|
||||
- Runtime зависит только от общих контрактов;
|
||||
- Coordinator сможет получать описание Engine без знания его реализации;
|
||||
- архитектурные зависимости остаются однонаправленными.
|
||||
|
||||
---
|
||||
|
||||
## Состав модели
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class EngineMetadata:
|
||||
# Описание Engine как компонента платформы.
|
||||
# Metadata не содержит аналитической логики и не является результатом анализа.
|
||||
# Она используется Runtime, Registry, Coordinator и документацией.
|
||||
name: EngineName
|
||||
version: EngineVersion
|
||||
description: str = ""
|
||||
supported_timeframes: tuple[TimeframeName, ...] = ()
|
||||
required_dependencies: tuple[EngineName, ...] = ()
|
||||
optional_dependencies: tuple[EngineName, ...] = ()
|
||||
enabled_by_default: bool = True
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Обоснование полей
|
||||
|
||||
### name
|
||||
|
||||
Уникальное имя Engine.
|
||||
|
||||
Используется Registry, Coordinator и журналированием.
|
||||
|
||||
---
|
||||
|
||||
### version
|
||||
|
||||
Версия реализации Engine.
|
||||
|
||||
Позволяет определять, какая именно версия логики сформировала результат анализа.
|
||||
|
||||
---
|
||||
|
||||
### description
|
||||
|
||||
Краткое описание назначения Engine.
|
||||
|
||||
Используется документацией, диагностикой и интерфейсами разработчика.
|
||||
|
||||
---
|
||||
|
||||
### supported_timeframes
|
||||
|
||||
Перечень поддерживаемых таймфреймов.
|
||||
|
||||
Позволяет Coordinator определить применимость Engine для конкретного анализа.
|
||||
|
||||
---
|
||||
|
||||
### required_dependencies
|
||||
|
||||
Перечень обязательных зависимостей.
|
||||
|
||||
Если хотя бы один требуемый Engine недоступен, выполнение данного Engine невозможно.
|
||||
|
||||
---
|
||||
|
||||
### optional_dependencies
|
||||
|
||||
Перечень необязательных зависимостей.
|
||||
|
||||
Их отсутствие не запрещает выполнение Engine, но может снизить качество анализа.
|
||||
|
||||
---
|
||||
|
||||
### enabled_by_default
|
||||
|
||||
Признак регистрации Engine по умолчанию.
|
||||
|
||||
Позволяет включать или отключать Engine без изменения Runtime.
|
||||
|
||||
---
|
||||
|
||||
## Что Build НЕ добавляет
|
||||
|
||||
Build сознательно не включает:
|
||||
|
||||
- Runtime;
|
||||
- Registry;
|
||||
- Coordinator;
|
||||
- Dependency Graph;
|
||||
- порядок запуска Engine;
|
||||
- приоритеты выполнения;
|
||||
- настройки Runtime;
|
||||
- timeout;
|
||||
- retry;
|
||||
- cache policy;
|
||||
- аналитическую логику.
|
||||
|
||||
Эти возможности относятся к следующим Build.
|
||||
|
||||
---
|
||||
|
||||
## Архитектурные последствия
|
||||
|
||||
После появления `EngineMetadata` становится возможным построение базового контракта Engine Layer.
|
||||
|
||||
Новая зависимость архитектуры выглядит следующим образом:
|
||||
|
||||
```text
|
||||
Common Layer
|
||||
│
|
||||
├── EngineContext
|
||||
├── EngineResult
|
||||
├── EngineDependencyResult
|
||||
└── EngineMetadata
|
||||
|
||||
▲
|
||||
|
||||
Engine Layer
|
||||
│
|
||||
├── EngineProtocol
|
||||
└── Engine Implementation
|
||||
|
||||
▲
|
||||
|
||||
Runtime Layer
|
||||
|
||||
▲
|
||||
|
||||
Coordinator Layer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Итоги Build
|
||||
|
||||
В результате Build 006.1:
|
||||
|
||||
- Common Layer получил новый общий контракт платформы;
|
||||
- устранён архитектурный пробел, обнаруженный при проектировании Engine Layer;
|
||||
- подготовлена основа для реализации `EngineProtocol`;
|
||||
- Runtime сможет использовать единый контракт Engine без знания конкретных реализаций.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance
|
||||
|
||||
Build считается завершённым после выполнения:
|
||||
|
||||
- ✅ Architecture Review
|
||||
- ✅ Architecture Decision (ADR)
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Documentation
|
||||
- ✅ Acceptance
|
||||
|
||||
---
|
||||
|
||||
## Следующий Build
|
||||
|
||||
```text
|
||||
Build 014
|
||||
|
||||
Engine Base Contracts
|
||||
|
||||
engine/protocol.py
|
||||
```
|
||||
263
docs/market_intelligence/builds/build-006-common-models.md
Normal file
263
docs/market_intelligence/builds/build-006-common-models.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Build №006 — Common Models
|
||||
|
||||
## Файл
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/models.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Назначение
|
||||
|
||||
Создание единого архитектурного контракта результатов работы всех аналитических движков платформы.
|
||||
|
||||
Данный файл определяет общий формат обмена данными между Engine и является центральной моделью подсистемы **Market Intelligence**.
|
||||
|
||||
Любой аналитический движок платформы должен использовать данный контракт независимо от своей предметной области.
|
||||
|
||||
---
|
||||
|
||||
# Реализовано
|
||||
|
||||
Созданы базовые модели:
|
||||
|
||||
- `EngineMetric`
|
||||
- `EngineDiagnostics`
|
||||
- `EngineEvaluationMeta`
|
||||
- `EngineDependencyResult`
|
||||
- `EngineContext`
|
||||
- `EngineResult`
|
||||
|
||||
Все модели реализованы как неизменяемые (`frozen=True`) dataclass с использованием `slots=True`.
|
||||
|
||||
---
|
||||
|
||||
# Назначение моделей
|
||||
|
||||
## EngineMetric
|
||||
|
||||
Описывает одну измеряемую характеристику, рассчитанную движком.
|
||||
|
||||
Примеры:
|
||||
|
||||
- сила движения;
|
||||
- процент волатильности;
|
||||
- ширина спреда;
|
||||
- длительность волны.
|
||||
|
||||
Метрика не является торговым решением.
|
||||
|
||||
---
|
||||
|
||||
## EngineDiagnostics
|
||||
|
||||
Хранит техническую диагностику выполнения движка.
|
||||
|
||||
Используется для:
|
||||
|
||||
- журналирования;
|
||||
- диагностики;
|
||||
- проверки качества работы;
|
||||
- анализа ошибок.
|
||||
|
||||
Диагностика полностью отделена от пользовательского интерфейса.
|
||||
|
||||
---
|
||||
|
||||
## EngineEvaluationMeta
|
||||
|
||||
Содержит служебную информацию о расчёте.
|
||||
|
||||
Например:
|
||||
|
||||
- название движка;
|
||||
- версия движка;
|
||||
- время выполнения;
|
||||
- длительность расчёта;
|
||||
- возраст входных данных.
|
||||
|
||||
---
|
||||
|
||||
## EngineDependencyResult
|
||||
|
||||
Представляет результат другого аналитического движка в компактной форме.
|
||||
|
||||
Используется для построения зависимостей между Engine без прямых импортов.
|
||||
|
||||
---
|
||||
|
||||
## EngineContext
|
||||
|
||||
Определяет единый входной контракт любого аналитического движка.
|
||||
|
||||
Контекст содержит только данные, необходимые для анализа рынка.
|
||||
|
||||
Контекст не содержит информации о:
|
||||
|
||||
- позициях;
|
||||
- балансе;
|
||||
- исполнении;
|
||||
- торговых приказах;
|
||||
- пользовательском интерфейсе.
|
||||
|
||||
---
|
||||
|
||||
## EngineResult
|
||||
|
||||
Является единым результатом работы любого Engine.
|
||||
|
||||
Содержит:
|
||||
|
||||
- состояние выполнения;
|
||||
- оценки;
|
||||
- уровень уверенности;
|
||||
- направление рынка;
|
||||
- режим рынка;
|
||||
- фазу рынка;
|
||||
- диагностическую информацию;
|
||||
- рассчитанные метрики;
|
||||
- служебные сведения.
|
||||
|
||||
EngineResult описывает только результат анализа рынка.
|
||||
|
||||
EngineResult не содержит торговых решений.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные решения
|
||||
|
||||
Во время реализации приняты следующие решения.
|
||||
|
||||
## Единый контракт
|
||||
|
||||
Все аналитические движки используют один и тот же тип результата.
|
||||
|
||||
Это позволяет Coordinator работать с любым Engine одинаковым образом.
|
||||
|
||||
---
|
||||
|
||||
## Разделение ответственности
|
||||
|
||||
Контракт разделён на независимые части:
|
||||
|
||||
- входные данные (`EngineContext`);
|
||||
- результат анализа (`EngineResult`);
|
||||
- диагностика (`EngineDiagnostics`);
|
||||
- служебные сведения (`EngineEvaluationMeta`);
|
||||
- зависимости (`EngineDependencyResult`);
|
||||
- отдельные измеряемые показатели (`EngineMetric`).
|
||||
|
||||
---
|
||||
|
||||
## Независимость от торговли
|
||||
|
||||
Контракт не содержит:
|
||||
|
||||
- открытия позиции;
|
||||
- закрытия позиции;
|
||||
- управления ордерами;
|
||||
- расчёта размера позиции;
|
||||
- информации о балансе;
|
||||
- информации о бирже.
|
||||
|
||||
Market Intelligence остаётся исключительно аналитическим уровнем платформы.
|
||||
|
||||
---
|
||||
|
||||
## Независимость движков
|
||||
|
||||
Ни один Engine не импортирует другой Engine напрямую.
|
||||
|
||||
Передача результатов между движками осуществляется через `EngineDependencyResult`.
|
||||
|
||||
Это исключает циклические зависимости и упрощает масштабирование платформы.
|
||||
|
||||
---
|
||||
|
||||
## Минимальный контекст
|
||||
|
||||
Engine получает только необходимые входные данные.
|
||||
|
||||
Контекст не превращается в универсальное хранилище состояния платформы.
|
||||
|
||||
Это позволяет каждому Engine работать независимо.
|
||||
|
||||
---
|
||||
|
||||
## Иммутабельность
|
||||
|
||||
Все модели объявлены как неизменяемые (`frozen=True`).
|
||||
|
||||
После формирования результата он больше не изменяется.
|
||||
|
||||
Это обеспечивает:
|
||||
|
||||
- предсказуемость;
|
||||
- безопасную передачу между компонентами;
|
||||
- стабильное журналирование;
|
||||
- корректное сравнение результатов.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
---
|
||||
|
||||
# Рекомендации
|
||||
|
||||
В дальнейшем рекомендуется дополнить архитектуру следующими сущностями после появления соответствующей практической необходимости:
|
||||
|
||||
- идентификатор результата (`result_id`);
|
||||
- источник рыночных данных (`data_source`);
|
||||
- время окончания актуальности результата (`expires_at`).
|
||||
|
||||
До появления реальной потребности данные поля не добавляются.
|
||||
|
||||
Это соответствует принципу **No Premature Abstractions**.
|
||||
|
||||
---
|
||||
|
||||
# Статус
|
||||
|
||||
```text
|
||||
ACCEPTED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Итоги Build
|
||||
|
||||
Build №006 завершил проектирование единого контракта аналитических движков.
|
||||
|
||||
Начиная с данного Build все новые Engine должны возвращать результат исключительно через `EngineResult`.
|
||||
|
||||
Создание собственных моделей результатов внутри отдельных Engine запрещается.
|
||||
|
||||
`common/models.py` становится единым источником истины для архитектуры результатов Market Intelligence.
|
||||
248
docs/market_intelligence/builds/build-007-common-validation.md
Normal file
248
docs/market_intelligence/builds/build-007-common-validation.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# Build 007 — Common Validation Layer
|
||||
|
||||
**Build ID:** 007
|
||||
|
||||
**Component:** `common/validation.py`
|
||||
|
||||
**Stage:** Stage 08.2 — Common Foundation
|
||||
|
||||
**Status:** **ACCEPTED**
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать единый слой архитектурной проверки (**Validation Layer**) для компонентов Market Intelligence.
|
||||
|
||||
Validation Layer отвечает за проверку соблюдения Runtime Contract и архитектурных ограничений Common Layer.
|
||||
|
||||
Данный слой не анализирует рынок и не принимает торговых решений.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
К моменту начала Build уже существовали:
|
||||
|
||||
- единые перечисления (`enums.py`);
|
||||
- общие типы (`types.py`);
|
||||
- архитектурные константы (`constants.py`);
|
||||
- единый словарь причин (`reasons.py`);
|
||||
- модели оценок (`scores.py`);
|
||||
- единые Runtime-модели (`models.py`).
|
||||
|
||||
Следующим необходимым компонентом стала централизованная проверка корректности этих моделей.
|
||||
|
||||
---
|
||||
|
||||
# Реализовано
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/validation.py
|
||||
```
|
||||
|
||||
Добавлены модели:
|
||||
|
||||
- ValidationIssue
|
||||
- ValidationResult
|
||||
|
||||
Добавлены проверки:
|
||||
|
||||
- validate_engine_context()
|
||||
- validate_engine_result()
|
||||
- validate_payload_has_no_trading_fields()
|
||||
|
||||
---
|
||||
|
||||
# Назначение Validation Layer
|
||||
|
||||
Validation Layer выполняет исключительно архитектурную проверку.
|
||||
|
||||
Он отвечает за:
|
||||
|
||||
- проверку обязательных полей Runtime Contract;
|
||||
- проверку ограничений Common Layer;
|
||||
- проверку запрещённых торговых полей;
|
||||
- формирование диагностического результата проверки.
|
||||
|
||||
Validation Layer не анализирует состояние рынка.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные решения
|
||||
|
||||
Во время Build были подтверждены следующие решения.
|
||||
|
||||
## Validation не принимает торговых решений
|
||||
|
||||
Validation Layer не выполняет:
|
||||
|
||||
- анализ рынка;
|
||||
- расчёт сигналов;
|
||||
- принятие торговых решений;
|
||||
- взаимодействие с биржей.
|
||||
|
||||
Он проверяет только соблюдение архитектурного контракта.
|
||||
|
||||
---
|
||||
|
||||
## Validation возвращает результат проверки
|
||||
|
||||
Проверка не использует исключения как основной механизм обработки.
|
||||
|
||||
Результатом проверки всегда является объект:
|
||||
|
||||
```text
|
||||
ValidationResult
|
||||
```
|
||||
|
||||
Это позволяет Coordinator и Runtime безопасно обрабатывать ошибки без остановки всей платформы.
|
||||
|
||||
---
|
||||
|
||||
## Validation использует единые модели Common
|
||||
|
||||
Validation Layer повторно использует:
|
||||
|
||||
- EngineContext
|
||||
- EngineResult
|
||||
- ReasonCode
|
||||
- CheckStatus
|
||||
- EngineStatus
|
||||
|
||||
Новые дублирующие модели не создаются.
|
||||
|
||||
---
|
||||
|
||||
## Validation защищает границы Market Intelligence
|
||||
|
||||
Добавлена централизованная проверка запрещённых торговых полей.
|
||||
|
||||
Используется архитектурная константа:
|
||||
|
||||
```text
|
||||
FORBIDDEN_TRADING_FIELDS
|
||||
```
|
||||
|
||||
Это предотвращает случайное проникновение торговой логики в аналитический слой.
|
||||
|
||||
---
|
||||
|
||||
## Validation не зависит от конкретных Engine
|
||||
|
||||
Validation Layer не содержит:
|
||||
|
||||
- знаний о Trend Engine;
|
||||
- знаний о Wave Engine;
|
||||
- знаний о Liquidity Engine;
|
||||
- знаний о Strategy;
|
||||
- знаний о Execution.
|
||||
|
||||
Он одинаково применим для любого аналитического движка платформы.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Статус:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence/common/validation.py
|
||||
```
|
||||
|
||||
Компиляция завершилась успешно.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Статус:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Проверено:
|
||||
|
||||
- отсутствие циклических зависимостей;
|
||||
- соблюдение Layer Isolation;
|
||||
- повторное использование моделей Common;
|
||||
- соблюдение Runtime Contract;
|
||||
- отсутствие нарушения зон ответственности.
|
||||
|
||||
Обязательные замечания отсутствуют.
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Статус:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- отсутствует торговая логика;
|
||||
- отсутствуют торговые решения;
|
||||
- отсутствует взаимодействие с биржей;
|
||||
- отсутствует работа с позициями;
|
||||
- Validation выполняет только проверку архитектурного контракта.
|
||||
|
||||
---
|
||||
|
||||
# Engineering Review
|
||||
|
||||
Подтверждено формирование законченного архитектурного фундамента Common Layer.
|
||||
|
||||
На текущем этапе сформирована следующая последовательность компонентов:
|
||||
|
||||
```text
|
||||
types
|
||||
↓
|
||||
enums
|
||||
↓
|
||||
constants
|
||||
↓
|
||||
reasons
|
||||
↓
|
||||
scores
|
||||
↓
|
||||
models
|
||||
↓
|
||||
validation
|
||||
```
|
||||
|
||||
Validation Layer завершает базовый уровень проверки архитектурного контракта.
|
||||
|
||||
---
|
||||
|
||||
# Рекомендации
|
||||
|
||||
В дальнейшем допускается развитие Validation Layer следующими возможностями:
|
||||
|
||||
- специализированные проверки отдельных Engine;
|
||||
- расширенная проверка Runtime Contract;
|
||||
- интеграция с будущим Review Layer;
|
||||
- автоматическая генерация диагностических отчётов.
|
||||
|
||||
Данные возможности не входят в текущий Build.
|
||||
|
||||
---
|
||||
|
||||
# Итог
|
||||
|
||||
Build №007 завершает создание базового Validation Layer подсистемы Market Intelligence.
|
||||
|
||||
Компонент полностью соответствует:
|
||||
|
||||
- Development Process v2.0;
|
||||
- Architecture Principles;
|
||||
- Runtime Contract.
|
||||
|
||||
Build получает статус:
|
||||
|
||||
**ACCEPTED**
|
||||
248
docs/market_intelligence/builds/build-008-common-checks.md
Normal file
248
docs/market_intelligence/builds/build-008-common-checks.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# Build 008 — Common Checks Layer
|
||||
|
||||
**Build ID:** 008
|
||||
|
||||
**Component:** `common/checks.py`
|
||||
|
||||
**Stage:** Stage 08.2 — Common Foundation
|
||||
|
||||
**Status:** **ACCEPTED**
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать единый слой инженерных проверок (**Checks Layer**) для аналитических движков подсистемы Market Intelligence.
|
||||
|
||||
Checks Layer предназначен для фиксации прохождения отдельных этапов обработки Engine и формирования единого инженерного отчёта о ходе выполнения анализа.
|
||||
|
||||
Данный слой не выполняет проверку корректности моделей и не анализирует состояние рынка.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
К началу Build уже существовали:
|
||||
|
||||
- единые перечисления (`enums.py`);
|
||||
- общие типы (`types.py`);
|
||||
- архитектурные константы (`constants.py`);
|
||||
- единый словарь причин (`reasons.py`);
|
||||
- модели оценок (`scores.py`);
|
||||
- Runtime-модели (`models.py`);
|
||||
- Validation Layer (`validation.py`).
|
||||
|
||||
Следующим этапом стало создание отдельного слоя инженерных проверок выполнения Engine.
|
||||
|
||||
---
|
||||
|
||||
# Реализовано
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/checks.py
|
||||
```
|
||||
|
||||
Добавлены модели:
|
||||
|
||||
- EngineCheck
|
||||
- EngineCheckReport
|
||||
|
||||
Добавлены функции:
|
||||
|
||||
- build_check()
|
||||
- build_check_report()
|
||||
|
||||
---
|
||||
|
||||
# Назначение Checks Layer
|
||||
|
||||
Checks Layer используется для фиксации результатов внутренних этапов обработки аналитического движка.
|
||||
|
||||
Он позволяет:
|
||||
|
||||
- описывать прохождение отдельных этапов Runtime;
|
||||
- объединять проверки в единый отчёт;
|
||||
- отделить инженерные проверки выполнения от проверки архитектурного контракта.
|
||||
|
||||
Checks Layer не анализирует рынок и не проверяет корректность входных данных.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные решения
|
||||
|
||||
Во время Build были подтверждены следующие решения.
|
||||
|
||||
## Checks Layer не заменяет Validation Layer
|
||||
|
||||
Validation Layer и Checks Layer имеют разные области ответственности.
|
||||
|
||||
Validation Layer отвечает на вопрос:
|
||||
|
||||
> **Корректен ли Runtime Contract?**
|
||||
|
||||
Checks Layer отвечает на вопрос:
|
||||
|
||||
> **Какие этапы обработки выполнил Engine?**
|
||||
|
||||
Таким образом оба слоя взаимно дополняют друг друга, не дублируя функциональность.
|
||||
|
||||
---
|
||||
|
||||
## Проверка выполняется по этапам обработки
|
||||
|
||||
Каждая проверка относится к одному значению `ProcessingStage`.
|
||||
|
||||
Например:
|
||||
|
||||
- INPUT
|
||||
- CALCULATION
|
||||
- VALIDATION
|
||||
- PAYLOAD
|
||||
- SNAPSHOT
|
||||
- RESULT
|
||||
- EVENT
|
||||
|
||||
Это позволяет анализировать работу Engine поэтапно.
|
||||
|
||||
---
|
||||
|
||||
## Отчёт агрегирует независимые проверки
|
||||
|
||||
Engine может сформировать несколько отдельных проверок.
|
||||
|
||||
Они объединяются в объект:
|
||||
|
||||
```text
|
||||
EngineCheckReport
|
||||
```
|
||||
|
||||
Отчёт определяет общий инженерный статус выполнения без повторной проверки отдельных этапов.
|
||||
|
||||
---
|
||||
|
||||
## Checks Layer не содержит предметной логики
|
||||
|
||||
Checks Layer не знает:
|
||||
|
||||
- что такое тренд;
|
||||
- что такое волна;
|
||||
- что такое ликвидность;
|
||||
- что такое фаза рынка.
|
||||
|
||||
Он работает исключительно с инженерными этапами выполнения Runtime.
|
||||
|
||||
---
|
||||
|
||||
## Checks Layer не зависит от конкретных Engine
|
||||
|
||||
Файл не содержит ссылок на:
|
||||
|
||||
- Trend Engine;
|
||||
- Wave Engine;
|
||||
- Liquidity Engine;
|
||||
- Coordinator;
|
||||
- Strategy;
|
||||
- Execution.
|
||||
|
||||
Любой аналитический движок может использовать данный слой без изменений.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Статус:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence/common/checks.py
|
||||
```
|
||||
|
||||
Компиляция завершилась успешно.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Статус:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- отсутствие циклических зависимостей;
|
||||
- корректное разделение Validation Layer и Checks Layer;
|
||||
- соблюдение Layer Isolation;
|
||||
- повторное использование моделей Common;
|
||||
- масштабируемость архитектуры.
|
||||
|
||||
Обязательные замечания отсутствуют.
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Статус:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- отсутствует торговая логика;
|
||||
- отсутствует анализ рынка;
|
||||
- отсутствует взаимодействие с биржей;
|
||||
- отсутствует работа с позициями;
|
||||
- Checks Layer выполняет исключительно инженерную диагностику выполнения Engine.
|
||||
|
||||
---
|
||||
|
||||
# Engineering Review
|
||||
|
||||
После завершения Build №008 фундамент Common Layer получил два независимых уровня контроля качества:
|
||||
|
||||
```text
|
||||
Runtime Contract
|
||||
↓
|
||||
Validation Layer
|
||||
↓
|
||||
Checks Layer
|
||||
```
|
||||
|
||||
Validation Layer отвечает за корректность архитектурного контракта.
|
||||
|
||||
Checks Layer отвечает за фиксацию прохождения этапов обработки.
|
||||
|
||||
Такое разделение обеспечивает независимое развитие обоих компонентов и предотвращает смешивание архитектурных обязанностей.
|
||||
|
||||
---
|
||||
|
||||
# Рекомендации
|
||||
|
||||
В дальнейшем допускается развитие Checks Layer следующими возможностями:
|
||||
|
||||
- группировка проверок по Engine;
|
||||
- сохранение времени выполнения отдельных этапов;
|
||||
- интеграция с Runtime Review;
|
||||
- автоматическое формирование инженерных отчётов.
|
||||
|
||||
Данные возможности не входят в текущий Build.
|
||||
|
||||
---
|
||||
|
||||
# Итог
|
||||
|
||||
Build №008 завершает создание базового Checks Layer подсистемы Market Intelligence.
|
||||
|
||||
Компонент полностью соответствует:
|
||||
|
||||
- Development Process v2.0;
|
||||
- Architecture Principles;
|
||||
- Runtime Contract.
|
||||
|
||||
Build получает статус:
|
||||
|
||||
**ACCEPTED**
|
||||
187
docs/market_intelligence/builds/build-009-common-payloads.md
Normal file
187
docs/market_intelligence/builds/build-009-common-payloads.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Build 009 — Common Payloads Layer
|
||||
|
||||
**Build ID:** 009
|
||||
|
||||
**Компонент:** `common/payloads.py`
|
||||
|
||||
**Статус:** **Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Реализовать единый механизм преобразования результатов работы Market Intelligence в стандартный диагностический Payload.
|
||||
|
||||
Payload является официальным способом передачи результатов аналитических движков между слоями платформы, а также используется для:
|
||||
|
||||
- журналирования;
|
||||
- диагностики;
|
||||
- Snapshot;
|
||||
- Runtime;
|
||||
- Event;
|
||||
- последующей сериализации.
|
||||
|
||||
Данный Build не реализует торговую логику и не принимает торговых решений.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные компоненты
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
market_intelligence/common/payloads.py
|
||||
```
|
||||
|
||||
Реализованы функции:
|
||||
|
||||
- `value_to_payload()`
|
||||
- `mapping_to_payload()`
|
||||
- `engine_score_to_payload()`
|
||||
- `engine_confidence_to_payload()`
|
||||
- `engine_metric_to_payload()`
|
||||
- `engine_diagnostics_to_payload()`
|
||||
- `engine_dependency_to_payload()`
|
||||
- `engine_result_to_payload()`
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная задача
|
||||
|
||||
До появления данного Build каждый Engine мог потенциально формировать собственный формат диагностических данных.
|
||||
|
||||
После реализации общего Payload Layer все Engine используют единый механизм сериализации.
|
||||
|
||||
Таким образом достигаются:
|
||||
|
||||
- единый формат Runtime;
|
||||
- единый формат Snapshot;
|
||||
- единый формат Diagnostics;
|
||||
- единый формат Event;
|
||||
- единый формат журналирования.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные решения
|
||||
|
||||
В ходе реализации приняты следующие решения.
|
||||
|
||||
## Единая сериализация
|
||||
|
||||
Все значения проходят единый процесс преобразования.
|
||||
|
||||
Поддерживаются:
|
||||
|
||||
- dataclass;
|
||||
- Enum;
|
||||
- Mapping;
|
||||
- tuple;
|
||||
- list;
|
||||
- простые типы Python.
|
||||
|
||||
Payload всегда содержит только сериализуемые структуры.
|
||||
|
||||
---
|
||||
|
||||
## Payload не принимает решений
|
||||
|
||||
Payload является исключительно транспортным представлением результата.
|
||||
|
||||
Он не содержит:
|
||||
|
||||
- торговых команд;
|
||||
- расчётов позиции;
|
||||
- рекомендаций на открытие сделки;
|
||||
- изменений Runtime.
|
||||
|
||||
---
|
||||
|
||||
## Автоматическая проверка архитектурных ограничений
|
||||
|
||||
Перед возвратом итогового Payload выполняется:
|
||||
|
||||
```text
|
||||
validate_payload_has_no_trading_fields()
|
||||
```
|
||||
|
||||
Если обнаружены запрещённые торговые поля, информация сохраняется в диагностическом разделе Payload.
|
||||
|
||||
Нарушение не скрывается и становится доступным для анализа во время Runtime и Engineering Review.
|
||||
|
||||
---
|
||||
|
||||
## Независимость от Engine
|
||||
|
||||
Payload Layer не знает:
|
||||
|
||||
- конкретные Engine;
|
||||
- Strategy;
|
||||
- AutoTrade;
|
||||
- Exchange;
|
||||
- Telegram UI.
|
||||
|
||||
Компонент работает исключительно с общими моделями слоя Common.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Выполнена проверка:
|
||||
|
||||
```bash
|
||||
python -m compileall \
|
||||
src/trading/market_intelligence/common/payloads.py
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Compile successful
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Результат: **PASSED**
|
||||
|
||||
Проверено:
|
||||
|
||||
- соблюдение ответственности слоя;
|
||||
- отсутствие торговой логики;
|
||||
- независимость от Runtime;
|
||||
- независимость от UI;
|
||||
- независимость от AutoTrade;
|
||||
- единый механизм сериализации.
|
||||
|
||||
Архитектурных замечаний не выявлено.
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Результат: **PASSED**
|
||||
|
||||
Проверено:
|
||||
|
||||
- отсутствие торговых решений;
|
||||
- объяснимость структуры Payload;
|
||||
- пригодность для журналирования;
|
||||
- пригодность для диагностики;
|
||||
- соответствие Runtime Contract.
|
||||
|
||||
Замечаний не выявлено.
|
||||
|
||||
---
|
||||
|
||||
# Итог Build
|
||||
|
||||
Build успешно завершил создание общего слоя сериализации результатов Market Intelligence.
|
||||
|
||||
Payload становится официальным форматом передачи аналитических результатов между компонентами платформы.
|
||||
|
||||
---
|
||||
|
||||
# Build Status
|
||||
|
||||
**Accepted**
|
||||
193
docs/market_intelligence/builds/build-010-common-snapshots.md
Normal file
193
docs/market_intelligence/builds/build-010-common-snapshots.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Build 010 — Common Snapshots Layer
|
||||
|
||||
**Build ID:** 010
|
||||
|
||||
**Компонент:** `common/snapshots.py`
|
||||
|
||||
**Статус:** **Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Реализовать единый слой Snapshot для подсистемы Market Intelligence.
|
||||
|
||||
Snapshot представляет собой неизменяемый снимок результата работы аналитического движка в определённый момент времени.
|
||||
|
||||
Данный Build создаёт единый формат хранения результатов анализа без привязки к конкретному Engine.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные компоненты
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
market_intelligence/common/snapshots.py
|
||||
```
|
||||
|
||||
Реализованы:
|
||||
|
||||
- `EngineSnapshot`
|
||||
- `build_engine_snapshot()`
|
||||
- `engine_snapshot_to_payload()`
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная задача
|
||||
|
||||
До появления данного Build существовал единый Runtime Result (`EngineResult`), но отсутствовал стандартный механизм фиксации его состояния.
|
||||
|
||||
После реализации Snapshot Layer каждый результат анализа может быть сохранён в неизменяемом виде.
|
||||
|
||||
Snapshot становится стандартным объектом для:
|
||||
|
||||
- журналирования;
|
||||
- диагностики;
|
||||
- формирования Event;
|
||||
- хранения истории анализа;
|
||||
- последующего сравнения состояний рынка.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные решения
|
||||
|
||||
В ходе реализации приняты следующие решения.
|
||||
|
||||
## Snapshot является неизменяемым
|
||||
|
||||
Используется
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True, slots=True)
|
||||
```
|
||||
|
||||
После создания Snapshot его содержимое больше не изменяется.
|
||||
|
||||
Это гарантирует воспроизводимость результатов анализа.
|
||||
|
||||
---
|
||||
|
||||
## Snapshot строится только из EngineResult
|
||||
|
||||
Snapshot никогда не вычисляет данные самостоятельно.
|
||||
|
||||
Он всегда строится через:
|
||||
|
||||
```text
|
||||
EngineResult
|
||||
↓
|
||||
engine_result_to_payload()
|
||||
↓
|
||||
EngineSnapshot
|
||||
```
|
||||
|
||||
Таким образом существует единая точка формирования результата анализа.
|
||||
|
||||
---
|
||||
|
||||
## Snapshot не содержит торговой логики
|
||||
|
||||
Snapshot не имеет права хранить:
|
||||
|
||||
- команды открытия позиции;
|
||||
- команды закрытия позиции;
|
||||
- расчёт размера позиции;
|
||||
- состояние AutoTrade;
|
||||
- состояние Exchange;
|
||||
- Runtime Position.
|
||||
|
||||
Snapshot фиксирует исключительно аналитический результат.
|
||||
|
||||
---
|
||||
|
||||
## Payload является частью Snapshot
|
||||
|
||||
Snapshot не копирует отдельные поля EngineResult.
|
||||
|
||||
Вместо этого используется единый Payload Layer.
|
||||
|
||||
Это исключает дублирование логики сериализации.
|
||||
|
||||
---
|
||||
|
||||
## Независимость от Runtime
|
||||
|
||||
Snapshot Layer не зависит от:
|
||||
|
||||
- AutoTrade;
|
||||
- Exchange;
|
||||
- Telegram;
|
||||
- Journal;
|
||||
- конкретных Engine.
|
||||
|
||||
Компонент использует исключительно сущности Common Layer.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Выполнена проверка:
|
||||
|
||||
```bash
|
||||
python -m compileall \
|
||||
src/trading/market_intelligence/common/snapshots.py
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Compile successful
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Результат:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Проверено:
|
||||
|
||||
- соблюдение Single Responsibility;
|
||||
- неизменяемость Snapshot;
|
||||
- отсутствие торговой логики;
|
||||
- использование единого Payload Layer;
|
||||
- отсутствие нарушения архитектурных границ.
|
||||
|
||||
Замечаний не выявлено.
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Результат:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Проверено:
|
||||
|
||||
- Snapshot отражает исключительно состояние анализа;
|
||||
- отсутствуют торговые решения;
|
||||
- структура пригодна для журналирования;
|
||||
- структура пригодна для Runtime;
|
||||
- структура соответствует Runtime Contract.
|
||||
|
||||
Замечаний не выявлено.
|
||||
|
||||
---
|
||||
|
||||
# Итог Build
|
||||
|
||||
Build завершил создание общего Snapshot Layer.
|
||||
|
||||
Все аналитические движки платформы получили единый механизм фиксации собственного состояния.
|
||||
|
||||
Snapshot становится стандартным архитектурным объектом Market Intelligence.
|
||||
|
||||
---
|
||||
|
||||
# Build Status
|
||||
|
||||
**Accepted**
|
||||
205
docs/market_intelligence/builds/build-011-common-events.md
Normal file
205
docs/market_intelligence/builds/build-011-common-events.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# Build 011 — Common Events Layer
|
||||
|
||||
**Build ID:** 011
|
||||
|
||||
**Компонент:** `common/events.py`
|
||||
|
||||
**Статус:** **Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Реализовать единый слой представления событий подсистемы Market Intelligence.
|
||||
|
||||
Events Layer определяет стандартный формат аналитических событий, которые в дальнейшем смогут использоваться Runtime, журналом, системой диагностики и EventBus.
|
||||
|
||||
Данный Build не реализует публикацию событий и не зависит от конкретного механизма доставки.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные компоненты
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
market_intelligence/common/events.py
|
||||
```
|
||||
|
||||
Реализованы:
|
||||
|
||||
- `MarketIntelligenceEvent`
|
||||
- `build_engine_result_event()`
|
||||
- `build_engine_snapshot_event()`
|
||||
- `build_result_snapshot_event()`
|
||||
- `market_intelligence_event_to_payload()`
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная задача
|
||||
|
||||
До появления данного Build существовали:
|
||||
|
||||
```text
|
||||
EngineResult
|
||||
|
||||
↓
|
||||
|
||||
Payload
|
||||
|
||||
↓
|
||||
|
||||
Snapshot
|
||||
```
|
||||
|
||||
Однако отсутствовало единое архитектурное представление аналитического события.
|
||||
|
||||
После реализации Events Layer любое завершение работы Engine может быть представлено в виде стандартного события Market Intelligence.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные решения
|
||||
|
||||
В ходе реализации приняты следующие решения.
|
||||
|
||||
## Event является архитектурной моделью
|
||||
|
||||
MarketIntelligenceEvent описывает событие анализа рынка.
|
||||
|
||||
Сам объект события не занимается публикацией.
|
||||
|
||||
Таким образом разделяются:
|
||||
|
||||
```text
|
||||
Event Model
|
||||
|
||||
↓
|
||||
|
||||
Event Transport
|
||||
```
|
||||
|
||||
Это позволяет использовать любые механизмы доставки без изменения модели события.
|
||||
|
||||
---
|
||||
|
||||
## Event строится из существующих моделей
|
||||
|
||||
События создаются исключительно через существующие архитектурные объекты.
|
||||
|
||||
Поддерживаются цепочки:
|
||||
|
||||
```text
|
||||
EngineResult
|
||||
↓
|
||||
Event
|
||||
```
|
||||
|
||||
и
|
||||
|
||||
```text
|
||||
EngineResult
|
||||
↓
|
||||
Snapshot
|
||||
↓
|
||||
Event
|
||||
```
|
||||
|
||||
Никаких дополнительных расчётов внутри Event Layer не выполняется.
|
||||
|
||||
---
|
||||
|
||||
## Payload не дублируется
|
||||
|
||||
Events Layer не сериализует данные самостоятельно.
|
||||
|
||||
Используются уже существующие компоненты:
|
||||
|
||||
- Payload Layer;
|
||||
- Snapshot Layer.
|
||||
|
||||
Это сохраняет принцип единственного источника истины.
|
||||
|
||||
---
|
||||
|
||||
## Независимость от EventBus
|
||||
|
||||
Common Layer определяет только структуру события.
|
||||
|
||||
Он ничего не знает о:
|
||||
|
||||
- EventBus;
|
||||
- Runtime;
|
||||
- Journal;
|
||||
- AutoTrade;
|
||||
- Telegram;
|
||||
- Exchange.
|
||||
|
||||
Таким образом Event Layer остаётся полностью независимым.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Выполнена проверка:
|
||||
|
||||
```bash
|
||||
python -m compileall \
|
||||
src/trading/market_intelligence/common/events.py
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Compile successful
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Результат:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Проверено:
|
||||
|
||||
- соблюдение Single Responsibility;
|
||||
- отсутствие публикации событий;
|
||||
- отсутствие торговой логики;
|
||||
- использование существующих моделей;
|
||||
- независимость от Runtime;
|
||||
- отсутствие циклических зависимостей.
|
||||
|
||||
Архитектурных замечаний не выявлено.
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Результат:
|
||||
|
||||
**PASSED**
|
||||
|
||||
Проверено:
|
||||
|
||||
- событие отражает только факт завершения анализа;
|
||||
- отсутствуют торговые действия;
|
||||
- отсутствуют Runtime-решения;
|
||||
- структура пригодна для журналирования;
|
||||
- структура соответствует Runtime Contract.
|
||||
|
||||
Замечаний не выявлено.
|
||||
|
||||
---
|
||||
|
||||
# Итог Build
|
||||
|
||||
Build завершил создание общего Events Layer.
|
||||
|
||||
Market Intelligence получил единый формат аналитических событий, который может использоваться любыми внешними компонентами платформы.
|
||||
|
||||
---
|
||||
|
||||
# Build Status
|
||||
|
||||
**Accepted**
|
||||
226
docs/market_intelligence/builds/build-012-common-timeframes.md
Normal file
226
docs/market_intelligence/builds/build-012-common-timeframes.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Build 012 — Common Timeframes
|
||||
|
||||
**Build ID:** 012
|
||||
|
||||
**Component:** `common/timeframes.py`
|
||||
|
||||
**Status:** ✅ Accepted
|
||||
|
||||
**Development Process:** v2.0
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать единый архитектурный слой описания таймфреймов, который будет использоваться всеми будущими Engine подсистемы Market Intelligence.
|
||||
|
||||
До данного Build информация о таймфреймах существовала только внутри отдельных модулей старой системы анализа рынка.
|
||||
|
||||
Это затрудняло повторное использование логики и не позволяло создать единый контракт для многоуровневого анализа.
|
||||
|
||||
Настоящий Build переносит описание таймфреймов в слой Common и делает его независимым от реализации конкретных аналитических движков.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные компоненты
|
||||
|
||||
Добавлен новый файл:
|
||||
|
||||
```text
|
||||
common/timeframes.py
|
||||
```
|
||||
|
||||
В рамках Build реализованы:
|
||||
|
||||
- модель `Timeframe`;
|
||||
- единый реестр поддерживаемых таймфреймов;
|
||||
- архитектурные роли таймфреймов;
|
||||
- карта переходов к старшему таймфрейму;
|
||||
- функции поиска и проверки таймфреймов;
|
||||
- преобразование модели в диагностический payload.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные решения
|
||||
|
||||
## Единая модель Timeframe
|
||||
|
||||
Каждый временной интервал представлен неизменяемым объектом `Timeframe`.
|
||||
|
||||
Модель содержит только архитектурное описание интервала:
|
||||
|
||||
- имя;
|
||||
- длительность;
|
||||
- роль;
|
||||
- описание.
|
||||
|
||||
Модель не содержит торговой логики.
|
||||
|
||||
---
|
||||
|
||||
## Централизованный реестр
|
||||
|
||||
Все поддерживаемые интервалы собраны в одном месте.
|
||||
|
||||
На текущем этапе поддерживаются:
|
||||
|
||||
```text
|
||||
1m
|
||||
5m
|
||||
15m
|
||||
1h
|
||||
4h
|
||||
1d
|
||||
1w
|
||||
```
|
||||
|
||||
Это создаёт единый источник истины для всей платформы.
|
||||
|
||||
---
|
||||
|
||||
## Архитектурные роли
|
||||
|
||||
Каждому таймфрейму назначается роль:
|
||||
|
||||
- LOWER;
|
||||
- PRIMARY;
|
||||
- CONFIRMATION;
|
||||
- HIGHER.
|
||||
|
||||
Роль используется будущими движками при построении многоуровневого анализа.
|
||||
|
||||
---
|
||||
|
||||
## Карта старших таймфреймов
|
||||
|
||||
Добавлена централизованная карта переходов:
|
||||
|
||||
```text
|
||||
1m → 5m
|
||||
5m → 1h
|
||||
15m → 1h
|
||||
1h → 4h
|
||||
4h → 1d
|
||||
1d → 1w
|
||||
```
|
||||
|
||||
На текущем этапе она полностью совместима с существующей реализацией `MarketAnalysisService`, где рабочий интервал `5m` использует старший `1h`.
|
||||
|
||||
---
|
||||
|
||||
## Независимость от существующего анализа рынка
|
||||
|
||||
Файл не использует:
|
||||
|
||||
- `MarketAnalysisService`;
|
||||
- `ExchangeService`;
|
||||
- старые модели;
|
||||
- AutoTrade.
|
||||
|
||||
Таким образом создаётся самостоятельный фундамент для новой подсистемы Market Intelligence без изменения существующего поведения бота.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные функции
|
||||
|
||||
Добавлены следующие функции:
|
||||
|
||||
- `get_timeframe()`
|
||||
- `require_timeframe()`
|
||||
- `is_supported_timeframe()`
|
||||
- `get_higher_timeframe()`
|
||||
- `get_timeframes_by_role()`
|
||||
- `timeframe_to_payload()`
|
||||
|
||||
Все функции являются детерминированными и не имеют побочных эффектов.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Статус:
|
||||
|
||||
```text
|
||||
PASSED
|
||||
```
|
||||
|
||||
Проверка:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence/common/timeframes.py
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Compiling 'src/trading/market_intelligence/common/timeframes.py'...
|
||||
```
|
||||
|
||||
Ошибок компиляции не обнаружено.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
Проверено:
|
||||
|
||||
- отсутствие циклических зависимостей;
|
||||
- отсутствие торговой логики;
|
||||
- независимость от Runtime;
|
||||
- независимость от Exchange;
|
||||
- независимость от AutoTrade;
|
||||
- соответствие архитектуре Common Layer.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
Проверено:
|
||||
|
||||
- корректность терминологии;
|
||||
- соответствие философии Market Intelligence;
|
||||
- отсутствие принятия торговых решений;
|
||||
- корректное разделение понятий "таймфрейм" и "анализ рынка".
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
---
|
||||
|
||||
# Engineering Review
|
||||
|
||||
Положительные результаты Build:
|
||||
|
||||
- создан единый источник истины для таймфреймов;
|
||||
- устранено дублирование будущих определений;
|
||||
- подготовлен фундамент для Multi-Timeframe Engine;
|
||||
- сохранена совместимость с существующей системой анализа рынка.
|
||||
|
||||
Build не оказывает влияния на работу действующего торгового бота.
|
||||
|
||||
---
|
||||
|
||||
# Документация
|
||||
|
||||
В рамках Build подготовлены:
|
||||
|
||||
- `common/timeframes.py`;
|
||||
- `build-012-common-timeframes.md`;
|
||||
- обновление `build_history.md`.
|
||||
|
||||
---
|
||||
|
||||
# Итог
|
||||
|
||||
Build успешно завершил создание единого слоя описания таймфреймов.
|
||||
|
||||
Следующие аналитические движки смогут использовать единый контракт работы с временными интервалами без зависимости от устаревшей реализации `market_analysis`.
|
||||
|
||||
---
|
||||
|
||||
**Итоговый статус Build:** ✅ **Accepted**
|
||||
@@ -0,0 +1,215 @@
|
||||
# Build 013 — Runtime Architecture
|
||||
|
||||
**Build ID:** 013
|
||||
|
||||
**Компонент:** Runtime Layer
|
||||
|
||||
**Статус:** ✅ Accepted
|
||||
|
||||
**Тип Build:** Architecture Build
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Спроектировать архитектуру слоя Runtime подсистемы **Market Intelligence**.
|
||||
|
||||
До начала реализации первого аналитического Engine необходимо определить единый механизм выполнения движков.
|
||||
|
||||
В рамках Build проектируется инфраструктурный слой Runtime, который станет основой для всех последующих Engine.
|
||||
|
||||
Исходный код в рамках данного Build не создаётся.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Runtime
|
||||
|
||||
После завершения Common Layer платформа получила единый набор:
|
||||
|
||||
- моделей;
|
||||
- типов;
|
||||
- диагностических структур;
|
||||
- проверки корректности;
|
||||
- snapshot;
|
||||
- payload;
|
||||
- событий.
|
||||
|
||||
Следующим логическим уровнем архитектуры является Runtime.
|
||||
|
||||
Без Runtime каждый Engine был бы вынужден самостоятельно решать вопросы:
|
||||
|
||||
- запуска;
|
||||
- обработки ошибок;
|
||||
- проверки результата;
|
||||
- формирования fallback;
|
||||
- взаимодействия с Coordinator.
|
||||
|
||||
Это неизбежно привело бы к дублированию логики.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурное решение
|
||||
|
||||
Введён новый архитектурный уровень:
|
||||
|
||||
```text
|
||||
Common Layer
|
||||
↓
|
||||
Runtime Layer
|
||||
↓
|
||||
Engine Layer
|
||||
↓
|
||||
Coordinator Layer
|
||||
```
|
||||
|
||||
Runtime становится единственной инфраструктурой выполнения Engine.
|
||||
|
||||
---
|
||||
|
||||
# Спроектированная структура Runtime
|
||||
|
||||
Определена следующая структура каталога.
|
||||
|
||||
```text
|
||||
runtime/
|
||||
|
||||
├── __init__.py
|
||||
├── protocol.py
|
||||
├── base.py
|
||||
├── runner.py
|
||||
├── registry.py
|
||||
├── dependencies.py
|
||||
└── validation.py
|
||||
```
|
||||
|
||||
Каждый файл получил единственную область ответственности.
|
||||
|
||||
---
|
||||
|
||||
# Основные обязанности Runtime
|
||||
|
||||
Runtime отвечает исключительно за инфраструктуру выполнения аналитических Engine.
|
||||
|
||||
В область ответственности Runtime входят:
|
||||
|
||||
- единый контракт Engine;
|
||||
- единый жизненный цикл выполнения;
|
||||
- безопасный запуск Engine;
|
||||
- обработка исключений;
|
||||
- Runtime Validation;
|
||||
- регистрация Engine;
|
||||
- управление зависимостями;
|
||||
- формирование безопасного EngineResult.
|
||||
|
||||
Runtime не содержит аналитической логики.
|
||||
|
||||
---
|
||||
|
||||
# Основные архитектурные принципы
|
||||
|
||||
Во время проектирования подтверждены следующие правила.
|
||||
|
||||
- Runtime не анализирует рынок.
|
||||
- Runtime не принимает торговых решений.
|
||||
- Runtime не взаимодействует с биржей.
|
||||
- Runtime не знает об AutoTrade.
|
||||
- Runtime использует Common как единственный источник базовых моделей.
|
||||
- Engine взаимодействуют только через Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Документация
|
||||
|
||||
В рамках Build создан новый раздел документации.
|
||||
|
||||
```text
|
||||
docs/market_intelligence/runtime/
|
||||
```
|
||||
|
||||
Созданы документы:
|
||||
|
||||
```text
|
||||
runtime/README.md
|
||||
|
||||
runtime/architecture.md
|
||||
```
|
||||
|
||||
Теперь Runtime имеет собственную архитектурную документацию, независимую от Build History.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные изменения
|
||||
|
||||
Исходный код не создавался.
|
||||
|
||||
Выполнено архитектурное проектирование Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Не требуется.
|
||||
|
||||
Build содержит исключительно архитектурную документацию.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
**Статус:** PASSED
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- правильное положение Runtime в архитектуре;
|
||||
- отсутствие нарушения слоёв;
|
||||
- независимость Runtime от Engine;
|
||||
- независимость Runtime от AutoTrade;
|
||||
- отсутствие циклических зависимостей.
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
**Статус:** PASSED
|
||||
|
||||
Runtime остаётся инфраструктурным уровнем.
|
||||
|
||||
Торговая логика отсутствует.
|
||||
|
||||
Аналитическая логика отсутствует.
|
||||
|
||||
---
|
||||
|
||||
# Documentation Review
|
||||
|
||||
Созданы новые документы Runtime.
|
||||
|
||||
Build History подлежит обновлению.
|
||||
|
||||
README Runtime создан.
|
||||
|
||||
Архитектурная спецификация Runtime создана.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 014
|
||||
|
||||
runtime/protocol.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Итог
|
||||
|
||||
Build успешно завершил проектирование Runtime Layer.
|
||||
|
||||
Данный Build создаёт архитектурный фундамент для всех будущих аналитических Engine.
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
ACCEPTED
|
||||
```
|
||||
243
docs/market_intelligence/builds/build-014-1-engine-protocol.md
Normal file
243
docs/market_intelligence/builds/build-014-1-engine-protocol.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# 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
|
||||
```
|
||||
272
docs/market_intelligence/builds/build-014-2-engine-base.md
Normal file
272
docs/market_intelligence/builds/build-014-2-engine-base.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 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
|
||||
```
|
||||
235
docs/market_intelligence/builds/build-014-3-engine-exceptions.md
Normal file
235
docs/market_intelligence/builds/build-014-3-engine-exceptions.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# Build 014.3 — Engine Exceptions
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 014.3 |
|
||||
| Название | Engine Exceptions |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Engine |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После реализации `EngineProtocol` и `BaseEngine` возникла необходимость стандартизировать обработку внутренних ошибок Engine Layer.
|
||||
|
||||
Использование стандартных исключений Python (`ValueError`, `NotImplementedError` и других) не отражало архитектурную модель платформы и затрудняло разделение инфраструктурных ошибок от штатных аналитических состояний.
|
||||
|
||||
Настоящий Build вводит единый набор внутренних исключений Engine Layer и интегрирует их в `BaseEngine`.
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать единый механизм внутренних исключений Engine Layer.
|
||||
|
||||
Исключения предназначены исключительно для обнаружения нарушений инфраструктурного жизненного цикла Engine и не являются частью внешнего Runtime Contract.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
В Engine Layer вводится единая иерархия исключений.
|
||||
|
||||
```text
|
||||
EngineError
|
||||
│
|
||||
├── EngineConfigurationError
|
||||
├── EngineContractError
|
||||
├── EngineContextError
|
||||
└── EngineExecutionError
|
||||
```
|
||||
|
||||
Все исключения используются исключительно внутри Engine Layer.
|
||||
|
||||
За пределы Engine Layer передаются только объекты `EngineResult`.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила соответствие архитектурным принципам проекта.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Runtime не зависит от исключений Engine;
|
||||
- Coordinator работает только с `EngineResult`;
|
||||
- штатные аналитические состояния не оформляются через исключения;
|
||||
- исключения используются исключительно для ошибок инфраструктуры Engine Layer;
|
||||
- архитектурные зависимости остаются однонаправленными.
|
||||
|
||||
Архитектурное решение признано корректным.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision (ADR)
|
||||
|
||||
## Решение
|
||||
|
||||
Ввести единый набор внутренних исключений Engine Layer.
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
## Обоснование
|
||||
|
||||
Исключения необходимы для описания нарушений жизненного цикла Engine:
|
||||
|
||||
- ошибок конфигурации;
|
||||
- ошибок входного контекста;
|
||||
- нарушений архитектурного контракта;
|
||||
- внутренних ошибок реализации.
|
||||
|
||||
При этом исключения не являются способом передачи аналитического результата.
|
||||
|
||||
Внешним контрактом платформы остаётся исключительно `EngineResult`.
|
||||
|
||||
## Последствия
|
||||
|
||||
После принятия решения:
|
||||
|
||||
- BaseEngine использует специализированные исключения Engine Layer;
|
||||
- Runtime не зависит от механизма исключений;
|
||||
- Coordinator продолжает работать только через официальный Runtime Contract;
|
||||
- архитектура сохраняет слабую связанность компонентов.
|
||||
|
||||
---
|
||||
|
||||
# Build Design
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/engine/exceptions.py
|
||||
```
|
||||
|
||||
Также обновлён файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/engine/base.py
|
||||
```
|
||||
|
||||
BaseEngine переведён на использование новых исключений.
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Реализованы классы:
|
||||
|
||||
```text
|
||||
EngineError
|
||||
├── EngineConfigurationError
|
||||
├── EngineContractError
|
||||
├── EngineContextError
|
||||
└── EngineExecutionError
|
||||
```
|
||||
|
||||
В `BaseEngine` выполнены следующие изменения:
|
||||
|
||||
- отсутствие `ENGINE_METADATA` приводит к `EngineConfigurationError`;
|
||||
- отсутствие обязательных полей `EngineContext` приводит к `EngineContextError`;
|
||||
- возврат объекта, отличного от `EngineResult`, приводит к `EngineContractError`.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- успешно скомпилирован `engine/exceptions.py`;
|
||||
- успешно скомпилирован обновлённый `engine/base.py`;
|
||||
- отсутствуют синтаксические ошибки;
|
||||
- отсутствуют циклические зависимости.
|
||||
|
||||
После интеграции исключений выполнена повторная проверка компиляции.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Проверено соответствие предметной области.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- исключения используются только внутри Engine Layer;
|
||||
- внешний контракт остаётся `EngineResult`;
|
||||
- штатные аналитические состояния не оформляются через исключения;
|
||||
- ошибки контекста отделены от ошибок конфигурации и нарушений контракта;
|
||||
- Runtime и Coordinator полностью изолированы от внутреннего механизма исключений.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
В рамках Build обновлены:
|
||||
|
||||
- Build History;
|
||||
- Engine Layer Architecture;
|
||||
- документация Engine Base.
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build считается завершённым.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture
|
||||
- ✅ Architecture Review
|
||||
- ✅ Architecture Decision (ADR)
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Documentation
|
||||
- ✅ Acceptance
|
||||
|
||||
Статус Build:
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Итоги Build
|
||||
|
||||
В результате Build 014.3:
|
||||
|
||||
- создан единый механизм внутренних исключений Engine Layer;
|
||||
- `BaseEngine` переведён на использование специализированных исключений;
|
||||
- внешний Runtime Contract не изменился;
|
||||
- архитектура стала более согласованной и подготовлена к появлению первых аналитических Engine.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 015
|
||||
|
||||
Runtime Layer
|
||||
|
||||
runtime/protocol.py
|
||||
```
|
||||
@@ -0,0 +1,237 @@
|
||||
# Build 015.1 — Common Models Extension / RuntimeResult
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 015.1 |
|
||||
| Название | Common Models Extension / RuntimeResult |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Common |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
Во время проектирования `RuntimeProtocol` было установлено, что Runtime не может возвращать `EngineResult`.
|
||||
|
||||
`EngineResult` описывает результат выполнения одного Engine.
|
||||
|
||||
Runtime агрегирует результаты нескольких Engine, поэтому ему нужен собственный официальный результат выполнения.
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Добавить в Common Layer модель:
|
||||
|
||||
```text
|
||||
RuntimeResult
|
||||
```
|
||||
|
||||
`RuntimeResult` является единым контрактом результата выполнения Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`RuntimeResult` агрегирует результаты нескольких Engine.
|
||||
|
||||
Модель не содержит аналитики, не принимает торговых решений и не зависит от конкретных Engine.
|
||||
|
||||
Основной источник истины:
|
||||
|
||||
```text
|
||||
engine_results
|
||||
```
|
||||
|
||||
Все производные данные вычисляются из него.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- модель относится к Common Layer;
|
||||
- RuntimeResult нужен Runtime, Coordinator, стратегиям, диагностике и тестам;
|
||||
- производные данные не должны храниться отдельно;
|
||||
- RuntimeResult не должен зависеть от Runtime-реализации.
|
||||
|
||||
Архитектура Build признана корректной.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision (ADR)
|
||||
|
||||
## Решение
|
||||
|
||||
Добавить `RuntimeResult` в `common.models`.
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
## Обоснование
|
||||
|
||||
Runtime выполняет несколько Engine и должен возвращать агрегированный результат.
|
||||
|
||||
Размещение `RuntimeResult` в Common Layer сохраняет однонаправленные зависимости и позволяет использовать модель разными слоями платформы.
|
||||
|
||||
## Последствия
|
||||
|
||||
После принятия решения:
|
||||
|
||||
- Runtime сможет возвращать единый результат выполнения;
|
||||
- Coordinator сможет работать с агрегированным контрактом;
|
||||
- исключается дублирование списков выполненных и ошибочных Engine;
|
||||
- RuntimeProtocol можно проектировать без временных моделей.
|
||||
|
||||
---
|
||||
|
||||
# Build Design
|
||||
|
||||
Модель добавлена в файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/models.py
|
||||
```
|
||||
|
||||
Расположение:
|
||||
|
||||
```text
|
||||
EngineResult
|
||||
↓
|
||||
RuntimeResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Реализованы хранимые поля:
|
||||
|
||||
```text
|
||||
engine_results
|
||||
diagnostics
|
||||
started_at
|
||||
finished_at
|
||||
duration_ms
|
||||
metadata
|
||||
```
|
||||
|
||||
Реализованы вычисляемые свойства:
|
||||
|
||||
```text
|
||||
successful_results
|
||||
failed_results
|
||||
partial_results
|
||||
stale_results
|
||||
executed_engines
|
||||
failed_engines
|
||||
successful_engines
|
||||
has_errors
|
||||
is_successful
|
||||
total_engines
|
||||
successful_count
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- успешно скомпилирован `common/models.py`;
|
||||
- синтаксические ошибки отсутствуют;
|
||||
- циклические зависимости отсутствуют.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Проверено соответствие предметной области.
|
||||
|
||||
`RuntimeResult`:
|
||||
|
||||
- агрегирует результаты нескольких `EngineResult`;
|
||||
- не содержит аналитической логики;
|
||||
- не принимает торговых решений;
|
||||
- не зависит от Runtime-реализации;
|
||||
- не зависит от Coordinator;
|
||||
- не зависит от конкретных Engine;
|
||||
- производные данные вычисляются из `engine_results`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
В рамках Build должны быть обновлены:
|
||||
|
||||
- Build History;
|
||||
- Runtime Contract;
|
||||
- Common Models Documentation;
|
||||
- будущая документация Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build считается завершённым.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture
|
||||
- ✅ Architecture Review
|
||||
- ✅ Architecture Decision (ADR)
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Documentation
|
||||
- ✅ Acceptance
|
||||
|
||||
Статус Build:
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Итоги Build
|
||||
|
||||
В результате Build 015.1:
|
||||
|
||||
- Common Layer получил модель `RuntimeResult`;
|
||||
- Runtime Layer получил будущий выходной контракт;
|
||||
- Coordinator сможет работать с агрегированным результатом Runtime;
|
||||
- подготовлена основа для Build 015.2 — `runtime/protocol.py`.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 015.2
|
||||
|
||||
Runtime Protocol
|
||||
|
||||
runtime/protocol.py
|
||||
```
|
||||
284
docs/market_intelligence/builds/build-015-2-runtime-protocol.md
Normal file
284
docs/market_intelligence/builds/build-015-2-runtime-protocol.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# Build 015.2 — Runtime Protocol
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 015.2 |
|
||||
| Название | Runtime Protocol |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Runtime |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После появления `RuntimeResult` стало возможно определить официальный контракт Runtime Layer.
|
||||
|
||||
Runtime должен взаимодействовать с аналитическими Engine через единый стабильный интерфейс и не зависеть от конкретных реализаций Engine.
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/runtime/protocol.py
|
||||
```
|
||||
|
||||
и определить в нём официальный контракт Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`RuntimeProtocol` описывает только внешний интерфейс Runtime.
|
||||
|
||||
Runtime отвечает за:
|
||||
|
||||
- регистрацию Engine;
|
||||
- удаление Engine;
|
||||
- получение зарегистрированного Engine;
|
||||
- выполнение анализа;
|
||||
- возврат агрегированного `RuntimeResult`.
|
||||
|
||||
Runtime не отвечает за:
|
||||
|
||||
- аналитику;
|
||||
- торговые решения;
|
||||
- порядок стратегий;
|
||||
- пользовательский интерфейс;
|
||||
- работу с биржей;
|
||||
- работу с БД;
|
||||
- журналирование.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- Runtime работает через `EngineProtocol`;
|
||||
- Runtime регистрирует классы Engine, а не экземпляры;
|
||||
- Runtime возвращает `RuntimeResult`;
|
||||
- Runtime не знает конкретных Engine;
|
||||
- Runtime не содержит аналитики;
|
||||
- Runtime не содержит Coordinator-логики;
|
||||
- AutoTrade не изменяется.
|
||||
|
||||
Архитектура Build признана корректной.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision (ADR)
|
||||
|
||||
## Решение
|
||||
|
||||
Runtime Layer регистрирует классы Engine, а не экземпляры Engine.
|
||||
|
||||
Официальный контракт:
|
||||
|
||||
```python
|
||||
register_engine(
|
||||
engine_type: type[EngineProtocol],
|
||||
) -> None
|
||||
```
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
## Обоснование
|
||||
|
||||
`EngineMetadata` доступна без создания экземпляра Engine через `get_metadata()`.
|
||||
|
||||
Поэтому Runtime не обязан создавать объект Engine на этапе регистрации.
|
||||
|
||||
Регистрация класса позволяет Runtime самостоятельно управлять жизненным циклом экземпляров Engine.
|
||||
|
||||
## Обязательное правило
|
||||
|
||||
Все Engine обязаны иметь конструктор без пользовательских параметров.
|
||||
|
||||
Всё изменяемое состояние и конфигурация анализа передаются через:
|
||||
|
||||
```text
|
||||
EngineContext
|
||||
```
|
||||
|
||||
## Запрещено
|
||||
|
||||
```python
|
||||
register_engine(engine: EngineProtocol)
|
||||
```
|
||||
|
||||
Регистрация экземпляров Engine запрещена.
|
||||
|
||||
## Последствия
|
||||
|
||||
После принятия решения:
|
||||
|
||||
- Runtime контролирует жизненный цикл Engine;
|
||||
- Engine не сохраняют состояние между запусками;
|
||||
- Runtime готов к параллельному выполнению;
|
||||
- Registry сможет хранить типы Engine;
|
||||
- добавление новых Engine не требует изменения Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Build Design
|
||||
|
||||
Реализуется контракт:
|
||||
|
||||
```text
|
||||
RuntimeProtocol
|
||||
├── register_engine(engine_type)
|
||||
├── unregister_engine(engine_name)
|
||||
├── get_engine(engine_name)
|
||||
└── analyze(context)
|
||||
```
|
||||
|
||||
Файл не содержит реализации Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Реализован файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/runtime/protocol.py
|
||||
```
|
||||
|
||||
Содержимое контракта:
|
||||
|
||||
```python
|
||||
class RuntimeProtocol(Protocol):
|
||||
def register_engine(
|
||||
self,
|
||||
engine_type: type[EngineProtocol],
|
||||
) -> None:
|
||||
...
|
||||
|
||||
def unregister_engine(
|
||||
self,
|
||||
engine_name: EngineName,
|
||||
) -> None:
|
||||
...
|
||||
|
||||
def get_engine(
|
||||
self,
|
||||
engine_name: EngineName,
|
||||
) -> type[EngineProtocol] | None:
|
||||
...
|
||||
|
||||
async def analyze(
|
||||
self,
|
||||
context: EngineContext,
|
||||
) -> RuntimeResult:
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- успешно скомпилирован `runtime/protocol.py`;
|
||||
- синтаксические ошибки отсутствуют;
|
||||
- циклические зависимости отсутствуют.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Проверено соответствие предметной области.
|
||||
|
||||
`RuntimeProtocol`:
|
||||
|
||||
- работает через `EngineProtocol`;
|
||||
- регистрирует классы Engine;
|
||||
- возвращает `RuntimeResult`;
|
||||
- не знает конкретных Engine;
|
||||
- не содержит аналитики;
|
||||
- не содержит Coordinator-логики;
|
||||
- не зависит от AutoTrade;
|
||||
- не обращается к бирже, БД, Telegram или EventBus;
|
||||
- получает изменяемые данные анализа только через `EngineContext`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
В рамках Build должны быть обновлены:
|
||||
|
||||
- Build History;
|
||||
- Runtime Contract;
|
||||
- Engine Layer Architecture;
|
||||
- Runtime Architecture.
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build считается завершённым.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture
|
||||
- ✅ Architecture Review
|
||||
- ✅ Architecture Decision (ADR)
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Documentation
|
||||
- ✅ Acceptance
|
||||
|
||||
Статус Build:
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Итоги Build
|
||||
|
||||
В результате Build 015.2:
|
||||
|
||||
- создан официальный контракт Runtime Layer;
|
||||
- Runtime получил стабильную зависимость от `EngineProtocol`;
|
||||
- закреплена регистрация классов Engine вместо экземпляров;
|
||||
- Runtime возвращает агрегированный `RuntimeResult`;
|
||||
- подготовлена основа для реализации Runtime Registry.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 015.3
|
||||
|
||||
Runtime Registry
|
||||
|
||||
runtime/registry.py
|
||||
```
|
||||
@@ -0,0 +1,296 @@
|
||||
# Build 015.3 — Common Models Extension / EngineRegistration
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 015.3 |
|
||||
| Название | Common Models Extension / EngineRegistration |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Common |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
Во время проектирования `RuntimeRegistry` было установлено, что хранение только класса Engine недостаточно.
|
||||
|
||||
Runtime Registry постоянно работает с двумя сущностями:
|
||||
|
||||
- типом Engine;
|
||||
- его Metadata.
|
||||
|
||||
Постоянный вызов `Engine.get_metadata()` привёл бы к дублированию логики и усложнил бы реализацию Registry.
|
||||
|
||||
Для устранения этой проблемы введена единая модель регистрации Engine.
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Добавить в Common Layer новую фундаментальную модель:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
Модель описывает зарегистрированный аналитический движок и является единицей хранения Runtime Registry.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`EngineRegistration` представляет собой атомарную запись регистрации Engine.
|
||||
|
||||
Модель не является:
|
||||
|
||||
- Engine;
|
||||
- Runtime;
|
||||
- Registry;
|
||||
- Runtime Contract.
|
||||
|
||||
Это исключительно модель Common Layer.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- модель относится к Common Layer;
|
||||
- Runtime Registry использует одну запись регистрации вместо двух независимых сущностей;
|
||||
- отсутствует дублирование Metadata;
|
||||
- сохраняется разделение Metadata и Logic;
|
||||
- сохраняется однонаправленная архитектура зависимостей.
|
||||
|
||||
Архитектура Build признана корректной.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision (ADR)
|
||||
|
||||
## Решение
|
||||
|
||||
Добавить модель:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
в `common.models`.
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
## Обоснование
|
||||
|
||||
Во время проектирования Runtime Registry подтверждено, что регистрация Engine является самостоятельной архитектурной сущностью.
|
||||
|
||||
Модель объединяет:
|
||||
|
||||
- тип Engine;
|
||||
- его Metadata.
|
||||
|
||||
При этом сама Metadata остаётся единственным источником информации об Engine.
|
||||
|
||||
## Главное правило
|
||||
|
||||
`EngineRegistration` не должен дублировать информацию, уже содержащуюся в `EngineMetadata`.
|
||||
|
||||
Запрещается добавлять отдельные поля:
|
||||
|
||||
```text
|
||||
engine_name
|
||||
engine_version
|
||||
dependencies
|
||||
priority
|
||||
enabled_by_default
|
||||
registered_at
|
||||
```
|
||||
|
||||
## Последствия
|
||||
|
||||
После принятия решения:
|
||||
|
||||
- Runtime Registry сможет хранить атомарные записи регистрации;
|
||||
- Metadata будет доступна без обращения к классу Engine;
|
||||
- Runtime сохранит контроль над жизненным циклом Engine;
|
||||
- модель регистрации останется независимой от Runtime-состояния.
|
||||
|
||||
---
|
||||
|
||||
# Build Design
|
||||
|
||||
В файл
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/models.py
|
||||
```
|
||||
|
||||
добавлены:
|
||||
|
||||
```text
|
||||
EngineTypeProtocol
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
`EngineTypeProtocol` используется как минимальный контракт класса Engine и позволяет избежать запрещённой зависимости:
|
||||
|
||||
```text
|
||||
Common → Engine
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Реализованы:
|
||||
|
||||
```text
|
||||
EngineTypeProtocol
|
||||
```
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
Состав модели:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
├── engine_type
|
||||
└── metadata
|
||||
```
|
||||
|
||||
Модель не содержит дополнительных полей.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- успешно скомпилирован `common/models.py`;
|
||||
- синтаксические ошибки отсутствуют;
|
||||
- циклические зависимости отсутствуют.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Проверено соответствие предметной области.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `EngineRegistration` описывает регистрацию Engine, а не сам Engine;
|
||||
- модель не содержит аналитической логики;
|
||||
- модель не содержит Runtime-состояния;
|
||||
- `EngineRegistration` не дублирует данные из `EngineMetadata`;
|
||||
- Common Layer не импортирует `EngineProtocol`;
|
||||
- Runtime Registry сможет использовать `EngineRegistration` как единую запись регистрации.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
В рамках Build должны быть обновлены:
|
||||
|
||||
- Build History;
|
||||
- Runtime Architecture;
|
||||
- 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 015.3:
|
||||
|
||||
- Common Layer получил модель `EngineRegistration`;
|
||||
- Runtime Registry получил единицу хранения зарегистрированных Engine;
|
||||
- устранено дублирование вызовов `Engine.get_metadata()`;
|
||||
- сохранён принцип единственного источника истины;
|
||||
- сохранена однонаправленная архитектура зависимостей между слоями.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные принципы, закреплённые Build
|
||||
|
||||
В рамках Build официально закреплены следующие правила.
|
||||
|
||||
### EngineRegistration не дублирует Metadata
|
||||
|
||||
Если информация уже содержится в `EngineMetadata`, она не должна повторяться в `EngineRegistration`.
|
||||
|
||||
### Один источник истины
|
||||
|
||||
Описание Engine хранится исключительно в `EngineMetadata`.
|
||||
|
||||
`EngineRegistration` только связывает тип Engine с его Metadata.
|
||||
|
||||
### Common Layer не зависит от Engine Layer
|
||||
|
||||
Для хранения типа Engine используется минимальный локальный протокол:
|
||||
|
||||
```text
|
||||
EngineTypeProtocol
|
||||
```
|
||||
|
||||
Это позволяет избежать запрещённой зависимости:
|
||||
|
||||
```text
|
||||
Common → Engine
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 015.4
|
||||
|
||||
Runtime Registry
|
||||
|
||||
runtime/registry.py
|
||||
```
|
||||
360
docs/market_intelligence/builds/build-015-4-runtime-registry.md
Normal file
360
docs/market_intelligence/builds/build-015-4-runtime-registry.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# Build 015.4 — Runtime Registry
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 015.4 |
|
||||
| Название | Runtime Registry |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Runtime |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После завершения Build:
|
||||
|
||||
- 015.1 (`RuntimeResult`);
|
||||
- 015.2 (`RuntimeProtocol`);
|
||||
- 015.3 (`EngineRegistration`);
|
||||
|
||||
Runtime получил все необходимые фундаментальные модели для реализации первого инфраструктурного компонента Runtime Layer.
|
||||
|
||||
Таким компонентом стал `RuntimeRegistry`.
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать каталог зарегистрированных аналитических Engine.
|
||||
|
||||
Registry является единым источником информации о зарегистрированных Engine и предоставляет минимальный API регистрации.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`RuntimeRegistry` отвечает исключительно за регистрацию аналитических Engine.
|
||||
|
||||
Registry не выполняет анализ рынка.
|
||||
|
||||
Registry не создаёт `EngineContext`.
|
||||
|
||||
Registry не запускает Engine.
|
||||
|
||||
Registry не агрегирует результаты.
|
||||
|
||||
Registry не управляет Coordinator.
|
||||
|
||||
Единственная ответственность Registry — управление зарегистрированными Engine.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- Registry соответствует принципу Single Responsibility;
|
||||
- Registry использует `EngineRegistration`;
|
||||
- Registry не содержит аналитики;
|
||||
- Registry не зависит от Coordinator;
|
||||
- Registry не зависит от AutoTrade;
|
||||
- Registry не создаёт `EngineContext`;
|
||||
- Registry не запускает Engine.
|
||||
|
||||
Архитектура Build признана корректной.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision (ADR)
|
||||
|
||||
## Решение
|
||||
|
||||
Добавить компонент:
|
||||
|
||||
```text
|
||||
RuntimeRegistry
|
||||
```
|
||||
|
||||
в Runtime Layer.
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
## Обоснование
|
||||
|
||||
Runtime должен иметь единый каталог зарегистрированных Engine.
|
||||
|
||||
Registry хранит записи регистрации и предоставляет к ним доступ другим компонентам Runtime.
|
||||
|
||||
Для хранения используется модель:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
## Утверждённая модель хранения
|
||||
|
||||
```python
|
||||
dict[
|
||||
EngineName,
|
||||
EngineRegistration,
|
||||
]
|
||||
```
|
||||
|
||||
## Публичный API
|
||||
|
||||
```text
|
||||
register()
|
||||
unregister()
|
||||
get()
|
||||
contains()
|
||||
list()
|
||||
clear()
|
||||
```
|
||||
|
||||
## Запрещено
|
||||
|
||||
Registry не должен содержать:
|
||||
|
||||
```text
|
||||
analyze()
|
||||
run()
|
||||
execute()
|
||||
resolve_dependencies()
|
||||
validate()
|
||||
build_graph()
|
||||
sort()
|
||||
```
|
||||
|
||||
## Последствия
|
||||
|
||||
После принятия решения:
|
||||
|
||||
- Runtime получил единый каталог Engine;
|
||||
- Registry остаётся независимым от аналитики;
|
||||
- RuntimeRunner сможет использовать Registry;
|
||||
- DependencyResolver сможет использовать Registry;
|
||||
- добавление новых Engine не требует изменения Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Build Design
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/runtime/registry.py
|
||||
```
|
||||
|
||||
Внутренний каталог Registry:
|
||||
|
||||
```python
|
||||
self._engines: dict[
|
||||
EngineName,
|
||||
EngineRegistration,
|
||||
]
|
||||
```
|
||||
|
||||
При регистрации Registry самостоятельно создаёт:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
через:
|
||||
|
||||
```python
|
||||
engine_type.get_metadata()
|
||||
```
|
||||
|
||||
Дополнительная фабрика регистрации не используется.
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Реализован компонент:
|
||||
|
||||
```text
|
||||
RuntimeRegistry
|
||||
```
|
||||
|
||||
Публичный интерфейс:
|
||||
|
||||
```text
|
||||
register()
|
||||
unregister()
|
||||
get()
|
||||
contains()
|
||||
list()
|
||||
clear()
|
||||
```
|
||||
|
||||
Registry использует:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
как единственную единицу хранения зарегистрированных Engine.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- успешно скомпилирован `runtime/registry.py`;
|
||||
- синтаксические ошибки отсутствуют;
|
||||
- циклические зависимости отсутствуют.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Проверено соответствие предметной области.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Registry хранит только зарегистрированные Engine;
|
||||
- Registry использует `EngineRegistration`;
|
||||
- Registry не содержит аналитики;
|
||||
- Registry не управляет выполнением Engine;
|
||||
- Registry не создаёт `EngineContext`;
|
||||
- Registry не формирует `RuntimeResult`;
|
||||
- Registry не знает Coordinator;
|
||||
- Registry не зависит от AutoTrade;
|
||||
- Registry не обращается к бирже, БД, Telegram или EventBus.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
В рамках Build должны быть обновлены:
|
||||
|
||||
- Build History;
|
||||
- Runtime Architecture;
|
||||
- Runtime Contract;
|
||||
- Runtime Layer Documentation.
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build считается завершённым.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture
|
||||
- ✅ Architecture Review
|
||||
- ✅ Architecture Decision (ADR)
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Documentation
|
||||
- ✅ Acceptance
|
||||
|
||||
Статус Build:
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Итоги Build
|
||||
|
||||
В результате Build 015.4:
|
||||
|
||||
- Runtime Layer получил первый инфраструктурный компонент;
|
||||
- появился единый каталог зарегистрированных Engine;
|
||||
- Runtime получил единый механизм регистрации аналитических движков;
|
||||
- Registry использует `EngineRegistration` как атомарную запись;
|
||||
- подготовлена основа для реализации Runtime Runner.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные принципы, закреплённые Build
|
||||
|
||||
## Registry отвечает только за регистрацию
|
||||
|
||||
`RuntimeRegistry` не выполняет анализ и не управляет выполнением Engine.
|
||||
|
||||
Единственная ответственность Registry — управление каталогом зарегистрированных Engine.
|
||||
|
||||
---
|
||||
|
||||
## EngineRegistration является единицей хранения
|
||||
|
||||
Внутри Registry хранится исключительно:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
Хранение отдельных `EngineType` или `EngineMetadata` запрещено.
|
||||
|
||||
---
|
||||
|
||||
## Runtime самостоятельно создаёт регистрацию
|
||||
|
||||
Во время регистрации Registry самостоятельно получает Metadata:
|
||||
|
||||
```python
|
||||
metadata = engine_type.get_metadata()
|
||||
```
|
||||
|
||||
и создаёт:
|
||||
|
||||
```text
|
||||
EngineRegistration
|
||||
```
|
||||
|
||||
Отдельная фабрика регистрации не вводится.
|
||||
|
||||
---
|
||||
|
||||
## Registry не содержит эксплуатационной логики
|
||||
|
||||
Registry не выполняет:
|
||||
|
||||
- анализ;
|
||||
- запуск Engine;
|
||||
- сортировку;
|
||||
- разрешение зависимостей;
|
||||
- построение графов;
|
||||
- валидацию.
|
||||
|
||||
Все перечисленные обязанности относятся к другим компонентам Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 015.5
|
||||
|
||||
Runtime Runner
|
||||
|
||||
runtime/runner.py
|
||||
```
|
||||
275
docs/market_intelligence/builds/build-015-5-runtime-core.md
Normal file
275
docs/market_intelligence/builds/build-015-5-runtime-core.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# Build 015.5 — Runtime Core
|
||||
|
||||
**Build Documentation**
|
||||
|
||||
---
|
||||
|
||||
# Контроль Build
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 015.5 |
|
||||
| Название | Runtime Core |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Проект | Dzentra |
|
||||
| Тип | Architecture Build |
|
||||
| Версия | 1.0 |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Завершить формирование базовой инфраструктуры Runtime Layer, реализовав компоненты, необходимые для регистрации аналитических Engine, их безопасного выполнения и обработки внутренних ошибок Runtime.
|
||||
|
||||
Build завершает минимальное ядро Runtime перед переходом к разработке Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная задача
|
||||
|
||||
До начала Build Runtime уже содержал:
|
||||
|
||||
- Runtime Protocol;
|
||||
- Runtime Models;
|
||||
- Runtime Registry.
|
||||
|
||||
Отсутствовали компоненты, отвечающие за непосредственное выполнение зарегистрированного Engine и унифицированную модель внутренних исключений Runtime.
|
||||
|
||||
Настоящий Build реализует данные компоненты без изменения существующих Runtime Contract.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурное решение
|
||||
|
||||
В рамках Build реализованы два самостоятельных компонента Runtime Layer.
|
||||
|
||||
## Runtime Runner
|
||||
|
||||
`RuntimeRunner` отвечает исключительно за выполнение одного зарегистрированного Engine.
|
||||
|
||||
Ответственность Runner ограничивается:
|
||||
|
||||
- созданием экземпляра Engine;
|
||||
- передачей Runtime Context;
|
||||
- получением Engine Result.
|
||||
|
||||
Runner не содержит:
|
||||
|
||||
- логики анализа рынка;
|
||||
- управления последовательностью выполнения Engine;
|
||||
- агрегации результатов;
|
||||
- обработки зависимостей;
|
||||
- координации Runtime.
|
||||
|
||||
---
|
||||
|
||||
## Runtime Exceptions
|
||||
|
||||
Создан единый набор специализированных исключений Runtime.
|
||||
|
||||
Исключения предназначены исключительно для внутренней инфраструктуры Runtime Layer.
|
||||
|
||||
Реализованы:
|
||||
|
||||
- RuntimeError;
|
||||
- EngineNotRegisteredError;
|
||||
- InvalidRuntimeContextError;
|
||||
- EngineExecutionError.
|
||||
|
||||
Наличие собственного пространства исключений исключает использование необобщённых Exception внутри Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные файлы
|
||||
|
||||
Добавлены:
|
||||
|
||||
```text
|
||||
runtime/exceptions.py
|
||||
runtime/runner.py
|
||||
```
|
||||
|
||||
Использован существующий компонент:
|
||||
|
||||
```text
|
||||
runtime/registry.py
|
||||
```
|
||||
|
||||
Изменён:
|
||||
|
||||
```text
|
||||
common/models.py
|
||||
```
|
||||
|
||||
В `EngineTypeProtocol` добавлен метод:
|
||||
|
||||
```python
|
||||
analyze(context) -> EngineResult
|
||||
```
|
||||
|
||||
Данное изменение устраняет расхождение между Runtime Registry и Runtime Runner и обеспечивает корректную статическую типизацию без изменения архитектурного контракта Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные зависимости
|
||||
|
||||
Build не изменяет существующую модель зависимостей.
|
||||
|
||||
Итоговая структура Runtime Layer:
|
||||
|
||||
```text
|
||||
Runtime Layer
|
||||
|
||||
├── protocol.py
|
||||
├── registry.py
|
||||
├── runner.py
|
||||
└── exceptions.py
|
||||
```
|
||||
|
||||
Зависимости остаются однонаправленными.
|
||||
|
||||
```text
|
||||
RuntimeRunner
|
||||
│
|
||||
▼
|
||||
EngineRegistration
|
||||
│
|
||||
▼
|
||||
EngineProtocol
|
||||
```
|
||||
|
||||
Runtime по-прежнему не зависит от Coordinator и не содержит предметной логики.
|
||||
|
||||
---
|
||||
|
||||
# Runtime Contract
|
||||
|
||||
Build не изменяет:
|
||||
|
||||
- Runtime Context;
|
||||
- Engine Result;
|
||||
- Runtime Status;
|
||||
- Runtime Events;
|
||||
- Runtime Models;
|
||||
- Runtime Contract.
|
||||
|
||||
Все существующие Runtime Contract остаются полностью совместимыми.
|
||||
|
||||
---
|
||||
|
||||
# Engineering Review
|
||||
|
||||
## Architecture Review
|
||||
|
||||
Passed.
|
||||
|
||||
Компоненты имеют единственную область ответственности.
|
||||
|
||||
---
|
||||
|
||||
## Dependency Review
|
||||
|
||||
Passed.
|
||||
|
||||
Циклические зависимости отсутствуют.
|
||||
|
||||
Направление зависимостей соответствует утверждённой архитектуре.
|
||||
|
||||
---
|
||||
|
||||
## Runtime Review
|
||||
|
||||
Passed.
|
||||
|
||||
Runtime остаётся инфраструктурным уровнем.
|
||||
|
||||
Runtime не содержит аналитической или торговой логики.
|
||||
|
||||
---
|
||||
|
||||
## Code Review
|
||||
|
||||
Passed.
|
||||
|
||||
Код соответствует принципам:
|
||||
|
||||
- Single Responsibility Principle;
|
||||
- One Source of Truth;
|
||||
- Stable Foundation;
|
||||
- Architecture First.
|
||||
|
||||
Во время проверки обнаружено частичное дублирование контрактов `EngineProtocol` и `EngineTypeProtocol`.
|
||||
|
||||
Для обеспечения корректной статической типизации в `EngineTypeProtocol` добавлен метод `analyze()`.
|
||||
|
||||
Архитектурное объединение контрактов признано отдельной задачей и не входит в настоящий Build.
|
||||
|
||||
---
|
||||
|
||||
## Compile Review
|
||||
|
||||
Passed.
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Ошибок компиляции не обнаружено.
|
||||
|
||||
---
|
||||
|
||||
# Изменённые документы
|
||||
|
||||
Обновление Runtime Contract не потребовалось.
|
||||
|
||||
Настоящий Build документирует исключительно развитие Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Итоговое состояние Runtime
|
||||
|
||||
После завершения Build Runtime Layer имеет следующий состав.
|
||||
|
||||
```text
|
||||
runtime/
|
||||
|
||||
├── protocol.py
|
||||
├── registry.py
|
||||
├── runner.py
|
||||
├── exceptions.py
|
||||
```
|
||||
|
||||
Runtime Layer полностью готов к реализации Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
Следующим этапом развития платформы является:
|
||||
|
||||
> **Build 016 — Coordinator Core**
|
||||
|
||||
Coordinator станет первым компонентом, использующим Runtime Registry и Runtime Runner для выполнения полного набора зарегистрированных аналитических Engine.
|
||||
|
||||
---
|
||||
|
||||
# Итог
|
||||
|
||||
Build 015.5 полностью завершает формирование базовой инфраструктуры Runtime Layer.
|
||||
|
||||
Все поставленные архитектурные задачи выполнены.
|
||||
|
||||
Build успешно прошёл:
|
||||
|
||||
- Architecture Review;
|
||||
- Dependency Review;
|
||||
- Runtime Review;
|
||||
- Code Review;
|
||||
- Compile Review.
|
||||
|
||||
Build получает статус:
|
||||
|
||||
> **Accepted**
|
||||
@@ -0,0 +1,265 @@
|
||||
# Build 015.6 — Runtime Dependencies
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 015.6 |
|
||||
| Название | Runtime Dependencies |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Runtime |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После реализации `RuntimeRegistry` и `RuntimeRunner` Runtime Layer получил возможность хранить и выполнять зарегистрированные Engine.
|
||||
|
||||
Однако порядок выполнения Engine должен учитывать зависимости, объявленные в `EngineMetadata`.
|
||||
|
||||
Для этого необходим отдельный компонент Runtime Layer, отвечающий только за разрешение зависимостей.
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать компонент:
|
||||
|
||||
```text
|
||||
RuntimeDependencies
|
||||
```
|
||||
|
||||
который определяет корректный порядок выполнения зарегистрированных Engine на основании их обязательных зависимостей.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`RuntimeDependencies` получает:
|
||||
|
||||
```text
|
||||
tuple[EngineRegistration, ...]
|
||||
```
|
||||
|
||||
и возвращает:
|
||||
|
||||
```text
|
||||
tuple[EngineRegistration, ...]
|
||||
```
|
||||
|
||||
в порядке выполнения.
|
||||
|
||||
Компонент не создаёт Engine, не запускает Engine, не формирует результаты и не зависит от Coordinator.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- Engine остаются независимыми;
|
||||
- зависимости объявляются через `EngineMetadata`;
|
||||
- Runtime не содержит аналитики;
|
||||
- Runner не смешивается с Dependency Resolver;
|
||||
- Registry не строит граф зависимостей;
|
||||
- Coordinator пока не реализуется.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision (ADR)
|
||||
|
||||
## Решение
|
||||
|
||||
В Runtime Layer вводится компонент:
|
||||
|
||||
```text
|
||||
RuntimeDependencies
|
||||
```
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
## Обоснование
|
||||
|
||||
Engine могут объявлять обязательные зависимости через:
|
||||
|
||||
```text
|
||||
EngineMetadata.required_dependencies
|
||||
```
|
||||
|
||||
Runtime должен определить порядок выполнения Engine до запуска анализа.
|
||||
|
||||
Эта ответственность не относится к Registry, Runner, Coordinator или конкретным Engine.
|
||||
|
||||
---
|
||||
|
||||
# Build Design
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/runtime/dependencies.py
|
||||
```
|
||||
|
||||
Обновлён файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/runtime/exceptions.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
RuntimeDependencies
|
||||
```
|
||||
|
||||
Публичный API:
|
||||
|
||||
```text
|
||||
resolve(registrations)
|
||||
```
|
||||
|
||||
Внутренние этапы:
|
||||
|
||||
```text
|
||||
_build_registration_map()
|
||||
_build_graph()
|
||||
_validate_dependencies()
|
||||
_topological_sort()
|
||||
_visit()
|
||||
```
|
||||
|
||||
Добавлены Runtime-исключения:
|
||||
|
||||
```text
|
||||
MissingEngineDependencyError
|
||||
CircularEngineDependencyError
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- успешно скомпилирован `runtime/dependencies.py`;
|
||||
- успешно скомпилирован `runtime/exceptions.py`;
|
||||
- синтаксические ошибки отсутствуют;
|
||||
- циклические зависимости отсутствуют.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Проверено соответствие предметной области.
|
||||
|
||||
`RuntimeDependencies`:
|
||||
|
||||
- работает только с зарегистрированными Engine;
|
||||
- берёт зависимости исключительно из `EngineMetadata.required_dependencies`;
|
||||
- не создаёт экземпляры Engine;
|
||||
- не запускает Engine;
|
||||
- не формирует `EngineResult` или `RuntimeResult`;
|
||||
- не зависит от Coordinator;
|
||||
- не добавляет аналитической логики.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review / Runtime Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент имеет одну ответственность;
|
||||
- отсутствующие обязательные зависимости обрабатываются отдельной ошибкой;
|
||||
- циклические зависимости обрабатываются отдельной ошибкой;
|
||||
- топологическая сортировка возвращает корректный порядок выполнения;
|
||||
- зависимости между слоями не нарушены.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
В рамках Build должны быть обновлены:
|
||||
|
||||
- Build History;
|
||||
- Runtime Architecture;
|
||||
- Runtime Layer Documentation.
|
||||
|
||||
Runtime Contract не изменяется.
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build считается завершённым.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture
|
||||
- ✅ Architecture Review
|
||||
- ✅ Architecture Decision
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Runtime Review
|
||||
- ✅ Documentation
|
||||
- ✅ Acceptance
|
||||
|
||||
Статус Build:
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Итоги Build
|
||||
|
||||
В результате Build 015.6:
|
||||
|
||||
- Runtime Layer получил механизм разрешения зависимостей;
|
||||
- порядок выполнения Engine теперь может быть построен из `EngineMetadata`;
|
||||
- Engine остаются независимыми и не обращаются друг к другу напрямую;
|
||||
- Registry, Runner и Dependency Resolver имеют разные зоны ответственности;
|
||||
- Runtime Layer стал готов к следующему этапу — Runtime Validation или Coordinator Core.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 015.7
|
||||
|
||||
Runtime Validation
|
||||
|
||||
runtime/validation.py
|
||||
```
|
||||
@@ -0,0 +1,280 @@
|
||||
# Build 015.7 — Runtime Validation
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 015.7 |
|
||||
| Название | Runtime Validation |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Runtime |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После реализации компонентов:
|
||||
|
||||
- Runtime Registry;
|
||||
- Runtime Runner;
|
||||
- Runtime Dependencies;
|
||||
|
||||
Runtime Layer получил возможность хранить зарегистрированные Engine, определять порядок их выполнения и запускать анализ.
|
||||
|
||||
Однако отсутствовала единая точка проверки корректности Runtime перед началом выполнения.
|
||||
|
||||
Проверка конфигурации Runtime должна выполняться централизованно и до запуска любого Engine.
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать компонент:
|
||||
|
||||
```text
|
||||
RuntimeValidation
|
||||
```
|
||||
|
||||
который подтверждает готовность Runtime Layer к выполнению анализа.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`RuntimeValidation` получает:
|
||||
|
||||
```text
|
||||
RuntimeRegistry
|
||||
```
|
||||
|
||||
и выполняет проверку корректности зарегистрированных Engine.
|
||||
|
||||
Компонент:
|
||||
|
||||
- не создаёт Engine;
|
||||
- не запускает Engine;
|
||||
- не изменяет Registry;
|
||||
- не выполняет анализ рынка;
|
||||
- не строит граф зависимостей самостоятельно.
|
||||
|
||||
Проверка зависимостей делегируется компоненту:
|
||||
|
||||
```text
|
||||
RuntimeDependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- RuntimeValidation имеет единственную ответственность;
|
||||
- проверки отделены от Registry и Runner;
|
||||
- RuntimeDependencies используется повторно без дублирования логики;
|
||||
- Coordinator не участвует в проверке Runtime;
|
||||
- архитектурные зависимости соответствуют утверждённой модели Runtime Layer.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision (ADR)
|
||||
|
||||
## Решение
|
||||
|
||||
В Runtime Layer вводится новый инфраструктурный компонент:
|
||||
|
||||
```text
|
||||
RuntimeValidation
|
||||
```
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
## Обоснование
|
||||
|
||||
Runtime должен гарантировать собственную корректность до запуска первого Engine.
|
||||
|
||||
Для этого необходим отдельный компонент, который централизует все проверки конфигурации Runtime.
|
||||
|
||||
Проверка зависимостей выполняется посредством использования уже существующего `RuntimeDependencies`.
|
||||
|
||||
Это сохраняет принцип единственной ответственности и предотвращает дублирование логики.
|
||||
|
||||
---
|
||||
|
||||
# Build Design
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/runtime/validation.py
|
||||
```
|
||||
|
||||
Обновлён файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/runtime/exceptions.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
RuntimeValidation
|
||||
```
|
||||
|
||||
Публичный интерфейс:
|
||||
|
||||
```text
|
||||
validate(registry)
|
||||
```
|
||||
|
||||
Во время проверки выполняются следующие этапы:
|
||||
|
||||
```text
|
||||
_validate_registry()
|
||||
_validate_metadata()
|
||||
_validate_duplicates()
|
||||
RuntimeDependencies.resolve()
|
||||
```
|
||||
|
||||
Добавлены новые исключения Runtime Validation:
|
||||
|
||||
```text
|
||||
RuntimeValidationError
|
||||
EmptyRuntimeRegistryError
|
||||
DuplicateEngineRegistrationError
|
||||
InvalidEngineMetadataError
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверка выполнена командой:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- успешно скомпилирован `runtime/validation.py`;
|
||||
- успешно обновлён `runtime/exceptions.py`;
|
||||
- синтаксические ошибки отсутствуют.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Проверено соответствие предметной области.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- RuntimeValidation проверяет только готовность Runtime;
|
||||
- Engine не создаются;
|
||||
- Engine не запускаются;
|
||||
- Registry не изменяется;
|
||||
- RuntimeResult не формируется;
|
||||
- аналитическая логика отсутствует;
|
||||
- проверка зависимостей делегирована RuntimeDependencies.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review / Runtime Review
|
||||
|
||||
Проверка успешно завершена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент имеет единственную ответственность;
|
||||
- отсутствует дублирование проверки зависимостей;
|
||||
- используется существующий RuntimeDependencies;
|
||||
- корректно проверяются обязательные поля Metadata;
|
||||
- иерархия Runtime-исключений расширена без нарушения существующей структуры.
|
||||
|
||||
Во время Code Review также подтверждено, что проверка повторной регистрации Engine в текущей реализации практически недостижима из-за использования словаря в `RuntimeRegistry`. Тем не менее данная проверка сохранена как часть публичного контракта `RuntimeValidation`, что обеспечивает устойчивость архитектуры при возможном изменении внутренней реализации Registry.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Documentation
|
||||
|
||||
В рамках Build должны быть обновлены:
|
||||
|
||||
- Build History;
|
||||
- Runtime Architecture;
|
||||
- Runtime Layer Documentation.
|
||||
|
||||
Runtime Contract не изменяется.
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build считается завершённым.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Development Strategy
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ Architecture Decision
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Runtime Review
|
||||
- ✅ Documentation
|
||||
- ✅ Acceptance
|
||||
|
||||
Статус Build:
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Итоги Build
|
||||
|
||||
В результате Build 015.7 Runtime Layer получил централизованный механизм проверки собственной корректности.
|
||||
|
||||
Теперь Runtime способен:
|
||||
|
||||
- проверять наличие зарегистрированных Engine;
|
||||
- проверять обязательные поля Metadata;
|
||||
- использовать RuntimeDependencies для проверки зависимостей;
|
||||
- подтверждать готовность Runtime до начала выполнения анализа.
|
||||
|
||||
После завершения Build 015.7 базовая инфраструктура Runtime Layer сформирована полностью.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 015.8
|
||||
|
||||
Runtime Service
|
||||
|
||||
runtime/service.py
|
||||
```
|
||||
226
docs/market_intelligence/builds/build-015-8-runtime-service.md
Normal file
226
docs/market_intelligence/builds/build-015-8-runtime-service.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Build 015.8 — Runtime Layer / Runtime Service
|
||||
|
||||
**Статус:** ✅ Accepted
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Завершить построение базовой инфраструктуры Runtime Layer путём введения единой публичной точки входа — `RuntimeService`.
|
||||
|
||||
Build объединяет ранее реализованные компоненты Runtime в единый жизненный цикл выполнения, не нарушая принцип единственной ответственности.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная задача
|
||||
|
||||
До Build 015.8 Runtime Layer уже содержал:
|
||||
|
||||
- Runtime Registry;
|
||||
- Runtime Validation;
|
||||
- Runtime Dependencies;
|
||||
- Runtime Runner.
|
||||
|
||||
Однако отсутствовал компонент, объединяющий их в единый процесс выполнения.
|
||||
|
||||
Build 015.8 завершает базовую архитектуру Runtime Layer введением Runtime Service.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные компоненты
|
||||
|
||||
```text
|
||||
runtime/
|
||||
|
||||
protocol.py
|
||||
registry.py
|
||||
validation.py
|
||||
dependencies.py
|
||||
runner.py
|
||||
service.py
|
||||
exceptions.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Реализовано
|
||||
|
||||
Создан новый компонент:
|
||||
|
||||
```text
|
||||
RuntimeService
|
||||
```
|
||||
|
||||
Runtime Service предоставляет единый публичный API Runtime Layer.
|
||||
|
||||
Поддерживаются операции:
|
||||
|
||||
- регистрация Engine;
|
||||
- удаление Engine;
|
||||
- получение регистрации Engine;
|
||||
- выполнение полного Runtime Pipeline.
|
||||
|
||||
---
|
||||
|
||||
# Архитектура выполнения
|
||||
|
||||
Во время выполнения Runtime Service использует существующие компоненты Runtime.
|
||||
|
||||
```text
|
||||
RuntimeRegistry
|
||||
↓
|
||||
RuntimeValidation
|
||||
↓
|
||||
RuntimeDependencies
|
||||
↓
|
||||
RuntimeRunner
|
||||
↓
|
||||
RuntimeResult
|
||||
```
|
||||
|
||||
Каждый компонент сохраняет собственную область ответственности.
|
||||
|
||||
---
|
||||
|
||||
# Ответственность Runtime Service
|
||||
|
||||
Runtime Service отвечает исключительно за координацию жизненного цикла Runtime.
|
||||
|
||||
Он:
|
||||
|
||||
- не содержит аналитики;
|
||||
- не реализует алгоритмы Engine;
|
||||
- не принимает торговых решений;
|
||||
- не интерпретирует результаты анализа;
|
||||
- не содержит собственной логики проверки зависимостей;
|
||||
- не содержит собственной логики запуска Engine.
|
||||
|
||||
Все специализированные задачи делегируются соответствующим Runtime-компонентам.
|
||||
|
||||
---
|
||||
|
||||
# Публичный API
|
||||
|
||||
Реализован следующий публичный интерфейс:
|
||||
|
||||
```python
|
||||
register_engine(...)
|
||||
unregister_engine(...)
|
||||
get_engine(...)
|
||||
analyze(...)
|
||||
```
|
||||
|
||||
Метод `analyze()` возвращает единый объект `RuntimeResult`.
|
||||
|
||||
---
|
||||
|
||||
# Runtime Pipeline
|
||||
|
||||
Во время анализа Runtime выполняет следующие этапы:
|
||||
|
||||
```text
|
||||
Registry
|
||||
↓
|
||||
Validation
|
||||
↓
|
||||
Dependency Resolution
|
||||
↓
|
||||
Engine Runner
|
||||
↓
|
||||
RuntimeResult
|
||||
```
|
||||
|
||||
Таким образом Runtime Layer получил полностью определённый жизненный цикл выполнения.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные результаты
|
||||
|
||||
Build завершил построение публичного фасада Runtime Layer.
|
||||
|
||||
После реализации:
|
||||
|
||||
- Coordinator больше не должен использовать внутренние Runtime-компоненты напрямую;
|
||||
- Runtime Layer имеет единственную официальную точку входа;
|
||||
- детали реализации Runtime полностью инкапсулированы;
|
||||
- дальнейшее развитие Runtime возможно без изменения внешнего контракта.
|
||||
|
||||
---
|
||||
|
||||
# Engineering Review
|
||||
|
||||
## Architecture Review
|
||||
|
||||
Passed.
|
||||
|
||||
Runtime Service реализует исключительно координацию компонентов Runtime и не нарушает архитектурные границы.
|
||||
|
||||
---
|
||||
|
||||
## Domain Review
|
||||
|
||||
Passed.
|
||||
|
||||
Runtime остаётся инфраструктурным слоем и не содержит аналитической либо торговой логики.
|
||||
|
||||
---
|
||||
|
||||
## Code Review
|
||||
|
||||
Passed.
|
||||
|
||||
Выявлено:
|
||||
|
||||
- отсутствует дублирование логики;
|
||||
- отсутствуют циклические зависимости;
|
||||
- соблюдён принцип единственной ответственности;
|
||||
- все существующие Runtime-компоненты используются повторно.
|
||||
|
||||
---
|
||||
|
||||
## Runtime Review
|
||||
|
||||
Passed.
|
||||
|
||||
Жизненный цикл Runtime полностью соответствует ранее утверждённому Runtime Protocol.
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
В рамках Build принято следующее архитектурное решение.
|
||||
|
||||
> Runtime Service является единственной публичной точкой входа Runtime Layer.
|
||||
|
||||
Внутренние компоненты Runtime (`Registry`, `Validation`, `Dependencies`, `Runner`) рассматриваются как детали реализации и не используются внешними слоями напрямую.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```text
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Итог
|
||||
|
||||
Build 015.8 завершил построение базового Runtime Layer.
|
||||
|
||||
После завершения Build Runtime включает:
|
||||
|
||||
- Runtime Protocol;
|
||||
- Runtime Registry;
|
||||
- Runtime Runner;
|
||||
- Runtime Dependencies;
|
||||
- Runtime Validation;
|
||||
- Runtime Service.
|
||||
|
||||
Runtime Layer готов к переходу к следующему этапу развития архитектуры — Coordinator Layer.
|
||||
@@ -0,0 +1,192 @@
|
||||
# Build 016.1 — Coordinator Models / CoordinatorResult
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 016.1 |
|
||||
| Название | Coordinator Models / CoordinatorResult |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Common / Coordinator Contract |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Добавить базовые модели результата Coordinator Layer.
|
||||
|
||||
Основной результат Build:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После утверждения архитектуры Coordinator Layer потребовался официальный выходной контракт Coordinator.
|
||||
|
||||
`CoordinatorResult` является межслойной моделью:
|
||||
|
||||
```text
|
||||
RuntimeResult
|
||||
↓
|
||||
Coordinator
|
||||
↓
|
||||
CoordinatorResult
|
||||
↓
|
||||
Trading Layer
|
||||
```
|
||||
|
||||
Поэтому модель размещена в Common Layer.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные модели
|
||||
|
||||
В файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/models.py
|
||||
```
|
||||
|
||||
добавлены:
|
||||
|
||||
```text
|
||||
CoordinatorDiagnostics
|
||||
CoordinatorEvaluationMeta
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- модели корректно размещены в Common Layer;
|
||||
- `CoordinatorResult` не является торговым решением;
|
||||
- `CoordinatorResult` не зависит от реализации Coordinator;
|
||||
- `RuntimeResult` остаётся входом Coordinator;
|
||||
- `EngineResult` и `RuntimeResult` не изменяются.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение добавить модели результата Coordinator в Common Layer, так как `CoordinatorResult` является межслойным контрактом между Coordinator Layer и будущим Trading Layer.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Добавлены модели:
|
||||
|
||||
```text
|
||||
CoordinatorDiagnostics
|
||||
CoordinatorEvaluationMeta
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
`CoordinatorResult` содержит:
|
||||
|
||||
- `runtime_result`;
|
||||
- `diagnostics`;
|
||||
- `meta`;
|
||||
- `payload`;
|
||||
- `status`;
|
||||
- `score`;
|
||||
- `confidence`;
|
||||
- `reason`;
|
||||
- `direction`;
|
||||
- `bias`;
|
||||
- `phase`;
|
||||
- `regime`;
|
||||
- `risk_level`.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `CoordinatorResult` является итоговой аналитической интерпретацией `RuntimeResult`;
|
||||
- модель не содержит торгового решения;
|
||||
- модель не содержит логики запуска Engine;
|
||||
- модель не содержит правил Coordinator;
|
||||
- будущий Trading Layer сможет использовать `CoordinatorResult` как контракт.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Замечаний, блокирующих Build, нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 016.2
|
||||
|
||||
Coordinator Protocol
|
||||
|
||||
coordinator/protocol.py
|
||||
```
|
||||
@@ -0,0 +1,189 @@
|
||||
# Build 016.2 — Coordinator Protocol
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 016.2 |
|
||||
| Название | Coordinator Protocol |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Coordinator |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать официальный публичный контракт Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После появления модели `CoordinatorResult` Coordinator Layer должен получить стабильный интерфейс взаимодействия.
|
||||
|
||||
Контракт Coordinator определяет единственную модель взаимодействия:
|
||||
|
||||
```text
|
||||
RuntimeResult
|
||||
↓
|
||||
Coordinator
|
||||
↓
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`CoordinatorProtocol` описывает только внешний интерфейс Coordinator.
|
||||
|
||||
Он не содержит:
|
||||
|
||||
- реализации;
|
||||
- правил согласования;
|
||||
- валидации;
|
||||
- исключений;
|
||||
- торговой логики;
|
||||
- зависимостей от конкретных Engine;
|
||||
- зависимостей от внутренних компонентов Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- Coordinator получает только `RuntimeResult`;
|
||||
- Coordinator возвращает только `CoordinatorResult`;
|
||||
- контракт не содержит реализации;
|
||||
- контракт не зависит от внутренних компонентов Runtime;
|
||||
- контракт не зависит от конкретных Engine;
|
||||
- контракт не содержит торговой логики.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение добавить официальный контракт:
|
||||
|
||||
```text
|
||||
CoordinatorProtocol
|
||||
```
|
||||
|
||||
Утверждённый метод:
|
||||
|
||||
```python
|
||||
async def coordinate(
|
||||
self,
|
||||
runtime_result: RuntimeResult,
|
||||
) -> CoordinatorResult:
|
||||
...
|
||||
```
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/coordinator/protocol.py
|
||||
```
|
||||
|
||||
Содержимое контракта:
|
||||
|
||||
```python
|
||||
class CoordinatorProtocol(Protocol):
|
||||
async def coordinate(
|
||||
self,
|
||||
runtime_result: RuntimeResult,
|
||||
) -> CoordinatorResult:
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Coordinator принимает исключительно `RuntimeResult`;
|
||||
- Coordinator возвращает исключительно `CoordinatorResult`;
|
||||
- протокол не содержит аналитической логики;
|
||||
- протокол не содержит торговой логики;
|
||||
- протокол не зависит от конкретных Engine;
|
||||
- протокол не зависит от реализации Runtime Layer.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 016.3
|
||||
|
||||
Coordinator Exceptions
|
||||
|
||||
coordinator/exceptions.py
|
||||
```
|
||||
@@ -0,0 +1,168 @@
|
||||
# Build 016.3 — Coordinator Exceptions
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 016.3 |
|
||||
| Название | Coordinator Exceptions |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Coordinator |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать единую иерархию исключений Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
Coordinator Layer является самостоятельным архитектурным уровнем.
|
||||
|
||||
Следовательно, он должен иметь собственное пространство ошибок и не использовать исключения Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Создана минимальная иерархия исключений:
|
||||
|
||||
```text
|
||||
CoordinatorError
|
||||
├── InvalidCoordinatorResultError
|
||||
├── CoordinatorValidationError
|
||||
└── CoordinatorExecutionError
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Coordinator Layer имеет собственную иерархию исключений;
|
||||
- исключения не зависят от Runtime Exceptions;
|
||||
- файл не содержит логики Coordinator;
|
||||
- файл не зависит от Engine;
|
||||
- дополнительные исключения не добавлены преждевременно.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение ввести собственное пространство ошибок Coordinator Layer.
|
||||
|
||||
Это обеспечивает:
|
||||
|
||||
- независимость Coordinator Layer;
|
||||
- явные границы между Runtime и Coordinator;
|
||||
- локальную обработку ошибок Coordinator;
|
||||
- возможность расширения без изменения Runtime.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/coordinator/exceptions.py
|
||||
```
|
||||
|
||||
Реализованы:
|
||||
|
||||
```text
|
||||
CoordinatorError
|
||||
InvalidCoordinatorResultError
|
||||
CoordinatorValidationError
|
||||
CoordinatorExecutionError
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- ошибки относятся исключительно к ответственности Coordinator;
|
||||
- исключения не пересекаются с Runtime Layer;
|
||||
- отсутствует торговая логика;
|
||||
- отсутствует аналитическая логика;
|
||||
- отсутствуют зависимости от Engine;
|
||||
- отсутствуют зависимости от Runtime internals.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 016.4
|
||||
|
||||
Coordinator Validation
|
||||
|
||||
coordinator/validation.py
|
||||
```
|
||||
@@ -0,0 +1,212 @@
|
||||
# Build 016.4 — Coordinator Validation
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 016.4 |
|
||||
| Название | Coordinator Validation |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Coordinator |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать компонент проверки входного `RuntimeResult` перед началом работы Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
Coordinator является следующим архитектурным уровнем после Runtime Layer.
|
||||
|
||||
Перед тем как Coordinator начнёт согласовывать результаты аналитических Engine, необходимо убедиться, что входной `RuntimeResult` корректен.
|
||||
|
||||
Validation выделяется в самостоятельный компонент, чтобы отделить проверку входных данных от правил согласования и логики Coordinator.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Создан компонент:
|
||||
|
||||
```text
|
||||
CoordinatorValidation
|
||||
```
|
||||
|
||||
с единственным публичным методом:
|
||||
|
||||
```python
|
||||
validate(
|
||||
runtime_result: RuntimeResult,
|
||||
) -> None
|
||||
```
|
||||
|
||||
Компонент выполняет только предварительную проверку входного результата Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Проверяемые условия
|
||||
|
||||
В Build реализованы следующие проверки:
|
||||
|
||||
- RuntimeResult передан;
|
||||
- RuntimeResult содержит результаты Engine;
|
||||
- RuntimeResult успешно завершён и не содержит критических ошибок Runtime.
|
||||
|
||||
Все остальные проверки будут реализованы в последующих Build Coordinator Rules.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Validation проверяет только входные данные;
|
||||
- Validation не изменяет `RuntimeResult`;
|
||||
- Validation не формирует `CoordinatorResult`;
|
||||
- Validation не содержит аналитической логики;
|
||||
- Validation не зависит от внутренних компонентов Runtime;
|
||||
- Validation использует только публичный контракт `RuntimeResult`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение выделить предварительную проверку входного `RuntimeResult` в отдельный компонент Coordinator Layer.
|
||||
|
||||
Validation выполняется до запуска правил согласования и обеспечивает корректность входных данных.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/coordinator/validation.py
|
||||
```
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
CoordinatorValidation
|
||||
```
|
||||
|
||||
Публичный метод:
|
||||
|
||||
```python
|
||||
validate(
|
||||
runtime_result: RuntimeResult,
|
||||
)
|
||||
```
|
||||
|
||||
Внутренние проверки:
|
||||
|
||||
```text
|
||||
_validate_runtime_result_exists()
|
||||
_validate_runtime_has_results()
|
||||
_validate_runtime_successful()
|
||||
```
|
||||
|
||||
При обнаружении ошибки используется исключение:
|
||||
|
||||
```text
|
||||
CoordinatorValidationError
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент проверяет только входной `RuntimeResult`;
|
||||
- компонент не изменяет `RuntimeResult`;
|
||||
- компонент не формирует `CoordinatorResult`;
|
||||
- компонент не согласует результаты Engine;
|
||||
- компонент не анализирует рынок;
|
||||
- компонент не принимает торговых решений;
|
||||
- компонент использует только публичные свойства `RuntimeResult`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент минимален и соответствует принципу Single Responsibility;
|
||||
- отсутствуют лишние зависимости;
|
||||
- отсутствует логика согласования результатов;
|
||||
- используется собственная иерархия исключений Coordinator Layer.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 016.5
|
||||
|
||||
Coordinator Rules
|
||||
|
||||
coordinator/rules.py
|
||||
```
|
||||
199
docs/market_intelligence/builds/build-016-5-coordinator-rules.md
Normal file
199
docs/market_intelligence/builds/build-016-5-coordinator-rules.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# Build 016.5 — Coordinator Rules
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 016.5 |
|
||||
| Название | Coordinator Rules |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Coordinator |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать компонент базового согласования результатов Engine.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После реализации `CoordinatorValidation` Coordinator Layer получил механизм проверки входного `RuntimeResult`.
|
||||
|
||||
Следующим шагом стал компонент, который преобразует:
|
||||
|
||||
```text
|
||||
RuntimeResult
|
||||
```
|
||||
|
||||
в:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Создан компонент:
|
||||
|
||||
```text
|
||||
CoordinatorRules
|
||||
```
|
||||
|
||||
Компонент отвечает за применение правил согласования результатов Engine.
|
||||
|
||||
В Build 016.5 реализован минимальный базовый каркас правил без сложных механизмов весов, конфликтов и голосования.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Rules не запускает Engine;
|
||||
- Rules не обращается к RuntimeService;
|
||||
- Rules не выполняет Validation;
|
||||
- Rules не зависит от CoordinatorService;
|
||||
- Rules не принимает торговых решений;
|
||||
- Rules работает только с `RuntimeResult` и формирует `CoordinatorResult`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение выделить правила согласования результатов Engine в отдельный компонент Coordinator Layer.
|
||||
|
||||
`CoordinatorRules` отвечает за формирование итогового `CoordinatorResult` из `RuntimeResult`.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/coordinator/rules.py
|
||||
```
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
CoordinatorRules
|
||||
```
|
||||
|
||||
Публичный метод:
|
||||
|
||||
```python
|
||||
coordinate(runtime_result)
|
||||
```
|
||||
|
||||
Внутренние методы:
|
||||
|
||||
```text
|
||||
_resolve_status()
|
||||
_resolve_score()
|
||||
_resolve_confidence()
|
||||
_resolve_direction()
|
||||
_resolve_bias()
|
||||
_resolve_phase()
|
||||
_resolve_regime()
|
||||
_resolve_risk_level()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент преобразует `RuntimeResult` в `CoordinatorResult`;
|
||||
- компонент не запускает Engine;
|
||||
- компонент не обращается к Runtime internals;
|
||||
- компонент не выполняет Validation;
|
||||
- компонент не принимает торговых решений;
|
||||
- компонент пока реализует только базовые правила согласования;
|
||||
- сложные механизмы весов, конфликтов и голосования не добавлены преждевременно.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент минимален;
|
||||
- публичный метод только один;
|
||||
- Validation не дублируется;
|
||||
- торговая логика отсутствует;
|
||||
- лишние зависимости отсутствуют;
|
||||
- сложные правила не добавлены преждевременно.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 016.6
|
||||
|
||||
Coordinator Service
|
||||
|
||||
coordinator/service.py
|
||||
```
|
||||
@@ -0,0 +1,252 @@
|
||||
# Build 016.6 — Coordinator Service
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 016.6 |
|
||||
| Название | Coordinator Service |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Layer | Coordinator |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать единую публичную точку входа Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После реализации компонентов:
|
||||
|
||||
- `CoordinatorProtocol`;
|
||||
- `CoordinatorValidation`;
|
||||
- `CoordinatorRules`;
|
||||
|
||||
Coordinator Layer получил все необходимые внутренние элементы, однако отсутствовал компонент, объединяющий их в единый рабочий процесс.
|
||||
|
||||
Эту роль выполняет `CoordinatorService`.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Создан компонент:
|
||||
|
||||
```text
|
||||
CoordinatorService
|
||||
```
|
||||
|
||||
Он реализует официальный контракт:
|
||||
|
||||
```text
|
||||
CoordinatorProtocol
|
||||
```
|
||||
|
||||
и обеспечивает последовательность выполнения:
|
||||
|
||||
```text
|
||||
RuntimeResult
|
||||
│
|
||||
▼
|
||||
CoordinatorValidation
|
||||
│
|
||||
▼
|
||||
CoordinatorRules
|
||||
│
|
||||
▼
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Service является единственной публичной точкой входа Coordinator Layer;
|
||||
- Service принимает только `RuntimeResult`;
|
||||
- Service возвращает только `CoordinatorResult`;
|
||||
- Service реализует `CoordinatorProtocol`;
|
||||
- Service делегирует проверку `CoordinatorValidation`;
|
||||
- Service делегирует согласование `CoordinatorRules`;
|
||||
- Service не содержит собственной бизнес-логики;
|
||||
- Service не зависит от внутренних компонентов Runtime Layer.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение объединить внутренние компоненты Coordinator Layer через единый сервис.
|
||||
|
||||
`CoordinatorService` становится единственной точкой взаимодействия внешних слоёв с Coordinator.
|
||||
|
||||
Все внутренние компоненты Coordinator инкапсулируются внутри Service.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/coordinator/service.py
|
||||
```
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
CoordinatorService
|
||||
```
|
||||
|
||||
Публичный метод:
|
||||
|
||||
```python
|
||||
coordinate(
|
||||
runtime_result: RuntimeResult,
|
||||
) -> CoordinatorResult
|
||||
```
|
||||
|
||||
Внутренние зависимости:
|
||||
|
||||
```text
|
||||
CoordinatorValidation
|
||||
CoordinatorRules
|
||||
```
|
||||
|
||||
Последовательность работы:
|
||||
|
||||
```text
|
||||
Validation
|
||||
↓
|
||||
Rules
|
||||
↓
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент является публичной точкой входа Coordinator Layer;
|
||||
- принимает только `RuntimeResult`;
|
||||
- возвращает только `CoordinatorResult`;
|
||||
- не содержит правил согласования;
|
||||
- не изменяет `RuntimeResult`;
|
||||
- не запускает Engine;
|
||||
- не принимает торговых решений;
|
||||
- не обращается к Runtime internals.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `CoordinatorService` реализует `CoordinatorProtocol`;
|
||||
- публичный метод только один;
|
||||
- Validation и Rules не дублируются;
|
||||
- отсутствуют лишние зависимости;
|
||||
- отсутствует торговая логика.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Итог Build
|
||||
|
||||
Build 016.6 завершает построение **Coordinator Foundation**.
|
||||
|
||||
Coordinator Layer полностью сформирован и включает:
|
||||
|
||||
```text
|
||||
Coordinator
|
||||
|
||||
├── models
|
||||
├── protocol
|
||||
├── exceptions
|
||||
├── validation
|
||||
├── rules
|
||||
└── service
|
||||
```
|
||||
|
||||
Теперь Coordinator Layer обладает:
|
||||
|
||||
- единым публичным API;
|
||||
- собственными моделями;
|
||||
- собственным пространством исключений;
|
||||
- механизмом предварительной проверки входных данных;
|
||||
- базовыми правилами согласования;
|
||||
- сервисом-оркестратором.
|
||||
|
||||
Архитектурный фундамент Coordinator завершён.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 017
|
||||
|
||||
Trading Layer Architecture
|
||||
```
|
||||
@@ -0,0 +1,363 @@
|
||||
# Build 016 — Coordinator Layer Architecture
|
||||
|
||||
**Статус:** ✅ Accepted
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Определить архитектуру нового слоя **Coordinator Layer**, отвечающего за объединение результатов аналитических Engine в единое представление состояния рынка.
|
||||
|
||||
Build не содержит реализации компонентов и фиксирует исключительно архитектурные решения, необходимые для дальнейшего развития платформы.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная задача
|
||||
|
||||
После завершения Runtime Layer платформа способна:
|
||||
|
||||
- зарегистрировать Engine;
|
||||
- проверить корректность Runtime;
|
||||
- определить порядок выполнения Engine;
|
||||
- выполнить все зарегистрированные Engine;
|
||||
- собрать результаты в единый `RuntimeResult`.
|
||||
|
||||
Однако `RuntimeResult` представляет собой лишь совокупность независимых результатов Engine.
|
||||
|
||||
Для получения единой аналитической картины рынка необходим отдельный архитектурный слой.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Coordinator Layer
|
||||
|
||||
Каждый Engine анализирует только собственную область ответственности.
|
||||
|
||||
Например:
|
||||
|
||||
```text
|
||||
Trend Engine
|
||||
↓
|
||||
UP
|
||||
|
||||
Structure Engine
|
||||
↓
|
||||
BULLISH
|
||||
|
||||
Wave Engine
|
||||
↓
|
||||
IMPULSE
|
||||
|
||||
Liquidity Engine
|
||||
↓
|
||||
LOW
|
||||
```
|
||||
|
||||
Каждый вывод корректен в рамках своего Engine.
|
||||
|
||||
Однако платформа должна получить единый ответ на вопрос:
|
||||
|
||||
> **Каково текущее состояние рынка с учётом всех аналитических компонентов одновременно?**
|
||||
|
||||
Эта ответственность не относится к Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Назначение Coordinator Layer
|
||||
|
||||
Coordinator Layer становится следующим архитектурным уровнем после Runtime Layer.
|
||||
|
||||
Он получает:
|
||||
|
||||
```text
|
||||
RuntimeResult
|
||||
```
|
||||
|
||||
и формирует:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
Coordinator отвечает исключительно за согласование результатов аналитических Engine.
|
||||
|
||||
---
|
||||
|
||||
# Ответственность Coordinator
|
||||
|
||||
Coordinator обязан:
|
||||
|
||||
- принимать `RuntimeResult`;
|
||||
- анализировать результаты всех Engine;
|
||||
- учитывать статус каждого Engine;
|
||||
- учитывать confidence каждого Engine;
|
||||
- выявлять подтверждения между Engine;
|
||||
- выявлять противоречия между Engine;
|
||||
- оценивать полноту аналитических данных;
|
||||
- формировать единый `CoordinatorResult`.
|
||||
|
||||
Coordinator не изменяет результаты Engine.
|
||||
|
||||
Coordinator не выполняет повторный анализ рынка.
|
||||
|
||||
---
|
||||
|
||||
# Что Coordinator не делает
|
||||
|
||||
Coordinator не должен:
|
||||
|
||||
- запускать Engine;
|
||||
- создавать Engine;
|
||||
- обращаться к Runtime Registry;
|
||||
- обращаться к Runtime Runner;
|
||||
- выполнять анализ рыночных данных;
|
||||
- рассчитывать технические индикаторы;
|
||||
- принимать торговые решения;
|
||||
- взаимодействовать с биржей;
|
||||
- взаимодействовать с Telegram;
|
||||
- работать с базой данных;
|
||||
- работать с AutoTrade.
|
||||
|
||||
Coordinator является исключительно аналитическим слоем согласования результатов.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурная схема
|
||||
|
||||
```text
|
||||
Market Data
|
||||
↓
|
||||
Engine
|
||||
↓
|
||||
Runtime
|
||||
↓
|
||||
RuntimeResult
|
||||
↓
|
||||
Coordinator
|
||||
↓
|
||||
CoordinatorResult
|
||||
↓
|
||||
Trading Layer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Границы Coordinator Layer
|
||||
|
||||
Coordinator располагается между Runtime Layer и будущим Trading Layer.
|
||||
|
||||
Runtime отвечает за выполнение Engine.
|
||||
|
||||
Coordinator отвечает за согласование результатов.
|
||||
|
||||
Trading Layer принимает решения на основании `CoordinatorResult`.
|
||||
|
||||
Таким образом каждый слой имеет собственную область ответственности.
|
||||
|
||||
---
|
||||
|
||||
# Предварительная структура Coordinator Layer
|
||||
|
||||
```text
|
||||
coordinator/
|
||||
|
||||
├── __init__.py
|
||||
├── models.py
|
||||
├── protocol.py
|
||||
├── exceptions.py
|
||||
├── validation.py
|
||||
├── rules.py
|
||||
└── service.py
|
||||
```
|
||||
|
||||
Каждый компонент имеет самостоятельную область ответственности.
|
||||
|
||||
---
|
||||
|
||||
# Предполагаемые компоненты
|
||||
|
||||
## models.py
|
||||
|
||||
Определяет модели Coordinator Layer.
|
||||
|
||||
Основной моделью станет:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
В дальнейшем могут появиться дополнительные модели диагностики и согласования.
|
||||
|
||||
---
|
||||
|
||||
## protocol.py
|
||||
|
||||
Определяет официальный публичный контракт Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
## exceptions.py
|
||||
|
||||
Содержит исключения Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
## validation.py
|
||||
|
||||
Проверяет корректность входного `RuntimeResult`.
|
||||
|
||||
---
|
||||
|
||||
## rules.py
|
||||
|
||||
Содержит правила согласования результатов Engine.
|
||||
|
||||
Именно данный компонент будет определять принципы объединения аналитических выводов.
|
||||
|
||||
---
|
||||
|
||||
## service.py
|
||||
|
||||
Является единственной публичной точкой входа Coordinator Layer.
|
||||
|
||||
Получает `RuntimeResult`.
|
||||
|
||||
Возвращает `CoordinatorResult`.
|
||||
|
||||
---
|
||||
|
||||
# Допустимые зависимости
|
||||
|
||||
Coordinator может использовать:
|
||||
|
||||
```text
|
||||
Common Layer
|
||||
↓
|
||||
RuntimeResult
|
||||
↓
|
||||
Coordinator Models
|
||||
```
|
||||
|
||||
Coordinator не должен зависеть от внутренних компонентов Runtime.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные принципы
|
||||
|
||||
При проектировании Coordinator подтверждены следующие инженерные принципы.
|
||||
|
||||
## Single Responsibility
|
||||
|
||||
Coordinator отвечает исключительно за согласование результатов Engine.
|
||||
|
||||
---
|
||||
|
||||
## Stable Foundation
|
||||
|
||||
Coordinator строится поверх полностью завершённого Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
## One Source of Truth
|
||||
|
||||
Единым результатом работы Coordinator становится `CoordinatorResult`.
|
||||
|
||||
---
|
||||
|
||||
## Architecture First
|
||||
|
||||
Сначала утверждается архитектура слоя.
|
||||
|
||||
Только после этого начинается реализация его компонентов.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Во время архитектурной проверки подтверждено:
|
||||
|
||||
- Runtime и Coordinator имеют различные области ответственности;
|
||||
- отсутствует пересечение обязанностей;
|
||||
- Runtime остаётся инфраструктурным слоем;
|
||||
- Coordinator становится аналитическим слоем согласования;
|
||||
- Trading Layer не зависит от внутренних компонентов Runtime.
|
||||
|
||||
Architecture Review завершён успешно.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Decision Record (ADR)
|
||||
|
||||
Принято следующее долгосрочное архитектурное решение.
|
||||
|
||||
> Coordinator Layer вводится как самостоятельный архитектурный слой между Runtime Layer и Trading Layer.
|
||||
|
||||
Coordinator становится единственным компонентом платформы, ответственным за объединение результатов аналитических Engine.
|
||||
|
||||
---
|
||||
|
||||
# План реализации Build 016.x
|
||||
|
||||
Разработка Coordinator Layer утверждена в следующей последовательности.
|
||||
|
||||
```text
|
||||
016.1
|
||||
Coordinator Models
|
||||
|
||||
↓
|
||||
|
||||
016.2
|
||||
Coordinator Protocol
|
||||
|
||||
↓
|
||||
|
||||
016.3
|
||||
Coordinator Exceptions
|
||||
|
||||
↓
|
||||
|
||||
016.4
|
||||
Coordinator Validation
|
||||
|
||||
↓
|
||||
|
||||
016.5
|
||||
Coordinator Rules
|
||||
|
||||
↓
|
||||
|
||||
016.6
|
||||
Coordinator Service
|
||||
```
|
||||
|
||||
Такая последовательность повторяет архитектурный подход, ранее использованный при построении Runtime Layer.
|
||||
|
||||
---
|
||||
|
||||
# Итог
|
||||
|
||||
Build 016 завершает проектирование нового архитектурного слоя платформы.
|
||||
|
||||
В результате утверждены:
|
||||
|
||||
- назначение Coordinator Layer;
|
||||
- область ответственности;
|
||||
- архитектурные границы;
|
||||
- место слоя в общей архитектуре;
|
||||
- структура компонентов;
|
||||
- последовательность дальнейшей реализации.
|
||||
|
||||
После завершения Build архитектура платформы принимает следующий вид.
|
||||
|
||||
```text
|
||||
Common Layer
|
||||
↓
|
||||
Engine Layer
|
||||
↓
|
||||
Runtime Layer
|
||||
↓
|
||||
Coordinator Layer
|
||||
↓
|
||||
Trading Layer
|
||||
```
|
||||
|
||||
Coordinator Layer официально включён в архитектуру подсистемы **Market Intelligence** и готов к реализации в серии Build **016.x**.
|
||||
187
docs/market_intelligence/builds/build-017-1-trading-models.md
Normal file
187
docs/market_intelligence/builds/build-017-1-trading-models.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Build 017.1 — Trading Models / TradingDecision
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 017.1 |
|
||||
| Название | Trading Models / TradingDecision |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Trading |
|
||||
| Layer | Common / Trading Contract |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Добавить базовые модели Trading Layer.
|
||||
|
||||
Основной результат Build:
|
||||
|
||||
```text
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После утверждения архитектуры Trading Layer потребовался официальный выходной контракт слоя.
|
||||
|
||||
`TradingDecision` является межслойной моделью:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
↓
|
||||
Trading Layer
|
||||
↓
|
||||
TradingDecision
|
||||
↓
|
||||
Execution / Risk / Portfolio
|
||||
```
|
||||
|
||||
Поэтому модель размещена в Common Layer.
|
||||
|
||||
---
|
||||
|
||||
# Реализованные модели
|
||||
|
||||
В файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/models.py
|
||||
```
|
||||
|
||||
добавлены:
|
||||
|
||||
```text
|
||||
TradingDiagnostics
|
||||
TradingEvaluationMeta
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Проверка подтвердила:
|
||||
|
||||
- модели корректно размещены в Common Layer;
|
||||
- `TradingDecision` является результатом Trading Layer;
|
||||
- `TradingDecision` не является ордером;
|
||||
- `TradingDecision` не исполняет сделку;
|
||||
- `TradingDecision` не управляет позицией;
|
||||
- модель не зависит от Execution / Risk / Portfolio слоёв.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение добавить модели Trading Layer в Common Layer, так как `TradingDecision` является межслойным контрактом между Trading Layer и будущими слоями Execution / Risk / Portfolio.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Добавлены модели:
|
||||
|
||||
```text
|
||||
TradingDiagnostics
|
||||
TradingEvaluationMeta
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
`TradingDecision` содержит:
|
||||
|
||||
- `coordinator_result`;
|
||||
- `diagnostics`;
|
||||
- `meta`;
|
||||
- `payload`;
|
||||
- `status`;
|
||||
- `score`;
|
||||
- `confidence`;
|
||||
- `reason`.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `TradingDecision` использует `CoordinatorResult` как входной аналитический контракт;
|
||||
- модель не является ордером;
|
||||
- модель не исполняет сделку;
|
||||
- модель не содержит биржевой логики;
|
||||
- модель не управляет позицией;
|
||||
- модель не содержит Risk Plan / Entry Plan / Exit Plan.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Замечаний, блокирующих Build, нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 017.2
|
||||
|
||||
Trading Protocol
|
||||
```
|
||||
191
docs/market_intelligence/builds/build-017-2-trading-protocol.md
Normal file
191
docs/market_intelligence/builds/build-017-2-trading-protocol.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# Build 017.2 — Trading Protocol
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 017.2 |
|
||||
| Название | Trading Protocol |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Trading |
|
||||
| Layer | Trading |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать официальный публичный контракт Trading Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После появления модели `TradingDecision` Trading Layer должен получить стабильный интерфейс взаимодействия.
|
||||
|
||||
Контракт Trading определяет единственную модель взаимодействия:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
↓
|
||||
Trading
|
||||
↓
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
`TradingProtocol` описывает только внешний интерфейс Trading Layer.
|
||||
|
||||
Он не содержит:
|
||||
|
||||
- реализации;
|
||||
- Validation;
|
||||
- Rules;
|
||||
- Execution;
|
||||
- Risk;
|
||||
- Portfolio;
|
||||
- биржевой логики;
|
||||
- логики исполнения сделок.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- вход — только `CoordinatorResult`;
|
||||
- выход — только `TradingDecision`;
|
||||
- контракт не содержит реализации;
|
||||
- контракт не зависит от Runtime;
|
||||
- контракт не зависит от Coordinator internals;
|
||||
- контракт не работает с биржей;
|
||||
- контракт не исполняет сделки.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение добавить официальный контракт:
|
||||
|
||||
```text
|
||||
TradingProtocol
|
||||
```
|
||||
|
||||
Утверждённый метод:
|
||||
|
||||
```python
|
||||
async def decide(
|
||||
coordinator_result: CoordinatorResult,
|
||||
) -> TradingDecision:
|
||||
...
|
||||
```
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/trading/protocol.py
|
||||
```
|
||||
|
||||
Содержимое контракта:
|
||||
|
||||
```python
|
||||
class TradingProtocol(Protocol):
|
||||
async def decide(
|
||||
self,
|
||||
coordinator_result: CoordinatorResult,
|
||||
) -> TradingDecision:
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Trading принимает только `CoordinatorResult`;
|
||||
- Trading возвращает только `TradingDecision`;
|
||||
- протокол не содержит реализации;
|
||||
- протокол не содержит торговых правил;
|
||||
- протокол не содержит логики исполнения сделок;
|
||||
- протокол не зависит от Runtime;
|
||||
- протокол не зависит от Coordinator internals.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 017.3
|
||||
|
||||
Trading Exceptions
|
||||
|
||||
trading/exceptions.py
|
||||
```
|
||||
@@ -0,0 +1,180 @@
|
||||
# Build 017.3 — Trading Exceptions
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 017.3 |
|
||||
| Название | Trading Exceptions |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Trading |
|
||||
| Layer | Trading |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать собственную иерархию исключений Trading Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После утверждения архитектуры Trading Layer, моделей и публичного контракта необходимо сформировать собственное пространство ошибок.
|
||||
|
||||
Каждый архитектурный слой платформы Dzentra использует собственную иерархию исключений, что обеспечивает слабую связанность между слоями и независимую обработку ошибок.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Trading Layer получает собственую иерархию исключений:
|
||||
|
||||
```text
|
||||
TradingError
|
||||
├── InvalidTradingDecisionError
|
||||
├── TradingValidationError
|
||||
└── TradingExecutionError
|
||||
```
|
||||
|
||||
Иерархия полностью независима от Runtime Layer и Coordinator Layer.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Trading Layer имеет собственное пространство ошибок;
|
||||
- исключения не зависят от Coordinator;
|
||||
- исключения не зависят от Runtime;
|
||||
- файл не содержит Validation;
|
||||
- файл не содержит Rules;
|
||||
- файл не содержит Service;
|
||||
- специализированные исключения преждевременно не добавляются.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение выделить собственную иерархию исключений Trading Layer.
|
||||
|
||||
Trading не использует ошибки других слоёв платформы.
|
||||
|
||||
Будущие компоненты Validation, Rules и Service будут использовать исключительно `TradingError` и его наследников.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/trading/exceptions.py
|
||||
```
|
||||
|
||||
Реализованы исключения:
|
||||
|
||||
```text
|
||||
TradingError
|
||||
InvalidTradingDecisionError
|
||||
TradingValidationError
|
||||
TradingExecutionError
|
||||
```
|
||||
|
||||
Иерархия соответствует архитектурному стандарту платформы.
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- ошибки относятся только к Trading Layer;
|
||||
- исключения не пересекаются с Coordinator / Runtime / Engine;
|
||||
- файл не содержит Validation;
|
||||
- файл не содержит Rules;
|
||||
- файл не содержит Service;
|
||||
- торговая логика отсутствует;
|
||||
- специализированные ошибки Risk / Position / Entry / Exit не добавлены преждевременно.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `TradingError` является базовым исключением Trading Layer;
|
||||
- все специализированные исключения наследуются только от `TradingError`;
|
||||
- файл не импортирует другие архитектурные слои;
|
||||
- отсутствуют лишние зависимости;
|
||||
- структура полностью соответствует архитектурному стандарту Dzentra.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 017.4
|
||||
|
||||
Trading Validation
|
||||
|
||||
trading/validation.py
|
||||
```
|
||||
@@ -0,0 +1,224 @@
|
||||
# Build 017.4 — Trading Validation
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 017.4 |
|
||||
| Название | Trading Validation |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Trading |
|
||||
| Layer | Trading |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать компонент предварительной проверки входного `CoordinatorResult` перед началом работы Trading Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
Trading Layer принимает торговое решение только на основании результата Coordinator Layer.
|
||||
|
||||
Перед применением торговых правил необходимо убедиться, что входной аналитический результат корректен и пригоден для дальнейшего использования.
|
||||
|
||||
Для этого вводится отдельный компонент:
|
||||
|
||||
```text
|
||||
TradingValidation
|
||||
```
|
||||
|
||||
Он отделяет проверку входных данных от бизнес-логики принятия решений.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
TradingValidation является первым этапом жизненного цикла Trading Layer:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
│
|
||||
▼
|
||||
TradingValidation
|
||||
│
|
||||
▼
|
||||
TradingRules
|
||||
│
|
||||
▼
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
Validation выполняет исключительно проверку входного контракта и не содержит торговых правил.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент принимает только `CoordinatorResult`;
|
||||
- компонент не изменяет `CoordinatorResult`;
|
||||
- компонент не формирует `TradingDecision`;
|
||||
- компонент не содержит Trading Rules;
|
||||
- компонент не взаимодействует с Runtime, Coordinator internals, биржей или внешними сервисами;
|
||||
- используются только публичные свойства `CoordinatorResult`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение выделить проверку входного результата в самостоятельный компонент.
|
||||
|
||||
Trading Layer использует исключительно публичный API `CoordinatorResult`:
|
||||
|
||||
- `is_usable`;
|
||||
- `has_errors`.
|
||||
|
||||
Trading Layer не анализирует внутренние статусы Coordinator и не зависит от его реализации.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/trading/validation.py
|
||||
```
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
TradingValidation
|
||||
```
|
||||
|
||||
Публичный метод:
|
||||
|
||||
```python
|
||||
validate(
|
||||
coordinator_result: CoordinatorResult,
|
||||
) -> None
|
||||
```
|
||||
|
||||
Выполняемые проверки:
|
||||
|
||||
1. Передан ли `CoordinatorResult`;
|
||||
2. Пригоден ли результат (`is_usable`);
|
||||
3. Отсутствуют ли критические ошибки (`has_errors`).
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент проверяет только входной `CoordinatorResult`;
|
||||
- компонент не изменяет входные данные;
|
||||
- компонент не содержит Trading Rules;
|
||||
- компонент не принимает торговых решений;
|
||||
- компонент использует только публичные свойства `CoordinatorResult`;
|
||||
- отсутствуют зависимости от Runtime, Coordinator internals и других слоёв.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- единственный публичный метод — `validate()`;
|
||||
- используется специализированное исключение `TradingValidationError`;
|
||||
- проверки разделены на приватные методы;
|
||||
- отсутствует бизнес-логика;
|
||||
- отсутствуют лишние зависимости.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Development Strategy
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Итог Build
|
||||
|
||||
Build 017.4 завершил создание компонента предварительной проверки Trading Layer.
|
||||
|
||||
Теперь фундамент Trading содержит:
|
||||
|
||||
```text
|
||||
Trading Foundation
|
||||
|
||||
├── Models
|
||||
├── Protocol
|
||||
├── Exceptions
|
||||
└── Validation
|
||||
```
|
||||
|
||||
Trading Layer получил собственный механизм проверки входного аналитического контракта без нарушения архитектурной изоляции между слоями.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 017.5
|
||||
|
||||
Trading Rules
|
||||
|
||||
trading/rules.py
|
||||
```
|
||||
194
docs/market_intelligence/builds/build-017-5-trading-rules.md
Normal file
194
docs/market_intelligence/builds/build-017-5-trading-rules.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# Build 017.5 — Trading Rules
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 017.5 |
|
||||
| Название | Trading Rules |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Trading |
|
||||
| Layer | Trading |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать компонент базового формирования `TradingDecision` из `CoordinatorResult`.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После реализации `TradingValidation` Trading Layer получил механизм проверки входного `CoordinatorResult`.
|
||||
|
||||
Следующим шагом стал компонент, который преобразует:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
```
|
||||
|
||||
в:
|
||||
|
||||
```text
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Создан компонент:
|
||||
|
||||
```text
|
||||
TradingRules
|
||||
```
|
||||
|
||||
В Build 017.5 реализован базовый каркас правил без BUY / SELL / HOLD / EXIT логики.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Rules не выполняет Validation;
|
||||
- Rules не обращается к Runtime;
|
||||
- Rules не обращается к Coordinator internals;
|
||||
- Rules не работает с биржей;
|
||||
- Rules не исполняет сделки;
|
||||
- Rules не управляет позицией;
|
||||
- Rules формирует только базовый `TradingDecision`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение выделить правила формирования торгового решения в отдельный компонент Trading Layer.
|
||||
|
||||
`TradingRules` отвечает за формирование `TradingDecision` из `CoordinatorResult`.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/trading/rules.py
|
||||
```
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
TradingRules
|
||||
```
|
||||
|
||||
Публичный метод:
|
||||
|
||||
```python
|
||||
decide(coordinator_result)
|
||||
```
|
||||
|
||||
Внутренние методы:
|
||||
|
||||
```text
|
||||
_resolve_status()
|
||||
_resolve_score()
|
||||
_resolve_confidence()
|
||||
_resolve_reason()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент преобразует `CoordinatorResult` в `TradingDecision`;
|
||||
- компонент не выполняет Validation;
|
||||
- компонент не обращается к Runtime;
|
||||
- компонент не обращается к Coordinator internals;
|
||||
- компонент не исполняет сделки;
|
||||
- компонент не управляет позициями;
|
||||
- компонент не содержит BUY / SELL / HOLD / EXIT логики;
|
||||
- компонент формирует только базовый каркас `TradingDecision`.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент минимален;
|
||||
- публичный метод только один;
|
||||
- Validation не дублируется;
|
||||
- торговая логика не добавлена преждевременно;
|
||||
- лишние зависимости отсутствуют.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 017.6
|
||||
|
||||
Trading Service
|
||||
|
||||
trading/service.py
|
||||
```
|
||||
253
docs/market_intelligence/builds/build-017-6-trading-service.md
Normal file
253
docs/market_intelligence/builds/build-017-6-trading-service.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Build 017.6 — Trading Service
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 017.6 |
|
||||
| Название | Trading Service |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Trading |
|
||||
| Layer | Trading |
|
||||
| Тип | Architecture + Implementation |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Создать единую публичную точку входа Trading Layer.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
После реализации компонентов:
|
||||
|
||||
- `TradingProtocol`;
|
||||
- `TradingValidation`;
|
||||
- `TradingRules`;
|
||||
|
||||
Trading Layer получил все необходимые внутренние элементы, однако отсутствовал компонент, объединяющий их в единый рабочий процесс.
|
||||
|
||||
Эту роль выполняет `TradingService`.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Создан компонент:
|
||||
|
||||
```text
|
||||
TradingService
|
||||
```
|
||||
|
||||
Он реализует официальный контракт:
|
||||
|
||||
```text
|
||||
TradingProtocol
|
||||
```
|
||||
|
||||
и обеспечивает последовательность выполнения:
|
||||
|
||||
```text
|
||||
CoordinatorResult
|
||||
│
|
||||
▼
|
||||
TradingValidation
|
||||
│
|
||||
▼
|
||||
TradingRules
|
||||
│
|
||||
▼
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- Service является единственной публичной точкой входа Trading Layer;
|
||||
- Service принимает только `CoordinatorResult`;
|
||||
- Service возвращает только `TradingDecision`;
|
||||
- Service реализует `TradingProtocol`;
|
||||
- Service делегирует проверку `TradingValidation`;
|
||||
- Service делегирует формирование решения `TradingRules`;
|
||||
- Service не содержит собственной торговой логики;
|
||||
- Service не зависит от внутренних компонентов Runtime или Coordinator.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение объединить внутренние компоненты Trading Layer через единый сервис.
|
||||
|
||||
`TradingService` становится единственной точкой взаимодействия внешних слоёв с Trading Layer.
|
||||
|
||||
Все внутренние компоненты Trading инкапсулируются внутри Service.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/trading/service.py
|
||||
```
|
||||
|
||||
Реализован класс:
|
||||
|
||||
```text
|
||||
TradingService
|
||||
```
|
||||
|
||||
Публичный метод:
|
||||
|
||||
```python
|
||||
decide(
|
||||
coordinator_result: CoordinatorResult,
|
||||
) -> TradingDecision
|
||||
```
|
||||
|
||||
Внутренние зависимости:
|
||||
|
||||
```text
|
||||
TradingValidation
|
||||
TradingRules
|
||||
```
|
||||
|
||||
Последовательность работы:
|
||||
|
||||
```text
|
||||
Validation
|
||||
↓
|
||||
Rules
|
||||
↓
|
||||
TradingDecision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- компонент является публичной точкой входа Trading Layer;
|
||||
- принимает только `CoordinatorResult`;
|
||||
- возвращает только `TradingDecision`;
|
||||
- не содержит торговых правил;
|
||||
- не изменяет `CoordinatorResult`;
|
||||
- не обращается к Runtime / Coordinator internals;
|
||||
- не работает с биржей;
|
||||
- не исполняет сделки.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `TradingService` реализует `TradingProtocol`;
|
||||
- публичный метод только один;
|
||||
- Validation и Rules не дублируются;
|
||||
- отсутствуют лишние зависимости;
|
||||
- отсутствует торговая логика.
|
||||
|
||||
Замечаний нет.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Development Strategy
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Итог Build
|
||||
|
||||
Build 017.6 завершает построение **Trading Foundation**.
|
||||
|
||||
Trading Layer полностью сформирован и включает:
|
||||
|
||||
```text
|
||||
Trading
|
||||
|
||||
├── models
|
||||
├── protocol
|
||||
├── exceptions
|
||||
├── validation
|
||||
├── rules
|
||||
└── service
|
||||
```
|
||||
|
||||
Теперь Trading Layer обладает:
|
||||
|
||||
- единым публичным API;
|
||||
- собственными моделями;
|
||||
- собственным пространством исключений;
|
||||
- механизмом предварительной проверки входных данных;
|
||||
- базовыми правилами формирования торгового решения;
|
||||
- сервисом-оркестратором.
|
||||
|
||||
Архитектурный фундамент Trading завершён.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 018
|
||||
|
||||
Execution Layer Architecture
|
||||
```
|
||||
@@ -0,0 +1,230 @@
|
||||
# Build 017.7 — Trading Boundary Correction
|
||||
|
||||
**Engineering Build Document**
|
||||
|
||||
---
|
||||
|
||||
# Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|-----------|
|
||||
| Build | 017.7 |
|
||||
| Название | Trading Boundary Correction |
|
||||
| Статус | **Accepted** |
|
||||
| Подсистема | Trading / Market Intelligence |
|
||||
| Тип | Architecture Refactoring |
|
||||
| Версия | 1.0 |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Цель Build
|
||||
|
||||
Исправить архитектурную границу между **Market Intelligence** и **Trading Decision**.
|
||||
|
||||
---
|
||||
|
||||
# Причина появления Build
|
||||
|
||||
В ходе подготовки к Build 018 было обнаружено, что Trading Foundation был размещён внутри:
|
||||
|
||||
```text
|
||||
src/trading/market_intelligence/trading/
|
||||
```
|
||||
|
||||
Это нарушало границу ответственности, поскольку `market_intelligence` должен содержать только компоненты анализа рынка.
|
||||
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Trading Foundation перенесён в самостоятельный слой:
|
||||
|
||||
```text
|
||||
src/trading/decision/
|
||||
```
|
||||
|
||||
Целевая структура:
|
||||
|
||||
```text
|
||||
src/trading/decision/
|
||||
├── __init__.py
|
||||
├── models.py
|
||||
├── protocol.py
|
||||
├── exceptions.py
|
||||
├── validation.py
|
||||
├── rules.py
|
||||
└── service.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `market_intelligence` содержит только компоненты анализа рынка;
|
||||
- `TradingDecision` больше не находится в `market_intelligence/common/models.py`;
|
||||
- Trading Decision вынесен в самостоятельный слой `src/trading/decision`;
|
||||
- существующий `src/trading/execution/` не затронут;
|
||||
- дублирования Execution Layer не создано.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# ADR
|
||||
|
||||
Принято решение перенести Trading Foundation из `market_intelligence` в самостоятельный слой `decision`.
|
||||
|
||||
`market_intelligence/common/models.py` должен содержать только модели Market Intelligence:
|
||||
|
||||
```text
|
||||
Engine*
|
||||
Runtime*
|
||||
Coordinator*
|
||||
```
|
||||
|
||||
Trading Decision использует `CoordinatorResult`, но не является частью Market Intelligence.
|
||||
|
||||
**Статус:** Accepted
|
||||
|
||||
---
|
||||
|
||||
# Implementation
|
||||
|
||||
Создан каталог:
|
||||
|
||||
```text
|
||||
app/src/trading/decision/
|
||||
```
|
||||
|
||||
Создан файл:
|
||||
|
||||
```text
|
||||
app/src/trading/decision/models.py
|
||||
```
|
||||
|
||||
Перенесены файлы:
|
||||
|
||||
```text
|
||||
protocol.py
|
||||
exceptions.py
|
||||
validation.py
|
||||
rules.py
|
||||
service.py
|
||||
```
|
||||
|
||||
Удалены модели Trading из:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/common/models.py
|
||||
```
|
||||
|
||||
Удалён старый каталог:
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/trading/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Compile Check
|
||||
|
||||
Проверены оба контура:
|
||||
|
||||
```bash
|
||||
python -m compileall src/trading/market_intelligence
|
||||
python -m compileall src/trading/decision
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
```text
|
||||
Passed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Domain Review
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- `market_intelligence` снова содержит только Market Intelligence компоненты;
|
||||
- Trading Decision вынесен в самостоятельный слой;
|
||||
- `decision` корректно использует `CoordinatorResult` как входной контракт;
|
||||
- существующая подсистема `execution` не затронута;
|
||||
- дублирования Execution Layer не создано.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Проверка пройдена.
|
||||
|
||||
Подтверждено:
|
||||
|
||||
- новые импорты используют `src.trading.decision`;
|
||||
- старых импортов из `src.trading.market_intelligence.trading` не обнаружено;
|
||||
- `TradingDecision` находится в `decision/models.py`;
|
||||
- `market_intelligence/common/models.py` очищен от Trading-моделей;
|
||||
- архитектурная граница восстановлена.
|
||||
|
||||
**Статус:** ✅ Passed
|
||||
|
||||
---
|
||||
|
||||
# Acceptance
|
||||
|
||||
Build завершён.
|
||||
|
||||
Выполнены:
|
||||
|
||||
- ✅ Development Strategy
|
||||
- ✅ Architecture Design
|
||||
- ✅ Architecture Review
|
||||
- ✅ ADR
|
||||
- ✅ Build Design
|
||||
- ✅ Implementation
|
||||
- ✅ Compile Check
|
||||
- ✅ Domain Review
|
||||
- ✅ Code Review
|
||||
- ✅ Documentation
|
||||
|
||||
Статус Build:
|
||||
|
||||
```text
|
||||
Accepted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Итог Build
|
||||
|
||||
Build 017.7 восстановил правильную архитектурную границу:
|
||||
|
||||
```text
|
||||
Market Intelligence
|
||||
↓
|
||||
CoordinatorResult
|
||||
↓
|
||||
Decision Layer
|
||||
↓
|
||||
TradingDecision
|
||||
↓
|
||||
Execution
|
||||
```
|
||||
|
||||
Теперь `market_intelligence` отвечает только за аналитику рынка, а `decision` отвечает за формирование торгового решения.
|
||||
|
||||
---
|
||||
|
||||
# Следующий Build
|
||||
|
||||
```text
|
||||
Build 018
|
||||
|
||||
Execution Layer Architecture
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
0
docs/market_intelligence/common/README.md
Normal file
0
docs/market_intelligence/common/README.md
Normal file
130
docs/market_intelligence/decisions/README.md
Normal file
130
docs/market_intelligence/decisions/README.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Architecture Decisions
|
||||
|
||||
Каталог **decisions/** содержит архитектурные решения (ADR — Architecture Decision Record), принятые во время разработки подсистемы **Market Intelligence**.
|
||||
|
||||
В отличие от технической документации, ADR отвечают не на вопрос:
|
||||
|
||||
> **Что реализовано?**
|
||||
|
||||
а на вопрос:
|
||||
|
||||
> **Почему архитектура построена именно так?**
|
||||
|
||||
Каждое решение принимается только после возникновения реальной инженерной необходимости.
|
||||
|
||||
Создание ADR "на будущее" не допускается.
|
||||
|
||||
---
|
||||
|
||||
# Иерархия архитектурных решений
|
||||
|
||||
Архитектурные решения разделены на три уровня.
|
||||
|
||||
```text
|
||||
Философия разработки
|
||||
↓
|
||||
Правила разработки
|
||||
↓
|
||||
Архитектурные ограничения
|
||||
```
|
||||
|
||||
Каждый следующий уровень основывается на предыдущем.
|
||||
|
||||
---
|
||||
|
||||
# Level 1 — Философия разработки
|
||||
|
||||
Данные решения определяют общий подход к развитию платформы.
|
||||
|
||||
| Decision | Назначение |
|
||||
|----------|------------|
|
||||
| 001 | Architecture First |
|
||||
| 002 | Build Lifecycle |
|
||||
|
||||
---
|
||||
|
||||
## Основная идея
|
||||
|
||||
Сначала проектируется архитектура.
|
||||
|
||||
Затем архитектура развивается небольшими завершёнными Build.
|
||||
|
||||
---
|
||||
|
||||
# Level 2 — Правила разработки
|
||||
|
||||
Данные решения определяют инженерный процесс разработки.
|
||||
|
||||
| Decision | Назначение |
|
||||
|----------|------------|
|
||||
| 003 | Domain Review |
|
||||
| 004 | No Existing Code Assumptions |
|
||||
| 005 | Human Readable Comments |
|
||||
| 007 | Documentation Is Code |
|
||||
|
||||
---
|
||||
|
||||
## Основная идея
|
||||
|
||||
Каждый Build проходит обязательные проверки качества.
|
||||
|
||||
Разработка ведётся только на основе существующего кода проекта.
|
||||
|
||||
Комментарии объясняют архитектурный смысл.
|
||||
|
||||
Документация развивается одновременно с кодом.
|
||||
|
||||
---
|
||||
|
||||
# Level 3 — Архитектурные ограничения
|
||||
|
||||
Данные решения определяют фундаментальные ограничения архитектуры платформы.
|
||||
|
||||
| Decision | Назначение |
|
||||
|----------|------------|
|
||||
| 006 | Immutable Engine Contract |
|
||||
|
||||
---
|
||||
|
||||
## Основная идея
|
||||
|
||||
Все аналитические движки используют единый неизменяемый контракт результатов.
|
||||
|
||||
---
|
||||
|
||||
# Правила создания новых Decision
|
||||
|
||||
Новый ADR создаётся только при выполнении следующих условий:
|
||||
|
||||
- возникла реальная инженерная проблема;
|
||||
- принято архитектурное решение, влияющее на развитие платформы;
|
||||
- решение невозможно корректно описать только комментариями в коде;
|
||||
- решение будет полезно при дальнейшем сопровождении проекта.
|
||||
|
||||
Создание ADR "на всякий случай" запрещается.
|
||||
|
||||
---
|
||||
|
||||
# Жизненный цикл ADR
|
||||
|
||||
Каждый Architecture Decision проходит одинаковый цикл.
|
||||
|
||||
```text
|
||||
Проблема
|
||||
↓
|
||||
Анализ вариантов
|
||||
↓
|
||||
Принятие решения
|
||||
↓
|
||||
Документирование
|
||||
↓
|
||||
Использование в проекте
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Главный принцип
|
||||
|
||||
Architecture Decision Record являются частью архитектуры Dzentra.
|
||||
|
||||
Они сохраняют инженерные знания проекта и позволяют развивать платформу последовательно даже спустя годы после принятия первоначальных решений.
|
||||
@@ -0,0 +1,157 @@
|
||||
# Decision 001 — Architecture First
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Дата принятия
|
||||
|
||||
Принято во время начала проектирования Stage-08.2 **Engine Runtime Contract**.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
Проект Dzentra развивается как долгосрочная автономная торговая платформа.
|
||||
|
||||
На ранних этапах развития стало очевидно, что традиционный подход:
|
||||
|
||||
```text
|
||||
Идея
|
||||
↓
|
||||
Написание кода
|
||||
↓
|
||||
Попытка встроить код в архитектуру
|
||||
```
|
||||
|
||||
со временем приводит к накоплению технического долга, усложнению зависимостей и постепенной деградации структуры проекта.
|
||||
|
||||
Для платформы, которая должна развиваться на протяжении многих лет, такой подход признан неприемлемым.
|
||||
|
||||
---
|
||||
|
||||
# Проблема
|
||||
|
||||
При разработке без предварительного архитектурного проектирования обычно возникают следующие последствия:
|
||||
|
||||
- смешивание зон ответственности компонентов;
|
||||
- появление временных решений, остающихся в проекте навсегда;
|
||||
- дублирование логики;
|
||||
- циклические зависимости;
|
||||
- усложнение сопровождения;
|
||||
- постоянный рефакторинг уже написанного кода.
|
||||
|
||||
Каждое новое изменение становится дороже предыдущего.
|
||||
|
||||
---
|
||||
|
||||
# Рассмотренные варианты
|
||||
|
||||
## Вариант 1
|
||||
|
||||
Сначала писать код, затем при необходимости выполнять рефакторинг.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- быстрый старт реализации;
|
||||
- минимальные затраты на начальном этапе.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- рост технического долга;
|
||||
- потеря целостности архитектуры;
|
||||
- постоянные изменения уже работающего кода;
|
||||
- усложнение тестирования;
|
||||
- снижение предсказуемости развития проекта.
|
||||
|
||||
---
|
||||
|
||||
## Вариант 2
|
||||
|
||||
Сначала проектировать архитектуру, затем реализовывать код.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- понятные зоны ответственности;
|
||||
- отсутствие случайных зависимостей;
|
||||
- возможность масштабирования;
|
||||
- предсказуемое развитие платформы;
|
||||
- уменьшение объёма последующего рефакторинга;
|
||||
- единый стиль разработки.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- увеличение времени подготовки перед реализацией;
|
||||
- необходимость поддерживать архитектурную документацию в актуальном состоянии.
|
||||
|
||||
---
|
||||
|
||||
# Принятое решение
|
||||
|
||||
Перед началом реализации любого нового компонента обязательно выполняется архитектурное проектирование.
|
||||
|
||||
Минимальный цикл разработки выглядит следующим образом:
|
||||
|
||||
```text
|
||||
Идея
|
||||
↓
|
||||
Architecture Design
|
||||
↓
|
||||
Architecture Review
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Compile Check
|
||||
↓
|
||||
Domain Review
|
||||
↓
|
||||
Documentation Update
|
||||
↓
|
||||
Build Closed
|
||||
```
|
||||
|
||||
Переход к написанию кода допускается только после определения места компонента в общей архитектуре платформы.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Использование подхода **Architecture First** позволяет:
|
||||
|
||||
- сохранять целостность архитектуры;
|
||||
- уменьшать технический долг;
|
||||
- заранее определять ответственность компонентов;
|
||||
- предотвращать появление случайных зависимостей;
|
||||
- упрощать сопровождение проекта;
|
||||
- обеспечивать предсказуемое развитие платформы.
|
||||
|
||||
---
|
||||
|
||||
# Последствия
|
||||
|
||||
После принятия данного решения:
|
||||
|
||||
- архитектура всегда проектируется раньше реализации;
|
||||
- новый код не появляется без заранее определённой роли;
|
||||
- каждый компонент имеет понятную область ответственности;
|
||||
- архитектурные решения фиксируются документально;
|
||||
- развитие платформы становится последовательным и контролируемым.
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
- `architecture_principles.md`
|
||||
- `runtime_contract.md`
|
||||
- `development_process.md`
|
||||
- `build_history.md`
|
||||
|
||||
---
|
||||
|
||||
# История изменений
|
||||
|
||||
| Версия | Изменение |
|
||||
|---------|-----------|
|
||||
| 1.0 | Первое принятие архитектурного решения. |
|
||||
@@ -0,0 +1,209 @@
|
||||
# Decision 002 — Build Lifecycle
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Дата принятия
|
||||
|
||||
Принято во время проектирования Stage-08.2 **Engine Runtime Contract**.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
После принятия решения **Architecture First** возник вопрос:
|
||||
|
||||
> Каким образом должна развиваться архитектура платформы?
|
||||
|
||||
Были рассмотрены различные подходы к организации процесса разработки.
|
||||
|
||||
Главной целью являлось обеспечение стабильного роста платформы без накопления незавершённых изменений и архитектурной деградации.
|
||||
|
||||
---
|
||||
|
||||
# Проблема
|
||||
|
||||
При длительной разработке больших систем часто возникают следующие проблемы:
|
||||
|
||||
- одновременно изменяется большое количество компонентов;
|
||||
- невозможно определить момент логического завершения работы;
|
||||
- документация перестаёт соответствовать коду;
|
||||
- проверки выполняются нерегулярно;
|
||||
- ошибки обнаруживаются слишком поздно;
|
||||
- архитектурные решения принимаются уже после написания кода.
|
||||
|
||||
В результате становится сложно определить, какая часть системы действительно готова.
|
||||
|
||||
---
|
||||
|
||||
# Рассмотренные варианты
|
||||
|
||||
## Вариант 1
|
||||
|
||||
Разрабатывать большие функциональные блоки без промежуточных этапов.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- меньше организационной работы;
|
||||
- меньше промежуточной документации.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- большие объёмы изменений;
|
||||
- сложность проверки;
|
||||
- высокий риск архитектурных ошибок;
|
||||
- длительный цикл обратной связи;
|
||||
- увеличение сложности сопровождения.
|
||||
|
||||
---
|
||||
|
||||
## Вариант 2
|
||||
|
||||
Разбивать разработку на небольшие логически завершённые Build.
|
||||
|
||||
Каждый Build представляет собой самостоятельный этап разработки.
|
||||
|
||||
После завершения Build выполняются все проверки качества.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- небольшие объёмы изменений;
|
||||
- высокая предсказуемость;
|
||||
- возможность проверки каждого этапа;
|
||||
- документация развивается одновременно с кодом;
|
||||
- упрощается поиск ошибок;
|
||||
- архитектурные решения принимаются постепенно.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- требуется сопровождать историю Build;
|
||||
- увеличивается объём инженерной документации.
|
||||
|
||||
---
|
||||
|
||||
# Принятое решение
|
||||
|
||||
Разработка Dzentra ведётся исключительно последовательностью небольших логически завершённых Build.
|
||||
|
||||
Каждый Build должен иметь:
|
||||
|
||||
- понятную цель;
|
||||
- ограниченную область изменений;
|
||||
- завершённую реализацию;
|
||||
- обязательную проверку качества;
|
||||
- обновлённую документацию.
|
||||
|
||||
Build считается завершённым только после прохождения полного жизненного цикла.
|
||||
|
||||
---
|
||||
|
||||
# Жизненный цикл Build
|
||||
|
||||
Каждый Build проходит следующие этапы:
|
||||
|
||||
```text
|
||||
Architecture Design
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Compile Check
|
||||
↓
|
||||
Architecture Review
|
||||
↓
|
||||
Domain Review
|
||||
↓
|
||||
Documentation Update
|
||||
↓
|
||||
User Confirmation
|
||||
↓
|
||||
Build Closed
|
||||
```
|
||||
|
||||
До завершения всех этапов переход к следующему Build не допускается.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Использование небольших Build обеспечивает:
|
||||
|
||||
- постепенное развитие архитектуры;
|
||||
- раннее обнаружение ошибок;
|
||||
- минимизацию технического долга;
|
||||
- постоянную актуальность документации;
|
||||
- простоту сопровождения;
|
||||
- возможность безопасного возврата к предыдущим решениям.
|
||||
|
||||
---
|
||||
|
||||
# Последствия
|
||||
|
||||
После принятия настоящего решения:
|
||||
|
||||
- каждая новая функциональность реализуется отдельным Build;
|
||||
- Build имеет собственную документацию;
|
||||
- Build фиксируется в общей истории разработки;
|
||||
- архитектурные решения принимаются постепенно;
|
||||
- документация обновляется одновременно с исходным кодом.
|
||||
|
||||
---
|
||||
|
||||
# Правила Build
|
||||
|
||||
Каждый Build должен удовлетворять следующим требованиям.
|
||||
|
||||
## Логическая завершённость
|
||||
|
||||
Build реализует одну законченную архитектурную задачу.
|
||||
|
||||
---
|
||||
|
||||
## Независимость
|
||||
|
||||
Build должен быть понятен без изучения будущих Build.
|
||||
|
||||
---
|
||||
|
||||
## Проверяемость
|
||||
|
||||
После завершения Build должны существовать все необходимые проверки.
|
||||
|
||||
---
|
||||
|
||||
## Документирование
|
||||
|
||||
Каждый Build сопровождается отдельным документом в каталоге:
|
||||
|
||||
```text
|
||||
docs/market_intelligence/builds/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## История
|
||||
|
||||
Каждый завершённый Build регистрируется в:
|
||||
|
||||
```text
|
||||
build_history.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
- `development_process.md`
|
||||
- `architecture_principles.md`
|
||||
- `build_history.md`
|
||||
- `runtime_contract.md`
|
||||
|
||||
---
|
||||
|
||||
# История изменений
|
||||
|
||||
| Версия | Изменение |
|
||||
|---------|-----------|
|
||||
| 1.0 | Первое принятие архитектурного решения. |
|
||||
181
docs/market_intelligence/decisions/decision-003-domain-review.md
Normal file
181
docs/market_intelligence/decisions/decision-003-domain-review.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Decision 003 — Domain Review
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Дата принятия
|
||||
|
||||
Принято во время проектирования Stage-08.2 **Engine Runtime Contract**.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
После внедрения обязательного **Architecture Review** стало очевидно, что архитектурной проверки недостаточно.
|
||||
|
||||
Компонент может быть:
|
||||
|
||||
- технически корректным;
|
||||
- соответствовать архитектуре;
|
||||
- успешно компилироваться;
|
||||
|
||||
но при этом нарушать предметную область Market Intelligence.
|
||||
|
||||
Например, аналитический движок может начать принимать торговые решения, рассчитывать размер позиции или управлять открытой сделкой.
|
||||
|
||||
Подобные изменения не являются архитектурными ошибками, но полностью нарушают назначение аналитического уровня платформы.
|
||||
|
||||
---
|
||||
|
||||
# Проблема
|
||||
|
||||
Обычная архитектурная проверка отвечает на вопрос:
|
||||
|
||||
> **Правильно ли построен компонент?**
|
||||
|
||||
Однако она не отвечает на другой вопрос:
|
||||
|
||||
> **Правильно ли компонент выполняет свою роль в предметной области?**
|
||||
|
||||
Без отдельной проверки постепенно появляются следующие проблемы:
|
||||
|
||||
- аналитика начинает принимать торговые решения;
|
||||
- смешиваются обязанности разных Engine;
|
||||
- появляются термины с разным смыслом;
|
||||
- один и тот же объект начинает означать разные вещи;
|
||||
- снижается объяснимость результатов анализа.
|
||||
|
||||
Подобные изменения сложно обнаружить техническими средствами.
|
||||
|
||||
---
|
||||
|
||||
# Рассмотренные варианты
|
||||
|
||||
## Вариант 1
|
||||
|
||||
Использовать только Compile Check и Architecture Review.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- проще процесс разработки;
|
||||
- меньше этапов проверки.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- отсутствует контроль предметной области;
|
||||
- возможно постепенное смешивание аналитики и торговли;
|
||||
- ошибки обнаруживаются слишком поздно.
|
||||
|
||||
---
|
||||
|
||||
## Вариант 2
|
||||
|
||||
Ввести отдельный Domain Review.
|
||||
|
||||
После проверки архитектуры дополнительно анализируется соответствие предметной области.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- сохраняется чистота аналитического уровня;
|
||||
- исключается смешивание ответственности;
|
||||
- поддерживается единая терминология;
|
||||
- повышается качество архитектурных решений;
|
||||
- сохраняется объяснимость системы.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- увеличивается время проверки Build;
|
||||
- требуется дополнительная инженерная дисциплина.
|
||||
|
||||
---
|
||||
|
||||
# Принятое решение
|
||||
|
||||
Каждый логически завершённый Build проходит обязательный **Domain Review**.
|
||||
|
||||
Domain Review выполняется после успешного прохождения:
|
||||
|
||||
- Compile Check;
|
||||
- Architecture Review.
|
||||
|
||||
---
|
||||
|
||||
# Цель Domain Review
|
||||
|
||||
Domain Review проверяет не качество кода, а корректность поведения компонента относительно предметной области.
|
||||
|
||||
Главный вопрос проверки:
|
||||
|
||||
> **Соответствует ли данный компонент своей архитектурной роли?**
|
||||
|
||||
---
|
||||
|
||||
# Что проверяется
|
||||
|
||||
Во время Domain Review анализируются:
|
||||
|
||||
- корректность используемой терминологии;
|
||||
- соответствие названий реальным рыночным процессам;
|
||||
- отсутствие торговых решений внутри аналитических компонентов;
|
||||
- отсутствие смешивания обязанностей разных Engine;
|
||||
- понятность комментариев разработчику;
|
||||
- соответствие Engine Runtime Contract;
|
||||
- объяснимость результатов анализа;
|
||||
- отсутствие скрытых смыслов и неоднозначных терминов.
|
||||
|
||||
---
|
||||
|
||||
# Что не проверяется
|
||||
|
||||
Domain Review не оценивает:
|
||||
|
||||
- стиль оформления Python-кода;
|
||||
- синтаксис;
|
||||
- производительность реализации;
|
||||
- качество алгоритмов;
|
||||
- оптимизацию вычислений.
|
||||
|
||||
Эти вопросы относятся к другим этапам разработки.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Использование Domain Review позволяет:
|
||||
|
||||
- сохранить чистоту предметной области;
|
||||
- избежать постепенного смешивания анализа рынка и торговли;
|
||||
- поддерживать единый словарь терминов;
|
||||
- обеспечить объяснимость результатов;
|
||||
- сохранить независимость аналитических движков.
|
||||
|
||||
---
|
||||
|
||||
# Последствия
|
||||
|
||||
После принятия настоящего решения:
|
||||
|
||||
- каждый Build проходит Domain Review;
|
||||
- нарушение предметной области считается архитектурным дефектом;
|
||||
- аналитические компоненты остаются независимыми от торговой логики;
|
||||
- новые Engine обязаны соответствовать принятой терминологии.
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
- `architecture_principles.md`
|
||||
- `development_process.md`
|
||||
- `runtime_contract.md`
|
||||
- `reviews/domain_reviews.md`
|
||||
|
||||
---
|
||||
|
||||
# История изменений
|
||||
|
||||
| Версия | Изменение |
|
||||
|---------|-----------|
|
||||
| 1.0 | Первое принятие архитектурного решения. |
|
||||
@@ -0,0 +1,171 @@
|
||||
# Decision 004 — No Existing Code Assumptions
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Дата принятия
|
||||
|
||||
Принято во время реализации первых Build подсистемы **Market Intelligence**.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
Во время разработки новых компонентов неоднократно возникала ситуация, когда для продолжения работы требовалось знать текущее состояние проекта.
|
||||
|
||||
Например:
|
||||
|
||||
- существующие модели;
|
||||
- типы;
|
||||
- контракты;
|
||||
- Runtime State;
|
||||
- Engine Contract;
|
||||
- общие структуры данных.
|
||||
|
||||
Использование предположений о содержимом существующих файлов приводило бы к риску расхождения между проектируемым кодом и реальным состоянием проекта.
|
||||
|
||||
Для долгоживущей платформы подобный подход признан неприемлемым.
|
||||
|
||||
---
|
||||
|
||||
# Проблема
|
||||
|
||||
Во время проектирования новых компонентов существует соблазн предположить, что существующий файл имеет ожидаемую структуру.
|
||||
|
||||
Например:
|
||||
|
||||
> «Наверное, эта модель уже существует.»
|
||||
|
||||
или
|
||||
|
||||
> «Скорее всего, поле называется именно так.»
|
||||
|
||||
Подобные предположения могут привести к следующим последствиям:
|
||||
|
||||
- дублирование уже существующих сущностей;
|
||||
- несовместимые контракты;
|
||||
- повторная реализация одинаковой логики;
|
||||
- нарушение принципа единого источника истины;
|
||||
- увеличение объёма последующего рефакторинга.
|
||||
|
||||
---
|
||||
|
||||
# Рассмотренные варианты
|
||||
|
||||
## Вариант 1
|
||||
|
||||
Использовать предположения о текущем состоянии проекта.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- быстрее писать код;
|
||||
- меньше дополнительных запросов.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- высокий риск ошибок;
|
||||
- потеря синхронизации с реальным проектом;
|
||||
- появление дублирующих сущностей;
|
||||
- снижение качества архитектуры.
|
||||
|
||||
---
|
||||
|
||||
## Вариант 2
|
||||
|
||||
Использовать существующий код как единственный источник истины.
|
||||
|
||||
Если для реализации требуется информация о существующем компоненте, соответствующий файл предварительно запрашивается у пользователя.
|
||||
|
||||
После получения файла все архитектурные решения принимаются исключительно на основании его фактического содержимого.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- отсутствие ложных предположений;
|
||||
- единый источник истины;
|
||||
- отсутствие дублирования;
|
||||
- минимизация архитектурных ошибок;
|
||||
- синхронное развитие проекта и документации.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- требуется дополнительный шаг перед началом реализации.
|
||||
|
||||
---
|
||||
|
||||
# Принятое решение
|
||||
|
||||
При реализации новых компонентов запрещается делать предположения о содержимом существующих файлов.
|
||||
|
||||
Если новый компонент зависит от уже существующей части проекта, соответствующий файл должен быть предварительно получен и использован как единственный источник истины.
|
||||
|
||||
---
|
||||
|
||||
# Правило разработки
|
||||
|
||||
Перед началом реализации необходимо определить, зависит ли новый компонент от существующего кода.
|
||||
|
||||
Если зависимость существует, разработчик обязан запросить соответствующий файл до начала проектирования или написания кода.
|
||||
|
||||
После получения файла запрещается создавать альтернативные реализации уже существующих сущностей.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Использование существующего кода как единственного источника истины позволяет:
|
||||
|
||||
- исключить дублирование;
|
||||
- избежать несовместимых контрактов;
|
||||
- сохранить целостность архитектуры;
|
||||
- уменьшить объём последующего рефакторинга;
|
||||
- обеспечить единое понимание структуры проекта.
|
||||
|
||||
---
|
||||
|
||||
# Последствия
|
||||
|
||||
После принятия настоящего решения:
|
||||
|
||||
- архитектурные решения принимаются только на основании реального состояния проекта;
|
||||
- существующие модели повторно используются вместо повторной реализации;
|
||||
- новые сущности создаются только при их фактическом отсутствии;
|
||||
- вероятность архитектурных расхождений существенно снижается.
|
||||
|
||||
---
|
||||
|
||||
# Практическое применение
|
||||
|
||||
Перед созданием любого нового файла выполняется следующий вопрос:
|
||||
|
||||
> **Требуется ли для его реализации существующий код проекта?**
|
||||
|
||||
Если ответ положительный, необходимые файлы запрашиваются до начала работы.
|
||||
|
||||
Данное правило распространяется на:
|
||||
|
||||
- модели;
|
||||
- контракты;
|
||||
- состояния Runtime;
|
||||
- общие типы;
|
||||
- перечисления;
|
||||
- вспомогательные функции;
|
||||
- архитектурные ограничения.
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
- `architecture_principles.md`
|
||||
- `development_process.md`
|
||||
- `runtime_contract.md`
|
||||
|
||||
---
|
||||
|
||||
# История изменений
|
||||
|
||||
| Версия | Изменение |
|
||||
|---------|-----------|
|
||||
| 1.0 | Первое принятие архитектурного решения. |
|
||||
@@ -0,0 +1,198 @@
|
||||
# Decision 005 — Human Readable Comments
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Дата принятия
|
||||
|
||||
Принято во время разработки подсистемы **Market Intelligence**.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
Во время проектирования первых компонентов Market Intelligence стало очевидно, что большая часть сложности проекта связана не с алгоритмами, а с пониманием их назначения.
|
||||
|
||||
Даже технически корректный код может быть труден для сопровождения, если разработчику приходится самостоятельно догадываться:
|
||||
|
||||
- зачем существует компонент;
|
||||
- какую задачу он решает;
|
||||
- какие ограничения необходимо учитывать;
|
||||
- почему архитектура построена именно таким образом.
|
||||
|
||||
Стандартные комментарии, объясняющие синтаксис Python, практически не помогают решить эти задачи.
|
||||
|
||||
---
|
||||
|
||||
# Проблема
|
||||
|
||||
Большинство комментариев в программных проектах описывают очевидные действия языка программирования.
|
||||
|
||||
Например:
|
||||
|
||||
```python
|
||||
# увеличиваем счётчик
|
||||
counter += 1
|
||||
```
|
||||
|
||||
или
|
||||
|
||||
```python
|
||||
# проверяем условие
|
||||
if value > limit:
|
||||
```
|
||||
|
||||
Подобные комментарии быстро устаревают и не помогают понять архитектуру системы.
|
||||
|
||||
Гораздо более ценными являются ответы на вопросы:
|
||||
|
||||
- зачем существует данный объект;
|
||||
- почему принято именно такое решение;
|
||||
- какие ограничения существуют;
|
||||
- что произойдёт при нарушении данного правила.
|
||||
|
||||
---
|
||||
|
||||
# Рассмотренные варианты
|
||||
|
||||
## Вариант 1
|
||||
|
||||
Использовать минимальное количество комментариев.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- меньше текста;
|
||||
- проще поддерживать.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- ухудшается сопровождаемость;
|
||||
- сложнее понимать архитектуру;
|
||||
- новые разработчики дольше погружаются в проект.
|
||||
|
||||
---
|
||||
|
||||
## Вариант 2
|
||||
|
||||
Комментировать синтаксис Python.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- большое количество комментариев.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- комментарии не несут архитектурной ценности;
|
||||
- быстро устаревают;
|
||||
- отвлекают от действительно важных пояснений.
|
||||
|
||||
---
|
||||
|
||||
## Вариант 3
|
||||
|
||||
Комментарии объясняют назначение компонента и архитектурный смысл.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- легче сопровождать проект;
|
||||
- проще понимать архитектуру;
|
||||
- быстрее находить причины существования компонентов;
|
||||
- комментарии остаются актуальными значительно дольше.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- требуется больше внимания при проектировании.
|
||||
|
||||
---
|
||||
|
||||
# Принятое решение
|
||||
|
||||
Комментарии в Dzentra должны объяснять **назначение**, **роль** и **ограничения** компонентов.
|
||||
|
||||
Комментарии не должны пересказывать синтаксис языка Python.
|
||||
|
||||
---
|
||||
|
||||
# Основные правила
|
||||
|
||||
Комментарии должны отвечать хотя бы на один из следующих вопросов:
|
||||
|
||||
- зачем существует данный компонент;
|
||||
- какую задачу он решает;
|
||||
- почему используется именно такое решение;
|
||||
- какие ограничения необходимо учитывать;
|
||||
- где проходит граница ответственности компонента.
|
||||
|
||||
---
|
||||
|
||||
# Следует избегать
|
||||
|
||||
Не рекомендуется писать комментарии, объясняющие очевидные конструкции языка.
|
||||
|
||||
Например:
|
||||
|
||||
```python
|
||||
# складываем два числа
|
||||
total = a + b
|
||||
```
|
||||
|
||||
или
|
||||
|
||||
```python
|
||||
# возвращаем результат
|
||||
return result
|
||||
```
|
||||
|
||||
Такие комментарии не добавляют полезной информации.
|
||||
|
||||
---
|
||||
|
||||
# Комментарии в Market Intelligence
|
||||
|
||||
При разработке аналитических движков комментарии должны быть понятны разработчику, который не является профессиональным трейдером.
|
||||
|
||||
Предпочтительно использовать простые технические формулировки.
|
||||
|
||||
Если существует возможность заменить узкоспециализированный термин более понятным описанием без потери смысла, следует использовать более понятное описание.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Использование человекочитаемых комментариев позволяет:
|
||||
|
||||
- уменьшить порог входа в проект;
|
||||
- повысить сопровождаемость;
|
||||
- сделать архитектуру более понятной;
|
||||
- уменьшить зависимость от автора исходного кода;
|
||||
- сохранить знания внутри проекта.
|
||||
|
||||
---
|
||||
|
||||
# Последствия
|
||||
|
||||
После принятия настоящего решения:
|
||||
|
||||
- новые комментарии ориентируются на смысл, а не на синтаксис;
|
||||
- архитектурные ограничения описываются непосредственно в коде;
|
||||
- комментарии становятся частью инженерной документации проекта;
|
||||
- разработчик может понять назначение большинства компонентов без обращения к внешним источникам.
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
- `architecture_principles.md`
|
||||
- `development_process.md`
|
||||
- `runtime_contract.md`
|
||||
|
||||
---
|
||||
|
||||
# История изменений
|
||||
|
||||
| Версия | Изменение |
|
||||
|---------|-----------|
|
||||
| 1.0 | Первое принятие архитектурного решения. |
|
||||
@@ -0,0 +1,157 @@
|
||||
# Decision 006 — Immutable Engine Contract
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Дата принятия
|
||||
|
||||
Принято во время реализации **Build №006 — `common/models.py`**.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
Во время проектирования единого контракта аналитических движков возник вопрос:
|
||||
|
||||
> **Могут ли модели результата изменяться после завершения расчёта?**
|
||||
|
||||
Рассматривались два варианта.
|
||||
|
||||
---
|
||||
|
||||
# Вариант 1
|
||||
|
||||
Изменяемые (`mutable`) модели.
|
||||
|
||||
После создания объекта любой компонент платформы может изменить его поля.
|
||||
|
||||
Например:
|
||||
|
||||
```python
|
||||
result.score = ...
|
||||
result.reason = ...
|
||||
result.direction = ...
|
||||
```
|
||||
|
||||
### Преимущества
|
||||
|
||||
- проще писать код;
|
||||
- меньше ограничений.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- невозможно гарантировать целостность результата;
|
||||
- результат может измениться после публикации;
|
||||
- журнал может содержать значения, отличающиеся от реально использованных;
|
||||
- сложнее искать ошибки;
|
||||
- возрастает риск скрытых побочных эффектов.
|
||||
|
||||
---
|
||||
|
||||
# Вариант 2
|
||||
|
||||
Неизменяемые (`immutable`) модели.
|
||||
|
||||
После создания объекта изменение его полей невозможно.
|
||||
|
||||
При необходимости формируется новый объект результата.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- результат всегда остаётся неизменным;
|
||||
- журнал отражает фактическое состояние расчёта;
|
||||
- безопасная передача между компонентами;
|
||||
- отсутствуют скрытые изменения;
|
||||
- упрощается диагностика;
|
||||
- упрощается тестирование;
|
||||
- повышается предсказуемость поведения платформы.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- при изменении необходимо создавать новый экземпляр объекта.
|
||||
|
||||
---
|
||||
|
||||
# Принятое решение
|
||||
|
||||
Для всех моделей, описывающих результат работы аналитических движков, используется **неизменяемый контракт**.
|
||||
|
||||
Все основные модели объявляются как:
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True, slots=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Область применения
|
||||
|
||||
Правило распространяется на:
|
||||
|
||||
- `EngineResult`;
|
||||
- `EngineContext`;
|
||||
- `EngineMetric`;
|
||||
- `EngineDiagnostics`;
|
||||
- `EngineEvaluationMeta`;
|
||||
- `EngineDependencyResult`;
|
||||
|
||||
а также на все будущие модели, описывающие результаты работы Engine.
|
||||
|
||||
---
|
||||
|
||||
# Исключения
|
||||
|
||||
Настоящее правило **не распространяется** на:
|
||||
|
||||
- Runtime State;
|
||||
- AutoTrade State;
|
||||
- Position State;
|
||||
- Execution Runtime;
|
||||
- внутренние рабочие объекты расчёта.
|
||||
|
||||
Эти объекты отражают изменяющееся состояние платформы и по своей природе являются изменяемыми.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Использование неизменяемых моделей обеспечивает:
|
||||
|
||||
- целостность результатов анализа;
|
||||
- безопасную передачу данных между Engine;
|
||||
- корректное журналирование;
|
||||
- предсказуемость поведения системы;
|
||||
- отсутствие скрытых побочных эффектов;
|
||||
- упрощение сопровождения проекта в долгосрочной перспективе.
|
||||
|
||||
---
|
||||
|
||||
# Архитектурные последствия
|
||||
|
||||
После принятия настоящего решения:
|
||||
|
||||
- результаты Engine не изменяются после создания;
|
||||
- каждый новый расчёт формирует новый объект результата;
|
||||
- публикация событий всегда выполняется на основе завершённого результата;
|
||||
- журнал содержит фактически опубликованные данные;
|
||||
- Coordinator работает только с завершёнными результатами анализа.
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
- `runtime_contract.md`
|
||||
- `architecture_principles.md`
|
||||
- `development_process.md`
|
||||
- `builds/build-006-common-models.md`
|
||||
|
||||
---
|
||||
|
||||
# История
|
||||
|
||||
| Версия | Изменение |
|
||||
|---------|-----------|
|
||||
| 1.0 | Первое принятие архитектурного решения. |
|
||||
@@ -0,0 +1,179 @@
|
||||
# Decision 007 — Documentation Is Code
|
||||
|
||||
## Статус
|
||||
|
||||
**Accepted**
|
||||
|
||||
---
|
||||
|
||||
# Дата принятия
|
||||
|
||||
Принято во время разработки Stage-08.2 **Engine Runtime Contract**.
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
Во время разработки первых компонентов Market Intelligence стало очевидно, что исходный код и документация развиваются одновременно.
|
||||
|
||||
Если документация обновляется позже кода, очень быстро возникает расхождение между:
|
||||
|
||||
- архитектурой;
|
||||
- реализацией;
|
||||
- инженерными решениями;
|
||||
- фактическим состоянием проекта.
|
||||
|
||||
В результате документация перестаёт отражать реальное устройство системы.
|
||||
|
||||
---
|
||||
|
||||
# Проблема
|
||||
|
||||
Во многих проектах документация рассматривается как дополнительный материал.
|
||||
|
||||
Обычно процесс выглядит следующим образом:
|
||||
|
||||
```text
|
||||
Написание кода
|
||||
↓
|
||||
Код работает
|
||||
↓
|
||||
Документацию обновим позже
|
||||
```
|
||||
|
||||
На практике "позже" часто не наступает.
|
||||
|
||||
Через некоторое время:
|
||||
|
||||
- документация устаревает;
|
||||
- архитектурные решения теряются;
|
||||
- новые разработчики вынуждены изучать проект только по исходному коду.
|
||||
|
||||
---
|
||||
|
||||
# Рассмотренные варианты
|
||||
|
||||
## Вариант 1
|
||||
|
||||
Документация обновляется по мере возможности.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- меньше работы во время реализации.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- документация быстро устаревает;
|
||||
- теряются архитектурные решения;
|
||||
- сложно понять историю развития проекта.
|
||||
|
||||
---
|
||||
|
||||
## Вариант 2
|
||||
|
||||
Документация обновляется одновременно с кодом.
|
||||
|
||||
Build считается завершённым только после обновления всей связанной документации.
|
||||
|
||||
### Преимущества
|
||||
|
||||
- документация всегда соответствует проекту;
|
||||
- архитектурные решения сохраняются;
|
||||
- упрощается сопровождение;
|
||||
- сохраняется история развития платформы;
|
||||
- новые разработчики быстрее понимают проект.
|
||||
|
||||
### Недостатки
|
||||
|
||||
- требуется дополнительное время на оформление документации.
|
||||
|
||||
---
|
||||
|
||||
# Принятое решение
|
||||
|
||||
Документация является частью исходного кода проекта.
|
||||
|
||||
Каждый Build считается завершённым только после обновления всей связанной документации.
|
||||
|
||||
Документация имеет такую же обязательность, как Compile Check или Architecture Review.
|
||||
|
||||
---
|
||||
|
||||
# Обязательная документация Build
|
||||
|
||||
После завершения каждого Build обязательно обновляются все связанные документы.
|
||||
|
||||
Например:
|
||||
|
||||
- Build Document;
|
||||
- Build History;
|
||||
- Architecture Decisions (при необходимости);
|
||||
- Runtime Contract (при необходимости);
|
||||
- Development Process (при необходимости);
|
||||
- README соответствующего раздела (при необходимости).
|
||||
|
||||
---
|
||||
|
||||
# Правило завершения Build
|
||||
|
||||
Build считается завершённым только после прохождения полного цикла:
|
||||
|
||||
```text
|
||||
Architecture Design
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Compile Check
|
||||
↓
|
||||
Architecture Review
|
||||
↓
|
||||
Domain Review
|
||||
↓
|
||||
Documentation Update
|
||||
↓
|
||||
User Confirmation
|
||||
↓
|
||||
Build Closed
|
||||
```
|
||||
|
||||
Если документация не обновлена, Build остаётся незавершённым.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Использование данного подхода позволяет:
|
||||
|
||||
- сохранять актуальность документации;
|
||||
- фиксировать архитектурные решения;
|
||||
- поддерживать единый источник знаний;
|
||||
- облегчать сопровождение проекта;
|
||||
- исключать расхождение между кодом и документацией.
|
||||
|
||||
---
|
||||
|
||||
# Последствия
|
||||
|
||||
После принятия настоящего решения:
|
||||
|
||||
- документация развивается одновременно с кодом;
|
||||
- архитектурные изменения всегда фиксируются;
|
||||
- история развития проекта полностью сохраняется;
|
||||
- Build не может считаться завершённым без обновления документации.
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
- `development_process.md`
|
||||
- `build_history.md`
|
||||
- `architecture_principles.md`
|
||||
- `runtime_contract.md`
|
||||
|
||||
---
|
||||
|
||||
# История изменений
|
||||
|
||||
| Версия | Изменение |
|
||||
|---------|-----------|
|
||||
| 1.0 | Первое принятие архитектурного решения. |
|
||||
@@ -0,0 +1,257 @@
|
||||
# Architecture Decision Record 008
|
||||
|
||||
# Engine Metadata Separation
|
||||
|
||||
Статус: **Accepted**
|
||||
|
||||
Версия: **1.0**
|
||||
|
||||
---
|
||||
|
||||
# Контекст
|
||||
|
||||
Подсистема **Market Intelligence** строится как долгосрочная аналитическая платформа, состоящая из множества независимых специализированных Engine.
|
||||
|
||||
Ожидается, что со временем количество Engine будет постепенно увеличиваться.
|
||||
|
||||
Каждый Engine должен быть независимым компонентом, который можно:
|
||||
|
||||
- зарегистрировать;
|
||||
- проверить;
|
||||
- документировать;
|
||||
- подключить к Runtime;
|
||||
- использовать Coordinator;
|
||||
- заменить новой реализацией.
|
||||
|
||||
До начала реализации Runtime было необходимо определить единый способ описания любого Engine.
|
||||
|
||||
---
|
||||
|
||||
# Проблема
|
||||
|
||||
Наивная реализация предполагает, что Runtime работает непосредственно с экземпляром Engine.
|
||||
|
||||
Например:
|
||||
|
||||
```python
|
||||
engine.run(context)
|
||||
```
|
||||
|
||||
При таком подходе Runtime ничего не знает о самом Engine до его создания.
|
||||
|
||||
Это приводит к нескольким проблемам.
|
||||
|
||||
Runtime не может заранее определить:
|
||||
|
||||
- имя Engine;
|
||||
- назначение Engine;
|
||||
- зависимости Engine;
|
||||
- поддерживаемые таймфреймы;
|
||||
- минимальные требования к данным;
|
||||
- совместимость версии;
|
||||
- возможность регистрации Engine.
|
||||
|
||||
В результате описание Engine смешивается с его логикой.
|
||||
|
||||
По мере роста количества Engine подобная архитектура становится всё менее масштабируемой.
|
||||
|
||||
---
|
||||
|
||||
# Решение
|
||||
|
||||
Каждый Engine разделяется на две полностью независимые части.
|
||||
|
||||
```text
|
||||
Engine
|
||||
|
||||
├── Metadata
|
||||
└── Logic
|
||||
```
|
||||
|
||||
Metadata описывает Engine.
|
||||
|
||||
Logic реализует анализ рынка.
|
||||
|
||||
Runtime работает с Metadata.
|
||||
|
||||
Engine выполняет только аналитический алгоритм.
|
||||
|
||||
---
|
||||
|
||||
# Engine Metadata
|
||||
|
||||
Metadata представляет собой неизменяемое описание Engine.
|
||||
|
||||
Metadata должна содержать всю информацию, необходимую инфраструктуре платформы.
|
||||
|
||||
Например:
|
||||
|
||||
- имя Engine;
|
||||
- версия Engine;
|
||||
- отображаемое имя;
|
||||
- краткое описание;
|
||||
- зависимости;
|
||||
- поддерживаемые таймфреймы;
|
||||
- минимальные требования к входным данным;
|
||||
- дополнительные возможности Engine.
|
||||
|
||||
Metadata не содержит вычисляемых значений.
|
||||
|
||||
Metadata не зависит от состояния рынка.
|
||||
|
||||
Metadata не изменяется во время выполнения Engine.
|
||||
|
||||
---
|
||||
|
||||
# Engine Logic
|
||||
|
||||
Logic содержит исключительно алгоритм анализа.
|
||||
|
||||
Logic получает:
|
||||
|
||||
```text
|
||||
EngineContext
|
||||
```
|
||||
|
||||
и возвращает
|
||||
|
||||
```text
|
||||
EngineResult
|
||||
```
|
||||
|
||||
Logic не должна хранить архитектурную информацию о себе.
|
||||
|
||||
Она не отвечает за:
|
||||
|
||||
- регистрацию;
|
||||
- описание возможностей;
|
||||
- зависимости;
|
||||
- документацию;
|
||||
- совместимость.
|
||||
|
||||
Эти сведения находятся исключительно в Metadata.
|
||||
|
||||
---
|
||||
|
||||
# Immutable Metadata
|
||||
|
||||
Metadata является полностью неизменяемой структурой.
|
||||
|
||||
После создания Metadata запрещается изменять её содержимое.
|
||||
|
||||
Runtime рассматривает Metadata как константу.
|
||||
|
||||
Engine не имеет права изменять собственное описание во время выполнения.
|
||||
|
||||
---
|
||||
|
||||
# Metadata Access
|
||||
|
||||
Metadata должна быть доступна инфраструктуре платформы без создания экземпляра Engine.
|
||||
|
||||
Runtime, Registry и Coordinator должны иметь возможность получить полное описание Engine до начала его выполнения.
|
||||
|
||||
Предпочтительной реализацией является хранение Metadata как неизменяемого атрибута класса Engine.
|
||||
|
||||
Например:
|
||||
|
||||
```python
|
||||
TrendEngine.metadata
|
||||
```
|
||||
|
||||
или отдельной неизменяемой структуры:
|
||||
|
||||
```python
|
||||
TREND_ENGINE_METADATA
|
||||
```
|
||||
|
||||
Создание экземпляра Engine исключительно для получения Metadata не допускается.
|
||||
|
||||
Это позволяет Runtime:
|
||||
|
||||
- регистрировать Engine;
|
||||
- строить граф зависимостей;
|
||||
- проверять совместимость;
|
||||
- формировать документацию;
|
||||
- анализировать архитектуру платформы;
|
||||
|
||||
без запуска аналитических алгоритмов.
|
||||
|
||||
---
|
||||
|
||||
# Причины принятия решения
|
||||
|
||||
Разделение Metadata и Logic обеспечивает:
|
||||
|
||||
- единый способ описания Engine;
|
||||
- независимость инфраструктуры от реализации Engine;
|
||||
- возможность автоматической регистрации Engine;
|
||||
- возможность построения графа зависимостей;
|
||||
- возможность автоматического формирования документации;
|
||||
- возможность проверки совместимости;
|
||||
- упрощение тестирования;
|
||||
- упрощение сопровождения.
|
||||
|
||||
---
|
||||
|
||||
# Последствия
|
||||
|
||||
После принятия настоящего решения любой новый Engine обязан состоять из двух независимых частей:
|
||||
|
||||
```text
|
||||
Metadata
|
||||
|
||||
↓
|
||||
|
||||
Logic
|
||||
```
|
||||
|
||||
Создание Engine без Metadata считается нарушением архитектурного стандарта платформы.
|
||||
|
||||
---
|
||||
|
||||
# Влияние на Runtime
|
||||
|
||||
Runtime работает исключительно через Metadata.
|
||||
|
||||
Runtime не должен получать архитектурную информацию путём анализа реализации Engine.
|
||||
|
||||
Все инфраструктурные механизмы используют Metadata как единственный источник архитектурного описания Engine.
|
||||
|
||||
---
|
||||
|
||||
# Влияние на Registry
|
||||
|
||||
Engine Registry использует Metadata для:
|
||||
|
||||
- регистрации Engine;
|
||||
- проверки уникальности;
|
||||
- поиска Engine;
|
||||
- проверки зависимостей;
|
||||
- формирования списка доступных Engine.
|
||||
|
||||
Registry не анализирует реализацию Engine.
|
||||
|
||||
---
|
||||
|
||||
# Влияние на Coordinator
|
||||
|
||||
Coordinator использует Metadata для определения порядка выполнения Engine.
|
||||
|
||||
Coordinator не должен знать внутреннее устройство конкретного Engine.
|
||||
|
||||
---
|
||||
|
||||
# Совместимость
|
||||
|
||||
Настоящее решение является обязательным для всех существующих и будущих Engine подсистемы **Market Intelligence**.
|
||||
|
||||
Изменение данного правила допускается только посредством нового Architecture Decision Record.
|
||||
|
||||
---
|
||||
|
||||
# Статус решения
|
||||
|
||||
Настоящее решение принято как долгосрочный архитектурный стандарт платформы **Dzentra Market Intelligence**.
|
||||
|
||||
Все последующие Runtime и Engine Build должны соответствовать данному ADR.
|
||||
3060
docs/market_intelligence/development_process.md
Normal file
3060
docs/market_intelligence/development_process.md
Normal file
File diff suppressed because it is too large
Load Diff
0
docs/market_intelligence/diagrams/README.md
Normal file
0
docs/market_intelligence/diagrams/README.md
Normal file
0
docs/market_intelligence/engines/README.md
Normal file
0
docs/market_intelligence/engines/README.md
Normal file
171
docs/market_intelligence/engines/architecture.md
Normal file
171
docs/market_intelligence/engines/architecture.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Архитектура Engine Layer
|
||||
|
||||
**Версия:** 1.0
|
||||
|
||||
**Статус:** Active
|
||||
|
||||
---
|
||||
|
||||
# Назначение
|
||||
|
||||
Настоящий документ определяет архитектуру слоя аналитических движков (Engine Layer)
|
||||
подсистемы **Market Intelligence**.
|
||||
|
||||
Каждый Engine отвечает только за один аспект анализа рынка и никогда не принимает
|
||||
торговых решений.
|
||||
|
||||
---
|
||||
|
||||
# Базовая модель Engine
|
||||
|
||||
Каждый Engine состоит из двух независимых частей:
|
||||
|
||||
```text
|
||||
Engine
|
||||
├── Metadata
|
||||
└── Logic
|
||||
```
|
||||
|
||||
Разделение Metadata и Logic является обязательным архитектурным правилом.
|
||||
|
||||
---
|
||||
|
||||
# Metadata
|
||||
|
||||
Metadata — неизменяемое архитектурное описание Engine.
|
||||
|
||||
Metadata содержит:
|
||||
|
||||
- имя Engine;
|
||||
- версию;
|
||||
- отображаемое имя;
|
||||
- назначение;
|
||||
- зависимости;
|
||||
- поддерживаемые таймфреймы;
|
||||
- требования к входным данным;
|
||||
- архитектурные возможности.
|
||||
|
||||
Metadata должна быть доступна без создания экземпляра Engine.
|
||||
|
||||
Во время выполнения Engine Metadata никогда не изменяется.
|
||||
|
||||
---
|
||||
|
||||
# Logic
|
||||
|
||||
Logic представляет собой аналитическую реализацию Engine.
|
||||
|
||||
Вход:
|
||||
|
||||
```text
|
||||
EngineContext
|
||||
```
|
||||
|
||||
Выход:
|
||||
|
||||
```text
|
||||
EngineResult
|
||||
```
|
||||
|
||||
Logic не должна изменять Metadata.
|
||||
|
||||
---
|
||||
|
||||
# Обязательная структура Engine
|
||||
|
||||
```text
|
||||
<engine>/
|
||||
├── metadata.py
|
||||
└── engine.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Рекомендуемая структура Engine
|
||||
|
||||
```text
|
||||
<engine>/
|
||||
├── __init__.py
|
||||
├── metadata.py
|
||||
├── models.py
|
||||
├── calculators.py
|
||||
├── evaluators.py
|
||||
├── checks.py
|
||||
├── payloads.py
|
||||
└── engine.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Допустимые расширения
|
||||
|
||||
Сложные Engine могут содержать дополнительные специализированные модули.
|
||||
|
||||
Пример:
|
||||
|
||||
```text
|
||||
wave/
|
||||
├── metadata.py
|
||||
├── models.py
|
||||
├── swing_points.py
|
||||
├── wave_builder.py
|
||||
├── impulse_detector.py
|
||||
├── pullback_detector.py
|
||||
├── evaluators.py
|
||||
├── checks.py
|
||||
├── payloads.py
|
||||
└── engine.py
|
||||
```
|
||||
|
||||
Уникальная внутренняя структура допускается, если сохраняется Runtime Contract.
|
||||
|
||||
---
|
||||
|
||||
# Запрещённые зависимости
|
||||
|
||||
Engine не должен напрямую зависеть от:
|
||||
|
||||
- другого Engine;
|
||||
- AutoTrade;
|
||||
- Exchange;
|
||||
- Telegram;
|
||||
- Execution;
|
||||
- Journal;
|
||||
- базы данных.
|
||||
|
||||
Результаты других Engine могут передаваться только через:
|
||||
|
||||
```text
|
||||
EngineContext.dependency_results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Разрешённые зависимости
|
||||
|
||||
Engine может зависеть от:
|
||||
|
||||
- `market_intelligence/common`;
|
||||
- Runtime Contract;
|
||||
- собственных внутренних модулей;
|
||||
- стандартной библиотеки Python.
|
||||
|
||||
---
|
||||
|
||||
# Главное правило
|
||||
|
||||
Внутренняя структура Engine может отличаться в зависимости от сложности предметной области.
|
||||
|
||||
Однако для любого Engine обязательны:
|
||||
|
||||
- соблюдение Runtime Contract;
|
||||
- наличие Metadata;
|
||||
- единая точка входа (`engine.py`).
|
||||
|
||||
---
|
||||
|
||||
# Заключение
|
||||
|
||||
Engine Layer развивается через расширение, а не через изменение Runtime.
|
||||
|
||||
Добавление нового Engine не должно требовать изменения Runtime Layer.
|
||||
0
docs/market_intelligence/glossary/README.md
Normal file
0
docs/market_intelligence/glossary/README.md
Normal file
0
docs/market_intelligence/information/README.md
Normal file
0
docs/market_intelligence/information/README.md
Normal file
3499
docs/market_intelligence/information/dzengi_market_data_inventory.md
Normal file
3499
docs/market_intelligence/information/dzengi_market_data_inventory.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,246 @@
|
||||
# Dzengi Market Intelligence Information Mapping
|
||||
|
||||
## Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|----------|
|
||||
| Документ | Dzengi Market Intelligence Information Mapping |
|
||||
| Тип документа | Information Mapping |
|
||||
| Версия | 1.0 |
|
||||
| Статус | Draft |
|
||||
| Степень верификации | Documentation Based |
|
||||
| Проект | Dzentra |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Источник | Dzengi API |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
## Статус документа
|
||||
|
||||
Настоящий документ определяет соответствие между техническими данными, предоставляемыми API Dzengi, и информационными сущностями подсистемы Market Intelligence.
|
||||
|
||||
Документ построен на основании **Dzengi Market Data Inventory** и не содержит интерпретации состояния рынка.
|
||||
|
||||
До выпуска версии Release допускается уточнение состава информационных сущностей и их соответствия данным API по результатам проверки фактических ответов биржи.
|
||||
|
||||
---
|
||||
|
||||
## Степень верификации
|
||||
|
||||
Настоящая редакция документа построена на основании:
|
||||
|
||||
- Dzengi Market Data Inventory;
|
||||
- официальной документации Dzengi;
|
||||
- OpenAPI (Swagger);
|
||||
- официальных примеров запросов;
|
||||
- официальных примеров ответов.
|
||||
|
||||
Фактическая проверка информационных сущностей посредством выполнения реальных запросов к бирже Dzengi на момент подготовки настоящей редакции документа не проводилась.
|
||||
|
||||
По этой причине:
|
||||
|
||||
- соответствие информационных сущностей данным API считается соответствующим официальной документации;
|
||||
- состав используемых полей считается соответствующим официальной документации;
|
||||
- описание информационных сущностей основано исключительно на опубликованной спецификации API.
|
||||
|
||||
Настоящий документ имеет статус **Documentation Verified**.
|
||||
|
||||
После проверки информационных сущностей посредством выполнения реальных запросов и анализа фактических ответов API документ получит статус **Runtime Verified**.
|
||||
|
||||
Все расхождения между документацией и фактическим поведением API должны фиксироваться в последующих редакциях настоящего документа.
|
||||
|
||||
---
|
||||
|
||||
## Назначение
|
||||
|
||||
Настоящий документ предназначен для формирования единого слоя информационных сущностей Market Intelligence на основании возможностей API Dzengi.
|
||||
|
||||
Документ определяет:
|
||||
|
||||
- какие информационные сущности могут быть получены из Dzengi;
|
||||
- какие информационные сущности могут быть автоматически вычислены;
|
||||
- какие поля API являются источниками каждой информационной сущности;
|
||||
- канонические имена информационных сущностей;
|
||||
- канонические идентификаторы информационных сущностей.
|
||||
|
||||
Настоящий документ не определяет:
|
||||
|
||||
- знания о рынке;
|
||||
- интерпретацию информации;
|
||||
- алгоритмы анализа рынка;
|
||||
- архитектуру Engine;
|
||||
- торговые стратегии;
|
||||
- правила принятия торговых решений.
|
||||
|
||||
---
|
||||
|
||||
## Цель
|
||||
|
||||
Цель настоящего документа — сформировать полный каталог информационных сущностей, потенциально доступных подсистеме Market Intelligence при использовании API Dzengi.
|
||||
|
||||
---
|
||||
|
||||
## Основной вопрос документа
|
||||
|
||||
Настоящий документ отвечает исключительно на следующий вопрос.
|
||||
|
||||
> **Какие информационные сущности Market Intelligence могут быть получены или автоматически вычислены на основании данных Dzengi API?**
|
||||
|
||||
---
|
||||
|
||||
## Источник информации
|
||||
|
||||
Настоящий документ построен на основании следующих источников.
|
||||
|
||||
- Dzengi Market Data Inventory;
|
||||
- REST API Documentation;
|
||||
- WebSocket Request API Documentation;
|
||||
- WebSocket Stream API Documentation;
|
||||
- OpenAPI (Swagger) Specification;
|
||||
- официальных примеров запросов;
|
||||
- официальных примеров ответов.
|
||||
|
||||
Настоящий документ не использует предположения о состоянии рынка и не содержит результатов аналитической интерпретации данных.
|
||||
|
||||
---
|
||||
|
||||
## Связь с архитектурой Dzentra
|
||||
|
||||
Настоящий документ является вторым уровнем архитектуры знаний подсистемы Market Intelligence.
|
||||
|
||||
```text
|
||||
Dzengi API
|
||||
│
|
||||
▼
|
||||
Dzengi Market Data Inventory
|
||||
│
|
||||
▼
|
||||
Dzengi Market Intelligence Information Mapping
|
||||
│
|
||||
▼
|
||||
Dzentra Market Intelligence Information Model
|
||||
│
|
||||
▼
|
||||
Dzentra Market Knowledge Catalogue
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Границы документа
|
||||
|
||||
Настоящий документ описывает исключительно информационные сущности, относящиеся к подсистеме Market Intelligence.
|
||||
|
||||
Документ не содержит:
|
||||
|
||||
- описания операций API;
|
||||
- внутренних моделей данных Dzentra;
|
||||
- знаний о рынке;
|
||||
- правил анализа;
|
||||
- правил торговли;
|
||||
- архитектуры Engine.
|
||||
|
||||
---
|
||||
|
||||
## Термины и определения
|
||||
|
||||
*Derived* — информация, автоматически вычисляемая на основании одной или нескольких информационных сущностей.
|
||||
|
||||
*Endpoint* — операция API, предоставляющая доступ к данным или сервису.
|
||||
|
||||
*Information ID* — канонический идентификатор информационной сущности, используемый во всей платформе Dzentra.
|
||||
|
||||
*JSON Path* — путь к полю внутри JSON-ответа API.
|
||||
|
||||
*Observed* — информация, непосредственно получаемая из внешнего источника данных без дополнительных вычислений.
|
||||
|
||||
---
|
||||
|
||||
## Правила Mapping
|
||||
|
||||
---
|
||||
|
||||
## Стандарт спецификации информационной сущности
|
||||
|
||||
Все информационные сущности настоящего документа описываются по единому шаблону.
|
||||
|
||||
```text
|
||||
### <information_id>
|
||||
|
||||
#### Определение
|
||||
|
||||
...
|
||||
|
||||
#### Тип информации
|
||||
|
||||
Observed | Derived
|
||||
|
||||
#### Источники информации
|
||||
|
||||
| Endpoint | Поле ответа (JSON Path) | Контекст получения |
|
||||
|----------|-------------------------|--------------------|
|
||||
|
||||
#### Зависимости
|
||||
|
||||
...
|
||||
|
||||
#### Использование в Dzentra
|
||||
|
||||
...
|
||||
|
||||
#### Примечания
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Содержание
|
||||
|
||||
---
|
||||
|
||||
## Информационные сущности
|
||||
|
||||
### best_ask_price
|
||||
|
||||
#### Определение
|
||||
|
||||
Лучшая доступная цена продажи (Ask) финансового инструмента в текущем состоянии рынка.
|
||||
|
||||
#### Тип информации
|
||||
|
||||
Observed
|
||||
|
||||
#### Статус исследования
|
||||
|
||||
🟡 Частично подтверждено.
|
||||
|
||||
#### Подтвержденные источники
|
||||
|
||||
| Транспорт | Endpoint | Поле ответа (JSON Path) |
|
||||
|-----------|----------|-------------------------|
|
||||
| REST | `/api/v1/depth` | `asks[0][0]` |
|
||||
| WSS Request | `/api/v1/depth` | `payload.asks[0][0]` |
|
||||
| WSS Stream | `marketData.subscribe` | `payload.ofr` |
|
||||
|
||||
#### Исследуемые источники
|
||||
|
||||
| Транспорт | Endpoint | Поле ответа (JSON Path) | Статус |
|
||||
|-----------|----------|-------------------------|--------|
|
||||
| REST | `/api/v1/ticker/24hr` | `askPrice` | Требует подтверждения эквивалентности |
|
||||
|
||||
#### Зависимости
|
||||
|
||||
Отсутствуют.
|
||||
|
||||
#### Использование в Dzentra
|
||||
|
||||
> **Не определяется настоящим документом.**
|
||||
|
||||
#### Примечания
|
||||
|
||||
Настоящая информационная сущность формируется по результатам исследования фактических ответов API Dzengi.
|
||||
|
||||
Подтверждено, что REST `/api/v1/depth`, WSS Request `/api/v1/depth` и WSS Stream `marketData.subscribe` предоставляют одну и ту же информацию о лучшей цене продажи, отличаясь только способом получения данных.
|
||||
|
||||
Эквивалентность поля `askPrice` endpoint `/api/v1/ticker/24hr` на момент подготовки настоящей редакции документа не подтверждена и требует дополнительного исследования.
|
||||
1
docs/market_intelligence/information/dzengi_openapi.json
Normal file
1
docs/market_intelligence/information/dzengi_openapi.json
Normal file
File diff suppressed because one or more lines are too long
@@ -0,0 +1,295 @@
|
||||
# Dzentra Market Information Catalogue
|
||||
|
||||
## Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|----------|
|
||||
| Документ | Dzentra Market Information Catalogue |
|
||||
| Тип документа | Information Catalogue |
|
||||
| Версия | 0.1 |
|
||||
| Статус | Draft |
|
||||
| Проект | Dzentra |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
## Статус документа
|
||||
|
||||
Настоящий документ определяет официальный реестр информационных показателей и информационных объектов, используемых для понимания рынка криптовалют.
|
||||
|
||||
Документ разрабатывается на основании **Dzentra Market Information Catalogue Architecture Charter**.
|
||||
|
||||
---
|
||||
|
||||
## Назначение
|
||||
|
||||
Настоящий документ определяет информацию, которая может использоваться подсистемой **Market Intelligence** для формирования знаний о рынке криптовалют.
|
||||
|
||||
Catalogue описывает:
|
||||
|
||||
- информационные показатели;
|
||||
- информационные объекты;
|
||||
- их официальные наименования;
|
||||
- канонические имена Dzentra;
|
||||
- определения;
|
||||
- возможные источники получения;
|
||||
- периодичность обновления;
|
||||
- связи между показателями и объектами.
|
||||
|
||||
---
|
||||
|
||||
## Область применения
|
||||
|
||||
Документ применяется при:
|
||||
|
||||
- построении информационной модели Market Intelligence;
|
||||
- разработке Market Knowledge Catalogue;
|
||||
- разработке Market Intelligence Reference Model;
|
||||
- проектировании Knowledge Architecture;
|
||||
- проектировании Engine Specifications;
|
||||
- проверке новых информационных сущностей.
|
||||
|
||||
---
|
||||
|
||||
## Что не входит в область документа
|
||||
|
||||
Документ не определяет:
|
||||
|
||||
- знания о рынке;
|
||||
- торговые сигналы;
|
||||
- торговые стратегии;
|
||||
- правила принятия решений;
|
||||
- алгоритмы анализа;
|
||||
- индикаторы;
|
||||
- программную реализацию;
|
||||
- источники данных как самостоятельные сущности.
|
||||
|
||||
---
|
||||
|
||||
## Цель
|
||||
|
||||
Цель документа — определить автоматически доступную или автоматически вычисляемую информацию, способную повысить качество понимания текущего состояния рынка криптовалют.
|
||||
|
||||
---
|
||||
|
||||
## Основной вопрос документа
|
||||
|
||||
> **Какая информация наиболее существенно влияет на качество понимания текущего состояния рынка криптовалют?**
|
||||
|
||||
---
|
||||
|
||||
# Принцип ранжирования
|
||||
|
||||
Информационные сущности располагаются по степени их вклада в качество понимания рынка.
|
||||
|
||||
Критерий ранжирования:
|
||||
|
||||
> **Насколько ухудшится способность системы понимать рынок, если данная информация будет полностью недоступна?**
|
||||
|
||||
Чем сильнее ухудшается качество модели рынка при отсутствии сущности, тем выше её место в Catalogue.
|
||||
|
||||
---
|
||||
|
||||
# Часть I. Информационные показатели
|
||||
|
||||
Настоящая часть содержит реестр информационных показателей Dzentra.
|
||||
|
||||
Информационный показатель — самостоятельная наблюдаемая характеристика предметной области, имеющая собственное значение.
|
||||
|
||||
---
|
||||
|
||||
## 1. Цена
|
||||
|
||||
### Официальное наименование
|
||||
|
||||
Цена
|
||||
|
||||
### Общепринятые наименования
|
||||
|
||||
- Price
|
||||
- Trade Price
|
||||
- Market Price
|
||||
|
||||
### Каноническое имя Dzentra
|
||||
|
||||
`price`
|
||||
|
||||
### Определение
|
||||
|
||||
Цена — информационный показатель, отражающий числовое значение стоимости анализируемого торгового инструмента в определённый момент времени.
|
||||
|
||||
Цена является самостоятельной информационной сущностью и не зависит от других информационных показателей.
|
||||
|
||||
Каждое значение цены существует только относительно конкретного момента времени.
|
||||
|
||||
### Тип значения
|
||||
|
||||
Decimal
|
||||
|
||||
### Единица измерения
|
||||
|
||||
Единица котирования анализируемого торгового инструмента.
|
||||
|
||||
### Обоснование включения в Catalogue
|
||||
|
||||
Цена является одной из наиболее значимых информационных сущностей для понимания текущего состояния рынка.
|
||||
|
||||
Без информации о цене невозможно определить текущее положение рынка, изменение стоимости торгового инструмента и большинство характеристик рыночного поведения.
|
||||
|
||||
Практически все последующие знания о рынке в той или иной степени используют информацию о цене.
|
||||
|
||||
### Возможные источники получения
|
||||
|
||||
- торговая площадка;
|
||||
- агрегатор рыночных данных;
|
||||
- поставщик исторических данных;
|
||||
- индексный провайдер.
|
||||
|
||||
### Периодичность обновления
|
||||
|
||||
Определяется источником информации.
|
||||
|
||||
Обновление может происходить как при каждом изменении цены, так и через фиксированные интервалы времени.
|
||||
|
||||
### Связанные информационные объекты
|
||||
|
||||
- Сделка (`trade`)
|
||||
- Свеча (`candle`)
|
||||
- Стакан заявок (`order_book`)
|
||||
- Тикер (`ticker`)
|
||||
- Индексная цена
|
||||
- Маркировочная цена
|
||||
|
||||
### Примечания
|
||||
|
||||
Рассматривается как обобщённое понятие стоимости торгового инструмента.
|
||||
|
||||
Специализированные разновидности цены (например, цена последней сделки, лучшая цена покупки, лучшая цена продажи, индексная цена, расчётная цена и другие) рассматриваются как самостоятельные информационные показатели и описываются отдельно.
|
||||
|
||||
Каждое значение цены интерпретируется только совместно с моментом времени, к которому оно относится.
|
||||
|
||||
---
|
||||
|
||||
## 2. Объём
|
||||
|
||||
### Официальное наименование
|
||||
|
||||
Объём
|
||||
|
||||
### Общепринятые наименования
|
||||
|
||||
- Volume
|
||||
- Trade Volume
|
||||
- Trading Volume
|
||||
|
||||
### Каноническое имя Dzentra
|
||||
|
||||
`volume`
|
||||
|
||||
### Определение
|
||||
|
||||
Объём — информационный показатель, отражающий суммарное количество торгового инструмента, участвовавшего в совершённых сделках за определённый интервал времени.
|
||||
|
||||
Объём является самостоятельной информационной сущностью и не зависит от других информационных показателей.
|
||||
|
||||
В отличие от цены, объём не существует в отдельный момент времени и всегда относится к некоторому интервалу наблюдения.
|
||||
|
||||
### Тип значения
|
||||
|
||||
Decimal
|
||||
|
||||
### Единица измерения
|
||||
|
||||
Количество анализируемого торгового инструмента.
|
||||
|
||||
### Обоснование включения в Catalogue
|
||||
|
||||
Объём является одним из наиболее значимых информационных показателей для понимания текущего состояния рынка.
|
||||
|
||||
Информация об объёме позволяет оценить интенсивность торговой активности за рассматриваемый интервал времени и существенно повышает качество интерпретации изменения цены.
|
||||
|
||||
Без информации об объёме невозможно достоверно оценить значимость большинства ценовых изменений.
|
||||
|
||||
### Возможные источники получения
|
||||
|
||||
- торговая площадка;
|
||||
- агрегатор рыночных данных;
|
||||
- поставщик исторических данных.
|
||||
|
||||
### Периодичность обновления
|
||||
|
||||
Определяется используемым интервалом наблюдения и источником информации.
|
||||
|
||||
Обновление может происходить после завершения интервала либо непрерывно по мере накопления данных внутри текущего интервала.
|
||||
|
||||
### Связанные информационные объекты
|
||||
|
||||
- Сделка (`trade`)
|
||||
- Свеча (`candle`)
|
||||
- Тикер (`ticker`)
|
||||
- Агрегированная статистика торгов
|
||||
|
||||
### Примечания
|
||||
|
||||
Рассматривается как обобщённое понятие торгового объёма.
|
||||
|
||||
Специализированные разновидности объёма (например, объём отдельной сделки, объём свечи, объём покупок, объём продаж, суточный объём и другие) рассматриваются как самостоятельные информационные показатели и описываются отдельно.
|
||||
|
||||
Каждое значение объёма интерпретируется только совместно с интервалом времени, к которому оно относится.
|
||||
|
||||
---
|
||||
|
||||
## 3. Время
|
||||
|
||||
### Официальное наименование
|
||||
|
||||
Время
|
||||
|
||||
### Общепринятые наименования
|
||||
|
||||
- Time
|
||||
- Timestamp
|
||||
- Event Time
|
||||
- Open Time
|
||||
- Close Time
|
||||
|
||||
### Каноническое имя Dzentra
|
||||
|
||||
`time`
|
||||
|
||||
### Определение
|
||||
|
||||
Время — значение момента или интервала, к которому относится информационная сущность.
|
||||
|
||||
### Тип значения
|
||||
|
||||
Datetime / Time Interval
|
||||
|
||||
### Единица измерения
|
||||
|
||||
Временная шкала.
|
||||
|
||||
### Возможные источники получения
|
||||
|
||||
- торговая площадка;
|
||||
- поставщик данных;
|
||||
- системное время источника;
|
||||
- календарь публикаций.
|
||||
|
||||
### Периодичность обновления
|
||||
|
||||
Определяется информационным объектом или событием.
|
||||
|
||||
### Связанные информационные объекты
|
||||
|
||||
- Сделка
|
||||
- Свеча
|
||||
- Тикер
|
||||
- Стакан заявок
|
||||
- Funding Snapshot
|
||||
- Макроэкономическая публикация
|
||||
|
||||
### Примечания
|
||||
|
||||
Время является обязательной координатой для сопоставления значений и построения истории рынка.
|
||||
@@ -0,0 +1,434 @@
|
||||
# Dzentra Market Information Catalogue Architecture Charter
|
||||
|
||||
## Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|----------|
|
||||
| Документ | Dzentra Market Information Catalogue Architecture Charter |
|
||||
| Тип документа | Architecture Standard |
|
||||
| Версия | 0.1 |
|
||||
| Статус | Release Candidate |
|
||||
| Проект | Dzentra |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
## Статус документа
|
||||
|
||||
Настоящий документ определяет архитектурные принципы проектирования **Dzentra Market Information Catalogue**.
|
||||
|
||||
До выпуска версии **1.0 Release** допускается изменение структуры и содержания документа при условии сохранения его архитектурной целостности.
|
||||
|
||||
После выпуска версии **1.0 Release** изменение документа допускается только посредством выпуска новой версии стандарта.
|
||||
|
||||
---
|
||||
|
||||
## Назначение
|
||||
|
||||
Настоящий документ устанавливает правила проектирования, наполнения и сопровождения **Dzentra Market Information Catalogue**.
|
||||
|
||||
Документ определяет:
|
||||
|
||||
- границы предметной области;
|
||||
- архитектурные принципы;
|
||||
- правила включения сущностей;
|
||||
- правила описания сущностей;
|
||||
- требования к терминологии;
|
||||
- требования к каноническим идентификаторам;
|
||||
- порядок развития Catalogue.
|
||||
|
||||
Настоящий документ является нормативной основой разработки и сопровождения **Dzentra Market Information Catalogue**.
|
||||
|
||||
---
|
||||
|
||||
## Область применения
|
||||
|
||||
Настоящий документ применяется при:
|
||||
|
||||
- разработке **Dzentra Market Information Catalogue**;
|
||||
- добавлении информационных объектов;
|
||||
- добавлении информационных показателей;
|
||||
- изменении существующих сущностей Catalogue;
|
||||
- архитектурной проверке изменений;
|
||||
- разработке документов, использующих **Dzentra Market Information Catalogue**.
|
||||
|
||||
Положения настоящего документа обязательны для всех редакций **Dzentra Market Information Catalogue**.
|
||||
|
||||
---
|
||||
|
||||
## Что не входит в область документа
|
||||
|
||||
Настоящий документ не определяет:
|
||||
|
||||
- состав информационных объектов;
|
||||
- состав информационных показателей;
|
||||
- модель знаний;
|
||||
- организацию знаний;
|
||||
- онтологию;
|
||||
- программную архитектуру;
|
||||
- программную реализацию;
|
||||
- алгоритмы анализа;
|
||||
- индикаторы;
|
||||
- торговые стратегии;
|
||||
- принятие торговых решений;
|
||||
- исполнение торговых решений.
|
||||
|
||||
Указанные вопросы определяются документами более низкого уровня.
|
||||
|
||||
---
|
||||
|
||||
## Цель
|
||||
|
||||
Цель документа — обеспечить построение единого, непротиворечивого, масштабируемого и независимого от реализации Dzentra Market Information Catalogue, содержащего информацию, обладающую практической ценностью для построения максимально достоверной модели текущего состояния рынка криптовалют.
|
||||
|
||||
Настоящий документ не ставит целью достижение полноты предметной области.
|
||||
|
||||
Catalogue развивается эволюционно по мере углубления понимания предметной области.
|
||||
|
||||
---
|
||||
|
||||
## Основной вопрос документа
|
||||
|
||||
Настоящий документ отвечает на следующий вопрос.
|
||||
|
||||
> **По каким архитектурным принципам должен проектироваться Dzentra Market Information Catalogue, чтобы содержать исключительно информацию, обладающую практической ценностью для понимания текущего состояния рынка криптовалют?**
|
||||
|
||||
---
|
||||
|
||||
# Определение Dzentra Market Information Catalogue
|
||||
|
||||
**Dzentra Market Information Catalogue** — единый официальный нормативный реестр информационных объектов и информационных показателей предметной области Dzentra.
|
||||
|
||||
Catalogue определяет состав информационной модели предметной области и является нормативной основой для всех последующих документов Knowledge Architecture.
|
||||
|
||||
Catalogue не определяет знания о рынке.
|
||||
|
||||
Catalogue определяет исключительно информацию, которая может использоваться для формирования таких знаний.
|
||||
|
||||
---
|
||||
|
||||
# Предметная область
|
||||
|
||||
## Объект моделирования
|
||||
|
||||
Предметной областью **Dzentra Market Information Catalogue** является информация, используемая для построения модели текущего состояния рынка криптовалют.
|
||||
|
||||
Catalogue не описывает рынок, знания о рынке или торговые решения.
|
||||
|
||||
Catalogue описывает исключительно информацию, которая может использоваться для построения знаний о текущем состоянии рынка.
|
||||
|
||||
---
|
||||
|
||||
## Границы предметной области
|
||||
|
||||
В Catalogue включается информация, которая одновременно удовлетворяет следующим условиям:
|
||||
|
||||
- может быть автоматически получена или автоматически вычислена системой;
|
||||
- имеет объективное определение;
|
||||
- не требует человеческой интерпретации;
|
||||
- способна повысить качество понимания рынка криптовалют.
|
||||
|
||||
---
|
||||
|
||||
## Объекты каталогизации
|
||||
|
||||
Catalogue содержит только два типа сущностей:
|
||||
|
||||
- информационные показатели;
|
||||
- информационные объекты.
|
||||
|
||||
Другие типы сущностей в рамках настоящего документа не рассматриваются.
|
||||
|
||||
---
|
||||
|
||||
## Информационный показатель
|
||||
|
||||
Информационный показатель — наблюдаемая характеристика предметной области, имеющая собственное значение и доступная для автоматического получения или вычисления системой.
|
||||
|
||||
---
|
||||
|
||||
## Информационный объект
|
||||
|
||||
Информационный объект — логически связанная совокупность информационных показателей, существующая как единая информационная сущность предметной области.
|
||||
|
||||
---
|
||||
|
||||
## Что не является информационной сущностью
|
||||
|
||||
В Catalogue не включаются:
|
||||
|
||||
### Элементы предметной области
|
||||
|
||||
- торговые инструменты;
|
||||
- торговые площадки;
|
||||
- типы рынков;
|
||||
- валюты;
|
||||
- блокчейны;
|
||||
- организации;
|
||||
- иные именованные сущности предметной области.
|
||||
|
||||
### Архитектурные и вычислительные сущности
|
||||
|
||||
- алгоритмы;
|
||||
- модели анализа;
|
||||
- индикаторы;
|
||||
- торговые стратегии.
|
||||
|
||||
Указанные сущности относятся к словарю предметной области Dzentra и не являются частью настоящего Catalogue.
|
||||
|
||||
# Архитектурные принципы
|
||||
|
||||
## Общие принципы
|
||||
|
||||
### AP-001. Независимость предметной области
|
||||
|
||||
Catalogue описывает предметную область.
|
||||
|
||||
Catalogue не зависит от программной реализации, языка программирования, архитектуры системы и способов хранения данных.
|
||||
|
||||
---
|
||||
|
||||
### AP-002. Независимость от источников данных
|
||||
|
||||
Catalogue описывает информационные сущности независимо от способов их получения.
|
||||
|
||||
Конкретные источники данных являются свойствами информационных сущностей и не определяют структуру Catalogue.
|
||||
|
||||
---
|
||||
|
||||
### AP-003. Независимость от торговых площадок
|
||||
|
||||
Catalogue не зависит от конкретных бирж, брокеров, поставщиков данных или внешних сервисов.
|
||||
|
||||
---
|
||||
|
||||
### AP-004. Независимость от алгоритмов
|
||||
|
||||
Catalogue не содержит алгоритмов анализа, вычислений или обработки информации.
|
||||
|
||||
---
|
||||
|
||||
### AP-005. Независимость от торговых решений
|
||||
|
||||
Catalogue не содержит правил открытия, сопровождения или закрытия позиций.
|
||||
|
||||
---
|
||||
|
||||
## Принципы моделирования
|
||||
|
||||
### AP-006. Каталогизация
|
||||
|
||||
Catalogue содержит только информационные показатели и информационные объекты.
|
||||
|
||||
Другие типы сущностей не допускаются.
|
||||
|
||||
---
|
||||
|
||||
### AP-007. Объективность
|
||||
|
||||
Каждая сущность должна иметь объективное определение.
|
||||
|
||||
Субъективные оценки не допускаются.
|
||||
|
||||
---
|
||||
|
||||
### AP-008. Автоматическая обработка
|
||||
|
||||
Каждая сущность должна быть доступна для автоматического получения или автоматического вычисления системой.
|
||||
|
||||
---
|
||||
|
||||
### AP-009. Информационная ценность
|
||||
|
||||
Каждая сущность включается в Catalogue только в том случае, если она способна повысить качество понимания текущего состояния рынка криптовалют.
|
||||
|
||||
Наличие информации без практической ценности для построения модели рынка не является основанием для включения сущности в Catalogue.
|
||||
|
||||
---
|
||||
|
||||
### AP-010. Приоритет информационной ценности
|
||||
|
||||
Информационные показатели и информационные объекты располагаются в Catalogue по степени их вклада в качество понимания текущего состояния рынка.
|
||||
|
||||
Расположение сущностей не определяется происхождением информации, её предметной областью или способом получения.
|
||||
|
||||
---
|
||||
|
||||
### AP-011. Критерий ранжирования
|
||||
|
||||
Степень важности информационной сущности определяется ухудшением качества понимания рынка при отсутствии данной информации.
|
||||
|
||||
Чем сильнее отсутствие сущности ухудшает качество модели рынка, тем выше её место в Catalogue.
|
||||
|
||||
---
|
||||
|
||||
### AP-012. Однозначность
|
||||
|
||||
Каждая сущность имеет единственное официальное определение в рамках Dzentra.
|
||||
|
||||
---
|
||||
|
||||
## Принципы терминологии
|
||||
|
||||
### AP-013. Единая терминология
|
||||
|
||||
Для каждой сущности используется единый официальный термин Dzentra.
|
||||
|
||||
---
|
||||
|
||||
### AP-014. Общепринятая терминология
|
||||
|
||||
При наличии общепринятого профессионального термина он используется в качестве официального термина Dzentra.
|
||||
|
||||
Если термин неоднозначен, Dzentra определяет собственный официальный термин.
|
||||
|
||||
---
|
||||
|
||||
## Принципы идентификации
|
||||
|
||||
### AP-015. Каноническое имя
|
||||
|
||||
Каждая сущность имеет одно каноническое имя Dzentra.
|
||||
|
||||
Каноническое имя является единственным официальным именем сущности во всей платформе.
|
||||
|
||||
---
|
||||
|
||||
### AP-016. Единственность имени
|
||||
|
||||
Каноническое имя используется во всех документах и компонентах платформы.
|
||||
|
||||
Использование альтернативных имён не допускается.
|
||||
|
||||
Каноническое имя информационной сущности является глобальным идентификатором предметной области Dzentra. Все архитектурные документы и программные компоненты, использующие данную сущность, обязаны ссылаться на неё исключительно посредством её канонического имени.
|
||||
|
||||
---
|
||||
|
||||
## Принципы развития
|
||||
|
||||
### AP-017. Первичность канонического имени
|
||||
|
||||
Каноническое имя сущности определяется до её использования в любом документе или программной реализации.
|
||||
|
||||
### AP-018. Первичность документации
|
||||
|
||||
Любая новая сущность сначала включается в Catalogue.
|
||||
|
||||
До утверждения сущности в Catalogue её использование в документации, архитектуре и программной реализации не допускается.
|
||||
|
||||
### AP-019. Единственность сущности
|
||||
|
||||
Каждая информационная сущность описывается в Catalogue только один раз.
|
||||
|
||||
Дублирование сущностей не допускается.
|
||||
|
||||
### AP-020. Единственность нормативного определения
|
||||
|
||||
Каждое архитектурное правило определяется только в одном месте.
|
||||
|
||||
Повторение нормативных правил в документации не допускается.
|
||||
|
||||
### AP-021. Минимальная достаточность
|
||||
|
||||
Описание каждой сущности должно содержать только сведения, необходимые для её однозначного определения и использования в рамках Information Catalogue.
|
||||
|
||||
Избыточная информация не допускается.
|
||||
|
||||
### AP-022. Эволюционное развитие
|
||||
|
||||
Структура Dzentra Market Information Catalogue может изменяться в процессе развития предметной области.
|
||||
|
||||
Добавление новых разделов, информационных показателей и информационных объектов допускается при соблюдении требований настоящего стандарта.
|
||||
|
||||
### AP-023. Приоритет источников информации
|
||||
|
||||
При наличии нескольких источников одной и той же информационной сущности Dzentra должна определять канонический источник, информация которого считается приоритетной для формирования модели рынка.
|
||||
|
||||
Для информационных сущностей, непосредственно влияющих на исполнение торговых операций, каноническим источником является торговая площадка, на которой осуществляется исполнение сделок.
|
||||
|
||||
---
|
||||
|
||||
# Правила описания сущностей
|
||||
|
||||
## Общие требования
|
||||
|
||||
Каждая сущность Catalogue описывается по единому шаблону.
|
||||
|
||||
Изменение структуры шаблона допускается только посредством изменения настоящего стандарта.
|
||||
|
||||
---
|
||||
|
||||
## Информационный показатель
|
||||
|
||||
Каждый информационный показатель должен содержать:
|
||||
|
||||
- официальное наименование;
|
||||
- общепринятые наименования (при наличии);
|
||||
- каноническое имя Dzentra;
|
||||
- определение;
|
||||
- тип значения;
|
||||
- единицу измерения (при наличии);
|
||||
- обоснование включения в Catalogue;
|
||||
- возможные источники получения;
|
||||
- периодичность обновления;
|
||||
- связанные информационные объекты;
|
||||
- примечания (при необходимости).
|
||||
|
||||
---
|
||||
|
||||
## Информационный объект
|
||||
|
||||
Каждый информационный объект должен содержать:
|
||||
|
||||
- официальное наименование;
|
||||
- общепринятые наименования (при наличии);
|
||||
- каноническое имя Dzentra;
|
||||
- определение;
|
||||
- связанные информационные показатели;
|
||||
- возможные источники получения;
|
||||
- периодичность обновления;
|
||||
- обоснование включения в Catalogue;
|
||||
- примечания (при необходимости).
|
||||
|
||||
---
|
||||
|
||||
## Критерий включения сущностей
|
||||
|
||||
Информационная сущность может быть включена в Catalogue только при одновременном выполнении следующих условий:
|
||||
|
||||
- информация может быть автоматически получена или автоматически вычислена;
|
||||
- информация имеет объективное определение;
|
||||
- информация обладает практической ценностью для понимания текущего состояния рынка;
|
||||
- информация не является торговым решением, алгоритмом или интерпретацией.
|
||||
|
||||
---
|
||||
|
||||
## Требования к определениям
|
||||
|
||||
Определение сущности должно:
|
||||
|
||||
- быть объективным;
|
||||
- быть однозначным;
|
||||
- не зависеть от реализации;
|
||||
- не содержать алгоритмов;
|
||||
- не содержать субъективных оценок.
|
||||
|
||||
---
|
||||
|
||||
## Требования к каноническим именам
|
||||
|
||||
Каноническое имя должно:
|
||||
|
||||
- быть уникальным;
|
||||
- быть неизменяемым;
|
||||
- использоваться во всей платформе Dzentra;
|
||||
- соответствовать официальному наименованию сущности.
|
||||
|
||||
---
|
||||
|
||||
# Управление изменениями
|
||||
|
||||
Изменение настоящего стандарта допускается только при изменении методологии проектирования Dzentra Market Information Catalogue.
|
||||
|
||||
Изменение состава информационных объектов и информационных показателей не является основанием для изменения настоящего документа.
|
||||
0
docs/market_intelligence/knowledge/continuation.md
Normal file
0
docs/market_intelligence/knowledge/continuation.md
Normal file
0
docs/market_intelligence/knowledge/entry_quality.md
Normal file
0
docs/market_intelligence/knowledge/entry_quality.md
Normal file
0
docs/market_intelligence/knowledge/liquidity.md
Normal file
0
docs/market_intelligence/knowledge/liquidity.md
Normal file
0
docs/market_intelligence/knowledge/market_cycle.md
Normal file
0
docs/market_intelligence/knowledge/market_cycle.md
Normal file
0
docs/market_intelligence/knowledge/market_regime.md
Normal file
0
docs/market_intelligence/knowledge/market_regime.md
Normal file
0
docs/market_intelligence/knowledge/momentum.md
Normal file
0
docs/market_intelligence/knowledge/momentum.md
Normal file
0
docs/market_intelligence/knowledge/reversal.md
Normal file
0
docs/market_intelligence/knowledge/reversal.md
Normal file
0
docs/market_intelligence/knowledge/trend.md
Normal file
0
docs/market_intelligence/knowledge/trend.md
Normal file
0
docs/market_intelligence/knowledge/volatility.md
Normal file
0
docs/market_intelligence/knowledge/volatility.md
Normal file
0
docs/market_intelligence/knowledge/wave.md
Normal file
0
docs/market_intelligence/knowledge/wave.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# Dzentra Market Intelligence Reference Model
|
||||
|
||||
## Контроль документа
|
||||
|
||||
Свойство Значение
|
||||
--------------- ---------------------------------------------
|
||||
Документ Dzentra Market Intelligence Reference Model
|
||||
Тип документа Architecture Reference Model
|
||||
Версия 0.1
|
||||
Статус Draft
|
||||
Проект Dzentra
|
||||
Подсистема Market Intelligence
|
||||
Язык Русский
|
||||
|
||||
## Статус документа
|
||||
|
||||
Настоящий документ определяет эталонную модель знаний, используемую подсистемой Market Intelligence проекта Dzentra.
|
||||
|
||||
Документ находится в стадии **Draft**.
|
||||
|
||||
До выпуска версии **1.0 Release** допускается изменение структуры и содержания документа при условии сохранения его архитектурной целостности.
|
||||
|
||||
После выпуска версии **1.0 Release** изменение настоящего документа допускается только посредством выпуска новой версии стандарта.
|
||||
|
||||
## Назначение документа
|
||||
|
||||
Настоящий документ определяет модель знаний, необходимую для построения достоверной модели текущего состояния рынка.
|
||||
|
||||
Документ описывает предметную область рынка и не зависит от конкретной реализации системы.
|
||||
|
||||
Настоящий документ является фундаментом модели знаний подсистемы Market Intelligence и развивает положения Knowledge Architecture Charter.
|
||||
|
||||
Все архитектурные документы более низкого уровня должны основываться на положениях настоящего стандарта и не могут ему противоречить.
|
||||
|
||||
## Область применения
|
||||
|
||||
Настоящий документ применяется при:
|
||||
|
||||
- разработке модели знаний о рынке;
|
||||
- проектировании специализированных доменов знаний;
|
||||
- проектировании Engine;
|
||||
- разработке подсистемы Market Intelligence;
|
||||
- построении Decision Layer;
|
||||
- архитектурной проверке новых компонентов системы.
|
||||
|
||||
Положения настоящего документа являются обязательными для всех компонентов, участвующих в формировании модели рынка.
|
||||
|
||||
## Что не входит в область документа
|
||||
|
||||
Настоящий документ не определяет:
|
||||
|
||||
- программную архитектуру;
|
||||
- программный код;
|
||||
- способы реализации;
|
||||
- используемые алгоритмы;
|
||||
- конкретные методы вычислений;
|
||||
- индикаторы;
|
||||
- торговые стратегии;
|
||||
- правила открытия и закрытия позиций;
|
||||
- методы управления капиталом;
|
||||
- методы управления рисками;
|
||||
- особенности отдельных торговых площадок.
|
||||
|
||||
Все перечисленные вопросы рассматриваются документами более низкого уровня.
|
||||
|
||||
## Цель документа
|
||||
|
||||
Целью настоящего документа является создание формальной, внутренне непротиворечивой и масштабируемой модели знаний о рынке.
|
||||
|
||||
Полученная модель должна быть достаточной для построения максимально достоверной модели текущего состояния рынка независимо от:
|
||||
|
||||
- класса финансового инструмента;
|
||||
- типа рынка;
|
||||
- торговой площадки;
|
||||
- используемого таймфрейма;
|
||||
- программной реализации;
|
||||
- конкретных методов анализа.
|
||||
|
||||
## Главный вопрос документа
|
||||
|
||||
Настоящий документ отвечает на следующий вопрос.
|
||||
|
||||
> **Какими знаниями должна обладать система, чтобы сформировать максимально полное, достоверное и непротиворечивое понимание текущее поведения рынка, его текущее состояние и процесс, который привёл рынок к этому состоянию, независимо от способов получения этих знаний и их последующей интерпретации?**
|
||||
|
||||
Все последующие главы настоящего документа являются последовательным раскрытием ответа на этот вопрос.
|
||||
|
||||
## Фундаментальные аксиомы
|
||||
|
||||
### Аксиома 1. Предмет моделирования
|
||||
|
||||
Предметом моделирования является наблюдаемое поведение рынка.
|
||||
|
||||
Настоящий документ не рассматривает причины возникновения рыночных процессов, если они не могут быть подтверждены наблюдаемыми свойствами рынка.
|
||||
|
||||
### Аксиома 2. Основание знаний
|
||||
|
||||
Любое знание, формируемое системой Dzentra, должно быть основано:
|
||||
|
||||
- либо на непосредственно наблюдаемых свойствах рынка;
|
||||
- либо на логически выводимых следствиях из ранее полученных знаний.
|
||||
|
||||
### Аксиома 3. Объективность модели
|
||||
|
||||
Модель рынка должна описывать рынок таким, каким он наблюдается.
|
||||
|
||||
Модель не должна содержать предположений о намерениях, целях или мотивах участников рынка, если такие предположения не могут быть подтверждены наблюдением.
|
||||
|
||||
### Аксиома 4. Независимость реализации
|
||||
|
||||
Модель знаний не зависит от:
|
||||
|
||||
- языка программирования;
|
||||
- структуры программного обеспечения;
|
||||
- используемых индикаторов;
|
||||
- способа хранения данных;
|
||||
- конкретных алгоритмов анализа.
|
||||
|
||||
Реализация должна соответствовать модели знаний, а не наоборот.
|
||||
|
||||
### Аксиома 5. Независимость от торговых решений
|
||||
|
||||
Модель знаний не принимает торговых решений.
|
||||
|
||||
Торговое решение является отдельным этапом обработки информации и основывается на уже сформированной модели рынка.
|
||||
|
||||
### Аксиома 6. Целостность модели
|
||||
|
||||
Рынок рассматривается как единая взаимосвязанная система.
|
||||
|
||||
Отдельные знания не являются независимыми сигналами.
|
||||
|
||||
Каждое знание рассматривается как часть единой модели текущего состояния рынка.
|
||||
|
||||
# Часть I. Фундамент модели знаний
|
||||
|
||||
Определяет фундаментальные понятия, терминологию, аксиомы и язык модели знаний.
|
||||
|
||||
## 4. Фундаментальные понятия
|
||||
|
||||
### 4.1 Рынок
|
||||
|
||||
#### Назначение
|
||||
|
||||
Настоящий раздел определяет фундаментальное понятие рынка, относительно которого формируются все остальные понятия настоящей модели знаний.
|
||||
|
||||
Все последующие понятия настоящей модели определяются относительно понятия рынка и рассматриваются как описание различных аспектов одной и той же предметной области.
|
||||
|
||||
#### Определение
|
||||
|
||||
**Рынок --- это объективно существующая динамическая система, непрерывно изменяющаяся во времени и доступная для наблюдения.**
|
||||
|
||||
В рамках настоящей модели рынок рассматривается исключительно как предметная область, знания о которой могут быть получены путём последовательного наблюдения, анализа и формализации наблюдаемых
|
||||
характеристик.
|
||||
|
||||
#### Фундаментальные аксиомы
|
||||
|
||||
*Аксиома 4.1.1. Независимость рынка*
|
||||
|
||||
Рынок существует независимо от наблюдателя.
|
||||
|
||||
Его существование не зависит от наличия системы анализа, программной реализации или человека, выполняющего наблюдение.
|
||||
|
||||
*Аксиома 4.1.2. Динамичность рынка*
|
||||
|
||||
Рынок непрерывно изменяется.
|
||||
|
||||
Любая модель рынка описывает рынок только в пределах рассматриваемого интервала наблюдения.
|
||||
|
||||
*Аксиома 4.1.3. Ограниченность познания*
|
||||
|
||||
Рынок не может быть полностью познан посредством одного наблюдения.
|
||||
|
||||
Любые знания о рынке формируются только на основании совокупности наблюдений и их последующего анализа.
|
||||
|
||||
*Аксиома 4.1.4. Разделение рынка и модели*
|
||||
|
||||
Настоящий документ описывает рынок как предметную область.
|
||||
|
||||
Модель рынка является результатом применения положений настоящего стандарта и рассматривается в последующих главах.
|
||||
|
||||
#### Следствия
|
||||
|
||||
Из настоящего определения следуют следующие положения.
|
||||
|
||||
1. Все знания настоящей модели формируются на основе наблюдений рынка.
|
||||
2. Любое знание относится к рынку непосредственно либо выводится логически из ранее полученных знаний.
|
||||
3. Одно наблюдение не может дать полного описания рынка.
|
||||
4. Полная модель текущего состояния рынка формируется посредством объединения различных видов знаний.
|
||||
|
||||
#### Ограничения
|
||||
|
||||
Настоящий раздел не определяет:
|
||||
|
||||
- внутреннее устройство рынка;
|
||||
- причины изменения рынка;
|
||||
- состав участников рынка;
|
||||
- механизмы формирования цены;
|
||||
- механизмы торговли;
|
||||
- экономические модели рынка.
|
||||
|
||||
Указанные вопросы не являются необходимыми для построения формальной модели знаний и рассматриваются только в той мере, в которой они выражаются через наблюдаемые свойства рынка.
|
||||
|
||||
### 4.2 Наблюдение
|
||||
|
||||
(пока пусто)
|
||||
|
||||
### 4.3 Свойство
|
||||
|
||||
(пока пусто)
|
||||
|
||||
### 4.4 Состояние
|
||||
|
||||
(пока пусто)
|
||||
|
||||
### 4.5 Контекст
|
||||
|
||||
(пока пусто)
|
||||
|
||||
### 4.6 Оценка
|
||||
|
||||
(пока пусто)
|
||||
|
||||
### 4.7 Решение
|
||||
|
||||
(пока пусто)
|
||||
|
||||
### 4.8 Иерархия понятий
|
||||
|
||||
(пока пусто)
|
||||
|
||||
# Часть II. Архитектура знаний
|
||||
|
||||
Определяет структуру знаний, их взаимосвязи и принципы формирования модели рынка.
|
||||
|
||||
# Часть III. Модель рынка
|
||||
|
||||
Определяет модель наблюдаемого рынка и её составные элементы.
|
||||
|
||||
# Часть IV. Домены знаний
|
||||
|
||||
Определяет домены знаний, необходимые для формирования полной модели рынка.
|
||||
|
||||
# Часть V. Архитектура Engine
|
||||
|
||||
Определяет принципы распределения доменов знаний между специализированными Engine.
|
||||
|
||||
# Часть VI. Модель состояния рынка
|
||||
|
||||
Определяет состав полной модели текущего состояния рынка.
|
||||
|
||||
# Часть VII. Граница принятия решений
|
||||
|
||||
Определяет границу между моделью знаний и процессом принятия торговых решений.
|
||||
|
||||
# Часть VIII. Развитие стандарта
|
||||
|
||||
Определяет правила развития настоящего стандарта.
|
||||
|
||||
Настоящая вводная часть определяет назначение документа, его границы, фундаментальные аксиомы и общую структуру.
|
||||
|
||||
Все последующие главы посвящены исключительно построению формальной модели знаний о рынке.
|
||||
@@ -0,0 +1,77 @@
|
||||
### 4.1 Рынок
|
||||
|
||||
#### Назначение
|
||||
|
||||
Настоящий раздел определяет фундаментальное понятие рынка, относительно
|
||||
которого формируются все остальные понятия настоящей модели знаний.
|
||||
|
||||
Все последующие определения рассматриваются как описание различных
|
||||
аспектов одного и того же рынка и не могут существовать вне этого
|
||||
понятия.
|
||||
|
||||
#### Определение
|
||||
|
||||
**Рынок --- это объективно существующая динамическая система, непрерывно
|
||||
изменяющаяся во времени и доступная для непосредственного наблюдения.**
|
||||
|
||||
В рамках настоящей модели рынок рассматривается исключительно как
|
||||
предметная область, знания о которой могут быть получены путём
|
||||
последовательного наблюдения, анализа и формализации наблюдаемых
|
||||
характеристик.
|
||||
|
||||
#### Фундаментальные аксиомы
|
||||
|
||||
##### Аксиома 4.1.1. Независимость рынка
|
||||
|
||||
Рынок существует независимо от наблюдателя.
|
||||
|
||||
Его существование не зависит от наличия системы анализа, программной
|
||||
реализации или человека, выполняющего наблюдение.
|
||||
|
||||
##### Аксиома 4.1.2. Динамичность рынка
|
||||
|
||||
Рынок непрерывно изменяется.
|
||||
|
||||
Любая модель рынка описывает рынок только в пределах рассматриваемого
|
||||
интервала наблюдения.
|
||||
|
||||
##### Аксиома 4.1.3. Ограниченность познания
|
||||
|
||||
Рынок не может быть полностью познан посредством одного наблюдения.
|
||||
|
||||
Любые знания о рынке формируются только на основании совокупности
|
||||
наблюдений и их последующего анализа.
|
||||
|
||||
##### Аксиома 4.1.4. Разделение рынка и модели
|
||||
|
||||
Настоящий документ описывает рынок как предметную область.
|
||||
|
||||
Модель рынка является результатом применения положений настоящего
|
||||
стандарта и рассматривается в последующих главах.
|
||||
|
||||
#### Следствия
|
||||
|
||||
Из настоящего определения следуют следующие положения.
|
||||
|
||||
1. Рынок является источником всех наблюдаемых знаний, используемых
|
||||
системой Dzentra.
|
||||
2. Любое знание относится к рынку непосредственно либо выводится
|
||||
логически из ранее полученных знаний.
|
||||
3. Одно наблюдение не может дать полного описания рынка.
|
||||
4. Полная модель текущего состояния рынка формируется посредством
|
||||
объединения различных видов знаний.
|
||||
|
||||
#### Ограничения
|
||||
|
||||
Настоящий раздел не определяет:
|
||||
|
||||
- внутреннее устройство рынка;
|
||||
- причины изменения рынка;
|
||||
- состав участников рынка;
|
||||
- механизмы формирования цены;
|
||||
- механизмы торговли;
|
||||
- экономические модели рынка.
|
||||
|
||||
Указанные вопросы не являются необходимыми для построения формальной
|
||||
модели знаний и рассматриваются только в той мере, в которой они
|
||||
выражаются через наблюдаемые свойства рынка.
|
||||
@@ -0,0 +1,585 @@
|
||||
# Market Intelligence Research Methodology
|
||||
|
||||
## Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|----------|
|
||||
| Документ | Market Intelligence Research Methodology |
|
||||
| Тип документа | Engineering Standard |
|
||||
| Версия | 1.0 |
|
||||
| Статус | Release |
|
||||
| Проект | Dzentra |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# Назначение
|
||||
|
||||
Настоящий документ определяет единую методологию исследования источников рыночной информации.
|
||||
|
||||
Методология применяется при исследовании любых источников данных независимо от:
|
||||
|
||||
- биржи;
|
||||
- транспортного протокола;
|
||||
- версии API;
|
||||
- способа получения данных.
|
||||
|
||||
Настоящий документ определяет общий порядок проведения исследований, но не содержит перечень конкретных проверок.
|
||||
|
||||
Конкретные проверки определяются специализированными документами Research Checklist.
|
||||
|
||||
---
|
||||
|
||||
# Фундаментальная модель исследования
|
||||
|
||||
Подсистема Market Intelligence строится на трех последовательно связанных уровнях.
|
||||
|
||||
```text
|
||||
ФАКТЫ
|
||||
│
|
||||
▼
|
||||
ЗНАНИЯ
|
||||
│
|
||||
▼
|
||||
РЕШЕНИЯ
|
||||
```
|
||||
|
||||
Каждый следующий уровень может строиться исключительно на основании предыдущего.
|
||||
|
||||
---
|
||||
|
||||
## Уровень 1. Факты
|
||||
|
||||
Факты представляют собой объективную информацию, получаемую непосредственно от биржи.
|
||||
|
||||
На данном уровне отсутствует какая-либо интерпретация данных.
|
||||
|
||||
Примеры фактов:
|
||||
|
||||
- bid;
|
||||
- ask;
|
||||
- volume;
|
||||
- trade;
|
||||
- candle;
|
||||
- order book;
|
||||
- funding rate;
|
||||
- open interest;
|
||||
- liquidation.
|
||||
|
||||
Результатом данного уровня являются подтвержденные информационные сущности (Information Facts).
|
||||
|
||||
---
|
||||
|
||||
## Уровень 2. Знания
|
||||
|
||||
Знания представляют собой интерпретацию подтвержденных фактов.
|
||||
|
||||
На данном уровне строится модель состояния рынка.
|
||||
|
||||
Примеры знаний:
|
||||
|
||||
- тренд;
|
||||
- импульс;
|
||||
- ликвидность;
|
||||
- волатильность;
|
||||
- дисбаланс стакана;
|
||||
- направление движения;
|
||||
- фаза рынка;
|
||||
- вероятность продолжения движения;
|
||||
- вероятность разворота.
|
||||
|
||||
Знания никогда не извлекаются непосредственно из API.
|
||||
|
||||
Они формируются исключительно на основании подтвержденных фактов.
|
||||
|
||||
---
|
||||
|
||||
## Уровень 3. Решения
|
||||
|
||||
Решения представляют собой результат работы торговой системы.
|
||||
|
||||
Примеры решений:
|
||||
|
||||
- открыть позицию;
|
||||
- закрыть позицию;
|
||||
- увеличить позицию;
|
||||
- уменьшить позицию;
|
||||
- изменить Stop Loss;
|
||||
- изменить Take Profit;
|
||||
- отказаться от входа в рынок.
|
||||
|
||||
Решения принимаются исключительно на основании знаний.
|
||||
|
||||
Факты не используются для принятия торговых решений напрямую.
|
||||
|
||||
---
|
||||
|
||||
# Основные архитектурные принципы
|
||||
|
||||
## Принцип последовательного построения знаний
|
||||
|
||||
Построение подсистемы Market Intelligence всегда выполняется в следующем порядке:
|
||||
|
||||
1. Исследование фактов.
|
||||
2. Подтверждение фактов.
|
||||
3. Построение модели знаний.
|
||||
4. Принятие решений.
|
||||
|
||||
Нарушение данной последовательности считается архитектурной ошибкой.
|
||||
|
||||
---
|
||||
|
||||
## Принцип отсутствия предположений
|
||||
|
||||
Подсистема Market Intelligence не использует предположения в качестве знаний.
|
||||
|
||||
Любая информационная сущность должна иметь подтвержденный источник происхождения.
|
||||
|
||||
Любое знание должно иметь подтвержденную зависимость от фактов.
|
||||
|
||||
Любое решение должно иметь подтвержденную зависимость от знаний.
|
||||
|
||||
---
|
||||
|
||||
## Принцип полной трассируемости
|
||||
|
||||
Любое торговое решение должно быть полностью прослеживаемо до фактов, полученных непосредственно от биржи.
|
||||
|
||||
Для любого решения должна существовать непрерывная цепочка происхождения информации.
|
||||
|
||||
```text
|
||||
Биржа
|
||||
│
|
||||
▼
|
||||
Факты
|
||||
│
|
||||
▼
|
||||
Знания
|
||||
│
|
||||
▼
|
||||
Решение
|
||||
```
|
||||
|
||||
Каждый переход между уровнями должен быть объяснимым и проверяемым.
|
||||
|
||||
---
|
||||
|
||||
## Принцип воспроизводимости
|
||||
|
||||
Любой вывод, содержащийся в документации Market Intelligence, должен быть воспроизводим.
|
||||
|
||||
Повторное выполнение исследования должно приводить к тем же результатам при одинаковых исходных условиях.
|
||||
|
||||
---
|
||||
|
||||
# Цель исследования
|
||||
|
||||
Любое исследование должно ответить на главный вопрос.
|
||||
|
||||
> **Какие факты о состоянии рынка предоставляет исследуемый источник данных?**
|
||||
|
||||
Исследование не должно ограничиваться описанием структуры API.
|
||||
|
||||
Результатом исследования является выявление подтвержденных информационных сущностей, содержащихся в исследуемом источнике данных.
|
||||
|
||||
---
|
||||
|
||||
# Основные принципы исследования
|
||||
|
||||
## Исследуется источник информации
|
||||
|
||||
Объектом исследования является не программный интерфейс API, а информация, передаваемая данным источником.
|
||||
|
||||
---
|
||||
|
||||
## Исследуются фактические данные
|
||||
|
||||
Все выводы должны подтверждаться одновременно:
|
||||
|
||||
- официальной документацией;
|
||||
- фактическими сообщениями биржи;
|
||||
- экспериментальными исследованиями.
|
||||
|
||||
Если подтверждение отсутствует, вывод считается неподтвержденным.
|
||||
|
||||
---
|
||||
|
||||
## Исследуются информационные факты
|
||||
|
||||
Исследование должно отвечать не на вопрос
|
||||
|
||||
> Какие поля содержит JSON?
|
||||
|
||||
а на вопрос
|
||||
|
||||
> Какие факты о состоянии рынка передает данный источник?
|
||||
|
||||
---
|
||||
|
||||
## Исследования являются воспроизводимыми
|
||||
|
||||
Каждый вывод должен подтверждаться экспериментом, который может быть повторен независимо от автора исследования.
|
||||
|
||||
---
|
||||
|
||||
## Принцип минимально необходимого исследования
|
||||
|
||||
Исследование должно проводиться в объеме, достаточном для подтверждения или опровержения информации, содержащейся в официальной документации.
|
||||
|
||||
Если официальная документация содержит однозначное описание исследуемого аспекта и фактическое поведение API соответствует этому описанию, дополнительные эксперименты не проводятся.
|
||||
|
||||
Экспериментальные исследования выполняются только в случаях, когда:
|
||||
|
||||
- документация отсутствует;
|
||||
- документация неоднозначна;
|
||||
- документация противоречит фактическому поведению API;
|
||||
- требуется определить неописанное поведение системы.
|
||||
|
||||
---
|
||||
|
||||
# Общий процесс исследования
|
||||
|
||||
Любое исследование выполняется в строго определенной последовательности.
|
||||
|
||||
Каждый следующий этап может начинаться только после завершения предыдущего.
|
||||
|
||||
---
|
||||
|
||||
## Этап 1. Изучение официальной документации
|
||||
|
||||
Цель этапа — определить ожидаемое назначение исследуемого источника данных.
|
||||
|
||||
Результат этапа:
|
||||
|
||||
- понимание назначения endpoint;
|
||||
- понимание способа взаимодействия;
|
||||
- понимание ожидаемой структуры сообщений;
|
||||
- определение перечня исследуемых сущностей.
|
||||
|
||||
На данном этапе не делаются выводы о фактическом поведении источника данных.
|
||||
|
||||
---
|
||||
|
||||
## Этап 2. Получение фактических данных
|
||||
|
||||
Цель этапа — получить реальные сообщения исследуемого источника.
|
||||
|
||||
Получение данных выполняется посредством специализированных Probe.
|
||||
|
||||
Результат этапа:
|
||||
|
||||
- реальные сообщения биржи;
|
||||
- реальные ответы endpoint;
|
||||
- реальные особенности поведения;
|
||||
- материал для последующего анализа.
|
||||
|
||||
---
|
||||
|
||||
## Этап 3. Определение типов сообщений
|
||||
|
||||
Для исследуемого источника необходимо определить:
|
||||
|
||||
- все типы сообщений;
|
||||
- назначение каждого типа сообщений;
|
||||
- сообщения, содержащие рыночную информацию;
|
||||
- служебные сообщения;
|
||||
- сообщения управления;
|
||||
- сообщения об ошибках.
|
||||
|
||||
Результатом этапа является классификация сообщений исследуемого источника.
|
||||
|
||||
---
|
||||
|
||||
## Этап 4. Исследование структуры сообщений
|
||||
|
||||
Для каждого типа сообщений необходимо определить:
|
||||
|
||||
- перечень полей;
|
||||
- тип каждого поля;
|
||||
- обязательность поля;
|
||||
- допустимые значения;
|
||||
- ограничения;
|
||||
- взаимное расположение данных.
|
||||
|
||||
Результатом этапа является описание структуры каждого типа сообщений.
|
||||
|
||||
---
|
||||
|
||||
## Этап 5. Исследование семантики
|
||||
|
||||
Для каждого поля необходимо определить:
|
||||
|
||||
- фактическое назначение;
|
||||
- происхождение информации;
|
||||
- ограничения использования;
|
||||
- степень достоверности;
|
||||
- взаимосвязь с другими полями.
|
||||
|
||||
На данном этапе запрещается использовать предположения как подтвержденные знания.
|
||||
|
||||
---
|
||||
|
||||
## Этап 6. Выделение информационных фактов
|
||||
|
||||
На основании исследованных сообщений необходимо определить:
|
||||
|
||||
- какие информационные факты содержит источник;
|
||||
- какие факты можно вычислить непосредственно из сообщения;
|
||||
- какие факты отсутствуют.
|
||||
|
||||
Результатом этапа является перечень информационных фактов, предоставляемых исследуемым источником.
|
||||
|
||||
---
|
||||
|
||||
## Этап 7. Исследование поведения
|
||||
|
||||
Для исследуемого источника необходимо определить:
|
||||
|
||||
- особенности изменения данных;
|
||||
- последовательность сообщений;
|
||||
- взаимосвязь изменений;
|
||||
- особенности временного поведения;
|
||||
- ограничения источника;
|
||||
- особенности протокола.
|
||||
|
||||
Результатом этапа является описание поведения исследуемого источника.
|
||||
|
||||
---
|
||||
|
||||
## Этап 8. Сравнение с другими источниками
|
||||
|
||||
Для каждого информационного факта необходимо определить:
|
||||
|
||||
- существует ли аналогичный источник;
|
||||
- подтверждается ли эквивалентность;
|
||||
- имеются ли различия;
|
||||
- какой источник является приоритетным.
|
||||
|
||||
Эквивалентность считается подтвержденной только после экспериментальной проверки.
|
||||
|
||||
---
|
||||
|
||||
## Этап 9. Формирование экспериментальных выводов
|
||||
|
||||
После завершения исследования все выводы должны быть разделены на следующие категории:
|
||||
|
||||
- подтвержденные;
|
||||
- предварительно подтвержденные;
|
||||
- гипотезы;
|
||||
- опровергнутые.
|
||||
|
||||
Только подтвержденные выводы могут использоваться при построении Information Mapping.
|
||||
|
||||
---
|
||||
|
||||
## Этап 10. Подготовка Endpoint Research
|
||||
|
||||
Результаты исследования оформляются отдельным документом Endpoint Research.
|
||||
|
||||
Документ должен содержать:
|
||||
|
||||
- описание источника;
|
||||
- результаты исследований;
|
||||
- подтвержденные информационные факты;
|
||||
- особенности поведения;
|
||||
- результаты сравнений;
|
||||
- экспериментальные выводы.
|
||||
|
||||
Endpoint Research является основным документом, описывающим исследуемый источник данных.
|
||||
|
||||
---
|
||||
|
||||
## Этап 11. Обновление Information Mapping
|
||||
|
||||
После подтверждения информационных фактов обновляется документ:
|
||||
|
||||
> Dzengi Market Intelligence Information Mapping.
|
||||
|
||||
В Information Mapping включаются только подтвержденные информационные факты.
|
||||
|
||||
---
|
||||
|
||||
## Этап 12. Обновление Information Model
|
||||
|
||||
Если исследование выявило новые информационные факты или новые взаимосвязи между ними, обновляется документ:
|
||||
|
||||
> Dzentra Market Intelligence Information Model.
|
||||
|
||||
---
|
||||
|
||||
## Этап 13. Обновление Knowledge Catalogue
|
||||
|
||||
Если исследование позволило сформировать новые знания о рынке, обновляется документ:
|
||||
|
||||
> Dzentra Market Knowledge Catalogue.
|
||||
|
||||
Knowledge Catalogue никогда не строится непосредственно на данных API.
|
||||
|
||||
Он строится исключительно на основании подтвержденных информационных фактов и Information Model.
|
||||
|
||||
---
|
||||
|
||||
## Этап 14. Завершение исследования
|
||||
|
||||
Исследование считается завершенным только при выполнении всех следующих условий:
|
||||
|
||||
- подготовлен Endpoint Research;
|
||||
- обновлен Information Mapping;
|
||||
- при необходимости обновлена Information Model;
|
||||
- при необходимости обновлен Knowledge Catalogue;
|
||||
- все выводы имеют степень подтверждения.
|
||||
|
||||
После завершения исследования результаты могут использоваться другими подсистемами Dzentra.
|
||||
|
||||
---
|
||||
|
||||
# Степени подтверждения
|
||||
|
||||
Любой вывод, содержащийся в документации Market Intelligence, должен иметь явно указанную степень подтверждения.
|
||||
|
||||
Использование неподтвержденных выводов в качестве знаний запрещается.
|
||||
|
||||
| Статус | Описание |
|
||||
|---------|----------|
|
||||
| Не исследовано | Исследование соответствующего вопроса не проводилось. |
|
||||
| Гипотеза | Имеется предположение, основанное на документации или наблюдениях, но отсутствует экспериментальное подтверждение. |
|
||||
| Предварительно подтверждено | Подтверждено ограниченным количеством экспериментов. Требуется дополнительная проверка. |
|
||||
| Подтверждено | Подтверждено официальной документацией и экспериментальными исследованиями либо многократно подтверждено экспериментально. |
|
||||
| Опровергнуто | Экспериментально доказано отсутствие соответствия первоначальному предположению. |
|
||||
|
||||
---
|
||||
|
||||
# Критерии качества исследования
|
||||
|
||||
Исследование считается качественно выполненным, если выполняются все следующие условия.
|
||||
|
||||
## Полнота
|
||||
|
||||
Исследованы все типы сообщений исследуемого источника.
|
||||
|
||||
Исследованы все поля сообщений.
|
||||
|
||||
Исследованы все информационные факты.
|
||||
|
||||
---
|
||||
|
||||
## Подтверждаемость
|
||||
|
||||
Каждый вывод имеет экспериментальное подтверждение либо явно обозначен как гипотеза.
|
||||
|
||||
---
|
||||
|
||||
## Воспроизводимость
|
||||
|
||||
Любой эксперимент может быть повторен другим разработчиком и привести к тем же результатам.
|
||||
|
||||
---
|
||||
|
||||
## Трассируемость
|
||||
|
||||
Каждый информационный факт имеет подтвержденный источник происхождения.
|
||||
|
||||
Каждое знание имеет подтвержденную зависимость от информационных фактов.
|
||||
|
||||
Каждое торговое решение должно быть объяснимо через цепочку:
|
||||
|
||||
```text
|
||||
Биржа
|
||||
│
|
||||
▼
|
||||
Информационные факты
|
||||
│
|
||||
▼
|
||||
Знания
|
||||
│
|
||||
▼
|
||||
Решение
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Документированность
|
||||
|
||||
Все результаты исследования отражены в соответствующих документах:
|
||||
|
||||
- Endpoint Research;
|
||||
- Information Mapping;
|
||||
- Information Model;
|
||||
- Knowledge Catalogue.
|
||||
|
||||
---
|
||||
|
||||
# Жизненный цикл исследований
|
||||
|
||||
Исследование источников рыночной информации является непрерывным процессом.
|
||||
|
||||
Появление новых возможностей API, изменение поведения биржи или обнаружение новых фактов требует повторного проведения соответствующих исследований.
|
||||
|
||||
Исследование никогда не считается завершенным окончательно.
|
||||
|
||||
Каждый исследованный источник может быть повторно исследован при появлении новых обстоятельств.
|
||||
|
||||
---
|
||||
|
||||
## Основания для повторного исследования
|
||||
|
||||
Повторное исследование выполняется при возникновении одного или нескольких следующих событий:
|
||||
|
||||
- выпуск новой версии API;
|
||||
- изменение структуры сообщений;
|
||||
- появление новых полей;
|
||||
- изменение семантики существующих полей;
|
||||
- обнаружение противоречий между источниками;
|
||||
- получение новых экспериментальных данных;
|
||||
- обнаружение ошибок предыдущих исследований;
|
||||
- изменение архитектурных требований Dzentra.
|
||||
|
||||
---
|
||||
|
||||
# Использование результатов исследований
|
||||
|
||||
Результаты исследований используются исключительно как источник подтвержденных информационных фактов.
|
||||
|
||||
Настоящий документ не определяет:
|
||||
|
||||
- архитектуру Engine;
|
||||
- алгоритмы анализа рынка;
|
||||
- методы прогнозирования;
|
||||
- торговые стратегии;
|
||||
- правила управления капиталом;
|
||||
- правила открытия или закрытия позиций.
|
||||
|
||||
Указанные вопросы рассматриваются отдельными архитектурными документами Dzentra.
|
||||
|
||||
---
|
||||
|
||||
# Связанные документы
|
||||
|
||||
Настоящий документ используется совместно со следующими документами:
|
||||
|
||||
- Market Intelligence Stream Research Checklist;
|
||||
- Market Intelligence REST Research Checklist;
|
||||
- Market Intelligence WebSocket Request Research Checklist;
|
||||
- Endpoint Research;
|
||||
- Dzengi Market Intelligence Information Mapping;
|
||||
- Dzentra Market Intelligence Information Model;
|
||||
- Dzentra Market Knowledge Catalogue.
|
||||
|
||||
---
|
||||
|
||||
# Заключение
|
||||
|
||||
Настоящая методология определяет единый инженерный подход к исследованию источников рыночной информации.
|
||||
|
||||
Все знания, используемые подсистемой Market Intelligence, должны быть построены исключительно на основании подтвержденных информационных фактов.
|
||||
|
||||
Таким образом обеспечиваются:
|
||||
|
||||
- воспроизводимость исследований;
|
||||
- объяснимость полученных знаний;
|
||||
- трассируемость торговых решений;
|
||||
- независимость знаний от конкретной реализации API;
|
||||
- возможность повторного исследования при изменении источников данных.
|
||||
|
||||
Следование настоящей методологии является обязательным требованием при разработке и сопровождении подсистемы Market Intelligence проекта Dzentra.
|
||||
@@ -0,0 +1,341 @@
|
||||
# Stream Research Protocol — marketData.subscribe
|
||||
|
||||
## Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|----------|----------|
|
||||
| Документ | Stream Research Protocol — marketData.subscribe |
|
||||
| Тип документа | Research Protocol |
|
||||
| Версия | 2.0 |
|
||||
| Статус | Draft |
|
||||
| Проект | Dzentra |
|
||||
| Подсистема | Market Intelligence |
|
||||
| Биржа | Dzengi |
|
||||
| Endpoint | `marketData.subscribe` |
|
||||
| Транспорт | WebSocket Stream |
|
||||
| Основан на | Market Intelligence Stream Research Standard |
|
||||
| Язык | Русский |
|
||||
|
||||
---
|
||||
|
||||
# 1. Исследование подключения
|
||||
|
||||
## 1.1 Подключение
|
||||
|
||||
### 1.1.1 Корректность подключения
|
||||
|
||||
- [x] корректность подключения — подтверждена.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
Получено успешное подключение к WebSocket API Dzengi.
|
||||
|
||||
Получено подтверждение подписки.
|
||||
|
||||
После подтверждения подписки начинают поступать сообщения `internal.quote`.
|
||||
|
||||
---
|
||||
|
||||
### 1.1.2 Требования к соединению
|
||||
|
||||
- [x] URL подключения — соответствует документации.
|
||||
- [x] используемый транспорт (WS/WSS) — соответствует документации.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
**URL подключения**
|
||||
|
||||
Production: `wss://api-adapter.dzengi.com/connect`
|
||||
Demo: `wss://demo-api-adapter.dzengi.com/connect`
|
||||
|
||||
**Используемый транспорт**
|
||||
|
||||
`WSS (WebSocket Secure)`
|
||||
|
||||
---
|
||||
|
||||
### 1.1.3 Требования к авторизации
|
||||
|
||||
- [x] требуется ли авторизация — соответствует документации.
|
||||
- [x] механизм авторизации — соответствует документации.
|
||||
- [x] обязательные заголовки авторизации — соответствует документации.
|
||||
- [x] возможность работы без авторизации — соответствует документации.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
Публичный поток `marketData.subscribe` доступен без передачи данных авторизации.
|
||||
|
||||
---
|
||||
|
||||
### 1.2 Подписка
|
||||
|
||||
- [x] формат подписки — частично соответствует документации;
|
||||
- [x] подтверждение подписки — соответствует документации;
|
||||
- [x] сообщения об ошибках — определено экспериментально;
|
||||
- [х] повторная подписка — определено экспериментально;
|
||||
- [x] подписка на несколько инструментов — определено экспериментально.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
**Формат подписки**
|
||||
|
||||
Документация описывает только содержимое `payload`:
|
||||
|
||||
```
|
||||
{
|
||||
"symbols": [
|
||||
"string"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Фактический формат сообщения, передаваемого через WebSocket /connect:
|
||||
|
||||
```
|
||||
{
|
||||
"correlationId": "...",
|
||||
"destination": "marketData.subscribe",
|
||||
"payload": {
|
||||
"symbols": [
|
||||
"BTC/USD_LEVERAGE"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Подтверждение подписки**
|
||||
|
||||
```
|
||||
{
|
||||
"destination": "marketData.subscribe",
|
||||
"status": "OK",
|
||||
"payload": {
|
||||
"subscriptions": {
|
||||
"BTC/USD_LEVERAGE": "PROCESSED"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Сообщения об ошибках**
|
||||
|
||||
Экспериментально зафиксированы варианты ошибок:
|
||||
|
||||
- `INVALID/SYMBOL` возвращает `status = OK`, но в `payload.subscriptions` указывается `ERROR: INVALID/SYMBOL not found`.
|
||||
- пустой `symbols` возвращает `status = ERROR`, `code = -1128`.
|
||||
- отсутствующий `symbols` возвращает `status = ERROR`, `code = -1128`.
|
||||
- отсутствующий `payload` возвращает `status = ERROR`, `code = -1128`.
|
||||
- неверный `destination` возвращает `status = ERROR`, `errorCode = BAD_REQUEST`.
|
||||
|
||||
**Повторная подписка**
|
||||
|
||||
- первая подписка получает статус `PROCESSED`;
|
||||
- повторные подписки получают статус `ALREADY_SUBSCRIBED`;
|
||||
- сообщения об ошибке не формируются;
|
||||
- повторная подписка работает без предварительной отмены;
|
||||
- в проведенных экспериментах признаков дублирования сообщений `internal.quote` не обнаружено.
|
||||
|
||||
**Подписка на несколько инструментов**
|
||||
|
||||
Экспериментально установлено:
|
||||
|
||||
- команда `marketData.subscribe` принимает несколько торговых инструментов;
|
||||
- подтверждение подписки содержит отдельный статус для каждого инструмента;
|
||||
- поток `internal.quote` передает сообщения для всех подписанных инструментов через одно WebSocket-соединение;
|
||||
- принадлежность сообщения к инструменту определяется полем `payload.symbolName`.
|
||||
|
||||
---
|
||||
|
||||
# 2. Исследование структуры потока
|
||||
|
||||
## 2.1 Типы сообщений
|
||||
|
||||
- [ ] назначение;
|
||||
- [ ] содержит ли рыночную информацию;
|
||||
- [ ] содержит ли служебную информацию;
|
||||
- [ ] содержит ли ошибки;
|
||||
- [ ] содержит ли подтверждение подписки;
|
||||
- [ ] содержит ли подтверждение отписки.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
## 2.2 Структура сообщений
|
||||
|
||||
- [ ] обязательные поля;
|
||||
- [ ] необязательные поля;
|
||||
- [ ] тип каждого поля;
|
||||
- [ ] допустимые значения;
|
||||
- [ ] диапазоны значений;
|
||||
- [ ] ограничения.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
# 3. Классификация сообщений
|
||||
|
||||
- [ ] рыночное сообщение;
|
||||
- [ ] служебное сообщение;
|
||||
- [ ] сообщение управления;
|
||||
- [ ] сообщение об ошибке;
|
||||
- [ ] сообщение подтверждения.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
# 4. Исследование семантики полей
|
||||
|
||||
- [ ] фактическое назначение;
|
||||
- [ ] источник происхождения;
|
||||
- [ ] обязательность;
|
||||
- [ ] изменяемость;
|
||||
- [ ] диапазон допустимых значений;
|
||||
- [ ] взаимосвязь с другими полями;
|
||||
- [ ] ограничения использования;
|
||||
- [ ] степень подтверждения семантики.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
# 5. Исследование информационных фактов
|
||||
|
||||
- [ ] какие информационные факты содержит сообщение;
|
||||
- [ ] какие информационные факты могут быть вычислены непосредственно из сообщения;
|
||||
- [ ] какие информационные факты отсутствуют;
|
||||
- [ ] какие информационные факты являются первичными;
|
||||
- [ ] какие информационные факты являются производными.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
## 5.1 Первичные информационные факты
|
||||
|
||||
- [ ] источник происхождения;
|
||||
- [ ] поле сообщения;
|
||||
- [ ] степень подтверждения;
|
||||
- [ ] ограничения использования.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
## 5.2 Производные информационные факты
|
||||
|
||||
- [ ] формула вычисления;
|
||||
- [ ] необходимые исходные данные;
|
||||
- [ ] ограничения вычисления;
|
||||
- [ ] степень достоверности.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
# 6. Исследование поведения потока
|
||||
|
||||
## 6.1 Частота сообщений
|
||||
|
||||
- [ ] минимальная частота;
|
||||
- [ ] максимальная частота;
|
||||
- [ ] средняя частота;
|
||||
- [ ] пиковая частота;
|
||||
- [ ] условия изменения частоты.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
## 6.2 Последовательность сообщений
|
||||
|
||||
- [ ] порядок поступления сообщений;
|
||||
- [ ] последовательность timestamp;
|
||||
- [ ] наличие пропусков;
|
||||
- [ ] наличие повторяющихся сообщений;
|
||||
- [ ] возможность нарушения порядка.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
## 6.3 Полнота сообщений
|
||||
|
||||
- [ ] полный снимок состояния;
|
||||
- [ ] инкрементальные изменения;
|
||||
- [ ] смешанный режим передачи;
|
||||
- [ ] обязательность всех полей;
|
||||
- [ ] возможность частичных обновлений.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
# 7. Исследование поведения данных
|
||||
|
||||
- [ ] условия появления;
|
||||
- [ ] условия изменения;
|
||||
- [ ] условия исчезновения;
|
||||
- [ ] частота изменения;
|
||||
- [ ] взаимосвязь с другими фактами.
|
||||
|
||||
---
|
||||
|
||||
## Дополнительно определить
|
||||
|
||||
- [ ] какие факты изменяются одновременно;
|
||||
- [ ] какие факты никогда не изменяются одновременно;
|
||||
- [ ] какие факты являются независимыми;
|
||||
- [ ] какие факты являются производными от других.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
# 8. Проверка эквивалентности
|
||||
|
||||
- [ ] существует ли аналогичный источник;
|
||||
- [ ] полностью ли совпадает значение;
|
||||
- [ ] совпадает ли семантика;
|
||||
- [ ] совпадает ли точность;
|
||||
- [ ] совпадает ли момент обновления;
|
||||
- [ ] имеются ли расхождения.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
## 8.1 Альтернативные источники
|
||||
|
||||
- [ ] REST endpoint;
|
||||
- [ ] WebSocket Request;
|
||||
- [ ] другие Stream;
|
||||
- [ ] внутренние вычисления.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
## 8.2 Приоритет источников
|
||||
|
||||
- [ ] основной источник;
|
||||
- [ ] резервный источник;
|
||||
- [ ] допустимые альтернативы;
|
||||
- [ ] причины выбора приоритетного источника.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
---
|
||||
|
||||
# 9. Исследование производительности
|
||||
|
||||
- [ ] средний размер сообщения;
|
||||
- [ ] максимальный размер сообщения;
|
||||
- [ ] средняя скорость передачи;
|
||||
- [ ] максимальная скорость передачи;
|
||||
- [ ] объём данных в минуту;
|
||||
- [ ] объём данных в час.
|
||||
|
||||
#### Журнал исследования
|
||||
@@ -0,0 +1,46 @@
|
||||
### 1.1.4 Дополнительные требования клиента
|
||||
|
||||
- [x] обязательный формат сообщений — частично соответствует документации;
|
||||
- [ ] поддержание соединения;
|
||||
- [x] heartbeat / keepalive / ping-pong — определено экспериментально;
|
||||
- [ ] автоматическое закрытие соединения;
|
||||
- [ ] idle timeout;
|
||||
- [ ] требования к кодировке;
|
||||
- [ ] другие обязательные требования.
|
||||
|
||||
#### Журнал исследования
|
||||
|
||||
**Обязательный формат сообщений**
|
||||
|
||||
Документация указывает формат payload (json):
|
||||
|
||||
```
|
||||
{
|
||||
"symbols": [
|
||||
"string"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Фактический формат сообщения через WebSocket /connect:
|
||||
|
||||
```
|
||||
{
|
||||
"correlationId": "...",
|
||||
"destination": "marketData.subscribe",
|
||||
"payload": {
|
||||
"symbols": ["BTC/USD_LEVERAGE"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Поддержание соединения**
|
||||
|
||||
Документация требований не содержит.
|
||||
|
||||
За время наблюдения получены сообщения только следующих типов:
|
||||
|
||||
- `marketData.subscribe`
|
||||
- `internal.quote`
|
||||
|
||||
Специальные сообщения heartbeat / keepalive / ping / pong не обнаружены.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user