MapLibreParticleLab/docs/60_测试/STEP-060_RNTestHost_Android人工编译与验收_v1.md

STEP-060 RN Test Host Android 人工编译与验收

本说明只列出人工步骤；Codex 未执行 Android Gradle、发布、安装或 ADB。

1. 确认当前为 particle/main，并记录 git rev-parse HEAD。Gate C 封存 Linux 环境是 custom MapLibre Native AAR 的构建环境；不要为 Test Host 生成工程的版本修改它。
2. 移走或清理 ~/.m2/repository/org/maplibre/gl/android-sdk-opengl/13.4.1/ 的旧 artifact，避免同坐标 provenance 混淆。2026-08-29 旧 AAR 的 SHA-256 是 5c67d2751fafe211a0df4b82deded09ab1c07cf6ca0f4a12a880283287f85e5c，只能作为 Gate C 历史证据。
3. 本轮唯一坐标是 org.maplibre.gl:android-sdk-opengl:13.4.1-step060f。必须先在 Linux 手工构建并 publish 这个新 AAR，记录 build output 与 Maven Local AAR SHA-256 且两者一致；不得复用 step060e 或先前 13.4.1 artifact。
4. 将该 AAR 按发布流程复制到 /mnt/nas/pbf/，Win11 用每次不同的 ?v=<cache-busting-value> 下载，核对 SHA-256 后安装 Maven Local。
5. cd integration/react-native/MapLibreParticleRNTestHost && npm ci && npx expo prebuild --platform android --clean。package-lock.json 已在无 --legacy-peer-deps 的 npm 安装下通过；不要改用 Yarn 或生成 yarn.lock。本次 plugin 变更后必须 clean prebuild。
6. 检查生成 root Gradle 有 MapLibreParticleRNTestHost custom OpenGL SDK、nativeVersion=13.4.1-step060f、nativeVariant=opengl；MLRN 与 Bridge 两条 dependencyInsight 都必须解析到 13.4.1-step060f。Maven Central 必须排除精确 custom module org.maplibre.gl:android-sdk-opengl，使该 AAR 缺失时失败而非 fallback。
7. 首次 prebuild 后实际记录 Test Host 的 Gradle wrapper、AGP、Kotlin plugin、min/compile/targetSdk、NDK、JDK、Hermes 与 New Architecture。当前观察到的 9.3.1/8.12.0/2.1.20/24/36/36/27.1.12297006 属于 Test Host 生成工程，不等于 Gate C 环境。
8. 再按实际生成工程编译。app.json 的 landscape 配置在本次 clean prebuild 后应使 MainActivity 生成 android:screenOrientation="landscape"；核对后以 scripts/05-install-and-run.ps1 安装启动。该脚本必须同时保持 adb -s 192.168.1.146 reverse tcp:8091 tcp:8091 与 adb -s 192.168.1.146 reverse tcp:8081 tcp:8091。
9. 对同一 reactTag 依次验证 Phase A：getState、enable、WeatherColor visible、particle visible、FPS 30 均得到结构化 Native result。
10. 验证 Phase B：stops、独立 particle/trail RGBA、count/line/length/opacity/fade 与 WeatherColor opacity。weather opacity 必须为 ACCEPTED，且不再出现 ParticleGPU: event=STYLE_PROPERTY_SET result=UNSUPPORTED_PROPERTY。无 Binary Field 时 PLAY/PAUSE、HALF/NORMAL/DOUBLE 与 epoch-ms seek 仍可因 TIMELINE_NOT_READY 返回 REJECTED；不得改变这个 fail-closed 行为，也不得出现 JS PLAYING/PAUSED 第二状态机。
11. 重载 style：旧 Runtime 必须 disposed；style ready attach 的新 Runtime 正常工作。remount Map 后，用旧 reactTag 调用必须返回 MAP_VIEW_NOT_FOUND，不得命中新 Map。
12. 卸载 Host：确认 view detach dispose；无持续 Handler wake、无全局 current map。通过上述 Android 验收后才进入 STEP-061；此前不要尝试 number[]、JSON/base64 大 field。