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

SPEC-REVIEW-426-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/426
• Этап: spec (ревью ТЗ, PROCESS.md §2.4)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4
• Материал: docs/specs/426-room-hover-tooltip-toggle.md на ветке issue/426-room-hover-tooltip-toggle, SHA 587c20699c4bc1ada405c5c7f9775d34b2b78a39 (совпадает с ревизией, заявленной автором в issue).
• Трек: полный (не small) — аналитик назвал нарушенные критерии §5 корректно: новое compatibility-поле в config.settings и новый публичный UX-контракт, изменение проходит через frontend и backend.

Скоуп

Один глобальный переключатель «Показывать окно с информацией при наведении на комнату» в «Общих настройках», управляющий только room-tooltip в View (включая kiosk с мышью); hover-подсветка комнаты и все прочие тултипы не меняются. Новое optional settings.show_room_tooltip: boolean, default true материализуется отсутствием ключа.

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

Ревью ТЗ на этапе spec не запускает автотесты/гейты (кода ещё нет) — задача ревьюера здесь одна: убедиться, что каждое AC однозначно, доказуемо, и что факты о текущем коде, на которые опирается контракт, не являются не помеченной догадкой. Поэтому весь разбор — очный аудит соответствия текста ТЗ реальному состоянию репозитория 587c2069:

1. docs/SCOPE.md, PROCESS.md, AGENTS.md — трек, обязательные разделы §7.1, класс изменений, шаблон вердикта.
2. Тело issue #426 и оба комментария (аналитика, занятие, готовность ТЗ) — сверка с тем, что владелец зафиксировал сам (место настройки, точная формулировка, default) против того, что ТЗ выдаёт за решённое.
3. docs/USER-GUIDE.ru.md (строка 203, 1871) — терминология «подсказка»/ «наведение», состав room-tooltip (название, чистая площадь, температура, влажность, LQI) — совпадает с описанием AC4.
4. docs/UX-MODES.md, docs/TOUCH-SUPPORT.md (pointer modality, hover ownership) — независимость room hover-подсветки от tooltip и контракт touch/pen уже существуют и не меняются этим ТЗ.
5. Построчная проверка каждого фактического утверждения ТЗ о текущем коде:
   • src/houseplan-card.ts:11578-11589 — локальный tip-замыкание на pointermove комнаты, guard if (this._mode !== 'view') return;, безусловный вызов _showTip() — подтверждает раздел «Проблема».
   • src/houseplan-card.ts:7282-7294 — _showTip() общий для комнаты и устройства, проверяет hoverEnabled/drag, ничего не знает про room-specific флаг — подтверждает риск «не трогать общий guard».
   • src/houseplan-card.ts:1032, 9542, 9659, 9668, 11626-11677 — _hoverRoom и room-hover-fill-layer/outline-layer независимы от tip, устанавливаются на pointerenter — подтверждает AC5.
   • src/houseplan-card.ts:12463-12472 — device tooltip гейтится _mode !== 'view' && _mode !== 'devices', использует тот же _showTip() — подтверждает «Device tooltip... в View и Редакторе устройств».
   • src/houseplan-editor-runtime.ts:9023-9039, 10213-10253 — _openSettingsDialog/_saveSettingsDialog уже хранят sunRays по схеме «явный true пишется, falsy удаляется» через settings: any = {...cfg.settings} — подтверждает, что план для show_room_tooltip (обратная схема: default true → удаление ключа, false → явная запись) технически реализуем тем же путём, а не гипотетичен.
   • src/houseplan-editor-runtime.ts:10537-10538 — gs.hint действительно первая строка тела диалога — подтверждает «сразу после вводного текста».
   • src/houseplan-editor-runtime.ts:10622-10626 — <label class="srcrow"> оборачивает _boolInput() и <span> для sunRays — подтверждает «доступное имя из видимой строки» как существующий, а не изобретённый паттерн.
   • custom_components/houseplan/validation.py:1917-1968 — CONFIG_SCHEMA.settings уже принимает sun_rays: bool рядом с extra=vol.ALLOW_EXTRA — подтверждает «explicit boolean для нового известного ключа» как существующий шаблон.
   • custom_components/houseplan/support_package.py:139-140 — _global_settings — явный allowlist _copy_keys(...), куда show_room_tooltip предстоit добавить — подтверждает claim о privacy-проекции.
   • src/space-card.ts:2 — докстринг «READ-ONLY, static schematic» — подтверждает «houseplan-space-card не меняется».
   • scripts/config-field-registry.mjs:26-29 — sun_rays (обычное экспонированное поле, не compatibility-долг) в реестре не числится, только show_all; отсутствие записи о новом поле в CONFIG-COMPATIBILITY.md реестре — верное решение по прецеденту, не пропуск.
   • src/i18n/{en,de,fr,ru}.json — ровно четыре синхронных словаря, подтверждает «четыре» без лишнего/недостающего языка.
