RuView WiFi-DensePose 移动伴随应用（ADR-034）架构解析：基于 Expo 的 5 屏实时 WiFi 传感 App 设计与实现

RuView WiFi-DensePose 移动伴随应用（ADR-034）架构解析：基于 Expo 的 5 屏实时 WiFi 传感 App 设计与实现

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView

FieldView 是 RuView / WiFi-DensePose 体系的移动伴随应用（代号FieldView），由 ADR-034 定义、落地于 ui/mobile，采用 Expo SDK 55 + React Native 单代码库同时产出 iOS、Android 与 Web 三端。它不直接与 ESP32 CSI 节点通信，而是通过 WebSocket 订阅 Rust 传感服务端已处理的感知结果，为灾后搜救（WiFi-MAT）、建筑安防、病房监护三类现场作业提供 3D 高斯泼溅人体视图、呼吸/心率生命体征仪表、分区占用热力图与批量伤员分诊面板。阅读本文可完整掌握该 ADR 的决策脉络、屏幕/状态/服务三层架构、SensingFrame帧契约与连接生命周期，并对照仓库中真实源码（含与 ADR 蓝图的演进差异）获得可直接运行的实战方案。

1. 为什么需要移动伴随应用

WiFi-DensePose 是基于信道状态信息（CSI）的人体姿态估计系统，原始 CSI 由 ESP32 网状节点采集。仓库中的桌面 Web UI（ui）面向桌面浏览器，并未针对移动端形态优化。ADR-034 明确列出三个必须以手机/平板作为现场终端的需求场景：

1. 灾害响应（WiFi-MAT）：救援人员需要在坍塌建筑中可视化幸存者检测、呼吸/心率生命体征与分区地图；瓦砾堆中笔记本电脑不现实，而救援者口袋中的手机是天然形态。
2. 建筑安防：巡逻安保需要手持设备查看按分区的占用情况、移动告警与历史规律。
3. 医疗监护：临床人员需要在床旁或护士站用平板查看基于 CSI 的非接触式生命体征，呼吸率与心率仪表须实时刷新。

三个场景有一个共同架构约束：移动设备不直接与 ESP32 节点通信，而是由 Rust 传感服务端（wifi-densepose-sensing-server，见 ADR-031）聚合 ESP32 UDP 流并通过 WebSocket API 暴露，移动 App 通过本地 WiFi 连接该服务端。

1.1 技术选型决策表

仓库中 package.json 印证了上述栈：expo ~55.0.4、react-native 0.85.2、zustand ^5.0.12、axios、react-native-svg、react-native-webview 13.16.0、react-native-wifi-reborn ^4.13.6、victory-native（图表）、react-native-reanimated 4.2.1与jest-expo。需要指出，实际 RN 版本（0.85.2）已高于 ADR 撰写时的 0.83，属于正常版本漂移。

1.2 与桌面 UI 的关系

桌面 Web UI 与移动 App在组件层面零代码共享，但消费同一套后端 API：

• WebSocket：流式下发SensingFrameJSON。
• REST：配置、历史、健康检查。

移动端 LiveScreen 的 Three.js 高斯泼溅查看器加载与桌面 UI 相同的 splat HTML bundle，在原生端放入 WebView、在 Web 端放入 iframe。仓库里对应 HTML 资产位于 src/assets/webview/gaussian-splats.html（MAT 仪表盘为 mat-dashboard.html）。

2. 决策：五屏现场操作架构

ADR 决定在ui/mobile/构建一个 Expo React Native App，为现场操作者提供五个主屏幕，通过 WebSocket 流连接 Rust 传感服务端；当服务端不可达时自动降级为模拟数据，支撑演示与离线测试。

2.1 屏幕架构

MainTabs (Bottom Tab Navigator) ├── Live 3D Gaussian splat + HUD ├── Vitals 呼吸 + 心率仪表 ├── Zones 楼层平面 SVG + 占用热力 ├── MAT 灾后响应（幸存者计数 + 告警） └── Cog （设置） ConnectionBanner（Connected / Simulated / Disconnected）

目录src/screens/下五个子目录（LiveScreen/、VitalsScreen/、ZonesScreen/、MATScreen/、SettingsScreen/）与之一一对应。ui/mobile/README.md 补充了每个屏幕的运行时语义：Vitals 正常范围为呼吸 6–30 BPM、心率 40–120 BPM，含 60 样本 sparkline 历史；MAT 屏幕按 START 分诊分类（Immediate / Delayed / Minor / Deceased）分组展示幸存者计数。

2.2 状态架构：三个 Zustand Store

三个 Zustand Store 分离关注点并避免无谓重渲染：

