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

# Ревью ТЗ — issue #152, цикл r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/152
- **ТЗ:** `docs/specs/152-room-click-fit.md`, ветка `issue/152-room-click-fit`,
  коммит `7f8751b4dce84880edaab95600be7f028b9fab5f`
- **Этап:** spec (PROCESS.md §2.4)
- **Вердикт:** красный · цикл r1/4 · High: 2 · Medium: 2

## Скоуп ревью

Прочитаны в указанном порядке: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (§1,
§2, §3, §4, §7, §8, §12), тело issue #152 и все три комментария (уточнение и
самоотзыв про double-tap на фоне, актуализация аналитики 2026-08-15, хендофф
автора ТЗ), `docs/USER-GUIDE.ru.md` (терминология «Карточка комнаты», клик по
комнате в Resize, пространство/комната), `docs/UX-MODES.md`, `docs/TOUCH-SUPPORT.md`,
`docs/CANVAS.md` (§4–8: content frame, ZOOM_MIN/MAX, viewport/editor handoff),
`docs/CONFIG-COMPATIBILITY.md`. Issue не помечен `small`/`trivial` (аналитика:
сложность 4/10, риск 5/10, «обычный трек»), поэтому ТЗ корректно вынесено в
отдельный файл `docs/specs/152-room-click-fit.md`, а не в тело issue. Формат
ревью — полный документ.

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

ТЗ активно ссылается на «существующее» поведение как на данность (существующий
resolver, существующий double-tap, существующая доступная подпись, существующие
ZOOM_MIN/MAX). Каждое такое утверждение сверено с реальным кодом, а не принято
на веру:

- `src/houseplan-card.ts:4792-4793`, `src/space-geometry.ts:203` — `ZOOM_MIN`/
  `ZOOM_MAX`/`MIN_ZOOM` существуют, значения `8` и `1/3` подтверждены.
- `src/houseplan-card.ts:5023-5035` (`_resetZoom`) и `:5264-5300`
  (`_stagePointerUp`) — double-tap-to-reset реализован, но целиком внутри
  `if (this._kiosk) { … }`; вне этого блока на stage нет ни `@dblclick`, ни
  иной обработки двойного тапа (проверено также по полному списку обработчиков
  стейджа, `:14471-14480`).
- `src/houseplan-card.ts:14619-14646` (room hover через нативные
  `@mouseenter`/`@mouseleave` на каждой SVG-форме комнаты) против
  `:6528, :9936, :11045, :11096` (`[...rooms].reverse().find(r => this._pointInRoom(raw, r))`,
  используется инструментами Resize/Delete/Merge/Split) — это два разных
  механизма, не один вызываемый resolver.
- `src/houseplan-card.ts:16001-16065` (`_renderRoomLabel`) — `.roomlabel` не
  имеет `tabindex`/`role`/`aria-label`/`@keydown`; единственные `tabindex` в
  файле — `tabindex="-1"` на editor-тулбарах (`:9241, :16963, :17044`),
  подтверждает `docs/SCOPE.md` («no ARIA labelling of the plan»).
- `gh issue view 82` — открыт, всё ещё `S3-spec`: гипотеза «до реализации #82»
  в ТЗ корректна, `ViewportAnimator` в `src/` действительно не найден (grep).
- `gh api repos/Matysh/houseplan-card/issues/28` — `state: closed,
  state_reason: not_planned`, закрыт 2026-08-14, то есть до публикации этого ТЗ.
- `docs/specs/146-four-phase-sun-background.md` §15 и
  `docs/specs/138-adjacent-room-autoclose.md` §13 — эталон формата AC с
  инлайн-аннотацией способа доказательства, использован как мера сравнения.

## Находки

### High-1 — ни один AC не указывает способ доказательства

**Где:** `docs/specs/152-room-click-fit.md` §11 (строки 172–187).

Раздел перечисляет 14 пронумерованных критериев без пометки `unit`/`backend`/
`smoke`/`golden`/«ревью кода» у каждого — в отличие от §12 «План тестирования»,
который группирует проверки по категории, но не привязывает их к номерам AC.
Например, AC5 («Flat и Isometric проверяются по итоговой экранной геометрии»)
может быть закрыт unit-тестом проекции, browser smoke со скриншотом или
golden-эталоном — все три упомянуты в §12, и по тексту ТЗ невозможно понять,
какой из них действительно обязателен для приёмки, а какой — просто
сопутствующий.

