docs: record STEP-055 particle trail visual repair

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

@@ -0,0 +1,41 @@
+# STEP-055 Android 真实 WeatherV2 风场综合可视化 Codex 完成报告 v4
+
+Starting HEAD / remote：`97aa019f6ff07d1b91e17c46ad0e6e6c0cd339d5`，`origin/particle/main`。
+
+## 根因与修复
+
+当前代码确认：State RGBA Float 已工作，但 State 在越界/无效时回固定 seed，导致重复集中；B 是未充分使用的 age。particle vertex 又按 `position ± normalizedVelocity * streakLength` 生成固定 world 短线；Trail A/B 是 viewport-sized UByte texture，却由全球 world 坐标写入/按地图 world quad 采样。上述组合解释了密度衰减、边缘集中、缩放时粗短棍与闪烁。
+
+State A/B 仍为 Float，Trail A/B 仍为 UnsignedByte。正式 State pass 现在以 B 保存 simulation age，以 A 保存“本帧 segment 是否可连接”标记；越界、invalid、near-zero velocity 或 age≥3600 simulation seconds 时，使用 particle UV 与旧位置的 GPU hash 在 Field bounds 内至多三次采样有效位置。重生帧 A=0，因此 draw 丢弃 `oldPosition → newPosition`；下一次正常 advection 后才画 segment。
+
+Particle draw 现绑定 StateRead 与 StateWrite，直接画 `previousPosition → currentPosition`，并用当前 MapLibre `matrixForTile()` 投影到 Trail framebuffer。`streakLength` 保留公开 UI/API 兼容，但在正式真实天气路径不再主导 segment 长度。正式 Composite 改为单次 fullscreen view-space Trail 合成；相机 transform 改变时仅重建 Trail，记录 `CAMERA_RESET`，保留 State、Field、Timeline 与 Runtime Window。
+
+旧 fade 是每 render frame `trail *= trailFade`。新公式是 `fadeFactor = pow(trailFade, wallDeltaSeconds * 60)`：UI 值保持“60 FPS 单帧保留率”，而 30/60/120 FPS 都按相同 wall-time 指数衰减。Timeline Pause 不影响该 wall-time fade。
+
+visual clock 从 6000 降为 1200 simulation seconds/real second；典型 60 FPS 为 20 simulation seconds/frame。5 m/s 约 100 m/frame，在 z9 约 0.65 px；30 m/s 约 3.9 px，降低高风速跨帧跳跃与频繁越界风险，未改变 canonical m/s。
+
+## 架构影响
+
+未修改 canonical Field、WeatherV2 assets、Host submission、Timeline、Runtime Field Window 或 WeatherColorLayer。正常 forecast boundary 的 reuse、NEW_T1-only upload、`simulationRebuild=false`、`trailCleared=false` 保持；camera Trail reset 与 forecast boundary 的 Trail 语义明确分离。
+
+修改文件：
+
+- `src/mbgl/renderer/layers/render_particle_validation_layer.cpp`
+- `shaders/particle_gpu_validation.vertex.glsl`
+- `shaders/particle_gpu_validation.fragment.glsl`
+- `include/mbgl/shaders/gl/particle_gpu_validation.hpp`（generator 输出）
+
+## 验证
+
+- `node shaders/generate_shader_code.mjs`：PASS。
+- Linux OpenGL CMake 精确编译 `render_particle_validation_layer.cpp`：PASS。
+- 既有非 Jest `style_layer.test.cpp` 精确编译：PASS。
+- `git diff --check`：PASS。
+- Android Gradle/APK/ADB/设备：未执行。
+- Jest：未执行。
+
+## Git 与状态
+
+功能提交：`4c84a791229aa9f11808460c5dbfcf96327fb780`（`fix: stabilize particle lifecycle and view-space trails`），已成功 push 至 `origin/particle/main`。本报告将以独立文档提交补充；用户已有未跟踪文件未修改、未 stage。
+
+最终状态：**IMPLEMENTED / WAITING_ANDROID_VALIDATION**。