488 lines
18 KiB
Markdown
488 lines
18 KiB
Markdown
# Lucky Dice 核心流程架构蓝图
|
||
|
||
## 文档信息
|
||
|
||
- 来源 PRD：[lucky-dice-core-flow-prd.md](../PRD/lucky-dice-core-flow-prd.md)
|
||
- 关联需求：[lucky-dice-core-flow-requirements.md](../Requirements/lucky-dice-core-flow-requirements.md)
|
||
- 关联规格：[lucky-dice-core-flow-spec.md](../Specs/lucky-dice-core-flow-spec.md)
|
||
- 适用项目：FishDice Unity 项目
|
||
- Unity 版本：2022.3.62f2c1
|
||
- 生成日期：2026-06-22
|
||
|
||
本文档定义 Lucky Dice 第一版核心闭环的架构蓝图。它不替代需求或接口规格，而是回答后续实现时最容易失控的几个问题：
|
||
|
||
- 普通 Roll、组合规则、Lucky Dice、目标玩法入口之间怎么分层。
|
||
- 哪些模块可以通过配置扩展，哪些模块才需要新增代码。
|
||
- 数据从玩家 Roll 到最终玩法模式如何流动。
|
||
- 追踪、兜底、测试和 Unity 落地目录应如何组织。
|
||
|
||
当前项目尚未落地生产 C# 玩法模块，因此本文档描述的是第一版建议架构，而不是对现有代码的复盘。
|
||
|
||
## 架构定位
|
||
|
||
Lucky Dice 不是普通骰子的二次 Roll，也不是一个独立短玩法本体。它在架构中承担的是“特殊玩法入口选择器”职责：
|
||
|
||
```text
|
||
普通 Roll 负责产出组合事实
|
||
组合规则负责决定业务行为
|
||
Lucky Dice 负责从特殊结果池中选择目标入口
|
||
目标玩法模块负责执行 Slap Down / Treasure Heist 等具体内容
|
||
```
|
||
|
||
第一版架构应优先保证三件事：
|
||
|
||
1. **可扩展**：新增组合、骰子数量、特殊结果、目标玩法模式时优先改配置。
|
||
2. **可测试**：组合事实、规则匹配、筛选、权重随机都能用确定性输入测试。
|
||
3. **可追踪**：一次 Roll 的所有关键决策能用同一个 `RollSessionId` 串起来。
|
||
|
||
## 架构原则
|
||
|
||
### 两套骰子集合隔离
|
||
|
||
普通骰子集合只表达主循环 Roll 的结果，例如 `2 / 3 / 4 / 5 / 6 / clover`。Lucky Dice 特殊结果集合只表达后续玩法入口，例如 `rocket / thief`。
|
||
|
||
两者不能混用同一套裸字符串，也不能让普通组合匹配器直接处理 Lucky Dice 特殊结果。
|
||
|
||
### 规则匹配先于行为执行
|
||
|
||
普通 Roll 结果必须先转换成结构化 `ComboFacts`，再交给规则匹配器。业务行为不应读取“左骰 / 右骰”这类固定位置状态。
|
||
|
||
```text
|
||
DiceRollResult
|
||
→ ComboFacts
|
||
→ ComboRule
|
||
→ RollActionSpec
|
||
→ IRollActionExecutor
|
||
```
|
||
|
||
### 配置增长优先于代码增长
|
||
|
||
组合数量增加时，应增加 `ComboRule` 配置。只有出现新的通用匹配能力时才新增 matcher，只有出现新的通用业务行为时才新增 executor。
|
||
|
||
禁止形成下面这种随组合数量膨胀的结构：
|
||
|
||
```text
|
||
clover_clover -> TriggerLuckyDice()
|
||
2_clover -> GrantCloverReward()
|
||
3_clover -> GrantCloverReward3()
|
||
...
|
||
```
|
||
|
||
### 流程服务不依赖表现层
|
||
|
||
核心流程可以产出展示所需数据，例如 Lucky Dice 标题、倍率、结果槽和目标玩法反馈，但不能依赖 UI 动画完成时序来做核心决策。
|
||
|
||
第一版表现层只消费核心结果，不参与筛选、随机和模式解析。
|
||
|
||
## 总览图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Player["玩家触发 Roll"] --> RollService["DiceRollService"]
|
||
RollService --> FactBuilder["ComboFactBuilder"]
|
||
FactBuilder --> RuleMatcher["ComboRuleMatcher"]
|
||
RuleMatcher --> ActionDispatcher["RollActionDispatcher"]
|
||
|
||
ActionDispatcher --> Reward["RewardExecutor"]
|
||
ActionDispatcher --> Multiplier["MultiplierExecutor"]
|
||
ActionDispatcher --> LuckyTrigger["TriggerLuckyDiceExecutor"]
|
||
|
||
LuckyTrigger --> LuckyFlow["LuckyDiceFlowService"]
|
||
LuckyFlow --> CandidateFilters["CandidateFilters"]
|
||
CandidateFilters --> WeightedPicker["WeightedPicker"]
|
||
WeightedPicker --> SlotBuilder["ResultSlotBuilder"]
|
||
SlotBuilder --> ModeResolver["TargetModeResolver"]
|
||
ModeResolver --> Launcher["TargetModeLauncher"]
|
||
Launcher --> TargetGameplay["Slap Down / Treasure Heist"]
|
||
TargetGameplay --> MainLoop["回到主循环"]
|
||
|
||
RollService -.-> Trace["RollTrace"]
|
||
RuleMatcher -.-> Trace
|
||
ActionDispatcher -.-> Trace
|
||
LuckyFlow -.-> Trace
|
||
ModeResolver -.-> Trace
|
||
```
|
||
|
||
## 分层架构
|
||
|
||
| 层级 | 主要职责 | 允许依赖 | 禁止依赖 |
|
||
| --- | --- | --- | --- |
|
||
| 配置层 | 提供骰子集合、规则、候选结果、目标模式映射 | Unity 资源、本地 JSON、静态配置 | UI 动画状态、运行时随机结果 |
|
||
| Roll 层 | 根据 DiceSet 生成普通骰子结果 | 配置层、随机源 | 规则、奖励、玩法入口 |
|
||
| 组合事实层 | 把普通 Roll 结果转为统计事实 | Roll 层数据 | Lucky Dice 特殊结果、UI |
|
||
| 规则匹配层 | 按 matcher 和优先级命中规则 | 组合事实、规则配置 | 行为执行器、目标玩法 |
|
||
| 行为执行层 | 按 action type 分发通用行为 | 规则结果、上下文服务 | 组合 key 到独立方法映射 |
|
||
| Lucky Dice 层 | 候选池、筛选、权重随机、结果槽 | 候选配置、上下文、随机源 | 普通组合 matcher |
|
||
| 模式解析层 | `ResultKey -> TargetKey -> ModeKey` | Lucky Dice 结果、上下文、模式配置 | 短玩法内部实现 |
|
||
| 表现层 | 展示 Lucky Dice 标题、倍率、结果槽、跳转反馈 | 核心流程产物 | 核心规则决策 |
|
||
| 目标玩法层 | 执行 Slap Down / Treasure Heist 等玩法 | TargetModeEntry | Lucky Dice 随机细节 |
|
||
| 追踪层 | 汇总关键决策链路 | 所有核心层事件 | 改变玩法结果 |
|
||
|
||
依赖方向应从上游输入流向下游结果。追踪层可以被各层写入，但不应反向影响流程决策。
|
||
|
||
## 组件职责
|
||
|
||
### DiceSetConfigProvider
|
||
|
||
负责提供骰子集合配置，包括普通骰子面、普通骰子数量、Lucky Dice 特殊结果面、默认结果槽数量。
|
||
|
||
第一版可以使用 ScriptableObject、JSON 或硬编码本地配置启动，但调用方必须只通过 provider 读取，不把 `2` 颗骰子或 `3` 个结果槽写死到流程逻辑中。
|
||
|
||
### DiceRollService
|
||
|
||
负责按骰子集合配置生成 Roll 结果。普通 Roll 会产出多个普通骰子面；Lucky Dice 第一版不需要真的 Roll 三颗特殊骰，而是由候选选择结果再生成展示槽。
|
||
|
||
该服务只负责“随机出可见骰子面”，不负责奖励、倍率或玩法入口。
|
||
|
||
### ComboFactBuilder
|
||
|
||
负责把普通 Roll 结果转成 `ComboFacts`：
|
||
|
||
- 原始面列表
|
||
- 面数量统计
|
||
- 数字列表
|
||
- 点数和
|
||
- Clover 数量
|
||
- 无序归一化 key
|
||
- 有序 key
|
||
|
||
它必须支持 N 颗骰子。`2 + clover` 与 `clover + 2` 的无序 key 必须一致。
|
||
|
||
### ComboRuleMatcher
|
||
|
||
负责把 `ComboFacts` 与规则配置匹配。matcher 按类型注册，例如 `ExactCombo`、`AllNumbers`、`ContainsFace`、`FaceCountRange`。
|
||
|
||
第一版按优先级从高到低匹配，默认命中高优先级规则后停止继续匹配，除非规则配置声明可以继续匹配。
|
||
|
||
### RollActionDispatcher
|
||
|
||
负责把命中规则中的 `RollActionSpec` 分发给对应 executor。
|
||
|
||
dispatcher 只能维护 `ActionType -> Executor` 注册表，不能维护组合 key 到方法的映射。
|
||
|
||
### LuckyDiceFlowService
|
||
|
||
负责 Lucky Dice 的核心入口选择流程：
|
||
|
||
```text
|
||
构建候选池
|
||
→ 筛选候选池
|
||
→ 处理空池兜底
|
||
→ 权重随机
|
||
→ 生成展示结果槽
|
||
```
|
||
|
||
它不直接启动 Slap Down 或 Treasure Heist，而是把选中结果交给模式解析层。
|
||
|
||
### TargetModeResolver
|
||
|
||
负责把 Lucky Dice 结果解析到具体目标玩法模式。
|
||
|
||
第一版映射：
|
||
|
||
| ResultKey | TargetKey | ModeKey |
|
||
| --- | --- | --- |
|
||
| `rocket` | `slap_down` | `slap_down_normal` |
|
||
| `thief` | `treasure_heist` | `treasure_heist_normal` |
|
||
|
||
后续教程模式、bonus 模式应通过 mode rule 扩展，而不是在 Lucky Dice 随机代码里写分支。
|
||
|
||
### TargetModeLauncher
|
||
|
||
负责统一启动目标玩法。它接收 `TargetModeEntry`，把 Lucky Dice 的结果、倍率、触发来源、`RollSessionId` 传给目标玩法入口。
|
||
|
||
目标玩法结束后，通过明确的 completion 回调或流程事件回到主循环。
|
||
|
||
### RollTrace
|
||
|
||
负责记录一次 Roll 的关键路径。追踪不是埋点管线本身，第一版可以是本地结构化日志或调试面板数据。
|
||
|
||
最小字段应覆盖：
|
||
|
||
- 原始普通骰子结果
|
||
- 组合事实和归一化 key
|
||
- 命中规则和执行行为
|
||
- Lucky Dice 初始候选、过滤过程、兜底类型
|
||
- 权重随机输入和选中结果
|
||
- 解析出的 TargetKey 和 ModeKey
|
||
- 最终结果
|
||
|
||
## 核心数据流
|
||
|
||
### 普通 Roll
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant P as Player
|
||
participant R as DiceRollService
|
||
participant F as ComboFactBuilder
|
||
participant M as ComboRuleMatcher
|
||
participant A as RollActionDispatcher
|
||
participant T as RollTrace
|
||
|
||
P->>R: Roll(normal_main)
|
||
R->>T: record normal faces
|
||
R->>F: DiceRollResult
|
||
F->>T: record ComboFacts
|
||
F->>M: ComboFacts
|
||
M->>T: record matched rule
|
||
M->>A: RollActionSpec list
|
||
A->>T: record executed actions
|
||
```
|
||
|
||
### Lucky Dice
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant A as TriggerLuckyDiceExecutor
|
||
participant L as LuckyDiceFlowService
|
||
participant F as CandidateFilters
|
||
participant W as WeightedPicker
|
||
participant S as ResultSlotBuilder
|
||
participant M as TargetModeResolver
|
||
participant T as RollTrace
|
||
|
||
A->>L: LuckyDiceContext
|
||
L->>T: record initial candidates
|
||
L->>F: apply filters
|
||
F->>T: record filter decisions
|
||
F->>W: filtered candidates
|
||
W->>T: record random value and selected result
|
||
W->>S: selected candidate
|
||
S->>T: record result slots
|
||
S->>M: selected candidate + context
|
||
M->>T: record target mode
|
||
```
|
||
|
||
## 配置架构
|
||
|
||
第一版建议至少拆成四类配置：
|
||
|
||
| 配置 | 示例内容 | 扩展方向 |
|
||
| --- | --- | --- |
|
||
| DiceSetConfig | `normal_main`、`lucky_dice`、骰子面、骰子数量、默认槽数 | 支持关卡自定义骰子数量 |
|
||
| ComboRuleConfig | 规则 id、优先级、matcher、actions | 策划新增组合语义 |
|
||
| LuckyDiceCandidateConfig | result、target、weight、enabled、slot count、default | 扩展特殊结果与概率 |
|
||
| TargetModeConfig | target、default mode、tutorial mode、bonus mode | 扩展玩法模式 |
|
||
|
||
配置读取顺序建议：
|
||
|
||
```text
|
||
本地默认配置
|
||
→ 关卡或活动覆盖配置
|
||
→ 运行时上下文修正
|
||
```
|
||
|
||
远端热更不在第一版范围内，但数据结构应避免与 Unity 场景对象强绑定，给后续迁移到远端配置留出空间。
|
||
|
||
## Unity 落地目录建议
|
||
|
||
如果第一版开始实现 C# 模块，建议按运行时核心、配置、表现、测试分开：
|
||
|
||
```text
|
||
FishDice/Assets/FishDice/
|
||
Runtime/
|
||
LuckyDice/
|
||
Core/
|
||
DiceRollService.cs
|
||
ComboFactBuilder.cs
|
||
ComboRuleMatcher.cs
|
||
RollActionDispatcher.cs
|
||
LuckyDiceFlowService.cs
|
||
TargetModeResolver.cs
|
||
Config/
|
||
DiceSetConfig.cs
|
||
ComboRuleConfig.cs
|
||
LuckyDiceCandidateConfig.cs
|
||
TargetModeConfig.cs
|
||
Actions/
|
||
GrantRewardExecutor.cs
|
||
AddMultiplierExecutor.cs
|
||
TriggerLuckyDiceExecutor.cs
|
||
EnterModeExecutor.cs
|
||
Filters/
|
||
EnabledFilter.cs
|
||
ProgressFilter.cs
|
||
SourceFilter.cs
|
||
CooldownFilter.cs
|
||
TutorialFilter.cs
|
||
Presentation/
|
||
LuckyDicePresenter.cs
|
||
LuckyDiceResultSlotView.cs
|
||
Trace/
|
||
RollTrace.cs
|
||
RollTraceLogger.cs
|
||
Tests/
|
||
EditMode/
|
||
LuckyDice/
|
||
```
|
||
|
||
第一版核心流程建议尽量放在纯 C# 类里，减少对 `MonoBehaviour` 的依赖。表现层再通过 Unity 组件消费核心流程产物。
|
||
|
||
## 错误处理与兜底
|
||
|
||
### 普通组合未命中
|
||
|
||
处理策略：
|
||
|
||
1. 记录 `RollSessionId`、原始骰子面、`NormalizedKey`。
|
||
2. 走普通奖励兜底，或在调试模式返回明确错误。
|
||
3. 不进入 Lucky Dice。
|
||
|
||
### Lucky Dice 候选池为空
|
||
|
||
处理策略：
|
||
|
||
1. 尝试使用配置的 default result。
|
||
2. default result 不可用时，降级为普通奖励兜底。
|
||
3. 记录每个 filter 过滤前后的候选数量和空池原因。
|
||
|
||
### 模式解析失败
|
||
|
||
处理策略：
|
||
|
||
1. 记录 `ResultKey`、`TargetKey` 和上下文。
|
||
2. 尝试使用目标玩法默认模式。
|
||
3. 仍失败时降级为普通奖励兜底，并标记为配置错误。
|
||
|
||
兜底必须可观测，不能静默吞掉。否则后续配置错误会表现成“玩家只是没进 Lucky Dice”，很难定位。
|
||
|
||
## 测试架构
|
||
|
||
测试应围绕外部行为和完整链路，而不是私有实现细节。
|
||
|
||
### 单元测试
|
||
|
||
| 测试对象 | 重点 |
|
||
| --- | --- |
|
||
| ComboFactBuilder | N 骰统计、无序 key、有序 key、Clover 数量 |
|
||
| ComboRuleMatcher | 优先级、matcher 类型、停止继续匹配 |
|
||
| RollActionDispatcher | 按 action type 分发，不按 combo key 分发 |
|
||
| CandidateFilters | enabled、progress、source、cooldown、tutorial 过滤 |
|
||
| WeightedPicker | 固定随机源下结果可预测 |
|
||
| TargetModeResolver | rocket/thief 映射和默认模式 |
|
||
|
||
### 链路测试
|
||
|
||
链路测试是第一版最重要的测试口：
|
||
|
||
```text
|
||
给定 Roll 请求
|
||
给定 DiceSet 配置
|
||
给定 ComboRule 配置
|
||
给定 Lucky Dice 候选池
|
||
给定固定随机源
|
||
断言最终 outcome
|
||
```
|
||
|
||
最小链路用例：
|
||
|
||
- `2 + 3` 发普通奖励。
|
||
- `2 + clover` 发普通奖励并提供 Clover bonus。
|
||
- `clover + clover` 触发 Lucky Dice。
|
||
- Lucky Dice 选中 `rocket` 后进入 `slap_down_normal`。
|
||
- Lucky Dice 选中 `thief` 后进入 `treasure_heist_normal`。
|
||
- 候选池为空时进入可观测兜底。
|
||
- 普通骰子数量改成 3 后，组合事实和 matcher 仍可工作。
|
||
|
||
## 架构决策记录
|
||
|
||
完整 ADR 存放在 [Docs/Decisions](../Decisions/README.md)。本节只保留摘要，后续决策变更应优先新增或更新独立 ADR 文档。
|
||
|
||
### ADR-001：普通骰子和 Lucky Dice 特殊结果分成两套集合
|
||
|
||
[ADR-001](../Decisions/adr-001-separate-normal-and-lucky-dice-sets.md)
|
||
|
||
上下文：普通骰子负责奖励组合，Lucky Dice 负责玩法入口。两者语义不同。
|
||
|
||
决策：使用 `DiceSetType.Normal` 和 `DiceSetType.Lucky` 区分集合，不让普通组合匹配器处理 Lucky Dice 特殊结果。
|
||
|
||
结果：避免数字结算和玩法入口混用。代价是配置和调试界面需要明确展示集合类型。
|
||
|
||
### ADR-002：Roll 结果先转组合事实，再匹配规则
|
||
|
||
[ADR-002](../Decisions/adr-002-build-combo-facts-before-rule-matching.md)
|
||
|
||
上下文：第一版默认 2 颗骰子，但未来需要支持 3 颗、4 颗或关卡自定义骰子数量。
|
||
|
||
决策：所有普通 Roll 都先生成 `ComboFacts`，matcher 只依赖事实统计，不依赖固定位置。
|
||
|
||
结果：后续扩骰数量时风险更低。代价是第一版需要多写一层事实构建和测试。
|
||
|
||
### ADR-003：行为按 action type 注册
|
||
|
||
[ADR-003](../Decisions/adr-003-dispatch-actions-by-action-type.md)
|
||
|
||
上下文：如果每个组合 key 绑定一个独立方法，组合增长会让执行层失控。
|
||
|
||
决策：规则只声明 action 列表，dispatcher 只按 `ActionType` 找 executor。
|
||
|
||
结果：新增组合多数情况下只改配置。代价是 action 参数需要有清晰校验。
|
||
|
||
### ADR-004：Lucky Dice 随机源可注入
|
||
|
||
[ADR-004](../Decisions/adr-004-inject-random-source-for-lucky-dice.md)
|
||
|
||
上下文：权重随机必须可测试、可回放。
|
||
|
||
决策：Lucky Dice 权重随机通过 `IRandomSource` 或等价接口注入随机源。
|
||
|
||
结果：测试可预测，线上问题可复盘。代价是运行时需要统一管理随机源生命周期。
|
||
|
||
## 新功能开发蓝图
|
||
|
||
### 新增普通组合
|
||
|
||
1. 确认现有 matcher 能否表达该组合。
|
||
2. 能表达时新增 `ComboRuleConfig`。
|
||
3. 需要新业务效果时，优先复用现有 action。
|
||
4. 只有确实出现新的通用行为时，新增 executor。
|
||
5. 补一条规则匹配测试和一条链路测试。
|
||
|
||
### 新增 Lucky Dice 特殊结果
|
||
|
||
1. 在 Lucky Dice 特殊结果集合中新增 `ResultKey`。
|
||
2. 在候选配置中声明 `TargetKey`、权重、启用条件、槽数、default 标记。
|
||
3. 在目标模式配置中声明默认 `ModeKey`。
|
||
4. 补候选筛选测试、权重随机测试和目标模式解析测试。
|
||
|
||
### 新增目标玩法模式
|
||
|
||
1. 在 `TargetModeConfig` 中增加模式映射。
|
||
2. 如模式选择依赖上下文，新增 mode rule。
|
||
3. 不修改 Lucky Dice 随机逻辑。
|
||
4. 补 `TargetModeResolver` 测试。
|
||
|
||
### 接入表现动画
|
||
|
||
1. 核心流程先产出 `LuckyDiceResultSlots` 和 `TargetModeEntry`。
|
||
2. 表现层播放标题、倍率、结果槽和跳转反馈。
|
||
3. 动画完成后再调用 launcher，或先启动目标玩法再做过场，取决于产品节奏。
|
||
4. 动画失败不能改变核心选择结果。
|
||
|
||
## 架构治理
|
||
|
||
实现和评审时重点检查以下规则：
|
||
|
||
- 核心流程中没有固定读取第 0/1 颗骰子的业务判断。
|
||
- 普通骰子和 Lucky Dice 特殊结果没有混用同一套集合。
|
||
- 新增组合时没有新增组合 key 到独立方法的 map。
|
||
- Lucky Dice 候选必须先筛选再随机。
|
||
- 候选池为空、模式解析失败、未命中规则都有可观测兜底。
|
||
- `RollSessionId` 贯穿普通 Roll、规则匹配、Lucky Dice、模式解析、目标玩法启动。
|
||
- 表现层不参与规则匹配、候选筛选和权重随机。
|
||
|
||
## 第一版落地顺序
|
||
|
||
建议按以下顺序实现：
|
||
|
||
1. 定义核心数据结构和本地默认配置。
|
||
2. 实现普通 Roll、组合事实和规则匹配。
|
||
3. 实现 action dispatcher 和普通奖励 / Clover bonus / trigger Lucky Dice 执行器。
|
||
4. 实现 Lucky Dice 候选筛选、权重随机、结果槽生成。
|
||
5. 实现 `rocket -> slap_down_normal` 和 `thief -> treasure_heist_normal` 模式解析。
|
||
6. 实现最小表现层：标题、倍率、结果槽、目标玩法跳转反馈。
|
||
7. 补齐链路测试和追踪字段。
|
||
|
||
这个顺序能先把核心闭环跑通，再逐步加表现和更多结果类型，避免一开始被动画和短玩法完整内容拖散。
|