houseplan-card/docs/USER-GUIDE.ru.md

# 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 | Ручку стены или комнату | Двигает стену с общей геометрией; по клику на комнату даёт угловую рамку масштабирования |
| Проём | Сначала тип в подменю, затем точку на стене | Создаёт окно 120 см, дверь 90 см или ворота 300 см; клик существующего проёма открывает его настройки |
| Граница | Две точки общей стены или существующий пунктир | Два клика делают участок общей стены виртуальным; один клик по пунктиру целиком восстанавливает физическую стену |
| Толщина | Реальный участок стены | Задаёт толщину выбранному участку или всем стенам комнаты |
| Удалить комнату | Точку внутри комнаты | После подтверждения удаляет только эту комнату; стены не запускают другие скрытые действия |

### 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 см.

В **Редакторе плана** кнопка **Проём** сама по себе ничего не размещает: она
открывает компактное подменю **Окно / Дверь / Ворота**. После выбора типа
наведите указатель на физическую стену. Полупрозрачный символ показывает точный
будущий вид, положение и сторону открывания; он виден поверх тела толстой стены.
Клик открывает свойства, а **Сохранить** создаёт объект. После сохранения или
отмены выбранный тип остаётся активным для серии одинаковых проёмов. `Esc`,
выбор другого инструмента, редактора или пространства завершает эту серию.

Наводить указатель перед кликом необязательно: клик по телу толстой стены сам
находит её ось и открывает тот же диалог. Виртуальная стена не принимает проёмы.
Если несколько стен сходятся в одной точке, House Plan выбирает одну физическую
секцию детерминированно; при необходимости поставьте проём чуть дальше от стыка.

Ворота по данным и поведению равны двери: могут иметь датчик открытия и замок, вырезают стену и пропускают 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, универсальное **Переключить состояние** или запуск сценария. Под селектором сразу показаны точная цель, текущее состояние и результат следующего нажатия либо причина, почему нажатие ничего не сделает |
| Управляет другими источниками света | Группа других `light.*`/`switch.*` и принудительных источников, уже размещённых на плане. Собственная entity и сущности привязанного устройства сюда не входят |
| Является источником света | **Авто** использует роль устройства, **Всегда** создаёт собственный источник даже без entity HA, **Никогда** исключает только собственный источник. Внешние `controls` продолжают учитываться в свете комнаты |
| Ведущая сущность | Появляется для роли **Всегда**, если у устройства несколько `light.*`/`switch.*`. Выбранная сущность определяет состояние и service call; исчезнувший выбор не стирается и временно заменяется безопасным fallback |
| Цвет и яркость свечения | **Из источника** использует живые данные HA; **Задать цвет** сохраняет живую яркость; **Задать цвет и яркость** фиксирует оба параметра (1–100%) |
| Использовать температуру climate | Добавляет `current_temperature` термостата/кондиционера в маркер и среднее комнаты |
| Скрыть / Показать | Кнопка в левом нижнем углу диалога. После сохранения убирает или возвращает значок; LQI скрытого устройства всё ещё может участвовать в среднем комнаты |
| Удалить | Кнопка рядом со «Скрыть». После подтверждения сразу полностью убирает устройство с плана и позволяет позднее добавить его заново |
| Радиус свечения | Локально переопределяет общий радиус, 0.1–100 м в хранилище |
| Иконка | Ручная `mdi:*`; пусто — автоматический подбор. Автовариант показывается в поле как значок с именем `mdi:*`, но не сохраняется как ручная замена |
| Отображение | Иконка, иконка + активность или значение вместо иконки. Ниже сразу видны фактический результат, источник и интеграция |
| Размер/поворот | Масштаб маркера и угол |
| Модель, ссылка, описание | Информация во внутренней карточке |
| Файлы | PDF, PNG, JPG/JPEG, WebP, TXT; несколько вложений |

### «Тупая» лампа с умным выключателем

1. Добавьте виртуальный маркер в реальной позиции лампы.
2. Выберите для него роль **Всегда**. Даже без сущности HA он станет пассивным
   источником; задайте цвет, яркость и радиус вручную. «Из источника» недоступно,
   потому что live-данных у такой лампы нет.
