docs(analysis): 添加 FishDice 框架分析页面

2026-06-25 10:46:23 +08:00
parent 4247782c01
commit 1edc72db0c
9 changed files with 800 additions and 0 deletions
--- a/analysis/FishDice/module-development.html
+++ b/analysis/FishDice/module-development.html
@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>FishDice 玩法与模块开发</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <main class="shell">
+    <div class="topbar"><a href="index.html">← 返回总览</a><span class="brand">玩法与模块开发</span></div>
+    <section class="hero">
+      <h1>从框架设计看玩法、模块、服务和管理器如何拆分</h1>
+      <p class="subtitle">FishDice 的扩展方式不是“给每个组合写一个 if 分支”，而是把变化拆到配置行、Matcher、ActionExecutor、候选定义和 TargetMode 映射里。</p>
+    </section>
+
+    <section>
+      <h2>核心开发原则</h2>
+      <div class="grid-2">
+        <div class="card"><h3>组合变化优先改规则配置</h3><p>新增“什么组合触发什么行为”时，优先新增 <code>ComboRuleDefinition</code>。只有现有 matcher 表达不了新语义时，才新增 <code>IComboMatcher</code>。</p></div>
+        <div class="card"><h3>行为变化按 ActionType 扩展</h3><p>新增通用行为时，新增 <code>IRollActionExecutor</code> 并注册到 context。Dispatcher 只知道 ActionType，不知道具体组合 key。</p></div>
+        <div class="card"><h3>特殊玩法入口走候选池</h3><p>Lucky Dice 的结果和目标玩法由 <code>LuckyDiceCandidateDefinition</code> 与 <code>TargetModeDefinition</code> 定义。</p></div>
+        <div class="card"><h3>目标玩法内部不反向污染 Lucky Dice</h3><p>目标玩法模式由 <code>TargetModeResolver</code> 解析，Lucky Dice 选择层只负责选结果和 target key，不关心玩法内部实现。</p></div>
+      </div>
+    </section>
+
+    <section>
+      <h2>新增内容应该放哪里</h2>
+      <table>
+        <tr><th>开发需求</th><th>推荐位置</th><th>实现方式</th><th>测试重点</th></tr>
+        <tr><td>新增普通骰子组合</td><td><code>Config</code></td><td>新增 <code>ComboRuleDefinition</code>，复用已有 matcher 和 action。</td><td>规则命中、优先级、action 顺序。</td></tr>
+        <tr><td>新增组合匹配能力</td><td><code>Rules/Matchers</code></td><td>实现 <code>IComboMatcher</code>，放入 <code>ComboMatcherRegistry</code> 或自定义 validation context。</td><td>MatcherType 唯一、边界输入。</td></tr>
+        <tr><td>新增奖励或业务行为</td><td><code>Actions</code></td><td>实现 <code>IRollActionExecutor</code>，通过 ActionType 注册。</td><td>未注册 action 失败记录、effect 输出。</td></tr>
+        <tr><td>新增 Lucky Dice 结果</td><td><code>Config</code> + 资源层</td><td>新增 candidate 和 target mode，并补图标/展示资源。</td><td>默认候选、权重、source filter、target mode 存在。</td></tr>
+        <tr><td>新增目标玩法模式</td><td><code>TargetMode</code> 接入层</td><td>新增 <code>TargetModeDefinition</code> 或后续扩展 resolver 规则。</td><td>缺失映射失败原因、成功解析 mode key。</td></tr>
+      </table>
+    </section>
+
+    <section>
+      <h2>服务和“管理器”的边界</h2>
+      <p>当前 Runtime 里没有传统 Unity 式单例 Manager，而是小服务组合：<code>DiceRollService</code> 做随机 Roll，<code>ComboRuleMatcher</code> 做规则匹配，<code>RollActionDispatcher</code> 做行为分发，<code>LuckyDiceFlowService</code> 做特殊候选选择，<code>TargetModeResolver</code> 做模式解析。</p>
+      <div class="note good">这让“管理器”职责被拆散：没有一个巨大的 LuckyDiceManager 同时管随机、规则、奖励、UI、场景跳转。</div>
+    </section>
+
+    <section>
+      <h2>扩展入口</h2>
+      <p><code>LuckyDiceRuntimeFactory.CreateFlow</code> 支持传入规则、候选和目标模式定义；<code>LuckyDiceConfigValidationContext</code> 支持传入自定义 matcher 与 action executor。测试里已经覆盖“自定义 matcher/action 能被同一 context 用于校验和运行时分发”。</p>
+    </section>
+
+    <section class="evidence">
+      <h2>证据</h2>
+      <ul>
+        <li><span class="path">LuckyDiceDefaultConfig.cs:151-238</span>：默认规则、候选、目标模式定义。</li>
+        <li><span class="path">ComboMatcherRegistry.cs:5-20</span>：默认 matcher 注册表。</li>
+        <li><span class="path">RollActionExecutorRegistry.cs</span>：默认 action executor 注册表。</li>
+        <li><span class="path">LuckyDiceConfigValidationContext.cs:8-30</span>：自定义 matcher/action 的上下文入口。</li>
+        <li><span class="path">LuckyDiceCoreFlowTests.cs:446-487</span>：自定义 matcher/action 走完整 flow。</li>
+      </ul>
+    </section>
+  </main>
+</body>
+</html>