houseplan-card/docs/reviews/CODE-REVIEW-450-r1.md

# CODE-REVIEW-450-r1

Issue: #450 · трек `trivial` · заход r1 · блокирующих циклов 0/2
Материал: `git diff origin/dev...HEAD`, `git log --oneline origin/dev..HEAD`
SHA на момент вывода: `a8ccb2b90fa72a808e818de51d0af1697febadda`

Ветка приведена к `dev` конвейером до ревью (1 коммит dev поверх, `41612974 -> a8ccb2b9`).
Разбор — полный, как и предписано при таком ребейзе (§7.2), но фактическая
дельта тривиальна: единственный добавленный коммит-надстройка —
`a8ccb2b9 docs: refresh screenshot source fingerprint` (класс C, `User-Visible: no`,
собственный doc-коммит публикации, что и разрешено правилом «допустим только
собственный doc-коммит поверх»). Продуктовый код не менялся между `41612974`
и текущим SHA.

## Скоуп

Баг: `normalizeZ2mTopology` в `src/zigbee-topology.ts` разбирает
`bridge/response/networkmap` только в соглашении `bridge/devices`
(`ieee_address`/`network_address`), а реальный raw-ответ Zigbee2MQTT
(zigbee-herdsman) отдаёт camelCase (`ieeeAddr`/`networkAddress`) и плоские
`sourceIeeeAddr`/`targetIeeeAddr` на связи. Итог — 0 узлов, 0 связей,
`error_invalid_payload` у каждого реального пользователя Z2M. Закрывает J7
(«Zigbee mesh health») из `docs/SCOPE.md` — без парсера не работает вся ветка
Z2M диагностики.

Один коммит продуктовых изменений (`8935a736`, класс A+B+C+D в одном
коммите): `src/zigbee-topology.ts`, `test/zigbee-topology.test.mjs`,
новая фикстура `test/fixtures/zigbee2mqtt-networkmap-real-anonymized.json`,
мутант в `scripts/mutation-gate.mjs`, чек-лист в `docs/TESTING.md`, оба
changelog. Трейлеры `Issue: #450` / `User-Visible: yes` на месте, оба
changelog — в этом же коммите (проверено `git show --stat`).

## Как проверялось

### Гейты (прогнаны лично на `a8ccb2b9`)

