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

# Код-ревью issue #197 — цикл r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/197
- **ТЗ:** `docs/specs/197-junction-patch-fail-dark.md` (r2, зелёное
  `docs/reviews/SPEC-REVIEW-197-r3.md`)
- **Диапазон:** `origin/dev...HEAD` (`db5718095624e55f6407e37f867e8e520f9c4882`,
  один продуктовый коммит `fix: isolate degenerate junction patches`)
- **Ревьюер:** Claude, свежая сессия без контекста реализации
- **Вердикт:** зелёный · цикл r1/4 · High: 0 · Medium: 0

## Скоуп изменения

Единственный класс-A файл в диффе — `src/wall-thickness.ts` (+60/-6 строк).
Остальное — тесты (`test/wall-thickness.test.mjs`,
`test/fixtures/197-junction-patch.json`, `test/golden-matrix.test.mjs`),
targeted browser smoke (`demo/smoke_junction_patch_resilience.mjs`), golden
candidate-сцены (`demo/golden/matrix.mjs`, `demo/golden/harness.mjs`),
документация (`WALL-THICKNESS.md`, `ARCHITECTURE.md`, `TESTING.md`,
`USER-GUIDE.ru.md`, `STATUS.md`, оба `CHANGELOG*`) и три синхронные копии
бандла. Ни backend, ни i18n, ни манифесты не затронуты — соответствует §6 ТЗ
(«не входит в задачу»).

Продуктовое изменение в `src/wall-thickness.ts`:

1. `stableJunctionPatch(patch, coordScale)` — квантует координаты вычисляемого
   junction-патча с относительным шагом `max(1, coordScale) × 10⁻¹²`,
   отбраковывает нефинитные точки и патчи с площадью не больше `quantum²`.
2. `unionJunctionPatches(body, patches, coordScale, unionFn)` — транзакционно
   добавляет каждый стабилизированный патч: локальный `try/catch` вокруг
   одного `union`, отказ сохраняет последнее валидное `body` и не прерывает
   обработку следующих патчей.
3. Цикл `for (const patch of junctions) body = body ? union(...) : ...` в
   `wallBodiesGeometry()` (`src/wall-thickness.ts:1760-1761` на `dev`) заменён
   вызовом `unionJunctionPatches(body, junctions, coordScale)`. Общий
   структурный `try { … } catch { return null; }`, оборачивающий весь
   остальной pass (exterior envelope, room rings, edge bodies, opening cuts,
   extraBodies), не тронут и по-прежнему оборачивает точку вызова.
4. `virtualJunctionPatches` сделана `export` (test seam, без изменения тела) —
   тот же паттерн, что и у остальных pure-geometry helpers этого модуля.

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

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | зелёный, без вывода |
| Unit | `npm test` | 900/900, зелёный |
| Build + сверка бандлов | `npm run build && cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js && cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js` | зелёный; обе копии побайтно идентичны `dist/`, SHA-256 `b0dcd6651964c1bf9b964e750758b8dc5cad25bccf099a1b740af9b873fe68b5` — совпадает с хендофф-комментарием автора |
| Дисциплина «тест умеет падать» | временный откат `unionJunctionPatches(...)` на исходный незащищённый цикл в рабочей копии, `npm test` | ровно один новый тест (`issue #197 keeps the full masonry when one virtual-junction patch has ULP noise`) стал красным, остальные 899 остались зелёными; после возврата файла `npm test` снова 900/900. Мутация подтверждает, что регрессия реальна, а не тавтологична |
| Targeted smoke (AC7/AC8) | `node demo/smoke_junction_patch_resilience.mjs` (после свежей сборки и копирования в `demo/srv/assets`) | зелёный, все 15 проверок `true`: полный fixture (8/25/3), Plan/View/kiosk/static/hidden Iso держат один и тот же canonical `d`, paper/floor/Glow/sun barriers непустые, dark-theme toggle и HA state tick не меняют path и переиспользуют кеш (`_wallUnionCache`, fingerprint), рендер не пишет `_serverCfg` |
| Golden (доп. проверка, не входит в обязательный гейт) | `node demo/golden/run.mjs --mode=verify` (полный локальный прогон, уже был начат случайно и доведён до конца) | 0 `failed`; все существующие wall-junction сцены (`wall-junctions-plan-preview-light`, `wall-junctions-plan-t-dark`, `wall-junctions-view-dark`, `isometric-wall-junctions-dark`) — `passed`, т.е. численная стабилизация не сдвинула ни один уже принятый эталон; обе новые сцены `junction-patch-resilience-*` — ожидаемо `missing-baseline` (AC9 требует принятия только через `golden:accept -- --reviewed` на полном Linux CI артефакте, что вне этого цикла); одна несвязанная сцена `decor-color-popover-mobile-ru` — `different`, и 6 других `missing-baseline` — все они про `#180`/opening-placement, не задеты этим диффом (диффом не создаются и не меняются) |

