Godot 赛后结算弱网补偿：奖励可以晚到，状态不能说两套话

为什么要单独治理

一局 12 分钟的合作战斗结束后，服务端已经判定胜利并发放奖励，但客户端在结算动画期间切到弱网。玩家看到胜利镜头，点击继续却卡住；背包里奖励没出现，邮件里也没有，重新登录后奖励又突然到账。技术上看只是结算请求超时，玩家感受到的是“奖励到底有没有给”。赛后结算比普通请求更敏感，因为玩家刚完成高投入行为，任何不确定都会被放大。

这篇不是普通断线重连，也不是奖励呈现流水线，而是专门处理赛后结算阶段的弱网补偿、幂等查询和客户端展示口径。 真正要解决的是状态边界。Godot 项目到了中后期，问题很少只停留在一个脚本里：输入会牵动 UI，网络会牵动资源，资源又会牵动画面和存档。把这类问题拆成系统，不是为了显得架构复杂，而是为了让每一次状态变化都能被解释、被复现、被回滚。

我更建议把它当成客户端可靠性工程来做。第一版不需要覆盖所有平台和所有边界，但必须有统一入口、可观察状态、明确的失败原因和 QA 能复现的样本。如果这些东西缺失，后面新增几个 if 分支只会把问题藏得更深。

先划清边界

建议从这些模块开始：MatchResultSnapshot, SettlementRequestQueue, RewardFinalityProbe, IdempotencyKeyStore, SettlementPresenter, CompensationDebugTrace。模块名不重要，重要的是职责不能混在一起。采样模块只采样，策略模块只给决策，执行模块只做状态切换，表现层只展示归一化后的结果。页面脚本不应该直接读取平台状态、修改资源、发起请求、调整渲染和写入存档。

这类系统最容易犯的错误是“临时处理一下”。比如某个按钮发现状态不对，就自己重试；某个资源加载失败，就自己换 fallback；某个输入事件迟到，就自己吞掉。短期看问题消失了，长期看排查路径被切碎了。更稳的做法是让所有特殊情况都回到同一个服务，至少在日志和调试面板里能看到它们来自哪里。

核心规则可以先写成几条：

• 每次外部状态变化都要生成 generation，旧回调不能覆盖新状态。
• 每个失败都要有 reason，不使用单纯的 failed 或 ok。
• 每个自动恢复动作都要能取消，不能在玩家离开场景后继续写状态。
• 每个高风险动作都要有 QA 场景，而不是只靠开发机手动点一次。

架构图

flowchart TD
    A["本地锁定比赛结果"] --> B["生成结算幂等键"]
    B --> C["提交或恢复结算请求"]
    C --> D["查询服务端最终状态"]
    D --> E["展示奖励或延迟到账"]
    E --> F["写入补偿追踪"]
    C --> G["Debug Trace"]
    F --> H["QA Scenario"]

这张图的价值不是画得完整，而是给程序、策划、QA 和运营一个共同语言。线上问题发生时，大家可以沿着图问：卡在采样、策略、执行、表现，还是恢复？如果图外还有隐式通路，比如页面直接改状态、回调直接写 UI，就要把它收回来。

数据模型

关键字段建议至少包含：match_id, settlement_id, idempotency_key, local_result_state, server_finality, reward_visibility, retry_after_ms, compensation_reason。字段不是为了堆结构，而是为了让问题能被解释。很多线上事故不是因为客户端完全没处理，而是处理过之后没人知道为什么会走到这个分支。

命名要尽量具体。enabled、valid、ready 这些字段只能说明当前分支想通过，不能说明由谁决定、什么时候决定、还能不能恢复。更好的字段会带 owner、source、reason、generation、revision、scope 和 timestamp。它们让日志能回答“谁在什么时候因为哪个原因把状态改成了什么”。

在 Godot 里，稳定配置适合放进 Resource，跨场景状态适合放在 autoload service，临时 UI 状态则留在页面节点。不要反过来：用页面节点保存跨场景状态，或者用全局单例保存每个控件的临时视觉状态。生命周期一乱，重连、切场景、热更新和前后台恢复都会变得不可预测。

