# House Plan — полное руководство пользователя

Актуально для **v1.60.0**. Руководство заново составлено по исходному коду и фактическому интерфейсу этой версии. Старые README и тематические спецификации использовались только для перепроверки сценариев.

House Plan — локальная интеграция и две Lovelace-карточки для Home Assistant:

- `custom:houseplan-card` — интерактивный план с редакторами, состояниями и управлением;
- `custom:houseplan-space-card` — статическая схема одного пространства со ссылкой на полный план.

Все планы, настройки и позиции хранятся внутри Home Assistant. Облачный сервис House Plan не используется.

> **Уровень поддержки устройств ввода.** Просмотр и киоск должны полноценно и
> удобно работать на телефонах, планшетах и настенных touch-панелях. Создавать и
> редактировать планы рекомендуется на компьютере с мышью и клавиатурой.
> Редакторы на touch поддерживаются по остаточному принципу: отдельные жесты,
> точные операции или элементы интерфейса могут работать неудобно, ограниченно
> либо отсутствовать. Это не относится к безопасности данных и действий:
> touch-редактор не должен повреждать план или отправлять случайные команды.

## Содержание

1. [Модель данных и терминология](#1-модель-данных-и-терминология)
2. [Установка и доступ](#2-установка-и-доступ)
3. [Добавление карточки](#3-добавление-карточки)
4. [Быстрый старт](#4-быстрый-старт)
5. [Режимы интерфейса](#5-режимы-интерфейса)
6. [Навигация, масштаб и жесты](#6-навигация-масштаб-и-жесты)
7. [Пространства](#7-пространства)
8. [Комнаты и стены](#8-комнаты-и-стены)
9. [Двери, окна и замки](#9-двери-окна-и-замки)
10. [Устройства](#10-устройства)
11. [Действия по нажатию](#11-действия-по-нажатию)
12. [Визуальные состояния устройств](#12-визуальные-состояния-устройств)
13. [Заливки комнат и свет](#13-заливки-комнат-и-свет)
14. [Редактор подложки](#14-редактор-подложки)
15. [Солнце и фон день/ночь](#15-солнце-и-фон-деньночь)
16. [Роботы-пылесосы](#16-роботы-пылесосы)
17. [Киоск-режим](#17-киоск-режим)
18. [Статическая карточка пространства](#18-статическая-карточка-пространства)
19. [Обслуживание планов](#19-обслуживание-планов)
20. [Хранение, совместная работа и резервные копии](#20-хранение-совместная-работа-и-резервные-копии)
21. [Ограничения текущей версии](#21-ограничения-текущей-версии)
22. [Диагностика](#22-диагностика)

## 1. Модель данных и терминология

Настройки образуют иерархию: общие значения задают базовый вид, пространство может их переопределить, затем отдельная комната, затем устройство.

| Уровень | Что это | Что хранит |
|---|---|---|
| Карточка | Один экземпляр `houseplan-card` на дашборде | Стартовое пространство, язык, размер иконок, показ значений/LQI, живые состояния, киоск и автолистание |
| Общие настройки | Настройки всего House Plan | Палитры заливок, фон, радиус света, север, солнце, погода, правила иконок |
| Пространство | Этаж, двор, гараж, отдельное строение | Подложку, масштаб сетки, комнаты, стены, проёмы, декор и настройки отображения |
| Комната | Только замкнутый контур | Название, необязательную HA-зону, источники температуры/влажности и локальную заливку |
| Стена | Сторона контура комнаты | Необязательную толщину и виртуальные участки общей границы |
| Проём | Дверь, окно или ворота на стене | Размер, ориентацию, контактный датчик и, для двери/ворот, замок |
| Маркер | Значок устройства на плане | Привязку к HA, комнату, действие, внешний вид, свет, описание и файлы |
| Декор | Элемент подложки | Линию, фигуру, текст, мебель или положение изображения плана |

Важное ограничение версии: стена пока не существует отдельно от комнаты. Она выводится из границы замкнутого контура. Незамкнутые и свободно стоящие стены пока не поддерживаются.

## 2. Установка и доступ

### Требования

| Компонент | Требование |
|---|---|
| Home Assistant | 2024.6.0 или новее |
| Тип установки | Любой, где доступны пользовательские интеграции |
| Браузер | Современный браузер с Web Components, SVG и Pointer Events |
| Права | По умолчанию редактировать House Plan могут только администраторы |

### Установка через HACS

1. В HACS добавьте `https://github.com/Matysh/houseplan-card` как пользовательский репозиторий категории **Integration**.
2. Установите **House Plan** и перезапустите Home Assistant.
3. Откройте **Настройки → Устройства и службы → Добавить интеграцию** и выберите **House Plan**.
4. Оставьте включённой опцию «редактировать план только администраторам», если обычным пользователям нужен только просмотр и управление.

Интеграция сама регистрирует Lovelace-ресурс. При YAML-управлении ресурсами добавьте его вручную:

```yaml
resources:
  - url: /houseplan_files/houseplan-card.js
    type: module
```

Не используйте файловый путь `/custom_components/houseplan/frontend/houseplan-card.js`: Home Assistant не раздаёт его как модуль. Обе карточки находятся в одном файле `/houseplan_files/houseplan-card.js`.

### Ручная установка

1. Скопируйте папку `custom_components/houseplan` из релиза в `config/custom_components/houseplan`.
2. Перезапустите Home Assistant.
3. Добавьте интеграцию **House Plan**.
4. Если ресурсы Lovelace управляются YAML, добавьте ресурс из примера выше.

### Права пользователей

| Настройка интеграции | Просмотр | Управление устройствами | Редактирование планов и загрузка файлов |
|---|---:|---:|---:|
| Только администраторы — включено (по умолчанию) | Все вошедшие пользователи | По обычным правам HA | Только администраторы |
| Только администраторы — выключено | Все вошедшие пользователи | По обычным правам HA | Все вошедшие пользователи |

Оптимизация планов и отмена оптимизации всегда требуют администратора, независимо от этой опции.

## 3. Добавление карточки

Минимальная конфигурация основной карточки:

```yaml
type: custom:houseplan-card
title: План дома
```

Параметры основной карточки доступны в визуальном редакторе Lovelace.

| Поле | Значение по умолчанию | Поведение |
|---|---:|---|
| `title` | пусто | Заголовок карточки |
| `default_floor` | первое/последнее открытое | Пространство при первом открытии этого экземпляра |
| `language` | язык HA | `auto`, `ru` или `en` |
| `icon_size` | `2.5` | Базовый размер маркеров, 1–6% ширины плана |
| `show_temperature` | `true` | Показывает компактные значения температуры **и влажности** у подходящих устройств |
| `live_states` | `true` | Включает рабочие/открытые/недоступные состояния, смену иконок и активность; аварии остаются видимыми всегда |
| `show_signal` | `true` | Базовый показ LQI; отдельное пространство может переопределить его |
| `kiosk` | `false` | Полноэкранный режим без шапки и редакторов |
| `cycle` | `0` | Интервал автолистания пространств в киоске, 0–3600 секунд; `0` выключает |

Карточечный `tap_action` из старых конфигураций игнорируется. Действие задаётся отдельно для каждого устройства.

## 4. Быстрый старт

Рекомендуемый порядок настройки:

1. Создайте пространство кнопкой **+**. Можно импортировать этажи из реестра этажей HA.
2. Загрузите SVG/PNG/JPG/WebP или выберите вариант без изображения.
3. Укажите размер одной клетки сетки в сантиметрах. От него зависят размеры стен, проёмов, мебели и площадь.
4. В **Редакторе плана** обведите каждую комнату замкнутым контуром.
5. Свяжите комнату с одноимённой HA-зоной или оставьте без зоны.
6. Добавьте толщину стен и проёмы.
7. В **Редакторе устройств** расставьте автоматически найденные маркеры и настройте действия.
8. В **Редакторе подложки** подвиньте изображение, добавьте мебель, подписи и декоративные линии.
9. Выберите режим заливки пространства и настройте палитру в общих настройках.
10. При необходимости включите киоск, солнечные лучи и живую позицию пылесоса.

Шаги создания и редактирования плана выполняйте в desktop-браузере. Телефон,
планшет и настенная панель являются полноценными целевыми устройствами для
последующего просмотра и управления домом, но не гарантированной средой
редактирования.

## 5. Режимы интерфейса

Обычный просмотр — не отдельная вкладка: это состояние, в которое возвращает крестик активного редактора.
Редакторы переключаются напрямую. Новая панель инструментов коротко проявляется,
а её фактическая высота плавно подстраивается даже при переносе кнопок на несколько строк;
при системной настройке уменьшения движения переход отключается.

| Режим | Основное назначение | Устройства | Комнаты/стены | Декор и проёмы |
|---|---|---|---|---|
| Просмотр | Контроль дома | Интерактивны; видны состояния, значения и подсказки | Комната подсвечивается при наведении; подсказка показывает название, чистую площадь, температуру и LQI | Видны, если не скрыты настройками пространства; проёмы не реагируют на клик, кроме значка замка |
| Редактор плана | Геометрия комнат, стен и проёмов | Скрыты | Интерактивны; видны кнопки настроек комнат, размеры и сетка | Проёмы всегда видны и редактируются; виртуальные стены рисуются полностью по оси |
| Редактор устройств | Позиции и параметры маркеров | Перетаскиваются; клик открывает настройки; доступны скрытые маркеры | Не редактируются | Служат фоном |
| Редактор подложки | Изображение, линии, фигуры, текст, мебель | Не редактируются и полупрозрачны | Комнаты, физические и виртуальные стены полупрозрачны | Декор интерактивен и непрозрачен; скрытый в просмотре декор всё равно виден здесь |
| Киоск | Настенный экран | Интерактивны как в просмотре | Только отображение | Только отображение; редакторы отсутствуют |
| Статическая карточка | Компактная схема пространства | Только рисунок | Только рисунок | Без состояний и интерактивности |

В редакторах сетка продолжается по всему рабочему холсту. В режиме просмотра сетка не показывается.

Основная панель каждого редактора содержит только постоянные инструменты, а
кнопка закрытия закреплена справа. Параметры активного инструмента, подсказки
незавершённой операции и действия выбранного объекта появляются в
полупрозрачной суб-панели поверх верхней части холста. Она не уменьшает рабочую
область и не меняет масштаб плана. На узком экране действия прокручиваются
горизонтально внутри самой суб-панели.

## 6. Навигация, масштаб и жесты

Холст практически бесконечен: элементы можно рисовать и размещать за пределами исходного квадрата плана. Команда **Показать всё** подбирает вид по фактическому содержимому.

Touch-жесты просмотра и киоска из таблицы ниже входят в гарантированный
сценарий. Наличие редактора на сенсорном экране не означает полного соответствия
desktop: для точного рисования, Resize, модификаторов клавиатуры и свойств по
двойному клику используйте компьютер.

| Действие | Мышь/клавиатура | Сенсорный экран |
|---|---|---|
| Масштаб | Колесо, кнопки `−`/`+` | Щипок двумя пальцами |
| Панорама | Перетаскивание пустого места | Перетаскивание |
| Показать всё | Центральная кнопка масштаба | Та же кнопка вне киоска |
| Привязка объектов | Выполняется автоматически и всегда | Выполняется автоматически и всегда |
| Сброс киоск-масштаба | — | Двойной тап |
| Следующее пространство в киоске | — | Горизонтальный свайп при масштабе 1:1 |
| Локальный размер киоска | — | Удерживать пустое место 3 секунды |

Особенности:

- панорамирование работает при любом масштабе;
- масштаб режима просмотра запоминается отдельно для каждого пространства на текущем клиенте;
- масштаб и панорама внутри редактора — рабочие и не заменяют сохранённый вид просмотра;
- если один или несколько объектов далеко от основного плана, появляется подсказка о дальних объектах;
- в киоске при увеличении выше 1:1 горизонтальный жест двигает план, а не листает этажи;
- любая ручная операция в киоске приостанавливает автолистание на 60 секунд;
- `Shift` не отключает позиционную сетку; при рисовании контура комнаты он фиксирует стену по ближайшему направлению с шагом 45°; в редакторе подложки делает прямоугольник квадратом/овал кругом при создании, разрешает непропорциональное масштабирование и свободный поворот; у компаса включает шаг 15°.

### Клавиши отмены

| Контекст | `Esc` | `Ctrl+Z` / `Cmd+Z` | `Ctrl+Shift+Z` / `Ctrl+Y` |
|---|---|---|---|
| Незавершённый Draw/Split | Убирает последнюю точку или выходит из инструмента | Сначала убирает незавершённую точку | — |
| Любой инструмент редактора плана | Отменяет текущий жест/выбор | Отменяет последнюю именованную геометрическую операцию | Повторяет отменённую операцию |
| Подложка | Отменяет незавершённое рисование или возвращает состояние до начала активного move/resize/rotate | Отменяет последнюю именованную операцию декора или картинки | Повторяет отменённую операцию |
| Текстовое поле | Закрывает верхний диалог | Обычная отмена текста браузером | Обычный повтор текста браузером |

Общий стек геометрии хранит 50 операций и используется редакторами плана и подложки. В обе панели добавлены кнопки **Отменить** и **Повторить**; их подсказка показывает имя следующего шага. История живёт в текущей сессии карточки и безопасно сбрасывается, если с сервера приходит более новая внешняя ревизия плана.

Во всех диалогах `Tab` и `Shift+Tab` перемещают фокус только внутри открытого
окна, `Esc` закрывает верхнее окно, а после закрытия фокус возвращается на
кнопку или объект, которыми диалог был открыт. При открытии вложенного окна
возврат сначала происходит в родительский диалог.

## 7. Пространства

Пространство подходит не только для этажа: это может быть двор, гараж, баня или отдельное строение.

### Источник плана

| Вариант | Когда использовать | Поведение |
|---|---|---|
| Изображение | Есть готовый чертёж или фото | SVG, PNG, JPG, WebP; пропорции изображения сохраняются, положение и масштаб можно менять позже |
| Уже загруженный файл | Один план используется повторно или файл уже лежит на сервере | Выбор из серверного списка; используемый пространством файл нельзя удалить |
| Без изображения | План рисуется непосредственно в House Plan | Бумага формируется по контурам комнат; границы и названия удобно включить сразу |
| Импорт этажей HA | В HA уже создан реестр этажей | Мастер создаёт пространства по очереди; любой этаж можно пропустить |

### Настройки пространства

| Раздел | Настройка | Результат |
|---|---|---|
| Масштаб | Сантиметров на клетку | Переводит сетку в реальные размеры и площади; начальное значение 5 см |
| Отображение | Всегда показывать границы | Рисует контуры комнат в просмотре |
| Отображение | Показывать названия | Рисует карточки/названия комнат; их можно двигать в редакторе плана |
| Отображение | Показывать LQI | Переопределяет базовую настройку карточки для этого пространства |
| Отображение | Скрыть декоративный слой | Не рисует линии, фигуры, текст и мебель в просмотре; в редакторе подложки они остаются видимыми |
| Отображение | Скрыть проёмы | Скрывает только символы дверей, окон и ворот; свет, солнечные лучи и датчики проёмов продолжают работать |
| Карточка комнаты | Температура/влажность/LQI/свет | Добавляет выбранные показатели под названием комнаты |
| Карточка комнаты | Общий размер шрифта | Масштабирует все комнатные карточки пространства, 50–300% |
| Стиль | Цвет и прозрачность | Общий цвет границ и названий |
| Фон | Наследовать/статический/день-ночь | Управляет фоном вокруг плана |
| Солнце | Север и лучи | Локально переопределяет общие настройки |
| Заливка | Световые источники/нет/LQI/свет/температура | Выбирает модель заливки для комнат пространства |

Удаление пространства удаляет его комнаты и разметку после подтверждения. Файл подложки при этом автоматически не удаляется: им можно управлять через список уже загруженных планов.

## 8. Комнаты и стены

### Создание комнаты

1. Откройте **Редактор плана**.
2. Выберите **Контур комнаты**.
3. При необходимости укажите толщину новых стен в появившейся над холстом
   панели параметров. `0`/пусто создаёт тонкую осевую границу.
4. Поставьте минимум три точки по сетке.
5. Замкните контур кликом по первой точке или `Ctrl` + кликом в любом месте.
   Быстрое замыкание доступно после двух нарисованных граней и не сработает,
   если замыкающая стена создаёт самопересечение.
6. В диалоге задайте название, выберите свободную HA-зону либо оставьте в списке «— без зоны —», затем нажмите «Сохранить».

Во время рисования показываются длина сегмента и угол. Углы, кратные 45°, выделяются. Удерживайте `Shift`, чтобы зафиксировать текущий отрезок по ближайшему такому направлению; предпросмотр и поставленная точка останутся на сетке. Новая комната не может частично перекрывать другую, но полностью вложенная «островная» комната поддерживается.

Каждый законченный отрезок незамкнутого контура сохраняется сразу. В той же
сессии инструмент продолжит его автоматически; после перезагрузки выберите
кликом один из концов. Замкнутый контур можно сохранить как комнату или выбрать
в диалоге действие **Оставить замкнутыми стенами**.

### Связь с HA-зоной

Одна HA-зона может быть назначена только одной комнате. Связь нужна для автоматического размещения устройств, LQI, света и средних климатических показателей. Комната без HA-зоны всё равно может иметь вручную назначенные устройства и отдельные источники температуры/влажности.

### Инструменты плана

| Инструмент | Что выбирать | Результат и ограничения |
|---|---|---|
| Контур комнаты | Точки контура | Создаёт комнату; незаконченный контур сохраняется и допускает разную толщину сегментов |
| Перегородка | Две точки | Создаёт одну независимую стену с текущей толщиной; комнату и HA-зону не делит |
| Колонна | Одну точку | Создаёт квадратную колонну с текущим размером; форму, размер и поворот можно изменить в свойствах |
| Объединить | Две соседние комнаты | Объединяет геометрию; в диалоге выбирается, чья идентичность/название/HA-зона сохранится |
| Split | Комнату, старт на стене, путь внутри, финиш на стене | Делит комнату; большая часть сохраняет исходную комнату, меньшая получает новое имя/HA-зону |
| Resize | Ручку стены или комнату | Двигает стену с общей геометрией; по клику на комнату даёт угловую рамку масштабирования |
| Opening | Точку на стене | Создаёт дверь, окно или ворота; клик существующего проёма открывает его настройки |
| Граница | Две точки общей стены или существующий пунктир | Два клика делают участок общей стены виртуальным; один клик по пунктиру целиком восстанавливает физическую стену |
| Толщина | Реальный участок стены | Задаёт толщину выбранному участку или всем стенам комнаты |
| Удалить комнату | Точку внутри комнаты | После подтверждения удаляет только эту комнату; стены не запускают другие скрытые действия |

### Merge

- Комнаты должны иметь общую границу.
- Пользователь выбирает, какая комната остаётся основной.
- Название, HA-зона и привязанные к ней устройства второй комнаты не переносятся автоматически. Устройства её HA-зоны исчезнут с этого плана, пока зона не будет назначена другой комнате.
- Вложенные и геометрически несовместимые варианты могут быть отклонены.

### Split

- Первая и последняя точки разреза должны лежать на границе выбранной комнаты.
- Промежуточные точки должны идти внутри комнаты и не пересекать контур или сам разрез.
- Большая по площади часть сохраняет исходную комнату и устройства.
- Для меньшей части открывается диалог новой комнаты.

### Resize

| Сценарий | Что происходит |
|---|---|
| Движение внешней стены | Меняется только выбранная комната |
| Движение общей стены | Одновременно меняются обе соседние комнаты |
| На стене есть проём | Проём следует за стеной и остаётся на ней |
| На стене разная толщина/виртуальный участок | Интервалы толщины и виртуальности переносятся вместе со стеной |
| Клик по комнате | Появляется рамка для масштабирования всей комнаты |
| Размер стал слишком мал | Минимальный размер комнаты — 30 см |

Resize показывает живые длины и чистую площадь по внутреннему контуру толстых стен. Завершённый drag становится одним именованным шагом общего 50-командного Undo/Redo.

Перегородки и колонны можно перетаскивать по сетке и редактировать двойным
кликом. У перегородки задаётся толщина 1–100 см. У колонны задаются квадратная
или круглая форма и внешний размер 1–150 см; у квадрата доступен поворот, у
круга размер означает диаметр. Они вычитаются из чистой площади, перекрывают
Glow и солнечные лучи, но при Resize комнаты остаются на месте. За пределами
комнат эти объекты не создают пол или фон.

### Толщина стены

| Параметр | Поведение |
|---|---|
| Значение | 1–100 см; пусто/0 в интерфейсе очищает толщину |
| Геометрия | Толщина растёт на половину значения в обе стороны от оси стены |
| Общая стена | Одна физическая стена между комнатами |
| Чистая площадь | Считается по внутренней грани стен |
| Углы | Соседние тела стен соединяются; на малом масштабе штриховка скрывается, тело остаётся |
| Соседние одинаковые участки | Нормализуются в один участок при редактировании/оптимизации |
| Виртуальный участок | Не имеет тела и толщины; реальные остатки сохраняют свою толщину |

### Виртуальные стены

Виртуальная стена — открытый участок **общей границы двух комнат**. Она нужна для зонирования одного физически открытого пространства.

| Ситуация | Поведение |
|---|---|
| Создание | Два клика на одном общем ребре; участок ограничивается ближайшими углами |
| Закрытие | Тот же инструмент «Граница» восстанавливает весь канонический пунктир одним кликом |
| Несколько соседних участков | Объединяются в один канонический отрезок |
| Проёмы на открываемом участке | Удаляются, потому что в виртуальной стене проём не нужен |
| Толщина | На открытом участке удаляется; на реальных остатках сохраняется |
| Свет | Свет свободно распространяется по всей связанной открытой зоне |
| Просмотр | Пунктир проходит по оси, но скрывается под телом примыкающих толстых стен |
| Редакторы | Пунктир рисуется полностью от оси стены для точного редактирования |
| Внешняя стена | Сделать виртуальной нельзя |
| Ответвление из середины | Не поддерживается |

Инструмент показывает действие до клика: на сплошной общей стене — точку
начала или диапазон будущего виртуального участка, на пунктире — тело
восстанавливаемой стены с наследуемой толщиной. У наружной стены курсор
блокируется. Если рядом со стыком подходят несколько разных участков, нужно
сместиться чуть дальше от узла. Перегородка, колонна или незавершённый контур
поверх границы также блокируют скрытое редактирование — сначала выберите и
переместите либо удалите самостоятельный объект.

## 9. Двери, окна, ворота и замки

Проём всегда привязан к стене. Дверь по умолчанию создаётся шириной 90 см, окно — 120 см, ворота — 300 см. Допустимый размер в интерфейсе: 20–600 см с шагом 5 см.

Ворота по данным и поведению равны двери: могут иметь датчик открытия и замок, вырезают стену и пропускают Glow. Отличается только символ: две половинные створки без большой дуги, приоткрытые наружу на 10°. С датчиком угол меняется от 0° до 10°; без датчика показаны статически открытыми на 10°. Выбор распашных/откатных и других типов пока не предусмотрен.

### Настройки проёма

| Поле | Дверь | Окно | Ворота |
|---|---:|---:|---:|
| Размер | Да | Да | Да |
| Контактный датчик | Да | Да | Да |
| Инверсия датчика | Да | Да | Да |
| Петли с другой стороны | Да | Да | Нет: створки симметричны |
| Открывается в другую сторону | Да | Да | Да; по умолчанию — наружу |
| Замок `lock.*` | Да | Нет | Да |

Контакт выбирается из подходящих `binary_sensor` и дверных `cover`. Состояние датчика анимирует створку/полотно. Инверсия нужна, если интеграция отдаёт противоположную логику.

### Поведение в разных режимах

| Режим | Клик по проёму | Перетаскивание |
|---|---|---|
| Просмотр | Сам проём инертен; значок замка открывает карточку проёма | Нет |
| Редактор плана | Открывает настройки | Да, вдоль стены |
| Остальные редакторы | Инертен | Нет |

При перетаскивании проём всегда магнитится к центру стены либо к шагу сетки вдоль стены. Обхода этой привязки нет.

### Замок

- `locked` показывается как закрытый замок;
- `unlocked`/`open` — как открытый, с оранжевым состоянием;
- неизвестное состояние получает нейтральное/неизвестное оформление;
- клик по значку открывает карточку проёма;
- закрытие выполняется без дополнительного подтверждения;
- открытие замка требует подтверждения;
- обычное действие маркера устройства никогда не переключает `lock.*` и не снимает охрану `alarm_control_panel.*`.

### Толстые стены

Тело стены вырезается по ширине проёма, откосы идут через всю глубину стены. Створка/дуга двери и окна смещается к внутренней грани комнаты, а створки ворот — к наружной. Свет проходит через дверь или ворота по ширине внутреннего тоннеля и отсекается откосами. Солнечный луч начинается из внутренних углов оконного тоннеля.

Солнце проходит только через наружные окна. Внутренние окна солнечных лучей не создают.

## 10. Устройства

### Как маркеры появляются автоматически

House Plan читает реестры устройств, сущностей и зон Home Assistant. Устройства HA-зоны появляются в комнате, связанной с этой зоной. Позиция назначается автоматически, затем её можно изменить.

Некоторые служебные и нефизические интеграции скрываются при первой материализации списка: например HACS, системные сущности, мосты, сцены и часть агрегатов. Лампочки, входящие в группу света, могут быть заменены одним групповым маркером.

После первичного заполнения новые устройства отмечаются красной точкой. Точка исчезает после первого открытия маркера в редакторе устройств.

### Виды привязки

| Вид | Что выбирается | Особенности |
|---|---|---|
| Устройство HA | Запись из реестра устройств | Использует все связанные сущности; основной домен выбирается автоматически |
| Сущность HA | Одна сущность | Доступно после включения «Показывать сущности»; удобно для helper/group/template |
| Виртуальное устройство | Ничего | Только подпись/иконка/описание; живого состояния HA нет |

Одну и ту же привязку нельзя одновременно использовать в двух маркерах.

### Редактор устройств

| Действие | Результат |
|---|---|
| Перетащить маркер | Меняет его общую серверную позицию; центр всегда оказывается на узле сетки |
| Клик по маркеру | Открывает диалог настройки |
| **Добавить** | Создаёт виртуальный маркер или вручную выбирает HA-привязку |
| **Скрытые и деактивированные** | Показывает пользовательски скрытые и отключённые в HA устройства служебными маркерами только в этой вкладке |
| **Правила иконок** | Открывает приоритетный список регулярных выражений для «имя + модель» |

### Основные настройки маркера

| Поле | Назначение |
|---|---|
| Имя | Подпись и заголовок карточки устройства |
| Привязка | Устройство, сущность или виртуальный маркер |
| Комната | Автоматическая HA-зона либо ручное назначение, включая комнату без зоны |
| Действие по нажатию | Карточка House Plan, HA more-info, toggle, запуск сценария или управление шторами |
| Управляет другими источниками света | Группа других `light.*`/`switch.*`, переключаемая вместе. Собственная entity и сущности привязанного устройства сюда не входят |
| Это источник света | Явно считает само реле/выключатель источником света и позволяет ему создавать световое пятно |
| Использовать температуру climate | Добавляет `current_temperature` термостата/кондиционера в маркер и среднее комнаты |
| Скрыть / Показать | Кнопка в левом нижнем углу диалога. После сохранения убирает или возвращает значок; LQI скрытого устройства всё ещё может участвовать в среднем комнаты |
| Удалить | Кнопка рядом со «Скрыть». После подтверждения сразу полностью убирает устройство с плана и позволяет позднее добавить его заново |
| Радиус свечения | Локально переопределяет общий радиус, 0.1–100 м в хранилище |
| Иконка | Ручная `mdi:*`; пусто — автоматический подбор. Автовариант показывается в поле как значок с именем `mdi:*`, но не сохраняется как ручная замена |
| Отображение | Иконка, иконка + активность или значение вместо иконки. Ниже сразу видны фактический результат, источник и интеграция |
| Размер/поворот | Масштаб маркера и угол |
| Модель, ссылка, описание | Информация во внутренней карточке |
| Файлы | PDF, PNG, JPG/JPEG, WebP, TXT; несколько вложений |

Удаление и скрытие — разные операции. Скрытый маркер можно показать через
**Скрытые и деактивированные**, и он продолжает участвовать в предусмотренных для скрытых
устройств данных. Удалённый маркер там не показывается, не участвует в LQI,
температуре, влажности, свете, Glow, карточке комнаты, управлении и живых
ссылках плана. Его привязка снова появляется в списке **Добавить**. Повторное
добавление создаёт новую позицию; сохранённая конфигурация проёмов и текстовых
переменных снова оживает. Позиция, вложения и след пылесоса удаляются.

### Скрытые устройства

Скрытый маркер:

- не рисуется в просмотре;
- в редакторе виден только при включённом **Скрытые и деактивированные**;
- не показывает цвет состояния, число, температуру, влажность и LQI;
- не создаёт световое пятно и не считается источником для заливки «Свет»;
- может продолжать участвовать в среднем LQI комнаты, потому что оно считается по реестру устройств зоны.

### Деактивированные в Home Assistant

Если устройство, привязанная сущность или все сущности устройства имеют
`disabled_by` в HA, House Plan временно исключает привязку полностью: маркер не
рисуется, не входит в LQI/температуру/влажность/свет/Glow, не питает текстовые
переменные и проёмы, не выполняет действия; у пылесоса также нет puck и следа.
Конфигурация, позиция, вложения и серверная история при этом не удаляются.

В редакторе **Скрытые и деактивированные** показывает серый marker с причиной.
Его можно открыть, изменить описание, удалить с плана или перейти в настройки
HA. «Показать» заблокировано до активации. После активации того же ID устройство
возвращается со старыми настройками и позицией; ранее установленное пользователем
«Скрыть» сохраняется.

Если аккаунту не разрешено читать полный реестр HA, House Plan не угадывает
деактивацию по отсутствию записи. Подтверждённые живые привязки работают, а
неподтверждённые безопасно не влияют на план до восстановления доступа.

## 11. Действия по нажатию

### Жесты маркера

| Жест | Режим просмотра | Редактор устройств |
|---|---|---|
| Короткий клик/тап | Выполняет выбранное действие | Открывает настройки маркера |
| Долгое нажатие, 600 мс | Открывает внутреннюю карточку House Plan | Не используется для управления |
| Правый клик | Открывает стандартный HA more-info основной сущности | Открывает контекст редактора/браузера по текущему поведению |

### Действия

| Действие | Что происходит | Защита |
|---|---|---|
| Карточка устройства | Открывается House Plan-карточка с сущностями, моделью, описанием, ссылками и файлами | Состояние не меняется |
| HA more-info | Открывается штатный диалог основной сущности | Состояние не меняется |
| Toggle | Переключается основная сущность или группа `controls` | Никогда не переключает замок и охранную панель; можно включить подтверждение |
| Run | `automation.trigger`, `script.turn_on` или `scene.turn_on` | Цель выбирается явно; можно включить подтверждение |
| Open/close | Для подходящего `cover.*`: closed→open, open→close, opening/closing→stop, неизвестно→toggle | Только явный выбор; не предлагается для garage/door/gate; можно включить подтверждение |

У устройства, чья основная функция — `light.*`, действие по умолчанию уже является Toggle. У остальных устройств по умолчанию открывается внутренняя карточка.

Если указаны несколько управляемых источников света:

- когда включён хотя бы один, нажатие выключает все;
- когда выключены все, нажатие включает все;
- визуальное состояние маркера объединяет эти источники.

## 12. Визуальные состояния устройств

В динамических режимах система состоит из трёх независимых слоёв:

1. **подложка маркера** сообщает устойчивый статус;
2. **иконка/число** сообщает тип или значение;
3. **кольцо активности** в режиме «Иконка + активность» сообщает событие, присутствие, движение или работу.

Приоритет статусов: **авария → работа → открыто → нейтрально**. Если все сущности, реально описывающие маркер, недоступны, маркер бледнеет. У медиаплеера `off` использует то же приглушённое отображение, что `unknown` и `unavailable`, без отдельного визуального состояния.

### Подложка и постоянный статус

| Вид | Что означает | Примеры |
|---|---|---|
| Красная авария | Критическое событие; показывается даже при выключенных живых состояниях | Дым, газ, CO, протечка, tamper/problem/safety, сирена `on`, охранная панель `triggered` |
| Жёлтая подложка | Устройство сейчас выполняет работу | Свет/реле/вентилятор/увлажнитель `on`; climate с распознанным action `heating`, `cooling`, `preheating` или `defrosting`; при отсутствии распознанного action — включённый HVAC-режим как лучшее доступное приближение; vacuum cleaning/returning; script on; техника washing/drying/etc. |
| Оранжевая подложка | Физически открыто/разблокировано | Датчик двери/окна/гаража `on`, замок unlocked/open, клапан open/opening/closing |
| Бледный маркер | Данные недоступны либо медиаплеер выключен | Все рабочие сущности маркера `unknown`, `unavailable` или отсутствуют; `media_player.* = off` |
| Нейтральный | Нет аварии, работы и открытого состояния | Выключено, закрыто, idle/standby/docked и т. п. |

`automation.* = on` означает «автоматизация включена», а не «исполняется», поэтому жёлтая подложка не появляется. Для climate распознанный `idle` всегда нейтрален; неизвестные служебные значения action от сторонних интеграций игнорируются и не блокируют проверку HVAC-режима. `cover.*` специально не получает оранжевую подложку за открытое состояние: открытие показывается формой иконки.

### Активность

Кольцо рисуется только при выбранном отображении **Иконка + активность** и включённых живых состояниях.

| Тип активности | Длительность | Источники |
|---|---|---|
| Событие | Около 3.3 секунды | Motion/vibration/sound при срабатывании; открытие контакта; button/event при изменении; ручной запуск сценария из карточки |
| Присутствие | Пока состояние активно | Binary sensor с классом occupancy/presence |
| Переход | Пока идёт движение; при мгновенном переходе около 3.3 секунды | Cover opening/closing, lock locking/unlocking, valve opening/closing, moving sensor, vacuum returning |
| Работа | Пока устройство работает | Свет, switch, fan, humidifier, climate action (либо включённый HVAC-режим при отсутствии action), vacuum cleaning, script и известные рабочие состояния техники |

Цвет и размер кольца можно изменить для конкретного маркера. Если цвет не задан, RGB-свет может передать кольцу свой текущий цвет.

### Четыре варианта «Отображение»

| Опция | Иконка | Подложка статуса | Активность | Значение |
|---|---:|---:|---:|---:|
| Значок + динамическая подложка | Да | Да | Нет | Отдельные компактные °/% и LQI возможны |
| Иконка + активность | Да | Да | Да | Отдельные компактные °/% и LQI возможны |
| Значение вместо иконки | Если значение получить нельзя или источник неоднозначен | Да | Нет | Температура/влажность либо числовое или текстовое состояние, отформатированное HA |
| Всегда статичный значок | Да | Всегда нейтральная тёмная | Нет | Нет |

В режиме «Значение вместо иконки» поддерживаются и числа, и локализованные HA
текстовые состояния. Если источник отсутствует, недоступен или неоднозначен,
карточка возвращается к иконке; предпросмотр объясняет причину. Длинный текст
сокращается многоточием, полный остаётся в подсказке и accessibility-описании.
LQI остаётся отдельным бейджем.

«Всегда статичный значок» — осознанное исключение из общей матрицы состояний.
Маркер не меняет подложку или иконку, не показывает тревогу, недоступность,
RGB-цвет, значение, температуру, влажность и LQI. Для пылесоса также скрываются
живой puck, след и подсветка убираемой комнаты, но сохранённая история не
удаляется. Hover/focus остаются такими же, как у других маркеров; клик, controls,
Glow и заливка «Свет» продолжают работать по фактическому состоянию и отдельным
настройкам устройства. Для привязок, способных сообщать о тревоге, редактор
показывает неблокирующее предупреждение перед сохранением этого режима.

Живой блок предпросмотра в настройках marker использует несохранённые поля
формы и текущее состояние HA. Он отдельно показывает интеграцию привязки и
фактическую сущность отображения. Для «Иконка + активность» можно безопасно
запустить локальный пример кольца на 3,3 секунды: состояние HA, конфигурация и
эффект marker на плане при этом не меняются.

### Смена иконки по состоянию

При включённых живых состояниях автоматически меняются известные пары:

- дверь/окно/гараж — закрыто/открыто;
- шторы, жалюзи, ставни, ворота и другие cover — закрыто/открыто;
- замок — locked/unlocked;
- стандартная лампочка — off/on.

Ручная иконка обычно не меняется. Для `cover.*` известная пара может меняться даже при ручном выборе, чтобы открытое состояние не потерялось.

### Матрица по типам устройств

| Тип сущности/устройства | Устойчивый статус | Активность «Иконка + активность» | Смена иконки | Короткий клик по умолчанию |
|---|---|---|---|---|
| `light.*` | Жёлтый, пока `on` | Работа, пока `on` | Стандартная лампочка off/on | Toggle |
| `switch.*`, `fan.*`, `humidifier.*` | Жёлтый, пока `on` | Работа, пока `on` | Обычно нет | Внутренняя карточка, если Toggle не выбран явно |
| Составное switch-only устройство с отдельной сущностью Power | Нейтральное при Power=`on`; приглушённое при Power=`off`/`unknown`/`unavailable` | Нет: соседние переключатели режимов и функций не считаются работой всего устройства | Обычно нет | Внутренняя карточка |
| Motion/vibration/sound binary sensor | Нейтральный | Событие около 3.3 с при переходе off→on | Нет | Внутренняя карточка |
| Occupancy/presence binary sensor | Нейтральный | Пока присутствие активно | Нет | Внутренняя карточка |
| Door/window/garage contact | Оранжевый, пока `on` | Короткое событие при открытии | Закрыто/открыто для известных классов | Внутренняя карточка |
| `cover.*` штор/жалюзи | Нейтральный | Переход во время opening/closing либо короткий fallback | Закрыто/открыто | Внутренняя карточка; Open/close выбирается явно |
| `cover.*` garage/door/gate | Нейтральный | Переход во время движения | Закрыто/открыто | Только карточка; Open/close намеренно не предлагается |
| `lock.*` | Оранжевый при unlocked/open | Переход при locking/unlocking | Замкнут/открыт | Карточка; Toggle запрещён |
| `valve.*` | Оранжевый при open/opening/closing | Переход при opening/closing | Обычно нет | Карточка; Toggle можно выбрать явно |
| `climate.*` | Жёлтый при реальном heating/cooling/working; если интеграция не отдаёт action — пока включён HVAC-режим | Работа по `hvac_action`/аналогичному атрибуту, иначе по режиму из `hvac_modes` | Нет | Внутренняя карточка |
| `media_player.*` | Нейтральный при любом включённом/транспортном состоянии; приглушённый при `off`, как при `unknown`/`unavailable` | Нет: `playing`, вспомогательная подсветка и служебные переключатели не считаются работой | Нет | Внутренняя карточка |
| `vacuum.*` | Жёлтый при cleaning и returning | Работа при cleaning, переход при returning | Нет | Внутренняя карточка; движущийся puck открывает HA more-info |
| `script.*` | Жёлтый, пока `on` | Работа, пока выполняется | Нет | Внутренняя карточка или явный Run |
| `automation.*` | Нейтральный даже при `on` | Короткое событие после явного Run из плана | Нет | Внутренняя карточка или явный Run |
| `button.*` / `event.*` | Нейтральный | Короткое событие при изменении | Нет | Внутренняя карточка |
| Smoke/gas/CO/moisture/safety/tamper/problem, siren, triggered alarm | Красная авария | Кольцо не требуется: авария имеет высший приоритет | Зависит от базовой иконки | Карточка; опасный Toggle запрещён |
| Виртуальный маркер | Нейтральный | Нет без HA-источника | Нет | Внутренняя карточка или явный Run |

## 13. Заливки комнат и свет

### Режимы заливки пространства

| Режим | Источник | Цвет/поведение | Нет данных |
|---|---|---|---|
| Световые источники | Включённые лампы и отмеченные реле | Дом затемняется, вокруг источников рисуются световые пятна | Остаётся базовая темнота |
| Нет | — | Прозрачная комната/только граница | — |
| Zigbee signal | Средний LQI устройств HA-зоны | Градиент от красного (≤40) до зелёного (≥180) | Без заливки |
| Свет | Единый набор видимых источников комнаты: внешние `controls` + собственный источник по флагу «Это источник света»; автоматические `light.*` — fallback | Цвет «включено», «всё выключено» или «нет источников» | Цвет «нет источников», если его прозрачность >0 |
| Температура | Источник комнаты или среднее датчиков | Холодно ниже минимума, комфорт между границами, жарко выше максимума | Без заливки |

Новая вручную созданная область по умолчанию предлагает «Световые источники». Старые планы без сохранённого режима остаются без заливки.

### Наследование

| Уровень | Что можно изменить |
|---|---|
| Общие настройки | Цвет и прозрачность всех состояний, радиус света, цвет стен |
| Пространство | Активный режим, температурные границы, показ LQI, фон |
| Комната | Наследовать или явно выбрать Нет/LQI/Свет/Температуру; отдельный Glow не выбирается |
| Устройство | Явно стать источником света, радиус свечения, цвет эффекта |

### Что считается светом

| Источник | Заливка «Свет» | Световое пятно Glow | Жёлтая подложка устройства |
|---|---:|---:|---:|
| Видимое `light.* = on` | Да | Да | Да |
| `switch.* = on`, обычный | Нет | Нет | Да |
| `switch.* = on` + «Это источник света» | Да | Да | Да |
| Управляемая группа `controls` | Да, по состояниям группы | Только у отдельных маркеров реальных источников; выключатель сам пятно не создаёт | Да, если работает любой источник |
| Скрытый маркер | Нет | Нет | Не рисуется |

Для всех четырёх потребителей — Glow, заливки «Свет», строки света в карточке
комнаты и группового toggle — набор вычисляется одинаково. Если заданы
`controls`, они описывают управляемые источники и состояние группы, но не
назначают координаты выключателя координатами лампы. Пятно Glow строится только
от отдельного маркера реального `light.*` либо от маркера с явным флагом «Это
источник света». Без явных настроек автоматически учитываются собственные
`light.*` устройства. Одна сущность не считается дважды; при наличии и
контроллера, и лампы физическая точка принадлежит лампе независимо от порядка
реестра. Собственная `switch.*`-сущность внутри старого `controls` игнорируется,
пока пользователь явно не включит флаг источника. Ручная привязка маркера к
комнате (`room_id`) точнее HA-зоны и работает в том числе для комнаты без HA Area.

В режиме Glow свет ограничивается внутренним контуром комнаты, проходит в комнаты через двери и свободно объединяет комнаты через виртуальные границы. Наружная дверь не выпускает свет за пределы дома. У толстых стен сектор двери дополнительно обрезается внутренним тоннелем и откосами.

Цвет пятна выбирается по приоритету: RGB-состояние лампы → цветовая температура → общий цвет света. Яркость влияет на интенсивность, но имеет минимальный визуальный порог 15%.

## 14. Редактор подложки

### Инструменты

| Инструмент | Создание | Редактирование |
|---|---|---|
| Выбрать | Клик выбирает объект | Drag перемещает; общая рамка масштабирует пропорционально и поворачивает; `Shift` разрешает разные оси; двойной клик открывает свойства; `Delete`/`Backspace` удаляет |
| Подложка | Доступна, если есть изображение | Drag перемещает изображение, угловые ручки масштабируют, верхняя поворачивает; `Shift` разрешает разные оси/свободный угол; двойной клик открывает числовые размеры и угол |
| Линия | Drag между двумя точками | Цвет, толщина и стиль «Сплошная / Пунктирная»; показываются длина и угол. Стиль меняется только в свойствах по двойному клику |
| Прямоугольник | Drag по диагонали; `Shift` фиксирует квадрат | Контур и независимая заливка с прозрачностью; показываются ширина × высота и площадь |
| Овал | Drag по габаритам; `Shift` фиксирует круг | Контур и независимая заливка с прозрачностью; показывается `R` либо `Rx × Ry` |
| Текст | Клик открывает диалог | Многострочный текст, переменные HA, цвет/прозрачность, физический размер и угол; масштаб и поворот ручками |
| Мебель | Выбор символа и клик по центру | Символ, размер, цвет, толщина, поворот; магнитится к стене |
| Стереть | Клик по объекту | После подтверждения удаляет объект; действие можно отменить через Undo |

Новые фигуры создаются не меньше половины клетки. После создания объект остаётся выбранным. Создание, движение и изменение размера всегда квантуются по сетке. При рисовании и перемещении действует лёгкий магнит к углам, серединам, центрам и рёбрам других объектов декора и комнат; устройства, проёмы и картинка-подложка не являются целями магнита.

Картинка подложки интерактивна только в своём инструменте. В остальных инструментах этого редактора она показана с непрозрачностью `0.5`, а в просмотре и других редакторах — `1.0`.

Цвет контура/текста/мебели и его прозрачность задаются общим компактным полем: нажмите на образец цвета, чтобы открыть выбор цвета и прозрачности. Толщина и размер текста хранятся физически и показываются в сантиметрах или дюймах. Для прямоугольника и овала заливка имеет собственные цвет и прозрачность. Большие размеры в свойствах показываются в метрах или футах.

Параметры нового объекта показываются в общей суб-панели над холстом только
для применимого инструмента. При выборе готового объекта эта же панель
показывает «Свойства» и «Удалить». Палитра мебели использует расширенный вариант
той же поверхности и также не меняет высоту или масштаб рабочей области.

Редактор подложки использует тот же именованный Undo/Redo на 50 команд, что и геометрия плана. `Esc` отменяет только незавершённое рисование или текущий drag/resize/поворот; после отпускания указателя используйте `Ctrl+Z`/`Cmd+Z`. Повтор — `Ctrl+Shift+Z` либо `Ctrl+Y`.

### Двойной клик в «Выбрать»

| Объект | Что открывается |
|---|---|
| Текст | Полный диалог текста и HA-переменных |
| Линия | Длина, угол, цвет/прозрачность и физическая толщина; концы также двигаются отдельными ручками |
| Прямоугольник/овал | Ширина, высота, угол, контур и независимая заливка с прозрачностью |
| Мебель | Символ, ширина, глубина, угол, цвет/прозрачность и физическая толщина контура |
| Картинка-подложка | Ширина, высота и угол (двойной клик в инструменте «Подложка») |

### Живой текст Home Assistant

Поле принимает обычный текст и любое количество ссылок в фигурных скобках до лимита 200 символов.

```text
На улице {sensor.outdoor_temperature}, влажность {sensor.outdoor_humidity}%
Котёл: {climate.boiler:hvac_action}
```

Поддерживаемые формы:

| Синтаксис | Значение |
|---|---|
| `{sensor.room_temperature}` | Состояние сущности, отформатированное Home Assistant |
| `{climate.living_room:current_temperature}` | Атрибут сущности |
| `{climate.living_room.current_temperature}` | Альтернативная форма атрибута |

Выбор сущности и затем состояния/атрибута вставляет токен в позицию курсора либо заменяет выделение. Токены можно вводить вручную, смешивать с любым текстом и добавлять несколько раз.

| Ситуация | Вывод |
|---|---|
| Сущность/атрибут отсутствует | `—` |
| Состояние `unknown`/`unavailable` | `—` |
| Массив | Элементы через запятую |
| Объект/dict | Не выводится |
| Некорректные скобки | Остаются обычным текстом |
| Очень длинное значение | Обрезается до 60 символов |

`Ctrl+Enter`/`Cmd+Enter` сохраняет подпись. Переносы строк сохраняются, автоматического переноса по ширине нет.

### Мебель

Библиотека содержит группы мебели, бытовой техники, сантехники и прочих символов. Размер можно задать в метрах или десятичных футах. При размещении рядом со стеной предмет:

- прижимается к ней и поворачивается параллельно;
- всегда прижимается к ближайшей стене в радиусе магнита, иначе размещается по сетке;
- с зажатым `Shift` пропускает стеновой магнит, но всё равно привязывается к декору, комнатам и сетке;
- угловыми ручками по умолчанию сохраняет пропорции, а с `Shift` меняет ширину и глубину независимо;
- поворачивается с шагом 5°, а с `Shift` — свободно.

## 15. Солнце и фон день/ночь

Для солнечных функций нужны `sun.sun` и направление севера на плане. Общие значения можно переопределить в конкретном пространстве.

### Настройка

1. В общих настройках выберите фон **Следует за солнцем** при необходимости.
2. Укажите север числом 0–359° или поверните стрелку компаса.
3. Включите **Солнечный свет через окна**.
4. Для отдельного этажа задайте локальный север/режим/включение либо оставьте наследование.

### Поведение

| Условие | Результат |
|---|---|
| Редактор открыт | Лучи не рисуются |
| Солнце ниже 3° | Лучей нет |
| Переход через 3° | Слой плавно появляется/исчезает за 2 секунды |
| Окно внутреннее | Луча нет |
| Окно не смотрит на солнце | Луча нет |
| Толстая внешняя стена | Луч начинается из внутренних углов тоннеля окна |
| «Скрыть проёмы» включено | Символ окна скрыт, луч продолжает работать |
| Белый план | По бокам луча есть тонкая 1px тёмная кромка для читаемости |
| Любая погода, включая дождь и снег | Погода не влияет на лучи |

Луч обрезается чистым контуром комнаты, имеет чёткие боковые границы и плавно растворяется по длине.

Фон день/ночь меняет оттенок вокруг плана по высоте солнца: нейтральный день, тёплый горизонт и тёмная ночь. Сам план ночью затемняется не более чем примерно на 10%. Обычные изменения плавные; после сна вкладки большой разрыв корректируется сразу.

Тени от других крыльев здания и внешних объектов не моделируются.

## 16. Роботы-пылесосы

Живая позиция доступна для маркера пылесоса, если одна из его сущностей отдаёт `vacuum_position` или `robot_position`. Поддерживаются распространённые соглашения Xiaomi Cloud Map Extractor, dreame-vacuum и Valetudo-подобных интеграций.

### Калибровка

| Режим | Требования | Результат |
|---|---|---|
| Автоматическая | В карте робота и плане совпадают минимум три названия комнат | Вычисляется аффинное преобразование и показывается ошибка совмещения |
| Ручная | Доступна карта/контуры робота | Полупрозрачную карту можно двигать, масштабировать, поворачивать на 90° и зеркалить |

Для каждого `map_id` хранится собственная калибровка, поэтому многоэтажный робот может работать с несколькими пространствами.

### Позиция и путь

| Настройка пути | Во время уборки | После уборки |
|---|---|---|
| Никогда | Нет пути | Нет пути |
| Во время уборки | Текущий путь | Не показывается |
| Всегда | Текущий путь | Последний завершённый путь |

- Позиция показывается, когда пылесос cleaning/returning/on и данные валидны.
- Клик по движущемуся значку открывает HA more-info пылесоса.
- Стационарный маркер док-станции/устройства остаётся отдельным.
- Путь хранится на сервере, переживает перезагрузку карточки и виден другим клиентам.
- Хранятся текущая и предыдущая уборка; сервер ограничивает сырой путь 2000 точками с прореживанием, клиентский живой буфер — 600 точками.
- Позиция старше 60 секунд визуально считается устаревшей.
- Разрыв данных более 10 секунд не соединяется ложной длинной линией.

## 17. Киоск-режим

```yaml
type: custom:houseplan-card
kiosk: true
cycle: 30
```

| Возможность | Поведение |
|---|---|
| Шапка карточки | Скрыта |
| Редакторы | Недоступны |
| Высота | 100dvh |
| Свайп | Листает пространства по кругу при масштабе 1:1 |
| Щипок/панорама | Масштабирует и двигает план |
| Двойной тап | Сбрасывает масштаб к 1:1 |
| Удержание пустого места 3 секунды | Открывает локальные размеры иконок и текста |
| `cycle` | Автоматически листает пространства; при взаимодействии пауза 60 секунд |

Размеры киоска хранятся локально в браузере конкретного экрана. Это позволяет одному планшету использовать крупные значки, не меняя другие клиенты.

House Plan скрывает только собственную шапку. Шапка Home Assistant скрывается средствами companion app или отдельным kiosk-плагином.

## 18. Статическая карточка пространства

`houseplan-space-card` показывает один план как неинтерактивную живую схему.
Маркеры используют те же состояния, значения, тревоги и эффекты, что полный
план, но не открывают подсказки или more-info. Единственный интерактивный
элемент — нижняя кнопка перехода.

```yaml
type: custom:houseplan-space-card
space: ground_floor
title: Первый этаж
show_button: true
button_label: Открыть полный план
button_target: /lovelace/house
icon_size: 2.5
live_states: true
show_temperature: true
show_signal: true
```

| Поле | По умолчанию | Назначение |
|---|---:|---|
| `space` | обязательно | ID пространства |
| `title` | название пространства | Заголовок |
| `show_button` | `true` | Показывать нижнюю кнопку |
| `button_label` | локализованный текст | Подпись кнопки |
| `button_target` | `/plan-doma` | Путь к полному плану; карточка добавляет `#space=<id>` |
| `icon_size` | базовый | Размер статических маркеров |
| `live_states` | `true` | Рабочие/открытые/недоступные состояния, смена иконок и активность; тревоги видны всегда |
| `show_temperature` | `true` | Компактные температура и влажность у подходящих устройств |
| `show_signal` | `true` | LQI у маркеров, если он доступен |

Устаревшее YAML-поле `aspect_ratio` в v1.59.1 фактически не используется и
больше не предлагается визуальным редактором. Холст квадратный, а размер
карточки определяется содержимым; старое поле можно безопасно удалить.

## 19. Обслуживание планов

Кнопка **Общие настройки → Оптимизировать планы** запускает явное обслуживание. Сначала показывается точный предпросмотр; данные не меняются до подтверждения.

### Что делает оптимизация

| Операция | Что меняется |
|---|---|
| Миграции модели | Старые, однозначно преобразуемые поля переводятся в текущий формат; для `entity:switch.*` собственный switch в старом `controls` становится флагом «Это источник света» (для `device:*` это делает сохранение настроек устройства, где доступен реестр HA) |
| Масштаб сетки | Некорректный старый `cell_cm` приводится к допустимому диапазону 0,1–1000 см |
| Комнаты | Вершины округляются к сетке |
| Декор и мебель | Положение и размеры округляются к сетке |
| Устройства и подписи комнат | Позиции округляются к сетке |
| Проёмы | Возвращаются на ближайшую стену, смещение вдоль стены округляется, угол исправляется |
| Стены | Одинаковые соседние участки толщины объединяются |
| Виртуальные стены | Соседние/перекрывающиеся участки объединяются и приводятся к общей границе |

Перед записью диалог показывает количество затрагиваемых элементов, максимальный сдвиг в сантиметрах и пространство с этим сдвигом.

### Что оптимизация сохраняет

- неизвестные поля новых версий;
- положение и масштаб изображения подложки;
- сохранённые виды/границы холста;
- неиспользуемые записи раскладки;
- файлы подложек и вложения.

### Риск и отмена

Старые и импортированные объекты между узлами будут привязаны к сетке. Новые редакторы такие координаты не создают. После оптимизации доступна одна серверная отмена, но только до следующего изменения плана. Новый edit делает резервную копию оптимизации устаревшей.

## 20. Хранение, совместная работа и резервные копии

### Где лежат данные

| Данные | Хранение |
|---|---|
| Пространства, комнаты, стены, проёмы, декор и настройки маркеров | HA storage `houseplan.config` |
| Позиции маркеров и комнатных карточек | HA storage `houseplan.layout` |
| Планы | `config/houseplan/plans` |
| Вложения устройств | `config/houseplan/files` |
| Путь пылесоса | Отдельное серверное storage House Plan |
| Кэш, текущий вид, локальный киоск-масштаб | `localStorage` конкретного браузера |

Обычная резервная копия Home Assistant, включающая каталог `config`, сохраняет конфигурацию и файлы House Plan. Перед крупной ручной переработкой плана всё равно разумно сделать свежую резервную копию HA.

### Несколько клиентов

- Конфигурация и позиции общие для всех карточек и пользователей.
- Точечные обновления позиций не должны перетирать одновременные движения других устройств.
- Изменения транслируются через WebSocket и появляются без перезагрузки.
- Масштаб просмотра, последнее открытое пространство и киоск-размеры локальны браузеру.
- Если открыт несохранённый диалог и Lovelace быстро пересобирает карточку, текущая версия пытается восстановить черновик в течение короткого окна.

### Файлы и квоты

| Объект | Форматы | Лимит одного файла | Общий лимит |
|---|---|---:|---:|
| План | SVG, PNG, JPG, WebP | 8 МБ | 200 файлов / 256 МБ; в селекторе показываются 60 последних |
| Вложение устройства | PDF, PNG, JPG/JPEG, WebP, TXT | 50 МБ | 1000 файлов / 1 ГБ; до 50 ссылок на маркер |

Запись также отклоняется, если на разделе HA остаётся меньше 512 МБ свободного места. Файлы не удаляются только из-за возраста. Подложка, отсоединённая от пространства, остаётся на сервере до явного удаления. Незавершённые временные загрузки очищаются автоматически.

## 21. Ограничения текущей версии

| Ограничение | Практическое следствие |
|---|---|
| Только замкнутые комнаты | Нельзя оставить отдельную стену или незамкнутый контур |
| Незавершённый контур не сохраняется | Переключение режима/инструмента теряет текущие точки |
| Виртуальная стена только между комнатами | Нельзя открыть наружную стену или сделать ответвление из середины |
| Одна HA-зона на одну комнату | Нельзя автоматически разделить одну HA-зону на несколько комнат; используйте ручное назначение |
| Проёмы инертны в просмотре | Нельзя открыть их карточку кликом по полотну; только отдельный значок замка активен |
| Комнатные подсказки основаны на hover | На touch-экране без hover площадь доступна только косвенно/в редакторе Resize |
| Редакторы desktop-first | На touch-устройствах функции редактирования могут быть неудобны, ограничены или отсутствовать; для создания и обслуживания плана используйте компьютер |
| Солнце не знает внешнюю 3D-геометрию | Нет теней от соседних крыльев, навесов и деревьев |
| Иконки по регулярным выражениям | Правила мощные, но требуют знания regex; первая совпавшая строка побеждает |

Технические пределы защиты хранилища: до 50 пространств, 400 комнат на пространство, 2000 маркеров, 500 проёмов, 1000 элементов декора, 500 записей стен и 500 виртуальных участков на пространство. Конфигурационный пакет ограничен 2 МБ.

## 22. Диагностика

### Карточка не загрузилась

| Симптом | Проверка |
|---|---|
| `Custom element doesn't exist: houseplan-card` | Интеграция добавлена и загружена; ресурс — `/houseplan_files/houseplan-card.js`, тип `module`; очистите кэш фронтенда |
| MIME `text/plain` | Использован неверный файловый URL `/custom_components/...`; замените на `/houseplan_files/...` |
| Интеграция не находится | Папка называется точно `custom_components/houseplan`; HA перезапущен; журнал не содержит ошибки импорта |
| После обновления старая версия | Перезапустите HA, перезагрузите ресурсы/браузер; URL ресурса содержит версионный query, который интеграция обновляет сама |

### Устройства или значения не появились

| Симптом | Причина/действие |
|---|---|
| Устройство не на плане | Проверьте HA-зону комнаты; откройте **Скрытые и деактивированные**; если marker серый — активируйте устройство/сущность в HA; при необходимости добавьте маркер вручную |
| Устройство помечено деактивированным | Откройте его серый marker и нажмите «Открыть в HA». Если показано ограничение реестра, проверьте права текущего HA-пользователя или войдите администратором |
| Новая сущность не предлагается | В диалоге привязки включите **Показывать сущности** |
| Нет температуры climate | В маркере включите использование `current_temperature` |
| Нет значения в value-режиме | Основное состояние нечисловое; используйте иконку или живой текст подложки |
| Нет LQI | Сущности устройства не отдают известный атрибут качества; проверьте локальную настройку пространства |
| Реле не светит в Glow | Включите «Это источник света». `controls` управляет внешними лампами, но не переносит их Glow на координаты реле; реальные лампы должны иметь свои маркеры |
| Реле не влияет на заливку «Свет» | Включите «Это источник света», проверьте состояние основного `switch.*` и привязку маркера к нужной комнате |

### Геометрия выглядит неверно

| Симптом | Действие |
|---|---|
| Дверь/окно слегка не на стене | Перетащите в редакторе плана или запустите оптимизацию после просмотра отчёта |
| Появились мелкие отрезки стен | Закройте соседние виртуальные участки; оптимизация объединит одинаковые реальные/виртуальные фрагменты |
| Площадь отличается от внешнего контура | Для толстых стен это ожидаемо: показывается чистая внутренняя площадь |
| После оптимизации сдвинулся старый декор | Объект был сохранён старой версией или импортирован вне сетки; отмените оптимизацию до следующего edit и скорректируйте его на сетке |
| Лучей нет | Нужны `sun.sun`, север, включённые лучи, наружное окно, высота солнца ≥3° и подходящее направление |

### Пылесос не движется

1. Проверьте наличие `vacuum_position` или `robot_position` у выбранной сущности.
2. Убедитесь, что включена живая позиция и выбрана правильная сущность-источник.
3. Проверьте калибровку текущего `map_id`.
4. Убедитесь, что пылесос находится в состоянии cleaning/returning/on.
5. Если координаты обновляются рывками реже минуты, бледнение позиции может быть ожидаемым.

## Краткая памятка безопасности

- Не отключайте ограничение редактирования администраторами без необходимости: разрешение включает загрузку файлов и запись всего плана.
- Для потенциально опасных Toggle/Run/Cover включайте подтверждение.
- Замки открываются только через специальную карточку проёма с подтверждением; не обходите это ручной конфигурацией.
- Перед удалением пространства, массовым объединением комнат или оптимизацией сделайте резервную копию Home Assistant.
- Всегда читайте отчёт оптимизации: она исправляет все старые и импортированные координаты между узлами.