diff --git a/docs/reviews/CODE-REVIEW-290-r3.md b/docs/reviews/CODE-REVIEW-290-r3.md new file mode 100644 index 00000000..00b11f64 --- /dev/null +++ b/docs/reviews/CODE-REVIEW-290-r3.md @@ -0,0 +1,218 @@ +# CODE-REVIEW-290-r3 + +- **Issue:** #290 — «Уступ в один шаг на общей стене создаётся молча и невидим при обычном зуме» +- **Этап:** код-ревью (PROCESS.md §2.7) +- **Заход:** r3 · блокирующих циклов израсходовано на входе 1 из 4 +- **Ветка:** `issue/290-near-axis-authoring-repair` +- **HEAD на момент ревью:** `d33ae88da4049bdbdfd02c57f935199007157cf3` +- **Диапазон:** `origin/dev..HEAD` (10 коммитов, `git diff --stat origin/dev...HEAD`: 35 файлов, +2611/-335) + +## Почему разбор полный, а не по дельте + +Формально предыдущий раунд (r2, комментарий issue #290 от 2026-08-24 13:21) — +зелёный, и по правилу §2.10 третий заход мог бы разобрать только дельту после +него. Но между r2 и этим заходом ветку **перебазировали на ушедший вперёд +`dev`** (комментарий владельца 2026-08-24 13:34: домержены #288/#290 changelog, +`WALL-THICKNESS.md`, пересобраны бандлы). Это прямо попадает под исключение +§2.10: «ребейз на ушедший вперёд `dev` — после ребейза это другой код». Сам r2 +уже один раз проходил через это же исключение относительно r1 (домёржен #289). + +Отдельно: **SHA, на котором получен вердикт r2, в самом вердикте не назван** +(комментарий #8 в issue называет только промежуточные коммиты `615c0744` и +`6ded0f01`, но не финальный HEAD ветки на момент зелёного вердикта). Это +находка процесса, а не кода: проверил — оба этих SHA сейчас нерезолвируемы +(`git cat-file -t` — «Not a valid object name»), что и является следствием +силового ребейза, а не пропуском автора. Дальше это не имеет практического +значения, потому что рабочий пункт §2.10 всё равно предписывает полный разбор +для этого случая, и я его сделал: прочитан и перепроверен весь diff +`origin/dev...HEAD`, а не только «правки со времени r2». + +## Скоуп + +Продукт: единый near-axis classifier (`src/near-axis.ts`, новый), authoring- +привязка при рисовании стен (`src/houseplan-card.ts`), exact-axis +постусловие Safe Resize (`src/resize.ts`), явный lossy-проход Optimize +(`src/plan-optimizer.ts`) с отчётом/Undo, единый источник допуска +`0.25°` для renderer (`src/wall-thickness.ts`), near-axis профиль в CLI +инвариантов (`scripts/model-invariants.mjs`), 6 mutation-gate записей, RU/EN +i18n, production-смоки, docs (ARCHITECTURE/CANVAS/RESIZE/WALL-THICKNESS/ +CONFIG-COMPATIBILITY/USER-GUIDE×2/TESTING), оба changelog. + +## Как проверялось — гейты + +| Гейт | Команда | Результат | +|---|---|---| +| Typecheck | `npx tsc --noEmit` | чисто, без ошибок | +| Unit | `npm test` | 1234 тестов: 1233 passed, 1 skipped, 0 failed | +| Build + bundle parity | `npm run build`; `diff dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js`; `git diff --stat -- dist/houseplan-card.js` | пересобранный `dist` идентичен закоммиченному и копии в `custom_components` — три копии совпадают | +| Docs fingerprint | `node scripts/check-docs.mjs` | «Documentation checks passed (7 files, 10 external links)» | +| Инварианты (геометрия задета) | `npm run invariants -- --config test/fixtures/real-plan-first-floor.json`; то же для `real-plan-second-floor.json` | код 0 на обоих; на первом плане 2 наблюдения (не нарушения, записи толщины на exact endpoints) | +| Near-axis профиль на реальных планах | `node scripts/model-invariants.mjs --config --near-axis` | first-floor: 0 почти-осевых стен; second-floor: 1 (это и есть исходный дефект issue, воспроизводимый и до правки) | +| Mutation-gate — все 6 обязательных AC9 ID индивидуально | `node scripts/mutation-gate.mjs --id=near-axis-*` ×6 | все шесть: «тест покраснел, как обязан» / «поймано 1 из 1»; после каждого прогона `git status --short` пуст — патчи откатываются | +| Smoke — прямое совпадение (`smoke-select.mjs --base origin/dev --head HEAD`) | `node demo/smoke_decor_layer_order.mjs`, `smoke_room_resize.mjs`, `smoke_zero_divider_taper.mjs` | все три OK | +| Smoke — зарегистрированная связь | `node demo/smoke_near_axis_optimize.mjs` | OK, все 12 ключей true | +| Smoke — файл прямо изменён диффом | `node demo/smoke_plan_drawing_repairs.mjs` | OK, все 19 ключей true, включая 3 новых near-axis ключа | +| Golden (полный, т.к. диф трогает Optimize-диалог и authoring-геометрию) | `npm run golden:verify` | код выхода 0, все 161 сценарий `passed`, включая `optimize-preflight-dialog-{dark-en,light-ru}` | +| Backend pytest | — | не прогонялся: `git diff --stat origin/dev...HEAD -- 'custom_components/**/*.py'` пуст | +| Дисциплина «тест умеет падать» — H1 регрессия (r1) | откат `src/resize.ts` к широкой проверке по всем рёбрам полигона, `node --test --test-name-pattern="#290 a remote near-axis" test/resize.test.mjs` | тест краснеет (`reason: 'invalid-geometry'` вместо ожидаемого `'partial-shared'`); после отката файла — снова зелёный, `git status` чист | +| Дисциплина «тест умеет падать» — AC1 source guard | откат `src/wall-thickness.ts:85` к инлайн-литералу `= 0.25` вместо импорта, полный `npm test` + `tsc --noEmit` | **не падает ничего** — см. находку M1 ниже | + +## Находки + +### M1 (Medium, в скоупе задачи) + +**ТЗ AC1** (`docs/specs/290-near-axis-authoring-and-repair.md:173-174`) прямо +обещает: «Authoring, Optimize и renderer #279 импортируют один threshold +source; **source guard запрещает отдельные литералы `0.25` в этих +classifiers**». Такого guard'а в коде нет. + +`src/wall-thickness.ts:85` действительно ссылается на источник: +`export const MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES = NEAR_AXIS_MAX_DEGREES;` +— но единственная проверка этого факта, `test/near-axis.test.mjs:23` +(`assert.equal(MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES, NEAR_AXIS_MAX_DEGREES)`), +сравнивает **числа**, а не происхождение значения. + +Воспроизведено: заменил в `src/wall-thickness.ts:85` импортированную ссылку на +инлайн-литерал (`export const MULTI_WALL_NEAR_ORTHOGONAL_MAX_DEGREES = 0.25;`, +удалив зависимость от `NEAR_AXIS_MAX_DEGREES`) и прогнал `npx tsc -p +tsconfig.test.json`, `node scripts/fix-test-build.mjs`, +`node --test test/near-axis.test.mjs test/wall-thickness.test.mjs` (115 +тестов) и отдельно `npx tsc --noEmit` — всё зелёное, ни один тест, ни +typecheck не заметили расхождения. Значение продублировано, а не +переиспользовано, ровно так, как AC1 запрещает, и ни один существующий гейт +этого не ловит. + +**Почему это не придирка, а реальный риск именно для этой задачи:** issue #290 +существует потому, что renderer (#279) и остальная система однажды разошлись в +допуске `0.25°`/`sin(0.25°)`. AC1 — это явно сформулированная защита от +повторения того же класса дефекта на трёх новых потребителях порога (authoring, +Optimize, renderer). Сейчас, если будущий рефакторинг/мёрдж случайно вернёт +renderer к собственному литералу (или к чуть другому числу), ни `npm test`, ни +`tsc`, ни один из зарегистрированных 6 mutation-gate ID для #290 этого не +поймают — именно тот тихий дрейф, который эта задача призвана исключить. + +**Как чинится в скоупе:** нужен один из двух вариантов — (а) статический guard +по образцу `test/single-source-numbers.test.mjs` (regex/AST-скан `src/**/*.ts` +на литерал `0.25` вне `src/near-axis.ts`), либо (б) mutation-gate запись, +аналогичная уже существующим шести, которая инлайнит литерал в +`wall-thickness.ts` и требует, чтобы это красило конкретный тест/typecheck. +Оба варианта дёшевы и не меняют продуктовое поведение. + +Находка в скоупе задачи, High отсутствует → **жёлтый вердикт**, исправляется в +этой же ветке, отдельный issue не заводится (решение владельца 2026-08-19, +#202). + +## Что проверено и корректно + +- **AC1 (кроме source guard)** — `test/near-axis.test.mjs:21-29` покрывает + exact axis, `316×1`/`316×2`, зеркальные/обратные концы, ровно `0.25°` + (`NEAR_AXIS_MAX_SLOPE`) и чуть выше, 30°-диагональ; boundary включительна + (`minor / major > NEAR_AXIS_MAX_SLOPE`, `src/near-axis.ts:28`). +- **AC2** — `demo/smoke_plan_drawing_repairs.mjs`: preview (`.active-axis`) + и committed draft персистят `316×0`; `snapNearAxisEndpoint` двигает только + свободный конец (`src/near-axis.ts:36-44`, `src/houseplan-card.ts:6917-6931`); + существующий узел, конфликтующий с near-axis правилом, корректно теряет + snap-owner (`effectiveCandidate`, тест `nearAxisRuleDoesNotClaimWrongEndpoint`). +- **AC3** — `src/resize.ts:1015-1021`: постусловие проверяет три инцидентных + сдвигаемым вершинам ребра (`involvedEdges = [prev, edge, edge+1]`), не весь + полигон. Регрессия r1 (H1: широкая проверка валила несвязанные ручки) закрыта + и подтверждена прямым откатом (см. таблицу гейтов); `test/resize.test.mjs` + фиксирует и «south-west,1 → enabled:true», и «north-west,3 → partial-shared + по независимой причине #289», не near-axis. +- **AC4/AC10** — `test/near-axis.test.mjs` тест «reduces the tracked real-plan + near-axis profile»: на `real-plan-second-floor.json` до repair — 1 почти- + осевая стена (совпадает с `--near-axis` CLI, см. таблицу гейтов), после + Confirm — 0, повторный Optimize — `changed:false`/`wallsStraightened:0`. +- **AC5** — `test/near-axis.test.mjs` «repairs a duplicated 316x1» проверяет, + что обе room-copies получают идентичные endpoints (`north.poly[1] === + south.poly[0]`), `demo/smoke_near_axis_optimize.mjs.applyRekeysWall` + подтверждает rekey записи толщины стены (`wall.key.endsWith('@0.0000')`). + Repair встроен в существующий pipeline `alignAllToGrid` → `normalizeWallIntervals` + → `degradeWalls` (`src/plan-optimizer.ts` вокруг строки 440), а не + специальным обходом, поэтому thickness/open-span rekey получается бесплатно + из уже проверенной инфраструктуры. +- **AC6** — тест «preserves true diagonals»: `316×2` и партиция `diagonal` + byte-equivalent после repair; отдельный юнит на openings, которые перестали + бы помещаться после repair (`skips a repair that would no longer fit a hosted + opening`) — кандидат корректно пропускается, `partitions` не тронуты. +- **AC7** — `maxStraightenShiftCm` в UI (`src/houseplan-card.ts`) округляется + вверх (`Math.ceil(x*10)/10`), то есть заведомо не меньше фактического сдвига + — соответствует требованию «верхняя граница». +- **AC8** — `demo/smoke_near_axis_optimize.mjs`: preview не пишет + (`previewDoesNotWrite`), Cancel не пишет (`cancelDoesNotWrite`), Confirm — один + атомарный `houseplan/plan/optimize` (`applyUsesOneAtomicWrite`), reload — + идемпотентно (`reloadIsIdempotent`), Undo восстанавливает исходную геометрию + байт-в-байт и глубина Undo равна одному шагу (`undoIsOneDeep`). Revision-guard + самого транспорта не менялся этим диффом — это существующая инфраструктура + Optimize, разбор чтением, не исполнением. +- **AC9** — все 6 обязательных mutation ID зарегистрированы + (`scripts/mutation-gate.mjs:945-1011`) и убиты индивидуально (см. таблицу + гейтов); это сильнее, чем просто `--check` реестра. +- **Single source of numbers** — `wallsStraightened`/`maxStraightenShiftCm` + считаются один раз в `plan-optimizer.ts` и не пересчитываются отдельно для + превью/после-Confirm/reload; единственное преобразование в UI — округление + вверх для отображения, не второй источник величины. +- **Changelog/трейлеры** — `edf8b068` (`fix: straighten near-axis wall + geometry`) несёт `Issue: #290`, `User-Visible: yes` и правки в оба + `docs/CHANGELOG.md`/`docs/CHANGELOG.ru.md` тем же коммитом. +- **Bundle parity** — пересобранный `dist/houseplan-card.js` побайтово + идентичен закоммиченному и копии в `custom_components/houseplan/frontend/`. +- **Golden** — полный прогон (161 сценарий) зелёный, включая два сценария + Optimize-диалога, которые непосредственно рендерят новые UI-строки. +- **Совместимость** — `docs/CONFIG-COMPATIBILITY.md` описывает repair как + подтверждаемый lossy-пас без миграции схемы; `PLAN_MODEL_VERSION` не поднят + (в диффе `plan-optimizer.ts` версия не менялась) — согласуется с «schema не + меняется» из ТЗ §9. +- **Производительность (прочитано, не исполнялось)** — `classifyNearAxisSegment` + O(1) на сегмент; `repairNearAxisRoomWalls` линеен по рёбрам/drafts/partitions + входного пространства, кандидаты не каскадируют (строятся из immutable + входа); добавка в `validateSafeResize` — фиксированные 3 проверки на вызов. + Отдельный performance-прогон не запускал, т.к. не назван в AC и алгоритмическая + сложность не изменилась по классу (было O(edges), осталось O(edges)). + +## Чего не проверял + +- **Полный набор mutation-gate** (все ID, не только 6 near-axis) — не требовался + диффом; случайно запустил фоном по невнимательности (`--help` без + распознанного флага не показал справку, а прогнал весь registry), прогон + завершился без ошибок, но я не использую его как доказательство — целевые 6 + ID проверены индивидуально и осознанно, этого достаточно для AC9. +- **Touch-специфичные смоки (pinch/pan/pointercancel)** — код диспетчеризации + жестов диффом не тронут, near-axis-правило встроено в уже общий для + touch/mouse путь `_resolvePlanDrawPoint`/commit; отдельного риска не вижу, + не гонял `smoke_editor_gestures`/`smoke_pan_any_zoom` и им подобные (в выдаче + `smoke-select.mjs` они пришли только как «слабая связь» по общему `_path`). +- **`python -m pytest tests_backend`** — не запускал, диф не трогает + `custom_components/**/*.py` (проверено `git diff --stat`). +- **Linux HA harness / полный CI Validate на этом SHA** — не мой гейт; + автор уже сообщил зелёный `Validate 32733382537` на текущем HEAD + (комментарий issue от 2026-08-24 13:34); не перепроверял внешний CI прогон + напрямую, доверяю ссылке как внешнему источнику, а не самопроверке автора. + +## Закрытие раунда r2 + +r2 (комментарий issue от 2026-08-24 13:21:36, зелёный, High:0/Medium:0) сам +закрыл H1/M1/M2 из r1 и не оставил открытых находок. Между r2 и этим заходом +код не менялся (ребейз перенёс тот же коммит `edf8b068`/`f6cf2c93` на новый +`dev` без изменения содержимого — конфликты владелец разрешил только в +changelog/`WALL-THICKNESS.md`/бандлах, что подтверждено комментарием "Разрешённые +конфликты" от 2026-08-24 13:34). Поэтому таблицы «находка → чем закрыта» для r2 +не требуется: закрывать нечего, r2 ничего не оставил. Настоящая находка этого +раунда (M1, source guard) — новая, не заявлена и не пропущена в r2: r2 прямо +пишет «дельта касается только `docs/specs/...`» на этапе ТЗ (SPEC-REVIEW-290-r2) +и не переразбирала AC1 на уровне кода за пределами заявленного автором +диффа между r1 и r2, а сам код AC1 (near-axis.ts/wall-thickness.ts) не менялся +между r1 и r2 — H1-фикс трогал только `resize.ts`. + +## Унаследовано из r2 + +Полный разбор в этом раунде проведён самостоятельно и заново по всему диффу +`origin/dev...HEAD`, а не по дельте — так как рёбейз делает предыдущий SHA +нерезолвируемым (см. «Почему разбор полный» выше). Поэтому код целиком +перепроверен мной лично, а не унаследован. Единственное, что действительно не +перепроверялось заново и взято как решённое на уровне продукта, а не кода — +**продуктовые решения владельца** (выравнивать без modifier, lossy-пас Optimize +с отчётом и подтверждением, единый допуск `0.25°`), зафиксированные и принятые +на этапе ТЗ в SPEC-REVIEW-290-r2 (`docs/reviews/SPEC-REVIEW-290-r2.md`, +зелёный, коммит `dc9f9a6c` по данным того документа) — эти решения не относятся +к коду и не могли быть затронуты ребейзом.