From ea2ec19b71c6b0b8339b8fb7c518e431580dcaad Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Sat, 5 Sep 2026 11:22:55 +0000 Subject: [PATCH] docs: review document for #462 Issue: #462 User-Visible: no --- docs/reviews/SPEC-REVIEW-462-r2.md | 289 +++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-462-r2.md diff --git a/docs/reviews/SPEC-REVIEW-462-r2.md b/docs/reviews/SPEC-REVIEW-462-r2.md new file mode 100644 index 00000000..81b68185 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-462-r2.md @@ -0,0 +1,289 @@ +# 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 + ```