# WmailHub 开发设计总览

## 1. 项目定位

WmailHub 是一个基于 Cloudflare Email Workers 的轻量邮件接收与转发平台。

核心原则：

- Cloudflare 负责邮件基础设施。
- Console 是控制平面，包含前端与管理 Node。
- Node 是邮件数据转发平面，无前端、无业务判断。
- Console 通过 Cloudflare OAuth 自动完成 Node、Domain、Mailbox、Email Worker 的配置。
- Node 只能处理被授权 Cloudflare Account 下的域名邮箱。
- Node 与 Console 的通信必须使用 HTTPS + 应用层签名。
- 邮件默认短期保存，例如 1 天，过期自动删除。
- 邮件进入 Console 后才能进入 Webhook、API、MCP 等业务能力。

## 2. 总体架构

```text
Internet
  |
  v
Cloudflare Email Routing
  |
  v
Cloudflare Email Worker
  |
  v
Node
  | HTTPS + Request Signature
  v
Console Management Node
  |
  +--> Database
  +--> Webhook
  +--> API
  +--> MCP
  +--> Frontend
```

## 3. Console

Console = Frontend + Management Node。

负责：Cloudflare OAuth、Cloudflare Account、Node、Domain、Mailbox、Email、Webhook、API、MCP、Node 安装与配置、数据存储、TTL 清理调度。

用户不执行 Node 安装命令。点击 Add Node 后进入 Cloudflare OAuth，授权后由 Cloudflare API 自动完成安装和配置。

## 4. Node

Node 是纯后端组件，只做：接收 Cloudflare Email Worker 的邮件、将邮件安全转发到 Console。

Node 不做 Domain 判断、Mailbox 判断、邮件业务路由、Webhook、MCP、API、用户权限、邮件长期存储。

Node 收到什么就转发什么。

## 5. 权限边界

一个 Node 与一个 Cloudflare Account 建立绑定。Node A 只能处理 Account A 下配置的 Email Worker，不允许处理其他 Account。

Domain 与 Mailbox 的具体业务信息由 Console 管理，Node 不需要理解这些业务字段。

## 6. 核心邮件流程

```text
Email
  |
  v
Cloudflare Email Routing
  |
  v
Email Worker
  |
  v
Node
  |
  v
Console
  |
  +--> Store
  +--> Webhook
  +--> API
  +--> MCP
```

## 7. 生命周期

默认邮件 TTL 为 1 天。数据库记录 expires_at，Cron 定期删除过期记录及对应 R2 对象。

## 8. 第一版明确不做

- 自建 SMTP Server
- IMAP / POP3
- 发件服务器
- 完整邮箱客户端
- 复杂邮件规则引擎
- AI 邮件分析
- 多租户复杂组织系统
- Node 端业务路由