MapLibreParticleLab/docs/50_Step记录/STEP-057D_WeatherRuntime接口收尾与RN桥接前冻结_v1.md

STEP-057D WeatherRuntime 接口收尾与 RN 桥接前冻结

状态：IMPLEMENTED / READY_ANDROID_COMPILE_CHECK

基线：01295df4b814562f569375e7e7cf1f48ce35388f，分支 particle/main。

目标与范围

本 Step 只收紧 Android Host WeatherRuntime 公共接口，为后续 RN 薄桥接冻结边界；不实现 RN/TurboModule/JSI，不修改 provider、Timeline、Runtime Field Window、canonical field、shader、UBO 或 renderer 架构。

已完成

• 新增 WeatherRuntime.setParticleColor(r,g,b,a) 与 setTrailColor(r,g,b,a)，分别通过 JNI 进入 Core 的独立 RasterParticleLayer::setParticleColor / setTrailColor。两者不提交 field、不影响 WeatherColor ramp、不重置 Timeline 或粒子模拟。
• 保留 setParticleColors(...) 作为兼容 helper，继续使用原子成对底层提交；新 Host/RN 契约使用两个独立 typed 方法。Core 既有 particleColor=(0.08,0.55,1,1)、trailColor=(1,1,1,1) 默认值不在 facade 重建或猜测。
• REAL WEATHER 数据提交改用 WeatherRuntime.FieldSubmitResult 与 accepted()/enum 名称，不再用 getCode() 或整数比较组织正常 Host 路径。
• REAL WEATHER playback/visual 正常路径遇到不支持命令或 property 时不再回退到 MapLibreMap 低层调用。旧 fixture、HOST、diagnostic time-mix/field-window 入口保留为 legacy/diagnostic 路径。
• 增加独立颜色 API 的现有 JUnit/Mockito 定向源码覆盖，包含独立调用、参数隔离和 native rejection fail-closed。

低层入口审计

• A 类（REAL WEATHER）：field submit、play/pause/speed、已支持粒子视觉属性均经 WeatherRuntime；独立 particle/trail color 也经 WeatherRuntime。
• B 类（legacy/diagnostic）：fixture/HOST INVALID/DUPLICATE、ADVANCE WINDOW、time-mix 及旧诊断 property 仍可直接使用 MapLibreMap，仅供既有验证工具，不构成未来 RN contract。

验证与未执行

• 已执行 git diff --check 与源码静态审计（typed API、getCode() 使用、REAL WEATHER fallback 边界）。
• 未执行 Android Gradle/APK、ADB、设备/虚拟机测试或 Jest；Android compile check 留待后续统一授权。

剩余风险与下一步

JNI/Android Java 编译及 Mockito 配置仍需 Android compile check；设备上的独立颜色视觉效果和 style reload/资源生命周期需后续人工验收。代码边界已冻结，可进入 RN 薄桥接前独立审计。