MapLibreParticleLab/docs/50_Step记录/STEP-075_QBIN2_V4_Binding与ProjectionIdentity_v3.md

STEP-075 — QBIN2 V4 Binding 与 Projection Identity v3

状态：完成

日期：2026-09-13

目标与基线

• 基于 653e6f2f1598b7817b7912a39877690f248d6f25，仅关闭 inactive selector 污染 ParticleBinding identity 的审计问题。
• 不进入 STEP-076；测试仅使用离线 C++ fixture。

必做项

• ParticleBinding::operator== 改为 mode-aware：VectorComponents 只比较 U/V selector；DirectionAngle 只比较 direction selector；两者均继续比较 mode、fieldKey 与 expectedUnitID。
• selector identity 继续仅为 (semanticID, groupID)；component 保持为 resolved Plane descriptor assertion，不进入 identity。
• VectorComponents 覆盖：仅变更 inactive directionPlane 时 binding equality 与 resolved ParticleProjectionContentIdentity 均相同；变更 active U selector 则 binding 不同且 PlaneMissing fail-closed。
• DirectionAngle 覆盖：仅变更 inactive U/V selectors 时 binding equality 与 resolved identity 均相同；变更 active direction selector 则 binding 不同且 PlaneMissing fail-closed。

允许修改

• include/mbgl/particle/field/field_binding.hpp
• src/mbgl/particle/field/field_binding.cpp
• test/particle/field_binding.test.cpp
• 本 Step、完成报告 v3 与 粒子开发记录.md

禁止修改

• 未修改 Decoder、Runtime、Renderer、Host/JNI/RN/Android，未进入 STEP-076。
• 未执行 Android Gradle/APK/ADB/Jest、iOS/Metal，未使用真实服务器 QBIN。

验证与当前结果

• Linux OpenGL：cmake --build build-linux-opengl --target mbgl-test-runner -j3，真实重建 PASS（全局 build-output-throttle）。
• ParticleFieldBinding.*：6/6，0 failure。
• ParticleFieldRuntime.*:ParticleFieldProfileValidator.*：11/11，0 failure。
• ParticleQbinV2Decoder.*:ParticleEncodedFieldIngress.*：24/24，0 failure。
• Source.ParticleFieldDataAdapter*:Source.RasterArrayTimeline*:Source.HostField*：11/11，0 failure。
• git diff --check PASS。

Git

• scoped commit：2645bd725f63c4da12ab48a0cc11ff034c9d9878，fix: close STEP-075 binding selector identity audit。
• push result：653e6f2f1..2645bd725 particle/main -> particle/main；remote branch：origin/particle/main。
• Final HEAD（scoped implementation delivery）：2645bd725f63c4da12ab48a0cc11ff034c9d9878。

阻塞与下一步

• 无实现阻塞。
• STEP-075 v3 已关闭；按任务书停止，不进入 STEP-076。