# SmsReceiver Worker（前后端分离版）

> 将 SmsReceiver-go 迁移到 Cloudflare Worker + Pages + D1 的 **Worker 化**实现。
> 目标是把「短信接收 API + 管理界面」拆分为独立的 API 服务与静态前端，提升部署弹性、跨域能力与运维简洁度。

## 开发目的

1. **Worker 化**：摆脱传统服务器进程部署，使用 Cloudflare Worker 作为 API 运行环境。
2. **前后端分离**：前端使用 Pages 静态托管，API 单独在 Worker 上运行，天然解耦。
3. **低运维成本**：无需自建数据库与运行时，D1 提供托管 SQLite 体验。
4. **部署可重复**：通过 wrangler + 配置文件完成快速部署与迁移。
5. **兼容原协议**：保留原 SmsReceiver-go 的字段、签名逻辑与接入方式。

## 架构概览

```
[TranspondSms / 客户端]
            |
            |  HTTP POST (token/sign)
            v
   Cloudflare Worker (Hono)
            |
            |  D1 (SQLite)
            v
      数据持久化 + 管理 API

   Cloudflare Pages (静态 UI)
            |
            |  API_BASE 指向 Worker
            v
         管理后台
```

## 项目结构

```
.
├── worker/                 # Cloudflare Worker API (Hono + D1)
│   ├── src/                # API 代码
│   ├── schema.sql          # D1 表结构
│   ├── migrate_sqlite_to_d1.py  # 旧 sqlite 数据迁移脚本
│   ├── wrangler.toml       # Worker 配置
│   └── package.json
└── pages/public/           # Cloudflare Pages 静态管理 UI
    ├── index.html
    ├── app.js
    └── app.css
```

---

# 关键设计说明（详细解读）

## 1. 前后端分离特性

- **API** 与 **UI** 完全解耦。
- UI 仅为静态资源（HTML/JS/CSS），部署到 Pages；
- API 只处理数据与鉴权，部署到 Worker；
- UI 通过 `API_BASE` 指向后端，无需在同域运行。

**优势**：
- UI 部署独立、回滚简单。
- API 可单独扩容/升级。
- 适配多域名、CDN 就近访问。

## 2. 数据层：D1 (SQLite)

- 使用 Cloudflare D1 替代本地 SQLite。
- 表结构与原 Go 版本保持一致：`sms_messages`、`receive_logs`。
- 使用 SQL 语句创建表，便于版本迁移与重建。

## 3. 兼容原接收协议

API 保持字段一致：

- `from` / `content` / `timestamp` / `sign` / `device` / `sim` / `token`

签名逻辑保持与 Go 版一致：

```
stringToSign = `${timestamp}\n${secret}`
sign = HMAC-SHA256(stringToSign) -> Base64 -> URL encode
```

## 4. 认证与登录

- 使用 `ADMIN_USER` + `ADMIN_PASS_HASH` 登录。
- 登录密码使用 HMAC-SHA256 生成 hash（与 SESSION_SECRET 绑定）。
- Cookie 采用 `SameSite=None; Secure`，解决跨域登录。

## 5. 查询能力

- 支持 `from`、时间区间筛选（start_ts / end_ts）。
- UI 默认显示当前月，并提供“本月 / 上月 / 全部”。
- 移动端适配：表格横向滚动，筛选区可滚动。

---

# 部署指南

## 1) 部署 Worker API

```bash
cd worker
npm install
```

编辑 `wrangler.toml`：
- `database_id`
- vars: `ADMIN_USER` / `ADMIN_PASS_HASH` / `SESSION_SECRET` / `HMAC_SECRET`

初始化 D1 表结构：
```bash
npx wrangler d1 execute smsreceiver --file=schema.sql
```

本地调试：
```bash
npx wrangler dev
```

发布：
```bash
npx wrangler deploy
```

---

## 2) 部署 Pages UI

将 `pages/public/` 作为静态站点部署到 Cloudflare Pages。

修改 `pages/public/app.js`：
```js
const API_BASE = "https://你的-worker域名"
```

部署完成后即可访问管理后台。

---

## 3) 密码 hash 生成

当前登录逻辑：`HMAC_SHA256(password, SESSION_SECRET)`

生成方式：
```bash
node -e "const c=require('crypto');console.log(c.createHmac('sha256','YOUR_SESSION_SECRET').update('YOUR_PASSWORD').digest('hex'))"
```

将结果写入 `ADMIN_PASS_HASH`。

---

## 4) 从旧 SQLite 迁移到 D1

脚本：`worker/migrate_sqlite_to_d1.py`

需要环境变量：
- `CF_ACCOUNT_ID`
- `CF_API_TOKEN`
- `D1_DATABASE_ID`
- `SQLITE_PATH`（默认 `sms_receiver_go.db`）

运行：
```bash
cd worker
python3 migrate_sqlite_to_d1.py
```

---

# 使用指南

## 1. 客户端上报短信

`POST /api/receive`

字段：
- `from`：发件人
- `content`：短信正文
- `timestamp`：Unix 时间戳
- `token`：API Token
- `sign`：签名
- `device` / `sim`：设备与卡槽信息（可选）

## 2. 登录管理后台

- 访问 Pages URL
- 输入 `ADMIN_USER` / 密码
- 可查看短信列表、详情、日志、筛选记录

## 3. 管理 API 端点示例

- `POST /api/auth/login`
- `POST /api/auth/logout`
- `GET /api/auth/me`
- `GET /api/messages`
- `GET /api/messages/:id`
- `GET /api/logs`
- `GET /api/stats`
- `GET /api/health`

---

# 本地开发流程（推荐）

1. 在 `worker/` 中使用 `wrangler dev` 启动本地 API。
2. 在 `pages/public/` 中修改前端并直接用静态服务器预览。
3. API_BASE 指向本地 API 或临时 Worker 域名。
4. 测试完成后分别部署 Worker 与 Pages。

---

# 注意事项

- UI 与 API 部署后跨域必须使用 `SameSite=None; Secure` Cookie。
- D1 为 SQLite 兼容，但限制与云端事务特性不同于本地。
- API Token 与 HMAC 密钥要妥善保管。

---

# License

内部项目使用，按需扩展。