From afcc74066f1395678621fa2b1a70d10bc722a623 Mon Sep 17 00:00:00 2001 From: OpenAI Codex Date: Sun, 13 Sep 2026 17:43:35 +0800 Subject: [PATCH] docs: record STEP-079 V4 fixture API blocker --- ...9_真实QBIN_GoldenFixture接入RNTestHost_v1.md | 41 +++++++++++++++++++ ...GoldenFixture接入RNTestHost_接口阻塞报告_v1.md | 35 ++++++++++++++++ 粒子开发记录.md | 6 +++ 3 files changed, 82 insertions(+) create mode 100644 docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v1.md create mode 100644 docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_接口阻塞报告_v1.md diff --git a/docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v1.md b/docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v1.md new file mode 100644 index 000000000..7b88c0bb6 --- /dev/null +++ b/docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v1.md @@ -0,0 +1,41 @@ +# 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；均未清理、暂存或提交。 + +## 已完成的只读核对 + +- [x] 核对冻结来源 `/root/sourceserver/weatherV2/_artifacts/MapLibre_QBIN_V2_单元测试数据_v1/`、说明、原始 manifest、profile/semantic/unit registry。 +- [x] 核对 8 个 raw `.qbin` 的目标（Wind/Wave/Current/Rain，各 T0/T1）及 descriptor：Wind/Current U/V 都是 `VELOCITY_COMPONENT`，semantic `1/2`、group `1`、unit `1`。 +- [x] 核对 STEP-078 V4 TypeScript、TurboModule/Kotlin bridge 与 Core ColorBinding resolver。 +- [x] 确认不存在可在不改变冻结 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`：待本 Step 的文档收尾后执行。 + +## 允许/禁止范围结果 + +- 未修改 Renderer/GPU/shader、Core/QBIN/Binding/Host API、Android bridge、RN package public API、NavSea、网络、下载或 gzip。 +- 未进入下一 Step；等待具备明确授权的 STEP-078 API 补充/修订后重新开始本 Step。 diff --git a/docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_接口阻塞报告_v1.md b/docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_接口阻塞报告_v1.md new file mode 100644 index 000000000..d4d852bb5 --- /dev/null +++ b/docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_接口阻塞报告_v1.md @@ -0,0 +1,35 @@ +# STEP-079 真实 QBIN Golden Fixture 接入 RN Test Host 接口阻塞报告 v1 + +状态：阻塞（未实现，未执行 Android 验收） + +## 结论 + +STEP-078 的冻结 V4 RN public API 无法表达真实 Wind/Current U 或 V plane 的正确 ColorBinding。因此本 Step 依照任务的停止条款退出，没有以 Test Host wrapper、错误 enum 或 Core/API 修改绕过。 + +## 可复核证据 + +冻结 WeatherV2 fixture manifest/profile registry 规定： + +| 数据集 | 要提交的 Color plane | fixture descriptor | +| --- | --- | --- | +| Wind `wind/1` | U 或 V | semantic `1`/`2`，group `1`，unit `1`，`VELOCITY_COMPONENT` | +| Current `current/1` | U 或 V | semantic `1`/`2`，group `1`，unit `1`，`VELOCITY_COMPONENT` | + +冻结 RN API `packages/maplibre-particle-rn/src/FieldRuntime.ts` 的 `setEncodedColorBinding` 只接受 `SCALAR`、`DIRECTION_ANGLE`；Android `WeatherRuntimeBridgeModule.kt` 也只将这两个字符串映射为 native value class。它没有 `VELOCITY_COMPONENT` 的 public enum 通路。 + +Core 并非可以安全忽略该差异：`src/mbgl/particle/field/field_binding.cpp` 会对 ColorBinding 的 selected T0/T1 plane 验证 value class。以 `SCALAR` 提交真实 U/V 必返回 `PlaneClassMismatch`。把 value class 伪造为 scalar 既不是 fixture-derived binding，也不会形成有效 V4 bridge 验证。 + +Wave（scalar Height）与 Rain（scalar precipitation）没有此问题；Wave 的 DirectionAngle particle binding 与 Wind/Current 的 VectorComponents particle binding 也均有冻结 public API 表达。但任务要求同一 Test Host V4 dataset contract 至少包含 ColorBinding，且固定规则特别允许 Wind/Current U/V 的 ColorBinding；缺少该 enum 使四组完整合同无法成立。 + +## 未执行的内容 + +- 未保留或提交 8 个 copied raw QBIN fixture，避免仓库出现无法被完整 Test Host contract 使用的半成品。 +- 未创建 V4 dataset/materialize/UI；未修改 V3 UI 或 Test Host Metro。 +- 未运行 TypeScript、TurboModule codegen、C++ rebuild/回归、Android Gradle/APK/ADB，因没有可验证的合规实现。 +- 未创建 commit、未 push；`particle/main` 仍指向起始基线，除本阻塞文档收尾外没有 task implementation。 + +## 最小解阻条件 + +需要新的、显式授权的 API 修订 Step：令 `EncodedColorBindingInput.expectedValueClass`、RN validation、TurboModule spec、Kotlin enum mapping 以同一冻结 ABI 支持 `VELOCITY_COMPONENT`，并增加相应的 Core/bridge contract tests。该 Step 必须单独决定 Renderer 是否仅 bridge-only；本报告不建议把 vector magnitude 伪造为 color input，也不建议在 Test Host 绕过 public API。 + +在该修订完成且稳定后，应重新从本任务指定 fixture source materialize 8 个 `.qbin`，进行完整 source/size/SHA-256 审计，并执行本任务要求的 Linux static validation。Windows 11 Android 验收目前没有可交付的 V4 Test Host，因此不能提供安装/ADB 验收步骤或宣称 Android PASS。 diff --git a/粒子开发记录.md b/粒子开发记录.md index 3f39af5a8..83ec4b28c 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -786,3 +786,9 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2` - fieldKey、runtime fieldID、profileID 统一按 UTF-8 byte length 1..64 验证：RN `TextEncoder`、Kotlin `toByteArray(Charsets.UTF_8)`、Java `StandardCharsets.UTF_8`。多字节 33 CJK（99 bytes）输入在 RN/Java guard tests 中拒绝。 - `particle-codex` 内所有限流验证均 PASS：package tsc、TS directed test、TurboModule schema、JDK-only Java guard、Linux runner rebuild、V4/V3 指定 filter、JNI name-set 与 `git diff --check`。Android Gradle/APK/ADB/JNI 真实编译、设备、Jest、iOS/Metal 仍未运行；未改 Renderer/GPU/shader/Test Host/NavSea，不进入 STEP-079。 - 实现 scoped commit `75a974e77503c56ec5bd2823ac1b689225ed80a7`（`fix: close STEP-078 V4 bridge guard audit`）已成功 push：`73779b89b..75a974e77 particle/main -> particle/main`；仅文档 Git 收尾 commit 随后推送并停止。 + +### 2026-09-13 STEP-079 真实 QBIN Golden Fixture RN Test Host 接入阻塞 + +- 在复制/接入前核对冻结 fixture contract 与 STEP-078 V4 public API：Wind/Current U/V 是 `VELOCITY_COMPONENT`（semantic 1/2、group 1、MPS），而 `setEncodedColorBinding` 的 RN/Android public contract 仅允许 `SCALAR` 或 `DIRECTION_ANGLE`。 +- 用 scalar 伪装 U/V 会被 Core ColorBinding resolver 以 `PlaneClassMismatch` fail-closed；扩 public enum 则改变 STEP-078 冻结 public API。本 Step 未堆叠 Test Host wrapper、未改 Core/Renderer/bridge，也未保留半成品 fixture。 +- 已按任务的接口阻塞停止条款生成 STEP/阻塞报告；未运行 TypeScript/codegen/C++/Android 验证，等待独立 API 修订 Step。