docs: record STEP-078 color binding revision
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
This commit is contained in:
OpenAI Codex
@@ -0,0 +1,57 @@
|
||||
# STEP-078 — QBIN2 V4 ColorBinding VELOCITY_COMPONENT 接口修订 v4
|
||||
|
||||
状态：完成
|
||||
|
||||
日期：2026-09-13
|
||||
|
||||
## 目标与基线
|
||||
|
||||
- 开始 HEAD：`dd1d7014710819fe55857968558fcc9538f28d9c`。
|
||||
- 开始 `origin/particle/main`：`dd1d7014710819fe55857968558fcc9538f28d9c`。
|
||||
- 仅解除 STEP-079 已确认的 ColorBinding public API blocker：让 `FieldRuntime.setEncodedColorBinding(...)` 能表达既有 Core `VELOCITY_COMPONENT`；不进入 STEP-079。
|
||||
- 任务开始时已有 STEP-062 两处 dirty、历史 untracked 与 build 日志；均未清理、改写、暂存或提交。
|
||||
|
||||
## 完成项
|
||||
|
||||
- [x] `EncodedColorBindingInput.expectedValueClass` 新增 `VELOCITY_COMPONENT`，TS public fail-fast validation 同步允许该值。
|
||||
- [x] Kotlin `WeatherRuntimeBridgeModule` 将 `SCALAR` / `VELOCITY_COMPONENT` / `DIRECTION_ANGLE` 精确映射为 Core value class `0` / `1` / `2`。
|
||||
- [x] JNI `setRasterArraySourceEncodedColorBinding(...)` 仅允许 `0..2`；`VALIDITY=3` 与其它非法值继续 fail-closed。
|
||||
- [x] Core 回归证明以真实 `VelocityComponent` U-east plane 的 ColorBinding 可 resolve，并证明 `Validity` ColorBinding 返回 `InvalidBinding`。
|
||||
- [x] TurboModule primitive string ABI 与 Java `WeatherRuntime.setEncodedColorBinding(...)` 的参数数量、顺序及 primitive 形状均未修改。
|
||||
|
||||
## 修改范围
|
||||
|
||||
- `packages/maplibre-particle-rn/src/types.ts`
|
||||
- `packages/maplibre-particle-rn/src/FieldRuntime.ts`
|
||||
- `packages/maplibre-particle-rn/android/src/main/java/org/navsea/maplibre/particle/weather/WeatherRuntimeBridgeModule.kt`
|
||||
- `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp`
|
||||
- `test/particle/field_binding.test.cpp`
|
||||
- 本记录、完成报告与 `粒子开发记录.md`。
|
||||
|
||||
未修改 Renderer/GPU/shader、QBIN container/decoder、Store、ForecastClock、Projection identity、ParticleBinding、Test Host V4 或 NavSea。
|
||||
|
||||
## 验证
|
||||
|
||||
所有 noisy command 均在 `particle-codex` tmux session 内经 `build-output-throttle` 执行，日志位于 `/tmp/step078v4-build-logs`：
|
||||
|
||||
- [x] package `tsc --noEmit`。
|
||||
- [x] TurboModule schema combine/codegen。
|
||||
- [x] Linux OpenGL `mbgl-test-runner` rebuild。
|
||||
- [x] `ParticleFieldBinding.*`。
|
||||
- [x] `Source.RasterArrayV4HostApi*`。
|
||||
- [x] `ParticleQbinV2Decoder.*:ParticleEncodedFieldIngress.*`。
|
||||
- [x] `ParticleFieldRuntime.*:ParticleFieldProfileValidator.*`。
|
||||
- [x] `Source.ParticleFieldDataAdapter*:Source.RasterArrayTimeline*:Source.HostField*`。
|
||||
- [x] Java `nativeSetRasterArraySourceEncodedColorBinding` 6-parameter declaration、C++ method signature 和 registration 静态一致性核对。
|
||||
- [x] task-scope `git diff --check`。
|
||||
|
||||
## 未完成、阻塞与下一步
|
||||
|
||||
- Android Kotlin/Java/JNI 真实编译、Gradle、APK、install、ADB、设备/模拟器验证均按任务约束未执行；Windows 11 Android Test Host 编译仍待用户手工验收。Jest、iOS/Metal 亦未执行。
|
||||
- 无实现阻塞。完成 scoped Git 收尾后立即停止；STEP-079 由 ChatGPT 独立复验本修订后重启。
|
||||
|
||||
## Git 收尾
|
||||
|
||||
- implementation commit：`e02353820aafa1834ce3a2ab3afe9261fadd83bc`（`fix: expose V4 velocity component color binding`）。
|
||||
- implementation push：PASS，`dd1d70147..e02353820 particle/main -> particle/main`；remote branch 为 `origin/particle/main`。
|
||||
- implementation Final HEAD：`e02353820aafa1834ce3a2ab3afe9261fadd83bc`。本记录、完成报告和开发记录将以独立、仅文档 scoped commit 推送；完成后立即停止。
|
||||
@@ -0,0 +1,34 @@
|
||||
# STEP-078 QBIN2 V4 ColorBinding VELOCITY_COMPONENT 接口修订 Codex 完成报告 v4
|
||||
|
||||
## 结果
|
||||
|
||||
已完成最小、向后兼容的 public API 修订：RN `FieldRuntime.setEncodedColorBinding(...)` 现在可传递 Core 已支持的 `VELOCITY_COMPONENT`。传输路径为 TS string → Kotlin `1` → JNI/Core `FieldValueClass::VelocityComponent`，不增加 TurboModule 参数，也不改变 Java 透传方法形状。
|
||||
|
||||
`VALIDITY` 没有被开放为 ColorBinding：TS/Kotlin 均拒绝该字符串，JNI 仅接受 `0..2`，Core 回归继续证明它返回 `InvalidBinding`。未实现 vector magnitude、单位换算或任何 provider/weather 特例。
|
||||
|
||||
## 修改与证明
|
||||
|
||||
- TS 类型与 public validation 加入 `VELOCITY_COMPONENT`。
|
||||
- Kotlin bridge 映射 `SCALAR=0`、`VELOCITY_COMPONENT=1`、`DIRECTION_ANGLE=2`。
|
||||
- JNI guard 从仅 `0/2` 收敛为合法连续值域 `0..2`，故 `3` 及其它非法值仍拒绝。
|
||||
- `ParticleFieldBinding.FailsClosedAndSupportsDirectionAngle` 增加真实 velocity component plane 的 accepted projection/storage identity 断言，另加 Validity fail-closed 断言。
|
||||
|
||||
## 验证结果
|
||||
|
||||
在 `particle-codex` tmux session 内，所有 typecheck、codegen、build 与 test 命令均经 `build-output-throttle`，8 个限流日志完整产生于 `/tmp/step078v4-build-logs`。package TypeScript typecheck、TurboModule schema combine/codegen、Linux OpenGL `mbgl-test-runner` rebuild，及 `ParticleFieldBinding.*`、Source V4 Host API、QBIN/Ingress、Runtime/Profile、V3 Source 指定回归均 PASS。
|
||||
|
||||
此外，Java `NativeMapView` 的 6 参数 native declaration、C++ `NativeMapView` member signature 与 `METHOD` registration 已静态核对一致；task-scope `git diff --check` PASS。
|
||||
|
||||
## 未完成与边界
|
||||
|
||||
按任务要求未运行 Android Gradle、APK、install、ADB、实体机或模拟器；Android Kotlin/Java/JNI 的真实编译和 Windows 11 Test Host 验收仍待用户执行。Jest、iOS/Metal 也未验证。既有 STEP-062 dirty、历史 untracked、workspace `.codex-build-logs/` 与其它无关内容均未纳入本任务。
|
||||
|
||||
未进入 STEP-079；它必须由 ChatGPT 独立复验本修订后再启动。
|
||||
|
||||
## Git 收尾
|
||||
|
||||
- implementation commit hash：`e02353820aafa1834ce3a2ab3afe9261fadd83bc`。
|
||||
- commit message：`fix: expose V4 velocity component color binding`。
|
||||
- push result：PASS，`dd1d70147..e02353820 particle/main -> particle/main`。
|
||||
- remote branch：`origin/particle/main`。
|
||||
- Final HEAD（implementation scoped commit）：`e02353820aafa1834ce3a2ab3afe9261fadd83bc`。本报告、Step 记录和开发记录随后使用独立、仅文档 scoped commit 收尾并 push；该提交完成即停止。
|
||||
@@ -792,3 +792,9 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2`
|
||||
- 在复制/接入前核对冻结 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。
|
||||
|
||||
### 2026-09-13 STEP-078 v4 ColorBinding VELOCITY_COMPONENT 接口修订
|
||||
|
||||
- `FieldRuntime.setEncodedColorBinding(...)` 现公开支持 `VELOCITY_COMPONENT`：TS string contract、Kotlin `1` 映射、JNI `0..2` guard 与现有 Core `FieldValueClass::VelocityComponent` 一致；TurboModule primitive ABI 和 Java 透传签名未改变。
|
||||
- 新 Core 回归通过真实 U-east velocity component plane 成功 resolve ColorBinding，`Validity` ColorBinding 仍为 `InvalidBinding` fail-closed；未增加 vector magnitude、单位转换或 provider 特例。
|
||||
- `particle-codex` 中经输出节流的 package tsc、TurboModule schema、Linux runner rebuild、Binding/Source V4/QBIN-Ingress/Runtime-Profile/V3 Source 过滤回归均 PASS；Android Gradle/APK/install/ADB/设备、Jest、iOS-Metal 未执行。STEP-079 不在本次进入，待 ChatGPT 独立复验后重启。
|
||||
|
||||
Reference in New Issue
Block a user