83 lines
2.3 KiB
Markdown
83 lines
2.3 KiB
Markdown
# 短信网关后端（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`
|
||
|
||
## 启动
|
||
|
||
```bash
|
||
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: [...] }`
|
||
|
||
6. 业务系统查询出站发送任务状态（新增）
|
||
- `GET /api/v1/business/outbound-tasks?limit=50&status=&phone=`
|
||
- 请求头：`X-Api-Key: <SMS_GATEWAY_API_KEY>`
|
||
- status 取值：
|
||
- `pending` / `sending` / `failed` / `success`
|
||
- 返回：`{ tasks: [{ taskId, phone, content, status, ...}] }`
|
||
|
||
## 数据表
|
||
|
||
- `inbound_sms`
|
||
- `outbound_tasks`
|
||
- `device_heartbeats`
|