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

# CODE-REVIEW-53-r1

- **Issue:** https://github.com/Matysh/houseplan-card/issues/53
- **ТЗ:** `docs/specs/053-pdf-export.md` (спецревью зелёное на r2, `docs/reviews/SPEC-REVIEW-53-r2.md`)
- **Ветка:** `issue/53-pdf-export`
- **SHA материала:** `6562d4820492fc8223099ecc060ea479c52411fb` (сверено `git rev-parse HEAD` непосредственно перед выводом, §2.7)
- **Диапазон:** `origin/dev..HEAD`, 20 коммитов, `git diff origin/dev...HEAD` — 150 файлов, +5073/‑969
- **Заход:** r1 (первый код-ревью задачи; ТЗ и его ревью — отдельный, уже пройденный этап)

## Скоуп

Первая реализация #53: экспорт текущего пространства в одностраничный
векторный PDF A4 — собственный минимальный PDF-writer (`src/pdf/pdf-writer.ts`),
печатная сцена из канонической геометрии (`pdf-scene.ts`, `pdf-dimensions.ts`),
диалог с четырьмя галочками (`hp-pdf-dialog.ts`), встроенный сабсет Roboto с
кириллицей, ленивый чанк `pdf`, i18n на 4 языках, golden-сцена,
9 mutation-свидетелей, смок `demo/smoke_pdf_export.mjs`, документация.

Не в скоупе ревью: AC12 (ручная проверка скачивания в мобильном приложении HA)
— по ТЗ выполняется владельцем до закрытия issue, задокументировано в
хендофф-комментарии как открытый риск.

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

### Дешёвые гейты — приняты по ссылке, не перегонялись

Полный Linux Validate зелёный на точном материале ревью SHA `6562d482`:
https://github.com/Matysh/houseplan-card/actions/runs/34075522192 — покрывает
`typecheck`, `npm test`, `build` со сверкой копий бандла, `hacs`, `hassfest`,
`backend`. Это разрешено §8/§343: на этом SHA они не перегоняются.

### Гейты, которые не покрыты Validate-ссылкой и прогнаны мной в этом раунде

| Гейт | Команда | Результат |
|---|---|---|
| Mutation-свидетели §53 (9 шт.) | `node scripts/mutation-gate.mjs --check` (пустой прогон), затем `node scripts/mutation-gate.mjs --id=<mutant>` по каждому из 9 | **все 9 «поймано 1 из 1»** — см. таблицу AC ниже, полный вывод сохранён в логах сессии |
| i18n dead keys | `node --test test/i18n-dead-keys.test.mjs` | 2/2 pass — новые ключи `pdf.*` имеют потребителя |
| Разбор кода (не гейт, а чтение) | `pdf-writer.ts`, `pdf-scene.ts`, `pdf-dimensions.ts`, `pdf-export.ts`, `svg-path.ts`, `pdf-raster.ts`, `pdf-date.ts`, `hp-pdf-dialog.ts`, `generate-pdf-font.mjs`, интеграция в `houseplan-card.ts` | прочитаны целиком |

### Гейты, сознательно не прогнанные, и почему

- **`node demo/smoke_pdf_export.mjs`, `smoke_isometric_contract.mjs`,
  `smoke_room_link.mjs`, `golden:verify`, `check-docs.mjs`** — не перегонялись
  повторно: все пять уже зелёные на материале ревью SHA согласно
  хендофф-комментарию автора (конкретные команды и результаты названы) и
  входят в тот же зелёный Validate-прогон (`smoke`, `golden`, `docs` —
  джобы, названные в §8 PROCESS.md как часть Validate). Диффом задет весь
  `src/**`, поэтому `check-docs` обязателен как гейт — его зелёность
  подтверждена ссылкой на прогон приёмки скриншотов
  (`docs/images/screenshots.json`, `sourceFingerprint` обновлён и совпадает
  с текущим деревом — проверено чтением).
