feat(lucky-dice): 提交 demo 前核心流程

FishDice/Docs/Decisions/adr-004-inject-random-source-for-lucky-dice.md

@@ -0,0 +1,113 @@
+# 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)