# Lucky Dice 核心流程规格

## 文档信息

- 来源需求：[lucky-dice-core-flow-requirements.md](../Requirements/lucky-dice-core-flow-requirements.md)
- 适用范围：FishDice 第一版普通骰子主循环与 Lucky Dice 特殊分支
- 文档目标：把玩法需求拆成可实现、可测试、可扩展的系统规格

## 设计目标

Lucky Dice 核心流程需要支持两层玩法：

1. 普通骰子主循环：玩家按骰子集合配置 Roll 普通骰子，根据组合事实匹配规则并执行奖励或特殊触发行为。
2. Lucky Dice 特殊流程：当普通骰子出现双四叶草或配置声明的触发条件时，进入独立的特殊结果池，经过筛选、权重随机和模式解析后启动目标玩法。

第一版只做核心闭环，不实现复杂动画、远端热更、完整短玩法内容和复杂运营权重策略。系统边界必须保留扩展点，避免后续新增组合或特殊结果时不断堆硬编码分支。

第一版默认值：

- 普通骰子数量默认 2 颗，但必须来自 DiceSet 配置。
- Lucky Dice 结果槽数量默认 3 格，但必须来自 Lucky Dice 结果或目标玩法配置。
- 规则系统、组合事实和展示流程不得把 2 颗骰子或 3 格结果槽写死为不可扩展假设。

## 总体架构

核心模块按职责拆分为以下几层：

```text
Roll 输入层
→ 骰子结果生成层
→ 组合事实提取层
→ 组合规则匹配层
→ 行为执行层
→ Lucky Dice 流程层
→ 目标玩法模式解析层
→ 目标玩法启动层
```

各层只依赖前一层产出的结构化数据，不直接读取 UI 状态或动画状态。

### 模块职责

| 模块 | 职责 | 不负责 |
| --- | --- | --- |
| DiceSetConfigProvider | 提供骰子集合、骰子数量、结果槽数量等配置 | 执行 Roll 或业务行为 |
| DiceRollService | 按骰子集合配置生成普通骰子或 Lucky Dice 结果 | 决定奖励、玩法入口 |
| ComboFactBuilder | 把普通 Roll 结果转换为结构化组合事实 | 执行业务行为 |
| ComboRuleMatcher | 按优先级匹配组合规则 | 直接发奖或进玩法 |
| RollActionDispatcher | 按行为类型分发到通用执行器 | 按组合 key 维护巨大方法 map |
| LuckyDiceFlowService | 构建候选池、筛选、随机、生成可展示结果槽 | 直接决定目标模式细节 |
| TargetModeResolver | 把 ResultKey/TargetKey 解析为 ModeKey | 执行目标玩法内容 |
| TargetModeLauncher | 统一启动目标玩法 | 参与 Lucky Dice 随机 |
| RollTraceLogger | 记录一次 Roll 的关键决策链路 | 影响玩法决策 |

## 核心流程

### 普通 Roll 流程

```text
PlayerRollRequest
→ DiceSetConfigProvider.GetNormalDiceSet(request)
→ DiceRollService.Roll(NormalDiceSet)
→ ComboFactBuilder.Build(result)
→ ComboRuleMatcher.Match(facts, ruleSet)
→ RollActionDispatcher.Execute(matchedRule.Actions)
    → grant_reward：发放普通奖励并结束
    → grant_reward + add_multiplier：发奖并应用 Clover bonus
    → trigger_lucky_dice：进入 LuckyDiceFlowService
```

普通 Roll 第一版默认两颗骰子，骰子面为：

```text
2 / 3 / 4 / 5 / 6 / Clover
```

骰子数量必须从 `DiceSetConfig.DiceCount` 读取。第一版配置值可以是 2，但 `DiceRollService`、`ComboFactBuilder` 和 matcher 都必须按 `Faces.Count` 或 `DiceCount` 处理，不读取固定的左骰、右骰两个位置。

### Lucky Dice 流程

```text
TriggerLuckyDiceAction
→ LuckyDiceFlowService.BuildCandidatePool(context)
→ LuckyDiceFlowService.ApplyFilters(pool, context)
→ LuckyDiceFlowService.ResolveEmptyPoolFallback(filteredPool, context)
→ LuckyDiceFlowService.WeightedPick(filteredPool, context)
→ LuckyDiceFlowService.BuildResultSlots(result, slotConfig)
→ LuckyDicePresentation.ShowResultSlots(resultSlots)
→ TargetModeResolver.Resolve(result, context)
→ TargetModeLauncher.Launch(targetEntry)
→ TargetModeCompletion 回到主循环
```

