houseplan-card/docs/reviews/SPEC-REVIEW-231-r1.md

SPEC-REVIEW-231-r1

• Issue: #231 — декоративный слой виден поверх заливок комнат
• ТЗ: docs/specs/231-decor-layer-order.md @ commit e023adb (dev)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4
• Вердикт: жёлтый · High: 0 · Medium: 1 (в скоупе, чинится в этом ТЗ)

Скоуп ревью

Первый заход, дельты нет — разбор ТЗ целиком: продуктовая рамка (docs/SCOPE.md), обязательные разделы §7.1 PROCESS.md, однозначность и доказуемость каждого AC, отсутствие догадок, выданных за решение, соответствие терминологии docs/USER-GUIDE.ru.md, согласованность с канонической документацией подсистемы (docs/BACKDROP.md, docs/DECOR-EDITOR.md, docs/CANVAS.md, docs/SUN.md) и с фактическим кодом.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md §2.4/§7.1/§7.2/§2.9/§2.10.
2. Прочитано тело issue #231 и все 6 комментариев: два уточнения владельца по целевой позиции слоя, аналитика, вопрос Q1 с default, решение владельца по Q1, финальный хендофф со ссылкой на ТЗ. Открытых продуктовых вопросов на момент ревью нет, blocked снят.
3. Прочитано ТЗ docs/specs/231-decor-layer-order.md целиком.
4. Сверено с фактическим кодом src/houseplan-card.ts:
   • подтверждён текущий порядок вызова _renderDecorLayer() (строка 16584) — он действительно предшествует рендеру заливок комнат (цикл с 16596), hover-заливке (16726), обычным тоннелям (16727), Glow-base комнат (16728), Glow-base тоннелей (16729), _renderGlowLayer (16730) и _renderSunRays (16731); стены (16747), символы проёмов (16763) и devlayer (16794) идут ещё позже. Абсолютные номера строк в теле issue (:16042…:16238) разошлись с HEAD (там сейчас :16584…), но порядок элементов, который единственно имеет значение для ТЗ, подтверждается независимо чтением кода — не является дефектом ТЗ;
   • целевая позиция ТЗ (между обоими проходами тоннелей и _renderGlowLayer) соответствует названным строкам 16729/16730;
   • проверено, что .decorlayer .dshape { pointer-events: none; } (src/styles.ts:1235) и включается только в .stage.mode-decor — утверждение ТЗ §9/§13 «decor не перехватывает tap/click вне редактора декора» верно независимо от DOM-позиции слоя, не является догадкой;
   • проверено .glow-pools-frame/.glow-pools/.glow-spot { isolation: isolate } (src/styles.ts:678) — комментарий у кода прямо говорит, что этот блок изолирует screen-blend от «room data fill, Glow base, paper and backdrop»; ТЗ §8.2 корректно описывает это как риск и явно требует не переносить decor молча, если целевая fixture покажет иной результат — не догадка, а обозначенное предположение (§19.2) с открытым эскейпом;
   • подтверждено, что houseplan-space-card не рисует decor вообще (grep decor src/space-render.ts — одно упоминание, к теме не относится);
   • подтверждено, что изометрический слой (iso-shadows-svg/iso-walls-svg, 16774–16782) — отдельные <svg> после закрытия основного плана, поэтому перестановка decor внутри основного SVG не меняет его позицию относительно 3D-стен; риск в таблице §16 корректен.
