Дмитрий Соловьев
209 lines
21 KiB
Markdown
209 lines
21 KiB
Markdown
<!-- /autoplan restore point: /home/dasolovyev/.gstack/projects/missionis-observatio-terrae/feat-tgu-slots-filters-autoplan-restore-20260616-165024.md -->
|
||
|
||
# Эргономика выбора слотов: выбор «полосами» + правило выполнимости брони
|
||
|
||
## Проблема (как сформулировал оператор)
|
||
Сделана работа по сортировке, подсветке брони, показу забронированных, расчёту %
|
||
покрытия. Но **сам выбор слотов под бронь по-прежнему неудобен**: сейчас оператор
|
||
отмечает слоты галочками поштучно (или Shift+клик диапазоном, или «все видимые /
|
||
все сутки»). На сотнях-тысячах слотов это утомительно. Плюс выбор «слепой» — он не
|
||
знает, можно ли вообще физически отснять выбранный набор (манёвренность КА).
|
||
|
||
## Решённые premise (premise-гейт, 2026-06-16, скорректировано после CEO-ревью)
|
||
1. **Ограничение брони через смену крена реально существует** (агилити КА).
|
||
2. **КОРРЕКЦИЯ:** модель манёвренности УЖЕ есть в slots-service, по-КА из каталога
|
||
(`mmi`, `maxSurveyDuration`, `maxChainLength`, `ROLL_EPSILON=0.01` — см. ниже).
|
||
Ручная бронь (`bookReq`) её не проверяет, но coverage-solver и `buildSurveyChains`
|
||
её соблюдают. Поэтому **не хардкодим физику на фронте** — проверка выполнимости
|
||
будет **бэкенд validate-эндпоинтом**, переиспользующим эти по-КА параметры.
|
||
3. **Iteration 1 = только UX выбора полосами** (frontend, без правила). Проверка
|
||
выполнимости — **iteration 2** (бэкенд validate-эндпоинт + проводка на фронте).
|
||
|
||
## Что уже есть в бэкенде (источник правды для it.2)
|
||
- Параметры по-КА из каталога ([SatelliteCatalogClient.kt:116](../../services/slots-service/src/main/kotlin/space/nstart/pcp/slots_service/service/SatelliteCatalogClient.kt#L116),
|
||
[AbstractSatellite.kt:25](../../services/slots-service/src/main/kotlin/space/nstart/pcp/slots_service/model/satellite/AbstractSatellite.kt#L25)):
|
||
`mmi`=10с (мин. интервал маневра, тот же крен), `maxSurveyDuration`=300с,
|
||
`maxChainLength`=30 слотов, `ROLL_EPSILON`=0.01.
|
||
- `buildSurveyChains` / `canMergeInTime` / `sameRoll` ([SlotService.kt:2151](../../services/slots-service/src/main/kotlin/space/nstart/pcp/slots_service/service/SlotService.kt#L2151))
|
||
— склейка цепочек по-КА (для отрисовки), `OccupiedIntervalPrefilter` — mmi/maxSurveyDuration.
|
||
- **Несоответствия исходного черновика** (закрыты решением «правило за бэком»): фронтовые
|
||
150с ≠ бэкендовые 300с; фронтовый ε=0.1° ≠ бэкендовый 0.01; «30с на смену крена» —
|
||
в бэке отдельной такой константы НЕТ (склейка только при том же крене). Эти числа
|
||
сверяются с каталогом/баллистиками в it.2, НЕ хардкодятся.
|
||
|
||
## Что уже есть (карта на существующий код)
|
||
- Выбор: `selectedKeys: Set<slotKey>` в [TguSlotsTab.tsx](../../services/pcp-tgu-ui-service/src/features/tgu-slots/TguSlotsTab.tsx).
|
||
Поштучный чек, Shift+клик-диапазон ([slotSelection.ts](../../services/pcp-tgu-ui-service/src/features/tgu-slots/slotSelection.ts) `selectionAfterCheck`),
|
||
«выбрать видимые», «все сутки», «снять выбор».
|
||
- Слот несёт `roll`, `revolution`, `revolutionSign`, `cycle`, `satelliteId`, `slotNumber`, `tn`, `tk`, `state`.
|
||
- Чистые модули с юнит-тестами: slotFilters.ts, slotSelection.ts, coverage.ts (+ .test.ts) — образец стиля.
|
||
- Бронь: `book()` → подтверждение → `performBook` (чанк 200), снятие аналогично.
|
||
- Бэкенд бронирует без валидации манёвренности ([SlotService.kt:2500](../../services/slots-service/src/main/kotlin/space/nstart/pcp/slots_service/service/SlotService.kt#L2500)). В it.1 не трогаем.
|
||
|
||
## Решение — Iteration 1 (только UX выбора полосами, frontend) — ФИНАЛ после ревью
|
||
|
||
### Модуль 1: `slotStrips.ts` (чистая логика + юнит-тесты)
|
||
- `groupStrips(slots, keyOf): Map<slotKey, StripId>` — максимальные same-roll цепочки
|
||
**по-КА**. `keyOf` — аксессор ключа слота (как `keyAt` в `selectionAfterCheck`), чтобы
|
||
не дублировать формулу `${satelliteId}:${slotNumber}:${cycle}`.
|
||
- **Детерминизм:** внутри функции тотальный порядок — сортировка по
|
||
`(satelliteId, parseLocal(tn), parseLocal(tk), slotNumber, cycle, slotKey)`. Результат
|
||
не зависит от порядка входного массива.
|
||
- **ε крена = `ROLL_EPSILON = 0.01`** (именованная константа, как в бэкенде; НЕ 0.1).
|
||
Сравнение — **с якорным креном полосы** (`abs(roll − anchorRoll) ≤ 0.01`), НЕ с
|
||
предыдущим слотом (иначе дрейф крена 0.00→0.009→0.018 ошибочно склеит). Совпадает с
|
||
бэкендовым `sameRoll(roll, chainRoll)`.
|
||
- **StripId стабилен и читаем:** `strip:${slotKey первого члена}` (не счётчик — счётчик
|
||
зависит от порядка обхода КА).
|
||
- Краевые: один слот → своя полоса; два КА вперемешку по времени НЕ склеиваются;
|
||
`tn` не парсится (NaN) → синглтон без падения; ровно на границе ε (`==0.01`) → та же полоса.
|
||
|
||
### Модуль 2: выбор «полосами» (UX в TguSlotsTab) — решения ревью
|
||
- **Жест: чип в строке `полоса ×N`** (N = число видимых членов полосы). НЕ Alt+клик
|
||
(необнаружим, конфликт с чек/Shift), НЕ клик по карте как основной. Чип появляется
|
||
только при N≥2 и если есть хоть один выбираемый (не-BUSY) член.
|
||
- **Identity ≠ selection target:**
|
||
- `stripIdByKey = useMemo(groupStrips(displaySlots, slotKey), [displaySlots])` — id по
|
||
СТАБИЛЬНОМУ набору (не filteredSlots/sortedSlots — иначе фильтр-дырка ложно склеит/разорвёт).
|
||
- Видимые выбираемые члены полосы берём из `filteredSlots` ∩ `!slotIsBusy` (по образцу
|
||
`selectableVisible`).
|
||
- **Поведение чипа = `toggleAllVisible`, но в рамках одной полосы:** если ВСЕ видимые
|
||
выбираемые члены уже выбраны → снять их; иначе добавить. После — `anchorIndexRef.current = null`.
|
||
Без нового state (`selectedStrips` не заводим — рассинхрон с `selectedKeys`).
|
||
- **Группировка визуально по StripId, sort-aware:** в сортировке «время» — левый рельс
|
||
(border-left, цвет по `StripId`, приглушённый) на смежных строках полосы. В «крен»/«вклад»
|
||
слоты полосы НЕ подряд → рельс НЕ рисуем; подсветка членов полосы по StripId при наведении.
|
||
Фон строки оставляем за состоянием (active/selected); статус-ячейки не перекрашиваем.
|
||
- **Карта it.1:** оставляем существующую подсветку выбранных слотов (`markedObjectIds` уже
|
||
ведётся от `selectedKeys`). Отдельную раскраску полос на карте и «выбрать полосу из
|
||
`SlotPickMenu`» — НЕ делаем в it.1 (расширяет scope на модель/рисовалку карты).
|
||
- **CSS/таблица:** обновить `colCount`; выравнивание ячеек — классами, не сдвигом
|
||
`nth-child`; чип держать в пределах `ROW_HEIGHT = 34`.
|
||
|
||
### Матрица состояний строки (зафиксировать перед реализацией)
|
||
| Состояние | Источник | Визуал |
|
||
|---|---|---|
|
||
| active (фокус по карте) | `activeSlotId` | подсветка строки (как есть) |
|
||
| selected | `selectedKeys.has(key)` | чек отмечен |
|
||
| strip-selected | все видимые выбираемые члены полосы выбраны | чип в активном виде |
|
||
| partial | часть членов полосы выбрана | чип в нейтральном виде |
|
||
| disabled chip | N<2 или 0 выбираемых членов | чипа нет |
|
||
| booked/occupied | как есть (бейдж) | не меняется; в полосу входит визуально, в выбор — нет |
|
||
|
||
## Реализовано (it.1, 2026-06-17 — пересмотрено)
|
||
|
||
ВАЖНО: первая версия it.1 (авто-чип «полоса ×N» по равному крену) оказалась не той фичей и
|
||
переделана. На реальных данных полоса по «подряд по времени + равный крен» не формировалась
|
||
(в один момент идёт «веер» кренов с шагом ~3°, равный крен повторяется не подряд, а вдоль трассы
|
||
через каденцию). Оператор хотел не авто-магию, а ручной выбор полосы мышью «от первого к последнему»
|
||
с запретом выйти за полосу.
|
||
|
||
Переопределение полосы (согласовано с оператором):
|
||
- **полоса = один КА + один крен (допуск `ROLL_EPSILON`) + подряд по времени (без разрыва каденции);**
|
||
- **виток/цикл в границу НЕ входят** — у экватора номер витка меняется, а слоты остаются в одной полосе.
|
||
|
||
Сделано:
|
||
- `slotStrips.ts`: `groupStrips(slots, keyOf) → { idByKey, membersOf }`. Группировка: по КА →
|
||
кластеризация по крену (`ROLL_EPSILON=0.5`, разрыв > ε начинает кластер) → внутри кластера деление
|
||
по непрерывности времени (`CADENCE_GAP_FACTOR=1.5` от медианной каденции). `PolosaId =
|
||
polosa:${ключ первого по времени члена}`; `membersOf` — члены в порядке времени.
|
||
- `slotSelection.ts`: вместо `toggleStripSelection` — `selectStripRange(current, members, fromKey,
|
||
toKey)` (чистая: добавляет членов полосы между двумя кликами включительно, без мутации).
|
||
- `TguSlotsTab.tsx`: убран чип/hover/`stripInfo`. Жест: обычный клик ставит якорь; Shift+клик по
|
||
слоту той же полосы выделяет членов между якорем и кликом (BUSY исключаются); Shift+клик по слоту
|
||
другой полосы/КА — выбор не меняется + подсказка «только в пределах одной полосы». Якорь — состояние
|
||
(`anchorKey`), строки полосы якоря подсвечены рельсом (оттенок по `PolosaId`); сбрасывается при
|
||
смене заявки/сортировки/фильтров/расчёта. Подсказка жеста в selbar.
|
||
- `tgu-planning.css`: удалены стили чипа/hover; рельс `tgu-slots-row--strip` переиспользован под
|
||
полосу якоря, добавлен `is-strip-anchor`.
|
||
- Калибровка `ROLL_EPSILON=0.5` / `CADENCE_GAP_FACTOR=1.5` — по скрину данных; при ручном прогоне
|
||
возможна подстройка по фактическим `roll`/`tn`.
|
||
- Бэкенд/DTO не тронуты. Правило выполнимости (манёвренность КА) по-прежнему it.2.
|
||
|
||
Доработки (2026-06-17):
|
||
- **Shift+клик ближе к якорю «сжимает» выделение.** `selectStripRange` теперь задаёт выбор полосы
|
||
РОВНО диапазоном [from..to]: члены полосы вне диапазона снимаются, выбор в других полосах сохраняется.
|
||
Якорь при Shift+клике не двигается (остаётся первым кликом) — можно тянуть конец туда-обратно.
|
||
- **Жест выбора полосы мышью на карте (Shift+drag).** Слоты на карте уже кликабельные полигоны
|
||
(`slot:${key}` в spatial-index). Карта на жесте отдаёт наверх ключи слотов под курсором
|
||
(`onStripAnchor`/`onStripDrag`/`onStripCommit`), а полосу/диапазон считает `TguSlotsTab`
|
||
(`pickStripAnchor` — самый ранний по времени слот под курсором = начало; `pickStripEnd` — самый
|
||
поздний член ТОЙ ЖЕ полосы под курсором = конец; за границу полосы выделение не уходит). Обычный
|
||
drag = панорама, Shift+drag по слоту = выбор полосы (без отдельной кнопки-режима). Подсветка
|
||
диапазона живая — через `markedObjectIds` (SVG-оверлей `is-marked`), отдельный слой превью не нужен.
|
||
|
||
## Решение — Iteration 2 (проверка выполнимости, отдельно)
|
||
- Бэкенд: read-only `POST /api/slots/booking/validate` (набор слотов → violations),
|
||
переиспользует по-КА `mmi`/`maxSurveyDuration`/`maxChainLength`/`ROLL_EPSILON` из каталога.
|
||
Сверить точную семантику (300 vs «150 на полосу», нужна ли отдельная 30с-граница) с
|
||
баллистиками. Опционально позже — валидация и в самом `bookReq`.
|
||
- Фронт: гонять validate при выборе/перед бронью, показывать violations, решить
|
||
блокировать кнопку или предупреждать.
|
||
|
||
## NOT in scope (it.1)
|
||
- Любая физика выполнимости на фронте (перенесено в it.2, за бэкенд).
|
||
- Переработка автоподбора покрытия (GREEDY/CONTINUOUS).
|
||
- Изменение модели хранения броней.
|
||
|
||
## Тест-план (it.1) — финал
|
||
- `slotStrips.test.ts` (groupStrips): мультиполоса в одном КА; два КА вперемешку по времени
|
||
(не склеиваются); один слот → своя полоса; граница ε (`diff==0.01` склеивает, `0.0101` рвёт);
|
||
дрейф крена 0.00/0.009/0.018 (с якорным сравнением → две полосы); устойчивость к порядку
|
||
входа (равенство РАЗБИЕНИЯ при перемешивании); tie-break по равному `tn`; NaN `tn` → синглтон
|
||
без падения; пустой вход → пустая Map.
|
||
- **Чистый хелпер выбора полосы** (выделить из компонента, как slotSelection): скрытые члены
|
||
не выбираются; BUSY исключён; «все видимые выбраны → снять, иначе добавить»; нет мутации
|
||
входного `selectedKeys`.
|
||
- Ручная проверка в vite dev: чип `полоса ×N`, рельс в сортировке «время», подсветка по
|
||
StripId в «крен»/«вклад», согласованность с Shift+клик/чек/«все сутки», счётчик «Выбрано».
|
||
|
||
## Смежная находка (вне scope, флаг оператору)
|
||
`anchorIndexRef` (якорь Shift-выбора) сбрасывается при смене сортировки, но НЕ при смене
|
||
фильтров (статус/КА/ветвь/сутки), хотя они тоже меняют порядок строк → Shift-диапазон после
|
||
фильтрации может выбрать не то. Существующий латентный баг, рядом с этой задачей. Дёшево
|
||
починить (сбрасывать якорь и при смене фильтров) — включить в it.1 или отдельным фиксом.
|
||
|
||
---
|
||
|
||
## Review artifacts (/autoplan, 2026-06-16)
|
||
|
||
### CEO consensus
|
||
| # | Вопрос | Claude | Codex | Консенсус |
|
||
|---|--------|--------|-------|-----------|
|
||
| 1 | Та ли проблема | да (UX выбора) | да | CONFIRMED |
|
||
| 2 | Фронт-физика — регрет? | да, критично | да, критично | CONFIRMED → правило за бэк |
|
||
| 3 | Бэкенд уже имеет модель? | да (нашёл chain-логику) | — | подтверждено в коде |
|
||
| 4 | Калибровка scope | разбить | разбить | CONFIRMED → it.1 только UX |
|
||
|
||
### Design consensus
|
||
| Тема | Claude | Codex | Консенсус |
|
||
|------|--------|-------|-----------|
|
||
| Жест | чип в строке | чип в строке | CONFIRMED |
|
||
| Grouping vs sort | sort-aware по StripId | sort-aware по StripId | CONFIRMED |
|
||
| Скрытые члены | только видимые | только видимые | CONFIRMED |
|
||
| Карта | вторично/отложить | вторично/отложить | CONFIRMED |
|
||
| Состояния | матрица | матрица | CONFIRMED |
|
||
|
||
### Eng consensus
|
||
| Тема | Claude | Codex | Консенсус |
|
||
|------|--------|-------|-----------|
|
||
| StripId над displaySlots | да | да | CONFIRMED |
|
||
| Identity ≠ selection target | да | да | CONFIRMED |
|
||
| Memo на [displaySlots] | да | да | CONFIRMED |
|
||
| ε: якорь vs предыдущий | оставил открытым | якорь (анти-дрейф) | DISAGREE → решено: якорь |
|
||
| Бэкенд-изменения в it.1 | нет | нет | CONFIRMED |
|
||
| Сброс якоря на фильтрах | — | да (смежный баг) | флаг оператору |
|
||
|
||
### Decision Audit Trail
|
||
| # | Фаза | Решение | Класс | Принцип | Обоснование |
|
||
|---|------|---------|-------|---------|-------------|
|
||
| 1 | premise | Правило выполнимости — за бэкенд (не фронт-хардкод) | User Challenge | — | оба ревьюера + бэкенд уже имеет по-КА модель из каталога |
|
||
| 2 | premise | it.1 = только UX выбора; правило → it.2 | User Challenge | P2/P3 | развязать безопасный win от спорной физики |
|
||
| 3 | design | Жест = чип `полоса ×N` | Taste | P5 (явное) | обнаружим, не конфликтует с чек/Shift |
|
||
| 4 | design | Grouping sort-aware (рельс в «время», подсветка иначе) | Mechanical | P1 | зебра по строкам врёт вне time-сортировки |
|
||
| 5 | design | Чип выбирает только видимые не-BUSY члены | Mechanical | P1 | не выбирать невидимое (доверие счётчику) |
|
||
| 6 | eng | StripId над `displaySlots`, memo на `[displaySlots]` | Mechanical | P3 | стабильность id + перф на тысячах строк |
|
||
| 7 | eng | ε-сравнение с якорным креном полосы | Mechanical | P1 | анти-дрейф, совпадает с бэкендовым sameRoll |
|
||
| 8 | eng | Без бэкенд/DTO-изменений в it.1 | Mechanical | P4 | всё нужное уже в SlotDTO |
|
||
| 9 | eng | Карта — без раскраски полос в it.1 | Mechanical | P3/P5 | не расширять scope на модель карты |
|