houseplan-card/docs/reviews/CODE-REVIEW-487-r1.md

# CODE-REVIEW-487-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/487
- **Заход:** r1 (первый заход код-ревью; блокирующих циклов израсходовано 0/4)
- **Ветка:** `issue/487-room-temperature-thresholds`
- **SHA материала:** `68462b81e08b6f4c3f366703879199bf5e493374` (проверено `git rev-parse HEAD` непосредственно перед выводом)
- **ТЗ:** `docs/specs/487-room-temperature-thresholds.md` (ревью ТЗ — зелёное, SPEC-REVIEW-487-r1)

## Скоуп диффа

`git diff origin/dev...HEAD`, 78 файлов. Продуктовый код: `src/types.ts`,
`src/logic.ts` (`roomTempRangeOf`), `src/space-dialog.ts` (draft/writer
helpers), `src/room-temperature-controls.ts` (новый, UI блока), `src/houseplan-card.ts`
(Full View: state, resolver, дренаж диалога), `src/houseplan-editor-runtime.ts`
(диалог создания/редактирования комнаты, writer, кнопки Save), `src/space-render.ts`
(static card), `src/styles/dialogs.styles.ts`, i18n en/ru/de/fr, backend
`validation.py` (`_finite_number_or_none`, `ROOM_SCHEMA`), `import_export.py`
(`_ROOM_DISPLAY_FIELDS`). Плюс тесты (unit/backend/smoke/golden/mutation),
config-schema/registry, changelog RU+EN, USER-GUIDE RU+EN, CONFIG-COMPATIBILITY,
ARCHITECTURE, bundle-budget.

История ветки содержит один задокументированный инцидент до код-ревью: хендофф
`S6→S7` в 07:40 не смог перейти в ревью, потому что ветка не ребейзилась на
`dev` без конфликта (комментарий 07:41, конфликт только в `dist/**` и
`custom_components/houseplan/frontend/**` — сгенерированный класс D). Это не
цикл ревью: код никто не читал, вердикта не было. После `git rebase origin/dev`
и пересборки бандла (коммиты `e2751062`…`68462b81`) ветка вернулась в
`S7-code-review` в 07:58; именно эта версия и есть материал настоящего r1.

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

### Дешёвые гейты — сняты с зелёного Validate на точном SHA (не гонялись повторно)

