houseplan-card/docs/specs/377-decor-default-persist.md

ТЗ #377 — Персист цвета декора по умолчанию в серверный конфиг

• Issue: https://github.com/Matysh/houseplan-card/issues/377
• Приоритет: P3, polish; полный трек (компатибилити-поле settings.decor_default_style, кросс-модульный путь записи — критерий §5 «без новых персистентных полей» не проходит; выделено из #376в по SPEC-REVIEW-376-r1 H1)
• Ревизия: 2 (2026-08-29) — по SPEC-REVIEW-377-r1 (M1)
• Продуктовое решение владельца (29.08): цвет декора по умолчанию персистится в серверный конфиг.

Сценарий

Хозяин плана (персона «владелец дома», Background-редактор) подбирает под свой план фирменный цвет разметки — например, тёмно-красный для линий мебели-обводки — через пикер основного цвета в главном тулбаре (#360). Назавтра он открывает редактор снова, рисует новую линию — и она рисуется его тёмно-красным, а не заводским серо-синим. Тот же цвет видит второй редактор этого плана на другом устройстве.

Что человек увидит до и после

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

Проблема

_decorStyle — приватное in-memory поле карты (houseplan-card.ts:984, { ...DEFAULT_DECOR_STYLE }). Ни конфиг, ни браузерное хранилище не задействованы: перезагрузка страницы молча выбрасывает выбор пользователя. Название #360 («цвет по умолчанию») обещает большее.

Скоуп

• Новый опциональный ключ settings.decor_default_style в серверном конфиге.
• Чтение при инициализации; запись при изменении стиля из UI.
• Валидация на бэкенде; юниты обеих сторон; смок; доки; ченджлоги.

Не-скоуп

• Новые элементы UI (пикеры уже существуют, #360).
• Per-space или per-user стиль (ключ один, глобальный, как settings.bg_color).
• Персист прочих сессионных предпочтений редактора (инструмент, зум и т.п.).
• Экспорт/импорт: ключ едет внутри settings штатно, отдельной обработки нет.

Контракт поведения

1. Ключ отсутствует → поведение сегодняшнее: _decorStyle = DEFAULT_DECOR_STYLE.
2. Ключ присутствует → _decorStyle = мердж ключа поверх DEFAULT_DECOR_STYLE (неизвестные/отсутствующие поля берутся из дефолта; лишние поля игнорируются).
3. Изменение любого поля стиля из UI (пикер тулбара или контекстный трей — оба уже пишут в один _decorStyle) планирует запись settings с дебаунсом 1000 мс от последнего изменения: драг по палитре даёт одну запись.
4. Запись идёт существующим сериализованным путём _writeConfig (houseplan-editor-runtime.ts:1764): expected_rev (#340), очередь записей, штатный conflict при гонке вкладок. Новый канал не создаётся.
5. Если текущий стиль равен DEFAULT_DECOR_STYLE по значению — ключ из settings удаляется (паттерн bg_color/fill_colors в _saveSettingsDialog: дефолт хранится отсутствием ключа).
6. Запись возможна только из editor-runtime; холодный View ключ читает, но никогда не пишет (класс #357 не задевается).
7. Формат ключа настроек — snake_case; фронтовый DecorStyle (src/editors/decor/types.ts:78) — camelCase. Явный маппинг (принято предположительно, по паттерну ручной конвертации widthCm → width_cm в src/editors/decor/geometry.ts:144): color↔color, opacity↔opacity, width_cm↔widthCm, fill↔fill, fill_color↔fillColor, fill_opacity↔fillOpacity. Все поля ключа опциональны; конвертация — единственная точка (одна пара функций toSettings/fromSettings), чтобы AC2 доказывал мердж всех шести полей.

UX

Видимых изменений нет. Единственная новая наблюдаемая вещь — сохранённый цвет после перезагрузки. Ошибка записи показывается существующим тостом конфликта ревизий (#340), нового текста нет.

Модель данных и миграция

• custom_components/houseplan/validation.py, settings-схема (~:1883): vol.Optional("decor_default_style"): vol.Schema({vol.Optional("color"): _COLOR, vol.Optional("opacity"): 0..1, vol.Optional("width_cm"): vol.All(vol.Coerce(float), vol.Range(min=0.1, max=100)), vol.Optional("fill"): bool, vol.Optional("fill_color"): _COLOR, vol.Optional("fill_opacity"): 0..1}).
• Миграции нет: ключ опционален, старые конфиги валидны без него, старый бэкенд при откате терпит лишний ключ (settings-схема — ALLOW_EXTRA, проверено SPEC-REVIEW-376-r1).
• import_export.py: settings переносится целиком — отдельной правки нет, но юнит это доказывает (AC6).

i18n

Новых строк нет. Проверка — существующий паритет-гейт словарей.

Критерии приёмки

• AC1 (юнит бэкенда, pytest): settings с валидным decor_default_style проходит; каждое поле с мусором (цвет не-цвет, opacity 2, width_cm 0) режется ошибкой валидации.
• AC2 (юнит фронта): конфиг с ключом → _decorStyle = мердж поверх DEFAULT_DECOR_STYLE; частичный ключ (только color) наследует остальные поля дефолта.
• AC3 (юнит фронта): конфиг без ключа → DEFAULT_DECOR_STYLE (легаси).
• AC4 (смок): смена цвета в тулбаре → ровно одна запись config/set после дебаунса, несущая decor_default_style; серия быстрых изменений (драг) → по-прежнему одна запись; выставление стиля обратно в дефолт → запись БЕЗ ключа.
• AC5 (смок, продолжение AC4): пересоздание карты на конфиге из AC4 → новый нарисованный объект несёт сохранённый цвет.
• AC6 (юнит): экспорт→импорт конфига с ключом сохраняет ключ байт-в-байт.
• AC7 (гейт): полный гейт зелёный; бюджет ≈ без изменений; в холодном View (launchColdView) изменение недостижимо — записи нет (доказательство: смок AC4 работает только после входа в редактор).

План автотестов

• pytest: AC1 (валидация), AC6 (import/export) — в существующих файлах тестов валидации/импорта.
• node --test: AC2, AC3 (инициализация; файл тестов карты/декора).
• смок demo/smoke_decor_default_persist.mjs (новый): AC4+AC5 на моковом config/set; плюс негативная ветка AC7.
• Мутанты (mutation-gate): м1 — вырезать чтение ключа при инициализации → красный AC2/AC5; м2 — вырезать дебаунс (запись на каждый ввод) → красный AC4.

Риски

• Гонка двух вкладок: штатный conflict #340; дебаунс сужает окно. Риск низкий.
• Захламление settings при частой смене: дебаунс + удаление ключа при дефолте.
• Обратная совместимость: ключ опционален в обе стороны (см. «Модель данных»).

Откат

git revert реализационных коммитов. Уже записанный decor_default_style остаётся в конфиге и игнорируется старым фронтом; бэкенд после отката схемной правки терпит ключ через ALLOW_EXTRA (пока владелец не решит вычистить его следующим сохранением настроек — паттерн weather_entity). Потери данных нет.

Release-артефакты

• CHANGELOG.md + CHANGELOG.ru.md: user-visible запись со ссылкой #377.
• USER-GUIDE(.ru): одно предложение в разделе Background про сохранение выбранного стиля.
• docs/STYLING-HOOKS.md / ARCHITECTURE.md: не задеты (ключ не влияет на хуки).