• poseStore：connectionStatus、最新帧、帧历史 RingBuffer、特征向量、人员、生命体征。实际实现见 poseStore.ts，状态字段为connectionStatus / isSimulated / lastFrame / rssiHistory(60 样本 RingBuffer) / features / classification / signalField / messageCount / uptimeStart，并提供handleFrame统一入口。
• matStore：幸存者、告警、事件、分区地图。
• settingsStore（AsyncStorage 持久化）：服务端 URL（默认http://localhost:3000）、主题、RSSI 开关、模拟模式。

值得注意的实现演进：ADR 设想的三态connected / error / simulated在真实代码中被四态取代——sensing.ts 定义ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'simulated'，粒度更细，可供ConnectionBanner与测试精确驱动。

2.3 服务层

RSSI 平台文件采用 React Native 文件解析约定（.android.ts/.ios.ts/.web.ts）：

2.4 数据流与连接生命周期

ESP32 Mesh Nodes │ UDP CSI 帧（ADR-029 TDM 协议） ▼ +---------------------------+ │ Rust Sensing Server │ wifi-densepose-sensing-server (ADR-031) │ 聚合 ESP32 流 / 运行 │ │ RuvSense 管线 │ │ 暴露 WS + REST │ +---------------------------+ │ │ │ WebSocket │ REST │ host:3001 │ host:3000 ▼ ▼ +---------------------------+ │ Expo Mobile App │ │ ws.service → poseStore │ │ 屏幕经 Zustand selector 订阅│ +---------------------------+

连接生命周期（来自 ADR，与实际代码一致）：

1. App 启动，settingsStore从 AsyncStorage 加载持久化的服务端 URL。
2. ws.service建立 WebSocket 连接。
3. 每收到一条消息即解析SensingFrameJSON 并派发至poseStore。
4. 连接失败按指数退避重试（1s、2s、4s、8s、16s 封顶）。
5. 达到最大重试次数后切换至simulation.service，以约 10Hz 生成合成帧。
6. poseStore.connectionStatus沿disconnected → connecting → connected / simulated迁移。
7. ConnectionBanner在所有屏幕反映当前状态。
8. 服务端恢复可达时，ws.service自动重连并恢复实时数据。

对照 websocket.ts 源码，有两个与 ADR 蓝图的差异值得记录：

• ADR 设想的端点/ws/sensing实际落地为WS_PATH = '/api/v1/stream/pose'（与 api.ts 中其余/api/v1/...资源一致）。
• ADR 写的MAX_RECONNECT_ATTEMPTS = 5在代码中是10，重连延迟表即RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 16000]（超过表长的重试循环使用末值）。

此外ws.service.ts实现了 URL 归一化：buildWsUrl()将http:升为ws:、https:升为wss:，并丢弃原 URL 路径而拼接WS_PATH；disconnect()使用 code1000区分「客户端主动断开」与「意外断线」，避免主动关闭触发无谓重连。

2.5 SensingFrame 帧契约

ADR 描述的帧对应 RustSensingFrame结构（设计态）：

