houseplan-card/docs/PRODUCT-IMPROVEMENT-PLAN.ru.md

# House Plan — актуальный план улучшений продукта

Срез: **локальная версия v1.60.2-beta.3**, 8 августа 2026 года.

Этот документ — рабочий backlog, а не журнал истории. Здесь находятся только нерешённые задачи, которые подтверждаются текущим кодом, интерфейсом, пользовательским руководством или зафиксированным scope продукта. После выхода изменения пункт удаляется из файла полностью; история остаётся в `CHANGELOG`.

## 1. Как читать и обновлять план

### Приоритеты

| Приоритет | Значение |
|---|---|
| **P0** | Подтверждённая потеря данных, нарушение модели доступа, опасное управление домом или блокировка основного сценария |
| **P1** | Регулярная пользовательская ловушка, недоступный основной сценарий, высокий риск регрессий или архитектурный долг, уже замедляющий развитие |
| **P2** | Существенное улучшение понятности, поддержки, производительности или качества, которое не блокирует текущую работу |
| **P3** | Условная продуктовая инициатива; начинать только после отдельного решения владельца и самостоятельного ТЗ |

На текущем срезе подтверждённых P0 нет. Если такой дефект появляется, он имеет приоритет над этой очередью и после исправления не остаётся в документе как закрытый пункт.

### Статусы открытых задач

| Статус | Значение |
|---|---|
| **Готово к ТЗ** | Проблема и ожидаемый результат понятны; перед кодом достаточно детализировать реализацию |
| **Нужно UX-решение** | Перед реализацией требуется утвердить конкретное пользовательское поведение |
| **Исследование** | Сначала нужны измерения, инвентаризация данных или прототип без изменения модели |
| **По запросу** | Инициатива соответствует scope, но не должна вытеснять основной backlog без отдельного решения |

### Обязательные правила

1. View остаётся главным ежедневным режимом; редакторы обслуживают его и не добавляют взаимодействия в просмотр без понятной пользы для членов семьи.
2. Ни одна миграция, оптимизация или очистка не удаляет пользовательские файлы и данные по косвенному признаку.
3. Новое поле настройки не добавляется без runtime-потребителя, локализации, backend validation, документации и теста совместимости.
4. Сложная геометрия развивается через чистые функции и сценарные матрицы, а не через дополнительные ветки внутри корневого render.
5. Большой рефакторинг делится на небольшие поведенчески нейтральные этапы. Переписывание приложения целиком не планируется.
6. Touch, мышь и клавиатура являются равноправными вариантами **режима просмотра**. Редакторы desktop-first: полная поддержка гарантируется для компьютера с мышью/клавиатурой, а touch-редактирование выполняется по остаточному принципу согласно `TOUCH-SUPPORT.md`. Светлая/тёмная тема и `prefers-reduced-motion` остаются общими требованиями всех поддерживаемых поверхностей.

## 2. Текущий срез и главные риски

| Область | Фактическое состояние | Главный оставшийся риск |
|---|---|---|
| Пользовательская ценность | Основные spatial-сценарии Home Assistant закрыты; продукт сочетает просмотр, редактирование, геометрию, свет, климат и быстрые действия | Дальнейшее добавление функций без упрощения существующего UI ухудшит осваиваемость |
| View на desktop | Информативен и визуально целостен | Часть контекста комнаты по-прежнему зависит от hover и маленькой иконки HA-зоны |
| View на touch | Устройства имеют tap/long-press сценарии | У комнаты нет полноценного tap-эквивалента hover-подсказки |
| Редакторы | Функционально глубокие, с сеткой и общей сессионной историей | Много скрытых жестов и маленьких зон попадания; полноценного клавиатурного управления холстом нет |
| Настройки | Все основные уровни наследования представлены | Диалоги пространства, устройства и общих настроек длинные и смешивают разные задачи |
| Состояния устройств | Семантика вычисляется общими resolver-функциями | Пользователь не видит в форме, какое состояние и какая сущность будут определять итоговый визуал |
| Данные и совместимость | Есть versioned migration и явная оптимизация | В модели остаются legacy-поля и внутренние ключи без публичного жизненного цикла |
| Frontend | 29 TypeScript-файлов, 28 333 физические строки | `src/houseplan-card.ts` содержит 13 840 строк — 48,8% всего TypeScript; любое изменение затрагивает слишком широкую поверхность |
| Типизация | Строгий TypeScript включён | В `src/` остаётся около 553 употреблений `any`, включая внутреннюю бизнес-логику, а не только границу HA |
| Проверки | Инвентаризация: 444 Node unit, 102 pure backend, 50 HA-harness и 114 browser smoke | Геометрические и визуальные регрессии всё ещё часто обнаруживаются по пользовательским скриншотам; нет системной golden-image матрицы и измеряемых performance budgets |
| Документация | Подробное русское руководство и двуязычный changelog существуют | Скриншоты и часть обзорного текста отстают от текущего состава редакторов |

