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

# CODE-REVIEW-318-r1

- Issue: [#318](https://github.com/Matysh/houseplan-card/issues/318) — «Маркер switch не меняет отрисовку при смене состояния сущности»
- Заход: r1 (код-ревью), блокирующих циклов израсходовано 0/4
- SHA материала ревью: `72913fee84db87df0871940bea8232aa183e8f61` (сверено `git rev-parse HEAD` непосредственно перед вердиктом)
- Ветка: `issue/318-switch-render-state`
- Трек: полный (ТЗ `docs/specs/318-empty-controller-roster.md`, ревью ТЗ зелёное — `docs/reviews/SPEC-REVIEW-318-r1.md`, SHA `1242a3b1`)
- Ребейз перед ревью: конвейер докатил ветку `7d11cac7 → 72913fee` (+1 коммит `dev`). Это другой код (§7.2), поэтому разбор ниже полный, не по дельте.

## 1. Скоуп

Разобрано (см. владельческое решение в комментариях issue): активный физический
`device:` binding с пустым собственным entity roster (0 строк entity registry)
должен считаться `available`, а его working/neutral — следовать `controls`.
Ранее пустой roster безусловно давал `unavailable`, поэтому маркер выглядел
постоянно недоступным независимо от состояния управляемой цели. Контракт #251
(доступность контроллера ≠ доступность цели) для непустого roster без живых
состояний не меняется.

Диапазон материала: `git log --oneline origin/dev..HEAD` (3 коммита) и
`git diff origin/dev...HEAD` (43 файла, из них продуктовый код — только
`src/device-presentation.ts`, остальное — тесты/смоки/mutation-gate/документация/
generated bundle-копии).

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

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | PASS, без вывода |
| Unit | `npm test` | PASS: 1473 passed, 0 failed, 1 skipped, 1474 всего |
| Build | `npm run build` | PASS |
| Копии бандла | `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` + `npm run bundle:sync` | PASS, `git status` после sync чист — все три дерева (`dist`, `custom_components/.../frontend`, `demo/srv/assets`) уже синхронизированы в коммите |
| Бюджет бандла | `npm run bundle:budget` | PASS: initial View 256091 B / 282000 B (запас 25909 B) — совпадает с числом хендоффа |
| Docs fingerprint | `node scripts/check-docs.mjs` | PASS: 7 files, 10 external links (диф трогает `src/**` → гейт обязателен) |
| Новый `any` | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | PASS: 10 добавленных строк в 1 файле, новых `any` нет |
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | НЕОПРЕДЕЛЁННОСТЬ: 1 файл `src/**`, 0 связанных символов на изменённых строках — инструмент не называет ни одного смока, решение по AC остаётся за ревьюером |
| Смок из AC5 | `node demo/smoke_wireless_controller_parity.mjs` | PASS — все 16 полей `true`, включая 5 новых полей `entityless*` (empty roster on/off/unavailable, parity plan/preview) |
| Mutation `entityless-active-controller-stays-available` (AC8, новый мутант) | `node scripts/mutation-gate.mjs --id=entityless-active-controller-stays-available` | PASS: чистый прогон green, мутант покраснел |
| Mutation `controller-availability-follows-target` (#251, регрессия) | `node scripts/mutation-gate.mjs --id=controller-availability-follows-target` | PASS, мутант покраснел |
| Mutation `controller-diagnostics-do-not-prove-online` (#251, регрессия) | `node scripts/mutation-gate.mjs --id=controller-diagnostics-do-not-prove-online` | PASS, мутант покраснел |
| Mutation `wireless-controller-loses-filtered-target-role` (#274, регрессия) | `node scripts/mutation-gate.mjs --id=wireless-controller-loses-filtered-target-role` | PASS, мутант покраснел |
| Mutation `wireless-controller-preview-drops-sibling-markers` (#274, регрессия) | `node scripts/mutation-gate.mjs --id=wireless-controller-preview-drops-sibling-markers` | PASS, мутант покраснел |
| Process gate | `node scripts/process-gate.mjs` | PASS: диапазон `origin/dev..HEAD`, 3 коммита, 0 предупреждений |

### Чего не прогонял и почему

- **`golden:verify`** — не прогонял. Диф действительно меняет видимый результат
  маркера, но только для одной узкой конфигурации: active `device:` binding с
  `d.entities.length === 0`. Проверено чтением `demo/golden/matrix.mjs` —
  ни один существующий golden-маркер с `binding: 'device:*'` не имеет пустого
  списка сущностей (все golden-устройства — реальные лампы/датчики с
  зарегистрированными entity rows), то есть изменённая ветвь
  `controllerAvailability()` не задействуется ни одним текущим golden-сценарием.
  Пересъёмка эталонов ради строки кода, которую они не исполняют, была бы
  «ради зелёного CI», что прямо запрещено. Решение согласуется с §15 ТЗ:
  новый golden baseline не требуется, если семантический smoke зелёный и
  существующая visual-матрица не задета.
- **`smoke_device_preview_parity.mjs`** — рассмотрен и не прогонялся. Слабая
  связь по имени («preview parity»), но по чтению кода он проверяет только
  собственный (`owned_light`/S09) источник лица для живого света, не
  `controllerAvailability()`/сценарий S03/S15; этот путь не тронут диффом.
- **`smoke_static_icon.mjs`, `smoke_disabled_device.mjs`, `smoke_device_inbox.mjs`,
  `smoke_new_device.mjs`, `smoke_device_icon_*`** — рассмотрены по списку
  `ls demo/smoke_*.mjs | grep -i device` (196 смоков всего), отклонены: static
  face (F08), lifecycle ha_disabled/orphaned (L02/L03/L06) и инвентарь новых
  устройств не проходят через изменённую ветку (правится только `active`+пустой
  roster).
- **`python -m pytest tests_backend`** — не тронут `custom_components/**/*.py`
  (см. diff stat), не запускал.
- **Performance-профили** — не названы в AC, диф — одна булева проверка `O(1)`
  на уже собранном marker, не запускал.
- **Полный набор `demo/smoke_*.mjs` (196 файлов)** — не запускал: `smoke-select`
  не нашёл ни одной доказанной связи, задача не задевает «всё», полный прогон —
  предрелизный гейт, а не гейт ревью (§8).

## 3. Разбор кода

`src/device-presentation.ts:208-225`, `controllerAvailability()`:

```ts
const ownEntities = d.entities || [];
const activeEntitylessDevice = ownEntities.length === 0
  && (d.bindingKind === 'device' || d.marker?.binding?.startsWith('device:'))
  && d.bindingStatus?.kind === 'active';
if (activeEntitylessDevice) return 'available';
const live = ownEntities.some((eid) => { ... });
```

Проверено чтением и трассировкой по продуктовому коду, не только по тесту:

- `virtual`-ветка (строка 211) идёт раньше нового предиката и не меняется —
  виртуальный контроллер с пустым roster по-прежнему `available` тем же путём,
  что и раньше (проверено тестом `virtual` в новом unit-кейсе).
- Предикат требует одновременно (а) пустой `d.entities`, (б) `device:` binding,
  (в) `bindingStatus.kind === 'active'`. `src/ha-binding-status.ts:14-17`
  показывает, что `kind` может быть только `active | ha_disabled | orphaned |
  unverified` — ни одно другое значение не проходит строгое сравнение `===
  'active'`, поэтому `ha_disabled`/`orphaned`/`unverified` не получают fallback
  (соответствует AC4, матрице §6.2 ТЗ и строкам L02/L03/L06 таблицы решений).
- `entity:`-binding никогда не удовлетворяет `d.bindingKind === 'device' ||
  d.marker?.binding?.startsWith('device:')`, поэтому маркер с точной `entity:`
  привязкой и пустым `d.entities` (аномальный случай) не получает fallback и
  остаётся на старом пути `live = ownEntities.some(...)` → `unavailable`.
  Негативный тест на это есть (`entityBinding` в новом unit-кейсе).
- Реальность предиката в продакшн-пути подтверждена в `src/devices.ts:1198`:
  `entIds = bindingStatus.kind === 'active' ? bindingStatus.enabledEntityIds :
  []` — то есть `d.entities === []` при `active` — это не выдумка теста, а
  реальный результат сборки ростера для `device:` маркера без entity rows
  (`src/ha-binding-status.ts:434-444`, ветка `enabledEntityIds.length === 0`).
- `controllerAvailability()` вызывается независимо от `sourceKind`
  (`src/device-presentation.ts:616-638`, `controllerFace = sourceKind ===
  'controls' || (configuredController && ...)`), поэтому fallback работает и в
  сценарии «все controls отфильтрованы рантаймом» (`sourceKind: 'none'`,
  AC2) — не только в прямом «target on/off».
- `working/neutral` не синтезируется отдельно: policy получает
  `controllerAvailability: 'available'` и `sourceVisual` из уже существующего
  `combineVisualSamples(sources.samples)`, который считается из
  `resolvePresentationSources()` — та же функция, что строила поведение до
  фикса. Значит фикс не создаёт новый источник статуса, а только снимает
  ложный приоритет `unavail` — ровно риск «Target unavailable станет ложным
  working», закрытый по таблице рисков ТЗ §13, подтверждён unit-тестом
  (`h.states[...] = 'unavailable'` / `delete h.states[...]` → `neutral`, не
  `working`).

**Один источник числа.** Диф не вводит и не дублирует ни одной пользовательской
величины (значение, площадь, подпись): решается только булева проекция
availability/status одного и того же уже вычисленного `combined`-агрегата.
Правило `test/single-source-numbers.test.mjs` диф не касается и не должно.

## 4. Разбор по AC

| AC | Статус | Доказательство |
|---|---|---|
| AC1 | Выполнен | `test/device-presentation.test.mjs` — «issue 318 keeps an active entityless physical controller available», ветки on/off; прогнан, зелёный; mutation `entityless-active-controller-stays-available` подтверждает, что тест умеет падать |
| AC2 | Выполнен | тот же unit-кейс: target `unavailable`, target `missing` (entity удалена из `hass.states`), runtime-filtered `controls: []` (`sourceKind: 'none'`) — все три дают `available`+`neutral`, не `working`/`unavail` |
| AC3 | Выполнен | тот же unit-кейс, ветка `provenOffline`: непустой roster (`event.*` без live state) при `target on` даёт `unavailable`; #251-тест (`issue 251 separates controller availability...`) не изменён и зелёный — mutation `controller-availability-follows-target`/`controller-diagnostics-do-not-prove-online` подтверждают, что регрессия была бы поймана |
| AC4 | Выполнен | unit-кейс проверяет `entity:`-binding и `orphaned` явно (обе — `unavailable`); `ha_disabled`/`user_hidden`/alarm/static/live_states-off не тронуты кодом (не в изменённой ветке) и покрыты существующими policy-тестами, прошедшими в `npm test` |
| AC5 | Выполнен | `demo/smoke_wireless_controller_parity.mjs`, новые проверки `entitylessOnIsAvailableWorking`, `entitylessPreviewMatchesOnPlan`, `entitylessOffIsAvailableNeutralEverywhere`, `entitylessUnavailableTargetIsAvailableNeutralEverywhere` — все `true` при запуске |
| AC6 | Выполнен частично автотестом, частично чтением | `resolveDevicePresentation()` — общий resolver для plan/preview/hosted Static (архитектурный инвариант, не специфичный для этой задачи); прямого hosted-Static-смока нет, но shared-resolver unit + `entitylessPreviewMatchesOnPlan` в browser-смоке покрывают ту же функцию, которую использует Static-путь. Light/dark и layout не проверялись экраном — **проверено чтением**: диф не трогает CSS/классы face, только availability boolean |
| AC7 | Выполнен | diff-аудит: `git diff origin/dev...HEAD -- src/` показывает изменения только в `device-presentation.ts`; конфиг/schema/model/backend не тронуты вовсе (нет файлов `custom_components/**/*.py`, `*.json` схем в diff) |
| AC8 | Выполнен | 5 команд `mutation-gate.mjs` выше, все «мутант покраснел» |
| AC9 | Выполнен | таблица гейтов раздела 2; числа `bundle:budget` совпадают с хендоффом |

## 5. Документация и трейлеры

- `docs/DEVICE-PRESENTATION.md` — S05 переформулирован под «непустой roster без
  live», добавлена строка S15 под новый fallback; таблица/фикстура/тест
  синхронизированы автоматическим тестом «device presentation decision
  document, fixture and mutation registry stay exact» (прогнан в составе
  `npm test`, зелёный).
- `docs/ARCHITECTURE.md`, `docs/USER-GUIDE.md`, `docs/USER-GUIDE.ru.md`,
  `docs/TESTING.md` — обновлены консистентно с новым контрактом; терминология
  RU/EN совпадает («выключатель», «непрозрачным», «жёлтая/нейтральная
  подложка» — уже принятые термины USER-GUIDE, не изобретены заново).
- Оба changelog обновлены в том же коммите `72913fee` (`fix: show entityless
  active controllers`, `User-Visible: yes`), трейлер `Issue: #318` на всех трёх
  коммитах диапазона.
- `docs/specs/README.md` получил строку для #318, но она вставлена перед #294,
  а не после — таблица в этом разделе иначе идёт по возрастанию номера issue.
  **Low, не вне скоупа, не блокирует**: чисто косметическая перестановка строки
  индекса, не влияет ни на один AC и не читается инструментом. Снимаю с записью,
  а не отправляю на правку — цена цикла ревью выше цены одной переставленной
  строки таблицы.
- Скриншоты `docs/images/*.png` + `docs/images/screenshots.json` пересобраны
  командой `npm run build && node demo/docs/capture.mjs`, что совпадает с
  явной инструкцией `check-docs.mjs` («run npm run build && node
  demo/docs/capture.mjs») и полем `command` в самом манифесте; фингерпринт
  обновлён и `check-docs.mjs` зелёный. Отдельная строгая приёмка
  `docs:accept -- --reviewed --from=<CI-артефакт>` — гейт релизного/`golden`-типа
  для официального байтового эталона, а не условие этого код-ревью.

## 6. Продуктовое рассуждение

Сценарий и контракт полностью соответствуют J1/J2 из `docs/SCOPE.md`
(«что происходит сейчас», спатиальная тревога/статус без ложных сигналов).
Решение владельца в комментариях issue («активный физический device-binding с
пустым roster считается доступным») реализовано буквально, включая явно
исключённые владельцем случаи (непустой roster без живых состояний остаётся
`unavailable`). Изменение не расширяет и не сужает скоуп: Toggle, service
payload, Glow, room fill, badge — не тронуты, что подтверждено diff-аудитом.
Жёлтых оснований (AC выполнены, но сценарий не решён или соседний ухудшен) не
нашёл.

## 7. Находки

Нет находок High или Medium. Один Low (порядок строки в `docs/specs/README.md`)
снят с записью в разделе 5.

## 8. Итог

Все 9 AC доказаны автотестом с подтверждённой способностью падать (mutation
gate) либо browser-смоком, один пункт (AC6, hosted Static визуально) закрыт
чтением кода при отсутствии прямого смока — задокументировано явно. Гейты
typecheck/test/build/bundle-sync/bundle-budget/check-docs/no-new-any/
process-gate зелёные на SHA `72913fee`. Регрессионные mutation-guards #251 и
#274 подтверждены неизменными. Вердикт: зелёный.