【插件发布】xvmail 1.7.0 — 游戏邮件 + 真实邮箱 HTML 通知 + 附件与领取奖励

---

插件名称： xvmail
当前版本： 1.7.0
作者： xiaolv
运行环境： Java 21；Paper API 编译目标 1.21.4，plugin.yml 声明 folia-supported: true
依赖： 无必需前置。JAR 已内置 Gson 与 Jakarta Mail；Vault / PlayerPoints 仅在开启付费发送时需要
存储： YAML 文件，无需数据库

一、这是什么

一个给 Paper / Folia 服务器用的游戏内邮件系统。玩家之间可以互相写信、寄物品，管理员可以给在线 / 离线玩家群发通知、发带奖励的领取邮件；玩家绑定真实邮箱后，别人发给他的游戏邮件会同步一封完整的 HTML 邮件到他的真实邮箱，玩家互发时邮件里显示的是发件玩家名，而不是笼统的服务器名。

文件读写、SMTP 发送、AI 审核请求都在后台线程执行，不占用游戏主线程。

二、主要功能

游戏内邮件

• 玩家私信、自定义主题与正文；在线 / 离线均可投递，上线后补看
• 分页收件箱 GUI、已读状态、单封删除、二次确认清空、登录未读提醒
• GUI 写信流程（收件人 → 主题 → 正文，随时输入 cancel 取消）
• 可配置邮件模板，支持 {player} / {sender} 占位符
• 主手整组物品作为附件，收件人在详情页点击领取一次；背包满则掉落脚边
• 每日免费发送次数，超出后可用 Vault / PlayerPoints 付费发送；失败自动退回次数与费用

真实邮箱

• SMTP 验证码绑定，验证成功后才写入 email_bindings.yml
• 游戏邮件成功投递后自动同步到已验证绑定邮箱，默认开启，覆盖玩家互发、管理员 / 控制台投递、领取邮件与近期上线群发
• 同步邮件是完整 HTML 邮件：Player Mail / System Notice 两套可自定义模板，品牌栏、发件人、正文、附件说明、通知标签与页脚一应俱全，Content-Type: text/html; charset=UTF-8
• 发件人区分来源：玩家互发显示 玩家名 (via 服务器名)，正文标注「发件人：玩家名（游戏内玩家）」和「来自：服务器名」；管理员 / 系统邮件显示服务器名
• 玩家填写的主题、正文、玩家名、服务器名都做 HTML 转义，防止邮件里被注入标签
• 验证码邮件同样是 HTML，验证码以大号字体突出显示

管理员与运营

• 管理员 GUI：发信、管理指定玩家邮箱、重载配置、近期上线筛选、领取邮件、领取命令设置
• 控制台可向在线 / 离线玩家投递；recent 按最近上线时间（1–3650 天）群发
• 领取邮件：玩家点击后由控制台执行服主预设命令，单封邮件只领一次，状态先写盘再执行
• 可配置 OpenAI-compatible AI 内容审核（仅玩家邮件）；链接与常见服务器宣传先由本地规则拦截，远程审核异常时 fail-closed 拒绝发送；管理员 / 控制台邮件免审核
• Paper / Folia 调度适配，存储、SMTP、审核网络请求异步执行

三、玩家命令

/mail                              打开邮件中心
/mail send <玩家> <正文>           普通发信（免费额度）
/mail sendex <玩家> <正文>         付费发信
/mail template <模板名> <玩家>     发送模板邮件
/mail list                        列出邮件
/mail read <ID>                   阅读邮件
/mail clear <ID|all>              删除 / 清空邮箱
/mail bindeamil <邮箱>            申请绑定验证码
/mail verifyemail <验证码>        完成邮箱绑定
/mail myemail                     查看绑定邮箱
/mail unbindemail                 解绑

邮箱绑定同时兼容正确拼写 /mail bindemail <邮箱>。

四、管理员命令

/mailadmin                                            管理主菜单（玩家可用 GUI）
/mailadmin send [online|offline] <玩家> <主题> <正文>  在线 / 离线投递
/mailadmin recent <天数> <主题> <正文>                 近期上线玩家群发
/mailadmin claim <玩家> <主题> <正文>                  发送领取邮件
/mailadmin claimcommand <命令模板>                     设置领取命令
/mailadmin listall <玩家>                              查看邮件数 / 未读数
/mailadmin clearall <玩家>                             清空玩家邮箱
/mailadmin reload                                      重载配置

领取命令示例：

/mailadmin claimcommand give {player} diamond 3
/mailadmin claim Alex 新手奖励 完成新手任务后点击领取

模板必须且只能包含一个 {player}，并拒绝命令拼接字符。请只填写可信的奖励命令。

五、安装（三步就能发信）

1. 把 xvmail-1.7.0.jar 放入 plugins/，启动一次生成配置。
2. 处理审核：moderation.enabled 默认 true 且 Key / 模型为空，审核是 fail-closed 的，不配服务就会拒绝所有发信。请填好兼容接口的 api-url / api-key / model，或明确改成 enabled: false（本地链接与宣传拦截仍会生效）。
3. 配置 SMTP（验证码与真实邮件都需要）：

smtp:
  enabled: true
  host: smtp.qq.com
  port: 465
  username: "your@qq.com"
  password: "邮箱 SMTP 授权码"
  from-address: "your@qq.com"
  from-name: "teana server"
  use-ssl: true
  use-tls: false
  timeout: 10000
email-bind:
  enabled: true
  auto-send-real-email: true

from-name 就是真实邮件里显示的服务器名。QQ / 163 一般用 465 + SSL 与授权码；Gmail / Outlook 一般用 587 + STARTTLS。改完执行 /mailadmin reload。

