docs: review document for #426

Issue: #426 User-Visible: no
2026-09-30 19:58:50 +00:00 · 2026-09-03 05:52:52 +00:00
parent 587c20699c
commit ac99a2ff08
1 changed files with 171 additions and 0 deletions
@@ -0,0 +1,171 @@
+# 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.
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `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
+  ```