NODEDC_MISSION_CORE/apps/k1-viewer

Пункт управления NODE.DC

Универсальный браузерный пункт управления NODE.DC на React 19, TypeScript и Vite. Приложение задаёт общую операторскую оболочку для аппаратов, сенсоров, наблюдения, миссий и записей. XGRIDS/LixelKity K1 является первым реальным device adapter, но структура интерфейса от него не зависит.

Внутри пространственной рабочей поверхности встроен открытый Rerun Web Viewer. Это self-hosted frontend-компонент из npm-пакета @rerun-io/web-viewer, а не переход во внешний облачный интерфейс. Сам браузерный компонент, однако, должен получить совместимый источник RRD или Rerun gRPC.

Текущее состояние

Контур	Состояние	Что это означает
NODE.DC fixed shell	Реализован	Header, навигация по разделам, рабочая поверхность, окна и инспекторы работают в одном приложении.
Локальный control plane	Реализован	React получает состояние и выполняет операции через FastAPI REST и WebSocket на loopback.
K1 BLE → Wi-Fi	Реализован	Реальный BLE-поиск всех видимых устройств и одна подтверждённая provisioning-запись выбранному устройству.
K1 live/replay MQTT	Реализован	Read-only приём, raw-first сохранение, декодирование облака точек и позы, реальные метрики.
Legacy Foxglove adapter	Реализован	Текущий Python runtime публикует декодированные K1 данные в локальный Foxglove WebSocket. Это проверенный диагностический backend, а не продуктовый UI.
Встроенный Rerun Viewer	Реализован	Открывает назначенный RRD по HTTP(S) или совместимый Rerun gRPC/proxy source внутри Control Station.
Автоматический MQTT → Rerun	Не реализован	Запуск K1 live/replay пока не создаёт RRD и не подаёт данные во встроенный Rerun viewport. Нужен отдельный stream adapter.
Контролы сцены → Rerun Blueprint	Не реализованы	Размер точек, палитра, накопление, слои, проекция, timeline и компоновка пока являются честным UI-контрактом и состоянием текущего сеанса.
Камеры, карты и миссии	Интерфейс готов	Серверная логика и реальные каналы для этих рабочих поверхностей ещё не подключены.

Приложение не генерирует демонстрационное облако, траекторию, кадры или метрики. Если реальных данных нет, область сцены остаётся пустой, а числовые поля показывают —.

Архитектура данных