付费发送（可选）：

sending:
  daily-free-limit: 10
  daily-paid-limit: 20
  currency: vault
  paid-cost: 100.0

Vault 需要再装 EssentialsX / CMI 等经济实现；用 PlayerPoints 请把 currency 改成 playerpoints。启动日志会打印 付费发送货币=...：<状态>，扣费失败时玩家和后台都能看到具体原因。

六、真实邮件效果说明

插件内置两套可自定义的 HTML 模板，按来源自动选择：

场景	模板	效果
玩家 → 玩家	Player Mail	品牌栏、圆形首字母头像、发件玩家 ID、「向你发送了一封邮件 · 服务器名」、正文、附件说明、游戏内回复提示、页脚版权
管理员 / 控制台 / 系统 / 群发 / 领取邮件 / 验证码	System Notice	品牌栏、System Notice 标记、通知类型标签、大标题、正文、页脚；验证码用高亮区块突出 6 位数字

举个例子：服务器名设为 teana server，玩家 Steve 给已绑定邮箱的 Alex 发信，Alex 收到的邮件发件人显示 Steve (via teana server)，头像圆里是 S，正文下方标注附件情况，页脚写明由玩家系统自动发送。管理员发的通知则显示服务器名并带 系统通知 标签。

模板文件在 plugins/xvmail/templates/player-mail.html 与 system-mail.html，首次启动自动释放；品牌名直接取 smtp.from-name，配色和文案可编辑 HTML 调整，改完 /mailadmin reload 生效，不需要重新编译插件。邮件底部带一行「邮件系统由 xvmail 插件提供」。占位符由插件填充：玩家模板用 [player_name]、[player_initial]、[server_name]、[Article]、[Attachment_content]；系统模板用 [notice_type]、[notice_title]、[notice_content]。玩家填写的内容一律转义成纯文本，避免邮件里被注入 HTML。

七、数据文件与备份

plugins/xvmail/
├── config.yml                    配置（含密钥，注意保密）
├── email_bindings.yml            已验证的邮箱绑定
├── daily_quotas.yml              每日发送计数
└── mail/
    ├── <uuid>.yml                每位玩家的邮件
    └── pending-attachments.yml   待退回的附件物品

建议停服后整体备份。写入采用临时文件 + 原子替换，降低崩溃时数据损坏的风险。

八、常见问题

Q：装好之后一封邮件都发不出去？
A：九成是审核。默认 moderation.enabled: true 但没填 Key / 模型，接口调用失败就拒绝发送。配置审核服务或关掉 AI 审核即可。另外本地规则会拦域名、邮箱地址、IP 和部分「服务器 + 加入 / 欢迎」组合，发信时避免这些写法。

Q：游戏里收到了，真实邮箱没有？
A：确认玩家已 /mail verifyemail 绑定成功、SMTP 已启用且授权码正确、同步开关为 true、邮件不在垃圾箱。同步失败不影响游戏内邮件，后台会有日志。

Q：邮件发件人怎么是服务器名？
A：管理员、控制台、系统发的邮件就显示服务器名；只有玩家互发才显示玩家名 + via 服务器名。若玩家邮件也显示服务器名，检查 mail.console-sender-name 是否被设成了玩家名。

Q：付费发送扣不了钱？
A：Vault 只是桥接层，还需要经济实现插件；currency 也要和实际安装的插件一致。启动日志和扣费失败提示会给出具体原因。发送失败时费用与次数都会退回。

Q：需要数据库吗？
A：不需要，当前是 YAML 存储；SQLite 未实现。

九、1.7.0 更新内容

• 真实邮件同步默认开启，并补上管理员群发路径；旧配置首次启动自动升级到 config-version: 2
• 真实邮件升级为完整 HTML 模板，玩家互发显示玩家名与来源服务器，不再统一显示服务器名
• 明确 text/html; charset=UTF-8 与 X-Mailer 头，验证码邮件同样使用 HTML 样式
• 修复 Vault / PlayerPoints 扣费失败：改用官方 OfflinePlayer 方法签名，兼容旧版 String 重载与 PlayerPoints 新旧 API
• 增加经济服务启动诊断、扣费失败具体原因、同步失败与 SMTP 队列拒绝日志
• 玩家与服主教程、BBS 发布稿全面重写

十、注意事项与已知限制

• 审核会把邮件主题与正文发送到服主配置的第三方接口；SMTP 邮件也会经过所选服务商。请确认数据政策、告知玩家，并保管好 config.yml 里的 API Key 与邮箱授权码。
• 本地链接 / 宣传规则不可关闭，且可能误伤 Hi.Hello、正文邮箱地址、服务器欢迎新人加入 等正常文本，上线前请用本服常见措辞实测。
• 领取奖励属于「最多执行一次」：状态先写盘再执行命令，极端情况下（写盘后崩溃）可能出现已标记领取但奖励未发；奖励命令建议做成幂等。
• 删除 / 清空带未领取附件的邮件，物品不会退回；SMTP 任务队列上限 128，超大群发建议分批。
• 没有过期邮件自动清理；外部 XvMailAPI 只覆盖基础收发、未读与邮箱绑定查询。
• 编译目标为 Paper API 1.21.4，源码声明 Folia 调度支持；尚未在真实 Paper / Folia 服务器完成装载验证，也没有自动化测试。请先在测试服验证启动关闭、在线 / 离线收件、GUI 路径、SMTP、经济扣费退款、附件与领取并发路径，再上正式服。兼容范围仅按已核对的编译目标与源码声明描述。

---

感谢各位服主与玩家的反馈，祝大家收信愉快。