houseplan-card/docs/specs/220-space-tab-reorder.md

# Issue #220 — порядок пространств перетаскиванием вкладок

- **Issue:** https://github.com/Matysh/houseplan-card/issues/220
- **Связанные контракты:** #210 (фиксированный этаж), #170 (fallback-привязка маркера), #3 (комнаты без HA-зоны)
- **Тип:** feature, обычный полный трек
- **Приоритет:** P2
- **Пользовательское изменение:** да

## 1. Сценарий и персона

**Персона:** администратор плана — тот, кто заводит пространства и поддерживает
план в актуальном виде (`docs/SCOPE.md`, job J6).

**Сценарий:** дом рос не по порядку. Сначала завели «Квартиру», через месяц —
«Подвал», потом «Мансарду». Вкладки стоят в порядке создания, а читается дом
снизу вверх. Сегодня переставить их нечем: порядок вкладок — это порядок
массива `config.spaces`, и единственный способ его изменить — удалить
пространство и завести заново, потеряв планировку, устройства и привязки.

**Момент:** администратор в режиме редактора видит панель вкладок, берёт вкладку
мышью и перетаскивает на новое место.

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

**До:** вкладки стоят в порядке заведения; изменить порядок невозможно.

**После:** в режимах редактора вкладку можно взять мышью и перетащить; во время
перетаскивания видно, куда она встанет; после отпускания порядок сохраняется и
переживает перезагрузку. Свайп между этажами и стрелки киоска идут в новом
порядке. Во View и на сенсорных экранах ничего не меняется: там вкладка
по-прежнему только переключает пространство.

## 3. Подтверждённая причина

Порядок вкладок задан порядком массива: панель рендерится прямым проходом по
модели (`houseplan-card.ts:15717`), `navigationSpaces.map(...)`, отдельного поля
сортировки нет. Запись идёт штатным `_writeConfig` (`:6692`) через
`houseplan/config/set` с `expected_rev`; изменение порядка — обычная правка
массива, схема и миграции не нужны.

**Порядок массива несёт смысл в трёх местах.** Проверено по коду dev:

