houseplan-card/docs/design/505-summary-panel/reference/DEVELOPER-HANDOFF.md

# Dashboard 5 — передача в разработку

Дата пакета: 8 сентября 2026 года.  
Основание: [houseplan-card issue #437](https://github.com/Matysh/houseplan-card/issues/437) и согласованные уточнения встречи от 8 сентября 2026 года.

## Назначение

Dashboard 5 — интерактивный HTML-прототип конфигурируемой информационной панели рядом с планом House Plan. Пакет предназначен как визуальная и поведенческая основа для реализации внутри существующей Lovelace-карточки.

## Зафиксированное поведение

- Информационная панель плавает поверх плана и не участвует в геометрии, `content bbox` или автоматическом `fit`.
- В горизонтальной ориентации панель размещается справа.
- В портретной ориентации панель размещается снизу, центрируется и подстраивает ширину под содержимое с ограничением шириной экрана.
- Панель имеет собственный пользовательский заголовок.
- В шапке House Plan используется составной контрол: слева настройка, справа показ или скрытие панели.
- Правая кнопка использует `svg/layout-sidebar-right.svg`.
- Отдельного состояния сворачивания всей панели и сворачивания блоков нет.
- Значения в строках выровнены по правому краю.
- Панель и её содержимое ограничены по высоте; при переполнении прокручиваются данные, а не план.
- В режиме киоска панель располагается ниже плавающего блока управления.

## Структура данных

```text
информационная панель
└── блок
    └── значение: пользовательское название — источник/состояние
```

Предлагаемая модель:

```js
{
  title: "Сводная информация",
  showOnMobile: true,
  blocks: [
    {
      id: "stable-block-id",
      title: "Общее",
      visible: true,
      scope: { type: "all" },
      values: [
        {
          id: "stable-value-id",
          label: "Количество устройств",
          source: { type: "system", key: "device_count" }
        }
      ]
    }
  ]
}
```

Для блока, привязанного к пространству:

```js
scope: { type: "space", spaceId: "stable-space-id" }
```

Для сущности Home Assistant:

```js
source: { type: "entity", entityId: "sensor.example" }
```

## Начальная конфигурация

- Название панели: «Сводная информация».
- Один включённый блок «Общее» для всех пространств.
- Системные строки в порядке:
  1. «Количество устройств»;
  2. «Общая площадь комнат»;
  3. «Текущие дата и время».

## Диалог настроек

Диалог работает с единым черновиком. «Сохранить» применяет все изменения атомарно. «Отмена», крестик и Escape отбрасывают весь черновик.

Поддерживаются:

- название панели;
- общий показ панели;
- показ в нативном узком режиме Home Assistant;
- создание, переименование, включение, выключение и удаление блоков;
- выбор области блока: все пространства или одно определённое;
- создание, переименование, сортировка и удаление строк;
- сортировка блоков и строк перетаскиванием и квадратными кнопками «выше/ниже»;
- выбор сущности по имени и `entity_id`;
- состояния загрузки, устаревания и недоступности;
- проверка обязательных полей и блокировка сохранения при ошибках;
- подтверждение удаления непустого блока.

Ограничения структуры: не более 10 блоков, не более 20 значений в блоке, заголовок панели или блока до 48 символов, название значения до 64 символов.

## Интеграция с Home Assistant

Прототип содержит демонстрационный список сущностей. В продукте необходимо:

1. Получать полный доступный пользователю список из `hass.states`.
2. Использовать стабильный `entity_id` и форматирование состояния средствами Home Assistant.
3. Показывать системные показатели в том же селекторе источников, что и сущности.
4. Автоматически включать в список новые Template-сущности.
5. Сохранять ранее выбранную недоступную сущность и отмечать её как требующую внимания.
6. Получать мобильный/узкий режим из нативного контекста Home Assistant, а не из собственного числового breakpoint.
7. Интегрировать конфигурацию с постоянным хранилищем House Plan, совместной работой и экспортом/импортом, не добавляя данные панели в геометрию плана.
8. Следовать действующей модели прав House Plan для доступа к структурным настройкам.

## Файлы прототипа

- `index.html` — экран House Plan, панель и диалоги.
- `dashboard-5.js` — состояние, черновик настроек, фильтрация по пространству и адаптивная позиция.
- `dashboard-5.css` — компоновка, темы, киоск и анимации.
- `styles.css`, `components.css`, `components.html` — базовая демонстрационная оболочка.
- `svg/` — локальные иконки интерфейса.

## Проверки перед реализацией

- Обычный и нативный узкий режим Home Assistant.
- Альбомная и портретная ориентации телефона и планшета.
- Панель справа и снизу, короткий и максимальный состав.
- Светлая и тёмная темы, 200% zoom и safe area.
- Клавиатурная навигация, Escape, фокус после сортировки.
- Pan/pinch/scroll плана при открытой панели.
- Переход между пространствами без `fit/refit` и скачка масштаба.
- Загрузка, отсутствие данных, `unknown`, `unavailable`, восстановленная и удалённая сущность.
- Удалённое пространство, сохранённая проблемная привязка и смена активного пространства.
- Перезагрузка страницы, совместное редактирование, импорт и экспорт конфигурации.

## Запуск прототипа

Из папки `Dashboard 5`:

```text
python -m http.server 8768
```

Открыть `http://127.0.0.1:8768/`.

## Граница ответственности прототипа

HTML-прототип демонстрирует интерфейс и взаимодействия. Статические системные числа, демонстрационный массив сущностей и `localStorage` не являются готовой продуктовой реализацией. Источники данных, постоянное хранение, права, i18n и интеграционные тесты реализуются в кодовой базе House Plan.