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

# CODE-REVIEW-249-r1

- Issue: [#249](https://github.com/Matysh/houseplan-card/issues/249) — ограниченная геометрия узла из трёх и более стен
- Этап: code (PROCESS.md §2.7)
- Заход: r1 · блокирующих циклов израсходовано 0 из 4 (этот заход не расходует бюджет: вердикт красный)
- Коммит на ревью: `062a98a1d841a5de633392357dcf0d4264ed3620` ("fix: bound multi-wall junction bevels")
- ТЗ: `docs/specs/249-multiwall-junction-bevel.md`, редакция r2 (SPEC-REVIEW-249-r2, зелёный)
- Материал: `git diff origin/dev...HEAD`, полный (не delta-review — это первый заход этапа code)

## Скоуп проверки

Прочитаны: `docs/SCOPE.md` (J1), `docs/WALL-THICKNESS.md`, `docs/ARCHITECTURE.md`, ТЗ
`docs/specs/249-multiwall-junction-bevel.md` (все 13 разделов, включая §9 AC1–AC7),
тело issue #249 и все комментарии (аналитика, продуктовые Q&A, ТЗ, оба раунда
spec-ревью, отчёт автора о реализации). Просмотрен весь diff
`src/wall-thickness.ts` (416 добавленных/изменённых строк), новый fixture,
`test/wall-thickness.test.mjs` (переписанные и новые тесты),
`demo/smoke_multiwall_junction.mjs`, изменения golden matrix/harness/test,
обновления `docs/WALL-THICKNESS.md`, `docs/ARCHITECTURE.md`, `docs/TESTING.md`,
`docs/CHANGELOG.md`/`.ru.md`.

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

Гейты реализации (соразмерны диапазону diff — трогает `src/**`, требует
check-docs; смоки выбраны по AC4 и по инструменту `smoke-select.mjs`, а не
прогнаны полным набором):

| Гейт | Результат | Прогнал |
|---|---|---|
| `npx tsc --noEmit` | зелёный | да |
| `npm test` | 1117 passed / 0 failed / 0 skipped (автор заявлял 1116+1 skip — итог тестов совпадает, расхождение по skip не расследовано, не блокирует) | да |
| `npm run build` | зелёный | да |
| SHA-256 трёх копий бандла | совпадают: `9e2c89fd...eefe05ec7` | да, сверил вручную |
| `node scripts/check-docs.mjs` | зелёный (7 файлов, 10 внешних ссылок) | да, обязателен — diff трогает `src/**` |
| `node demo/smoke_multiwall_junction.mjs` | зелёный, 15/15 | да — прямой AC4 гейт |
| `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | нашёл 1 прямое совпадение: `smoke_decor_layer_order.mjs` (символ `roomPoly`) | да |
| `node demo/smoke_decor_layer_order.mjs` | зелёный, 26/26 | да |
| `node demo/smoke_split_corner_wall.mjs` | зелёный, 14/14 | да — тема пересекается с новым junction-кодом |
| `node demo/smoke_junction_patch_resilience.mjs` | зелёный, 14/14 | да |
| `node demo/smoke_wall_junctions.mjs` | зелёный, 12/12 | да |

**Не прогонялось** (предрелизные гейты по PROCESS.md §8, не гейт ревью):
`npm run golden:verify` (полный), `npm run golden:accept`, performance-профили,
полный `smokes:select`/167 смоков, backend/HA-harness (Python не тронут).
Golden baseline не принимался — соответствует отчёту автора.

Все заявленные автором числа (SHA-256 бандла, счётчики smoke JSON, состав
`smoke-select`) подтверждены самостоятельным прогоном, а не переписаны со слов
автора.

Дополнительно я самостоятельно воспроизвёл геометрию (см. находку H1) через
compiled `test-build/wall-thickness.js`, вызывая экспортированные
`roomWallProfile`/`insetContour`/`outsetContour`/`buildMultiWallNodeMap`
напрямую, и сравнил результат с тем же вызовом на `origin/dev` (через
временный `git worktree`) — оба прогона выполнены, артефакты и worktree
удалены до завершения ревью, в репозитории не оставлено файлов.

## Находки

### H1 (High, блокирует). `innerContourForRoom` (clean floor) получает
геометрически неверную bevel-точку на узлах с несимметричной толщиной
сходящихся стен — floor выходит за пределы контура здания

**Точка отказа:** `src/wall-thickness.ts:1066-1069` (fallback-ветка
`insetContour`/`outsetContour`, идентичный код в обеих функциях) —
существующий (не новый) код, который для чрезмерной митры кладёт две точки
`poly[i] + normal·offset` независимо для каждого ребра, без проверки, что
результат остаётся внутри многоугольника. Раньше эта ветка почти не
срабатывала для узлов 3+ (порог был `MITRE_LIMIT×maxO`, то есть до `4×`
толщины), поэтому дефект был латентным. #249 делает порог `1.25×H` — то есть
именно тем механизмом, который теперь регулярно уводит обычные T/L-стыки
перегородки с внешней стеной в эту ветку, — и подставляет туда несимметричные
толщины (перегородка много толще внешней стены), при которых точка одного
ребра уходит по нормали на всю величину offset этого ребра, что при остром угле
между рёбрами пробивает противоположную сторону многоугольника насквword.

**Воспроизведение (числами, не «на глаз»):** тот же `cornerSplitFixture`, что
уже используется в тестах `test/wall-thickness.test.mjs` (`outerCm: 15`,
`dividerCm: 100`, path по умолчанию — то есть комбинация, реально
прогоняемая гейтом «corner Split preserves facade... every positive-thickness
3-ray matrix», строка `outerCm=15, dividerCm=100`):

```
node — узел (100, 100), угол между наружным ребром и перегородкой ≈ 26.6°
H = 41.6667 (полутолщина перегородки), R = 1.25×H = 52.0833