PROCESS.md §2.5 (DoR) требует буквально: «AC1…ACn — пронумерованные проверяемые
критерии приёмки; у каждого указано, чем он доказывается: unit / backend /
smoke / golden / «ревью кода»». Соседние ТЗ этого же репозитория соблюдают это
дословно (`docs/specs/146-four-phase-sun-background.md:417-465`: «**AC1
(`unit`; разработчик):**» и так для всех 16 пунктов; аналогично
`docs/specs/138-adjacent-room-autoclose.md:276-323`). ТЗ #152 — единственное
из свежей серии, где это правило не выполнено ни разу.

**Почему High, а не Low:** это не стилистическая придирка, а прямое условие
готовности к разработке (§2.5) и то, что мне прямо поручено проверить в этом
ревью («указание способа доказательства» для каждого AC). Без этой аннотации
issue не может законно перейти в `S5-ready`.

**Что нужно поправить:** проставить у каждого из AC1–AC14 способ доказательства
и исполнителя, как в §15 `docs/specs/146-...md`.

### High-2 — потерян отдельный проверяемый AC про синхронность hit targets во время перехода

**Где:** `docs/specs/152-room-click-fit.md` §8 (строки 130–151) и §11 (172–187);
ср. issue #152, пункт критериев приёмки «Viewport и все SVG/HTML hit targets
остаются синхронны во время перехода» (14-й из 15 чекбоксов тела issue).

Это требование в финальном ТЗ не стало отдельным AC — оно осталось прозой
внутри §8: «Viewport, SVG и HTML overlays получают один и тот же camera state
на каждом кадре; промежуточное рассогласование hit targets недопустимо.» Ни
одного номера в §11, ни отдельного пункта browser smoke в §12 (там есть
«Flat/Isometric screenshot bounds; ни один видимый слой или hit target не
отстаёт» — но это один общий пункт про финальный кадр, а не про сам переход
кадр за кадром) под это не выделено.

