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

# SPEC-REVIEW-39-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/39 — «[HP-UX-09] большие подложки»
- Этап: ТЗ на ревью (PROCESS.md §2.4)
- Заход: r1 · блокирующих циклов израсходовано 0/4
- ТЗ: `docs/specs/039-large-backdrops.md`, ревизия 2, SHA `156be645`
- Трек: полный (владелец, 2026-08-15: «P3, polish/tech-debt, обычный трек»)
- Предыдущего вердикта по этому ТЗ нет — это первый проход ревью, раздел
  «Унаследовано из r0» не применяется, разбор полный по §2.10 (не второй цикл).

## Скоуп проверки

Диагностика разрешения/decoded-памяти PNG/JPEG/WebW до какой-либо тяжёлой
аллокации, warn/hard-диалог, клиентский downscale до 4096px, замена ручного
base64-цикла на `FileReader`. Один файл изменён в этом коммите:
`docs/specs/039-large-backdrops.md` (165 строк, Class C). Продуктового/кода
diff нет — ревью касается только текста ТЗ.

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

1. `docs/SCOPE.md` — сценарий укладывается в надёжность onboarding-загрузки
   плана (соседствует с J4), сама задача уже протриажена владельцем как
   valid tech-debt (комментарий от 2026-08-14), продуктового конфликта со
   стандартными правилами (never-delete-a-file, lock invariant) нет.
2. `AGENTS.md`, `PROCESS.md` §2.3–2.5, §7.1 — состав обязательных разделов ТЗ
   и критерии DoR.
3. Issue #39: тело + оба комментария (аналитика 2026-08-14, актуализация
   2026-08-29). Вопросов к владельцу автор не поднимал («Вопросы: нет»).
4. `docs/USER-GUIDE.ru.md` — сверил терминологию: «подложка», «Редактор
   подложки», диалоги `hp-dialog` — используются в ТЗ корректно, не
   изобретены.
5. `docs/CANVAS.md` → обнаружил ссылку на `docs/BACKDROP.md` (канонический
   документ калибровки/размещения подложки на канвасе, не входит в список
   в промпте, но напрямую относится к подсистеме). Прочитан: описывает
   `plan_x/y`, scale, rotation — геометрию подложки, а не upload/decode.
   Задача этой геометрии не касается («Вне скоупа» ТЗ подтверждает), конфликта
   нет.
6. Сверка технических якорей ТЗ с текущим кодом (раздел «не додумывается —
   выносится» требует, чтобы заявленные факты о коде были фактами, а не
   догадкой):
   - `_pickPlanFile` (`src/houseplan-editor-runtime.ts:8243`) — ручной
     base64-цикл `String.fromCharCode` подтверждён построчно (:8253-8255);
     разрешение действительно не проверяется; aspect действительно берётся
     через `<img>.onload` (:8261-8266) — то есть полный decode уже
     происходит на этом шаге. Совпадает с текстом ТЗ дословно.
   - `MAX_FILE_BYTES = 50 * 1024 * 1024` подтверждён в
     `custom_components/houseplan/validation.py:24`, использование в
     `http_api.py:252` — совпадает с «50 МБ» в ТЗ.
   - `check_quota` в `custom_components/houseplan/plans.py:216` — квота
     подтверждена, комментарий рядом («Files are never removed for getting
     old») согласуется с standing rule SCOPE.md «never delete a user's file».
   - Транзакционный комментарий в `_saveSpaceDialog`
     (`src/houseplan-editor-runtime.ts:~8375-8390`, «Upload BEFORE touching
     the config...») подтверждает заявление ТЗ «staging не трогает конфиг до
     успешного save» — это не догадка, а верно прочитанный существующий код.
   Вывод: технические анкеры ТЗ точны, автор не выдаёт предположение за факт
   там, где дело касается существующего кода.
7. Сверка ревизии 1 → 2 (`git show 156be645^:docs/specs/039-large-backdrops.md`
   vs текущая) — чтобы не приписать ревизии 2 разрыв, унаследованный от
   ревизии 1. Структурные пробелы (см. находки ниже) присутствовали уже в
   ревизии 1 — не новый регресс, но это первый **ревью** документа, поэтому
   они предъявляются сейчас.
8. i18n: подтвердил, что проект поддерживает en/ru/de (`src/i18n/{en,ru,de}.*`),
   так что «Тексты en/ru/de» в ТЗ — не опечатка и не лишний язык.
9. `docs/TOUCH-SUPPORT.md` — `_pickPlanFile` живёt только в Plan editor
   (`houseplan-editor-runtime.ts`), редакторы — desktop-first/best-effort,
   View/kiosk (блокирующая часть touch-контракта) это изменение не
   затрагивает. Конфликта нет, но ТЗ не проговаривает это явно (см. находки).

## Гейты

