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

SPEC-REVIEW-196-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/196
• ТЗ под ревью: тело issue #196 (лёгкий трек small, файл в docs/specs/ отсутствует — корректно, docs/specs/196-*.md не создан)
• Роль: ревьюер ТЗ (не автор), этап S4-spec-review
• Трек: лёгкий (small), лимит циклов ревью ТЗ — 2 (§4, §5 PROCESS.md)
• Цикл: r1/2

Скоуп ревью

ТЗ #196: room hover tooltip в View получает необязательную строку «средняя влажность: N%» между температурой и LQI. Значение берётся из уже существующего _roomHum() (tier-3 hum_source → среднее по HA-зоне из _climate()), симметрично уже реализованной температуре. Device tooltip, room card/label (влажность там уже есть), touch-эквивалент hover, backend, схема, миграция — вне скоупа по тексту ТЗ.

Ветки issue/196-* в репозитории ещё нет — ожидаемо: лёгкий трек, задача только что вышла из аналитики в ревью ТЗ, продуктового кода не существует. Гейты (typecheck/test/build, smoke) не прогонялись: на этом этапе им неоткуда взяться (PROCESS.md §2.4/§8).

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

1. Прочитаны целиком docs/SCOPE.md, AGENTS.md, PROCESS.md (действующая редакция, включая §1, §2.4, §5, §7.1, §8).
2. Прочитано тело issue #196 целиком и все три комментария: аналитика владельца (ценность 4/10 · сложность 2/10 · P2 · enhancement · поверхности src/houseplan-card.ts + i18n + smoke/docs · трек small, trivial явно отклонён из-за нового i18n-ключа) и два «Взял:» на роли аналитика/автора ТЗ.
3. Построчно сверены все технические утверждения раздела «Сейчас» и «Контракт» с кодом origin/dev (src/houseplan-card.ts, 19891 строка):
   • _tip / _showTip() — houseplan-card.ts:713 и :5758: сигнатура (ev, title, meta, lqi?, temp?), поле _tip уже несёт lqi?: number | null; temp?: number | null. Добавление hum?: number | null последним параметром — прямое расширение без переупорядочивания существующих.
   • Room hover передаёт _showTip(e, name, area, lqi, this._roomTemp(r)) — houseplan-card.ts:15627-15633 (в ТЗ заявлено :15621, расхождение на 6 строк из-за коммитов после написания ТЗ — не дефект, код найден и совпадает буквально).

   • Рендер тултипа — houseplan-card.ts:15863-15874 (в ТЗ :15860, то же

     смещение): строка tip.temp идёт первой (if (this._tip.temp != null)),

     затем tip.lqi — вставка hum между ними ровно там, где просит

     контракт п.3, синтаксически тривиальна (тот же паттерн `!= null ? html…

     nothing`).

   • Device tooltip — houseplan-card.ts:16729-16731: вызывает _showTip(e, d.name, metrics) — без lqi/temp/hum вовсе. Подтверждает заявление контракта п.1 «existing device call остаётся семантически неизменным»: добавление пятого необязательного параметра ничего здесь не меняет, TS не потребует правки этого call site.
   • _roomTemp() / _roomHum() — houseplan-card.ts:16769-16781: функции буквально симметричны («tier-3 temp_source/hum_source → иначе _climate().get(area)»). _roomHum() уже существует и уже используется в room label (:17085-17086, ${hm}% — тот же формат значения, что просит ТЗ). Ссылка на реальный существующий helper, а не на функцию, которую ещё нужно написать.
   • _climate() — houseplan-card.ts:16792-16802: один кеш на hass identity, комментарий на :16790 дословно говорит «two, with humidity on» (в ТЗ упомянут как :16784, тот же класс смещения) — подтверждает п.7 контракта: чтение влажности не создаёт нового прохода по registry.
   • _noHover — houseplan-card.ts:5652-5653, используется как guard первой строкой _showTip() (:5759) — подтверждает контракт п.6: _showTip уже отказывается строить тултип на no-hover устройствах, новая строка не создаёт новую touch-поверхность просто потому, что hum передаётся тем же вызовом.
   • Значение уже целое: areaClimateMap округляет hum до Math.round(...) (src/devices.ts:1396), sourceValue() для явного entity:/device: источника — тоже Math.round(v) (src/devices.ts:1252, humFor). Предположение ТЗ «значение не пересчитывается, используется готовый результат _roomHum() с суффиксом %» корректно: дробного значения физически не бывает, формат ${hum}% без округления в тултипе не потеряет точность.
