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

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION

Starting HEAD：b535d98263af58ac86845f15bb7c51bd85b59519。

实际完成内容

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/生成工程尚未验证。
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。
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 的字节来源仍须用户手工发布/检查。
MLRN 的共享 ReactTagResolver 实例由 MLRNPackage 私有持有，不能安全注入外部模块。Bridge 没有复制其 mViews：使用 React Native/Fabric 的公开 UIManagerHelper.getUIManager(...).resolveView(reactTag)，验证结果是具体 MLRNMapView。
从该具体 View 读取 MLRN 公开只读 mapLibreMap；不存在 global/current map。
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。
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。
Style JSON 由 Test Host 预先创建 background、host-field RasterArraySource、WeatherColorLayer、RasterParticleLayer。Bridge 不创建 Weather 私有 Style registry；style reload 后由 MLRN style event 的 attach 重建。
Phase A 五项均完成：getState、setWeatherEnabled、setWeatherColorVisible、setParticleVisible、setTargetFps。
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。
为 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 与生命周期

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 后的交付消息给出。

5.4 KiB Raw Permalink Blame History Unescape Escape