251 lines
7.0 KiB
Markdown
251 lines
7.0 KiB
Markdown
# 短信网关 APK 开发文档
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档用于指导开发一个 Android APK（短信网关），通过**自有手机号**实现短信验证码的接收、解析、转发，以及按需发送短信。
|
||
目标是不依赖第三方云短信服务，构建可自部署、可运维、可扩展的短信能力。
|
||
|
||
## 2. 适用场景
|
||
|
||
- 自有系统登录验证码收集与转发
|
||
- 小规模业务短信收发自动化
|
||
- 企业内网或私有化环境下的短信接入
|
||
|
||
> 注意：必须用于合法合规的业务场景，禁止用于批量注册、绕过风控、骚扰营销等违规用途。
|
||
|
||
## 3. 总体架构
|
||
|
||
### 3.1 架构组件
|
||
|
||
1. **Android 短信网关 App**
|
||
- 监听并接收短信
|
||
- 解析验证码或原始短信文本
|
||
- 调用后端 API 上报短信
|
||
- 接收后端任务并发送短信
|
||
|
||
2. **后端服务（自建）**
|
||
- 接收网关回调
|
||
- 下发发送任务
|
||
- 记录日志、重试、告警
|
||
- 提供业务系统查询接口
|
||
|
||
3. **业务系统**
|
||
- 发起发送请求
|
||
- 获取验证码处理结果
|
||
|
||
### 3.2 数据流
|
||
|
||
1. 上游平台向手机号发送验证码短信
|
||
2. Android 网关接收到短信广播
|
||
3. 网关解析短信内容（提取验证码）
|
||
4. 网关将完整短信 + 解析结果上报后端
|
||
5. 业务系统从后端查询验证码并完成流程
|
||
|
||
发送流程（可选）：
|
||
|
||
1. 业务系统调用后端发短信接口
|
||
2. 后端生成发送任务
|
||
3. 网关轮询/长连接获取任务
|
||
4. 网关使用 `SmsManager` 发送短信并回执结果
|
||
|
||
## 4. 技术选型建议
|
||
|
||
- **客户端**：Android 原生 Kotlin（推荐）
|
||
- **网络层**：HttpURLConnection（MVP）
|
||
- **本地存储**：Room 或轻量 SQLite
|
||
- **日志**：本地文件 + 后端集中日志
|
||
- **保活策略**：Foreground Service（前台轮询）
|
||
|
||
> 若主项目使用 uniapp，建议通过原生插件封装短信能力，不建议纯前端层直接处理短信底层功能。
|
||
|
||
## 5. Android 权限与系统能力
|
||
|
||
### 5.3 默认短信应用角色（ROLE_SMS）
|
||
部分 Android 系统/ROM 在后台/静默发送短信时，会要求应用先成为“默认短信应用”（`ROLE_SMS`）。
|
||
如果你发现需要手动确认发送（或发送会被系统拦截），请按以下方式处理：
|
||
|
||
1. 首次启动 App，点击保存配置后等待系统弹出“默认短信应用”角色授权（系统界面可能叫“短信应用/默认短信应用”）
|
||
2. 授权完成后，App 的前台服务会继续轮询并自动发送，无需每次手动确认
|
||
|
||
> 说明：`ROLE_SMS` 授权至少需要一次用户确认，之后应自动生效。
|
||
|
||
## 5.1 必要权限
|
||
|
||
在 `AndroidManifest.xml` 中声明：
|
||
|
||
- `android.permission.RECEIVE_SMS`
|
||
- `android.permission.READ_SMS`（如需读取短信内容库）
|
||
- `android.permission.SEND_SMS`
|
||
- `android.permission.RECEIVE_BOOT_COMPLETED`
|
||
- `android.permission.FOREGROUND_SERVICE`
|
||
|
||
运行时动态申请：
|
||
|
||
- `RECEIVE_SMS`
|
||
- `READ_SMS`
|
||
- `SEND_SMS`
|
||
|
||
## 5.2 广播接收
|
||
|
||
核心广播：
|
||
|
||
- `android.provider.Telephony.SMS_RECEIVED`
|
||
|
||
实现方式：
|
||
|
||
- 注册 `BroadcastReceiver`
|
||
- 从 PDU 解析短信发送方、内容、时间戳
|
||
- 在接收器中快速落库与入队，避免阻塞主线程
|
||
|
||
## 5.3 发送短信
|
||
|
||
使用 `SmsManager`：
|
||
|
||
- 单卡：`SmsManager.getDefault()`
|
||
- 双卡：按 `SubscriptionId` 获取目标 `SmsManager`，避免走错 SIM 卡
|
||
|
||
## 5.4 保活策略
|
||
|
||
- 前台服务常驻（通知栏提示）
|
||
- 开机自启恢复服务
|
||
- 引导用户关闭电池优化限制
|
||
- 失败任务在下次轮询继续重试（可在后续增加失败队列/指数退避）
|
||
|
||
## 6. 模块设计
|
||
|
||
## 6.1 模块划分
|
||
|
||
1. **sms-receiver**：短信接收与解析
|
||
2. **sms-sender**：短信发送与发送回执
|
||
3. **task-sync**：任务拉取、状态上报
|
||
4. **storage**：本地缓存与失败队列
|
||
5. **api-client**：后端 API 通信
|
||
6. **security**：签名、鉴权、加密
|
||
|
||
## 6.2 关键数据结构（建议）
|
||
|
||
### InboundSms（入站短信）
|
||
|
||
- `id`
|
||
- `sender`
|
||
- `content`
|
||
- `receivedAt`
|
||
- `parsedCode`
|
||
- `parseStatus`
|
||
- `rawPduHash`
|
||
|
||
### OutboundTask（出站任务）
|
||
|
||
- `taskId`
|
||
- `phone`
|
||
- `content`
|
||
- `status`（pending/sending/success/failed）
|
||
- `retryCount`
|
||
- `lastError`
|
||
|
||
## 7. 后端接口设计（示例）
|
||
|
||
## 7.1 鉴权建议
|
||
|
||
- 网关端通过请求头携带 `X-Api-Key: SMS_GATEWAY_API_KEY` 进行鉴权
|
||
- 使用 HTTPS，拒绝明文传输
|
||
|
||
## 7.2 API 列表
|
||
|
||
1. `POST /api/v1/sms/inbound`
|
||
- 作用：上报入站短信
|
||
- 请求体：发送方、短信内容、时间、解析结果
|
||
- 返回：`ackId`
|
||
|
||
2. `GET /api/v1/device/tasks?limit=5`
|
||
- 作用：拉取发送任务
|
||
- 返回：任务列表
|
||
|
||
3. `POST /api/v1/sms/outbound/result`
|
||
- 作用：回传发送结果
|
||
- 请求体：`taskId`、状态、失败原因、运营商回执（如有）
|
||
|
||
## 8. 验证码解析策略
|
||
|
||
## 8.1 正则提取建议
|
||
|
||
建议预置多个规则，按顺序匹配：
|
||
|
||
- `\\b\\d{4}\\b`
|
||
- `\\b\\d{6}\\b`
|
||
- `验证码[:：\\s]*([0-9]{4,8})`
|
||
|
||
## 8.2 容错策略
|
||
|
||
- 同一发送方短时间多条短信，按时间窗口聚合
|
||
- 对重复短信做哈希去重
|
||
- 解析失败也要上报原文，便于后端二次识别
|
||
|
||
## 9. 异常与重试机制
|
||
|
||
- 网络失败：指数退避重试（如 2s/5s/10s/30s）
|
||
- 接口 5xx：自动重试
|
||
- 接口 4xx：记录并告警，不无限重试
|
||
- 本地持久化失败队列，避免进程被杀导致数据丢失
|
||
|
||
## 10. 安全与合规要求
|
||
|
||
- 严格控制设备与接口访问白名单
|
||
- 本地敏感数据最小化存储，必要时加密
|
||
- 日志脱敏（手机号中间位、验证码字段）
|
||
- 定期轮换设备密钥
|
||
- 仅用于已授权业务，不得违反运营商与法律规定
|
||
|
||
## 11. 测试计划
|
||
|
||
## 11.1 功能测试
|
||
|
||
- 接收短信：不同发送方、长短信、分片短信
|
||
- 发送短信：单卡/双卡、不同运营商号段
|
||
- 解析测试：4位/6位/8位验证码、多语言模板
|
||
- 任务链路：拉取、执行、回执、重试
|
||
|
||
## 11.2 稳定性测试
|
||
|
||
- 24小时持续运行
|
||
- 断网恢复
|
||
- 杀进程后自恢复
|
||
- 低电量模式、系统省电模式下行为
|
||
|
||
## 11.3 压力测试
|
||
|
||
- 高频短信接收场景
|
||
- 并发任务发送场景
|
||
- 后端不可用情况下队列堆积与恢复
|
||
|
||
## 12. 发布与运维建议
|
||
|
||
- 渠道：企业内部分发、MDM、私有下载页
|
||
- 不建议直接面向公开应用市场发布
|
||
- 建立设备监控面板：在线率、延迟、失败率
|
||
- 预留远程配置开关：正则规则、重试参数、限流阈值
|
||
|
||
## 13. 里程碑计划（建议）
|
||
|
||
1. **M1（1周）**：完成收短信 + 上报 API
|
||
2. **M2（1周）**：完成发短信任务闭环
|
||
3. **M3（1周）**：完成保活、重试、日志
|
||
4. **M4（1周）**：完成灰度部署与稳定性压测
|
||
|
||
## 14. 最小可用版本（MVP）范围
|
||
|
||
- 接收短信并解析验证码
|
||
- 上报后端并可查询
|
||
- 支持基础发送任务
|
||
- 支持失败重试与本地缓存
|
||
- 提供基础运行状态页（在线、最近短信、错误信息）
|
||
|
||
---
|
||
|
||
如需继续推进，可在下一步补充：
|
||
|
||
1. Android 端包结构与类图
|
||
2. 完整 `AndroidManifest.xml` 示例
|
||
3. Kotlin 核心代码模板（Receiver/Service/SmsManager/API）
|
||
4. 后端接口 OpenAPI 文档草案
|