feat,fix(core,docs): 完善核心模块代码注释并添加架构改进文档

- 为 core 目录下主要模块 (models, context, creator, base_api, exchange, executor) 添加了详细的类和方法 Docstring。
   - 新增 docs/架构改进.md 文件。

docs/架构改进.md

@@ -0,0 +1,80 @@
+# 自动化测试框架架构改进建议
+
+本文档基于对当前 `InterfaceAutoTest` 项目代码的深度分析，整理了针对框架稳定性、扩展性和易用性的架构改进建议。
+
+## 1. 并发执行支持 (Concurrency Support)
+
+### 现状问题
+当前 `VariableStore` 使用简单的文件读写 (`extract.yaml`) 来存储全局变量。
+- 在使用 `pytest-xdist` 进行多进程并发测试时，每个进程会加载独立的内存变量副本。
+- 测试结束写回文件时，不同进程会相互覆盖，导致变量提取丢失或数据不一致。
+
+### 改进方案
+1.  **引入分布式缓存 (推荐)**:
+    -   使用 **Redis** 作为变量存储后端。
+    -   Redis 天然支持原子操作和并发读写，能完美解决多进程数据共享问题。
+2.  **文件锁机制 (轻量级)**:
+    -   如果不引入 Redis，需在 `VariableStore` 的读写操作中增加 **文件锁 (File Lock)** (如使用 `filelock` 库)。
+    -   这会降低并发性能，但能保证数据一致性。
+
+## 2. 配置管理增强 (Configuration Management)
+
+### 现状问题
+`settings.py` 中存在大量硬编码配置（如 API 映射、日志路径），且缺乏对多环境（Dev/Test/Prod）的动态切换支持。
+
+### 改进方案
+1.  **多环境配置文件**:
+    -   建立 `config/` 目录，分离 `base_config.yaml`, `dev.yaml`, `prod.yaml`。
+    -   运行时通过环境变量 `ENV=prod` 加载对应配置并合并。
+2.  **环境变量集成**:
+    -   使用 `.env` 文件管理敏感信息和基础路径。
+    -   利用 `python-dotenv` 在项目启动时加载环境变量。
+
+## 3. 扩展性与钩子机制 (Extensibility & Hooks)
+
+### 现状问题
+`WorkflowExecutor` 的执行逻辑（准备 -> 请求 -> 后处理）是固定的。如果需要添加自定义逻辑（如请求签名加密、复杂的响应解密），目前很难插入。
+
+### 改进方案
+在执行器中引入 **Hooks (钩子)** 机制，允许注册回调函数：
+-   `before_request(request_data)`: 请求发出前调用，用于修改 Header、计算签名。
+-   `after_response(response)`: 收到响应后调用，用于全局解密、统一错误码判断。
+-   `before_case(context)` / `after_case(result)`: 用例级别的 setup/teardown。
+
+## 4. 安全性管理 (Security)
+
+### 现状问题
+敏感数据（如密码、SecretKey）可能明文写在 YAML 用例中。
+
+### 改进方案
+扩展 `Exchange` 类的变量替换逻辑，增加对环境变量的读取支持：
+-   **语法示例**: `password: ${ENV:DB_PASSWORD}`
+-   在运行时从系统环境变量中读取，避免将其提交到代码仓库。
+
+## 5. 可观测性增强 (Observability)
+
+### 现状问题
+虽然 `Session` 类中有日志记录，但在高并发或海量日志场景下，难以串联单个用例的完整执行链路。
+
+### 改进方案
+1.  **全链路 Trace ID**:
+    -   在用例开始执行时生成唯一的 `trace_id`。
+    -   将其注入到 `logging` 的 `Extra` 信息中，使其出现在每一行日志里。
+    -   同时将 `trace_id` 添加到 HTTP 请求头中（如 `X-Trace-Id`），便于服务端排查。
+2.  **结构化日志**:
+    -   考虑使用 JSON 格式输出日志，便于接入 ELK 等日志分析系统。
+
+## 6. 代码健壮性 (Robustness)
+
+### 修复建议
+-   **属性一致性**: 检查 `core/executor.py` 中的 PO 模式反射逻辑，确保属性访问与 `core/models.py` 定义一致。
+    -   `ApiActionModel` 定义了 `module` (alias=`class`)。
+    -   确保执行器中使用 `action.module` 而非 `action.api_class`，防止 `AttributeError`。
+
+---
+
+**实施路线图建议**:
+1.  优先修复代码健壮性问题（属性一致性）。
+2.  实施配置管理增强，便于环境隔离。
+3.  引入 Redis 或文件锁解决并发问题。
+4.  逐步完善 Hooks 和 Trace ID。