| Место | Код | Что зависит |
|---|---|---|
| Fallback-пространство маркера | `houseplan-card.ts:3350`, `:4273` → `devices.ts:1058`, `:1063`, `:1249` | `firstSpaceId = _model[0]?.id`: маркеры без явного пространства садятся в первое |
| Свайп и карусель | `logic.ts:1870-1879` | `spaceIds[(i + 1) % n]` — сосед по индексу |
| `floor` числом (#210) | `houseplan-card.ts:1165` `_fixedFloorState` | числовое значение разрешается как позиция, есть ветвь `out-of-range-index` |

Первое — риск потери данных на ровном месте, второе и третье обязаны следовать
новому порядку либо предупреждать.

## 4. Продуктовые решения владельца (2026-08-20)

1. **Перетаскивание — только мышь и только в режимах редактора** (`plan`,
   `devices`, `decor`). Во View и киоске поведение вкладок не меняется вовсе.
2. **Числовой `floor` из #210** — после успешной перестановки показать
   предупреждение один раз.
3. **Клавиатурная альтернатива не нужна** — `docs/SCOPE.md` честно фиксирует
   отсутствие клавиатурной навигации в редакторах.

## 5. Цели

- Порядок пространств меняется без потери данных и переживает перезагрузку.
- Ни один маркер не меняет своё размещение из-за перестановки.
- Навигация (свайп, карусель) следует новому порядку немедленно.
- Скрытая зависимость «позиция в массиве = смысл» становится явной и покрытой
  тестами.

## 6. Scope

- Панель вкладок: обработчики `pointerdown`/`pointermove`/`pointerup` на `.tab`,
  порог начала перетаскивания, индикатор места вставки, курсор.
- Запись нового порядка `config.spaces` через существующий `_writeConfig`.
- Развязка `firstSpaceId` с позицией в массиве (см. §8).
- Предупреждение о числовом `floor` (§4.2), ключи i18n en+ru.
- `docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md`, оба changelog.

## 7. Не входит в задачу

- Перетаскивание на сенсорных экранах и во View — решение владельца §4.1.
- Клавиатурная альтернатива — §4.3.
- Порядок комнат, устройств, вложений, вкладок режимов (`plan`/`devices`/`decor`).
- Сортировка «по имени» и любые автоматические порядки.
- Изменение самого механизма `floor` из #210: числовая адресация остаётся как
  есть, задача только предупреждает.

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

### 8.1. Перетаскивание

- Drag начинается только при `_canEdit`, не в киоске, `this._mode !== 'view'`,
  `event.pointerType === 'mouse'` и после смещения ≥ 4 px по горизонтали.
  До порога это обычный клик — переключение пространства сохраняется.
- Вкладка «+» (`.tabadd`) в перестановке не участвует и не может стать целью.
- Во время перетаскивания видно место вставки; при отпускании вне панели
  порядок не меняется.
- Одно пространство — перетаскивать нечего, обработчики не навешиваются.

### 8.2. Запись

- Новый порядок пишется целиком массивом `spaces` штатным `_writeConfig`
  с `expected_rev`; конфликт ревизий обрабатывается как у любой другой правки.
- Активное пространство после перестановки не меняется: перетащили не ту, что
  открыта — открытая остаётся открытой; перетащили открытую — она открыта на
  новом месте.

### 8.3. Маркеры не двигаются: материализация вместо нового поля

Обязательное свойство одно: **ни один маркер не меняет `space` из-за изменения
порядка**. Достигается оно не хранением якоря, а тем, что перестановка делает
явной ту привязку, которая до неё держалась на позиции.

**Норматив.** В той же транзакции записи, что и новый порядок, каждый маркер,
чьё пространство сегодня разрешается через `firstSpaceId` — то есть у него нет
ни `area`, ведущей в пространство, ни собственного `space` — получает явное
`space`, равное тому пространству, в котором он находится **сейчас**, до
перестановки. После этого его размещение от порядка не зависит вовсе, и
`firstSpaceId` перестаёт быть для него значимым.

**Почему так, а не якорь в `settings`.** Первая редакция ТЗ предполагала хранить
id «первого» пространства отдельным полем. Ревью r1 (M2) справедливо указало,
что это новое поле конфигурации, которое §9 в том же документе отрицал.
Материализация решает ту же задачу без расширения схемы:

- новых полей нет — `CONFIG_SCHEMA`, `scripts/config-field-registry.mjs` и
  `docs/CONFIG-COMPATIBILITY.md` не трогаются;
- запись идёт одним `config/set` с уже существующими полями маркеров;
- правка данных минимальна и сохраняет наблюдаемое состояние: маркер остаётся
  ровно там, где пользователь его видел;
- откат не нужен: явное `space` — валидное и предпочтительное состояние,
  которое карточка и так пишет при любом сохранении маркера.

**Граница.** Материализуются только маркеры, разрешавшиеся через
`firstSpaceId`. Маркеры с `area` или с уже заданным `space` не трогаются —
проверяется AC3.

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

### 8.4. Навигация

`swipeTarget` продолжает работать по индексам — он получает уже
переупорядоченный `spaceIds`, поэтому изменений не требует. AC4 фиксирует, что
свайп идёт в новом порядке немедленно, без перезагрузки.

### 8.5. Предупреждение о числовом `floor`

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

## 9. Данные, i18n, a11y, touch, privacy, security

**Touch editor: not exposed.** Классификация по `docs/TOUCH-SUPPORT.md` §153:
перетаскивание вкладок на сенсорных экранах не появляется вовсе — ни как
degraded-вариант, ни как долгое нажатие. Это решение владельца §4.1, а не
недоделка. Обоснование: вкладки живут во View, где переключение пространств —
fully supported на тач и release-blocking; любой жест на вкладке рискует съесть
тап. Порядок пространств меняется на десктопе, как и остальная работа с планом.

Safety floor §69 того же документа соблюдён по построению: на тач-устройстве
поведение вкладок не меняется ни на йоту, значит ни потери данных, ни случайной
мутации при мультитаче новая функция внести не может.

- **Данные:** порядок элементов массива `spaces` плюс материализация неявной
  привязки маркеров (§8.3). Новых полей конфигурации не появляется, схема и
  `CONFIG_SCHEMA` не меняются — см. §8.3 о том, почему выбран путь без нового
  поля и что это значит для `docs/CONFIG-COMPATIBILITY.md`.
- **i18n:** один новый ключ тоста (en + ru) и, при необходимости, `title`
  вкладки в режиме редактора.
- **a11y:** без изменений — клавиатурной навигации в редакторах нет и не
  обещано (`docs/SCOPE.md`).
- **privacy / security:** новых данных и путей записи нет.

## 10. Performance

Панель вкладок — единицы элементов. Обработчики навешиваются только в режимах
редактора и только для мыши. Влияния на бюджеты нет; performance-профили не
затрагиваются.

## 11. Риски

1. **Drag съедает клик.** Порог 4 px и проверка `pointerType` — единственное,
   что отделяет перестановку от переключения. AC2 проверяет обе стороны.
2. **Маркеры уезжают.** Главный риск задачи: `firstSpaceId` сегодня буквально
   «первый по порядку». Закрывается §8.3 + AC3 + мутант.
3. **Числовой `floor`.** Предупреждение — смягчение, а не защита: чужие панели
   отсюда не видны. Записано в USER-GUIDE.
4. **Конкурентная правка.** Перестановка уходит с `expected_rev`; на конфликт
   реагирует общий механизм — AC6.

## 12. Acceptance criteria

1. **AC1 — перестановка и запись.** Перетаскивание вкладки меняет её позицию;
   порядок сохраняется на сервере и переживает перезагрузку страницы.
   **Доказательство:** `smoke`.
2. **AC2 — клик не сломан.** Клик по вкладке без смещения переключает
   пространство; смещение ≥ 4 px начинает перетаскивание и клик не срабатывает.
   **Доказательство:** `smoke`.
3. **AC3 — маркеры не двигаются.** Конфигурация с маркером, чьё размещение
   опирается на fallback-пространство, после перестановки даёт то же `space`
   для каждого маркера; такой маркер получает явное `space` в той же записи, а
   маркеры с `area` или с уже заданным `space` остаются побитово прежними.
   Тест красный до §8.3. **Доказательство:** `unit` (`buildDevices` + запись).
4. **AC4 — навигация следует порядку.** После перестановки `swipeTarget`
   возвращает нового соседа немедленно, без перезагрузки.
   **Доказательство:** `unit` + `smoke`.
5. **AC5 — границы включения.** Обработчики не навешиваются во View, в киоске,
   при `pointerType !== 'mouse'` и при единственном пространстве; вкладка «+»
   не участвует. **Доказательство:** `unit` (чистая функция решения) + `smoke`
   для View.
6. **AC6 — конкурентная правка.** Перестановка уходит с `expected_rev`;
   конфликт ревизий не молчит и не теряет порядок.
   **Доказательство:** `unit` либо `smoke` по существующему механизму.
7. **AC7 — предупреждение о числовом `floor`.** После первой перестановки в
   сессии показан тост; повторные перестановки его не повторяют.
   **Доказательство:** `smoke`.
8. **AC8 — release-артефакты.** Оба changelog, оба USER-GUIDE описывают
   перестановку и её ограничения (мышь, редактор, числовой `floor`); `dist`,
   demo и integration bundle идентичны друг другу.
   **Доказательство:** diff + сверка копий бандла.

## 13. План автотестов

- `test/` — юниты на чистую функцию «можно ли начать перетаскивание» (AC5) и на
  стабильность `firstSpaceId` в `buildDevices` (AC3); проверка `swipeTarget` на
  переупорядоченном списке (AC4).
- `demo/smoke_space_tab_reorder.mjs` — новый смок: перестановка мышью, запись,
  сохранение активного пространства, клик без смещения, отсутствие drag во View,
  тост о числовом `floor` (AC1, AC2, AC4, AC5, AC7).
- Существующие смоки навигации и `smoke_fixed_floor` (#210) — прогон без правок.

## 14. Мутационный гейт (`scripts/mutation-gate.mjs`)

| id | Патч | Guard |
|---|---|---|
| `tab-reorder-not-persisted` | перестановка меняет только локальную модель, `_writeConfig` не зовётся | смок AC1 |
| `tab-reorder-eats-click` | убрать порог смещения — любой pointerdown начинает drag | смок AC2 |
| `reorder-skips-materialization` | записывать новый порядок, не материализуя привязку маркеров | юнит AC3 |
| `materialization-touches-bound-markers` | материализовать `space` и у маркеров с `area` | юнит AC3 |
| `tab-reorder-ignores-pointer-type` | снять проверку `pointerType === 'mouse'` | юнит AC5 |

## 15. Release-артефакты

- `docs/CHANGELOG.md` + `docs/CHANGELOG.ru.md` — `User-Visible: yes`;
- `docs/USER-GUIDE.md` + `docs/USER-GUIDE.ru.md` — раздел про панель вкладок:
  перестановка мышью в редакторе, ограничение по тачу, оговорка про числовой
  `floor`;
- golden не затрагивается: панель вкладок в матрице не участвует, визуальных
  изменений в состоянии покоя нет;
- performance-профили не затрагиваются.

## 16. Откат

Порядок — обычные данные, обратной миграции не требуется: администратор
перетаскивает вкладки назад. Код откатывается снятием обработчиков; развязка
`firstSpaceId` (§8.3) остаётся полезной сама по себе и откату не подлежит.

## 17. Принятые предположения (техническое, менять свободно)

1. **Порог 4 px** взят как минимально заметное намеренное движение; точное
   число не продуктовое решение и может быть изменено ревьюером.
2. **Механика вставки** — вставка перетаскиваемой вкладки перед той, над
   серединой которой отпущена мышь. Альтернатива (обмен местами) отвергнута:
   при переносе через несколько позиций она даёт неожиданный результат.
3. **Атомарность записи предположением не является.** Требование «порядок и
   материализация уходят одним `config/set`» — норматив §8.3, его проверяет AC3
   и стережёт мутант `reorder-skips-materialization`. Разносить запись на две
   нельзя: между ними возникает окно, где порядок уже новый, а привязка ещё
   старая — ровно тот риск, ради которого §8.3 написан. Здесь пункт оставлен
   только как указатель: свободно меняется всё остальное в этом разделе, но не
   это (находка M3 ревью r2; прежняя редакция §17 держала норматив под
   заголовком «менять свободно»).

   Историческая справка к §8.3: первая редакция предлагала хранить якорь
   `firstSpaceId` в `settings` — отвергнута по M2 ревью r1 как новое поле
   конфигурации.
4. **Тост о числовом `floor`** показывается всегда, а не только когда числовой
   `floor` действительно где-то используется: карточка не видит чужие панели,
   поэтому условие проверить нечем.