Главная цель ближайших циклов: **сделать уже существующую глубину понятной, доступной и дешёвой в сопровождении**, не расширяя без необходимости поверхность настроек.

## 3. Реестр открытых инициатив

| ID | Приоритет | Статус | Результат |
|---|---|---|---|
| HP-UX-01 | P1 | Нужно UX-решение | Карточка комнаты по tap/click с чистой площадью и доступными метриками |
| HP-UX-02 | P1 | Нужно UX-решение | Понятный inbox устройств: новые, размещённые, скрытые и доступные к повторному добавлению |
| HP-UX-03 | P1 | ТЗ на согласовании | Live preview отображения устройства и предсказуемый текстовый режим значения |
| HP-UX-04 | P1 | Готово к ТЗ | Разделение длинных диалогов по задачам и условное скрытие неприменимых полей |
| HP-UX-05 | P3 | По запросу | Помощь по жестам и недорогое улучшение touch-редакторов без требования паритета с desktop |
| HP-A11Y-01 | P1 | Исследование | Семантика плана для клавиатуры и screen reader; состояние читается не только цветом |
| HP-A11Y-02 | P1 | Готово к ТЗ | Единое кастомное подтверждение вместо оставшихся browser `confirm()` |
| HP-DATA-01 | P1 | Исследование | Единый реестр схемы, миграций и срока жизни compatibility-полей |
| HP-ARCH-01 | P1 | Готово к ТЗ | Поэтапное разбиение корневого компонента и монолитных стилей |
| HP-QA-01 | P1 | Готово к ТЗ | Визуальная regression-матрица геометрии, света и адаптивных диалогов |
| HP-PERF-01 | P1 | Исследование | Воспроизводимый профиль большого дома и бюджеты производительности |
| HP-DOC-01 | P1 | Готово к ТЗ | Актуальные скриншоты и единая пользовательская навигация по документации |
| HP-UX-06 | P2 | Нужно UX-решение | Явный room override для Glow |
| HP-UX-07 | P2 | Нужно UX-решение | Упрощённая и объяснимая система масштабов названия и карточки комнаты |
| HP-UX-08 | P2 | Нужно UX-решение | Визуальный конструктор правил иконок с advanced regex-режимом |
| HP-UX-09 | P2 | Исследование | Диагностика слишком больших подложек и безопасное уменьшение растров |
| HP-UX-10 | P2 | Нужно UX-решение | Более направляемое создание комнат на основе Floors/Areas Home Assistant |
| HP-A11Y-03 | P2 | Исследование | Клавиатурное редактирование выбранных объектов на сетке |
| HP-ENG-01 | P2 | Готово к ТЗ | Измеряемое backend coverage, строгая Python-типизация и quality-scale хвосты |
| HP-ENG-02 | P2 | Нужно UX-решение | Безопасный пользовательский support report из раздела обслуживания |
| HP-ENG-03 | P2 | Исследование | Явное решение по внутренним фильтрам и группировке устройств |
| HP-PROD-01 | P3 | По запросу | Пользовательские картинки как объекты декора |
| HP-PROD-02 | P3 | По запросу | Сводный security glance по дверям, окнам и замкам |
| HP-PROD-03 | P3 | По запросу | Пространственное отображение person/presence |
| HP-PROD-04 | P3 | По запросу | Пороговые цвета метрик карточки комнаты |

## 4. P1 — ближайший продуктовый цикл

### HP-UX-01 — карточка комнаты в режиме просмотра

**Проблема.** Чистая площадь и часть контекста комнаты доступны через hover. На touch hover отсутствует, а переход к HA area спрятан в маленькой иконке около названия. Нажатие по самому полу комнаты сейчас не даёт равнозначного результата.

**Предлагаемое поведение.** Обычный tap/click по свободной части комнаты в View открывает компактный `hp-dialog`:

- название комнаты;
- чистая площадь по той же геометрии, которая используется в hover и расчётах;
- только доступные метрики: температура, влажность, LQI и состояние света;
- явное действие «Открыть зону в Home Assistant», если у комнаты есть area;
- закрытие без навигации для комнаты без area.

