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

# SPEC-REVIEW-645-r1

Issue: #645 — «Plan editor: временно перемещать кнопку "Настройки комнаты",
если она перекрывает элементы» (bug/polish, P2, полный трек — лёгкий трек
аналитика отклонила: нарушен критерий §5 «нет нового UX-контракта», плюс
задача трогает touch-контракт редактора).
Заход: r1 · блокирующих циклов израсходовано 0 из 4.

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

ТЗ живёт в теле issue #645, раздел `## ТЗ` (решение владельца 2026-09-10,
#517). Ревьюер читает только тело issue и комментарии, без устных пояснений
автора. Материал: тело issue на момент чтения (2026-09-24), метки `bug`,
`P2`, `polish`, `S4-spec-review`. Реализация ещё не начиналась (хендофф-
комментарий автора: «продуктовый код не менялся… реализация не начиналась»),
поэтому диапазон `origin/dev...HEAD` пуст для класса A/B — на этом этапе
проверяется только текст.

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

1. Прочитаны `docs/SCOPE.md`, `docs/process/REVIEWER.md`, `AGENTS.md`
   (порядок из инструкции), `PROCESS.md` §2.3–§2.5, §2.10, §4, §7.1, §7.2 —
   секции, определяющие объём и формат ревью ТЗ.
2. Прочитано полностью тело issue #645: секции до `## ТЗ` («Проблема»,
   «Предлагаемое UX-решение», «Время жизни позиции», «Почему не только
   автоматическое уклонение», «Ожидаемое поведение», «Проверки для будущего
   ТЗ») и сам раздел `## ТЗ` целиком (Сценарий → «Принято предположительно»),
   плюс оба комментария («Оценка…», «Взял…», «Сделано…»).
3. Сверены все 14 пунктов «Контракта поведения» и 10 AC на однозначность,
   проверяемость и полноту покрытия — каждый пункт контракта закрыт минимум
   одним AC (проверено построчным сопоставлением, таблица приведена ниже в
   «Что проверено»).
4. Каждое фактическое утверждение ТЗ о текущем коде сверено с исходниками, а
   не принято на слово:
   - `_renderRoomGear()`, `poleOfInaccessibility(room.poly)`, `.rlgearbtn`,
     `pointer-events: auto` — `src/houseplan-editor-runtime.ts:10276–10300`.
     Подтверждено: центр — плановая точка `c`, транслируется в `left/top %`
     через текущий `view` (`(c[0]-view.x)/view.w*100`), то есть модель
     «временная позиция в координатах плана» технически реализуема поверх
     существующего рендера без структурных изменений.
   - «Существующий редакторский порог 3 CSS px» (контракт п.3) — найден и
     подтверждён: `src/houseplan-card.ts:7031`,
     `Math.abs(ev.clientX-drag.sx)+Math.abs(ev.clientY-drag.sy) > 3` в
     `_pointerMoveNow` (device drag), `clientX/clientY` уже в CSS-пикселях,
     от DPR/zoom не зависят — заявление ТЗ точное, не догадка.
   - Существующий паттерн подавления synthetic click —
     `_suppressClick`/`setTimeout(…, 0)` в `src/houseplan-card.ts` (строки
     1905, 5598, 6708, 6804, 6903–6904, 6941, 7062–7063) — подтверждает, что
     механизм из «Принято предположительно» («конкретный механизм… одноразового
     подавления synthetic click») уже есть готовый прецедент в этом же файле.
   - `pointInPolygon` существует (`src/logic.ts`, используется также в
     `src/houseplan-editor-runtime.ts`, `src/houseplan-card.ts`) — ссылка ТЗ
     в «Принято предположительно» не выдумана.
   - Терминология кнопки (`room.settings_title` / `room.settings_short` =
     «Настройки комнаты») сверена с `src/i18n/ru.json:765,800` и
     `docs/USER-GUIDE.ru.md:1621` — совпадает, ТЗ не изобретает термин.
5. Проверено взаимодействие с соседним поведением, читающим позицию кнопки:
   поиск `gearCenter`/`poleOfInaccessibility` по `src/**` вскрыл
   `src/resize-labels.ts:25–27,97,113–116` и вызывающий код
   `src/houseplan-editor-runtime.ts:3404–3435` (`_rszEdgeLabels` →
   `placeResizeAreaLabel({ …, gearCenter: poleOfInaccessibility(poly), … })`)
   — живая раскладка длин/площади при Resize стены уклоняется именно от
   позиции кнопки «Настройки комнаты». См. находку M2.
