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

SPEC-REVIEW-141-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/141
• ТЗ под ревью: docs/specs/141-wall-junctions.md (коммит 59c66dd, ветка issue/141-wall-joints)
• Роль: ревьюер ТЗ (не автор), этап S4-spec-review
• Трек: обычный (не small/trivial) — сложность/риск 7/10, две+ поверхности (перегородки/drafts и рисование комнатных стен), влияние на golden, свет и производительность; лёгкий/короткий трек владелец и автор корректно не применили.
• Цикл: r1/4

Скоуп ревью

Проверялось соответствие ТЗ:

• docs/SCOPE.md — попадание в Core user jobs, отсутствие расширения скоупа;
• PROCESS.md §2.4, §2.5 (DoR), §7.1 (обязательные разделы), §3/§12 (запреты);
• AGENTS.md — классы файлов, ветка, трейлеры коммита ТЗ;
• каноническим документам: docs/WALL-THICKNESS.md (модель толщины, mitre/bevel, union тел), docs/LIGHT.md (барьеры/_lightBarriers), docs/SUN.md (occluders), docs/ISOMETRIC.md (wallBodiesGeometry + extra physical bodies), docs/CANVAS.md (координаты/масштаб), docs/TOUCH-SUPPORT.md (best-effort editors), docs/CONFIG-COMPATIBILITY.md (миграция — в задаче её нет, но проверено, что это верно);
• docs/USER-GUIDE.ru.md — терминология «Контур комнаты» / «Перегородка»;
• фактическому коду (src/wall-thickness.ts, src/physical-geometry.ts, src/houseplan-card.ts) — на предмет того, что технический диагноз ТЗ не является непроверенной догадкой, выданной за факт.

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

1. Прочитан весь тред issue #141: исходное описание с уточнением владельца («проявляется и на прямых, и на непрямых углах»), полная аналитика (ценность 8/10, сложность/риск 7/10, P2, тип bug, полный трек) с Q1–Q3 и явными defaults, решение владельца «принимаю все defaults», финальный комментарий автора со ссылкой на коммит ТЗ.
2. Сверены обязательные разделы ТЗ (§7.1 PROCESS.md) построчно — таблица ниже.
3. Прочитан код и подтверждены построчно все технические утверждения §3 ТЗ:
   • drawWallPreviewD() (src/wall-thickness.ts:490) действительно строит outset−inset только для closed-контура (:496); открытый путь — независимый quad на каждый сегмент (:512-529). Диагноз ТЗ п.1 точен.
   • partitionBody() (src/physical-geometry.ts:41) строит прямоугольник с плоскими торцами без топологии узла; physicalBodies() (:89) просто собирает такие прямоугольники в список. Диагноз ТЗ п.2 точен.
   • MITRE_LIMIT = 4 (src/wall-thickness.ts:28) и его использование в трёх местах (:669, :1429, :1805) существуют — ссылка ТЗ §7.2.3/AC3 не изобретена.
   • Изометрия (src/houseplan-card.ts:4606-4611) уже вызывает wallBodiesGeometry(..., extras) с extras = physicalBodies(...) — значит full/static/iso уже объединяют независимые тела через wallBodiesUnionPath/wallBodiesGeometry (тот же приём подтверждён в src/space-render.ts:338 для статической карточки). Ровно то, что ТЗ утверждает в §3.5 и §8.2 («full/static/isometric render уже объединяют…»).
   • _lightBarriers() (src/houseplan-card.ts:13556) вызывает wallBodiesGeometry() без extras (:13623) и затем отдельно кладёт сырые ребра каждого physical-тела в occluders (:13637: for (const body of physical) occluders.push(...polygonSegments(body));). Солнце (src/houseplan-card.ts:12705-12716) вызывает directionalOccluders(physical, ...) напрямую на тех же сырых прямоугольниках. Это подтверждает диагноз ТЗ §3.5/§8.2: свет и солнце сегодня действительно обходят raw-прямоугольники отдельно от joined-пути рендера, а не голословное утверждение.
   • floorMinusBodies() вызывается с тем же _physicalBodiesR() (сырые тела) и для чистой площади (:7366, :7388), и для проверки source-inside (:11655) — совпадает с AC8.
