docs(android): record FZG MapLibre 13.6.1 APK installation verification

docs/50_Step记录/STEP-105_FZG1-2_MapLibre13.6.1打包安装记录_v1.md

@@ -0,0 +1,11 @@
+# STEP-105 FZG1-2 MapLibre Native 13.6.1 Validation APK 安装记录
+
+- 日期：2026-10-09（JST）
+- 代码来源：官方 Native Android 13.6.1 + Particle .21 迁移候选，分支 `upgrade/android-native-13.6.1-20261009`，构建源提交 `30d0e6665e`。
+- 构建与目标：Mac，`MapLibreAndroidTestApp`、OpenGL Debug、Native x86_64，Gradle 6m48s 初次完成；因 Sentry 辅助库多 ABI 被旧检查规则拒绝；修订验证规则后增量 Gradle 10s，ZIP/ABI/体积检查 PASS。
+- 脚本修改：`tools/particle_android_validation/build_validation_apk.sh` 仅允许非目标 ABI 中已确认的 Sentry 库；`libmaplibre.so` 与 Custom Layer 必须仍为 x86_64；独立提交 `73db0356ac5860366f314ddba23b716220e7c16a`。
+- APK：`artifacts/maplibre-particle/step105-native1361-fzg/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk`，66,505,502 字节，SHA-256 `77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa`。
+- 设备：FZG1-2 / Android 13 / ADB `192.168.200.139:5555`。覆盖安装 `adb install -r` **Success**；设备实际版本 `13.6.1`，签名一致、首次安装日期不变，设备文件 SHA 与 Mac 完全一致。
+- NavSea 仍为前台 App，未主动启动测试 App；运行、GPU 绘制、RenderSegment 等仍 **NOT RUN**，不可写成已通过。
+- 回退：旧版 13.4.1-particle.21 APK 已独立保存于忽略目录 `artifacts/.../rollback/`，未纳入 Git。
+- Gate：本阶段 **APK_BUILD_AND_INSTALL_PASS**；下一阶段是 FZG 可视运行及完整功能回归。

docs/报告/STEP-105_FZG_MapLibre13.6.1测试APK打包安装_RDC执行报告_v1.md

