houseplan-card/docs/specs/443-vacuum-route-polish.md

ТЗ #443 — Полиш маршрутов карт робота

• Issue: https://github.com/Matysh/houseplan-card/issues/443
• Приоритет: P3, bug / polish / vacuum
• Статус ТЗ: готово к ревью
• Маршрут: full; меняются frontend и backend semantics, single-space export, локализованный Device editor и performance-sensitive render snapshot
• Связанные контракты: #162 (маршрутизация карт по пространствам), #441 (атомарное добавление новой карты робота)

Сценарий

Home admin удаляет у робота последний явный маршрут карты, редактирует старую конфигурацию с маршрутами в удалённые пространства либо показывает большой многоэтажный план с сотнями устройств. Пустой список маршрутов должен означать осознанное отсутствие маршрутов, строки с потерянным пространством должны быть понятно собраны, а View не должен повторно просматривать все не относящиеся к роботам устройства ради vacuum overlay.

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

До: map_routes: [] может снова включить оставшийся legacy calibration и показать робота/карту там, откуда пользователь удалил маршрут. При экспорте одного пространства отфильтрованный до пустоты список может превратиться в null и создать тот же эффект после импорта. Маршруты в удалённые пространства помечены построчно и оказываются в конце, но визуально не образуют явную группу. Каждый render vacuum layer ещё раз перебирает все устройства плана.

После: любой массив map_routes, включая пустой, является явной authority; legacy fallback действует только при отсутствующем или null поле. Экспорт не теряет осознанную пустоту. Потерянные маршруты собраны в локализованную группу «Пространство удалено», остаются редактируемыми и имеют стабильный порядок. Vacuum renderer получает сохранённый в snapshot список только роботов, сохраняя межэтажные маршруты и визуальное поведение.

Подтверждённая проблема

1. src/vacuum-routes.ts::effectiveRoutes() и custom_components/houseplan/vacuum_routes.py::effective_routes() выбирают explicit routes только при непустом массиве/списке. Это противоречит #162 §7.3 и docs/VACUUM.md: наличие map_routes как массива уже означает единственную route authority.
2. Single-space export в custom_components/houseplan/import_export.py записывает kept_routes or None. Когда все маршруты отфильтрованы, явная пустота теряется, а оставшийся в marker legacy calibration может ожить при последующем чтении.
3. Заявленная в issue случайная перестановка missing-space строк по коду не подтверждается: comparator уже детерминирован по space order, map_id и source, а schema запрещает повтор пары source/map. Подтверждён UX-недочёт: строки лишь неявно идут в конце и не имеют отдельной группы.
4. _captureRenderDeviceSnapshot() уже обходит все устройства и рассчитывает vacuum facts. Затем _renderVacuums(this._renderDevices, ...) повторно перебирает весь device roster, хотя vacuum renderer нужны только роботы.

Скоуп

В скоупе:

• единая frontend/backend семантика absent, null, пустого и непустого map_routes;
• сохранение явного пустого массива при single-space export;
• явная локализованная группа строк, чьё space_id больше не существует;
• стабильный порядок валидных и потерянных маршрутов;
• vacuum-only subset в immutable render snapshot и его использование слоем vacuum overlay;
• сохранение межэтажного отображения робота, hidden/static правил и continuity при временном отсутствии нового snapshot;
• unit, backend, browser smoke, mutation и performance evidence;
• актуализация документации и обоих changelog.

Не-скоуп

• новый каталог vacuum integrations, обнаружение карт или изменение протокола источников;
• изменение route identity, калибровки, puck/trail/room outline либо команд уборки;
• автоматический выбор нового пространства для потерянного маршрута;
• автоматическое удаление missing-space route;
• миграция или eager rewrite сохранённых legacy markers;
• изменение семантики malformed non-array map_routes;
• оптимизация остальных проходов по device roster и полный рефактор render snapshot;
• изменение удаления пространства за пределами экспортного edge case;
• изменение static space-card UX или редакторов вне vacuum maps section.

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

1. Authority map_routes

Frontend и backend используют одну таблицу решений:

Состояние marker	Эффективные маршруты
поле map_routes отсутствует	legacy fallback из calibration, как сейчас
map_routes: null	legacy fallback из calibration, как сейчас
map_routes: []	пустой explicit result; legacy полностью игнорируется
map_routes: [ ... ]	только нормализованные explicit routes; legacy игнорируется

Проверка должна зависеть от типа массива/списка, а не от его truthiness или длины. Пустой массив не создаёт overlay, trail, puck или route-space presentation из legacy calibration.

Malformed non-array значения остаются на прежнем compatibility path; #443 не расширяет schema и не пытается молча исправлять неизвестные будущие формы. Никакой фоновой записи конфигурации при чтении не выполняется.

2. Single-space export