3. Откройте маркер умного выключателя. В **Управляет другими источниками света**
   найдите лампу в группе источников на плане и добавьте её.

После этого выключатель отображает агрегированное рабочее состояние, но пятно,
заливка и статистика принадлежат лампе и её комнате. Несколько выключателей
управляют одной лампой по OR. Если не связать пассивную лампу ни с одним
контроллером, явная роль **Всегда** означает постоянно включённый источник.
`marker:*` является только внутренней ссылкой плана и никогда не отправляется
в Home Assistant как entity ID.

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

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

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

- не рисуется в просмотре;
- в редакторе виден только при включённом **Скрытые и деактивированные**;
- не показывает цвет состояния, число, температуру, влажность и 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 | Открывается штатный диалог основной сущности | Состояние не меняется |
| Переключить состояние | Переключает точную привязанную сущность, функциональную сущность устройства либо явно настроенную группу `controls`. Для штор/жалюзи и клапанов автоматически выбирает open/close/stop | Замки, охранные панели и защитные `garage`/`door`/`gate` остаются безопасным no-op; можно включить подтверждение |
| Run | `automation.trigger`, `script.turn_on` или `scene.turn_on` | Цель выбирается явно; можно включить подтверждение |

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

Вариант **Переключить состояние** доступен для любого маркера, в том числе
виртуального. Выбор всегда сохраняется. Если у маркера нет переключаемой цели,
под настройкой прямо написано, что по нажатию ничего не произойдёт; House Plan
не подменяет такое действие открытием карточки. Привязка к одной HA-сущности
всегда точная: неподдерживаемый датчик не будет незаметно заменён соседним реле
того же устройства. Временно отсутствующие или деактивированные цели остаются
в конфигурации, но не получают service call.

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

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

## 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 при изменении; ручной запуск сценария из карточки; мгновенный terminal-переход без travelling state |
| Постоянная: присутствие | Пока состояние активно | Binary sensor с классом occupancy/presence |
| Постоянная: переход | Пока идёт движение | 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 остаётся отдельным бейджем.

### Бейдж со значением рядом с устройством

В настройках устройства над предпросмотром можно включить отдельный бейдж,
выбрать его значение и положение: справа, снизу, слева или сверху. В список
попадают состояния сущностей этого устройства, полезные атрибуты (например,
текущая температура, яркость, заряд, положение или громкость), средний LQI и
состояния связанных источников света. Изменения сразу видны в предпросмотре.

Это независимый элемент: он может показываться и рядом с обычной иконкой, и
рядом с режимом «Значение вместо иконки». Если бейдж расположен снизу, системный
LQI автоматически становится второй строкой; если сам бейдж показывает LQI,
дублирующая строка скрывается. Недоступный сохранённый источник не заменяется
другим молча — отображается `—`, а редактор позволяет сохранить связь или
выбрать новую.

Для старых маркеров без этой настройки прежние автоматические °/% сохраняются.
Явно выключенный бейдж подавляет эту legacy-эвристику. Явный бейдж не зависит
от общей настройки показа температуры; «Всегда статичный значок» временно
скрывает его, не удаляя выбор. Настройка «Учитывать температуру устройства в
комнате» теперь отвечает только за среднее значение комнаты и не управляет
внешним бейджем.

«Всегда статичный значок» — осознанное исключение из общей матрицы состояний.
Маркер не меняет подложку или иконку, не показывает тревогу, недоступность,
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/stop |
| `cover.*` garage/door/gate | Нейтральный | Переход во время движения | Закрыто/открыто | **Переключить состояние** можно сохранить, но оно явно показывает защитный no-op и не выполняет service call |
| `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` + собственный источник по роли Авто/Всегда/Никогда | Цвет «включено», «всё выключено» или «нет источников» | Цвет «нет источников», если его прозрачность >0 |
| Температура | Источник комнаты или среднее датчиков | Холодно ниже минимума, комфорт между границами, жарко выше максимума | Без заливки |
| Свой цвет | Настройка пространства или комнаты | Постоянный цвет и прозрачность, не зависящие от HA | Безопасный серо-синий `#607d8b`, 18% |