5. Проверено docs/BACKDROP.md — «Layer order» там даёт грубую группировку («sun / walls / openings / rooms / decor» одним пунктом), которая не различает internal order и в этом и есть источник бага; ТЗ верно ставит её актуализацию в release-артефакты (§18).
6. Проверено docs/DECOR-EDITOR.md — контракта видимого порядка в View там нет вообще (только editor-opacity), обновление не требуется, ТЗ не настаивает («при необходимости») — согласовано.
7. Проверено docs/CANVAS.md («who owns the pointer», «Architectural connection overlay») и docs/SUN.md (four-phase background) — оба документа говорят о decor на уровне, который порядок внутри плана не меняет; актуализация не нужна, ТЗ их не трогает — корректно.
8. Проверена регистрация ТЗ в docs/specs/README.md:71 — присутствует.
9. Проверены существующие смоки: demo/smoke_decor.mjs, demo/smoke_decor_text.mjs, demo/smoke_hide_layers.mjs, demo/smoke_backdrop.mjs, demo/smoke_glow.mjs (hoverLayerOrder, строки 244–261) — ни один не проверяет порядок decor относительно hover-заливки комнаты (см. находку ниже).
10. Прогон гейтов для ревью спецификации не требуется (диапазон правок — документация ТЗ и issue, продуктовый код не менялся); git diff --check и node scripts/check-docs.mjs --external, упомянутые автором в хендоффе, достаточны для этого этапа и не перепроверялись повторно — они не относятся к предмету ревью (корректность и доказуемость контракта), а к гигиене коммита ТЗ.

Находки

Medium (в скоупе — чинится в этом же ТЗ)

M1. Нормативная позиция decor относительно room hover fill не имеет привязанного AC/доказательства.

• Где: docs/specs/231-decor-layer-order.md §8.1 (нормативный порядок слоёв, пункт «room hover fill» между room fills и opening tunnels) и §14 (AC1–AC8).
• Суть: §8.1 явно требует: «любой [data-hp="decor"] следует в DOM после room fill, hover fill, обоих видов тоннелей и Glow-base» — hover-заливка комнаты прямо включена в обязательный нижний контур. Однако ни один AC этого не проверяет:
  • AC1 говорит про «room fill» (заливку), не про hover;
  • AC2 перечисляет ровно три вещи, после которых должен идти decor — «обычный тоннель, Glow-base комнаты и Glow-base тоннель» — hover fill в списке нет;
  • AC3 описывает верхнюю границу (Glow/солнце/стены/символы/устройства), тоже не про hover. Значит Goal 5 из §5 («Защитить порядок… тестом, который падает при возврате старого расположения слоя») в этой конкретной паре (decor vs hover fill) не реализуется ни одним названным доказательством. Существующий demo/smoke_glow.mjs уже умеет сравнивать DOM-позицию (hoverLayerOrder, строка 260: hoverFillLayer.compareDocumentPosition(glowLayer)), но decorlayer в нём не упоминается вовсе — расширить эту же проверку стоит недорого.
