houseplan-card/docs/reviews/SPEC-REVIEW-362-r1.md

SPEC-REVIEW-362-r1

Issue: #362 — «Редактор подложки: устройства перехватывают hover и действия инструментов» Трек: small (лёгкий) · заход r1 · блокирующих циклов ревью ТЗ 0 из 2 Материал: тело issue #362 на момент разбора (createdAt/updatedAt 2026-08-29), последний комментарий автора «ТЗ готово, передача на ревью (small track, r1)». Дерево кода: ветка dev, HEAD 156be645 (issue ещё не в коде — ревью читает только описание поведения и сверяет его с фактическим состоянием dev, из которого фикс будет писаться).

Скоуп

Баг в редакторе Background (Подложка): видимая часть device layer (иконка, 44px псевдо-область, shell/frame, капсула, value/LQI/бейджи, пульсы, спутники opening-lock) остаётся pointer target и общими device-обработчиками, хотя по docs/DECOR-EDITOR.md устройства в Background — чисто контекстный ориентир на 35% opacity. Из-за этого устройство перехватывает hover/tooltip, может открыть карточку, выполнить toggle/run или начать drag устройства вместо действия активного инструмента Подложки (Line/Rectangle/Text/Furniture), и мешает поставить декоративный элемент в нужную точку.

Продуктовая рамка (docs/SCOPE.md): задача в J4 («GUI-only редактирование плана») и J6 («drag/resize, два редактора») — восстанавливает уже задокументированный (не новый) UX-контракт Background, а также защищает инвариант «никакой lock/alarm-экшен не срабатывает по тапу на плане» той же секции SCOPE.md, поскольку сейчас клик по устройству в Подложке может инициировать реальный HA-service-call. Правка входит в скоуп, новой персоны или поверхности не создаёт.

Как проверялось

Ревью ТЗ на small-треке не предполагает файла в docs/specs/ — проверено, файла docs/specs/362-*.md в дереве нет, как и требуется §5 PROCESS.md.

Каждое техническое утверждение ТЗ («Подтверждение по коду») сверено чтением актуального dev (156be645), а не принято на слово автора:

Утверждение ТЗ	Файл : строка	Результат сверки
.stage.mode-decor .devlayer { pointer-events: none } уже есть, но перекрывается	src/styles/plan.styles.ts:856	подтверждено — правило есть
.dev, .dev::before, .device-shell-frame явно pointer-events: auto	src/styles/devices.styles.ts:144,182,213	подтверждено дословно
_renderDevice() вешает click/contextmenu/pointerover/pointermove/pointerdown/up без учёта Background	src/houseplan-card.ts:12017-12029	подтверждено; role/tabindex действительно ограничены interactive = view|devices (:11980, :12012-13)
_clickDevice() блокирует только plan, Background проваливается в общий action-путь	src/houseplan-card.ts:5179-5182	подтверждено — только if (this._mode === 'plan') return;, ветки devices и общий tap-action идут дальше
_pointerDown() блокирует plan, отдельно обрабатывает view, всё остальное (включая Background) идёт в drag-путь устройства	src/houseplan-card.ts:6337-6361	подтверждено — после plan/view сразу this._drag = {...}
_showTip() не проверяет режим вовсе	src/houseplan-card.ts:6549-6561	подтверждено — единственная проверка hoverEnabled/_drag, режим не участвует
_ctxDevice() (правый клик) уже fail-closed вне View	src/houseplan-card.ts:5170-5177	не баг — if (this._mode !== 'view') return; уже безопасен для Background; ТЗ верно требует лишь сохранить это регрессионной проверкой, не выдаёт это за новый фикс
_selId (device selection) выставляется только в _pointerUp при moved	src/houseplan-card.ts:6388-6396 (единственное присваивание — houseplan-card.ts:6394)	подтверждено — фикс _pointerDown автоматически закрывает и «device selection» без отдельного гварда
:hover-покраска CSS не зависит от JS-обработчиков, а только от того, является ли элемент pointer target	src/styles/devices.styles.ts:329-407 (:host([data-pointer-hover]) .dev:hover и т. п.)	подтверждено — это обосновывает контрактный пункт 6 («CSS явно перекрывает descendants, JS-гварды одни pointer-events не заменяют») как техническую необходимость, а не избыточность
Терминология «Подложка» / «Просмотр» / «Устройства»	docs/USER-GUIDE.ru.md:56,109,120,198,1090 и др.	совпадает с интерфейсом, не изобретена
Ссылки на дубликаты #101, #213, #266	gh issue view 101/213/266	#213 — расширение hover/action до всей капсулы (источник «капсулы» в ТЗ), #266 — чисто структурный CSS-рефакторинг, #101 — переход View↔редакторы/фон; ни один не дублирует маршрутизацию событий Background, ссылки корректны
demo/smoke_decor.mjs существует, есть куда добавлять AC1/AC4	ls demo/smoke_decor.mjs	подтверждено