| Гейт | Команда | Результат |
|---|---|---|
| Typecheck | `npx tsc --noEmit` | green, без ошибок |
| Unit | `npm test` | green: `tests 1909 · pass 1908 · fail 0 · skipped 1` (совпадает с заявленным в хендоффе; 1 skip — известный `#89`-класс окружения, не связан с диффом) |
| Build + сверка бандла | `npm run build` затем `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | green, идентичны. Копия `demo/srv/assets/**` не коммитится (#255) — сверка неприменима |
| Docs freshness | `node scripts/check-docs.mjs` (diff трогает `src/**`) | green: «Documentation checks passed (7 files, 12 external links)» |
| Новый `any` | `node scripts/no-new-any.mjs --base origin/dev --head HEAD` | green: 18 добавленных строк в 1 файле, новых `any` нет |
| Бюджет бандла | `npm run bundle:budget` | green: initial View 295079 B, headroom 4921 B — тот же известный долг #367, не новый регресс (диф не добавляет UI/рендер) |
| Мутант автора | `node scripts/mutation-gate.mjs --id=zigbee-topology-z2m-camelcase-node-rejected` | green: «тест покраснел, как обязан», поймано 1 из 1 |

Не гонялись и почему:
- `npm run golden:verify` — diff не меняет рендер/геометрию/стили/слои: правка только в чистом нормализаторе данных (`hp-zigbee-topology-overlay` в исходниках не тронут, изменился лишь его собранный чанк — сама сборка, а не логика оверлея). Визуальных последствий нет.
- `python -m pytest tests_backend -q` — Python не тронут.
- Инварианты модели (`npm run invariants`) — diff не касается геометрии, `layout`, `marker.space`, `open_spans`, толщины стен.
- Performance-профили — не названы в AC, чувствительных путей не касается.

### Браузерные смоки

`node scripts/smoke-select.mjs --base origin/dev --head HEAD`:

```
Изменено файлов src/**: 1 · символов на изменённых строках: 2
НЕОПРЕДЕЛЁННОСТЬ: дифф исполняемый, но ни один смок не связан доказуемо.
Символы, которых нет ни в одном смоке: endpointIeee, normalizeIeee
```

Решение: смок не гоняю. Обе неопознанные функции — внутренние помощники
чистого нормализатора MQTT-payload, без пути к DOM/canvas; сама UI-часть
(`hp-zigbee-topology-overlay`) в этом диффе не меняется вовсе, а её
рендер-контракт (что и как рисуется при наведении) не затронут — меняется
только то, какие узлы/связи долетают до неё живыми. Наблюдаемое поведение
целиком укладывается в существующий runtime-тест
(«Z2M runtime verifies retained bridge info…», низкоуровневая проверка
`refreshZ2mTopology` на реальном MQTT envelope, доходит до `phase: 'ready'`).
Браузерный смок добавил бы дублирующее, не более сильное доказательство того
же контракта. AC задачи browser-смок не называет.

### Защитные AC — таблица «чем краснеет» (§2.7)

Обе строки, требующие мутации/снятия защиты, проверены лично поверх зелёного
`npm test` (чистый юнит, без дорогого гейта — по правилу достаточно прогона
со снятой защитой):

| AC | Чем доказан | Чем краснеет |
|---|---|---|
| AC1: camelCase-узлы (`ieeeAddr`) не отбрасываются | `node --test --test-name-pattern="real anonymized camelCase" test/zigbee-topology.test.mjs` | Мутант `zigbee-topology-z2m-camelcase-node-rejected` (убирает `ieeeAddr` из чтения узла) — `node scripts/mutation-gate.mjs --id=...` → «тест покраснел, как обязан» |
| AC1: плоские `sourceIeeeAddr`/`targetIeeeAddr` имеют приоритет над вложенными `source`/`target` | `node --test --test-name-pattern="prefers flat link IEEE fields" test/zigbee-topology.test.mjs` (тест намеренно конфликтует: flat указывает на узлы 1↔2, nested на тот же узел 3↔3) | Ручная инверсия приоритета (`endpointIeee(...) ?? normalizeIeee(flat)` вместо `normalizeIeee(flat) ?? endpointIeee(...)`) на пересобранном `test-build` → `0 !== 1`, тест красный (nested self-link «съедает» оба звена) |
| AC2: массив `failed` не помечает узел недоступным (`available` не должен стать `false`) | `node --test --test-name-pattern="real anonymized camelCase" test/zigbee-topology.test.mjs` (реальная фикстура: у End device `failed: ["routingTable"]`) | Ручное снятие защиты (трактовка непустого массива как `available: false`) на пересобранном `test-build` → ожидание `{ieee, role}` без `available`, факт `available: true/false` для всех трёх узлов — тест красный |
| AC2: legacy `boolean` fallback остаётся совместимым | `node --test test/zigbee-topology.test.mjs` (тест «keeps snake_case compatibility…», узел с `failed: true` → `available: false`) | Обычное сравнение ожидаемого/фактического — AC не заявляет защиту сверх уже проверенного выше, третий столбец не нужен |
| AC3: runtime доходит до `ready` на реальной raw-схеме, malformed/ZHA не меняются | `npm test` целиком (весь `test/zigbee-topology.test.mjs`, 11/11 green) | Тест «rejects a malformed response immediately» и ZHA-тесты не тронуты диффом (сверено `git diff`) и остаются зелёными в полном прогоне — регрессии нет |

Оба ручных мутанта откачены после проверки (`src/zigbee-topology.ts`
восстановлен из `git`, `test-build` пересобран обратно перед сдачей отчёта).

## Проверка AC по существу

1. **AC1** (реальный raw-payload нормализуется без `invalid_payload`, приоритет
   плоских IEEE-полей при конфликте) — доказано автотестом
   `Z2M normalization accepts a real anonymized camelCase raw network map` на
   фикстуре `test/fixtures/zigbee2mqtt-networkmap-real-anonymized.json`
   (снята с реального payload из тела issue, IEEE обезличены) и тестом
   `...prefers flat link IEEE fields` с намеренным конфликтом flat/nested.
   Мутационно проверено (см. таблицу выше). **Выполнено.**
2. **AC2** (snake_case + nested endpoints остаются рабочими; `failed`-массив
   не превращается в недоступность; старый `boolean` совместим) — доказано
   тем же тестом (три узла с `failed: []`/`["routingTable"]` → `available`
   не выставлен) и тестом snake_case-совместимости (`failed: true` →
   `available: false`). Мутационно проверено. **Выполнено.**
3. **AC3** (runtime-тест на фактической raw-схеме доходит до `ready`;
   malformed payload и ветка ZHA не меняются) — тест
   `Z2M runtime verifies retained bridge info, correlates transaction and
   cleans subscriptions` переведён на `z2mNetworkmapFixture` целиком (через
   MQTT-подписку `refreshZ2mTopology`), проверяет `phase === 'ready'`,
   `nodes.length === 3`, `links.length === 2`. Ветка ZHA
   (`normalizeZhaTopology`, `readZhaTopology`) и malformed-тест не
   затронуты диффом — проверено чтением `git diff` (нет ни одной строки в
   ZHA-функциях) и подтверждено зелёным полным прогоном. **Выполнено.**

Примечание не по коду, а по тексту issue: раздел «Проверка» в теле issue
называет команду `node --test test/zigbee-runtime.test.mjs` — такого файла в
репозитории нет, runtime-тесты Z2M/ZHA живут в `test/zigbee-topology.test.mjs`
и покрывают ровно то же поведение (см. AC3 выше). Это неточность в тексте
issue, а не пробел кода: эквивалентная проверка существует и зелёная. Не
блокирует, не заводится отдельно — правка тела issue вне полномочий этого
ревью.

## Побочная проверка: последствие `available: false`

Проверено чтением: `mapTopologyNodes` (`src/zigbee-topology.ts:282`) исключает
узел из размещения на плане при `node.available === false`
(`provider_scan_failure`). Это делает AC2 не косметическим: до правки любой
реальный узел с частичным сбоем опроса (`failed: ["lqi"]` и т.п. — обычное
дело в живой сети) при доверчивом мэппинге массива в `false` тихо пропадал бы
с карты. Мутационная проверка выше воспроизводит именно этот сценарий на
реальном узле End device (`failed: ["routingTable"]`).

## Не проверял

- `golden:verify`, `pytest tests_backend`, `npm run invariants`,
  performance-профили — обоснование см. таблицу гейтов выше.
- Полный набор `demo/smoke_*.mjs` — не запускал ни одного: diff не задевает
  ни один визуальный/интерактивный контракт, `smoke-select.mjs` не нашёл
  прямых совпадений.
- Внешний CI-прогон `docs` (ссылка из хендоффа) — не открывал; воспроизвёл
  тот же гейт локально (`check-docs.mjs`, зелёный) и этого достаточно.
- Ветку ZHA на настоящих данных (упомянута в issue как отдельная забота) —
  сознательно исключена из скоупа автором на этапе аналитики («Ветка ZHA
  использует отдельный фактический контракт… не требует изменения»), в этом
  issue не проверяется.

## Находки

Нет High. Нет Medium — ни в скоупе, ни вне скоупа. Low нет.

Единственное отмеченное выше расхождение (несуществующий файл в тексте
«Проверка» issue) — не дефект кода и ниже порога Low: не требует правки, не
маскирует непроверенное поведение.

## Один источник числа

Диф не добавляет и не меняет ни одной пользовательски видимой величины
(площадь, размер, подпись с единицей измерения). LQI попадает в модель как
было (`lqiOf`), способ отображения не менялся. Правило неприменимо к этому
диффу.

## Вердикт

Все три AC доказаны автотестами, для защитных претензий (camelCase-приоритет,
приоритет плоских IEEE-полей, семантика `failed`-массива) лично проверено,
что тест умеет падать — мутацией автора и двумя ручными мутациями. Дешёвые
гейты зелёные. Диф укладывается в объявленный скоуп (`trivial`, одна
поверхность — Z2M-нормализатор), ветка ZHA не тронута, откат тривиален
(файл конфигурации не меняется).

**Вердикт: зелёный · заход r1 · блокирующих циклов 0/2 · High: 0 · Medium: 0**

---

## Материал раунда

- Ветка/SHA материала: `a8ccb2b90fa72a808e818de51d0af1697febadda` (HEAD на
  момент вывода, сверено `git rev-parse HEAD` непосредственно перед
  подведением итогов).
- Дерево материала: вывод `git diff origin/dev...HEAD --stat` выше,
  33 файла (13 продуктовых/тестовых/документных + генерированные `dist/**`
  и `custom_components/houseplan/frontend/**`).
- Диапазон: `git log --oneline origin/dev..HEAD` = `8935a736` (реализация),
  `a8ccb2b9` (doc-коммит публикации конвейера).
- Команды поиска (если ветка задачи будет перебазирована/удалена до r2):
  `git log --all --find-object=<blob> -- src/zigbee-topology.ts`.

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/450-z2m-networkmap-camelcase`, коммит `416129744b3a` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `d305da400327b44c81c69a8467ffab58fb02f6f7`
  ```
  git log --all --format='%H %T' | grep d305da400327
  ```