## Context

当前 app 已有短信验证码接收实现：Manifest 声明了 `RECEIVE_SMS`、`READ_SMS`，静态 `SmsReceiver` 监听 `android.provider.Telephony.SMS_RECEIVED`，`MainActivity` 提供权限申请、最近结果展示、`READ_SMS` 最新短信读取、ContentObserver 和短时轮询诊断。用户反馈“逻辑试过了能用”，但不确定为什么某些场景 `onReceive` 收不到。

目标设备是小米 12S、澎湃 OS 3、Android 15。根据 Android 官方文档，`RECEIVE_SMS` 允许应用接收 SMS，但它是 dangerous 且 hard restricted 权限，是否能真正持有可能受安装来源/安装器 allowlist 影响。Android 15 又新增了 `BOOT_COMPLETED` 启动部分前台服务类型的限制；Doze/App Standby 白名单也不是无限制后台执行。小米官方支持文档说明 HyperOS/小米系统存在“Background autostart”用户开关，路径为 Settings > Apps > Permissions > Background autostart。

参考资料：

- Android 15 前台服务类型变更：https://developer.android.com/about/versions/15/changes/foreground-service-types
- Android 15 行为变更：https://developer.android.com/about/versions/15/behavior-changes-15
- Doze/App Standby 与电池优化：https://developer.android.com/training/monitoring-device-state/doze-standby
- `RECEIVE_SMS` 权限：https://developer.android.com/reference/android/Manifest.permission#RECEIVE_SMS
- 小米后台自启动设置：https://www.mi.com/global/support/faq/details/KA-507608/

## Goals / Non-Goals

**Goals:**

- 先形成完整 spec，不直接写代码。
- 在当前可用短信接收 app 上补齐后台保活和开机恢复方案。
- 让用户能手动完成小米设置，并在 app 内看到哪些设置已完成、哪些只能人工确认。
- 让 `onReceive` 收不到时有明确诊断：权限、安装来源、force-stop、系统广播、HyperOS 后台策略、短信是否进入收件箱。
- 后续实现保持可解释、可关闭、可验证。

**Non-Goals:**

- 不做无通知、不可感知、规避系统策略的隐藏保活。
- 不承诺杀进程、force-stop、清后台、系统级省电清理后仍 100% 存活。
- 不把 C++ fork/native daemon 当成可靠能力；Android 应用沙箱和系统进程管理不会因为 native 代码而失效。
- 不把 app 做成默认短信客户端。
- 不要求本轮编译。

## API Strategy

### 1. 系统短信广播仍是主路径

短信进入设备时，主路径仍是 `SMS_RECEIVED_ACTION`。这是最直接的验证码捕获路径，但它依赖：

- 应用真正持有 `RECEIVE_SMS`。
- 应用未被用户 force-stop。
- 系统或厂商策略允许静态 receiver 在当前状态下被拉起。
- 短信确实由 Android Telephony 入库/分发，而不是被系统短信 app 或安全策略特殊处理。

现有 `SmsReceiver` 的 manifest 写法包含 `android:permission="android.permission.BROADCAST_SMS"`，该写法用于限制只有持有系统广播权限的发送方能投递该 receiver；系统短信广播通常满足此条件。后续诊断要验证它不是问题根因，但不建议先移除。

### 2. 前台服务用于“可见后台运行”，不用于读取短信

新增 `SmsKeepAliveService`：

- app 前台点击“开启常驻保活”后调用 `startForegroundService`。
- 服务在 5 秒内调用 `startForeground`，展示低打扰常驻通知。
- 通知内容显示“短信监听运行中”、最近一次心跳、最近一次短信来源。
- 服务只做状态心跳、通知刷新、诊断状态保存。
- 短信接收仍由 `SmsReceiver` 和收件箱兜底路径处理。

这样做的原因是前台服务可以提升后台进程可见性，但不能替代短信广播，也不能保证被厂商永不杀。它的价值是让系统和用户明确知道该 app 在后台运行，并给 HyperOS “省电无限制 + 自启动”一个更稳定的承载对象。

### 3. 开机自启动采用轻量 BootReceiver

新增 `BootReceiver` 监听：

- `android.intent.action.BOOT_COMPLETED`
- `android.intent.action.LOCKED_BOOT_COMPLETED`
- `android.intent.action.MY_PACKAGE_REPLACED`

收到后：

- 记录 boot 事件和时间。
- 检查用户是否曾开启“常驻保活”。
- 如果已开启，则尝试启动 `SmsKeepAliveService`。
- 捕获 `ForegroundServiceStartNotAllowedException` 等异常，写入诊断，不崩溃。

Android 15 对 `BOOT_COMPLETED` 启动前台服务的限制集中在 dataSync、camera、mediaPlayback、phoneCall、mediaProjection、microphone 等类型。当前保活服务不应声明这些类型；如果后续升级 targetSdk 到 35，仍必须真机验证 BootReceiver 启动服务是否被 HyperOS 额外限制。

### 4. 电池优化与 HyperOS 设置采用“检测 + 引导”

Android 标准能力：

- 用 `PowerManager.isIgnoringBatteryOptimizations(packageName)` 展示是否在电池优化白名单。
- 提供 `Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS` 打开白名单设置。
- 个人自用场景可考虑 `ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` 直接请求，但 UI 必须说明它仍不等于无限后台。

小米/HyperOS 能力：

- 提供“打开小米自启动设置”按钮，优先尝试常见 MIUI/HyperOS 安全中心组件。
- 如果显式组件不可用，回退 `ACTION_APPLICATION_DETAILS_SETTINGS` 和通用系统设置。
- UI 显示人工清单：
  - 权限：短信权限已授权。
  - 自启动：用户已在 HyperOS 开启。
  - 省电策略：用户已设为无限制。
  - 通知：常驻通知未被关闭。
  - 保活服务：正在运行。

