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

SPEC-REVIEW-307-r1

Issue: #307 · Этап: ТЗ (spec) · Трек: small · Заход: r1 · Вердикт: зелёный Блокирующих циклов израсходовано: 0/2 (лимит лёгкого трека, §4)

Скоуп

ТЗ (в теле issue #307, small-трек, шаблон §5: проблема · контракт · AC · откат) на исправление визуального дефекта инструмента «Стены» в редакторе плана: во время рисования цепочки уже поставленные (персистнутые) сегменты теряют осевую линию .pathline и узлы .vertex, потому что тело стены рисуется поверх них, а снап-оверлей намеренно исключает активный драфт из своей геометрии. Решение — вынести ось/узлы/rubber-band активной цепочки (.pathline, .vertex, .active-axis, .active-vertex) из _renderMarkupLayer в отдельный editor-слой между _renderWallBodies и _renderPlanSnapOverlay, ничего не меняя в геометрии снапа.

Затронутая поверхность — Plan editor (src/houseplan-card.ts, один модуль), только режим _markup/_editing; View не затрагивается. Персона — Home admin (единственная, кто пользуется редакторами, docs/SCOPE.md), контекст — задача J4/J6 («от нуля до плана» и «поддерживать план актуальным», два встроенных редактора). Изменение чисто композиционное (порядок отрисовки уже существующих DOM-узлов), без новых полей конфига, миграций, i18n-ключей.

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

Ревью читал ТЗ и тело/комментарий issue без устных пояснений автора, состязательно — искал, где контракт невыполним или непроверяем, а не соглашался с текстом. Каждое фактическое утверждение о коде и документации проверено чтением, а не принято на веру:

1. docs/SCOPE.md — подтвердил, что задача обслуживает J4/J6 и не задевает инвариант View/lock; продуктового конфликта нет.
2. docs/USER-GUIDE.ru.md:372-375 — дословно подтверждает цитату ТЗ: «поверх уже нарисованных стен видны тонкие осевые линии и точки их концов». Значит ожидаемое поведение — не догадка автора, а уже зафиксированный контракт; исключение для «ещё не завершённой цепочки» нигде не оговорено.
3. src/houseplan-card.ts — построчно сверил все технические утверждения ТЗ:
   • _renderMarkupLayer (:19960) действительно эмитит .pathline (:20029), .active-axis/.active-vertex (:20032-20036) и .vertex (:20038);
   • вызов _renderMarkupLayer (:17553) стоит до _renderWallBodies (:17565), которая, в свою очередь, стоит до _renderPlanSnapOverlay (:17582) — ровно та последовательность, что и в ТЗ;
   • _renderPlanSnapOverlay (:19843) и геометрия buildPlanSnapGeometry (src/plan-snap-overlay.ts:253) действительно пропускают активный драфт (if (draft.id === options.activeDraftId) continue) — второй заявленный механизм подтверждён, не выдумка;
   • physical-geometry.ts:210-221 подтверждает, что каждый персистнутый сегмент room_drafts немедленно попадает в непрозрачные тела (draftSegments/drafts) без исключения активного драфта — то самое тело, которое перекрывает ось;
   • «hit-слой», упомянутый в контракте как остающийся на месте элемент _renderMarkupLayer, — реален: _renderPhysicalEditorLayer() (:19711, вызывается на :20008) рисует .physical-hit (прозрачные линии/пути для перетаскивания драфтов/перегородок/колонн, pointer-events: none вне инструмента «Выбор», src/styles.ts:2256-2264) — контракт не подменяет несуществующим термином существующий механизм;
   • цвет #ffc14d из AC1 подтверждён как реальный stroke/fill .pathline и .vertex (src/styles.ts:1803-1857) — пиксельная проба технически осмысленна и отличима от штриховки масонри;
   • AC3 ссылается на существующий demo/smoke_plan_snap_overlay.mjs — файл существует.
4. docs/specs/228-plan-drawing-problems.md — беглая проверка, что active-axis/active-vertex действительно история #228 (проекция оси активного отрезка), заявленная в issue как смежная, не пересекающаяся работа — согласуется, конфликта скоупа нет.
5. Сверил критерии лёгкого трека (§5 PROCESS.md) построчно: сложность/риск ≤3 (аналитика — 2/10), одна поверхность, без миграции конфига, поведение уже описано в USER-GUIDE (не новый UX-контракт), перф/touch не задеты (перестановка существующих DOM-узлов, ни одного нового элемента). Шаблон ТЗ соответствует §5 буквально: проблема · контракт · AC · откат, файла в docs/specs/ нет — верно для small.
6. Комментарии issue — один, аналитика владельца (S2→S4, метка small поставлена и объяснена). Прежнего вердикта ревью ТЗ нет — это первый заход, раздел «Унаследовано из r0» не применяется.

Находки

Блокирующих (High/Medium) не найдено.

Один пограничный момент, не тянущий на находку, а не пропущенный молча: контракт не называет позицию нового слоя относительно _renderResizeMeasurements/_renderRoomHoverOutline/диагностического оверлея скрытых стен/превью размещения проёма — всех элементов, которые сейчас лежат между _renderWallBodies и _renderPlanSnapOverlay. Это не продуктовый вопрос: перечисленные оверлеи активны для других инструментов (resize/двери-окна) и не пересекаются по времени с активной цепочкой «Стены», кроме, возможно, подсветки наведённой комнаты (roomHover), которая может сработать параллельно с рисованием. AC2 не требует конкретной позиции внутри этого промежутка — только «тела → слой цепочки → снап-оверлей», и это достаточно проверяемо смоком. Оставляю как техническую деталь на усмотрение реализации, как и позволяет §7.1 («всё, чего пользователь не наблюдает, агенты решают сами»); не блокирует и не снижает вердикт.

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

• Оба продуктовых вопроса (что видит пользователь, какой объём входит в задачу) не требуют обращения к владельцу: ожидаемое поведение уже зафиксировано в USER-GUIDE.ru.md, объём — один модуль, одна визуальная причина с двумя техническими механизмами, обе описаны и обе имеют решение. Владельцу вопросов не задавалось — и это оправдано, а не пропущено.
• Причина дефекта — не догадка, выданная за факт: каждое утверждение о коде (номера строк, имена классов/функций, порядок вызовов, поведение buildPlanSnapGeometry) подтверждено чтением текущего dev (см. выше).
• Контракт однозначен: что именно переносится (.pathline, .vertex, .active-axis, .active-vertex), откуда, куда (между конкретными двумя существующими вызовами), что не меняется (геометрия/резолвер снапа, жёлтая стилистика, всё остальное содержимое markup-слоя).
• AC1-AC3 — каждый проверяем и указывает способ доказательства (smoke новый/существующий, ревью кода). AC1 задаёт конкретные пиксельные точки (середина оси первого сегмента, центр промежуточного узла) и конкретный ожидаемый цвет, отличимый от штриховки — тест способен упасть на текущем dev, что и заявлено явно («падает на текущем dev»). AC3 явно фиксирует границу: plan-snap-overlay.ts не входит в дифф.
• Откат тривиален и назван верно: одиночный revert, ни новых полей, ни миграций, ни persisted-состояний — соответствует характеру чисто композиционного изменения.
• Критерии лёгкого трека выполнены все одновременно, метка small не оспаривается.
• Не найдено расхождений ТЗ с docs/SCOPE.md, docs/USER-GUIDE.ru.md, docs/UX-MODES.md: изменение целиком внутри hp-editor-only-layer, гейтится this._markup, View не задет, инвариант блокировок (SCOPE.md, «The lock invariant») не касается геометрии стен.

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

• Не запускал код и не собирал бандл — на этапе ревью ТЗ кода ещё нет, проверка была по чтению текущего dev (git log показывает dev на 489f68ee, что совпадает с SHA, названным в аналитике owner). typecheck/test/build к этому этапу не относятся (это гейты код-ревью, §2.7).
• Не проверял, как новый слой будет вести себя при одновременной подсветке наведённой комнаты (roomHover) во время рисования цепочки — отмечено выше как техническая деталь реализации, не блокирующая ТЗ.
• Не оценивал производительность численно — оценка «перестановка тех же DOM-узлов» правдоподобна на глаз и совпадает с заявлением owner в аналитике, но замер не проводился (задача не требует его: §2.5 требует «влияние на производительность названо», а не измерено, когда оно очевидно нулевое).