HN 系列 Wiki

主题

这页聚焦 HNMail 最核心的业务模型：

  • 一封邮件如何创建
  • 附件如何存储
  • 玩家如何领取
  • 为什么奖励推荐先进邮箱，而不是直接塞背包

邮件模型的核心思路 ​

HNMail 的邮件不是“只有标题和正文”的信件，而是一份完整的业务记录。

一封邮件通常至少包含：

  • 收件人 UUID / 名称快照
  • 发件人 UUID / 名称快照
  • 发件人类型：玩家 / 系统 / 管理员
  • 邮件类型：普通 / 系统 / 奖励
  • 标题与正文
  • 是否有附件
  • 已读状态
  • 删除状态
  • 创建时间、过期时间、删除时间
  • 来源服务器

这意味着 HNMail 在设计上更偏向：

可审计的投递单据，而不是单纯的聊天信箱。

为什么奖励推荐先进邮箱 ​

相比“命令一执行就直接给玩家东西”，邮箱式投递有明显优势：

  • 玩家不在线也能先投递
  • 背包满时不会立刻丢物
  • 管理员可先发，玩家后领
  • 奖励发放有可查记录
  • 物品 / 金币 / 命令三类奖励能统一入口

所以 HNMail 最适合做：

  • 节日礼包
  • 新手奖励
  • 活动补偿
  • 人工补发
  • 离线奖励中心

当前支持的附件类型 ​

1. ITEM ​

物品附件。

适合：

  • 装备
  • 材料
  • 礼包物品
  • 一次性实物奖励

2. MONEY ​

金币附件。

依赖：

  • HNEconomy
  • allow-money-attachment: true

适合：

  • 活动补贴
  • 签到奖励
  • 运维补偿

3. COMMAND ​

命令附件。

适合：

  • 权限发放
  • 头衔发放
  • 第三方礼包命令
  • 需要后台执行的奖励逻辑

默认建议保持关闭，确认风险边界后再启用。

附件是怎么存的 ​

ITEM ​

通常序列化为可持久化文本（例如 Base64 编码后的 ItemStack）。

MONEY ​

通常存：

  • currencyId
  • amount

COMMAND ​

通常存：

  • 原始命令文本
  • 领取时做变量替换后，由后台执行

这类设计的共同目标只有一个：

附件必须可离线持久化，而不是依赖当前在线对象。

玩家领取时会发生什么 ​

领取一封带附件的邮件时，通常会经历下面的流程：

  1. 读取该邮件未领取的附件
  2. 按附件类型分流处理
  3. 先做必要的前置校验
  4. 发放奖励
  5. 标记附件已领取
  6. 写审计日志

其中最关键的是第 3 步：

  • 物品附件先检查背包空间
  • 金币附件先校验货币与最大余额
  • 命令附件先确认当前服允许命令附件
  • 当前实现还会先锁定未领取附件，失败时尽量回滚并保留可追踪状态

也就是说，它不是先给奖励，再想办法补状态；而是先尽量挡住明显会失败的情况。

ITEM 附件的领取规则 ​

当前推荐策略 ​

  • 先检查背包空位
  • 背包空间不足则直接拒绝领取
  • 不做部分领取
  • 不做“先塞一半，剩下掉地上”

为什么不用部分领取 ​

因为部分领取会立刻带来这些复杂度：

  • 哪些算已领，哪些没领
  • 一个附件拆不拆分
  • 异常时怎么回滚
  • 玩家掉线时怎么处理

所以首版更推荐：

宁可保守拦截，也不要冒丢物风险。

MONEY 附件的领取规则 ​

金币附件通常会走 HNEconomy 的正式服务层，而不是自己写数据库。

也就是说，领取时会经过：

  • 货币是否存在
  • 金额是否合法
  • 领取后是否超过最大余额
  • 账变是否成功
  • 幂等请求是否被拦截

这能保证金币附件和正常经济系统共用同一套账务模型，而不是做一套“邮箱私账”。

COMMAND 附件的领取规则 ​

当前推荐策略是：

  • 仅管理员创建
  • 领取时由后台执行
  • 不以玩家身份执行

典型形式：

text
lp user {player} parent add vip

支持的变量 ​

  • {player}
  • {uuid}
  • {mail_uuid}
  • {server}

额外限制 ​

  • 当前实现不支持“命令附件和其他类型附件混发”
  • 当前实现也不支持“一封邮件里放多个命令附件”
  • 如果邮件里存在命令附件，通常应把它设计成单独一封奖励邮件

适合什么命令 ​

  • 权限奖励
  • 称号奖励
  • 受控礼包命令

不适合什么命令 ​

  • 高风险破坏性命令
  • 不可重复执行且无补偿机制的命令

领取后的审计 ​

一封邮件在生命周期里通常会留下这些动作：

  • send
  • admin-send
  • read
  • claim
  • delete

这意味着如果玩家反馈：

  • 没收到
  • 收到了但没领到
  • 说已经领过
  • 说奖励发错了

你不是只能靠猜，而是可以回审计和邮件日志去看。

删除和过期的关系 ​

邮件有两类常见退出方式：

玩家主动删除 ​

  • is_deleted = true
  • 写入 deleted_at
  • 后续由清理任务按 deleted_at 判断是否彻底移除

系统过期清理 ​

当前实现里，过期邮件和“玩家主动删除”不是同一条路径：

  • expire_at < now 的邮件会在清理任务里按批次直接清理
  • 清理时会一并删除关联附件与审计数据
  • 不依赖先写入 is_deleted = true 或 deleted_at

也就是说：

  • 玩家主动删除：更接近“软删除 → 延迟彻底清理”
  • 邮件自然过期：更接近“到期后由清理任务直接批量移除”

推荐的附件启用顺序 ​

最稳的启用顺序建议是：

  1. 先只开基础邮件
  2. 再开 ITEM
  3. 再接 MONEY
  4. 最后再评估 COMMAND

因为三类附件的风险层级其实完全不同：

  • ITEM：最直观
  • MONEY：涉及账务
  • COMMAND：涉及外部系统与命令安全

建议联动阅读 ​

HN 系列插件文档

Copyright © 2024