# House Plan Card — интерактивный план дома для Home Assistant

Нативная Lovelace-карточка «План дома» (дача, Кирилловское) + интеграция для серверного
хранения раскладки иконок. Замена прототипа `/local/houseplan/` (iframe + токен + localStorage).

- Работает **без токена** — использует объект `hass` фронтенда (сессия пользователя).
- План этажей (подложки РЕМПЛАННЕР 1489×1053, 1 ед. = 1 px) + двор, комнаты-зоны кликабельны.
- Устройства строятся **из реестров HA** (devices/entities/areas) с курированием и
  группировкой ламп — те же правила, что в прототипе. Новое устройство с area появляется само.
- **Живые состояния**: температура у датчиков, подсветка вкл/выкл (свет/розетки/медиа),
  открыто/закрыто (шторы/ворота/замки/датчики), приглушение при `unavailable`. Всё реактивно.
- Клик по иконке → штатное окно **more-info** (группа ламп → меню: вся группа / отдельные).
- Клик по комнате → страница зоны (`/config/areas/area/…`) без перезагрузки.
- **Правка**: кнопка ✥ — drag иконок + ввод X/Y; позиции сохраняются **на сервере**
  (WS-команды интеграции `houseplan`) — раскладка одна на все устройства и браузеры.
  Без интеграции карточка откатывается на localStorage.

## Установка (HACS)

1. HACS → меню (⋮) → **Custom repositories** → URL этого репозитория, категория **Integration**.
2. Установить «House Plan», перезапустить HA.
3. Настройки → Устройства и службы → **Добавить интеграцию → House Plan** (одна запись; опция
   «правка только администраторами»). Интеграция сама раздаёт и подключает JS карточки —
   ресурс Lovelace добавлять не нужно.
4. В дашборд добавить карточку:

```yaml
type: custom:houseplan-card
title: План дома · Кирилловское
default_floor: f1        # f1 | f2 | yard
icon_size: 22            # px
show_temperature: true
live_states: true
```

Только карточка (без серверного хранения): категория **Dashboard/Lovelace**, ресурс
`/hacsfiles/houseplan-card/houseplan-card.js` — позиции будут в localStorage браузера.

## WS-API интеграции

| Команда | Параметры | Действие |
|---|---|---|
| `houseplan/layout/get` | — | вернуть раскладку `{device_id: {x, y}}` |
| `houseplan/layout/set` | `layout` | заменить целиком |
| `houseplan/layout/update` | `device_id`, `pos` | обновить одну позицию |

Хранилище: `.storage/houseplan.layout` (helpers.storage.Store).

## Почему не ha-floorplan

Оценивали `ExperienceLovelace/ha-floorplan` (установлен в этом HA): он закрывает SVG-план,
привязку сущностей и стили по состоянию, но привязки статичны (entity → элемент SVG прописывается
руками в YAML/SVG), нет автопоявления новых устройств из реестра, нет курирования/группировки
ламп и главное — нет drag-раскладки с серверным сохранением. Перенос этих требований в
ha-floorplan потребовал бы генератор SVG+конфига и всё равно не дал бы редактирование из UI.
Своя карточка (~1 файл) оказалась дешевле и полностью повторяет прототип. Решение: **свой card**.

## Документация

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — устройство карточки и интеграции, координаты, WS API
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — сборка, деплой, грабли окружения (обязательно к прочтению)
- [docs/CHANGELOG.md](docs/CHANGELOG.md) — история версий
- [docs/ROADMAP.md](docs/ROADMAP.md) — план до публикации в HACS (универсализация, редактор разметки, виртуальные устройства)

## Разработка

```bash
npm install
npm run build        # dist/houseplan-card.js (+ скопировать в custom_components/houseplan/frontend/)
```

Геометрия комнат/viewBox — `src/data/house.ts`; подложки — `src/data/backgrounds.ts`
(генерируются из data.js прототипа); правила иконок/курирования — `src/rules.ts`.

Релиз: тег `vX.Y.Z` → GitHub Release; workflow соберёт и приложит `houseplan-card.js`.