- **`npm run model-invariants -- --config <...>`** — не прогонялся. Диффом не
  тронуты `src/wall-thickness.ts`, `src/physical-geometry.ts`,
  `src/plan-geometry-preflight.ts`, `src/zero-walls.ts`, `src/space-geometry.ts`,
  `src/logic.ts` (проверено `git diff --stat` — пусто). PDF только читает уже
  построенную геометрию через существующие резолверы и разделяемый кэш
  (`sharedWallGeometry`, `resolveInnerContour`, `resolveRoomArea`); записи
  толщины, `layout`, `marker.space`, `open_spans` не затронуты — гейт не
  применим.
- **`python -m pytest tests_backend`** — бэкенд не тронут (нет диффа в
  `custom_components/**/*.py`).
- **Performance-профили `large-house-*-smoke`** — задеты только
  `src/iso-*`/`src/live-*`/`src/render-*` в списке §8 их не включают; PDF
  вообще не входит в initial View граф (см. AC11), поэтому изменение не может
  задеть эти профили. Собственный perf-порог AC (< 200 мс CPU на текущем
  20‑комнатном `large-house`) доказан отдельным unit-тестом
  (`test/pdf-scene.test.mjs`, «under 200 ms»), который я прочитал и который
  входит в зелёный `npm test`.
- **Полный набор `demo/smoke_*.mjs`** — не запускался: диффом не задета ни
  одна другая функциональная область (никаких изменений в `src/wall-*`,
  `src/editors/**` кроме стилей заголовка, разобранных ниже).

## Находки

Ни одной High или Medium. Одна Low.

### Low-1 — расхождение текста ТЗ §8.3 с фактическим поведением фолбэка шрифта

`docs/specs/053-pdf-export.md` §8.3 утверждает: «Глиф вне сабсета →
`.notdef` (пустой прямоугольник)». Фактически (`src/pdf/pdf-writer.ts:55`):

```ts
const glyph = PDF_FONT_GLYPHS[code] || PDF_FONT_GLYPHS[0x3f] || 0;
```

`0x3f` — код символа `?`; `PDF_FONT_GLYPHS["63"]` резолвится в реальный,
видимый глиф вопросительного знака (проверено чтением
`src/pdf/pdf-font.generated.ts:7`), а не в глиф `0` (`.notdef`). На листе вне
сабсета печатается видимый «?», а не пустой прямоугольник — расхождение с
текстом ТЗ, не с продуктом: поведение внутренне непротиворечиво и не хуже
описанного (видимый плейсхолдер читаемее пустого прямоугольника).

Формулировка ТЗ «язык плана ограничен четырьмя поддерживаемыми, поэтому в
практике не встречается» тоже неточна: `pdf.room_names`/decor-текст — это
**пользовательский ввод** (название комнаты, текстовый декор), не
локализация карточки; пользователь волен ввести любой символ вне
Latin/Cyrillic/пунктуации сабсета (например, CJK), и тогда сработает именно
этот фолбэк. AC8 требует только «кириллица и латиница» — выполнено и
доказано парсингом `pdfjs-dist`; фолбэк для символов вне сабсета в AC не
заявлен и веткой не тестируется отдельно, но и не заявлен как отсутствующий
риск — это чисто текстовая неточность ТЗ, не отсутствие защиты в коде.

Серьёзность: Low — расхождение документации и факта без порчи вывода. Не
требую правки кода; вопрос — снять формулировку ТЗ или оставить как есть.
**Снимаю с записью**: поведение (видимый placeholder вместо пустого
прямоугольника) безопаснее описанного в ТЗ и не нарушает ни один AC;
исправление текста ТЗ увеличивало бы объём этого раунда без изменения кода
— решение за автором на будущее, не блокирует.

## Таблица AC — доказательство и «чем краснеет»