4. Прочитан docs/WALL-THICKNESS.md целиком: подтверждён существующий контракт mitre/bevel для комнатных стен (§3) и отдельный раздел «9. Independent partitions, drafts and columns» — независимые тела уже юнионятся с комнатными только после вырезов проёмов и участвуют в clean-floor/Glow/sun occlusion. ТЗ §7.3.2, §9 и AC6/AC10 корректно продолжают именно эту, а не новую, модель.
5. Прочитан docs/LIGHT.md и docs/SUN.md: подтверждено, что _lightBarriers держит один общий барьерный набор на пространство и кэшируется по геометрическому fingerprint, а не по _cfgEpoch — ТЗ §8.3.1-2 корректно продолжает существующий кэш-контракт, не изобретая новый механизм инвалидации.
6. Прочитан docs/ISOMETRIC.md: src/iso-walls.ts явно описан как потребитель «канонического wallBodiesGeometry() MultiPolygon after openings and extra physical bodies have been resolved» — буквально подтверждает ТЗ §8.2 («full/static/isometric не создают разные join алгоритмы»), т.е. это не домысел автора, а прямая цитата канона.
7. Прочитан docs/TOUCH-SUPPORT.md: политика требует, чтобы «новые спецификации editor-фич и код-ревью» явно указывали одно из трёх значений Touch editor: supported / best effort / not exposed. ТЗ §10 описывает ровно best-effort-поведение словами, но не использует эту точную метку — см. Low-1.
8. Прочитан docs/USER-GUIDE.ru.md (раздел «Создание комнаты», таблица «Инструменты плана», раздел «Виртуальные стены»): термины «Контур комнаты» и «Перегородка» в ТЗ (§4.1, §5.3 и др.) совпадают с интерфейсным словарём ровно там, где употребляются полностью; там же нашёл существующую строку «Углы | Соседние тела стен соединяются…» (:347) — актуальное описание, которое release-артефакты ТЗ (§15) обязывают дополнить для partitions — корректно учтено.
9. Прочитан src/types.ts:45-72 — RoomDraftCfg, PartitionCfg, space.room_drafts, space.partitions существуют как реальные поля схемы, а не придуманы для ТЗ; AC4/AC5 про кросс-типовые соединения (partition↔partition, draft↔partition, partition/draft↔room wall) технически имеют смысл на этой модели.
10. Проверена запись docs/specs/README.md:85 — строка на #141 добавлена в том же коммите; ссылка issue ↔ ТЗ двусторонняя (ТЗ ссылается на issue в заголовке, issue-комментарий ссылается на файл ТЗ и коммит).
11. Проверены трейлеры и class-принадлежность: git diff --stat origin/dev...HEAD показывает только docs/specs/141-wall-junctions.md и docs/specs/README.md (класс C, ни одного файла класса A); коммит 59c66dd несёт Issue: #141 и User-Visible: no — корректно для документа ТЗ, который сам не меняет поведение.

Обязательные разделы (§7.1 PROCESS.md)

