From 9baf533c90acb15a0f86a639224666a4ec3b9626 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Tue, 18 Aug 2026 19:02:43 +0000 Subject: [PATCH] docs: review document for #117 Issue: #117 User-Visible: no --- docs/reviews/SPEC-REVIEW-117-r1.md | 264 +++++++++++++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-117-r1.md diff --git a/docs/reviews/SPEC-REVIEW-117-r1.md b/docs/reviews/SPEC-REVIEW-117-r1.md new file mode 100644 index 00000000..56e535a5 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-117-r1.md @@ -0,0 +1,264 @@ +# SPEC-REVIEW-117-r1 + +- **Issue:** https://github.com/Matysh/houseplan-card/issues/117 +- **ТЗ под ревью:** `docs/specs/117-registryless-opening-entity.md` (коммит `cc2298816b8ca4e41a41830fef69fd2ee1cb7ed9`) +- **Роль:** ревьюер ТЗ (не автор), этап `S4-spec-review` +- **Трек:** обычный (не `small`) — аналитика оценила сложность 4/10, риск 5/10 + (> 3), поверхности: opening entity picker/resolver, View state/action, + unit/smoke/docs — больше одной поверхности; лёгкий трек корректно не применён +- **Цикл:** r1/4 + +## Скоуп ревью + +Проверялось соответствие ТЗ: +- `docs/SCOPE.md` — попадание в Core user jobs, отсутствие расширения скоупа; +- `PROCESS.md` §2.4, §2.5 (DoR), §7.1 (обязательные разделы), §3.18 и §12 + (запреты, включая «Medium как TODO в тексте ревью»); +- `AGENTS.md` — классы файлов, ветка, трейлеры; +- `docs/USER-GUIDE.ru.md` — терминология «Контактный датчик» / «Замок» / + «проём»; +- issue #104 — откуда #117 выделен решением владельца, и не пересекается ли + ТЗ с уже закрытым скоупом #104 (marker tombstone); +- фактическому состоянию кода (`src/ha-binding-status.ts`, `src/houseplan-card.ts`) + — на предмет того, что технические утверждения ТЗ не являются непроверенной + догадкой, а не описанием несуществующего поведения. + +## Как проверялось + +1. Прочитано тело issue #117 (автор — владелец, `Matysh`, 2026-08-13) и оба + комментария: аналитика (2026-08-14, P2/bug/обычный трек, продуктовых + вопросов нет) и заведение ТЗ (2026-08-15, ссылка на файл и коммит). +2. Прочитан весь текст `docs/specs/117-registryless-opening-entity.md` + (223 строки) построчно. +3. Прочитан `src/ha-binding-status.ts:308-545`: подтверждено, что + `activeRegistryHass()` уже сознательно сохраняет live state registry-less + сущности (комментарий в коде на строках 342-346 прямо это объясняет), а + `renderOpeningEntityAvailable()` (строка 538) требует одновременно + `.entities[entityId]` **и** `.states[entityId]` — то есть расхождение, + которое ТЗ называет причиной бага, реально существует в коде, а не + придумано. Более того, комментарий к функции на строке 536 уже сегодня + говорит: «Registry-less render parity is #117» — само ТЗ не изобретает + этот план, а закрывает уже отмеченный в коде долг. +4. Прочитан `src/houseplan-card.ts:16256-16380`: подтверждено, что и + `_openingAmt()`, и `_renderOpeningLocks()` идут через единственную точку + `_renderOpeningEntityAvailable()` → `renderOpeningEntityAvailable(this._renderPlanHass, eid)` + — то есть один фикс на уровне `ha-binding-status.ts` действительно + закрывает contact и lock одновременно, как заявляет ТЗ, без риска + рассинхронизации двух копий логики. +5. Прочитано `_captureRenderDeviceSnapshot()` (`src/houseplan-card.ts:3559-3673`): + подтверждено, что `opening.contact`/`opening.lock` уже входят в `entityIds` + при захвате snapshot (строки 3595-3596) и что `planHass` в этом снимке — + результат `activeRegistryHass()` (строка 3553/3574) — то есть registry-less + state уже присутствует в замороженном кадре сегодня; баг только в лишней + проверке `.entities[entityId]` при чтении, как и утверждает §2 ТЗ. +6. Прочитан `src/houseplan-card.ts:16269-16284` (`_renderEntityAvailable` vs + `_renderOpeningEntityAvailable`): подтверждено, что общий + `_renderEntityAvailable()` (используется для прочих marker-биндингов) не + входит в фикс — ТЗ §4 прямо исключает «generic поддержку registry-less + entities во всех marker bindings», и это согласуется с кодом: два разных + потребителя, значит сужение скоупа не оставляет незамеченного разрыва. +7. Прочитан `docs/USER-GUIDE.ru.md:409-444` («Настройки проёма», «Замок») — + терминология ТЗ («контакт», «замок», «info card», «unlock confirmation») + совпадает с пользовательским словарём; текущая формулировка «Контактный + датчик и замок — самостоятельные точные привязки проёма» уже описывает + независимость от marker (#104), но ничего не говорит о registry — + подтверждает, что баг сегодня не задокументирован пользователю и правка + §14 (уточнить в user-guide поддержку YAML-сущности без `unique_id`) + осмысленна. +8. Сверено, что упомянутые в плане тестирования файлы существуют: + `test/ha-binding-status.test.mjs`, `test/render-device-snapshot.test.mjs`, + `demo/smoke_opening_binding.mjs`, `demo/smoke_lock_action.mjs`, + `demo/smoke_lock_invariant.mjs` — план тестирования не ссылается на + несуществующее покрытие. +9. Прочитано тело issue #104: подтверждено, что #104 занимался независимостью + opening-биндинга от marker tombstone (не от registry-строки) — #117 не + пересекается с уже закрытым скоупом #104, а закрывает отдельно вынесенную + часть, как и написано в issue. +10. Проверена запись `docs/specs/README.md:85` — добавлена тем же коммитом, + ссылка issue ↔ ТЗ двусторонняя. +11. Автор issue — владелец (`Matysh`), легитимность входа в процесс вопросов + не вызывает. + +## Обязательные разделы (§7.1 PROCESS.md) + +| Раздел | Есть | Комментарий | +|---|---|---| +| Сценарий (персона/поверхность/момент) | ❌ | нет отдельного раздела; персона и поверхность не названы явно нигде в документе | +| Что человек увидит до/после (без терминов реализации) | ❌ | ближе всего — последняя фраза §1 («сохранённый contact/lock не влияет на отрисованный проём»), но она внутри технического абзаца с `hass.states`/render path, а не отдельной продуктовой фразой | +| Проблема | ✅ | §1–2, с точной причиной по коду | +| Скоуп / не-скоуп | ✅ | §3 (Цели) / §4 (Не входит) | +| Контракт поведения | ✅ | §5, §8, §9 | +| UX | ~ | нет отдельного раздела, но §6 (матрица), §8, §9 покрывают поведение по существу | +| Модель данных и миграция | ✅ | §10 («config/storage/API не меняются») | +| i18n | ✅ | §14 («новых RU/EN строк нет») | +| AC1…ACn с доказательством | ~ | §11, 10 пунктов, но без инлайн-тега типа доказательства у каждого (см. Low-2) | +| План автотестов | ✅ | §12 | +| Риски | ✅ | §15 | +| Откат | ✅ | §15 | +| Release-артефакты | ✅ | §14 | + +Два обязательных продуктовых раздела (сценарий, что человек увидит) в виде +отдельных секций отсутствуют — см. Low-1. Технической неоднозначности это не +создаёт: контент восстановим из §1/§9 и подтверждён чтением кода (см. «Как +проверялось»), поэтому не поднимаю до High/Medium (см. обоснование в Low-1). + +## Находки + +Находок уровня **High** и **Medium** нет. + +### Low-1 — нет отдельных разделов «Сценарий» и «Что человек увидит» + +**Файл:** `docs/specs/117-registryless-opening-entity.md:9-17` (§1) + +PROCESS.md §7.1 требует эти два раздела первыми и объясняет почему: «ТЗ, +которое не может ответить на эти два вопроса, описывает работу, а не +изменение продукта». В этом ТЗ persona/surface/moment нигде не названы явно, +а «что увидит человек» растворено в техническом абзаце про `hass.states` и +render path. + +Восстановленный ответ (проверяемый по SCOPE.md и коду, не по догадке): +персона — **Home admin** привязывает live YAML-сущность без `unique_id` +(например, `binary_sensor` без `unique_id`) к контакту/замку проёма в Plan +editor, picker её принимает; после сохранения все три персоны, смотрящие на +**View** (включая kiosk-планшет), видят проём/замок, который не реагирует на +реальное изменение состояния сущности, хотя в HA оно меняется. После фикса — +тот же проём ведёт себя как с обычной зарегистрированной сущностью. + +**Решение ревьюера:** Low, не блокирует. Ни один AC не становится +двусмысленным из-за отсутствия этих разделов, и содержание однозначно +восстанавливается из §1/§9/кода — не тот случай, когда «домыслил ревьюер» +подменяет решение владельца, потому что сама сцена уже зафиксирована в issue +и SCOPE.md (View — продукт для двух персон), а не изобретена сейчас. Оставляю +на усмотрение автора: можно добавить двумя короткими фразами при следующей +правке файла, отдельного цикла ревью это не требует. + +### Low-2 — AC1–AC10 (§11) не несут инлайн-тег способа доказательства + +**Файл:** `docs/specs/117-registryless-opening-entity.md:145-158` + +DoR (`PROCESS.md` §2.5) требует: «AC1…ACn — ... у каждого указано, чем он +доказывается: `unit` / `backend` / `smoke` / `golden` / «ревью кода»». Ни один +из десяти пунктов §11 не несёт такой пометки; способ доказательства нужно +реконструировать из §12 «План тестирования» отдельно. + +Реконструкция (сверена с реальными файлами, см. «Как проверялось», п.8): + +| AC | Доказательство | +|---|---| +| AC1 (registry-less contact меняет presentation) | `smoke`: новый YAML-like `binary_sensor` сценарий (§12) | +| AC2 (registry-less lock badge) | `smoke`: новый YAML-like `lock` сценарий (§12) | +| AC3 (frame использует projection, не raw hass) | `unit`: mutation-guard «вернуть `.entities[entityId]` — YAML case красный» (§12) — единственный AC, где мутационный тест сам по себе и есть доказательство, а не просто регрессия | +| AC4 (registry entity — прежнее поведение) | `smoke`/`golden`: существующие opening-сценарии без изменений | +| AC5 (disabled/orphan/missing остаются unavailable) | `unit`: расширенная матрица в `ha-binding-status.test.mjs` | +| AC6 (limited-registry live entity работает) | `unit`: тот же файл, ветка `authoritative: false` | +| AC7 (marker tombstone не блокирует) | `smoke`: «same entity tombstoned as marker» (§12) | +| AC8 (lock security/confirmation не меняются) | не назван явно; фактически покрыт существующими `demo/smoke_lock_action.mjs` и `demo/smoke_lock_invariant.mjs` (регрессия, п.3 «Регрессия» §12) плюс «ревью кода» | +| AC9 (state update без geometry/config rebuild) | `smoke`: «render snapshot atomicity on state tick» (§12) | +| AC10 (существующие opening golden/interactions без регресса) | `golden`/`smoke`: регрессионный прогон существующих сценариев (§12, явно уточнено, что golden-эталоны не переакцептуются) | + +Каждый AC в итоге прослеживается к конкретному, реально существующему тесту +или к явно допустимому DoR методу «ревью кода» (AC8). Ни один пункт не +остаётся недоказуемым по существу — разрыв чисто в оформлении: тег не +проставлен инлайн, как это было сделано, например, в предыдущем ТЗ #123 (13/13 +AC с явным типом). + +**Решение ревьюера:** Low, не блокирует. Реконструкция выше снимает риск +«недоказанного AC» для этого цикла; рекомендую при следующей правке файла +добавить тег каждому AC (особенно явно объявить AC8 как «ревью кода + +`smoke_lock_action.mjs`/`smoke_lock_invariant.mjs`», а не оставлять +подразумеваемым). Отдельного issue не завожу: это дефект оформления текущего +ТЗ, а не самостоятельная будущая работа — заводить для него `S1-new` issue +было бы имитацией процесса, а не пользой. + +### Low-3 — матрица (§6) не содержит отдельной строки для registry-less entity в состоянии `unavailable/unknown` + +**Файл:** `docs/specs/117-registryless-opening-entity.md:79-95` + +Матрица явно разбирает «registry entity `unavailable/unknown`» (строка 85), но +не добавляет параллельную строку для «YAML/no registry row entity в +`unavailable/unknown`». Пояснение под таблицей («unavailable/unknown здесь +означает, что exact reference существует... #117 не подменяет эти states +active/open») по формулировке относится к обеим ветвям, и это подтверждено +чтением кода: `openingAmount()` (`src/logic.ts:316`) не различает +registry-статус сущности, работает только со строкой state — поэтому поведение +для YAML-сущности в `unavailable` идентично зарегистрированной. Риска для +корректности нет, только асимметрия изложения. + +**Решение ревьюера:** Low, снимаю с этой записью, правка не обязательна. + +## Что проверено и корректно + +- Соответствие `docs/SCOPE.md`: правка внутри уже закрытых J4 (онбординг/editor) + и J6 («Keep the plan true as the home evolves», два редактора, drag/resize, + editable icon rules) — это регрессионный/пограничный баг внутри принятой + функциональности opening-биндинга, а не новая фича и не расширение скоупа. +- Технический диагноз (§2) подтверждён построчным чтением `ha-binding-status.ts` + и `houseplan-card.ts` — не голословное утверждение автора; комментарий в коде + уже сегодня ссылается на #117 как на известный долг. +- Единая точка фикса (`renderOpeningEntityAvailable`) реально закрывает и + contact, и lock одновременно — проверено по вызывающему коду, а не + предположено. +- Матрица поведения (§6) корректно защищает все смежные случаи, которые могли + бы регрессировать: явный `disabled_by` у сущности и у устройства, + authoritative orphan, отсутствующий state, limited-registry режим — все эти + ветки уже реализованы в `activeRegistryHass()`/`resolveHaBindingStatus()` и + проверены построчно (см. «Как проверялось», п.3). +- Независимость от marker tombstone (AC7) корректно унаследована из #104: + `renderOpeningEntityAvailable` не обращается к `isRemovedPlanEntity()`, в + отличие от соседнего `_renderEntityAvailable()` — сужение скоупа (§4, + «generic поддержка... во всех marker bindings» — не входит) не оставляет + незамеченного разрыва, оба потребителя разделены в коде. +- Lock security и confirmation (§9) сформулированы дословно в терминах + существующего инварианта `docs/SCOPE.md` («The lock invariant, stated + precisely») — не ослабление и не новая семантика actuation. +- Раздел 16 «Принятые технические предположения» корректно отделяет свободно + изменяемые технические решения от продуктового контракта; ни одна догадка не + выдана за факт без пометки — я не нашёл ни одного утверждения о поведении, + которое не следует из кода, SCOPE.md или явно принятых допущений. +- Открытых продуктовых вопросов действительно нет: единственные развилки + (registry vs registry-less, authoritative vs limited access, disabled vs + orphaned) — все технические, не продуктовые, и решены автором согласно + правилу §7.1 «всё, чего пользователь не наблюдает, агенты решают сами». +- Терминология (USER-GUIDE.ru.md) не изобретена заново — «контакт», «замок», + «info card», «unlock confirmation» совпадают с действующим словарём. +- Совместимость (§10): config/storage/API не меняются, существующие + registry-backed openings объявлены pixel-identical, touch/kiosk жесты не + меняются, i18n ключей не добавляется — всё согласуется с + `docs/CONFIG-COMPATIBILITY.md` и `docs/TOUCH-SUPPORT.md` (нет заявленного + влияния, что и требуется). +- Реестр `docs/specs/README.md` обновлён тем же коммитом, ссылка issue ↔ ТЗ + двусторонняя; issue заведён владельцем — легитимность входа в процесс не + вызывает вопросов. +- Golden явно не требует переакцептации (существующие baseline не меняются) — + корректное сужение release-артефактов, не попытка обойти гейт. + +## Чего не проверял + +- Не запускал никаких автотестов или смоков — на этапе `spec` это не + требуется; существование файлов, упомянутых в плане тестирования, проверено + чтением (`test/ha-binding-status.test.mjs`, `test/render-device-snapshot.test.mjs`, + `demo/smoke_opening_binding.mjs`, `demo/smoke_lock_action.mjs`, + `demo/smoke_lock_invariant.mjs`), не исполнением. +- Не проверял реальное поведение реальной HA-инсталляции с YAML-сущностью без + `unique_id` — это будет предметом browser smoke на код-ревью (§12 плана + тестирования), не ревью ТЗ. +- Не проверял `src/logic.ts:openingAmount()` построчно на предмет всех + инвариантов инверсии/leaf-угла — доверяю формулировке §8 «state проходит + текущий `openingAmount(...)`; invert сохраняется» как описанию уже + существующего, не нового контракта; это не предмет этого фикса (§4: «не + входит в задачу» новые opening types или geometry). +- Не проверял historical переписку по ревью ТЗ #104 (сам документ ревью #104 + не найден отдельно) — доверяю формулировке issue #117 «решением владельца + registry-less render исключён из scope #104», подтверждённой владельцем в + комментарии аналитики (нет открытых вопросов/несогласия по этой границе). +- Не проверял производительность — ТЗ явно заявляет «нет» (§14), и правка не + трогает горячий путь по кадрам иначе, чем чтением одного дополнительного + boolean на существующей projection. + +## Вердикт + +Зелёный. High: 0, Medium: 0. Три находки Low (отсутствие двух обязательных +продуктовых разделов; отсутствие инлайн-тегов доказательства у AC1–AC10; +асимметрия одной строки матрицы) — ни одна не блокирует и не оставляет +AC недоказуемым по существу; все зафиксированы с реконструкцией и оставлены на +усмотрение автора при следующей правке файла, без нового цикла ревью.