这份文档旨在指导你从零开始构建 **comments-worker** —— 一个基于 Cloudflare 生态、高性能、零成本且支持审核功能的静态博客评论系统。

---

# 📚 comments-worker 开发文档

## 1. 项目概述
**comments-worker** 是专为静态博客设计的评论系统后端。
- **核心特性**：支持 OTP 邮件验证码与 OAuth（GitHub）登录、评论回复嵌套、管理员邮件审核提醒、完全基于 Cloudflare 边缘网络。
- **技术栈**：Cloudflare Workers, D1 Database, Hono 框架, Cloudflare Email Routing.

---

## 2. 数据库设计 (D1)

在 Cloudflare 控制台或通过 `wrangler` 执行以下 SQL 初始化 D1 数据库：

```sql
-- 用户表：存储身份信息
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    display_name TEXT NOT NULL,
    avatar_url TEXT,
    auth_provider TEXT NOT NULL, -- 'otp' 或 'github'
    is_admin INTEGER DEFAULT 0,  -- 1 为管理员
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 评论表：支持层级回复
CREATE TABLE comments (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    post_slug TEXT NOT NULL,          -- 文章唯一标识
    user_id INTEGER NOT NULL,         -- 关联用户
    parent_id INTEGER DEFAULT NULL,   -- 父评论ID
    content TEXT NOT NULL,
    status TEXT DEFAULT 'pending',    -- 'pending', 'approved', 'spam'
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (parent_id) REFERENCES comments(id)
);

-- 验证码表：用于 OTP 登录
CREATE TABLE auth_codes (
    email TEXT PRIMARY KEY,
    code TEXT NOT NULL,
    expires_at INTEGER NOT NULL
);
```

---

## 3. 环境配置

### 3.1 `wrangler.toml` 配置
```toml
name = "comments-worker"
main = "src/index.ts"
compatibility_date = "2023-12-01"

# D1 数据库绑定
[[d1_databases]]
binding = "DB"
database_name = "your-d1-db-name"
database_id = "your-d1-db-id"

# 邮件发送绑定
send_email = [
    { name = "EMAIL" }
]

[vars]
DOMAIN = "yourdomain.com"
ADMIN_EMAIL = "[email protected]"
FRONTEND_URL = "https://blog.yourdomain.com"
JWT_SECRET = "your-super-secret-key"
GITHUB_CLIENT_ID = "your-github-id"
```

---

## 4. 核心功能实现

### 4.1 身份验证模块 (Auth)
系统支持两种验证方式，最终均下发 JWT Token。

- **OTP 流程**：
    1. `POST /auth/otp/send`: 生成 6 位验证码，通过 `env.EMAIL.send()` 发送至用户邮箱。
    2. `POST /auth/otp/verify`: 校验验证码，若正确则在 `users` 表创建/更新记录，并生成 JWT。
- **OAuth 流程**：
    1. `GET /auth/github/login`: 重定向至 GitHub 授权页。
    2. `GET /auth/github/callback`: 接收 `code`，换取用户信息，存入 D1 并下发 JWT。

### 4.2 评论模块 (Comments)
- **GET `/comments/:slug`**: 
    - 逻辑：查询 `status = 'approved'` 的评论。
    - 返回：建议返回扁平数组，由前端根据 `parent_id` 构建树状 UI。
- **POST `/comments`**: 
    - 逻辑：需携带 JWT Header。插入评论时 `status` 默认为 `pending`。
    - 自动化：插入成功后，调用 `env.EMAIL.send()` 向 `ADMIN_EMAIL` 发送提醒。

### 4.3 管理模块 (Admin)
- **PATCH `/admin/approve/:id`**: 
    - 权限：校验 JWT 负载中的 `email` 是否等于 `ADMIN_EMAIL` 或 `is_admin` 字段。
    - 逻辑：更新评论状态为 `approved`。

---

## 5. 邮件发送逻辑 (Email Worker)

使用 `mimetext` 库简化原始邮件构造：

```typescript
import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from "mimetext/browser";

async function sendMail(env, to, subject, body) {
  const msg = createMimeMessage();
  msg.setSender({ name: "评论系统", addr: `noreply@${env.DOMAIN}` });
  msg.setRecipient(to);
  msg.setSubject(subject);
  msg.addMessage({ contentType: 'text/html', data: body });

  const email = new EmailMessage(
    `noreply@${env.DOMAIN}`,
    to,
    msg.asRaw()
  );
  await env.EMAIL.send(email);
}
```

---

## 6. 前端集成建议

由于是静态博客，你可以编写一个轻量级的 JS SDK：

1.  **状态持久化**：将 JWT 存储在 `localStorage` 中。
2.  **UI 组件**：
    - 登录框（输入邮箱 -> 获取 OTP -> 输入 OTP）。
    - 评论列表（递归渲染回复）。
    - 评论框（支持 Markdown 预览）。
3.  **审核快捷链接**：在发给管理员的邮件中，可以直接附带一个带有 Token 的审核链接，实现“一键审核”。

---

## 7. 开发与部署步骤

### 第一步：初始化项目
```bash
npm create cloudflare@latest comments-worker -- --framework=hono
cd comments-worker
npm install mimetext
```

### 第二步：创建 D1 数据库
```bash
npx wrangler d1 create comments-db
# 根据输出的 ID 修改 wrangler.toml
npx wrangler d1 execute comments-db --file=./schema.sql
```

### 第三步：配置 GitHub OAuth
1. 在 GitHub Settings -> Developer Settings 创建新 OAuth App。
2. 设置 Callback URL 为 `https://comments-worker.yourname.workers.dev/auth/github/callback`。

### 第四步：部署
```bash
npx wrangler deploy
```

---

## 8. 安全建议
1.  **CORS 策略**：在 Hono 中使用 `cors()` 中间件，限制 `origin` 为你的博客域名。
2.  **速率限制**：针对 OTP 发送接口，利用 Cloudflare Worker 的 `Rate Limiting` 或在 D1 中记录请求频率，防止邮件被刷。
3.  **输入过滤**：在存储评论前进行简单的 HTML 转义，防止 XSS 攻击。

---

**项目维护提示**：
- 监控 D1 的读写额度（免费额度非常慷慨，通常每日 500w 次读，10w 次写）。
- 定期检查 `auth_codes` 表，可以写一个定时任务（Cron Trigger）清理过期验证码。