Если исходный vacuum marker содержит массив map_routes, export одного пространства сохраняет map_routes массивом даже тогда, когда фильтрация не оставила ни одного route. Результат в этом случае — [], а не null, отсутствующее поле или возврат legacy calibration.

Если исходное поле отсутствовало или было null, действующее legacy-compatible поведение не меняется. Экспорт не создаёт synthetic routes и не удаляет legacy-поля из source marker: безопасность обеспечивается сохранённой explicit empty authority.

3. Группировка потерянных пространств

Device editor показывает маршруты в следующем порядке:

1. маршруты существующих пространств — по текущему порядку spaces, затем по map_id, source и route id как детерминированному tie-breaker;
2. отдельная группа потерянных маршрутов после всех валидных групп — по map_id, source и route id.

Группа имеет видимый локализованный заголовок с семантикой «Пространство удалено». Рекомендуемые строки:

• ru: «Пространство удалено»;
• en: “Deleted space”;
• de: “Gelöschter Bereich”;
• fr: “Espace supprimé”.

Существующая построчная индикация missing-space и общий warning сохраняются: заголовок помогает сканировать список, но не является единственным объяснением ошибки. Каждая строка по-прежнему доступна для выбора, редактирования и удаления; House Plan не угадывает замену пространства. Pending draft добавления маршрута не смешивается с группой и сохраняет контракт #441.

Если потерянных маршрутов нет, заголовок и дополнительная группа не рендерятся. Порядок валидных строк визуально не меняется.

4. Vacuum-only render snapshot

Capture одного device snapshot формирует immutable vacuum-only subset из той же согласованной копии device roster, на которой рассчитаны facts. Vacuum renderer в обычном View перебирает этот subset, а не полный список устройств.

Subset обязан содержать всех роботов плана, а не только устройства текущего пространства. Поэтому сохраняются:

• показ робота на route-space другого этажа относительно пространства базы;
• выбор map route и route facts из того же snapshot;
• suppression скрытых и static devices;
• отсутствие повторного resolve route authority внутри renderer;
• snapshot continuity: незавершённый новый capture не смешивает старые devices с новыми facts.

Fallback полного списка допустим только на существующем snapshot-less инициализационном/тестовом пути и не должен становиться обычным render path. Изменение сокращает повторный render scan с O(N) до O(V), где N — все device markers, а V — vacuum markers; capture остаётся O(N) и не обязан ускоряться в этой задаче.

Данные и совместимость

• Schema version и persisted shape не меняются; миграции нет.
• Старые конфигурации без map_routes и с map_routes: null продолжают читать legacy calibration.
• Уже сохранённый map_routes: [] меняет только ошибочную read semantics и перестаёт оживлять legacy routes.
• Frontend и backend обязаны дать одинаковый результат на четырёх состояниях таблицы authority.
• Atomic add/dedup/rollback из #441 не меняются.

Touch, клавиатура и доступность

Новых жестов и targets нет. Группа missing-space получает обычный неинтерактивный текстовый заголовок и структурную связь со следующими строками; состояние не передаётся только цветом. Tab order, действия строк, focus restore и touch targets остаются прежними. Новая строка проходит en/ru/de/fr completeness и locale smoke.

Ошибки, гонки и крайние случаи

Случай	Ожидаемое поведение
map_routes: [] и непустой legacy calibration	0 effective routes, legacy не читается
map_routes: null и legacy calibration	прежний legacy route
все routes отфильтрованы single-space export	в export остаётся map_routes: []
один valid и несколько missing routes	valid group первая, затем одна missing-space group со стабильными строками
отсутствуют все пространства routes	после draft area показывается только missing-space group; строки редактируемы
несколько роботов на разных этажах	subset содержит всех; каждый показывается только по своим route facts
roster меняется между HA updates	кадр использует одну immutable snapshot revision без смешения
нет captured snapshot	существующий fallback не падает и не фильтрует робота по dock space
malformed non-array map_routes	прежнее compatibility/fail-closed поведение без новой миграции

Acceptance criteria и доказательства

AC1. Единая route authority

TS unit проверяет absent, null, [] и non-empty map_routes при наличии legacy calibration. Пустой массив даёт ноль routes; непустой — только explicit; absent/null сохраняют legacy.

AC2. Backend parity

Python unit прогоняет ту же матрицу и сверяет нормализованные результаты с frontend contract. Как минимум один отрицательный кейс обязан падать при возврате старого условия «список непуст».

AC3. Export не оживляет legacy

Backend import/export test экспортирует одно пространство из marker с explicit routes, полностью удалёнными фильтром, и оставшимся legacy calibration. Результат содержит map_routes: []; повторное вычисление effective routes после round-trip даёт пустоту.

AC4. Понятная и стабильная группа

Browser smoke открывает Device editor с valid и несколькими missing routes, проверяет порядок групп/строк, единственный локализованный заголовок, warning и доступность edit/delete. Повторный render и перестановка входного словаря spaces при том же canonical order не меняют порядок. Pending draft остаётся отдельно.

