【实战案例】宠物探险离线收益的时区坑：结算事故复盘

实战应用：用在哪里

宠物探险的离线收益在某个周一集体翻倍：玩家发现收益异常后论坛沸腾。排查的根因是时区的双重计算——探险的开始时间用了本地时区、结束时间用了 UTC，两个时间戳的差把 8 小时的探险算成了 16 小时。这起事故的复盘是时间处理的经典教材。

事故的代码

-- 事故版本：两种时区的时间混用
function Expedition.start(actor)
    setplayvar(actor, "HUMAN", "exp_start", os.date("%Y%m%d%H%M"), 1)
end

function Expedition.claim(actor)
    local startLocal = str2time(getplayvar(actor, "HUMAN", "exp_start"))
    local hours = math.floor((os.time() - startLocal) / 3600)
    return math.min(hours, 24) * EXP_PER_HOUR
end

开始时间存的是格式化文本（本地时区），结算时用 os.time 解析（按 UTC 解释），8 小时的时区差让收益翻倍。事故的触发条件是玩家在特定时段开始探险，问题的隐蔽性在于大部分时段的结算正确。

修复的方案

function Expedition.startFixed(actor)
    setplayvar(actor, "HUMAN", "exp_start", os.time(), 1)
end

function Expedition.claimFixed(actor)
    local startAt = tonumber(getplayvar(actor, "HUMAN", "exp_start")) or 0
    local hours = math.min(math.floor((os.time() - startAt) / 3600), 24)
    return hours * EXP_PER_HOUR
end

修复把开始与结束统一为时间戳存储，时间的计算全部在时间戳域完成，格式化只在展示层发生。事故的存量玩家按修复后的公式重新结算并补差，补差的邮件附上计算明细让玩家看得明白。时间类事故的复现用例进了回归集：跨天的探险、跨月的签到、跨年的排行榜，三类时间边界的用例每次发版必跑，时区坑的教训被用例永久记住。

验证与监控

探险收益的分布监控：收益的分布按小时分层，翻倍的异常层在修复后消失。

踩坑记录

事故的发现来自玩家的截图对比：同样的探险时长收益差一倍，截图的比对让排查直奔时间字段。时间处理的规范因此更新：所有时间的存储用时间戳、所有时区的换算在展示层、禁止在存储层出现格式化文本，三条铁律写进了开发规范。

上线要点

时间类变量的字段命名带 tz 后缀标记时间戳语义，命名即文档。存量数据的迁移脚本要有干跑模式：先打印受影响的行数再执行，干跑的输出是迁移的信心的来源。

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