6. Проверено `docs/TOUCH-SUPPORT.md` целиком, в частности «Documentation
   rule» (строки 214–223: три обязательных значения `Touch editor: …`) —
   применительно к тому, что #645 является «new editor feature
   specification», трогающей touch-путь Plan editor. См. находку M1.
7. Проверены `docs/UX-MODES.md` (модель трёх режимов/вкладок редактора,
   `_mode: 'view'|'plan'|'devices'|'decor'` в `src/houseplan-card.ts:851`) —
   пункт контракта 12 («сессия… заканчивается при выходе из редактора
   "План"») однозначно читается как «переключение на вкладку Устройств/
   Подложки завершает сессию», конфликта или недосказанности не найдено.
8. Проверены обязательные разделы ТЗ по чек-листу `PROCESS.md` §7.1 —
   присутствуют все: сценарий, что человек увидит, проблема, скоуп/не-скоуп,
   контракт поведения, UX и доступность, модель данных/миграция/i18n, AC1–10
   с доказательством, план автотестов, риски, откат, release-артефакты.
9. Проверен DoR-чек-лист `PROCESS.md` §2.5 пункт за пунктом (список — в
   «Что проверено»).

Этап spec: тяжёлые/browser-гейты не запускались и не нужны — код ещё не
написан, ни один AC не реализован; проверке подлежит только текст ТЗ и его
непротиворечивость уже существующему коду.

## Находки

### Medium (в скоупе задачи — без High это жёлтый вердикт, правится в #645)

**M1. Отсутствует обязательная строка `Touch editor: …` из
`docs/TOUCH-SUPPORT.md` → «Documentation rule».**

`docs/TOUCH-SUPPORT.md:214–223` требует буквально для «new editor feature
specifications»: одно из трёх значений — `Touch editor: supported` /
`Touch editor: best effort / intentionally degraded` / `Touch editor: not
exposed`, — записанное явной строкой. ТЗ #645 добавляет именно новую
touch-возможность редактора (одиночный touch/pen drag капсулы кнопки,
контракт п.2/8, AC6) и в прозе объясняет, что редактор «остаётся best effort
по `docs/TOUCH-SUPPORT.md`», но нигде не содержит требуемую формальную
строку. Тот же формальный пробел уже разбирался ревью на #449 (закрыт
добавлением ровно одной строки в шапку ТЗ, `docs/reviews/SPEC-REVIEW-449-r1.md`
M1) — прецедент показывает, что это не придирка к форме, а работающий
механизм, который здесь просто не применён.

**Воспроизведение:**
```
grep -n "Touch editor:" <(gh issue view 645 --repo Matysh/houseplan-card --json body -q .body)
```
даёт пусто; в то же время `docs/specs/359-furniture-placement-preview.md:12`
и `docs/specs/449-double-fit-all.md:9` показывают действующий образец записи
для сопоставимых по риску editor-фич.

**Почему это находка:** это не стилистика — правило `docs/TOUCH-SUPPORT.md`
существует именно чтобы код-ревью и будущие читатели не собирали
touch-классификацию по кусочкам прозы, а видели один явный маркер. Задача
прямо подпадает под критерий «new editor feature specification».

**Как чинится:** добавить одну строку вида `Touch editor: best effort /
intentionally degraded` (или `supported` — выбор буквы предположительно за
автором, поскольку это техническая классификация, а не продуктовый вопрос)
рядом с разделом «Сценарий» или «UX и доступность», с краткой ссылкой на
`docs/TOUCH-SUPPORT.md`.

**M2. ТЗ не учитывает существующую зависимость live-подписей Resize от
позиции кнопки «Настройки комнаты» — после реализации риск воспроизвести ту
же проблему («подпись перекрывает кнопку»), которую issue должен решить.**

`src/houseplan-editor-runtime.ts:3404–3435` (`_rszEdgeLabels`, вызывается во
время активного перетаскивания стены в режиме Resize того же редактора
«План», см. `src/houseplan-card.ts:1663–1667` — Resize это часть `_mode ===
'plan'`) строит живые подписи длины/площади и передаёт в
`placeResizeAreaLabel()` (`src/resize-labels.ts:25–27,97,113–116`)
`gearCenter: poleOfInaccessibility(poly)` — то есть **всегда** автоматический
центр, безусловно, без какой-либо временной поправки. Кнопка `.rlgearbtn`
при этом продолжает рендериться параллельно (`this._markup ?
space.rooms.map(...this._renderRoomGear...) : nothing`,
`src/houseplan-card.ts:11181`) и, согласно контракту #645 п.9/12, может в
этот момент фактически находиться в другой, перетащенной пользователем
точке той же комнаты.

