houseplan-card/docs/specs/010-vacuum-roomba-live-position.md

ТЗ #10 — Roomba string pose: полный Stage 2

• Issue: https://github.com/Matysh/houseplan-card/issues/10
• Приоритет: P2
• Статус ТЗ: draft, UX-решение предложено ниже
• Зависимость: HP-VAC-02 Stage 1/#58 должен быть стабилен

Цель

Для pose-capable Roomba отобразить live puck и server trail из vacuum entity без camera/rooms, не обещая координаты моделям, которые их не предоставляют.

Shared parser

Каноническая grammar для attributes.position:

1. только string;
2. trim whitespace;
3. удалить не более одной внешней пары (...), если обе скобки присутствуют;
4. split , ровно на три token;
5. trim → Number, все три finite;
6. результат {x,y,theta}, иначе null без исключения.

Одинаковый JSON corpus используется src/vacuum.ts и trails.py. Corpus: valid whitespace/sign/exponent/zero; missing/extra token; partial parens; empty/NaN/Infinity/hex/locale comma/object. Backend parser обязателен, потому что trail записывается при закрытой карточке.

Source arbitration

• Position-capable camera того же device всегда выше Roomba string pose.
• Явно pinned camera остаётся sticky даже missing; string не делает silent fallback вокруг сохранённого выбора.
• В automatic mode string source допустим только у primary vacuum.* того же marker и только при валидном pose.
• position:null/invalid → Tier D: dock marker и обычное управление, без puck, trail и calibration error.

Калибровка без комнат — рекомендуемый two-mark flow

1. Пользователь запускает/ставит робота в точку A, нажимает «Зафиксировать A» и кликает соответствующую точку плана.
2. Робот физически перемещается минимум на configurable raw-distance; аналогично фиксируются B и plan B.
3. По двум векторам решается uniform scale + rotation + translation.
4. Mirror не выводится из двух точек, поэтому preview имеет явный toggle «Отразить ось Y», default off. Theta preview помогает выбрать вариант.
5. Совпадающие/слишком близкие raw или plan points блокируют Apply.
6. Matrix остаётся proposal до Apply; Cancel не меняет config.

Калибровка хранится в существующем marker.vacuum.calibration[mapId]; map id для string pose — stable roomba-default, пока интеграция не даёт иной доказанный идентификатор.

Runtime и backend trail

Theta преобразуется с rotation/mirror matrix и нормализуется для puck. Recorder читает position из vacuum state, применяет существующие teleport/stale/run правила и пишет тот же trail format. HA restart mid-run продолжает current run.

Field protocol и проверки

• две отдельные уборки, разнесённые точки, повороты и возврат на dock;
• restart HA mid-run; стабильность origin/scale и отсутствие ложного previous;
• parser parity fixture TS/Python;
• source priority camera/string/pinned missing;
• calibration Cancel/Apply/mirror/degenerate;
• модель без pose и временный null;
• beta release только после реального pose-capable Roomba protocol.

Приёмка

Live puck и trail совпадают с физическим движением после two-mark fit; камера не уступает string source; сервер пишет путь без открытой карточки; неподдержанная Roomba деградирует без ошибок и ложных координат.