Validate `68462b81` (https://github.com/Matysh/houseplan-card/actions/runs/34201690270) —
`success`; job «Фронтенд: типы, юниты, мутанты, синхрон бандла» зелёный, что
покрывает `npx tsc --noEmit`, `npm test`, `npm run build` + сверку бандла.
`docs`/`process-gate`/`hacs`/`hassfest` — зелёные там же.

На этом SHA тяжёлые джобы (`smoke`, `golden`, `performance_smoke`, `backend`)
в самом `68462b81` — `skipped` (обычный push, не release-candidate — §8). Но
`git diff 89deee0f..68462b81 --stat` показывает единственное отличие —
`docs/images/screenshots.json` (провенанс скриншотов документации, не код).
На `89deee0f` (родитель `68462b81`, идентичный функционально) прогон
https://github.com/Matysh/houseplan-card/actions/runs/34201299329 (`workflow_dispatch
full=true`) дал: `Бэкенд: pytest` → success, `Golden-кадры против принятых
эталонов` → success, `Смоки: все шарды зелёные` (1/3, 2/3, 3/3) → success,
`Мутанты по диффу` (1/3, 2/3, 3/3) → success, `Перф-смок` → success. Общий
конклюжен run был `failure` только из-за `Предполётные проверки: документация`
(ожидаемо — экран-провенанс устарел до докоммита `68462b81`, который его и
чинит). Поскольку единственная разница между `89deee0f` и `68462b81` —
docs-провенанс, результаты тяжёлых джобов на `89deee0f` переносятся на текущий
SHA без повторного прогона.

**Явно НЕ гонял:** `npm run gate:small` целиком, `npm run golden:capture`,
полный `npm test` локально (не нужно — см. выше), `python -m pytest
tests_backend -q` целиком (targeted-прогон уже зафиксирован в CI-джобе
«Бэкенд»).

### Что прогнал сам

- `node scripts/smoke-select.mjs --base origin/dev --head HEAD` — вывод см.
  ниже, прямых совпадений 22, слабых связей (только `_roomDialog`) 3.
  Диффу для этой задачи целиком покрывающий смок — новый
  `smoke_room_temperature_thresholds.mjs`, уже зелёный в CI (шард 3/3, run
  34201299329). Остальные 21 прямых совпадений (`_nameSel`, `_areaSel`,
  `_roomDialog`, `_climate`, `_renderPlanHass`, `_markers`) относятся к
  существующим, не тронутым этой задачей веткам поведения (стены, мердж/сплит,
  автозакрытие) — изменения в этой задаче в `_saveRoom`/`_saveRoomEdit`/
  `_openRoomEdit`/`_resetRoomDialogFields` строго аддитивны и активируются
  только при непустом черновике температуры (проверено чтением — см. ниже),
  поэтому дополнительный прогон всей группы не требуется; 3 слабые связи
  (`_roomDialog` без иного пересечения) также не запускал — риск регрессии в
  них не выше, чем в 21 пропущенном прямом совпадении, и по той же причине.
- `node scripts/mutation-gate.mjs --id=room-temperature-blank-becomes-zero` →
  чистый прогон **ok**, мутант **ok: тест покраснел, как обязан**.
- `node scripts/mutation-gate.mjs --id=room-temperature-min-inherits-wrong-side`
  → чистый прогон **ok**, мутант **ok: тест покраснел, как обязан**.
- Ручная мутация вне реестра (для AC7, «чистый юнит», по правилу §2.7
  достаточно прогона со снятой защитой, приведённого в документе): в
  `src/space-render.ts` временно заменил `tempRange.min, tempRange.max,` на
  `disp.tempMin, disp.tempMax,` (тот самый регресс, который описывает AC7 —
  «один из renderer paths продолжает передавать disp.tempMin/max напрямую») и
  прогнал `node --test test/room-temperature-renderers.test.mjs`: тест
  **упал** (`assert.doesNotMatch` сработал). Патч отменён сразу после
  прогона, дерево чистое (`git status` — clean).
- Прочитал (не исполнял отдельно, потому что уже покрыто CI выше): весь
  продуктовый дифф построчно — `src/logic.ts`, `src/space-dialog.ts`,
  `src/room-temperature-controls.ts`, `src/houseplan-card.ts` (включая
  `_resolvedRoomFills`, `_roomTemp`/`_roomHum`, обработчики диалога),
  `src/houseplan-editor-runtime.ts` (`_saveRoom`, `_saveRoomEdit`,
  `_roomSettingsFromDialog`, `_openRoomEdit`, `_resetRoomDialogFields`,
  `_renderRoomDialog`), `src/space-render.ts`, backend `validation.py`/
  `import_export.py`, все i18n правки, `scripts/config-schema.json`,
  `scripts/config-field-registry.mjs`, `scripts/bundle-budget.mjs` (объяснение
  поднятого потолка 290 500→291 500 с измеренным фактом 290 937 Б).
- Проверил, что провенанс golden-эталонов реален: коммит `89deee0f` несёт
  `Release: v1.73.0-beta.6` и `Baseline-Reviewed: .../runs/34198109380`. Этот
  прогон в целом `cancelled`, а его job «Golden-кадры против принятых
  эталонов» — `failure`. Проверил семантику: `goldenRunFailed()` в
  `demo/golden/policy.mjs` считает verify-прогон красным, если **любой**
  сценарий не `passed` — а для двух совершенно новых сцен закономерно нет
  эталона (`missing-baseline` ≠ `passed`), то есть красный статус этого job
  ожидаем именно потому, что сцены новые, а не потому, что кадры неверны.
  Подтверждение, что принятые эталоны корректны: `89deee0f` сам по себе (уже
  содержащий новые эталоны) даёт `Golden-кадры против принятых эталонов` →
  **success** в run 34201299329. Ложной тревоги не было, но стоило проверить
  явно — процесс запрещает «зелёный ради зелёного» (правило 13), поэтому
  ссылка на красный/отменённый прогон заслуживала отдельной проверки, а не
  доверия на слово.

### smoke-select — вывод инструмента

```
Матрица: 231 смоков · порог «широкого» символа: больше 46 смоков

Прямое совпадение (22): smoke_room_settings, smoke_editor_tabs,
smoke_merge_split, smoke_room_autoclose, smoke_draw_wall_thickness,
smoke_feedback_v2, smoke_island_rooms, smoke_junction_limits,
smoke_plan_drawing_repairs, smoke_room_temperature_thresholds (← _roomTempMax,
_roomTempMin — новый смок, целевой),
smoke_unified_wall_tool, smoke_v8_draft_write, smoke_wall_face_overlap,
smoke_wall_thickness_transition, smoke_zero_divider_taper, smoke_binding_picker,
smoke_climate_once, smoke_climate_temp, smoke_linked_virtual_light,
smoke_registryless_opening, smoke_render_invalidation, smoke_room_climate_placement

Слабая связь (3, только по _roomDialog): smoke_plan_snap_overlay,
smoke_split_nonsnap, smoke_split_polyline
```

## Находки

Нет находок уровня High или Medium.

**Low (не блокирует, зафиксировано без правки):**

1. `src/houseplan-card.ts`, метод `_roomTemp`/`_roomHum` (около строки 12559) —
   попутный рефакторинг, не требуемый задачей: две задокументированные
   функции с раздельными JSDoc-комментариями схлопнуты в однострочный
   тернарник без комментариев. Поведение идентично (сравнил построчно: было
   `if (src) return sourceValue(...); ...; return key ? ... : null;`, стало
   `src ? sourceValue(...) : key ? ... : null`) — регрессии нет, но это
   несвязанная правка соседнего кода вне скоупа задачи (правило «скоуп не
   расширяется», §2.6). Решение — оставить: правка безвредна и обратный откат
   стоит дороже, чем экономит.
2. `src/styles/dialogs.styles.ts` — блок `.colorrow { ... }` переформатирован
   с отступа 6 пробелов на 2 без изменения содержимого (чистый шум диффа);
   остальной файл сохраняет 6-пробельный отступ. Не влияет на выполнение,
   решение — оставить.
3. `demo/smoke_room_temperature_thresholds.mjs` не проверяет отдельно случай
   «невалидное значение при скрытом (не-temp) режиме заливки всё равно
   блокирует Save» — AC5/AC6 пересекаются здесь только по построению кода
   (`tempValid`/`canSaveNew` не зависят от видимости блока), не по
   отдельному свидетелю. Логика проста и линейна, дополнительного риска не
   вижу — не Medium, просто отмечаю как замеченный, но не обязательный пробел
   покрытия.

## AC — таблица «чем доказано / чем краснеет»

| AC | Доказано | Чем краснеет — команда и результат |
|---|---|---|
| AC1 Полное наследование | `test/logic.test.mjs` (`roomTempRangeOf(20,25,null)` и правки space min/max без записи комнаты — читал `_resolvedRoomFills`, наследование идёт через `disp.tempMin/tempMax`, не кэшируется) | покрыто `test/logic.test.mjs`; отдельного мутанта в реестре нет (чистый юнит, читал вручную — резолвер не хранит состояние между вызовами) |
| AC2 Полный override + соседняя комната | `test/logic.test.mjs` + `demo/golden/matrix.mjs` (`room-temperature-dialog-mobile-ru`, partial); соседство проверяется тем, что резолвер вызывается **на комнату**, а не на пространство (цикл `space.rooms.map` в `space-render.ts` и `_resolvedRoomFills`) | `test/room-temperature-renderers.test.mjs` — проверил вручную: откат `space-render.ts` на `disp.tempMin/tempMax` красит тест (см. «ручная мутация» выше) |
| AC3 Частичный override | `test/logic.test.mjs` (own min only / own max only), `test/space-dialog.test.mjs` (`roomTempThresholdDraft('', '19')` → `{min:null,max:19}`) | `--id=room-temperature-min-inherits-wrong-side` → **краснеет** (запускал) |
| AC4 Переставленные границы | `test/logic.test.mjs` (`temp_min:28, temp_max:18` → `{min:18,max:28}`), `test/space-dialog.test.mjs` (`'24,5'`/`'18,5'` с запятой как разделителем — проверил, что `strictNumber` понимает и запятую, и точку) | читал: удаление `Math.min/Math.max` в `roomTempRangeOf` очевидно ломает оба теста выше |
| AC5 Blank/zero/invalid | `test/space-dialog.test.mjs` (`applyRoomTempThresholdDraft` пустое→удаление key, `'0'`→`0`, `'bad'`→`false` без изменения settings) | `--id=room-temperature-blank-becomes-zero` → **краснеет** (запускал) |
| AC6 Скрытые значения не теряются | `demo/smoke_room_temperature_thresholds.mjs` (`hiddenOutsideTemp`, `hiddenDraftRetained`) — зелёный в CI (шард смоков, run 34201299329); писатель (`applyRoomTempThresholdDraft`) вызывается безусловно, не под `if (effectiveFill==='temp')` — проверил чтением в `_saveRoomEdit`/`_roomSettingsFromDialog` | проверено чтением: перенос вызова `applyRoomTempThresholdDraft` под условие `fill==='temp'` регрессировал бы AC6, но живого свидетеля-мутанта на этот шаг нет — единственный пробел эквивалентного веса Low №3 выше |
| AC7 Live preview / parity | `test/room-temperature-renderers.test.mjs`, golden `room-temperature-dialog-desktop-en/mobile-ru` (успешно верифицированы в CI, run 34201299329) | проверил вручную (см. «ручная мутация») — **краснеет** |
| AC8 UI/responsive | golden (обе сцены: desktop-en 900×900, mobile-ru 390×820 dark + partial override), `demo/golden/harness.mjs` бросает при `scrollWidth > clientWidth+1` или неполном наборе полей | golden verify зелёный в CI на этих двух сценах; убрать `flex-wrap: wrap` в `.roomtemprange-fields` сломало бы `narrowHasNoHorizontalScroll` в смоке — не проверял отдельным мутантом, чисто визуальный CSS-инвариант |
| AC9 Backend/compat | `tests_backend/test_validation.py::test_room_temperature_thresholds_are_optional_strict_finite_numbers` — bool/строка/NaN/Infinity отклоняются, `None` принимается, `0`/`24.5` проходят | тест сам по себе явно перебирает контрпримеры (`True`, `"20"`, `nan`, `inf`) внутри одного теста — эквивалент мутации, проверил чтением, что `_finite_number_or_none` действительно вызывает `vol.Invalid` на каждый |
| AC10 Import/export | `tests_backend/test_ha_import_export.py` — full/space round-trip сохраняет `temp_min/max` вместе с `future_room_binding` (недокументированное поле не теряется), plan-only включает оба поля в проекцию и отбрасывает `area`/`future_room` | читал `_ROOM_DISPLAY_FIELDS`: поля добавлены в allowlist рядом с `glow`, а не в HA-identity список — приватность plan-only не ослаблена |
| AC11 Без побочных изменений | `_roomTemp`/`_roomHum` не создают новый climate-pass — сверил, что `roomClimateKey`/`this._climate()` вызываются так же, как до диффа (см. Low №1: рефакторинг чисто косметический) | проверено чтением; `roomTempRangeOf` не читает `hass`/`this._climate()` вообще — чисто математическая функция от трёх аргументов |
| AC12 Локализация/docs | `test/i18n-dead-keys.test.mjs` (`derivedHelpAria.size` 19→20, детерминированно проверяет, что `.help`/`.help.aria` пара существует для всех языков через `_help()`); USER-GUIDE EN/RU и CONFIG-COMPATIBILITY правки читал построчно — соответствуют реальному контракту (наследование, «As the space», единственный потребитель — заливка) | i18n-parity тесты — часть «Фронтенд» job, зелёного на `68462b81` |

## Продуктовое рассуждение (не только AC)

Задача заявлена как закрытие пробела в J5 («Room climate at a glance»,
`docs/SCOPE.md` явно называет «Threshold colouring for room-card metrics» в
списке частично покрытых улучшений). Реализация точно уважает решения
владельца от 07.09: наследование двухуровневое без глобального яруса, нет
ссылок на HA helpers, нет отдельного индикатора «свой диапазон» вне диалога.
Соседние поверхности (room-card, tooltip, источник температуры, HA
service calls) не тронуты — проверил построчно, единственный потребитель
новых полей это `resolveEffectiveRoomFill` через `roomTempRangeOf`/
`roomTempRangeFromDraft`.

«Одно число — один источник» (обязательная проверка): диапазон комфорта
комнаты вычисляется **один раз за кадр** в `_resolvedRoomFills()`
(Full View) и **один раз** в `renderSpaceStatic()` (static card) — оба
вызывают один и тот же чистый резолвер `roomTempRangeOf` (static — напрямую,
Full View — через `roomTempRangeFromDraft`, который добавляет только черновик
активного диалога поверх того же резолвера). Ни диалоговый placeholder, ни
подпись, ни room-card не показывают температурный диапазон отдельно — они
показывают саму температуру, которая этой задачей не переоценивается.
Дублирования числа не вижу.

## Унаследовано / что проверял в этом раунде

Не применимо — это первый заход (r1) код-ревью для #487. Раздел «Унаследовано
из r<N−1>» не требуется (§2.10 относится к повторным раундам). Досрочный
инцидент «Ревью не запускалось» (рассинхрон бандла при ребейзе, 07:41) не
образует раунда: код не читался, вердикта не было, только конфликт
слияния — материал этого r1 это версия ветки уже **после** ребейза.

## Вердикт

Зелёный. AC1–AC12 доказаны — либо автотестом с подтверждённым «умением
падать» (два зарегистрированных мутанта в `scripts/mutation-gate.mjs` плюс
одна ручная мутация для AC7, все три реально прогнаны в этом раунде и
показали красный на дефекте), либо проверкой чтением с явной пометкой.
Находки — три Low, ни одна не требует правки для приёмки (оставлены с
записью выше). Дешёвые гейты подтверждены зелёным Validate на точном SHA
`68462b81` и его функционально идентичном родителе `89deee0f` (полный
тяжёлый набор, включая golden и все три шарда смоков). Golden-провенанс
проверен отдельно из-за красного/отменённого `Baseline-Reviewed` прогона —
семантика подтверждена (новые сцены закономерно красят verify до принятия),
подмены эталонов не найдено.

---

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

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

- Ветка: `issue/487-room-temperature-thresholds`, коммит `68462b81e08b` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `5e50ffb3debd91974b494e4ba49d073a8402e583`
  ```
  git log --all --format='%H %T' | grep 5e50ffb3debd
  ```
- ТЗ `docs/specs/487-room-temperature-thresholds.md`, блоб `d1d33e782d3edd6fd7e393c6e372a7d76439d05e`
  ```
  git log --all --find-object=d1d33e782d3edd6fd7e393c6e372a7d76439d05e -- docs/specs/487-room-temperature-thresholds.md
  ```