Итог: если пользователь в рамках одной сессии редактора сначала перетащил
кнопку в свободное место, а затем начал Resize стены той же комнаты,
алгоритм уклонения площади/длины по-прежнему обходит **старую** (уже не
отображаемую) автоматическую точку. Он может как оставить подпись рядом с
пустым местом без причины, так и, что хуже, отрисовать подпись поверх
**фактической**, перетащенной позиции кнопки — то есть воспроизвести ровно
тот дефект «элемент перекрыт и недоступен», ради устранения которого заведён
#645, только теперь в паре «подпись Resize ↔ кнопка», а не «кнопка ↔
устройство/мебель/проём».

Раздел «Затронутые модули» не называет ни `src/resize-labels.ts`, ни
`_rszEdgeLabels`/`placeResizeAreaLabel`; «Скоуп» и «Не-скоуп» не упоминают
Resize вообще; ни один из AC1–AC10 не покрывает этот сценарий. Это не
догадка — оба вызова и точная передача `poleOfInaccessibility(poly)` без
альтернативы прочитаны в текущем коде (пути указаны выше).

**Воспроизведение (чтением, не исполнением — кода ещё нет):**
```
sed -n '3404,3435p' src/houseplan-editor-runtime.ts   # gearCenter: poleOfInaccessibility(poly)
sed -n '25,27p;90,120p' src/resize-labels.ts           # gearCenter используется для уклонения подписи
sed -n '11175,11182p' src/houseplan-card.ts            # кнопка рендерится в том же _markup-режиме
```

**Почему это находка, а не придирка:** ревью ТЗ обязано искать не только
внутреннюю непротиворечивость AC, но и то, решает ли изменение заявленный
сценарий, не ухудшая соседний (`docs/process/REVIEWER.md`, «Находки и
вердикт»; `PROCESS.md` §2.7 по духу применимо уже на этапе спецификации,
поскольку риск детерминированно вытекает из уже читаемого кода, а не из
будущей реализации). Здесь риск не гипотетический: оба фрагмента кода уже
существуют и жёстко связаны единственным явным чтением
`poleOfInaccessibility(poly)`.

**Как чинится (любой вариант закрывает находку):**
- явно включить в скоуп: `_rszEdgeLabels`/`placeResizeAreaLabel` должны
  получать эффективную (временную, если она есть) позицию кнопки, а не
  всегда автоматическую — с отдельным AC и добавлением файла в «Затронутые
  модули»; либо
- явно вынести в «Не-скоуп» с обоснованием и явным принятым риском (например:
  «одновременная комбинация активного Resize и перетащенной кнопки в той же
  комнате достаточно редка, деградация принимается»), чтобы код-ревью не
  спрашивал о ней как о непокрытой находке.

Любой из вариантов — правка внутри текущего ТЗ, отдельный issue не нужен:
дефект — прямое следствие этой же задачи.

### High / Low

Находок этих уровней нет.

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