Диапазон изменений — только `docs/specs/039-large-backdrops.md` (Class C,
0 файлов в `src/**`/`custom_components/**`). Код не менялся, поэтому:

| Гейт | Применимо? | Причина |
|---|---|---|
| `npx tsc --noEmit` / `npm test` / `npm run build` | нет | diff не содержит кода; сверять бандл не с чем |
| `node scripts/check-docs.mjs` | нет | триггерится изменениями `src/**`, их нет |
| `npm run invariants` | нет | геометрия/`layout`/толщина стен не затронуты |
| browser-смоки, `golden:verify`, `pytest tests_backend` | нет | нет реализации, смоки из ТЗ (`demo/smoke_backdrop_guard.mjs`) ещё не существуют — они появятся в коде, не в этом коммите |

Ничего не прогонял намеренно — прогон дорогих или дешёвых гейтов на
docs-only коммите ничего не проверяет по существу и не относится к предмету
ревью этапа `spec`.

## Находки

Все находки — Medium, в скоупе задачи (правятся автором ТЗ в этом же issue,
без отдельного issue). High-находок нет: ТЗ реализуемо и в основном
проверяемо, ни одна находка не требует решения владельца.

### M1 — нет обязательных продуктовых разделов §7.1 «сценарий» и «что человек увидит»

PROCESS.md §7.1: «Два первых раздела — продуктовые... Сценарий: какая
персона, на какой поверхности, в какой момент. Что человек увидит: одной
фразой, без терминов реализации. ТЗ, которое не может ответить на эти два
вопроса, описывает работу, а не изменение продукта.»

Текущий документ начинается сразу с «Цель» → «Текущее состояние (анкеры
кода)» — реализационный язык с первой содержательной строки. Персона (Home
admin), поверхность (Plan editor, диалог создания/замены пространства) и
момент (выбор файла подложки при создании/редактировании floor plan) нигде
не названы явно, хотя ответ на изучение (см. «Как проверялось», п.6, 9) есть —
что и делает пробел исправимым без обращения к владельцу.

**Как воспроизвести:** прочитать `docs/specs/039-large-backdrops.md` — раздел
«Сценарий» и фраза «что человек увидит до/после» без терминов реализации
отсутствуют физически.

**Правка:** добавить два первых раздела по шаблону §7.1.

### M2 — i18n-раздел не перечисляет ключи, DoR §2.5 не закрыть

§7.1 требует раздел «i18n» в самом ТЗ; DoR §2.5 требует «ключи en + ru
перечислены» как отдельный обязательный пункт. Текущий текст — одна строка
внутри UX: «Тексты en/ru/de; диалог на мобильной ширине без горизонтального
скролла» — ни одного имени ключа.

Три новых пользовательских текста как минимум (warn-заголовок/тело,
кнопка «Загрузить уменьшенную копию», кнопка «Оставить оригинал», hard-текст
с советом уменьшить файл) не имеют предполагаемых ключей — это чисто
техническое решение (§7.1: «Всё, чего пользователь не наблюдает [в смысле
имени ключа], агенты решают сами»), но раздел должен *содержать* список,
не быть пустым.

**Как воспроизвести:** grep `docs/specs/039-large-backdrops.md` на `\.title\|\.body\|key` —
ни одного предложенного ключа.

**Правка:** перечислить en+ru ключи (можно предположительно, «assumed, change
freely») — это разблокирует DoR-пункт.

### M3 — нет разделов «Риски» и «Release-артефакты», обязательных по §7.1

§7.1 перечисляет обязательные разделы: «...план автотестов · **риски** ·
откат · **release-артефакты**». В документе есть «Откат» и «Тесты и
мутанты», но нет ни выделенного раздела «Риски» (хотя по существу риск
называн — «честная оговорка» про недоступный reference-планшет, — он не
собран в заявленный по процессу раздел и не сопровождён явной пометкой
«принято предположительно, поменять свободно», как требует §7.1 в конце
документа), ни раздела «Release-артефакты» (changelog RU+EN, документация,
golden/скриншоты, performance/security — ни один пункт не назван, хотя
`User-Visible: yes` почти наверняка потребуется на новый UX-диалог).

**Как воспроизвести:** grep заголовков `^##` в файле — «Риски» и
«Release-артефакты» отсутствуют.

**Правка:** добавить оба раздела; риски можно перенести из «Честной
оговорки», Release-артефакты — минимум подтвердить `User-Visible: yes` и оба
changelog.

### M4 — AC4 объединяет два разных момента наступления `hard` без единого UI-контракта

