# MapLibreParticleRNTestHost

这是 MapLibreParticleLab 的独立 React Native 验证宿主，不是 NavSea 业务应用。当前用途是验证 `@navsea/maplibre-particle-rn@13.4.1-particle.3` 与 Native `13.4.1-particle.3` 的 Android OpenGL / QBIN V4 链路。

## 当前版本

- RN package：`@navsea/maplibre-particle-rn@13.4.1-particle.3`
- Native：`cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.3`
- MLRN：`11.3.6`
- React Native：`0.85.2`
- package：`org.maplibre.particle.rntesthost`
- Android 测试设备：`192.168.1.146`

`.2`、Maven Local handoff、`D:\V308` 等只属于历史 Step，不是当前正常构建入口。

## QBIN V4 Golden Fixture

`assets/qbin-golden/` 固化 8 个 raw QBIN：Wind、Wave、Current、Rain 各 T0/T1。`src/qbinGoldenFixtures.ts` 定义 field identity、profile contract、validTime、SHA 和 Binding。

V4 页面实际调用：

```text
FieldRuntime.submitEncodedField
FieldRuntime.setEncodedColorBinding
FieldRuntime.setEncodedParticleBinding
FieldRuntime.setEncodedForecastTime
FieldRuntime.setEncodedForecastPlaybackState
FieldRuntime.setEncodedForecastPlaybackSpeed
FieldRuntime.clearEncodedField
```

Android Native 链路最终进入 `RasterArraySource::submitEncodedField(...)` 与 `QbinV2Decoder::decode(...)`。因此 V4 验证不是 JS 解码 QBIN。

Test Host 仍保留 V3 canonical 控件作为历史兼容/对照，不代表 NavSea 新接入应继续使用 V3。

## Metro fixture 配置

`metro.config.js` 注册 `.f32`、`.u8`、`.qbin`，并自动探测 `particle-v3-fields`：仓库内运行时使用 `integration/react-native/particle-v3-fields`；独立 Win11 Host 复制到 `D:\React\MapLibreParticleRNTestHost-V4` 时可使用同级 `D:\React\particle-v3-fields`。

## Windows 构建

正常消费路径必须来自公网 pbf：RN tgz 从 `https://pbf.jpcn.ccwu.cc/npm/` 安装，Native Gradle 从 `https://pbf.jpcn.ccwu.cc/maven` 解析。Windows 不编译 Native AAR，也不以 Maven Local/LAN AAR 作为正常路径。

仓库内 Test Host 的 `package.json` 保留 `file:../../../packages/maplibre-particle-rn`，用于同仓源码开发；**正式 Win11 发布物验证时必须显式安装公网 tgz 覆盖该开发依赖**，以证明发布包本身可独立消费。

不要在 `V:\` 等盘符根目录执行 Expo prebuild；使用普通子目录，例如：

```text
D:\React\MapLibreParticleRNTestHost-V4
```

第一次生成 Android 工程时确保 `android/local.properties` 或 `ANDROID_HOME`/`ANDROID_SDK_ROOT` 指向实际 Android SDK。

完整 Linux AAR 发布、Win11 npm/Gradle 构建步骤以 `docs/50_Step记录/STEP-080_Android_AAR与RNTestHost标准构建流水线_v2.md` 为准。

## Metro 与 ADB

Metro 固定监听 Win11 `8091`：

```powershell
npx expo start --port 8091 --clear
```

Debug App 仍连接设备 `localhost:8081`，所以正确 reverse 只有：

```powershell
adb -s 192.168.1.146 reverse tcp:8081 tcp:8091
```

安装/启动可使用 `scripts/05-install-and-run.ps1`。脚本固定设备、package、activity，并按 `8081 → 8091` 设置 reverse。

## 当前人工验收

2026-09-14 已完成 Win11 Debug APK 构建、安装、Metro bundle 和人工功能验证。V4 Wind/Wave/Current/Rain 可加载；T0/midpoint/T1、PLAY/PAUSE、速度和 clear 可操作。midpoint 只证明 forecast-time command 接受；若没有 Native mix getter/日志，不把 UI 操作本身写成“已观测 mix=0.5”。

历史 STEP-060～072 过程与旧 V3/MavenLocal 证据保留在 `docs/`，但当前操作先读 `docs/00_项目总则/当前基线与开发路线_v2.md` 与 STEP-080 v2。