yunzesms/docs/端到端开发与部署.md

短信网关端到端开发与部署（MVP）

本页说明如何先把“安卓短信网关端 + 后端服务端”跑通，然后你后续的业务系统接入即可。

1. 启动后端

1. 进入 backend 目录
2. 复制并配置环境变量

cd backend
copy .env.example .env
notepad .env

确保设置：

• SMS_GATEWAY_API_KEY

• 安装依赖并启动

npm i
npm start

默认监听：http://localhost:7788

2. 构建安卓端

android-gateway/README.md 说明了导入方式：需要在 Android Studio 新建项目后，把本仓库里的源码/配置拷贝进去。

首次打开 App 后填写并保存：

• backendUrl：你的后端地址
• apiKey：与后端 .env 的 SMS_GATEWAY_API_KEY 一致
• （不再需要 deviceId，由 apiKey 在后端自动归属）

保存后 App 会启动前台服务，轮询后端下发任务，并注册短信接收广播。

3. 联调流程（最小闭环）

1. 业务系统（或你用接口测试工具）向后端入队发送任务：
   • POST /api/v1/business/outbound-tasks
2. 安卓端轮询到任务后通过 SmsManager 发送短信
3. 安卓端把入站验证码短信通过 POST /api/v1/sms/inbound 上报后端
4. 你业务系统再从后端读取/查询验证码结果（你可在现有业务端对接这些接口）

4. 业务系统接入（对接示例：TP 管理后台）

如果你的业务系统是 ThinkPHP（例如你现在的 TP 后台管理页），建议不要直接写本仓库的数据库表，而是调用本短信网关后端提供的入队接口：

1. 确保安卓端填写的 backendUrl 指向本短信网关后端（例如 https://yzsms.yunzer.cn）

2. 确保安卓端填写的 apiKey 与后端 .env 里的 SMS_GATEWAY_API_KEY 完全一致

3. 业务系统发送短信时，调用：

   • POST {backendUrl}/api/v1/business/outbound-tasks
   • 请求头：X-Api-Key: SMS_GATEWAY_API_KEY
   • body：{ "phone": "+8613712345678", "content": "短信测试验证码：123456" }

4. 安卓端会通过轮询：

   • GET {backendUrl}/api/v1/device/tasks 自动拉取任务并发送，然后回传到：
   • POST {backendUrl}/api/v1/sms/outbound/result

5. 查询发送任务状态（可选，用于业务侧展示）

   • GET {backendUrl}/api/v1/business/outbound-tasks?limit=50
   • 请求头：X-Api-Key: SMS_GATEWAY_API_KEY

5. 后续扩展建议

• 增加任务重试与失败原因字段
• 增加短信去重与解析规则配置（正则规则下发）