8.0 KiB
STEP-072 V3-08 Android 单次综合验收
历史 V3 验收文档。 本文的 Native
.2、Maven Local、旧 reverse/临时路径仅描述 STEP-072 当时事实；当前 QBIN V4.3验收请改读docs/00_项目总则/当前基线与开发路线_v2.md与docs/50_Step记录/STEP-080_Android_AAR与RNTestHost标准构建流水线_v2.md。
状态与边界
本文件只列出用户手工执行的单次 Android 验收流程。目标组合是 RN/TS 13.4.1-particle.3 与 Native cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.2。.2 是 STEP-069 v2 multi-plane 所需的新坐标；不得复用、覆盖或误用旧 .1。
执行前记录当前 commit。所有 Gradle 调用均使用 --console=plain；所有设备命令均显式指定 adb -s 192.168.1.146。本流程完成前不得将 AAR、发布、Android 或 bridge 验收写为 PASS。
1. Native .2 Release AAR 与 Maven Local
在 /mnt/sda1/MapLibreParticleLab/platform/android 手工确认 VERSION 为 13.4.1-particle.2，然后执行 OpenGL Release AAR 构建与 Maven Local 发布：
make RENDERER=opengl BUILDTYPE=Release JOBS=1 \
'MLN_ANDROID_GRADLE=./gradlew --console=plain --parallel --max-workers=$(JOBS) -Pmapbox.buildtype=$(buildtype) -Pmapbox.stl=$(MLN_ANDROID_STL) -Dorg.gradle.internal.http.socketTimeout=$(SOCKET_TIMEOUT) -Dorg.gradle.internal.http.connectionTimeout=$(CONNECTION_TIMEOUT)' \
apackage
./gradlew :MapLibreAndroid:publishOpenglreleasePublicationToMavenLocal --console=plain
上述 make 写法已用 make -n 验证，最终 Gradle 命令包含 --console=plain、--max-workers=1、-Pmapbox.buildtype=release 和 -Pmaplibre.abis=all；不要把 MLN_ANDROID_GRADLE 只作为环境变量放在 make 前面，因为 Makefile 的普通赋值会覆盖环境变量。
记录构建产物 MapLibreAndroid/build/outputs/aar/MapLibreAndroid-opengl-release.aar 的 SHA-256，并与 Maven Local .2 AAR 的 SHA-256 比对；二者必须完全一致。
AAR 不是可直接传给 javap 的 JAR；先提取 classes.jar：
M2_AAR="$HOME/.m2/repository/cc/navsea/maplibre/android-sdk-particle-opengl/13.4.1-particle.2/android-sdk-particle-opengl-13.4.1-particle.2.aar"
unzip -p "$M2_AAR" classes.jar > /tmp/step072-particle2-classes.jar
javap -classpath /tmp/step072-particle2-classes.jar -public org.maplibre.android.maps.WeatherRuntime \
| grep -E 'submitField|clearFields|setFieldValueSource|setParticleAdvectionScale'
若任一方法缺失、AAR 坐标不是 .2 或 SHA 不一致，停止后续 Test Host 验收。
2. Linux → Win11 Native .2 handoff
若 Test Host 继续按已验证的 CARBON7i/Win11 流程构建，则 Linux Maven Local 发布完成后，必须把同一 .2 的 AAR、POM、module 三个文件传到 Win11，并放入 Win11 当前用户的 Maven Local 对应目录；不能只复制 AAR，也不能让 Win11 fallback 到 .1 或官方 SDK。
目标目录结构：
%USERPROFILE%/.m2/repository/cc/navsea/maplibre/android-sdk-particle-opengl/13.4.1-particle.2/
android-sdk-particle-opengl-13.4.1-particle.2.aar
android-sdk-particle-opengl-13.4.1-particle.2.pom
android-sdk-particle-opengl-13.4.1-particle.2.module
Win11 上再次计算 AAR SHA-256，必须与 Linux build output 及 Linux Maven Local AAR 三者一致。可用 Get-FileHash <AAR路径> -Algorithm SHA256。完成后再进入 Test Host clean prebuild。若直接在 Linux 同机编译 Test Host，则可使用该机 Maven Local，不需要此 handoff；但不得因此省略 artifact SHA/API 检查。
3. Test Host 单次 Android 周期
沿用已验证的 CARBON7i/Win11 流程时，在 Win11 当前 Test Host checkout 根目录执行下面的 PowerShell 命令。先 clean prebuild，再用 dependencyInsight 确认 app 最终只解析到 cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.2，然后只编译一次 Debug APK：
npm ci
npx expo prebuild --platform android --clean
Set-Location android
.\gradlew.bat :app:dependencyInsight --dependency android-sdk-particle-opengl --configuration debugRuntimeClasspath --console=plain
.\gradlew.bat :app:assembleDebug --console=plain
Set-Location ..
dependencyInsight 中若出现 .1、官方 org.maplibre.gl:android-sdk-opengl 最终胜出，或 .2 未解析，立即停止，不安装 APK。
在另一个 Win11 PowerShell 窗口启动 Metro，固定监听 8091：
npm run start
Metro ready 后执行固定设备安装/启动命令；每条 ADB 都必须显式带设备地址：
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 install -r android/app/build/outputs/apk/debug/app-debug.apk
adb -s 192.168.1.146 shell am force-stop org.maplibre.particle.rntesthost
adb -s 192.168.1.146 shell am start -n org.maplibre.particle.rntesthost/.MainActivity
Metro binary asset extension 必须仍为 .f32 与 .u8。本轮 Test Host 只做这一轮 clean prebuild + Debug APK 编译/安装，不为单个数据组重复编译 APK。
4. 五组 field 数据逐组验收
对每一组分别先 clear，再按 T0、T1 顺序加载，且每次均记录页面结果和 logcat：
| 数据组 | plane/粒子期望 |
|---|---|
| Wind real | vector；Wind/GLOBAL 粒子显示 |
| Rain scalar-only | scalar；不得显示粒子 |
| Wave scalar+DIRECTION | scalar + direction vector；色场与粒子均可用 |
| Tide VELOCITY | vector velocity；粒子可用 |
| Wave synthetic independence | scalar + direction vector；专用于独立性检查 |
每一组都必须依序满足 T0=ACCEPTED_PENDING_INITIAL_WINDOW、T1=INITIAL_WINDOW_READY，并使最终 Runtime=READY。任一状态不同、出现拒绝或 Runtime 非 READY，记录失败组并停止将该组标记为通过。
对每个 Runtime READY 的数据组验证：PLAY/PAUSE、HALF/NORMAL/DOUBLE、seek T0/T1、AUTO/30/60 FPS，以及 Field/Particle 的独立显隐。额外检查 Wave synthetic independence：scalar 色场和 direction particle 的表现及开关互不绑定；Rain scalar-only 不得出现粒子。
5. Logcat 与结论
使用固定设备筛查 logcat，观察 v2 submit、initial window ready，以及 fatal bridge/JNI 错误：
adb -s 192.168.1.146 logcat -c
adb -s 192.168.1.146 logcat -v time | Select-String -Pattern 'submitField|INITIAL_WINDOW_READY|initial window ready|WeatherRuntime|FATAL EXCEPTION|JNI|bridge'
记录每组的 T0/T1/READY 证据、控制项结果、AAR SHA 比对、javap 输出摘要及 logcat。仅当五组均符合要求且无 fatal bridge/JNI 错误时，才可由用户决定更新 Android 验收状态；本文件本身不代表已执行或通过。
2026-09-11 V3-08 最终关闭
状态：CLOSED / PASS。
Win11/CARBON7i 使用 Gradle 8.14.3、AGP 8.12.0、Kotlin 2.1.20、JDK 17.0.18、NDK 27.1.12297006、compileSdk/targetSdk 36、minSdk 24 完成正式 npm 消费链与 Debug APK 构建。dependencyInsight 最终解析到 cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.2。
实体机 192.168.1.146 上五组数据均满足 T0=ACCEPTED_PENDING_INITIAL_WINDOW、T1=INITIAL_WINDOW_READY、最终 Runtime=READY：Wind real、Rain scalar-only、Wave real、Tide/Current、Wave synthetic independence。
控制面 PLAY/PAUSE、HALF/NORMAL/DOUBLE、FPS AUTO/30/60、seek T0/T1、Weather/Particle 独立显隐、Field stops、Particle color、Trail color、Apply visual 均返回 ACCEPTED；最终 FATAL/JNI/UnsatisfiedLinkError 扫描为空。
测试期间发现 fixture 位于 Metro project root 外，临时 Win11 D:\V308 验收 worktree 通过 watchFolders 纳入 integration/react-native/particle-v3-fields 后 bundle 成功。该临时 Metro 修改不进入正式仓库，不属于 Native/RN Runtime 缺陷。
最终产物：Native .2 AAR SHA-256 f890f834692d3cacb8a281b2d0f82cf4a7f8ba7756132092be800505b961e9a2；RN .3 tgz SHA-256 16e5dab86aac9832f7a48d8c35dd9821f80f52e7e53ff4e0e6c98724781eda3a；APK SHA-256 49824062CAB72771282294114B5A818D2067F9B786B8697D2D2A983BF0B743E2。