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

# Code review #219 — r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/219
- **Spec:** `docs/specs/219-lock-orange-palette.md`, зелёное `SPEC-REVIEW-219-r2.md`
- **Reviewed branch:** `issue/219-lock-orange-palette`
- **Reviewed range:** `origin/dev..HEAD` = `28d6b9c`…`84fa434` (ТЗ и ревью ТЗ,
  уже приняты на этапе spec) → `bc75e00` (единственный продуктовый коммит)
- **Base:** `origin/dev` at `b56e122`
- **Reviewer:** Claude, независимая сессия без контекста реализации

## Вердикт

**Зелёный · цикл r1/4 · High: 0 · Medium: 0.**

Единственный продуктовый коммит `bc75e00` заменяет старую black/amber
lock-палитру на red/green и унифицирует foreground всех цветных подложек
(`on`/`open`) по теме. Изменение точечное и декларативное — только
`src/styles.ts` — и покрыто исполняемыми contract-тестом и browser-smoke,
которые я лично прогнал, а contract-тест дополнительно проверил на
способность падать. Все 7 AC закрыты либо автотестом, либо чтением кода с
явной пометкой. Одна Low-находка снята без правки.

## Скоуп

Продуктовый файл — `src/styles.ts`:

- `.oplock.locked`/`.oplock.unlocked` (compact opening lock badge) и
  `.dev.lock-locked`/`.dev.lock-unlocked` (обычный marker) получили core/stroke
  `#66D17A`/`#F0410C` вместо `light-dark(#000,#252525)`/`#F0A00C`; foreground
  переведён на общий паттерн `light-dark(#fff,#252525)` + explicit
  `.theme-light`/`.theme-dark` overrides, как уже сделано у `.dev.on`;
- `.dev.open` получил тот же foreground-паттерн вместо постоянного `#4a2800`,
  плюс явные `.dev.theme-light.open`/`.dev.theme-dark.open`;
- ни geometry, ни stroke-ratio, ни selector order, ни alarm/hover/focus/
  selected/unavailable/virtual/press-правила не тронуты — весь остальной файл
  вне двух изменённых блоков идентичен `dev`.

Сопутствующие изменения: `test/device-marker-polish-contract.test.mjs` (новый
contract-тест issue 219), `demo/smoke_device_icon_design.mjs` (новый
`openingLockPaletteMatches`/`orangeGlyphsFollowTheme`/
`darkLockUsesGreenCoreAndDarkGlyph`, обновлённый reference override),
`demo/capture_device_icon_reference.mjs` + `demo/srv/reference/device-icons/README.md`
(runtime-override red/green поверх byte-identical designer SVG),
`demo/golden/matrix.mjs` + `test/golden-matrix.test.mjs` (сцена
`device-icon-state-table-*` теперь показывает `open` рядом с `on` и обоими
lock-состояниями), `docs/TESTING.md`, `docs/USER-GUIDE.md` +
`docs/USER-GUIDE.ru.md` (раздел «Замок» и таблица постоянных статусов —
заменяемый black/amber текст убран), оба changelog, `docs/specs/README.md`,
`docs/images/screenshots.json` (обновлён только `sourceFingerprint`, все 10
`imageSha256` без изменений), три сгенерированные копии бандла.

Ровно один продуктовый коммит `bc75e00`, трейлеры `Issue: #219` /
`User-Visible: yes` на месте, оба changelog в том же коммите, документация
(USER-GUIDE, TESTING) в том же коммите, что и поведение. Ветка
`issue/219-lock-orange-palette` соответствует правилу именования.

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

| Гейт | Результат |
|---|---|
| `npx tsc --noEmit` | pass |
| `npm test` | **962/962 pass**, 0 skipped в этом окружении (`npm run inventory` подтверждает канонический счётчик 962 Node unit); хендофф указывает «961 passed, 1 skipped» — расхождение объяснимо `test/process-gate.test.mjs`, где 1 подтест условно `t.skip('нужен исполняемый stub gh')`/«git недоступен» в зависимости от окружения автора, файл не затронут этим диффом |
| `npm run build` + сверка трёх копий бандла | pass, все три `sha256` = `9c7df844ce825c0d56cfb65e82a0fbbb98620428d5aa5806abec0c40b1d9b1a2`, совпадает с хендоффом |
| `node --test test/device-marker-polish-contract.test.mjs` (targeted contract, назван в AC1/AC2/AC3) | pass (8/8) |
| Временный откат `--oplock-core-bg: #66D17A` → `#000` и повтор того же теста | **тест `issue 219 gives locks red-open green-closed…` красный** — дисциплина «тест умеет падать» подтверждена мной, а не только на слово автора |
| `node --test test/golden-matrix.test.mjs` | pass (26/26), включая новую проверку `deviceClassOverrides['golden-right-linkquality'] === ['open']` |
| `node demo/smoke_device_icon_design.mjs` (назван в AC1/AC3, хендоффе) | pass, все поля true, включая новые `openingLockPaletteMatches`, `orangeGlyphsFollowTheme`, `darkLockUsesGreenCoreAndDarkGlyph` |
| `node demo/smoke_device_preview_parity.mjs` (поверхность AC5 — Device preview) | pass |
| `node demo/smoke_static_icon.mjs` (поверхность AC5 — static space card) | pass |
| `node demo/smoke_lock_action.mjs` (смежная поверхность — lock action не должен был измениться) | pass |
| `node demo/smoke_lock_invariant.mjs` (смежная поверхность — lock invariant/SCOPE.md guard) | pass |
| `node scripts/check-docs.mjs --external` (AC7) | pass, 7 файлов, 10 внешних ссылок |
| `npm run golden:verify` | `device-icon-state-table-light`/`-dark` — **different**, ожидаемо (см. ниже); плюс 3 сцены, не названные в ТЗ — разобраны отдельно |