4. Прочитан src/i18n/en.json и ru.json: tip.temp_avg (:374 "average temperature:" / "средняя температура:") и tip.lqi (:150) — предложенный tip.hum_avg ("average humidity:" / "средняя влажность:") следует тому же формату (двоеточие, строчная буква, average <metric>:), новый ключ не выдуман по структуре.
5. Прочитан docs/USER-GUIDE.ru.md: строка 173 (таблица режимов) — «подсказка показывает название, чистую площадь, температуру и LQI» — это ровно то место, которое ТЗ обязано обновить (и заявляет это в разделе Release), и ровно то место, что фиксирует нынешний пробел (влажности в перечислении нет, хотя строка 128/275/1175 подтверждает, что влажность уже показывается в room card). Строка 1310 «Комнатные подсказки основаны на hover» — существующее, не создаваемое этим ТЗ ограничение, распространяется на новую строку тем же образом, что и на текущие.
6. Прочитан docs/TOUCH-SUPPORT.md целиком. Правило «Documentation rule» (Touch editor: …) относится к «New editor feature specifications» — тултип комнаты живёт в View, не в редакторе, правило не применяется механически. Контракт «fully supported View» (строка 31-32: «provide a touch path for essential information that desktop exposes through hover») для влажности не создаёт нового риска: disp.labelHum уже кладёт влажность в room label (houseplan-card.ts:17084-17086), который виден без hover — то есть на touch влажность уже доступна отдельным путём, ТЗ не ухудшает существующий (уже документированный как ограничение, USER-GUIDE.ru.md:1310) hover-only статус тултипа для area/temp/LQI.
7. Проверено, что docs/specs/196-*.md не существует (ls docs/specs/ — пусто по маске) — соответствует лёгкому треку.
8. Проверено соответствие docs/SCOPE.md: задача закрывает J5 «Room climate at a glance» (persona home admin/household, View), не расширяет out-of-scope списки, не касается lock invariant, не создаёт нового job'а.
9. Проверены оба существующих файла-кандидата для smoke: demo/smoke_ux_fixes.mjs (:21-27) уже содержит инфраструктуру для проверки _tip.temp и текстового содержимого .tip («средняя температура»), то есть AC1-AC3 технически осуществимы без нового тестового харнесса — паттерн для новой hum-проверки уже есть в файле. demo/srv/demo.html не содержит фикстуры-сенсора влажности; но 31 файл в demo/ (в т.ч. smoke_room_settings.mjs, smoke_sun.mjs и др.) уже инжектируют синтетические hass.states динамически в page.evaluate — значит отсутствие штатной humidity-фикстуры не блокирует AC1/AC2, разработчик может ввести сенсор тем же приёмом. Это техническое решение, ТЗ корректно оставляет выбор конкретных имён/assertions разработчику (раздел «Принятые технические предположения»).

Обязательные разделы для лёгкого трека (§5 PROCESS.md)

Раздел	Есть	Комментарий
Проблема	✅	Подтверждена построчным чтением кода (см. «Как проверялось» п.3): _roomHum() существует и используется в label, но не в tooltip — не догадка, факт
Контракт	✅	7 пронумерованных пунктов, включая явную защиту от расширения device tooltip (п.1) и touch-поверхности (п.6)
AC1…ACn с доказательством	✅	5 штук, у каждого назван способ (smoke/unit+build/«ревью кода»)
Откат	✅	«Совместимость и откат»: revert одного коммита, без миграции, без cleanup

Дополнительно присутствуют разделы, не обязательные для лёгкого трека, но усиливающие ТЗ: «Не входит в задачу» (явный анти-скоуп), «Файлы и проверки», «Release, performance, security, visual», «Принятые технические предположения» (3 пункта, все технические — не маскируют продуктовый вопрос).

Находки

Low-1 — AC2 частично привязывает smoke-доказательство к утверждению, проверяемому только кодом

Место: тело issue #196, раздел «Критерии приёмки», AC2: «код tooltip вызывает общий _roomHum(), а не дублирует resolver».

Первая половина AC2 (значение override совпадает с настроенным hum_source) действительно проверяется браузерным смоком через видимый текст. Вторая половина («не дублирует resolver») — по природе утверждение о структуре кода, а не о видимом поведении; смок не может отличить «вызвал _roomHum()» от «скопировал ту же формулу в другом месте с тем же результатом». Это не отменяет проверяемость: AC5 уже требует ревью кода на отсутствие новых resolver'ов/scope creep, так что содержательно вторая половина AC2 покрыта — реального пробела в доказательстве нет, только неточная маркировка способа доказательства одним словом smoke на весь пункт.

Обоснование severity: Low — не блокирует, ничего не остаётся непроверенным, дефект чисто редакционный (смешаны behavioral и structural части одного AC под одной меткой доказательства).

