| 1 | <!-- markdownlint-disable MD060 --> |
| 2 | |
| 3 | # Software Cross-Domain Transfer Matrix v1 |
| 4 | |
| 5 | ## Purpose |
| 6 | |
| 7 | Маршрутизация **неявных** и смешанных software-задач: когда симптом в одном слое (Skia, ViewModel, «сделай красиво», биндинг Avalonia) требует **другого** playbook/kb — прежде всего **структуры (OOA&D)** vs **оформления (HCI)** vs **стека (.NET/Avalonia)** vs **процесса (Git/Roslyn)**. |
| 8 | |
| 9 | Не заменяет Domain Entry Map в `index-knowledge-router-v1.md`; даёт **компактную таблицу переноса** после выбора домена «software». |
| 10 | |
| 11 | **Версия:** v1.0 · 2026-05-17 |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## Transfer contract |
| 16 | |
| 17 | - Переносить **принципы и порядок чтения**, не копировать API/паттерны из чужого мира без проверки. |
| 18 | - Перед любым cross-world шагом: [`../knowledge-engineering/matrix-do-not-transfer-v1.md`](../knowledge-engineering/matrix-do-not-transfer-v1.md) (жёсткие deny). |
| 19 | - Культура/формулировки в UI-текстах: при необходимости [`../knowledge-engineering/matrix-culture-routing-v1.md`](../knowledge-engineering/matrix-culture-routing-v1.md). |
| 20 | - Порядок загрузки при срабатывании матрицы: **`status-software-authoring-v1` → эта матрица (строка) → целевой playbook → kb по вопросу**. |
| 21 | - Эпистемика: не объявлять «архитектуру готова» без проверки сборки/Roslyn там, где менялся C#. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## Fast symptom router (агент) |
| 26 | |
| 27 | **Troubleshooting-вход мира:** [`troubleshooting/playbook-software-authoring-troubleshooting-v1.md`](troubleshooting/playbook-software-authoring-troubleshooting-v1.md) (таблица синхронна с этой секцией). |
| 28 | |
| 29 | | Симптом в запросе или коде | Сначала | Потом (если нужно) | Не делать | |
| 30 | |----------------------------|---------|---------------------|-----------| |
| 31 | | `switch` / `enum Kind` / `ItemKind` в renderer, handler, VM | `playbook-ooad-agent-operational-v1.md` | `playbook-domain-nouns-verbs-decomposition-v1.md` | ещё одна ветка в том же `switch` | |
| 32 | | God-class / ViewModel > ~800 строк / Control «всё умеет» | шаг 5 OOA&D (слои) + nouns-verbs | `code-writing-principles-v1.md` | выносить 20 микро-классов без домена | |
| 33 | | «Сделай визуал», карточки, layout, цвет, шрифт | **HCI** (`playbook-hci-core-v1`, `ui-ux-playbook`) для UX-контракта | **OOA&D**, если растёт discriminated union | Nielsen вместо типов | |
| 34 | | Новый экран / панель / overview / wizard | полный 7-шаговый OOA&D | Avalonia playbook при выборе контролов | сразу пиксели без словаря домена | |
| 35 | | Ошибка биндинга, тема, Dock, `axaml` | `playbook-avalonia-dock-ui-v1.md` | HCI только для copy/иерархии | полный OOA&D | |
| 36 | | CSxxxx / analyzer / «почини warning» | `playbook-csharp-roslyn-mcp-diagnostics-v1.md` | code action, не ручной костыль | редизайн домена | |
| 37 | | «Как в авиации / PFD / cockpit / scan pattern» | `kb-aviation-pfd-mfd-efis-eicas-fundamentals-v1.md` | HCI + Avalonia для IDE | перенос регламентов FAA в код-ревью | |
| 38 | | DDD / Clean / «настоящая архитектура» | `status-software-authoring-v1` + OOA&D | Track C в `map-engineering-reading-v1.md` **после** анализа | папки по моде без сущностей | |
| 39 | | Только цвет/отступ/1 строка в одном методе | `code-writing-principles-v1.md` | — | OOA&D-проход | |
| 40 | | Compositor уже отдаёт `*Snapshot` / DTO | nouns-verbs: **presentation догоняет domain** | `SceneBuilder` + `ISkia*Entity` | дублировать домен в Control | |
| 41 | | Производительность `Draw` / jank | профиль hot path, кэш layout | не плодить сущности на кадр | OOA&D «с нуля» | |
| 42 | | Коммит, ветка, submodule | `playbook-git-workflow-v1.md` | — | структура классов | |
| 43 | | Интеграция API / MCP / Telegram | `software-integration-kb` | — | UI entity model | |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Matrix (детально) |
| 48 | |
| 49 | ### A. Presentation → structure (Skia, custom draw, hit-test) |
| 50 | |
| 51 | | Источник | Переносимое ядро | Целевой артефакт | Boundary check | |
| 52 | |----------|------------------|------------------|----------------| |
| 53 | | Второй `if` по kind в `Draw`/`Measure` | полиморфизм, Information Expert | `ISkiaChatEntity` + классы сущностей | один новый вид = один тип, не enum-ветка | |
| 54 | | Общий record + дискриминатор на 4+ формы UI | noun/verb таблица | отдельные типы на форму | enum только без разного поведения | |
| 55 | | Control > 400 строк, цикл + switch | оркестратор + `SceneBuilder` | Control: scroll, theme, hit dispatch | не тащить padding карточки в Control | |
| 56 | | Hit-test с `switch` по kind | `CreateHit()` у сущности | hit-модель с `SelectThreadId` и т.д. | не смешивать hit с layout-математикой в одном методе | |
| 57 | | «Как на макете / картотека» | сущность `TopicCard` + поля summary/badges | HCI для иерархии текста | не рисовать без типа «карточка» | |
| 58 | |
| 59 | **Канон-пример:** Cascade IDE `Views/Chat/Skia/` — domain в `ChatSurfaceCompositor`, presentation в `SkiaChat*`. |
| 60 | |
| 61 | ### B. Application layer → domain (MVVM, ViewModel, commands) |
| 62 | |
| 63 | | Источник | Переносимое ядро | Целевой артефакт | Boundary check | |
| 64 | |----------|------------------|------------------|----------------| |
| 65 | | ViewModel знает Skia-координаты | разделение слоёв GRASP | VM → snapshot; Skia → entities | VM не рисует | |
| 66 | | Дублирование полей snapshot и VM | один источник истины | compositor / snapshot | не третий слой «ради удобства» | |
| 67 | | 50+ команд в одном VM | Controller / feature slice | отдельные VM или handlers по фиче | не god-VM «пока не больно» | |
| 68 | | `async` логика + UI state в одном файле | application vs presentation | сервис + тонкий VM | не Extract Class без границы | |
| 69 | |
| 70 | ### C. HCI / UX → implementation |
| 71 | |
| 72 | | Источник | Переносимое ядро | Целевой артефакт | Boundary check | |
| 73 | |----------|------------------|------------------|----------------| |
| 74 | | «Неудобно», «не видно», «запутано» | эвристики Nielsen/Norman | `playbook-hci-core-v1` | не переименовывать 30 классов | |
| 75 | | Плотность информации, overview | progressive disclosure | HCI + структура overview-сущностей | не всё в один scroll | |
| 76 | | Тексты кнопок, ошибки, тон | `kb-russian-language-rules-v1` при RU | copy в ресурсах | не law/psychology без матрицы культуры | |
| 77 | | IDE / dock / панели как продукт | `kb-ide-dx-literature-evidence-v1` | Avalonia dock playbook | не aviation regs | |
| 78 | |
| 79 | ### D. Aviation metaphors → IDE (Cascade) |
| 80 | |
| 81 | | Источник | Переносимое ядро | Целевой артефакт | Boundary check | |
| 82 | |----------|------------------|------------------|----------------| |
| 83 | | PFD/MFD/«главный индикатор» | фокус внимания, scan path | `kb-aviation-pfd-mfd-efis-eicas-fundamentals-v1` + HCI | не буквальные приборы в UI | |
| 84 | | CRM / cross-check | второй источник перед commit | git + review playbook | не бюрократия на каждый typo | |
| 85 | | TEM / go-around | откат неудачного UI-рефакторинга | ветка, маленькие коммиты | не «продолжать ломать» | |
| 86 | |
| 87 | См. ADR 0021 Cascade IDE при привязке к продукту. |
| 88 | |
| 89 | ### E. Engineering evidence → design order |
| 90 | |
| 91 | | Источник | Переносимое ядро | Целевой артефакт | Boundary check | |
| 92 | |----------|------------------|------------------|----------------| |
| 93 | | «Code Complete», McConnell | стиль и дефекты **после** структуры | `kb-engineering-evidence-v1` § OOA&D | не McConnell вместо noun/verb | |
| 94 | | GoF / паттерны | Polymorphism, Creator после CRC | `kb-ooad-fundamentals-v1` | не Singleton «на всякий» | |
| 95 | | Refactoring book | механические переносы **после** границ типов | Roslyn refactorings | не Move Method в god-class | |
| 96 | |
| 97 | ### F. Stack / tooling (не путать со структурой) |
| 98 | |
| 99 | | Источник | Переносимое ядро | Целевой артефакт | Boundary check | |
| 100 | |----------|------------------|------------------|----------------| |
| 101 | | Avalonia version / Dock / theme JSON | status + avalonia playbook | csproj + `Themes/` | не OOA&D | |
| 102 | | `dotnet build` fail | build log + Roslyn | MCP build | не новая иерархия пакетов | |
| 103 | | Partial class / DependentUpon | `roslyn_sync_dependent_upon_partials` | csproj hygiene | не domain model | |
| 104 | |
| 105 | --- |
| 106 | |
| 107 | ## Load order when matrix fires |
| 108 | |
| 109 | 1. `worlds/software-authoring/status-software-authoring-v1.md` |
| 110 | 2. **Эта матрица** — выбрать строку Fast symptom router. |
| 111 | 3. Целевой **playbook** (OOA&D operational, nouns-verbs, HCI, Avalonia, Roslyn, Git — одна главная). |
| 112 | 4. Один **kb** только под явный вопрос (теория GRASP, Avalonia fundamentals, …). |
| 113 | 5. При смешении миров (текст UI + структура): **два playbook максимум**, не весь корпус. |
| 114 | |
| 115 | --- |
| 116 | |
| 117 | ## Non-transfer zones |
| 118 | |
| 119 | - **HCI-эвристика → имена классов:** «понятнее» не значит `ManagerHelperUtils`. |
| 120 | - **Aviation regulation → обязательный процесс разработки:** только метафоры внимания. |
| 121 | - **DDD buzzwords → папки без сущностей:** сначала словарь домена (шаг 1 OOA&D). |
| 122 | - **Git hygiene → архитектура:** коммиты не заменяют слои. |
| 123 | - **Один успешный рефакторинг в репо A → тот же cut-paste в модуль B** без snapshot/compositor в B. |
| 124 | - **Визуальный референс (скрин макета) → поля без доменного имени:** назвать сущность, потом пиксели. |
| 125 | |
| 126 | --- |
| 127 | |
| 128 | ## Agent checklist (перед коммитом структурного рефакторинга) |
| 129 | |
| 130 | - [ ] Словарь существительных/глаголов явно согласован с snapshot/compositor. |
| 131 | - [ ] Нет нового `switch` по kind для разной **формы** UI. |
| 132 | - [ ] Control/оркестратор < ~300–400 строк или обоснован в ответе. |
| 133 | - [ ] `roslyn_get_diagnostics` по затронутым `.cs` — errors = 0. |
| 134 | - [ ] HCI-требования (если были) отражены в layout, не только в цвете. |
| 135 | |
| 136 | --- |
| 137 | |
| 138 | ## Validation snapshot v1 |
| 139 | |
| 140 | - Матрица наиболее полезна при **смешанных** запросах («карточки как в референсе» + рост `ChatPanelViewModel`). |
| 141 | - Ложное срабатывание: полный OOA&D на однострочный CSS-цвет — отсекается Fast symptom router. |
| 142 | - Следующее расширение v1.1: строки для `software.ml-applied` (OCR/barcode UI), `software-integration-kb`, тестовые контуры (xUnit → не redesign). |
| 143 | |
| 144 | ## Related |
| 145 | |
| 146 | | Документ | Роль | |
| 147 | |----------|------| |
| 148 | | `playbook-ooad-agent-operational-v1.md` | 7 шагов | |
| 149 | | `playbook-domain-nouns-verbs-decomposition-v1.md` | быстрый контракт | |
| 150 | | `index-knowledge-router-supplement-v1.md` | `router-software-transfer-matrix` | |
| 151 | | `agent-notes.md` | `software-cross-domain-transfer-stub-v1`, `route-context-hints-v1` | |
| 152 | |
| 153 | <!-- markdownlint-enable MD060 --> |
| 154 | |
| 155 | <!-- section:language-world-resolution-v1 --> |
| 156 | ## Language, tooling & UI resolution (шаг −1 / −2) |
| 157 | |
| 158 | **Карта:** `kb-software-authoring-language-worlds-v1.md` |
| 159 | |
| 160 | | Шаг | Сигнал | World tag | |
| 161 | |-----|--------|-----------| |
| 162 | | −1 | синтаксис, idioms, async, nullable | `software.authoring.dotnet.csharp` | |
| 163 | | −1 | **CSxxxx, analyzer, code action, rename, symbol, `roslyn_*`** | `software.authoring.dotnet.tooling.roslyn` | |
| 164 | | −1 | `composer.json` / `.php` | `software.authoring.php` | |
| 165 | | −2 | `Avalonia.*`, `*.axaml` | `…csharp.desktop-ui.avalonia` | |
| 166 | | −2 | `UseWPF` / WinForms / MAUI | `…desktop-ui.wpf` / `.winforms` / `.maui` | |
| 167 | |
| 168 | **Roslyn ≠ C#:** диагностика и рефакторинг через MCP — **tooling.roslyn**; не смешивать с OOA&D и не считать «частью языка». |
| 169 | |
| 170 | **Порядок:** authoring + matrix → csharp **и/или** tooling.roslyn → desktop-ui.* → HCI. |
| 171 | <!-- /section:language-world-resolution-v1 --> |
| 172 | |
| 173 | |