roomWallProfile('source').poly = [[100,100],[900,100],[900,500]]
roomWallProfile('source').offsets = [6.25, 6.25, 41.6667]

insetContour(poly, offsets, multiWallNodes) →
  [118.63389981249824, 62.7322003750035],   ← точка floor ВНЕ здания
  [100, 106.25],
  [893.75, 106.25],
  [893.75, 450.2902504687544]
```

Комната "source" — часть прямоугольника `y ∈ [100,700]`. Точка
`[118.63, 62.73]` имеет `y = 62.73 < 100`, то есть лежит **выше верхнего
края здания**, вне контура вообще (не просто вне комнаты — вне здания
целиком). Расстояние точки от узла — ровно `41.6667` (халф-толщина
перегородки), то есть формально `≤ R` (52.08), поэтому проверка §7.2.4
(«join-вершина не дальше `R + epsilon`») этот дефект не ловит: контракт
ограничивает только *расстояние*, а не сторону многоугольника, а фактическая
точка получена смещением от узла по нормали чужого (перегородочного) ребра на
всю его полутолщину — без проверки, что это не пробивает соседнее ребро.

Union-уровневый `multiWallBevelTriangles`/`bevelMultiWallBody` (новый код
#249, добавляющий вырезание лишнего клина из финального wall body) эту же
несимметрию на этом узле не ломает так явно, потому что `wallBodiesGeometry`
дополнительно пересекает итоговое тело с `exterior.centre`
(`src/wall-thickness.ts:2364-ish`, `if (body && exterior) body =
intersection(body, exterior.centre)`), что подрезает вылезшую геометрию
обратно к контуру здания. У `innerContourForRoom` (clean floor) такой
защитной пересечки нет вовсе — функция отдаёт результат `insetContour`
напрямую (после диффа: `src/wall-thickness.ts` в районе
`innerContourForRoom`), поэтому дефект долетает до потребителя без всякой
подрезки.

**Проверка «было/стало»:** тот же вызов на `origin/dev` (до #249, через
временный `git worktree`, тот же `cornerSplitFixture`, идентичный код helper'ов)
даёт `insetContour` без всплеска — расхождение строгого инварианта
`floor_union == original.poly − wall_body` составляет `≈ 6.5e-11` (шум
плавающей точки, тест на dev проходит с допуском `1e-7`). На коммите #249 то
же расхождение — `≈ 1686.24` (на 10 порядков больше допуска), причём вся
дельта — это именно тот вырвавшийся за пределы здания клин.

**Почему это не поймано авторскими гейтами:** этот же fixture
(`outerCm=15`, `dividerCm=100`) используется в тесте
`test/wall-thickness.test.mjs` — было
`'corner Split clean floors are exactly the room union minus canonical
walls'` со строгим `closeTo(geometryDifferenceArea(actual, expected), 0,
1e-7)` в обоих направлениях. Автор **заменил** этот тест на
`'corner Split clean-floor contours use the same bounded bevel endpoints'`
(новое имя), где вместо точного геометрического равенства теперь проверяется
только «каждая bevel-точка присутствует где-то среди вершин floor-контура»
(`floors.some((floor) => floor.some((point) => distance < 1e-7))`) — эта
проверка тривиально проходит, даже когда floor-контур неверно вышел за
пределы здания, поскольку сама вырвавшаяся точка — это ровно та «bevel-точка»,
которую тест ищет. Ни `demo/smoke_multiwall_junction.mjs`
(`cleanFloorConsumerIsPresent` проверяет только наличие path, не его форму),
ни новый golden-сценарий (`fill_mode: 'none'` — floor не рисуется вовсе)
дефект не покрывают. AC4 ТЗ прямо называет floor/room fills/room hover
каноническим потребителем той же исправленной геометрии (§7.4) — это
нарушено.

**Почему это Blocking, а не косметика:** это ровно тот же класс дефекта, для
которого написано ТЗ (клин, вылезающий за пределы стены), только
переехавший с внешнего контура кладки на внутренний контур пола, причём для
совершенно реалистичной конфигурации — перегородка заметно толще наружной
стены, встречающая её под острым/умеренным углом. Инструмент, которым это
создаётся («Split» комнаты по диагонали с последующей установкой толщины
перегородки), — штатный редакторский путь, не синтетика теста.

**Что нужно автору:** переоценить fallback-ветку `insetContour`/
`outsetContour` (строки 1066–1069) для случаев, когда единичное смещение по
нормали одного ребра на всю величину его offset выходит за пределы,
образуемые соседним ребром — либо ограничивать длину смещения проекцией на
соседнее ребро/дистанцией до узла, либо (как минимум) вернуть
`innerContourForRoom` защитное пересечение с исходным полигоном комнаты,
аналогичное тому, что `wallBodiesGeometry` уже делает для wall body. Отдельно
нужно вернуть строгую (не ослабленную) проверку инварианта
`floor_union == room_union − canonical_wall_body`, которая существовала до
этого коммита — она и обнаружила бы дефект сама.

---

### M1 (Medium, в скоупе — чинится в этом же цикле). AC2 не покрыт буквально
заявленным кейсом «три стены 15/50/70 см» (три РАЗНЫЕ толщины у трёх лучей)

Спецификация (§9, AC2) требует минимум четыре сценария, включая «трёх стен
15/50/70 см» — то есть узел, где ВСЕ ТРИ луча имеют разную толщину (без
повторов). Матрица в `test/wall-thickness.test.mjs`
(`'issue #249 node classification is order, direction and scale
independent'`) покрывает: 3 равных луча, 3 луча с halves `[7,5,5]`
(**только два разных значения** — 7 и 5,5), 4 равных луча, 4 луча
`[2,5,3,7]` (все разные). Ни один 3-лучевой случай с тремя различными
попарными halfDepth не тестируется явно; сам fixture AC1 тоже
50/50/70 см (две толщины совпадают). Кейс `[7,5,5]` покрывает оба
направления одной несимметричной пары через обход по кругу, но не покрывает
тройку из трёх взаимно разных величин (нет пары «средний-большой» без
повторов), которую владелец в issue привёл как конкретный числовой пример
(«например 15/50/70»).