第一版 Lucky Dice 默认展示 3 格相同特殊图标，不要求实现托盘、飞入、粒子爆发、白烟转场等表现。结果槽数量必须从 Lucky Dice 结果或目标玩法配置读取，后续可扩展为 2 格、4 格或按玩法定义不同槽数。

## 数据模型

### DiceSetConfig

骰子集合配置定义一次 Roll 使用哪套骰子、投几颗骰子，以及该集合是否拥有展示槽概念。

```csharp
public sealed class DiceSetConfig
{
    public string DiceSetId { get; init; }
    public DiceSetType SetType { get; init; }
    public int DiceCount { get; init; }
    public IReadOnlyList<DiceFaceDefinition> Faces { get; init; }
    public int? DefaultResultSlotCount { get; init; }
}
```

约束：

- `DiceCount` 必须大于 0。
- 第一版普通骰子 `DiceCount = 2`，但核心逻辑不得依赖该常量。
- Lucky Dice 如果不真实 Roll 多颗特殊骰，可以将 `DiceCount` 理解为结果选择次数；第一版只随机一次，再由展示槽配置生成多个相同槽。
- `DefaultResultSlotCount` 用于展示层默认槽数，第一版 Lucky Dice 为 3。

### DiceFace

普通骰子面与 Lucky Dice 特殊结果必须区分集合类型，不能混用同一个裸字符串列表。

```csharp
public enum DiceSetType
{
    Normal,
    Lucky
}

public readonly struct DiceFace
{
    public DiceSetType SetType { get; }
    public string Key { get; }
    public int? NumberValue { get; }
}
```

约束：

- 普通数字面使用 `Key = "2" ... "6"`，`NumberValue` 为对应数字。
- 普通四叶草使用 `Key = "clover"`，`NumberValue = null`。
- Lucky Dice 特殊结果使用 `DiceSetType.Lucky`，例如 `rocket`、`thief`。
- 业务代码不得到处裸写这些 key，必须集中在定义表或常量入口。

### DiceRollResult

```csharp
public sealed class DiceRollResult
{
    public string RollSessionId { get; init; }
    public string DiceSetId { get; init; }
    public DiceSetType SetType { get; init; }
    public int DiceCount { get; init; }
    public IReadOnlyList<DiceFace> Faces { get; init; }
    public int Multiplier { get; init; }
    public string TriggerSource { get; init; }
}
```

约束：

- `DiceCount` 必须等于本次配置要求的投掷数量。
- `Faces.Count` 必须等于本次实际产出的骰子面数量。
- 普通 Roll 中 `DiceCount` 和 `Faces.Count` 不一致时，应拒绝进入规则匹配并记录错误。

### ComboFacts

`ComboFacts` 是普通组合匹配的唯一输入。

```csharp
public sealed class ComboFacts
{
    public DiceSetType DiceSetType { get; init; }
    public int DiceCount { get; init; }
    public IReadOnlyList<DiceFace> Faces { get; init; }
    public IReadOnlyDictionary<string, int> FaceCounts { get; init; }
    public int NumberSum { get; init; }
    public IReadOnlyList<int> NumberValues { get; init; }
    public int CloverCount { get; init; }
    public bool HasClover { get; init; }
    public string NormalizedKey { get; init; }
    public string OrderedKey { get; init; }
}
```

归一化规则：

- 默认按无序组合处理。
- `2 + clover` 与 `clover + 2` 都归一为 `2_clover`。
- `clover + clover` 归一为 `clover_clover`。
- N 颗骰子的 `NormalizedKey` 由所有面 key 排序后拼接，例如 `2_2_clover`、`3_3_3`。
- 后续若需要有序语义，由规则显式声明使用 `OrderedKey`。

约束：

- `ComboFacts` 不能假设只有 2 颗骰子。
- matcher 必须基于 `DiceCount`、`Faces`、`FaceCounts`、`NumberValues` 等统计信息判断。
- 只有有序规则才能读取 `OrderedKey`，普通规则默认使用无序事实。

### ComboRule

```csharp
public sealed class ComboRule
{
    public string RuleId { get; init; }
    public int Priority { get; init; }
    public ComboMatcherSpec Matcher { get; init; }
    public IReadOnlyList<RollActionSpec> Actions { get; init; }
    public bool StopAfterMatched { get; init; } = true;
}
```

第一版规则：