Гейты кода (typecheck/test/build/смоки) не запускались: на этапе ревью ТЗ кода ещё нет, проверке подлежит только описание поведения и его соответствие текущему dev.

Находки

Нет. High — 0, Medium — 0, Low — 0.

Рассмотренные и отклонённые кандидаты на находку:

• AC5 не называет конкретные файлы existing device/decor smokes. Отклонено: AC5 — регрессионная, а не основная проверка; ТЗ явно допускает альтернативное доказательство «чтение mode guards на код-ревью», выбор конкретных смоков — техническое решение реализации, не продуктовый вопрос, ревьюер не вправе его требовать на этом треке.
• Контракт требует сохранить fail-closed для _ctxDevice, хотя эта ветка уже безопасна. Отклонено как находка: ТЗ не выдаёт существующее поведение за новый фикс, а включает его в перечень side-effects, которые обязана держать регрессия — это корректная практика, не догадка.
• Не назван отдельный вопрос владельцу. Отклонено: ни один открытый пункт не требует продуктового решения (что видит/делает человек) — контракт нигде не меняет видимое поведение сверх уже описанного в DECOR-EDITOR.md (35% opacity, устройства вне magnet targets), только устраняет утечку интерактивности. Догадок, выданных за факт, не обнаружено — каждое поведенческое утверждение либо сверено с кодом (таблица выше), либо с DECOR-EDITOR.md/UX-MODES.md.

Что проверено и корректно

• Обязательные разделы лёгкого трека (§5 PROCESS.md): Проблема · Контракт · AC1…AC6 с указанным способом доказательства · Откат — все присутствуют в теле issue.
• Каждый AC — проверяемое утверждение с явным способом доказательства (smoke_decor.mjs, browser smoke со spies/counters, DOM/computed-style smoke, diff review + typecheck/unit/build). AC3 отдельно требует, чтобы мутация (возврат pointer-events:auto или снятие mode guard) роняла smoke — дисциплина «тест умеет падать» заложена уже в ТЗ.
• Скоуп: одна поверхность (Background), нет миграции конфига, нет новых compatibility/i18n-полей, нет влияния на touch-контракт и performance — критерии small (§5 PROCESS.md) выполнены одновременно, трек выбран верно.
• Контракт не вводит новый UX, а восстанавливает уже задокументированный в docs/DECOR-EDITOR.md (35% opacity, устройства исключены из magnet targets) и docs/UX-MODES.md (Background — desktop-first editor, View/Devices не меняются).
• Откат описан конкретно и с явным запретом частичного отката (CSS без guards или наоборот), что верно устраняет риск оставить один из двух путей случайного действия.
• Технические утверждения о текущем состоянии кода все подтверждены прямым чтением dev@156be645 (таблица выше) — ни одно не оказалось устаревшим или неточным.

Чего не проверял

• Сам фикс не написан — код-ревью впереди, эта проверка не про реализацию, а про план работы.
• Не проверялись гейты (typecheck/test/build/смоки) — на этапе ТЗ кода нет, гонять их не над чем.
• Не проверялся live browser-стенд — вне скоупа ревью ТЗ.

Вердикт

Зелёный. ТЗ полное, однозначное, каждый AC проверяем и привязан к способу доказательства, технические утверждения подтверждены чтением кода, догадок, выданных за факт, не найдено. Продуктовых вопросов владельцу нет и не требуется.