3.6 KiB
3.6 KiB
ADR-002: Roll 结果先转组合事实，再匹配规则
Status
Accepted
Date
2026-06-22
Context
Lucky Dice 第一版普通 Roll 默认使用 2 颗骰子，但 PRD 明确要求骰子数量必须来自配置，并保留后续扩展到 3 颗、4 颗或特殊关卡自定义骰子数量的能力。
普通 Roll 的规则也不只包含精确组合。首批规则需要覆盖：
- 双 Clover 触发 Lucky Dice。
- 单 Clover 加数字发放普通奖励并提供 bonus。
- 纯数字结果发放普通奖励。
后续还需要支持对子、N 连、指定面数量、点数和区间、骰子数量约束等统计型规则。
如果规则匹配直接读取固定位置，例如左骰和右骰，就会把第一版默认值 2 固化到系统里。后续扩展 3 骰时，规则、测试和日志都要大范围修改。
Decision
普通 Roll 结果必须先转换成结构化 ComboFacts，再进入规则匹配。
ComboFacts 至少包含：
DiceSetTypeDiceCount- 原始
Faces FaceCountsNumberValuesNumberSumCloverCountHasCloverNormalizedKeyOrderedKey
普通规则默认使用无序事实。2 + clover 与 clover + 2 必须归一为同一个 NormalizedKey。只有规则明确声明需要顺序语义时，才允许读取 OrderedKey。
matcher 必须基于 ComboFacts 中的统计信息判断，不能依赖固定的左骰、右骰字段。
Alternatives Considered
在规则里直接读取骰子数组位置
示例：faces[0] == clover && faces[1] == clover。
优点：
- 第一版双骰场景写起来最快。
- 不需要单独的事实构建层。
缺点：
- 默认写死 2 骰。
- 顺序和无序语义容易混乱。
- 后续 3 骰、4 骰会导致规则分支爆炸。
- 测试会绑定实现细节，而不是外部行为。
结论：拒绝。它与可配置骰子数量的核心要求冲突。
只生成字符串组合 key
示例：直接生成 2_clover、clover_clover，规则只匹配 key。
优点：
- 对精确组合匹配足够简单。
- 配置和日志易读。
缺点：
- 难以表达统计型规则，例如至少 2 个 Clover、三连、点数和区间。
- matcher 会被迫解析字符串，或者需要维护大量派生 key。
- 原始骰子和统计信息缺失，不利于调试。
结论：拒绝作为唯一事实来源。NormalizedKey 可以作为 ComboFacts 的一个字段，但不能替代完整事实。
由每个 matcher 自己计算统计信息
优点：
- 不需要统一事实模型。
- matcher 内部可以自由处理自己的需求。
缺点：
- 多个 matcher 重复遍历和统计。
- 不同 matcher 对 key、顺序、数字值的理解可能不一致。
- 日志难以记录统一的匹配输入。
结论：拒绝。统一事实模型更利于一致性和测试。
Consequences
正向影响：
- 后续扩展骰子数量时，核心规则仍基于统计事实工作。
- 规则匹配器可以用少量通用 matcher 覆盖多种组合语义。
- 日志能记录原始结果、统计结果、无序 key 和有序 key。
- 测试可以直接验证外部行为和事实结构。
代价和约束：
- 第一版需要实现并测试
ComboFactBuilder。 ComboFacts字段需要保持稳定，不能随意为某个规则塞临时字段。- Lucky Dice 特殊结果不能进入普通
ComboFactBuilder。