InventoryGenerationComponent + TagRegistryComponent 收口

2026-03-13 11:06:14 +08:00
parent 0c92fd9886
commit aa44170d56
23 changed files with 967 additions and 251 deletions
@@ -9,7 +9,7 @@

 - 商店、敌人掉落、满血 3 选 1 候选都在各自生成组件实例，逻辑分散，后续改规则要改多处。
 - `ShopFormUseCase`、旧 `EnemyDropResolver`、`CombatSettlementService` 都曾同时承担“流程 + 规则 + 数据组装”的混合职责。
- `runSeed` 目前只稳定了 Tag 生成，没有稳定整个组件产出流程。
+- 重构前 `runSeed` 只稳定了 Tag 生成，没有稳定整个组件产出流程；当前已补齐到商店、掉落、奖励候选与奖励展示顺序。
 - Tag 模块本身已经分成 `Generation / Aggregation / Combat / Metadata / Presentation`，但初始化入口还散在流程代码里。

 ## 重构边界
@@ -30,7 +30,7 @@
   - `TagDefinitionRegistry`
   - `TagGenerationRuleRegistry`
   - `RarityTagBudgetRuleRegistry`
-   - 替代当前散在 `ProcedurePreload` 里的 Tag 注册表装载逻辑。
+   - 替代旧的 `ProcedurePreload` 直连刷新逻辑，并收口当前主流程初始化入口。

 ### 不适合抽成 `GameFrameworkComponent` 的模块

@@ -54,6 +54,8 @@

 - `Assets/GameMain/Scripts/Factory/ComponentItemFactory.cs`
  - 唯一负责“从配置行构造 `TowerCompItemData`”。
+- `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/InventoryGenerationRandomContext.cs`
+  - 统一承载商店 / 掉落 / 奖励候选的随机合同。
 - `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/ShopGoodsBuilder.cs`
  - 只负责商店货物生成。
 - `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/DropPoolRoller.cs`
@@ -101,7 +103,9 @@

 - `ProcedurePreload`
  - 移除 Tag 注册表刷新细节。
-  - 只保留“数据表加载完成后通知组件刷新”。
+  - 只保留资源与数据表预加载职责。
+- `ProcedureMain`
+  - 进入主流程时主动调用 `GameEntry.TagRegistry.OnInit()`。
 - `TagRegistryComponent`
  - 成为 Tag 相关表与注册表的唯一运行时入口。

@@ -157,9 +161,9 @@

 | 状态  | ID    | 任务                               | 目标                 |
 |-----|-------|----------------------------------|--------------------|
-| [ ] | G4-01 | 新增 `TagRegistryComponent`        | 建立 Tag 运行时入口       |
-| [ ] | G4-02 | 挪出 `ProcedurePreload` 中 Tag 注册逻辑 | 流程代码不再直接维护 Tag 注册表 |
-| [ ] | G4-03 | 对齐 Tag 加载时机与重载入口                 | 初始化路径明确            |
+| [x] | G4-01 | 新增 `TagRegistryComponent`        | 建立 Tag 运行时入口       |
+| [x] | G4-02 | 挪出 `ProcedurePreload` 中 Tag 注册逻辑 | 流程代码不再直接维护 Tag 注册表 |
+| [x] | G4-03 | 对齐 Tag 加载时机与重载入口                 | 初始化路径明确            |

 ### G4 验收标准

@@ -171,9 +175,9 @@

 | 状态  | ID    | 任务                     | 目标                  |
 |-----|-------|------------------------|---------------------|
-| [ ] | G5-01 | 统一商店 / 掉落 / 奖励候选的随机上下文 | 全部产出链路使用一致合同        |
-| [ ] | G5-02 | 补齐整体产出的 `runSeed` 稳定性  | 不只稳定 Tag，也稳定物品产出    |
-| [ ] | G5-03 | 增加对应 EditMode 测试       | 同 Run 可复现，跨 Run 可区分 |
+| [x] | G5-01 | 统一商店 / 掉落 / 奖励候选的随机上下文 | 全部产出链路使用一致合同        |
+| [x] | G5-02 | 补齐整体产出的 `runSeed` 稳定性  | 不只稳定 Tag，也稳定物品产出    |
+| [x] | G5-03 | 增加对应 EditMode 测试       | 同 Run 可复现，跨 Run 可区分 |

 ### G5 验收标准

@@ -188,6 +192,7 @@
 - `Assets/GameMain/Scripts/UI/Shop/UseCase/ShopFormUseCase.cs`
 - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSettlementService.cs`
 - `Assets/GameMain/Scripts/Procedure/Base/ProcedurePreload.cs`
+- `Assets/GameMain/Scripts/Procedure/ProcedureMain/ProcedureMain.cs`
 - `Assets/GameMain/Scripts/Base/GameEntry.Custom.cs`
 - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs`

@@ -196,6 +201,7 @@
 - `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/InventoryGenerationComponent.cs`
 - `Assets/GameMain/Scripts/CustomComponent/TagRegistry/TagRegistryComponent.cs`
 - `Assets/GameMain/Scripts/Factory/ComponentItemFactory.cs`
+- `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/InventoryGenerationRandomContext.cs`
 - `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/ShopGoodsBuilder.cs`
 - `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/DropPoolRoller.cs`
 - `Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/RewardCandidateBuilder.cs`
@@ -215,7 +221,7 @@
 2. 先替换商店货物生成。
 3. 再替换战斗掉落与奖励候选生成。
 4. 再拆战斗结算计算与提交。
-5. 最后收 `TagRegistryComponent` 与 `ProcedurePreload` 的 Tag 初始化入口。
+5. 最后收 `TagRegistryComponent` 与主流程中的 Tag 初始化入口。

 ## 通过标准

