【框架设计】首充礼包：跨角色标记与漏发补发

实战应用：用在哪里

首充双倍与首充礼包是付费转化的第一环，新玩家第一笔付费的体验决定后续付费意愿。标记必须挂在账号而不是角色上，否则玩家换角色反复领；漏发场景要有对账补发机制，付费体验出问题最伤口碑，一单漏发被截图传播的损失远超一单金额。

首充标记

function FirstCharge.grant(accountId, productId)
    if firstChargeDone[accountId] then
        return FirstCharge.normalReward(productId)
    end
    firstChargeDone[accountId] = os.time()
    QF_PersistJson("first_charge", firstChargeDone)
    return FIRST_CHARGE_PACK
end

标记按账号维度持久化，任何角色充值都只走一次首充流程，换角色、删号重建都无法重复领取。标记文件写入与支付回调同事务，崩溃后可从支付流水重建标记，两个数据源互为备份。

对账补发

function FirstCharge.reconcile(day)
    local pays = PayFlow.load(day)
    for _, pay in ipairs(pays) do
        if pay.productId == FIRST_CHARGE_ID and not pay.delivered then
            local role = QF_MainRole(pay.accountId)
            QF_MailItems(role, FIRST_CHARGE_PACK, "首充补发")
            pay.delivered = true
            QF_Alarm("首充漏发已补", pay.orderId)
        end
    end
end

每日凌晨比对支付流水与发放记录，漏发自动补邮件并告警，补发动作本身也留痕。礼包内容跨端一致，客户端领取按钮用 GUI:addOnClickEvent 绑定，未充值态展示跳转支付页，支付完成回调刷新礼包状态。首充价格档位按渠道配置，礼包内容全服统一，避免比价纠纷。

验证与监控

支付回调到礼包到账的时长按分钟监控，超过 5 分钟未到账即预触发补发流程。

踩坑记录

支付回调的幂等键设计在第一次大促就经受住考验，同笔回调重复推送了四次，礼包只发了一次，幂等这课在支付链路上永远不嫌贵。首充跳转支付页的转化埋点曾经统计了重复点击，一个玩家连点八次算八次流失，埋点口径改成按会话去重后数据才可用。礼包内容的全服统一口径避免了比价纠纷，跨渠道差价留给渠道政策处理，游戏内绝不做两套价格。首充礼包的内容物做过一轮数据复盘，武器外观的使用率远超预期，外观类物品在付费首包里的权重随后上调，玩家用真金白银投票的结论最可靠。支付页到礼包领取页的跳转链路做了三段埋点，每一段的流失率都有归因，最长的流失发生在支付成功后的加载等待，等待动画的优化让转化率又抬了一个点。补发流程的自动化程度持续提升，从人工审核到自动补发加事后抽检，处理时长从小时级压到分钟级。首充礼包的内容物做过一轮数据复盘，武器外观的使用率远超预期，外观类物品在付费首包里的权重随后上调，玩家用真金白银投票的结论最可靠。支付页到礼包领取页的跳转链路做了三段埋点，每一段的流失率都有归因，最长的流失发生在支付成功后的加载等待，等待动画的优化让转化率又抬了一个点。补发流程的自动化程度持续提升，从人工审核到自动补发加事后抽检，处理时长从小时级压到分钟级。

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