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

SPEC-REVIEW-74-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/74
• Этап: ревью ТЗ (PROCESS.md §2.4)
• Материал: docs/specs/074-device-position-undo.md на SHA a3c305e6052c001d3ea39a190ed6b528f56e2df5 (ветка issue/74-device-position-undo, комментарий владельца от 2026-08-30 фиксирует этот SHA как перебазированную и расширенную редакцию ТЗ)
• Заход: r1 (первое ревью документа; прежних вердиктов по этому ТЗ в issue нет — комментарии от 2026-08-14/08-15/08-30 это аналитика и акт написания ТЗ, не ревью)
• Вердикт: зелёный
• High: 0 · Medium: 0 · Low: 2 (обе сняты ревьюером с записью ниже)

Скоуп разбора

Первый заход — полный разбор: сам документ ТЗ, тело issue #74 и все три комментария (аналитика 2026-08-14, публикация ТЗ 2026-08-15, актуализация на dev 2026-08-30), docs/SCOPE.md, AGENTS.md, PROCESS.md §2.4/§7.1, docs/UX-MODES.md, docs/TOUCH-SUPPORT.md, и заявленное в ТЗ текущее поведение dev (раздел 2 «Актуальность на 2026-08-30») сверено построчно с кодом.

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

Ревью ТЗ не запускает гейты (это не код-ревью), но обязано поймать догадку, выданную за факт. Документ №074 необычно детален и содержит развёрнутый раздел «Актуальность» с явными утверждениями о текущем поведении dev — каждое из них можно фальсифицировать чтением кода, поэтому все они прочитаны и сверены:

1. CommandStack существует и используется только для geometry/decor, отдельной истории позиций устройств нет — подтверждено: src/command-stack.ts:15-55, src/houseplan-card.ts:1704 (_geometryHistory = new CommandStack<...>(50)), отдельной по-девайсной истории в коде нет.
2. Device toolbar не содержит Undo/Redo — подтверждено: _renderDevicesBar() (src/houseplan-editor-runtime.ts:11743-11768) не рендерит такие кнопки, в отличие от _renderMarkupBar() (:11722-11729).
3. Keyboard handler выходит до истории в devices — подтверждено: src/houseplan-card.ts:2816 if (!this._markup) return; до диспетчеризации undo/redo (:2824-2856), а _markup — это mode === 'plan' (:1699-1701); devices не попадает ни в decor-ветку, ни в _markup.
4. _pointerMove() вызывает _savePos() и планирует persist на каждом кадре — подтверждено: src/houseplan-card.ts:6381-6405 вызывает _savePos безусловно; _savePos (:5001-5021) кладёт id в _dirtyPos и вызывает _persistLayout() (debounce, :4769) при каждом вызове.
5. pointercancel направлен в тот же _pointerUp, что и обычный pointerup — подтверждено: src/houseplan-card.ts:11806-11807, оба события биндятся на this._pointerUp(e, d); отдельного abort-пути для устройств сегодня нет.
6. Backend уже предоставляет точечные houseplan/layout/update и houseplan/layout/delete без изменения схемы — подтверждено: custom_components/houseplan/websocket_api.py:147-148,622,1077, уже вызываются из фронтенда (houseplan-card.ts:4782, houseplan-editor-runtime.ts:8308,8369).
7. _sentPos (pending-authority карта, §9) существует — подтверждено: src/houseplan-card.ts:4767,4739,4780,4785.
8. Механизм различения own echo / внешнего изменения по revision/content, на переиспользование которого рассчитывает §10, существует и именно content-based, не timeout — подтверждено: _adoptStructuralResponses (houseplan-card.ts:4033-4053) сравнивает contentFingerprint(...) и чистит _geometryHistory только при реальном расхождении, с явным комментарием в коде «A reconnect echo with identical content deliberately does not [clear]».
9. Кросс-пространственная история (§9 «команда другого пространства сначала переключает карточку на spaceId») — не новый паттерн: _applyGeometryState (houseplan-editor-runtime.ts:2344-2348) уже переключает host._space перед применением geometry-команды, а _commitSpace/_slideTo (houseplan-card.ts:1443-1463) никогда не чистят _geometryHistory — существующий стек уже глобальный, не по-пространственный. ТЗ описывает продолжение существующего контракта, а не изобретает новый.
10. rl_* (room-label) действительно имеют отдельный от устройств путь сохранения — подтверждено (houseplan-card.ts:11913,11941,12123, houseplan-editor-runtime.ts:10706-10770), корректно исключены из §7/§10.
11. Guards перед pointerdown, на которые ссылается §8.1 — подтверждено: houseplan-card.ts:6356 (mode guard), :6373 (ha_disabled guard) до фиксации _drag (:6374-6376).
12. docs/TOUCH-SUPPORT.md и docs/UX-MODES.md сверены на противоречия с §1 и §9/§12: противоречий не найдено, «не сохранять случайную позицию при системной отмене жеста» — прямое следствие уже существующего требования TOUCH-SUPPORT.md:78-79 («not... saving unintended geometry merely because a pinch, pointer cancellation or second touch was misread as a click»).
13. Формат интерполяции history.device_move с именем устройства технически совместим с существующим паттерном {name} в history.undo_named / redo_named (src/i18n/en.json:105-110), хотя это первый ключ, где сам {name} — динамически подставленное (не статическое) значение; отмечаю как новый, но не проблемный шаг того же механизма.
14. Числа языков/ключей: en/ru/de/fr параллельны (по 37 history.* ключей в каждом), подтверждает выполнимость плана и18n на 4 языка из §16.

