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

# Код-ревью issue #339 — заход r1

Вердикт: зелёный · заход r1 · блокирующих циклов 0/2 · High: 0 · Medium: 0

## Скоуп

Одна поверхность: `isDegenerateApexCorner` (`src/wall-thickness.ts`), функция,
классифицирующая острый (<15°) угол легаси-плана как вырожденный для целей
рендера контура стены (`outsetContour`/`insetContour`). Путь записи не тронут
(П1 из #329 запрещает создавать такие углы заново — правка чисто
рендер-легаси). Коммит `66bd3d69`, HEAD совпадает с веткой
`issue/339-mixed-thickness-apex`, один коммит поверх актуального `origin/dev`
(dev — предок HEAD, дерево чистое).

Диапазон изменённых файлов по существу: `src/wall-thickness.ts` (24 строки),
`test/junction-limits.test.mjs` (+29 строк, только добавление). Остальное в
диффе — синхронизированный бандл (`dist/`, `custom_components/.../frontend`),
пересъём скриншотов и CHANGELOG (en+ru) — сопутствующие, не код.

Трек — `trivial` (§5.1 PROCESS.md): тип bug, одна поверхность, без миграций/
i18n/перфа/touch, ожидаемое поведение зафиксировано (§4 спеки #329 +
собственный анализ автора в S2 с точной геометрической выкладкой). Соответствие
критериям — под вопросом не было, поэтому не проверяю отдельно: сам S2-анализ
содержит доказательство (таблица смыканий), которое я перепроверил численно.

## Что закрывает задачу продуктово

`docs/SCOPE.md` J6 — «Keep the plan true as the home evolves»: честный рендер
геометрии для существующих (легаси) планов — это условие доверия к карточке.
Баг — визуальный дефект унаследованного плана, не новая функциональность;
подходящая строка ровно эта.

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

**Математика.** Формула в PR: `alongPrev = (halfNext + halfPrev·cosθ)/sinθ`,
`alongNext = (halfPrev + halfNext·cosθ)/sinθ`, вырожденность — обе величины
внутри своих рёбер. Перепроверил численно для кейса из S2-анализа (10°, 15+30
см на рёбрах по 160 см):

```
along(edge h=7.5)  = 128.916 см
along(edge h=15)   = 128.260 см
```

Совпадает с таблицей автора (128.3/128.9 см < 160 см) с точностью до
округления. Тождество со старой формулой `h/tan(θ/2)` при `h1=h2=h`
проверил алгебраически: `(1+cosθ)/sinθ = cot(θ/2)` — верно, регресс
равнотолщинных углов исключён по построению, а не только по утверждению.

**Тест умеет падать.** Временно вернул старую версию `src/wall-thickness.ts`
(`git show origin/dev:...`), пересобрал `test-build`, прогнал новый тест
`#339` — упал ожидаемо (`false !== true`, "смешанные толщины [prev=0.0125,
next=0.00625] обязаны быть вырождены"). Восстановил рабочее дерево, тест
снова зелёный, `git status` чист.

**Гейты, прогнанные мной лично на `66bd3d69`:**