Hover-подсказка на desktop остаётся быстрым просмотром. Клик по устройству, двери, окну, кнопке комнаты или другому интерактивному объекту не должен проваливаться в комнату.

**Эдж-кейсы.** Комната без area; вложенные комнаты; отверстия в чистом полу; толстые и скрытые стены; перегородки и колонны; Glow под курсором; pan до отпускания указателя; несколько комнат с общей стеной; выключенные метрики; пустое название.

**Критерии приёмки.** Площадь совпадает с hover и resize; сценарий работает мышью, touch и клавиатурой; один tap не открывает одновременно устройство и комнату; переход в HA существует только как подписанная кнопка.

### HP-UX-02 — inbox и жизненный цикл устройств

**Проблема.** Текущие «Добавить» и «Показать скрытые» технически позволяют восстановить устройство, но не объясняют, почему оно не появилось на плане, было скрыто или снова стало доступно. Автоматический фильтр, ручное скрытие и удаление выглядят как похожие состояния.

**Целевая структура.** В редакторе устройств нужен единый список с фильтрами:

| Раздел | Что показывает | Действия |
|---|---|---|
| Новые | Привязки HA, которых ещё нет на плане | Добавить, скрыть |
| На плане | Видимые маркеры | Найти на плане, редактировать |
| Скрытые | Маркеры с ручным `hidden` и первично отфильтрованные кандидаты | Показать, добавить, объяснить причину |
| Доступные снова | Удалённые привязки, которые можно добавить как новый маркер | Добавить заново |

Причина должна быть пользовательской: «скрыто вручную», «служебная сущность», «исключённый тип», «уже представлено родительским устройством». Внутренние regex и id не показываются как основное объяснение.

**Инварианты.** Просмотр списка не изменяет конфигурацию; повторное добавление не создаёт дубликат binding; никакой раздел не удаляет файл или trail без явного подтверждённого действия; одна и та же привязка получает один жизненный цикл на всех клиентах.

### HP-UX-03 — предпросмотр отображения устройства

**ТЗ:** `docs/superpowers/specs/2026-08-08-device-display-preview-design.md` — проект на согласовании, включая integration provenance, actual preview, демонстрацию activity и предсказуемый text value.

**Проблема.** Поле «Отображение» выбирает сложную комбинацию подложки, иконки, активности и значения, но форма не показывает итог для текущих сущностей. В режиме «Значение вместо иконки» числовое состояние отображается, а текстовое молча возвращает иконку.

**Предлагаемая система.** В диалоге устройства показывать live preview, построенный тем же `resolvedDeviceVisual`, что и маркер на плане. Рядом выводить короткое объяснение: какая сущность выбрана источником, доступность, фактический статус и тип активности. Статическая «легенда всех цветов» вторична; важнее объяснить текущее устройство.

Для текстового value-режима нужно утвердить один контракт:

- использовать локализованное Home Assistant значение;
- одна строка с ограничением ширины и ellipsis;
- полное значение доступно в tooltip/ARIA и карточке устройства;
- `unknown`/`unavailable` используют обычное приглушённое представление, а не новый цвет;
- слишком длинное или отсутствующее значение предсказуемо возвращает иконку и объясняет это в preview.

В тот же небольшой пакет входит исправление UI-подписей без смены ключей хранения: `show_temperature` должен называться «Показывать температуру и влажность», а вложения — «Файлы и инструкции» с форматами и лимитом.

### HP-UX-04 — информационная архитектура диалогов

**Проблема.** Диалоги пространства, устройства и общих настроек содержат несколько независимых задач в одной длинной прокрутке. У виртуального или пассивного объекта видны поля, которые не могут дать полезный результат.

**Целевая группировка.** Это изменение интерфейса, а не модели данных.

| Диалог | Разделы |
|---|---|
| Пространство | Основа; комнаты и подписи; внешний вид; окружение |
| Устройство | Привязка; действие; состояние и свет; внешний вид; информация и файлы |
| Общие настройки | Цвета; окружение; обслуживание; о продукте |

На desktop допустимы вкладки или боковая навигация; на узком экране — последовательные секции/аккордеон. Выбранный вариант должен оставаться нативно понятным в HA и не создавать вложенный горизонтальный скролл.