Отдельно проверено требование §7.1 «сценарий + что человек увидит» (раздел 1 документа: персона — администратор HA, поверхность — Device editor, desktop-first; до/после — одной фразой без терминов реализации, за вычетом одного слова «layout», которое уже вошло в пользовательскую терминологию проекта через docs/USER-GUIDE.ru.md) и соответствие Core user job (J6 «Keep the plan true as the home evolves», docs/SCOPE.md:48) — подтверждено как владельцем в аналитике (2026-08-14), так и по существу.

Находки

Low-1 — неверные пути трёх скриптов в §14 «Регрессия и gates»

docs/specs/074-device-position-undo.md:285-287 называет python scripts/check_docs.py, node scripts/no_new_any.mjs, node scripts/smoke_select.mjs. Фактические имена в репозитории: scripts/check-docs.mjs (Node, не Python), scripts/no-new-any.mjs, scripts/smoke-select.mjs (дефис, не подчёркивание) — проверено ls scripts/. Как написано, ни одна из трёх команд не выполнится.

Воспроизведение: ls scripts/check_docs.py → No such file or directory; реальный файл — scripts/check-docs.mjs. Аналогично для двух других.

Решение ревьюера: снимаю как Low без возврата в цикл — не влияет на выполнимость самого AC-контракта (доказательства AC1-AC14 не зависят от этих трёх строк), тривиально исправляется при выходе в реализацию простой заменой имён на актуальные. Автору стоит поправить эти три строки перед S5-ready, но отдельного цикла ревью это не требует.

Low-2 — нет явного блока «принято предположительно, поменять свободно» и явной строки про bundle-бюджет

PROCESS.md §7.1 требует технические решения автора, не наблюдаемые пользователем, фиксировать явным блоком в конце ТЗ. Документ принимает несколько таких решений по ходу текста (имя нового модуля src/device-position-history.ts помечено «рекомендуемо», отдельный CommandStack<DevicePositionCommand>(50) вместо переиспользования geometry-стека, форма интерфейса DevicePlacement), но не сводит их в отдельный итоговый блок. Также §12 называет производительность (O(1), снижение нагрузки на pointermove), но не отдельной строкой — влияние на bundle:budget (256000 B gzip, AGENTS.md:334) от нового модуля + 2 кнопок + 2 ключей i18n×4 языка.

