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

SPEC-REVIEW-530-r1

Issue: #530 — «Экспорт в PDF: план занимает половину листа A4, а столбец выносов отбирает у него целый шаг масштаба» Этап: spec (ревью ТЗ, PROCESS.md §2.4) Трек: полный (автор называет нарушенные критерии §5: «нет влияния на производительность» и «нет нового UX-контракта» — оба нарушены обоснованно, см. «Что проверено и корректно») Заход: r1 · блокирующих циклов израсходовано 0 из 4

Скоуп

ТЗ живёт в теле issue #530, раздел ## ТЗ (после аналитики S2 и текста «ТЗ готово» в комментариях). Предмет: убрать столбец «Internal dimensions» и метки R… из PDF-экспорта плана (src/pdf/pdf-scene.ts), уменьшить кегли подписей внутри плана на 25 % (размер 7→5.25, площадь 8→6, имя комнаты 9/7→6.75/5.25), не трогая ряд масштабов и правило выбора ориентации. Контракт К1-К5, AC1-AC6.

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

Чтением кода, без исполнения — на этапе ТЗ кода ещё нет, гейты не прогонялись (правка кода не входит в этот этап). Каждое количественное или поведенческое утверждение ТЗ сверено построчно с текущим dev на материале 8f5a08a6 (совпадает с SHA, на котором получена аналитика S2).

• docs/SCOPE.md — продуктовая рамка (J4/J6, персона «администратор дома», печатный лист как артефакт, уносимый из продукта); раздел «Out of scope» с узким исключением для #53 (сам факт существования PDF-экспорта).
• AGENTS.md, PROCESS.md §2.3-§2.5, §5, §7.1 — формальные требования к ТЗ и лёгкому/полному треку.
• docs/PDF-EXPORT.md — канонический документ подсистемы PDF-экспорта (не входит в список §-канонов AGENTS.md дословно, но это единственный документ, детально описывающий поведение, которое правка меняет).
• docs/USER-GUIDE.ru.md:1835-1857 — раздел «Сохранение текущего пространства в PDF»; ссылается на PDF-EXPORT.md за деталями, сам текст выносок/столбца не упоминает.
• src/pdf/pdf-scene.ts целиком (840 строк): PDF_SCALE_SERIES, betterPdfCandidate, buildPdfPage, цикл подбора масштаба (770-839), блок печати меток/столбца (624-696), кегли (584-740).
• src/i18n/{en,ru,fr,de}.json:452 — pdf.internal_dimensions существует во всех четырёх локалях.
• test/pdf-scene.test.mjs целиком (840 строк): тесты unprintable fixed callouts fail closed… (494-503), oversized architecture brackets a larger printable scale… (505-514), dense non-rectangular rooms keep mandatory dimensions in stable callouts (563-598), бюджетный тест на 200 мс CPU (618-679).
• demo/golden/matrix.mjs:367-419 — сценарии pdf-export-geometry-light, pdf-export-stepped-dimensions-light, их текущие minSceneCoverage.
• scripts/mutation-gate.mjs:224-247 — существующие мутанты pdf-dimensions-ignore-toggle, pdf-room-edge-dropped, их guard/because.

Находки

Medium — правка меняет два поведения, задокументированных в docs/PDF-EXPORT.md, но документ не назван ни в скоупе, ни в release-артефактах

Файл: тело issue #530, разделы «Чего задача не трогает» и «Release-артефакты».

docs/PDF-EXPORT.md — единственный текст, детально описывающий именно то поведение, которое ТЗ меняет, и он расходится с новым контрактом в двух конкретных местах:

