df-test-framework 4.5.0__tar.gz → 4.7.0__tar.gz

{df_test_framework-4.5.0 → df_test_framework-4.7.0}/CHANGELOG.md

@@ -5,6 +5,43 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.7.0] - 2026-05-19
+
+### ✨ 新增
+
+- **`RuntimeContext.metadata` 字段**：`dict[str, Any]` 类型，默认空字典；用于携带跨进程/跨插件的平台业务上下文（`tenant_id`、`execution_id` 等），避免将业务键值编码到 scope 字符串中
+- **`RuntimeContext.with_metadata(**kwargs)`**：返回 metadata 已合并的新 RuntimeContext（不可变，新键覆盖同名旧键）；`with_scope()` / `with_overrides()` 自动传播 metadata
+- **`RuntimeContext.register_async_database(name, connection_string, **kwargs)`**：按名称注册多个 AsyncDatabase 连接池（`SingletonProvider` 延迟创建），支持多数据库场景（如 OMS DbStepExecutor 按 URL 缓存）；同名重复注册自动 shutdown 旧实例
+- **`RuntimeContext.get_async_database(name=None)`**：按名称获取已注册的 AsyncDatabase 实例；`name=None` 时返回由 `settings.db` 配置的默认实例
+- **`RuntimeBuilder.with_metadata(metadata)`**：构建时注入初始 metadata
+
+## [4.6.1] - 2026-05-18
+
+### ✨ 新增
+
+- **`CaseContext.skip` / `.xfail`**：YAML stage 元数据支持 `skip: "原因"` / `xfail: "原因"`（或 `true`），自动转换为对应 pytest mark，无需在 conftest 手写
+- **`CaseContext.seed`（YAML 级别）**：`tests.{stage}.seed: 42` 设置 case 级别随机种子；CLI `--seed` 全局覆盖优先级更高
+- **`--case-file` CLI 选项**：按数据文件路径过滤（部分匹配），多数据集项目可精准指定只跑某个文件的 case
+- **pytest 插件自动 Allure**：`pytest_runtest_setup` 钩子自动调用 `CaseReporter.attach_to_allure()`，写标题/标签/附件，测试函数无需手动调用
+- **pytest 插件自动 seed**：有 seed 的 case 自动 `random.seed()` + `Faker.seed()`（Faker 不可用时静默跳过）
+- **`pytest_collection_modifyitems`**：自动清除因空参数过滤产生的 `NotSetType` 占位用例，避免空壳测试出现在报告
+- **复现命令补充 `--seed`**：失败用例有 seed 时复现命令自动附带 `--seed=N`
+- **`DataAssetResolver` 路径安全**：`resolve()` / `resolve_file()` 禁止绝对路径和 `../` 路径逃逸，违规时 `raise ValueError`
+- **脚手架 `models/cases/`**：`df-test init` 自动创建 `src/{project}/models/cases/__init__.py`，作为场景领域模型的标准目录
+
+## [4.6.0] - 2026-05-18
+
+### ✨ 新增
+
+- **测试数据管线**：从 YAML/JSON 到 pytest 参数化的完整基础设施（`testing/data/pipeline/`）
+  - `case_dataset(path, model, root_key, id_field)` — 工厂函数，延迟加载 case 文件，支持 dict-of-dicts（key=case_id）和 list-of-dicts 两种 YAML 格式
+  - `CaseContext[T]` — 泛型 case 上下文冻结 dataclass，承载 domain data + stage/title/tags/marks/timeout/seed/source_path/raw
+  - `CaseDataset[T].parametrize(metafunc, fixture_name, stage)` — pytest_generate_tests 一行注入，读取 CLI 过滤选项
+  - `CaseDataset[T].all(stage)` — 不经参数化直接返回 CaseContext 列表，适合脚本/单元测试场景
+  - `DataAssetResolver` — 自动发现项目根（pyproject.toml + tests/），统一解析 `tests/data/fixtures/` 与 `tests/data/files/`
+  - `CaseReporter.attach_to_allure(ctx)` — 写 Allure 动态标题、case_id/stage 标签、tags，附 case 元信息 JSON 附件
+- **pytest 插件 `df_test_framework_data_pipeline`**：全局注册 `--case`、`--case-stage`、`--case-tag`、`--seed` CLI 过滤选项；测试失败时自动在报告 section 输出最小复现命令
+
 ## [4.5.0] - 2026-05-12
 
 ### ✨ 新增