• Сценарий отказа: реализация вставляет decor куда-то между room fill и Glow-base (что удовлетворяет AC1/AC2/AC3 буква в букву — «после обычного тоннеля» и т.д. формально не нарушены только если decor вставлен после тоннелей, но ничего не мешает случайно вставить decor до hover fill, например прямо перед строкой рендера hover — тоннели и Glow-base всё ещё идут после него по факту кода, так что AC2 останется зелёным, а на реальном плане при наведении на комнату с decor внутри hover-подсветка ляжет поверх декоративной линии/фигуры, а не под неё, что расходится с §8.1 и остаётся недоказанным дефектом.
• Почему не High: это пробел в покрытии доказательства, а не неверное продуктовое решение — сам порядок (decor после hover fill) уже прямо задан диаграммой владельца в теле issue (позиции :16202 до целевой :16205→:16206) и корректно перенесён в §8.1; чинится добавлением одной фразы в AC2 (или отдельного AC) и одной строки в план тестов (§15.1/§15.2), без обращения к владельцу.
• Что сделать: явно включить hover fill в формулировку AC2 (например: «…после hover fill, обычного тоннеля, Glow-base комнаты и Glow-base тоннеля…») и добавить в §15.2/§15.1 конкретное доказательство — расширение smoke_glow.mjs/hoverLayerOrder или отдельный targeted-assert на compareDocumentPosition между .room-hover-fill-layer и .decorlayer.

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

• Продуктовая рамка: сценарий, персона, «что человек увидит до/после» — присутствуют, соответствуют docs/SCOPE.md/аналитике владельца в issue (владелец сам отнёс задачу к J1 в комментарии-аналитике; повторно отдельно в ТЗ можно не обосновывать).
• Все обязательные разделы §7.1 PROCESS.md на месте: сценарий, что увидит человек, проблема, скоуп/не-скоуп, контракт поведения (§8–§9), UX (§10), данные/миграция/i18n (§11), AC1–AC8 (кроме отмеченного пробела), план автотестов (§15), риски (§16), откат (§17), release-артефакты (§18).
• Явный блок «Принятые предположения» (§19) присутствует и корректно помечает как assumption именно то, что действительно не было продиктовано владельцем дословно (например, что Glow-base — часть пола, а live Glow/солнце — часть света) — не выдаёт догадку за факт, ревьюер может её оспорить (не оспариваю: подтверждается разделением функций _renderGlowBaseRooms/_renderGlowLayer в коде).
• Причина бага (§3) точно подтверждена чтением кода — вызов decor действительно предшествует рендеру комнат.
• Решение владельца по Q1 (без нового флага «под планом», единый порядок для старого и нового decor) корректно и полностью перенесено в §8.3/§19.1, без расширения скоупа.
• Открытый технический риск с Glow/CSS isolation (§8.2) не замалчивается: ТЗ прямо требует не переносить decor поверх live Glow «молча» и возвращать вопрос владельцу, если fixture покажет иное — правильная эскалация вместо догадки.
• «Не входит в задачу» (§7) корректно исключает per-object флаг, изменение геометрии старого декора, любые изменения заливки/Glow/солнца/стен, добавление decor в статическую карточку и в скрытую изометрию отдельным рендерером, новый UI/i18n/миграцию.
• Touch/UX (§10): корректно ссылается на docs/TOUCH-SUPPORT.md, не создаёт новых focus targets/жестов; View/kiosk-контракт (блокирующий по TOUCH-SUPPORT.md) не расширяется и не сужается.
• Данные/миграция/i18n (§11): корректно — рендер-порядок не персистентное поле, миграция не нужна, что подтверждается отсутствием изменений в custom_components/houseplan/validation.py/типах decor.
• AC5 (documented mutant) явно требует, чтобы smoke падал по существу (AC1/AC2), а не просто по отсутствию DOM-узла — соответствует духу scripts/mutation-gate.mjs и извлечённому там же уроку про тесты, которые «ни разу не проверяли на способность падать».
• Golden-план (§15.3) корректно ограничивает принятие эталона отдельным reviewed Linux-артефактом, Windows — только диагностика; согласуется с AGENTS.md.
• Регистрация ТЗ в docs/specs/README.md на месте.

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

• Не проверял и не мог проверить визуальный результат Glow-blend на decor в браузере — эта проверка относится к этапу реализации/код-ревью (targeted fixture, §8.2), на этапе спецификации нет кода, который можно запустить.
• Не прогонял тяжёлые гейты (typecheck/test/build/golden/smoke) — на этом этапе продуктовый код не менялся, они не относятся к предмету ревью ТЗ и будут частью код-ревью.
• Не проверял docs/TESTING.md на предмет уже существующей документации layer-order/mutant contract для decor — в текущей редакции ТЗ такого описания там нет, и ТЗ (§12) верно относит его актуализацию к зонам изменений реализации, а не к самой спецификации.
• Не оценивал производительность фактически (нет кода) — только сверил, что §13 не описывает новых наблюдателей/таймеров/network calls, что достаточно для стадии ТЗ.

Резюме

Одна находка Medium в скоупе (M1 — отсутствует доказательство для одной конкретной, но явно нормативной, границы порядка: decor относительно room hover fill). High-находок нет. Остальной контракт — порядок слоёв, hide/editor parity, компат старого decor, touch/UX, данные/i18n, release-артефакты — точен, проверяем и обоснован чтением кода, а не заявлением автора. Вердикт: жёлтый, возврат автору на правку ТЗ (добавить hover fill в AC2 и тест-план), без обращения к владельцу.