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

SPEC-REVIEW-53-r1 — Экспорт пространства в PDF: чистый архитектурный план

• Issue: https://github.com/Matysh/houseplan-card/issues/53
• Этап: ТЗ на ревью (PROCESS.md §2.4), полный трек
• Заход: r1 (первый цикл ревью этого ТЗ) · блокирующих циклов израсходовано 0 из 4 до этого раунда
• Материал: docs/specs/053-pdf-export.md на коммите cc93e93da9277a5e20c677e35ea1a0be0af57791 (ветка issue/53-pdf-export; коммит 48a17f5d в теле issue устарел на момент ревью — cc93e93d содержит уточнение владельца по внутренним/внешним размерам и является актуальной версией ТЗ), сопутствующая правка docs/specs/052-view-dimensions.md на том же коммите.

Скоуп ревью

Первый цикл — разбор полный (§2.10 не применяется, предыдущего раунда нет). Проверялись: обязательные разделы ТЗ (PROCESS.md §7.1), однозначность и доказуемость AC1–AC15, отсутствие выданных за факт догадок, соответствие терминологии docs/USER-GUIDE.ru.md, соответствие контракту #52 (docs/specs/052-view-dimensions.md), согласованность с каноническими документами подсистем (docs/SUN.md, docs/WALL-THICKNESS.md, docs/BACKDROP.md, docs/FURNITURE.md, docs/TOUCH-SUPPORT.md), продуктовая рамка docs/SCOPE.md.

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

