Feature/pause stack manager

GFramework.Core.Abstractions/pause/IPauseHandler.cs

@@ -0,0 +1,19 @@
+namespace GFramework.Core.Abstractions.pause;
+
+/// <summary>
+/// 暂停处理器接口，由引擎层实现具体的暂停/恢复逻辑
+/// </summary>
+public interface IPauseHandler
+{
+    /// <summary>
+    /// 处理器优先级（数值越小优先级越高）
+    /// </summary>
+    int Priority { get; }
+
+    /// <summary>
+    /// 当某个组的暂停状态变化时调用
+    /// </summary>
+    /// <param name="group">暂停组</param>
+    /// <param name="isPaused">是否暂停</param>
+    void OnPauseStateChanged(PauseGroup group, bool isPaused);
+}

GFramework.Core.Abstractions/pause/IPauseStackManager.cs

@@ -0,0 +1,81 @@
+using GFramework.Core.Abstractions.utility;
+
+namespace GFramework.Core.Abstractions.pause;
+
+/// <summary>
+/// 暂停栈管理器接口，管理嵌套暂停状态
+/// </summary>
+public interface IPauseStackManager : IContextUtility
+{
+    /// <summary>
+    /// 推入暂停请求
+    /// </summary>
+    /// <param name="reason">暂停原因（用于调试）</param>
+    /// <param name="group">暂停组</param>
+    /// <returns>暂停令牌（用于后续恢复）</returns>
+    PauseToken Push(string reason, PauseGroup group = PauseGroup.Global);
+
+    /// <summary>
+    /// 弹出暂停请求
+    /// </summary>
+    /// <param name="token">暂停令牌</param>
+    /// <returns>是否成功弹出</returns>
+    bool Pop(PauseToken token);
+
+    /// <summary>
+    /// 查询指定组是否暂停
+    /// </summary>
+    /// <param name="group">暂停组</param>
+    /// <returns>是否暂停</returns>
+    bool IsPaused(PauseGroup group = PauseGroup.Global);
+
+    /// <summary>
+    /// 获取指定组的暂停深度（栈中元素数量）
+    /// </summary>
+    /// <param name="group">暂停组</param>
+    /// <returns>暂停深度</returns>
+    int GetPauseDepth(PauseGroup group = PauseGroup.Global);
+
+    /// <summary>
+    /// 获取指定组的所有暂停原因
+    /// </summary>
+    /// <param name="group">暂停组</param>
+    /// <returns>暂停原因列表</returns>
+    IReadOnlyList<string> GetPauseReasons(PauseGroup group = PauseGroup.Global);
+
+    /// <summary>
+    /// 创建暂停作用域（支持 using 语法）
+    /// </summary>
+    /// <param name="reason">暂停原因</param>
+    /// <param name="group">暂停组</param>
+    /// <returns>可释放的作用域对象</returns>
+    IDisposable PauseScope(string reason, PauseGroup group = PauseGroup.Global);
+
+    /// <summary>
+    /// 清空指定组的所有暂停请求
+    /// </summary>
+    /// <param name="group">暂停组</param>
+    void ClearGroup(PauseGroup group);
+
+    /// <summary>
+    /// 清空所有暂停请求
+    /// </summary>
+    void ClearAll();
+
+    /// <summary>
+    /// 注册暂停处理器
+    /// </summary>
+    /// <param name="handler">处理器实例</param>
+    void RegisterHandler(IPauseHandler handler);
+
+    /// <summary>
+    /// 注销暂停处理器
+    /// </summary>
+    /// <param name="handler">处理器实例</param>
+    void UnregisterHandler(IPauseHandler handler);
+
+    /// <summary>
+    /// 暂停状态变化事件
+    /// </summary>
+    event Action<PauseGroup, bool>? OnPauseStateChanged;
+}

GFramework.Core.Abstractions/pause/PauseGroup.cs