interface SensingFrame { timestamp: number; // Unix epoch ms amplitude: number[]; // Per-subcarrier amplitude (52 or 114 values) phase: number[]; // Per-subcarrier phase (radians) features: { mean_amplitude; std_amplitude; phase_slope; doppler_shift; delay_spread; }; classification: string; // "empty" | "single_person" | "multi_person" | "motion" confidence: number; // 0.0 - 1.0 persons: Array<{ id; keypoints: Array<[x,y,conf]>; bbox; track_id; }>; vital_signs?: { breathing_rate_bpm; heart_rate_bpm; breathing_confidence; heart_confidence; }; rssi?: number; node_id?: number; }

实际落地版（sensing.ts）经过明显演进，与传感服务端当前协议对齐：

• 顶层为nodes: SensingNode[]（每节点node_id / rssi_dbm / position / amplitude / subcarrier_count）、features: FeatureSet、classification: Classification、signal_field: SignalField（3D 体素网格）、可选vital_signs、pose_keypoints、persons、posture、signal_quality_score与estimated_persons。
• features采用mean_rssi / variance / motion_band_power / breathing_band_power / spectral_entropy等频带功率指标，替代 ADR 初稿的载波幅相描述。
• classification为{ motion_level: 'absent'|'present_still'|'active'; presence: boolean; confidence }。
• VitalsData同时兼容两种字段命名：新命名breathing_bpm / hr_proxy_bpm与 Rust 服务端命名breathing_rate_bpm / heart_rate_bpm / breathing_confidence / heart_confidence（源码注释明确 "Rust sensing server uses these field names"），体现前后端契约的平滑过渡。

这种向后兼容的字段定义说明SensingFrame是前后端协商演进的活契约；ADR 的 6.3 风险表亦提议在帧中增加protocol_version字段以版本化 WebSocket 协议。

3. 3D 高斯泼溅渲染与设计系统

3.1 LiveScreen 的 Two-Path 渲染

LiveScreen 用 WebView（原生）/ iframe（Web）渲染 Three.js 高斯泼溅场景，避免原生 OpenGL 绑定并复用桌面渲染器（HTML 资产见 gaussian-splats.html）：

• 原生路径：GaussianSplatWebView.tsx 加载打包 HTML；React Native 与 WebView 通过postMessage/onMessage桥通信；useGaussianBridge.ts 管理桥并将骨架关键点以 JSON 下发。
• Web 路径：GaussianSplatWebView.web.tsx 渲染同款 bundle 的<iframe>，用带 origin 校验的window.postMessage通信。

WebView 桥的通用逻辑抽为 useWebViewBridge.ts。

3.2 设计系统 Token

深色为默认主主题，针对野外光照（低环境光、抗眩光）优化；浅色主题变体可在 Settings 屏幕切换。Token 定义文件位于 theme/colors.ts、theme/spacing.ts、theme/typography.ts，由 ThemeContext.tsx 通过 React Context 提供。

4. ESP32 集成模型与网络拓扑

移动 App不与 ESP32 节点直接通信：

ESP32 Node A ---\ ESP32 Node B ----+---> Sensing Server（Raspberry Pi / 笔记本）<---> Mobile App ESP32 Node C ---/ （本地 WiFi） （本地 WiFi）

• 现场部署：传感服务端运行于树莓派 4 或操作者笔记本；ESP32 节点、服务端、移动 App 全部连入同一本地 WiFi 或便携路由器。
• 服务端 URL：Settings 屏幕可配置；默认http://localhost:3000（REST）与 WebSocket 端口 3001。现场一般改为服务端 LAN IP，如http://192.168.1.100:3000。URL 输入组件带实时校验与连接测试（ServerUrlInput.tsx 通过validateServerUrl校验、点击 Test Connection 调用/api/v1/pose/status测延迟并回显毫秒数），非法 URL 边框与文案即时标红。
• 无 BLE/直连：ESP32 以 UDP 广播 CSI 帧（见 ADR-029）；移动 App 不设 UDP 监听，只消费服务端处理后的输出。

5. 目录结构与工程形态

ui/mobile/顶层包含App.tsx（根组件）、app.config.ts、app.json、eas.json（dev/preview/production 构建档）、index.ts、jest.config.js、metro.config.js、tsconfig.json，以及assets/、e2e/、src/。src/内按components（12 个共享组件，含 ADR 清单之外额外出现的LoadingSpinner等）、constants、hooks、navigation、screens、services、stores、theme、types、utils与镜像源码结构的__tests__/组织。为后续需求新增的实现还包括 MATScreen 的SimulationBanner与SimulationWarningOverlay（模拟态在 MAT 场景的显式提示）。

工程数量统计：源码 63 个.ts/.tsx；单元测试约 25 个测试文件（实际 src/tests下含 stores/services/components/hooks/screens/utils 六个类别及测试工具与 mock）；Maestro E2E 6 个 YAML spec（e2e/ 下live_screen、vitals_screen、zones_screen、mat_screen、settings_screen、offline_fallback）；7 个配置文件；6 个图标/启动图资产。

6. 实施计划与验收标准

ADR 给出五阶段文件级计划：Phase 1 Core Infrastructure（App.tsx、index.ts、theme、navigation、types/sensing.ts）、Phase 2 State and Services（三个 store + 四服务 +ringBuffer/urlValidator）、Phase 3 Shared Components（12 个共享组件）、Phase 4 Screens（五屏细分组件）、Phase 5 Testing（store/service/component/hook/screen/utils 各层测试 + E2E），并按 P0–P2 优先级排列，全部与上文目录结构吻合。

验收标准可按组解读为可直接照做的检查清单：

• 构建与平台（B-1~B-5）：npx expo start三端可跑；TS--noEmit零错误。
• 流与数据（W-1~W-5）：连接后connectionStatus === 'connected'；帧派发 <100ms；退避序列 1/2/4/8/16s；断连后 5s 内进入simulated；服务端重启可无崩溃恢复。源码层面MAX_RECONNECT_ATTEMPTS实为 10 次，退避表与 ADR 一致。
• 屏幕渲染（S-1~S-7）：五屏在实时与模拟数据下均可渲染；仪表平滑动画；splat 显示骨架；floor plan 随人员注入更新标记；MAT 面板数据驱动；banner 三态文案/颜色正确。
• 持久化（P-1~P-3）：设置跨重启保留；无持久化值时默认http://localhost:3000；URL 校验拒绝not-a-url、接受http://192.168.1.1:3000。
• 导航与 UX（N-1~N-4）：底部 Tab 五标签导航正确；深色主题三端一致；处理 1000 帧无内存泄漏（不超 ring buffer 上限）；ErrorBoundary 兜底渲染。
• 平台特性（R-1~R-3）：Android RSSI 需授权后扫描；iOS 返回空数组不崩溃；Web 返回合成数据。
• 测试（T-1~T-4）：npm test全绿；maestro test e2e/全过；TS 零类型错误。

仓库侧的执行证据：五屏均有独立单测（如 LiveScreen.test.tsx），核心服务ws.service、simulation.service、api.service、rssi.service各配测试，poseStore测试覆盖状态迁移与帧处理。

7. 快速上手：安装、运行与连接

ui/mobile/README.md 给出完整入门路径（无需传感服务端即可体验）：

# Web 预览最快（约 30 秒） cd ui/mobile npm install npx expo start --web # 打开 http://localhost:8081，自动进入模拟模式 # Android（需模拟器或装有 Expo Go 的真机） npx expo start --android # iOS（需 Xcode 模拟器或 Expo Go；RSSI 需 wifi-info entitlement） npx expo start --ios

运行时依赖建议：Node.js 18+、npm 9+、Android 模拟器 API 33+、iOS Xcode 15+。测试执行：npm test（jest-expo）；E2E 使用 Maestro CLI 运行maestro test e2e/。

连接服务端时按场景配置 Settings 中的 Server URL：

REST API 面（constants/api.ts 与 README 的实测端点）：

api.service基于 Axios，5 秒超时、2 次自动重试。服务端不可达时，App 在耗尽重连次数后进入模拟模式，连接横幅出现黄色SIM徽标，服务恢复后自动重连。

8. 后果、权衡与风险

8.1 正面收益

• 单代码库三平台：同一 TypeScript 源码产出 iOS/Android/Web，相对分立原生 App 显著降低开发维护成本。
• 分钟级现场部署：开发期用 Expo Go、生产用 EAS Build 安装后即可连接本地服务端，无需移动端服务端基础设施。
• 近实时显示：WebSocket 流相对 CSI 处理管线新增 <100ms 显示延迟。
• 离线可演示：模拟服务生成逼真合成帧，无 ESP32 硬件或运行中的服务端也能向干系人演示。
• 可测试架构：Zustand selector 订阅 + 服务层抽象 + Maestro E2E，贯通单元/集成/端到端。
• 复用现有设施：消费与桌面 UI 相同的 WS/REST API，后端零改动；splat 渲染器经 WebView 复用。

8.2 负面与限制

• WebView 内 3D 渲染弱于原生 OpenGL：多一层 JS↔Native 桥跳转，中端机型约 30 FPS（原生 Metal/Vulkan 可达 60 FPS 但需平台专属代码）。
• Android RSSI 需原生模块链接，破坏纯 Expo 托管工作流，Android 构建必须走 EAS Build 自定义开发客户端；iOS 因 Apple 限制根本无法扫描。
• Expo 托管工作流限制部分原生 API（后台定位、BLE、裸 WiFi 帧），未来如 BLE mesh 回退需 eject 到 bare 工作流。
• WebViewpostMessage桥每消息 5–15ms 延迟，对 10–20Hz 帧率可接受，更高帧率将成瓶颈。
• AsyncStorage 无加密，凭据类数据应改用 expo-secure-store。

8.3 风险与缓解

9. 未来演进方向

• 离线模型推理：以onnxruntime-react-native在端上运行量化 ONNX 姿态模型（前置：导出 ADR-023 模型、INT8 量化、真机延迟基准），实现无服务端的全离线作业。
• MAT 告警推送：Firebase Cloud Messaging / APNs 推送新幸存者或危急生命体征告警（前置：服务端加推送端点、App 集成 Expo Notifications）。
• Apple Watch 伴随：watchOS 极简生命体征视图 + 关键告警触觉反馈。
• BLE Mesh 回退：WiFi 不可用时用 BLE mesh 转发聚合 CSI 摘要（前置：ADR-018 固件 GATT、react-native-ble-plx、低带宽压缩摘要协议；需 eject 到 bare 工作流）。
• 多服务端聚合仪表盘：同时连接多个传感服务端（每层/每翼一个），统一分区地图与 MAT 面板（前置：settingsStore支持服务端列表、ws.service多连接、按server-id合并帧）。

10. 相关 ADR 关系矩阵

一言以蔽之：ADR-034 的价值在于它把「桌面传感仪表盘」重构为「面向废墟、走廊与病床的掌上传感终端」。它以清晰的五屏导航、Zustand 三 store、可插拔服务层与自动化模拟回退，让 RuView 的空间感知能力真正走出机房与实验室——而仓库中 ui/mobile 的完整实现则证明这套架构蓝图是可运行、可测试、可持续演进的活代码。

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView