# PRD · MailGo 邮件系统

- **项目名称**：mail_go
- **编程语言**：Go
- **核心依赖**：go-smtp / go-imap / go-pop3（emersion 系列）+ Gin + html/template
- **文档版本**：v0.1  
- **作者**：许清楚（PM）

---

## 一、原始需求

用 Go 语言开发一套完整的自托管邮件系统，包含 SMTP/IMAP/POP3 服务端、Web 管理后台（/admin）和用户邮箱界面（/），配置遵循 FHS 标准，支持 SQLite/MySQL 双数据库，支持 Linux 生产环境与 Windows 本地测试。

---

## 二、产品目标

1. **可自托管的完整邮件服务**：提供生产可用的 SMTP/IMAP/POP3 服务端，开箱即用，无需依赖第三方邮件服务商。
2. **低门槛运维管理**：通过 Web 管理后台完成域名配置、用户管理、DNS 指引，运维人员无需手动编辑配置文件。
3. **标准化配置与数据存储**：严格遵循 FHS 目录规范，配置自动补全，支持 Linux/Windows 双环境，降低部署与迁移成本。

---

## 三、用户故事

| # | 角色 | 需求 | 价值 |
|---|------|------|------|
| US-1 | 系统管理员 | 通过 /admin 配置域名、端口和 TLS 证书 | 无需 SSH 手动改配置即可上线邮件服务 |
| US-2 | 系统管理员 | 创建/删除/修改域名下的邮件用户并设置附件配额 | 集中管理账户，控制存储资源占用 |
| US-3 | 普通用户 | 登录后在浏览器中收发邮件并上传附件 | 随时随地通过 Web 界面使用邮箱 |
| US-4 | 普通用户 | 用标准邮件客户端（IMAP/POP3/SMTP）连接账户 | 继续使用 Outlook、Thunderbird 等熟悉工具 |
| US-5 | 系统管理员 | 启动时配置文件缺失项自动补全，并在 /admin 查看 DNS 配置提示 | 减少初始化错误，快速完成 DNS 配置 |

---

## 四、功能需求池

### P0 · 必须实现

| ID | 功能 | 说明 |
|----|------|------|
| P0-01 | SMTP 服务端 | 基于 go-smtp，支持收信/转发，TLS 可配置 |
| P0-02 | IMAP 服务端 | 基于 go-imap，支持标准 IMAP4 操作（文件夹、标记、搜索） |
| P0-03 | POP3 服务端 | 基于 go-pop3，支持标准 POP3 收信 |
| P0-04 | 配置文件自动补全 | 启动时检查 `/etc/mail_go/`（Windows：`./win/etc/mail_go/`），缺失项写入默认值 |
| P0-05 | 数据库支持 | 默认 SQLite，可切换 MySQL；数据目录 `/srv/mail_go`（Windows：`./win/srv/mail_go`） |
| P0-06 | 邮件持久化 | 收/发邮件元数据及正文存入数据库 |
| P0-07 | 附件存储 | 附件保存至 `/srv/mail_go/attachments`（Windows：`./win/srv/mail_go/attachments`） |
| P0-08 | 默认 admin 账户 | 首次启动自动生成 admin 管理员账户 |
| P0-09 | 用户登录认证 | Web 界面登录，Session 管理，未登录重定向 |
| P0-10 | 收件箱页面 | 邮件列表 + 邮件阅读（HTML/纯文本） |
| P0-11 | 撰写/发送邮件 | 支持附件上传，调用本地 SMTP 发送 |
| P0-12 | Web 框架 | Gin + html/template，/admin 仅管理员可访问 |

### P1 · 应当实现

