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

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

状态：阻塞

日期：2026-09-13

目标

把 WeatherV2 冻结的 QBIN V2 Golden Fixture 通过 STEP-078 的 V4 public API 接入 MapLibreParticleRNTestHost；本 Step 不执行 Android Gradle、APK、安装或 ADB。

起始基线

• HEAD：2ea8f03064b2379d5220ce67806e3543e9cba0a7
• origin/particle/main：2ea8f03064b2379d5220ce67806e3543e9cba0a7
• 开始前存在 STEP-062 dirty、历史 untracked、.codex-build-logs/、Test Host generated Android/Expo/modules 与 package tgz；均未清理、暂存或提交。

已完成的只读核对

• 核对冻结来源 /root/sourceserver/weatherV2/_artifacts/MapLibre_QBIN_V2_单元测试数据_v1/、说明、原始 manifest、profile/semantic/unit registry。
• 核对 8 个 raw .qbin 的目标（Wind/Wave/Current/Rain，各 T0/T1）及 descriptor：Wind/Current U/V 都是 VELOCITY_COMPONENT，semantic 1/2、group 1、unit 1。
• 核对 STEP-078 V4 TypeScript、TurboModule/Kotlin bridge 与 Core ColorBinding resolver。
• 确认不存在可在不改变冻结 public API 语义的前提下为 Wind/Current 提交正确 ColorBinding 的路径。

阻塞

Wind/Current 的任务合同要求选择 U 或 V 做 ColorBinding；其正确 expectedValueClass 是 VELOCITY_COMPONENT。然而冻结的 RN public API 在 FieldRuntime.setEncodedColorBinding 只接受 SCALAR 或 DIRECTION_ANGLE，Kotlin bridge 同样只映射这两者。将 U/V 伪装为 SCALAR 虽能通过 JS/Kotlin 参数白名单，但 Core resolver 会以 PlaneClassMismatch 拒绝真实 velocity plane。

因此无法同时满足“所有 dataset 至少有 ColorBinding”“所有 binding 仅通过冻结 V4 public API”“不得改变 STEP-078 public API 语义”。按任务的接口阻塞条款，未创建 Test Host wrapper、未修改 package/Core/Renderer，也未保留半成品 fixture 复制。

完整证据与解阻条件见 docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_接口阻塞报告_v1.md。

构建与验证

• 未执行 TypeScript/codegen/C++ build 或测试：在实现开始前已得到不可绕过的 public-API 合同矛盾，继续执行不会验证一个可交付实现。
• 未执行 Android Gradle、APK、install、ADB、模拟器、实体机或 iOS/Metal 操作。
• git diff --check 与 staged git diff --cached --check：在 particle-codex tmux session 执行，PASS。

Git 收尾

• 阻塞记录提交：afcc74066f1395678621fa2b1a70d10bc722a623，docs: record STEP-079 V4 fixture API blocker。
• 已推送至 origin/particle/main；该提交只含本 Step 的 Step 记录、接口阻塞报告和开发记录，不含 fixture、Test Host 或既有 dirty/untracked 文件。

允许/禁止范围结果

• 未修改 Renderer/GPU/shader、Core/QBIN/Binding/Host API、Android bridge、RN package public API、NavSea、网络、下载或 gzip。
• 未进入下一 Step；等待具备明确授权的 STEP-078 API 补充/修订后重新开始本 Step。