| AC | Доказательство | Чем краснеет |
|---|---|---|
| AC1 (кнопка/_canEdit/диалог) | `demo/smoke_pdf_export.mjs` (`clickPrinter`, `dialogHasConditionalOptions`) + чтение `src/houseplan-card.ts` (кнопка внутри `this._norm && this._canEdit`, между `settings-button` и `support-button`) | smoke: клик по несуществующей кнопке — таймаут `waitForFunction` |
| AC2 (галочка подложки условна; persist) | smoke: `dialogHasConditionalOptions`, `optionsPersistAcrossReload` (reload реальной страницы, не переоткрытие того же элемента) | смок красный при рассинхроне `expectedCount` или `rememberedNames` |
| AC3 (скачивание, один A4) | smoke: `oneA4Page`, `downloadNameIsStable`; unit `pdf-scene.test.mjs` («chooses one A4 orientation and a standard scale») | unit сравнивает `595.2755905511812` — любое отклонение размера листа красит тест |
| AC4 (геометрия §7.1, общая стена один раз, без устройств) | unit `pdf-scene.test.mjs` («shared wall … emitted once and devices never enter»​) + мутант `pdf-shared-wall-twice`, `pdf-devices-leak` | **прогнано мной**: оба мутанта «поймано 1 из 1» |
| AC5 (внутренние размеры, не исчезают) | unit `pdf-scene.test.mjs` («dense non-rectangular rooms…», реконструкция контура из `stableDimensionEdges`) + мутант `pdf-room-edge-dropped` | **прогнано мной**: «поймано 1 из 1» |
| AC6 (внешние размеры) | unit `pdf-dimensions.test.mjs` («external dimension normal…») + мутант `pdf-outer-face-inside` | **прогнано мной**: «поймано 1 из 1» |
| AC7 (галочки реально управляют содержимым) | unit `pdf-scene.test.mjs» («respects names/dimensions switches», «dimensions switch removes…», «decor toggle…», «backdrop … disappears with its option») + мутант `pdf-dimensions-ignore-toggle` | **прогнано мной**: «поймано 1 из 1» |
| AC8 (кириллица извлекается) | unit `pdf-writer.test.mjs` — реальный парсинг `pdfjs-dist`, `getTextContent()` находит «Кухня» | мутант `pdf-font-no-tounicode` — **прогнано мной**: «поймано 1 из 1» |
| AC9 (подвал: масштаб/линейка/север/легенда) | unit `pdf-dimensions.test.mjs` (`choosePdfScale` в стандартном ряду) + мутант `pdf-scale-not-standard`; линейка/легенда — проверено чтением `pdf-scene.ts:489-533` | **прогнано мной** для масштаба: «поймано 1 из 1» |
| AC10 (детерминизм) | unit `pdf-writer.test.mjs`: `writePdf(page)` дважды, `assert.deepEqual` байтов | смена любого входа (дата, опция) даёт другой поток — проверено чтением: `CreationDate` строится из `page.now`, координаты округляются `fmt` |
| AC11 (ленивость, бюджет, отказ чанка, чужая сборка) | `bundle-budget.mjs` требует непустой `lazyPdfFiles` и отсутствие пересечения с initial; `test/bundle-assets.test.mjs` (обновлён); smoke `pdfChunkAbsentBeforeIntent`, `onePdfChunkRequest`, `failedChunkRetriesOnceAndKeepsView` | `test/bundle-assets.test.mjs` красит пересечение графов; smoke красит повторный запрос чанка не 2 раза |
| AC12 (Android) | не доказано автотестом — по ТЗ ручная проверка владельцем до закрытия, зафиксировано как открытый риск в хендоффе | — |
| AC13 (подложка, лимит 25 МБ) | unit `pdf-raster.test.mjs` (граница `MAX_PDF_RASTER_BYTES`) + smoke `rasterLimitRejectsBeforePdfWrite` + мутант `pdf-backdrop-over-geometry` (слой поверх геометрии) | **прогнано мной**: «поймано 1 из 1»; unit: `assert.throws` на лимит+1 байт |
| AC14 (модальность после reconnect) | smoke `dialogRecoversAfterReconnect` — тот же сценарий, что `smoke_dialog_modal_recovery`, применённый к `hp-pdf-dialog` | смок красит потерю центрирования/`:modal` после переподключения |
| AC15 (9 свидетелей «1 из 1») | `scripts/mutation-gate.mjs --check` + `--id=<mutant>` по каждому | **прогнано мной все 9** — сведено в строки выше |

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

- **Единый источник числа (§8 PROCESS.md).** Площадь и внутренний контур
  комнаты в PDF читаются через `resolveRoomArea`/`resolveInnerContour`,
  которые в `houseplan-card.ts:10691-10712` вызывают **те же** `_cleanFloor` и
  `_innerRoomContour`/`_wallUnionGeometry`, что и видимая карточка комнаты
  (`_cleanFloor` используется на строке 12545 для той же цели) — проверено
  чтением обоих мест вызова. Расхождения «превью PDF ≠ карточка» не может
  возникнуть в рамках этой архитектуры.
- **Изоляция от устройств/состояний.** В `pdf-scene.ts` нет ни одного чтения
  `config.markers`/состояний HA; единственная точка, где маркер мог бы
  попасть на лист, закрыта мутантом `pdf-devices-leak` и красит тест.
- **Безопасность текста в PDF.** Текст комнаты/декора попадает в поток PDF
  только как hex-код глифов (`<${encoded.hex}> Tj`), не как сырая строка —
  инъекция в синтаксис PDF через имя комнаты/декора невозможна (нет случая,
  где пользовательская строка конкатенируется в `(...)`-литерал потока).
- **Скачивание подложки** — тот же `credentials: 'same-origin'` и
  `_display()`-путь подписанного доступа, что у экрана; отказ (`pdf.asset_failed`)
  останавливает экспорт до записи файла — соответствует ТЗ §7.6 «лист без
  обещанной подложки молча — хуже, чем честный отказ».
  Проверено чтением `pdf-export.ts:17-64`.
- **Ленивая граница.** `_pdfRuntimeLoader` в `houseplan-card.ts` — точная
  копия контракта `EditorRuntimeLoader`, использованного `iso-scene-render`
  (exact-build fingerprint, ретрай с nonce, терминальный отказ); manifest/budget
  скрипты требуют непустой `lazyPdfFiles` и отсутствие пересечения с initial —
  проверено чтением `scripts/bundle-manifest.mjs`, `scripts/bundle-budget.mjs`
  и обновлённых `test/bundle-assets.test.mjs`.
- **Трейлеры и changelog.** Все 20 коммитов диапазона несут `Issue: #53` и
  ровно один `User-Visible: yes|no`; единственный `User-Visible: yes`
  (`d277eeb7`) правит `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md` в том же
  коммите. Коммиты, трогающие `demo/golden/baselines/**`, несут
  `Release:`+`Baseline-Reviewed:` со ссылками на реальные прогоны CI —
  проверено `git show -s --format=%b` по каждому из 20 коммитов.