docs/重构总结.md

@@ -0,0 +1,22 @@
+本次重构核心总结：升级为“模型驱动+混合模式”的自动化测试框架我们本次重构的目标是将现有框架从基于字典（dict）的松散操作，升级为一个结构严谨、易于扩展的现代化测试框架。其核心包含以下四大支柱：1.
+核心驱动力：Pydantic 模型层•目标：用强类型、带校验的模型对象取代脆弱的字典操作。•实现：创建 commons/models/case_model.py
+文件，并定义 CaseInfo 类。•关键收益：•健壮性：在执行测试前，通过模型实例化，对 YAML
+文件中的字段、类型、结构进行严格校验，提前发现拼写错误或格式问题。•可维护性：代码中不再出现 case.get("request")
+这类“魔法字符串”，而是通过 case.request 这样的属性访问，IDE 可以提供智能提示和补全，代码更清晰、更安全。•灵活性：支持使用
+alias，让 YAML 中的字段名（如 validate）与模型属性名（如 validate_data）解耦，使模型设计更符合 Python 规范。2.
+执行模式：支持混合模式（Hybrid Mode）•目标：让框架同时适应简单的数据驱动测试和复杂的业务流测试。•实现：•YAML 驱动模式：保留并优化
+TestAPI 类。它负责扫描 tests/features/ 目录下的 test_*.yaml 文件，并动态生成 pytest 用例。此模式非常适合单接口、多场景的数据验证。•手动脚本模式：允许在
+tests/flows/ 目录下直接编写 test_*.py 脚本。开发者可以像写普通 pytest 用例一样，通过导入业务方法来编排复杂的、跨多个接口的业务流程。3.
+架构设计：清晰的三层分离•目标：遵循最佳实践，分离关注点，让框架结构清晰，避免混乱。•实现：•数据层 (YAML + Pydantic Model)
+：定义测试的输入数据和预期结果（是什么）。•业务层/服务层 (api/*.py)：将原始的 HTTP 请求封装成具有业务含义的方法，如
+api.auth.login()。它定义了如何执行具体业务操作（怎么做）。•测试层 (TestAPI 或 test_*.py)
+：作为“导演”，负责编排测试流程。它从数据层获取数据，调用业务层的方法执行动作，并进行最终断言（测什么）。4.
+上下文与状态：统一的会话与变量池•目标：打通 YAML 驱动和手动脚本之间的数据壁垒，实现真正的端到端流程测试。•实现：•所有测试（无论来源）共享同一个
+core.session.Session 实例，确保 Cookie、Header 等会话状态的连续性。•所有测试共享同一个 commons.exchange.Exchange
+实例（变量交换器）。•关键收益：手动脚本（.py）中通过登录获取的 token，可以被无缝地注入到后续的 YAML 用例中；反之，YAML 用例提取的
+ID 也能被后续的 .py 脚本使用。重构后的标准执行流程（以 YAML 为例）：1.加载：TestAPI 扫描并加载 test_*.yaml
+文件。2.数据驱动：DataDriver 将 YAML 文件内容解析为多个独立的、参数化的测试用例。3.执行：在 pytest 的 test_func 内部： a.
+变量替换：exchanger.replace() 将用例中的 ${variable} 替换为实际值。 b. 模型校验：CaseInfo(**replaced_case_data) 将替换后的字典实例化为
+CaseInfo 模型对象，完成数据校验。（这是与旧流程最核心的区别） c. 请求发送：使用模型对象的数据发送请求 session.request(**
+case.request.model_dump())。 d. 变量提取：exchanger.extract() 从响应中提取数据，并存入全局变量池。 e.
+断言：validator.assert_all(case.validate_data) 使用模型中的断言数据进行校验。