Решение ревьюера: снимаю как Low. Технические решения по существу разумны, обоснованы рядом (риски §17 прямо привязаны к каждому), и реальный прирост бюджета от pure-модуля на пару функций и двух иконок пренебрежимо мал по сравнению с порогом 256000 B — нет оснований ожидать, что бюджет пострадает. Формальное отсутствие сводного блока не создаёт продуктовой неоднозначности и не блокирует DoR по существу.

Других находок нет. High и Medium не обнаружены — ни в скоупе, ни вне его.

Что проверено и признано корректным

• Все технические утверждения §2 «Актуальность на 2026-08-30» о поведении текущего dev — фактически точны (детали выше, пп. 1-11). Раздел не содержит выданной за факт догадки: каждое утверждение фальсифицируемо и выдержало проверку.
• Продуктовая рамка (§1): персона, поверхность, момент и видимый результат названы, соответствуют J6 из docs/SCOPE.md и позиции «редакторы admin-only, desktop-first» — противоречий с UX-MODES.md / TOUCH-SUPPORT.md не найдено.
• Не-скоуп (§4) и строгая граница истории (§11) описывают ровно то, что оставлено вне задачи, без незаявленных побочных эффектов на geometry/decor историю: reuse-механизмы (own-echo/content fingerprint, кросс-space переключение) — это переиспользование уже существующего в коде контракта, а не новое допущение, которое стоило бы адресовать владельцу.
• AC1-AC14 (§13) — каждый снабжён способом доказательства (unit / browser smoke / golden / source guard), формулировки однозначны, ни один не описывает выдуманное поведение.
• Откат (§17, последний абзац) и миграция (везде явно «не требуется», формат layout не меняется) — присутствуют и не голословны, поскольку backend API уже существует без изменений (см. п. 6 выше).
• Открытых продуктовых вопросов владельцу нет; предыдущий комментарий владельца (2026-08-14) подтверждает это независимо («Вопросы: нет»), и разбор ТЗ не нашёл скрытого продуктового вопроса, который следовало бы поднять вместо этого.
• i18n: новые ключи (history.device_move, history.device_stale) не коллизируют с существующими (проверено grep по всем четырём src/i18n/*.json), план покрывает en/ru/de/fr, что соответствует фактическому состоянию проекта (по 37 history.* ключей на язык уже сегодня).

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

• Не запускал npm run typecheck/npm test/npm run build — на этапе ревью ТЗ кода ещё нет (ветка на SHA a3c305e6 не содержит изменений в src/** или test/** для этой задачи, только сам файл спецификации), гейты реализации нечего гонять.
• Не проверял golden-инфраструктуру построчно за пределами подтверждения, что существующий baseline device-editor toolbar-сценария (geometry-devices-editor-*.png) уже существует как объект для будущего diff — сам скриншот не перегенерировал. Это не требуется на этапе ТЗ.
• Не оценивал производительность драга количественно (нет кода для профилирования); раздел §12 принят по правдоподобию инженерного рассуждения (O(1) snapshot/apply, устранение persist на каждый pointermove объективно снижает, а не повышает нагрузку), не по измерению.
• Не сверял с точностью до символа все 14 AC на предмет полноты матрицы edge-cases сверх выборочной проверки логической согласованности §8-§11 — это стандартный предмет код-ревью (тест умеет падать), а не ревью ТЗ.

Итог

Документ ТЗ #074 методологически образцовый для полного трека: раздел «Актуальность» не содержит ни одной догадки, выданной за факт — все 11+ проверенных технических утверждений о dev подтвердились построчным чтением кода; продуктовая рамка и Core user job названы и совпадают с docs/SCOPE.md; AC полны, пронумерованы и каждый снабжён способом доказательства; риски и откат заполнены содержательно, а не для галочки. Единственные две находки — Low, обе не блокируют DoR и сняты этим ревью с запиской для автора поправить имена скриптов перед стартом реализации.

Вердикт: зелёный. Переход в «Готово к разработке» (S5-ready).