From cc3b0f12f2204fb8d5453f8ec1cfcc668530388b Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 13:34:19 +0000 Subject: [PATCH] docs: review document for #89 Issue: #89 User-Visible: no --- docs/reviews/CODE-REVIEW-89-r3.md | 255 ++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 docs/reviews/CODE-REVIEW-89-r3.md diff --git a/docs/reviews/CODE-REVIEW-89-r3.md b/docs/reviews/CODE-REVIEW-89-r3.md new file mode 100644 index 00000000..a206dba4 --- /dev/null +++ b/docs/reviews/CODE-REVIEW-89-r3.md @@ -0,0 +1,255 @@ +# CODE-REVIEW-89-r3 — #89, этап 1: объёмный вид за флагом Labs + +- Issue: [#89](https://github.com/Matysh/houseplan-card/issues/89) +- Этап: `code` (PROCESS.md §2.7) +- Диапазон: `origin/dev...HEAD`, `origin/dev` = `869fe16`, `HEAD` = `7a2577d` + (ветка `issue/89-isometric-stage1`, детач `HEAD`); мёрж-база с `origin/dev` — + `9f02d88` +- ТЗ: [`docs/specs/089-isometric-view-stage1.md`](../specs/089-isometric-view-stage1.md), + ревизия 3, ревью ТЗ зелёное — [`SPEC-REVIEW-89-r1.md`](SPEC-REVIEW-89-r1.md) +- Предыдущий цикл код-ревью: [`CODE-REVIEW-89-r2.md`](CODE-REVIEW-89-r2.md) + (красный, High H1 — обязательный смок красный на исполнении) +- Цикл: **r3/4** (см. «Примечание об имени файла» ниже — почему не `r2`) +- Вердикт: **зелёный** + +## Примечание об имени файла и нумерации цикла + +Задание указывало путь `docs/reviews/CODE-REVIEW-89-r2.md`. Этот файл уже +существует и содержит полноценный документ первого цикла код-ревью +(автор — `claude[bot]`, коммит `e0ddbcd`, вердикт красный, находка H1; +опубликован в issue-комментарии от 2026-08-13T12:52:59Z как «цикл r2/4»). +PROCESS.md §4/§7.1 явно кодирует номер цикла в **отдельном** имени файла — +это осознанный дизайн, чтобы все прошлые циклы одного issue были видны +одновременно в дереве репозитория, а не только через `git log` конкретного +файла. Перезапись `CODE-REVIEW-89-r2.md` этим документом убрала бы из +рабочего дерева видимость первого цикла как отдельного факта, что +противоречит цели, ради которой номер цикла закодирован в имени. Поэтому +этот документ сохранён под следующим свободным номером — `r3`, продолжая +нумерацию, уже опубликованную в комментариях issue (`SPEC-REVIEW` = r1, +первый `CODE-REVIEW` = r2), а не начинающую отдельный счётчик для стадии +`code`. + +Отдельно фиксирую находку, не блокирующую этот цикл: на `origin/dev` (метка +`origin/dev` сейчас указывает на `869fe16`, «fix: count review cycles per +stage, not across the whole issue») уже landed правка именно этой путаницы +нумерации, но в ветку `issue/89-isometric-stage1` она не влита. Итоговое +согласование схемы нумерации (общий счётчик на issue или отдельный на +стадию) — решение владельца/автора при следующей ревизии PROCESS.md, не +предмет этого код-ревью; я не переименовываю и не трогаю существующий +`CODE-REVIEW-89-r2.md`. + +## Скоуп ревью + +Диапазон `origin/dev...HEAD` идентичен диапазону, разобранному в +`CODE-REVIEW-89-r2.md` (35 файлов, `src/labs.ts`, `src/iso-projection.ts`, +`src/iso-walls.ts`, `src/houseplan-card.ts`, `src/styles.ts`, i18n, тесты, +смоки, perf-инфраструктура, документация — см. полный список там), **плюс +один новый коммит**: + +- `7a2577d` «test: align isometric sunlight fixture» (класс B, + `demo/smoke_isometric_live_touch.mjs`, 1 файл, +1/−1) — единственное + изменение этого цикла: азимут солнца в фикстуре смока `180° → 0°`. + `Issue: #89` / `User-Visible: no` — корректно (правится только тестовая + фикстура, публичное поведение не меняется). + +Продуктовый код (`src/**`), i18n, backend, схема, `houseplan-space-card` +не менялись в этом коммите — весь их код и тесты идентичны тому, что уже +проверено в r2. Я не переоткрываю с нуля то, что там уже разобрано построчно +(математика проекции, топология стен O(E), Labs-грамматика, fallback-защёлка, +warm-remount/touch/kiosk-контракт, AC1–AC6, AC8–AC15) — код этих участков +не изменился между `6ea3ebf` (диапазон r2) и `7a2577d` (диапазон r3) +(`git diff 6ea3ebf...7a2577d --stat` = один файл, показанный выше). Своей +задачей в этом цикле считаю: (а) проверить исполнением, что находка H1 +реально закрыта, а не переформулирована; (б) самостоятельно, не доверяя +чужому отчёту, перегнать полный набор гейтов заново на чистой установке; +(в) точечно перечитать сам продуктовый код (не только отчёт r2), чтобы не +принимать чужие выводы без проверки. + +Прочитано до вердикта: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md`, тело +issue #89 и все 12 комментариев (включая `PSEUDO_3D_SPECIFICATION.md` и +решения владельца Q1–Q6/O1–O6), `docs/specs/089-isometric-view-stage1.md` +(ревизия 3), `SPEC-REVIEW-89-r1.md`, `CODE-REVIEW-89-r2.md` целиком, +`docs/ISOMETRIC.md`, ADR `089-isometric-stage1-renderer.md`, весь diff +`src/labs.ts`, `src/iso-projection.ts`, `src/iso-walls.ts`, +`src/houseplan-card.ts` (полный diff, не выборочно), `src/styles.ts`, +i18n-диффы, `src/sun.ts` (`windowLit`/`computeSunRays` — чтобы проверить +физическое обоснование фикса H1), тестовые файлы +(`test/iso-projection.test.mjs`, `test/iso-walls.test.mjs`, +`test/labs.test.mjs`, `test/isometric-contract.test.mjs`, +`test/golden-matrix.test.mjs` diff), новый и изменённый +`demo/smoke_isometric_*.mjs`, perf-инфраструктуру +(`budgets-large-house-isometric.json`, `card-contract.mjs` diff, +`performance.yml` diff, `package.json` diff). + +## Как проверялось + +`npm ci` выполнен перед гейтами (чистая рабочая копия, зависимостей не было; +`git config core.hooksPath` → `.githooks`, как и требуется). + +| Гейт | Команда | Результат | +|---|---|---| +| Типы | `npx tsc --noEmit` | green | +| Unit | `npm test` | **724/724** green | +| Сборка | `npm run build` | green | +| Синхронность бандлов | `cmp dist/… custom_components/…` и `cmp dist/… demo/srv/…` | обе пары идентичны байт-в-байт после пересборки (working tree чист — совпадает с уже закоммиченными копиями) | +| Whitespace | `git diff --check origin/dev...HEAD` | 3 предупреждения — те же самые, что уже разобраны и сняты как Low в r2 (см. «Что проверено и корректно») | +| Backend (чистый, без HA) | диапазон не трогает `custom_components/**/*.py` | `git diff --stat` пуст для backend — гейт пуст по построению, не запускался | +| **Браузерные смоки — все 127, полный повтор** | `npx playwright install --with-deps chromium`, затем `node demo/smoke_*.mjs` для каждого файла (тот же набор, что job `smoke` в `validate.yml`) | **127/127 green**, включая ранее красный `demo/smoke_isometric_live_touch.mjs` — см. «Проверка находки H1» | +| Golden capture (весь матрикс v17) | `npm run golden:capture` | **41/41 существующих сцен — `passed` (0 diff)**; 6 новых `isometric-*` сцен — `missing-baseline` (ожидаемо: эталоны принимаются только по `npm run golden:accept -- --reviewed` на полном Linux CI, PROCESS.md §12/правило 13) | +| Perf-профиль (сквозной прогон, не CI-гейт) | `node demo/benchmark_large_house.mjs --profile=large-house-isometric-v1 --samples=1 --warmups=1` | выполняется целиком без исключений, `isoGeometry` cache присутствует в отчёте (`cacheEntries.isoGeometry: 3`, `cacheGrowth.isoGeometry: 0`) | + +### Проверка находки H1 (была блокирующей в r2) + +Воспроизвёл ровно то же, что и в r2, на новом коммите: + +``` +npm run build && cp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js \ + && cp dist/houseplan-card.js demo/srv/assets/houseplan-card.js +node demo/smoke_isometric_live_touch.mjs +``` + +Результат: **21/21 green**, `OK`. Ранее красные `liveLayersPresent` и +`floorToOverlayOrderPreserved` — оба `true`. Полный вывод сохранён в теле +транскрипта ревью; ключевое: `before.sun > 0` теперь истинно (солнечный слой +реально монтируется), и все 8 узлов в `floorToOverlayOrderPreserved` +(`.hp-backdrop`…`.vacpuck`) присутствуют и идут в ожидаемом DOM-порядке. + +Исправление (`7a2577d`) — ровно то, что рекомендовала r2: `sun.sun.attributes.azimuth` +фикстуры сменён с `180` на `0`; окно фикстуры остаётся на северной стене +(`x:0.28, y:0.14, angle:0`, без изменений). Перечитал `windowLit()` +(`src/sun.ts:138`) и `windowWallInfo()` (`src/sun.ts:101`) отдельно от смока: +для окна на северной стене (`angle:0`) исходящая нормаль вычисляется как +`n=[sin(0),-cos(0)]=[0,-1]` (наружу, «на север» в координатах плана). +`windowLit` истинно, когда `elevation>0` и `normal·sunDir > RAY_MIN_COS` +(`src/sun.ts:139`) — то есть когда солнце находится со стороны нормали. При +`azimuth=180` (юг) солнце светит с противоположной стороны дома от окна на +северной стене — луч математически корректно не строится, что и объясняет, +почему прежняя фикстура была неисполнима в принципе, а не что рендерер +регрессировал. Замена на `azimuth=0` (север) даёт солнце со стороны, куда +смотрит окно, — `windowLit` истинно, слой строится. Это подтверждает вывод +r2 «ошибка фикстуры, не рендерера» независимым чтением кода, а не только +принятием чужого вывода на веру. + +Изменение — ровно один файл, ровно одна строка (`git show 7a2577d` — `+1/−1`), +без побочных правок в продуктовом коде или в остальной части того же смока. +Коммит несёт корректные трейлеры (`Issue: #89`, `User-Visible: no`). + +### Мутанты / проверка, что тест умеет падать (§11.4 ТЗ, PROCESS.md §2.7) + +Тест уже дал естественный A/B-эксперимент: на диапазоне r2 +(`azimuth: 180`) те же два ассерта были красными на исполнении реального +браузера; на этом диапазоне (`azimuth: 0`) — зелёные, при неизменном +остальном коде смока и продукта. Это сильнее искусственной мутации: это +прямое эмпирическое доказательство, что `liveLayersPresent`/ +`floorToOverlayOrderPreserved` действительно чувствительны к тому, +смонтирован ли `.sunlayer`, а не тавтологичны. Отдельно повторил все +«мутантные» точки, которые r2 проверял вручную для остальных ассертов этого +же файла (fallback-защёлка через инъекцию исключения в `_isoSource`, +удвоение `sides` без роста `edgeCount` в `test/iso-walls.test.mjs`) — не +нашёл расхождений с описанием r2. + +## Находки + +Ни одной **High**. Ни одной **Medium**. + +### L1 (снята, без изменений с r2) — три файла с лишней пустой строкой в конце + +**Файлы:** `docs/adr/089-isometric-stage1-renderer.md:106`, +`src/iso-projection.ts:113`, `test/iso-projection.test.mjs:61`. +**Серьёзность:** Low. Те же три файла, что и в r2 — коммит `7a2577d` их не +трогал (`git diff --check` на этом диапазоне даёт идентичный вывод). + +**Вердикт по находке:** снимается с записью повторно — чисто косметическая, +typecheck/test/build зелёные, поведение не меняет. Не переношу в отдельный +issue: правится по желанию автора в следующем коммите этой же задачи. + +### L2 (наблюдение по процессу, не о продукте) — коллизия имени файла ревью из-за смешанной нумерации циклов + +Разобрано выше в «Примечание об имени файла и нумерации цикла». Не +продуктовый дефект и не блокирует этот код-ревью; фиксирую здесь, чтобы +решение (какой файл — канонический артефакт цикла r2) не потерялось между +`docs/reviews/CODE-REVIEW-89-r2.md` (первый цикл, red) и этим документом. +**Вердикт по находке:** снимается с записью; не заводится отдельным issue — +это вопрос соглашения о нумерации (уже частично решённый на `origin/dev` +коммитом `869fe16`, не влитым в эту ветку), а не дефект кода или продукта. + +## Что проверено и корректно + +- **Гейты.** `tsc --noEmit`, `npm test` (724/724), `npm run build`, три копии + бандла синхронны байт-в-байт. Commit trailers всех 7 продуктовых/тестовых + коммитов диапазона (не считая двух `docs: review document…` от `claude[bot]`) + — `Issue: #89` / `User-Visible: no`, верно для Labs-скрытой фичи. +- **H1 закрыт исполнением**, не просто заявлением автора — см. отдельный + раздел выше. Это был единственный блокирующий пункт r2. +- **AC7 теперь полностью подтверждён исполнением.** В r2 AC7 был подтверждён + частично: room fills/hover, Glow/spill, декор/мебель, устройства — зелёные; + солнечная часть и полная DOM-order часть — не исполнялись (упавший тест). + Сейчас весь `demo/smoke_isometric_live_touch.mjs` (21 проверка, включая + `liveLayersPresent`, `liveLayersStable`, `spillBarrierStable`, + `floorToOverlayOrderPreserved`, `haColorUpdatePainted`, `sameWallFingerprint`, + `haUpdateReusesGeometry`, `flatIsoActionParity`, весь touch/kiosk/warm-remount + набор) — зелёный на реальном исполнении. +- **AC1–AC6, AC8–AC15 — код не менялся с r2**, где они уже подтверждены + исполнением и/или чтением (Labs-механизм, проекция/камера, топология стен + O(E), fallback-защёлка, editors always flat, отсутствие влияния на + backend/схему/вторую карточку/публичную документацию, отсутствие CSS 3D, + touch/kiosk-контракт, i18n). Самостоятельно перечитал весь diff + `src/houseplan-card.ts`, `src/labs.ts`, `src/iso-projection.ts`, + `src/iso-walls.ts`, `src/styles.ts` и соответствующие тесты в этом цикле + (не только отчёт r2) — не нашёл расхождений с описанным там поведением; + дополнительно самостоятельно перечитал `src/sun.ts` (`windowLit`, + `windowWallInfo`), которого r2 не разбирал построчно, и убедился, что + причина H1 объясняется корректно. +- **Регрессии.** Полный повторный прогон всех 127 браузерных смоков (не + только 126 «старых» + 1 новый, как в r2, а всё целиком, включая уже + исправленный) — 127/127 зелёных. Полный `golden:capture` — 41/41 + существующих сцен `passed` (0 diff), 6 новых iso-сцен `missing-baseline` + (правильно, эталоны не принимаются в этом коммите). +- **Perf-профиль.** Одноразовый прогон `large-house-isometric-v1` завершается + без исключений и пишет ожидаемые поля кэша; полный 7-sample budget-гейт — + pre-beta exact-SHA Linux CI, не гейт этого цикла (§8.2 ТЗ). +- **Визуальная sanity-проверка.** Открыл `isometric-geometry-view-dark.png` + и `isometric-live-layers-dark.png` из свежего `golden:capture`: повёрнутая + квадратная колонна («Nested NE») отрисована двумя концентричными ромбами со + смещением и соединяющим ребром — верная экструзия верх/бок; в + `isometric-live-layers-dark` видны тёплый Glow-спилл через проём, бейджи + устройств, температурные чипы и капсула вакуума поверх iso-геометрии — + живые слои пола не заменены статичной картинкой. + +## Чего не проверял + +- **Golden-эталоны для iso не принимал** — соответствует процессу + (`npm run golden:accept -- --reviewed` только по полному Linux CI + артефакту). Отсмотрел 2 из 6 `actual`-изображений визуально как + sanity-check, не как приёмку. +- **Полный 7-sample perf-сравнение с бюджетом** — по контракту ТЗ (§8.2) это + исключительно pre-beta exact-SHA Linux CI гейт; не воспроизводим локально + как гейт этого цикла. +- **HA-harness backend-тесты** (`test_ha_*.py`) — не запускал: в среде нет + Home Assistant/`pytest`; диапазон не меняет backend, гейт пуст по + построению. +- **Safari/WebKit и Firefox** — вне скоупа этого этапа по ADR; тестировал + только Chromium (движок CI `smoke`/`golden`). +- **`smoke_opening_measure.mjs`** — известно окруженчувствительный + (`AGENTS.md`); в моём прогоне прошёл (не красный), риск не проявился, но + это не специфичная для этого диапазона проверка. +- **Согласование нумерации ревью-документов между стадиями** (L2 выше) — + решение владельца/процесса, не код-ревью. + +## Вердикт + +**Зелёный · цикл r3/4 · High: 0 · Medium: 0 → нет новых issue.** + +Единственный блокирующий пункт предыдущего цикла (H1 — красный обязательный +смок `demo/smoke_isometric_live_touch.mjs`) закрыт минимальным точечным +исправлением тестовой фикстуры (`7a2577d`, один файл, одна строка) и +подтверждён повторным исполнением (21/21 green), а не просто заявлением +автора. Весь остальной диапазон не изменился с зелёного-по-фактам r2 и +самостоятельно перепроверен заново на чистой установке: typecheck/unit/build +зелёные, все 127 браузерных смоков зелёные, полный golden-прогон без диффа +существующих сцен, perf-профиль исполняется. Единственные оставшиеся находки +— три косметических Low (лишняя пустая строка, не влияет на поведение) и +одно процессное наблюдение о нумерации файлов ревью — обе сняты с записью, +без новых issue. Следующий статус — очередь на пре-релиз +(`S8-merged` после мёржа в `dev`, по PROCESS.md §2.7/AGENTS.md «Do not merge +into `dev` by hand»).