# 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) - 架构蓝图：[lucky-dice-core-flow-architecture-blueprint.md](../Architecture/lucky-dice-core-flow-architecture-blueprint.md) - 架构决策：[Docs/Decisions](../Decisions/README.md) - 生成日期：2026-06-22 本文档把 Lucky Dice 核心流程拆成可实现、可验收、可并行推进的功能包。它面向后续开发排期和任务拆分，不替代 PRD、需求或规格文档。 ## 总目标 ### 问题 FishDice 需要一套可扩展的普通骰子主循环和 Lucky Dice 特殊分支。第一版不能只写死几组骰子结果，也不能把每个组合绑定到独立业务方法，否则后续新增组合、骰子数量、特殊结果或目标玩法模式时会快速失控。 ### 解决方案 把核心闭环拆成配置、普通 Roll、组合事实、规则匹配、行为执行、Lucky Dice 筛选随机、目标模式解析、最小表现和追踪测试几个功能包。每个功能包都有明确输入输出和验收口，优先保证玩法闭环、可配置、可测试和可排查。 ### 第一版影响 - 玩家能完成普通 Roll，并看到普通奖励、Clover bonus 或 Lucky Dice 触发结果。 - 策划能通过规则和候选配置表达基础组合和 Lucky Dice 入口。 - 开发能在不写组合专用方法的前提下扩展新组合。 - 测试能用固定输入和固定随机源验证完整链路。 ## 用户角色 | 角色 | 关注点 | | --- | --- | | 玩家 | Roll 结果清晰，双 Clover 有惊喜，Lucky Dice 能看到目标玩法反馈 | | 策划 | 骰子数量、组合规则、候选结果、权重和模式可配置 | | 开发 | 模块边界清晰，新增组合不堆硬编码，随机和追踪可测试 | | 测试 | 能覆盖组合事实、规则优先级、Lucky Dice 兜底和完整链路 | | 产品负责人 | 第一版范围收敛，先验证闭环，不被复杂动画和完整短玩法拖散 | ## 功能包总览 | 编号 | 功能包 | 优先级 | 目标 | 依赖 | | --- | --- | --- | --- | --- | | F0 | 本地配置与核心常量 | P0 | 提供第一版默认配置和 key 入口 | 无 | | F1 | 普通 Roll 结果生成 | P0 | 根据 DiceSet 配置生成普通骰子结果 | F0 | | F2 | 组合事实构建 | P0 | 把 Roll 结果转成可匹配事实 | F0, F1 | | F3 | 组合规则匹配 | P0 | 按优先级命中普通组合规则 | F0, F2 | | F4 | 行为执行与分发 | P0 | 按 action type 执行奖励、倍率和 Lucky Dice 触发 | F3 | | F5 | Lucky Dice 候选筛选与权重随机 | P0 | 从特殊结果池选出目标结果 | F0, F4 | | F6 | 目标玩法与模式解析 | P0 | 把 Lucky Dice 结果解析成目标玩法模式 | F5 | | F7 | 最小表现与目标玩法占位入口 | P1 | 展示 Lucky Dice 标题、倍率、结果槽和跳转反馈 | F5, F6 | | F8 | 追踪与调试信息 | P0 | 用 RollSessionId 串起关键决策 | F1-F6 | | F9 | 测试套件 | P0 | 覆盖事实、匹配、筛选、随机和链路 | F1-F8 | | F10 | 后续扩展预留 | P2 | 为更多组合、模式、动画和远端配置留口 | F0-F9 | P0 是第一版闭环必须完成的功能包。P1 是第一版玩家可见体验的最小表现。P2 是明确预留但不要求第一版完整实现的扩展。 ## F0 本地配置与核心常量 ### 目标 建立第一版默认配置和统一 key 入口，让后续模块不在业务逻辑里散落裸字符串和硬编码数量。 ### 功能需求 - 提供普通骰子集合 `normal_main`。 - 普通骰子面为 `2 / 3 / 4 / 5 / 6 / clover`。 - 普通骰子数量来自 DiceSet 配置，第一版配置值为 2。 - 提供 Lucky Dice 特殊结果集合 `lucky_dice`。 - Lucky Dice 第一版结果至少包含 `rocket`、`thief`。 - Lucky Dice 默认结果槽数量来自配置，第一版配置值为 3。 - 提供普通组合规则配置。 - 提供 Lucky Dice 候选结果配置。 - 提供目标玩法模式映射配置。 ### 非功能需求 - 配置结构不能绑定具体 Unity 场景对象。 - key 应集中定义或集中加载，避免业务代码到处裸写。 - 配置加载失败时需要返回结构化错误。 ### 验收标准 - 能读取普通骰子集合、Lucky Dice 集合、组合规则、候选结果和模式映射。 - 修改普通骰子数量配置后，核心流程读取到新数量。 - 修改 Lucky Dice 结果槽数量配置后，展示槽构建读取到新数量。 - 普通骰子集合和 Lucky Dice 特殊结果集合有明确类型区分。 ### 不在范围内 - 远端配置热更新。 - 策划可视化配置编辑器。 - 完整配置校验工具链。 ## F1 普通 Roll 结果生成 ### 目标 根据普通 DiceSet 配置生成一次普通 Roll 结果，并携带同一个 `RollSessionId`。 ### 功能需求 - 接收玩家 Roll 请求。 - 从配置获取普通骰子集合和骰子数量。 - 按配置生成 `DiceRollResult`。 - `DiceRollResult` 包含 DiceSetId、DiceSetType、DiceCount、Faces、Multiplier、TriggerSource、RollSessionId。 - 不决定奖励、组合规则或 Lucky Dice 入口。 ### 非功能需求 - 支持注入随机源或可控 Roll 输入，方便测试。 - 不写死两颗骰子位置。 - 生成结果数量必须与配置 DiceCount 一致。 ### 用户故事 作为玩家，我希望普通掷骰能产出清晰结果，从而知道每次 Roll 都有意义。 ### 验收标准 - 给定 `DiceCount = 2`，Roll 结果包含 2 个普通骰子面。 - 给定 `DiceCount = 3`，Roll 结果包含 3 个普通骰子面。 - Roll 结果携带 `RollSessionId`。 - Roll 层不调用奖励、规则匹配或 Lucky Dice 服务。 ## F2 组合事实构建 ### 目标 把普通 Roll 结果转换成结构化 `ComboFacts`，供规则匹配使用。 ### 功能需求 - 从 `DiceRollResult` 构建 `ComboFacts`。 - 统计原始面列表、面数量、数字列表、点数和、Clover 数量。 - 生成无序 `NormalizedKey`。 - 生成有序 `OrderedKey`。 - `2 + clover` 与 `clover + 2` 归一为相同无序 key。 - 拒绝或报错处理 Lucky Dice 特殊结果进入普通组合事实构建。 ### 非功能需求 - 必须支持 N 颗骰子。 - 不依赖固定左骰、右骰字段。 - 输出字段应可用于日志和测试断言。 ### 用户故事 作为开发者，我希望 Roll 结果先转成组合事实，从而规则可以基于数据匹配，而不是依赖固定位置判断。 ### 验收标准 - `2 + 3` 生成 `NumberSum = 5`、`CloverCount = 0`、`NormalizedKey = 2_3`。 - `2 + clover` 与 `clover + 2` 生成相同 `NormalizedKey`。 - `clover + clover` 生成 `CloverCount = 2`。 - `2 + 2 + clover` 能生成 3 骰事实。 - Lucky Dice 特殊结果不会被当成普通组合事实处理。 ## F3 组合规则匹配 ### 目标 按规则优先级和通用 matcher 匹配普通组合，输出命中规则和 action 列表。 ### 功能需求 - 支持规则优先级。 - 第一版默认命中高优先级规则后停止继续匹配。 - 支持首批 matcher： - `ExactCombo` - `AllNumbers` - `ContainsFace` - `FaceCount` - `FaceCountRange` - `DiceCount` - `NumberPair` - `NumberOfAKind` - `NumberSumRange` - 第一版默认规则： - 双 Clover 触发 Lucky Dice。 - 单 Clover 加数字发普通奖励和 Clover bonus。 - 纯数字发普通奖励。 ### 非功能需求 - matcher 只按 matcher type 注册，不按组合 key 注册。 - 规则匹配不执行业务副作用。 - 匹配结果需要包含命中规则 id、优先级、matcher type。 ### 用户故事 作为策划，我希望组合规则支持优先级，从而让双 Clover 这类稀有触发优先于普通奖励规则。 ### 验收标准 - `clover_clover` 命中 Lucky Dice 规则，而不是泛用 Clover 规则。 - `2_clover` 命中 Clover bonus 规则。 - `2_6` 命中纯数字普通奖励规则。 - 高优先级规则优先于低优先级规则。 - 3 骰事实可以通过统计型 matcher 命中规则。 ## F4 行为执行与分发 ### 目标 把命中规则中的 action list 按 `ActionType` 分发给通用行为执行器。 ### 功能需求 - 支持 `grant_reward`。 - 支持 `add_multiplier`。 - 支持 `trigger_lucky_dice`。 - 支持 `enter_mode` 扩展口。 - 支持 `show_popup` 扩展口。 - 多个 action 按规则配置顺序执行。 - 未注册 action 返回结构化错误并写入追踪。 ### 非功能需求 - dispatcher 只维护 `ActionType -> Executor` 注册表。 - 不允许维护 `combo key -> method` 映射。 - executor 不重新做组合匹配判断。 ### 用户故事 作为开发者，我希望行为分发按行为类型注册，从而不需要维护巨大的“组合 key 到方法”映射表。 ### 验收标准 - 纯数字规则执行普通奖励 action。 - 单 Clover 规则执行普通奖励和倍率或 bonus action。 - 双 Clover 规则执行 Lucky Dice 触发 action。 - 新增组合但复用现有 action 时，不需要新增 executor。 - 未注册 action 能被追踪到。 ## F5 Lucky Dice 候选筛选与权重随机 ### 目标 Lucky Dice 触发后，从独立特殊结果池中构建候选、筛选候选、处理兜底，并按权重随机选中一个结果。 ### 功能需求 - 构建 Lucky Dice 候选池。 - 候选包含 ResultKey、TargetKey、Weight、Enabled、MinLevel、SourceFilter、CooldownRule、IsDefault、ResultSlotCount。 - 支持首批筛选器： - EnabledFilter - ProgressFilter - SourceFilter - CooldownFilter - TutorialFilter - 筛选后按权重随机。 - 权重随机使用可注入随机源。 - 候选池为空时优先使用 default result。 - default result 不可用时降级为普通奖励兜底。 ### 非功能需求 - Lucky Dice 特殊结果不与普通骰子集合混用。 - 随机结果可通过固定随机源复现。 - 筛选过程需要记录每个 filter 前后的候选数量。 ### 用户故事 作为策划，我希望 Lucky Dice 候选结果可筛选，从而未解锁、未开启或冷却中的目标玩法不会被抽中。 ### 验收标准 - 未开启候选会被过滤。 - 玩家进度不足候选会被过滤。 - 来源不匹配候选会被过滤。 - 固定随机源下可以稳定选中预期结果。 - 候选池为空时进入可观测兜底。 - `rocket` 和 `thief` 可以作为第一版有效候选。 ## F6 目标玩法与模式解析 ### 目标 把 Lucky Dice 选中的结果解析为目标玩法和具体模式。 ### 功能需求 - 支持 `ResultKey -> TargetKey -> ModeKey` 两级解析。 - `rocket` 解析到 `slap_down_normal`。 - `thief` 解析到 `treasure_heist_normal`。 - 保留教程模式和 bonus 模式扩展规则。 - 输出 `TargetModeEntry`，包含 TargetKey、ModeKey、ResultKey、Multiplier、TriggerSource、RollSessionId。 ### 非功能需求 - 模式解析不参与 Lucky Dice 随机。 - 目标玩法启动不反向影响候选筛选。 - 模式解析失败必须可兜底、可追踪。 ### 用户故事 作为玩家，我希望 Rocket 结果进入 Slap Down，从而让结果和后续玩法有明确绑定。 ### 验收标准 - `rocket` 解析为 `TargetKey = slap_down`、`ModeKey = slap_down_normal`。 - `thief` 解析为 `TargetKey = treasure_heist`、`ModeKey = treasure_heist_normal`。 - 模式解析结果携带原始 `RollSessionId`。 - 模式映射失败时进入可观测兜底。 ## F7 最小表现与目标玩法占位入口 ### 目标 提供第一版玩家可见反馈：Lucky Dice 标题、倍率、结果槽图标和目标玩法跳转反馈。 ### 功能需求 - 展示 Lucky Dice 标题。 - 展示当前倍率。 - 按结果槽数量展示特殊图标。 - 第一版结果槽可全部展示同一个 ResultKey。 - 触发目标玩法入口反馈。 - 目标玩法结束后能回到主循环。 - Slap Down 和 Treasure Heist 第一版可以是占位入口，不要求完整玩法内容。 ### 非功能需求 - 表现层不参与规则匹配、候选筛选和权重随机。 - 动画失败不能改变核心选择结果。 - 结果槽数量来自配置或候选，不写死在 UI 中。 ### 用户故事 作为玩家，我希望 Lucky Dice 结果能清楚显示特殊图标，从而知道即将进入哪个短玩法。 ### 验收标准 - Lucky Dice 触发后能看到标题、倍率和结果槽。 - 选中 `rocket` 时展示 Rocket 结果并进入 Slap Down 占位入口。 - 选中 `thief` 时展示 Thief 结果并进入 Treasure Heist 占位入口。 - 结果槽数量修改为 2 或 4 时，表现层能按配置展示。 ### 不在范围内 - 托盘动画。 - 骰子飞入。 - 粒子爆发。 - 白烟转场。 - 完整 Slap Down 和 Treasure Heist 玩法。 ## F8 追踪与调试信息 ### 目标 让一次 Roll 从普通结果到最终玩法模式的关键决策可解释、可回放、可排查。 ### 功能需求 - 每次 Roll 创建或携带同一个 `RollSessionId`。 - 记录普通骰子结果和骰子数量。 - 记录组合事实和 `NormalizedKey`。 - 记录命中规则、优先级和执行 action。 - 记录 Lucky Dice 初始候选和筛选结果。 - 记录兜底类型。 - 记录权重随机输入和选中结果。 - 记录最终 TargetKey、ModeKey 和 FinalOutcome。 ### 非功能需求 - 追踪层不改变玩法决策。 - 第一版可以使用本地结构化日志或调试数据结构。 - 字段命名应稳定，方便后续接入埋点。 ### 用户故事 作为开发者，我希望每次 Roll 都携带同一个会话 id，从而普通 Roll、规则匹配、Lucky Dice 结果和目标玩法启动可以串起来排查。 ### 验收标准 - 普通奖励链路可以从 trace 解释为什么发奖。 - 双 Clover 链路可以从 trace 解释为什么进入 Lucky Dice。 - Lucky Dice 链路可以从 trace 看到哪些候选被过滤。 - 模式解析失败或候选池为空时，trace 中有兜底原因。 ## F9 测试套件 ### 目标 用测试锁住第一版核心闭环，避免后续扩展组合或结果时破坏基础行为。 ### 功能需求 - 组合事实测试。 - 规则匹配测试。 - 行为分发测试。 - Lucky Dice 筛选测试。 - 权重随机测试。 - 目标模式解析测试。 - 完整链路测试。 - 兜底场景测试。 ### 非功能需求 - 测试外部行为，不测试私有实现细节。 - 使用固定随机源。 - 关键链路测试应覆盖 `RollSessionId`。 ### 验收标准 - `2 + 3` 最终发普通奖励。 - `2 + clover` 最终发普通奖励并提供 Clover bonus。 - `clover + clover` 最终进入 Lucky Dice。 - Lucky Dice 选中 `rocket` 后进入 `slap_down_normal`。 - Lucky Dice 选中 `thief` 后进入 `treasure_heist_normal`。 - 候选池为空时走兜底。 - 普通骰子从 2 改为 3 后，组合事实和 matcher 仍工作。 ## F10 后续扩展预留 ### 目标 明确第一版不做但架构需要保留的扩展方向，防止第一版把未来道路堵死。 ### 扩展方向 - 更多普通组合，例如对子、三连、点数和区间、指定数字组合、有序组合。 - 更多 Lucky Dice 特殊结果，例如 Chest、Bomb、Key。 - 教程模式和 bonus 模式。 - 按活动或关卡调整权重。 - 远端配置热更新。 - 完整表现动画。 - 完整 Slap Down 和 Treasure Heist 玩法内容。 - 埋点管线集成。 ### 约束 - 扩展普通组合优先新增配置，不新增组合专用方法。 - 扩展特殊结果优先新增候选和模式映射。 - 扩展动画不能改变核心随机和模式解析结果。 - 接入埋点时复用 `RollSessionId` 和现有 trace 字段。 ## 依赖顺序 ```mermaid flowchart TD F0["F0 本地配置与核心常量"] --> F1["F1 普通 Roll 结果生成"] F1 --> F2["F2 组合事实构建"] F2 --> F3["F3 组合规则匹配"] F3 --> F4["F4 行为执行与分发"] F4 --> F5["F5 Lucky Dice 筛选与随机"] F5 --> F6["F6 目标玩法与模式解析"] F5 --> F7["F7 最小表现"] F6 --> F7 F1 --> F8["F8 追踪"] F3 --> F8 F5 --> F8 F6 --> F8 F1 --> F9["F9 测试"] F2 --> F9 F3 --> F9 F4 --> F9 F5 --> F9 F6 --> F9 ``` ## 建议迭代切片 ### Slice 1：普通 Roll 到普通奖励 包含 F0、F1、F2、F3、F4 的普通奖励部分、F8 基础字段、F9 基础测试。 验收： - 纯数字结果发普通奖励。 - 单 Clover 加数字发普通奖励和 bonus。 - 组合事实和规则命中可追踪。 ### Slice 2：双 Clover 触发 Lucky Dice 包含 F4 的 `trigger_lucky_dice`、F5、F6、F8 Lucky Dice 字段、F9 Lucky Dice 测试。 验收： - 双 Clover 不发普通奖励，而是进入 Lucky Dice。 - `rocket` 能解析到 Slap Down 普通模式。 - `thief` 能解析到 Treasure Heist 普通模式。 - 候选池为空有兜底。 ### Slice 3：最小玩家可见闭环 包含 F7 和链路测试补齐。 验收： - Lucky Dice 标题、倍率、结果槽可见。 - 目标玩法占位入口可达。 - 目标玩法结束后能回到主循环。 ### Slice 4：扩展性验证 包含 3 骰配置测试、结果槽数量变化测试、一个统计型 matcher 示例。 验收： - 普通骰子数量改为 3 后不改核心流程。 - 结果槽数量改为 2 或 4 后表现层按配置展示。 - 新增一个组合规则时复用已有 matcher 和 action。 ## 总体验收标准 - 普通骰子结果能转换为结构化组合事实。 - 普通骰子数量和 Lucky Dice 结果槽数量来自配置。 - 规则系统通过少量通用 matcher 命中普通组合。 - 双 Clover 优先触发 Lucky Dice。 - 行为执行层只按 action type 分发。 - Lucky Dice 先筛选候选，再按权重随机。 - `rocket` 进入 `slap_down_normal`。 - `thief` 进入 `treasure_heist_normal`。 - 候选池为空、模式解析失败、未注册 action 都有可观测兜底。 - `RollSessionId` 能串起完整链路。 ## 第一版不做 - 完整复刻参考 Lucky Dice 动画。 - 托盘、飞入、粒子爆发、白烟转场。 - 完整 Slap Down 玩法。 - 完整 Treasure Heist 玩法。 - 所有 Lucky Dice 特殊结果类型。 - 远端配置热更新。 - 复杂运营活动概率策略。 - 正式埋点管线集成。 - 为每个组合 key 编写独立业务方法。 - 假设普通骰子永远只有 2 颗。 - 假设 Lucky Dice 永远只有 3 个结果槽。