# 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` 至少包含：

- `DiceSetType`
- `DiceCount`
- 原始 `Faces`
- `FaceCounts`
- `NumberValues`
- `NumberSum`
- `CloverCount`
- `HasClover`
- `NormalizedKey`
- `OrderedKey`

普通规则默认使用无序事实。`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`。

## Related Documents

- [Lucky Dice 核心流程需求](../Requirements/lucky-dice-core-flow-requirements.md)
- [Lucky Dice 核心流程规格](../Specs/lucky-dice-core-flow-spec.md)
- [ADR-001](adr-001-separate-normal-and-lucky-dice-sets.md)