From e000665c67790c3268a26effa794723518efdae4 Mon Sep 17 00:00:00 2001
From: GwWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Wed, 7 Jan 2026 21:16:43 +0800
Subject: [PATCH] =?UTF-8?q?feat(architecture):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E4=B8=8A=E4=B8=8B=E6=96=87=E5=B7=A5=E5=85=B7=E5=88=9D=E5=A7=8B?=
 =?UTF-8?q?=E5=8C=96=E9=98=B6=E6=AE=B5=E6=94=AF=E6=8C=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 在架构中新增 _mContextUtilities 集合存储未初始化的上下文工具
- 实现工具注册时根据初始化状态决定是否立即初始化上下文工具
- 添加 BeforeUtilityInit 和 AfterUtilityInit 两个新的架构阶段
- 更新架构阶段转换配置以支持工具初始化流程
- 在同步和异步架构测试中验证新的初始化阶段序列
- 完善架构初始化流程日志记录和调试信息
---
 .../enums/ArchitecturePhase.cs                | 10 ++++++
 .../tests/AsyncArchitectureTests.cs           |  2 ++
 .../tests/SyncArchitectureTests.cs            |  2 ++
 GFramework.Core/architecture/Architecture.cs  | 34 ++++++++++++++++++-
 .../architecture/ArchitectureConstants.cs     | 10 +++++-
 5 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/GFramework.Core.Abstractions/enums/ArchitecturePhase.cs b/GFramework.Core.Abstractions/enums/ArchitecturePhase.cs
index a46310c..93b2aa3 100644
--- a/GFramework.Core.Abstractions/enums/ArchitecturePhase.cs
+++ b/GFramework.Core.Abstractions/enums/ArchitecturePhase.cs
@@ -14,6 +14,16 @@ public enum ArchitecturePhase
     /// </summary>
     None = 0,
 
+    /// <summary>
+    /// 工具类初始化之前阶段
+    /// </summary>
+    BeforeUtilityInit,
+
+    /// <summary>
+    /// 工具类初始化之后阶段
+    /// </summary>
+    AfterUtilityInit,
+
     /// <summary>
     ///     模型初始化之前阶段
     /// </summary>
diff --git a/GFramework.Core.Tests/tests/AsyncArchitectureTests.cs b/GFramework.Core.Tests/tests/AsyncArchitectureTests.cs
index a29c190..de86f7b 100644
--- a/GFramework.Core.Tests/tests/AsyncArchitectureTests.cs
+++ b/GFramework.Core.Tests/tests/AsyncArchitectureTests.cs
@@ -60,6 +60,8 @@ public class AsyncArchitectureTests : ArchitectureTestsBase<AsyncTestArchitectur
         CollectionAssert.AreEqual(
             new[]
             {
+                ArchitecturePhase.BeforeUtilityInit,
+                ArchitecturePhase.AfterUtilityInit,
                 ArchitecturePhase.BeforeModelInit,
                 ArchitecturePhase.AfterModelInit,
                 ArchitecturePhase.BeforeSystemInit,
diff --git a/GFramework.Core.Tests/tests/SyncArchitectureTests.cs b/GFramework.Core.Tests/tests/SyncArchitectureTests.cs
index 30f1507..0695be3 100644
--- a/GFramework.Core.Tests/tests/SyncArchitectureTests.cs
+++ b/GFramework.Core.Tests/tests/SyncArchitectureTests.cs
@@ -76,6 +76,8 @@ public class SyncArchitectureTests : ArchitectureTestsBase<SyncTestArchitecture>
         CollectionAssert.AreEqual(
             new[]
             {
+                ArchitecturePhase.BeforeUtilityInit,
+                ArchitecturePhase.AfterUtilityInit,
                 ArchitecturePhase.BeforeModelInit,
                 ArchitecturePhase.AfterModelInit,
                 ArchitecturePhase.BeforeSystemInit,
diff --git a/GFramework.Core/architecture/Architecture.cs b/GFramework.Core/architecture/Architecture.cs
index 93ec98d..7cf2b92 100644
--- a/GFramework.Core/architecture/Architecture.cs
+++ b/GFramework.Core/architecture/Architecture.cs
@@ -110,6 +110,12 @@ public abstract class Architecture(
     /// </summary>
     private readonly HashSet<ISystem> _allSystems = [];
 
+    /// <summary>
+    ///     存储尚未初始化的上下文工具集合
+    /// </summary>
+    private readonly HashSet<IContextUtility> _mContextUtilities = [];
+
+
     /// <summary>
     ///     标记架构是否已初始化完成
     /// </summary>
@@ -328,6 +334,19 @@ public abstract class Architecture(
         _logger.Debug("Calling user Init()");
         Init();
         _logger.Debug("User Init() completed");
+        // === Context Utility 初始化阶段 ===
+        EnterPhase(ArchitecturePhase.BeforeUtilityInit);
+        _logger.Info($"Initializing {_mContextUtilities.Count} context utilities");
+
+        foreach (var utility in _mContextUtilities)
+        {
+            _logger.Debug($"Initializing context utility: {utility.GetType().Name}");
+            utility.Init();
+        }
+
+        _mContextUtilities.Clear();
+        EnterPhase(ArchitecturePhase.AfterUtilityInit);
+        _logger.Info("All context utilities initialized");
 
         // === 模型初始化阶段 ===
         // 在此阶段初始化所有注册的模型组件
@@ -447,7 +466,20 @@ public abstract class Architecture(
     public void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility
     {
         _logger.Debug($"Registering utility: {typeof(TUtility).Name}");
-        utility.IfType<IContextUtility>(contextUtility => { contextUtility.SetContext(Context); });
+        utility.IfType<IContextUtility>(contextUtility =>
+        {
+            contextUtility.SetContext(Context);
+
+            if (!_mInitialized)
+            {
+                _mContextUtilities.Add(contextUtility);
+            }
+            else
+            {
+                _logger.Trace($"Immediately initializing context utility: {typeof(TUtility).Name}");
+                contextUtility.Init();
+            }
+        });
         Container.RegisterPlurality(utility);
         _logger.Info($"Utility registered: {typeof(TUtility).Name}");
     }
diff --git a/GFramework.Core/architecture/ArchitectureConstants.cs b/GFramework.Core/architecture/ArchitectureConstants.cs
index e187ee4..f81d2b5 100644
--- a/GFramework.Core/architecture/ArchitectureConstants.cs
+++ b/GFramework.Core/architecture/ArchitectureConstants.cs
@@ -17,7 +17,15 @@ public static class ArchitectureConstants
     public static readonly ImmutableDictionary<ArchitecturePhase, ArchitecturePhase[]> PhaseTransitions =
         new Dictionary<ArchitecturePhase, ArchitecturePhase[]>
         {
-            { ArchitecturePhase.None, [ArchitecturePhase.BeforeModelInit] },
+            { ArchitecturePhase.None, [ArchitecturePhase.BeforeUtilityInit] },
+            {
+                ArchitecturePhase.BeforeUtilityInit,
+                [ArchitecturePhase.AfterUtilityInit, ArchitecturePhase.FailedInitialization]
+            },
+            {
+                ArchitecturePhase.AfterUtilityInit,
+                [ArchitecturePhase.BeforeModelInit, ArchitecturePhase.FailedInitialization]
+            },
             {
                 ArchitecturePhase.BeforeModelInit, [
                     ArchitecturePhase.AfterModelInit, ArchitecturePhase.FailedInitialization