# Android 环境、构建与交付

App 0.3.0 / versionCode 6 增加 BLE 会话内 WiFi 加速，协议 1.2；仅 debug。Android 使用固定 OkHttp 4.12.0，Gradle verification-metadata.xml 记录依赖 SHA-256。设备复用 FastAPI/uvicorn/cryptography，无新增板端依赖。保持设备 VERSION 和发布记录，不导出 OTA/IMG。

## 安装门槛

Android Studio 是正常安装软件，由用户运行已核验官方安装包。安装包放用户普通下载目录，不放仓库或 Codex bin。准备好后停止等待用户安装，不自动运行安装器。安装时建议采用默认位置，首次向导安装 Android SDK；不必创建项目，也不必先下载模拟器或 NDK。

首次完成后记录实际安装版本、JDK、SDK、Build Tools、Kotlin、Compose、AGP 与 Gradle 的兼容组合，锁入版本目录、Wrapper 和依赖校验文件。安装位置用环境探测／local.properties，不写到可提交源码。官方参考：

- https://developer.android.com/studio
- https://developer.android.com/studio/install
- https://developer.android.com/kotlin/multiplatform/plugin
- https://kotlinlang.org/docs/multiplatform/multiplatform-compatibility-guide.html

## 工程与路径

源码位于相邻 `安卓程序源代码/`，模块 androidApp、sharedCore、sharedUi。在 Android Studio 打开工程根，不分别打开子模块。先验证中文和空格路径；若 Android 工具拒绝该路径，通过受保护的仓库外 ASCII 构建目录同步源码并执行，结果回收到交付目录。同步只包含源码及明确资源，不复制私有登记、密钥、缓存或 `.git`；脚本记录源摘要，不覆盖用户目录。

已安装工具链：Android Studio Quail 4 Patch 1（用户确认中文）、JBR 25.0.3、SDK 37；工程固定 Gradle 9.5.0、AGP 9.3.1、Kotlin 2.4.20、Compose 1.12.1。Wrapper 使用官方发行地址和 SHA-256。首次 `:androidApp:assembleDebug` 与 `:sharedCore:jvmTest` 已在隔离 ASCII 路径通过；这只是骨架及协议验证，不等于功能验收。lint 与真实 BLE 已有通过记录，具体覆盖范围见测试结果归档。

在仓库根执行下列命令，参数替换为本机实际目录，不把替换后的路径提交：

```text
python "移动端相关内容/安卓app/构建与发布/build_android.py" --work-root "<受保护临时目录的ASCII路径>" --jdk "<Android Studio的jbr目录>" --sdk "<Android SDK目录>"
```

脚本每次创建独立 `qms-build-*` 子目录，只复制工程源码，忽略 build、.gradle、.kotlin、local.properties。默认使用 Wrapper；可用 `--gradle` 指定已核验的同版本 Gradle，避免重复下载。默认运行 JVM 测试和 assembleDebug，可在末尾显式传任务列表。保留构建目录用于查看测试报告和 `androidApp/build/outputs/apk/debug/androidApp-debug.apk`；验证后只清理本次明确目录。Android 调试签名沿用用户默认 Android 密钥目录，不复制到源码或隔离工程。

路径实测：AGP 默认拒绝非 ASCII 路径；启用 `android.overridePathCheck=true` 后编译继续，但当前 JBR／Gradle 下 JVM 测试出现类加载失败。在 ASCII 隔离目录同一测试通过，故当前使用该回退。2026-09-25 已在全新且包含空格的 ASCII 构建根目录重新执行全部 92 个任务，JVM 测试及两个 debug APK 均成功；保留中文源码位置。

## APK 与签名