@@ -0,0 +1,42 @@
+namespace GFramework.Core.Abstractions.pause;
+
+/// <summary>
+/// 暂停组枚举，定义不同的暂停作用域
+/// </summary>
+public enum PauseGroup
+{
+    /// <summary>
+    /// 全局暂停（影响所有系统）
+    /// </summary>
+    Global = 0,
+
+    /// <summary>
+    /// 游戏逻辑暂停（不影响 UI）
+    /// </summary>
+    Gameplay = 1,
+
+    /// <summary>
+    /// 动画暂停
+    /// </summary>
+    Animation = 2,
+
+    /// <summary>
+    /// 音频暂停
+    /// </summary>
+    Audio = 3,
+
+    /// <summary>
+    /// 自定义组 1
+    /// </summary>
+    Custom1 = 10,
+
+    /// <summary>
+    /// 自定义组 2
+    /// </summary>
+    Custom2 = 11,
+
+    /// <summary>
+    /// 自定义组 3
+    /// </summary>
+    Custom3 = 12
+}

GFramework.Core.Abstractions/pause/PauseToken.cs

@@ -0,0 +1,43 @@
+namespace GFramework.Core.Abstractions.pause;
+
+/// <summary>
+/// 暂停令牌，唯一标识一个暂停请求
+/// </summary>
+public readonly struct PauseToken : IEquatable<PauseToken>
+{
+    /// <summary>
+    /// 令牌 ID
+    /// </summary>
+    public Guid Id { get; }
+
+    /// <summary>
+    /// 是否为有效令牌
+    /// </summary>
+    public bool IsValid => Id != Guid.Empty;
+
+    /// <summary>
+    /// 创建暂停令牌
+    /// </summary>
+    /// <param name="id">令牌 ID</param>
+    public PauseToken(Guid id)
+    {
+        Id = id;
+    }
+
+    /// <summary>
+    /// 创建无效令牌
+    /// </summary>
+    public static PauseToken Invalid => new(Guid.Empty);
+
+    public bool Equals(PauseToken other) => Id.Equals(other.Id);
+
+    public override bool Equals(object? obj) => obj is PauseToken other && Equals(other);
+
+    public override int GetHashCode() => Id.GetHashCode();
+
+    public static bool operator ==(PauseToken left, PauseToken right) => left.Equals(right);
+
+    public static bool operator !=(PauseToken left, PauseToken right) => !left.Equals(right);
+
+    public override string ToString() => $"PauseToken({Id})";
+}

GFramework.Core.Tests/extensions/AsyncExtensionsTests.cs

@@ -1,6 +1,6 @@
 using System.Diagnostics;
 using GFramework.Core.extensions;
-using GFramework.Core.Functional.Async;
+using GFramework.Core.functional.async;
 using NUnit.Framework;
 
 namespace GFramework.Core.Tests.extensions;

GFramework.Core.Tests/extensions/ResultExtensionsTests.cs

@@ -11,11 +11,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using GFramework.Core.Functional;
+using GFramework.Core.functional;
 using GFramework.Core.functional.result;
 using NUnit.Framework;
 
-namespace GFramework.Core.Tests.Extensions;
+namespace GFramework.Core.Tests.extensions;
 
 /// <summary>
 ///     ResultExtensions 扩展方法测试类

GFramework.Core.Tests/functional/OptionTests.cs

@@ -11,10 +11,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using GFramework.Core.Functional;
+using GFramework.Core.functional;
 using NUnit.Framework;
 
-namespace GFramework.Core.Tests.Functional;
+namespace GFramework.Core.Tests.functional;
 
 /// <summary>
 ///     Option&lt;T&gt; 类型测试类

GFramework.Core.Tests/functional/ResultTTests.cs

@@ -11,10 +11,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using GFramework.Core.Functional;
+using GFramework.Core.functional;
 using NUnit.Framework;
 
-namespace GFramework.Core.Tests.Functional;
+namespace GFramework.Core.Tests.functional;
 
 /// <summary>
 ///     Result&lt;A&gt; 泛型类型测试类

GFramework.Core.Tests/functional/ResultTests.cs

@@ -11,10 +11,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using GFramework.Core.Functional;
+using GFramework.Core.functional;
 using NUnit.Framework;
 
-namespace GFramework.Core.Tests.Functional;
+namespace GFramework.Core.Tests.functional;
 
 /// <summary>
 ///     Result 类型测试类