yunzesms/backend/README.md

短信网关后端（backend）

目标

为安卓短信网关端提供：

• 接收短信上报（/api/v1/sms/inbound）
• 为指定设备下发发送任务（/api/v1/device/tasks）
• 接收发送结果回传（/api/v1/sms/outbound/result）
• 业务系统入队发送任务（/api/v1/business/outbound-tasks）

使用 SQLite（单文件数据库）便于自部署。

环境准备

1. 安装 Node.js 18+
2. 进入 backend 目录
3. 复制 .env.example 为 .env 并修改 SMS_GATEWAY_API_KEY

启动

cd backend
npm i
npm start

默认监听由环境变量 PORT 决定（示例：http://localhost:7788）

鉴权

所有接口都要求请求头：X-Api-Key: <SMS_GATEWAY_API_KEY>

API 说明

1. 入站上报

   • POST /api/v1/sms/inbound
   • body 示例：
     • sender：字符串（短号码/发送方）
     • content：短信文本
     • receivedAt：毫秒时间戳（可选；不传则由服务端补齐）
     • parsedCode：解析后的验证码（可空）
     • parseStatus：字符串（如 matched/unmatched/error）
     • rawPduHash：字符串（用于去重，可选）

2. 设备拉取任务

   • GET /api/v1/device/tasks?limit=5
   • 返回：{ tasks: [...] }

3. 设备回传任务结果

   • POST /api/v1/sms/outbound/result
   • body 示例：
     • taskId
     • status：success/failed
     • error：失败原因（可选）

4. 业务系统入队发送任务

   • POST /api/v1/business/outbound-tasks
   • body 示例：
     • phone
     • content
   • 返回：{ taskId }

5. 业务系统读取入站验证码（可选但建议）

   • GET /api/v1/business/inbound-sms?since=0&limit=20&onlyMatched=false
   • 说明：
     • since：毫秒时间戳，返回该时间之后的短信
     • onlyMatched=true：只返回 parseStatus=matched 的验证码
   • 返回：{ inbounds: [...] }

数据表

• inbound_sms
• outbound_tasks
• device_heartbeats