shandong/Fishdice

Fork 0

Files

$JSD\13999$ JSD\13999 855659bf78 feat(lucky-dice): 提交 demo 前核心流程

2026-06-23 14:13:08 +08:00

3.3 KiB

Raw Blame History

ADR-004: Lucky Dice 权重随机使用可注入随机源

Status

Accepted

Date

2026-06-22

Context

Lucky Dice 需要在候选结果池筛选后按权重随机选择一个结果。第一版至少需要支持：

rocket 进入 slap_down_normal。
thief 进入 treasure_heist_normal。
候选结果可按启用状态、玩家进度、触发来源、冷却状态和新手期规则筛选。
候选池为空时有可观测兜底。

测试策略要求固定随机源下的权重随机结果可预测。PRD 还要求每次 Roll 都能通过同一个 RollSessionId 串起普通 Roll、规则匹配、Lucky Dice 结果和目标玩法启动，方便排查和回放。

如果 Lucky Dice 流程直接调用 Unity 或系统随机，会让链路测试不稳定，也难以复盘线上问题。

Decision

Lucky Dice 权重随机必须通过可注入随机源执行。

建议使用等价于以下概念的接口：

public interface IRandomSource
{
    int Range(int minInclusive, int maxExclusive);
    float Value01();
}

WeightedPicker 接收筛选后的候选列表、上下文和随机源。它需要记录：

候选列表快照。
每个候选的有效权重。
随机值。
最终选中的 ResultKey。

测试环境可以注入固定序列随机源。运行时环境可以注入 Unity 随机适配器或项目统一随机服务。

Alternatives Considered

直接使用 UnityEngine.Random

优点：

Unity 项目中最容易使用。
不需要额外接口。

缺点：

测试难以稳定复现。
多个系统共享全局随机状态，结果容易受调用顺序影响。
回放和问题定位难度高。

结论：拒绝在核心逻辑中直接使用。可以通过适配器在运行时接入 Unity 随机。

直接使用 System.Random

优点：

可指定 seed。
不依赖 Unity API，适合 EditMode 测试。

缺点：

如果在核心服务内部自行 new，仍然无法由测试控制。
seed 生命周期和 RollSessionId 的关系不透明。
后续如果项目已有统一随机服务，需要再改接口。

结论：不直接在核心流程中创建。可以作为 IRandomSource 的一个实现。

配置固定结果，不做随机

优点：

第一版实现和测试最简单。
结果完全可控。

缺点：

不满足 Lucky Dice 候选结果支持权重的需求。
后续接入概率策略时需要重构核心流程。
无法提前验证候选筛选和权重随机之间的边界。

结论：拒绝。第一版可以配置极简权重，但流程必须保留权重随机。

Consequences

正向影响：

链路测试可以稳定断言 Lucky Dice 最终结果。
回放和问题排查可以复用相同随机输入。
WeightedPicker 不依赖 Unity API，更容易做纯 C# 测试。
后续接入活动概率策略时，随机入口清晰。

代价和约束：

需要实现至少两个随机源：运行时随机源和测试固定随机源。
需要记录随机值和候选权重，否则可注入随机源的排查价值会下降。
随机源生命周期需要统一管理，避免同一 Roll 中不同阶段使用不同来源。

3.3 KiB Raw Blame History Unescape Escape