> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wanyouxi.online/llms.txt
> Use this file to discover all available pages before exploring further.

# 邮件系统设计

> **摘要**：本文聚焦「邮件系统设计」，梳理核心概念、关键方法与落地实践。

> **核心定义**: 邮件系统是游戏服务器与玩家（以及玩家之间）进行**异步通信**的核心管道。它不仅是信息传递工具，更是资源发放、运营补偿和社交互动的关键载体。

## 1. 🗂️ 功能分类 (Functional Classification)

### 1.1 系统邮件 (System Mail)

* **全服广播 (Global Broadcast)**:
  * *场景*: 停服维护补偿、节日活动奖励、版本更新公告。
  * *技术特点*: 只有一份数据存储在公共区域，玩家读取时动态实例化引用，节省存储空间。
* **定向通知 (Targeted Notification)**:
  * *场景*: 排行榜结算奖励、竞技场排名变动、客服回复。
  * *技术特点*: 点对点发送，存储在玩家个人数据块中。

### 1.2 触发式邮件 (Triggered Mail)

* **溢出保护 (Overflow Protection)**: 当背包已满时，获得的道具自动转入邮件。
* **离线收益 (Offline Gains)**: 基地挂机产出在上线时通过邮件汇总报告（可选，增加仪式感）。

### 1.3 社交邮件 (Social Mail) (可选)

* *注意*: 现代手游通常**慎用**自由文本的 P2P 邮件，以避免广告、骚扰和 RMT (现金交易)。
* **公会群发**: 仅限公会会长向成员发送通知。

## 2. 💾 数据结构与生命周期 (Data & Lifecycle)

### 2.1 核心数据字段

| 字段名           | 类型            | 说明                                       |
| :------------ | :------------ | :--------------------------------------- |
| `MailUID`     | UUID          | 唯一标识符。                                   |
| `TemplateID`  | Int           | 引用本地化文本模板 (支持多语言)。                       |
| `Parameters`  | List\<String> | 动态参数 (如: "恭喜你在\[S1 赛季]获得第\[3]名")。        |
| `Attachments` | List\<Item>   | 附件列表 (ID, 数量, 类型)。                       |
| `State`       | Enum          | 未读 (Unread) / 已读 (Read) / 已领取 (Claimed)。 |
| `CreateTime`  | Timestamp     | 发送时间。                                    |
| `ExpireTime`  | Timestamp     | 过期时间 (TTL)。                              |

### 2.2 生命周期管理 (TTL Policy)

* **有效期**:
  * 含附件邮件: 通常 **30 天**。过期自动删除，附件可能会被系统回收或再次尝试发送（不推荐）。
  * 无附件通知: 通常 **7-14 天**。
* **容量限制 (Cap)**:
  * 例如上限 **100 封**。
  * **策略**: 当超过上限时，优先删除 **\[已读且无附件]** -> **\[已读且已领取]** 的邮件。
  * *警告*: 绝对**不能**自动删除含有未领取附件的邮件，除非它们已过期。如果必须删除，应阻止新邮件进入并报错（但这体验很差），通常做法是建立一个临时溢出缓冲区。

## 3. 👆 用户体验设计 (UX/UI)

### 3.1 交互流

1. **红点 (Red Dot)**: 仅当有 \[未读] 或 \[有未领取附件] 的邮件时显示。

2. **一键领取 (Claim All)**:

   * **必须功能**。玩家极其厌恶一封封点。
   * *逻辑*: 遍历所有邮件 -> 领取附件 -> 标记为已读 & 已领取 -> 弹窗汇总显示获得的物品。

3. **一键删除 (Delete Read)**: 仅删除 \[已读] 且 \[无附件/已领取] 的邮件。

### 3.2 视觉层级

* **重要性标记**: 维护补偿、大奖应有特殊边框或置顶显示。
* **附件预览**: 在邮件列表页直接显示前 3 个附件图标，吸引点击。

## 4. ⚙️ 运营后台需求 (GM Tool Requirements)

* **批量发送**: 支持按 UserID 列表导入发送。
* **条件筛选发送**: "发送给所有等级 > 20 且 3 天内登录过的玩家"。
* **定时发送**: 预设好节日邮件，零点自动触发。
* **撤回功能 (Recall)**:
  * *紧急功能*: 如果发错了奖励（例如发了 10000 钻而不是 100 钻），必须能紧急撤回。
  * *限制*: 只能撤回玩家**尚未领取**的邮件。如果已领取，需要回档或扣除对应货币（负债）。

## 5. 🏗️ 性能与架构 (Architecture)

* **冷热分离**: 活跃邮件存 Redis/内存，过期或已删除邮件归档到冷存储（或直接丢弃）。
* **拉取策略**: 登录时只拉取 Header (标题/状态)，点击具体邮件时再拉取 Body (正文)，减少登录包体大小。