- **`docs/SCOPE.md`.** Узкое исключение для #53 записано текстом (закрывает
  Medium-находку №1 из SPEC-REVIEW-53-r1) и совпадает по формулировке с ТЗ §7.
- **Регресс из-за новой кнопки в шапке** (`fix: keep editor header geometry
  stable`, `fix: preserve projection geometry with PDF action`) — оба
  коммита адресные: сдвиг брейкпоинта `.head .count` (900px→1100px под более
  тесную шапку) и вынос точки скрытия из `620px` в отдельное правило;
  геометрия плана (не шапки) не меняется — проверено чтением обоих диффов.
  Этим объясняется широкий список пересобранных golden-эталонов (любой кадр
  с шапкой карточки); каждый принят с `Baseline-Reviewed`-ссылкой.
- **Лицензия шрифта.** `assets/fonts/LICENSE` — полный текст Apache 2.0,
  путь совпадает с указанным в ТЗ и `PDF-EXPORT.md`.
- **Мутационные свидетели §13/AC15** — все 9 прогнаны мной лично в этом
  раунде (`--check` даёт чистый прогон, `--id=<mutant>` даёт «поймано 1 из 1»
  для каждого); это «чистые юниты» в терминах §2.7 (защита в
  `src/pdf/pdf-scene.ts`/`pdf-dimensions.ts`/`pdf-writer.ts`, проверяется
  `test/pdf-scene.test.mjs`/`pdf-dimensions.test.mjs`/`pdf-writer.test.mjs` —
  не смок/бэкенд/golden), поэтому по правилу «для чистых юнитов достаточно
  прогона со снятой защитой, приведённого в документе» этого прогона
  достаточно и я не обязан требовать дополнительного golden/смок-свидетеля.

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

