diff --git a/docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v2.md b/docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v2.md new file mode 100644 index 000000000..b62141705 --- /dev/null +++ b/docs/50_Step记录/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_v2.md @@ -0,0 +1,49 @@ +# 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 和旧任务书均未清理、暂存或提交。 + +## 完成项 + +- [x] 从 `/root/sourceserver/weatherV2/_artifacts/MapLibre_QBIN_V2_单元测试数据_v1/` 逐字节复制 8 个 raw `.qbin` 到 Test Host 自有 `assets/qbin-golden/`;运行时不读取该来源、不使用 HTTP/CDN/NAS/download/gzip。 +- [x] 新增 V4 fixture contract:稳定 `fieldKey`、`fieldID`、generation/dataVersion、真实 validTime/midpoint、profile contract、source 相对路径、bytes 与 SHA-256。 +- [x] Wind/Current 使用真实 U ColorBinding:semantic 1 / group 1 / `VELOCITY_COMPONENT` / unit 1,并使用 U/V `VECTOR_COMPONENTS` ParticleBinding;未伪装为 `SCALAR`。 +- [x] Wave 使用 height ColorBinding(20/0/`SCALAR`/2)及 direction ParticleBinding(10/0/unit 4);Rain 使用 precipitation ColorBinding(30/0/`SCALAR`/5),Particle 明确 N/A。 +- [x] 沿用 `expo-asset` 将 bundled asset materialize 为 fail-closed 的本地 `file://` URI,再调用 `FieldRuntime.submitEncodedField(...)`;Metro 仅追加 `qbin` asset extension。 +- [x] 保留 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。 +- [x] 新增开发期 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`: + +- [x] Test Host `npm --prefix integration/react-native/MapLibreParticleRNTestHost run typecheck`:PASS。 +- [x] package `npx tsc --noEmit -p packages/maplibre-particle-rn/tsconfig.json`:PASS。 +- [x] TurboModule schema combine 与 Android modules codegen:PASS。 +- [x] `scripts/verify-qbin-golden-fixtures.py`:PASS(8 个 raw source/copy 文件 bytes + SHA-256)。 +- [x] Linux OpenGL `cmake --build build-linux-opengl --target mbgl-test-runner -j3`:PASS(当前无 Core 变更,target 已最新)。 +- [x] `ParticleFieldProfileContractJson.*`、`ParticleEncodedFieldTransport.*`、`Source.RasterArrayV4HostApi*`、`ParticleFieldBinding.*`、`ParticleQbinV2Decoder.*:ParticleEncodedFieldIngress.*`、`ParticleFieldRuntime.*:ParticleFieldProfileValidator.*`、`Source.ParticleFieldDataAdapter*:Source.RasterArrayTimeline*:Source.HostField*` 合并过滤:PASS。 +- [x] `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`;该文档收尾后立即停止。 diff --git a/docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_Codex完成报告_v2.md b/docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_Codex完成报告_v2.md new file mode 100644 index 000000000..2bda9b4a3 --- /dev/null +++ b/docs/报告/STEP-079_真实QBIN_GoldenFixture接入RNTestHost_Codex完成报告_v2.md @@ -0,0 +1,50 @@ +# STEP-079 真实 QBIN Golden Fixture 接入 RN Test Host Codex 完成报告 v2 + +## 结果 + +状态:**IMPLEMENTED / WAITING FOR WINDOWS 11 ANDROID VALIDATION**。 + +RN Test Host 现保留 V3 功能并新增独立 V4 QBIN Golden 区。8 个冻结 raw QBIN 已随 Test Host 打包,JS 不接收 payload bytes、数组、Base64 或 URL;只由 `expo-asset` materialize 为本地 `file://` URI 并调用冻结的 `FieldRuntime.submitEncodedField(...)`。 + +Wind/Current 的真实 U/V descriptor 以 `VELOCITY_COMPONENT` 传入 ColorBinding,Wave/Rain 以各自真实 scalar semantic 传入;Wave direction 才作为 ParticleBinding,Rain 没有虚构粒子数据。load 按 clear → binding → T0 → T1 → midpoint 运行,T0/T1 必须分别返回 `ACCEPTED_INSERTED`,否则界面显示实际结果并失败。midpoint 只证明 V4 seek command accepted,不能证明或显示 mix=0.5。 + +## 已完成 + +- 冻结来源 `/root/sourceserver/weatherV2/_artifacts/MapLibre_QBIN_V2_单元测试数据_v1/` 的 8 个 raw fixture 已复制至 Test Host 自有 assets;开发 verifier 对 source 与 copy 的 size/SHA-256 全部 PASS。 +- V4 manifest 保留 profile contract、runtime identity、validTime、midpoint、source path、size/SHA-256 和真实 binding;运行时没有 source-server 依赖。 +- Metro 最小追加 `.qbin`,V3 UI/transport 没有移除或改成 V4-only。 +- Test Host typecheck、package typecheck、TurboModule schema combine/codegen、Linux OpenGL runner target、Contract JSON / Transport / Source V4 / Binding / QBIN-Ingress / Runtime-Profile / V3 Source 回归和 `git diff --check` 均 PASS。 + +## 未完成与无法验证 + +- 未执行 Android Gradle、APK build、install、ADB、模拟器、实体机或 Jest;也未验证 iOS/Metal。 +- 因任务明确禁止 Linux Android 操作,无法声明 Android PASS,也无法在此环境观察 V4 画面、实际 decode/submit、binding、midpoint、clear 或 PLAY/PAUSE 的设备结果。 +- 任务开始前既有 STEP-062 dirty、历史 untracked、`.codex-build-logs/`、generated Android/Expo/modules、tgz 与旧任务书均未纳入提交。 + +## Windows 11 Android 手工验收 + +在 Windows checkout 的 `particle/main`,由用户执行(路径与 APK 产物名如与本地不同,以实际生成工程为准): + +```powershell +git fetch origin +git checkout particle/main +git pull --ff-only origin particle/main +cd integration/react-native/MapLibreParticleRNTestHost +npm ci +npx expo prebuild --platform android --clean +npx expo run:android +adb -s 192.168.1.146 reverse tcp:8091 tcp:8091 +adb -s 192.168.1.146 reverse tcp:8081 tcp:8091 +adb -s 192.168.1.146 shell am start -n org.maplibre.particle.rntesthost/.MainActivity +``` + +如选择手工 APK 安装,须使用实际 APK 路径且显式指定同一设备:`adb -s 192.168.1.146 install -r <实际-debug-apk路径>`。 + +观察项:依次选择 Wind/Wave/Current/Rain 并 load;每类均确认 T0/T1 为 `ACCEPTED_INSERTED`、Color/Particle binding 为 `ACCEPTED`(Rain Particle=N/A)、midpoint 仅显示 command accepted、T0/T1 seek、V4 PLAY/PAUSE/speed 和 clear selected/all 均返回 `ACCEPTED`。检查 Metro/Android logcat 无 QBIN 读取、decode、contract 或 binding rejection;不得以画面存在替代以上文字结果。Android build/install/ADB 结果由用户记录后才可更新此状态。 + +## Git 收尾 + +- implementation commit hash:`f1ea88b0ce9c6995f05a8d2ae2eb2696d72e5f28`。 +- commit message:`feat: add V4 QBIN golden fixture test host`。 +- remote branch:`origin/particle/main`。 +- implementation Final HEAD:`f1ea88b0ce9c6995f05a8d2ae2eb2696d72e5f28`。本报告、Step 记录和开发记录随后使用仅文档 scoped commit 推送;push result 和收尾 Final HEAD 以该次 Git 输出为准,完成后立即停止。 diff --git a/粒子开发记录.md b/粒子开发记录.md index f092f2a4e..4226ad836 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -798,3 +798,9 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2` - `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 独立复验后重启。 + +### 2026-09-13 STEP-079 真实 QBIN Golden Fixture 接入 RN Test Host v2 + +- Test Host 已保留 V3 区并新增 V4 Wind/Wave/Current/Rain 四组冻结 QBIN T0/T1。8 个 raw asset 仅从冻结 WeatherV2 source 复制并随 Host 打包;`expo-asset` materialize 后只传本地 `file://` URI,运行时无 source-server、网络或 gzip 依赖。 +- V4 dataset 真实表达 Wind/Current U `VELOCITY_COMPONENT` ColorBinding 与 U/V particle,Wave height/direction,Rain precipitation/Particle N/A;load、submit result、binding、midpoint seek(不宣称 mix)、PLAY/PAUSE、正 speed、clear 均有独立 UI。 +- `particle-codex` 限流验证:Host/package TypeScript、TurboModule combine/codegen、8 文件 bytes/SHA-256、Linux runner target、Contract/Transport/V4/Binding/QBIN/Runtime/V3 filter 与 `git diff --check` 均 PASS。Android Gradle/APK/install/ADB/设备/Jest/iOS-Metal 未运行;状态 `IMPLEMENTED / WAITING FOR WINDOWS 11 ANDROID VALIDATION`。