# SPEC-REVIEW-462-r2
- **Issue:** https://github.com/Matysh/houseplan-card/issues/462
- **Спецификация:** `docs/specs/462-card-resource-registration.md`, коммит `e9e3d6bd`
(ветка `issue/462-card-resource-registration`, HEAD на момент ревью — тот же SHA)
- **Трек:** полный
- **Заход:** r2 · блокирующих циклов израсходовано 1 из 4 (лимит на полном треке — 4)
## Материал раунда r1 (для дельты)
- Предыдущий вердикт: жёлтый · заход r1 · High: 0 · Medium: 1 → в задаче
(комментарий issue, 2026-09-05T11:03:23Z).
- **SHA в самом вердикте (комментарии issue) не назван** — это находка процесса
фиксации, отдельно от содержательного разбора (см. «Находки», Low-2). SHA
восстановлен из документа `docs/reviews/SPEC-REVIEW-462-r1.md`, где он назван
явно: `12ddd107a9cdd9b12ea8411360760f684f5293c1`, и подтверждён порядком коммитов
(`910eedb4 docs: review document for #462` — публикация документа r1 —
следует сразу за `12ddd107`, до `8973431f`, который отвечает на находку r1).
- Дельта этого раунда: `git diff 12ddd107..e9e3d6bd -- docs/specs/462-card-resource-registration.md`
(151 изменённая строка), двумя коммитами:
`8973431f` («Замечание SPEC-REVIEW r1 исправлено» + новый YAML resource_mode
контракт + источник touch-target) и `e9e3d6bd` («устранены технические
двусмысленности» — retry timing/cancellation, нормализация версии, translations
category, card-level overlay в ранних render-states, kiosk-guard дополнения).
Дельта не локальна: она вводит новый терминологический контракт поведения HA
(«YAML resources mode» vs «Legacy full-YAML dashboard mode», см. ниже) и меняет
формулировку четырёх AC (AC1, AC3, AC12, AC13) плюс план тестов и риски. По
правилу «смена контракта поведения → полный разбор» я перечитал документ
целиком (§1–22) и проверил новые технические утверждения по коду HA, а не
только территорию, формально задетую диффом.
## Скоуп ревью
Прочитано перед разбором: `docs/SCOPE.md` (Core user jobs, J4), `AGENTS.md`,
`PROCESS.md` §1–10, тело issue #462 и все 8 комментариев (включая решение
владельца о тихой kiosk-перезагрузке и аналитику 2026-09-05), документ и
находки `SPEC-REVIEW-462-r1.md`, `docs/UX-MODES.md` (Kiosk mode),
`docs/TOUCH-SUPPORT.md`. Сам документ ТЗ — целиком, §1–22.
## Как проверялось
Ревью состязательное: issue + ТЗ + код `dev` + прямая проверка технических
утверждений о платформе HA, без доверия формулировке «по официальному контракту
HA» на слово (именно так был подписан коммит `8973431f`).
1. **Материал среды.** `pip index versions homeassistant` в этом окружении
зеркалирует PyPI и обрывается на `2025.1.4` (последняя доступная версия) —
то же ограничение уже зафиксировал r1 («не проверялся HA 2026.8 напрямую»).
Скачан `homeassistant==2025.1.4` (`pip download --no-deps`) и прочитан исходник
компонента `lovelace`.
2. **Ключевая новая находка.** `homeassistant/components/lovelace/__init__.py`
(2025.1.4) содержит единственный `CONFIG_SCHEMA` для домена `lovelace`:
```python
vol.Optional(CONF_MODE, default=MODE_STORAGE): vol.All(vol.Lower, vol.In([MODE_YAML, MODE_STORAGE])),
vol.Optional(CONF_DASHBOARDS): ...,
vol.Optional(CONF_RESOURCES): [RESOURCE_SCHEMA],
```
Один `mode` одновременно решает: (а) в YAML ли dashboard, (б) читаются ли
`resources:` из YAML. В ветке `else` (mode != yaml, т.е. storage — умолчание)
код явно делает `_LOGGER.warning("Lovelace is running in storage mode. Define
resources via user interface")`, если `yaml_resources is not None` — то есть
**подтверждает**, а не опровергает исходную посылку issue («в storage-режиме
`lovelace.resources` из YAML игнорируется целиком»). Отдельного ключа
`resource_mode`, который расцеплял бы «источник ресурсов» и «режим dashboard»,
в схеме нет. `grep -r resource_mode` по всему распакованному пакету (`.py`,
все файлы) — ноль совпадений. `grep -rn resource_mode` по всему репозиторию
houseplan-card вне `docs/specs/462-*.md` — тоже ноль: концепция не
встречается больше нигде в кодовой базе, документации или прежних раундах.
3. **Попытка проверить внешний источник.** `WebSearch`/`WebFetch` недоступны в
этой сессии («haven't granted it yet» на оба вызова, дважды). Верификация
ограничена локальным кодом платформы и внутренней согласованностью
документа — этого достаточно, чтобы поднять находку, но не достаточно, чтобы
на 100% исключить более поздний upstream-релиз (ниже, «Чего не проверял»).
4. **Проверка синхронности `persistent_notification.async_create`.** §9 теперь
утверждает: флаг «уведомление создано» пишется «сразу после того, как
синхронный callback `persistent_notification.async_create` вернулся без
исключения». Подтверждено в исходнике 2025.1.4:
`homeassistant/components/persistent_notification/__init__.py` — функция
помечена `@callback` (не `async def`, не корутина), тело — синхронная запись
в dict + `async_dispatcher_send`, реальных исключений в штатном пути нет.
Формулировка точна.
5. **Проверка card-level overlay в ранних render-состояниях (§11.2).**
`src/houseplan-card.ts:11282-11320` — реальность подтверждена: `fixed.kind
=== 'pending'`, `'invalid'` и `!model.length` действительно возвращают три
независимых `...` шаблона до основной сцены. Требование
«отдельные копии разметки в render-ветках не становятся независимыми
состояниями» — не выдумка, а корректный ответ на реальную структуру кода;
без него легко забыть плашку в одной из трёх веток.
6. **Проверка закрытия Medium-находки r1** (баннер против тоста #353) — по
тексту нового §11.2 и обновлённых AC12/§16 (ниже, «Закрытие раунда r1»).
7. **Проверка закрытия Low-находки r1** (число 44×44 без источника) — §22 п.8.
## Находки
### High — новый контракт `lovelace.resource_mode: yaml` не подтверждён и
### противоречит и коду HA, и собственной посылке issue
Введено в этом раунде (`8973431f`, отсутствовало в редакции r1). §5, §12, AC1 и
план тестов (§16 «Docs/mutation») теперь утверждают, что в «HA 2026.2+»
`lovelace.resource_mode: yaml` — независимый от `lovelace.mode` ключ, который
подключает YAML-ресурсы к storage-managed dashboard. Формулировка прямая,
без оговорки «предположение»: «Нельзя утверждать, что `lovelace.resources`
всегда игнорируется storage-managed dashboard: в HA 2026.2+ именно
`resource_mode: yaml` поддерживает YAML-ресурсы независимо от режима
dashboard» (docs/specs/462-card-resource-registration.md:405-408). Коммит
`8973431f` в issue подписан «по официальному контракту HA» — то есть подан как
проверенный факт, не как гипотеза.
Что не сходится:
- В единственной доступной для проверки версии HA (`2025.1.4`, актуальная в
индексе pip этого окружения) ключа `resource_mode` не существует нигде —
ни в `lovelace`, ни где-либо ещё в пакете. Единственный `mode` управляет и
dashboard, и тем, читаются ли `resources:` из YAML.
- Это прямо противоречит тому, что сама схема делает сегодня: `resources:` под
`lovelace:` **действительно игнорируется** (с explicit warning) при
`mode: storage` — то есть исходная посылка issue («в storage-режиме
`lovelace.resources` из YAML игнорируется целиком») **подтверждена кодом**, а
не опровергнута, как теперь пишет ТЗ.
- Это противоречит собственному телу issue (написано владельцем в тот же день):
«в storage-режиме дашбордов (умолчание HA) `lovelace.resources` из YAML
игнорируется целиком» — заявлено как подтверждённый факт полевого разбора, не
снято ни одним последующим комментарием.
- `vol.Schema({...})` для домена `lovelace` в 2025.1.4 не имеет
`extra=vol.ALLOW_EXTRA` (в отличие от внешней обёртки `CONFIG_SCHEMA`) —
значит непредусмотренный ключ верхнего уровня внутри `lovelace:` обычно
**валится валидацией конфигурации HA**, а не тихо игнорируется. Если
`resource_mode` не появится в реальном будущем релизе именно так, как описано,
рекомендованный «современный» sniplet из §12 может не просто не сработать
(старая проблема #462), а **сломать загрузку `lovelace:` целиком** — то есть
задача рискует внедрить дефект хуже исходного, ровно в том месте, которое
должно чинить документацию.
- Утверждение не помечено в §22 («Принятые технические предположения — можно
менять на ревью») как гипотеза, хотя структурно — это ровно тот раздел, где
ему место, если бы оно было гипотезой, а не фактом.
- Утверждение приводит к automated docs-contract тесту (AC1, §16) и
формулировке AC1 «мутант: … современный `mode: yaml` вместо `resource_mode:
yaml` … делает docs contract красным» — то есть контракт будет насильно
удерживать в README/User Guide формулировку, которую нечем подтвердить, и
снимать её будет уже не ревью, а очередной пользовательский репорт, как #462.
**Возврат автору.** Нужно либо (а) привести проверяемый источник для
`lovelace.resource_mode` (номер release note/PR HA, который это ввёл — тогда
формулировка остаётся, но с явной ссылкой), либо (б) убрать разделение на
современный/legacy YAML-режим и вернуться к единственному подтверждённому
контракту: `lovelace.mode: yaml` меняет и dashboard, и разрешает
`resources:`, а storage-режим требует UI Resources — то есть к тому описанию,
которое уже было верно на r1 и не вызывало вопросов. Пока источник не назван —
AC1, §5, §12 и соответствующий пункт §16 остаются недоказанным техническим
угадыванием, оформленным как решённый факт. High, блокирует.
### Low-1 (наследуется, закрыта) — числовой touch-target 44×44
Была Low в r1 без источника в каноне. §22 п.8 теперь явно помечает число как
«локальный accessibility-порог», а не заимствование канона. Формулировка
r1 предлагала ровно это — принимаю как закрытую, отдельного действия не
требуется.
### Low-2 — SHA не назван в вердикт-комментарии r1
Комментарий-вердикт r1 в issue (`Вердикт: жёлтый · заход r1 …`) не называет SHA
материала, на котором получен вердикт — притом что сам документ
`SPEC-REVIEW-462-r1.md` SHA называет дважды (в шапке и в «Материале раунда»).
Практических последствий не имело: SHA восстановлен однозначно по порядку
коммитов. Не блокирует, но стоит отметить в шаблоне хендофф-комментария на
будущее — вердикт-комментарий в issue должен либо называть SHA сам, либо явно
отсылать к документу как единственному источнику SHA.
## Закрытие раунда r1
| Находка r1 | Чем закрыта | Где видно |
|---|---|---|
| Medium: новый version-controller баннер и terminal-тост #353 просят reload независимо и могут показаться одновременно с разными формулировками | Явное правило: terminal-тост #353 подавляется только пока видна version-mismatch плашка; network/non-terminal тост и terminal-тост без плашки не подавляются; одновременно два сообщения с одной просьбой не показываются | `docs/specs/462-card-resource-registration.md:312-318` (§11.2), AC12 (`:526-528`), план тестов §16 «Browser smoke/golden» (`:560-562`), риск §19 п.11 (`:629-631`) |
| Low: touch-target 44×44 без источника в каноне | Помечено как локальное (не канонное) accessibility-решение | §22 п.8 (`:681-683`) |
Обе находки r1 закрыты по существу, без новых открытых вопросов по ним самим.
Однако правка Medium-находки (коммит `8973431f`) в том же дыхании внесла
новую, более серьёзную находку — см. «Находки», High — что и есть причина,
по которой предупреждение §2.9/#102 в этой задаче не абстрактно: починка одного
AC создала риск в другом месте того же коммита.
## Унаследовано из r1 (без повторной проверки в этом раунде)
Следующее не тронуто дельтой `12ddd107..e9e3d6bd` за пределами описанного выше
и принимается по документу `docs/reviews/SPEC-REVIEW-462-r1.md`
(SHA материала `12ddd107a9cdd9b12ea8411360760f684f5293c1`):
- Наличие и содержание обязательных разделов §7.1 PROCESS.md (сценарий, что
человек увидит, причина, скоуп/не-скоуп, контракт §8–11, данные/миграция,
i18n, AC1…AC13, план тестов, риски, откат, release-артефакты, §22).
- Существование и смысл символов кода, проверенных в r1:
`_register_lovelace_resource`/`_lovelace_resources`
(`custom_components/houseplan/__init__.py:336-378`), `manifest.json`
(dependencies без `lovelace`), `system_health_info`, `CARD_VERSION`
(`src/houseplan-card.ts:402`), `integration_version` в `config/get`,
`_preflightVersionsDiffer` (`houseplan-editor-runtime.ts:9610`),
`_cyclePausedUntil`/`_zoom`/`_editing`/`_pendingPhysicalWrites`/
`_writesPending`/`_vacFit`.
- Подтверждённая по реальным wheel `homeassistant==2024.6.0` и `==2025.1.4`
цепочка зависимостей `houseplan → frontend → lovelace` (§3) и отсутствие
`remove_extra_js_url` в 2024.6 (обосновывает `lovelace_resource_with_
session_fallback`, §8.2 абзац после п.9). Эти два факта дельта не
затрагивала и я их не переоткрывал.
- Пригодность `homeassistant.helpers.start.async_at_started` как
`CALLBACK_TYPE`, совместимого с `entry.async_on_unload` (§22 п.3, базовая
часть механизма; новым в этом раунде является только добавка secondary
cancellable delay поверх него — это я перепроверил заново, см. «Как
проверялось», п.2 относится к другому вопросу, а сам `async_at_started`
переподтверждать не стал).
- Полный список из 4 файлов документации с невалидным плоским `resources:`
(README.md:101, README.ru.md:105, docs/USER-GUIDE.md:94,
docs/USER-GUIDE.ru.md:93) — дельта не меняла состав списка, только
требуемое содержание правки.
- Обоснование выбора `persistent_notification` вместо Repairs (§22 п.1) через
прецедент `custom_components/houseplan/repairs.py`.
- Соответствие SCOPE.md: задача закрывает J4, out-of-scope не задет.
- AC2, AC5, AC6, AC7, AC8, AC9, AC10, AC11 — формулировки не менялись в дельте
(проверено `git diff` по разделам, см. «Материал раунда r1»); принимаю их
однозначность и доказуемость как установленную в r1.
## Что проверено и корректно (в этом раунде)
- Раздел «Закрытие раунда r1» — обе находки закрыты по существу, без
формальных отписок.
- §9 (флаг notification после синхронного `async_create`) — техническая
точность подтверждена по исходнику HA 2025.1.4.
- §11.2 card-level overlay в ранних `fixed-floor`/пустых состояниях —
требование обосновано реальной структурой `render()` в
`src/houseplan-card.ts` (три отдельных ``-ветки), не выдумка.
- §11.3 новые guard-пункты (нативный HA more-info не участвует по
ненадёжному полю; pending layout debounce/грязные позиции устройств
блокируют auto-reload) описаны как требования к реализации без ссылки на
несуществующие внутренние символы — не нарушают правило «не выдавать догадку
за решение», это раздел, где §17 явно оставляет точные имена за
реализацией.
- §22 п.8 (touch-target) и §11.2/AC12/§16/§19 (закрытие toast/banner
конфликта) корректно закрывают находки r1 — см. таблицу выше.
- Нумерация и внутренняя согласованность AC1–AC13 не нарушены дельтой: каждый
из четырёх изменённых AC (AC1, AC3, AC12, AC13) по-прежнему однозначен и
называет способ доказательства; проблема не в форме, а в фактической
достоверности содержания AC1.
## Чего не проверял
- Не проверял HA-версии новее `2025.1.4` напрямую — недоступны в индексе pip
этого окружения (то же ограничение, что и в r1). Это ровно тот пробел,
из-за которого High-находка выше сформулирована как «не подтверждено», а не
как «стопроцентно неверно»: теоретически upstream мог ввести такой ключ
именно так, как описано, в версии между `2025.1.4` и «2026.2+», но ни одного
подтверждения этому нет ни в коде, ни в вебе (недоступен), ни в остальной
части репозитория.
- `WebSearch`/`WebFetch` недоступны в сессии (permission denied на оба вызова)
— не смог свериться с release notes/документацией HA напрямую; вся
верификация High-находки — по исходному коду ближайшей доступной версии и
внутренней логике самого ТЗ.
- Не прогонял `typecheck`/`test`/`build` — этап spec, кода нет; гейты
применимы к код-ревью (§2.7), не к этому этапу.
- Не проверял AC2, AC5–AC11 заново по существу — формулировки не изменились
дельтой, приняты из r1 (см. «Унаследовано из r1»).
- Не оценивал разделы §13/§14/§17/§18/§20/§21 заново — дельта их не касалась
(кроме упомянутых точечных правок в §21 про «три golden» и «десять кадров»,
которые являются числовым уточнением существующего пункта r1, а не новым
контрактом, и не меняют вывод r1 по этим разделам).
## Материал раунда
- Ветка: `issue/462-card-resource-registration`
- SHA материала: `e9e3d6bd7d8e61a0e7d561da76b19cedb157f32b`
- Дерево: `7bea3d2ffb5216214a550abe845e67d7b4680797`
- ТЗ `docs/specs/462-card-resource-registration.md`, блоб
`c507644bf4fb0f5e902ddc4628497e329afeba3c`
- SHA r1 (для дельты): `12ddd107a9cdd9b12ea8411360760f684f5293c1`
---
## Материал раунда
- Ветка: `issue/462-card-resource-registration`, коммит `e9e3d6bd7d8e` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `7bea3d2ffb5216214a550abe845e67d7b4680797`
```
git log --all --format='%H %T' | grep 7bea3d2ffb52
```
- ТЗ `docs/specs/462-card-resource-registration.md`, блоб `c507644bf4fb0f5e902ddc4628497e329afeba3c`
```
git log --all --find-object=c507644bf4fb0f5e902ddc4628497e329afeba3c -- docs/specs/462-card-resource-registration.md
```