71 lines
5.3 KiB
Markdown
71 lines
5.3 KiB
Markdown
## Why
|
||
|
||
当前 `SmsReceive` 已经能在部分场景接收并解析验证码短信，但目标设备是小米 12S、澎湃 OS 3、Android 15，后台策略比标准 Android 更激进。仅靠 `SMS_RECEIVED_ACTION` 静态广播不够，需要补齐“开机后自动恢复监听、后台运行可见、系统设置可引导、失败可诊断”的完整方案。
|
||
|
||
这次需求的重点不是规避系统限制，而是在个人自用 sideload/debug app 的边界内，把 Android 官方后台机制、HyperOS 人工设置、短信广播兜底路径和可验证诊断组合起来。用户也会手动在小米设置中开启“自启动”和“省电策略-无限制”，因此方案应显式利用这个前提。
|
||
|
||
## What Changes
|
||
|
||
- 新增小米/Android 15 后台保活规格，覆盖：
|
||
- 开机自启动：注册 `BOOT_COMPLETED`、`LOCKED_BOOT_COMPLETED`、`MY_PACKAGE_REPLACED`，开机后恢复轻量状态并尝试启动保活服务。
|
||
- 通知栏常驻：增加前台服务 + 低打扰常驻通知，用于让进程在后台更可见、更不容易被系统回收。
|
||
- 短信广播链路：保留当前 `RECEIVE_SMS` + `SMS_RECEIVED_ACTION` 主路径，增加更清晰的“为什么 onReceive 收不到”的诊断。
|
||
- 服务链路：增加 `SmsKeepAliveService`，只负责常驻通知、状态心跳和轻量诊断，不在服务内做耗时短信扫描。
|
||
- 收件箱兜底：保留 `READ_SMS` 最新短信读取、ContentObserver、手动读取和短时轮询，用于确认短信已入库但广播未到达的场景。
|
||
- HyperOS 设置引导：提供打开应用详情、忽略电池优化设置、小米后台自启动设置的入口，并在 UI 展示用户需要手动完成的清单。
|
||
- Native/C++ 尝试边界：允许加入 NDK native heartbeat 作为实验诊断，但不把 C++ fork/daemon 作为可靠保活主方案。
|
||
- 明确 Android 15 限制：
|
||
- `RECEIVE_SMS` 是 dangerous 且 hard restricted 权限，安装来源/安装器 allowlist 可能影响授权。
|
||
- Android 15 对 `BOOT_COMPLETED` 启动部分类型前台服务有限制，不能把 dataSync/media 等类型当成开机拉起通道。
|
||
- Doze/App Standby 即使加入电池优化白名单也仍会有部分限制，必须用真机验证而不是只看 API 成功。
|
||
- 不直接修改业务代码。后续实现前需要先用 OpenSpec 校验本 change。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `sms-background-keepalive`: 定义开机广播、前台服务、常驻通知、保活心跳和失败恢复行为。
|
||
- `xiaomi-hyperos-background-setup`: 定义小米/HyperOS 自启动、省电无限制、电池优化、权限设置入口和用户操作清单。
|
||
- `sms-receiver-delivery-diagnostics`: 定义 `onReceive` 不触发时的排查维度，包括权限、安装来源、force-stop、开机广播、厂商后台策略、短信是否入库、广播是否被系统限制。
|
||
|
||
### Modified Capabilities
|
||
|
||
- `sms-code-capture`: 后续实现应把短信广播主路径和收件箱兜底路径接入统一诊断来源，明确区分 `system_sms_broadcast`、`sms_inbox_observer`、`sms_inbox_manual`、`sms_inbox_polling`、`boot_keepalive`。
|
||
- `sms-permission-diagnostics`: 后续实现应补充电池优化、前台服务、开机接收器、HyperOS 设置状态和最近心跳状态。
|
||
- `sms-code-validation-workflow`: 后续验证应增加重启、锁屏、后台、省电策略、force-stop、开机后第一条短信等设备场景。
|
||
|
||
## Impact
|
||
|
||
- 预期后续会修改：
|
||
- `app/src/main/AndroidManifest.xml`
|
||
- `app/src/main/java/com/smsreceive/app/MainActivity.java`
|
||
- 新增 `BootReceiver`、`SmsKeepAliveService`、`KeepAliveNotification`、`BackgroundSetupGuide`、`KeepAliveStateStore` 等 Java 类
|
||
- 可选新增 NDK/C++ heartbeat 实验文件，但默认不作为交付必需项
|
||
- 预期新增权限：
|
||
- `android.permission.RECEIVE_BOOT_COMPLETED`
|
||
- `android.permission.FOREGROUND_SERVICE`
|
||
- 视 targetSdk 和实现情况考虑 `android.permission.POST_NOTIFICATIONS`
|
||
- 视是否直接请求白名单考虑 `android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`
|
||
- 主要 API 和设置入口：
|
||
- `Intent.ACTION_BOOT_COMPLETED`
|
||
- `Intent.ACTION_LOCKED_BOOT_COMPLETED`
|
||
- `Intent.ACTION_MY_PACKAGE_REPLACED`
|
||
- `Context.startForegroundService`
|
||
- `Service.startForeground`
|
||
- `PowerManager.isIgnoringBatteryOptimizations`
|
||
- `Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS`
|
||
- `Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`
|
||
- 小米自启动设置入口优先使用显式组件尝试，失败时回退应用详情页或系统设置页
|
||
- 该方案面向个人自用，不承诺 Play Store 合规；但仍不应隐藏通知、不应滥用后台执行、不应上传短信内容。
|
||
|
||
## Validation
|
||
|
||
- OpenSpec 文档结构完整，包含 `proposal.md`、`design.md`、`tasks.md` 和三个 capability spec。
|
||
- 方案必须能解释以下问题：
|
||
- 为什么 `onReceive` 可能收不到短信。
|
||
- 前台服务能解决什么，不能解决什么。
|
||
- 开机自启动在 Android 15 和 HyperOS 上的真实限制。
|
||
- C++/native 进程为什么只能作为诊断实验，不能作为可靠保活。
|
||
- 代码实现完成后不要求本轮编译，但后续至少需要完成单元测试和真机验证清单。
|
||
- 每次 commit 或 push 前必须检查 diff，避免引入非预期 EOF newline 变化。
|