• Прочитаны целиком: docs/SCOPE.md, AGENTS.md, PROCESS.md (§2.3–2.10, §7.1–7.3), тело issue #53 и все 7 комментариев, docs/specs/053-pdf-export.md и docs/specs/052-view-dimensions.md на cc93e93d.
• Каждое техническое утверждение ТЗ, которое можно свести к конкретному имени символа/файла/поля, сверено с кодом и документацией отдельным проходом (см. таблицу ниже) — не принято на слово ни одно нетривиальное заявление.
• Изучены существующие прецеденты процесса (docs/reviews/SPEC-REVIEW-473-*, docs/reviews/SPEC-REVIEW-445-r1.md) для калибровки формата вердикта и допустимости ручного способа доказательства (AC12).
• Дешёвые гейты не гонялись: на этапе ревью ТЗ они не предусмотрены (в репозитории ещё нет кода фичи — src/pdf/** не существует); это ревью контракта, а не кода.

Сверка технических утверждений ТЗ с фактическим состоянием кода

Утверждение ТЗ	Где смотрел	Итог
§7.1 — spaceModels(cfg) даёт wall_segments, partitions, wall_columns, проёмы door/window/gate/passage	src/space-geometry.ts:135-189, src/types.ts:80-83,218	подтверждено дословно
§7.5 — резолвер севера: сначала компас пространства, потом общий north_deg, «тот же, что у солнца»	src/sun.ts:667-671 (northDegOf)	подтверждено, порядок совпадает
§7.6 — поля подложки plan_x/plan_y/plan_scale*, поворот, подписанный доступ «как на экране»	docs/BACKDROP.md:11-19, src/signing.ts, src/logic.ts:1877, src/space-geometry.ts:165	подтверждено
§7.4 — decor[], furniture-art-runtime, kind: 'image'	scripts/config-schema.json:448, src/space-render.ts:338,637, src/furniture-art-runtime.ts, src/decor-assets.ts:33,41,117	подтверждено
§7.1/§8 — geometryArea = резолвер площади карточки комнаты	src/physical-geometry.ts:424, src/houseplan-card.ts:9930-9963,12455-12457 (_cleanFloor → geometryArea → formatArea)	подтверждено
§7.3 — «числа совпадают с живой линейкой ресайза на том же ребре» (грань-в-грань, а не по оси)	src/houseplan-editor-runtime.ts:3708-3729 (_rszEdgeLabels/_rszInnerSpanCms), явный комментарий: «Длины — между внутренними гранями... Раньше здесь считалась осевая длина... (#233)»	подтверждено: линейка ресайза с #233 действительно грань-в-грань, а не осевая — заявление ТЗ верно (проверял отдельно, т.к. 052-view-dimensions.md описывает именно осевую длину для другого, никогда не реализованного слоя — это не тот же измеритель)
§8.2 — образец iso-scene-render, lazyIsometricFiles, терминальный отказ с нонсом	src/iso-scene-render.ts:50, src/editor-runtime-loader.ts:8-11,54, src/houseplan-card.ts:341-344,761-774, scripts/bundle-manifest.mjs:108, scripts/bundle-budget.mjs:280,297	подтверждено
§11 — потолок houseplan-card.ts 13659, факт 13563 после #478	test/core-file-budget.test.mjs:22 (CAPS['src/houseplan-card.ts'] = 13659), wc -l src/houseplan-card.ts = 13563	подтверждено, запас 96 строк — арифметика верна
§8.5 — кнопка между «Общие настройки» и «Помощь и обратная связь»	docs/USER-GUIDE.ru.md:58,2078	терминология и порядок совпадают
§1 — «диалог обязан работать пальцем»	docs/TOUCH-SUPPORT.md — таблица: «View dialogs and safe device actions» → touch: Fully supported; кнопка живёт в том же блоке шапки, что и «Помощь и обратная связь», доступном в View для _canEdit	обоснованно, не голословно
§15 — «< 200 мс на large-house фикстуре, 60 комнат»	demo/fixtures/large-house.mjs:8-9,198-205 (FLOOR_COUNT=3, ROOMS_PER_FLOOR=20, spaces = Array.from({length: FLOOR_COUNT}, ...), каждое пространство получает свои 20 комнат)	не подтверждено — см. Medium-4
§11 — «docs/SCOPE.md (исключение 2026-08-15 — уже записано, проверить формулировку)»	docs/SCOPE.md (полный текст, grep 53|PDF|2026-08-15), git log --oneline -- docs/SCOPE.md (последний коммит, трогавший файл, — задолго до 2026-08-15)	не подтверждено — см. Medium-1

Из двенадцати проверенных фактических утверждений десять подтвердились дословно — автор ТЗ последовательно сверялся с кодом, а не описывал желаемое. Ниже — находки по двум неподтвердившимся пунктам и по двум местам внутренней несогласованности контракта.

Находки

Medium-1 — docs/SCOPE.md не содержит заявленного исключения для #53

Раздел 11 ТЗ утверждает: «docs/SCOPE.md (исключение 2026-08-15 — уже записано, проверить формулировку)». Это неверно: в docs/SCOPE.md нет ни одного упоминания issue #53, PDF-экспорта или даты 2026-08-15. git log --oneline -- docs/SCOPE.md показывает, что последний коммит, трогавший файл, относится к периоду задолго до 2026-08-15 (v1.62-эры), и раздел «Excess-functionality audit (2026-07-22)» — единственная запись такого рода в файле, к #53 не относящаяся.

Комментарий владельца от 2026-08-15 в самой issue («Владелец подтвердил исключение из docs/SCOPE.md: #53 остаётся в продуктовой очереди») — это решение по scope, а не запись в самом guard-rail документе. Прецедент есть: для #89 (2.5D-изометрия) исключение записано прямо в тексте SCOPE.md («A narrow exception approved for #89 is a deterministic 2.5D presentation of the existing canonical plan...», строка ~103). #53 такой записи не получил.

Почему это находка, а не мелочь. AGENTS.md называет SCOPE.md guard rail'ом: «features are built, improved and accepted only if they serve a job listed here». Печатный архитектурный экспорт прямо конфликтует с пунктом Out of scope («Photorealistic rendering... → niche tools») — этот конфликт и разбирался в комментариях 2026-08-14/2026-08-15/2026-08-30, и исключение из него принято владельцем трижды подряд (2026-08-15, 2026-08-30 подтверждение, 2026-09-07 сужение скоупа). Формулировка ТЗ «уже записано» означает, что реализатор с высокой вероятностью не добавит запись в SCOPE.md вовсе — раздел 11 не просит этого сделать, только «проверить формулировку» несуществующего текста. Без записи следующий, кто откроет SCOPE.md за поиском причины, почему в out-of-scope зоне лежит печатный architectural-tooling экспорт, её не найдёт — ровно то расхождение, которое guard rail обязан предотвращать.

Воспроизведение:

grep -n "53\|PDF\|2026-08-15" docs/SCOPE.md   # пусто, кроме несвязанных совпадений
git log --oneline -- docs/SCOPE.md | head -1  # последний коммит — не после 2026-08-15

Как чинится в этом же раунде: раздел 11 переписывается с «уже записано» на «требуется добавить запись» — короткий абзац в docs/SCOPE.md (Out of scope или Excess-functionality audit) по образцу #89, со ссылкой на issue #53 и обеими датами решений (2026-08-15, 2026-09-07). Это документация (класс C), не блокирует объём остального ТЗ.

Medium-2 — Коллизионное правило противоречит гарантии «нельзя опускать» для непрямоугольных комнат

§7.3, абзац «Внутренние размеры комнаты», формулирует твёрдую гарантию: «Для непрямоугольных контуров опускать нельзя: каждое ребро — свой размер.» Этим же абзацем обосновано ключевое AC5 («по этим числам комната вычерчивается автономно») и свидетель pdf-room-edge-dropped («у непрямоугольной комнаты пропущено ребро — контур невосстановим»), т.е. пропуск ребра непрямоугольной комнаты явно объявлен дефектом.

Но абзац «Коллизии» того же раздела описывает обратное для того же случая: «подпись... скрывается (кроме случая «непрямоугольный контур» — там уменьшается кегль до 6 pt прежде чем скрыться)». Формулировка «прежде чем скрыться» — это не альтернатива скрытию, а отложенный шаг перед ним: если подпись не помещается даже 6-м кеглем (плотный план, комната с 5+ рёбрами рядом с другими подписями — ровно сценарий, для которого в §16 заведён риск «по 4+ числа на комнату» и golden на large-house), правило коллизий её всё равно скрывает. Это прямое противоречие: один и тот же раздел одновременно запрещает и разрешает пропуск ребра непрямоугольной комнаты.

Почему это находка, а не общая забота о вёрстке. AC5 — центральный AC этого ТЗ (реализация уточнения владельца от 2026-09-07, ради которого #52 был закрыт и слит с #53). Если приоритет коллизий в реализации выигрывает у «нельзя опускать» (что текст явно допускает своей формулировкой), AC5 будет молча нарушаться на плотных планах — то есть ровно там, где риск и назван. Автор теста для AC5/свидетеля pdf-room-edge-dropped не может однозначно решить, должен ли он проверять «никогда не пропущено» или «пропущено только после исчерпания уменьшения кегля», не имея ответа в тексте контракта.

Как чинится в этом же раунде: одно из двух — либо у непрямоугольного контура исключить хвостовое «скрывается» полностью (после 6pt — минимальная короткая засечка без числа по аналогии с правилом < 30 см, но для любой длины при коллизии, а не только для короткого ребра), либо явно ограничить «нельзя опускать» примечанием «в пределах листа при разумной плотности» и завести отдельный, честно описанный fallback для перегруженного случая. Оба варианта укладываются в один абзац §7.3.

Medium-3 — AC6 проверяет правило, которого нет в контракте внешних размеров

AC6: «...текст не вверх ногами; коллизии детерминированы; рёбра < 30 см — засечка без числа». По формулировке и позиции в таблице AC6 целиком о внешних размерах планировки («Внешние размеры: у каждой прямой наружной грани... своя размерная линия... виртуальные границы без размера... рёбра < 30 см — засечка без числа»).

Но правило «короче 30 см — засечка без числа, длина восстановима из соседних» в §7.3 сформулировано только в абзаце «Внутренние размеры комнаты» («Рёбра короче 30 см на бумаге не подписываются... такие рёбра помечаются короткой засечкой без числа»). Абзац «Внешние размеры планировки» этого порога не содержит вовсе: там нет ни минимальной длины, ни правила засечки для коротких наружных граней — только правило для виртуальных (нулевых) границ.

AC — это критерий приёмки, а не описание поведения; поведение обязан задавать контракт (§7.3), AC его только проверяет. Здесь AC6 проверяет то, чего контракт для внешних граней не описывает: реализатору придётся либо угадывать (перенести правило по аналогии — которое рискует стать «догадкой, выданной за факт», ровно то, что это ревью обязано ловить), либо писать тест против неопределённого поведения.

Как чинится в этом же раунде: либо в §7.3 «Внешние размеры планировки» добавляется явное предложение о коротких гранях (перенос правила из внутреннего абзаца с той же формулировкой засечки), либо клауза «рёбра < 30 см — засечка без числа» убирается из AC6 (если для внешних граней порог не нужен — наружные грани планировки обычно не бывают короче 30 см, но это тоже должно быть сказано явно, а не подразумеваться).

Medium-4 — Порог производительности ссылается на несуществующую конфигурацию фикстуры

§15: «Генерация — синхронный расчёт сцены (< 200 мс на large-house фикстуре, 60 комнат; проверяется в unit как порог)». §16 повторяет: «... проверено на large-house фикстуре в golden».

demo/fixtures/large-house.mjs (строки 8-9, 198-233) строит FLOOR_COUNT = 3 пространства (spaces = Array.from({length: FLOOR_COUNT}, ...)), каждое — через roomGrid(floor) с ROOMS_PER_FLOOR = 20 комнатами. Итого 60 комнат на весь дом, но ни одно из трёх пространств фикстуры не содержит 60 комнат — в каждом ровно 20. ТЗ §5 фиксирует: «Экспортируется только текущее пространство» — экспорт в PDF работает с одним пространством за раз, поэтому релевантное число для порога производительности — 20 комнат на пространство (плюс пропорциональная доля из ~60 partitions/40 columns/500 decor, разделённых на три этажа), а не 60.

Это конкретная, проверяемая фактическая неточность: автор теста AC (порог «< 200 мс на 60 комнатах») либо не найдёт такого пространства в large-house и должен будет угадывать, что имелось в виду, либо build ошибочно просуммирует три пространства в один синхронный вызов, чего сцена PDF не делает по контракту (одно пространство за раз).

Как чинится в этом же раунде: правится число в §15 на фактическое (20 комнат на пространство этой фикстуры) либо явно указывается новая фикстура с одним пространством на 60 комнат, если такая плотность нужна для честной проверки порога — в таком случае она также должна быть названа по имени, а не как «large-house».

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

• Обязательные разделы §7.1 PROCESS.md присутствуют: сценарий (§1), что человек увидит до/после (§2), проблема (§3), скоуп/не-скоуп (§5/§6), контракт поведения (§7-8), UX диалога (§8.5), модель данных и миграция (§10 — явно «без изменений»), i18n (§9), AC1-AC15 с указанием доказательства (§12), план автотестов (§13), риски (§16), откат (§17), release-артефакты (§14).
• Все двенадцать проверенных фактических технических утверждений о существующем коде и документации — десять подтверждены дословно (см. таблицу выше); ни одно не оказалось выдумкой, кроме двух разобранных выше как находки.
• Продуктовые вопросы (§18, Q1/Q2) — не голые догадки: у каждого есть принятое значение по умолчанию с обоснованием и явной пометкой «принято», ревьюер вправе оспорить. Оба разумны и не требуют эскалации владельцу (объём видимых изменений и умолчания диалога — не то, что процесс требует спрашивать владельца отдельно, когда автор уже сузил вопрос до варианта по умолчанию).
• Терминология интерфейса («Общие настройки», «Помощь и обратная связь», порядок иконок в шапке, видимость только для _canEdit, скрытие в киоске) сверена с docs/USER-GUIDE.ru.md и совпадает.
• Требование «диалог обязан работать пальцем» (§1) обосновано таблицей docs/TOUCH-SUPPORT.md («View dialogs and safe device actions» → touch: Fully supported), а не заявлено произвольно.
• AC12 (ручная проверка скачивания в мобильном приложении HA) — не новый прецедент: аналогичная форма («вручную... команды и числа в issue») уже принята процессом для AC7 в #473 (docs/reviews/SPEC-REVIEW-473-r2.md) как единственный доступный способ доказательства для сценария, не воспроизводимого в CI. Условие того прецедента — ручной способ явно назван и результат фиксируется в issue — здесь выполнено (§8.4, §16).
• Все AC1-AC15 пронумерованы без пропусков и дублей, у каждого указан способ доказательства из принятого словаря (unit/smoke/golden/вручную с обоснованием); открытых продуктовых вопросов не осталось непокрытыми.
• «Один источник числа»: площадь и внутренние размеры на бумаге явно привязаны к тем же резолверам, что карточка комнаты и живая линейка ресайза (§7.3, AC5) — проверено по коду _rszEdgeLabels/_cleanFloor, это действительно один источник, а не два похожих числа из разных мест (см. таблицу сверки выше — заявление подтвердилось, это не находка).
• Свидетели §13 покрывают по имени каждый значимый защитный сценарий таблицы §7.1/§7.3/§8 (общая стена, галочки, отсутствие ToUnicode, виртуальная стена, устройства на листе, нестандартный масштаб, теперь ещё pdf-room-edge-dropped/pdf-outer-face-inside), что для этапа спеки (не код-ревью) достаточно — состав мутационных гейтов будет предметом код-ревью.

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

• Код фичи не существует (src/pdf/**, pdf-font.generated.ts, scripts/generate-pdf-font.mjs — всё запланировано, не реализовано): дешёвые гейты (tsc, test, build), golden, смоки, мутационные свидетели не гонялись и не могли гоняться — на этапе ревью ТЗ им нечего проверять.
• Не проверял вручную рендеринг PDF-макета (шрифт, коллизии, масштабная линейка) — на этом этапе такого артефакта не существует.
• Не оценивал реалистичность оценок «~15 КБ gzip кода», «60-80 КБ raw шрифта» — это целевые ориентиры дизайна (ожидаемо), а не факты о существующей системе, и не заявлены как факт.
• Не проверял, требует ли реализация фактического похода к scripts/bundle-budget.mjs/bundle-manifest.mjs для добавления роли pdf (код не написан) — это предмет код-ревью.
• Q1/Q2 из §18 не эскалировал владельцу: это принятые автором предположения с обоснованием, ревьюер вправе (и в данном случае согласен) их принять без дальнейшего вопроса.

Вердикт

Три Medium-находки внутри скоупа задачи (Medium-2, Medium-3, Medium-4 — все правятся правкой текста ТЗ, без обращения к владельцу) плюс одна Medium-находка о недостающей записи в docs/SCOPE.md (Medium-1), тоже внутри скоупа — это правка документации docs/SCOPE.md, которую и так называет раздел 11 этого же ТЗ, а не чужой скоуп. High-находок нет. Согласно PROCESS.md §2.4/§2.7 без High это жёлтый вердикт: автор правит четыре абзаца (§7.3 коллизии, §11 запись в SCOPE.md и AC6, §15 число фикстуры) и перевыставляет S4-spec-review.

Вердикт: жёлтый · заход r1 · блокирующих циклов 1/4 · High: 0 · Medium: 4 → в задаче

---

Материал раунда

• Ветка: issue/53-pdf-export, коммит 48a17f5dc998 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: be8a4d9c9e368d67691846b74c69de39cfaaf40b

  git log --all --format='%H %T' | grep be8a4d9c9e36