# STEP-060 RN Test Host 与 WeatherRuntime 薄桥接 — Codex 完成报告

状态：`IMPLEMENTED / WAITING_ANDROID_VALIDATION`

Starting HEAD：`b535d98263af58ac86845f15bb7c51bd85b59519`。

## 实际完成内容

1. RN Test Host 最终目录为 `integration/react-native/MapLibreParticleRNTestHost/`。固定 RN `0.85.2`、React `19.2.5`、Expo `56.0.4`、TypeScript `5.9.3`、MLRN `11.3.6`；New Architecture 已由 Expo config 请求，但 Android prebuild/生成工程尚未验证。
2. MLRN `11.3.6` 实际 Android `build.gradle` 按 root extra `org.maplibre.reactnative.nativeVersion/nativeVariant` 解析 `android-sdk-<variant>`。Test Host config plugin 固定 `13.4.1`/`opengl`。
3. STEP-060B 将 plugin 的 Maven Central 排除收敛为 custom module `org.maplibre.gl:android-sdk-opengl`，并将 Maven Local 排在首位。因此 custom `android-sdk-opengl:13.4.1` 缺失即依赖失败，不会从普通官方 SDK fallback；MLRN 的独立 turf/annotation/scalebar artifacts 不会因全 group 排除而失去正常来源。artifact 的字节来源仍须用户手工发布/检查。
4. MLRN 的共享 `ReactTagResolver` 实例由 `MLRNPackage` 私有持有，不能安全注入外部模块。Bridge 没有复制其 `mViews`：使用 React Native/Fabric 的公开 `UIManagerHelper.getUIManager(...).resolveView(reactTag)`，验证结果是具体 `MLRNMapView`。
5. 从该具体 View 读取 MLRN 公开只读 `mapLibreMap`；不存在 global/current map。
6. `MapLibreMap` 新增唯一 map-owned `WeatherRuntime` attachment seam。Bridge 不维护 Map→Runtime 表：style replacement 通过 `MapLibreMap.setStyle()` dispose，View detach listener dispose，React `useEffect` unmount 也调用 detach；下一次 style ready attach 必定创建新 facade。
7. style ready 前分别 fail-closed 为 `MAP_NOT_READY` 或 `STYLE_NOT_READY`；source/layers 缺失为 `WEATHER_OBJECTS_NOT_READY`。不存在/已 drop tag 为 `MAP_VIEW_NOT_FOUND`，已 dispose runtime 为 `RUNTIME_DISPOSED`；参数问题为 `INVALID_ARGUMENT`，facade throw 为 `NATIVE_REJECTED`。
8. Style JSON 由 Test Host 预先创建 background、host-field `RasterArraySource`、WeatherColorLayer、RasterParticleLayer。Bridge 不创建 Weather 私有 Style registry；style reload 后由 MLRN style event 的 attach 重建。
9. Phase A 五项均完成：`getState`、`setWeatherEnabled`、`setWeatherColorVisible`、`setParticleVisible`、`setTargetFps`。
10. Phase B 完成：epoch-ms `setForecastTime`、playback state/speed、ColorStop list、独立 particle/trail RGBA、particle count/line width/length/opacity、trail opacity/fade、WeatherColor opacity 与 native snapshot。未完成：Binary Field、JSI/zero-copy、provider/network、NavSea 正式接入、iOS bridge。
11. 为 snapshot 增加唯一最小 getter `WeatherRuntime.getPlaybackState()`；`state`、target FPS、disposed 均为既有 native 权威值，Bridge 不缓存播放/runtime state。没有 Adapter、Normalizer、第二 registry 或 renderer 改动。

## 修改/新增文件

- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java`
- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java`
- `integration/react-native/MapLibreParticleRNTestHost/`（Expo Test Host、Android TurboModule、style、README、lock/config plugin）
- `docs/50_Step记录/STEP-060_RNTestHost与WeatherRuntime薄桥接_v1.md`
- `docs/60_测试/STEP-060_RNTestHost_Android人工编译与验收_v1.md`
- `粒子开发记录.md` 与本报告。

## API 与生命周期

```text
JS typed TurboModule + reactTag
  → Fabric UIManager resolveView(tag)
  → concrete MLRNMapView.mapLibreMap
  → MapLibreMap.replaceWeatherRuntime(config)
  → WeatherRuntime typed command
```

Bridge 不接触 T0/T1/MIX/timeline integer command。`setForecastTime` 只接收 non-negative integral epoch milliseconds；ColorStop 限有限 RGBA `[0,1]` 与严格递增 speed；particle/trail color 独立于 WeatherColor ramp。无 `number[]`、JSON 数组、base64 或 Binary Field contract。

## 实际验证

- `npm install --package-lock-only --ignore-scripts --legacy-peer-deps --no-audit --no-fund`：PASS，生成/核对 lock。
- 构建输出节流下 `npx tsc --noEmit`：PASS。
- `node --check plugins/withParticleNativeAndroid.js`、版本/lock 一致性检查、禁止边界搜索：PASS。
- `git diff --check`：PASS。

## 未执行与风险

没有执行 Android Gradle、custom artifact publish、APK/AAB、ADB、安装、App launch、模拟器/真机或 Jest。故 Android codegen/TurboModule 的实际 Java/Kotlin 编译、MLRN autolinking project name、Maven Local artifact provenance、Fabric event target、style reload/remount 的时序和 Handler/renderer 行为均仍待人工验收。详细步骤在 `docs/60_测试/STEP-060_RNTestHost_Android人工编译与验收_v1.md`；包括 custom SDK build/publish、Test Host build/install、地图、同 reactTag 的五个 Phase A 命令、Phase B、style reload、old tag fail-closed、remount/unmount。

## Git

- 功能 commit：`4c906b21fbc9834699c5dcd62e551b05b2526c53`（`feat: add RN WeatherRuntime bridge test host`）
- 文档 commit：`5c6fa2c668a6fef76a87820672ae84e178aea403`（`docs: record STEP-060 RN bridge test host`）
- Push：待本报告元数据收尾 commit 后推送至 `origin/particle/main`。
- Final HEAD / Remote HEAD：由本报告元数据收尾 commit 与 push 后的交付消息给出。