docs: record STEP-055 viewport density fix

docs/报告/STEP-055_Android真实WeatherV2风场综合可视化_Codex完成报告_v6.md

@@ -0,0 +1,35 @@
+# STEP-055 Android 真实 WeatherV2 风场综合可视化 Codex 完成报告 v6
+
+Starting HEAD / remote：`d9a9c8ed57605abca86893ba7fb3b5265db3c0dc`，`origin/particle/main`。
+
+本任务只调整 zoom 后的 viewport particle density；未修改功能范围外的数据链或 UI。
+
+## 实现
+
+`RenderRasterParticleLayer` 以当前 TransformState 的 viewport 四角取得 unwrapped Web Mercator AABB，按宽高各扩展 15%，然后与 canonical `fieldBounds` 求交。交集有效且 camera stable（沿用 150ms Trail debounce）时，该交集作为独立 `respawnBounds`。交集为空、无效或 extent 过小时，回退 full field bounds。
+
+新增 UBO `respawnBounds`，并以 `fieldScale.z` 传递 `viewportDensityActive`。Field sampling、UV grid 映射和 U/V decode 始终使用 `fieldBounds`；viewport bounds 不参与 Field 采样。State shader 在 existing invalid/out-of-field/age-expired 条件外，仅于 `viewportDensityActive` 时将 expanded viewport 外 slot 标记为 respawn candidate。复生仍复用既有 hash、三次有效 Field sample、age=0 和首帧 alpha=0；没有 CPU readback、全体 reseed、均匀网格或 zoom-based particleCount。
+
+camera moving 时，`viewportDensityActive=false` 且 respawn domain 固定为 full field，避免交互期间强制 viewport respawn。相机稳定后启用 viewport domain；`ParticleDensity` 低频日志输出 zoom、mode、margin、respawnBounds、fieldBounds、fallback 与 configuredSlots。resize 与普通 camera transform 的 Trail 语义保持 v8：只有 resize 重分配 Trail target。
+
+## 修改文件
+
+- `src/mbgl/renderer/layers/render_particle_validation_layer.cpp`
+- `shaders/particle_gpu_validation.vertex.glsl`
+- `shaders/particle_gpu_validation.fragment.glsl`
+- `include/mbgl/shaders/particle_gpu_validation_ubo.hpp`
+- `include/mbgl/shaders/gl/particle_gpu_validation.hpp`（generator 输出）
+
+未修改 State A/B Float、Trail A/B UnsignedByte、previous→current segment、zoom-aware speed、wall-time lifecycle、canonical Field、WeatherV2 assets、Host Submission、Timeline、Runtime Window、WeatherColorLayer 或 REAL WEATHER UI。
+
+## 验证
+
+- shader generator：PASS。
+- Linux OpenGL 精确编译 `render_particle_validation_layer.cpp`：PASS。
+- 既有非 Jest `style_layer.test.cpp` 精确编译：PASS。
+- `git diff --check`：PASS。
+- Android Gradle/APK/ADB/设备与 Jest：未执行。
+
+功能提交：`f8e715d080d69db779fe37ea7a5aa37c0f7c42c4`（`fix: keep particle density stable across zoom`），已成功 push 至 `origin/particle/main`。本报告随后以独立文档提交记录，不改变功能实现。
+
+最终状态：**IMPLEMENTED / WAITING_ANDROID_VALIDATION**。