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

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

@@ -5,6 +5,49 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.7.1] - 2026-05-22
+
+### 🐛 修复
+
+- **Allure 报告重复记录**（`testing/fixtures/allure.py`）：`_auto_allure_observer` autouse fixture 在每次测试结束后未取消 EventBus 订阅，导致 handler 随测试数量线性累积，后续测试的每个 HTTP/DB 事件被 N 个遗留 observer 重复写入报告。现改为在 `finally` 块中逐一 unsubscribe，彻底消除重复。
+
+## [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.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.5.0
+Version: 4.7.1
 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.1}/README.md

@@ -1,7 +1,7 @@
 # DF Test Framework
 
-> **版本**: v4.0.0
-> **更新时间**: 2026-01-16
+> **版本**: v4.7.0
+> **更新时间**: 2026-05-19
 > 简单、强大、可扩展的现代化 Python 测试自动化框架
 
 [![PyPI version](https://img.shields.io/pypi/v/df-test-framework.svg)](https://pypi.org/project/df-test-framework/)
@@ -14,6 +14,19 @@
 
 ### 当前版本亮点 ⚡🔭📊
 
+**🆕 v4.7.0 Bootstrap 多数据库 + 平台元数据**：
+- ✨ **`register_async_database(name, url)`** - 按名称注册多个异步连接池，多数据库场景（OMS/BPM 等）
+- ✨ **`get_async_database(name)`** - 每次返回绑定当前 RuntimeContext 的视图，事件携带 scope/metadata
+- ✨ **`RuntimeContext.metadata`** - 跨插件/跨进程平台上下文（tenant_id、execution_id 等）
+- ✨ **`with_metadata(**kwargs)`** - 不可变合并，与 `with_scope()` 自动联动传播
+
+**🆕 v4.6.x 测试数据管线（标准能力完整版）**：
+- ✨ **`case_dataset()` + `CaseContext[T]`** - YAML → pytest 参数化全链路，支持泛型领域模型
+- ✨ **YAML 级 skip/xfail/seed/timeout/marks/tags** - 在数据文件中声明测试行为，无需 conftest 手写
+- ✨ **自动 Allure**：pytest 插件 setup 阶段自动写标题/标签/附件，测试函数零样板
+- ✨ **CLI 过滤**：`--case`/`--case-stage`/`--case-tag`/`--case-file`/`--seed` 精准复现
+- ✨ **`DataAssetResolver`**：文件资产路径安全（禁绝对路径 + `../` 逃逸）
+
 **🚀 v4.0.0 全面异步化 - 性能飞跃**：
 - ✨ **AsyncHttpClient** - 异步 HTTP 客户端，并发性能提升 **10-30 倍**
 - ✨ **AsyncDatabase** - 异步数据库客户端，基于 SQLAlchemy 2.0 AsyncEngine

{df_test_framework-4.5.0 → df_test_framework-4.7.1}/docs/guides/bootstrap_guide.md

@@ -1,7 +1,7 @@
 # Bootstrap 引导系统指南
 
-> **最后更新**: 2026-01-17
-> **适用版本**: v3.16.0+（Bootstrap 架构），v4.0.0+（异步支持）
+> **最后更新**: 2026-05-19
+> **适用版本**: v3.16.0+（Bootstrap 架构），v4.0.0+（异步支持），v4.7.0+（多数据库 + 平台元数据）
 
 ## 概述
 
@@ -396,6 +396,66 @@ finally:
 
 ---
 
+---
+
+## v4.7.0 扩展：多数据库 + 平台元数据
+
+### 命名 AsyncDatabase 注册（多数据库场景）
+
+```python
+# conftest.py — session 级一次性注册
+@pytest.fixture(scope="session", autouse=True)
+def register_named_databases(runtime):
+    settings = runtime.settings
+    runtime.register_async_database("oms", settings.oms_db_url)
+    runtime.register_async_database("bpm", settings.bpm_db_url)
+
+# 测试侧 — 按名称获取，每次绑定调用时的 RuntimeContext
+async def test_order_sync(runtime):
+    oms_db = runtime.get_async_database("oms")   # 连接池复用，runtime 视图是当前 context
+    bpm_db = runtime.get_async_database("bpm")
+
+    order = await oms_db.query_one("SELECT * FROM orders WHERE id = :id", {"id": 1})
+    task  = await bpm_db.query_one("SELECT * FROM tasks WHERE order_id = :id", {"id": 1})
+    assert task["status"] == "approved"
+```
+
+**核心设计**：
+- `register_async_database(name, url)` 用 `SingletonProvider` 延迟创建引擎（首次 `get_async_database` 时才建连接）
+- `get_async_database(name)` 每次返回 `db.with_runtime(self)` 视图：engine/session_factory 共享，`_runtime` 绑定当前 RuntimeContext
+- 事件（`DatabaseQueryStartEvent` 等）携带调用时的 scope 和 metadata，不会丢失测试上下文
+
+### RuntimeContext.metadata — 平台业务上下文
+
+```python
+# 创建携带租户/执行 ID 的运行时
+exec_runtime = (
+    runtime
+    .with_scope(request.node.nodeid)
+    .with_metadata(tenant_id="t-123", execution_id="exec-456")
+)
+
+# 插件或 DB 事件处理侧读取
+tenant_id = runtime.metadata.get("tenant_id")
+```
+
+`with_scope()` / `with_overrides()` 自动传播 metadata，不需要重复传入。
+
+### RuntimeBuilder 初始化时注入 metadata
+
+```python
+runtime = (
+    RuntimeBuilder()
+    .with_settings(settings)
+    .with_logger(logger)
+    .with_event_bus(event_bus)
+    .with_metadata({"env": "staging", "suite": "regression"})
+    .build()
+)
+```
+
+---
+
 ## 相关文档
 
 - [配置系统指南](config_guide.md) - FrameworkSettings 详细说明
@@ -406,4 +466,4 @@ finally:
 
 ---
 
-**完成时间**: 2026-01-17
+**完成时间**: 2026-01-17 | **最后更新**: 2026-05-19（v4.7.0）

{df_test_framework-4.5.0 → df_test_framework-4.7.1}/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.1}/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.1/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 落地，再补装饰器语法糖。