MapLibreParticleLab/docs/50_Step记录/STEP-070_MapLibreParticleLab_V3-06_四类场Fixture与RN通用回归_v1.md

STEP-070 MapLibreParticleLab V3-06 四类场 Fixture 与 RN 通用回归

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION

目标与边界

在 particle/main 3b012759 上增加离线 V3 fixture、转换/校验工具、RN Test Host .3 公共 API 接线和最小 Core contract test。不修改 Timeline/Playback/T0/T1/MIX/rollover、schema、shader、WeatherV2、NavSea 或 STEP-062 两份用户 dirty 文档；不运行 Android Gradle/AAR/APK/ADB/Jest。

完成内容

• tools/particle_v3_fixture 生成并校验 v2 metadata、shared validity、可选 scalar/vector、长度与 SHA-256。validator 对每一个 validity=1 的 cell 检查所有存在 plane：finite 且不等于 noData。
• wind-real 从本地 canonical v1 field.f32 重新封装；shared validity 严格派生为 finite(U) && finite(V) && U != -9999 && V != -9999。
• wave-real 由 WeatherV2 ecmwf-wam/waves/2026090912/wave_bin 的正式 2026090918/2026090919 BIN 和 header sidecar 解码：scalar=height_m，vector=规范化 unit_to_u/unit_to_v，语义 DIRECTION；period_s 和原始 degree 不进入 canonical。
• tide-real 由 WeatherV2 cmems/tide/2026090900/current_bin 的正式 2026090901/2026090902 BIN 和 header sidecar 解码为 vector-only VELOCITY。
• Wave/Tide 每帧 summary 记录正式源 BIN 与 sidecar SHA-256、target_time、referenceTime、bounds、grid、projection、included/excluded channels 和 validity 派生规则；两者 generation 为小且严格递增的 1/2。
• Rain 保持 rain-decoder-fixture，manifest/provenance 明确为非真实 field values，因为本 Step 未实现 PMTiles reader；fallback generation 为严格递增的 1/2。
• Test Host 的 fieldDatasets 已指向 wave-real 和 tide-real，继续仅经 package FieldRuntime 公共 API 提交 local file refs。
• 保留并验证 Wave synthetic scalar/vector independence；新增 C++ provider-neutral 四类 shape contract test。

验证

• python3 tools/particle_v3_fixture/generate_fixtures.py --write-reference-fixtures --validate：PASS。
• package .3 tsc --noEmit：PASS。
• RN Test Host npm run typecheck：PASS（不含 Jest）。
• RN TurboModule combine-js-to-schema-cli.js：PASS。
• 使用 CCACHE_DIR=/tmp/step070-ccache，重新编译 source.test.cpp.o：PASS。
• mbgl-test / mbgl-test-runner 完整 Linux OpenGL 重编译/重链：459/459 完成；Source.ParticleFieldV3* 过滤测试 6/6 PASS；验证链退出码 0。
• git diff --check：PASS（提交前复核）。
• Android Gradle/AAR/APK/ADB/Jest：按任务范围未运行。

当前结果、阻塞与下一步

fixture 数据契约、TypeScript/codegen、Linux 完整重链与 V3 Source 过滤测试均已完成。Android/JNI 真实编译和设备视觉验收仍由后续统一周期完成。Rain 要升级为真实数值场，需要另行实现只读 PMTiles reader；不得把现有 fallback 改称 real。

Git 收尾

• implementation：8588e6fcb4f3f5d874159c2e42619c5227cb7921（feat: add V3 field fixtures and RN regression host），已 push 至 origin/particle/main。
• docs-only Git handoff 在 git add 创建 .git/index.lock 时因只读文件系统被阻断，未提交、未推送；STEP-062 两份用户 dirty 文档与历史 untracked/build/cache/tgz 均未暂存。