`probeBackdrop` классифицирует `hard` синхронно по заголовку (сторона
>16384px) — до какого-либо клика пользователя, поэтому в этом случае
Cancel-only диалог логично показывается сразу вместо `safe`/`warn`. Но АС4
также включает «decode-ошибка или таймаут 10 с **на этапе уменьшения**» —
это происходит ПОСЛЕ того, как пользователь уже увидел `warn`-диалог и нажал
«Загрузить уменьшенную копию» (шаг из UX-раздела, «Уменьшение:
`createImageBitmap`... OffscreenCanvas... aspect сохраняется»). В этот момент
пользователь уже закрыл первый диалог и, вероятно, видит какое-то состояние
busy/loading.

ТЗ не говорит, что именно пользователь увидит при отказе на этом втором
шаге: тот же Cancel-only диалог переоткрывается, показывается инлайн-ошибка
поверх текущего состояния, или тост — сказано только «текущая подложка и
staging не изменились» (что описывает данные, а не экран). Это ровно тот
класс вопроса, который §7.1 called «продуктовый» («что человек видит или
делает» в пограничном случае) и который автор обязан решить явно (не
обязательно спрашивая владельца — решение внутри компетенции автора, но оно
должно быть записано, а не подразумеваться).

Без этого AC4 не полностью проверяем одним однозначным тестом: тест-автор
должен будет сам придумать, какой UI ожидать после ошибки на втором шаге, и
разные реализации/тесты разойдутся.

**Как воспроизвести:** перечитать AC4 и раздел UX «hard» — оба говорят про
данные (staging/config не меняются), ни один не описывает экран после
runtime-отказа downscale, случившегося уже после клика в `warn`-диалоге.

**Правка:** одна фраза, например «повторно показывается тот же hard-диалог поверх
прерванного действия» или «инлайн-ошибка в уже открытом warn-диалоге, без его
закрытия» — и синхронизировать с AC4.

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

- Технические анкеры кода (base64-цикл, aspect via `<img>`, MAX_FILE_BYTES,
  quota, staging-до-save транзакция) — точны, сверены построчно с текущим
  `dev`, не догадка.
- Бенчмарк-матрица (4–165 МП) внутренне согласована, источник (headless
  Chromium, `createImageBitmap`+downscale) назван, ограничение (нет
  reference wall-tablet) явно оговорено, а не скрыто; направление ошибки
  консервативно (раньше предупреждаем, а не позже) — это разумная инженерная
  позиция, а не выданная за факт догадка.
- Константы собраны в одном модуле (`src/backdrop-probe.ts`) с явной целью
  «полевая рекалибровка = правка одного файла» — соответствует духу
  «assumed, change freely».
- AC1–AC3, AC5–AC9 — каждый привязан к способу доказательства (unit/smoke/
  ревью) и формулирует наблюдаемое поведение однозначно; для AC1 и AC9 в
  тексте прямо продумано, как тест проверит «до-decode» инвариант (spy на
  `window.createImageBitmap`, отсутствие canvas в юните) — «тест умеет
  падать» проверяемо уже на этапе спеки через реестр мутантов (4 пункта,
  каждый называет, что именно ломается).
- Терминология («подложка», диалоги) соответствует `docs/USER-GUIDE.ru.md`,
  не изобретена.
- Не найдено нарушений standing rules SCOPE.md (never-delete-a-file, lock
  invariant — оба нерелевантны этой задаче и не задеты).
- `docs/BACKDROP.md` (геометрия/калибровка подложки) не конфликтует —
  задача его не касается, что подтверждено разделом «Вне скоупа».
- Раздел «Вне скоупа» и «Откат» по существу закрывают «модель данных и
  миграция» (эндпоинты/схема не меняются) — содержательно ОК, только не под
  отдельным заголовком (см. M3, куда это включено).

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

- Реальное поведение в браузере — реализации ещё нет, диалог/downscale не
  существуют в коде; нечего запускать.
- `demo/benchmark_backdrop_decode.mjs` — упомянут как будущий файл, в
  репозитории отсутствует (`git ls-files` не находит), не мог сверить числа
  бенчмарка независимо — доверился as-is как research-отчёту автора,
  корректность самих чисел проверке на этом этапе не подлежит (это войдёт в
  реализацию).
- Не оценивал производительность реального downscale на low-end wall-tablet
  устройстве — сам автор честно называет это недоступным; ревью не может
  закрыть то, что недоступно и автору.
- Не проверял `test/backdrop-probe.test.mjs` и `demo/smoke_backdrop_guard.mjs`
  — они не существуют, появятся в реализации; их «умение падать» — предмет
  код-ревью, не этого этапа.

## Вердикт

0 High, 4 Medium (все в скоупе задачи, возвращаются автору для правки ТЗ,
без отдельных issue). Технический фундамент ТЗ хороший (анкеры кода точны,
бенчмарк честен, AC в основном проверяемы), но структурная неполнота против
чек-листа §7.1 (M1–M3) и одна реальная развилка поведения без явного решения
(M4) не позволяют закрыть DoR §2.5 как есть.

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