From 487f55fef6c902b7a5df9a137552fe733220a89d Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sun, 15 Feb 2026 20:55:00 +0800
Subject: [PATCH] =?UTF-8?q?refactor(state):=20=E9=87=8D=E6=9E=84=E5=BC=82?=
 =?UTF-8?q?=E6=AD=A5=E7=8A=B6=E6=80=81=E5=9F=BA=E7=B1=BB=E5=AE=9E=E7=8E=B0?=
 =?UTF-8?q?=E6=9E=B6=E6=9E=84=E4=B8=8A=E4=B8=8B=E6=96=87=E6=84=9F=E7=9F=A5?=
 =?UTF-8?q?=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 更新类注释说明IAsyncState继承自IState接口
- 添加SetContext和GetContext方法用于架构上下文管理
- 实现Destroy方法用于状态销毁和资源释放
- 显式实现IState同步方法并标记为已弃用
- 使用Obsolete特性标注同步方法并提示使用异步版本
- 恢复IAsyncState异步方法的正常实现
- 添加上下文未设置时的操作异常处理
---
 .../state/AsyncContextAwareStateBase.cs       | 81 +++++++++++--------
 1 file changed, 46 insertions(+), 35 deletions(-)

diff --git a/GFramework.Core/state/AsyncContextAwareStateBase.cs b/GFramework.Core/state/AsyncContextAwareStateBase.cs
index 368641e..ff99f21 100644
--- a/GFramework.Core/state/AsyncContextAwareStateBase.cs
+++ b/GFramework.Core/state/AsyncContextAwareStateBase.cs
@@ -21,7 +21,7 @@ namespace GFramework.Core.state;
 /// <summary>
 ///     上下文感知异步状态基类
 ///     提供基础的异步状态管理功能和架构上下文访问能力
-///     实现了IAsyncState和IContextAware接口
+///     实现了IAsyncState（继承IState）和IContextAware接口
 /// </summary>
 public class AsyncContextAwareStateBase : IAsyncState, IContextAware, IDisposable
 {
@@ -30,6 +30,49 @@ public class AsyncContextAwareStateBase : IAsyncState, IContextAware, IDisposabl
     /// </summary>
     private IArchitectureContext? _context;
 
+    // ============ IState 同步方法显式实现（隐藏 + 运行时保护） ============
+
+    /// <summary>
+    ///     同步进入状态（显式实现，不推荐直接调用）
+    ///     异步状态应该使用 OnEnterAsync 方法
+    /// </summary>
+    /// <exception cref="NotSupportedException">异步状态不支持同步操作</exception>
+    [Obsolete("This is an async state. Use OnEnterAsync instead.", error: true)]
+    void IState.OnEnter(IState? from)
+    {
+        throw new NotSupportedException(
+            $"Async state '{GetType().Name}' does not support synchronous OnEnter. " +
+            $"Use {nameof(OnEnterAsync)} instead.");
+    }
+
+    /// <summary>
+    ///     同步退出状态（显式实现，不推荐直接调用）
+    ///     异步状态应该使用 OnExitAsync 方法
+    /// </summary>
+    /// <exception cref="NotSupportedException">异步状态不支持同步操作</exception>
+    [Obsolete("This is an async state. Use OnExitAsync instead.", error: true)]
+    void IState.OnExit(IState? to)
+    {
+        throw new NotSupportedException(
+            $"Async state '{GetType().Name}' does not support synchronous OnExit. " +
+            $"Use {nameof(OnExitAsync)} instead.");
+    }
+
+    /// <summary>
+    ///     同步判断是否可以转换（显式实现，不推荐直接调用）
+    ///     异步状态应该使用 CanTransitionToAsync 方法
+    /// </summary>
+    /// <exception cref="NotSupportedException">异步状态不支持同步操作</exception>
+    [Obsolete("This is an async state. Use CanTransitionToAsync instead.", error: true)]
+    bool IState.CanTransitionTo(IState target)
+    {
+        throw new NotSupportedException(
+            $"Async state '{GetType().Name}' does not support synchronous CanTransitionTo. " +
+            $"Use {nameof(CanTransitionToAsync)} instead.");
+    }
+
+    // ============ IAsyncState 异步方法实现 ============
+
     /// <summary>
     ///     异步进入状态时调用的方法
     ///     子类可重写此方法以实现特定的异步状态进入逻辑（如加载资源、初始化数据等）
@@ -61,52 +104,20 @@ public class AsyncContextAwareStateBase : IAsyncState, IContextAware, IDisposabl
         return Task.FromResult(true);
     }
 
-    /// <summary>
-    ///     同步进入状态（不推荐使用）
-    ///     异步状态应该使用 OnEnterAsync 方法
-    /// </summary>
-    /// <exception cref="NotSupportedException">异步状态不支持同步操作</exception>
-    public virtual void OnEnter(IState? from)
-    {
-        throw new NotSupportedException(
-            $"This is an async state ({GetType().Name}). Use OnEnterAsync instead of OnEnter.");
-    }
-
-    /// <summary>
-    ///     同步退出状态（不推荐使用）
-    ///     异步状态应该使用 OnExitAsync 方法
-    /// </summary>
-    /// <exception cref="NotSupportedException">异步状态不支持同步操作</exception>
-    public virtual void OnExit(IState? to)
-    {
-        throw new NotSupportedException(
-            $"This is an async state ({GetType().Name}). Use OnExitAsync instead of OnExit.");
-    }
-
-    /// <summary>
-    ///     同步判断是否可以转换（不推荐使用）
-    ///     异步状态应该使用 CanTransitionToAsync 方法
-    /// </summary>
-    /// <exception cref="NotSupportedException">异步状态不支持同步操作</exception>
-    public virtual bool CanTransitionTo(IState target)
-    {
-        throw new NotSupportedException(
-            $"This is an async state ({GetType().Name}). Use CanTransitionToAsync instead of CanTransitionTo.");
-    }
-
     /// <summary>
     ///     设置架构上下文
     /// </summary>
     /// <param name="context">架构上下文实例</param>
     public void SetContext(IArchitectureContext context)
     {
-        _context = context;
+        _context = context ?? throw new ArgumentNullException(nameof(context));
     }
 
     /// <summary>
     ///     获取架构上下文
     /// </summary>
     /// <returns>架构上下文实例</returns>
+    /// <exception cref="InvalidOperationException">当上下文未设置时抛出</exception>
     public IArchitectureContext GetContext()
     {
         return _context ?? throw new InvalidOperationException(