docs: review document for #505

Issue: #505
User-Visible: no

docs/reviews/SPEC-REVIEW-505-r2.md

@@ -0,0 +1,234 @@
+# SPEC-REVIEW-505-r2
+
+Issue: https://github.com/Matysh/houseplan-card/issues/505
+Стадия: ТЗ на ревью (`S4-spec-review`), полный трек (не пересматривается в r2 —
+основание трека не затронуто дельтой).
+Заход: r2 · блокирующих циклов израсходовано 1 из 4 (жёлтый r1 бюджет потратил;
+зелёный r2 цикла не образует, #227).
+Материал: `docs/specs/505-summary-panel-design-parity.md` на SHA
+`8c0962f36f2b93dd0c043806aa2e838d570fcd1c` (ветка `issue/505-summary-panel-polish`,
+коммит «docs: address summary panel spec review r1»). Рабочая копия уже стоит
+на этом SHA (`HEAD detached at origin/issue/505-summary-panel-polish`).
+
+## 1. Скоуп ревью — почему разбор по дельте
+
+Предыдущий раунд: `docs/reviews/SPEC-REVIEW-505-r1.md`, вердикт жёлтый,
+заход r1, High 0 / Medium 2 / Low 1, материал на SHA
+`8defee4ce1cb0f2794495c03173348c7a6c34e13`. SHA в вердикте r1 назван явно (в
+самом документе, раздел «Материал раунда») — расследовать не пришлось.
+
+Дельта: `git diff 8defee4ce1cb0f2794495c03173348c7a6c34e13..8c0962f36f2b93dd0c043806aa2e838d570fcd1c`
+затрагивает ровно два файла:
+
+- `docs/reviews/SPEC-REVIEW-505-r1.md` — публикация документа r1 конвейером
+  (не предмет разбора, это чужой артефакт);
+- `docs/specs/505-summary-panel-design-parity.md` — 46 insertions / 5 deletions,
+  единственный коммит `8c0962f3` с трейлерами `Issue: #505` / `User-Visible: no`.
+
+Правка сугубо аддитивна и локальна:
+
+1. добавлены два новых раздела в начало документа — «Сценарий» и «Что человек
+   увидит до и после» (перед прежним «1. Problem, value and scope»);
+2. переписан один абзац в конце §8 (список визуальных пар);
+3. добавлен раздел «Принятые технические предположения» в конец документа
+   (после прежнего раздела 9).
+
+Ни один из существующих разделов 1–9, таблица AC1–AC11, `Baseline`
+(`dev@abbca50c`), тело issue (`updated_at` issue = момент последнего
+комментария автора, содержимое не менялось со времени r1 — сверено
+построчно) не тронуты. Это не ребейз (baseline тот же `abbca50c`), не смена
+контракта поведения, не новая подсистема, объём дельты (46 строк) на порядок
+меньше исходного ТЗ (291 строка). Разбор по дельте: полная переоценка нужна
+только находкам r1 и участку текста, который они затронули; AC1–AC11 и весь
+технический анализ §2–7 наследуются без повторной проверки.
+
+## 2. Как проверялось
+
+- `git diff 8defee4c..8c0962f3 -- docs/specs/505-summary-panel-design-parity.md`
+  — построчно, для локализации правки и проверки отсутствия побочных правок.
+- Полное чтение текущего файла `docs/specs/505-summary-panel-design-parity.md`
+  на SHA `8c0962f3` (не только диффа) — чтобы увидеть новые разделы в
+  контексте, а не изолированно.
+- Прочитан текст issue #505 и все 5 комментариев (аналитика ×2, пауза,
+  возобновление, r1-вердикт, отчёт о правках) — подтверждено, что тело issue
+  и объём scope не менялись после r1, и что комментарий автора (`comment 4`)
+  корректно описывает содержание фактической правки.
+- Проверено соответствие терминологии персон в новом разделе «Сценарий»
+  канону `docs/SCOPE.md:28-30` — «Home admin» / «Household members» /
+  «Guests / kiosk» и их типовые поверхности (desktop / phone / wall tablet
+  kiosk) совпадают дословно по смыслу с «Администратор дома на desktop», «домочадец
+  ... на телефоне», «гость ... в киоске».
+- Проверено, что новые разделы не содержат терминов реализации (CSS/код/имена
+  функций) — только пользовательское поведение и персоны, как требует
+  PROCESS.md §7.1.
+- Проверено, что раздел «Принятые технические предположения» стоит в конце
+  документа (после раздела 9), как требует PROCESS.md §7 («записывается явным
+  блоком в конце ТЗ»), и что все четыре односторонних технических решения,
+  названные в r1-находке M2 (имя CSS-переменной, состав файлов, имена
+  i18n-ключей, механика generation-guard/анимации), в явном виде перечислены.
+- Проверено, что расширенный абзац visual evidence в §8 перечисляет все пять
+  контекстов чек-листа issue («Дополнительные критерии приёмки», пункт 4)
+  отдельно: desktop light, desktop dark, bottom portrait, kiosk, mobile View
+  panel — плюс отдельно диалог настроек light/dark desktop и narrow
+  native/real HA.
+- `grep -n '§[0-9]\|Sections'` по всему файлу — все существующие
+  перекрёстные ссылки (`§2–3`, `Sections4–8`, `§2`, `§7`, `§6`) продолжают
+  указывать на прежние номерованные разделы 1–9; новые разделы намеренно не
+  пронумерованы и не сдвинули нумерацию, поэтому ни одна ссылка не сломана.
+  Это лучше, чем предложенный в r1-находке M1 вариант «со сдвигом
+  нумерации» — автор выбрал более безопасный способ починки, не создав
+  новый класс дефекта (битые ссылки на разделы).
+- Прогнан `node scripts/process-gate.mjs --range 8defee4c..8c0962f3` →
+  «гейт пройден, предупреждений 0» (офлайн-часть; `--issues` не запускался —
+  статус issue уже виден в метках: `S4-spec-review`, без `blocked`).
+- Проверены трейлеры коммита `8c0962f3`: `Issue: #505`, `User-Visible: no` —
+  корректно, правка чисто документационная.
+- Проверен CI на точном материале ревью:
+  `gh run view 34316874922` → `Проверка (CI)`, `headSha ==
+  8c0962f36f2b93dd0c043806aa2e838d570fcd1c`, `status: completed`,
+  `conclusion: success`. Детализация по джобам (`gh api
+  .../commits/8c0962f3.../check-runs`): лёгкие джобы «Фронтенд: типы, юниты,
+  мутанты, синхрон бандла», «Предполётные проверки: документация, провенанс,
+  процесс», «Классификация изменённых файлов», «Мутанты по диффу (1–3/3)»,
+  «Переиспользование: это дерево уже проверено» — все `success`; тяжёлые
+  джобы (смоки, golden, perf, backend pytest, HACS/Hassfest) — `skipped`, что
+  ожидаемо для чисто документационного диффа класса C. **Уточнение к вводным
+  этого раунда**: там указано «Зелёного Validate на этом SHA нет — прогон не
+  найден, не завершён либо не success» — это не подтвердилось, как и в r1 с
+  тем же типом утверждения; прогон найден и зелёный именно на материале
+  ревью. Дополнительно вручную дешёвые гейты не гонялись сверх
+  `process-gate.mjs` — диапазон диффа ограничен `docs/**` (`git diff --stat
+  origin/dev..8c0962f3` подтверждает, что `src/**`/`custom_components/**` не
+  тронуты во всей ветке), поэтому `tsc`/`npm test`/`npm run build`/
+  `check-docs.mjs` к предмету этого раунда не относятся, а к предмету всей
+  ветки их уже покрыл зафиксированный зелёный CI-прогон на этом SHA.
+
+## 3. Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где это видно |
+|---|---|---|
+| Medium — отсутствуют разделы «Сценарий» и «Что человек увидит до и после» (PROCESS.md §7.1) | Оба раздела добавлены первыми в документе, до прежнего «1. Problem, value and scope»; названы персоны admin/household member/guest-kiosk по канону SCOPE.md, одна фраза «что увидит» без терминов реализации | `docs/specs/505-summary-panel-design-parity.md:9-22` (в текущем файле на `8c0962f3`) |
+| Medium — отсутствует раздел «Принятые технические предположения» (PROCESS.md §7/§7.1) | Раздел добавлен в конец документа; перечислены все 4 пункта из находки: имя CSS-переменной real-HA диалога помечено как подлежащее проверке, состав файлов §7 назван планом реализации, имена i18n-ключей допущены к переименованию при сохранении семантики, механика lifecycle-анимации (CSS transitions/WAAPI, generation guards) явно оставлена на усмотрение реализации | `docs/specs/505-summary-panel-design-parity.md:271-291` |
+| Low — неполный список визуальных пар в §8 | Абзац переписан, все пять контекстов чек-листа issue названы отдельно поимённо (desktop light/dark, bottom portrait, kiosk, mobile View panel) плюс отдельно диалог настроек | `docs/specs/505-summary-panel-design-parity.md:233-243` |
+
+Все три находки закрыты правкой того же файла без нового технического
+исследования, как и предполагал вердикт r1 («формат восстановим без нового
+анализа»). Новых дефектов формата правка не внесла — численность и ссылки
+разделов 1–9 не пострадали (см. §2 выше).
+
+## 4. Унаследовано из r1
+
+Принято без повторной проверки в этом раунде, основание — документ
+`docs/reviews/SPEC-REVIEW-505-r1.md` на SHA `8defee4ce1cb0f2794495c03173348c7a6c34e13`,
+поскольку дельта r1→r2 не затрагивает предмет этих пунктов:
+
+- продуктовая рамка и соответствие `docs/SCOPE.md` (исключение #437 для
+  read-only summary overlay), приоритет источников истины
+  owner > контракты House Plan > прототип > демо;
+- технический анализ причин всех четырёх исходных дефектов, подтверждённый
+  чтением кода `dev@abbca50c` (`renderPanel()` возвращает `nothing` без
+  exit-анимации, отсутствие exit-keyframes, `min-width` на `.summary-editor`,
+  несвязанный mobile-чекбокс, нерасширенный `Sizes on this screen`);
+- корректность механизма wide-диалога (`--hp-dialog-wide-width`,
+  `hp-dialog.ts:163`) как технически реализуемого пути;
+- согласованность с `docs/USER-GUIDE.ru.md` (раздел «Сводная панель»),
+  `docs/TOUCH-SUPPORT.md:48-56` (44×44 px, гарантированный View-контракт),
+  `docs/CONFIG-COMPATIBILITY.md:100-132` (namespace version 1 не меняется,
+  local size prefs вне серверного конфига);
+- целостность референс-архива `docs/design/505-summary-panel/reference/**` и
+  совпадение SHA-256 между README задачи, README референса и телом issue;
+- обновление `docs/specs/README.md` (строка для #505 добавлена);
+- полнота и однозначность таблицы AC1–AC11, включая требование
+  отрицательного свидетеля и mutation-gate для дорогих AC3/AC5;
+- отсутствие открытых продуктовых вопросов владельцу (текст ТЗ не выдаёт
+  догадку за факт нигде, кроме явно помеченного «verify actual pinned HA
+  frontend contract»).
+
+Эти пункты дельта r2 не касается: ни один из трёх изменённых участков текста
+(два новых вводных раздела, абзац visual evidence, финальный блок
+предположений) не переопределяет и не сужает ни один из перечисленных
+пунктов.
+
+## 5. Находки (r2)
+
+Нет. Дельта полностью закрывает обе Medium- и одну Low-находку r1, не
+привнося нового дефекта содержания или формата.
+
+## 6. Что проверено и корректно
+
+- Все три находки r1 закрыты по существу (см. таблицу §3), а не
+  переформулированы без изменения сути.
+- Терминология персон в новом разделе «Сценарий» — канонические термины
+  `docs/SCOPE.md`, не изобретённые.
+- «Что человек увидит до и после» — одна фраза, без терминов реализации,
+  как требует PROCESS.md §7.1.
+- «Принятые технические предположения» размещены в конце документа и явно
+  разрешают ревьюеру их оспорить — соответствует формулировке PROCESS.md §7.
+- Правка не переименовала и не сдвинула номера существующих разделов —
+  все внутренние перекрёстные ссылки (`§2–3`, `§6`, `§7`, `Sections4–8`)
+  остались корректны.
+- Baseline (`dev@abbca50c`), таблица AC1–AC11 и весь технический контракт
+  поведения (§2–7, §9) в дельте не менялись — не о чем спорить заново.
+- Коммит несёт корректные трейлеры (`Issue: #505`, `User-Visible: no` —
+  верно для чисто документационной правки), `process-gate.mjs` проходит без
+  предупреждений на диапазоне r1→r2.
+- CI зелёный именно на материале этого раунда (`8c0962f3`, run `34316874922`,
+  `Проверка (CI)`), включая релевантные для класса C джобы (фронтенд
+  типы/юниты/мутанты/синхрон бандла, предполётные документация/провенанс/
+  процесс).
+- Диапазон всей ветки `dev..8c0962f3` подтверждён как класс C: только
+  `docs/**`, продуктовый код не тронут.
+
+## 7. Чего не проверял
+
+- Полный повторный разбор разделов 1–9 и таблицы AC1–AC11 — не требуется,
+  дельта их не касается (обоснование в §1 и §4 выше).
+- Пиксельное сравнение реализации с прототипом и тяжёлые браузерные гейты
+  (`golden`, `smoke_*`, `performance_smoke`, `pytest tests_backend`) — как и
+  в r1, не относится к этапу ТЗ; продуктовый код по-прежнему не существует
+  и не менялся.
+- Содержимое архива `макет.zip` за пределами зафиксированного SHA-256 —
+  не переисследовалось повторно, наследуется из r1.
+- Флаг `--issues` у `process-gate.mjs` — статус issue подтверждён напрямую
+  через `gh issue view` (метка `S4-spec-review`, без `blocked`).
+
+## 8. Вердикт
+
+High: 0. Medium: 0. Обе Medium- и одна Low-находка r1 закрыты правкой того
+же документа, дельта не привнесла нового дефекта. Дельта локальна (один файл
+документации, 46/5 строк, без ребейза, без смены baseline, без смены
+контракта поведения) — полный переразбор не требуется и не проводился.
+
+Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0 → в задаче
+
+## Материал раунда
+
+- Ветка: `issue/505-summary-panel-polish`
+- SHA материала: `8c0962f36f2b93dd0c043806aa2e838d570fcd1c`
+- Дерево материала: `2af4e1c1420a56d9914b793d60e8024fd3181f16`
+  ```
+  git log --all --format='%H %T' | grep 2af4e1c1420a
+  ```
+- ТЗ `docs/specs/505-summary-panel-design-parity.md`, блоб `fed71b61cb26deae64fef8dc1a364d3401242d48`
+  ```
+  git log --all --find-object=fed71b61cb26deae64fef8dc1a364d3401242d48 -- docs/specs/505-summary-panel-design-parity.md
+  ```
+- Предыдущий раунд: `docs/reviews/SPEC-REVIEW-505-r1.md`, SHA `8defee4ce1cb0f2794495c03173348c7a6c34e13`
+- Вердикт конвейера: `green` · High 0 · Medium 0
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/505-summary-panel-polish`, коммит `8c0962f36f2b` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `2af4e1c1420a56d9914b793d60e8024fd3181f16`
+  ```
+  git log --all --format='%H %T' | grep 2af4e1c1420a
+  ```
+- ТЗ `docs/specs/505-summary-panel-design-parity.md`, блоб `fed71b61cb26deae64fef8dc1a364d3401242d48`
+  ```
+  git log --all --find-object=fed71b61cb26deae64fef8dc1a364d3401242d48 -- docs/specs/505-summary-panel-design-parity.md
+  ```
+- Вердикт конвейера: `green` · High 0