docs: review document for #459

Issue: #459
User-Visible: no

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

@@ -0,0 +1,144 @@
+# SPEC-REVIEW-459-r1
+
+**Issue:** #459 «Настройка «Zigbee links»: подсказка о функции, её ограничениях и легенда цветов и пунктира»
+**Этап:** spec (лёгкий трек, `small`), PROCESS.md §2.4 / §5
+**Заход:** r1 · блокирующих циклов израсходовано 0 из 2 (лимит лёгкого трека)
+**Материал:** ТЗ в теле issue #459, редакция после комментария автора «ТЗ готово (лёгкий трек)» от 2026-09-05T07:16:30Z. Зависимость — issue #457 (`S6-in-progress`, ТЗ `docs/specs/457-zigbee-route-arrows.md` на ветке `issue/457-zigbee-route-arrows`, зелёное ревью r1). Репозиторий проверялся на `dev` `6af6d7b3` — код этой задачей ещё не тронут.
+
+## Скоуп ревью
+
+Лёгкий трек: ТЗ живёт в теле issue, отдельный файл в `docs/specs/` не создаётся — проверяю по шаблону §5 (проблема · контракт · AC1…ACn с доказательством · откат) и по общим требованиям §7.1 там, где они применимы (сценарий и «что человек увидит» — неявно, но выводимы из контракста §1). Задача полностью зависит от ещё не смержённого #457: проверил отдельно, что #457 достиг состояния, на которое можно ссылаться (спека принята, ревью зелёное r1), и что все технические утверждения #459 о поведении #457 (ключи, инвариант дерева, разделы §6–§9, §11) соответствуют реальному принятому тексту `docs/specs/457-zigbee-route-arrows.md`, а не являются пересказом по памяти.
+
+## Как проверялось
+
+Построчная сверка каждого фактического утверждения ТЗ с текущим кодом на `dev` и с принятым ТЗ #457:
+
+- `src/hp-zigbee-topology-settings.ts:159-171` — секция `.section`/`.toggle`/`.hint`, ключи `title`/`hint` через `_t()` → `topologyT`. Место установки кружка («у заголовка, не у тумточка») соответствует реальной структуре шаблона.
+- `src/hp-zigbee-topology-overlay.ts:185-189` — сплошная линия/`lqiColor`/пунктир `5 5` при `lqi === undefined`; номера строк в ТЗ (187-189) совпадают с фактическими.
+- `src/logic.ts:8-11` (`lqiColor`) — `hue = clamp(0,120, (lqi-40)/140*120)`; `lqiColor(40)` → hue 0 (красный край), `lqiColor(180)` → hue 120 (зелёный край). Формула и граничные числа в ТЗ точны.
+- `src/houseplan-editor-runtime.ts:1228-1233` (`_help()`) — реальный fail-closed паттерн: `nothing`, если `hasTranslation` не находит `key` или `${key}.aria`. Подтверждает, что описанное в ТЗ поведение «как у `_help()`» списано с кода, а не придумано.
+- `src/i18n/topology/{en,ru,de,fr}.json` — по 25 ключей в каждом, плоские имена через `_` (`zha_hint`, `z2m_topics`, …), без точечной нотации. Подтверждает выбор имён `help`/`help_aria` (не `help.aria`) как согласованный с namespace, а не произвольный.
+- `src/i18n/topology.ts` (`topologyT`) — `DICTIONARIES[lang]?.[key] ?? en[key] ?? key`. Важно для находки Low ниже.
+- `test/i18n.test.mjs` и `test/i18n-dead-keys.test.mjs` — оба реально проверяют только основной словарь + `support`; `topology` не участвует ни в одном. Утверждение ТЗ «namespace не покрыт ни одним из существующих гейтов» подтверждено чтением, не только словами автора.
+- `test/core-file-budget.test.mjs` — отслеживает только `houseplan-card.ts` и `houseplan-editor-runtime.ts`; `hp-zigbee-topology-settings.ts` в «Затронутых файлах» ТЗ не входит в отслеживаемые, и это не создаёт проблемы: правка не касается вызывающей стороны в `houseplan-editor-runtime.ts` (импорт и точка использования `<hp-zigbee-topology-settings>` не меняются, только внутренний рендер компонента), поэтому AC7 не сломан ссылкой на нерелевантный гейт — гейт просто останется зелёным, потому что диффа в отслеживаемых файлах нет.
+- `src/hp-help.ts:80-85` — `max-width: min(320px, calc(100vw - 16px))`, `max-height: calc(100vh - 16px)`, `overflow: auto`. Подтверждает аргумент ТЗ «всплывашка вмещает» текст 500–700 знаков без изменения CSS общего компонента.
+- `demo/smoke_zigbee_topology_hover.mjs:47,59` — обращается к `hp-zigbee-topology-settings` по тегу, не проверяет разметку самого заголовка секции; добавление кружка рядом с заголовком не должно задеть существующие проверки. AC8 правдоподобен.
+- Сверка #457: прочитан принятый `docs/specs/457-zigbee-route-arrows.md` целиком (§1–§20) и все 8 комментариев issue #457. Ключи `route_other_space`, `route_device_not_on_plan`, `route_coordinator_not_on_plan` (§11), формулировка «новый цвет или legend не вводятся» (§8), правила исходящей/входящей стрелки, bubble только для родительского направления (§7.1–7.4), приближённость дерева между роутерами (§6, §10 через комментарий с решениями владельца) — всё это в #459 процитировано точно, без искажений и без домысливания того, чего в #457 нет.
+
+Гейты не гонялись — код этой задачей не менялся, что и ожидается на этапе ТЗ.
+
+## Находки
+
+### Medium (в скоупе) — AC не покрывают главное новое содержимое подсказки
+
+Контракт §4 п.2 обязывает подсказку назвать (дословно из тела issue): исходящую
+стрелку («следующий шаг к координатору, одна исходящая у устройства и ни одной
+у координатора»), входящие стрелки («те, кто ходит через него»), линию без
+стрелки («запасной сосед»), подпись на конце стрелки («цель не на этом плане»)
+и полное отсутствие стрелки («путь до координатора неизвестен»); п.3 отдельно
+требует фразу-предостережение, прямо унаследованную от #457 §6 — «стрелки
+показывают дерево маршрутов, которое строит House Plan, а не путь пакета в эту
+секунду».
+
+Ни один AC это не проверяет. AC3 — единственный, что смотрит на содержание
+текста, — требует лишь «три состояния линии (сплошная цветная, серый пунктир,
+со стрелкой)» и две границы шкалы LQI. Реализация, которая опишет только
+цвет/пунктир линии и упомянёт слово «стрелка» вскользь, не называя направления,
+не называя bubble/подпись и не давая оговорку про дерево-а-не-маршрут-пакета,
+формально проходит AC1–AC8 целиком — притом что именно эти пункты являются
+причиной, по которой задача вообще ждала #457 (первая строка issue: «После #457
+вопросов станет больше»). Это ровно тот случай из §2.4: «жёлтый вердикт допустим
+и при полностью выполненных AC, если изменение не решает заявленный сценарий».
+
+**Воспроизведение риска:** возьмите черновик текста «Shows who talks directly to
+whom. Line color = signal quality (red at 40, green at 180 and above), solid =
+known, dashed = unknown.» — он проходит AC1, AC2, AC4, AC5 (нет `\n`), AC6, AC7,
+AC8 и почти проходит AC3 (упомянуты сплошная/пунктир и обе границы), но не
+содержит ни слова о стрелках, bubble или приближённости дерева. Пробел в AC его
+не ловит.
+
+**Правка:** расширить AC3 (или добавить AC3b) явным перечислением: строка `help`
+для каждого языка должна свидетельствовать о (а) исходящей стрелке = аплинк к
+координатору, (б) входящих стрелках = маршрутизация через устройство, (в) линии
+без стрелки = запасной сосед, (г) отсутствии стрелки у всего устройства = путь
+неизвестен, (д) подписи на конце стрелки = цель не на плане, и отдельно —
+наличии оговорки о приближённости («дерево, не фактический путь пакета»).
+Доказательство может остаться unit-проверкой по словарю (наличие ключевых слов/
+фраз в EN, как и для остальных AC этой задачи) — изменение дешёвое, это не
+довод против скоупа, только против полноты текущего перечня AC.
+
+### Low — фикстура для AC2 не покрыта в «Затронутых файлах»
+
+`topologyT()` (`src/i18n/topology.ts:13-15`) устроен так, что отсутствие ключа
+не проявляется как «нет значения»: `DICTIONARIES[lang]?.[key] ?? en[key] ?? key`
+— в худшем случае возвращает буквальный `key`, но никогда `undefined`/`''`.
+Реальный `_help()` (`src/houseplan-editor-runtime.ts:1228`) отличает
+«есть перевод» от «нет» через отдельную функцию `hasTranslation`, которая
+привязана к основному словарю и не годится для `topology`-namespace без
+адаптации. Значит фраза ТЗ «локальный аналог… и `nothing`, если хотя бы одного
+ключа нет» не может быть реализована через один `topologyT()` — нужен ещё один
+маленький примитив проверки присутствия ключа для `topology`-словарей (или
+локальная функция, принимающая словарь параметром, что заодно объясняет
+«словарь-фикстуру» из доказательства AC2). Ни этот примитив, ни файл, в котором
+он появится, не названы в разделе «Затронутые файлы».
+
+Это чисто техническая деталь (§7.1: «всё, чего пользователь не наблюдает,
+агенты решают сами»), не продуктовый вопрос, и не блокирует выполнимость AC2 —
+разработчик может выделить чистую функцию `resolveTopologyHelp(lang, dict)`
+с тестируемой фикстурой, ровно как описано в доказательстве. Снимаю без
+правки: реализатору достаточно одной строки экспорта или локальной функции,
+называть это отдельным пунктом ТЗ избыточно.
+
+## Что проверено и корректно
+
+- Лёгкий трек подтверждён: все пять критериев §5 не нарушены, оценка автора
+  (сложность 2, одна поверхность, без миграции/UX-контракта/perf-touch влияния)
+  совпадает с моей собственной проверкой по коду.
+- Все технические цитаты (номера строк, формула `lqiColor`, структура словарей,
+  паттерн `_help()`, отсутствие покрытия `topology` в существующих i18n-гейтах,
+  CSS `hp-help`) подтверждены чтением актуального кода — ни одна не оказалась
+  устаревшей или придуманной.
+- Ссылки на #457 точны: имена ключей (`route_other_space`,
+  `route_device_not_on_plan`, `route_coordinator_not_on_plan`), формулировка «новый
+  цвет или legend не вводятся» (§8 принятого ТЗ #457), правила направления
+  стрелок и bubble (§7.1–7.4) процитированы без искажений; #457 находится в
+  состоянии, дающем право на них ссылаться (принятое ТЗ, зелёное ревью r1,
+  `S6-in-progress`).
+- AC6 (гейт паритета словарей `topology`) обоснован верно: `test/i18n.test.mjs`
+  и `test/i18n-dead-keys.test.mjs` действительно не видят namespace `topology`
+  ни в одном виде; добавление паритета в рамках этой же задачи, которая кладёт
+  туда новые ключи, — не выход за скоуп (это тот же диф, а не соседний дефект).
+- AC7 корректен несмотря на то, что `hp-zigbee-topology-settings.ts` не входит в
+  отслеживаемые `core-file-budget` файлы: диф не касается вызывающей стороны в
+  `houseplan-editor-runtime.ts`, поэтому гейт остаётся релевантной (хоть и не
+  меняющейся) проверкой, а не бутафорией.
+- Откат прост и корректен: без сохранённого состояния и конфига — оговорка
+  верна, действие обратимо одним коммитом.
+
+## Чего не проверял и почему
+
+- Гейты (`typecheck`, `test`, `build`, golden, смоки) не гонялись — на этапе
+  ТЗ код не менялся, гонять нечего.
+- Не проверял качество перевода RU/DE/FR текста подсказки — на этом этапе текст
+  ещё не написан; за содержательную полноту всех четырёх языков будет отвечать
+  код-ревью (или, как минимум, EN-версия по AC3/AC3b, доработка выше).
+- Не проверял бюджет бандла (`bundle:budget`) числом — компонент и так лежит в
+  ленивом чанке редактора вместе с `hp-help` (оба импортируются только из
+  `houseplan-editor-runtime.ts`/`houseplan-onboarding-runtime.ts`), рост
+  стартового View-графа противоречил бы архитектуре чанков; проверено чтением
+  импортов, не измерением.
+
+## Вердикт
+
+Жёлтый: одна Medium-находка в скоупе задачи (AC3 не покрывает содержание,
+ради которого затевалась задача и ради которого она ждала #457). High-находок
+нет. Low-находка снята с запиской выше без правки ТЗ.
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `dev`, коммит `` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Якоря снять не удалось: ветки задачи нет, материал читался по `dev`.