54 lines
3.8 KiB
Markdown
54 lines
3.8 KiB
Markdown
## Why
|
||
|
||
你想做的不是完整短信客户端，而是一个只服务自己手机的验证码接收工具：在小米 12S、澎湃 OS 3、Android 15 上尽可能可靠地读取新收到短信里的验证码，并把关键结果快速展示出来。
|
||
|
||
这类需求的关键不在 UI，而在 Android 15 与厂商系统对短信权限、广播分发、后台限制和验证码短信格式的真实行为。因此必须先把可用 API、兜底路径和真机验证方案写清楚，再进入编码。
|
||
|
||
## What Changes
|
||
|
||
- 新建一个 Android App 规格方案，目标能力限定为“接收短信验证码、解析验证码、展示最近结果、输出诊断状态”。
|
||
- 明确三条可用 SMS 获取路径，并按优先级落地：
|
||
- `Telephony.Sms.Intents.SMS_RECEIVED_ACTION` + `RECEIVE_SMS`：主路径，适合个人自用、非 Play 上架场景，直接读取收到短信内容。
|
||
- `SMS User Consent API`：备选路径，不要求短信带 app hash，但需要用户对单条短信授权，适合验证系统广播被限制时的可行性。
|
||
- `SMS Retriever API`：受控格式路径，不需要短信权限，但要求验证码短信包含当前 app 的 hash，更适合服务端可控验证码，不适合作为读取任意平台验证码的主路径。
|
||
- 明确不把 Android Studio、Gradle、JDK 环境初始化纳入本次工作，后续实现时参考已有 `Weather` 项目的构建环境。
|
||
- 设计验证码解析策略，支持常见 4-8 位数字码、中文验证码文案、带空格/短横线的验证码，以及短信多段 PDU 合并后的正文。
|
||
- 设计真机验证路径，重点验证 Android 15 + HyperOS 3 上：
|
||
- 运行时申请 `RECEIVE_SMS` 是否成功。
|
||
- 应用在前台/后台时 `SMS_RECEIVED_ACTION` 是否触发。
|
||
- 短信正文是否能被解析为完整 message body。
|
||
- 常见短信验证码是否能稳定提取。
|
||
- 建立诊断能力，暴露权限状态、API 路径状态、最近一次广播时间、最近一次解析结果和失败原因。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `sms-code-capture`: 定义应用通过系统短信广播、Google SMS 验证 API 备选路径接收短信正文并抽取验证码的行为要求。
|
||
- `sms-permission-diagnostics`: 定义应用对短信权限、接收状态、API 可用性和解析失败原因的诊断展示要求。
|
||
- `sms-code-validation-workflow`: 定义在小米 12S、澎湃 OS 3、Android 15 真机上的验证流程和测试通过标准。
|
||
|
||
### Modified Capabilities
|
||
|
||
- 无。当前 `SmsReceive` 目录没有既有 OpenSpec 能力规格。
|
||
|
||
## Impact
|
||
|
||
- 预期后续会创建一个最小 Android 工程或复用 Weather 工程环境生成同类 Android 工程配置。
|
||
- 预期会影响 Android Manifest、运行时权限申请、BroadcastReceiver、短信 PDU 解析、验证码正则解析、前台诊断 UI 和测试用例。
|
||
- 需要引入或使用的主要 Android/Google API：
|
||
- `android.provider.Telephony.Sms.Intents.SMS_RECEIVED_ACTION`
|
||
- `android.permission.RECEIVE_SMS`
|
||
- `Telephony.Sms.Intents.getMessagesFromIntent(Intent)`
|
||
- `com.google.android.gms.auth.api.phone.SmsRetriever`
|
||
- `SMS User Consent API`
|
||
- 不以 Play Store 上架合规为目标，因此可以使用短信权限；但实现仍必须本地化处理短信内容，不上传、不持久化完整短信正文，减少隐私风险。
|
||
|
||
## Validation
|
||
|
||
- OpenSpec 文档结构完整，至少包含 `proposal.md`、`design.md`、`tasks.md` 和三个 capability spec。
|
||
- API 方案必须明确主路径、备选路径、适用条件和限制，不写成泛泛而谈的短信读取方案。
|
||
- 设计必须说明 Android 15、HyperOS 3、个人自用 sideload/debug 场景下的权限与后台行为风险。
|
||
- 后续实现前必须能从任务列表直接进入编码，不再需要重新讨论核心架构。
|
||
- 后续实现完成后，必须在目标真机上完成至少一轮短信接收、解析和诊断验证。
|