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

# CODE-REVIEW-275-r1

Issue: [#275](https://github.com/Matysh/houseplan-card/issues/275) — multi-wall bevel вырезает реальные полосы стен на перпендикулярных T/X-стыках.
Этап: код-ревью, заход r1 (первый заход код-ревью; ТЗ уже прошло 3 захода spec-review, все зафиксированы в `docs/reviews/SPEC-REVIEW-275-r*.md`).
Диапазон: `git diff origin/dev...HEAD` (8 коммитов: 3 редакции ТЗ + 3 ревью-документа + 2 коммита реализации `7bcc5b2`, `7cef301`).
Ревьюер ≠ автор, свежая сессия без контекста реализации.

## 1. Скоуп

Продукт: `src/wall-thickness.ts` — новая пара-уровневая классификация перпендикулярных
лучей узла (`multiWallProtectedRayIndexes`), защищённая полоса-геометрия
(`multiWallProtectedStripGeometry`/`multiWallProtectedMapGeometry`) и «эффективный
cut» (`multiWallEffectiveCutGeometry` = `pairwiseCuts − protectedStrips`),
встроенные в `bevelMultiWallBody` и `bevelMultiWallPaper`.

Тесты/доказательства: `test/wall-thickness.test.mjs` (+186/-14),
`test/fixtures/275-orthogonal-strip-containment.json` (минимизированные узлы
обоих backups владельца), `demo/smoke_multiwall_strip_containment.mjs`,
`demo/golden/harness.mjs` + `demo/golden/matrix.mjs` (2 новых golden-сцены,
`GOLDEN_MATRIX_VERSION` 40→41), `scripts/mutation-gate.mjs` (1 новый мутант +
1 расширенный), `scripts/wall-strip-containment.mjs` +
`demo/capture_wall_strip_backup.mjs` (локальный exact-input гейт по приватным
backup-файлам), `scripts/smoke-links.mjs`.

Документация: `docs/WALL-THICKNESS.md`, `docs/ARCHITECTURE.md`,
`docs/TESTING.md`, `docs/USER-GUIDE(.ru).md`, `docs/CHANGELOG(.ru).md`.
`docs/images/*.png` + `screenshots.json` — пересъёмка скриншотов документации
(отпечаток проверен `check-docs.mjs`, см. §2).

Персона/скоуп по `docs/SCOPE.md`: J1/J6 — «показать дом как есть» и «плита
должна оставаться истинной геометрией по мере жизни плана». Это регрессия
рендера, ломающая J1 (виден несуществующий проём в стене) без изменения
persisted-данных — ровно то, что заявлено в ТЗ и что не выходит за рамки этих
core jobs.

## 2. Как проверялось — гейты

| Гейт | Команда | Результат |
|---|---|---|
| typecheck | `npx tsc --noEmit` | green, без вывода |
| unit | `npm test` | `1170 pass, 0 fail, 0 skip` |
| build + bundle parity | `npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | green, копия совпадает байт-в-байт; `demo/srv/assets` не в репозитории (#255), проверена через `npm run bundle:sync` |
| docs fingerprint | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 10 external links)` |
| smoke-select | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | «Зарегистрированная связь (3)»: `smoke_junction_patch_resilience.mjs`, `smoke_multiwall_junction.mjs`, `smoke_multiwall_strip_containment.mjs` — все три прогнаны ниже |
| targeted smoke | `node demo/smoke_multiwall_strip_containment.mjs` | все проверки `true`, `OK` |
| targeted smoke | `node demo/smoke_multiwall_junction.mjs` | все проверки `true`, `OK` |
| targeted smoke | `node demo/smoke_junction_patch_resilience.mjs` | все проверки `true`, `OK` |
| mutation | `node scripts/mutation-gate.mjs --id=multi-wall-orthogonal-strip-protection-disabled` | чистый прогон green, мутант покраснел — «поймано 1 из 1» |
| mutation | `node scripts/mutation-gate.mjs --id=multi-wall-exterior-corridor-disabled` | чистый прогон green, мутант покраснел — «поймано 1 из 1» |
| golden (диагностика) | `node demo/golden/run.mjs --mode=capture` (полная матрица, локально, не заменяет предрелизный `--mode=verify`) | 96 passed, 2 `missing-baseline` (новые сцены #275, ожидаемо), 2 `different` — см. находку L1 ниже |

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

- **AC3 (exact-input lifecycle на приватных backups `1.json`/`2.json`)** — не
  перепрогонял: файлы приватны, лежат только на машине владельца/автора и не
  попадают в артефакты ревью. Проверено чтением: SHA-256 в хендофф-комментарии
  (`7e553c4aff08ace687d54a0d89a7d37e2c261f0c708fd4339e3fccee55a695b0` и
  `bca90c818116ba8ab53fa7c9360a1c67dee5299e620d5cb658eda97f6a3432e1`) совпадают
  байт-в-байт с хешами, указанными владельцем в теле issue — значит отчёт
  автора о «12/12» и «14/12» защищённых узлов и «0 нарушений» на всех четырёх
  состояниях (raw/preview/applied/reload) относится именно к тем файлам, на
  которых баг воспроизведён, а не к похожей синтетике (это разряд ошибки,
  из-за которого beta.6 вообще проскочила #272-ревью).
- **`python -m pytest tests_backend`** — не прогонял: diff не касается
  `custom_components/**/*.py`.
- **`node scripts/model-invariants.mjs --config <...>`** — не прогонял.
  Diff не меняет модель хранения: `wallIntervals`/`buildMultiWallNodeMap` не
  тронуты, новая логика работает только над уже построенным
  `MultiWallNodeMap` и не меняет ключи стен, `layout`, `marker.space` или
  `open_spans`. Инварианты #253/#244/#252/#258/#259 отвечают на вопросы про
  устойчивость записи толщины и ключей решётки — это persisted-модель, а
  §5 «Не входит» ТЗ прямо исключает её изменение. Раздел «Что человек увидит»
  и AC1-AC5 говорят только про производную рендер-геометрию.
- **`npm run golden:verify` (предрелизный, на точном SHA Linux CI)** — не
  запускался как гейт приёмки (baseline принимаются только через
  `golden:accept -- --reviewed` на полном Linux-артефакте, это гейт
  пре-релиза, не ревью). Локальную диагностику `--mode=capture` по всей
  матрице всё же прогнал, потому что diff прямо меняет отрисовываемую
  геометрию — см. находку L1.
- **performance-профили** — не запускались: не названы в AC, не задет
  явно перфочувствительный путь (protected-геометрия строится один раз на
  структурный проход, кэш не инвалидируется — проверено smoke-полями
  `state_tick_reuses_wall_geometry`/`state_tick_reuses_light_geometry`, оба
  `true`).

## 3. AC — доказательства

- **AC1 (обе новые категории дают нулевую потерю protected strips).**
  Доказано автотестом `issue #275 preserves...` в `test/wall-thickness.test.mjs`:
  независимый оракул (`protectedOrthogonalStripGeometry`, продублированная в
  тесте реализация классификации) сверяется с продуктовыми
  `multiWallProtectedRayIndexes`/`multiWallProtectedStripGeometry`, затем
  площадь разницы между обязательным union и `roomGeom`/`geom` проверяется
  `closeTo(..., 0, 1e-6)` на точных узлах `(204.166667, 645.833333)` и
  `(-354.166667, 2087.5)` — это именно координаты из обоих backups владельца
  (сверено с fixture `test/fixtures/275-orthogonal-strip-containment.json`).
  Тест умеет падать: см. мутационный прогон `multi-wall-orthogonal-strip-protection-disabled`
  выше — без protected-геометрии этот же тест краснеет.
- **AC2 (#249 остаётся ограниченным).** Доказано: `multiWallProtectedRayIndexes(node)`
  для узла #249 (`assert.deepEqual(..., [])`), площадь/probe той же
  fixture в существующем тесте `issue #249 bounds...` не изменились
  (`closeTo` на прежних константах). Я независимо пересчитал углы трёх лучей
  #249 (описаны в SPEC-REVIEW-275-r2 как ~102.3°/45°/−27.7°) — ни одна пара не
  близка к 90° при epsilon `1e-9`, значит узел действительно не получает
  protected-статус по построению, а не по совпадению порога.
- **AC3 (exact-input lifecycle).** Проверено чтением хендоффа + сверкой
  SHA-256, см. «Чего не проверял» выше. Инструмент `scripts/wall-strip-containment.mjs`
  прочитан целиком: он гоняет raw/preview/applied/reload через
  production pure-функции, не печатает и не сохраняет содержимое backup,
  использует ту же `multiWallProtectedRayIndexes`/`multiWallProtectedStripGeometry`,
  что и unit-тест — не отдельную, потенциально разошедшуюся, копию проверки.
- **AC4 (browser и downstream consumers).** Доказано прогоном
  `demo/smoke_multiwall_strip_containment.mjs` — плотная выборка семплов на
  обеих fixture-категориях, проверены Plan/View/kiosk/Static/hidden Iso/paper/light,
  плюс `render_never_writes_config` и переиспользование кэша при HA-тике.
  Всё `true`.
- **AC5 (visual gate видит именно выемку).** Golden-сцены
  `orthogonal-strip-cell-5-view-dark`/`orthogonal-strip-cell-1-view-dark`
  добавлены с семантической проверкой в `demo/golden/harness.mjs`
  (`isPointInFill()` по плотной сетке до PNG-сравнения) и юнитом
  `issue #275 golden preflight samples protected strips...` в
  `test/golden-matrix.test.mjs`. Оба прочитаны и логика соответствует §6.3
  ТЗ. Локально baseline для них ожидаемо отсутствует (`missing-baseline`) —
  первая съёмка и `golden:accept --reviewed` на Linux CI-артефакте остаются
  за пре-релизом, как и требует процесс.
- **AC6 (мутант ловит release escape).** Проверено исполнением, не только
  чтением — см. таблицу гейтов: оба мутанта (новый и расширенный старый)
  корректно проходят чистый прогон и корректно краснеют под мутацией.
- **AC7 (privacy и determinism).** В репозитории нет полных backups/layout/имён
  — подтверждено `git show`/просмотром diff, в фикстуре только минимизированная
  топология с généric room id (`a`/`b`/`c`). Table-driven классификация
  (`node([0, 90, 180])`, mixed-node `[0, 45, 90, 180]`, epsilon-граница) прочитана
  и пересчитана вручную — совпадает построчно (см. §4). Permutation/reversed-endpoint
  независимость для новых fixture-случаев отдельным permutation-тестом не
  покрыта, но существующий permutation-тест на fixture #197 (строки после
  обновлённых констант площади) уже гоняет `[...rooms].reverse()`,
  `[...walls].reverse()` и `wall.a↔wall.b` через тот же продуктовый путь, а
  площадь в этом тесте изменилась именно из-за #275 (124243.77→124534.61) —
  то есть узел этой fixture теперь имеет protected-лучи и permutation-инвариант
  для protected-геометрии фактически проверяется, просто не на новых
  backup-узлах. Не блокирует: относится к самому механизму, не к
  конкретным координатам, и делит один физический путь кода.
- **AC8 (локальные гейты).** Все выполнены и приведены в таблице выше.

## 4. Находки

### L1 (Low, информационная, не возвращает автору) — незадокументированный golden-impact на двух существующих сценах

При диагностическом прогоне `node demo/golden/run.mjs --mode=capture` по
полной матрице (см. §2) две **уже существующие** сцены дают `different`
против текущих baseline: `split-corner-wall-thick-dark` и
`isometric-large-warm-remount-dark`. Ни ТЗ, ни хендофф-комментарий их не
называют — оба говорят только про две новые сцены `orthogonal-strip-cell-*`.

Изолировал причину: временно вернул `src/wall-thickness.ts` к версии
`origin/dev`, пересобрал бандл (`npm run bundle:sync`) и повторил захват тех
же двух сцен — обе стали `passed`. Значит разницу вносит именно код этой
задачи, а не окружение/Chromium. Рабочее дерево полностью восстановлено
(`git status` чист) до продолжения ревью.

Просмотр `artifacts/golden/diff/*.png` показывает, что в обоих случаях это
**тот же класс дефекта**, который чинит #275: в `split-corner-wall-thick-dark`
закрывается маленький белый треугольник ровно в углу, где диагональная стена
примыкает к двум ортогональным наружным стенам (виден на baseline PNG, отсутствует
на actual PNG); в `isometric-large-warm-remount-dark` — десяток мелких
розовых отметок ровно в местах внутренних T-стыков плотной сетки комнат
large-house fixture. Оба — улучшения, не регрессии; повторного открытия
проблемы не нашёл.

**Почему это Low, а не Medium/High:** ни один AC не называет и не гарантирует
неизменность этих двух сцен, значит формально AC не нарушен. Baseline
принимаются только через `npm run golden:accept -- --reviewed` на полном
Linux CI-артефакте (§8, §11.4) — это отдельный, уже существующий предрелизный
шаг, который сам обнаружит несовпадение через job `golden` и потребует
осознанного принятия, а не тихого прохода. Находка не про корректность кода
(код прав), а про полноту сопроводительной документации.

**Что стоит сделать (не блокирует зелёный вердикт):** до принятия бет
предупредить релиз-менеджера — в `docs/TESTING.md`/хендоффе к бете стоит
явно перечислить оба задетых существующих golden-сценария по прецеденту
#231 («exact golden impact set»), чтобы `different` на pre-release гейте не
читался как неожиданная регрессия.

### Ничего Medium/High не найдено

Не нашёл находок, которые ломают AC, меняют persisted-контракт, расширяют
скоуп или создают регрессию в соседнем поведении. Основной алгоритм
(`multiWallProtectedRayIndexes` → `multiWallProtectedStripGeometry`/`multiWallProtectedMapGeometry`
→ `multiWallEffectiveCutGeometry` → `bevelMultiWallBody`/`bevelMultiWallPaper`)
прочитан построчно и соответствует геометрическому контракту §6.1–6.4 ТЗ,
включая явно требуемый в ТЗ fail-safe (повторная защита protected-геометрии
после difference, плюс финальный map-wide restore, плюс полный откат к
исходному телу, если сама protected-геометрия не строится).

## 5. Что проверено и признано корректным

- Классификация пар лучей (`multiWallProtectedRayIndexes`) не зависит от
  порядка вставки: работает на `node.rays`, который `buildMultiWallNodeMap`
  уже строит канонически (сортировка по углу, дедупликация по направлению,
  инвариантность к тому, был ли физический endpoint сохранён как `a` или
  `b`) — свойство унаследовано от существующего билдера, не нового кода.
- `bevelMultiWallBody`: protected-геометрия строится один раз на весь
  `MultiWallNodeMap` (а не по узлу), что явно устраняет найденный в r1 spec
  review риск «поздний проход стирает более ранний ремонт» — вычитается из
  `outerCuts` и `retainedCuts`, восстанавливается union'ом дважды (локально
  и в финальном map-wide проходе), при ошибке построения защиты — полный
  откат к небевелованному телу вместо риска дыры.
- `bevelMultiWallPaper`: рефакторинг с одного batched `multiWallBevelCutsAt(map, true, true)`
  на постуловый цикл с `multiWallEffectiveCutGeometry(node, ...)`
  математически эквивалентен (A − c1 − c2 − ... − cn = A − union(c1..cn)),
  проверил на исходнике `multiWallBevelCutsAt` — она чисто локальна к узлу и
  не использует состояние соседних узлов, поэтому batch/per-node дают
  одинаковый результат. Дополнительно per-node try/catch делает изоляцию
  отказа строже, чем раньше (одна проблемная нода больше не гасит бумагу
  для всех остальных).
- Мутации: расширение `multi-wall-exterior-corridor-disabled` (существующий
  #272-мутант) и новый `multi-wall-orthogonal-strip-protection-disabled`
  оба целятся именно в новый код (`effectiveCut`/`protectedStrips`
  restore/final union) и оба ловятся регрессионным тестом «issue #275
  preserves...», а не побочно другим тестом — проверено запуском `--id=`
  по отдельности.
- Документация (`WALL-THICKNESS.md`, `ARCHITECTURE.md`, `TESTING.md`,
  `USER-GUIDE(.ru).md`, оба `CHANGELOG`) прочитана целиком в дифф-виде:
  термины совпадают с ТЗ и друг с другом, changelog на обоих языках говорит
  об одном и том же на пользовательском языке («Оптимизировать планы» может
  остаться no-op — ровно то, что подтверждено в §4 ТЗ и хендоффе), новых
  i18n-ключей, контролов, touch/schema изменений нет — сверено `grep`
  по `src/i18n`.
- Трейлеры коммитов: `7bcc5b2` и `7cef301` несут `Issue: #275`; проверил, что
  реализационный коммит с `User-Visible: yes` содержит правки в обоих
  `docs/CHANGELOG*.md` (см. diff §2 хендоффа выше) — выполнено в одном
  коммите, как требует §10.1 provenance-гейта.
- Единственная пользователю видимая величина в этом диффе — геометрическая
  форма стены на плане; отдельного текстового/числового дублирования
  (превью против записи и т.п.) в этом диффе нет, «одно число — один
  источник» неприменимо буквально, а сама форма проверена AC4 одним
  общим источником (`_wallUnionGeometry()`/`roomGeom`) для всех потребителей
  (`plan_uses_canonical_path` = `true` в смоке).

## 6. Вердикт

High: 0 · Medium: 0 · Low: 1 (информационная, снята без правки: не про
корректность кода, а про полноту golden-impact описания, которое
обнаружится и будет обработано штатным пре-релизным гейтом `golden` +
`golden:accept -- --reviewed`).

Все AC1–AC8 доказаны — автотестом с подтверждённой способностью падать, либо
разобраны чтением с явной пометкой там, где повторное исполнение
физически невозможно (приватные backups). Скоуп не расширен, persisted-модель
не тронута, соседнее поведение (#249, #261, #271, #272, #197) явно
регрессионно защищено и перепроверено.

**Зелёный.**