MapLibreParticleLab/docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v2.md

STEP-079 — 真实 QBIN Golden Fixture 接入 RN Test Host v2

状态：完成（IMPLEMENTED / WAITING FOR WINDOWS 11 ANDROID VALIDATION）

日期：2026-09-13

目标与基线

• 开始 HEAD / origin/particle/main：a83ab9cc94a14426913f971786eae6b13a6f1702。
• 将 WeatherV2 冻结来源的 Wind、Wave、Current、Rain QBIN V2 原始 T0/T1 fixture 接入现有 RN Test Host 的 V4 public API；保留全部 V3 测试区。
• 开始前的 STEP-062 dirty、历史 untracked、.codex-build-logs/、Test Host generated android/.expo/modules、tgz 和旧任务书均未清理、暂存或提交。

完成项

• 从 /root/sourceserver/weatherV2/_artifacts/MapLibre_QBIN_V2_单元测试数据_v1/ 逐字节复制 8 个 raw .qbin 到 Test Host 自有 assets/qbin-golden/；运行时不读取该来源、不使用 HTTP/CDN/NAS/download/gzip。
• 新增 V4 fixture contract：稳定 fieldKey、fieldID、generation/dataVersion、真实 validTime/midpoint、profile contract、source 相对路径、bytes 与 SHA-256。
• Wind/Current 使用真实 U ColorBinding：semantic 1 / group 1 / VELOCITY_COMPONENT / unit 1，并使用 U/V VECTOR_COMPONENTS ParticleBinding；未伪装为 SCALAR。
• Wave 使用 height ColorBinding（20/0/SCALAR/2）及 direction ParticleBinding（10/0/unit 4）；Rain 使用 precipitation ColorBinding（30/0/SCALAR/5），Particle 明确 N/A。
• 沿用 expo-asset 将 bundled asset materialize 为 fail-closed 的本地 file:// URI，再调用 FieldRuntime.submitEncodedField(...)；Metro 仅追加 qbin asset extension。
• 保留 V3 区域；新增 V4 dataset 选择、load、分开的 T0/T1 submit 结果、binding 结果、T0/midpoint/T1 seek、PLAY/PAUSE、正数 speed、clear selected/clear all 控制。load 固定顺序为 clear → binding → T0 → T1 → midpoint，T0/T1 非 ACCEPTED_INSERTED 会显示失败；midpoint 仅显示 command accepted，不宣称观测到 mix=0.5。
• 新增开发期 fail-closed fixture verifier，逐个同时核验冻结 source 与 bundled copy 的 raw bytes/SHA-256。

修改范围

• 仅修改 integration/react-native/MapLibreParticleRNTestHost/ 下的 V4 fixture、assets、materialize/UI、Metro、README 与 verifier，以及本 Step、完成报告、粒子开发记录.md。
• 未修改 Core、QBIN decoder、JNI、Android bridge、RN package public API、Renderer/GPU/shader、NavSea 或网络层。

验证

以下均在 particle-codex tmux session 内执行；所有 build/typecheck/codegen/test 经 build-output-throttle，日志位于 /tmp/step079-build-logs：

• Test Host npm --prefix integration/react-native/MapLibreParticleRNTestHost run typecheck：PASS。
• package npx tsc --noEmit -p packages/maplibre-particle-rn/tsconfig.json：PASS。
• TurboModule schema combine 与 Android modules codegen：PASS。
• scripts/verify-qbin-golden-fixtures.py：PASS（8 个 raw source/copy 文件 bytes + SHA-256）。
• Linux OpenGL cmake --build build-linux-opengl --target mbgl-test-runner -j3：PASS（当前无 Core 变更，target 已最新）。
• ParticleFieldProfileContractJson.*、ParticleEncodedFieldTransport.*、Source.RasterArrayV4HostApi*、ParticleFieldBinding.*、ParticleQbinV2Decoder.*:ParticleEncodedFieldIngress.*、ParticleFieldRuntime.*:ParticleFieldProfileValidator.*、Source.ParticleFieldDataAdapter*:Source.RasterArrayTimeline*:Source.HostField* 合并过滤：PASS。
• git diff --check 与 task-scope cached git diff --check：PASS。

未完成、无法验证与下一步

• Android Gradle/APK/install/ADB/模拟器/真机均未在 Linux 执行；Jest、iOS/Metal 也未执行。
• 无法在 Linux 证明 Android Test Host 实际读取 Expo bundled .qbin、Kotlin/JNI/Renderer consumer 接受 fixture，或观察 Android 画面/播放效果；这些必须由 Windows 11 用户手工验收。
• 无 implementation blocker。下一步仅为 Windows 11 Android 手工验收；本 Step 不进入 Renderer consumer、NavSea 正式接入或下一 Step。

Git 收尾

• implementation commit：f1ea88b0ce9c6995f05a8d2ae2eb2696d72e5f28，feat: add V4 QBIN golden fixture test host。
• implementation Final HEAD：f1ea88b0ce9c6995f05a8d2ae2eb2696d72e5f28。本 Step/报告/开发记录使用独立且仅文档的 scoped commit 收尾并 push 到 origin/particle/main；该文档收尾后立即停止。