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

# SPEC-REVIEW-598-r1

**Issue:** https://github.com/Matysh/houseplan-card/issues/598
**Заголовок:** Три оставшихся диалога настроек на общий набор контролов: Пространство, Общие,
Устройство (шаг 3 эпика #591)
**Этап:** ревью ТЗ (PROCESS.md §2.4)
**Заход:** r1 · блокирующих циклов израсходовано (до этого раунда) 0 из 4
**Материал:** тело issue #598, раздел `## ТЗ`, на момент чтения 2026-09-19. Комментариев к
issue на момент ревью — 0 (`gh api repos/Matysh/houseplan-card/issues/598/comments` → `length: 0`),
поэтому раздела «Унаследовано из r0» не требуется — это первый заход.

## Скоуп ревью

Ревью ТЗ, не код: код по этому issue не писался (веток `issue/598-*` в репозитории нет,
рабочая копия на `dev`, `git status` — чисто). Проверялась (а) полнота обязательных разделов
ТЗ по PROCESS.md §7.1, (б) однозначность и проверяемость AC1…AC10, (в) отсутствие догадок,
выданных за факт — каждое числовое или структурное утверждение ТЗ сверено с реальным деревом
`src/`, `demo/`, `docs/`, а не принято на слово.

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

Технической реализации нет, поэтому «прогон гейтов» неприменим — сверка шла чтением дерева на
`dev` (SHA `958ab366`, рабочая копия чистая) против конкретных утверждений ТЗ:

1. Счётчики файлов и разметки — `wc -l` трёх диалогов и `form-kit.ts` (177/318/760/140 строк) —
   совпадают с таблицей «Что предстоит переработать» построчно.
2. Классы-опоры К5 — `grep` по `demo/*.mjs`: `.srcrow` встречается в 9 файлах
   (`smoke_discovery_filters`, `smoke_ha_controls`, `smoke_hide_layers`, `smoke_room_settings`,
   `smoke_room_tooltip_toggle`, `smoke_space_create_display_defaults`, `smoke_sun`,
   `smoke_tap_run`, `smoke_ux_fixes`), `.dispsection` — в 2 (`smoke_backup_transfer`,
   `smoke_general_settings`). Совпадает с текстом ТЗ буквально.
3. Существующие примитивы набора (`form-kit.ts`): `formCard`, `formRow`, `segmented`,
   `colorRow`, лёгкий CSS-лист через `ensureFormKitStyles` — реально существуют и уже лежат в
   ленивом редакторском графе (комментарий в файле прямо называет измеренный бюджет из #594),
   что подтверждает К7 и AC9 не как обещание, а как состояние кода.
4. `hp-color-opacity` используется во всех трёх целевых файлах плюс в уже переведённом
   `room-settings-dialog.ts` — К3 не изобретает нового компонента.
5. `hpf-switch` в коде не существует (`grep -n "hpf-switch" src/editors/*.ts` — 0 совпадений,
   `withSwitch: false` зашито в текущей сборке листа) — ТЗ сама называет это «принято
   предположительно, поменять свободно» и даёт откат («дешевле оставить `.srcrow` как есть»).
   Корректно помечено, не выдано за решённый факт.
6. Мутанты `dialog-control-writes-to-a-neighbour-key` и `dialog-segment-drops-radio-semantics`
   в `scripts/mutation-registry.mjs` пока не существуют, но по нему уже есть точный прецедент
   того же автора того же приёма — `form-kit-writes-to-a-neighbour-key` (патч в
   `room-settings-dialog.ts`, страж `smoke_room_settings.mjs`) и
   `form-kit-segment-drops-radio-semantics` (патч в `form-kit.ts`, страж `test/form-kit.test.mjs`)
   из #594. Именование и форма ссылки на ещё не написанный мутант соответствует уже принятой в
   реестре практике — это не догадка, а перенос доказанного шаблона.
7. Все 11 поимённых golden-сцен AC7 существуют в `demo/golden/baselines/baselines-index.json`
   (`scenarios` содержит все 11 id, всего сцен в индексе — 173) — сцены не изобретены, это
   реальные существующие кадры, часть которых пересматривается намеренно.
8. `space.display_section`/`space.roomcard_section` реально существуют и переиспользуются как
   заявлено; арифметика счётчика новых заголовков (5 «Общих» + 2 «Пространства» + 5
   «Устройства» = 12 × 4 языка = 48 строк) подтверждается построчным разбором UX-таблиц —
   см. находку M1 про второй ряд той же таблицы.
9. Терминология «карточки-группы» уже используется `docs/USER-GUIDE.ru.md:572` для диалога
   комнаты (#594) — ТЗ #598 не изобретает новый термин интерфейса, а продолжает принятый.
10. 44 px в К6/AC5 — не число из воздуха, это документированный минимум `docs/TOUCH-SUPPORT.md`
    (строки 14, 72, 97).
11. `smoke_backup_transfer.mjs` собирает `.dispsection` через `.some(node => textContent === …)`,
    а не по индексу/соседству — перекладка в карточки такую проверку не ломает, заявление AC2
    «без единой правки» для этого смока правдоподобно.
12. `smoke_general_settings.mjs` сегодня собирает `out.groups` как список ВСЕХ `.dispsection` —
    девять штук. Из УX-таблицы следует, что `gs.glow_group` и `gs.sun_group` в новой раскладке
    становятся заголовками карточек (`<h3>` в `formCard()`, без класса `.dispsection`), а не
    остаются подзаголовками — то есть реальный состав `.dispsection` после переделки — семь, не
    девять. Это ровно то расширение, которое ТЗ называет единственным допустимым в AC3: вывод
    ревью — AC3 корректно предвидит настоящую причину изменения смока, а не создаёт её.

## Находки

### M1 (Medium, в скоупе) — судьба `marker.run_target_gone` не решена, счётчик i18n не сходится

**Где:** раздел «i18n», строка `.help` + `.help.aria` для семи существующих пояснений
(14 ключей × 4 языка = 56 строк); раздел «УX» → «Устройство на плане»; К4.

**Воспроизведение:**

- Вводная таблица ТЗ («Что предстоит переработать») называет ровно одно
  пояснение-абзац диалога устройства — `marker.run_target_gone` (строка
  `src/editors/marker-dialog.ts:334`, `<div class="rhint">`).
- УX-раздел расписывает, какую карточку и чей текст получает «?», для каждого
  переносимого пояснения **кроме этого**: «Общие» — 4 явные пары «карточка → текст»
  (`gs.hint`→«Цвета заливки комнат», `gs.radar_show_live_hint`→«Отображение»,
  `gs.backup_hint`/`gs.grid_hint`→«Данные»); «Пространство» — явно
  `space.hide_decor_tip`/`space.hide_openings_tip`→«Внешний вид». Итого явно
  названо **6** пояснений. Для «Устройства» ни один из пяти рядов таблицы карточек
  не называет пояснение и не связывает `marker.run_target_gone` ни с одной из
  пяти карточек.
- Таблица i18n утверждает «семь существующих пояснений». Явно поимённо в тексте
  ТЗ названо шесть. Седьмым может быть только `marker.run_target_gone` — но тогда
  ТЗ обязано сказать, в какую из пяти карточек устройства едет его «?», как это
  сделано для всех шести остальных.
- Альтернатива — `marker.run_target_gone` остаётся инлайновым callout'ом, как
  `gs.sun_missing` (который К4/УX прямо называют исключением: «gs.sun_missing
  остаётся callout'ом»). Но для `run_target_gone` такого исключения текст не
  формулирует, хотя по факту (строка кода) это ровно тот же паттерн: условный
  инлайновый предупреждающий текст с переменной (`{id}`), а не статичное
  объяснение настройки.
- Разница ощутима для AC4: «абзацев-пояснений в трёх формах не осталось» —
  формула безусловная. Если `run_target_gone` остаётся как есть, AC4 в этой
  редакции не выполняется буквально (абзац остался); если он переезжает под «?»,
  разработчику неизвестно, в какую карточку, и ревьюеру кода нечем судить
  результат, кроме собственной догадки.
- Сама арифметика тоже расходится: если верно, что пояснений было 6 (гипотеза
  «run_target_gone — callout, как sun_missing»), то строка i18n должна быть
  «6 × 2 × 4 = 48», а не «7 × 2 × 4 = 56»; итоговая сумма ключей/строк ТЗ (26
  ключей / 104 строки) в этом случае тоже должна быть на 1 ключ и 4 строки меньше.

**Почему это Medium, а не Low:** это не опечатка в тексте, а нерешённый вопрос,
прямо влияющий на проверяемость AC4 в самом рискованном из трёх файлов (устройство
— 760 строк, единственный без единой существующей группы, по риску №2 самого ТЗ).
Без решения код-ревьюер не может отличить правильную реализацию от нарушения AC4
чтением диффа — придётся гадать так же, как автор кода.

**Почему в скоупе:** диалог устройства прямо входит в скоуп этого issue
(`src/editors/marker-dialog.ts` — первая строка таблицы скоупа), решение
технического характера (куда девать один инлайн-текст), не продуктовое — автору
ТЗ решать самому, без вопроса владельцу.

**Чем закрывается:** один из двух вариантов, явно вписанный в текст ТЗ —
(а) добавить `marker.run_target_gone` в перечень пояснений с картой «карточка →
текст» вроде остальных шести (тогда i18n-таблица подтверждает «7», разночтения не
возникает), либо (б) явно объявить его исключением, аналогичным `gs.sun_missing`,
и убрать из счётчика (тогда i18n-таблица и итоговая сумма ключей пересчитываются
на «6»/48/96 вместо 7/56/104). Любой из двух вариантов делает AC4 проверяемым без
догадки.

## Что проверено и признано корректным

- Обязательные разделы §7.1 присутствуют все: сценарий, что человек увидит до/после,
  проблема, скоуп/не-скоуп, контракт поведения (К1–К7), UX, модель данных и
  миграция, i18n, AC1–AC10 с доказательством и способом покраснения, план
  автотестов, риски, откат, release-артефакты. Ничего не пропущено.
- Первые два раздела продуктовые и отвечают на «какая персона/поверхность/момент» и
  «что видно одной фразой без терминов реализации» — соответствует §7.1 буквально,
  и персона (администратор дома) верно привязана к SCOPE.md («Editors are
  admin-only tools»).
- Скоуп/не-скоуп — образцовый: не-скоуп перечисляет ровно то, что архивный `SPEC.md`
  эпика #591 предлагал сверху (активность «Сохранить», инлайн-цвет, плитки, компас,
  футер, ширина) и что уже было осознанно оставлено вне #594 — граница
  воспроизведена, а не придумана заново.
- К1–К7 проверяемы и опираются на существующий код, а не на воображаемое поведение
  (см. «Как проверялось» пп. 3–6, 10).
- Классы риска §2.6 разобраны все шесть, неприменимые обоснованно помечены
  («геометрия — не применимо», «async — не применимо: перекладка синхронной
  разметки»), а не пропущены молча.
- AC7 (golden) называет ровно те 11 сцен, которые реально существуют в индексе, и
  корректно суммируется с построчным разбором «7 устройство + 3 общие + 1
  пространство» из раздела «Риски» №2.
- AC2/AC3 логически согласованы: AC3 верно предсказывает, что `smoke_general_settings`
  — единственный смок, требующий правки, и по правильной причине (переход
  `gs.glow_group`/`gs.sun_group` из подзаголовков в заголовки карточек меняет
  реальный состав `.dispsection`, а не просто «на всякий случай»).
- «Принято предположительно» блок в конце корректно отделяет технические решения
  (имена ключей, включение `hpf-switch`, порядок карточек, `label.dispsection` для
  подзаголовков) от продуктовых — ни одно продуктовое решение туда не спрятано.
- Открытых вопросов владельцу в тексте нет, и по итогам проверки такого вопроса не
  появилось: единственная находка (M1) — техническая, автор ТЗ решает её сам.

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

- Не запускал `npm test` / `npm run typecheck` / `npm run build` — на этапе ревью ТЗ
  кода ещё нет (ветки `issue/598-*` не существует), гейты неприменимы; они
  относятся к код-ревью этого issue.
- Не проверял, действительно ли CI сможет прогнать смоки/golden с текущими путями —
  это код-ревью проверит по факту диффа; на этапе ТЗ проверялась только
  правдоподобность заявленных путей и существующих файлов, а не их прогон.
- Не оценивал соответствие присланного архивного `SPEC.md` (файлов
  из архива эпика #591) построчно — ТЗ прямо и осознанно берёт из него только
  раскладку и явно называет, что остальное (поведение) отклонено; сверять
  отклонённые части не было предмета ревью.
- Не проверял французскую (`fr`) локаль на предмет реальных значений строк — только
  то, что счётчик «4 языка» соответствует существующим `en/ru/de/fr` словарям.

## Вердикт

Единственная находка — Medium, в скоупе задачи, без High. Согласно PROCESS.md §2.4/§7.2,
это жёлтый вердикт: автор правит ТЗ (решает судьбу `marker.run_target_gone` явно и
приводит счётчик i18n в соответствие), фикс проходит повторный цикл ревью ТЗ.

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

---

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

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

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