邮件
1. 功能范围
邮件承载系统和运营通知，以及随邮件发放的附件奖励。功能包括列表、正文、阅读、领取、删除、锁定和链接点击状态；发送与奖励结算以服务端结果为准。
本文分别说明策划规则和已读到的客户端实现。旧来源批准状态为 unknown，整理不会使其自动成为已批准或已上线规则；按钮可见也不代表奖励已经到账。
2. 入口、开放与前置条件
玩家通过主界面已开放的邮件入口进入列表。关闭列表返回主界面，关闭详情返回邮件列表。具体开放条件归主界面、功能入口与红点，现有邮件资料未给出固定等级或关卡门槛。
列表摘要用于快速展示；详情响应补全正文、附件和有效期。领取要求邮件存在未领取附件，不能仅凭列表上的礼物图标认定当前仍可领取。服务端删除资格及过期摘要如何处理尚待确认。
3. 玩家流程
- 进入邮件列表，查看标题、状态和剩余时间，选择一封邮件打开详情。
- 查看标题、正文、发送者、发送时间和附件图标、数量。点击附件可打开道具说明；无附件时隐藏奖励区并向下扩展正文。
- 有未领取附件时点击领取。成功响应后更新奖励展示以及已读、已领状态；失败不能提前标记已领取。
- 返回列表继续处理邮件，或使用一键领取、一键删除。锁定与链接点击各自记录状态，不替代阅读或领奖。
源码存在独立阅读、领取、删除、锁定和链接点击命令，但命令存在不代表所有操作都有当前界面入口；以下按钮表现仅列已有资料明确的部分。
4. 业务规则与资源变化
| 操作 | 规则与资源变化 |
|---|---|
| 单封阅读 | 请求阅读状态。无附件邮件可转为已处理；有附件邮件仍保留待领奖状态，阅读不发附件奖励 |
| 单封领取 | 仅有未领取附件时显示领取按钮；成功后一次性领取该邮件附件，更新已读、已领和奖励展示。未成功不能提前变更为已领取 |
| 一键领取 | 已读、未读邮件中的可领取附件都参与，同种道具在奖励弹窗堆叠。UI 源表还要求无奖励邮件一并标已读，当前是否执行尚待确认 |
| 一键删除 | 策划规则仅删除已读且没有未领附件的邮件；不能将“读过但未领奖”视为可删除。普通删除应尊重锁定，实际服务端资格检查待确认 |
| 锁定与解锁 | 锁定为独立状态，成功响应后更新。解锁恢复普通删除资格，不改变奖励状态；锁定与自动过期、容量清理的关系未定义 |
| 链接点击 | 单独记录点击状态，不能替代阅读或附件领取 |
附件奖励随邮件数据下发；现有资料未定义领取是否存在额外消耗，本页不补定消耗或固定奖励数值。重复领取的服务端处理、失败重试及批量操作部分成功时的处理尚无确认结论。
5. 状态、界面反馈与红点
列表与详情
| 项目 | 策划表现 |
|---|---|
| 加载 | 首次加载 10 封，滚至末尾再加载 10 封；当前客户端与此不同，见第 9 节 |
| 排序 | 未读优先，其次有未领附件，其次发送时间从新到旧 |
| 邮件状态 | 无奖励邮件打开后已读；有奖励邮件的方案图保留未处理视觉直到领取。已处理显示灰色开封信封及“已查收”；有附件显示礼物标记 |
| 滚动提示 | 列表末项露出一部分，提示可继续滚动 |
| 空态 | 显示“空空如也”，一键领取、一键删除不可点；当前禁用表现尚待核实 |
| 领取反馈 | 当前详情未领时显示领取按钮，已领时显示已领取标识。旧表“领取后变删除按钮”与此冲突，不作为当前界面规则 |
列表原型表达未读、礼物、已读灰态、剩余时间和底部批量按钮，不是当前实机截图。
详情按标题与关闭、正文、发送者、附件及领取按钮分区；左侧小图表示领取后的勾记。
无附件时不保留空奖励区，正文区域下延。
红点
| 环节 | 规则 |
|---|---|
| 出现 | 存在未读邮件，或存在有附件但未领取的邮件 |
| 清除 | 对应未读、未领条件都不再成立时清除；进入列表本身不能无条件清除。有附件邮件只读未领时仍保留红点 |
| 刷新 | 初始化邮件数据、新增或删除推送，以及阅读、领取、删除成功后的状态变化，需要重算列表和红点；到期清理后的刷新实际路径待确认 |
| 层级 | 邮件状态汇总至邮件功能入口；父入口按主界面红点树聚合。资料未列出邮件专属的更多红点层级，不补造详情按钮红点 |
6. 时间、清理与中断恢复
策划规定每封邮件保存 25 天，到期移除，包含尚未领取的附件。容量可因性能设置上限，但未给具体数量；超限时从最早邮件删除，即使未到期或未领奖。这两项是旧方案的明确条款，尚未确认服务端当前策略，不能改写为保护未领奖励或宣称已经生效。
当前详情将 ExpireTime 与本机 UTC 的差值向上取整为剩余天数，到期显示 0，没有时间戳时留空。这个显示算法不证明服务端按本机时间执行清理。
客户端有摘要与详情合并、全量种子加载及成功回包后的缓存更新；现有资料不足以确定断线、超时、重登后的恢复顺序和重试行为。删除后仍打开的详情如何关闭或提示、锁定邮件是否免于到期或容量清理，也需要确认。资料没有另定义邮件每日重置规则。
7. 埋点与统计
现有埋点与数据分析没有定义邮件打开、阅读、领取、删除或链接点击的专属事件名、字段和上报归属，不能据此断言运行时没有埋点。
共同事件 item_change 用于物品数量变化，字段包括道具 ID、变化途径、变化前数量、变化量、变化后数量及获得/消耗类型。它可用于理解邮件奖励的资源记录，但邮件领取是否接入、使用哪种途径值、如何处理重复上报仍待核实；点击领取不能代替权威发奖结果。角色身份和公共属性沿用共同定义，本页不另建事件 ID。
8. 数据、配置、文案与关联规则
邮件数据包括 ID、标题与正文及其多语言参数、发送者、发送时间、过期时间、已读、附件已领、锁定、链接点击状态，以及奖励列表。摘要和详情分别承担快速列表展示与内容补全，不应把摘要缺失字段解释成业务状态已经结束。
文案和视觉要求包括“空空如也”“已查收”、已领取标识与剩余天数；现有资料未给出它们的确切语言 key。入口与红点聚合归主界面、功能入口与红点，附件说明与奖励展示使用道具与资源的共同语义。
9. 当前实现、待确认差异与依据
以下静态事实来自 frontend 7f0636c9，不等于本轮已完成界面和服务端链路测试。
| 源码位置 | 已确认的实现与差异 |
|---|---|
Features/Mail/Model/MailModel.cs | 管理缓存、摘要与详情合并、一次全量种子加载，以及成功回包后的阅读、领取、删除、锁定、URL 状态。领取标记同时置已读和已领，红点计算为未读或有附件未领 |
MailModelVO.SortMail | 当前排序为锁定→未读→有附件→未领取→时间新。“有已领取附件”也可能影响顺序，与策划只优先未领附件不同 |
UI/ViewMailLogic.cs | 展示全量缓存，以空 IDs 派发批量命令；没有实现每 10 封分页，空态刷新中未见批量按钮禁用分支 |
UI/PanelMailShowLogic.cs | 从缓存取得最新详情并监听变化；无附件扩展正文，有附件显示奖励条目，未领显示按钮、已领显示标识。按第 6 节算法显示剩余时间；该视图自身不发奖励 |
Commands/MailReceiveCommand.cs、MailReadCommand.cs、MailDeleteCommand.cs、MailLockCommand.cs、MailURLClickCommand.cs | 分别为领取、阅读、删除、锁定、链接点击的命令入口 |
需要确认的差异集中在：服务端 25 天及容量清理、锁保护和删除资格；一键领取是否将无附件邮件标已读；分页与空态按钮；过期摘要有效期；重复领取、失败重试及删除后详情表现。本文保留这些差异，不替任一未决方案作产品批准。
来源：旧 features/mail.md；飞书 QiscbUo8soVy5KxTiNzcB7Fen0d 的功能表、列表表、详情表与原型（阅读件 2026-10-13）；上述 frontend 文件。
现有测试入口：Features/Mail/Tests/MailModelTests.cs、Features/Mail/Tests/PlayMode/MailUiClickRoundTripTests.cs。本次未运行、未新增或扩写测试。本地验证：根据项目策略禁止执行。