**Условность полей.** Световые controls и радиус показываются только когда привязка может участвовать в on/off-свете; climate temperature — только при climate; vacuum — только при источнике координат; настройки состояния скрываются у полностью виртуального маркера; удаление и скрытие остаются видимыми действиями жизненного цикла.

**Критерии приёмки.** Переключение разделов не теряет несохранённые значения; ошибки ведут к конкретному полю; footer стабилен при любой высоте; весь сценарий проходит клавиатурой; существующие конфиги сохраняются без миграции.

### HP-A11Y-01 — доступная семантика View

**Проблема.** Комнаты являются SVG-формами с hover, устройства — кликабельными `div`, а смысл working/open/alarm часто считывается прежде всего по цвету. Общий `hp-dialog` закрывает модальную часть, но сам план остаётся слабым для клавиатуры и screen reader.

**Исследование и целевой контракт.**

1. Определить компактное дерево доступности, которое не создаёт сотни tab-stop: roving tabindex либо отдельный список «Комнаты / Устройства / Проёмы».
2. Для интерактивного объекта сформировать единый `aria-label`: имя, тип, локализованное состояние, комната и доступное действие.
3. Добавить нецветовой визуальный признак для критических состояний: тревога, открыто/разблокировано, активная механика. Он не должен превращать каждый маркер в набор badge.
4. Room card из HP-UX-01 сделать основной доступной точкой комнаты.
5. Проверить порядок фокуса после смены пространства, режима и закрытия карточки.

**Критерии приёмки.** Основные View-сценарии доступны без мыши; axe-проверка не находит базовых нарушений name/role/value и modal boundaries; при отключённом цвете состояния остаются различимы текстом или формой.

### HP-A11Y-02 — единое подтверждение опасных действий

**Проблема.** В коде остаются browser `confirm()` для удаления комнаты, пространства, плана, устройства, незавершённого контура/сегмента и для unlock. Они визуально и семантически отличаются от остальных диалогов, плохо объясняют объект операции и не дают контролировать начальный фокус.

**Решение.** Компонент `hp-confirm` поверх `hp-dialog` с promise API:

- заголовок операции, имя объекта и короткое описание последствий;
- destructive-кнопка визуально отделена от cancel;
- начальный фокус на безопасном действии;
- `Esc`, focus trap и restore focus наследуются от `hp-dialog`;
- unlock имеет отдельную предупреждающую семантику и никогда не переиспользует текст удаления;
- повторный вызов не накладывает два подтверждения и не применяет callback старого экземпляра.

**Критерий приёмки.** В runtime-коде нет прямых `confirm()`; каждый destructive path имеет browser smoke с cancel и accept; touch footer не обрезается.

### HP-DATA-01 — единая схема и lifecycle compatibility-полей

**Проблема.** Типы TypeScript, формы, runtime и Voluptuous validation синхронизируются вручную. В текущей модели видны разные классы долга:

- устаревший карточечный `tap_action`;
- read-compatibility значение display `ripple`;
- временный `settings.show_all`;
- `vacuum.room_highlight` и `vacuum.segment_map`, для которых нет найденного runtime-потребителя;
- `settings.group_lights` и `settings.exclude_integrations`, влияющие на runtime без поддерживаемого пользовательского интерфейса.

**Первый этап — исследование без удаления.** Сформировать registry полей с типом, default, уровнем наследования, UI-видимостью, runtime consumer, frontend/backend enum, версией появления, migration и сроком read-compatibility. Локальный анализатор конфига должен показать, какие legacy-поля реально встречаются, не отправляя телеметрию наружу.

**Второй этап.**

- parity-тест сравнивает frontend и backend enum/limits;
- «Оптимизировать планы» показывает конкретную миграцию до записи;
- unknown future fields сохраняются;
- deprecated поле удаляется из публичной модели только после явно заданного окна чтения;
- внутренний ключ либо получает поддерживаемый UI, либо становится фиксированным правилом и удаляется из хранимой конфигурации.

**Критерии приёмки.** Нет поля, одновременно публичного в типе/schema и не имеющего решения «используем / мигрируем / удаляем»; новый schema drift ломает CI; открытие и сохранение старого конфига не меняет визуал без явной миграции.

### HP-ARCH-01 — декомпозиция frontend без big bang

**Проблема.** Почти половина TypeScript находится в одном `houseplan-card.ts`; там смешаны lifecycle Lit, server sync, pointer state machines, геометрические команды, все диалоги и render layers. `styles.ts` также остаётся глобальным монолитом. Это главный множитель стоимости любых следующих функций.