6. Дубликаты: gh issue view для #79 (closed, регрессия заливки), #154 (closed, touch hover sticking), #196 (closed, содержимое тултипа), #152 (open, но про клик/тап-зум, не про информационное окно) — ни один не пересекается с «отключить только информационное окно».

Материал полный, дельты нет — это первый заход (r1), раздел «Унаследовано из r0» не применим.

Находки

Нет High. Нет Medium. Нет Low.

Все девять AC (AC1–AC9) сформулированы как проверяемые утверждения с указанным способом доказательства (unit/smoke/backend/commands), не пересекаются по ответственности и в сумме покрывают контракт из разделов 1–3: UI/default, persistence, tooltip off, default parity, hover/device independence, pointer/mode parity, compatibility/privacy, i18n/docs/release, гейты/бюджет. План автотестов называет конкретные мутационные пробы для каждого AC (замена resolver на Boolean(value), guard внутри общего _showTip(), скрытие _hoverRoom, хранение true вместо удаления ключа, отсутствие очистки .tip при Save) — то есть тесты, которые способны упасть, а не тавтологичные проверки. Раздел «Принятые предположения» отделяет то, что решил владелец (место, формулировка, default), от того, что решает автор технически (ключ конфига, точное место переключателя в вёрстке диалога, отсутствие per-space override) — ни одна догадка не выдана за факт без пометки.

Продуктовая рамка (SCOPE.md job J1, View как продукт для двух персон из трёх, инвариант «не трогать другие интерактивные эффекты комнаты» из тела issue) соблюдена явно разделами «Скоуп»/«Не-скоуп»/«Контракт поведения» и не противоречит ни одному пункту docs/UX-MODES.md/docs/TOUCH-SUPPORT.md.

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

• Обязательные разделы §7.1 присутствуют все, включая оба продуктовых (сценарий; что человек увидит до/после) первыми.
• AC пронумерованы, у каждого явно назван способ доказательства.
• i18n: ключ gs.show_room_tooltip, все четыре словаря, формулировки заданы.
• Совместимость: optional boolean, ALLOW_EXTRA уже покрывает старый backend/frontend в обе стороны, миграции store/model version нет и не требуется — согласуется с docs/CONFIG-COMPATIBILITY.md (эта настройка не compatibility-долг, а обычное новое поле, как sun_rays).
• Откат описан явно и без требования флага Labs (persisted boolean — сам себе выключатель), с уточнением, что произойдёт при вынужденном отступлении. Требование docs/PROCESS.md §2.5 «откат: как выключить или вернуть назад» выполнено содержательно, а не формальной строкой.
• Release-артефакты называют оба changelog, User Guide EN/RU, UX-MODES.md/TOUCH-SUPPORT.md/CONFIG-COMPATIBILITY.md, осведомлённость о доокументационном скриншотном гейте (check-docs.mjs/source fingerprint) и обоснованный отказ от нового golden-сценария (default View визуально не меняется, диалог общих настроек не входит в принятые golden-сценарии).
• Риски перечислены с конкретной привязкой к AC, который их снимает — не общие фразы.

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

• Существование и корректность самого кода реализации — на этапе spec кода ещё нет по правилу (ТЗ пишется до кода), проверять нечего.
• Гейты typecheck/test/build/no-new-any/check-docs/backend pytest — не запускались: это гейты реализации (S6-in-progress) и код-ревью (S7-code-review), а не ревью ТЗ. Zeленый Validate на 587c2069 (https://github.com/Matysh/houseplan-card/actions/runs/33720335555) проверяет только документационный коммит этого SHA, не имеет отношения к ненаписанному коду issue #426.
• Мутационные пробы плана автотестов не выполнялись физически (кода нет) — оценена только их логическая способность различить дефект от корректной реализации, что и требуется от ревью ТЗ.

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

• Ветка: issue/426-room-hover-tooltip-toggle
• SHA: 587c20699c4bc1ada405c5c7f9775d34b2b78a39
• ТЗ: docs/specs/426-room-hover-tooltip-toggle.md (та же ревизия)

Вердикт

Зелёный. Готово к переходу в S5-ready. High: 0 · Medium: 0.

---

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

• Ветка: issue/426-room-hover-tooltip-toggle, коммит 587c20699c4b — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: ed72e6cb924cd5e6167c04ba95a73fc0f0bf649d

  git log --all --format='%H %T' | grep ed72e6cb924c
  

• ТЗ docs/specs/426-room-hover-tooltip-toggle.md, блоб 35a3ad7ff77cf1597f004b94b0799844b56f29f1

  git log --all --find-object=35a3ad7ff77cf1597f004b94b0799844b56f29f1 -- docs/specs/426-room-hover-tooltip-toggle.md