Mail 邮件系统

模块简介

Mail 是 Suite 的全功能邮件系统模块，提供 收件箱、玩家写信、预设邮件、CDK 兑换 四合一邮件服务。模块通过 ArcartX UI 实现全图形化交互，支持物品附件、多货币附件、领取条件、内容审核、跨服同步等高级功能，并可被其他模块通过 MailDispatchable Capability 调用发送奖励邮件。

如果你只需要收件箱，可以前往 ArcartX 官方购买高级会员获取插件 SystemMail。

Suite 支持将 SystemMail 作为邮件后端：未启用本模块时，其他模块的邮件发送请求会自动降级转发给 SystemMail 投递，详见下方「SystemMail 降级模式」。

SystemMail 降级模式

当服务器未启用本模块（mail）但安装了 SystemMail 插件时，宿主会自动注册一个降级适配器（SystemMailMailDispatchable），把 MailDispatchable Capability 指向 SystemMail——所有依赖邮件发送能力的模块会无感知地改用 SystemMail 投递邮件，收件、查看、领取由 SystemMail 自身的收件箱提供。

工作原理

1. 自动检测：宿主在模块加载前检测 SystemMail 是否已安装且 API 就绪（SystemMailApi.isReady()）
2. 注册降级适配器：检测通过即注册为 MailDispatchable 核心 Capability，控制台输出 检测到 SystemMail 插件，已注册邮件降级适配器（MailDispatchable → SystemMail）
3. 模块无感知接管：所有通过 MailDispatchable.sendMail() 发邮件的功能自动改走 SystemMail，模块侧零配置。涵盖 BattlePass 赛季奖励、Market 到期退回、OnlineRewards 在线奖励、EntityTracker Boss 结算、Fishing 奖励、Lottery 奖品、EventPacket 事件邮件、QQBot 通知等
4. 本模块优先：mail 模块正常加载时会覆盖降级适配器，所有邮件回到 AXS 邮箱，SystemMail 适配器不再生效；此时 SystemMail 自身的邮件仍保留在其收件箱中，两套邮箱互不影响

发送内容映射

限制与注意事项

• 货币附件会丢失：降级模式下邮件中的货币附件（含 Vault 金币）不会发放，玩家只收到标题、正文和物品附件。依赖货币奖励的场景建议安装本模块
• 预设派发不可用：dispatchPreset 直接返回失败（SystemMail 不支持预设派发），依赖预设的模块需自行降级处理
• 仅接管发送能力：写信界面、AXS 收件箱 UI、预设、CDK、邮件日志、领取条件等均为本模块功能，降级模式下全部不可用
• 启动时检测一次：适配器仅在宿主启动时注册。若启动日志未出现降级适配器提示，请检查 SystemMail 是否正常启用，并保证其先于 Suite 完成启用

降级适配基于 SystemMail 1.0.0 API（priv.seventeen.artist.arcartx.systemmail.api）构建。SystemMail 的 send 为异步接口，适配器最多阻塞等待 5 秒；超时将乐观返回成功，实际投递由 SystemMail 在后台完成。

功能特性

依赖

邮件类型详解

Mail 模块通过 MailSourceType 枚举区分四种邮件来源类型：

系统邮件

系统邮件由其他模块通过 Capability 或公开 API 发送。例如 BattlePass 发放赛季奖励、Market 退回到期物品、OnlineRewards 发放在线奖励等。系统邮件支持物品附件和货币附件混合，可自定义发件人名称和过期时间。

玩家邮件

玩家通过 /mail compose 打开写信界面，填写收件人、标题、正文，并可从背包拖入物品附件和填写 Vault 货币金额。发送时根据配置收取手续费（base-fee + item-fee）和货币附件税率（attachment-tax-rates）。玩家邮件受内容审核约束，命中敏感词/正则/物品屏蔽规则时禁止发送。

预设邮件

预设邮件是管理员预先定义的邮件模板（YAML 文件），包含固定的标题、正文、附件、领取命令和领取条件。管理员可通过命令或管理 UI 批量派发给在线玩家（all-online）或全部注册玩家（all-registered），多人派发需二次确认。预设邮件还可内嵌 CDK 兑换码，执行 /axs reload mail 后自动同步到数据库。

CDK 邮件

CDK 邮件是玩家通过 /mail cdk <code> 兑换兑换码后自动投递的邮件。CDK 关联一个预设邮件，兑换成功后预设邮件的内容（标题、正文、附件、领取命令、领取条件）会作为新邮件投递到玩家收件箱。CDK 支持全局共享领取次数（所有玩家共用，领完即止）和每玩家仅可领一次的限制。

邮件生命周期

邮件从发送到最终清理，经历以下状态流转（由 MailStatus 枚举管理）：

发送 ──→ UNREAD ──→ READ ──→ CLAIMED ──→ 自动清理删除
           │                    │
           │                    └─→ DELETED ──→ 自动清理删除
           │
           └─→ EXPIRED ──→ 自动清理删除

完整生命周期

1. 发送：系统/玩家/预设/CDK 触发邮件发送，邮件以 UNREAD 状态写入 mail_entries 表，附件写入 mail_attachments 表
2. 投递通知：若收件人在线，发送 ArcartX 聊天卡片通知（axs_mail_notify），并刷新收件箱 UI；若跨服启用，通过 Redis/Proxy 广播 refresh:<uuid> 消息
3. 查看：玩家打开收件箱（/mail），选中邮件时自动标记为 READ
4. 领取：玩家点击领取，系统检查领取条件（claim-conditions）、背包空间，原子标记为 CLAIMED，发放物品到背包、执行领取命令、存入货币
5. 删除：玩家手动删除（受 allow-delete-with-unclaimed-attachments 配置约束），标记为 DELETED
6. 过期：定时清理任务将超过 expires_at 的邮件标记为 EXPIRED
7. 清理：定时清理任务删除超过保留天数的 CLAIMED/DELETED/EXPIRED 邮件及其附件记录

过期与清理

预设邮件的过期时间由预设的 expires-after-days 字段控制，覆盖默认值。