1. Строка 59: «…while required values that cannot fit beside an edge use numbered callouts» — после AC1 это утверждение становится ложным: такое значение теперь не печатается вовсе (контракт п.1: «Размер, который не удалось разместить внутри комнаты, не печатается»), а не переносится в столбец, которого больше нет. Заодно строка 32 перечисляет «callouts» как часть собираемой сцены — тоже устаревает.
2. Строки 41-42: «If a fixed annotation itself cannot fit on one A4 sheet, export stops with an error instead of producing a clipped file.» Прочитан код, который это реализует: buildPdfPage (src/pdf/pdf-scene.ts:770-839) подбирает масштаб перебором PDF_SCALE_SERIES, а при неудаче — экспоненциальным пробегом до maxFallbackScale = 1_000_000 (773-820), и бросает pdf.failed только если вообще ни один масштаб не подошёл (821) либо финальная проверка границ не сошлась (838). Единственный тест, дёргающий этот путь — unprintable fixed callouts fail closed… (494-503) — форсирует его руками через name: 'X'.repeat(1000), которое превращается в строку столбца выносов (${callout.mark} ${callout.room}: ${callout.value}, 691) фиксированной ширины, не сжимающуюся с ростом масштаба. Архитектура сама по себе всегда находит подходящий масштаб (второй тест, 505-514, явно это проверяет: output.scale > 500, до 1:1 000 000), а подписи внутри плана (имя 9/7, размер 7, площадь 8) при нехватке места не бросают исключение, а тихо не печатаются (nameSize = 0, комментарий 674-676 «Rectangular rooms have no unambiguous numbered callout fallback… omit the unsafe label»). То есть столбец выносов — единственный известный код-путь, форсирующий отказ pdf.failed через «не влезающую фиксированную подпись»; когда он уходит, предложение из PDF-EXPORT.md перестаёт описывать что-либо достижимое обычным использованием (кроме отдельного, уже названного в контракте п.5 случая «архитектура не влезает ни в один масштаб», #53) — но сам текст документа остаётся как есть и вводит в заблуждение.

Контракт п.5 ТЗ сам по себе корректен и честен («Отказ fail closed сохраняется для архитектуры, которая не влезает ни в один масштаб (#53)») — это именно то более узкое, правильное описание, которое должно заменить нынешний текст PDF-EXPORT.md. Но раздел «Release-артефакты» называет только два бюллетеня changelog; раздел «Чего задача не трогает» тоже не упоминает документацию. DoR (PROCESS.md §2.5) требует «release-артефакты названы: changelog RU+EN, документация, golden/скриншоты… — либо явное "нет"» — здесь пункт «документация» просто отсутствует, а не назван явным «нет», и это не безобидный пропуск: документ буквально описывает то, что задача удаляет.

Требуется от автора (правка ТЗ, тот же issue, без нового): добавить docs/PDF-EXPORT.md в затронутые файлы/release-артефакты и явно зафиксировать, что строки 32/58-59 (упоминание «callouts»/«numbered callouts») убираются, а строки 41-42 (fail-closed для «fixed annotation») переформулируются в духе контракта п.5 — только для архитектуры, не влезающей ни в один масштаб.

Серьёзность — Medium, в скоупе задачи: без High-находок это жёлтый вердикт, правка ТЗ и повторный (второй) заход.

Low — существующий мутант pdf-room-edge-dropped защищает ровно ту гарантию, которую контракт отменяет

Файл: scripts/mutation-gate.mjs:235-247.

Мутант pdf-room-edge-dropped (because: 'every non-short edge must retain a direct value or a numbered callout') роняет из массива дедуплицированных рёбер последнее (.slice(0, -1)) и ожидает, что тест dense non-rectangular rooms keep mandatory dimensions in stable callouts его поймает. AC1 переписывает именно этот тест на противоположное утверждение («не печатается» вместо «восстанавливается через столбец»), и «every non-short edge must retain a direct value or a numbered callout» после правки более не является инвариантом продукта. AC-таблица называет только два новых мутанта (pdf-restores-dimension-callouts, pdf-keeps-large-in-plan-labels), не называя, что делать со старым pdf-room-edge-dropped — хотя scripts/mutation-gate.mjs уже назван затронутой поверхностью в аналитике S2. Не блокирует: файл уже в списке затронутых, и это естественное следствие переписывания теста, на который мутант ссылается по имени — но стоит явно решить (снять мутант или переформулировать его because) при реализации, а не молча оставить ссылку на несуществующую больше гарантию.

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

• Продуктовая рамка (§7.1). Раздел «Продуктовая рамка» называет персону (администратор дома, docs/SCOPE.md), поверхность (печатный лист) и момент («уносит из продукта наружу»). «До/После» сформулированы одной фразой без терминов реализации.
• Трек выбран верно. Оба названных нарушенных критерия §5 подтверждаются: перф — сборка сцены имеет собственный бюджет 200 мс, проверяемый существующим тестом (618-679), состав сцены меняется; UX-контракт — печатный лист меняет ориентацию (книжная вместо альбомной на форме владельца) и теряет целый раздел (столбец), это не «поведение в рамках уже описанного».
• Все количественные утверждения о текущем состоянии подтверждены чтением кода. PDF_SCALE_SERIES = [20,25,50,75,100,150,200,250,500] (pdf-dimensions.ts:572); кегли — размер 7 (pdf-scene.ts:611,643), площадь 8 (596), имя 9/7 (584-585), метка R… 6 (673), заголовок столбца 8 (688), строка столбца 6 (692); хром страницы — заголовок 14 (707), название карточки 10 (710), «Scale 1:N» 8 (716), линейка/компас 7 (728,736,740) — контракт п.2 correctно утверждает, что хром не меняется. Арифметика ×0.75 (7→5.25, 8→6, 9→6.75, 7→5.25) верна.
• AC1/К1 точно описывают, что удаляется. Столбец (688-693), линия-выноска и счётчик R${callouts.length+1} (670-673), ключ pdf.internal_dimensions — существует во всех четырёх локалях (en/ru/fr/de.json:452) и больше нигде в src/**, кроме pdf-scene.ts:688 и самого теста (test/pdf-scene.test.mjs:587).
• Два переписываемых теста названы точно и по существу. unprintable fixed callouts fail closed instead of returning a clipped PDF page (494-503) действительно форсирует переполнение именно через столбец (см. находку выше) — «теряет предмет» после удаления столбца заявлено честно, не втихую. dense non-rectangular rooms keep mandatory dimensions in stable callouts (563-598) действительно утверждает восстановимость через pdf.internal_dimensions/R\d+ — ТЗ верно называет, что смысл теста меняется на противоположный.
• AC5 использует существующие, а не выдуманные golden-сценарии. pdf-export-geometry-light (matrix.mjs:371) и pdf-export-stepped-dimensions-light (415) существуют, у обоих уже задан pdfSemantic.minSceneCoverage (0.20 и 0.15), который run.mjs:292-293 сравнивает с фактическим покрытием — «поднятый до фактического» порог технически корректен как способ доказательства.
• Контракт п.1 «правило, по которому уже сегодня живут прямоугольные комнаты, становится общим» — подтверждено. Для прямоугольных комнат (nonRect === false) код уже тихо пропускает неразмещённую подпись без исключения (комментарий 674-676); правка лишь распространяет это же поведение на непрямоугольные.
• AC4 корректно закрывает риск «потеряли подписи, убирая столбец». Формулировка требует не меньшего числа подписей на плане (38 vs 35) и отсутствия повторной печати значения — это тот же класс требования, что и «одно число — один источник»; отдельного нарушения этого принципа в диффе нет, поскольку до правки значение печаталось либо на плане, либо в столбце, никогда в обоих местах одновременно, и после правки источник остаётся один — на плане либо нигде.
• Риски честны и по существу. Кегль 5.25 pt (~1.85 мм) назван на грани чертёжной практики с обозначенным путём отступления (−15 % вместо −25 %); потеря семи коротких размеров явно вынесена в changelog; необходимость пересъёмки golden на Linux CI (#455) названа как риск, а не как гейт «для галочки».
• Блок «Принято предположительно» сформулирован по форме, требуемой §7.1 («принято предположительно, менять свободно»), и содержит только техническую механику (пилообразное заполнение — отдельная задача; поля/шапка/подвал не трогаются; выноска у стены — альтернатива, не эта задача), без продуктовых решений, спрятанных под видом технических.
• Откат — один revert, данные/конфиг/публичные контракты не затронуты — соответствует реальному объёму правки (i18n-ключ + один модуль рендера + тесты + golden-кадры).

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

• Не запускал npx tsc --noEmit, npm test, npm run build, golden — этап ТЗ, продуктового кода ещё нет, оценивать нечего.
• Не проверял точность самих числовых замеров аналитики S2 (35→38 подписей, 29 против 36 уникальных значений, доли площади листа) — не переисполнял buildPdfPage на синтетической фикстуре владельца; это воспроизводимый прогон Node-скрипта, а не факт из документа, и на этапе ТЗ отдельно не перепроверялся. Внутренняя согласованность утверждений (аркметика кеглей, существующие константы, имена тестов) проверена полностью и разошлась только в находках выше.
• Не проверял demo/smoke_pdf_export.mjs на предмет ассертов, зависящих от столбца/меток — файл назван затронутой поверхностью в S2, но правка теста туда не входит в контракт ТЗ явно; беглый grep не нашёл в нём упоминаний internal_dimensions/R\d/callout, так что видимого зазора нет, но фикстуры смока не читал построчно.
• Не проверял docs/images/10-pdf-export.png (скриншот диалога опций) на предмет устаревания — диалог опций (чекбоксы) визуально не меняется этой задачей, только содержимое самого PDF, так что скриншот UI, по всей видимости, не затронут; глубже не копал.

Вердикт

Жёлтый. Контракт технически точен и хорошо обоснован для всего, что он утверждает о src/pdf/pdf-scene.ts и тестах (все количественные и поведенческие claims сверены с кодом построчно и подтвердились), выбор полного трека обоснован верно, продуктовая рамка и AC полны и проверяемы. Но задача меняет два конкретных предложения канонического документа docs/PDF-EXPORT.md (упоминание «numbered callouts» и формулировку fail-closed для «fixed annotation»), и ни «Чего задача не трогает», ни «Release-артефакты» этот документ не называют — DoR §2.5 требует явного «документация: …» или явного «нет», здесь нет ни того, ни другого. Это Medium-находка в скоупе задачи, без High.

---

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

---

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

• Ветка: dev, коммит 8f5a08a60974 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 0728cc169939a5f201f20df07fc695b6055a071c

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

• Тело issue: 3c6248e088a3948ba1b6a44fafbc15118b8ad7706edb941b92b3fd9a4c8135ac
• Вердикт конвейера: yellow · High 0