- 应用名“奇妙小屏幕”，applicationId 为 `org.qimiaoscreen.controller`，minSdk 26，首版版本 0.1.0。
- 仅 debug 签名，沿用本机调试密钥并记录证书摘要（不记录私钥）。正式签名只有用户明确命令才配置或执行。
- 调试签名更换可能无法覆盖安装；不能自动卸载并清除用户配置来掩盖。需要时先报告原因。
- App versionCode 独立递增，设备版本／协议版本分别登记，不能因设备部署自动提升 App 版本。
- 每次交付放 `交付包/<App版本>-<versionCode>/`：APK、SHA256SUMS、manifest.json、README.md。manifest 包含 App／协议／兼容设备信息、源摘要、工具链版本和签名证书摘要，不包含本机路径或测试机标识。
- APK 与发布元数据保留在私有 Git 仓库，需要时沿用 Git LFS；构建缓存、SDK、真实登记、调试及正式签名私钥都不提交。
- 本任务不导出核桃派 IMG／OTA；设备功能时间按根规则更新，设备发布版本不因普通部署占号。

## 交付前检查

从隔离目录依文档重新构建并验证；按 [影响选测](../如何安卓测试/按影响选测.md) 完成相关验证；仅通信路径/平台行为受影响时做相应协议互操作和定向真实 BLE 联调；运行根仓库卫生检查。交付说明准确区分通过、未验证和不适用。第二台手机验收 APK 放到同一清晰可找到的交付目录，用户安装后再进行实机互斥测试。

## 可重复打包

```text
python "移动端相关内容/安卓app/构建与发布/package_debug.py" --build "<本轮隔离工程目录>" --sdk "<Android SDK目录>"
```

运行前将 JAVA_HOME 指向正常安装的 Android Studio jbr。脚本逐文件核对隔离工程与当前源码的 SHA-256，调用 Build Tools 36.0.0 的 apksigner 验证 Android Debug 证书，创建版本独立目录，保存 APK、摘要、工具链和源文件清单。已存在交付目录拒绝覆盖。结果默认标为开发验证包，必须结合测试报告说明验收范围，不用打包成功替代验收。versionCode 2 包含本轮连接清理和界面信息补充，可覆盖同证书的 code 1。

本轮 App 0.2.0 / versionCode 3 为四栏界面及设备记忆优化，仍仅 debug 签名。关于页显示本次 Gradle 构建日期（北京时间），不修改设备发布版本。

## 构建排障与测试复盘

手动调用隔离工程 Wrapper 时，每个新 shell 都须明确使用已登记的 JDK/SDK（JAVA_HOME/ANDROID_HOME）；前一工具调用的进程环境不会自动传到下一次调用。缺少 SDK location 时先检查环境，不重复下载工具、不改动中文源码位置。

Gradle Kotlin DSL 里 `java` 可能被插件扩展名遮蔽；构建日期实现显式 import `ZonedDateTime`、`ZoneId`、`DateTimeFormatter`，避免直接以 `java.time...` 引用引发解析错误。日期仍使用北京时间，不通过硬编码本机路径解决。

Python 在 Windows 缺少 IANA tzdata 时，固定北京时间时间戳可使用标准库 `timezone(timedelta(hours=8))`；这一方法只适用于明确要求的固定 UTC+08:00 时间，不当作任意地区夏令时转换方案，也不因该情况自动新增依赖。

打包前重新核对隔离源码、实际 APK、构建日期和签名摘要；测试源码调整也要同步隔离工程，不能测试旧测试 APK。测试/构建遇到的新问题在完成后更新相应文档并在最终反馈说明，具体输入和真机排障见 [测试排障指南](../如何安卓测试/常见问题与排障.md)。

Android 0.2.1 / versionCode 4：顶栏长文本循环、连接条目断开／扫描保留、居中预览；仅debug签名。交付和本轮覆盖范围见交付包0.2.1-4及测试结果归档2026-09-27_界面细节优化。

独立模拟器 UI 测试 APK 构建任务为 `:uiTest:assembleDebug`，只用于验证，不进入产品交付包；测试框架调整不提升产品版本。

Android 0.2.2 / versionCode 5：显示内容两档图片传输、128 MiB 本地缓存及软件设置清空；协议 1.1 增量能力，仍只允许 debug 签名。设备功能部署沿用回滚开发流程，正式设备版本不因本次开发部署递增。验收以本轮测试归档为准。