114 lines
3.3 KiB
Markdown
114 lines
3.3 KiB
Markdown
# 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)
|