feat(docs,page_objects): 完善文档以及测试用例演示

- 新增 AndroidSDK环境配置指南.md, 常用参数.md
- 更新 README.md
- 优化 wan_android_home.py, wan_android_project.py
- 其他优化

utils/decorators.py

@@ -29,8 +29,23 @@ indent_var = ContextVar("indent_level", default=0)
 
 class StepTracer(ContextDecorator):
     """
-    既是装饰器也是上下文管理器
-    职责：负责计时、日志格式化和异常记录
+    一个结合了上下文管理器和装饰器功能的追踪器。
+
+    主要职责是记录一个代码块或函数的执行情况，包括：
+    - 开始和结束的日志，并根据上下文进行缩进，形成层级结构。
+    - 计算并记录执行耗时。
+    - 捕获并记录执行期间发生的异常。
+
+    可作为上下文管理器使用:
+    with StepTracer("处理数据"):
+        ...
+
+    也可作为装饰器的一部分（通过 step_trace 工厂函数）。
+
+    Attributes:
+        step_desc (str): 对当前步骤或操作的描述。
+        source (str): 日志记录器的名称。
+        func_info (str, optional): 关联的函数信息，用于日志输出。
     """
 
     def __init__(self, step_desc, source='wrapper', func_info=None):
@@ -40,6 +55,9 @@ class StepTracer(ContextDecorator):
         self.start_t = None
 
     def __enter__(self):
+        """
+        进入上下文，记录步骤开始，并增加日志缩进层级。
+        """
         # 1. 获取当前层级并计算前缀
         level = indent_var.get()
         # 使用 "  " (空格) 或 "│ " 作为缩进符号
@@ -55,6 +73,10 @@ class StepTracer(ContextDecorator):
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        退出上下文，记录步骤结束（成功或失败）、耗时，并恢复日志缩进层级。
+        如果发生异常，会记录异常信息但不会抑制它，异常会继续向上传播。
+        """
         # 3. 恢复层级，层级 -1
         level = indent_var.get() - 1
         indent_var.set(level)
@@ -83,7 +105,23 @@ class StepTracer(ContextDecorator):
 
 def resolve_wait_method(func):
     """
-    装饰器：将字符串形式的等待条件解析为可调用的 EC 对象
+    装饰器：将字符串形式的等待条件解析为可调用的 Expected Condition (EC) 对象。
+
+    这个装饰器用于修饰那些接受一个 `method` 参数的方法（通常是等待方法）。
+    如果 `method` 是一个字符串，它会尝试将其解析为一个预定义的 `expected_conditions`。
+
+    字符串格式支持:
+    - "key": 直接映射到一个无参数的 EC。
+    - "key:arg1,arg2": 映射到一个需要参数的 EC，参数以逗号分隔。
+
+    解析逻辑委托给 `core.custom_expected_conditions.get_condition` 函数。
+    如果解析失败，会记录错误并重新抛出异常。
+
+    Args:
+        func (Callable): 被装饰的函数。
+
+    Returns:
+        Callable: 包装后的函数。
     """
 
     @wraps(func)
@@ -113,10 +151,22 @@ def resolve_wait_method(func):
 
 def action_screenshot(func):
     """
-    显式截图装饰器：在方法执行前（或后）立即触发 BasePage 的截图逻辑。
-    用于记录关键操作后的页面状态。
-    """
+    装饰器：在被装饰方法成功执行后，自动触发截图。
 
+    主要用于UI自动化测试中，记录关键业务操作执行后的页面状态。
+    它会调用被装饰对象（通常是 Page Object）的 `attach_screenshot_bytes` 方法。
+
+    注意:
+    - 截图操作在原方法成功返回后执行。
+    - 被装饰的实例 (`self`) 必须拥有 `attach_screenshot_bytes` 方法。
+    - 如果截图失败，会记录一个警告日志，但不会影响主流程。
+
+    Args:
+        func (Callable): 被装饰的函数。
+
+    Returns:
+        Callable: 包装后的函数。
+    """
     @wraps(func)
     def wrapper(self, *args, **kwargs):
         # 1. 正常执行原方法
@@ -139,7 +189,21 @@ def action_screenshot(func):
 
 
 def _format_params(func, *args, **kwargs):
-    """辅助函数：专门处理参数过滤和格式化"""
+    """
+    辅助函数：格式化函数调用的参数，以便清晰地记录日志。
+
+    它会检查函数的签名，并执行以下操作：
+    1. 过滤掉实例方法或类方法中的 `self` 或 `cls` 参数。
+    2. 将位置参数和关键字参数格式化为一个可读的字符串。
+
+    Args:
+        func (Callable): 目标函数。
+        *args: 传递给函数的位置参数。
+        **kwargs: 传递给函数的关键字参数。
+
+    Returns:
+        str: 格式化后的参数字符串，例如 "arg1, kwarg='value'"。
+    """
     sig = inspect.signature(func)
     params = list(sig.parameters.values())
     display_args = args[1:] if params and params[0].name in ('self', 'cls') else args
@@ -153,12 +217,30 @@ def _format_params(func, *args, **kwargs):
 
 def step_trace(step_desc="", source='wrapper'):
     """
-    通用执行追踪装饰器：
-    1. 智能识别并过滤 self/cls 参数
-    2. 记录入参、出参、耗时
-    3. 异常自动捕获并记录
-    """
+    装饰器工厂：创建一个通用的执行追踪装饰器。
 
+    此装饰器利用 `StepTracer` 上下文管理器来提供结构化的日志，记录
+    函数的调用、参数、执行耗时和任何发生的异常。
+
+    功能包括:
+    - 自动格式化并记录函数的输入参数（会智能过滤 `self` 和 `cls`）。
+    - 使用 `StepTracer` 生成带缩进的层级式日志，清晰展示调用栈。
+    - 记录每个被追踪步骤的开始、成功/失败状态以及执行耗时。
+    - 捕获并记录异常，但不会抑制异常，保证上层逻辑可以处理。
+
+    用法:
+        @step_trace("执行用户登录操作")
+        def login(username, password):
+            ...
+
+    Args:
+        step_desc (str, optional): 对被装饰函数所执行操作的描述。
+                                   如果为空，日志中将只显示函数信息。
+        source (str, optional): 指定日志记录器的名称。默认为 'wrapper'。
+
+    Returns:
+        Callable: 一个可以装饰函数的装饰器。
+    """
     def decorator(func):
         @wraps(func)
         def wrapper(*args, **kwargs):