| ID | 功能 | 说明 |
|----|------|------|
| P1-01 | 发件箱页面 | 展示已发送邮件列表 |
| P1-02 | 域名管理（/admin） | 配置域名、SMTP/IMAP 端口、TLS 证书路径 |
| P1-03 | 用户管理（/admin） | 创建/删除/修改用户，设置附件空间配额（默认 5 GB） |
| P1-04 | DNS 配置提示（/admin） | 展示 MX、SPF、DKIM、DMARC 记录的填写示例 |
| P1-05 | Web 监听配置 | 支持 TCP 端口和 Unix Socket（Windows 仅 TCP） |
| P1-06 | DKIM 签名 | 发信时自动附加 DKIM 签名 |

### P2 · 有则更好

| ID | 功能 | 说明 |
|----|------|------|
| P2-01 | 邮件搜索 | Web 界面关键词搜索收件箱 |
| P2-02 | 垃圾邮件过滤 | 基础规则过滤或集成第三方库 |
| P2-03 | 多域名支持 | 单实例托管多个邮件域名 |
| P2-04 | 邮件分组/标签 | 用户自定义文件夹或标签 |
| P2-05 | 操作审计日志 | /admin 记录管理操作日志 |

---

## 五、关键 UI 页面描述

### 5.1 登录页（`/login`）
- 居中卡片：邮箱地址 + 密码输入框 + 登录按钮
- 登录失败提示错误信息

### 5.2 收件箱（`/inbox`）
- 左侧导航：收件箱 / 发件箱 / 撰写 / 退出
- 右侧主区：邮件列表（发件人、主题、时间、未读标记）
- 点击邮件展开正文，底部显示附件下载链接

### 5.3 撰写邮件（`/compose`）
- 表单：收件人、抄送（可选）、主题、正文（textarea）
- 附件上传按钮（支持多文件）
- 发送 / 存草稿 按钮

### 5.4 发件箱（`/sent`）
- 与收件箱布局一致，展示已发送邮件列表

### 5.5 管理后台 - 域名配置（`/admin/domains`）
- 表格列：域名、SMTP 端口、IMAP 端口、TLS 状态、操作
- 新增/编辑弹层：域名、端口、证书路径输入框
- DNS 提示区：自动生成 MX / SPF / DKIM / DMARC 记录文本，可一键复制

### 5.6 管理后台 - 用户管理（`/admin/users`）
- 表格列：用户名、域名、配额、已用空间、状态、操作
- 新增/编辑弹层：用户名、密码、所属域名、附件配额（GB）

---

## 六、配置文件结构（参考）

```toml
# /etc/mail_go/config.toml

[database]
driver = "sqlite"          # sqlite | mysql
dsn    = "/srv/mail_go/mail.db"

[storage]
base_dir      = "/srv/mail_go"
attachments   = "/srv/mail_go/attachments"

[web]
listen = ":8080"           # TCP 端口或 Unix socket 路径（仅 Linux）

[smtp]
port    = 25
tls_port = 465
cert    = ""
key     = ""

[imap]
port     = 143
tls_port = 993
cert     = ""
key      = ""

[pop3]
port     = 110
tls_port = 995
cert     = ""
key      = ""
```

Windows 测试时路径前缀替换为 `./win`。

---

## 七、待确认问题（Open Questions）

| # | 问题 | 影响范围 |
|---|------|----------|
| OQ-1 | DKIM 私钥由系统自动生成还是管理员手动导入？影响 /admin 域名配置页交互设计 | P1-02、P1-06 |
| OQ-2 | 是否需要支持邮件转发规则（Forward Rule）？影响 SMTP 服务端逻辑复杂度 | P0-01 |
| OQ-3 | 附件大小上限由全局配置还是按用户配额单独限制？ | P0-07、P1-03 |
| OQ-4 | Web 界面是否需要支持富文本（HTML）邮件撰写，还是纯文本即可？ | P0-11 |
| OQ-5 | 多域名（P2-03）是否纳入第一期范围？影响数据库 Schema 设计 | P2-03 |
| OQ-6 | 是否需要 OAuth2 / 外部 LDAP 认证，还是仅本地账户？ | P0-09 |