**Сценарий, которому это открывает дорогу:** как только заработает `ViewportAnimator`
(#82) и переход из клика по комнате в её fit станет анимированным tween'ом,
визуальный viewBox обновляется на каждом кадре, а SVG/HTML hit-элементы
(устройства, проёмы, room label) должны обновляться синхронно. Если реализация
пересчитывает hit-геометрию на кадр позже видимой, пользователь тапает туда,
где устройство видно **сейчас**, и промахивается — либо получает клик по
случайно оказавшемуся там другому объекту. Именно этот класс дефекта
(«hit target отстаёт от кадра во время перехода») уже упомянут как прецедент в
`AGENTS.md` (#89 — «смок, который не умел падать» стоил целого цикла ревью), и
без отдельного AC с проверяемым доказательством ничто не гарантирует, что тест
на это вообще напишут, а не просто положатся на прозу §8.

**Почему High:** это не новая функциональность сверх скоупа — она уже была
явно сформулирована владельцем в теле issue как критерий приёмки и молча
выпала при переносе в ТЗ. Восстановление контракта — не расширение задачи, а
исправление ТЗ до его полноты.

**Что нужно поправить:** вернуть требование как отдельный пронумерованный AC с
указанным способом доказательства (browser smoke с промежуточными кадрами
tween, не только конечным) и явной строкой в §12.

### Medium-1 — accessibility-раздел выдаёт «существующую accessible-подпись» за факт, хотя такой доступности сегодня нет

**Где:** `docs/specs/152-room-click-fit.md` §9 (строки 153–163), формулировка
«Существующая доступная подпись либо room-card target получает action Enter и
Space».

`.roomlabel` (`src/houseplan-card.ts:16043-16056`, `_renderRoomLabel`) сегодня
не имеет ни `tabindex`, ни `role`, ни `aria-label`, ни `@keydown` — только
pointer-обработчики для drag в Plan-редакторе и клик на дочерней `ha-icon`
(переход в HA area). Единственные `tabindex` во всём файле — три
`tabindex="-1"` на editor-тулбарах (`:9241, :16963, :17044`), что снимает tab-
stop, а не добавляет. Это согласуется с прямой формулировкой `docs/SCOPE.md`
(«Accessibility: … no ARIA labelling of the plan») — сегодня в плане нет ни
одного клавиатурно-доступного или ARIA-размеченного элемента вообще.

Формулировка §9 читается как «добавить действие к уже доступному элементу», а
по факту задача вводит **первый** в продукте клавиатурно-фокусируемый,
ARIA-размеченный элемент плана, причём по одному на каждую комнату — со всеми
последствиями (порядок табуляции по потенциально многим комнатам,
обнаруживаемость, стили `:focus-visible`, отсутствие конфликта с уже занятыми
`tabindex="-1"` зонами тулбаров). Раздел §9 сам по себе технически осторожен
(явно запрещает невидимую полноэкранную сетку tab-stop), но опирающееся на него
предложение 1 и допущение из AC12 создают впечатление меньшего объёма работы,
чем есть на самом деле, и не фиксируют явно, что это новая a11y-поверхность, а
не расширение существующей.

**Почему Medium:** это не блокирует ни один AC — предложенное поведение
реализуемо, задача была явно запрошена в теле issue (пункт про Enter/Space уже
был в исходных критериях). Но формулировка занижает объём и скрывает
продуктовый факт (первая ARIA-разметка плана), который стоит зафиксировать
явно, а не как побочный эффект неточной фразы.

**Заведён отдельный issue** https://github.com/Matysh/houseplan-card/issues/182.

### Medium-2 — «существующий» double-click/tap fit-all на фоне на деле существует только в kiosk

**Где:** `docs/specs/152-room-click-fit.md` §3 («не входит… изменение
существующего double-click/tap fit всего плана на свободном фоне»), §7
(«Double click/tap по свободному фону сохраняет существующий fit/reset всего
плана без изменений»).

`docs/UX-MODES.md` документирует double-tap-reset только в разделе «Kiosk mode
(v1.41.0)»: «double tap resets zoom». В разделе «View» такого жеста нет вовсе.
Чтение кода подтверждает документацию: логика `_lastTap`/`_resetZoom()` в
`_stagePointerUp` (`src/houseplan-card.ts:5264-5277`) целиком находится внутри
`if (this._kiosk) { … }`; на самом stage нет `@dblclick` (полный список
обработчиков — `:14474-14480`). То есть на обычном (не kiosk) View — ни
десктопный dblclick мышью, ни touch double-tap — сегодня **ничего** не делают
на фоне; жест существует только в kiosk.

ТЗ формулирует это как факт про View в целом, а не как допущение или явно
ограниченное kiosk-наблюдение (в отличие от §16, где рядом стоящее допущение
«до #82 переход атомарный» правильно вынесено в блок предположений). Первый
комментарий владельца к issue («двойной клик/тап… – Поправка, это поведение
кажется уже реализовано») показывает, что сама неоднозначность уже была на
поверхности при заведении issue и не была закрыта явной проверкой.

**Последствия:** (1) пункт browser smoke «double tap свободного фона сохраняет
прежнее поведение» (§12) содержателен только для kiosk — для обычного View
«прежнее поведение» это просто отсутствие эффекта, что тривиально пройдёт даже
при ошибке в общей gesture-арбитраже; (2) для ownership-логики §6–7 (отличить
одиночный tap от первой половины double-tap) потребуется **новая** общая
(не только kiosk) логика распознавания double-tap — её сегодня не существует,
а формулировка «новые независимые константы не вводятся» (§7) намекает, что
общий тайминг уже есть и его достаточно переиспользовать, что неверно вне
kiosk.

**Почему Medium:** не блокирует ни один AC (инструкция «сохранить как есть»
остаётся корректной независимо от истинного текущего охвата), но фактическая
неточность способна привести к смоку, проверяющему не то окружение, и к
недооценке объёма новой gesture-арбитражной логики.

**Заведён отдельный issue** https://github.com/Matysh/houseplan-card/issues/183.

## Заведённые issue по Medium-находкам

- **Medium-1** → https://github.com/Matysh/houseplan-card/issues/182
- **Medium-2** → https://github.com/Matysh/houseplan-card/issues/183

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

- **Геометрический контракт (§4)** — однозначен и самосогласован: safe rect
  `0.8W×0.8H`, формула `scale = min(0.8W/Rw, 0.8H/Rh)`, пример 2000×1000 →
  800×800 с полями 100/100/600/600 px — арифметика проверена вручную и
  совпадает с телом issue дословно.
- **`ZOOM_MIN`/`ZOOM_MAX` действительно существуют** (`houseplan-card.ts:4792-4793`,
  `space-geometry.ts:203`, значения 8 и 1/3) — ссылка на «существующие пределы
  zoom» не выдумана.
- **#82 корректно учтён как ещё не реализованный** — issue #82 открыт,
  `S3-spec`; `ViewportAnimator` в `src/` не найден (grep). Условная
  формулировка «до реализации #82 … атомарно» точна, а не догадка.
- **Конфликт с #28 (§10)** — сам факт конфликта (обычный клик не может
  одновременно принадлежать двум действиям) реален, а решение (primary click
  закреплён за fit-to-room) — явное продуктовое решение, а не техническая
  подмена; см. также Low-1 про устаревший статус #28 ниже.
- **Модель данных и миграция** — по существу закрыто корректно: room fit не
  меняет `room`/`space`/backend-схему, новых полей не появляется; сверено с
  `docs/CONFIG-COMPATIBILITY.md` (нет ни одной точки пересечения с текущим
  реестром совместимости). Разнесено по §8/§15 вместо отдельного раздела
  (см. Low-3), но по содержанию пробелов нет.
- **Non-scope (§3)** согласован с non-scope тела issue и не оставляет скрытого
  расширения (открытие карточки, кнопка «назад», авто-смена пространства,
  свободное вращение изометрии, второй animator — всё явно исключено).
- **Блок предположений (§16)** используется по назначению: пункты про базис
  измерения 10%, состав bounds, атомарность до #82 и передачу trigger карточки
  в #28 — это действительно технические/уточняющие решения, а не спрятанные
  продуктовые вопросы, которые следовало адресовать владельцу. Ревьюер
  оспаривает формулировку пункта про «единственный resolver» (см. Low-4) в
  рамках штатного технического спора автор/ревьюер, не как продуктовый вопрос.
- **i18n** — конкретный текст на двух локалях дан («Вписать комнату Гостиная» /
  «Fit room Living room»); имена ключей не выбраны, но это техническая деталь
  именования, а не продуктовая неясность.

## Low (снято с записью, не блокирует)

- **Low-1.** §10 обсуждает #28 как открытую задачу, которой перед реализацией
  «нужно изменить UX». По факту #28 закрыт `not_planned` 2026-08-14 — до
  публикации этого ТЗ. Само продуктовое решение (primary click → fit-to-room)
  от этого не меняется, но формулировку стоит поправить в следующей редакции,
  чтобы не выглядела как отсылка к живой задаче.
- **Low-2.** §1 не называет явно персону из таблицы `docs/SCOPE.md` (Home admin /
  Household members / Guests) — сценарий описан через поверхность (View,
  kiosk) и типичный триггер (большой/сложный план), персона угадывается, но не
  названа. Не мешает пониманию контракта.
- **Low-3.** В отличие от `docs/specs/146-...md`/`138-...md`, в ТЗ #152 нет
  отдельного заголовка «Модель данных и миграция» — содержание корректно, но
  разнесено по §8 и §15. Рекомендация на будущее — для единообразия со
  смежными ТЗ этого репозитория.
- **Low-4.** §16 полагается на «единственный existing room hover/hit resolver».
  По коду это два разных механизма: hover в View — нативные
  `@mouseenter`/`@mouseleave` на SVG-форме каждой комнаты (`:14619-14646`), а
  инструменты Resize/Delete/Merge/Split используют собственный
  `[...rooms].reverse().find(pointInRoom)`, продублированный в 4 местах
  (`:6528, :9936, :11045, :11096`). Оба, вероятно, совпадают на практике
  (одинаковый z-порядок), но структурно это не один переиспользуемый
  resolver. Пункт уже явно оформлен как допущение в §16, поэтому не требует
  отдельного issue — фиксирую как технический спор для реализации: имеет
  смысл вынести один явный shared-хелпер, а не полагаться на совпадение двух
  независимых путей.

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

- Реализацию — её нет, это ревью ТЗ, а не кода.
- Golden/визуальные артефакты и производительность — на этапе ТЗ не
  требуются; §12 корректно откладывает их проверку до реализации/пре-релиза.
- Backend/`custom_components/houseplan/**/*.py` — задача их не касается по
  заявленному scope, отдельно построчно не сверялось, так как заявлено
  «room fit не меняет model/backend», а `docs/CONFIG-COMPATIBILITY.md` не
  показал точек пересечения.
- Полное соответствие проектируемого «одного focus target на комнату»
  практикам ARIA authoring patterns — это вопрос code review на этапе
  реализации, не ТЗ.
- Не выполнялись гейты (`typecheck`/`test`/`build`) — на этом этапе нет кода
  для их запуска, только документ.

## Вывод

Два блокирующих дефекта: (1) ни один из 14 AC не указывает способ
доказательства, что напрямую противоречит DoR (PROCESS.md §2.5) и практике
соседних ТЗ этого репозитория; (2) явный критерий приёмки issue про
синхронность SVG/HTML hit targets с viewport во время перехода потерялся при
переносе в ТЗ и не имеет ни номера AC, ни отдельной smoke-проверки. Оба
дефекта устраняются правкой текста ТЗ, а не пересмотром продуктового решения.
Геометрический контракт, non-scope, обработка конфликта с #28/#82 и модель
данных проверены по коду и корректны.

Возврат в «ТЗ в работе» (`S3-spec`), цикл r1/4.