From 7e4751ba624140dee9563e4d11ace795aabfa524 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 12:26:46 +0000 Subject: [PATCH] docs: review document for #485 Issue: #485 User-Visible: no --- docs/reviews/SPEC-REVIEW-485-r4.md | 260 +++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-485-r4.md diff --git a/docs/reviews/SPEC-REVIEW-485-r4.md b/docs/reviews/SPEC-REVIEW-485-r4.md new file mode 100644 index 00000000..7683f034 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-485-r4.md @@ -0,0 +1,260 @@ +# SPEC-REVIEW-485-r4 + +Issue: [#485](https://github.com/Matysh/houseplan-card/issues/485). +Материал: ветка `issue/485-radar-presence`, SHA `2f2e3fcaca98055b93e647fe8e11df0f1567f643` +(baseline r3 материал `21950437b4343deead48c955d06191ea15bb567a`, докс-only diff, +проверено `git diff --stat` — только `docs/specs/485-radar-presence-stage1.md` и +`docs/specs/485-radar-presence.md`; коммит `docs/reviews/SPEC-REVIEW-485-r3.md` (`749970bb`) +в дельту не входит, по прецеденту r2/r3). +Этап: **spec** (S4-spec-review). Заход: r4. Блокирующих циклов израсходовано 2 из 4 +(r1 жёлтый — цикл 1/4; r2 зелёный — цикла не образовал, #227; r3 жёлтый — цикл 2/4). +Трек: полный (`gh issue view 485` — метки `P2, feature, S4-spec-review`, `small` +отсутствует). Ревьюер ≠ автор. + +## Скоуп разбора (по дельте, PROCESS §2.9/§2.10, issue #214) + +Единственная блокирующая находка r3 — **M-1**: новый гейт видимости раздела +(«структурные метаданные адаптера/реестра») тихо исключал ранее принятый адаптер +«любой числовой сенсор» (класс `range_v1`), не оставляя описанного ручного пути его +настроить. Найдено два варианта исправления: (1) явный ручной путь-эскейп для +неопознанного устройства, либо (2) явное сужение AC/таблицы профилей с отдельным +вопросом владельцу. Между r3 и r4 владелец подтвердил **Q5-default** +(issuecomment-5585013213, 2026-09-08T12:18:52Z): вариант (1) — вторичное действие +«Это радар присутствия» в дополнительных действиях редактора устройства. + +`git diff 21950437..2f2e3fca --stat` (исключая коммит документа r3): + +``` +docs/specs/485-radar-presence-stage1.md | 101 +++++++++++++++++++++++++------- +docs/specs/485-radar-presence.md | 19 ++++-- +``` + +Дельта локальна по объёму и по содержанию: это реализация уже принятого владельцем +Q5-решения, которое r3 уже разобрал как «новый поведенческий контракт» и проверил +широко (точки входа этапов 2/3, `docs/SCOPE.md`, прецедент условного раздела +пылесоса, `docs/UX-MODES.md`). r4 не открывает новую подсистему и не меняет контракт +повторно — он проверяет, что текст фикса **точно** реализует уже одобренный Q5, +не ослабляет ACL/безопасность и не вносит новой недекларированной догадки. Поэтому +разбор в этом раунде ограничен: (а) построчная сверка обеих правок с формулировкой +Q5-default и с «как чинится» M-1 из r3, (б) чтение всего файла на предмет +рассинхронизации формулировок (старый текст, оставшийся противоречить новому), +(в) проверка последствий для ACL/WS-контракта (единственное реально новое +техническое расширение — доступ к draft-источникам без общего HA-устройства). +Остальное (продуктовая рамка, границы этапов, модель идентичности, AC-таблицы +C/S2/S3 и S1 кроме S1-19/20, совместимость, touch-декларации, i18n кроме двух +новых ключей, перф-бюджеты) дельтой не задето — см. «Унаследовано из r3». + +## Как проверялось + +- `gh issue view 485 --json labels,state` — `OPEN`, `P2, feature, S4-spec-review`, + `small` отсутствует: трек не изменился. +- `gh api repos/Matysh/houseplan-card/issues/485/comments` — прочитан весь текущий + список комментариев issue от последнего разобранного (после r3) до конца; + подтверждено, что после хендоффа автора (`IC_kwDOTOcLQM8AAAABTOT_XA`, + 2026-09-08T12:21:18Z) новых комментариев нет — это материал раунда. +- Найден и прочитан дословно комментарий владельца Q5-default + (`gh api .../comments -q 'select(.id==5585013213)'`) — сверен построчно с текстом + `Q5 default` в `485-radar-presence.md:54` и с разделом «Manual entry (Q5)» в + `stage1.md:93-118`: формулировка «вторичное действие в дополнительных действиях», + «основной раздел скрыт до выбора», «отмена ничего не сохраняет», «общий + переключатель не меняется», «путь исправления сохранённой настройки остаётся» — + совпадают дословно по смыслу, расширений сверх решения владельца не найдено. +- Построчный `git diff 21950437..2f2e3fca` по обоим файлам (полный текст правки). +- `grep -n -i "manual" docs/specs/485-radar-presence-stage1.md` и по общему + контракту — проверено отсутствие рассинхронизации: ни один старый фрагмент + («completely unidentifiable hardware… cannot be automatically distinguished», + «unresolved metadata is not positive evidence», исполнение AC S1-19) не + противоречит новому тексту после правки; все ссылки на «ручной путь» согласованно + указывают на один и тот же механизм Q5. +- Проверено, что `docs/specs/485-radar-presence-stage2.md:75` и + `-stage3.md:86` (точки входа «Device editor → Presence on plan → …», не тронуты + дельтой) остаются валидны: обе продолжают описывать вход из уже + определённого/настроенного радара — ручное объявление лишь добавляет способ, + которым радар становится «настроенным» (`marker.radar` сохранён), не открывает + новый вход в этапы 2–3 в обход существующей модели. +- Проверено расширение WS/ACL-раздела (`stage1.md:495-501`, «Draft sources use the + same strict schema/size caps…»): новый текст явно требует, чтобы (а) существующий + маркер принадлежал запрошенному пространству и был `may_write`, (б) каждый явно + выбранный источник был независимо читаем текущим пользователем, (в) само ручное + объявление/фронтенд-eligibility не были авторизацией — сервер валидирует граф + источников самостоятельно. Это закрывает очевидный риск новой фичи (клиент + заявляет «это радар» и получает доступ к чужим данным): проверка per-source ACL + и `may_write` остаётся обязательной независимо от объявления. +- Проверено i18n: два новых ключа (`additional_actions`, `declare_radar`) добавлены + с обеими колонками en/ru в единственной таблице §8 stage1; остальные ключи не + тронуты дельтой. +- Проверено, что «где именно живёт эта кнопка» (свёрнутая группа «Additional + actions», отсутствие отдельного персистентного флага классификации) явно помечено + как реализационный выбор в блоке допущений в конце `stage1.md` («For Q5, session- + local declaration state and the collapsed additional-actions group are + implementation choices…») — не догадка, выданная за факт. +- Перечитан весь диапазон AC S1-19/S1-20 на предмет доказательства и негативного + свидетеля по каждому пункту (`git diff` выше) — оба присутствуют дословно + («remove eligibility guard => …», «Require auto identity => generic-setup witness + fails», «persist declaration early => cancel-config comparison fails», «bypass + ACL or adapter proof => restricted-source/service canary fails»). +- Проверено, что решение M-1 из r3 не расширяет и не сужает исключения + `docs/SCOPE.md` (запись/тепловая карта/производные сущности) — дельта не трогает + `docs/SCOPE.md`, вопрос ограничен точкой входа в уже существующий редактор + устройства, не новым классом данных/хранения. + +### Гейты + +Диапазон затрагивает только `docs/specs/*.md` (class C); продуктовый код и тесты не +тронуты (`git diff --stat 21950437..2f2e3fca -- src custom_components` — пусто). +Validate зелёный на точном материале раунда (`2f2e3fca`, +https://github.com/Matysh/houseplan-card/actions/runs/34225567412, `success`, +запущен 2026-09-08T12:20:55Z) — дешёвые гейты (`typecheck`, `test`, `build` со +сверкой копий бандла) на этом SHA подтверждены и повторно не гонялись. + +Прогнано самостоятельно, дёшево, напрямую по этому SHA (диапазон докс-only, эти +гейты применимы и не покрыты Validate по существу для этой дельты): + +| Гейт | Команда | Результат | +|---|---|---| +| Markdown/diff-гигиена | `git diff --check 21950437..2f2e3fca -- docs/specs/485-radar-presence-stage1.md docs/specs/485-radar-presence.md` | чисто (exit 0) | +| Документационные проверки | `node scripts/check-docs.mjs` | `Documentation checks passed (7 files, 12 external links)` | + +`tsc`/`test`/`build`/`invariants`/смоки/`golden`/`pytest`/перфопрофили — не +запускал: diff не касается `src/**`/`custom_components/**/*.py`, ни один AC этой +стадии не требует их прогона для spec-review, и Validate на этом же SHA уже +подтвердил дешёвые гейты репозитория в целом. + +## Закрытие раунда r3 + +| Находка r3 | Чем закрыта | Где это видно | +|---|---|---| +| **M-1** — новый структурный гейт видимости исключал ранее принятый адаптер «любой числовой сенсор» (`range_v1`) без ручного пути настройки; продуктовая граница решена предположением автора, а не владельцем | Владелец подтвердил Q5-default: вторичное действие **«Это радар присутствия»** в свёрнутой группе «Additional actions» редактора устройства для любого нераспознанного реального устройства/сущности (включая standalone `sensor` без `device_id`); действие открывает тот же мастер с ручным выбором из `range_v1`/`cartesian_v1`/`polar_v1`/`zones_v1`/`presence_v1`, без авто-подстановки и без доп. диалога подтверждения. Основной раздел остаётся скрытым до явного выбора; Cancel/выход/скрытие страницы/смена привязки ничего не сохраняет и не переносит согласие на другое устройство. Сохраняется только валидированный целиком `marker.radar` по успешному атомарному Save. Добавлена новая AC S1-20 с доказательством и негативными свидетелями; WS/ACL-раздел явно уточнён: объявление не есть авторизация, per-source ACL и `may_write` проверяются сервером независимо. Добавлены i18n-ключи `additional_actions`/`declare_radar` (en+ru). | `docs/specs/485-radar-presence.md:54` (Q5 default в таблице), `:67-79` (§3 UX-абзац с новым действием); `docs/specs/485-radar-presence-stage1.md:48-51` (гейт видимости с явной оговоркой про Q5), `:71-79` (новый маркированный пункт «explicit… This is a presence radar action»), `:93-118` (раздел «Manual entry (Q5)» целиком), `:495-501` (уточнённый WS/ACL-абзац), `:524-525` (i18n), `:611-612` (AC S1-19 обновлена, AC S1-20 добавлена) | + +Находка закрыта предметно: правка лежит ровно там, где r3 указала место +(«ручной путь-эскейп»), реализует ровно тот вариант, который r3 предложила первым +(«Добавить в §2 явный ручной путь… ведущий в тот же мастер… отдельное от двух +автоматических путей»), и количественно совпадает с формулировкой владельца — не +шире и не уже. + +## Унаследовано из r3 + +Принято без повторной проверки в этом раунде, так как дельта их не задевает; +основание — [SPEC-REVIEW-485-r3](https://github.com/Matysh/houseplan-card/blob/21950437b4343deead48c955d06191ea15bb567a/docs/reviews/SPEC-REVIEW-485-r3.md) +на SHA `21950437b4343deead48c955d06191ea15bb567a` (и через неё — r2 на `f4bab4a4`, +r1 на `6550a69e`): + +- Продуктовая рамка, границы этапов 1→2→3 и их отнесение к J1/`docs/SCOPE.md`. +- `docs/SCOPE.md`-исключения для производных HA-сущностей и записи/тепловой карты + (закрытые в r1→r2) — эта дельта их не расширяет и не сужает. +- Touch-декларация мастера калибровки этапа 1 (`best effort / intentionally + degraded`) и этапов 2/3 — не тронута. +- Единая модель идентичности (`source_generation`, `calibration_revision`, + `server_session_id`/`seq`), лимиты, WS-контракт §7 stage1 (кроме уточнённого + ACL-абзаца, разобранного в этом раунде). +- Полнота AC-таблиц C-1…C-8, S2-1…S2-22, S3-1…S3-18 и S1-1…S1-18 (кроме + обновлённой S1-19 и новой S1-20, разобранных в этом раунде). +- Правило скрытия раздела для обычных устройств (лампы/выключатели/температура/ + обычный PIR/виртуальный маркер) и сохранение пути ремонта уже настроенного + радара. +- Точки входа этапов 2 и 3 (`stage2.md:75`, `stage3.md:86`) — повторно сверены в + этом раунде на предмет совместимости с новым ручным путём (см. «Как + проверялось»), новых противоречий не найдено. +- Матрицы совместимости/жизненного цикла, i18n-таблица §8 stage1 (кроме двух новых + ключей), перф-бюджеты §10 stage1. +- Ответы Q1–Q4 и их количественное соответствие тексту. + +## Находки + +Нет. Единственная блокирующая находка r3 (M-1) закрыта предметно и в точности по +предложенному варианту; дельта не вносит новых недекларированных догадок, не +ослабляет ACL/безопасность и не противоречит унаследованным AC. + +## Что проверено и корректно + +- Q5-default количественно и дословно совпадает между комментарием владельца, + общим контрактом (§3, таблица Q-defaults) и этапом 1 (§2, раздел «Manual entry + (Q5)») — три места не разошлись. +- Новый ручной путь явно не создаёт авторизации: WS/ACL-абзац требует независимой + проверки чтения каждого источника и `may_write` маркера сервером, объявление + «это радар» само по себе прав не даёт — закрывает очевидный риск privilege + escalation через самообъявление. +- Реализационные детали (расположение кнопки, отсутствие отдельного персистентного + флага) явно помечены как «assumed, change freely», а не выданы за факт. +- AC S1-20 имеет колонку доказательства и минимум три названных негативных + свидетеля (авто-идентичность обязательна → падает; ранняя персистентность → + падает; обход ACL/аппаратного адаптера → падает). +- i18n добавлен в обеих колонках (en/ru) в единственной таблице, второй копии не + создано (правило «один источник» не нарушено — новых пользовательских чисел + дельта не вводит вовсе). +- Точки входа этапов 2 и 3 остаются валидны при новом способе получения + «настроенного радара» — они читают уже сохранённый `marker.radar`, а не способ, + которым он появился. +- `docs/SCOPE.md` не требует правки для этой дельты — вопрос ограничен точкой входа + в существующий редактор устройства. +- Трейлеры коммита `2f2e3fca`: `Issue: #485`, `User-Visible: no` — верно для + докс-only изменения без видимого пользователю поведения (фича ещё не + реализована). + +## Чего не проверял + +- Не перепроверял полностью AC-таблицы C-1…C-8, S2-1…S2-22, S3-18, модель + идентичности, совместимость, перф-бюджеты, touch-декларации, продуктовую рамку — + дельта их не задевает; раздел «Унаследовано из r3» перечисляет, что принято без + повторной проверки. +- Не запускал `npx tsc --noEmit`, `npm test`, `npm run build`, `npm run + invariants`, браузерные смоки, `golden:verify`, `python -m pytest + tests_backend`, перфопрофили — diff докс-only, не касается + `src/**`/`custom_components/**/*.py`; ни один AC пакета не требует их прогона на + стадии spec-review; Validate на этом же SHA (`2f2e3fca`) подтверждает дешёвые + гейты репозитория в целом. +- Не проверял `docs/USER-GUIDE.ru.md`/`docs/USER-GUIDE.md` построчно — фича не + выпущена, руководство ещё не содержит раздела о радарах (не с чем сверять). +- Не оценивал реализуемость новых числовых/технических деталей WS-абзаца — они не + являются числовыми константами и не помечены как открытый вопрос; явных + внутренних противоречий не найдено при построчной сверке. + +## Вердикт + +**Зелёный.** High — 0, Medium — 0. Единственная находка r3 (M-1) закрыта предметно +и без расширения/сужения скоупа сверх решения владельца. Комплект (общий контракт ++ три этапа) готов к переходу S4 → S5 — с оговоркой владельца, повторённой в +хендоффе автора: **остановиться в S5-ready, реализацию не начинать**. + +Этот зелёный вердикт цикла не образует и бюджет §4 не тратит (#227): было +израсходовано 2 из 4, после этого раунда — по-прежнему 2 из 4. + +--- + + + +## Материал раунда + +- Ветка: `issue/485-radar-presence`, коммит `2f2e3fcaca98055b93e647fe8e11df0f1567f643`. +- ТЗ `docs/specs/485-radar-presence-stage1.md` на этом коммите. +- ТЗ `docs/specs/485-radar-presence.md` на этом коммите. +- ТЗ `docs/specs/485-radar-presence-stage2.md`, `docs/specs/485-radar-presence-stage3.md` — не изменены с r2 (блобы см. SPEC-REVIEW-485-r2.md/r3.md). +- Validate: https://github.com/Matysh/houseplan-card/actions/runs/34225567412 (`success`, headSha `2f2e3fca`). + +--- + + + +## Материал раунда + +- Ветка: `issue/485-radar-presence`, коммит `2f2e3fcaca98` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `a72dbb18c130b5f648a5e07570646e9fc2cdaf45` + ``` + git log --all --format='%H %T' | grep a72dbb18c130 + ``` +- ТЗ `docs/specs/485-radar-presence-stage1.md`, блоб `c47c46bec46eda4be832809273fbe30de48cd9a8` + ``` + git log --all --find-object=c47c46bec46eda4be832809273fbe30de48cd9a8 -- docs/specs/485-radar-presence-stage1.md + ``` +- ТЗ `docs/specs/485-radar-presence-stage2.md`, блоб `b403e73fc26ba0ffb97be4ffa73be067d179880f` + ``` + git log --all --find-object=b403e73fc26ba0ffb97be4ffa73be067d179880f -- docs/specs/485-radar-presence-stage2.md + ``` +- ТЗ `docs/specs/485-radar-presence-stage3.md`, блоб `c65e28389d762216c47f00249bdb751f3c9d5082` + ``` + git log --all --find-object=c65e28389d762216c47f00249bdb751f3c9d5082 -- docs/specs/485-radar-presence-stage3.md + ``` +- ТЗ `docs/specs/485-radar-presence.md`, блоб `3297ed0140265ad86f2072a40cb9bf8097c0674d` + ``` + git log --all --find-object=3297ed0140265ad86f2072a40cb9bf8097c0674d -- docs/specs/485-radar-presence.md + ```