【框架设计】邮箱系统设计：附件、过期与批量发放的完整实现

实战应用：用在哪里

补偿发放、订单交付、系统通知——所有"玩家不在线也要送达"的内容都走邮箱。邮箱系统的三块核心：附件托管（发放时物品先入附件、领取时校验入包）、过期清理（超期附件按规则返还或销毁）、批量发放（全服/按条件群发）。设计质量直接决定客诉量。

数据结构与领取流程

每封邮件一条记录：标题、正文、发件人、附件列表（物品id+数量）、过期时间、已读标志。附件领取的完整校验链：

function Mail.claimAttachment(playerId, mailId)
    local mail = loadMail(playerId, mailId)
    if not mail then return false, "邮件不存在" end
    if mail.expired and os.time() > mail.expired then
        return false, "附件已过期"
    end
    if mail.claimed then return false, "附件已领取" end
    local ok, err = BagService.addItem(playerId, mail.itemId, mail.count)
    if not ok then return false, err or "背包空间不足" end
    mail.claimed = true
    saveMailState(playerId, mailId)
    log("MAIL_CLAIM", playerId, mailId)
    return true
end

背包空间不足时的行为要明确：整封保留未领取状态（不部分领取），玩家清理背包后可再领。

批量发放的分批控制

全服补偿发放是事故高发操作。三条控制：按在线分批（每批 500 人，批间隔 1 秒），离线玩家走离线投递表；发放脚本支持断点续跑（记录已发放的玩家游标，中断后从游标继续）；发放前先对 10 个测试账号做全流程验证（含领取）。批量操作的幂等由订单式流水号保证，重复执行不重复发放。

过期清理的实现

过期清理走定时扫描：每次扫描一批（500 封），过期附件按类型处理——普通物品返还发件人或销毁、有价物品（充值类）转人工审核队列。清理必须留存记录：邮件摘要、附件内容、处理方式， retention 期与玩家协议一致。实测某服 3 万封存量邮件的分批清理耗时 41 秒，服务无感知。邮箱系统做好这三块后，所有"发东西"的需求都汇入同一个入口，发放逻辑从散落各处收敛到单点，审计与排障成本同步下降。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。