Не прогонялось и почему:

- `npm run golden:capture`/принятие baseline — вне цикла ревью по процессу
  (§8 PROCESS.md, AC9 ТЗ): baseline принимается только `golden:accept
  -- --reviewed` на полном Linux CI артефакте, локальное принятие запрещено.
  `golden:verify` был прогнан целиком (см. выше) и дал полезный негативный
  результат — регрессий нет; этого достаточно.
- Полный набор `demo/smoke_*.mjs` (127 сценариев) — diff касается одной чистой
  geometry-функции без renderer-specific веток; ограничился targeted smoke,
  явно названным в AC7/АС8, плюс уже пройденным golden verify как независимым
  подтверждением на уровне рендера.
- `python -m pytest tests_backend -q` — backend не тронут (0 файлов
  `custom_components/**/*.py` в диффе).
- Performance-профили — ТЗ §13 явно оставляет fixture #197 вне отдельного
  performance-бюджета («добавляется в performance только если измерение
  покажет отдельный значимый профиль»); изменение — один дополнительный
  `try/catch` и линейное квантование вершин на патч, асимптотика не меняется.

## Разбор критериев приёмки

- **AC1 (unit).** `test/wall-thickness.test.mjs:794-856` строит полный fixture
  ровно по reproducer §3 ТЗ (только `rooms`/`open_spans` × `NORM_W`,
  `walls[].a/b` без предварительного масштабирования), проверяет
  `[8, 25, 3]`, наличие 20-см узла и вызывает production-сигнатуру
  `wallBodiesGeometry(...)`. На исходном `dev` эта же комбинация даёт `null`
  (см. мутационную проверку выше); после исправления —
  непустые `geom`/`paperGeom` с площадями `124991.31944444453` и
  `727303.8194444444`, что совпадает с числами из хендофф-комментария автора.
  Доказано автотестом, тест умеет падать. **AC1 выполнен.**
- **AC2 (unit).** Строки 818-843: `virtualJunctionPatches()` даёт ровно один
  патч с побайтно теми же четырьмя вершинами, что в §3 ТЗ;
  `stableJunctionPatch` на исходных вершинах и на предварительно нормированных
  (`/NORM_W`) даёт согласованные форкнутые координаты (`stable[1][0] ===
  stable[2][0]`, `stable[2][1] === stable[3][1]`) и bounds совпадают с
  исходным патчем с точностью `1e-9`. **AC2 выполнен.**