| Гейт | Результат |
|---|---|
| `npx tsc --noEmit` | чисто, без вывода |
| `npm test` | 1461/1461 pass, 1 skipped, 0 fail |
| `npm run build` + сверка 3 копий бандла | сборка ок; `diff dist/houseplan-card.js custom_components/.../houseplan-card.js` — идентичны; `diff dist/houseplan-assets.json ...` — идентичны; после `npm run build` `git status` чист (рабочее дерево уже содержало актуальный синхронизированный бандл) |
| `node scripts/check-docs.mjs` (diff трогает `src/**`) | "Documentation checks passed (7 files, 10 external links)" |
| `npm run golden:verify` (диф меняет геометрию рендера) | полный прогон, все сцены `passed`, 0 `failed`, exit code 0; включая `sharp-apex-legacy-dark` (равнотолщинная контрольная сцена #329 — подтверждает отсутствие регресса) |
| Мутационная проверка нового юнита | тест падает на дооткатной версии функции, зелёный на текущей — не тавтология |

Порядок был непустой: `demo/srv/assets` в репозитории не хранится, и первый
прогон `golden:verify` упал таймаутом на `Failed to fetch dynamically
imported module` — потребовался `npm run bundle:sync`, чтобы наполнить
рабочую копию стенда. Это состояние окружения ревью, не находка о ветке.

**Инварианты модели (`npm run invariants -- --config ...`) — не прогонял.**
Обоснование: изменённая функция работает исключительно внутри
`outsetContour`/`insetContour` — строит точки контура для рендера, не
трогает ключи рёбер (`keyOf`), записи толщины или `WallBodyPath.key`/`cm`
(они вычисляются отдельно, до вызова `isDegenerateApexCorner`, и не зависят
от неё). Три вопроса, на которые отвечают инварианты — исчезновение записи
толщины, разрешимость ссылок, совпадение ключа записи с ключом решёточного
ребра — не про эту функцию: она ничего не пишет и не адресует по ключу,
только решает геометрическую развилку рендера. `npm test` уже прогоняет
инварианты на всех моделях проекта и прошёл (см. выше).

**Смоки `demo/smoke_*.mjs` — не прогонял ни одного вручную.**
`node scripts/smoke-select.mjs --base origin/dev --head HEAD` вернул
НЕОПРЕДЕЛЁННОСТЬ (0 связанных символов, порог широкого символа — 39). Решение
за мной: полный `golden:verify` уже пиксельно проверяет рендер стен по всей
матрице (включая профильную сцену `sharp-apex-legacy-dark` и десяток
`junction-*`/`opening-*`/`wall-*` сцен с разными толщинами и углами) — это
более сильная и более прямая проверка именно этой функции, чем интерактивные
браузерные смоки (`real_plan_masonry`, `resize_pointer_real_plan`,
`plan_drawing_repairs`, `junction_limits`), которые автор прогнал вручную и
на которые я не полагаюсь без независимого доказательства. К тому же
интерактивные смоки идут через путь записи, а он не может создать угол <15°
(П1 из #329) — значит, воспроизвести именно легаси-конфигурацию 15+30 см
через них нельзя в принципе, они бы проверяли не тот код. Юнит-тест
считает точную геометрию напрямую, golden проверяет пиксели напрямую — этого
достаточно для узкой чистой функции.

**`npm run golden:capture`/`accept`, `python -m pytest tests_backend`,
performance-профили** — не прогонял: diff не трогает `custom_components/**/
*.py`, AC не называют перф, `golden:verify` (без `capture`) — правильный режим
для проверки отсутствия регрессии, а не пересъёма эталонов.

**«Одно число — один источник»** — не применимо: диф не добавляет и не
меняет ни одной видимой пользователю величины (не показывает толщину,
площадь, длину и т.п. — это решение внутренней геометрии контура). Новый
`test/single-source-numbers.test.mjs` не задет и не должен быть.

## Проверка AC (из S2-анализа, зафиксированного в S5-ready)

- **AC1** — угол 10°, смежные рёбра 15+30 см в оба порядка обхода: вырождена.
  Доказано юнитом `#339: вершина 10° со смежными рёбрами 15+30 см вырождена в
  оба обхода` — оба порядка (`[7.5,7.5,15]` и `[15,7.5,7.5]`) дают `true`;
  плюс рендер-проверка: `outsetContour` даёт ровно одну точку внешнего
  контура у вершины плана (острие в `(0,0)` с точностью 1e-9). **Выполнено.**
- **AC2** — равные толщины и обычные углы: вердикты байт-прежние, существующие
  §4-юниты и golden `sharp-apex-legacy-dark` зелёные без правок. Тестовый файл
  не содержит правок существующих кейсов (только добавление в конец), все
  1461 юнит зелёные, `sharp-apex-legacy-dark` — `passed` в полном
  `golden:verify`. Алгебраическое тождество `(1+cosθ)/sinθ = cot(θ/2)`
  подтверждает, что для `halfPrev = halfNext` формулы `alongPrev`/`alongNext`
  сводятся к старой `half/tan(θ/2)` без приближений. **Выполнено.**
- **AC3** — 30° со смешанными толщинами не вырождена (пара #310), нулевая
  толщина не вырождена. Оба случая — отдельные `assert.equal(...,  false)` в
  том же юните. **Выполнено.**

## Трейлеры и changelog

`Issue: #339`, `User-Visible: yes` — оба присутствуют в теле коммита
`66bd3d69`. При `User-Visible: yes` правки обязаны быть в обоих changelog в
том же коммите — проверено: `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`
получили симметричные записи в разделе `## Unreleased` в этом же коммите.
`docs/USER-GUIDE.ru.md` не тронут и не должен быть — новой терминологии
интерфейса задача не вводит (внутренняя геометрия рендера, не новый
UX-контракт), критерию `trivial`-трека это не противоречит.

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

- Формула замены математически верна и алгебраически регресс-безопасна
  (равные толщины ⇒ старая формула тождественно).
- Новый тест не тавтологичен: падает на предыдущей версии функции, проходит
  на текущей — проверено мутацией, а не по одному прочтению кода.
- Полный прогон golden (все сцены каталога `demo/golden/matrix.mjs`) зелёный,
  включая контрольную сцену именно для этого класса дефекта.
- Бандл синхронизирован побайтово между `dist` и обеими копиями,
  `check-docs` зелёный несмотря на пересъём 9 скриншотов (фингерпринт по
  `src/**` учтён и принят).
- Путь записи не затронут — П1 (#329) остаётся в силе, новых углов <15° по
  прежнему нельзя создать; правка не расширяет и не сужает контракт записи.

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

- `npm run invariants -- --config <...>` на конкретной конфигурации — не
  нашёл предмета: функция не адресует по ключу и не пишет записи толщины
  (см. обоснование выше). Общие инварианты по всем моделям прогнаны через
  `npm test`.
- Интерактивные браузерные смоки (`real_plan_masonry`,
  `resize_pointer_real_plan`, `plan_drawing_repairs`, `junction_limits`) —
  не прогонял сам; полагаюсь на `golden:verify` (пиксельно строже) и на то,
  что путь записи, который эти смоки в основном упражняют, не может
  воспроизвести исследуемый легаси-кейс.
- `golden:capture`/`golden:accept`, `pytest tests_backend`, perf-профили —
  вне скоупа диффа, не прогонял намеренно (см. обоснование выше).
- Ручного тестирования в браузере не было — как и предписано для стадии code
  для этого цикла: доказательство — автотест плюс чтение кода, оба выполнены.

## Находки

Нет. High: 0, Medium: 0. Зелёный вердикт, возврата автору не требуется,
issue вне скоупа не заводится.