- **AC12** (скачивание в мобильном приложении HA на Android) — не доказано
  автотестом ни автором, ни мной; по ТЗ это ручная проверка владельца до
  закрытия issue. Не блокирует код-ревью: AC12 явно размечен методом
  доказательства «вручную владельцем», а не автотестом (`docs/specs/053-pdf-export.md`
  §12).
- **Golden-кадр `pdf-export-geometry-light` визуально мной не пересматривался
  пиксель-в-пиксель** — принят автором через `npm run golden:accept -- --reviewed`
  по полному Linux CI артефакту (ссылка на прогон в хендоффе и трейлеры
  `Release:`/`Baseline-Reviewed:` коммита `6562d482`), что и является
  каноническим способом приёмки по PROCESS.md §13; я проверил чтением, что
  `demo/golden/run.mjs` реально рендерит PDF через `pdfjs-dist` в canvas (не
  берёт скриншот экрана) и что golden-сцена подключена в `demo/golden/matrix.mjs`.
- **Полный набор `demo/smoke_*.mjs`** — не прогонялся; выбор ограничен тремя
  смоками, названными в хендоффе (`pdf_export`, `isometric_contract`,
  `room_link`) плюс `smoke-links.mjs`, который регистрирует символы задачи
  за `smoke_pdf_export.mjs` — не вызывал `scripts/smoke-select.mjs` отдельно,
  так как диффом не затронута ни одна другая смок-поверхность (никаких
  изменений вне `src/pdf/**`, `src/houseplan-card.ts` (кнопка/лоадер),
  `src/styles/dialogs.styles.ts` (брейкпоинт)).
- **`npm run model-invariants`** — не прогонялся; обоснование в таблице гейтов
  выше (геометрическая модель не тронута).
- **Ручной просмотр итогового PDF в Acrobat/Preview** (§16 риск таблицы ТЗ) —
  не выполнялся; заменён более сильной автоматической проверкой —
  парсингом `pdfjs-dist` в трёх независимых unit/smoke/golden контекстах,
  что и есть механическое доказательство «открывается стандартным ридером».

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

- Ветка: `issue/53-pdf-export`
- Дерево материала: `git rev-parse HEAD` на момент вывода = `6562d4820492fc8223099ecc060ea479c52411fb`
- Диапазон: `origin/dev..HEAD` (merge-base `afbee9d328e9159cc69934ffa7a3c795c0320eed`)
- Полный Validate: https://github.com/Matysh/houseplan-card/actions/runs/34075522192
- Документационные кадры: https://github.com/Matysh/houseplan-card/actions/runs/34075005646
- Golden: https://github.com/Matysh/houseplan-card/actions/runs/34075026829

## Вердикт

Зелёный. High: 0. Medium: 0. Low: 1 (снята с записью, без правки кода).
Задача полностью реализует ТЗ #53 и закрывает все автоматически доказуемые
AC; AC12 корректно оставлен ручной проверке владельца по контракту ТЗ.

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

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

- Ветка: `issue/53-pdf-export`, коммит `6562d4820492` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `1db7839f17586fa2cf7ad9e1aea009377c31fbff`
  ```
  git log --all --format='%H %T' | grep 1db7839f1758
  ```