| Priority | Matcher | Actions |
| --- | --- | --- |
| 100 | ExactCombo `clover_clover` | `trigger_lucky_dice` |
| 50 | ContainsFace `clover` count 1 | `grant_reward`, `add_multiplier` |
| 10 | AllNumbers | `grant_reward` |

匹配策略：

- 按 `Priority` 从高到低匹配。
- 同优先级按配置顺序匹配。
- 第一版默认命中第一条 `StopAfterMatched = true` 的规则后停止。
- 未命中任何规则时走可观测兜底，默认发普通奖励或返回明确错误，由产品配置决定。

### ComboMatcherSpec

```csharp
public sealed class ComboMatcherSpec
{
    public string MatcherType { get; init; }
    public string ComboKey { get; init; }
    public string FaceKey { get; init; }
    public int? RequiredCount { get; init; }
    public int? MinCount { get; init; }
    public int? MaxCount { get; init; }
    public int? DiceCount { get; init; }
    public int? OfAKindCount { get; init; }
    public int? MinSum { get; init; }
    public int? MaxSum { get; init; }
    public bool UseOrderedKey { get; init; }
}
```

首批 matcher：

- `ExactCombo`
- `AllNumbers`
- `ContainsFace`
- `FaceCount`
- `FaceCountRange`
- `DiceCount`
- `NumberPair`
- `NumberOfAKind`
- `NumberSumRange`

新增组合语义优先新增规则配置；只有出现新的通用匹配能力时才新增 matcher。

N 颗骰子扩展示例：

| Matcher | 例子 | 含义 |
| --- | --- | --- |
| `FaceCountRange` | `faceKey = clover`, `minCount = 2` | 至少 2 个 Clover |
| `DiceCount` | `diceCount = 3` | 只匹配 3 骰规则 |
| `NumberOfAKind` | `ofAKindCount = 3` | 任意数字三连 |
| `NumberSumRange` | `minSum = 18`, `maxSum = 24` | 点数和落在 18 到 24 |

### RollActionSpec

```csharp
public sealed class RollActionSpec
{
    public string ActionType { get; init; }
    public IReadOnlyDictionary<string, string> Params { get; init; }
}
```

首批 action：

- `grant_reward`
- `add_multiplier`
- `trigger_lucky_dice`
- `enter_mode`
- `show_popup`

执行层只按 `ActionType` 找执行器，不按组合 key 找方法。

### LuckyDiceCandidate

```csharp
public sealed class LuckyDiceCandidate
{
    public string ResultKey { get; init; }
    public string TargetKey { get; init; }
    public int? ResultSlotCount { get; init; }
    public int Weight { get; init; }
    public bool Enabled { get; init; }
    public int MinLevel { get; init; }
    public IReadOnlySet<string> SourceFilter { get; init; }
    public CooldownRule CooldownRule { get; init; }
    public bool IsDefault { get; init; }
}
```

第一版候选配置：

| ResultKey | TargetKey | ResultSlotCount | Weight | Enabled | Mode 默认结果 |
| --- | --- | --- | --- | --- | --- |
| `rocket` | `slap_down` | 3 | 1 | true | `slap_down_normal` |
| `thief` | `treasure_heist` | 3 | 1 | true | `treasure_heist_normal` |

`ResultSlotCount` 允许为空。为空时使用 Lucky Dice 集合配置或目标玩法配置中的默认槽数。

### LuckyDiceResultSlots

Lucky Dice 随机只选中一个特殊结果；展示层按槽配置生成实际槽位。

```csharp
public sealed class LuckyDiceResultSlots
{
    public string ResultKey { get; init; }
    public string TargetKey { get; init; }
    public int SlotCount { get; init; }
    public IReadOnlyList<string> SlotResultKeys { get; init; }
}
```

第一版要求：

- `SlotCount` 默认 3。
- `SlotResultKeys` 第一版全部填入同一个 `ResultKey`。
- 后续如某玩法需要不同槽位结果，可通过配置扩展 `SlotResultKeys` 的生成策略。

### LuckyDiceContext

```csharp
public sealed class LuckyDiceContext
{
    public string RollSessionId { get; init; }
    public string TriggerSource { get; init; }
    public int NormalDiceCount { get; init; }
    public int LuckyResultSlotCount { get; init; }
    public int PlayerLevel { get; init; }
    public int Multiplier { get; init; }
    public bool IsTutorial { get; init; }
    public IReadOnlyDictionary<string, object> RuntimeTags { get; init; }
}
```

### TargetModeEntry