«Свечение источников света» теперь включается отдельно и сочетается с любым
режимом заливки. При отсутствии данных, room-level режиме «Нет» или своём цвете
с нулевой прозрачностью оно добавляет базовое затемнение и световые пятна. При
видимой заливке по LQI, свету, температуре или своим цветом базовое затемнение
не рисуется: исходный цвет и прозрачность сохраняются точно, а световые пятна
остаются видимыми поверх неё. Новое вручную созданное пространство по
умолчанию имеет режим «Свой цвет» с прозрачностью 0% и включённое свечение:
пока пользователь не повысит прозрачность заливки, вид остаётся таким же, как
у прежнего режима «Нет». Старые планы с режимом
«Световые источники» читаются без визуальной потери и при следующем обычном
сохранении переводятся в независимые настройки. Старое space-level значение
«Нет» показывается как «Свой цвет» с прозрачностью 0% и сохраняется без
визуального изменения.

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

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

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

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

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

Ручная яркость Glow — не обычная прозрачность, а доля интенсивности источника.
Она проходит ту же перцептивную кривую, что и живой атрибут `brightness`: 100%
сохраняет прежний потолок эффекта, а малые значения остаются различимыми. Ноль
на шкале намеренно отсутствует; чтобы убрать собственное свечение маркера,
выберите роль «Никогда». Выключенный или недоступный источник не рисует пятно
даже при зафиксированной яркости.

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

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

Цвет пятна выбирается по приоритету: 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 (Tasshack) и Valetudo-подобные камеры. Roomba со
строковым атрибутом `position` в текущий этап не входит.

В настройках устройства блок «Живая позиция» показывает источник, интеграцию,
статус, наличие позиции, число комнат, путь и ID карты. По умолчанию источник
выбирается среди сущностей того же устройства независимо от порядка в реестре.
Если XCME-камера не относится к устройству, откройте «Выбрать источник» → «Все
камеры» и выберите её явно. Глобальные камеры никогда не выбираются
автоматически.

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

Для Xiaomi Cloud Map Extractor включите атрибуты `vacuum_position`, `rooms`,
`path` и `map_name`; точная YAML-подсказка показывается в самом диалоге.

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

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

Для каждого `map_id` хранится собственная калибровка, поэтому многоэтажный робот может работать с несколькими пространствами.
Если максимальное расхождение больше 40 см, настройки не меняются до выбора
«Применить». Можно вместо этого открыть ручную подгонку или отменить операцию.

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

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

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

## 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. Хранение, совместная работа и резервные копии

### Переносимая JSON-копия House Plan

Откройте **Общие настройки → Резервная копия и перенос**. Экспорт предлагает
два варианта:

- **Полная копия** — пространства, комнаты, стены, проёмы, декор, настройки
  устройств и все позиции. Её импорт заменяет текущую модель целиком; до
  следующего изменения плана доступна одна отмена.
- **Текущее пространство** — независимая копия выбранного пространства. При
  импорте оно получает новые внутренние ID и добавляется рядом с существующими;
  глобальные настройки не меняются и отмена не создаётся.

Файл сначала загружается в безопасный серверный предпросмотр: House Plan
показывает тип, версии, количество объектов, источник и состояние ссылок, но
ничего не записывает до подтверждения. Если привязка к устройству HA уже есть,
можно пропустить повтор или создать безвредную статичную виртуальную копию.

JSON хранит названия, идентификаторы HA и точные координаты. Подложки и вложения
в файл не вкладываются: внешние URL сохраняются, а внутренние ссылки работают
только на исходном экземпляре, где соответствующий файл ещё существует. При
переносе на другой экземпляр такие ссылки нужно явно согласиться отвязать.
Текущие состояния устройств и маршруты пылесосов в экспорт не входят.

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

| Данные | Хранение |
|---|---|
| Пространства, комнаты, стены, проёмы, декор и настройки маркеров | 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.
- Всегда читайте отчёт оптимизации: она исправляет все старые и импортированные координаты между узлами.