NODE.DC Control Station в браузере
├── control plane
│   └── REST /api/* + WebSocket /api/events
│       └── FastAPI на 127.0.0.1:8000
│           ├── CoreBluetooth: discovery и reviewed Wi-Fi provisioning
│           └── live/replay session runtime
│
├── текущий K1 preview path — legacy adapter
│   └── K1 MQTT :1883, read-only
│       ├── raw .k1mqtt + metadata + SHA-256 сохраняются первыми
│       └── protobuf/LZ4 decoder
│           └── Foxglove bridge → локальный WebSocket
│
└── продуктовая пространственная сцена
    └── встроенный @rerun-io/web-viewer
        └── RRD URL или Rerun gRPC/proxy source

Между декодером K1 и Rerun Viewer сейчас нет автоматической стрелки. Поля foxglove_ws_url и foxglove_viewer_url ещё присутствуют в API только потому, что Python runtime продолжает поднимать проверенный legacy adapter. Пункт управления не использует их как основную поверхность визуализации.

Фиксированная оболочка

Shell собран из локальных NODE.DC UI packages и сохраняет одну структуру для всех функциональных модулей:

1. AppHeader — марка NODE.DC, выбор архитектурного раздела и состояние локального backend.
2. AdminNavigationPanel — контекст аппарата и список рабочих поверхностей выбранного раздела.
3. LandingStage — стартовая ситуационная поверхность и быстрые переходы.
4. ApplicationPanel — единый контейнер активной рабочей поверхности.
5. Window и Inspector — источник, отображение, слои и компоновка без раскрытия внутренних панелей визуального движка.

Встроенный Rerun Viewer работает как canvas внутри этой оболочки. Его верхняя, blueprint-, selection- и time-панели скрыты, чтобы продуктовые действия жили в Control Station. Это ещё не означает, что все продуктовые контролы уже связаны с API Rerun: текущая граница явно показана статусом Интерфейс готов.

Архитектурные разделы

Навигация описана данными в src/productModel.ts, а не зашита в разметку каждой страницы.

Раздел	Назначение
Центр	Оперативный обзор, состояние контура и активность оператора.
Парк	Аппараты, текущее устройство, сенсоры и конфигурации борта.
Наблюдение	Пространственная сцена, камеры, карта, объекты, телеметрия и время.
Миссии	Планировщик, маршруты, сценарии и исполнение. Командный backend отключён.
Данные	Сессии, потоки, сущности, playback и экспорт доказательств.
Система	Модули, интеграции, сеть, аудит и настройки платформы.

Карточки возможностей имеют четыре честных уровня: работает сейчас, готово к источнику, интерфейсный контракт и последующий этап. Каталог не следует читать как утверждение, что для каждой карточки уже существует backend.

Установка, проверка, сборка и запуск

Требуются Node.js 20 или новее, uv и соседний checkout NODEDC_DESIGN_GUIDELINE: зависимости @nodedc/* подключены к нему через локальные file: пути. Python устанавливается только в .venv репозитория.

Канонический путь от корня репозитория:

cd /Users/dcconstructions/Downloads/mnt/NODEDC/NDC_xgrids-k1-connector
uv sync --group dev

cd apps/k1-viewer
npm install
npm run typecheck
npm run build

cd ../..
uv run k1link serve

Открыть http://127.0.0.1:8000. Команда serve отдаёт собранный dist/ и локальный API. Она намеренно привязана только к 127.0.0.1; LAN bind не предусмотрен, потому что endpoint подключения кратковременно принимает пароль Wi-Fi.

Для разработки интерфейса после запуска backend:

cd apps/k1-viewer
npm run dev

Vite слушает http://127.0.0.1:5173 и проксирует /api и /api/events на http://127.0.0.1:8000. Другой локальный backend можно указать переменной VITE_API_TARGET. Preview production-сборки запускается командой npm run preview на http://127.0.0.1:4173.

Операторский путь для текущего K1 adapter

1. Запустить uv run k1link serve и открыть Control Station.
2. Выбрать Парк → Локальное устройство.
3. Включить K1, дождаться стабильного индикатора и подтвердить это в форме.
4. Нажать Показать все BLE-устройства. Интерфейс показывает полный результат шестисекундного поиска; метка совместимости является подсказкой, выбор делает оператор.
5. Ввести SSID и пароль существующей сети и явно запустить подключение. Это одна reviewed provisioning-запись без автоматических повторов.
6. Запустить live-приём по определённому адресу K1 либо replay локального .k1mqtt/проверенного TSV. Физическое сканирование K1 запускается и останавливается подтверждённым двойным нажатием кнопки устройства.
7. Состояние, частота, число точек, задержка и пропуски preview появятся только после прихода реальных данных.

Этот путь запускает существующий MQTT/Foxglove runtime. Чтобы увидеть тот же живой K1 поток во встроенной пространственной сцене, нужно сначала реализовать и запустить MQTT→Rerun stream adapter; одного запуска live-сессии сейчас недостаточно.

Источники Rerun

В Наблюдение → Пространственная сцена → Источник принимается URL, который понимает @rerun-io/web-viewer версии, зафиксированной в package.json:

rerun+http://127.0.0.1:9876/proxy
http://127.0.0.1:8080/recording.rrd
https://example.internal/recording.rrd

• rerun+http://…/proxy — живой Rerun gRPC source через доступный браузеру proxy;
• http(s)://…/recording.rrd — RRD-запись по HTTP(S);
• версия RRD должна быть совместима с версией Web Viewer;
• URL хранится только в состоянии текущей страницы;
• ошибка запуска показывается в viewport, без подстановки фиктивных данных.

После готовности Viewer выбор Rerun entity возвращает entityPath и имя view в оболочку. Продуктовые настройки отображения, custom timeline, переключатель 2D/3D/карты и сохранение RBL пока не вызывают Blueprint/playback API. Черновик компоновки фиксируется только в памяти текущей страницы и не записывается на диск.

Контракт локального API

Метод	Route	Тело / назначение
GET	/api/health	Проверка локального сервиса.
GET	/api/state	Авторитетный snapshot состояния.
POST	/api/ble/scan	{ "duration_seconds": 6 }.
POST	/api/connect	{ "device_id", "ssid", "password" }.
POST	/api/session/live	Опционально { "host", "duration_seconds" }.
POST	/api/session/replay	{ "path", "speed", "loop" }.
POST	/api/session/stop	Остановка активного источника.
WS	/api/events	Периодические snapshots для live UI.

/api/state и изменяющие состояние ответы могут вернуть snapshot напрямую или как { "state": { ... } }. Текущие поля включают phase, message, devices, selected_device_id, k1_ip, source_mode, metrics и legacy-поля foxglove_ws_url/foxglove_viewer_url. OpenAPI доступен по /api/docs.

Карта исходников frontend

Файл	Ответственность
src/App.tsx	Fixed shell, выбор разделов и окна source/display/layers/layout.
src/productModel.ts	Архитектурные разделы, рабочие поверхности и уровни готовности.
src/workspaces/DeviceWorkspace.tsx	Реальный K1 BLE/Wi-Fi/live/replay adapter UI.
src/workspaces/Workspaces.tsx	Оперативный обзор, spatial viewport и остальные продуктовые поверхности.
src/components/RerunViewport.tsx	Жизненный цикл встроенного Rerun Web Viewer и selection events.
src/api.ts	REST/WebSocket контракт с FastAPI.
src/useK1Console.ts	Состояние backend, polling, события и действия оператора.
src/sceneSettings.ts	Типизированный UI-профиль пространственной сцены.
src/presentation.ts	Русские подписи фаз и форматирование реальных метрик.
src/messages.ts	Обезличивание и локализация технических сообщений в пользовательском интерфейсе.
src/styles.css, src/styles/*	Компоновка shell и рабочих поверхностей.

Safety и чувствительные данные

• Control Station и credential endpoint доступны только на loopback.
• Пароль Wi-Fi находится только в React memory, передаётся в JSON POST body, очищается после успешного ответа и не сохраняется в URL/local storage.
• BLE-подключение выполняет только отдельно рассмотренную provisioning-запись; случайные GATT writes и автоматические повторы запрещены.
• MQTT live/replay не публикует команды устройству. Запуск и остановка физического сканирования остаются за кнопкой K1.
• Live-сессии сначала сохраняют сырые сообщения, затем формируют preview. При перегрузке preview может быть отброшен, raw evidence сохраняется.
• sessions/ игнорируется Git и может содержать адреса, идентификаторы, траекторию и карту помещения. В репозиторий попадают только redacted manifests и безопасная документация.