Решение ревьюера: снимаю без возврата ТЗ на правку. Код-ревью (AC5) обязан явно подтвердить, что _roomHum() вызывается напрямую, без дублирования резолвера — этот пункт настоящим решением фиксируется как входящий в объём AC5, а не отдельно требующий правки текста ТЗ.

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

• Диагноз проблемы не голословен. _roomHum() (:16777-16781) дословно симметричен _roomTemp() (:16769-16774), уже используется в room label (:17085-17086) и уже настраивается в диалоге комнаты (_renderRoomSource('hum'), :19717-19838) — но не передаётся в _showTip() при hover (:15627-15633). Пробел реален, не выдуман.
• Соответствие docs/SCOPE.md: закрывает J5, персона home admin/household member, поверхность View; не расширяет lock invariant, out-of-scope список, backend/schema/migration.
• Контракт защищает device tooltip от регрессии (п.1, подтверждено реальным call site :16729-16731, который не передаёт lqi/temp вовсе — пятый необязательный параметр hum для него ничего не меняет).
• Touch-поверхность не ухудшается. Room label уже показывает влажность без hover (disp.labelHum, :17084-17086); hover-only статус самого тултипа — существующее, уже задокументированное ограничение (USER-GUIDE.ru.md:1310), не создаваемое этим ТЗ. Правило Touch editor: … из docs/TOUCH-SUPPORT.md не применяется — это не editor-фича.
• AC1-AC5 однозначны, каждый снабжён допустимым способом доказательства (smoke/unit+build/«ревью кода»); формат значения (Math.round, целое число, суффикс %) подтверждён на уровне devices.ts — в тултипе не появится дробное число, которое пришлось бы отдельно форматировать.
• i18n-ключ следует существующей конвенции (tip.temp_avg → tip.hum_avg, тот же шаблон текста на обоих языках).
• AC3 корректно защищает границы: null/невалидный источник не показывает строку (тот же паттерн != null, что уже используют tip.temp/tip.lqi), device tooltip не получает ложную влажность, _noHover не создаёт тултип — все три случая проверены по коду и логически вытекают из уже существующих guard'ов, не из нового кода, который ещё предстоит написать правильно.
• Откат тривиален — один user-visible коммит, без миграции схемы/данных, без cleanup.
• Принятые технические предположения (3 пункта) — все технические (порядок параметра _showTip, отсутствие пересчёта формата, свобода имён тестов), продуктовый вопрос под видом технического решения не найден.
• Не додумано скрытых предположений о поведении. Ни одно утверждение контракта не описывает поведение, которого нет в коде/канонических документах и не помечено как assumption.

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

• Реализацию — её нет: ветка issue/196-* в репозитории отсутствует, продуктовый код не менялся (git branch -r не находит ветку).
• Гейты typecheck/test/build/smoke — не относятся к этапу ревью ТЗ (PROCESS.md §2.4/§8), выполнить их не над чем.
• python -m pytest tests_backend — задача не касается backend ни кодом, ни текстом ТЗ.
• Реальный визуальный результат (браузерный рендер строки влажности, точное позиционирование .tip) — CSS/разметка ещё не написаны; заявленное («тот же паттерн, что и temp/lqi») — это план, а не исполненный факт, что и должно быть на этапе ТЗ.
• Точность числовых оценок аналитики (4/10, 2/10, P2) по существу — поле владельца (PROCESS.md §2.2), не предмет ревью ТЗ.
• Возможность технического спора автор/ревьюер по разделу «Принятые технические предположения» — не возникла, все три пункта разумны без необходимости их оспаривать.

Вердикт

Зелёный. High: 0, Medium: 0, Low: 1 (AC2 смешивает поведенческую и структурную часть под одной меткой smoke — не оставляет пробела в доказательстве, так как структурная часть уже покрыта AC5; снимается без возврата ТЗ на правку, код-ревью проверяет обе половины). ТЗ подтверждено построчным чтением кода origin/dev: каждое техническое утверждение оказалось фактом (с точностью до нормального смещения номеров строк из-за коммитов после написания ТЗ), продуктовых вопросов владельцу нет и не додумано новых, AC1-AC5 однозначны и снабжены допустимыми способами доказательства, откат тривиален, лёгкий трек применён корректно (новый i18n-ключ и enhancement-тип верно исключают trivial, сложность/риск ≤3 и одна поверхность верно подтверждают small).

Вердикт: зелёный · цикл r1/2 · High: 0 · Medium: 0 → в задаче · Документ: docs/reviews/SPEC-REVIEW-196-r1.md