- **Выбор полного трека обоснован явно** — аналитика называет нарушенный
  критерий §5 («нет нового UX-контракта») и указывает на touch-контракт
  редактора, а не отделывается фразой «обычный трек» (issue #338).
- **Оба первых обязательных раздела `PROCESS.md` §7.1 присутствуют и
  корректны**: «Сценарий» называет персону (администратор дома,
  `docs/SCOPE.md`), поверхность (Plan editor, desktop) и момент (кнопка
  закрывает элемент); «Что человек увидит до и после» — одной фразой без
  терминов реализации.
- **Обязательные разделы ТЗ присутствуют все** (сценарий · что человек
  увидит · проблема · скоуп/не-скоуп · контракт поведения · UX/доступность ·
  модель данных/миграция · i18n · AC1–AC10 · план автотестов · риски · откат
  · release-артефакты) — `PROCESS.md` §7.1 выполнен формально и по
  содержанию.
- **Контракт поведения (14 пунктов) покрыт критериями приёмки без пробелов**:
  1→AC1, 2→AC2/AC3 (косвенно, начало жеста), 3→AC3, 4→AC1, 5→AC2, 6→AC4,
  7→AC3, 8→AC6, 9→AC5, 10→AC7, 11→AC8, 12→AC7, 13→AC7, 14→AC9; AC10
  закрывает регрессии вне редактора. Ни один пункт контракта не остался без
  проверяемого AC.
- **Каждый AC однозначен, привязан к конкретному наблюдаемому исходу и несёт
  способ доказательства** (`unit`/`browser smoke`/`ревью кода`, без смешения
  «ручное тестирование» как доказательства — раздел Release-артефакты прямо
  это исключает).
- **Технические заявления о текущем коде верны**, что подтверждено чтением
  (см. «Как проверялось» п.4): `_renderRoomGear`, порог 3 px, механизм
  подавления click, `pointInPolygon` — ничего не придумано.
- **Ограничение полигоном для вогнутой комнаты специфицировано корректно**:
  «доходит до ближайшей допустимой точки на пути жеста» (а не «до ближайшей
  евклидовой точки границы») — формулировка исключает типичную ошибку
  прыжка в несвязанную допустимую область, реализуемо через пересечение
  сегмента жеста с границей полигона.
- **Модель координат согласована с реальным рендером**: `_renderRoomGear`
  уже хранит и транслирует плановую точку через `view` в проценты экрана
  (`src/houseplan-editor-runtime.ts:10289–10290`) — контракт п.9 (позиция
  переживает pan/zoom) не требует новой модели преобразований, только замену
  источника точки `c`.
- **Не-скоуп сформулирован явно и без размывания**: collision-aware
  раскладка относительно устройств/мебели, сохранение позиции вне сессии,
  Undo/Redo, изменение исходного алгоритма/вида кнопки, выход за пределы
  комнаты, полная touch-паритетность — всё явно исключено, без формулировок
  «и подобное».
- **Данные/миграция/совместимость закрыты явным «нет»** — соответствует
  DoR-пункту (§2.5): постоянная схема не меняется, `docs/CONFIG-
  COMPATIBILITY.md` не применяется к чисто временному UI-состоянию.
- **i18n закрыт корректно**: новых строк нет, существующие ключи
  `room.settings_title`/`room.settings_short` не меняются (сверено с
  `src/i18n/ru.json`, `src/i18n/en.json`).
- **Производительность названа предметно**, не общей фразой: O(1) по
  `roomId`, ограничение геометрии только для активного жеста, переиспользование
  существующего coalescing pointermove (тот же паттерн, что уже используется
  для device drag, `_queuePointerMove('device', …)`,
  `src/houseplan-card.ts:7016`) — реалистично, не выдумана мощность.
- **Откат назван и реалистичен**: убрать обработчики/временное отображение,
  `_renderRoomGear()` возвращается к чистому автоматическому центру без
  миграции — пользовательских данных для отката нет, потому что позиция
  никогда не сохранялась.
- **Release-артефакты названы полно**: оба changelog со ссылкой на #645,
  оба `USER-GUIDE` (en+ru), `STATUS.md` при наличии соответствующего
  раздела, явное «нет» для golden (обоснованно — статичный idle-кадр не
  меняется, см. также M2 о смежном Resize-сценарии, не о golden) и для
  performance/security/backend/migration notes.
- **Риски перечислены содержательно и каждый закрыт конкретным AC**
  (проверено построчно): synthetic click → AC3; потерянный pointerup/
  `grabbing` → AC6 (см. также ниже про `lostpointercapture`, отмечено как
  «не проверял» — технический нюанс уже прикрыт разделом «Принято
  предположительно»); второй touch/pinch-owner → AC6; смешение экранных/
  плановых координат при DPR → AC5; clamp для вогнутой комнаты → AC4;
  устаревший `roomId`/полигон → AC8; лишний `requestUpdate` на pointermove →
  раздел «Производительность» + план автотестов.
- **Блок «Принято предположительно» корректно отделяет техническое от
  продуктового**: имена полей, структура состояния (`Map`), выбор
  `pointInPolygon`/бинарного поиска, механизм pointer capture и подавления
  click, величина визуального подъёма — всё нечувствительно для пользователя
  и справедливо оставлено на усмотрение исполнителя/ревьюера код-ревью, без
  подмены продуктовых решений (позиция кнопки, её видимый вид, порог 3 px,
  время жизни) техническими догадками.
- **Открытых продуктовых вопросов действительно нет**: единственная
  потенциально спорная точка — граница «сколько touch-паритета входит в
  скоуп» — разрешена ТЗ явно и без выдумки (одиночный pointer — да, полная
  паритетность — нет), совпадает с прежним owner-решением
  `docs/TOUCH-SUPPORT.md` («editors are desktop-first… best effort»), не
  требует нового решения владельца.

## Чего не проверял и почему

- **Реализацию** — её нет: диапазон `git diff origin/dev...HEAD` не содержит
  ни одного файла класса A/B на момент ревью; хендофф-комментарий автора
  прямо это подтверждает.
- **`npx tsc --noEmit` / `npm test` / `npm run build` / `node
  scripts/check-docs.mjs`** — не гонял: ни одна строка кода ещё не изменена,
  прогон гейтов на этапе ревью ТЗ бессмыслен (§2.4 их не требует).
- **Browser smoke / golden / performance / mutation** — не запускались по
  той же причине; план автотестов ТЗ оценён на реалистичность (существующие
  примитивы `_queuePointerMove`, `_suppressClick`, `pointInPolygon`,
  `mutation-gate.mjs`-конвенции существуют), но не исполнялся.
- **Тонкость `lostpointercapture` при штатном завершении drag** —
  контракт п.7/8 и AC3/AC6 в сумме требуют, чтобы обычный `pointerup` после
  drag сохранял позицию, а `lostpointercapture` — откатывал к началу жеста;
  в браузерах `lostpointercapture` штатно следует сразу за `pointerup`,
  когда элемент удерживал capture, так что наивная реализация «любой
  `lostpointercapture` = отмена» откатывала бы даже успешный drag. Это не
  противоречие ТЗ по существу — стандартная идиома (различать «capture
  потеряна без завершающего `pointerup` той же последовательности» и
  «capture отпущена вследствие `pointerup`») закрывает вопрос, и ТЗ уже
  относит «конкретный механизм pointer capture» к «Принято предположительно»
  — технический выбор, а не пробел контракта. Не поднимаю отдельной
  находкой (Low, снята решением ревьюера с записью): проверяемо будущим
  unit-тестом реордера жеста (план автотестов, п.1), и не требует
  вмешательства владельца.
- **Существование/содержимое смоков, которые план автотестов обещает
  повторно прогнать** (`smoke_room_settings`, `smoke_room_cards`,
  `smoke_feedback_v2`, `smoke_hide_room_names`) — не открывал построчно;
  для целей spec-ревью достаточно, что файлы называются по существующей
  конвенции (`demo/smoke_*.mjs`), их фактическое существование и охват —
  забота код-ревью при реализации.
- **`docs/CANVAS.md`, `docs/WALL-THICKNESS.md`, `docs/LIGHT.md`, `docs/SUN.md`
  целиком** — не читал: ни один из них не является каноническим документом
  предметной области этой задачи (Plan editor UI-жест, не геометрия стен,
  свет или солнце); `docs/UX-MODES.md` и `docs/TOUCH-SUPPORT.md` прочитаны
  как релевантные каноны.
- **История issue #645 до текущей редакции тела** — issue не редактировался
  после публикации (`edited: false` во всех трёх комментариях и в самом
  issue по данным `gh issue view`), поэтому вопрос «на каком тексте вынесен
  вердикт» не возникает; хеш тела для якоря ниже.

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

- Issue: #645, метки на момент ревью: `bug`, `P2`, `polish`, `S4-spec-review`.
- ТЗ: раздел `## ТЗ` тела issue #645 (единственная редакция, r1,
  `edited: false`).
