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

# SPEC-REVIEW-584-r1

**Issue:** #584 · **Этап:** ТЗ на ревью (S4-spec-review) · **Заход:** r1 ·
**Трек:** полный (аналитика от 2026-09-15 назвала критерий: сложность/риск >3,
несколько модулей и поверхностей, меняется публичный контракт «см. в
свойствах = видимый габарит»).

**Вердикт: жёлтый**

---

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

ТЗ живёт в теле issue #584 под заголовком `## ТЗ` (комментарий владельца от
2026-09-16T19:33:08Z объявляет переход в `S4-spec-review`). Материал ревью —
текст issue на момент чтения (последний комментарий владельца, тот же, что
поставил статус); отдельного файла в `docs/specs/` нет и не создаётся (архив
закрыт с #517).

Прочитано перед разбором: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` целиком
(включая §2.4, §2.5, §2.7, §7.1, §12), тело issue #584 и все 6 комментариев
(аналитика → вопросы Q1/Q2 → ответ владельца → полное ТЗ дизайнеру →
присланный архив → приёмка пака дизайнером-исполнением). `docs/TOUCH-SUPPORT.md`
и канонические документы подсистем (SUN/LIGHT/CANVAS/WALL-THICKNESS/UX-MODES/
CONFIG-COMPATIBILITY) просмотрены на предмет пересечения — задача их не
затрагивает (чистая геометрия SVG-артворка мебели, не стены/не свет/не солнце).

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

Поскольку задача целиком про фактическую геометрию, а не про рассказ, каждое
фактическое утверждение ТЗ сверено с текущим состоянием репозитория (SHA
`7c5fd32a`, `dev`), а не принято на слово:

| Утверждение ТЗ | Проверка | Результат |
|---|---|---|
| 44 плановых SVG в `svg/plan`, 33 иконки в `svg/menu` | `ls assets/furniture/houseplan-0.3.0/svg/plan \| wc -l`, `svg/menu` | 44 и 33 — совпадает |
| `furnitureRenderTransform` существует | `grep -r furnitureRenderTransform src/` | найден в `houseplan-card.ts`, `houseplan-editor-runtime.ts`, `furniture.ts` |
| `parseSvgPath` — производственный парсер экспорта | `grep -r parseSvgPath src/` | единственное определение в `src/pdf/svg-path.ts` |
| `kitchen_floor` — дизайнерский символ 60×60, `svg/plan/kitchen_floor.svg` | `pack.json` строки 580-600 | `width_cm: 60, depth_cm: 60, file: svg/plan/kitchen_floor.svg` — совпадает |
| `dishwasher` — legacy-примитив 60×60, заполняющий unit box | `pack.json` (единственная запись — `svg/menu/dishwasher.svg`, без `width_cm`) + `src/furniture.ts:155` (`w: 60, h: 60, g: [box(), …]`) | подтверждено: `dishwasher` не входит в дизайнерский пак, это legacy-примитив из `RETAINED_IDS`, `box()` рисует полный `0..1×0..1` |
| `plant` — единственный legacy-символ с полями 2% | `src/furniture.ts:226-231` (`e 0.5,0.5,0.22,0.22` + лучи-линии до `0.02`/`0.98`) | внешний bbox линий действительно `0.02…0.98` — 2% с каждой стороны, совпадает |
| Генератор склеивает `path` простой конкатенацией `paths.join(' ')` | `scripts/generate-furniture-assets.mjs:97` | `return { d: paths.join(' '), … }` — подтверждён ровно описанный дефект |
| `furniture-plan-art.generated.ts`, `furniture-plan-catalog.generated.ts` существуют | `ls src/*.generated.ts` | оба файла на месте |
| `furniture:check` — существующий гейт | `package.json:47` | `"furniture:check": "node scripts/generate-furniture-assets.mjs --check"` |
| `test/furniture-*.test.mjs` — свидетели AC1–AC5 | прочитаны `furniture-stroke-contract.test.mjs`, `furniture-transform-contract.test.mjs` | оба существуют, но проверяют другие контракты (#361/#376/#383 — экранный stroke-resolver, resize/rotate editor-контракт), а не bounds SVG-геометрии; конфликта с новыми AC нет, но новые unit-тесты AC1–AC4, скорее всего, лягут в отдельный новый файл — это техническая деталь, не продуктовая, решать разработчику |

Все фактические утверждения ТЗ подтвердились чтением кода — ни одной догадки,
выданной за факт, не найдено. Отдельно ценно, что владелец не просто принял
присланный дизайнером пак на слово, а перепроверил его **тем же
production-парсером**, которым будет проверяться AC1/AC2 (комментарий от
2026-09-16T19:33:08Z: 44 из 44, худшее отклонение `0.000000`) — то есть контракт
уже был воспроизведён на реальных файлах ещё до передачи в разработку.

## §7.1 — обязательные разделы

| Раздел §7.1 | Есть в ТЗ | Комментарий |
|---|---|---|
| Сценарий | ✅ «Пользовательский сценарий» | персона не названа явно (home admin), но контекст (свойства мебели, план) её однозначно определяет |
| Что человек увидит до/после | ✅ | числа названы (14% по стороне, 30% по площади), формулировка «это исправление, а не регрессия» — по делу |
| Проблема | ✅ | в теле issue выше `## ТЗ` («Что происходит») |
| Скоуп и не-скоуп | ⚠️ распределено | явного заголовка нет; не-скоуп фактически задан AC7 («редактор, hit-area, привязка к стенам, схема конфига и i18n не меняются») — содержание есть, форма нет. Low, не блокирует |
| Контракт поведения | ✅ «Контракт», пп. 1–8 | однозначен, проверен по коду (см. таблицу выше) |
| UX | ⚠️ отсутствует явно | по существу — «нет нового UX-контракта» (задача не трогает интеракции), это следует из AC7, но отдельного раздела нет. Low, не блокирует |
| Модель данных и миграция | ✅ «Совместимость и миграция» | миграции нет, обосновано |
| i18n | ✅ | явное «новых ключей нет» |
| AC1…ACn с доказательством | ✅ AC1–AC8 | у каждого назван способ (unit/golden/review/гейты) |
| План автотестов | ⚠️ распределено | не оформлен отдельным разделом, но каждый AC называет тип теста и файлы перечислены в «Затронутые файлы» — по существу план есть |
| Риски | ✅ «Риски» | 3 пункта, по делу (маскировка регрессии golden-пересъёмкой, склейка путей, рост ленивого чанка) |
| Откат | ✅ | «возврат коммита» — корректно для непереносимой миграции |
| Release-артефакты | ⚠️ частично | changelog RU+EN и golden названы (в «Затронутые файлы»), перф — отдельным разделом; **security явно не упомянут** (ни разу, даже «нет») |

## Находки

### Medium (в скоупе) — влияние на touch не названо

**Файл:** тело issue #584, раздел `## ТЗ`.

DoR §2.5 явно требует пункт «влияние на touch по `docs/TOUCH-SUPPORT.md` (View
и киоск — блокирующие)» как обязательный, отдельно от i18n и производительности,
которые в ТЗ присутствуют. В тексте ТЗ слова «touch», «тач», «киоск» не
встречаются вообще — раздел не просто краток, он отсутствует.

**Почему это не тривиальная придирка:** задача меняет физический видимый
размер мебели **в View/kiosk тоже**, не только в редакторе (мебель рендерится
и там, и там одним и тем же `furnitureRenderTransform`). AC7 отдельно
фиксирует «hit-area… не меняются», что фактически закрывает главный
touch-риск (позиция resize/rotate-хэндлов на touch не сдвигается), но это
написано как граница скоупа редактора, а не как ответ на явно
предусмотренный процессом пункт. Реальный риск, скорее всего, нулевой — но
DoR требует **явного** «нет», а не выводимого из соседнего пункта.

**Как закрыть:** одно предложение в ТЗ, например: «Touch: изменение
непосредственно не затрагивает — View/kiosk остаются readonly-поверхностью,
позиции hit-area и resize/rotate-хэндлов не пересчитываются (AC7); мебель в
редакторе визуально крупнее/меньше на ту же величину, что и в View, новых
touch-жестов не добавляется.» Правки кода не требует.

**Серьёзность:** Medium, в скоупе — блокирует переход в DoR (§2.5 явно требует
пункт), но правится добавлением одного абзаца в тот же issue, без нового цикла
имплементации. Без High это жёлтый вердикт.

### Low (снимается с записью, не блокирует)

1. **Раздел «UX» и «скоуп/не-скоуп» не оформлены отдельными заголовками.**
   Содержание по факту присутствует: AC7 однозначно перечисляет, что НЕ
   меняется (редактор, hit-area, привязка к стенам, схема конфига, i18n), а
   отсутствие нового UX-контракта следует из того же AC7 и из того, что задача
   правит только артворк и генератор. Формального заголовка нет, но
   переспрашивать автора ради двух заголовков дороже, чем цена неясности —
   снимаю с записью.
2. **Security как release-артефакт не назван даже «нет».** Задача не
   затрагивает ни одну поверхность из OWASP-класса рисков (правятся SVG-пути
   мебели и генератор ассетов, без сетевых вызовов, парсинга пользовательского
   ввода на новом пути или новых прав) — риска не вижу, но пункт DoR формально
   пуст. Снимаю с записью, а не как Medium: в отличие от touch, здесь нет
   спорной поверхности (View/kiosk), которую процесс называет блокирующей
   явно.
3. **AC3 «допуск, пропорциональный масштабу» не даёт формулу.** Это разумно
   оставить на усмотрение разработчика (технический, не продуктовый вопрос —
   §7.1: «то, чего пользователь не наблюдает, агенты решают сами») при
   условии, что реализация зафиксирует конкретную формулу и она останется
   проверяемой (не «плавает» между прогонами). Ревьюер кода должен убедиться,
   что тест «умеет падать» на конкретной, а не абстрактной величине допуска —
   отмечаю на будущее, не как находку ТЗ.

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

- **AC1–AC8 однозначны и снабжены способом доказательства** (unit / unit-generator
  / golden / review / гейты) — ни один не пришлось домысливать.
- **AC2 конкретен**: именно пара `kitchen_floor`/`dishwasher`, оба подтверждены
  в `pack.json`/`furniture.ts` как реальные `60×60` записи — тест будет
  проверять то, что реально описано в баг-репорте, а не абстракцию.
- **AC4 и контракт п.6** точно описывают дефект склейки путей — сверено с
  реальным кодом генератора (`paths.join(' ')`), включая упомянутые
  `coffee_table_round`/`table_round`.
- **Ни одной догадки, выданной за факт**: все количественные утверждения
  (44 символа, доля полей 2,7–3,9 у дизайнерских, 2% у `plant`, конкретные id
  и размеры) подтверждаются либо кодом, либо независимым измерением владельца
  тем же production-парсером, которым будет доказываться AC1.
- **Продуктовые вопросы закрыты владельцем предметно** (Q1 — видимый габарит
  = осевая линия контура, обводка не считается; Q2 — без миграции,
  центрируется в прежнем физическом боксе), открытых продуктовых вопросов в
  тексте не осталось; технические решения (склейка путей, `plant`) вынесены в
  явный блок «Принятые предположения», как требует §7.1.
- **Границы скоупа (AC7)** явно исключают редактор/hit-area/привязку к
  стенам/схему конфига/i18n — правка не расползается на соседние подсистемы.
- **Откат и совместимость** описаны корректно для правки без миграции: `x/y`,
  `w/h`, угол, зеркалирование сохраняются, откат — реверт коммита.
- **Риски названы предметно**, включая специфичный для этой задачи риск —
  маскировку чужой регрессии golden-пересъёмкой.

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

- Не проверял сам присланный дизайнером ZIP-архив (`fix-584-1`) —
  на этапе ревью ТЗ кода/ассетов ещё нет, они появятся в ветке реализации;
  их проверка (в том числе повторное измерение AC1/AC2 после факта) —
  предмет код-ревью.
- Не запускал `furniture:check`, `npm test`, `golden:verify` и т.п. — на
  этом этапе нет ни одной строки кода/ассета, гейты нечего гонять; это
  предмет §8 на код-ревью, не ревью ТЗ.
- Не проверял `docs/CONFIG-COMPATIBILITY.md` построчно на предмет
  дополнительных полей совместимости сверх того, что решает п.8 контракта —
  задача явно не трогает схему конфига (AC7), риск счёл пренебрежимым для
  ревью ТЗ.

## Итог

ТЗ содержательно сильное: контракт точен, AC проверяемы и уже частично
эмпирически подтверждены владельцем на реальном присланном паке тем же
инструментом, которым будет доказываться AC1. Единственная находка,
требующая правки текста, — отсутствующий явный пункт про touch/View/kiosk,
обязательный по DoR §2.5. High-находок нет, поэтому вердикт жёлтый:
одно предложение в ТЗ, без нового раунда имплементации.

---

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

- **Issue:** https://github.com/Matysh/houseplan-card/issues/584
- **Материал ТЗ:** тело issue #584, раздел `## ТЗ`, редакция комментария от
  2026-09-16T19:33:08Z (тот же комментарий ставит `S4-spec-review`).
- **Репозиторий на момент ревью:** `dev` @ `7c5fd32a08f07177d55905d65990180a354dd0ec`
  (кода по задаче ещё нет — ревью ТЗ смотрит только текст issue и сверяет его
  утверждения с текущим `dev`).

---

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

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

- Ветка: `dev`, коммит `7c5fd32a08f0` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `2b57427cbed60f2f3b46aaf1b2c9a84147a8ed88`
  ```
  git log --all --format='%H %T' | grep 2b57427cbed6
  ```
- Тело issue: `a4ec41f212d36f3ec2d313b534161c25a38e58c118ed2f7b97ab437de1593eb3`
- Вердикт конвейера: `yellow` · High 0