diff --git a/docs/reviews/SPEC-REVIEW-505-r2.md b/docs/reviews/SPEC-REVIEW-505-r2.md new file mode 100644 index 00000000..24617444 --- /dev/null +++ b/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 + +--- + + + +## Материал раунда + +- Ветка: `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