houseplan-card/docs/reviews/SPEC-REVIEW-580-r1.md

# SPEC-REVIEW-580-r1

**Issue:** #580 «Солнечные лучи от внешних углов проходят сквозь толстые стены»
**Этап:** ТЗ на ревью (`S4-spec-review`), трек — полный продуктовый
**Заход:** r1 · блокирующих циклов израсходовано 0/4 (лимит для полного трека — 4)
**Материал:** тело issue #580, раздел `## ТЗ`, на момент публикации комментария
«Передача ТЗ на ревью» (2026-09-15T04:52:39Z), ветка `issue/580-outer-sun-wall-occlusion`
от `d37b2c9f8a4369082fec6970117cc97dd1e303c7` без продуктовых изменений.

## Скоуп

Задача чинит регрессию в геометрии солнечных лучей режима `sun_ray_origin: outer`
(#577): на толстой наружной стене с окном при косом положении солнца
`computeSunRays()` строит комнатную часть луча пересечением ПОЛНОГО внешнего
пролёта окна с контуром комнаты, а не с интервалом, реально прошедшим сквозь
оконный туннель — откосы стены не отсекают лишнюю ширину, и часть заливки
визуально идёт сквозь тело стены. Правка ограничена `src/sun.ts` и его тестами;
UI, i18n, схема конфигурации и touch-контракт не затрагиваются согласно самому
ТЗ.

Job по `docs/SCOPE.md`: J1/J5 (свет как часть спатиального обзора) не при
чём напрямую — window rays это отдельный decorative-визуал, но исправление
физически неверного визуала — прямая работа над качеством уже принятой фичи
#577, а не новая функциональность вне списка задач. Отклонений от SCOPE.md не
найдено.

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

1. Прочитан `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (§1–§10, до строки 871
   первой порции + смежные разделы §2.4/§2.5/§2.10/§7.1/§7.2).
2. Прочитано тело issue #580 (шапка бага + `## ТЗ`) и оба комментария
   («Аналитика», «Передача ТЗ на ревью») через `gh issue view --json`.
3. Прочитан канонический документ подсистемы `docs/SUN.md` целиком, включая
   раздел «Window light wedges — `settings.sun_ray_origin`» и список файлов.
4. Прочитан раздел «Лучи солнца» `docs/USER-GUIDE.ru.md` (строки ~1634–1665):
   таблица уже содержит строку «Толстая внешняя стена, режим «внешние углы» —
   Луч начинается с фасадной стороны и проходит к комнате только внутри
   оконного тоннеля» — то есть **пользовательский текст уже описывает
   исправленное поведение**, реализация ему пока не соответствует.
5. Прочитан код `computeSunRays()` в `src/sun.ts` (строки 402–459) построчно,
   чтобы проверить, что диагноз ТЗ («второе пересечение снова допускает в
   комнату всю исходную ширину луча») соответствует фактическому коду, а не
   догадке: `polys = clipToRoom(quad, clipPoly)` действительно клипует ПОЛНЫЙ
   `quad` (от внешнего пролёта) напрямую по контуру комнаты, а туннельная
   часть добавляется ОТДЕЛЬНЫМ независимым клипом (`if (origin === 'outer' &&
   d > 0) { … polys.push(...) }`) — комнатная и туннельная части не связаны
   пересечением друг с другом. Диагноз подтверждён чтением, не исполнением.
6. Прочитан существующий тест `#577` в `test/sun.test.mjs:468` — он проверяет
   `outer`-режим при азимуте 270°/угле окна 90° (перпендикулярное падение),
   поэтому не мог поймать именно эту регрессию на косом солнце. Технический
   подход ТЗ (разделить туннельную и комнатную часть, для комнатной считать
   траектории, прошедшие оба пролёта) реализуем поверх уже существующих
   входов функции (`wallDepthByOpening`, координаты окна, контур комнаты) —
   новых геометрических данных не требует.
7. Подтверждено существование `demo/smoke_sun.mjs` и `demo/golden/matrix.mjs`,
   на которые ссылается план тестов AC4/AC5.

Ручного тестирования UI не проводилось — этап ТЗ, кода ещё нет
(`issue/580-outer-sun-wall-occlusion` без продуктовых изменений).

## Находки

### Medium (в скоупе задачи — правится в том же ТЗ)

**M1. ТЗ не отвечает на несколько обязательных пунктов §7.1 / чек-листа DoR
§2.5, оставляя их фактически открытыми, хотя ответ на каждый тривиален.**

Отсутствуют как явные утверждения:

- **Сценарий** (какая персона/поверхность/момент, `docs/SCOPE.md`) и **что
  человек увидит до и после** одной фразой без терминов реализации — первые
  два обязательных раздела ТЗ идут первыми не случайно (`PROCESS.md` §7.1).
  Раздел `## ТЗ` начинается сразу с «Проблема» в терминах реализации
  (`sun_ray_origin: outer`, «откосы», «внутренняя плоскость»). Материал для
  этих двух разделов есть в шапке issue («Ожидаемое поведение»), но она тоже
  сформулирована в терминах реализации и не перенесена в ТЗ как отдельный
  продуктовый раздел.
- **i18n** — DoR требует «ключи en + ru перечислены»; в ТЗ нет даже строки
  «нет новых ключей», хотя ответ очевиден.
- **Влияние на touch** (`docs/TOUCH-SUPPORT.md`, View и киоск — блокирующие
  пункты DoR) — не упомянуто, хотя window rays рендерятся именно в View/
  киоске, для которых touch-совместимость обязательна к проверке по чек-листу.
- **Влияние на производительность** — не упомянуто, хотя правка меняет
  горячий путь `computeSunRays()` (пересчёт при каждом изменении
  азимута/элевации, см. `docs/SUN.md`: «Sun geometry is recomputed ONLY when
  … change» — то есть путь всё равно активный и не редкий) добавлением
  дополнительного пересечения полигонов. DoR требует «названо (или явно
  «нет»)» — сейчас не названо никак.
- **Риски** как раздел самого ТЗ — риски перечислены только в отдельном
  комментарии «Аналитика» (сложность 5/10, риск 6/10, «важно не изменить
  режим внутренних углов, прямое падение, нулевую толщину и fade/rim»), но не
  перенесены в тело `## ТЗ`. Аналитика и ТЗ — разные артефакты процесса
  (§2.2 vs §2.3); DoR (§2.5) требует риски именно при переходе в «Готово к
  разработке», то есть от ТЗ, а не от предшествующего комментария аналитика.

Почему это Medium, а не Low: без явных ответов на эти пункты DoR-чек-лист
§2.5 формально не проходится ни по одному из пяти перечисленных пунктов —
не потому, что ответы сложны (все пять тривиальны — «нет» или короткая
фраза), а потому что их сейчас в ТЗ просто нет, и переход в `S5-ready`
по букве процесса не может считаться завершённым. Правка дешёвая: добавить
пять коротких строк/раздел, не переписывая контракт и AC.

Как закрыть: добавить в тело `## ТЗ` явные строки: сценарий (персона,
поверхность View/kiosk, момент — низкое косое солнце), одну фразу «что
человек увидит» без терминов реализации, `i18n: нет новых ключей`, `touch:
не меняется (View/kiosk рендерят как раньше, взаимодействия нет)`,
`производительность: доп. пересечение полигона в уже пересчитываемом на
каждое изменение азимута/элевации пути, без нового порядка сложности —
либо явную оценку, если авторы считают иначе`, и короткий раздел «Риски»
(перенести формулировку из комментария аналитика).

### Low (на усмотрение автора — можно поправить или снять с записью)

**L1. Контракт п.4 использует немодальную формулировку («может оставаться
видимым»), которую ни один AC не проверяет.**

> «Если направление настолько косое, что ни один луч не проходит через оба
> пролёта, комнатная часть отсутствует; свет внутри доступной части туннеля
> **может** оставаться видимым.»

AC2 проверяет только пустоту комнатной части в этом случае
(«при предельно косом направлении без сквозной видимости комнатная часть
пуста»), но не утверждает и не проверяет, остаётся ли туннельная часть
освещённой. Формулировка «может» уместна как честное признание
неопределённости (поведение туннельной части не входит в эту правку и,
по всей видимости, не меняется относительно уже принятого #577
поведения), но в разделе «Контракт», который по определению должен
описывать однозначное поведение, такая модальность читается как
недорешённый пункт. Не блокирует: последствия ограничены тем самым
пограничным случаем, который вне зависимости от трактовки не влияет на
AC1–AC3 (типичные и предельные-но-не-нулевые углы) и не расширяет скоуп.
Рекомендация: либо явно пометить как «поведение вне контракта данной задачи,
не меняется» (аналогично формулировке п.6 про взаимное затенение), либо
удалить хеджирующее слово и добавить проверку в AC4 (там уже есть
контрольная точка «за закрытым откосом»).

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

- **Диагноз бага соответствует коду**, а не является догадкой: строки
  423/440–450 `src/sun.ts` подтверждают, что комнатная и туннельная части
  луча в режиме `outer` считаются двумя независимыми клипами одного и того
  же полного `quad`, без пересечения друг с другом — именно это описывает
  «Причина» в комментарии «Аналитика» и «Проблема» в ТЗ.
- **Технический подход реализуем на существующих входных данных**
  (`wallDepthByOpening`, координаты/угол/длина окна, контур комнаты) — не
  требует новой геометрии стен (откосов, рам) сверх уже используемой глубины
  `d`. Заявление «принято предположительно» про отсутствие моделирования
  скошенных откосов и отдельной глубины рамы согласуется с тем, что этой
  геометрии в проекте вообще нет ни для одного другого сценария (глубина
  считается прямоугольным туннелем и в текущем, не только багованном, коде).
- **Регрессионный периметр назван и обоснован верно**: контракт п.3 (нет шва
  между туннелем и комнатной частью, полная ширина при перпендикулярном
  падении), п.5 (`inner`, нулевая толщина, направление/длина/fade/rim не
  меняются) точно называют места, где чинить проще всего сломать — они прямо
  соответствуют существующим тестам `#577` (`test/sun.test.mjs:468,495`) и
  `DEV-EB173-01` (`test/sun.test.mjs:509`), которые эта задача не должна
  регрессировать.
- **`docs/USER-GUIDE.ru.md` не нуждается в правке** — таблица «Поведение» уже
  описывает целевое (исправленное), а не текущее ошибочное поведение
  режима «внешние углы» (строка «...проходит к комнате только внутри
  оконного тоннеля»). Хорошо, что автор не стал ничего менять в
  пользовательской документации, поскольку менять там нечего; отдельно
  отмечаю здесь как проверенный факт, а не находку.
- **AC1–AC7 однозначны и каждому указан способ доказательства** (`unit` ×3,
  `browser smoke`, `golden`, гейты, `review`) — ни один AC не описывает
  реализацию вместо наблюдаемого результата (AC1/AC2/AC4/AC5 говорят о
  видимых/измеримых геометрических свойствах луча, AC3 — о регрессионной
  идентичности, AC6/AC7 — гейты и объём диффа).
- **«Принятые предположения» оформлены по правилу §7.1** явным блоком, а не
  вписаны в контракт как факт — ревьюер может их оспорить, оба технические
  (не продуктовые), эскалация владельцу не требуется.
- **Не-скоуп назван явно и совпадает с ранее принятым лимитом** SUN.md
  («mutual shading… NOT computed»): контракт п.6 не пытается расширить
  задачу на взаимное затенение стен/крыльев.
- Track-решение («полный трек», не `small`) обосновано названным критерием
  (сложность/риск выше 3, меняется геометрический алгоритм) — соответствует
  требованию §2.2 называть нарушенный критерий, а не писать «обычный трек»
  без обоснования.

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

- Не проверял `npx tsc --noEmit` / `npm test` / `npm run build` — на этапе
  ТЗ продуктового кода ещё нет (ветка `issue/580-outer-sun-wall-occlusion`
  без изменений от `d37b2c9f`), гонять гейты не над чем.
- Не выполнял браузерные смоки и golden — они станут актуальны на код-ревью,
  когда появится реализация AC1–AC5.
- Не проверял `python -m pytest tests_backend` — задача не касается
  `custom_components/**/*.py`.
- Не пересчитывал производительность численно (нет кода) — отметил как
  находку M1 отсутствие даже качественной оценки в тексте ТЗ.

## Вердикт

Жёлтый: High-находок нет, но найден Medium в скоупе задачи (M1) — несколько
обязательных пунктов чек-листа §7.1/DoR §2.5 не имеют явного ответа в теле
`## ТЗ`, хотя ответ на каждый тривиален и не меняет контракт/AC. Технический
разбор задачи (диагноз, подход, критерии приёмки) проверен по коду и
корректен; возврат нужен только чтобы явно закрыть пропущенные разделы, а не
чтобы переписывать решение.

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

- Issue: #580, репозиторий Matysh/houseplan-card.
- Материал ТЗ: тело issue, раздел `## ТЗ`, на момент комментария
  `IC_kwDOTOcLQM8AAAABUkBntg` (2026-09-15T04:52:39Z, «Передача ТЗ на ревью»).
- Ветка `issue/580-outer-sun-wall-occlusion`, `HEAD = d37b2c9f8a4369082fec6970117cc97dd1e303c7`
  (без продуктовых изменений на момент ревью).
- Заход r1, документ первый; предыдущих раундов нет — разделы «Закрытие
  раунда r0» и «Унаследовано из r0» не применимы.

---

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

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

- Ветка: `issue/580-outer-sun-wall-occlusion`, коммит `d37b2c9f8a43` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `cd142c70cdb0ab25b12dd4fa2a77c9d955f01940`
  ```
  git log --all --format='%H %T' | grep cd142c70cdb0
  ```
- Тело issue: `25c7fa5fa2430ab0ce56a0f7684ab0fb192b932a209aba248b951ddd82189135`
- Вердикт конвейера: `yellow` · High 0