{df_test_framework-4.5.0 → df_test_framework-4.7.0}/CLAUDE.md

@@ -8,8 +8,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.2.2
-- **更新时间**: 2026-04-15
+- **版本**: v4.7.0
+- **更新时间**: 2026-05-19
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.5.0 → df_test_framework-4.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.5.0
+Version: 4.7.0
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework
@@ -22,7 +22,7 @@ Requires-Python: >=3.12
 Requires-Dist: allure-pytest>=2.13.0
 Requires-Dist: assertpy>=1.1
 Requires-Dist: faker>=38.2.0
-Requires-Dist: filelock>=3.20.1
+Requires-Dist: filelock>=3.29.0
 Requires-Dist: freezegun>=1.5.0
 Requires-Dist: h2>=4.3.0
 Requires-Dist: hpack>=4.1.0
@@ -40,15 +40,15 @@ Requires-Dist: pymysql>=1.1.0
 Requires-Dist: pypinyin>=0.53.0
 Requires-Dist: pytest-asyncio>=1.3.0
 Requires-Dist: pytest-timeout>=2.2.0
-Requires-Dist: pytest==9.0.3
+Requires-Dist: pytest>=9.0.3
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: redis>=5.0.0
-Requires-Dist: requests>=2.32.4
+Requires-Dist: requests>=2.34.2
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: structlog>=25.4.0
-Requires-Dist: urllib3>=2.6.0
+Requires-Dist: urllib3>=2.7.0
 Provides-Extra: all
 Requires-Dist: aiomysql>=0.2.0; extra == 'all'
 Requires-Dist: aiosqlite>=0.20.0; extra == 'all'

{df_test_framework-4.5.0 → df_test_framework-4.7.0}/docs/guides/fixture_chain_pattern.md

@@ -6,6 +6,12 @@
 
 ---
 