**Целевые границы.**

```text
src/
  app/
    houseplan-card.ts          # composition, HA lifecycle, top-level routing
    houseplan-store.ts         # normalized config/layout snapshot and revisions
    navigation-controller.ts   # space, mode, viewport, warm remount
  editors/
    plan/                      # tools, pointer state, commands, toolbar
    devices/                   # discovery, form state, marker commands
    decor/                     # tools, form state, render orchestration
  render/
    rooms.ts
    walls.ts
    openings.ts
    lighting.ts
    devices.ts
    vacuum.ts
  dialogs/
    room-dialog.ts
    space-dialog.ts
    device-dialog.ts
    settings-dialog.ts
  components/
    hp-dialog.ts
    hp-confirm.ts
    hp-color-opacity.ts
```

Это направление, а не требование создать все файлы заранее. Каждый этап переносит одну законченную ответственность вместе с типами и тестами.

**Порядок безопасного разбиения.**

1. Render-only слои с явным immutable input и callbacks.
2. Модели состояния диалогов и их validation/serialization.
3. Контроллеры Plan/Devices/Decor как конечные автоматы жестов.
4. Нормализованный store и серверные ревизии.
5. Scoped styles рядом с компонентами.

**Ограничения.** Никакой новой второй модели геометрии; чистые модули `logic`, `wall-thickness`, `open-spans`, `resize`, `physical-geometry`, `sun` и `device-visual` остаются источниками истины. В новой продуктовой логике используется `unknown` и type guards вместо `any`; HA adapter boundary может быть изолированным исключением.

**Критерии приёмки.** Корневой компонент становится композиционным, ориентир — менее 3 500 строк; feature-модуль обычно не превышает 800 строк; количество `any` монотонно снижается; один и тот же полный smoke-набор проходит до и после каждого этапа; визуальных изменений в refactor-only PR нет.

### HP-QA-01 — visual regression для геометрии и диалогов

**Проблема.** 114 browser smoke хорошо проверяют события и DOM-контракты, но не гарантируют отсутствие белых щелей, ложных торцов, чёрной промежуточной заливки, смещения footer или обрезания заголовка.

**Golden-image матрица.**

| Набор | Обязательные случаи |
|---|---|
| Стены | одинаковая/разная толщина, T/X-стыки, вложенная комната, реальная+виртуальная граница, перегородка и колонна |
| Проёмы | дверь/окно, тонкая/толстая стена, тоннель, край стены, общая стена |
| Свет | Glow через дверной проём, отсечение откосами, блокировка перегородкой/колонной, несколько источников, солнечные лучи |
| Hover | чистый пол, общие стены, Glow поверх комнаты, вложенные контуры |
| Диалоги | длинный RU/EN title, мобильная ширина/высота, footer, keyboard focus, color picker popover |
| Темы | тёмная и светлая HA theme, View и каждый editor |
| Масштаб | 0.4×, fit, крупный zoom, warm remount |

Снимки строятся на синтетических fixtures. Обновление эталона требует явного просмотра diff, а не автоматической перезаписи.

**Критерии приёмки.** Матрица запускается отдельным CI job; браузер, viewport, шрифты и анимации детерминированы; обычные DOM-smoke остаются быстрым первым слоем; новый тип стыка или диалога добавляет fixture в ту же матрицу.

### HP-PERF-01 — профиль большого дома

**Проблема.** Кэши чистого пола и световой геометрии уже есть, но нет воспроизводимого ответа, сколько стоит план с большим числом комнат, физических объектов, декора и устройств. Без baseline оптимизация остаётся реактивной.

**Reference fixture.** Не менее 60 комнат, 200 устройств, 100 проёмов, 100 перегородок/колонн, 500 объектов декора, несколько этажей и частые HA state updates. Все данные синтетические.

**Измерения.** Первый стабильный render; смена пространства; один state update; pan/zoom; открытие больших диалогов; пересчёт Glow; resize сложной комнаты; объём кэшей после продолжительной работы.

Сначала фиксируется baseline на одном Chromium/CI-профиле. Затем утверждаются budgets: отсутствие long task выше согласованного порога в View, отсутствие роста памяти после циклов переключения и максимум допустимой регрессии к baseline. Числа нельзя выбирать до первого измерения.

**Критерии приёмки.** Benchmark повторяем; результат хранится как artefact; PR с изменением горячего пути показывает diff; кэши имеют ограничение и корректную инвалидацию; производительность не проверяется только субъективным «плавно».

