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

# CODE-REVIEW-251-r1

- Issue: [#251](https://github.com/Matysh/houseplan-card/issues/251) — «Маркер выключателя гаснет, когда недоступна управляемая им лампа — читается как «выключатель offline»»
- Этап: код-ревью (PROCESS.md §2.7), заход **r1**, блокирующих циклов израсходовано **0/4** до этого разбора
- Ветка: `issue/251-controller-target-availability`
- Проверяемый диапазон: `origin/dev..HEAD`
- Коммиты в диапазоне:
  - `ba0c787` docs(spec): separate controller and target availability — `User-Visible: no`
  - `eb4f9aa` docs: review document for #251 (артефакт спек-ревью, зелёный) — `User-Visible: no`
  - `b984f16` fix: separate controller and target availability — `User-Visible: yes`
  - `f18b5b4` docs: refresh screenshots for controller states — `User-Visible: no`
- Спецификация: `docs/specs/251-controller-target-availability.md`, ТЗ-ревью зелёное (r1, `IC_kwDOTOcLQM8AAAABQOr4Dg`).
- r1 — полный разбор, раздел «объём по дельте» (§2.10) неприменим.

## Скоуп

Задача разделяет два факта, которые раньше вычислялись как одно: доступность
физического контроллера (`unavail`/полупрозрачность) и working-состояние
управляемой им цели (`on`/жёлтая подложка) для маркеров с `marker.controls`.
Доступность контроллера теперь читается только из его собственных активных HA
entity states (включая диагностические `battery`/`linkquality`/`update`),
цели в неё не входят. Полностью недоступная configured-группа при явном
Toggle теперь объясняет безопасный no-op локальным тостом с именем цели вместо
молчаливого возврата; частично доступная группа продолжает исполнять доступное
подмножество без тоста. Изменение Glow/fill/statistics, персистентной схемы,
group-семантики «any on → all off» и нового визуального бейджа — вне скоупа и
не тронуты.

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

Дешёвые гейты (гоняются всегда, диапазон `origin/dev..HEAD`, HEAD `f18b5b4`):

| Гейт | Результат |
|---|---|
| `npx tsc --noEmit` | OK, чисто |
| `npm test` | `# tests 1117 / # pass 1117 / # fail 0` (у автора в хендоффе — 1116 passed + 1 skipped; локально skipped не воспроизвёлся, на выводимость AC не влияет) |
| `npm run build` | OK, `dist/houseplan-card.js` собран |
| `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` и `cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` | совпадают, три копии идентичны |
| `node scripts/check-docs.mjs --external` (diff трогает `src/**`) | `Documentation checks passed (7 files, 10 external links)` |
| `node scripts/process-gate.mjs --range origin/dev..HEAD --issues` | `гейт пройден, предупреждений 0` |

По необходимости, определяемой diff'ом и AC:

| Гейт | Результат |
|---|---|
| `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | Прямое совпадение (4): `smoke_controls.mjs` (← `DevItem`), `smoke_help_affordance.mjs`, `smoke_optimize_coordinate_canonicalization.mjs`, `smoke_partition_openings.mjs` (все три ← `_showToast`, широко используемый символ — слабая связь, но дешёвые, прогнал все) |
| `node demo/smoke_controls.mjs` | OK, включая новые ключи `unavailableTargets*`, `confirmRace*` — все `true` |
| `node demo/smoke_help_affordance.mjs` | OK |
| `node demo/smoke_optimize_coordinate_canonicalization.mjs` | OK |
| `node demo/smoke_partition_openings.mjs` | OK |
| `node scripts/mutation-gate.mjs --id=controller-availability-follows-target` | `controller-availability-follows-target: тест покраснел, как обязан` (1/1) |
| `node scripts/mutation-gate.mjs --id=controller-diagnostics-do-not-prove-online` | покраснел (1/1) |
| `node scripts/mutation-gate.mjs --id=unavailable-toggle-stays-silent` | покраснел (1/1) |
| `node scripts/mutation-gate.mjs --id=partial-group-shows-noop-toast` | покраснел (1/1) |
| `node demo/golden/run.mjs --mode=capture --scenario=device-icon-state-table-light` (diff меняет рендер: `demo/golden/matrix.mjs` правит уже забазленный сценарий) | **`different`** — см. находку H1 |
| `node demo/golden/run.mjs --mode=capture --scenario=device-icon-state-table-dark` | **`different`** — см. находку H1 |

Полный `npm run golden:verify` (все ~40 сценариев) не гонял: `policy.mjs`
требует полный прогон за один вызов (нет `--scenario` в verify-режиме), а два
единственных сценария, которые правит diff, уже проверены точечно в
diagnostic-`capture`-режиме напрямую против закоммиченных baseline-файлов —
остальные 38 сценариев diff не касается ни по фикстурам, ни по коду рендера.
Полный прогон — предрелизная обязанность (§8), не гейт этого ревью.

Не гонял и не было необходимости: `python -m pytest tests_backend` (diff не
трогает `custom_components/**/*.py`), performance-профили (в AC не названы,
чувствительный к перфу код не тронут — own-availability добавляет только
`O(e)`-проход по уже построенному `d.entities`).

## Находки

### H1 (High, в скоупе) — golden-эталон `device-icon-state-table-{light,dark}` сломан этим же diff'ом, приёмки baseline нет

`demo/golden/matrix.mjs` в этом diff'е меняет уже забазленный сценарий
`device-icon-state-table-{light,dark}`: маркеру `golden-left-linkquality`
добавлен `tap_action: 'toggle', controls: ['light.golden_light_three']`, а
`light.golden_light_three` переведён в `state: 'unavailable'`. Это ровно та
матрица AC1/AC6 из ТЗ — доказательный сценарий, — но правка меняет визуальный
результат уже принятого эталона, а сам эталон (`demo/golden/baselines/
device-icon-state-table-{light,dark}.png`) в этом diff'е не тронут и не
переприниимался.

Воспроизведение (сборка — `npm run build && cp dist/houseplan-card.js
demo/srv/assets/houseplan-card.js` на HEAD `f18b5b4`):

```
$ node demo/golden/run.mjs --mode=capture --scenario=device-icon-state-table-light
different         device-icon-state-table-light
```
`artifacts/golden/golden-report.json`: `status: "different"`, `diffRatio:
0.0013937744740160616` при пороге `maxDiffRatio: 0.0005`, `maxObservedDelta:
221` при пороге `maxChannelDelta: 10`.

```
$ node demo/golden/run.mjs --mode=capture --scenario=device-icon-state-table-dark
different         device-icon-state-table-dark
```
`diffRatio: 0.0014678027885700283`, `maxObservedDelta: 221` — тот же перебор
порога.

Последствия:
- job `golden` в `.github/workflows/validate.yml` идёт на **каждый** push в
  `dev` без путевых фильтров (`needs.reuse.outputs.golden != 'true'`, а
  `demo/golden/matrix.mjs` входит в отпечаток `reuse`, значит кэш не
  переиспользуется) и уже существующий baseline есть → шаг вызывает
  `npm run golden:verify`, который упадёт на этом же расхождении. Слияние
  этого коммита в `dev` красит обязательный job тем же классом, что описан в
  контексте задачи для #230/#234, только для `golden`, а не `docs`.
- `docs/TESTING.md` в этом же коммите утверждает доказательство AC6 как
  `golden: device-icon-state-table light/dark` — на деле этот golden сейчас
  красный, то есть AC6 (визуальный контракт View/kiosk/Static/preview один и
  тот же, без сдвига layout) не доказан визуально, только конфигурационно
  (`test/golden-matrix.test.mjs` проверяет только структуру сценария, не
  пиксели — сам тест это подтверждает, `npm test` зелёный именно поэтому).
- Локальный гейт перед выходом из «В разработке» (PROCESS.md §8) явно требует
  `golden:verify`, «если менялся визуал» — здесь менялся по определению (сам
  diff это и добавляет), но команда отсутствует в хендофф-комментарии автора
  среди прогнанных гейтов.

Это не претензия к корректности самого расчёта доступности — юнит-матрица
(`test/device-presentation.test.mjs`) и её мутанты подтверждают, что новое
поведение соответствует ТЗ. Дефект в поставке: изменение уже принятого
эталона без сопутствующей приёмки нового, что ломает обязательный CI-гейт на
`dev`.

**Как чинить, не задевая процесс:** эталон нельзя просто перезаписать локально
(§3.13, §12: «принятие golden-эталонов ради зелёного CI» запрещено) — нужен
полноценный `npm run golden:accept -- --reviewed` по прогону `golden` job на
полном Linux CI-артефакте той же ветки, аналогично тому, как коммит `f18b5b4`
принял provenance скриншотов документации по прогону
`32617490601`. До этого коммита — issue не может уйти дальше «В разработке».

Блокирует. Возврат автору.

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

- **AC1/AC2 (матрица §6.1, разделение фактов).** `controllerAvailability()` в
  `src/device-presentation.ts:218-234` читает только `d.entities`, живое
  состояние — не пустая строка, не `unknown`, не `unavailable`; virtual-девайс
  всегда `available`. Применяется только когда `sources.sourceKind ===
  'controls'`, оставляя `combined.status` (working/alarm) нетронутым. Новый
  тест `issue 251 separates controller availability from controlled target
  status` (`test/device-presentation.test.mjs`) прогоняет ровно матрицу из
  ТЗ: battery/LQI живые + target unavailable → available+neutral; target `on`
  → working при доступном контроллере; все own diagnostics unavailable + target
  `on` → `unavail` имеет приоритет над working; `live_states:false` → нейтраль;
  event-only own → unavailable; virtual controller → available; критический
  alarm own-сущности сохраняет приоритет (`status: 'alarm'`, `availability:
  'available'`). Мутанты `controller-availability-follows-target` и
  `controller-diagnostics-do-not-prove-online` покраснели, как обязаны.
- **AC3/AC4 (тост при полностью недоступной группе, единственная/множественная
  цель, mixed secure/unsupported).** `unavailableToggleTargetNames()`
  (`src/device-toggle.ts:769-796`) фильтрует по `kind==='group'` +
  `noneReason==='configured-targets-missing'`, называет только
  `missing`/`ha-disabled`/`unavailable`, глушится при любом `unsupported` в
  пропусках, не называет `secure`. Юнит `issue 251 classifies only
  unavailable configured groups...` покрывает singular/plural/partial/exact
  binding/mixed-secure/mixed-unsupported — все ветки ТЗ §7.1. Прод-бандл
  smoke (`smoke_controls.mjs`) подтверждает: нет `callService`/`callWS`, нет
  press feedback (`_devicePressAnimations.size === 0`), нет открытия
  confirm/info card, точный текст тоста для singular и plural. Мутант
  `unavailable-toggle-stays-silent` покраснел.
- **AC5 (confirm race).** `houseplan-card.ts:4972-4977`: перед сравнением
  target-set повторно резолвит intent и, если `!toggleOperation(current)` и
  `_showUnavailableToggleTargets(current)` вернул `true` (т.е. это именно наш
  no-op класс), показывает unavailable-тост и не идёт дальше; иначе (secure,
  unsupported, обычная смена состава) — прежний `toast.tap_target_changed`,
  поведение не регрессирует (прочитано и сверено построчно со старой веткой,
  smoke `confirmRaceNoService`/`confirmRaceUnavailableToast` — `true`).
- **AC7 (config/schema/model не меняются).** В diff'е нет файлов схемы/модели
  (`src/types.ts`, backend, персистентный формат конфигурации); существующие
  config-тесты (входят в те же 1117) зелёные без изменений в них.
- **AC8 (документация и i18n).** `docs/ARCHITECTURE.md`, `docs/USER-GUIDE.md`
  и `.ru.md`, `docs/TESTING.md`, оба `docs/CHANGELOG*.md` — правки в том же
  коммите `b984f16` (`User-Visible: yes`), формулировки соответствуют
  реализации (сверено построчно). `test/i18n.test.mjs` подтверждает точное
  совпадение EN/RU текста тоста и наличие обоих ключей в `cardSource`.
  `check-docs.mjs --external` зелёный.
- **AC9 (implementation loop, bundle parity)** — см. таблицу гейтов выше,
  все три копии бандла идентичны байт в байт.
- **Трейлеры/провенанс.** Все три продуктовых коммита несут `Issue: #251` и
  ровно один `User-Visible:`; `b984f16` — `yes` с правками в обоих changelog в
  том же коммите; `process-gate.mjs --issues` зелёный.
- **Скриншоты документации.** `f18b5b4` ссылается на прогон `Docs screenshots
  run: 32617490601` и обновляет `docs/images/*` + `screenshots.json`;
  `check-docs.mjs` (без `--external`, полная проверка provenance) зелёный —
  отпечаток соответствует текущему `src/**`.

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

- Полный `npm run golden:verify` (все ~40 сценариев) и полный `npm run
  golden:capture` для остальных сценариев — не задеты ни фикстурой, ни кодом
  рендера этого diff'а; это предрелизная, а не ревью-обязанность (§8).
- `python -m pytest tests_backend` — diff не трогает `custom_components/**/*.py`.
- performance-профили — не названы в AC, presentation-путь остаётся `O(e)` по
  уже построенному `d.entities` (проверено чтением, не исполнением).
- Реальную живую HA-инсталляцию/ручной клик в браузере вне smoke-гарнеса —
  ручного тестирования в цикле нет по правилам процесса; вопрос «работает ли»
  закрыт сочетанием юнит-матрицы, мутантов и production-bundle smoke.
- Провенанс CI-прогона `32617490601` (сам workflow run на GitHub) — доверился
  структурной проверке `check-docs.mjs`, содержимое run'а не открывал.