build: stabilize Android particle validation APK pipeline

docs/00_项目规范/07_Android粒子Validation_APK构建规范_v1.md

@@ -0,0 +1,68 @@
+# 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 脚本与本规范，再使用新流程；不得只在聊天或临时命令中形成新的事实基线。