Godot 接入点

Godot 的优势是场景和信号组织灵活，风险也是太灵活。建议把统一服务做成 autoload，例如 ClientReliabilityService 的一个子服务，再让具体场景通过信号订阅结果。平台层、网络层或资源层的原始事件先进入服务，服务归一化之后再通知 UI 和玩法节点。

下面的代码只展示关键习惯：先确认 generation，再做策略判断，最后由表现层订阅结果。

func submit_settlement(match_id: String) -> void:
    var key := idempotency_store.get_or_create(match_id)
    presenter.lock_result_screen(match_id)
    var result := await settlement_api.submit(match_id, key)
    if result.timeout:
        queue.mark_pending(match_id, key, "network_timeout")
        presenter.show_pending_reward()
        return
    await finality_probe.apply_result(result)

真实项目里还要补错误码、trace_id、调试开关和单元测试夹具。trace_id 用来把一次玩家操作串起来；错误码让 UI、日志和客服口径一致；调试开关让开发包看得清，正式包不泄露内部细节。单元测试则至少覆盖状态机分支，避免后续改动把恢复流程打断。

和其他系统的协作

这个主题通常会同时影响三个相邻系统。第一是 UI：它要知道当前是恢复中、暂停、失败还是可继续，而不是只显示一个通用转圈。第二是资源或网络：它们要能暂停和恢复，不能在状态不稳定时抢跑。第三是 QA 和可观测性：它们要能制造边界场景，而不是等玩家在线上遇到。

协作时要避免互相调用成网状。更推荐事件和状态订阅：服务发布状态，UI 订阅；服务请求资源层执行动作，资源层返回结构化结果；QA 面板从服务读取当前快照。这样每条链路都能画出来，也能在日志里串起来。

另一个细节是玩家可感知行为。系统内部自动恢复不代表 UI 可以沉默。超过 500ms 的恢复最好有轻量状态，超过 3 秒的恢复要有明确文案，超过可接受阈值的失败要给玩家下一步选择。很多客户端问题不是不能恢复，而是恢复期间玩家不知道发生了什么。

QA 场景

这类功能必须做真机场景，而不是只在编辑器里点按钮。建议至少覆盖：

• 结算动画中断网，10 秒后恢复网络
• 结算提交超时后重启客户端
• 服务端已发奖但客户端首次查询失败
• 玩家连续点击继续和返回大厅
• 多人房间中有人结算成功有人仍 pending

每个场景都检查四件事。第一，状态是否进入预期分支。第二，旧 generation 的回调是否被丢弃。第三，UI 文案是否解释了真实原因。第四，恢复后是否会把临时状态写成永久状态。最后一条尤其重要，很多 bug 当场看不出来，几分钟后自动保存或下一次切场景才暴露。

QA 面板可以显示当前 generation、状态机节点、最后一次 reason、最近十条状态变化和当前 owner。这个面板不需要做得漂亮，但要能截图。只要 QA 能把截图和 trace_id 发给程序，定位效率就会明显提高。

线上指标

建议记录这些指标：settlement_pending_rate, reward_finality_probe_ms, duplicate_submit_blocked, pending_to_final_success_rate, manual_compensation_count。指标不要只服务漂亮报表，要能回答具体问题：恢复是否成功，失败是否集中在某类设备，重试有没有浪费玩家时间，fallback 是否真的被用上，玩家是否因为状态不确定而退出。

采样要克制。不要上传隐私内容，不要上传完整本地路径，也不要把每一帧状态都打上来。通常记录状态变化、错误码、设备类别、资源版本、场景 id 和耗时就够了。如果需要更细日志，只在灰度包或玩家授权的诊断模式里打开。

落地步骤

第一阶段只做观测。把现有散落的判断集中到调试面板里，不急着改变行为。你会很快发现哪些状态没有 owner，哪些失败没有 reason，哪些模块在绕过统一入口。

第二阶段接入最容易出事故的一个场景，先跑通状态机、UI 文案和 QA 用例。不要一开始全项目替换，否则问题面太大，团队很难判断是新架构的问题还是旧逻辑没有迁干净。

