# 短信网关后端（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
```

默认监听：`http://localhost:3000`

## 鉴权

所有接口都要求请求头：`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`