docs: review document for #462

Issue: #462
User-Visible: no

docs/reviews/SPEC-REVIEW-462-r1.md

@@ -0,0 +1,208 @@
+# SPEC-REVIEW-462-r1
+
+- **Issue:** https://github.com/Matysh/houseplan-card/issues/462
+- **Спецификация:** `docs/specs/462-card-resource-registration.md`, коммит `12ddd107`
+  (ветка `issue/462-card-resource-registration`, `HEAD` на момент ревью — тот же SHA)
+- **Трек:** полный (аналитика в issue назвала нарушенные критерии `small`:
+  несколько поверхностей, новый UX-контракт notification + kiosk auto-reload)
+- **Заход:** r1 · блокирующих циклов израсходовано 0 из 4 (лимит на полном треке — 4)
+
+## Скоуп ревью
+
+Прочитано перед разбором: `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (§1–10),
+тело issue #462 и все 7 комментариев, `docs/UX-MODES.md` (Kiosk mode),
+`docs/TOUCH-SUPPORT.md`, `docs/CONFIG-COMPATIBILITY.md` (выборочно, по ключевым
+словам kiosk/reload/version), `docs/USER-GUIDE.ru.md` (установка, киоск,
+существующий текст про плашку/перезагрузку из #353), README.md/README.ru.md,
+docs/USER-GUIDE.md.
+
+Сам документ ТЗ прочитан целиком (§1–22). Проверено соответствие §7.1
+`PROCESS.md`: все обязательные разделы присутствуют (сценарий — §1; что человек
+увидит — §2; проблема/подтверждённая причина — §3; скоуп/не-скоуп — §6/§7;
+контракт поведения — §8–11 + §4; UX — §11.2/§12; модель данных и миграция —
+§13; i18n — §14; AC1…AC13 с доказательством — §15; план автотестов — §16;
+риски — §19; откат — §20; release-артефакты — §21); плюс обязательный блок
+«принято предположительно, поменять свободно» — §22.
+
+## Как проверялось
+
+Ревью состязательное: без устных пояснений автора, только issue + ТЗ + код на
+`dev`. Каждое нетривиальное техническое утверждение спецификации сверено с
+реальным поведением платформы, а не принято на слово:
+
+1. **Существование ссылок на код.** Прочитаны и подтверждены в `dev`
+   (`16b4c2d6`/текущий `HEAD`): `_register_lovelace_resource` и
+   `_lovelace_resources` (`custom_components/houseplan/__init__.py:336–378`),
+   `manifest.json` (dependencies без `lovelace`), `system_health_info`
+   (`custom_components/houseplan/system_health.py`), `CARD_VERSION` в
+   `src/houseplan-card.ts:402` и отдельно в `src/houseplan-editor-runtime.ts:379`
+   (гейт `scripts/release-contract.mjs` уже держит их синхронными — не новая
+   проблема, существующий механизм), `_haIntegrationVersion`
+   (`src/houseplan-card.ts:2039,4094-4095,4882-4883` — **подтверждено**: при
+   отсутствующем/некорректном `integration_version` текущий код **не
+   очищает** значение, оставляет старое — именно это правит AC6/§11.1, и это
+   реальный баг, а не выдумка), `_preflightVersionsDiffer`
+   (`houseplan-editor-runtime.ts:9610`), `_cyclePausedUntil`/`_zoom`/`_editing`
+   /`_pendingPhysicalWrites`/`_writesPending`/`_vacFit`
+   (`src/houseplan-card.ts`, `houseplan-editor-runtime.ts` — все существуют
+   ровно с тем смыслом, который им приписывает ТЗ).
+2. **Проверка ключевой технической гипотезы §3 против реального HA API.**
+   Спецификация утверждает: hard-зависимость `houseplan → frontend → lovelace`
+   уже гарантирует порядок настройки на HA 2024.6 (минимально поддерживаемая) и
+   актуальной ветке. Я не поверил на слово и скачал реальные wheel-пакеты
+   `homeassistant==2024.6.0` и `homeassistant==2025.1.4` (более новых нет в
+   доступном индексе) и прочитал `manifest.json` обоих компонентов:
+   `frontend` **действительно** объявляет `"dependencies": [..., "lovelace", ...]`
+   в обеих версиях; `lovelace` зависит только от `onboarding`. Цепочка в ТЗ
+   подтверждена буквально, а не додумана — редкий случай, когда стоило
+   перепроверить смелое техническое утверждение и оно оказалось верным.
+3. **Проверка технической реализуемости §8.2 п.9 (`remove_extra_js_url`).**
+   В том же скачанном `homeassistant==2024.6.0` функции
+   `remove_extra_js_url` в `homeassistant/components/frontend/__init__.py`
+   **нет** (появляется только в более поздних версиях — подтверждено в
+   `2025.1.4`). Это значит, что состояние `lovelace_resource_with_session_fallback`
+   из §8.3 — не гипотетический край, а **обязательный путь на всей матрице
+   минимально поддерживаемой HA**, если retry случился после fallback. ТЗ это
+   учитывает явно (AC3: «…снимает fallback либо честно маркирует его
+   остаток»). Найдено правильно.
+4. **Проверка `async_at_started`.** Подтверждено по исходнику
+   `homeassistant/helpers/start.py` (2024.6): возвращает `CALLBACK_TYPE`,
+   пригодный для `entry.async_on_unload`, ведёт себя точно как описано в §22 п.3.
+5. **Сверка документации.** `grep` по всем `.md` файлам репозитория нашёл ровно
+   4 места с невалидным плоским `resources:` — README.md:101, README.ru.md:105,
+   docs/USER-GUIDE.md:94, docs/USER-GUIDE.ru.md:93 — это ровно тот список,
+   который называет §12/§17. Пропущенных мест нет.
+6. **Проверка терминологии.** `kiosk: true`, `_cyclePausedUntil`, 60-секундная
+   пауза автолистания и условие масштаба 1:1 совпадают с уже описанным
+   контрактом в `docs/UX-MODES.md` («Kiosk mode»). i18n EN/RU/DE/FR — то же
+   множество языков, что уже существует в `src/i18n/` и
+   `custom_components/houseplan/translations/`, не новая номенклатура.
+
+## Находки
+
+### Medium (в скоупе задачи) — пересечение нового баннера с существующим тостом #353
+
+`docs/USER-GUIDE.ru.md:111-119` документирует уже существующий (issue #353)
+механизм: если открытая вкладка держит код одной сборки, а lazy-чанк
+редактора (`Plan`/`Devices`/`Подложка`) отдаётся с несовпадающим
+`ENTRY_BUILD_FINGERPRINT` (`src/editor-runtime-loader.ts`), при попытке
+открыть редактор показывается **тост** «`editor.load_failed` +
+`editor.refresh_advice`» — «поможет только перезагрузка страницы». Это
+триггерится независимо от `CARD_VERSION`/`integration_version` — по
+fingerprint конкретного lazy-чанка, полученного через `import()`.
+
+Новый runtime version controller (§11.1–§11.2) вводит **второй** независимый
+триггер той же самой user-facing просьбы («перезагрузите страницу») —
+несовпадение `CARD_VERSION`/`integration_version` — и явно требует показывать
+его «в обычном режиме... включая editor и открытый dialog» (§11.2). При этом:
+
+- ничто в `_setMode`/клике по вкладке редактора (`src/houseplan-card.ts:7429-7444`,
+  `:11451`) не блокируется и не учитывает состояние version-mismatch — переход
+  в редактор всегда возможен;
+- реалистичный сценарий: HA/интеграция обновились, у пользователя открыта
+  вкладка → banner уже показан (баннер триггерится раньше, сразу на
+  следующем `config/get`); пользователь всё равно кликает «План» → lazy-чанк
+  редактора либо переехал/удалён на новую версию, либо не совпадает
+  fingerprint'ом → **тост поверх уже показанного баннера**, с другим текстом
+  того же смысла.
+
+ТЗ ни разу не обсуждает это пересечение в поведенческих разделах (§8–22): #353
+упомянут только в шапке ("Связано") без анализа. Не решено ни одно из:
+подавлять ли тост, пока баннер уже сообщил о том же; должен ли известный
+mismatch блокировать/предупреждать вход в редактор заранее; допустимо ли
+одновременное появление тоста и баннера как есть. Это ровно то расхождение,
+о котором предупреждает §8 `PROCESS.md` («одно число — один источник») в
+широком смысле — здесь не число, а **одна и та же пользовательская просьба
+через два независимых, не согласованных друг с другом триггера** — тот же
+класс дефекта, что стоил продукту #234/#233.
+
+**Возврат автору.** Достаточно одного явного решения в ТЗ (тост подавляется,
+пока показан баннер того же смысла — или наоборот, или оба допустимы с
+обоснованием) плюс отражение выбора в AC12/плане тестов. High-находок нет,
+поэтому по Medium-в-скоупе — жёлтый вердикт, чинится в этой же задаче
+(владелец, 2026-08-19, #202).
+
+### Low — числовой touch-target 44×44 не имеет источника в каноне
+
+§11.2 требует «touch-target кнопки не менее 44×44 CSS px». Ни в
+`docs/TOUCH-SUPPORT.md`, ни в `docs/UX-MODES.md`, ни в существующем коде
+(`grep` по `44px`/`min-width: *44` в `src/*.ts` — пусто) такого порога нет; это
+не переиспользование канона, а собственное (хоть и общепринятое,
+WCAG/Apple HIG) число автора. Не помечено в §22 как предположение. Влияния на
+продукт это не меняет (число консервативное и безопасное), поэтому не
+поднимаю до Medium — можно поправить формулировкой «стандартный
+accessibility-минимум (не описан в каноне отдельно)» или добавить строкой в
+§22. Не блокирует, правится на усмотрение автора либо снимается запиской.
+
+## Что проверено и корректно
+
+- Все обязательные разделы §7.1 присутствуют по существу (см. «Скоуп ревью»).
+- Каждый AC1–AC13 имеет однозначную формулировку и названный способ
+  доказательства (`unit`/`backend`/`browser`/`golden`/`build`/`ревью кода`),
+  без AC, доказательство которых осталось бы неясным.
+- Ни одного продуктового вопроса, оставленного нерешённым: единственная
+  продуктовая развилка (тихая kiosk-перезагрузка) решена владельцем в
+  комментариях issue (05.09.2026) и внесена в тело/ТЗ дословно.
+- Технический выбор `persistent_notification` вместо Repairs (§22 п.1)
+  первоначально выглядел как неподтверждённое решение владельца («потому что
+  контракт владельца» без цитируемого комментария) — проверено против
+  прецедента: `custom_components/houseplan/repairs.py` уже использует Repairs
+  строго для сохраняющихся дефектов (пропавший файл плана, снимается при
+  исправлении), что структурно отличается от одноразового onboarding-сообщения
+  «карточка подключена, перезагрузите». Выбор обоснован существующей
+  конвенцией репозитория и корректно помечен как «можно менять на ревью» —
+  не поднимаю как находку.
+- Гипотеза о startup race (§3) и связанные с ней §8.2/§22 п.3 проверены против
+  реального API `homeassistant` 2024.6/2025.1.4 (см. «Как проверялось», п.2–4)
+  — технически точны.
+- Список файлов документации, которые чинит §12, — исчерпывающий (сверено
+  `grep`).
+- Терминология (kiosk, плашка/подсказка, языки i18n) не изобретена, берётся из
+  `docs/USER-GUIDE.ru.md`/`docs/UX-MODES.md`/существующего `src/i18n`.
+- `docs/CONFIG-COMPATIBILITY.md`: заявление §13 «формат плана/layout/store не
+  меняются, миграция не нужна» согласуется с общей философией документа
+  (аддитивные optional-поля не требуют миграции схемы).
+- `docs/TESTING.md:972` подтверждает необходимость правки release-чеклиста,
+  названную в §21 (текущий пункт не упоминает обязательность reload).
+- SCOPE.md: задача закрывает J4 (zero-to-plan onboarding) и общую надёжность
+  первого запуска; из «Out of scope» ничего не задето; lock-инвариант не
+  применим (нет управления замками).
+
+## Чего не проверял
+
+- Не проверялась реализация (её нет — это ревью ТЗ, код ещё не написан).
+- Не прогонялись `typecheck`/`test`/`build` — на этапе спецификации нет кода
+  для сборки; гейты применимы к код-ревью, не к этому этапу.
+- Не проверялся HA 2026.8 напрямую — недоступен в индексе pip на момент
+  ревью (последняя видимая версия — 2025.1.4); экстраполяция на «актуальную»
+  ветку опирается на многолетнюю стабильность связи `frontend → lovelace` в
+  проверенных версиях, а не на точный релиз.
+- Не проверялось поведение `persistent_notification.async_create` с точки
+  зрения точного API (idempotent `notification_id`) — это стандартный,
+  многократно проверенный в экосистеме HA паттерн, не специфичный для этой
+  задачи; углублённая проверка не показалась пропорциональной риску.
+- Не оценивался landing page/дистрибуция (вне репозитория, зона Claude по
+  `AGENTS.md`, не часть ТЗ).
+
+## Материал раунда
+
+- Ветка: `issue/462-card-resource-registration`
+- SHA материала: `12ddd107a9cdd9b12ea8411360760f684f5293c1`
+- Файл ТЗ: `docs/specs/462-card-resource-registration.md` (полная редакция,
+  зафиксированная этим коммитом)
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/462-card-resource-registration`, коммит `12ddd107a9cd` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `2e4d5a20cc878962b7689e3a8603703577daba01`
+  ```
+  git log --all --format='%H %T' | grep 2e4d5a20cc87
+  ```
+- ТЗ `docs/specs/462-card-resource-registration.md`, блоб `fd9bc322a17b303c3e76495ef3233fb9324010d8`
+  ```
+  git log --all --find-object=fd9bc322a17b303c3e76495ef3233fb9324010d8 -- docs/specs/462-card-resource-registration.md
+  ```