第三阶段加入恢复和回滚。恢复动作必须可取消，回滚路径必须保留旧状态。玩家离开场景、切账号、切语言、切网络、切前后台时，旧恢复任务都要重新确认 generation。

第四阶段再做自动化和灰度。把 QA 场景沉淀成调试命令或测试夹具，在线上灰度中观察指标。指标稳定后，再把更多页面和玩法接入。

常见误区

一个误区是把所有问题都归成“平台差异”。平台差异当然存在，但客户端仍然需要统一模型。没有模型时，每个平台都会长出自己的特殊分支，最后谁也说不清哪个分支是当前真相。

第二个误区是把恢复做得太积极。自动重试、自动重载、自动切换 fallback 都有成本。它们可能掩盖真正的错误，也可能在错误条件仍然存在时反复执行。恢复策略要有次数、间隔和退出条件。

第三个误区是只关注成功路径。越是边界系统，越要把失败路径写清楚。失败时能保留玩家状态、给出可理解文案、留下诊断证据，往往比成功时快几十毫秒更重要。

结算补偿复盘演练

推荐准备一个可控测试服务端，能分别模拟提交超时、提交成功但响应丢失、奖励已发但查询延迟、奖励发放失败等待补偿。客户端在这四种情况下的表现不能一样。提交成功但响应丢失时，应通过 finality probe 查到最终状态；奖励发放失败等待补偿时，应显示“奖励确认中”，并保留 match_id 和 settlement_id。

上线检查还要覆盖跨端登录。玩家在 A 设备结算 pending，又在 B 设备登录查看背包，两个设备看到的奖励状态应该来自服务端最终状态，而不是各自猜测。客户端本地可以缓存 pending，但不能把 pending 当成最终发奖。客服后台如果能按 settlement_id 查到状态，玩家反馈时就不用让他重复打一局来证明。

交付标准与 review 关注点

PR review 要特别警惕重复发奖和错误覆盖。任何结算请求都必须带 idempotency_key，任何超时都不能直接改成失败发奖，任何本地 pending 都不能覆盖服务端 finality。交付标准是：玩家可以离开结算页，但 match_id 和 settlement_id 仍能继续追踪；奖励晚到时有明确文案；重新登录后看到的状态和服务端一致。

团队分工和长期维护

这个系统上线后，维护责任要写清楚。客户端负责状态机、UI 反馈、日志和本地恢复；服务端或平台层负责给出稳定错误码、版本信息和最终状态；QA 负责保留可复现样本；制作团队负责确认体验降级是否可接受。不要把所有问题都丢给客户端临时兜底，也不要让客户端在没有服务端语义的情况下猜测最终结果。

每次版本迭代都应该检查三类变更。第一，是否新增了状态来源，比如新平台 SDK、新资源包、新输入设备或新玩法入口。第二，是否新增了自动恢复动作，比如重试、重载、fallback 或重建会话。第三，是否新增了玩家可见文案。只要其中一项变化，就要同步更新调试字段、QA 用例和线上指标。

长期维护还要避免“隐性成功”。系统自动恢复后，不能什么都不记录。恢复成功同样需要 trace，因为线上偶发问题往往来自连续成功后的某一次失败。只记录失败会让团队看不到恢复频率，也就无法判断系统是否正在频繁擦屁股。稳定的客户端不是永远不遇到边界，而是遇到边界后能用一致方式处理，并留下足够证据。

小结

Godot 赛后结算弱网补偿：奖励可以晚到，状态不能说两套话 这个问题看起来很具体，但它代表了 Godot 客户端中后期最常见的工程挑战：系统之间互相牵动，而玩家只关心结果是否可信。把它拆成可观察、可恢复、可验证的系统，才能避免后期靠临时分支续命。

建议从一个真实事故场景开始落地。先让状态能被看见，再让恢复能被控制，最后再追求自动化。只要边界清楚，后续扩平台、扩玩法、扩资源包时，团队就不用每次重新解释同一个问题。