@@ -223,3 +229,12 @@
 - 掉落、商店、奖励候选不再各自维护相似逻辑。
 - Tag 模块保留现有分层，不再继续和流程代码缠在一起。
 - `GameFrameworkComponent` 只承接运行时入口，不承接纯规则实现。
+
+## 当前结果
+
+- `InventoryGenerationComponent` 已成为商店、战斗掉落、奖励候选的统一运行时入口。
+- 掉落概率规则与掉落物品构造已继续下沉到 `OutGameDropRuleService` 与 `OutGameDropItemBuilder`，`InventoryGenerationComponent` 保持入口编排职责。
+- `TagRegistryComponent` 已成为 Tag 运行时入口，并由 `ProcedureMain` 主动初始化。
+- `TagRegistryComponent` 已改为 fail-fast 初始化，缺少必要数据表时会直接暴露错误。
+- `InventoryGenerationRandomContext` 已统一商店、掉落、奖励候选的随机合同，并补齐稳定临时实例 Id。
+- `Assets/Tests/EditMode/InventoryGenerationStabilityTests.cs` 已覆盖 G5 的可复现性验收点。
@@ -310,12 +310,30 @@
 - 在内部编排：
  - `DropPoolRoller`
  - `RewardCandidateBuilder`
-  - `ComponentItemFactory`
+  - `OutGameDropRuleService`
+  - `OutGameDropItemBuilder`
+  - `InventoryGenerationRandomContext`

 约束：
 - `CombatNode` 域不直接持有或复制组件产出规则。
 - `CombatScheduler` 与结算状态链只调用统一入口，不直接访问掉落池滚动或组件实例构造细节。
- `InventoryGenerationComponent` 负责组件实例生成、Tag 随机上下文以及 `runSeed/sequenceIndex` 相关上下文。
+- `InventoryGenerationComponent` 负责运行时入口、稳定临时实例 Id、Tag 随机上下文以及 `runSeed/sequenceIndex` 相关上下文。
+- 掉落是否产出组件由 `OutGameDropRuleService` 决定；掉落池行到组件实例的构造由 `OutGameDropItemBuilder` 决定。
+
+### 4.5.x InventoryGenerationRandomContext
+
+文件：`Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/InventoryGenerationRandomContext.cs`
+
+目标职责：
+- 统一承载组件产出链路的随机合同。
+- 统一派生：
+  - 商店 / 掉落 / 奖励候选的稳定随机流
+  - 稳定临时组件 `InstanceId`
+  - `InventoryTagRandomContext`
+
+约束：
+- `ShopGoodsBuilder`、`DropPoolRoller`、`RewardCandidateBuilder` 不再直接使用全局 `UnityEngine.Random`。
+- 同一 `runSeed + sequenceIndex + sourceType + localOrdinal` 下，应得到一致的物品本体与 Tag 结果。

 ### 4.6 CombatSettlementCalculator

@@ -1,6 +1,6 @@
 # Tag System Design

-最后更新：2026-03-12
+最后更新：2026-03-13

 > 目标：这是 GeometryTD 当前 Tag 系统的唯一正式口径。
 > 本文档只记录当前真实实现、当前边界与正式规则。
@@ -76,7 +76,9 @@ M1 已完成 Tag 最小闭环：
 - 当前负责 `MinRarity`、`Weight`
 - `Tag.txt + TagConfig.txt -> TagDefinitionRegistry.ReloadFromRows(...)`
 - 当前负责 `IsImplemented`、`TriggerPhase`、`Description` 与正式运行时参数
- `ProcedurePreload` 在 `Tag` 或 `TagConfig` 任一表加载完成后，都会基于当前已加载的两张表组合重建定义层
+- `ProcedureMain -> GameEntry.TagRegistry.OnInit() -> TagRegistryComponent`
+- 当前在主流程进入时统一基于已加载数据表重建 Tag 定义层与生成规则层
+- `TagRegistryComponent` 对 `TagConfig`、`Tag`、`RarityTagBudget` 三张表采用 fail-fast 依赖约束；缺表时直接暴露初始化错误，不再静默跳过
 - `RarityTagBudget.txt -> DRRarityTagBudget -> RarityTagBudgetRuleRegistry`
 - 当前负责按品质读取 `MinCount / MaxCount`

@@ -100,9 +102,9 @@ public sealed class TagRuntimeData
 当前统一入口是 `ComponentTagGenerationService`，以下链路共用同一套规则：

 - `InventorySeedUtility`
- `ShopFormUseCase`
- `EnemyDropResolver`
- 结算奖励候选组件
+- `InventoryGenerationComponent.BuildShopGoods(...)`
+- `InventoryGenerationComponent.ResolveEnemyDrop(...)`
+- `InventoryGenerationComponent.BuildRewardCandidates(...)`

 当前流程：

@@ -124,7 +126,15 @@ Tag 随机结果的正式上下文为：
 - `ItemInstanceId`
 - `ConfigId`

-当前运行时通过 `InventoryTagRandomContext` 统一承载上述字段。
+当前运行时通过 `InventoryGenerationRandomContext + InventoryTagRandomContext` 统一承载上述字段：
+
+- `InventoryGenerationRandomContext`
+  - 统一承载 `runSeed + nodeSequenceIndex + sourceType + localOrdinal`
+  - 统一派生产出链路自己的稳定随机流
+  - 统一派生稳定的临时组件 `InstanceId`
+- `InventoryTagRandomContext`
+  - 承载 Tag 生成所需的 `RunSeed / SourceType / ItemInstanceId / ConfigId`
+  - 由 `InventoryGenerationRandomContext` 进一步派生

 各来源构造口径：