# 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 权重随机必须通过可注入随机源执行。

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

```csharp
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 中不同阶段使用不同来源。

## Related Documents

- [Lucky Dice 核心流程 PRD](../PRD/lucky-dice-core-flow-prd.md)
- [Lucky Dice 核心流程规格](../Specs/lucky-dice-core-flow-spec.md)
- [ADR-003](adr-003-dispatch-actions-by-action-type.md)