Раздел	Есть	Комментарий
Сценарий (персона/поверхность/момент)	✅	§1 — домашний администратор, desktop Plan editor, момент второго клика
Что человек увидит до/после	✅	§2, «До:»/«После:» — см. Low-2
Проблема (с подтверждённой причиной)	✅	§3, шесть пунктов, все проверены по коду (см. выше)
Скоуп / не-скоуп	✅	§5 / §6, явные границы (без snap #137, без нового cap, без #138)
Контракт поведения	✅	§7 (геометрия) + §8 (архитектура)
Модель данных и миграция	✅	§9 — явное «schema не меняется», «читается исправленно, без записи»
UX, i18n, accessibility, touch	✅	§10 — см. Low-1
AC1…ACn с доказательством	✅	§12, 13 штук, каждый с типом доказательства и наблюдаемым результатом
План автотестов	✅	§13, по подпунктам на unit/smoke/golden/performance
Риски	✅	§16, таблица с вероятностью/ущербом/снижением
Откат	✅	§17
Release-артефакты	✅	§15, конкретный список файлов документации и обоих changelog

Все обязательные разделы присутствуют и содержательны. Дополнительно есть раздел «Решения владельца» (§4, явно фиксирует принятые Q1–Q3), архитектурный контракт (§8), план реализации (§14, помечен как техническая свобода) и явный блок «принятые технические предположения» (§18) — соответствует духу PROCESS.md §7.1 об отделении продуктового решения от технического.

Находки

Находок уровня High и Medium нет — новых issue не требуется.

Low-1 — нет явной метки touch-контракта по docs/TOUCH-SUPPORT.md

Файл: docs/specs/141-wall-junctions.md:252-261 (§10)

docs/TOUCH-SUPPORT.md требует: «New editor feature specifications and code reviews must state one of: Touch editor: supported; Touch editor: best effort / intentionally degraded; Touch editor: not exposed.» §10 ТЗ по существу описывает best-effort-контракт словами («Plan editor остаётся desktop-first… новый hover parity не обещается») и корректно ссылается на safety floor (сохранённая geometry тапнутого сегмента должна совпадать), но не использует ни одну из трёх канонических формулировок буквально.

Решение ревьюера: Low, не блокирует. При следующей правке ТЗ или в хендоффе код-ревью достаточно добавить одну строку Touch editor: best effort / intentionally degraded — по содержанию это именно то, что §10 уже описывает.

Low-2 — «что человек увидит» длиннее одной фразы

Файл: docs/specs/141-wall-junctions.md:28-37 (§2)

PROCESS.md §7.1 требует «одной фразой, без терминов реализации». Раздел написан двумя короткими абзацами («До:» / «После:»), по одному предложению каждый; по существу требование выполнено (без терминов реализации, конкретно и однозначно), но формально это не «одна фраза». Тот же класс находки уже фиксировался как Low и не блокировал приёмку в SPEC-REVIEW-137-r1.

Решение ревьюера: Low, не блокирует. Косметическая правка на усмотрение автора.

Low-3 — доказательство AC10 («code review») до кода не проверяемо, но это ожидаемо для code-review-этапа

Файл: docs/specs/141-wall-junctions.md:315-321 (AC10, AC11)

AC10 и AC11 указывают доказательство «unit + code review» / «performance + code review» — это не входит буквально в список §2.5 PROCESS.md (unit/backend/smoke/golden/«ревью кода»), но «code review» — это то же самое «ревью кода» иначе сформулированное, и AC11 корректно называет performance, обязывая код-ревьюера прогнать performance-профиль по правилу «гейты соразмерны AC» (PROCESS.md §8). Не дефект по существу, тот же класс находки не блокировал SPEC-REVIEW-137-r1 (Low-3 там).

Решение ревьюера: Low, не блокирует. Оставить как есть.

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

• Соответствие docs/SCOPE.md: задача закрывает J4 («от нуля до плана без внешнего редактора» — администратор должен доверять форме стены в момент рисования, не после замыкания) и J6 («план остаётся правдивым по мере развития» — независимые перегородки не деградируют в кривую геометрию навсегда). Обе строки Closed — это исправление дефекта внутри принятой функциональности, не расширение продукта.
• Легитимность полного трека: сложность/риск 7/10, минимум две поверхности (перегородки и рисование стен комнаты), влияние на golden, свет и производительность — критерии small/trivial (§5/§5.1 PROCESS.md) не выполняются ни по одному пункту; полный трек выбран верно.
• Продуктовые вопросы закрыты по процессу: Q1 (какие соединения входят), Q2 (нормализуется ли rubber-band до клика) и Q3 (что делать со свободными торцами) заданы одним пакетным комментарием, каждый с предлагаемым default, issue корректно ушёл в blocked+S3-spec до ответа и вышел из blocked сразу после решения владельца. Ни одна догадка не выдана за факт без пометки — §18 отдельно и явно перечисляет технически свободные решения и прямо фиксирует «нет открытых продуктовых вопросов» (§18.10).
• Технический диагноз не голословен. Все шесть пунктов §3 (независимый путь drawWallPreviewD, плоские торцы partitionBody, отсутствие топологии узла в physicalBodies, отдельный путь mitre для закрытого контура, частичное объединение в full/static/iso против необъединённых barriers у Glow/sun, неподтверждённость отдельного дефекта свободного торца по скриншоту) построчно проверены по исходному коду и совпадают с ним — см. «Как проверялось» п.3.
• Не-скоуп (§6) корректно отсекает соседние соблазны: snap-tolerance/#137, автоматическое дробление persisted-геометрии, превращение partition в границу комнаты/HA-зону, новый persisted junction-тип и миграция, новый cap/join selector, #138 (замыкание контура по углам существующей комнаты) — все явно исключены с указанием, почему это не эта задача.
• Регрессионные гарантии сформулированы явно: AC10 поимённо защищает проёмы комнатных стен, virtual-T, nested/partial стены, экстерьер #123 и колонны — то есть ровно те механизмы, которые уже используют MITRE_LIMIT/union и могли бы негласно пострадать от новой топологии узлов.
• Производительность: §11/AC11 корректно ссылаются на существующую 60-partition фикстуру large-house-v1 и явно запрещают full-house boolean union на каждый pointermove/HA-tick (§8.3.3) — согласуется с docs/LIGHT.md («barriers keyed by geometry fingerprint, never _cfgEpoch») и не вводит новый бюджет без решения процесса.
• Модель данных и миграция (§9): корректно заявлено «schema не меняется», «читается исправленно без записи», без прямой/обратной миграции — сверено с docs/CONFIG-COMPATIBILITY.md: задача не создаёт нового compatibility-случая, потому что не меняет persisted-представление.
• Release-артефакты (§15) перечисляют конкретные существующие документы (WALL-THICKNESS.md, LIGHT.md, SUN.md, ISOMETRIC.md, ARCHITECTURE.md, TESTING.md, STATUS.md, USER-GUIDE.ru.md) и оба changelog в одном implementation-коммите — соответствует §7.1/правилу 11 PROCESS.md. Golden корректно ограничен принятием только через npm run golden:accept -- --reviewed по полному Linux-артефакту (§13.3), perf/golden/browser-suite верно отнесены к пре-релизному, а не implementation-гейту (§8, §11.4 PROCESS.md).
• Откат (§17) корректно опирается на отсутствие миграции данных: revert implementation-коммита восстанавливает прежний (дефектный) визуал без риска для сохранённых данных.
• Трассируемость: docs/specs/README.md:85 обновлён тем же коммитом (59c66dd); ветка issue/141-wall-joints и трейлеры (Issue: #141, User-Visible: no) корректны для документа класса C, который сам не меняет поведение. git diff --stat origin/dev...HEAD не содержит ни одного файла класса A — продуктовый код не тронут до S5-ready (правило №1).

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

• Не проверял реализуемость «одного чистого вычисляемого frame» (§8.1) как конкретной структуры данных/API — по правилам ТЗ это явно свободное техническое решение автора кода (§18.2), не предмет ревью ТЗ.
• Не запускал автотесты, golden, performance или browser-смоки — на этапе spec это не требуется; существование фикстур (large-house-v1, реальные поля схемы, конкретные функции и их поведение) проверено чтением кода, а не исполнением.
• Не проверял, что boolean-decomposition конкретной реализации (mitre patch для узла степени 3+, T-разрез сквозного сегмента) технически осуществима средствами polyclip-ts в разумное время — это открытое для автора кода техническое решение, отмеченное в ТЗ как свободно изменяемое (§18.3), и фактическая проверка бюджета (AC11) относится к код-ревью и пре-релизному гейту.
• Не проверял корректность конкретных числовых оценок аналитики (8/10 · 7/10 · P2) по существу — это поле владельца (PROCESS.md §2.2), уже принято явным решением владельца до написания ТЗ.
• Не проверял связанные issue #123/#137/#138 по существу за пределами того, что понадобилось для верификации ссылок ТЗ (регрессия #123, снэп #137, разграничение с #138) — они не входят в предмет этого ревью.

Вердикт

Зелёный. High: 0, Medium: 0. Три находки Low (отсутствие буквальной метки touch-контракта по docs/TOUCH-SUPPORT.md; «что человек увидит» длиннее одной фразы; типы доказательства AC10/AC11 вне буквального перечня §2.5) — ни одна не блокирует приёмку, все либо правятся косметически при следующей редакции, либо снимаются этой записью без нового цикла.