Перейти к содержанию

ADR 0047: Инструмент кабины (Instrument) — дескриптор композиции слота, не Control

Статус: Accepted · Implemented
Дата: 2026-04-15

Связанные ADR

ADR / документ Роль
0036 Канал → CDS → композитор → поверхность
0021 Зоны внимания
0039 Semantic Map, навигация
0046 Инварианты presentation
cds-contract-v0.md Чертёж дескрипторов и слотов

Имя файла (история): ранее черновик назывался *widget*; канонический термин продукта — Instrument (см. п.1).

Снимок реализации

Элемент Значение
— термин Instrument, CockpitInstrumentDescriptor, MainWindowHostSurfaceFrame, MainWindowInstrumentMountRegistry
— см. cds-contract-v0.md
— расширение списка инструментов — по дорожной карте

Контекст

В разговоре о Solution Explorer и Semantic Map всплыла путаница уровней: «данные», «представление данных», «поверхность Avalonia» и «слот внимания» смешивались. Нужен устойчивый термин для единицы, которую композитор выбирает для слота и которую поверхность монтирует — без подмены смысла «любым Control». Слово instrument в английском многозначно (авиа-прибор, измерительный прибор, музыкальный инструмент и т.д.); в этом ADR оно закреплено в значении кабинного инструмента: логическая единица индикации/представления в зоне внимания, в духе метафоры PFD/MFD, не обязательно «стрелка на приборной доске».

Решение

  1. Instrument (кабинный) — это именованный выбор представления в слоте внимания, результат работы композитора. Это не синоним Avalonia-Control и не сырой канал данных (Build log, граф навигации и т.д. остаются в каналах / проекциях).

  1. CockpitInstrumentDescriptor (код) — минимальный контрактный дескриптор: стабильный instrument_id, идентификатор слота (slot_id, например pfd / mfd / forward), schema_version строки дескриптора. Расширение полей (параметры инструмента, ссылки на данные) — по мере появления второго и третьего инструмента в одном слоте.

  1. CDS по-прежнему отвечает на «куда имеет право попасть инструмент» при текущем presentation и топологии; композитор — на «какой instrument_id в каком slot_id»; поверхность — на «какой Control/View реализует этот дескриптор».

  1. Примеры слотов PFD: solution_explorer_tree и workspace_navigation_map (Semantic Map) — два разных инструмента одного класса слота «представление workspace», взаимоисключаемо или с явным split — решает композитор + capabilities, не произвольный код View.

Последствия

  • Появляется язык для MCP/агента: «смонтировать инструмент X в слот Y» без привязки к имени контрола в дереве.
  • Регрессии «сломали не данные, а представление» локализуются в композиторе и реестре инструментов.

Не цели (v1)

  • Полный реестр инструментов и hot-swap всех панелей — отдельными итерациями после стабилизации дескриптора.
  • Замена UiLayoutSnapshot для автоматизации дерева UI.

Отклонённые альтернативы

  • Widget — перегружен (веб, Flutter, «виджеты ОС»); заменён на Instrument для ясной связи с кабинной метафорой и меньшей коллизией с UI-фреймворками.
  • Называть любой UserControl «инструментом» без дескриптора — отклонено: размывает границу композитор/поверхность.
  • Вешать выбор SE vs Semantic Map только на TOML без слоя композитора — отклонено: не масштабируется на MCP и тесты.