### HP-DOC-01 — документация текущего пользовательского опыта

**Проблема.** User guide подробный, но обзорные README-скриншоты и часть формулировок отражают более ранний состав редакторов. Пользователь сначала видит именно README/HACS, поэтому несоответствие ухудшает onboarding.

**Пакет.**

- переснять на синтетическом доме View, создание пространства, комнату, Plan editor, Devices editor, Background editor и карточку устройства;
- коротко объяснить различие «Контур комнаты / Перегородка / Колонна / Граница / Проём»;
- добавить таблицу жестов mouse/touch/keyboard;
- провести проверку внутренних ссылок и терминов RU/EN;
- README оставить обзорным, детали вести в `USER-GUIDE.ru.md` и тематические документы;
- для нескольких карточек с разными стартовыми пространствами явно зафиксировать поддерживаемый сценарий и ограничения.

**Критерии приёмки.** Ни один screenshot не показывает отсутствующую кнопку или старое название; основной путь от установки до первой комнаты читается без changelog; ссылки проверяются в CI.

## 5. P2 — следующий слой улучшений

### HP-UX-06 — явный Glow на уровне комнаты

Сейчас пространство может выбрать Glow, а комната — наследовать его или переопределить на `none/lqi/light/temp`. Комната не может зафиксировать Glow, если пространство позднее переключат в другой режим.

Нужно добавить `glow` в room override без изменения семантики наследования. До кода требуется решить, участвует ли явно отключённая от Glow соседняя комната в физическом распространении света или только не рисует базовое затемнение. Решение фиксируется одной матрицей для fill, clip и переходов через виртуальные/дверные границы.

### HP-UX-07 — одна объяснимая система масштабов комнаты

Сейчас итоговый размер образуют масштаб карточки пространства, отдельные `name_scale`/`label_scale` комнаты и сохранённый drag-scale карточки. Система мощная, но пользователь не видит итоговый коэффициент и способ сброса конкретного уровня.

Цель: оставить один default пространства и явные room overrides для названия и метрик. Визуальный resize либо редактирует те же числа, либо показывает фактическое значение и кнопку Reset. Legacy layout-scale читается без визуального скачка и преобразуется только явной оптимизацией.

### HP-UX-08 — конструктор правил иконок

Обычный режим должен предлагать поля «домен», `device_class`, слова в имени/модели и итоговую иконку. Порядок правил остаётся видимым, тестовое устройство показывает первое сработавшее правило и причину. Regex сохраняется как advanced-режим с валидацией и предупреждением о приоритете; существующие regex не переписываются автоматически.

### HP-UX-09 — большие подложки

Добавить локальную диагностику разрешения, decoded memory и ожидаемого размера перед загрузкой PNG/JPEG/WebP. Для больших растров предложить безопасную копию с уменьшением, сохраняя оригинал до подтверждения успешной загрузки. SVG не растеризуется автоматически. Порог определяется после тестов на типичных wall-tablet/desktop устройствах и документируется вместе с file-size limit.

### HP-UX-10 — Floors/Areas как направляемый onboarding

При создании комнат список area должен учитывать выбранный/импортированный floor, первым показывать неиспользованные зоны этого этажа и предлагать их имя. Нужен небольшой progress «размечено N из M зон» и явный путь для комнаты без zone. Компонент по-прежнему не переименовывает и не переносит HA area — он только читает registry.

### HP-A11Y-03 — клавиатурное редактирование выбранных объектов

Первый этап не обязан рисовать произвольный polygon только клавиатурой. Достаточно сделать выбор и точные операции:

- roving focus между объектами текущего слоя;
- Enter — свойства, Delete — только выбранный объект с подтверждением там, где оно требуется;
- стрелки — на один узел сетки, модификатор — на согласованный увеличенный шаг;
- Escape — отмена текущего жеста/выбора;
- доступное объявление координат, длины, угла и результата Undo.

До реализации нужен прототип конфликтов со scroll, pan и текстовыми полями.

### HP-ENG-01 — измеряемое инженерное качество backend

- подключить `pytest-cov` и зафиксировать честное покрытие backend, затем довести его минимум до 95% по исполняемым строкам;
- настроить строгую Python-типизацию по модулям, начиная с validation/store/websocket boundaries;
- добавить lint/format gate без массового шумного rewrite;
- закрыть применимые пункты quality scale: troubleshooting и examples;
- пользовательские ошибки WebSocket, которые доходят до UI, должны иметь стабильный code и локализованное сообщение.