```csharp
public sealed class TargetModeEntry
{
    public string TargetKey { get; init; }
    public string ModeKey { get; init; }
    public string ResultKey { get; init; }
    public int Multiplier { get; init; }
    public string TriggerSource { get; init; }
    public string RollSessionId { get; init; }
}
```

## 接口边界

### 组合事实构建

```csharp
public interface IComboFactBuilder
{
    ComboFacts Build(DiceRollResult result);
}
```

要求：

- 只接受普通骰子结果构建普通组合事实。
- 如果传入 Lucky Dice 结果，应返回错误或拒绝处理，避免两套骰子语义混用。
- 输出必须保留 DiceCount、原始 Faces、FaceCounts、NumberValues、NormalizedKey、OrderedKey。
- 不允许只读取固定两个骰子位置；必须遍历 `Faces`。

### 组合规则匹配

```csharp
public interface IComboRuleMatcher
{
    ComboRuleMatchResult Match(ComboFacts facts, IReadOnlyList<ComboRule> rules);
}
```

要求：

- matcher 由 `MatcherType` 注册，不由组合 key 注册。
- 匹配结果需要包含命中的 `RuleId`、`Priority`、`MatcherType` 和关键输入 facts，供日志追踪。

### 行为执行

```csharp
public interface IRollActionExecutor
{
    string ActionType { get; }
    RollActionResult Execute(RollActionContext context, RollActionSpec action);
}
```

要求：

- `RollActionDispatcher` 只维护 `ActionType -> IRollActionExecutor` 注册表。
- 不允许维护 `clover_clover -> SomeMethod` 这类随组合数量增长的 map。
- 多个 action 按规则配置顺序执行。
- action 失败时需要返回结构化失败结果，并进入统一日志。

### Lucky Dice 筛选

```csharp
public interface ILuckyDiceCandidateFilter
{
    string FilterType { get; }
    IReadOnlyList<LuckyDiceCandidate> Apply(
        IReadOnlyList<LuckyDiceCandidate> candidates,
        LuckyDiceContext context);
}
```

首批 filter：

- `EnabledFilter`
- `ProgressFilter`
- `SourceFilter`
- `CooldownFilter`
- `TutorialFilter`

筛选器按固定顺序执行，顺序建议为：

```text
Enabled → Progress → Source → Cooldown → Tutorial
```

### 权重随机

```csharp
public interface IWeightedPicker
{
    LuckyDiceCandidate Pick(
        IReadOnlyList<LuckyDiceCandidate> candidates,
        LuckyDiceContext context,
        IRandomSource random);
}
```

要求：

- 权重小于等于 0 的候选不参与普通随机。
- 随机源可注入，便于测试和回放。
- 选中结果必须记录候选池快照、权重、随机值和最终 ResultKey。

### Lucky Dice 结果槽构建

```csharp
public interface ILuckyDiceResultSlotBuilder
{
    LuckyDiceResultSlots BuildSlots(
        LuckyDiceCandidate selected,
        LuckyDiceContext context,
        DiceSetConfig luckyDiceSetConfig);
}
```

要求：

- 槽数优先级：候选结果配置 `ResultSlotCount` → 目标玩法配置 → Lucky Dice 集合配置 `DefaultResultSlotCount`。
- 第一版每个槽都展示同一个 `ResultKey`。
- 槽数小于等于 0 时返回结构化错误并进入 Lucky Dice 兜底。

### 模式解析

```csharp
public interface ITargetModeResolver
{
    TargetModeEntry Resolve(LuckyDiceCandidate selected, LuckyDiceContext context);
}
```

解析优先级：

1. `TutorialModeRule`
2. `BonusModeRule`
3. `DefaultModeRule`

第一版映射：

| ResultKey | TargetKey | Default ModeKey |
| --- | --- | --- |
| `rocket` | `slap_down` | `slap_down_normal` |
| `thief` | `treasure_heist` | `treasure_heist_normal` |

## 兜底与错误处理

### 普通组合未命中

处理策略：

1. 记录 `RollSessionId`、原始 Faces、NormalizedKey。
2. 使用配置的普通奖励兜底，或返回可见错误给调试面板。
3. 不进入 Lucky Dice。

第一版建议默认发普通奖励兜底，避免玩家流程中断。

### Lucky Dice 候选池为空

处理策略：

1. 尝试使用配置的 default result。
2. 如果 default result 不可用，执行普通奖励兜底。
3. 记录空池原因：初始候选数量、每个 filter 过滤前后数量、最终兜底类型。

