131 lines
13 KiB
Markdown
131 lines
13 KiB
Markdown
# STEP-097 V13 修复后集中验证清单 v1
|
||
|
||
状态：**STEP-097 整体 PARTIAL；A1 与 A2 的 Android/Core 检查已完成，B/C 未开始。** 下方较早段落按当时事实保留；后续 RDC 结果以本文末尾带日期的更新为准。Metal host Core 测试不等于 iOS runtime，iOS runtime 按用户豁免记 `USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`。
|
||
|
||
## 通用 Core 与现有测试入口（RDC）
|
||
|
||
在本仓 Mac 当前 checkout，使用已配置的现有 build 目录；若目录不存在，先按当前构建规范配置。此处不自动运行：
|
||
|
||
```sh
|
||
cmake --build build-step088-opengl --target mbgl-test-runner -j3
|
||
build-step088-opengl/mbgl-test-runner --gtest_filter='RenderSegmentPlan.*:RenderSegmentDiagnostics.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:ParticleFastPath.*'
|
||
```
|
||
|
||
新入口 `RenderSegmentDiagnostics.OldCacheReleaseCannotChargeReplacementAtSameIndex` 预期同 index 的旧 revision release 不计入新 topology，当前 revision release 计 1。`RetainedUnderlayCache.UnsupportedAndResourceFailureFallBackSafely` 为旧入口，用于资源失败后的基础状态；尚不能替代真实 layer render 异常注入。失败保留完整日志，回传首个错误和日志路径。
|
||
|
||
## Android OpenGL（Particle-Android / RDC，NOT RUN）
|
||
|
||
```sh
|
||
./tools/particle_android_validation/build_validation_apk.sh
|
||
```
|
||
|
||
RDC 应使用同一 commit 生成 APK，再由后续授权的 Win11/模拟器操作按标准流水线安装。现有 Test Host 仅有 C-R 控制，尚缺同一 vector source/same tiles 的 R-R、R-C-R、C-R-R fixture，故该 APK 即使构建成功也不能关闭 01/03。需比较 cache ON/OFF 的首帧、重建、reuse、主目标与离屏目标像素；失败后 diagnostics 不得 Ready，下帧可恢复。记录 Renderer、ABI、SHA-256、截图与日志。不得引用 STEP-094 历史 43/43 作为本轮结果。
|
||
|
||
## iOS Metal（Particle-iOS / RDC，NOT RUN）
|
||
|
||
```sh
|
||
cmake --build build-ios --target ios-sdk-static -- -quiet
|
||
```
|
||
|
||
同 commit 的 iOS simulator 与真机需开启 Metal API Validation，捕获 retained R-R/R-C-R 的 color/depth/stencil texture、load/clear/store，特别确认 simulator 的 Depth32Float_Stencil8 同时绑定 depth 和 stencil。故障注入覆盖附件创建失败、encoder 创建失败及 layer render 异常；预期不发布 Ready cache、后续能 fallback/retry。专用自动测试入口尚缺，不能因静态修改或 `ios-sdk-static` 成功就宣称 Metal runtime PASS。
|
||
|
||
## 后续 GPU 性能（粒子负责人协调，NOT RUN）
|
||
|
||
完成 A1/A2/B/C 代码与平台测试入口后，以相同设备、commit、Style、视口和场数据采样 cache ON/OFF、R×viewport×fieldKey 阶梯，记录 30/60 FPS、p50/p95/p99、GPU/CPU frame time、纹理创建/释放、峰值/长稳内存、方向/缩放/状态恢复。Metal capture 记录 `waitUntilCompleted` 的实际同步点及资源依赖。未经运行不填写数字；F06 multi-C 与 F08 精细失效另行设计。
|
||
|
||
## Test Host 依赖（B 阶段后，NOT RUN）
|
||
|
||
目前默认 RN `.10` 与 Native `.13` 错配，阶段 B 未开始，不得运行安装并声称配对成功。B 修正 package/lock/SPM 后，RDC 再在 Test Host 目录执行：
|
||
|
||
```sh
|
||
npm ci
|
||
npm run typecheck
|
||
```
|
||
|
||
必须同时检查实际已安装 RN tgz、Android Gradle substitution、iOS SPM exactVersion 与 lockfile；不得以 node_modules 临时软链代替默认安装结果。本清单不含 Jest 命令。
|
||
|
||
## 2026-09-25 FZG1 A1 部分执行结果（覆盖上方 Codex 交付时的 NOT RUN 状态）
|
||
|
||
- 标准构建脚本已由 Mac RDC 实际执行；HEAD `91c2491b0`，x86_64 OpenGL Debug APK `BUILD SUCCESSFUL`，SHA-256 `8677197c5f83a22747cb51f0c261edffc5db4678fc25b3f366474f6ecb94dc99`。冻结于 `artifacts/maplibre-particle/step097-fzg1/`。
|
||
- ADB `192.168.200.139:5555` 对 FZG1-2 实际执行覆盖安装、20 组截图/UI XML、既有 STEP-093 topology、CACHE OFF/ON、相机、非法范围恢复与 mutation/fail-closed，日志见 `docs/报告/STEP-097_A1_FZG1测试APK与实机验证报告_v1.md`。
|
||
- 此处只是设备冒烟；A1 的同 tile stencil fixture、Metal 附件验证、真正 LayerGroup exception 注入与 `OldCacheReleaseCannotChargeReplacementAtSameIndex` GTest **仍 NOT RUN／缺专用入口**；A2/B/C 和软件发布亦未执行。
|
||
|
||
## 2026-09-26 第 19 项原生 GTest 已执行
|
||
|
||
- RDC 使用当前源码 HEAD `0d13552bed84f427dd43cae9856391bd26622179` 增量重编译 `mbgl-test-runner`：95/95 steps，exit 0；第 19 项 `OldCacheReleaseCannotChargeReplacementAtSameIndex` **1/1 PASS**；`RenderSegmentDiagnostics.*` **5/5 PASS**，两次退出码均为 0。原始日志和分析见 `docs/报告/STEP-097_A1_第19项GTest运行验证报告_v1.md`。
|
||
- 上方第 19 项“NOT RUN”是 2026-09-25 FZG1 冒烟时点的历史事实，现已由本条更新。01 同 tile、02 Metal、03 render exception 测试仍未闭合；A1 不得整体标 PASS。
|
||
|
||
## 2026-09-26 第 19 项 FZG1 设备辅助测试结果
|
||
|
||
- 经 RDC 在 FZG1-2 重新覆盖安装与 hash 复核，执行两轮 topology 轮换和资源诊断场景，20 个截图检查点；18 个有效配置均 valid=true/fallback=false，缺失 START fail-closed 后恢复。B/T 的粗粒度 create-release 差额 0/1，实时日志中无应用崩溃记录。详见 `docs/报告/STEP-097_A1_第19项FZG1运行验证报告_v1.md` 与 Mac 忽略目录 `artifacts/maplibre-particle/step097-fzg1-gtest19-device/`。
|
||
- 这次是 Android Runtime 冒烟，前述第 19 项精确计数归属 GTest 由 Mac 原生测试覆盖；01 同 source/tile stencil、02 Metal、03 绘制异常注入仍缺，A1 整体 PARTIAL，A2/B/C 未实施。
|
||
|
||
## 2026-09-26 A1 新入口执行清单（RDC，NOT RUN）
|
||
|
||
通用 Core（当前 OpenGL 构建目录）：
|
||
|
||
```sh
|
||
cmake --build build-step088-opengl --target mbgl-test-runner -j3
|
||
build-step088-opengl/mbgl-test-runner --gtest_filter='RenderOrchestratorError.*:RenderSegmentDiagnostics.OldCacheReleaseCannotChargeReplacementAtSameIndex'
|
||
```
|
||
|
||
预期异常 observer/failed 与 cache 不复用、重试后 Reuse；第 19 项保持 1/1 PASS。Metal GTest `MetalRetainedAttachments.*` 需由 RDC 使用可在 Mac 主机执行且配置 `MLN_WITH_METAL=ON` 的 `mbgl-test-runner` 构建目录执行；先检查所用目录的 CMakeCache、目标和 Metal device，再编译、执行并记录命令与日志。不能用 iOS 静态库构建替代主机 GTest。真机/simulator 的创建失败、encoder 失败与 API Validation 仍单独执行。
|
||
|
||
Android 同源 stencil：以本提交标准脚本构建 Validation APK，打开 Particle Core Layer Validation → STEP-093 → STEP-097 SAME SOURCE STENCIL；依次选择 RR、RCR、CRR。每种拓扑在 CACHE ON 首帧、稳定 reuse、REBUILD CURRENT 后，再切 CACHE OFF 与 ON；保存每个检查点截图、`STEP097_STENCIL_PLAN/READY/DIAGNOSTICS` 日志及 `READ SNAPSHOT`。预期 `accepted=true`、`valid=true`、`fallback=false`，多个 retained 段分别 build/reuse，四层同一 source 的轮廓与填充在缓存切换后无残影/漏裁剪。再以相机移动强制重建；记录主目标与离屏结果。此清单是待执行判据，不能据此宣称像素 PASS。真正 GPU 绘制异常及下一帧 full fallback/recovery 需 RDC 专项注入；GTest 状态机不能代替它。
|
||
|
||
## 2026-09-26 A1 实测结果（覆盖上方待运行记录）
|
||
|
||
- Android/FZG1：新 APK 源码 `8c006ac83`，SHA-256 `48df19cf5a4c4250934efa2596423d3ad9571fe49a65b9b704a81cdb41f58671`；同 source/tile RR/RCR/CRR、重建、缓存 OFF/ON 18/18 状态与像素采样检查通过，无本次捕获的 FATAL。
|
||
- Core：03 `RenderOrchestratorError.*` 2/2 PASS；19 `OldCacheReleaseCannotChargeReplacementAtSameIndex` 1/1 PASS，诊断组 5/5 PASS。
|
||
- Metal：编译通过，2/2 SKIP（无 Metal device）；用户豁免 iOS runtime，标 `USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`，不是 iOS 运行测试 PASS。详见 `docs/报告/STEP-097_A1_Android专项验收报告_v1.md`。后续 A2/B/C 未执行。
|
||
|
||
## 2026-09-26 A2 中途静态/Core 结果（不是 A2 关闭）
|
||
|
||
- OpenGL `mbgl-test-runner` 编译 exit 0；定向 16/16 PASS；两次 Shader generator 均 exit 0 且输出一致。Metal host 可编译并执行同一跨 Core GTest 16/16 PASS，未运行 iOS 设备。
|
||
- 上述结果仅覆盖现有原生测试入口。Codex A2 代码尚未审查/提交，Android 设备/APK 仍 NOT RUN，不能推进 B/C。证据与完整边界见 `docs/报告/STEP-097_A2_阶段验证记录_v1.md`。
|
||
|
||
## 2026-09-26 A2 最终验证结果（RDC 独立执行）
|
||
|
||
### Core / Shader
|
||
|
||
- 原先因旧测试断言与既有语义不一致而失败的 58 项完整集合，在修复断言后 **58/58 PASS**。`sameFieldGpuContent()` 仍表达忽略 producer generation/dataVersion 的解码 payload 等价；`sameFieldGpuEndpoint()` 单独负责严格 GPU endpoint identity。
|
||
- 当前 broad filter 在 OpenGL 与 Metal host `mbgl-test-runner` 各 **121/121 PASS**。命令：
|
||
|
||
```sh
|
||
build-step088-opengl/mbgl-test-runner --gtest_filter='Particle*.*:Source.RasterArray*:Source.HostField*:Source.ParticleField*:Source.CanonicalField*'
|
||
build-step097-metal-host/mbgl-test-runner --gtest_filter='Particle*.*:Source.RasterArray*:Source.HostField*:Source.ParticleField*:Source.CanonicalField*'
|
||
```
|
||
|
||
- 三项 A2 Source 定向回归在 OpenGL 与 Metal host 各 **3/3 PASS**：mix-only 50 ticks 不重物化、真 endpoint 与 revision 变化触发物化、同步通知重入不双推进、clear fail-closed。
|
||
- `node shaders/generate_shader_code.mjs` 两次执行成功且输出幂等。Metal host 是 Mac 上 Core 测试，不是 iOS device runtime。
|
||
|
||
### Android / FZG1-2
|
||
|
||
- RDC 使用 `./tools/particle_android_validation/build_validation_apk.sh` 构建标准 OpenGL Debug x86_64 APK；61,753,803 bytes，SHA-256 `27bf4a6cc191bd86c4d1c10398478d81c2999edd61fe7242e40e5188516b0ca5`。FZG1-2 `192.168.200.139:5555` 安装成功，设备 APK SHA-256 相同。
|
||
- Test-App-only V4 Golden Wind T0/T1：load、seek 25/75、speed 2x/1x、PLAY 30 秒、PLAY 时 UI/TIME 可响应、PAUSE/stable pause、replay、CLEAR、reload、再次 PLAY/PAUSE；脚本 exit 0、17 PNG、24 steps、ANR=0。`05_play_15s.png` 可见粒子。30 秒场景闭环不是长期稳定性或性能测试。
|
||
- stable mix-only epoch 中 renderer 日志的 `fieldUploadCount=6/resetCount=2` 保持不变；explicit CLEAR/reload 后 upload 合法增至 10，reset 增至 4；reload 后 playback 稳定在该新计数。不能宣称跨 CLEAR/reload 零上传/零 reset。
|
||
- APK 工作树源 diff 与 `mix-reuse-build-source.diff` SHA-256 均为 `18927a5f30a88f5c1c3a00e0017473dc33b04151c227e4baf52250dc4ad2e6a2`，源码快照一致。原始 build/device/test 日志、steps 与截图位于 `artifacts/maplibre-particle/step097-a2-final-validation/`。
|
||
|
||
### 历史失败与范围
|
||
|
||
- 12:43 首次 ANR 为 synchronous Source notification 重入 forecast tick；`forecastTickInProgress` guard 与重入 GTest 已修复并覆盖。
|
||
- 后续无 ANR 但主线程仍高负载、PLAY/TIME 无响应的试跑由 debuggerd 定位到每 tick 重物化大场和深比较；mix-only immutable endpoint reuse 后通过本次 FZG1 闭环。旧失败日志和 debuggerd 保留，不从报告中删除。
|
||
- 本次不测 iOS runtime；标 `USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`。没有完成 GPU 性能基准、FPS/pXX 或长期运行测试。STEP-097 整体仍 PARTIAL，B/C 未开始；不包含 Jest、STEP-098、发布 `.13`。
|
||
|
||
### 2026-09-26 A2 源码独立 scoped commit 核验
|
||
|
||
- A2 的 26 个生产源码、shader、TestApp-only V4 Golden fixture 和定向测试文件已固定为 `f49ffa68a17e0a505199bdbeccf07f8543f3a05f` 并推送，`origin/particle/main` 回读一致；没有 stage 用户未跟踪 STEP-098。完整代码/设备证据仍见 `docs/报告/STEP-097_A2_阶段验证记录_v3.md`，不因 Git 提交改变原 APK 的 `git_dirty=true` 来源事实。STEP-097 整体 PARTIAL，B/C 待用户指令。
|
||
|
||
## 2026-09-26 B 阶段 RDC 实测与待闭合
|
||
|
||
- Mac Core 增量构建 PASS；B 的 JSON 严格校验、非法配置清除与恢复、数值溢出拒绝和合法 validity=0 四项 GTest：**4/4 PASS**。
|
||
- 扩大回归初次 132/134，旧 16-bit fixture 误用 4-byte UInt8 storage；修正为合法四样本 8-byte 小端之后重新编译，broad **134/134 PASS**，没有放宽生产校验。
|
||
- Test Host package.json/package-lock.json 的 RN tarball 均为正式 `13.4.1-particle.13`，实包 SHA-256/SRI 一致。
|
||
- Android 要分别验证本仓新源码的 MapLibreMap destroy listener JUnit 与 RN module 对正式 `.13` AAR 的 compile；前者不能替代后者。正式 .13 source commit 无 `addOnDestroyListener`，因此当前 bridge 存在 ABI 阻塞，不能标 Android consumer PASS。
|
||
- C、STEP-098、Jest 与正式发布不执行；完整证据见 `docs/报告/STEP-097_B_独立验收与版本阻塞报告_v1.md`。
|
||
|
||
## 2026-09-26 B 阶段 RDC 验证更新
|
||
- Mac 最新 GTest runner：定向 6/6、扩展 139/139 PASS，旧 broad 2 项失败经纠正测试 fixture 后消除；完整日志 `artifacts/maplibre-particle/step097-b-rdc/validation-*.log`。
|
||
- Android Native OpenGL Debug：`MapLibreMapDestroyListenerTest` 2/2 PASS；`compileOpenglDebugJavaWithJavac` exit 0；owner Kotlin 独立 JVM JUnit 4/4 PASS（源码 SHA 与当前 B10 一致）。隔离单测不能替代 React Native 模块与发布 AAR 精确配对编译。
|
||
- B10 当前默认 RN Gradle 对已发布 .13 Native AAR 依赖新缺失符号 `addOnDestroyListener`；RN consumer 校验标 `BLOCKED_NATIVE_AAR_COMPATIBILITY`，禁止记录 PASS 或覆盖 .13。Linux 独立 Gradle 状态另记，C 与 STEP-098 均不得越过此门槛。
|