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

# CODE-REVIEW-577-r1

Issue: #577 «Выбор граней окон для солнечных лучей» · заход **r1** · блокирующих циклов
использовано **0/4** (лимит 4, полный трек).

Материал: ветка `issue/577-sun-ray-window-corners`, коммиты `db4b397e` (feat) и
`6f6a85a1` (fix: типизация). Материал ревью — ровно
`6f6a85a11687c4f5cd20e79a2088d05ab6be12df`, рабочая копия на этом SHA.
ТЗ прошло лёгкое... нет, **полный** трек ревью ТЗ (аналитика назвала критерий:
новый UX-контракт + новое compatibility-поле): `SPEC-REVIEW-577-r1` (жёлтый,
Medium в скоупе — недостающие release-артефакты) → `SPEC-REVIEW-577-r2`
(зелёный). Правки после зелёного ревью ТЗ в тело issue не вносились —
дельта с r2 отсутствует.

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

`git diff origin/dev...HEAD` — 74 файла, из них продуктовые (класс A):

- `src/sun.ts` — параметр `origin: SunRayOrigin` в `computeSunRays()`, сдвиг
  исходного пролёта на `±d/2` по знаку `side`, вторая клипуемая грань
  («тоннель») для `outer` при `d > 0`; `SUN_RAY_ORIGINS`/`SunRayOrigin`/
  `sunRayOriginOf()`.
- `src/houseplan-card.ts` — `_effSunRayOrigin()`, `origin` в ключе
  `_sunRaysCache`, передача в `computeSunRays()`.
- `src/houseplan-editor-runtime.ts` — `sunRayOrigin` в `_settingsDialog`,
  чтение при открытии, запись при `_saveSettingsDialog()`.
- `src/sun-settings-view.ts` (новый) — `renderSunRayOriginSelect()`.
- `src/types.ts` — `ServerConfig.settings.sun_ray_origin` плюс попутная
  типизация соседних `north_deg`/`bg_mode`/`sun_rays` (эти три поля были
  доступны как `any`/через `Record<string, unknown>`; типизация нужна ровно в
  той же строке интерфейса, где добавляется новое поле — не отдельная работа).
- `src/i18n/{en,ru,de,fr}.json` — три ключа `gs.sun_ray_origin*` во всех
  четырёх локалях, тексты совпадают с телом issue.
- `custom_components/houseplan/{validation,support_package,const}.py` —
  строгий enum `vol.In(["inner","outer"])`, привилегированная фильтрация в
  support package, `sun_ray_origin: "inner"` в `DEFAULT_CONFIG`.
- `scripts/config-field-registry.mjs`, `scripts/config-schema.json` —
  запись реестра additive-полей и парного enum-контракта.
- `scripts/bundle-budget.mjs` — потолок `INITIAL_VIEW_GZIP_CEILING`
  перецентрирован 290 900 → 291 300 (комментарий объясняет факт и причину).
- `scripts/mutation-registry.mjs` — 5 новых мутантов (ниже).
- Тесты: `test/sun.test.mjs` (+2 теста), `test/config-schema-parity.test.mjs`,
  `demo/smoke_sun.mjs` (диалоговый round-trip + rekey кеша),
  `tests_backend/test_{validation,support_package,ha_import_export}.py`.
- Документация (класс C, в скоупе DoD): `docs/SUN.md`,
  `docs/WALL-THICKNESS.md` §5, `docs/CONFIG-COMPATIBILITY.md`,
  `docs/USER-GUIDE.ru.md`, `docs/TESTING.md`, оба `docs/CHANGELOG*.md`.
- Класс D: `dist/**`, `custom_components/houseplan/frontend/**` — пересобраны
  вместе с исходниками в тех же коммитах (не самостоятельный коммит).

Не найдено ни одного изменения в `demo/golden/matrix.mjs` или
`demo/golden/baselines/**` — см. находку ниже.