+本文专注“运行期前置造数链”。如果要从数据文件、Case Model、pytest 参数化一路设计到
+前置准备、清理和报告，请先阅读
+[测试数据管线设计指南](test_data_pipeline_design.md)。
+
+---
+
 ## 目录
 
 - [问题：为什么需要这个范式](#问题为什么需要这个范式)

{df_test_framework-4.5.0 → df_test_framework-4.7.0}/docs/guides/test_data.md

@@ -6,6 +6,16 @@
 
 ---
 
+## 阅读路径
+
+如果只需要加载 JSON / CSV / YAML 或生成假数据，阅读本文即可。
+
+如果要设计完整的数据驱动测试链路，包括 case 元信息、pytest 参数化、前置造数、
+cleanup、文件资产和报告，请阅读
+[测试数据管线设计指南](test_data_pipeline_design.md)。
+
+---
+
 ## 概述
 
 测试数据工具包含三大模块：

df_test_framework-4.7.0/docs/guides/test_data_pipeline_design.md

@@ -0,0 +1,389 @@
+# 测试数据管线设计指南
+
+> 最后更新: 2026-05-15
+> 适用范围: 参数化、数据驱动、测试造数、前置准备、清理和报告
+
+本文记录 df-test-framework 后续在测试数据方向的标准设计。它不是替代
+`test_data.md` 或 `fixture_chain_pattern.md`，而是把二者串成一条完整的数据管线：
+
+```text
+静态场景数据 -> Case Model -> 参数矩阵 -> 前置准备 -> 测试执行 -> 断言 -> 清理 -> 报告
+```
+
+## 一句话结论
+
+框架应该提供“测试数据管线基础设施”，业务项目负责“领域数据和领域造数逻辑”。
+
+框架负责：
+
+- 数据文件定位和加载。
+- Case 元信息、参数化、过滤和 pytest id。
+- 文件资产路径解析。
+- 随机 seed 管理。
+- 前置准备协议。
+- cleanup 挂钩。
+- Allure / 日志中的 case 元信息记录。
+- 脚手架模板和规范文档。
+
+业务项目负责：
+
+- 领域模型，例如订单、合同、会签、客户、产品。
+- 领域 YAML / JSON / CSV 数据。
+- 领域 API / UI Actions。
+- 领域造数步骤，例如创建客户、生成合同、提交审批。
+- 领域断言，例如 DB 字段、页面结果、业务状态。
+
+## 业界模式
+
+主流自动化测试框架大致都分为同一组能力：
+
+| 关注点 | 业界常见做法 | 框架对应方向 |
+| --- | --- | --- |
+| 参数化 | pytest `parametrize` / `pytest_generate_tests`，JUnit `ParameterizedTest`，TestNG `DataProvider` | `parametrize_cases()` |
+| 昂贵前置 | fixture 间接参数化，setup fixture | `Provisioner` 协议 |
+| 动态造数 | factory / builder / seed data | `Factory` / `DataGenerator` / 项目 factory |
+| 清理 | teardown、transaction rollback、cleanup manager | `cleanup` / `uow` / `data_preparer` |
+| UI 登录态 | storage state、role based context、worker auth state | `AuthSetup` / `ui_client(storage_state=...)` |
+| 外部依赖 | Testcontainers、临时 DB、隔离服务 | 后续可选增强 |
+
+参考资料：
+
+- pytest 参数化: <https://docs.pytest.org/en/stable/how-to/parametrize.html>
+- pytest indirect parametrization: <https://docs.pytest.org/en/stable/example/parametrize.html>
+- Playwright 认证态复用: <https://playwright.dev/docs/auth>
+- factory_boy: <https://factory-boy.readthedocs.io/>
+- Testcontainers: <https://docs.docker.com/testcontainers/>
+
+## 数据分类
+
+测试数据不要混成一个“大 data 目录”。标准分为五类：
+
+| 类型 | 推荐位置 | 说明 |
+| --- | --- | --- |
+| 场景主数据 | `tests/data/fixtures/{domain}/` | YAML / JSON / CSV，表达业务场景和预期 |
+| 文件资产 | `tests/data/files/{domain}/` | 上传、导入、下载比对文件 |
+| 环境配置 | `config/` | 地址、开关、环境差异 |
+| 敏感值 | `config/secrets/` 或环境变量 | 密码、token、cookie、私钥 |
+| 动态造数 | `src/{project}/fixtures/*_chain.py` | 运行期通过 API / DB / UI 准备数据 |
+
+重要边界：
+
+- CI 主输入优先是文本数据文件，不依赖二进制 Excel。
+- Excel 可以作为业务维护视图，但需要先转换为 YAML / JSON 再进入测试。
+- Apifox / OpenAPI 导出是请求模板来源，不是业务场景列表。
+- Actions / API Flow 不在 import 阶段读取数据文件。
+- 绝对路径不进入 case 数据，文件资产必须由框架或项目 resolver 解析。
+
+## 标准数据流
+
+```mermaid
+flowchart TD
+  A["tests/data/fixtures/{domain}/*.yaml"] --> B["CaseLoader"]
+  B --> C["Case Model / Schema"]
+  C --> D["CaseContext"]
+  D --> E["parametrize_cases / pytest_generate_tests"]
+  E --> F["test function"]
+  F --> G["Provisioner / fixture chain"]
+  G --> H["API / UI / DB 准备"]
+  H --> I["Actions / API Flow"]
+  I --> J["assertions"]
+  J --> K["cleanup / uow rollback"]
+  D --> L["Allure case metadata"]
+  G --> L
+```
+
+运行期要遵守两个阶段：
+
+1. 收集阶段只做轻量工作：读取数据、校验 schema、生成 pytest 参数。
+2. 执行阶段才做昂贵前置：API 造数、DB 写入、UI 操作、外部服务调用。
+
+这与 pytest 的 indirect parametrization 思路一致：昂贵 setup 应放在 fixture 执行期，
+而不是 collection 期。
+
+## 推荐对象模型
+
+框架后续可以提供通用对象，业务项目只补领域模型。
+
+```python
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class CaseContext(Generic[T]):
+    """测试场景上下文。"""
+
+    case_id: str
+    data: T
+    source_path: Path
+    stage: str | None = None
+    title: str | None = None
+    tags: tuple[str, ...] = ()
+    marks: tuple[str, ...] = ()
+    seed: int | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+```
+
+业务项目仍然定义自己的领域模型：
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class OrderCase:
+    case_id: str
+    customer_name: str
+    products: tuple[str, ...]
+    expected_status: str
+```
+
+## 参数化标准
+
+推荐测试入口只消费一个 case 对象或 context 对象：
+
+```python
+def test_create_order(order_case: CaseContext[OrderCase], order_actions):
+    result = order_actions.create(order_case.data)
+    assert result.status == order_case.data.expected_status
+```
+
+参数化层应该统一处理：
+
+- pytest id：默认 `stage-case_id` 或 `case_id`。
+- `marks`：从数据映射为 pytest mark。
+- `skip` / `xfail`：从数据或 CLI 过滤策略进入 pytest 参数。
+- `tags`：用于 `--case-tag` 过滤。
+- `stage`：用于同一 case 在不同阶段复用。
+- `seed`：用于可复现随机。
+
+未来框架 API 可以长这样：
+
+```python
+from df_test_framework.testing.data.pipeline import case_dataset
+
+
+direct_cases = case_dataset(
+    path="countersign/direct_cases.yaml",
+    model=DirectCountersignInput,
+    root_key="cases",
+    id_field="case_id",
+)
+
+
+def pytest_generate_tests(metafunc):
+    direct_cases.parametrize(
+        metafunc,
+        fixture_name="direct_case",
+        stage="approving",
+    )
+```
+
+更进一步可以提供装饰器：
+
+```python
+@data_cases(
+    path="countersign/direct_cases.yaml",
+    model=DirectCountersignInput,
+    stages=("approving", "archive"),
+)
+def test_direct_countersign(case):
+    ...
+```
+
+装饰器方案体验更好，但 pytest hook 方案更透明。框架应优先落透明的底层 API，
+再考虑装饰器糖。
+
+## 前置准备标准
+
+前置准备分三层：
+
+```text
+step_*        单个原子业务动作
+provision_*   组合一段业务链路
+fixture        pytest 暴露入口
+```
+
+标准写法：
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CustomerData:
+    customer_id: str
+    customer_name: str
+
+
+def step_create_customer(customer_api, case, cleanup) -> CustomerData:
+    response = customer_api.create(name=case.customer_name)
+    customer_id = response["data"]["id"]
+    cleanup.add("customers", customer_id)
+    return CustomerData(customer_id=customer_id, customer_name=case.customer_name)
+
+
+def provision_order_case(order_case, customer_api, cleanup) -> PreparedOrderCase:
+    customer = step_create_customer(customer_api, order_case, cleanup)
+    return PreparedOrderCase(case=order_case, customer=customer)
+```
+
+规则：
+
+- `step_*` 函数公开签名，不加下划线。
+- `step_*` 成功创建数据后立刻注册 cleanup。
+- 返回 frozen dataclass，不返回裸 dict。
+- 能通过 API 造数就不通过 UI 造数。
+- DB 直写只用于基础数据或无 API 的场景，并优先走 `uow` / `prepare_data`。
+- UI 前置优先使用 `storage_state`，复杂 UI 状态才考虑 fixture chain。
+
+## 框架能力设计
+
+### CaseLoader
+
+职责：
+
+- 基于项目根目录解析 `tests/data/fixtures`。
+- 支持 YAML / JSON / CSV。
+- 支持 `root_key`、`id_field`、`include`、`exclude`。
+- 支持 schema/model 校验。
+- 报错时包含文件路径、case_id、字段路径。
+
+### CaseContext
+
+职责：
+
+- 统一承载 case 元信息。
+- 给 Allure、日志、过滤器、fixture chain 使用。
+- 支持原始数据 `raw`，便于排查数据转换问题。
+
+### CaseMatrix / parametrize_cases
+
+职责：
+
+- 生成 pytest 参数。
+- 处理 `marks`、`ids`、`skip`、`xfail`。
+- 支持 `stage` 和 `tag` 过滤。
+- 支持 CLI 参数：`--case`、`--case-tag`、`--case-stage`、`--case-file`、`--seed`。
+
+### DataAssetResolver
+
+职责：
+
+- 解析 `tests/data/files/{domain}` 下的相对路径。
+- 禁止 case 数据使用本机绝对路径。
+- 报告缺失文件。
+- 支持调试时输出实际解析路径。
+
+### Provisioner 协议
+
+职责：
+
+- 标准化运行期前置准备。
+- 将 `CaseContext[T]` 转成 `PreparedCase[T]`。
+- 自动接入 cleanup 和 Allure step。
+- 将前置准备失败归因到 case，而不是普通 fixture error。
+
+### CaseReporter
+
+职责：
+
+- 在 Allure 附件中记录 case_id、title、stage、tags、source_path、seed。
+- 记录脱敏后的关键输入。
+- 失败时输出数据来源和复现命令。
+
+## 不建议进入框架的内容
+
+这些必须留在业务项目：
+
+- 业务实体字段。
+- 业务 API 调用顺序。
+- 业务 DB 表结构。
+- Apifox 某个请求名或中文接口名。
+- 某个系统的登录账号、角色、流程节点。
+- Excel 模板列定义。
+
+框架可以提供模板和协议，但不内置任何业务假设。
+
+## 落地路线
+
+### 阶段 1：文档和脚手架
+
+- 补充本文档。
+- 在项目模板中生成 `tests/data/fixtures/.gitkeep`、`tests/data/files/.gitkeep`。
+- 在 fixture chain 模板中补充 CaseContext 风格示例。
+
+### 阶段 2：最小 API
+
+新增包：
+
+```text
+src/df_test_framework/testing/data/pipeline/
+  __init__.py
+  context.py
+  dataset.py
+  resolver.py
+  parametrize.py
+```
+
+最小能力：
+
+- `CaseContext`
+- `DataAssetResolver`
+- `case_dataset()`
+- `CaseDataset.parametrize()`
+
+### 阶段 3：CLI 过滤
+
+- 增加 `--case`、`--case-tag`、`--case-stage`、`--seed`。
+- 支持逗号分隔和多次传参。
+- 支持失败时输出复现命令。
+
+### 阶段 4：报告和诊断
+
+- 自动写入 Allure case metadata。
+- 支持脱敏后的 case 输入附件。
+- 支持数据源路径和 seed 记录。
+
+### 阶段 5：高级能力
+
+- Pydantic / JSON Schema 集成。
+- Excel 导入导出模板工具。
+- Testcontainers / 临时依赖环境的可选集成。
+- 数据依赖图可视化。
+
+## 与现有能力的关系
+
+| 现有能力 | 保留 | 新管线如何使用 |
+| --- | --- | --- |
+| `YAMLLoader` / `JSONLoader` / `CSVLoader` | 保留 | 作为底层 loader |
+| `DataGenerator` | 保留 | 生成动态字段和 seed 数据 |
+| `Factory` / `ModelFactory` | 保留 | 构建领域对象默认值 |
+| `cleanup` | 保留 | 前置准备成功后注册清理 |
+| `uow` / `prepare_data` | 保留 | DB 前置准备和事务管理 |
+| `fixture_chain_pattern` | 保留 | 作为 Provisioner 的项目侧范式 |
+| `AuthSetup` / `ui_client` | 保留 | UI 登录态和多角色入口 |
+
+## 反模式
+
+- 测试函数里直接读取 YAML / Excel。
+- Actions 在 import 阶段读取数据文件。
+- 用 Excel 作为 CI 唯一主数据源。
+- 在 case 数据里写本地绝对路径。
+- 动态随机没有 seed。
+- 造数成功但 cleanup 留给测试函数手动注册。
+- 在 `pytest_generate_tests` 中执行 API / DB / UI 前置。
+- 业务项目为了参数化复制多个几乎一样的测试函数。
+
+## 设计原则
+
+1. 收集期轻，执行期重。
+2. 数据表达业务意图，代码表达业务动作。
+3. 主数据文本化，二进制文件只做资产。
+4. 随机必须可复现。
+5. 造数和清理是一个原子操作。
+6. 框架提供协议和通用工具，业务项目保留领域判断。
+7. 先用透明 API 落地，再补装饰器语法糖。

df_test_framework-4.7.0/docs/releases/v4.6.0.md

@@ -0,0 +1,173 @@
+# v4.6.0 发布说明
+
+**发布日期**: 2026-05-18
+**版本类型**: MINOR — 新增独立功能模块（测试数据管线）
+
+---
+
+## 概述
+
+v4.6.0 引入**测试数据管线**（`testing/data/pipeline/`），提供从 YAML/JSON 到 pytest 参数化的完整基础设施。消费方项目可用声明式 YAML 文件管理 case 数据，通过一行 `parametrize()` 注入多场景测试，并享受 CLI 过滤、Allure 自动上报、失败复现命令等能力。
+
+---
+
+## 新增功能
+
+### 1. `case_dataset()` — 数据集工厂
+
+```python
+from df_test_framework.testing.data.pipeline import case_dataset, CaseContext
+
+my_cases = case_dataset(
+    path="countersign/direct_cases.yaml",  # 相对 tests/data/fixtures/
+    model=DirectCountersignInput,          # dataclass 领域模型，None 时保留 dict
+)
+```
+
+- 延迟加载：模块导入时不读文件，首次 `parametrize` / `all()` 调用时才加载
+- 支持两种 YAML 格式：
+  - **dict-of-dicts**（推荐）：`cases: {case_001: {fields..., tests: {stage: {meta}}}}`
+  - **list-of-dicts**：`cases: [{case_id: case_001, fields..., tests: {...}}]`
+- `root_key` 默认 `"cases"`，可传 `None` 使用文件根节点
+- `id_field` 仅 list 格式需要指定（默认 `"case_id"`）
+- 相对路径基于 `tests/data/fixtures/`，也可传 `base_dir` 自定义
+
+### 2. `CaseContext[T]` — 泛型 case 上下文
+
+```python
+@dataclass(frozen=True)
+class CaseContext[T]:
+    case_id: str
+    data: T                    # 领域模型实例（或 dict）
+    stage: str | None          # 测试阶段名
+    title: str | None          # Allure 标题
+    tags: tuple[str, ...]      # 标签（用于 --case-tag 过滤）
+    marks: tuple[str, ...]     # pytest marks
+    timeout: int | None        # 超时秒数
+    seed: int | None           # 随机种子
+    source_path: Path | None   # 数据文件路径
+    raw: dict                  # 原始 YAML dict
+
+    @property
+    def id(self) -> str: ...   # pytest 参数 id：stage-case_id 或 case_id
+```
+
+### 3. `CaseDataset.parametrize()` — pytest 参数化注入
+
+```python
+# conftest.py 或测试文件顶层
+def pytest_generate_tests(metafunc):
+    my_cases.parametrize(metafunc, "approving_case", stage="approving")
+    my_cases.parametrize(metafunc, "archive_case", stage="archive")
+
+def test_approving(approving_case: CaseContext[DirectCountersignInput]):
+    case = approving_case.data
+    allure.dynamic.title(approving_case.title)
+```
+
+- `stage=None` 时不按阶段过滤，所有 case 均参与
+- 自动读取 `--case` / `--case-stage` / `--case-tag` CLI 过滤选项
+- CLI 指定的 stage 与当前 stage 不符时，该 fixture 产出空集（避免误跳）
+
+### 4. CLI 过滤选项（全局 pytest 插件）
+
+```bash
+pytest --case=case_001                # 按 case_id 过滤（可多次传入或逗号分隔）
+pytest --case case_001 --case case_002
+pytest --case-stage=approving         # 按阶段过滤
+pytest --case-tag=smoke,regression    # 按标签过滤
+pytest --seed=42                      # 固定随机种子
+```
+
+失败时报告自动追加复现命令：
+
+```
+数据管线: 复现命令: pytest --case=case_001 --case-stage=approving 'tests/test_countersign.py'
+```
+
+### 5. `CaseReporter.attach_to_allure()` — Allure 集成
+
+```python
+def test_approving(approving_case: CaseContext[DirectCountersignInput]):
+    CaseReporter.attach_to_allure(approving_case)  # 一行搞定
+    # 效果：
+    # - allure.dynamic.title(approving_case.title)
+    # - allure.dynamic.label("case_id", ...)
+    # - allure.dynamic.label("stage", ...)
+    # - allure.dynamic.tag(*approving_case.tags)
+    # - 附件 case_meta.json
+```
+
+allure 不可用时静默跳过，不影响测试运行。
+
+### 6. `DataAssetResolver` — 资产路径解析
+
+```python
+from df_test_framework.testing.data.pipeline import DataAssetResolver
+
+resolver = DataAssetResolver()                       # 自动发现项目根
+path = resolver.resolve("countersign/direct.yaml")   # tests/data/fixtures/...
+file = resolver.resolve_file("uploads/sample.pdf")   # tests/data/files/...
+```
+
+---
+
+## YAML 标准格式
+
+```yaml
+cases:
+  case_001:
+    customer_name: 张三
+    amount: 1000.00
+    tests:
+      approving:
+        title: "审批-正常流程"
+        timeout: 60
+        marks: [smoke]
+        tags: [regression, api]
+      archive:
+        title: "归档-正常"
+        timeout: 30
+  case_002:
+    customer_name: 李四
+    amount: 0.01
+    tests:
+      approving:
+        title: "审批-最小金额边界"
+        marks: [edge_case]
+```
+
+---
+
+## 迁移指南
+
+无破坏性变更，全量向后兼容。现有数据驱动测试无需修改。
+
+如需迁移现有手动参数化测试：
+
+1. 将 case 数据移至 `tests/data/fixtures/<domain>/cases.yaml`
+2. 创建领域模型 dataclass（可选）
+3. 用 `case_dataset()` 替换 `@pytest.mark.parametrize` 的数据列表
+4. 在 `pytest_generate_tests` 调用 `.parametrize()`
+5. 测试函数参数换成 `CaseContext[Model]`，`allure.dynamic.title()` 换成 `CaseReporter.attach_to_allure(ctx)`
+
+---
+
+## 文件变更
+
+| 文件 | 变更 |
+|------|------|
+| `src/df_test_framework/testing/data/pipeline/context.py` | 新增 `CaseContext[T]` |
+| `src/df_test_framework/testing/data/pipeline/dataset.py` | 新增 `CaseDataset[T]`, `case_dataset()` |
+| `src/df_test_framework/testing/data/pipeline/loader.py` | 新增 `load_cases()`, `_build_model()` |
+| `src/df_test_framework/testing/data/pipeline/resolver.py` | 新增 `DataAssetResolver` |
+| `src/df_test_framework/testing/data/pipeline/reporter.py` | 新增 `CaseReporter` |
+| `src/df_test_framework/testing/data/pipeline/__init__.py` | 新增模块入口 |
+| `src/df_test_framework/testing/plugins/data_pipeline.py` | 新增 pytest 插件 |
+| `src/df_test_framework/testing/data/__init__.py` | 导出管线 API |
+| `pyproject.toml` | 注册 pytest11 入口点 |
+| `tests/testing/data/pipeline/test_pipeline.py` | 22 项单元测试 |
+| `docs/guides/test_data_pipeline_design.md` | 设计文档 |
+| `docs/guides/test_data.md` | 更新阅读路径 |
+| `docs/guides/fixture_chain_pattern.md` | 添加管线引用 |
+| `cli/templates/project/fixture_chain_example.py` | 添加集成示例模板 |