### Разбор `golden:verify`: почему «different» больше, чем в ТЗ

ТЗ (§10, §15, §16) называет ревьюеру только `device-icon-state-table-light`/
`-dark` как ожидаемую визуальную дельту. Фактический прогон показал ещё три
«different»: `isometric-large-warm-remount-dark`, `large-house-zoom-250-dark`,
`large-house-warm-remount-dark` (у всех пяти одинаковый `maxObservedDelta: 218`
— общий признак одного и того же цветового изменения).

Я не принял это на слово и сравнил с чистым `origin/dev` в отдельном
`git worktree` (та же сборка, тот же `golden:verify`): на `dev` эти три сцены
проходят как `passed`, а `device-icon-state-table-*` уже были `different`/
`missing-baseline` **до** этой задачи — предсуществующий дрейф baseline
(`GOLDEN_MATRIX_VERSION` 32→33 внесён более ранним `39456dc`, эталоны не
приняты), не имеющий отношения к #219. Причина трёх новых «different» —
`demo/fixtures/large-house.mjs` строка 129 циклически включает
`['lock', 'locked']` в синтетический набор устройств, которым пользуются
`perf-floor-1`/`perf-floor-2`; палитра lock-marker в этих сценах меняется тем
же общим CSS, что и ожидалось для shared renderer (AC5). Это не регрессия и
не «постороннее» изменение из риска в §13 — только более широкий, чем
задокументировано, набор golden-сцен, которым в предрелизном гейте потребуется
`npm run golden:accept -- --reviewed` вместе с state-table.