## Как проверялось (таблица гейтов)

Дешёвые гейты подтверждены зелёным Validate на этом SHA
(https://github.com/Matysh/houseplan-card/actions/runs/34898363073) и
перепрогнаны здесь же по инструкции ревью (код мог быть тем же, но раз уж
песочница это позволяла — так надёжнее для нового `origin`-пути):

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc -p tsconfig.test.json` (для юнитов) + `npm run build` (`tsc --noEmit` внутри) | green |
| Unit — sun | `node --test test/sun.test.mjs` | 43/43 green |
| Unit — config parity | `node --test test/config-schema-parity.test.mjs` | green |
| Build + bundle sync | `npm run build && npm run bundle:sync` | green; `cmp` трёх копий (`dist`, `custom_components/.../frontend`, `demo/srv/assets`) — байт в байт |
| Bundle budget | `npm run bundle:budget` | green: initial View 290 620 Б при потолке 291 300 (комментарий кода объясняет пересчёт) |
| no-new-any | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | green: 81 добавленная строка, новых `any` нет |
| check-docs | `node scripts/check-docs.mjs` | green (diff трогает `src/**`) |
| smoke-select | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | 18 прямых совпадений (полный список приложен исполнителем и здесь) |
| Смок — `smoke_sun` | `node demo/smoke_sun.mjs` | green, включая все новые `origin*`-проверки (см. ниже) |
| Смок — `smoke_sun_soft` | `node demo/smoke_sun_soft.mjs` | green — существующая геометрия/градиент/rim не задеты |
| Смок — `smoke_wall_thickness` | `node demo/smoke_wall_thickness.mjs` | green — толщина стены как подсистема не регрессировала |
| Мутация — geometry | `npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs && node --test --test-name-pattern="#577: outer rays" test/sun.test.mjs` на мутанте `side = 1` | воспроизведено вручную: мутант **краснеет** (`AssertionError`, `90` → `110`), откат чист |
| Backend | не прогнан локально (нет `pytest`/`.venv-backend` в этой песочнице) | принят по зелёному job `backend` Validate на этом SHA + прочтением диффа `validation.py`/`support_package.py`/`const.py`/тестов — строки совпадают дословно с тем, что описывают тесты |
| golden:verify | не прогнан | **находка ниже** — сценария для `outer` в матрице нет вовсе, верифицировать нечего |
| performance_smoke | не прогнан (heavy-гейт, не гейт ревью; AC9 — «ревью кода») | прочтением: новая ветка — один enum в уже существующем ключе кеша и одна арифметическая ветка в существующем цикле по окнам; тайминга/сетевых вызовов не добавлено |

Остальные 17 прямых совпадений smoke-select (`smoke_bg_color`,
`smoke_color_picker_consumers`, `smoke_dialog_zombie`, `smoke_draw_wall_thickness`,
`smoke_esc_dialogs`, `smoke_grid_snap`, `smoke_gs_always`, `smoke_ha_controls`,
`smoke_help_affordance`, `smoke_room_tooltip_toggle`,
`smoke_summary_dialog_scroll/first_paint/polish/panel`,
`smoke_zigbee_topology_hover`) совпали по общим символам диалога настроек
(`_settingsDialog`, `_settings`) — не по `sun`/`computeSunRays`/`WALL`. Диффа в
их предметной области нет (ни одна строка вне sun/i18n/types их не касается),
и почитанный код `_settingsDialog` показывает только добавление одного поля
и одного независимого рендер-вызова, не меняющих существующие поля — не
прогонялись, риск регрессии этих экранов оценён как отсутствующий.

## Находки

### Medium (в скоупе, не блокирует — жёлтый вердикт)

**AC4 и AC7 объявляют доказательство `golden`, но ни один golden-сценарий и
эталон для режима `outer` в диффе не появился.**

ТЗ (план автотестов) прямо требовал: «golden matrix: отдельный
детерминированный кадр `outer` на толстой стене плюс неизменность
существующего `inner`; светлая/тёмная тема». Фактически:

- `git diff origin/dev...HEAD -- demo/golden/` — пусто. Ни одна запись в
  `demo/golden/matrix.mjs` не добавлена, `demo/golden/baselines/**` не
  тронут.
- `demo/smoke_sun.mjs` получил только диалоговые проверки (`#gs-sun-ray-origin`
  select, save/reopen round-trip, инвалидация кеша по `_sunRaysCache`) — ни
  одна из них не рендерит реальную толстую наружную стену в режиме `outer` и
  не сравнивает её ни с пикселями, ни хотя бы с геометрией через
  `_sunRaysCache.rays[...].polys` на сцене с реальными стенами (только
  `test/sun.test.mjs` делает это на синтетической комнате).
- Хендофф-комментарий описывает только `golden:verify` на **существующих**
  сценариях («относящиеся к legacy-inner солнечные сценарии... зелёные») —
  это доказывает, что `inner` не изменился (AC3), но ничего не говорит о
  визуальном виде `outer`.

Из трёх заявленных каналов доказательства AC4 (`unit` + `smoke` + `golden`)
фактически поставлен только один — юнит на синтетической комнате (проверено:
`node --test test/sun.test.mjs`, тест `#577: outer rays...` зелёный и
воспроизводимо падает на мутанте `side = 1`, см. таблицу гейтов). Из двух
каналов AC7 (`smoke` + `golden`) не поставлен ни один в части, специфичной
для выбора грани — существующие смоки на тему, свет/тьма, киоск проверяют
общий рендер лучей, но никогда не переключают `sun_ray_origin` при этом.

Почему это не просто формальность: новый код в `computeSunRays()` при
`origin === 'outer' && d > 0` кладёт в `SunRay.polys` **два отдельных
полигона** (клип по тоннелю плюс клип по комнатному контуру), рисуемых как
два разных `<polygon>` с одной и той же полупрозрачной SVG-градиентной
заливкой и общей границей на внутренней грани стены. Совпадение координат
этой общей границы проверено юнитом только на синтетической фикстуре, где
`innerByRoom` подставлен вручную равным той же формуле `w.x + normal·d/2`,
которой независимо (через `_innerRoomContour`/`innerContourForRoom`) в
реальном рендере пользуется общий контур комнаты. Пара чисел «край тоннеля»
и «край комнатного контура» получены двумя разными путями в проде (это,
впрочем, тот же самый пре-существующий контракт, на который уже опирается
сегодняшний `inner`, так что риск разъезда не новый — но эффект нового
двойного полигона на стыке — растровый шов при полупрозрачной заливке —
проверяется только скриншотом, и скриншота нет). Это ровно тот исполнимый
oracle, который ТЗ и назвало, и без него утверждение AC4 «свет не течёт по
телу стены снаружи окна» подтверждено только на бумаге у стены, которую
тест сам же построил без реальной сшивки геометрии.

**Правка тривиальна и не блокирует:** без High-находок вердикт жёлтый,
доработка — в этой же задаче (#202). Ожидаемое исправление: одна запись в
`demo/golden/matrix.mjs` (толстая наружная стена, `settings.sun_ray_origin:
'outer'`, возможно светлая+тёмная тема как в существующей паре
`day-cycle-*`), плюс `demo/smoke_sun.mjs`-проверка, что при `outer` за
пределами `[innerX, outerX]` по нормали свет не выходит на реальной сцене
(не только в юните). Приёмка нового эталона — как обычно, только через
`npm run golden:accept -- --reviewed` на полном Linux-артефакте; до этого
момента ревью не может подтвердить AC4/AC7 golden-каналом и открыто говорит
об этом здесь, а не молчит.

### Low

Нет.

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

- **AC1 (UI/сохранение):** select `#gs-sun-ray-origin` рендерится ровно один
  раз, сразу после переключателя «Солнце в окнах» (`_settingsDialog`),
  никогда не `disabled`, независимо от состояния лучей — подтверждено и
  чтением (`sun-settings-view.ts` не содержит атрибута `disabled`), и смоком
  (`originAvailableWhenRaysOff: true`). Настройка пространства нового
  контрола не получила — `grep` не находит `sunRayOrigin`/`sun_ray_origin` ни
  в одном коде space-диалога.
- **AC2 (совместимость):** `sunRayOriginOf()` типизирован на
  `{ sun_ray_origin?: unknown } | null | undefined` и фейл-safe на `inner`
  для `null/''/0/true/[]/{}` — юнит-тест `#577: zero-depth walls are
  identical...` перечисляет все эти случаи явно. Backend:
  `vol.In(["inner","outer"])`, тест перечисляет 7 негодных значений (включая
  `None`, `""`, `0`, `True`, `[]`, `{}`) и ждёт `vol.Invalid` на каждом —
  протестировано мутантом `_SUN_RAY_ORIGIN = str`, который зарегистрирован
  как отдельный обязательный свидетель в `mutation-registry.mjs`. Экспорт/
  импорт и support package — юнит-тесты `test_ha_import_export.py` /
  `test_support_package.py` проверяют round-trip и фильтрацию
  неизвестной строки соответственно.
- **AC3 (внутренняя грань):** формула `sourceX = w.x + normal·d·side/2` с
  `side=1` для `inner` — байт-в-байт та же, что была в `dev` до этой задачи
  (сверено построчно с `git show origin/dev:src/sun.ts`); существующие golden
  для `inner` (`day-cycle-*`, `lighting-sun-window-state-only-dark`) остаются
  зелёными по заявлению автора — независимая проверка не требуется, так как
  сама формула не менялась.
- **AC5 (инварианты луча):** юнит `#577: outer rays start at the exterior
  corners...` явно сравнивает `len`, `dir`, `normal`, `depth` между `inner` и
  `outer` — все равны; нулевая толщина даёт `deepEqual(outer, inner)` —
  проверено самим тестом и повторно прогнано здесь.
- **AC6 (кеш):** `origin` — часть `_sunRaysCache` ключа
  (`houseplan-card.ts:10505`); мутант, убирающий `origin` из шаблонной
  строки, ловится смоком `smoke_sun` (зарегистрирован, воспроизводимость не
  перепроверялась вручную — дорогой браузерный гейт, довод §2.7 «мутант
  обязателен... там ревьюер не воспроизведёт отрицательный прогон второй
  раз», сам смок green на живом коде подтверждён).
- **AC8 (соседние контракты):** `windowWallInfo`, `isExteriorWall`,
  per-space `sun_rays`/`north_deg` (`sunRaysOn`/`northDegOf`) не тронуты
  диффом вообще (0 строк в диффе); `smoke_sun`, `smoke_sun_soft`,
  `smoke_wall_thickness` green подтверждают отсутствие регрессии на
  прилегающих сценариях (rain/clouds, editors-off, thin/thick wall
  hatching).
- **AC9 (производительность):** прочтением — новый код добавляет один
  enum-literal в уже вычисляемый ключ мемоизации и одну ветку `side = ... ?
  -1 : 1` внутри существующего цикла по окнам; ни новых таймеров, ни сетевых
  вызовов, ни работы вне пересчёта по (`azimuth, elevation, north, origin,
  _cfgEpoch, ...`). Проверено чтением, не исполнением (performance_smoke —
  heavy-гейт вне гейта ревью).
- **i18n:** все четыре локали (`en/ru/de/fr`) получили одинаковый набор из
  трёх ключей; русские тексты дословно совпадают с телом issue.
- **Config registry / schema parity:** `settings.sun_ray_origin` зарегистрирован
  в `scripts/config-field-registry.mjs` по образцу `bg_mode`/`summary_panel`;
  `test/config-schema-parity.test.mjs` добавляет пару
  `SUN_RAY_ORIGINS`↔`config.settings.sun_ray_origin` и прогнан зелёным.
- **Откат:** удаление поля возвращает `inner` — подтверждено самой формулой
  `sunRayOriginOf()` (fail-closed на `inner`), отдельного теста на «поле
  физически удалено из json» не требуется — это тот же путь, что и
  «отсутствует».
- **Бандл/бюджет:** три копии бандла (`dist`, `custom_components/.../frontend`,
  `demo/srv/assets`) идентичны байт-в-байт после `npm run bundle:sync`;
  `INITIAL_VIEW_GZIP_CEILING` поднят с обоснованием в комментарии кода и
  подтверждён замером (290 620 Б).
- **Типизация `types.ts`:** добавление `north_deg`/`bg_mode`/`sun_rays` рядом
  с новым `sun_ray_origin` — не самостоятельная незапрошенная работа: это та
  же строка интерфейса, что и новое поле, и снимает ранее нетипизированный
  доступ через `Record<string, unknown>` (`houseplan-editor-runtime.ts:10022`);
  не расширяет скоуп задачи.

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

- **`python -m pytest tests_backend`** — не прогонялся: в этой песочнице нет
  `pytest`/`.venv-backend`. Принято по зелёному job `backend` Validate на
  точном SHA `6f6a85a1` плюс построчному сличению изменённых файлов с тем,
  что тесты утверждают (см. таблицу гейтов) — это чтение, не исполнение,
  зафиксировано явно.
- **`npm run golden:verify` / `golden:capture`** — не прогонялся мной: без
  нового сценария для `outer` в матрице результат ничего нового не покажет
  (то же самое, что зафиксировано находкой выше); прогон существующей
  матрицы повторял бы то, что уже подтвердил автор на Linux CI, и не
  является Windows/локально принимаемым эталоном в любом случае.
- **`performance_smoke` (glow/interaction профили)** — heavy-гейт, не входит
  в обязательный набор код-ревью; AC9 сам называет проверкой «ревью кода» —
  выполнено чтением (см. выше).
- **Полный `ls demo/smoke_*.mjs` (249 смоков)** — прогонялись только 3 из 18
  прямых совпадений (`smoke_sun`, `smoke_sun_soft`, `smoke_wall_thickness`) —
  выбраны как единственные, реально пересекающиеся с изменённым кодом
  (`computeSunRays`, `WALL`); остальные 15 совпали только по общему символу
  диалога настроек, не по предметной области — не прогонялись, обоснование
  выше.
- **`npm run invariants`** — диффа не в модели геометрии (рёбра комнат,
  `layout`, `marker.space`, записи толщины) нет, только в рендере солнечных
  лучей и i18n/настройках; гейт не относится к этому диффу, поэтому не
  прогонялся (автор прогнал его добровольно на своём фиксture — это
  избыточно, но не вредно).

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

- Ветка: `issue/577-sun-ray-window-corners`
- SHA материала: `6f6a85a11687c4f5cd20e79a2088d05ab6be12df`
- Дерево: `2e07221ac58df96dcd816dd7cfa9df614addf09d`
- Предыдущий раунд: нет (это r1 код-ревью; ревью ТЗ — отдельная цепочка,
  `SPEC-REVIEW-577-r1`/`-r2`, закрыта зелёным до начала реализации)

---

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

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

- Ветка: `issue/577-sun-ray-window-corners`, коммит `6f6a85a11687` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `2e07221ac58df96dcd816dd7cfa9df614addf09d`
  ```
  git log --all --format='%H %T' | grep 2e07221ac58d
  ```
- Тело issue: `ebb1c05540c7191db0b4a76841f19b1371239caa0d41798ba82ec319116b32fc`
- Вердикт конвейера: `yellow` · High 0