### HP-ENG-02 — support report без персональных данных

В «Обслуживании» добавить действие «Скопировать отчёт для поддержки». Отчёт содержит версии card/integration/HA, модель данных, количества пространств/комнат/стен/устройств, состояние ревизий, результаты read-only validation и активные Repairs. По умолчанию исключаются имена, entity/device id, URLs, пути файлов, описания и координаты дома. Перед копированием пользователь видит полный текст.

### HP-ENG-03 — фильтры и группировка как явное решение

Провести инвентаризацию `exclude_integrations` и `group_lights` на реальных локальных конфигах. Для каждого ключа выбрать одно из двух:

1. поддерживаемая advanced-настройка в inbox с понятным эффектом и default;
2. фиксированное продуктовой логикой поведение без хранимого ключа.

Нельзя оставлять третий вариант — скрытую настройку, которая влияет на результат, но не видна пользователю и не имеет migration policy.

## 6. P3 — инициативы только по отдельному решению

### HP-UX-05 — помощь по жестам и best-effort touch-редакторы

**Статус поддержки.** Редакторы являются desktop-first инструментами администратора. Полный touch-паритет не является целью или критерием релиза. Пользователям рекомендуется редактировать планы на компьютере; неудобная, частичная или отсутствующая touch-операция допустима, если View и безопасность данных не страдают.

**Проблема.** Даже в эталонной desktop-среде скрытые жесты (`double click`, `Ctrl`/`Cmd`, `Shift`, конечные ручки и тонкие объекты) не всегда объясняются в момент работы. Некоторые touch-улучшения можно получить дёшево, не усложняя модель взаимодействия.

**Что изменить.**

- интерактивные ручки и icon-only кнопки получают увеличенную невидимую область там, где это не создаёт конфликтов геометрии или desktop-ввода; размер 44×44 является ориентиром, а не обязательным контрактом всех редакторов;
- линии, тонкие контуры и концы сегментов используют scale-independent hit area;
- активный инструмент показывает одну короткую контекстную подсказку, а не постоянную стену текста;
- Help overlay собирает `Ctrl`/`Cmd`-замыкание, `Shift`-углы, double click свойств, Undo/Redo, pan/zoom и Erase;
- подсказка различает keyboard modifier по платформе;
- overlay можно закрыть навсегда и повторно открыть из панели;
- дорогие precision-жесты не переносятся на touch только ради формального паритета; допустимо скрыть/отключить операцию и рекомендовать desktop;
- best effort не позволяет сохранять случайную геометрию после pinch, `pointercancel` или второго касания и не позволяет ломать выход обратно в View.

**Эдж-кейсы.** Пересекающиеся hit-зоны; две близкие ручки; pan/pinch над выбранным объектом; stylus; zoom 0.4× и крупный zoom; скрытая панель; `prefers-reduced-motion`; гибридный ноутбук; планшет с подключённой мышью.

**Критерий.** Desktop-подсказки и рабочие операции остаются понятными и полными. Touch-улучшения принимаются отдельно по конкретным сценариям; общая функциональная эквивалентность редакторов не проверяется.

### HP-PROD-01 — картинки как объекты декора

До UI нужен отдельный lifecycle-дизайн: upload, reuse, copy-on-write, ссылки между пространствами, квоты, замена, экспорт, явное удаление и защита от файлов-сирот. Геометрический transform может использовать существующий контракт декора, но серверное хранение нельзя строить как побочный вариант вложений устройства.

### HP-PROD-02 — security glance

Один компактный статус дома: закрыты ли двери/окна и заперты ли замки, с раскрытием списка проблемных точек. Это только просмотр и навигация; новый быстрый массовый unlock запрещён.

### HP-PROD-03 — person/presence на плане

Нужно сначала выбрать модель приватности и источник: HA person area, device tracker или присутствие комнаты. Не смешивать длительное присутствие с коротким событием движения и не рисовать ложную точную позицию, если HA знает только area.

### HP-PROD-04 — пороговые цвета метрик комнаты

Температура, влажность и LQI в карточке комнаты могут иметь настраиваемые диапазоны, но настройка не должна дублировать существующие fill thresholds. Сначала определить общую модель порогов и наследования.

## 7. Рекомендуемый порядок выполнения

