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

# Ревью ТЗ — issue #152, заход r2

- **Issue:** https://github.com/Matysh/houseplan-card/issues/152
- **ТЗ:** `docs/specs/152-room-click-fit.md`, ветка `issue/152-room-click-fit`,
  коммит `f672de67` (родитель ревьюируемой правки — `f29c4c5b`)
- **Этап:** spec (PROCESS.md §2.4)
- **Вердикт:** зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0

## Материал раунда

Вердикт r1 (комментарий issue) называет коммит `0fd4e66`, документ
`docs/reviews/SPEC-REVIEW-152-r1.md` в заголовке — коммит `7f8751b4dce8…`. Ни
один из двух SHA не резолвится в текущей истории (`git cat-file -t` на оба —
`fatal`). Per PROCESS.md §2.10 это «обычное дело», а не находка сама по себе:
ветку между раундами перебазируют/сквошат. Материал восстановлен по
содержимому, а не по SHA: `docs/reviews/SPEC-REVIEW-152-r1.md` цитирует ТЗ
построчно (§8 130–151, §9 153–163, §11 172–187, пример 2000×1000→800×800,
формулировки «существующая accessible-подпись», «существующий
double-click/tap fit-all»), и коммит `f29c4c5b` («docs: specify room click
fit», Aug 15, начало истории файла) даёт файл, в котором все эти цитаты
находятся на совпадающих строках дословно. Это и есть материал r1: он же
единственный родитель следующего коммита `f672de67`, поэтому дельта раунда —
`git diff f29c4c5b..f672de67 -- docs/specs/152-room-click-fit.md`.

Два SHA, названных r1 в разных местах, не резолвятся оба — вероятно, r1
работал на ветке, где рабочий коммит амендился/ребейзился уже после того, как
были сняты оба значения, и они не сверялись друг с другом перед публикацией
(§7.2 требует сверки на момент вывода). Отмечаю это как процессное наблюдение
уровня Low применительно к прошлому раунду; на выводы текущего раунда это не
влияет, поскольку материал восстановлен по содержимому надёжно.

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

Дельта — не локальная правка: `git diff --stat` даёт 487 добавленных / 252
удалённых строк на файле, который в исходной редакции насчитывал 270 строк, то
есть фактически полная переработка документа (изменился даже заголовок:
«Issue #152 — …» → «ТЗ #152 — …», добавлен раздел «Подтверждённое текущее
состояние», переписаны структура и формулировки всех разделов). Per PROCESS.md
§2.10 («разбор остаётся полным, если … объём дельты сопоставим с исходной
задачей») разбор проведён полностью, а не только по находкам r1.

Прочитаны: `docs/SCOPE.md` (Core user jobs, персоны, lock invariant),
AGENTS.md/PROCESS.md (§2.4, §2.5, §2.7, §2.10, §3, §4, §7.1, §7.2), тело
issue #152 и все три комментария, `docs/reviews/SPEC-REVIEW-152-r1.md`, текущий
`docs/specs/152-room-click-fit.md` целиком, `docs/SCOPE.md` (персоны и
accessibility-рамка), исходный код (`src/houseplan-card.ts`,
`src/viewport-transition.ts`) для проверки каждого утверждения раздела
«Подтверждённое текущее состояние» и математики геометрического контракта, а
также текущий статус issue #28, #82, #182, #183 через `gh issue view`.

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

