主题
GameSystemUI 运营邮件收件箱
GameSystemUI 已提供基于 OperationMail 的运营邮件收件箱：服务端查询全服和个人邮件，用 CloudData 保存每位玩家的已读、领取、隐藏状态；客户端可直接使用邮件入口、红点和收件箱窗口。适合运营后台给玩家发通知或游戏资源附件，不是玩家互发邮件，也不提供游戏脚本主动发信接口。只需要原始邮件数据、自行设计状态和界面时，使用 OperationMail 底层查询。
接入默认界面
项目需引用 GameSystemUI 依赖库。邮件服务通过 MailSystemInitializer 自动注册；默认 UI 需要项目在客户端自行创建，不会自动出现在游戏画面。
csharp
#if CLIENT
using GameSystemUI.MailSystemUI.Advanced;
public static class MailUiSetup
{
public static (MailWindow Window, MailEntrance Entrance) Create()
{
var window = MailWindow.Create(); // 加入界面，默认隐藏
var entrance = MailEntrance.Create(window); // 加入界面，默认显示
return (window, entrance);
}
}
#endif在客户端 UI 初始化时创建一次即可；不要在每次显示窗口时重复创建。可以自行控制入口的布局、可见性，或只创建 MailWindow 并通过项目自己的按钮调用 mailWindow.Show() / Hide()。打开窗口会请求服务端刷新收件箱；登录后服务端也会主动推送一次（默认延迟 2 秒）。列表支持查看详情、已读标记、领取、批量领取及删除（隐藏），入口显示未读或待领取红点；服务端会校验所有写操作。
示例中的 MailUiSetup.Create() 应在客户端 UI 初始化时调用一次，并保存返回的控件；不再使用时依次调用 Entrance.Destroy()、Window.Destroy() 释放控件及事件订阅。
不使用默认界面时，客户端可通过 GameSystemUI.MailSystem.MailSystemClient 调用 QueryInbox()、MarkRead(mailKey)、Claim(mailKey)、ClaimAll()、Hide(mailKey)，订阅 OnInboxSync、OnActionSuccess、OnActionFailed、OnRedDotChanged，并读取 CachedMails、UnreadCount 和 UnclaimedCount。这些方法返回的 bool 仅表示请求是否已发出，实际结果以后续事件为准；mailKey 从 MailRecordView.MailKey 获取。
服务端设置与附件
GameSystemUI.MailSystem.MailSystemServer 默认使用当前项目 ID 作为 MapName，按游戏局运行时环境生成 EnvironmentName，默认每次查询都访问后台（QueryCacheTtl = TimeSpan.Zero）。若项目的邮件后台使用不同的地图名或环境名，在查询发生前显式设置这两个属性。
默认环境按当前游戏局的 Game.RuntimeEnvironment 映射：Formal 查询后台 formal，Test 查询 test，Debug 查询 debug，与 OperationMailApi 的枚举重载一致。运行环境未知时不会回退到其它邮件环境；如项目确有特殊后台配置，可显式设置 MailSystemServer.EnvironmentName 覆盖默认值。不要把 Game.DeploymentEnvironment 或部署环境 production 当作邮件环境。
附件按运营后台的资源链接及数量解析，对应 GameDataLobbyResource；领取时服务端把资源发放与已领取状态放入同一 CloudData 事务，避免重复领取。资源需事先配置并能解析；无法解析的附件不会被误发放。平台星火币附件不由此收件箱发放。ReceiveType == 1 的静默邮件在玩家登录后尝试自动领取，不进入可见收件箱。默认不允许隐藏尚未领取的附件邮件；需要修改时可设置 MailSystemServer.AllowHideUnclaimed。服务端还可订阅 OnClaimSuccess / OnClaimFailed，或通过 ShouldIncludeMail 自定义可见范围。
全服邮件默认遵循后台“排除新玩家”选项，个人邮件不受此过滤影响。首次进入时间由邮件系统单独记录；EnableNewPlayerFilter 可关闭内置过滤。查询失败时系统返回失败结果，不会把失败当作空收件箱继续领取。邮件正文、附件及有效期以后台查询为准；已读、领取、隐藏状态存于 CloudData。
使用边界
- 仅服务端可查询运营邮件并执行领取；客户端缓存仅用于显示，不能当作发放凭据。
- 邮件到期后不再可领取；后台配置的生效窗口按北京时间比较，返回的邮件时间按 UTC 解释，默认 UI 转为北京时间显示。
- 需要自行实现邮件规则或界面时，参阅 OperationMail 运营邮件查询；不要同时让自建流程和 GameSystemUI 为同一附件分别发放奖励。