# WmailHub 开发设计总览(v2,docs/11)

## 1. 项目定位

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

核心原则:

- 不自建 SMTP、IMAP、POP3。
- 不部署邮件转发 Node(v1 的 Node 已从邮件链路移除)。
- Email Worker 是邮件入口 + SMTP reject 执行者。
- Console 是唯一业务控制中心,也是"是否允许接收邮件"的唯一事实来源。
- Worker 不保存邮箱业务数据;邮箱、域名、启用状态全部由 Console 管理。
- Console 明确允许时,Worker 接收邮件;明确拒绝时执行 `message.setReject()`;
  Console 超时或 5xx 不能被解释成邮箱不存在。
- 邮件默认短期保存,例如 1 天,过期自动删除。
- 邮件进入 Console 后才能进入 Webhook、API、MCP 等业务能力。

## 2. 总体架构

```text
Internet
  |
  v
Cloudflare Email Routing
  |
  v
Cloudflare Email Worker
  | HTTPS + HMAC(authorize / ingest)
  v
Console
  |
  +--> D1
  +--> R2
  +--> Webhook
  +--> API
  +--> MCP
  +--> Frontend
```

## 3. Console

Console = Frontend + Management API。

负责:Cloudflare OAuth、Cloudflare Account、Domain、Mailbox、邮箱启用/禁用、Email Storage、
Webhook、REST API、MCP、TTL Cleanup、Cloudflare Email Routing 配置、Email Worker 部署、
Worker Credential。

用户不执行安装命令。点击「添加账号」进入 Cloudflare OAuth(Connect Cloudflare Account),
授权后由 Cloudflare API 自动完成域名同步、Worker 部署与凭据配置。

## 4. Email Worker

Worker 只做:接收 Cloudflare Email Routing 邮件 -> authorize(询问 Console)-> 
reject 时 `message.setReject()` -> accept 时把 raw MIME 提交 ingest。

不做邮箱/域名管理、用户权限、Webhook、API、MCP、D1/R2 业务查询、TTL、邮箱业务规则。

## 5. 权限边界

一个账号绑定一个 Cloudflare Account 与一个 Email Worker;Worker credential 只能处理
所属账号下的域名邮箱(docs/04 归属校验)。

## 6. 核心邮件流程(两阶段)

```text
Email
  |
  v
Cloudflare Email Routing(catch-all)
  |
  v
Email Worker
  |
  v
Console /internal/email/authorize
  +-- accept  -> /internal/email/ingest -> D1 + R2 + Webhook
  +-- reject  -> message.setReject()
  +-- temporary_error -> 交由 Cloudflare 邮件机制重试
```

## 7. 生命周期

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

## 8. 第一版明确不做

- 自建 SMTP Server
- IMAP / POP3
- 发件服务器 / NDR(反站)
- 完整邮箱客户端
- 复杂邮件规则引擎
- AI 邮件分析
- 多租户复杂组织系统
- KV/DO 邮箱缓存与同步(性能需要时再评估,须接受传播延迟)