MapLibreParticleLab/docs/50_Step记录/STEP-057_AndroidHost天气运行时接口基础_v1.md

STEP-057 Android Host 天气运行时接口基础

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION。

Starting HEAD：faf7548220e9a1282275711c236987f7faedfa03，分支 particle/main。

已实现：Android WeatherRuntime typed facade；canonical byte[] submit result enum；clear fields；timestamp seek；play/pause/0.5/1/2x；独立 visibility；OFF unload；WeatherColor 8-stop dynamic ramp；独立 particle/trail RGBA；Android→JNI→C++ 接线；REAL WEATHER Test App submit/playback 改走 facade。

Core 保持 canonical U/V、Timeline、Runtime Field Window、T0/T1 interpolation 和 Renderer 架构边界。正常窗口边界的 GPU content reuse 路径未改变；normal seek 不改变 window revision，跨窗口仍由既有 revision 驱动 reuse。

OFF 会停止 Timeline、clear Host ownership，并在 Render 线程的空 Source path 清理 layer drawables、particle State/Trail/draw targets、field textures 和 WeatherColor resources。结构化日志包括 TIMELINE_STOP、FIELD_WINDOW_CLEAR、SNAPSHOT_CLEAR、PARTICLE_RESOURCE_RELEASE、TRAIL_RESOURCE_RELEASE、WEATHER_COLOR_RESOURCE_RELEASE。

本地验证：shader generator、Linux OpenGL mbgl-core、style_layer.test.cpp 与 source.test.cpp 精确编译；git diff --check。Android Gradle/APK/ADB/设备测试和 Jest 未运行。

未完成：Android 手工 T1–T13 验收，特别是 OFF resource log、ON 后重新 T0/T1、dynamic ramp/colour 无 field upload/particle reset、timestamp mid-point 和窗口边界回归。

STEP-057A 审计修正（2026-09-07）

状态保持 IMPLEMENTED / WAITING_ANDROID_VALIDATION。基于已推送 efaa3e61c 审计修正，不进入 STEP-058。

• 删除正式 WeatherRuntime.setParticleVisual(String, float)；改为 particle count、line width、length、particle/trail opacity、trail fade、speed-color enabled 的明确 typed 方法。Test App 的 fixture-only generic property 调试仍只留在低层路径。
• 修正 facade 状态：READY 重复 enable 幂等；DISABLED enable 进入 WAITING；ERROR 收到 pending T0 恢复 WAITING；initial window ready 进入 READY；clear/disable 只在对应 Core 成功时转入 WAITING/DISABLED。新增 Android 既有 JUnit state transition 定向测试源码，未按本轮限制执行 Gradle。
• RenderOrchestrator 不再对所有 hidden RasterArray layer 执行额外 prepare/update。RenderLayer 默认无 cleanup；仅仍持有资源、Host-field Source 已空的 RasterParticle/WeatherColor renderer 显式 opt-in，完成一次空场 GPU cleanup。普通 hidden layer 语义不变。
• Host stop capacity 改为由 JNI 读取 Core MaxWeatherColorStops；Host API 继续接受 ColorStop list，未暴露 UBO。严格验证与 particle/trail 独立性保持。
• timestamp 测试改为 epoch milliseconds（2024-01-01 UTC 起的 64-bit ms），覆盖 exact T0、midpoint、exact T1、上下界 out-of-range 与 clear 后 fail-closed。

验证：output-throttle 下 shader generator、Linux OpenGL mbgl-core、mbgl-render、mbgl-test-runner、相关精确 Source/Style compile 和定向非 Jest tests 均 PASS；git diff --check PASS。Android Gradle/APK/ADB/设备/Jest 未运行。

STEP-057B 状态语义修正（2026-09-07）

状态：IMPLEMENTED / WAITING_CODE_REVIEW。

基于 dad6876c72f29e2d5671677ee15e13cd25e653a1，本轮只修改 WeatherRuntime 与状态测试/记录：普通 REJECTED_ADAPTER、REJECTED_INCOMPATIBLE、REJECTED_NON_MONOTONIC、REJECTED_CAPACITY 和空 metadata/payload 保持当前 state；REJECTED_SOURCE_MODE、UNKNOWN 才进入 ERROR。pending T0、initial window、next snapshot、duplicate 的成功/保持语义不变。

READY + enable(true)、WAITING_FOR_FIELDS + enable(true) 为幂等 no-op；DISABLED + enable(true) 成功恢复到 WAITING；ERROR enable 明确返回 REJECTED 并保持 ERROR。clear/disable 成功与失败转换保持原有契约，DISABLED 重复 disable 仍为成功 no-op。

WeatherRuntimeStateTest 已覆盖普通 rejection 保持 READY/WAITING、真正错误、所有 enable 分支、clear/disable，以及 public flow 的 invalid submit 和 ERROR enable。public flow 测试源码已加入现有 Mockito/JUnit 体系，但本轮未运行 Android Gradle；因此仍需代码审计后统一 Android 验收。