@@ -0,0 +1,59 @@
+# STEP-105 Android Native 13.6.1 — FZG1-2 Validation APK 打包与安装 RDC 执行报告 v1
+
+## 1. 结论
+
+**APK_BUILD_PASS / FZG_INSTALL_PASS / DEVICE_APK_HASH_PASS / RUNTIME_NOT_RUN**。
+
+本次在 Mac 使用官方 MapLibre Native Android 13.6.1 + Particle .21 升级候选打包 `MapLibreAndroidTestApp`，通过 FZG1-2 的 ADB 覆盖安装，并在设备端核对实际版本和完整 APK SHA-256。没有安装 NavSea，也没有声明粒子运行态通过。
+
+## 2. 环境与版本
+
+- Mac 目录：`/Users/tei/dev/MapLibreParticleLab-upgrade-android-1361`
+- 源码分支：`upgrade/android-native-13.6.1-20261009`
+- 构建源 HEAD：`30d0e6665eb16a258e47b3a8cc0d16932e43762b`
+- 底座 Native：`android-v13.6.1`；OpenGL Debug，Native ABI `x86_64`
+- Test App 包名：`org.maplibre.android.testapp`；新版本 `13.6.1`，`versionCode=14`，`targetSdk=35`。
+- FZG：`FZG1-2` / Android 13 / `192.168.200.139:5555`，`ro.product.cpu.abi=x86_64`；另一台 Odin 不在修改范围。
+- 工具：Mac JDK17、Android SDK/NDK、Gradle `--console=plain`；缺失的 Android SDK Platform 35 已经由 Gradle 获取。
+
+## 3. APK 构建与失败恢复
+
+使用项目原有 `tools/particle_android_validation/build_validation_apk.sh`。
+
+1. 第一轮 Gradle `:MapLibreAndroidTestApp:assembleOpenglDebug` 编译 **BUILD SUCCESSFUL in 6m 48s**，但原 Validation 脚本要求 APK 全部 ABI 集合精确为 `x86_64`。实际 APK 其他 ABI 含有 Sentry 日志库 `libsentry.so` / `libsentry-android.so`，因此脚本按照 fail-closed 策略拒绝打包，未安装。
+2. 调整 `tools/particle_android_validation/build_validation_apk.sh`：所有非目标 ABI 的文件只接受 `arm64-v8a`、`armeabi-v7a`、`x86` 下这两种 Sentry 库；其它意外 Native 库仍拒绝。额外确认 `lib/x86_64/libmaplibre.so`、`lib/x86_64/libexample-custom-layer.so` 存在；保持 APK 体积及 `libmaplibre.so` 体积上限。
+3. 脚本通过 `bash -n`、`git diff --check`；增量 Gradle **BUILD SUCCESSFUL in 10s**，脚本报告 **BUILD SUCCESS**。
+4. 修改脚本单独 Git commit：`73db0356ac5860366f314ddba23b716220e7c16a`。APK 的 `build-info.txt` 记录源码 HEAD `30d0e6665e` 且当时 `git_dirty=true`，因为脚本尚未提交；这里如实保留这一构建时事实，不能把后续 commit 当作已经编入 APK 的 C++ SHA。
+
+## 4. APK 最终产物
+
+- 相对路径：`artifacts/maplibre-particle/step105-native1361-fzg/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk`
+- APK 字节数：`66,505,502`。
+- `libmaplibre.so` 在 APK 内的字节数：`39,970,088`。
+- SHA-256：`77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa`。
+- `aapt dump badging`：`org.maplibre.android.testapp` / `versionName=13.6.1`。
+- `apksigner verify` PASS；校验日志中的非致命 META-INF 元信息警告不代表签名失败。
+- APK 同时携带三种其它 ABI 的 *Sentry 辅助库*；`libmaplibre.so` 和 Test App Custom Layer 均仅为 x86_64。产物命名中的 x86_64 指 MapLibre Native 编译目标，不表示 APK 没有任何其它架构的 Sentry 依赖。
+
+## 5. FZG 安装与设备端回读
+
+- 安装前原版：`13.4.1-particle.21`，包名相同。
+- 从设备拉取旧 APK，`apksigner verify --print-certs` 核对新旧证书 SHA-256 均为 `e3f8fae6451ed6322259d090dd8e8788df554ab25ed89a01c78014f1d5ef8236`，允许正常覆盖。
+- 安装命令：`adb -s 192.168.200.139:5555 install -r <APK>`。
+- ADB 明确返回 **Success**，完成时间 **2026-10-09 12:03:06 JST**。
+- `dumpsys package`：`versionName=13.6.1`，`lastUpdateTime=2026-10-09 12:03:06`，`firstInstallTime=2026-09-22 07:34:56`，未卸载重装。
+- `adb shell sha256sum /data/app/.../base.apk` 返回 `77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa`，与 Mac 本地 APK 字节级一致。
+- 安装后 FZG 前台仍是 `com.navsea.app/.MainActivity`。这不是 NavSea 更换 Native AAR/npm，也未更改 NavSea 本身。
+
+## 6. 回退与未完成内容
+
+- 安装前旧 APK 备份在（Git 忽略目录）：`artifacts/maplibre-particle/step105-native1361-fzg/rollback/MapLibreAndroidTestApp-original-13.4.1-particle.21.apk`，SHA-256 `999f773276b29fffae05c1edc977e19df6cebecd94e4a4095508d0c5e97e07c2`。无需重新下载旧版 APK；尚未执行回退。
+- **NOT RUN**：Test App 前台启动、GPU 粒子动画/QBIN/T0/T1、地图 pan/zoom/rotation、RenderSegment retained、Style/layer unload/reload、崩溃/帧性能、其它 ABI、RN 11.5.0 和 iOS。
+- 下一阶段建议使用已安装的 FZG 测试 App 进行上述真实 GPU/生命周期回归，验收完成后再考虑升级分支合并或发布。
+- 本任务通过 RDC 直接构建/安装，**没有调用 Codex 模型或替换 Codex 工作**。与此前 STEP-104 的 GPT-6.1 Sol/High 实施范围不同。
+
+## 7. 记录与 Git
+
+- Root `recoder_step.md` 追加事实，`docs/50_Step记录/` 单独记录，完成报告写入 `docs/报告/`。
+- 脚本代码 commit `73db0356ac5860366f314ddba23b716220e7c16a`。本次文档提交与 push、远端 HEAD 由 RDC 单独验收，最终结果以实际 Git 回执为准。
+- 只推送 `upgrade/android-native-13.6.1-20261009`；正式 `particle/main` 不更新。

recoder_step.md

@@ -44,3 +44,16 @@
 - 产物：`platform/android/MapLibreAndroid/build/intermediates/cmake/openglDebug/obj/x86_64/libmaplibre.so`，ELF 64-bit x86-64 动态库，包含 debug_info，大小 `377246848` bytes，SHA-256 `ff5a5eb45f84ff633a87fe385fb04ee39ba63ed3bc486003408e02cea78c8907`。
 - Gate 结论：**Android x86_64 / OpenGL Native compile+link PASS**。这不是 APK 实机验证，不是全 ABI、Vulkan/iOS/RN 11.5.0/发布 PASS；其他 ABI 和运行态 Gate 暂未执行。
 - 下一步建议：保留此为可复验的 Native 编译检查点；下阶段批量执行 Android 多 ABI 编译与 Test Host GPU 场景（Field/QBIN、Pan/Zoom/Rotate、RenderSegment、Style lifecycle），确认后再推进 RN 11.5.0。
