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

SPEC-REVIEW-482-r1 — Доводка экспорта пространства в PDF

• Issue: https://github.com/Matysh/houseplan-card/issues/482
• Этап: ревью ТЗ (PROCESS.md §2.4)
• ТЗ: docs/specs/482-pdf-export-polish.md
• Трек: полный (аналитика #482 назвала критерии small, которые задача не проходит: сложность/риск 7/10, более одной поверхности, уточнение публичного контракта размеров/компоновки — обоснование присутствует)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4 (до этого вердикта)

Скоуп ревью

Первый заход. Разбор полный (иного и не может быть на r1): читал тело issue #482 и все три комментария (уточнение владельца, аналитика, ссылка на ТЗ), docs/specs/482-pdf-export-polish.md целиком, связанные контракты docs/specs/053-pdf-export.md и docs/specs/052-view-dimensions.md (объединён в #53), docs/SCOPE.md, docs/TOUCH-SUPPORT.md, docs/PDF-EXPORT.md, docs/USER-GUIDE.ru.md (раздел про PDF), и — поскольку ТЗ делает утверждения о текущем поведении кода как обоснование problem statement — сверил каждое такое утверждение с фактическим src/pdf/*.ts, src/near-axis.ts, src/wall-thickness.ts, src/styles/plan.styles.ts.

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

1. Продуктовая рамка: docs/SCOPE.md — задача внутри узкого исключения печатного экспорта (зафиксировано 2026-08-15/2026-09-07 для #53/#52), сама ничего не расширяет (§4 ТЗ явно ограничивает изменяемый контракт частями #53, §6 явно перечисляет не-скоуп).
2. Процесс: AGENTS.md, PROCESS.md §1–§9 — трек, статусы, лимит циклов, требования DoR (§2.5), обязательные разделы ТЗ (§7.1).
3. Само ТЗ построчно на однозначность, проверяемость каждого AC и наличие способа доказательства.
4. Отдельно — не выдаёт ли автор догадку за факт. Для этого каждое утверждение раздела «Подтверждённые причины» (§3 ТЗ) и технической карты (§20) сверено с реальным кодом:
   • compactRing() (src/pdf/pdf-dimensions.ts:16-33) действительно ищет коллинеарные точки по previous/point/next до какого-либо схлопывания точных/почти точных дублей — корневая причина ложной хорды подтверждена чтением, не предположением;
   • WALL = [0.33, 0.33, 0.33] (pdf-scene.ts:79) — заливка без штриховки, подтверждает «нет hatch-прохода»;
   • pdf.legend.* (6 ключей: wall/partition/virtual/door/window/gate) в pdf-scene.ts:522-533 и src/i18n/en.json:454-459 — легенда и ключи существуют ровно как описано;
   • выбор ориентации landscape = physicalWidth > physicalHeight (pdf-scene.ts:236) и резервы calloutWidthMm = 48, dimensionReserveMm = 30 (pdf-scene.ts:246,250) — подтверждают «сырой bbox до размеров» и «приближённые 30/48 mm» из §3.4/§12.1 ТЗ;
   • цветовой форматтер fmt = (v) => v.toFixed(2)... (pdf-writer.ts:38) — общий двухзнаковый форматтер действительно даст 0.5 для 127/255, подтверждает необходимость отдельного high-precision форматтера (§11, риск-таблица);
   • в pdf-writer.ts нет ни одного W/W* clip-оператора — подтверждает «writer не умеет even-odd clipping» (§3.5);
   • канонический допуск NEAR_AXIS_MAX_DEGREES = 0.25 реально существует в src/near-axis.ts и используется вне PDF (repair/draw) — ссылка ТЗ §8.2 на «канонические 0.25°» не изобретена, это существующая общая константа;
   • fallback «выноска R для непрямоугольной комнаты» (§10.2 ТЗ) — реальный код pdf-scene.ts:422-479 (nonRect, callouts, R${…}), не придуманный механизм;
   • существующий экранный hatch (houseplan-card.ts:9259-9263, space-render.ts:902-906) действительно повёрнут на 45° — обоснование «как на самом плане» для §11 ТЗ не голословно.
5. docs/PDF-EXPORT.md подтверждает, что легенда и порядок футера (масштаб, scale bar, north, дата, версия) — уже документированное поведение, которое §14 ТЗ корректно урезает, не придумывая нового.
6. docs/TOUCH-SUPPORT.md — диалог PDF относится к View и подпадает под «полностью поддерживается», это верно отражено в §16 ТЗ (320 px, а не best-effort).

Гейты кода на этом этапе не запускались — ревью ТЗ оценивает выполнимость и проверяемость постановки, а не код; кода по этому issue ещё нет (S4-spec-review, ветка issue/482-pdf-export-polish содержит только ТЗ и предыдущие несвязанные коммиты beta.3).

Находки

Medium (в скоупе задачи)

M1 — источник и лицензия векторного компаса заявлены как факт без проверяемой цитаты, аналогично истории #159. docs/specs/482-pdf-export-polish.md §13: ТЗ утверждает, что приложенный владельцем compass-svgrepo-com.svg (так его в issue называет владелец) — это «compass-line из VMware Clarity Assets», MIT license, copyright VMware 2018, ссылается на конкретный upstream URL и приводит SHA-256 «переданного владельцем файла», который «совпадает по path с каноническим ассетом».

Ни владелец в issue, ни один документ репозитория (docs/FURNITURE.md, docs/PDF-EXPORT.md, лицензионные заметки) не называют этот источник — владелец лишь приложил геометрию SVG и попросил заменить стрелку. Атрибуцию «VMware Clarity Assets, MIT, © 2018» вносит сам автор ТЗ. Это ровно тот класс дефекта, который PROCESS.md требует ловить на этапе ревью ТЗ: «догадка, записанная как факт» — и ровно тот тип дефекта, что уже случился на #159 (SPEC-REVIEW-159-r1.md, High-1: провенанс/лицензия SVG опирались на комментарий, который не подтверждал ни авторства, ни лицензии).

В этом ревью у меня нет доступа к внешним URL (инструмент веб-фетча не подтверждён средой — см. «Чего не проверял»), поэтому я не могу ни подтвердить, ни опровергнуть конкретное совпадение path/SHA-256. Именно поэтому фактическая проверка не может остаться на совести одного только автора: пока в самом ТЗ нет воспроизводимого способа перепроверить атрибуцию (например, точный upstream commit/blob вместо общей ссылки на master, который может уехать, или явное подтверждение владельца, что он взял файл из названного источника), AC8 «license сохранена» проверяется только по тому, что реализация совпадает с недоказанным утверждением ТЗ, а не с внешней истиной.

Почему в скоупе, а не отдельным issue: это ровно тот же деливерабл, что и пункт 7 issue/§13 ТЗ (векторный компас), не соседняя подсистема — чинится правкой этого же ТЗ, не новым issue (#202).

Как закрыть (на выбор автора, ТЗ не подсказывает решение):

• заменить общую ссылку на master точным upstream commit SHA/blob, который не уедет, и явно пометить абзац как «принято предположительно, проверить перед реализацией» по механике §7.1 PROCESS.md; или
• получить у владельца прямое подтверждение источника одним продуктовым вопросом («откуда взят приложенный SVG-файл — просто подтвердите источник/лицензию, чтобы не приписать чужой копирайт неверно»); или
• обойтись без внешней атрибуции вовсе: сохранить в репозитории только то, что доказуемо — сам SHA-256 приложенного владельцем файла как idempotency proof, без утверждений о конкретном третьесторонним репозитории/лицензии, которые ТЗ не может подтвердить.

Без High-находок это жёлтый вердикт: правка ТЗ и повторный заход в рамках той же задачи, отдельный issue не заводится.

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

• Продуктовая рамка (§1–§2 ТЗ): персона, поверхность и момент названы верно; предложение «до/после» одной фразой без терминов реализации выдержано.
• Скоуп/не-скоуп (§5–§6): граница задачи явная, включая явный триггер возврата в S3-spec при выходе за неё (новое config-поле, диагональные стены, новые галочки).
• Изменяемый контракт (§4): точно называет, какие части #53/#52 заменяются, а какие гарантии сохраняются — не тихая ревизия чужого ТЗ.
• Нормализация контуров (§8): порядок очистки (схлопнуть дубли → удалить коллинеарные) и допуски (1 mm физических, 0.25° из существующей константы) однозначны и проверяемы; описание «промежуточной точки» через ненулевые векторы и положительное скалярное произведение исключает как раз тот дефект, что породил issue.
• Локальная дедупликация (§9): критерии пары (ось, нормаль, interval, длина, inside-probe) и правило разрешения конфликтов (score → стабильный ключ) полностью детерминированы, включая явные «не следствия» (разные комнаты/rings/оси не трогать).
• Размещение размеров (§10): единая полоса, сдвиг целиком, шаги в мм — корректно запрещает старый баг «tangent-jitter отдельного текста».
• Материал стен (§11) и компоновка листа (§12): точные числа (127/127/127, 45°/3 mm/0.18 mm, допуск 0.5 mm на bbox, порядок выбора масштаба) — каждое либо взято из уже существующей константы (45°, INK), либо является явным новым техническим решением автора, не заявленным как продуктовое наблюдение владельца — то есть законная зона «решает автор».
• Footer/i18n (§14): корректно ссылается на реально существующие pdf.legend.* ключи и текущий состав footer из docs/PDF-EXPORT.md.
• Модель/миграция/rollback (§15), touch/a11y/perf/security (§16): все пункты DoR присутствуют; миграции нет, что верно для чисто визуальной доводки.
• AC1–AC12 (§17): каждый пронумерован, привязан к разделу контракта и несёт способ доказательства (unit/smoke/golden/mutation witness), включая защитные критерии (дедупликация, axis filter, clipping) — это избыточно подробно относительно минимума DoR (§2.5), что для риска 7/10 уместно.
• Тест-план (§18) и границы Windows/Linux для golden корректно повторяют канон PROCESS.md §8 (golden:verify диагностический на Windows, канонические эталоны — только Linux CI).
• Документация и release-artifacts (§19): перечислены все реально существующие затрагиваемые документы, включая замену контракта в docs/specs/053-pdf-export.md.
• Карта изменений (§20) соответствует существующей структуре src/pdf/* — файлы, которые ТЗ называет изменяемыми, действительно существуют (pdf-dimensions.ts, pdf-scene.ts, pdf-writer.ts, hp-pdf-dialog.ts); pdf-compass.ts — новый файл, что согласовано явно.
• Открытых продуктовых вопросов к владельцу нет и не требуется: все технические развилки (где хранить lane-состояние, как разрешать коллизии) решены и явно объявлены зоной ответственности автора/ревьюера (§7.1 PROCESS.md), а не вынесены как недостающие продуктовые решения.

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

• Не запускал npx tsc --noEmit/npm test/npm run build — на этапе ревью ТЗ кода по задаче ещё нет (ветка содержит только сам файл ТЗ поверх v1.73.0-beta.3), гонять гейты не по чему.
• Не проверял независимо через внешний URL, действительно ли приложенный владельцем SVG побайтово совпадает с vmware-archive/clarity-assets и действительно ли лицензия этого репозитория — MIT с указанным копирайтом: инструмент веб-фетча запросил разрешение и не получил его в этой сессии. Это прямая причина находки M1, а не молчаливый пропуск.
• Не проверял смоки/golden/perf — на стадии ТЗ им нечего мерить; тест-план ТЗ (§18) сам называет их как будущее доказательство AC, что и является предметом код-ревью, а не этого захода.
• Не проверял docs/specs/README.md/docs/STATUS.md/docs/ARCHITECTURE.md построчно на предмет того, что именно там устареет — ТЗ (§19) верно называет их условно («при изменении перечисленных модулей»), это станет предметом код-ревью, когда будет виден фактический diff.

Вердикт

Одна находка Medium в скоупе задачи, High нет. По PROCESS.md §2.4/§4: без High-находок это жёлтый вердикт — ТЗ возвращается автору на правку в рамках этого же issue, отдельный issue не заводится (#202). Бюджет циклов ревью ТЗ для полного трека — 4; этот заход тратит один цикл (жёлтый вердикт бюджет расходует, в отличие от зелёного, #227).

---

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

• Ветка: issue/482-pdf-export-polish, коммит bc93babdf8e7 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 38bf116ad9ad52b85ed8e0aaee3799819a5a1e58

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

• ТЗ docs/specs/482-pdf-export-polish.md, блоб 28628a6c925a3a20886cf0315499ffd478ea8a25

  git log --all --find-object=28628a6c925a3a20886cf0315499ffd478ea8a25 -- docs/specs/482-pdf-export-polish.md