SMS-Receive/proposal.md at 790afd679e1059bce7cf8f4c34a351da81c6b926

2026-05-18 11:10:52 +08:00

5.3 KiB

Raw Blame History

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 变化。

5.3 KiB Raw Blame History Unescape Escape

Why