| 1 | # ADR 0073: PFD instrument deck — каталог вариантов состава и поверхностей (SA) |
| 2 | |
| 3 | **Статус:** Proposed |
| 4 | **Дата:** 2026-04-19 |
| 5 | ## Связанные ADR |
| 6 | |
| 7 | | ADR | Роль | |
| 8 | |-----|------| |
| 9 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | модель внимания PFD/MFD | |
| 10 | | [0037](0037-pfd-surface-invariants-and-roslyn-enforcement.md) | **строгая PFD-поверхность**, `[PfdStrict]` / `PfdStrictControl`; **не** синоним всей географии колонки PFD | |
| 11 | | [0063](0063-instrument-deck-named-composition-one-anchor.md) | **instrument deck** как именованная композиция в одном якоре; ось **ContentRepresentation** | |
| 12 | | [0064](0064-deck-primitives-visual-language-render-layer-and-palette.md) | примитивы / палитра отрисовки приборов | |
| 13 | | [0066](0066-cockpit-ui-vs-ide-presentation-layer.md) | Cockpit UI vs presentation IDE | |
| 14 | | [0050](0050-declarative-instrument-zone-placement-toml.md) | `[instrument_routing]`, слоты `pfd_primary` / … | |
| 15 | | [0047](0047-cockpit-instrument-descriptor-and-slot-composition.md) | `Instrument`, `CockpitInstrumentDescriptor` | |
| 16 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | MCP / паритет с командами | |
| 17 | | [0011](0011-debug-situational-awareness.md) | SA в отладке — родственная ось «осведомлённость» | |
| 18 | | [0061](0061-context-aware-adr-map-pfd-knowledge-indicator.md) | ADR-карта и индикатор на PFD — **кандидат** в ту же колоду | |
| 19 | |
| 20 | ## Резюме |
| 21 | |
| 22 | - Каталог вариантов **PFD instrument deck** (SA, metrics, semantic map, ADR indicator…). |
| 23 | - Критерии «PFD vs по запросу»; живой черновик до выбора пресета. |
| 24 | |
| 25 | ### Вне ADR |
| 26 | |
| 27 | | Документ | Роль | |
| 28 | |----------|------| |
| 29 | | [§3](#adr0073-v3) | §3 | |
| 30 | **Назначение ADR:** зафиксировать **рабочее место** для перебора вариантов — **какие** инструменты и **в каком режиме** имеют смысл на **PFD** (первичный скан, тактика), не смешивая с **MFD**/палитрой без явного решения. Это **не** дублирует норматив [0063](0063-instrument-deck-named-composition-one-anchor.md) по терминам; здесь — **предметный** список кандидатов и **открытые** развилки. |
| 31 | |
| 32 | --- |
| 33 | ## Контекст |
| 34 | |
| 35 | **PFD** в [0021](0021-pfd-mfd-cockpit-attention-model.md) — зона **первичного** внимания (дерево решения, навигация, тактические инструменты). **Instrument deck** [0063](0063-instrument-deck-named-composition-one-anchor.md) описывает *форму* композиции («несколько приборов на одном экране»), но не закрывает *какой* набор для PFD продуктово оправдан. |
| 36 | |
| 37 | Отдельно обсуждалось: **ситуационная осведомлённость (SA)** — сводки о контексте работы (объём кода, сложность, карта знаний). Часть сигналов уже есть **вне** PFD (например бейдж LOC / уровень Low·Medium·High в task cockpit; пороги `[loc_limits]` в `workspace.toml`). **Code metrics** через MCP (`get_code_metrics`) отдаёт JSON по scope — удобно агенту и сценариям, но **не** отвечает само по себе на вопрос «где это показать пилоту». |
| 38 | |
| 39 | Нужен **накопительный** документ: варианты **PFD instrument deck** и критерии «здесь / по запросу / не PFD». |
| 40 | |
| 41 | --- |
| 42 | |
| 43 | <a id="adr0073-v1"></a> |
| 44 | |
| 45 | ## 1. Инварианты (не обсуждаются в этом ADR как «новая ось») |
| 46 | |
| 47 | - Слоты и merge TOML — [0050](0050-declarative-instrument-zone-placement-toml.md); дескриптор инструмента — [0047](0047-cockpit-instrument-descriptor-and-slot-composition.md). |
| 48 | - **EICAS** (W/C/A) и **ось LOC** (Low/Medium/High по `[loc_limits]`) — **разные** семантики; не смешивать цвета/лейблы без легенды (см. обсуждение в продукте; бейдж LOC — отдельная ось «величина файла»). |
| 49 | |
| 50 | <a id="adr0073-v1b"></a> |
| 51 | |
| 52 | ### 1.1. Продуктовый ориентир: Strict и Glass Cockpit |
| 53 | |
| 54 | **Идеал для приборной части PFD:** поведение ближе к **read-only** и **строгому** контракту в смысле [0037](0037-pfd-surface-invariants-and-roslyn-enforcement.md) — компоненты с **`[PfdStrict]`** / **`PfdStrictControl`**: ограничения по вводу (**Input Lock**), весу (**Weight**), каналам данных; без «офисного» тяжёлого интерактива внутри маркированной приборной поверхности. |
| 55 | |
| 56 | **Визуальный стиль:** ориентир **glass cockpit** — тёмное поле приборов, светящиеся индикаторы, читаемость в боковом зрении; детали примитивов и палитры — [0064](0064-deck-primitives-visual-language-render-layer-and-palette.md). Не смешивать с хромом shell / оверлеями **presentation IDE** ([0066](0066-cockpit-ui-vs-ide-presentation-layer.md)). |
| 57 | |
| 58 | **Важный нюанс [0037](0037-pfd-surface-invariants-and-roslyn-enforcement.md):** **географическая** зона PFD **не** равна «вся колонка read-only». **Навигация** (дерево решения, выбор файла, раскрытие узлов) остаётся **интерактивной** — это контекст «где я», а не приборная строгость. Строгий контракт навешивается на **явно** помеченные индикаторы/тактические приборы, а не на всё, что нарисовано слева. |
| 59 | |
| 60 | <a id="adr0073-loc-composite"></a> |
| 61 | |
| 62 | ### 1.2. Пример составного индикатора: LOC (черновик) |
| 63 | |
| 64 | Целевое представление **LOC** (непустые строки, пороги `[loc_limits]`) — **два канала в одном приборе**, по аналогии с реальной авионикой (метафора не смешивается с EICAS W/C/A): |
| 65 | |
| 66 | | Канал | Роль | Образ | |
| 67 | |-------|------|--------| |
| 68 | | **Зонированная шкала** | Где файл относительно **Low / Medium / High** | **Glide slope** (или локальный горизонт): полоса с тремя сегментами, маркер **положения** (не «курс» в навигационном смысле — в tooltip зафиксировать, что это эвристика по размеру). | |
| 69 | | **Число** | Точное значение LOC, без потери точности на границах зон | **Altimeter**: крупный цифровой/барабанный **readout** рядом или внутри того же виджета — как у приборов: и шкала, и значение. | |
| 70 | |
| 71 | Практика: без **цифры** на границе `medium_min` / `high_min` пользователь не видит «насколько» внутри зоны; без **шкалы** теряется мгновенный скан «зелёный/жёлтый/красный» коридора. Детали примитивов — [0064](0064-deck-primitives-visual-language-render-layer-and-palette.md). |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | <a id="adr0073-v2"></a> |
| 76 | |
| 77 | ## 2. Критерии отбора (черновик) |
| 78 | |
| 79 | | Критерий | Вопрос | |
| 80 | |----------|--------| |
| 81 | | **Скан** | Укладывается ли сигнал во **взгляд 1–2 с** без drill-down? | |
| 82 | | **Тактика** | Относится ли к **текущему файлу/узлу/курсору** (vs стратегия всего решения)? | |
| 83 | | **Частота** | Нужен ли **постоянно** на PFD или достаточно **по команде** / на MFD? | |
| 84 | | **Паритет** | Должен ли человек и агент видеть **тот же** снимок ([0008](0008-mcp-contracts-and-testable-infrastructure.md))? | |
| 85 | |
| 86 | --- |
| 87 | |
| 88 | <a id="adr0073-v3"></a> |
| 89 | |
| 90 | ## 3. Каталог вариантов (наполняется) |
| 91 | |
| 92 | Статусы: **идея** | **кандидат PFD** | **скорее не PFD** | **отклонено / отложено**. |
| 93 | |
| 94 | | # | Элемент | Суть | Черновой вердикт | Заметки | |
| 95 | |---|---------|------|------------------|---------| |
| 96 | | A | **Solution Explorer / дерево** | Навигация по проекту | Уже якорь PFD по умолчанию | — | |
| 97 | | B | **Semantic Map (control flow)** | Поток управления в методе | **Кандидат PFD** ([0053](0053-semantic-map-control-flow-pfd.md)) | Тактика, курсор | |
| 98 | | C | **LOC / размер файла** | Непустые строки, уровень L/M/H | **Скорее не отдельный прибор PFD v0** — уже **бейдж** в task cockpit; дубль на PFD только при явной политике «всё SA на левом краю» | `[loc_limits]`; целевой вид прибора — [§1.2](#adr0073-loc-composite): **BarWithLevels + маркер** (образ glideslope) + **число** (образ altimeter). | |
| 99 | | D | **Code metrics (`get_code_metrics`)** | LOC, классы, методы, cyclomatic, `hot_methods` | **Скорее по запросу** (палитра, MCP, опционально компактная панель) или **MFD** для scope=solution; **мини-сводка** на PFD — только если закрепить «текущий файл only» | Не раздувать PFD полным JSON | |
| 100 | | E | **ADR / knowledge indicator** | Карта путь → ADR, intent | **Кандидат** ([0061](0061-context-aware-adr-map-pfd-knowledge-indicator.md)) | SA по документации | |
| 101 | | F | **Git / статус** | Изменённые файлы | Часто **MFD** или полоса WH; на PFD — если слот свободен и продукт выберет «git рядом с деревом» | Пересечение с Git в других зонах | |
| 102 | | G | *(запасная строка)* | — | — | Добавлять новые строки снизу | |
| 103 | |
| 104 | **Правило редактирования:** новые идеи — новая буква или подпункт; не переписывать историю без пометки внизу ADR (дата, что изменилось). |
| 105 | |
| 106 | --- |
| 107 | |
| 108 | <a id="adr0073-v4"></a> |
| 109 | |
| 110 | ## 4. Открытые вопросы |
| 111 | |
| 112 | 1. Нужен ли **единый** пресет «PFD = навигация + один тактический прибор» vs «PFD = плотная колода из N ячеек» ([0063](0063-instrument-deck-named-composition-one-anchor.md) § Page + deck)? |
| 113 | 2. Должен ли **code metrics** для **current file** дублироваться **визуально** на PFD, если MCP уже отдаёт те же числа агенту? |
| 114 | 3. Граница **PFD vs Forward** ([0021](0021-pfd-mfd-cockpit-attention-model.md)) для мини-индикаторов SA — не съесть ли центральный редактор. |
| 115 | |
| 116 | --- |
| 117 | |
| 118 | ## Решение |
| 119 | |
| 120 | **Зафиксировать как Proposed:** вести **этот ADR** как **живой каталог** вариантов PFD deck и критериев; **не** считать строку таблицы §3 принятой продуктовой нормой, пока не переведено в отдельное **Accepted** решение или не реализовано в коде с отсылкой сюда. |
| 121 | |
| 122 | **Следующий шаг (вне этого файла):** по мере зрелости — вынести отдельные строки в **UiModes** / пресеты / `[instrument_routing]` ([0050](0050-declarative-instrument-zone-placement-toml.md)) с ссылкой на номер строки §3. |
| 123 | |
| 124 | --- |
| 125 | |
| 126 | ## Последствия |
| 127 | |
| 128 | - Документ может **часто меняться** (таблица §3); стабильные определения терминов — по-прежнему в [0063](0063-instrument-deck-named-composition-one-anchor.md) и [0021](0021-pfd-mfd-cockpit-attention-model.md). |
| 129 | - Реализация конкретного ряда приборов на PFD — отдельные коммиты и при необходимости узкий ADR «как именно» (layout, CDS), не раздувая **0073**. |
| 130 | |
| 131 | --- |
| 132 | |
| 133 | ## История изменений (кратко) |
| 134 | |
| 135 | | Дата | Изменение | |
| 136 | |------|-----------| |
| 137 | | 2026-04-19 | Первичная фиксация: контекст, критерии §2, стартовая таблица §3, открытые вопросы §4. | |
| 138 | | 2026-04-19 | §1.1: ориентир **Strict** + **Glass Cockpit**; разводка с полностью read-only колонкой — по [0037](0037-pfd-surface-invariants-and-roslyn-enforcement.md). | |
| 139 | | 2026-04-19 | §1.2: LOC — составной индикатор: шкала с зонами + маркер (образ **glideslope**) и числовой readout (образ **altimeter**); строка C §3. | |
| 140 | |