houseplan-card/docs/specs/054-zigbee-topology-overlay.md

ТЗ #54 — Диагностический Zigbee topology overlay

• Issue: https://github.com/Matysh/houseplan-card/issues/54
• Приоритет: P2
• Статус ТЗ: research + adapter contract; provider APIs проверяются до кода

Цель

По явному запросу показать связи ZHA/Zigbee2MQTT между уже размещёнными устройствами поверх реальной геометрии, не превращая House Plan в редактор сети.

Stage 0 — capability research

На поддерживаемых версиях HA зафиксировать официальные/фактические API:

• ZHA topology/neighbour source, permissions, direction и LQI semantics;
• Zigbee2MQTT networkmap request/response через HA MQTT integration либо документированную exposed entity;
• соответствие IEEE ↔ HA device registry connections;
• timeout/rate limits и поведение sleeping end devices.

Неподтверждённые command/topic не hardcode-ятся. Каждый provider имеет fixture с обезличенными ids и дату/версию проверенного контракта.

Normalized model

type ZigbeeTopology = {
  provider: 'zha' | 'z2m'; capturedAt: number;
  nodes: Array<{ key: string; deviceId?: string; role: 'coordinator'|'router'|'end' }>;
  links: Array<{ from: string; to: string; lqi?: number; direction: 'one'|'both'|'unknown' }>;
  warnings: string[];
};

Provider adapters живут backend-side либо в изолированном HA adapter; render не знает API. Browser не подключается к MQTT напрямую и не хранит topology в House Plan config.

Fetch/cache/security

• Overlay off по умолчанию; первый toggle запускает fetch с progress/cancel.
• Shared per-provider cache TTL 60 s (уточняется Stage 0), in-flight dedupe и hard timeout. Toggle off отменяет UI ожидание, но безопасный backend request может завершить cache.
• Refresh только явный или после TTL; HA state ticks не сканируют topology.
• Read permission проверяется backend. Ошибка/unsupported не ломает plan и показывает localized status.

Mapping и визуал

Node сопоставляется marker только через device registry/explicit entity owner. На plan рисуются links, у которых оба конца имеют видимые live markers текущего space. Остальные nodes доступны в summary «Не размещено N», но не рисуются.

Edges — pointer-transparent отдельный layer. Цвет/opacity/thickness отражают нормализованный LQI только при сопоставимой шкале provider; unknown — нейтральный пунктир. Direction optional arrow только при достоверных данных. Coordinator и router имеют legend. Geometry стен не интерпретируется как причина сигнала.

Multiple spaces и lifecycle

Cross-space link не рисуется как линия через разные планы; endpoints получают badge/count и список другого пространства. Hidden/removed/disabled marker не рисуется. Rebind refreshes mapping без нового network scan.

Performance и проверки

• 20/100/500 nodes, dense mesh; edge cap/viewport culling после Stage 0;
• provider fixtures, timeout, malformed/cyclic/duplicate links;
• mapping IEEE/device/entity, cross-space, hidden lifecycle;
• lazy request/in-flight cache and no fetch on ordinary HA ticks;
• golden LQI/unknown legend и performance budget;
• network layer полностью исчезает при toggle off и не меняет config.