| Пакет | Состав | Почему так |
|---|---|---|
| **A. Понятный View** | HP-UX-01, HP-A11Y-01, HP-A11Y-02, короткие подписи из HP-UX-03 | Максимальная ежедневная польза и обязательный desktop/touch-паритет View |
| **B. Защита от повторных регрессий** | HP-QA-01, HP-PERF-01, начало HP-DATA-01 | Сначала измеряем и фиксируем поведение, затем продолжаем крупные изменения |
| **C. Понятная настройка устройств** | HP-UX-02, HP-UX-03, HP-UX-04 | Общая информационная архитектура строится поверх уже зафиксированной семантики данных |
| **D. Desktop-редакторы без скрытых ловушек** | HP-A11Y-03; HP-UX-05 только по запросу или когда улучшение дёшево | Полнота и точность редакторов гарантируются на desktop; touch-паритет не должен раздувать сложность |
| **E. Модульность** | HP-ARCH-01 маленькими этапами на протяжении пакетов A–D | Не откладывать декомпозицию до отдельного многомесячного rewrite и не смешивать её с изменением поведения |
| **F. Второй приоритет** | HP-UX-06…10, HP-ENG-01…03 | Брать по одному после стабилизации соответствующего слоя |

Архитектурное разбиение, visual regression и schema registry — не отдельная «заморозка продукта». Каждый пользовательский пакет должен оставлять затронутый участок более модульным и лучше проверяемым, чем до него.

## 8. Матрицы качества

### Обязательные сценарные матрицы

| Матрица | Измерения |
|---|---|
| Устройство | binding kind × domain × device class × state × availability × display × controls |
| Свет | auto/explicit/control source × hidden/removed × fill mode × opening × wall/partition/column |
| Комната | area/no area × nested/shared × thick wall × fill override × touch/hover/keyboard |
| Геометрия | real/virtual × thickness A/B × corner/T/X × opening × resize × Undo/Redo |
| Декор | kind × solid/dashed × fill/stroke × transform × erase/select × zoom |
| Ввод View | mouse × touch × stylus × keyboard × View/kiosk; touch является обязательной поддерживаемой поверхностью |
| Ввод редакторов | desktop mouse/keyboard × Plan/Devices/Background; touch/stylus — safety floor и только отдельно обещанные сценарии |
| Миграция | legacy field × open/save × optimize × undo optimize × future unknown field |
| Адаптивность | RU/EN × light/dark × narrow/medium/wide × reduced motion |

### Метрики направления

| Метрика | Цель |
|---|---|
| Обычное действие, теряющее данные без явного решения | 0 |
| Публичное поле без runtime consumer или migration policy | 0 |
| Ключевая информация, доступная только через hover | 0 |
| Опасное действие через native `confirm()` | 0 |
| Критический статус, различимый только цветом | 0 |
| Новый `any` вне изолированного HA adapter boundary | 0 |
| Расхождение frontend/backend enum и limits | 0 в CI |
| Визуальная правка геометрии без соответствующего fixture | 0 |
| Размер `houseplan-card.ts` после декомпозиции | Ориентир <3 500 физических строк |
| Backend coverage после HP-ENG-01 | ≥95% исполняемых строк |

## 9. Release- и документационный процесс

Рабочий процесс владельца остаётся источником истины:

- обычные локальные правки вносятся без тестов и без коммитов;
- перед pre-release выполняются production build и минимально необходимые целевые unit/smoke проверки изменённых поверхностей;
- перед stable release выполняется полный frontend/backend/browser gate;
- текущие количества тестов берутся из `npm run inventory`, а не копируются навсегда в статусные документы;
- пользовательское изменение одновременно обновляет RU/EN changelog и соответствующую таблицу поведения/руководство;
- release body короткий: только значимые функции, остальное группируется как «Мелкие исправления и улучшения» / “Small fixes and improvements”, плюс ссылки на RU и EN changelog.

Сам этот файл обновляется иначе, чем changelog: завершённая инициатива удаляется, а не отмечается галочкой. Если задача утратила смысл из-за другого решения, она также удаляется с объяснением в ADR/spec или changelog соответствующего изменения.

## 10. Границы плана

В этот backlog не входят:

- 3D/isometric/фотореалистичное моделирование;
- редактор автоматизаций, сценариев и уведомлений;
- администрирование entity/device/area registry Home Assistant;
- история, графики, energy analytics, camera streams и медиапульт;
- общий dashboard framework;
- облачное хранение или телеметрия пользовательских планов.

Новая идея попадает сюда только если усиливает spatial glance, безопасное быстрое действие, создание/поддержку плана или качество реализации этих сценариев.