ТЗ активно опирается на раздел «Подтверждённое текущее состояние» — каждое его
утверждение сверено с `origin/dev` заново, а не принято на веру (код с момента
r1 успел измениться: #82 реализован):

- **#82 реализован.** `gh issue view 82` → `state: CLOSED, stateReason:
  COMPLETED`. В коде есть `CameraTransitionController`
  (`src/viewport-transition.ts:119`), `CameraTransitionReason = 'button' |
  'wheel' | 'fit' | 'home' | 'double-tap'` (`:10`), инстанс в
  `houseplan-card.ts:1241`, `CAMERA_FIT_MS = 220` (`:438`). Утверждение ТЗ
  «единый camera transition, реализован» — факт, не догадка.
- **Room hover сменил механизм со времён r1.** r1 цитировал
  `mouseenter`/`mouseleave` на SVG-форме; в текущем коде этих обработчиков нет
  вовсе (`grep` — 0 совпадений), room floor теперь вешает `@pointerenter` /
  `@pointerleave` (`houseplan-card.ts:11700-11731`, функция `enterRoom` пишет
  `_hoverRoom`). Формулировка ТЗ «browser target … определяют тот же room hit,
  что текущий hover» верна для **текущего** кода, а не устарела — обновление
  корректно отражает факт, что #82 заодно перевёл hover на pointer-события.
- **Kiosk-only double-tap-reset подтверждён на актуальном коде.**
  `_stagePointerUp` (`:6970-6982`) — весь блок `_lastTap`/`_resetZoom` внутри
  `if (this._kiosk)`; вне kiosk на stage нет ни одного обработчика double-tap.
  Совпадает с утверждением ТЗ п.4 «Подтверждённого текущего состояния» и с
  находкой r1 Medium-2.
- **`.roomlabel` не клавиатурно-доступна.** `_renderRoomLabel`
  (`:12756-12805`) не содержит `role`/`tabindex`/`aria-label`/`keydown`.
  Совпадает с утверждением ТЗ п.2 и с находкой r1 Medium-1 — в новой редакции
  claim сужен до `.roomlabel`, а не до «плана в целом» (важно, см. ниже).
- **Пустое имя не рендерит подпись в View.** `_renderRoomLabel:12761`:
  `if (!r.name && !this._markup) return nothing;` — подтверждает claim §
  «Клавиатура и доступность» про edge case пустого имени.
- **`LS_ZOOM` хранит только zoom.** `_saveZoom` (`:6735-6746`) пишет
  `this._zoomBySpace` (объект `{spaceId: zoom}`), без центра камеры —
  подтверждает п.5 «Подтверждённого текущего состояния».
- **`ZOOM_MIN`/`ZOOM_MAX`** не изменились (`8` и `1/3`,
  `houseplan-card.ts:6448-6449`, `space-geometry.ts:245`).
- **Архитектурная возможность AC15 (room-reason не пишет zoom-only state)
  подтверждена чтением, не только заявлена.** `_settleCameraTransition`
  (`:1277-1284`) сегодня безусловно вызывает `_saveZoom()` для любого `reason`,
  но `state.reason` уже прокинут через `CameraTransitionState`
  (`viewport-transition.ts:21`) в оба хука (`frame`/`settled`) — то есть
  ветвление по `reason === 'room'` не требует переделки контроллера, только
  добавления условия в существующий callback. ТЗ не выдаёт эту часть за уже
  решённую (это AC15 к разработке), но математика того, что она реализуема без
  второго controller-а, проверена.
- **Интерактивные владельцы существуют как классы/элементы**, на которые ТЗ
  ссылается: `.dev`, `.oplock`, `.op-hit`, `.roomlabel` уже участвуют в других
  exclusion-списках (`:6794`, `:6815`), `data-hp="opening"` (`:13055`).
- **Инструменты, упомянутые в плане тестов и release-артефактах, существуют:**
  `scripts/mutation-gate.mjs`, `scripts/smoke-select.mjs`,
  `demo/smoke_smooth_zoom.mjs`, `npm run bundle:budget`, `golden:verify`,
  `golden:accept`, `docs:accept`, `invariants` — все есть в `package.json`/дереве.
  `demo/smoke_smooth_zoom.mjs` уже содержит паттерн опроса промежуточных кадров
  через `requestAnimationFrame` в `page.evaluate` (`settle()`,
  строки 18-24) — ровно то, что требует AC10; проверяемость не гипотетична.
- **#28 закрыт `NOT_PLANNED`** (`gh issue view 28`) — подтверждает и обновлённую
  формулировку ТЗ («#28 закрыта как not planned»), и закрытие Low-1 из r1.

## Закрытие раунда r1

| Находка r1 | Чем закрыта | Где это видно |
|---|---|---|
| **High-1** — ни один из AC1–AC14 не указывал способ доказательства | Раздел «Acceptance criteria и доказательства» переписан: 16 AC, у каждого инлайн-аннотация метода(ов) через `unit`/`smoke`/`golden`/`performance`/«ревью кода» и исполнителя (`Codex` либо `Codex/Claude`) | `docs/specs/152-room-click-fit.md:300-416`, AC1…AC16 |
| **High-2** — критерий issue «hit targets синхронны во время перехода» не стал отдельным AC | Добавлен отдельный **AC10** с явной проверкой промежуточных кадров tween (не только финального), способ доказательства `smoke`, названа мутация | `:369-375` |
| **Medium-1** (#182) — §9 выдавал `.roomlabel` за «существующую accessible-подпись» | Раздел «Подтверждённое текущее состояние» п.2 прямо констатирует отсутствие `role`/`tabindex`/`aria-label`/`keydown`; раздел «Клавиатура и доступность» явно назван «узким исключением из non-scope accessibility плана», а не расширением существующего. Claim сужен до `.roomlabel`, что закрывает и уточнение из закрытия #182 (про бейдж осиротевшего проёма — см. «Унаследовано» ниже) | `:34-35`, `:227-244` |
| **Medium-2** (#183) — §3/§7 трактовали double-tap fit-all на фоне как поведение всего View | П.4 «Подтверждённого текущего состояния» и раздел «Double-tap без задержки single tap» ограничивают double-tap-reset kiosk’ом явно; non-scope добавляет отдельный пункт «добавление fit-all double-tap в обычный non-kiosk View»; выбран архитектурный путь, не требующий выноса 350-мс порога из kiosk-ветки (room tap принимается сразу, без окна ожидания) | `:39-40`, `:174-184`, `:67` |
| Low-1 — §10 называл #28 живой задачей | Раздел «Связанные задачи» указывает «#28 (карточка комнаты закрыта как not planned)» | `:6-7` |
| Low-2 — не названа персона из `docs/SCOPE.md` | «Сценарий»: «Житель либо home admin …» | `:11` |
| Low-3 — нет отдельного заголовка «Модель данных и миграция» | Отдельный раздел «Данные, миграция, compatibility и i18n» | `:253-266` |
| Low-4 — «единственный resolver» технически не один механизм (View hover vs. editor `pointInRoom`) | ТЗ больше не заявляет объединение с editor-resolver: click-ownership описан только для View/kiosk через тот же SVG pointer-target, что и hover (`data-hp="room"` + `@pointerenter`); редакторы в non-scope и не затрагиваются | `:146-154`, «Скоуп»: «работает только в основном View, включая kiosk» |

## Унаследовано из r1

Наследуется без повторной проверки на этом заходе (дельта их не задевает,
подтверждено чтением текущей редакции ТЗ и кода выше, где это пересекалось):

- Геометрическая арифметика примера 2000×1000 → 800×800 (проверена вручную в
  r1; в r2 формула и пример перенесены дословно, `:137-138`, дополнительно
  ре-проверены построчно в этом заходе как часть полного разбора).
- Конфликт с #28 и решение в пользу primary-click за fit-to-room — продуктовое
  решение не пересматривалось, только формулировка статуса #28 (см. таблицу
  выше).
- Non-scope не создаёт скрытого расширения задачи — подтверждено заново в этом
  заходе, поскольку раздел был существенно переписан (не наследование, а
  повторная проверка из-за нелокальности дельты).
- Источник: `docs/reviews/SPEC-REVIEW-152-r1.md`, материал — коммит `f29c4c5b`
  (см. «Материал раунда» выше).

## Находки

Блокирующих (High) и Medium-находок в этом заходе нет.

**Low-note (не блокирует, к сведению).** Закрывающий комментарий #182
(2026-08-23) уточняет, что на `origin/dev` уже существует один
клавиатурно/ARIA-доступный элемент — бейдж осиротевшего проёма
(`role="button" tabindex="0" aria-label"`, `houseplan-card.ts:18806`), то есть
план сегодня не абсолютно лишён доступной разметки. Текущая редакция ТЗ этой
ошибки не повторяет: она нигде не утверждает «в плане нет ни одного
доступного элемента» — claim сужен до `.roomlabel` конкретно, что фактически
верно независимо от бейджа проёма. Считаю снятым без правки текста.

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

- **Обязательные разделы §7.1** присутствуют: сценарий + «что человек увидит
  до/после» первыми, скоуп/не-скоуп, геометрический и pointer/touch контракт,
  camera/intent/persistence, клавиатура и доступность, данные/миграция/i18n,
  AC1–AC16 с доказательством и исполнителем, план автотестов, риски, откат,
  release-артефакты — все на месте и в этом порядке.
- **Блок «Принятые предположения»** (8 пунктов) использован по назначению:
  каждый пункт либо прямая цитата уже принятого владельцем решения из тела
  issue (10%-база, LS_ZOOM session-only, отсутствие невидимого tab-stop, статус
  #28), либо честно техническое решение реализации (single-tap без 350 мс
  окна, переиспользование `CAMERA_FIT_MS`, scope wall body по room provenance,
  SVG target как authority без нового resolver) — открытых продуктовых
  вопросов, замаскированных под предположения, не найдено.
- **DoR-требования (§2.5), проверяемые на этапе ТЗ**: i18n-ключи названы
  (`room.fit_action`, en+ru), миграция/compatibility решены явно («не
  меняются», сверено с `docs/CONFIG-COMPATIBILITY.md` по неизменности схемы),
  производительность/бюджеты названы отдельным разделом, touch — блокирующая
  поверхность по `docs/TOUCH-SUPPORT.md`, откат описан («revert
  frontend/tests/docs/bundle», без обратной миграции), открытых продуктовых
  вопросов нет.
- **Все факты раздела «Подтверждённое текущее состояние» и математика
  геометрического контракта** — перепроверены по актуальному `origin/dev`
  (список — в «Как проверялось»), расхождений с кодом не найдено.
- **Non-scope согласован** с non-scope тела issue и не создаёт скрытого
  расширения: отдельно исключены Labs-флаг/новый config, floor-wide tab-stop
  grid, второй animator, вращение изометрии, general non-kiosk double-tap.
- **Персона (`docs/SCOPE.md`)** названа явно («Житель либо home admin»),
  задача закрывает пространственную навигацию View (не отдельный Core user
  job, а улучшение J1 «show the whole home» applied к одной комнате) — в
  рамках guard rail SCOPE.md, не excess-функциональность.

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

- Дешёвые гейты (`npx tsc --noEmit`, `npm test`, `npm run build`) не
  запускал: дельта раунда — исключительно `docs/specs/152-room-click-fit.md`
  (`git show --stat f672de67` — один файл), кода это ревью не касается, а
  предыдущий прогон этих гейтов не может отражать документную правку. На
  этапе «ТЗ на ревью» кода к тестированию ещё нет (то же ограничение отмечал
  r1). `node scripts/check-docs.mjs` не запускал по той же причине: диап не
  трогает `src/**`.
- Golden/browser smoke/performance/invariants — не запускал: реализации нет,
  §12 ТЗ корректно откладывает их до этапа «В разработке»/пре-релиза.
- Backend/`custom_components/houseplan/**/*.py` — задача их не касается по
  заявленному и подтверждённому non-scope (модель/backend не меняются).
- Полную ARIA-authoring-экспертизу «один action target на подпись» — вопрос
  код-ревью на этапе реализации, не ТЗ.
- Обоснованность продуктового решения «primary click = fit-to-room» как
  такового — оно принято владельцем в теле issue и не пересматривается ни в
  этом, ни в прошлом заходе.

## Вывод

Оба High из r1 закрыты предметно (полная таблица доказательств AC1–AC16 +
восстановленный AC10 про синхронность hit targets на промежуточных кадрах),
оба вынесенных Medium (#182, #183) отражены в тексте точнее, чем было — и
подтверждены их же закрывающими комментариями от 2026-08-23 как полностью
влитые в #152. Полный разбор, оправданный нелокальностью дельты (документ
переписан почти полностью), не нашёл новых High/Medium: геометрический
контракт, pointer/touch ownership, camera/intent lifecycle, accessibility и
release-артефакты проверены по актуальному коду (включая то, что успело
поменяться из-за реализации #82) и корректны. ТЗ готово к переводу в «Готово к
разработке».

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/152-room-click-fit`, коммит `f672de674fcf` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `862dfc7f9622c8432d7dc288446dc360a4900ea2`
  ```
  git log --all --format='%H %T' | grep 862dfc7f9622
  ```
- ТЗ `docs/specs/152-room-click-fit.md`, блоб `fb036d2bb9cc522555c55e15000d7d693e204f8b`
  ```
  git log --all --find-object=fb036d2bb9cc522555c55e15000d7d693e204f8b -- docs/specs/152-room-click-fit.md
  ```