# Android 粒子 Validation APK 构建规范 v1

## 目的

固定 `MapLibreAndroidTestApp` 粒子验证 APK 的制作流程，避免每次重新调查 Gradle 参数、Java/Android SDK 环境、native strip 与 APK 体积异常。

权威入口：

```bash
./tools/particle_android_validation/build_validation_apk.sh
```

除排错外，不再手工拼接 Validation APK 的 Gradle 命令。

## 固定构建契约

```text
App: MapLibreAndroidTestApp
Renderer: OpenGL
BuildType: Debug
ABI: x86_64
Native debug symbols: strip
Gradle console: plain
```

核心参数固定为：

```text
:MapLibreAndroidTestApp:assembleOpenglDebug
-Pmaplibre.abis=x86_64
-Pmaplibre.validation.stripNativeDebugSymbols=true
--console=plain
```

## 必须执行的防错逻辑

1. 构建前删除目标 APK 文件，但不做全量 Gradle clean。
2. Java 必须为 17；Android SDK 必须可解析。
3. 构建失败时不得复用旧 APK。
4. 构建成功后必须校验 APK ZIP 完整性。
5. APK 内 native ABI 必须只有 `x86_64`。
6. 必须包含 `lib/x86_64/libmaplibre.so`。
7. 默认 `libmaplibre.so` 不得超过 80 MiB。
8. 默认 APK 不得超过 100 MiB。
9. 必须记录 SHA-256、commit、branch、dirty 状态和完整 Gradle 日志。

STEP-090/091 的正常 APK 参考体积约 57 MB。数百 MB 通常表示未 strip native debug symbols；约 95 MB 且 ZIP 逻辑内容仍约 60 MB，通常表示同一路径增量打包残留旧 ZIP 尾部数据。

## 标准产物目录

```text
artifacts/maplibre-particle/android-validation/
├── MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
├── build-info.txt
└── build.log
```

该目录为本地验证产物目录，不进入 Git。

## 边界

本 Pipeline 只负责构建和 APK 自验，不负责 ADB 安装、Activity 启动、设备交互或 STEP 业务场景验收。

Android 上机验证仍由后续独立步骤执行。构建成功不等于 STEP 场景已通过。

## 变更规则

若未来测试 App、ABI、Renderer、strip 策略或产物门槛发生正式变化，应先修改 Pipeline 脚本与本规范，再使用新流程；不得只在聊天或临时命令中形成新的事实基线。