- **AC3 (unit).** Отдельный узкий тест `junction patch union isolates one
  failure and continues with later patches` (строки 881-902) инжектирует
  контролируемый throw через `unionFn`-параметр `unionJunctionPatches`:
  первый патч падает, второй получает именно последнее валидное `body`
  (`calls[1].body === 'initial-body'`), финальный результат —
  `'body-with-second-patch'`; отдельно проверено, что нефинитные/нулевые по
  площади патчи не доходят до boolean engine (`invalidCalls === 0`). Основной
  структурный `throw` по-прежнему даёт `null` — не покрыто отдельным новым
  unit-тестом, но подтверждено чтением кода: `unionJunctionPatches(...)`
  вызывается внутри неизменного внешнего `try { … } catch { return null; }`
  (`src/wall-thickness.ts:1771` и `:1844-1846`), который до этого изменения уже
  оборачивал весь structural pass и продолжает делать это после патча;
  существующие 900 тестов, включая множество null-return сценариев для
  #123/#141/#150/#172, продолжают проходить без регрессии этого поведения.
  Зафиксировано как «проверено чтением, не исполнением» в части общего
  fail-dark; изолирующая часть доказана исполняемой мутацией. **AC3
  выполнен.**
- **AC4 (unit).** Строки 806, 853-856: `before`/после сравнение
  `JSON.stringify({ rooms, walls, cuts, openings, extraBodies })` до и после
  вызова — побайтно равны; исходные 25 wall records не редактируются и не
  сливаются перед вызовом. **AC4 выполнен.**
- **AC5 (unit).** Строки 858-878: `[...rooms].reverse()`/`[...walls].reverse()`
  и вариант с разворотом каждого сегмента (`a`↔`b`) дают ту же geometry
  (`geometryDifferenceArea` в обе стороны `< 1e-7`); повторный вызов с теми же
  аргументами идемпотентен. **AC5 выполнен.**