+
+## 2026-10-09 / STEP-105 / FZG1-2 Android 13.6.1 Validation APK 打包及安装
+
+- 范围：Mac 的 `upgrade/android-native-13.6.1-20261009`，Native/源码基线 `30d0e6665eb16a258e47b3a8cc0d16932e43762b`；仅 Android Test App，未修改 NavSea、`particle/main`、iOS 或共享合同。
+- 设备：FZG1-2，ADB `192.168.200.139:5555`，Android 13、首选 ABI `x86_64`；未操作另一台 Odin。
+- 打包：使用 `tools/particle_android_validation/build_validation_apk.sh`，Gradle `:MapLibreAndroidTestApp:assembleOpenglDebug -Pmaplibre.abis=x86_64 -Pmaplibre.validation.stripNativeDebugSymbols=true --console=plain`。第一轮 Gradle **BUILD SUCCESSFUL in 6m 48s**，但验证脚本因 Sentry 辅助动态库同时包含其它 ABI 而拒绝；没有安装不合格包。
+- 修复：脚本仍严格要求 MapLibre 与 example-custom-layer 仅有 x86_64，并仅对白名单 `libsentry.so` / `libsentry-android.so` 允许 arm64-v8a、armeabi-v7a、x86 的辅助库；其余意外 ABI 库 fail-closed。第二轮增量 Gradle **BUILD SUCCESSFUL in 10s**，完整 ZIP/ABI/包体校验 **PASS**；脚本独立提交 `73db0356ac5860366f314ddba23b716220e7c16a`。
+- 产物：`artifacts/maplibre-particle/step105-native1361-fzg/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk`，package `org.maplibre.android.testapp`，versionName `13.6.1`，66,505,502 bytes，Native `libmaplibre.so` 打包后 39,970,088 bytes；SHA-256 `77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa`。
+- 安装前验证：FZG 已安装旧版 `13.4.1-particle.21`，旧新 APK 签名证书 SHA-256 均为 `e3f8fae6451ed6322259d090dd8e8788df554ab25ed89a01c78014f1d5ef8236`。
+- 安装：Mac `adb -s 192.168.200.139:5555 install -r <APK>` 返回 **Success**，2026-10-09 12:03:06 JST 完成；FZG `dumpsys package` 返回 versionName=`13.6.1`，firstInstallTime 仍为 2026-09-22 07:34:56，未卸载/清除原有应用数据；设备上已安装 APK 的 SHA-256 与 Mac 文件一致。
+- FZG 原版 APK 备份：`artifacts/maplibre-particle/step105-native1361-fzg/rollback/MapLibreAndroidTestApp-original-13.4.1-particle.21.apk`（不纳入 Git），SHA-256 `999f773276b29fffae05c1edc977e19df6cebecd94e4a4095508d0c5e97e07c2`。
+- 当前 FZG 前台依旧 `com.navsea.app/.MainActivity`；本轮不自动启动 Test App，未进行 Particle/RenderSegment GPU 画面或功能回归。
+- 结论：**APK_BUILD_PASS / FZG_INSTALL_PASS / INSTALLED_FILE_SHA_PASS / RUNTIME_NOT_RUN**。下一步单独进行 FZG Test App 启动、粒子/QBIN、Pan/Zoom/Rotate、RenderSegment/Style/卸载的真机运行验收。

tools/particle_android_validation/build_validation_apk.sh

@@ -97,7 +97,14 @@ fi
 unzip -tq "$SOURCE_APK" >/dev/null || fail "APK ZIP integrity check failed."
 
 ABI_LIST="$(unzip -Z1 "$SOURCE_APK" | sed -n 's#^lib/\([^/]*\)/.*#\1#p' | sort -u | tr '\n' ' ' | sed 's/ $//')"
-[[ "$ABI_LIST" == "x86_64" ]] || fail "Unexpected APK ABI set: [$ABI_LIST]"
+# The Android 13.6.1 Test App includes Sentry auxiliary libraries for other ABIs.
+# Only x86_64 may contain MapLibre or CustomLayer native code; do not reject
+# harmless, explicitly whitelisted Sentry files or relax the core ABI contract.
+[[ " $ABI_LIST " == *" x86_64 "* ]] || fail "x86_64 ABI missing: [$ABI_LIST]"
+UNEXPECTED_ABI_LIBS="$(unzip -Z1 "$SOURCE_APK" | grep '^lib/' | grep -v '^lib/x86_64/' | grep -Ev '^lib/(arm64-v8a|armeabi-v7a|x86)/libsentry(-android)?\.so$' || true)"
+[[ -z "$UNEXPECTED_ABI_LIBS" ]] || fail "Non-target ABI contains unexpected libraries: [$UNEXPECTED_ABI_LIBS]"
+[[ -n "$(unzip -Z1 "$SOURCE_APK" | grep '^lib/x86_64/libexample-custom-layer\.so$')" ]] || fail "lib/x86_64/libexample-custom-layer.so missing."
+
 
 LIB_BYTES="$(unzip -l "$SOURCE_APK" 'lib/x86_64/libmaplibre.so' | awk '/lib\/x86_64\/libmaplibre\.so$/ {print $1}')"
 [[ -n "$LIB_BYTES" ]] || fail "lib/x86_64/libmaplibre.so not found in APK."
@@ -124,6 +131,7 @@ git_dirty=$GIT_DIRTY
 built_at_utc=$BUILT_AT_UTC
 variant=OpenglDebug
 abi=x86_64
+bundled_abis=$ABI_LIST
 strip_native_debug_symbols=true
 apk=$OUT_APK
 apk_bytes=$APK_BYTES