# 短信网关 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.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 文档草案