# CODE-REVIEW-20-r1 - Issue: https://github.com/Matysh/houseplan-card/issues/20 - ТЗ: `docs/specs/020-glow-open-door-spill.md` (ревью ТЗ зелёное, `docs/reviews/SPEC-REVIEW-20-r1.md`, 2026-08-28) - Ветка: `issue/20-glow-open-door-spill` - SHA материала ревью: `f62926fbeb9e79e850eef54f01448bdf3aed5b68` (единственный коммит с продуктовым кодом; впереди него в ветке — `72e6939f` docs: review document, `3fa98a09` docs: actualize spec, оба до реализации и без изменений в `src/**`) - Заход: r1 · блокирующих циклов израсходовано 0/4 (это первый заход) ## Скоуп Дифф `origin/dev...HEAD`: `src/logic.ts`, `src/houseplan-card.ts`, `src/physical-geometry.ts`, `src/space-render.ts`, тесты (`test/logic.test.mjs`, `test/physical-geometry.test.mjs`, `test/golden-matrix.test.mjs`), `demo/smoke_glow.mjs`, `demo/golden/matrix.mjs`, `demo/fixtures/visual-matrix.mjs`, `docs/LIGHT.md`, `docs/ARCHITECTURE.md`, changelog RU/EN, плюс сгенерированные bundle-деревья и пересобранные скриншоты документации. Ровно один коммит класса A/B (`f62926fb`) с трейлерами `Issue: #20` / `User-Visible: yes`. Задача полного трека (не `small`): геометрия и горячий render/cache-путь. ## Как проверялось | Гейт | Команда | Результат | |---|---|---| | typecheck | `npx tsc --noEmit` | OK | | unit | `npm test` | 1503 тестов: 1502 passed, 1 skipped, 0 failed | | build + сверка копий | `npm run build && npm run bundle:sync` | OK; `dist/`, `custom_components/.../frontend`, `demo/srv/assets` идентичны, `git status` чист после sync | | bundle budget | `npm run bundle:budget` | initial View 271455 B gzip / бюджет 282000 B, запас 10545 B | | no-new-any | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | 111 добавленных строк в 4 файлах, новых `any` нет | | check-docs (diff трогает `src/**`) | `node scripts/check-docs.mjs` | OK: 7 файлов, 10 внешних ссылок | | smoke-select | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 10 прямых совпадений (список ниже) | | browser smokes (все 10 прямых совпадений) | `node demo/smoke_{registryless_opening,glow,opening_binding,linked_virtual_light,open_passage,opening_entity_search,opening_preview,partition_openings,plan_drawing_repairs,plan_snap_overlay}.mjs` | все 10 — OK | | golden | `npm run golden:verify` (полная матрица, 80 сцен) | 79 passed, 1 **different**: `lighting-opaque-glow-two-doorways-dark` — см. «Известный пробел» ниже | | invariants | не запускал | диф не меняет сохранённую геометрию/схему (см. обоснование ниже) | | backend pytest | не запускал | `custom_components/**/*.py` не тронут | | performance smoke | не запускал | AC9 сам называет доказательством exact-SHA CI performance smoke перед бетой, не код-ревью | **smoke-select, вывод целиком:** ``` Изменено файлов src/**: 4 · символов проекта на изменённых строках: 24 Прямое совпадение (10): smoke_registryless_opening.mjs (_openingAmt, _openingsR, _renderOpeningEntityAvailable, _renderPlanHass), smoke_glow.mjs (_cmToUnits, _openingsR, _pointInRoom), smoke_opening_binding.mjs (_openingAmt, _openingsR), smoke_linked_virtual_light.mjs (_renderPlanHass), smoke_open_passage.mjs (_openingsR), smoke_opening_entity_search.mjs (_openingsR), smoke_opening_preview.mjs (_openingsR), smoke_partition_openings.mjs (_openingsR), smoke_plan_drawing_repairs.mjs (_cmToUnits), smoke_plan_snap_overlay.mjs (_cmToUnits). Ничего не учтено как «широкий» символ (порог >40). ``` Прогнал все 10, а не только тематически близкие: инструкция прямо предупреждает, что тематическое сужение уже один раз пропустило регресс (#234), а здесь все 10 — прямые совпадения, не слабые связи. **Инварианты модели не прогонял.** Диф не меняет сохранённую геометрию, `layout`, `marker.space`, `open_spans` или ключи записи толщины — вырезы, которые теперь зависят от `amount`, вычисляются заново на каждый рендер из НЕ сохраняемого состояния HA и не пишутся обратно в конфиг (спека прямо это фиксирует: «Модель и сохранённый JSON не меняются»). Автор указал ту же причину в хендоффе. Согласен: инварианты отвечают на вопросы про персистентную геометрию, здесь её нет. ## Находки Блокирующих (High) находок нет. Находок уровня Medium в скоупе или вне скоупа нет. ### Low L1 — AC7 для контурной (не partition) стены доказан только чтением кода, не тестом `test/physical-geometry.test.mjs` получил новый тест именно для перегородки («partition body uses the same full, partial and closed light aperture» — `pointInOpaquePlanBody` проверен для full/half/closed на партиционном хосте). Для обычного проёма в контурной стене (не partition) аналогичного прямого теста «источник внутри закрыто-схлопнутого выреза подавлен» не добавлено — существующий `sourceInsideWallSuppressed` в `demo/smoke_glow.mjs` не изменился и проверяет источник внутри обычной стеновой массы, а не внутри именно закрытой (`amount<=0`) двери. Прочитал код и убеждён, что риск закрыт по конструкции, а не только по вере в автора: `_lightBarriers()` (`src/houseplan-card.ts:10267-10410`) отдаёт `masonryGeometry`/`opaqueBodies` из ТОГО ЖЕ `passageStates`/`roomPassages`, из которого строится видимость — вырез контурной стены создаётся, только если `amount > 0` (см. `passages = passageStates.filter(({amount}) => amount > 0)` → `_roomWallOpeningInputs(passages, space)` → `recutWallBodiesGeometry`/ `wallBodiesGeometry`). Guard источника читает именно этот `masonryGeometry` (`pointInOpaquePlanBody(sourcePoint, masonryGeometry, opaqueBodies)`, строка 10481) — то есть закрытая контурная дверь механически становится частью той же непрозрачной кладки, что и окно, для которого fail-dark уже покрыт существующими тестами (`test/physical-geometry.test.mjs`, `test/houseplan-runtime-contract.test.mjs`, оба не в этом диффе и не задеты). Это тот же код до и после диффа — диф не добавил отдельной ветки для «закрытой двери», он лишь расширил множество «непрозрачных» проёмов условием `amount<=0` вместо жёсткого «окно/наружная». **Проверено чтением, не исполнением.** Оставляю Low: тест — не догадка, будущая правка того же файла с меньшей вероятностью сломает это неявно проверенное свойство, если бы у контурного случая было явное assert-покрытие. Решение по Low — на усмотрение автора/следующего раунда, не блокирует. ## Что проверено и корректно (по AC ТЗ) - **AC1** (закрытая привязанная дверь не пропускает Glow). Доказано: `openingAmount()` (`src/logic.ts:305-330`) возвращает `0` для закрытого бинарного контакта; при `amount<=0` проём не входит в `passages` → не вырезается из кладки (`src/houseplan-card.ts:10317-10327`). `demo/smoke_glow.mjs`: `closedDoorBlocksGlow` — прогнан, OK (`closedDelta <= 3`). - **AC2** (открытие в течение одного render tick, без сохранения конфига). Доказано: `demo/smoke_glow.mjs` меняет только `c.hass.states` (без `_cfgEpoch++`/`_glowClipCache.clear()` вручную) и получает изменённые пиксели после `updateComplete` + двух rAF — то есть проверяет сам факт автоматической инвалидации кэша по сигнатуре, а не подложенную вручную очистку. OK. - **AC3** (`current_position=50` → центрированный вырез вдвое короче, символ получает тот же `amount`). Доказано unit: `openingLightApertureLength(80, 0.5) === 40` (`test/logic.test.mjs`); `openingAmount('gate','open',false,50) === 0.5`. Единый источник: и `_lightBarriers()` (`src/houseplan-card.ts:12332-12341`, `_openingAmt`), и видимый символ партиционного проёма (`src/space-render.ts:508-514`), и видимый символ обычного проёма (`src/houseplan-card.ts:12392`), и изометрия (строка 8753) читают ровно один и тот же `_openingAmt`/`openingAmount()` с одним и тем же `entity.attributes.current_position`. Проверено чтением всех вызовов (grep `_openingAmt(` и `openingAmount(`), дублирующего вычисления процента нет — «одно число, один источник» выполняется. `smoke_glow.mjs`: `partialDoorNarrowsGlow` — прогнан, OK (`0 < halfWidth < openWidth`). - **AC4** (invert меняет известное значение, не меняет outage-fallback). Доказано unit-матрицей `test/logic.test.mjs`: `openingAmount('gate','unavailable',true,25) === 1` — инверсия не трогает fallback, потому что в коде (`src/logic.ts:317-319`) ветка `unavailable/unknown` возвращает результат ДО применения `invert`. Тест «умеет падать»: если убрать ранний `return`, значение стало бы `0`, а не `1`. - **AC5** (ворота как двери; passage всегда прозрачен; окно/неизвестный тип/наружный проём — всегда непрозрачны). Классификатор `isInteriorLightOpeningType` не менялся этим диффом — проверено чтением, регресс невозможен без изменения этой функции. `openingAmount('passage', …) === 1` всегда — юнит подтверждает. - **AC6** (тот же контракт full/zero/partial для partition). Доказано `test/physical-geometry.test.mjs`: новый тест `scalePartitionOpeningCut` (центр сохраняется, `depth`/`hostId` неизменны, немутирующая функция) плюс `physicalBodyParts` full/half/closed через `pointInOpaquePlanBody`. `smoke_partition_openings.mjs` — прогнан, OK (не специфичен под Glow, но подтверждает отсутствие регрессии в общей семантике partition-openings). - **AC7** (источник внутри закрытого проёма полностью гаснет). Partition-случай — юнит (см. AC6). Контурный случай — см. Low L1 выше: проверено чтением общего fail-dark пути, дефекта не нашёл, но отдельного нового теста для этой ветки нет. - **AC8** (кэш переиспользуется при постороннем HA-апдейте, разный `amount` — новый ключ, LRU bounded). Структура ключа проверена чтением (`fingerprint = contentFingerprint([geometryFingerprint, openingStateSignature])`, `cacheKey = space.id|fingerprint`, `lruWrite(this._lightBarrierPool, cacheKey, entry, 8)` — лимит 8 не менялся) плюс существующий текстовый unit (`test/golden-matrix.test.mjs`: «a light source paints exactly one region…» сверяет буквальный текст сборки fingerprint — тот же приём, что уже использовался в проекте для `_cfgEpoch`). Поведенчески: `demo/smoke_glow.mjs`'s `setDoorPosition` меняет только состояние без явной очистки кэшей — рендер обновляется, то есть сигнатура действительно входит в реальный cache key, а не только в текст. `recut`-путь (переиспользование стеновой геометрии) сверяет `sharedFingerprint === geometryFingerprint` (только геометрия, без состояния дверей) — прочитал: `_wallUnionGeometry()`'s `sourceFingerprint` считается из `[this._curSpaceCfg, this._cellCm, this._gridPitch]`, то есть идентичен `geometryFingerprint` и не зависит от состояния дверей — смена состояния двери не форсирует пересборку общей wall-union геометрии, только пересчёт вырезов поверх неё. Корректно. - **AC9** (перф-бюджет на large-house). Вне скоупа код-ревью по собственной формулировке ТЗ — доказательство «exact-SHA CI performance smoke перед бетой». Не проверял. - **AC10** (golden-сцена closed/open/50%). Сценарий `lighting-opaque-glow-two-doorways-dark` расширен третьей дверью с `current_position: 50` и второй с закрытым cover — структурно верно и соответствует AC. Baseline не обновлён — см. «Известный пробел» ниже. ## Известный пробел (не блокирует, не Medium) `npm run golden:verify` на этом SHA даёт **1 different** из 80 сцен: `lighting-opaque-glow-two-doorways-dark`. Причина не в коде: сценарий (`demo/golden/matrix.mjs`) теперь рисует другую геометрию (2 двери → 3, изменена позиция второй), а PNG-эталон в `demo/golden/baselines/lighting-opaque-glow-two-doorways-dark.png` не обновлён. Диф `git diff origin/dev...HEAD --stat -- demo/golden/baselines` пуст — эталон действительно не менялся. Это не находка, а корректное следование процессу: правило §13/AGENTS.md запрещает принимать golden-эталон иначе как `npm run golden:accept -- --reviewed` по полному Linux CI-артефакту, и автор явно зафиксировал это в хендоффе («baseline локально не обновлялся… эталон должен принять Linux CI»). Приложенный AC10 сам называет доказательством «reviewed Linux golden artefact», а не локальный прогон код-ревью. Требовать здесь зелёный `golden:verify` значило бы просить автора нарушить §13. Фиксирую как открытый пункт для пре-релизного гейта (Validate/CI на `dev`), не как дефект этой задачи. ## Унаследовано / контекст ревью ТЗ Ревью ТЗ уже зелёное (`docs/reviews/SPEC-REVIEW-20-r1.md`, комментарий 2026-08-28T19:07:32Z, High 0 / Medium 0). Спека не менялась после этого вердикта (единственный коммит, трогающий `docs/specs/020-glow-open-door-spill.md`, — `3fa98a09`, который по топологии истории идёт ДО вердикта ревью ТЗ). Контракт спеки не пересматривал повторно, кроме сверки с фактическим кодом построчно по AC — раздел «Что проверено и корректно» выше. ## Чего не проверял и почему - **Performance smoke / large-house budget (AC9)** — по формулировке AC доказывается exact-SHA CI перед бетой, не код-ревью; локального перф-фикстур-прогона не делал. - **`python -m pytest tests_backend`** — диф не трогает `custom_components/**/*.py`. - **`node scripts/model-invariants.mjs`** — диф не меняет персистентную геометрию/схему (обоснование выше); нет пользовательского export/config для конкретной конфигурации. - **Полный browser-smoke матрикс (200 файлов)** — не запускал все, диф не задевает всё; прогнал ровно те 10, что `smoke-select.mjs` пометил прямым совпадением. - **Приёмка golden-эталона** — вне полномочий код-ревью и вне возможностей локальной машины без CI-артефакта; см. «Известный пробел». - **Ручное тестирование в браузере** — не проводилось (в цикле его нет); AC поддержаны автотестами/смоками, которые я прогнал сам и для ключевых — перечитал, что они умеют падать (openingAmount invert-fallback, cache-signature через отсутствие ручной очистки в смоке). ## Вердикт Зелёный. Реализация соответствует контракту ТЗ, единый источник числа `amount` подтверждён по всем потребителям (символ/Glow/изометрия), кэш-инвалидация проверена и поведенчески, и по формуле ключа, fail-dark для источника внутри закрытого проёма верен по конструкции для обоих типов стен. Единственная Low-находка (недостающий прямой тест для контурного варианта AC7) не блокирует и не требует правки в этом заходе. Незакрытый golden diff — ожидаемый и корректно задокументированный пункт пре-релизного гейта, не дефект этой задачи.