257 lines
20 KiB
Markdown
257 lines
20 KiB
Markdown
# Пункт управления NODE.DC
|
||
|
||
Универсальный браузерный пункт управления NODE.DC на React 19, TypeScript и
|
||
Vite. Приложение задаёт общую операторскую оболочку для аппаратов, сенсоров,
|
||
наблюдения, миссий и записей. XGRIDS/LixelKity K1 является первым реальным
|
||
device adapter, но структура интерфейса от него не зависит.
|
||
|
||
Внутри пространственной рабочей поверхности встроен открытый Rerun Web Viewer.
|
||
Это self-hosted frontend-компонент из npm-пакета `@rerun-io/web-viewer`, а не
|
||
переход во внешний облачный интерфейс. При запуске K1 live/replay backend сам
|
||
создаёт Rerun gRPC/proxy source; ручной адрес нужен только для другого Rerun
|
||
потока или совместимой RRD-записи.
|
||
|
||
## Текущее состояние
|
||
|
||
| Контур | Состояние | Что это означает |
|
||
| --- | --- | --- |
|
||
| 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 сохранение, декодирование облака точек и позы, реальные метрики. |
|
||
| Автоматический MQTT → Rerun | Реализован | Первый live/replay поднимает process-wide `RecordingStream` и gRPC/proxy на TCP 9876; следующие сессии сбрасывают сцену и метрики и переиспользуют его. |
|
||
| Встроенный Rerun Viewer | Реализован | Self-hosted npm-компонент автоматически открывает текущий gRPC source внутри Control Station; внешний viewer не используется. |
|
||
| Контролы сцены → Rerun | Реализованы для текущей геометрии | Работают размер и видимость точек, атрибут цвета, палитра, окно накопления, траектория и сетка. Проекция, собственный timeline и сохранённые layout-профили ещё не подключены. |
|
||
| Legacy Foxglove module | Только regression | Модуль и тесты сохранены для сравнения декодирования. Текущий live/replay runtime не запускает Foxglove WebSocket и не использует TCP 8765. |
|
||
| Камеры, карты и миссии | Интерфейс готов | Серверная логика и реальные каналы для этих рабочих поверхностей ещё не подключены. |
|
||
|
||
Приложение не генерирует демонстрационное облако, траекторию, кадры или
|
||
метрики. Если реальных данных нет, область сцены остаётся пустой, а числовые поля
|
||
показывают `—`.
|
||
|
||
## Архитектура данных
|
||
|
||
```text
|
||
K1 MQTT :1883, read-only
|
||
└── raw .k1mqtt + metadata + SHA-256 сохраняются первыми
|
||
└── bounded latest-wins preview queue (32 сообщения)
|
||
└── проверенный protobuf/LZ4 decoder
|
||
└── Rerun Points3D + Transform3D + LineStrips3D
|
||
└── gRPC/proxy TCP 9876
|
||
└── rerun_grpc_url в REST/WebSocket state
|
||
└── встроенный @rerun-io/web-viewer
|
||
└── пространственная сцена NODE.DC
|
||
|
||
React Control Station ←→ REST /api/* + WebSocket /api/events
|
||
FastAPI на 127.0.0.1:8000
|
||
CoreBluetooth + live/replay runtime
|
||
```
|
||
|
||
В момент готовности `RerunBridge` backend публикует адрес вида
|
||
`rerun+http://127.0.0.1:9876/proxy`. Frontend автоматически назначает его сцене,
|
||
если оператор не указал ручной source. После остановки приёма URL и встроенный
|
||
viewer остаются активны, а следующая сессия сбрасывает session-local геометрию,
|
||
траекторию и метрики и использует тот же listener. Он закрывается вместе с
|
||
процессом `k1link serve`.
|
||
|
||
Поля `foxglove_ws_url` и `foxglove_viewer_url` пока остаются в API как
|
||
совместимость со старым контрактом, но текущий runtime держит их пустыми.
|
||
|
||
## Фиксированная оболочка
|
||
|
||
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. Размер точек, способ окрашивания и палитра, 12-секундное по
|
||
умолчанию накопление, видимость облака и траектории и сетка связаны с backend и
|
||
Rerun Blueprint. Кнопки собственного timeline, смена 2D/3D/карты и сохранение
|
||
layout пока остаются интерфейсным контрактом.
|
||
|
||
## Архитектурные разделы
|
||
|
||
Навигация описана данными в `src/productModel.ts`, а не зашита в разметку каждой
|
||
страницы.
|
||
|
||
| Раздел | Назначение |
|
||
| --- | --- |
|
||
| Центр | Оперативный обзор, состояние контура и активность оператора. |
|
||
| Парк | Аппараты, текущее устройство, сенсоры и конфигурации борта. |
|
||
| Наблюдение | Пространственная сцена, камеры, карта, объекты, телеметрия и время. |
|
||
| Миссии | Планировщик, маршруты, сценарии и исполнение. Командный backend отключён. |
|
||
| Данные | Сессии, потоки, сущности, playback и экспорт доказательств. |
|
||
| Система | Модули, интеграции, сеть, аудит и настройки платформы. |
|
||
|
||
Карточки возможностей имеют четыре честных уровня: работает сейчас, готово к
|
||
источнику, интерфейсный контракт и последующий этап. Каталог не следует читать
|
||
как утверждение, что для каждой карточки уже существует backend.
|
||
|
||
## Установка, проверка, сборка и запуск
|
||
|
||
Требуются Node.js 20.19+ либо 22.12+, `uv` и соседний checkout
|
||
`NODEDC_DESIGN_GUIDELINE`: зависимости `@nodedc/*` подключены к нему через
|
||
локальные `file:` пути. Python устанавливается только в `.venv` репозитория.
|
||
|
||
Канонический путь от корня репозитория:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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. Backend автоматически поднимет Rerun gRPC на TCP 9876 и опубликует адрес в
|
||
state. Ручной source вводить не требуется.
|
||
8. Открыть **Наблюдение → Пространственная сцена**. Реальные облако и траектория,
|
||
частота, число точек, задержка и пропуски preview появятся после прихода
|
||
сообщений K1.
|
||
|
||
В проверочном live-сеансе через этот путь прошло 80 реальных MQTT-сообщений:
|
||
38 кадров `lio_pcl`, 42 кадра `lio_pose`, 2 775 точек в последнем облаке и
|
||
0 ошибок декодирования.
|
||
|
||
## Источники Rerun
|
||
|
||
Live/replay runtime автоматически назначает первый URL из примера. В
|
||
**Наблюдение → Пространственная сцена → Источник** можно оставить ручное поле
|
||
пустым либо указать другой адрес, который понимает `@rerun-io/web-viewer`
|
||
зафиксированной в `package.json` версии:
|
||
|
||
```text
|
||
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 хранится только в состоянии текущей страницы и имеет приоритет над
|
||
автоматическим source;
|
||
- ошибка запуска показывается в viewport, без подстановки фиктивных данных.
|
||
|
||
После готовности Viewer выбор Rerun entity возвращает `entityPath` и имя view в
|
||
оболочку. Backend принимает и применяет к Rerun размер точки `0.5–12.0`, режимы
|
||
цвета `intensity`, `height`, `distance`, `rgb`, `class`, палитры Turbo, Viridis,
|
||
Plasma, grayscale и custom, накопление `0–120` секунд, а также видимость облака,
|
||
траектории и сетки. Значение по умолчанию — 12 секунд истории реальных кадров.
|
||
Для текущего firmware-3 `lio_pcl` доказана только интенсивность из младшего
|
||
байта `rgbi`; RGB используется лишь когда он действительно присутствует в
|
||
декодированном формате. Custom/class сейчас означает выбранный сплошной цвет,
|
||
а не готовую семантическую классификацию.
|
||
|
||
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` | Остановка активного источника. |
|
||
| `POST` | `/api/viewer/settings` | Размер/цвет точек, накопление, видимость облака, траектории и сетки. |
|
||
| `WS` | `/api/events` | Периодические snapshots для live UI. |
|
||
|
||
`/api/state` и изменяющие состояние ответы могут вернуть snapshot напрямую или
|
||
как `{ "state": { ... } }`. Текущие поля включают `phase`, `message`, `devices`,
|
||
`selected_device_id`, `k1_ip`, `source_mode`, `metrics`, `rerun_grpc_url` и
|
||
`viewer_settings`. 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.
|
||
- Исключение: Rerun gRPC/proxy на TCP 9876 сейчас слушает все сетевые интерфейсы,
|
||
хотя автоматически возвращаемый URL содержит `127.0.0.1`. На нём нет
|
||
connector-level authentication или TLS. Этот порт допустим только в доверенной
|
||
лабораторной LAN; его нельзя пробрасывать в публичный Интернет или cellular
|
||
WAN без аутентифицированного TLS reverse proxy. Listener намеренно остаётся
|
||
активным между сессиями; для его закрытия нужно остановить `k1link serve`.
|
||
- Пароль Wi-Fi находится только в React memory, передаётся в JSON POST body,
|
||
очищается после успешного ответа и не сохраняется в URL/local storage.
|
||
- BLE-подключение выполняет только отдельно рассмотренную provisioning-запись;
|
||
случайные GATT writes и автоматические повторы запрещены.
|
||
- MQTT live/replay не публикует команды устройству. Запуск и остановка
|
||
физического сканирования остаются за кнопкой K1.
|
||
- Live-сессии сначала сохраняют сырые сообщения, затем формируют preview. При
|
||
перегрузке preview может быть отброшен, raw evidence сохраняется.
|
||
- Timeline `capture_time` сохраняет Unix-время приёма сообщения Mac, а окно
|
||
накопления viewer использует session-local `stream_time`. `capture_time` — не
|
||
доказанный timestamp сенсора K1 и не photon-to-screen latency.
|
||
- Панорамный камерный поток в наблюдавшихся MQTT report topics отсутствует;
|
||
текущая Rerun-сцена содержит только облако точек и позу/траекторию, а
|
||
операционные метрики отображаются внешней оболочкой Control Station.
|
||
- `sessions/` игнорируется Git и может содержать адреса, идентификаторы,
|
||
траекторию и карту помещения. В репозиторий попадают только redacted manifests
|
||
и безопасная документация.
|