- Комментарии учтены: «Оценка…» (аналитика, полный трек обоснован), «Взял:
  автор ТЗ · сессия Codex · ветка `issue/645-room-settings-button-drag`»,
  «Сделано: … реализация не начиналась».
- Рабочее дерево репозитория на момент чтения кода: `2b3959e55bcb139b6ad872a312ad212de36f44db`
  (справочно, для проверки фактических заявлений ТЗ о текущем коде — не
  является материалом самого ТЗ, т.к. ветка задачи не создавала коммитов
  поверх него).

## Вердикт

Вердикт: жёлтый · заход r1 · блокирующих циклов 0/4 · High: 0 · Medium: 2 →
в задаче | — · Документ: docs/reviews/SPEC-REVIEW-645-r1.md

Обе находки (M1, M2) — в скоупе задачи #645 и без High-находок дают жёлтый
вердикт (`PROCESS.md` §2.4, §12): ТЗ возвращается автору на правку. M1
чинится одной строкой; M2 требует явного решения — включить Resize-подписи в
скоуп с AC или явно и обоснованно исключить их с принятием риска. Обе правки
локальны для текста ТЗ, следующий цикл разбирается по дельте (§2.10).

---

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

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

- Ветка: `issue/645-room-settings-button-drag`, коммит `2b3959e55bcb` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `7f08cac08613119d6e48b96c345db826e22d4b9a`
  ```
  git log --all --format='%H %T' | grep 7f08cac08613
  ```
- Тело issue: `9102a02fd0ea8a92464cbbe6662e2932cb711640384b5f99ce28f04f3acded91`
- Вердикт конвейера: `yellow` · High 0