Учитывая находку H1 (именно несимметрия толщин на многолучевом узле — источник
дефекта), это не формальная придирка: тест с тремя различными halfDepth,
особенно при остром угле, с высокой вероятностью тоже поймал бы H1 или его
аналог. Чинится точечно — один дополнительный кейс в существующем
`cases`-массиве с тремя различными halves, без новых продуктовых вопросов.

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

- **AC1** (экспортный fixture #249, узел 50/50/70): unit
  `'issue #249 bounds the exported three-wall junction with straight
  bevels'` — воспроизведён и зелёный; `H = 4.8611`, все join-вершины `≤
  1.25×H + epsilon`, один связный компонент, повторный расчёт даёт тот же
  результат, вход не мутируется (deep-equal до/после). Для ЭТОГО конкретного
  узла (толщины 50/50/70, угол не острый) floor-консьюмер H1 не проявляет —
  проверил отдельно (`innerContourForRoom` на этом fixture даёт точки на
  разумном расстоянии 3.5–4.9 от узла, без выхода за пределы), дефект
  специфичен для более несимметричных/острых конфигураций.
- **AC3** (двухлучевые узлы не меняются): существующий 2-лучевой набор
  тестов не тронут (кроме одного, №197-фикстура, у которого расширенный
  fixture содержит собственный узел степени 3+ — это отдельный, задокументированный
  в тесте, легитимный сдвиг площади, не 2-лучевой регресс). Отдельный
  тест `twoRay` подтверждает `insetContour`/`outsetContour` с пустой
  multi-wall картой идентичны вызову без карты.
- **AC4** (общий body для всех поверхностей): `demo/smoke_multiwall_junction.mjs`
  зелёный по всем 15 полям — Plan/View/kiosk/Static/hidden-Iso совпадают
  байт-в-байт по пути, light barriers используют ту же masonry, HA-tick и
  смена темы не перестраивают topology (кэш переиспользуется).
- **AC5** (golden фиксирует видимый результат): новый сценарий
  `multiwall-junction-bevel-view-dark` с semantic assertions (узел заполнен,
  отброшенный клин пуст, 3 луча) — не может пройти на пустом/неверном кадре;
  версия матрицы поднята (38→39); `test/golden-matrix.test.mjs` проверяет
  форму сценария.
- **AC6** (данные не мутируются): подтверждено deep-equality до/после в новом
  unit-тесте и в `'corner Split rendering does not materialize or mutate
  saved geometry'`.
- **AC7** (гейты реализации): все четыре зелёные, включая build/typecheck —
  перепроверено самостоятельно, не только со слов автора.
- **Документация**: `docs/WALL-THICKNESS.md`, `docs/ARCHITECTURE.md`,
  `docs/TESTING.md` обновлены по существу (не формально) и соответствуют
  фактическому коду; `docs/CHANGELOG.md`/`.ru.md` оба обновлены в этом же
  коммите при `User-Visible: yes`; трейлеры `Issue: #249` и
  `User-Visible: yes` на месте.
- **Union-уровневая коррекция** (`multiWallBevelTriangles`/
  `bevelMultiWallBody`) корректна для симметричных/сбалансированных узлов
  (проверено чтением кода и подтверждено зелёными таргетированными unit- и
  smoke-тестами) — проблема локализована именно в старой fallback-ветке
  `insetContour`/`outsetContour`, не в новой union-логике.

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

- Полный `npm run golden:verify`/`golden:accept`, полный набор из 167 смоков,
  performance-профили — предрелизные гейты по PROCESS.md §8, не обязаны быть
  прогнаны на этом заходе; риск R1 самой спеки («широкий blast radius для
  T-стыков») явно требует именно полного golden-прогона перед бетой, и находка
  H1 показывает, что этот прогон обязателен и по причине, шире описанной в
  спеке — не только визуальный дрейф, но и потенциальный явный дефект.
  Golden-сценарий #249 не поймает H1 — там `fill_mode: 'none'`.
  Не устанавливал/не запускал этот набор сам.
- Не искал системно другие узлы (существующие golden fixtures, реальные
  сохранённые планы) с похожей несимметрией толщин/острым углом, где H1 мог
  бы проявиться иначе (например, в `openingWallIndex`/tunnel-геометрии рядом с
  таким узлом) — за рамками того, что доказывает конкретный repro.
- Backend/Python — не тронут диффом, HA-harness не требовался и не запускал.

## Резюме

Реализация в целом добросовестно покрывает контракт ТЗ (единая node map,
union-уровневая коррекция клина, документация, golden/smoke на заявленном
экспортном сценарии) — но именно в том месте, где спецификация явно
предупреждала о риске (§11 R2: «фаска может создать щель или ложную
кладку… визуально малый дефект»), обнаружен подтверждённый воспроизведением
дефект (H1), который автор не поймал, потому что ослабил единственный тест,
способный его обнаружить. Это блокирующая находка — заход не может быть
зелёным.