`device-text-shell-long-light/-dark` — `missing-baseline` независимо от этой
задачи (тот же предсуществующий дрейф `dev`, issue #217, вне скоупа #219).

### Не прогонялось, и почему

- **Полный набор из 155 browser-smoke.** Задача — точечное изменение общих CSS
  state-токенов; прогнаны названные в AC/хендоффе плюс смежные поверхности
  (device preview parity, static card, lock action, lock invariant). Остальные
  150 смоков не относятся к lock/orange-подложке (проёмы без замков, Glow,
  wall geometry, UI-хром и т. д.).
- **`python -m pytest tests_backend`.** Ни один файл
  `custom_components/**/*.py` не тронут.
- **Performance-профили.** Не названы в AC; §12 ТЗ явно фиксирует «CSS
  variables и fixture/test metadata», без нового DOM/JS в render path.

## Проверка AC1–AC7

| AC | Метод по ТЗ | Статус | Как закрыт |
|---|---|---|---|
| AC1 | contract unit + light/dark visual artifact | ✅ | `device-marker-polish-contract.test.mjs` проверяет `.oplock.locked/unlocked` core/stroke/fg по обеим темам; artifact — `smoke_device_icon_design.mjs` `openingLockPaletteMatches` (реальный `.oplock-core`/`.oplock-shell` computed style против reference с runtime-override) |
| AC2 | presentation/unit source contract + shared-renderer test + golden state-table | ✅ | Тот же contract-тест проверяет `.dev.lock-locked/unlocked` идентичными hex теми же селекторами, что и `.oplock.*`; `houseplan-card.ts`/`hp-device-preview.ts`/`space-card.ts` подтверждены источником как использующие общий `cardStyles`; golden `device-icon-state-table-*` включает оба lock-состояния |
| AC3 | contract unit + state-table light/dark golden с одновременно видимыми `on`/`open` | ✅ | Contract-тест проверяет `.dev.open` не содержит `#4a2800` и использует `light-dark(#fff,#252525)`; smoke `orangeGlyphsFollowTheme` подтверждает `rgb(255,255,255)`/`rgb(37,37,37)` для `on` и `open` в обеих темах на реальном рендере; golden-сцена теперь содержит `open` (`golden-right-linkquality`) рядом с `on` |
| AC4 | существующие device presentation/polish/pointer tests + source review | ✅ (чтением) | Diff `src/styles.ts` ограничен двумя блоками (`oplock.locked/unlocked`, `dev.open/lock-locked/lock-unlocked`); alarm/hover/focus/selected/unavailable/virtual/press/pulse селекторы вне диффа побайтово идентичны `dev`; полный regression (962/962) не покраснел |
| AC5 | shared-renderer unit + golden matrix | ✅ | Contract-тест проверяет, что `houseplan-card.ts`, `hp-device-preview.ts`, `space-card.ts` импортируют `cardStyles`; smoke `smoke_device_preview_parity.mjs`/`smoke_static_icon.mjs` подтверждают parity на реальных DOM для plan/preview/static; golden `device-icon-state-table-{light,dark}` — одна fixture, обе темы |
| AC6 | diff review, typecheck, полный unit и build | ✅ | Diff не касается config/backend/i18n (нет файлов вне `src/styles.ts`, тестов, demo, docs, generated); typecheck/unit/build зелёные |
| AC7 | diff, hash comparison, `check-docs` | ✅ | Оба changelog, `docs/TESTING.md`, `docs/USER-GUIDE.md`+`.ru.md` (раздел «Замок», таблица «Жёлтая подложка»/«Чёрный значок замка» переписаны на red/green) — все в `bc75e00`; три bundle sha256 идентичны; `check-docs.mjs --external` pass; `sourceFingerprint` в `docs/images/screenshots.json` обновлён и совпадает с фактическим build fingerprint, все 10 `imageSha256` не изменились |

## Находки

### Low-1 — AC7/§16 не называют все golden-сцены, которые изменит эта правка

ТЗ и хендофф называют только `device-icon-state-table-light`/`-dark` как
ожидаемую golden-дельту. Фактически общий CSS задевает ещё три сцены
(`isometric-large-warm-remount-dark`, `large-house-zoom-250-dark`,
`large-house-warm-remount-dark`) через lock-устройства в синтетической `large`
fixture (см. разбор выше) — я подтвердил это сравнением с чистым `dev`, а не
предположением. Риск §13 «Golden покажет ожидаемую дельту вместе с
посторонней» ровно это и предвидел, возлагая проверку на ревьюера — что я и
сделал.

**Вердикт:** снимается без правки. Не блокирует AC7 (диапазон изменяемых
сцен явно не был ограничен списком) и не создаёт риска для релиза — я
проверил происхождение всех пяти «different» и подтвердил, что это одно и то
же корректное цветовое изменение, а не регрессия. Фиксирую для предрелизного
гейта: `npm run golden:accept -- --reviewed` должен принять **все пять**
сцен разом (`device-icon-state-table-{light,dark}` +
`isometric-large-warm-remount-dark` + `large-house-zoom-250-dark` +
`large-house-warm-remount-dark`), не только две названные в ТЗ.
`device-text-shell-long-{light,dark}` (`missing-baseline`) — предсуществующий
дрейф `dev` вне скоупа #219, не путать с этой правкой при приёмке.

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

- `.oplock.locked`/`.oplock.unlocked` и `.dev.lock-locked`/`.dev.lock-unlocked`
  используют идентичные hex (`#66D17A`/`#F0410C`) и идентичный
  `light-dark`+explicit-override паттерн foreground — одна lock-сущность даёт
  одинаковый цвет как compact badge, так и обычный marker (риск §13 «Compact
  opening badge и device marker разойдутся» закрыт одним contract-тестом на
  обе пары).
- Исходные designer SVG (`demo/srv/reference/device-icons/**`) остаются
  byte-identical; runtime-override в `capture_device_icon_reference.mjs`
  подтверждён построчным чтением фактических `fill="black"`/`fill="#252525"`/
  `fill="#1DC21D"`/`fill="#F0A00C"` — каждое встречается в SVG ровно один раз,
  `replaceAll` не задевает ничего постороннего.
- `--oplock-stroke-ratio: .025`/`--device-shell-stroke-ratio: .025` (dark
  theme) и вся геометрия/MDI-path/hit-area не изменены — совпадает с
  «не входит в задачу» §7 ТЗ.
- `mdi:lock`/`mdi:lock-open-variant` classification не менялась (regex-проверка
  в contract-тесте против `houseplan-card.ts`).
- `docs/USER-GUIDE.md`/`.ru.md`: заменяемые формулировки («чёрный/тёмный
  замок», «жёлтая подложка» применительно к lock, «Чёрный значок замка»)
  убраны полностью, включая таблицу постоянных статусов и `lock.*` в общей
  таблице поведений — сверено построчно, не на слово хендоффа.
- Trailers, changelog RU/EN, `docs/specs/README.md` — все в одном продуктовом
  коммите, соответствуют PROCESS.md §7.1/§10.1.

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

- Визуальный итог обновлённых golden-сцен (baseline не принимается
  исполнителем/ревьюером по контракту — только `npm run golden:accept
  -- --reviewed` на полном Linux CI artifact перед бетой).
- Полный набор из 155 browser-smoke и `performance_smoke` — не относятся к
  этому точечному CSS-изменению; остаются обязательными на предрелизном
  гейте.
- Backend/HA harness — не затронут, ни один файл `custom_components/**/*.py`
  не изменён.
- Мобильный/touch путь отдельно не тестировал: правка ограничена CSS-цветом,
  не добавляет и не убирает pointer-modality селекторы (подтверждено чтением
  диффа — новых `:hover`/`[data-pointer-*]` правил нет).