dzentra_bot/docs/market_intelligence/builds/build-015-3-common-models-engine-registration.md

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 новую фундаментальную модель:

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)

Решение

Добавить модель:

EngineRegistration

в common.models.

Статус

Accepted

Обоснование

Во время проектирования Runtime Registry подтверждено, что регистрация Engine является самостоятельной архитектурной сущностью.

Модель объединяет:

• тип Engine;
• его Metadata.

При этом сама Metadata остаётся единственным источником информации об Engine.

Главное правило

EngineRegistration не должен дублировать информацию, уже содержащуюся в EngineMetadata.

Запрещается добавлять отдельные поля:

engine_name
engine_version
dependencies
priority
enabled_by_default
registered_at

Последствия

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

• Runtime Registry сможет хранить атомарные записи регистрации;
• Metadata будет доступна без обращения к классу Engine;
• Runtime сохранит контроль над жизненным циклом Engine;
• модель регистрации останется независимой от Runtime-состояния.

---

Build Design

В файл

app/src/trading/market_intelligence/common/models.py

добавлены:

EngineTypeProtocol
EngineRegistration

EngineTypeProtocol используется как минимальный контракт класса Engine и позволяет избежать запрещённой зависимости:

Common → Engine

---

Implementation

Реализованы:

EngineTypeProtocol

EngineRegistration

Состав модели:

EngineRegistration
├── engine_type
└── metadata

Модель не содержит дополнительных полей.

---

Compile Check

Проверка выполнена командой:

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 используется минимальный локальный протокол:

EngineTypeProtocol

Это позволяет избежать запрещённой зависимости:

Common → Engine

---

Следующий Build

Build 015.4

Runtime Registry

runtime/registry.py