### 目标模式解析失败

处理策略：

1. 记录 `ResultKey`、`TargetKey`、上下文标签。
2. 如果存在 TargetKey 默认模式，降级到默认模式。
3. 如果不存在默认模式，返回 Lucky Dice 失败并执行普通奖励兜底。

## 可观测性

每次 Roll 必须拥有同一个 `RollSessionId`，贯穿普通 Roll、规则匹配、Lucky Dice、模式解析和目标玩法启动。

最小日志字段：

```text
RollSessionId
TriggerSource
NormalFaces
NormalDiceCount
ComboNormalizedKey
MatchedRuleId
MatchedRulePriority
ExecutedActions
LuckyDiceInitialCandidates
LuckyDiceFilteredCandidates
LuckyDiceFallbackType
LuckyDiceSelectedResultKey
LuckyDiceSelectedTargetKey
LuckyDiceResultSlotCount
LuckyDiceSlotResultKeys
ResolvedModeKey
FinalOutcome
```

日志目标：

- 复盘一次 Roll 为什么发奖、为什么进 Lucky Dice、为什么进某个玩法。
- 发现配置问题时能看出是规则未命中、候选池为空、权重异常还是模式解析失败。

## 配置示例

第一版可以使用本地静态配置或 ScriptableObject；远端配置热更新不在范围内。

### 骰子集合配置示例

```json
{
  "diceSetId": "normal_main",
  "setType": "Normal",
  "diceCount": 2,
  "faces": ["2", "3", "4", "5", "6", "clover"]
}
```

```json
{
  "diceSetId": "lucky_dice",
  "setType": "Lucky",
  "diceCount": 1,
  "defaultResultSlotCount": 3,
  "faces": ["rocket", "thief", "chest", "bomb", "key"]
}
```

### 普通组合规则示例

```json
[
  {
    "ruleId": "normal_clover_clover_lucky_dice",
    "priority": 100,
    "matcher": {
      "matcherType": "ExactCombo",
      "comboKey": "clover_clover"
    },
    "actions": [
      { "actionType": "trigger_lucky_dice", "params": {} }
    ],
    "stopAfterMatched": true
  },
  {
    "ruleId": "normal_number_clover_bonus",
    "priority": 50,
    "matcher": {
      "matcherType": "ContainsFace",
      "faceKey": "clover",
      "requiredCount": 1
    },
    "actions": [
      { "actionType": "grant_reward", "params": {} },
      { "actionType": "add_multiplier", "params": { "reason": "clover_bonus" } }
    ],
    "stopAfterMatched": true
  },
  {
    "ruleId": "normal_all_numbers_reward",
    "priority": 10,
    "matcher": {
      "matcherType": "AllNumbers"
    },
    "actions": [
      { "actionType": "grant_reward", "params": {} }
    ],
    "stopAfterMatched": true
  }
]
```

后续多骰规则示例：

```json
[
  {
    "ruleId": "normal_at_least_two_clovers_lucky_dice",
    "priority": 100,
    "matcher": {
      "matcherType": "FaceCountRange",
      "faceKey": "clover",
      "minCount": 2
    },
    "actions": [
      { "actionType": "trigger_lucky_dice", "params": {} }
    ],
    "stopAfterMatched": true
  },
  {
    "ruleId": "normal_three_of_a_kind_bonus",
    "priority": 60,
    "matcher": {
      "matcherType": "NumberOfAKind",
      "ofAKindCount": 3
    },
    "actions": [
      { "actionType": "grant_reward", "params": {} },
      { "actionType": "add_multiplier", "params": { "reason": "three_of_a_kind" } }
    ],
    "stopAfterMatched": true
  }
]
```

### Lucky Dice 候选示例

```json
[
  {
    "resultKey": "rocket",
    "targetKey": "slap_down",
    "resultSlotCount": 3,
    "weight": 1,
    "enabled": true,
    "minLevel": 0,
    "sourceFilter": ["normal_roll"],
    "isDefault": true
  },
  {
    "resultKey": "thief",
    "targetKey": "treasure_heist",
    "resultSlotCount": 3,
    "weight": 1,
    "enabled": true,
    "minLevel": 0,
    "sourceFilter": ["normal_roll"],
    "isDefault": false
  }
]
```

## 测试规格

### 组合事实测试

