Build 060.25: implement Production Runtime Integration
This commit is contained in:
557
docs/architecture/dzentra_target_architecture.md
Normal file
557
docs/architecture/dzentra_target_architecture.md
Normal file
@@ -0,0 +1,557 @@
|
||||
# Dzentra Target Architecture
|
||||
|
||||
## Контроль документа
|
||||
|
||||
| Свойство | Значение |
|
||||
|---|---|
|
||||
| Тип | Target Architecture |
|
||||
| Статус | Active Baseline |
|
||||
| Версия | 1.0 |
|
||||
| Дата | 2026-07-31 |
|
||||
| Проект | Dzentra |
|
||||
|
||||
---
|
||||
|
||||
## 1. Назначение
|
||||
|
||||
Документ фиксирует целевую архитектурную карту Dzentra и связывает:
|
||||
|
||||
- фактическую структуру существующего проекта;
|
||||
- выполняемую Build-by-Build миграцию;
|
||||
- будущие подсистемы профессиональной автоматической торговой системы;
|
||||
- обязательное направление зависимостей между доменами.
|
||||
|
||||
Документ не требует немедленного создания всех перечисленных каталогов
|
||||
и не заменяет архитектурные спецификации отдельных Build.
|
||||
|
||||
Целевая архитектура отвечает на вопрос:
|
||||
|
||||
> Какие ответственности должны существовать в системе и как они могут
|
||||
> взаимодействовать?
|
||||
|
||||
Последовательность реализации и текущий статус определяет
|
||||
`docs/roadmap/master-roadmap.md`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Текущий контекст
|
||||
|
||||
Dzentra является работающим modular monolith, который постепенно
|
||||
мигрирует из Telegram trading bot в модульную алгоритмическую торговую
|
||||
платформу.
|
||||
|
||||
Проект не является greenfield-системой. В нём одновременно существуют:
|
||||
|
||||
- принятые новые архитектурные слои;
|
||||
- рабочие legacy-компоненты;
|
||||
- временные compatibility boundaries;
|
||||
- будущие целевые подсистемы.
|
||||
|
||||
Поэтому целевой каталог нельзя создавать механическим переносом файлов.
|
||||
Любое изменение ownership или направления зависимостей выполняется
|
||||
отдельным Build после анализа фактических consumers.
|
||||
|
||||
---
|
||||
|
||||
## 3. Верхнеуровневая карта
|
||||
|
||||
```text
|
||||
External Exchanges and Data Sources
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────────────┐
|
||||
│ Market Data │
|
||||
│ Acquisition → Canonicalization → Quality │
|
||||
│ │ │
|
||||
│ ├── Live / Operational │
|
||||
│ └── Storage → Replay │
|
||||
└───────────────────────────────────────────────┘
|
||||
│ Canonical Live or Replay Data
|
||||
▼
|
||||
┌───────────────────────────────────────────────┐
|
||||
│ Market Intelligence │
|
||||
│ Processing → Features → Market State │
|
||||
│ → Scenario Evaluation │
|
||||
└───────────────────────────────────────────────┘
|
||||
│ Analysis Results
|
||||
▼
|
||||
┌───────────────────────────────────────────────┐
|
||||
│ Trading │
|
||||
│ Strategy / Decision → Portfolio / Risk │
|
||||
│ → Order Management → Execution │
|
||||
│ → Position and Account Reconciliation │
|
||||
└───────────────────────────────────────────────┘
|
||||
│ Commands and Reports
|
||||
▼
|
||||
Exchange
|
||||
```
|
||||
|
||||
Все уровни обслуживаются общей Platform-плоскостью:
|
||||
|
||||
```text
|
||||
Runtime and Scheduling
|
||||
Event Contracts
|
||||
Configuration and Secrets
|
||||
Logging, Audit and Observability
|
||||
Resilience and Recovery
|
||||
Security
|
||||
Deployment and Operations
|
||||
```
|
||||
|
||||
Logging, Audit, Monitoring и Runtime не являются последними этапами
|
||||
торгового конвейера. Они действуют на всех уровнях системы.
|
||||
|
||||
---
|
||||
|
||||
## 4. Market Data
|
||||
|
||||
### 4.1. Market Data Acquisition
|
||||
|
||||
**Назначение:** получение внешних рыночных и справочных данных.
|
||||
|
||||
Целевые семейства Feed:
|
||||
|
||||
- Instrument Reference Data;
|
||||
- Quotes;
|
||||
- OHLCV / Candles;
|
||||
- Trades / Time & Sales;
|
||||
- Order Book;
|
||||
- Derivatives Market Data;
|
||||
- Market Index;
|
||||
- Exchange Time;
|
||||
- Exchange and Instrument Status.
|
||||
|
||||
Каждый Feed развивается как самостоятельный vertical slice:
|
||||
|
||||
```text
|
||||
external document
|
||||
↓
|
||||
schema validation
|
||||
↓
|
||||
parser / transport model
|
||||
↓
|
||||
value validation
|
||||
↓
|
||||
mapper
|
||||
↓
|
||||
canonical model
|
||||
↓
|
||||
handler / feed / service
|
||||
```
|
||||
|
||||
REST и WebSocket могут иметь независимые transport pipelines, но до
|
||||
передачи downstream обязаны сходиться в одну source-independent
|
||||
Canonical Model.
|
||||
|
||||
**Текущее размещение:**
|
||||
|
||||
```text
|
||||
app/src/market_data/acquisition/
|
||||
```
|
||||
|
||||
**Текущий активный результат:** Production Runtime для Trades Feed
|
||||
завершён в Build 060.25.
|
||||
|
||||
### 4.2. Validation, Canonicalization and Data Quality
|
||||
|
||||
**Назначение:**
|
||||
|
||||
- проверять структуру внешних документов;
|
||||
- проверять допустимость значений;
|
||||
- нормализовать время, числовые значения и идентификаторы;
|
||||
- преобразовывать transport data в Canonical Models;
|
||||
- контролировать дубликаты, порядок и пропуски;
|
||||
- формировать явные признаки качества и freshness.
|
||||
|
||||
Эта ответственность сейчас распределена между:
|
||||
|
||||
```text
|
||||
adapters/
|
||||
validation/
|
||||
models/
|
||||
consistency/
|
||||
recovery/
|
||||
```
|
||||
|
||||
Build 061.00 должен сначала проверить фактические границы, а уже затем
|
||||
решить, требуется ли отдельный каталог `normalization`.
|
||||
|
||||
Schema Validation, Value Validation, Mapping, Stream Consistency и
|
||||
Missing Data Recovery не должны смешиваться в один универсальный
|
||||
компонент.
|
||||
|
||||
### 4.3. Operational Market State
|
||||
|
||||
Оперативное состояние необходимо для работы активного потока:
|
||||
|
||||
- последний принятый Trade;
|
||||
- deduplication window;
|
||||
- состояние подписок;
|
||||
- connection generation;
|
||||
- liveness и reconnect state.
|
||||
|
||||
Оно не является долговременной историей рынка.
|
||||
|
||||
`TradeStreamState` принадлежит Consistency Layer, а не общему Market
|
||||
Data Storage и не WebSocket Transport.
|
||||
|
||||
### 4.4. Persistent Market Data Storage
|
||||
|
||||
**Назначение:** долговременно хранить Canonical Market Data для:
|
||||
|
||||
- восстановления после перезапуска;
|
||||
- исторических запросов;
|
||||
- Replay;
|
||||
- разработки и проверки аналитики;
|
||||
- backtesting;
|
||||
- аудита качества данных.
|
||||
|
||||
Хранилище должно определить:
|
||||
|
||||
- raw и canonical retention policy;
|
||||
- ключи идемпотентности;
|
||||
- порядок и уникальность событий;
|
||||
- партиционирование по типу данных, символу и времени;
|
||||
- правила исправления и повторной загрузки;
|
||||
- provenance и версию Canonical schema.
|
||||
|
||||
Существующий `app/src/storage/` нельзя автоматически считать готовым
|
||||
Market Data Storage. Его фактические контракты проверяются в
|
||||
Build 060.27.
|
||||
|
||||
### 4.5. Historical Access and Replay
|
||||
|
||||
**Назначение:**
|
||||
|
||||
- исторические запросы;
|
||||
- последовательное воспроизведение Canonical Market Data;
|
||||
- управляемые виртуальные часы;
|
||||
- одинаковые контракты данных для production и replay consumers;
|
||||
- основа backtesting и воспроизводимой диагностики.
|
||||
|
||||
Replay должен воспроизводить порядок событий и не обходить Canonical
|
||||
Models или validation guarantees.
|
||||
|
||||
---
|
||||
|
||||
## 5. Market Intelligence
|
||||
|
||||
### 5.1. Market Data Processing
|
||||
|
||||
Формирует устойчивое состояние и базовые рыночные представления:
|
||||
|
||||
- Candle aggregation;
|
||||
- Order Book reconstruction;
|
||||
- best bid / ask / mid / spread;
|
||||
- trade-flow aggregation;
|
||||
- временные окна;
|
||||
- подтверждённые market events.
|
||||
|
||||
Processing не принимает торговых решений.
|
||||
|
||||
### 5.2. Feature Engineering
|
||||
|
||||
Формирует производные признаки:
|
||||
|
||||
- returns и momentum;
|
||||
- volatility;
|
||||
- relative и abnormal volume;
|
||||
- trade-flow intensity и delta;
|
||||
- Order Book imbalance и microprice;
|
||||
- liquidity;
|
||||
- time/session features;
|
||||
- statistical и cross-market features;
|
||||
- derivatives features.
|
||||
|
||||
Canonical Trade price, quantity и timestamp уже являются исходными
|
||||
данными и не требуют отдельного дублирующего Trade Facts model без
|
||||
подтверждённого consumer.
|
||||
|
||||
### 5.3. Market State Estimation
|
||||
|
||||
Интерпретирует признаки и определяет:
|
||||
|
||||
- market structure;
|
||||
- trend и range;
|
||||
- momentum и correction;
|
||||
- volatility regime;
|
||||
- liquidity regime;
|
||||
- order-flow state;
|
||||
- market phase;
|
||||
- microstructure context.
|
||||
|
||||
**Текущее основное размещение:**
|
||||
|
||||
```text
|
||||
app/src/trading/market_intelligence/
|
||||
```
|
||||
|
||||
Изменение этого ownership требует отдельного архитектурного Build.
|
||||
|
||||
### 5.4. Scenario Evaluation
|
||||
|
||||
Dzentra рассматривает прогнозирование как оценку нескольких возможных
|
||||
сценариев:
|
||||
|
||||
- scenario generation;
|
||||
- probability estimation;
|
||||
- ranking;
|
||||
- confidence and uncertainty.
|
||||
|
||||
Scenario Evaluation является опциональной аналитической возможностью.
|
||||
Strategy, которой отдельный прогноз не требуется, не должна создавать
|
||||
фиктивную зависимость от Forecasting.
|
||||
|
||||
---
|
||||
|
||||
## 6. Trading
|
||||
|
||||
### 6.1. Strategy and Trading Decision
|
||||
|
||||
Преобразует рыночный анализ в торговое намерение:
|
||||
|
||||
- enter;
|
||||
- hold;
|
||||
- reduce;
|
||||
- exit;
|
||||
- do nothing.
|
||||
|
||||
Результат Decision не является биржевым ордером и не должен напрямую
|
||||
вызывать Transport.
|
||||
|
||||
### 6.2. Portfolio and Risk
|
||||
|
||||
Проверяет и ограничивает торговое намерение:
|
||||
|
||||
- допустимый размер позиции;
|
||||
- leverage и margin;
|
||||
- общий капитал под риском;
|
||||
- концентрацию по символам;
|
||||
- drawdown и loss limits;
|
||||
- pre-trade, continuous и emergency risk controls.
|
||||
|
||||
Risk не является только одним последовательным шагом после Strategy.
|
||||
Он может запрещать вход, изменять размер позиции и останавливать уже
|
||||
активное исполнение.
|
||||
|
||||
### 6.3. Order Management System
|
||||
|
||||
Отвечает за внутренний жизненный цикл собственных заявок:
|
||||
|
||||
- создание client order identity;
|
||||
- переходы состояния заявки;
|
||||
- amend / cancel;
|
||||
- partial fills;
|
||||
- deduplication;
|
||||
- reconciliation с биржей;
|
||||
- восстановление после reconnect и restart.
|
||||
|
||||
OMS не следует смешивать с Market Trades Feed: рыночная сделка и
|
||||
исполнение собственной заявки являются разными предметными сущностями.
|
||||
|
||||
### 6.4. Execution Management
|
||||
|
||||
Отвечает за:
|
||||
|
||||
- преобразование одобренного намерения в execution command;
|
||||
- выбор цены и способа исполнения;
|
||||
- маршрутизацию на биржу;
|
||||
- контроль slippage, liquidity и freshness;
|
||||
- обработку transport и exchange errors.
|
||||
|
||||
**Текущее основное размещение:**
|
||||
|
||||
```text
|
||||
app/src/trading/execution/
|
||||
```
|
||||
|
||||
### 6.5. Position and Account Reconciliation
|
||||
|
||||
Сопоставляет локальное состояние с биржей:
|
||||
|
||||
- позиции;
|
||||
- balances;
|
||||
- fills;
|
||||
- open orders;
|
||||
- fees;
|
||||
- realized и unrealized PnL.
|
||||
|
||||
Биржевое состояние является внешним фактом и должно периодически
|
||||
сверяться, а не только вычисляться из локальных событий.
|
||||
|
||||
---
|
||||
|
||||
## 7. Platform and Governance
|
||||
|
||||
### Runtime and Scheduling
|
||||
|
||||
- явные владельцы задач и ресурсов;
|
||||
- конечные timeouts;
|
||||
- детерминированные startup и shutdown;
|
||||
- controlled retry/reconnect;
|
||||
- отсутствие скрытого fire-and-forget.
|
||||
|
||||
### Event Contracts
|
||||
|
||||
- типизированные и версионируемые события;
|
||||
- явная граница между market, runtime, execution и audit events;
|
||||
- контролируемое ordering;
|
||||
- отсутствие чувствительных transport payload в логах.
|
||||
|
||||
### Configuration and Secrets
|
||||
|
||||
- feature flags безопасны по умолчанию;
|
||||
- URL, symbols и credentials задаются явно;
|
||||
- production secrets не попадают в код, документацию и события.
|
||||
|
||||
### Logging, Audit and Observability
|
||||
|
||||
- технические логи;
|
||||
- domain audit trail;
|
||||
- Trade Journal;
|
||||
- metrics, latency и data freshness;
|
||||
- health и liveness;
|
||||
- alerting;
|
||||
- объяснение причин торгового решения.
|
||||
|
||||
### Resilience
|
||||
|
||||
- idempotency;
|
||||
- reconnect;
|
||||
- Recovery;
|
||||
- persistent checkpoint;
|
||||
- startup reconciliation;
|
||||
- controlled degradation;
|
||||
- failure isolation.
|
||||
|
||||
### Backtesting and Simulation
|
||||
|
||||
Backtesting является отдельной capability, но переиспользует:
|
||||
|
||||
- Canonical Market Data;
|
||||
- Replay;
|
||||
- deterministic clock;
|
||||
- production Feature, Decision и Risk contracts;
|
||||
- exchange/OMS simulator.
|
||||
|
||||
Отдельная копия торговой логики только для backtest не допускается.
|
||||
|
||||
---
|
||||
|
||||
## 8. Правила зависимостей
|
||||
|
||||
Разрешённое основное направление:
|
||||
|
||||
```text
|
||||
Market Data
|
||||
↓
|
||||
Market Intelligence
|
||||
↓
|
||||
Trading Decision
|
||||
↓
|
||||
Portfolio / Risk
|
||||
↓
|
||||
OMS / Execution
|
||||
↓
|
||||
Exchange Integration
|
||||
```
|
||||
|
||||
Обязательные ограничения:
|
||||
|
||||
- Market Data не импортирует Trading;
|
||||
- Canonical Models не зависят от Dzengi transport schema;
|
||||
- Market Intelligence не управляет WebSocket lifecycle;
|
||||
- Strategy не отправляет биржевую заявку напрямую;
|
||||
- Execution не изменяет правила Market Data Consistency;
|
||||
- Telegram UI не является владельцем domain state;
|
||||
- Storage не вызывает торговые решения;
|
||||
- Backtesting использует те же domain contracts, что production;
|
||||
- Platform-компоненты не получают лишнюю предметную ответственность.
|
||||
|
||||
Обратная информация от Exchange возвращается через явные execution,
|
||||
order, account и runtime events, а не через обратные импорты между
|
||||
слоями.
|
||||
|
||||
---
|
||||
|
||||
## 9. Политика каталогов
|
||||
|
||||
Логический домен и физический каталог не обязаны иметь одинаковое имя.
|
||||
|
||||
Текущее соответствие:
|
||||
|
||||
| Ответственность | Фактическое размещение |
|
||||
|---|---|
|
||||
| Market Data Acquisition | `app/src/market_data/acquisition/` |
|
||||
| Application Runtime Composition | `app/src/bootstrap/` |
|
||||
| Runtime Events | `app/src/runtime_events/` и локальные runtime events |
|
||||
| Storage foundation | `app/src/storage/` |
|
||||
| Market Intelligence | `app/src/trading/market_intelligence/` |
|
||||
| Trading Decision | `app/src/trading/decision/` |
|
||||
| Execution | `app/src/trading/execution/` |
|
||||
| Position | `app/src/trading/position/` |
|
||||
| Trade Journal | `app/src/trading/journal/` |
|
||||
| Exchange Integration | `app/src/integrations/exchange/` |
|
||||
|
||||
Новый каталог создаётся только когда:
|
||||
|
||||
1. ответственность подтверждена фактическими consumers;
|
||||
2. определён публичный контракт;
|
||||
3. существующее ownership признано неверным;
|
||||
4. подготовлен отдельный migration plan;
|
||||
5. проверено направление импортов.
|
||||
|
||||
Предложенные имена вроде `analytics/features`,
|
||||
`market_data/normalization` или `market_data/storage` являются
|
||||
логическими ориентирами, а не заранее утверждённой файловой структурой.
|
||||
|
||||
---
|
||||
|
||||
## 10. Current-to-target status
|
||||
|
||||
| Область | Состояние |
|
||||
|---|---|
|
||||
| Market Data Acquisition foundation | Реализуется Build-by-Build |
|
||||
| Trades Feed production runtime | Completed — Build 060.25 |
|
||||
| Runtime integration/stress verification | Next — Build 060.26 |
|
||||
| Persistent Market Data Storage | Planned — Build 060.27 |
|
||||
| Persistent Checkpoint / Startup Recovery | Planned — Build 060.28 |
|
||||
| Historical Access / Replay | Planned — Build 060.29 |
|
||||
| Validation ownership audit/refactoring | Planned — Build 061.00 |
|
||||
| Market Intelligence | Существующая активная подсистема |
|
||||
| Decision / Execution / Position | Существующие подсистемы, требуют будущих boundary audits |
|
||||
| OMS / Reconciliation | Целевая ответственность, отдельный план не утверждён |
|
||||
| Backtesting | Целевая capability после Storage и Replay |
|
||||
| Operations / Deployment | Целевая cross-cutting программа |
|
||||
|
||||
`Completed` означает завершение утверждённого Build, а не окончательную
|
||||
сертификацию всей подсистемы для любой production-нагрузки.
|
||||
|
||||
---
|
||||
|
||||
## 11. Управление изменениями
|
||||
|
||||
Этот документ изменяется только когда меняется:
|
||||
|
||||
- ownership домена;
|
||||
- публичная архитектурная граница;
|
||||
- разрешённое направление зависимостей;
|
||||
- целевая карта подсистем.
|
||||
|
||||
Статус конкретного Build изменяется в `master-roadmap.md` и его
|
||||
migration report.
|
||||
|
||||
Детали реализации, тестовые evidence и локальные решения фиксируются в:
|
||||
|
||||
```text
|
||||
docs/migrations/build_<number>_architecture.md
|
||||
docs/migrations/build_<number>.md
|
||||
docs/decisions/
|
||||
```
|
||||
|
||||
При конфликте:
|
||||
|
||||
1. фактический код и тесты определяют текущее поведение;
|
||||
2. принятый Build architecture document определяет локальное решение;
|
||||
3. настоящий документ определяет целевую границу;
|
||||
4. roadmap определяет порядок дальнейшей миграции.
|
||||
Reference in New Issue
Block a user