| 1 | # Playbook: зона внимания ↔ панель shell ↔ SDK |
| 2 | |
| 3 | **Статус:** чертёж v1. |
| 4 | **Связь:** [ADR 0021](../adr/0021-pfd-mfd-cockpit-attention-model.md) (семантика), [ADR 0017](../adr/0017-multi-window-workspace-and-agent-surfaces.md) (несколько окон / поверхности), [ADR 0025](../adr/0025-sdk-attention-zones-and-capabilities.md) (контракты), [0010](../adr/0010-ui-modes-toml-configuration.md) (overlay). |
| 5 | **Проверка среза:** [vertical-slice-attention-capabilities-v1](vertical-slice-attention-capabilities-v1.md). |
| 6 | |
| 7 | ## Зачем |
| 8 | |
| 9 | Чтобы после фразы «эта поверхность в **PFD**» был **следующий шаг без догадок**: какой **id панели**, где **дефолт зоны** в рантайме, что **переопределяет** `workspace.toml`. |
| 10 | |
| 11 | ## Три слоя (не смешивать) |
| 12 | |
| 13 | | Слой | Что это | Где живёт | |
| 14 | |------|---------|-----------| |
| 15 | | Семантика зоны | «Где в модели внимания» (PFD / Forward / …) | `PrimaryAttentionZoneId` в `UiSurfaceCapabilityDescriptor`, константы `AttentionZoneCanonicalIds` | |
| 16 | | Панель shell | Стабильный ключ панели в сетке / доке | `HostAttentionPanelId` ↔ `AttentionPanelCanonicalIds` / `AttentionPanelIds` | |
| 17 | | Презентация | Видимость, размер, вкладки | TOML overlay ([0010](../adr/0010-ui-modes-toml-configuration.md)), Axaml | |
| 18 | |
| 19 | **Топология презентации** (одно окно с колонками vs несколько окон/мониторов) в коде задаётся отдельно от id зоны: `AttentionLayoutSurfaceKind` (сейчас только `MainWindowDockedGrid`); на `MainWindowViewModel` — `ActiveAttentionLayoutSurface`. Свойства `IsPfdColumnVisible` / `IsMfdColumnVisible` относятся только к этой топологии. |
| 20 | |
| 21 | **Колонки MainGrid ≠ содержимое зоны.** Свойства вроде «видна колонка под якорь PFD/MFD» в VM описывают **разметку главного окна** (есть ли место под левую/правую колонку в одном `MainGrid`). **Какая панель** сейчас привязана к зоне `pfd` / `mfd` / `forward` — это слой карты `AttentionZonePanelRuntime` и TOML, а не то же имя, что у колонки сплиттера. |
| 22 | |
| 23 | **Колонки — не единственная форма раскладки.** Три семантики (PFD / лобовое / MFD) на **одном мониторе** часто складываются в три колонки одного окна; при **мультимониторе или нескольких top-level** те же зоны могут жить в **отдельных окнах** или на разных дисплеях — семантика зон сохраняется, меняется только геометрия презентации ([ADR 0021 §13 «Мультиоконность и мультимонитор»](../adr/0021-pfd-mfd-cockpit-attention-model.md), [ADR 0017](../adr/0017-multi-window-workspace-and-agent-surfaces.md)). Пример целевой схемы на **двух** мониторах: первый — PFD + лобовое, второй — MFD (см. [0017 §«Два монитора»](../adr/0017-multi-window-workspace-and-agent-surfaces.md)). Playbook про колонки описывает текущий путь «главное окно → MainGrid»; роутинг зон по окнам — предмет 0017 и будущей реализации, не замена таблицы панель→зона выше. |
| 24 | |
| 25 | ## Дефолтная карта панель → зона |
| 26 | |
| 27 | Источник в коде: `AttentionZonePanelRuntime.BuildDefaultMap()` (после загрузки workspace накладываются переопределения из `attention_zone_panels`). |
| 28 | |
| 29 | | Панель (`AttentionPanelIds`) | Дефолтная зона (канонический id) | Примечание | |
| 30 | |------------------------------|-------------------------------------|------------| |
| 31 | | `solution_explorer` | `pfd` | контекст workspace слева | |
| 32 | | `chat_panel` | `mfd` | | |
| 33 | | `git` | `mfd` | | |
| 34 | | `terminal_dock` | `mfd` | | |
| 35 | | `editor` | `forward` | лобовое | |
| 36 | | `editor_hud` | `hud` | слой над редактором, не отдельная колонка | |
| 37 | |
| 38 | EICAS как **канал** оповещений в этой таблице не как отдельная строка-панель — см. ADR 0021. |
| 39 | |
| 40 | ## Что делать при добавлении UI surface |
| 41 | |
| 42 | 1. Выбрать **канонический id зоны** (`AttentionZoneCanonicalIds`) для ментальной модели. |
| 43 | 2. Если поверхность = **конкретная панель** дока: задать **`HostAttentionPanelId`** тем же строковым id, что в таблице выше (или добавить новый id в `AttentionPanelCanonicalIds`, `AttentionPanelIds`, дефолт в `AttentionZonePanelRuntime`). |
| 44 | 3. Заполнить **оба** поля (`PrimaryAttentionZoneId` + `HostAttentionPanelId`) — тогда при `BuildMap()` проверка **`CapabilityAttentionConsistency`** сравнит с текущей картой рантайма и выведет предупреждение в Debug при рассинхроне. |
| 45 | 4. Для переопределения **места** панели пользователем — только **TOML** (`attention_zone_panels`), не подмена семантики в SDK. |
| 46 | |
| 47 | ## Чего этот playbook не делает |
| 48 | |
| 49 | - Не задаёт пиксели и не заменяет разметку Axaml. |
| 50 | - Не заставляет вешать зону на команды без привязки к панели. |
| 51 | |