- **AC6 (unit).** `npm test` зелёный на всех 900 тестах, включая существующие
  матрицы corner Split (#123), junction/thickness (#141), transition (#150),
  zero-divider (#172), openings, open spans, independent extras — без единой
  регрессии. **AC6 выполнен.**
- **AC7/AC8 (smoke).** `node demo/smoke_junction_patch_resilience.mjs` —
  зелёный, разобран выше по каждой проверке: Plan/View/kiosk/static/hidden
  Iso держат идентичный masonry path; paper, clean-floor hover, Glow/sun
  barriers непустые; dark-theme toggle и HA state tick не пересчитывают
  topology (кеш и fingerprint переиспользуются) и не пишут config. **AC7/AC8
  выполнены.**
- **AC9 (golden).** Кандидатные сцены `junction-patch-resilience-plan-dark` и
  `junction-patch-resilience-view-dark` добавлены в матрицу (dark theme, Plan
  и View), `test/golden-matrix.test.mjs` проверяет их состав (`[8, 25, 3]`) и
  версию матрицы (`GOLDEN_MATRIX_VERSION = 30`). Baseline не принят локально
  (`missing-baseline` в прогоне `golden:verify` — ожидаемо и корректно, ТЗ
  прямо требует принятия только через reviewed Linux CI артефакт). **AC9
  выполнен на уровне доступном код-ревью**; фактическое принятие эталона —
  вне этого цикла.
- **AC10 (ревью кода).** Diff ограничен `src/wall-thickness.ts`; ни
  renderer-specific обхода, ни grid-snapping физических offset-вершин
  (квантование идёт по `coordScale × 10⁻¹²`, не по шагу сетки), ни
  schema/backend/i18n правок, ни правок #198/#199 не найдено. Локальный
  `catch` окружает исключительно один `union(current, piece)` внутри
  `unionJunctionPatches`, а не остальной structural pass — основной отказ
  по-прежнему долетает до внешнего catch. **AC10 выполнен.**
- **AC11 (гейты).** Таблица выше: typecheck/unit/build зелёные, три копии
  бандла байтово идентичны, targeted smoke зелёный до передачи на ревью.
  **AC11 выполнен.**

## Находки

Находок нет. High: 0, Medium: 0, Low: 0.

Рассмотренные и отклонённые как не-находки:

- Экспорт `stableJunctionPatch`/`unionJunctionPatches`/`virtualJunctionPatches`
  как публичных функций модуля — это test seam в том же стиле, что и десятки
  других уже экспортированных pure-geometry helpers этого файла (см. список
  импорта в начале `test/wall-thickness.test.mjs`), а не новый runtime
  diagnostic API; ТЗ §17.6 явно допускает такой путь инъекции отказа.
- Квантование применяется ко **всем** вычисляемым junction-патчам, а не
  только к падающему — в спецификации (§7.1.2-4) это заложено как общее
  правило, и `golden:verify` подтверждает исполнением, что это не сдвинуло ни
  один уже принятый junction-эталон (`wall-junctions-*`, `isometric
  -wall-junctions-dark` — все `passed`).
- Продуктовый контракт (AC10, §4/§7 ТЗ со ссылкой на `docs/specs/141-wall-
  junctions.md`) соответствует итоговой реализации: изоляция ровно на
  границе optional patch, а не на границе всего structural pass.

## Документация и трейлеры

Коммит `db57180` несёт `Issue: #197` и `User-Visible: yes`; changelog правки
(`docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md`) присутствуют в том же коммите,
формулировки на двух языках согласованы и ссылаются на #197. Обновлены
`docs/WALL-THICKNESS.md` (§3, §8 — per-piece failure и numeric stabilisation),
`docs/ARCHITECTURE.md` (граница optional patch vs. structural failure),
`docs/USER-GUIDE.ru.md` (новая строка диагностики «После оптимизации исчезла
вся толстая кладка» в таблице troubleshooting — терминология согласована с
остальной таблицей раздела), `docs/TESTING.md` (новый чеклист-пункт с явной
привязкой к unit/smoke/golden) и `docs/STATUS.md` (текущий локальный цикл).
Всё — в том же коммите, что и поведение, как того требует §2.6/§11
PROCESS.md.

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

- Численная стабилизация патча собирает ровно ту же математику, что описана
  в ТЗ §7.1 и §17.1: относительный квантум, не завязанный на шаг сетки,
  отбраковка нефинитных/вырожденных патчей до попытки `union`.
- Изоляция патча — честная транзакция: присваивание `current = next`
  происходит только после успешного `unionFn`, при throw `current` не
  меняется; проверено и unit-тестом с инжектированным отказом, и чтением.
- Общий fail-dark контракт (структурный отказ вне патчей всё ещё даёт `null`)
  не нарушен — внешний `try/catch` не тронут.
- Единый canonical `wallBodiesGeometry()` остаётся источником истины для всех
  перечисленных в ТЗ §7.3 потребителей — подтверждено смоуком, не только
  декларацией в ТЗ.
- Persisted config не переписывается и не мутируется (immutability-проверка в
  unit и `renderNeverWritesConfig` в smoke).
- Три бандл-копии синхронны, SHA совпадает с заявленным в хендоффе.
- Golden-регрессий на существующих сценах нет (полный `golden:verify`,
  выполненный сверх обязательного минимума, подтвердил это исполнением).

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

- Полный `demo/smoke_*.mjs` (127 сценариев за пределами
  `smoke_junction_patch_resilience.mjs`) — не запускал; diff ограничен одной
  чистой geometry-функцией без затронутых renderer-веток, targeted smoke плюс
  выполненный (сверх обязательного) полный `golden:verify` дают
  соразмерное покрытие.
- Принятие golden baseline (`golden:capture`/`golden:accept -- --reviewed`) —
  вне этого цикла по процессу; baseline принимается только на полном Linux CI
  артефакте.
- `python -m pytest tests_backend` — backend не тронут диффом, прогон не
  требуется.
- Performance-профили (`performance_smoke`, Full Performance) — не названы в
  AC, ТЗ §13 явно не требует отдельного бюджета для этого fixture; не
  запускал.
- Полный `npm run inventory` (актуальные счётчики тестов для документации) —
  не запускал; в этом обзоре количество тестов приведено по фактическому
  выводу `npm test` (900/900), а не скопировано из чужого документа.