AC5. Renderer получает только роботов

Unit/contract test создаёт roster с не-vacuum и vacuum markers и проверяет, что captured subset immutable, содержит только всех vacuum markers и используется обычным _renderVacuums call site. Renderer не выполняет второй полный scan.

AC6. Межэтажное и snapshot-поведение сохранено

Существующий multifloor vacuum smoke и cold/live continuity test остаются зелёными: робот с базой на другом этаже отображается в route-space, hidden и static suppression прежние, старые devices не смешиваются с новыми facts. Mutation, возвращающий current-space devs в vacuum renderer, обязан уронить межэтажный witness.

AC7. Производительность не ухудшена

Large-house профиль 60 rooms / 200 devices на exact SHA проходит действующий performance smoke и budget. Дополнительный structural witness фиксирует V < N и один vacuum-only render pass; отдельный новый timing budget не вводится, поскольку изменение сокращает сложность и не добавляет visual work.

AC8. Совместимость и документация

Typecheck, unit и build зелёные. Перед бетой проходят golden, smoke и performance по канону процесса; Linux CI является каноном полного HA harness. docs/VACUUM.md явно называет пустой массив authority, оба changelog описывают пользовательское исправление, en/ru/de/fr dictionaries проходят completeness.

План тестирования

• расширить TS unit для effectiveRoutes() таблицей всех состояний поля;
• расширить backend unit vacuum_routes и import/export round-trip;
• добавить/расширить browser smoke vacuum route editor для missing-space group;
• расширить render snapshot unit/contract vacuum-only subset;
• сохранить и прогнать multifloor/cold-view vacuum smokes;
• обновить scripts/mutation-gate.mjs: explicit-empty mutant возвращает старую проверку длины и краснеет; cross-floor mutant подменяет vacuum subset на current-space devices и краснеет;
• в implementation loop запускать только typecheck, unit, build; golden, smoke и performance запускать перед бетой согласно runbook.

Карта реализации

• src/vacuum-routes.ts — array presence вместо non-empty selection;
• custom_components/houseplan/vacuum_routes.py — backend parity;
• custom_components/houseplan/import_export.py — сохранение explicit empty;
• src/editors/vacuum-maps-section.ts — partitions/groups и stable tie-breaker;
• src/i18n/support/{en,ru,de,fr}.json — заголовок missing-space group;
• src/render-device-snapshot.ts и src/houseplan-card.ts — immutable vacuum-only subset и renderer call site;
• test/, tests_backend/, demo/, scripts/mutation-gate.mjs — witnesses;
• docs/VACUUM.md, docs/CONFIG-COMPATIBILITY.md, docs/USER-GUIDE.ru.md, docs/CHANGELOG.md, docs/CHANGELOG.ru.md — release artifacts.

Риски и rollback

• Главный compatibility risk — ошибочно отключить legacy fallback для absent или null; его закрывает одинаковая четырёхстрочная матрица в TS и Python.
• Главный render risk — отфильтровать робота по текущему пространству/этажу; subset строится глобально, а cross-floor mutant обязан краснеть.
• Главный snapshot risk — создать subset из другого поколения devices; список формируется и замораживается вместе с основной snapshot revision.
• UI-группа может нарушить focus/order; smoke проверяет интерактивные строки, а заголовок остаётся неинтерактивным.
• Rollback code path не требует data rollback: schema не меняется. Возврат implementation не переписывает сохранённые конфигурации.

Release-артефакты

• Обязательны записи в docs/CHANGELOG.md и docs/CHANGELOG.ru.md в том же user-visible коммите.
• Обновляется docs/VACUUM.md для явного empty-array/export контракта.
• Обновляется docs/CONFIG-COMPATIBILITY.md: раздел vacuum map routes явно различает absent, null, explicit empty и non-empty map_routes, включая сохранение [] при single-space export.
• Обновляется docs/USER-GUIDE.ru.md: раздел «Карты и этажи» описывает новую видимую группу маршрутов «Пространство удалено» в Device editor.
• Изменение Device editor требует browser screenshot/smoke evidence в light/dark темах; новый постоянный golden добавляется только если этот экран уже входит в canonical golden surface, иначе review artifact прикладывается к issue без расширения baseline.
• Перед бетой обязательны штатные golden, smoke и full performance artifacts; новый security artifact не требуется.

Принятые предположения

• Явный массив map_routes является authority независимо от длины — это уже принятое решение #162, а не новый вопрос.
• Требование issue «явная группа» означает отдельный локализованный заголовок после всех валидных пространств; действия строк не меняются.
• Исправление производительности ограничено устранением второго полного обхода: отдельный новый latency threshold без подтверждённой деградации не нужен.
• map_routes: null остаётся legacy-compatible, чтобы не создавать скрытую миграцию старых конфигураций.