MapLibreParticleLab/docs/报告/STEP-057_AndroidHost天气运行时接口基础_Codex完成报告_v2.md

STEP-057A Android Host 天气运行时接口审计修正 — Codex 完成报告

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION。本轮仅修正 STEP-057，不进入 STEP-058、React Native bridge 或性能任务。

实际修正

1. WeatherRuntime 删除公开 setParticleVisual(String, float)。正式 API 改为 setParticleCount、setParticleLineWidth、setParticleLength、setParticleOpacity、setTrailOpacity、setTrailFade、setParticleSpeedColorEnabled；Core property 语义未改。Test App 的未映射 fixture diagnostic 才可使用低层 generic setter。
2. 状态转换被收敛为可单测函数：READY enable 幂等；DISABLED 成功 enable → WAITING；ERROR 成功 pending field → WAITING；initial window ready/next snapshot → READY；成功 clear → WAITING；成功 disable → DISABLED。新增 WeatherRuntimeStateTest，使用现有 Android JUnit 体系；遵从任务限制未运行 Gradle。
3. 取消 RenderOrchestrator 的所有 hidden RasterArray 层全局 prepare/update。新增默认关闭的 RenderLayer::needsHiddenLayerSourceCleanup；只有持有 GPU resource 且 Host-field source 已清空的 RasterParticle/WeatherColor layers opt-in，才在 hidden 时接收一轮 cleanup。普通 hidden MapLibre layer 生命周期不变。
4. stop 上限继续由 C++ MaxWeatherColorStops=8 定义。Java 经 JNI 获取 capacity，facade 以 ColorStop list 验证，不暴露 UBO 数组。严格 speed/RGBA 校验和独立 particle/trail color 保持。
5. Source timestamp tests 现在使用 epoch milliseconds：T0=1704067200000、T1=1704070800000，验证 exact T0、midpoint、exact T1、lower/upper out-of-range 与 clear 后 fail-closed。

既有 clear/unload、JNI、Core-owned T0/T1/MIX、dynamic ramp、独立颜色、field/window reuse、无 style reload 均保留。正常 window boundary 的 OLD_T1→NEW_T0 / only NEW_T1 upload 路径未改；本轮没有触及 simulation/trail reset 条件。

验证

所有编译、codegen 和测试均经 build-output-throttle wrapper，日志仅存 /tmp/step057a-logs/，未提交。

• shader generator：PASS。
• Linux OpenGL mbgl-core：PASS。
• Linux OpenGL mbgl-render：PASS。
• Linux OpenGL mbgl-test-runner：PASS。
• style_layer.test.cpp / source.test.cpp 精确编译：PASS。
• 定向非 Jest tests（timestamp seek、clear、WeatherColor stop validation、particle/trail properties）：PASS。
• git diff --check：PASS。

未执行：Android Gradle、APK build、ADB、Android device validation、Jest。

Git

• 审计起点：efaa3e61c94e056bf06a955eb250cdfdc1633ecd
• 功能提交、文档提交、push 和 Final HEAD：在完成提交后以最终交付结果为准。

Android 后续人工验收仍需重点检查 OFF hidden cleanup logs、READY 重复 ON、ERROR→pending→WAITING、dynamic stop/colour 无 field upload/reset、epoch-ms seek 与正常 window boundary simulationRebuild=false / trailCleared=false。