自启动和省电无限制通常没有稳定公开 API 可直接读取真实状态，因此必须允许用户手动勾选“我已完成设置”，并把这部分标记为人工确认。

### 5. Native/C++ 方案只做实验诊断

可以加入一个可选 native heartbeat：

- Java 服务加载 native library。
- native 层定期写入一个本地 heartbeat 文件或通过 JNI 回调返回时间戳。
- 用于确认进程活着、JNI 正常、服务被杀后心跳停止。

不建议实现 native fork daemon：

- Android 应用进程被系统管理，子进程同属应用 UID/cgroup，厂商清理通常会一起处理。
- 后台私自 fork 常驻进程会带来电量、兼容性和安全风险。
- 对短信广播恢复没有直接帮助。

如果用户坚持尝试，必须放在“实验开关”下，并以诊断结论交付，不作为保活主链路。

## Why `onReceive` May Not Fire

后续 UI 和 logcat 诊断必须覆盖以下根因：

- `RECEIVE_SMS` 未授权，或因 hard restricted 机制安装后实际不可持有。
- app 被 force-stop；Android 不会为 force-stopped app 投递大多数隐式广播，直到用户再次打开。
- 小米自启动未开启，系统不允许后台拉起静态 receiver 或服务。
- 省电策略不是无限制，后台/锁屏/待机时进程或广播处理被延迟/限制。
- app 刚安装后从未启动，部分系统不会让 receiver 正常进入用户期望状态。
- 短信由运营商/RCS/系统短信能力特殊处理，未走普通 SMS_RECEIVED。
- 双卡或短信格式异常导致 PDU 解析失败，但此时 receiver 应该已有日志。
- Manifest receiver 被禁用、包名不匹配、构建安装的不是当前调试版本。
- 通知权限关闭不应直接阻止短信广播，但可能影响前台服务可见性和用户判断。

诊断顺序建议：

1. 看 UI 权限状态和最近 boot/service 心跳。
2. 发送短信时抓 logcat `SmsReceive`。
3. 如果 receiver 无日志，点“读取最新短信”确认短信是否入库。
4. 如果短信已入库但 receiver 无日志，重点排查权限、force-stop、HyperOS 自启动和省电。
5. 如果 receiver 有日志但无验证码，排查 PDU/body/parser。

## Data Model

新增 `KeepAliveState` 本地状态：

- `enabledByUser`: 用户是否开启常驻保活。
- `serviceRunning`: 最近一次服务 onCreate/onStartCommand/onDestroy 状态。
- `lastHeartbeatMillis`: 服务最近心跳。
- `lastBootEvent`: 最近一次 boot/package replaced 事件。
- `lastServiceStartFailure`: 最近一次服务启动失败原因。
- `batteryOptimizationIgnored`: 标准 Android 电池优化白名单状态。
- `manualAutostartConfirmed`: 用户手动确认已开启小米自启动。
- `manualBatteryUnrestrictedConfirmed`: 用户手动确认已设置省电无限制。
- `notificationEnabledHint`: 通知是否可能可见。

保存方式优先使用 `SharedPreferences`，与现有 `SmsCaptureStore` 保持简单一致。

## UI Strategy

首版继续使用现有 Java View UI，不引入新框架：

- 增加“后台保活状态”区域：
  - 保活开关。
  - 服务运行状态。
  - 最近心跳。
  - 最近开机事件。
  - 最近启动失败原因。
- 增加“系统设置”区域：
  - 打开应用详情。
  - 打开电池优化设置。
  - 请求忽略电池优化。
  - 打开小米自启动设置。
  - 人工确认自启动已开启。
  - 人工确认省电无限制已开启。
- 增加“短信广播诊断”区域：
  - 最近 `system_sms_broadcast` 时间。
  - 最近 `sms_inbox_*` 时间。
  - 当收件箱有新短信但广播未到时提示“疑似广播未投递”。

## Test Strategy

单元/本地测试：

- `KeepAliveStateStore` 读写测试。
- `BootReceiver` 在不同 action 下生成正确状态。
- `SmsKeepAliveService` 的状态更新逻辑抽出为纯 Java 方法测试。
- 设置 intent builder 测试：小米组件不可用时能 fallback。

ADB/真机验证：

- `adb shell am broadcast -a android.intent.action.BOOT_COMPLETED -n com.smsreceive.app/.BootReceiver`
- 重启手机后验证保活服务是否恢复。
- 开启保活通知后，后台 30 分钟、锁屏 30 分钟分别发送短信。
- 开启/关闭小米自启动、开启/关闭省电无限制，对比短信广播和收件箱兜底结果。
- 手动 force-stop 后发送短信，确认不承诺接收，并在再次打开 app 后展示诊断。
- Android Doze 测试可参考官方命令 `dumpsys deviceidle force-idle`、`am set-inactive`。

## Rollout Plan

1. 完成本 OpenSpec 并 validate。
2. 先实现 Java 层 BootReceiver、Foreground Service、通知和状态 UI。
3. 再补小米设置入口和人工确认状态。
4. 最后根据真机结果决定是否加入 native heartbeat 实验。
5. 如果前台服务/开机恢复在 HyperOS 上仍不稳定，交付时明确记录限制和必须手动设置项。

## Open Questions

- 当前安装方式是 Android Studio/adb 直装，还是包管理器/文件管理器安装 APK；这会影响 hard restricted SMS 权限表现。
- 用户是否接受常驻通知一直显示。
- 是否希望 app 开机后自动开启保活，还是必须用户先在 UI 中开启一次后才持久化。
- 是否需要 native heartbeat 实验；建议第一轮 Java 方案真机验证后再决定。