- `2 + 3` 生成 `NumberSum = 5`、`CloverCount = 0`、`NormalizedKey = "2_3"`。
- `2 + clover` 与 `clover + 2` 都生成 `NormalizedKey = "2_clover"`。
- `clover + clover` 生成 `CloverCount = 2`、`NormalizedKey = "clover_clover"`。
- `2 + 2 + clover` 生成 `DiceCount = 3`、`NumberValues = [2, 2]`、`NormalizedKey = "2_2_clover"`。
- Lucky Dice 特殊结果不能被普通 `ComboFactBuilder` 当成普通组合处理。

### 规则匹配测试

- `clover_clover` 命中优先级 100 的 Lucky Dice 规则。
- `2_clover` 命中优先级 50 的 Clover bonus 规则。
- `2_6` 命中优先级 10 的 AllNumbers 规则。
- 当多条规则同时可命中时，高优先级先执行。
- 3 骰配置下，`FaceCountRange clover min 2` 能命中任意至少 2 个 Clover 的组合。
- `NumberOfAKind count 3` 能命中三个相同数字，不依赖具体数字 key。

### 行为执行测试

- `grant_reward` 调用奖励执行器。
- `trigger_lucky_dice` 调用 Lucky Dice 流程入口。
- dispatcher 只按 `ActionType` 分发，不依赖组合 key。
- 未注册的 action 返回结构化错误并记录日志。

### Lucky Dice 测试

- Enabled=false 的候选被过滤。
- 玩家等级不足时候选被 `ProgressFilter` 过滤。
- 候选池为空时使用 default result。
- default result 不可用时走普通奖励兜底并记录日志。
- 权重随机可以通过固定随机源得到可预测结果。
- Lucky Dice 结果槽数量来自候选结果、目标玩法或 DiceSet 默认配置。
- 第一版 `rocket` 生成 3 个 `rocket` 展示槽。
- `rocket` 解析到 `slap_down_normal`。
- `thief` 解析到 `treasure_heist_normal`。

### 链路测试

- 普通 Roll 出 `clover + clover` 后，最终进入 Lucky Dice，而不是发普通奖励。
- Lucky Dice 选中 `rocket` 后，启动 Slap Down 普通模式。
- Lucky Dice 选中 `thief` 后，启动 Treasure Heist 普通模式。
- 同一个 `RollSessionId` 能串起普通结果、命中规则、Lucky Dice 候选、随机结果和最终 ModeKey。
- 普通骰子数量从 2 改为 3 时，组合事实与 matcher 仍按统计结果工作，不出现固定左右骰逻辑。

## 验收映射

| 需求验收点 | 规格落点 |
| --- | --- |
| 普通骰子结果能转换为结构化组合事实 | `ComboFacts`、组合事实测试 |
| 普通骰子数量和 Lucky Dice 结果槽数量来自配置 | `DiceSetConfig`、`LuckyDiceResultSlots`、槽构建测试 |
| 少量通用匹配器命中普通组合 | `ComboMatcherSpec`、规则匹配测试 |
| 双四叶草触发 Lucky Dice | 普通规则优先级 100、链路测试 |
| 执行层不维护大型组合 map | `IRollActionExecutor`、行为执行测试 |
| Lucky Dice 先筛选再权重随机 | Lucky Dice 筛选、权重随机接口 |
| Lucky Dice 结果解析到目标玩法和模式 | `TargetModeResolver`、模式映射 |
| Rocket 进入 Slap Down 普通模式 | 第一版模式映射、Lucky Dice 测试 |
| Thief 进入 Treasure Heist 普通模式 | 第一版模式映射、Lucky Dice 测试 |
| 候选池为空时有可观测兜底 | 兜底与错误处理、日志字段 |
| 日志能追踪一次 Roll 的关键决策 | 可观测性字段、链路测试 |

## 第一版不做

- 复杂动画完整复刻。
- 所有 Lucky Dice 特殊结果类型。
- 复杂运营活动权重策略。
- 完整短玩法内容实现。
- 远端配置热更新。
- 按组合 key 直接绑定业务方法。

## 后续扩展建议

- 当组合规则增多后，把本地配置迁移到 ScriptableObject 或 JSON 配置表。
- 当 Lucky Dice 特殊结果超过第一版范围后，补充结果图标、目标玩法、默认模式和冷却规则的配置校验。
- 当接入埋点时，直接复用 `RollSessionId` 和可观测性字段，避免另起一套追踪链路。
- 当新增有序组合时，只新增规则声明与 matcher 参数，不修改 `ComboFacts` 的原始结果保存方式。
- 当普通骰子扩展到 3 颗或 4 颗时，优先新增统计型规则，不新增固定位置分支。