df-test-framework 4.10.3__tar.gz → 4.10.4__tar.gz

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/AGENTS.md

@@ -8,8 +8,8 @@ This file provides guidance to Codex (Codex.ai/code) when working with code in t
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.10.3
-- **更新时间**: 2026-11-04
+- **版本**: v4.10.4
+- **更新时间**: 2026-11-06
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）
@@ -116,7 +116,7 @@ df-test init my-project --type full  # 完整项目：API + UI 两侧齐备
 - **基准数据池**: `BaselinePool` + `baseline` fixture + `df-test baseline check|ensure`，共享环境受管数据的幂等保障与巡检拦截（v4.9.12）
 - **闸门与竞态**: `@pytest.mark.requires_env/requires_flag` 统一环境/开关 skip；`race()` 栅栏对齐的竞态原语；`get_df_settings/env/runtime` 公开访问器；Allure environment.properties 自动填充（v4.9.15）
 - **UI 健壮原语**: `toolkit` 模块 + AppActions 内置（antd/element 方言；仅用于页面不可控场景，语义化定位仍是第一选择）（v4.9.7）
-- **可观测七层模型**: 能力层只埋一次语义观测点（框架事件），日志/Allure/指标为事件订阅者；EventBus 是纯路由器，组合根用 `create_default_event_bus()`；`publish_sync` 异步上下文入队跟踪 + 每测试自动 `drain()`（v4.9.21）
+- **可观测七层模型**: 能力层只埋一次语义观测点（框架事件），日志/Allure/指标为事件订阅者；EventBus 是纯路由器，组合根用 `create_default_event_bus(settings)`（输出策略属于该次运行，观测配置构造时绑定）；`publish_sync` 异步上下文入队跟踪 + 每测试自动 `drain()`（v4.9.21）
 - **DB 事务参与**: CRUD 全系支持 `session=` 参数参与 `transaction()`；SQL 标识符全面校验（表名/列名/条件键/order_by）防注入；`savepoint(session)` 真实部分回滚（v4.9.19~21）
 - **MQ async 化**: `AsyncKafkaClient`/`AsyncRabbitMQClient`（专属单线程 executor 委托）；Kafka 命名对齐 confluent 官方（`produce` 系 + `value` 参数）；双侧 `connect()`/`stop()`/`fetch()`（v4.9.21）
 - **机检体系**: 双轨对账、core 层依赖 AST 检查、文档死链/import 路径/版本一致性、事件 dataclass、golden 快照——规范尽量机检化（DESIGN_STANDARDS R0.1）

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/CHANGELOG.md

@@ -5,7 +5,84 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [Unreleased]
+## [4.10.4] - 2026-11-06
+
+> 含配置显式归属与 Runtime 组合契约的破坏性变化。维护者指定按 PATCH 发布，
+> 消费项目统一维护并同步适配；详见 [v4.10.4 发布说明](docs/releases/v4.10.4.md)。
+
+### 资源所有权、执行归属与输出隔离
+
+- `with_scope` / `with_metadata` 为资源借用视图；`fresh()` 返回 self 的共享 Provider
+  由原注册表关闭。注册表关闭后拒绝获取资源，资源只执行一个关闭协议。
+- session 异步 fixture 经 Provider 释放并清空缓存；CLI cleanup/baseline 统一经 Bootstrap
+  加载项目插件，finally 关闭资源。浏览器 fixture 补齐启动失败时的清理。
+- 新增 `execution_scope(scope, phase=...)`，事件在产生时捕获现有 ExecutionContext；pytest
+  自动绑定用例和阶段，HTTP/MQ 线程桥接及 `race()` 的预热/目标调用复制上下文。Allure、调试器和失败记录器按用例订阅。
+  **行为变化**：session 客户端的事件现在有调用用例归属；脚本共享客户端用 execution_scope
+  显式绑定，with_scope 视图本身不激活执行上下文。
+- 事件构造、发布与订阅故障不覆盖被测结果；HTTP/gRPC/GraphQL 证据准备失败不阻断请求。
+  脱敏失败丢弃原文，UI 输入保守遮盖；附件失败记录安全诊断，诊断出口故障回退 stderr。
+
+### Runtime 组合场景修复
+
+- `RuntimeContext.with_overrides()` 不再丢失插件注册的自定义 Provider：注册表经
+  `ProviderRegistry.fork()` 派生，保留定义、不共享已缓存实例。Provider 须实现 `fresh()`
+  声明派生方式（返回新 Provider 表示隔离、返回 self 表示明确共享）；未实现的自定义 Provider
+  在派生时报 `TypeError`，不再默认共享可能按旧配置创建的实例。
+- 新增可等待关闭入口 `RuntimeContext.aclose()` / `ProviderRegistry.ashutdown()` /
+  `SingletonProvider.ashutdown()`；此前事件循环内关闭只调度任务即返回，异步资源可能未关闭
+  或被取消。同步 `close()` 在循环内误用时告警并由 Provider 记录调度出的关闭任务，随后的
+  `aclose()` 会等待这些任务完成；单个资源关闭失败不再中断其余资源释放。
+
+### 配置显式归属（含破坏性变更）
+
+- **修复 pytest 指定环境时内部读取点读错环境**：`--env`、`--config-dir`、`--local` 此前只作用于
+  `runtime.settings`，脱敏、可观测/Allure/调试/指标开关、`keep_test_data` 判定、RabbitMQ/Kafka
+  fixture 连接配置仍按 `ENV`（缺省 `test`）加载另一套配置。现在全部使用本次会话配置。
+  **行为变化**：在非默认环境运行的项目，上述各项改按指定环境生效。
+- 配置与策略改为构造/装配时显式确定，删除全局查找与回退：
+  - 脱敏：删除 `get_sanitize_service` / `set_sanitize_service` / `clear_sanitize_service`，
+    新增 `resolve_sanitizer` / `sanitizer_for` / `default_sanitizer`；HTTP/gRPC/GraphQL 客户端与
+    事件中间件、gRPC 追踪中间件、失败现场记录器、AllureObserver 新增 `sanitizer` 参数。
+    传入 `runtime` 的客户端使用其 `settings.sanitize`；裸构造使用纯默认 `SanitizeConfig()`，
+    不读取环境变量；`settings.sanitize` 类型非法时报错。
+  - 观测开关：删除 `is_observability_enabled` / `set_observability_enabled`、
+    `get_observability_logger` / `http_logger` 等日志器缓存、Allure 的 `is_allure_enabled`；
+    `ObservabilityLogger` / `ObservabilityLogObserver` 新增 `enabled` / `sanitizer` 构造参数；
+    是否记录 Allure 由 fixture 按会话配置决定是否创建 observer。
+  - `create_default_event_bus(settings)` 改为必需参数，按 `observability.enabled` 决定是否挂日志观察者。
+  - 删除 DB/Redis 无事件总线时的日志回退直投（`get_fallback_observer`）：观测由显式装配决定。
+  - `rabbitmq_config` / `kafka_config` fixture 改为依赖 `settings` fixture。
+- `Bootstrap.run()` 默认按本次配置创建事件总线并注入 Runtime（新增 `with_event_bus()` 覆盖），
+  pytest 会话复用这条总线；**不再隐式配置进程级日志**，需要时显式 `with_logging(...)`。
+- `configure_logging(config, sanitize=None)`：进程级日志管道的脱敏在配置时绑定，重新配置对早期
+  已缓存的 logger 同样生效（pytest 两阶段初始化下，早期 logger 此前会一直沿用默认脱敏规则）。
+- `RuntimeContext.with_overrides()` 覆盖 `observability.*` 时报 `ValueError`：派生 Runtime 共享事件
+  总线，输出策略属于总线（行为契约调整，此前该覆盖静默不生效）。
+- 新增 `SanitizeService.sanitize_url()`：HTTP、GraphQL 事件中 URL 查询串里的凭据与 `params` 同样遮盖。
+
+### 清理与依赖解析
+
+- `SimpleCleanupManager` 的 `add_api_data` / `add_db_row` / `add_redis_key` 按登记时的
+  客户端/数据库执行清理；此前多客户端场景下清理请求全部交给最后登记（Redis、HTTP）或
+  最先登记（DB）的资源，可能清错对象。DB 行清理的表名与条件列名补做标识符校验。
+- `@service_client` / `@api_class` / `@actions_class` 依赖解析只在被请求的 fixture 本身不存在时
+  回退为字面字符串；fixture 初始化失败或其内部依赖缺失时原样抛出（此前 `@service_client`
+  会吞掉初始化异常并把 fixture 名当字符串注入）。
+
+### 可观测
+
+- EventBus 处理器为无 `__name__` 的可调用对象时，其异常不再在日志环节二次抛出、穿透到发布方。
+- `metrics_observer` 拿不到 `test_runtime` 时的兜底分支改用 `get_global_event_bus()`
+  （此前导入不存在的 `get_event_bus`）。
+- `TracingInterceptor` 新增 `sensitive_headers` 参数并提供默认凭据头集合；此前开启
+  `record_headers=True` 即因属性未定义抛 `AttributeError`。
+
+### 独立安装依赖
+
+- 核心依赖改为 `sqlalchemy[asyncio]`，保证 Bootstrap 导入异步数据库能力所需的
+  `greenlet` 随正式包安装；此前仅在开发或异步数据库 extra 中补齐，新版 SQLAlchemy
+  的干净安装会在导入 Bootstrap 时失败。独立 wheel 冒烟增加组合根导入检查。
 
 ## [4.10.3] - 2026-11-04
 

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/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.10.3
-- **更新时间**: 2026-11-04
+- **版本**: v4.10.4
+- **更新时间**: 2026-11-06
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）
@@ -119,7 +119,7 @@ df-test init my-project --type full  # 完整项目：API + UI 两侧齐备
 - **基准数据池**: `BaselinePool` + `baseline` fixture + `df-test baseline check|ensure`，共享环境受管数据的幂等保障与巡检拦截（v4.9.12）
 - **闸门与竞态**: `@pytest.mark.requires_env/requires_flag` 统一环境/开关 skip；`race()` 栅栏对齐的竞态原语；`get_df_settings/env/runtime` 公开访问器；Allure environment.properties 自动填充（v4.9.15）
 - **UI 健壮原语**: `toolkit` 模块 + AppActions 内置（click_button/set_text_input 等，antd/element 方言；仅用于页面不可控场景，语义化定位仍是第一选择）（v4.9.7）
-- **可观测七层模型**: 能力层只埋一次语义观测点（框架事件），日志/Allure/指标为事件订阅者；EventBus 是纯路由器，组合根用 `create_default_event_bus()`；`publish_sync` 异步上下文入队跟踪 + 每测试自动 `drain()`（v4.9.21）
+- **可观测七层模型**: 能力层只埋一次语义观测点（框架事件），日志/Allure/指标为事件订阅者；EventBus 是纯路由器，组合根用 `create_default_event_bus(settings)`（输出策略属于该次运行，观测配置构造时绑定）；`publish_sync` 异步上下文入队跟踪 + 每测试自动 `drain()`（v4.9.21）
 - **DB 事务参与**: CRUD 全系支持 `session=` 参数参与 `transaction()`；SQL 标识符全面校验（表名/列名/条件键/order_by）防注入；`savepoint(session)` 真实部分回滚（v4.9.19~21）
 - **MQ async 化**: `AsyncKafkaClient`/`AsyncRabbitMQClient`（专属单线程 executor 委托）；Kafka 命名对齐 confluent 官方（`produce` 系 + `value` 参数）；双侧 `connect()`/`stop()`/`fetch()`（v4.9.21）
 - **机检体系**: 双轨对账、core 层依赖 AST 检查、文档死链/import 路径/版本一致性、事件 dataclass、golden 快照——规范尽量机检化（DESIGN_STANDARDS R0.1）

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: df-test-framework
-Version: 4.10.3
+Version: 4.10.4
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Author-email: DF QA Team <qa@example.com>
 License: MIT
@@ -44,7 +44,7 @@ Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: redis>=5.0.0
 Requires-Dist: requests>=2.34.2
-Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: structlog>=25.4.0
 Requires-Dist: urllib3>=2.7.0
 Provides-Extra: all

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/README.md

@@ -1,7 +1,7 @@
 # DF Test Framework
 
-> **版本**: v4.10.3
-> **更新时间**: 2026-11-04
+> **版本**: v4.10.4
+> **更新时间**: 2026-11-06
 > 简单、强大、可扩展的现代化 Python 测试自动化框架
 
 [![PyPI version](https://img.shields.io/pypi/v/df-test-framework.svg)](https://pypi.org/project/df-test-framework/)

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/docs/ESSENTIAL_DOCS.md

@@ -1,8 +1,8 @@
 # 核心文档导航 - 真正有价值的文档清单
 
 > **目标读者**: 测试开发人员、框架使用者、新团队成员
-> **更新日期**: 2026-11-04
-> **框架版本**: v4.10.3
+> **更新日期**: 2026-11-06
+> **框架版本**: v4.10.4
 
 ---
 

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/docs/README.md

@@ -1,6 +1,6 @@
 # DF Test Framework 文档中心
 
-> 版本：v4.10.3 · 最近更新：2026-09-01
+> 版本：v4.10.4 · 最近更新：2026-09-01
 > 现代化 Python 测试自动化框架的官方知识库。
 
 ---

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/docs/architecture/DESIGN_STANDARDS.md

@@ -49,6 +49,9 @@
 - **R3.4 (MUST)** 持有连接/进程/文件句柄的对象，其 fixture 必须 yield + 显式
   close/await close；框架代管仅限框架自有类型，第三方对象生命周期不代管
   （教训：AsyncHttpClient fixture 泄漏，v4.9.21）。
+  所有权必须显式：Runtime 视图与借用 Provider 不关闭原所有者资源；异步 fixture
+  释放资源时同时清空 Provider 缓存，避免归还已关闭实例。CLI 使用 Bootstrap 装配
+  并在 finally 关闭（优先四项修复，Unreleased）。
 - **R3.5 (MUST)** 跨库/跨驱动语义差异必须在 docstring 标注（如 lastrowid 对
   PostgreSQL 无效）。
 - **R3.6 (SHOULD)** 上下文管理器承诺的语义必须真实成立并有集成测试锚定
@@ -165,9 +168,16 @@
   （现状欠账：UI 细分事件无发布方，见 roadmap 候选①）。
 - **R8.4 (MUST)** 脱敏在事件发布边界（EventPublisher/SanitizeService）完成一次，
   订阅者不重复脱敏。
-- **R8.5 (MUST)** 事件发布失败不影响主流程但必须可见（logger.debug 起）。
+- **R8.5 (MUST)** 可选证据的准备、构造、发布与报告输出失败，不得替换业务返回值、
+  异常或断言；隔离边界不得包含被测操作。诊断仅含组件与异常类型，脱敏失败必须
+  丢弃或保守遮盖原文，禁止原文降级。诊断出口自身故障也须隔离
+  （优先四项修复，Unreleased；机检：`test_output_isolation.py`）。
 - **R8.6 (SHOULD)** 关联标识用 correlation_id（短形态展示），不引入平行的
   实例内计数器。
+- **R8.7 (MUST)** 共享客户端按操作发生时的 ExecutionContext 关联 scope/phase，
+  不把创建时的 Runtime scope 当作当前用例；框架提交 executor 时复制上下文。
+  pytest 归属覆盖 setup/call/teardown，按用例订阅在整个 protocol 结束后清理
+  （优先四项修复，Unreleased；机检：`test_execution_scope.py`）。
 
 ## 9. sync/async 双轨
 
@@ -233,7 +243,7 @@
 
 1. ✅ **EventBus 职责越界**（已清偿）：`EventBus()` 默认自行挂载日志观察者——通用事件路由器
    与默认输出策略绑死；挂载决策应上移到组合根（Bootstrap / pytest 插件层）。
-   **落地约束**：上移必须配防退化机制（`create_default_event_bus()` 工厂 +
+   **落地约束**：上移必须配防退化机制（`create_default_event_bus(settings)` 工厂 +
    机检断言 Bootstrap 产出的 bus 挂有观察者），否则"忘挂载=实时日志静默丢失"
    只是把漏埋点风险从能力层挪到组合根。
 2. ✅ **`publish_sync()` 名不副实**（已清偿：语义澄清 + _pending_tasks 跟踪 + drain() + 每测试 autouse 自动 drain）：已有事件循环时走 `create_task()` 立即返回，

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/docs/architecture/README.md

@@ -15,6 +15,7 @@
 | 文档 | 定位 |
 |---|---|
 | [framework-positioning-notes](./framework-positioning-notes.md) | 定位梳理记录（讨论稿，非规范） |
+| [framework-capability-assessment](./framework-capability-assessment.md) | 理想能力模型与现状对照、推进层次（讨论记录，非规范） |
 
 ## 专题
 

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/docs/architecture/TEST_EXECUTION_LIFECYCLE.md

@@ -82,7 +82,7 @@ logging/markers/allure/debugging/metrics/monitoring/ui   各自初始化
 ```
 
 RuntimeContext 创建即完成组合根装配：EventBus 由
-`create_default_event_bus()` 工厂创建（挂 ObservabilityLogObserver），
+`create_default_event_bus(settings)` 工厂创建（挂 ObservabilityLogObserver），
 tracing 启用时 Bootstrap 显式注册 trace context 提供者（core 依赖反转）。
 
 `config` 对象此后携带：`_df_settings` / `_df_current_env` / `_df_runtime` /
@@ -115,7 +115,7 @@ Session 级（首条测试时创建，整个会话复用）
     └─ settings
 
 Function 级（每条测试独立）
-  test 隔离 EventBus ── _df_test_buses[nodeid]，create_default_event_bus()
+  test 隔离 EventBus ── _df_test_buses[nodeid]，create_default_event_bus(settings)
     ├─ _auto_allure_observer (autouse)   AllureObserver 订阅全部事件
     ├─ _auto_debug_by_marker (autouse)   有 @debug/配置开关时挂 Console 观察者
     ├─ 事件 drain fixture (autouse)      teardown 时 await bus.drain()
@@ -189,7 +189,7 @@ UI 取证据此决定 trace 去留。
 pytest_sessionfinish   df_session_finish hook；Allure 结果已由 allure-pytest 落盘
 pytest_unconfigure     （与 configure 相反顺序）
   └─ RuntimeContext.close()
-       ├─ Provider 逆序 shutdown（含 df_providers 注册的项目 Provider）
+       ├─ Provider shutdown（含 df_providers 注册的项目 Provider）
        ├─ http_client / database / redis 连接释放
        └─ 残留测试 EventBus 清理
 ```
@@ -217,9 +217,9 @@ pytest_unconfigure     （与 configure 相反顺序）
 
 ### 测试隔离 EventBus
 
-每条测试独立 bus（`_df_test_buses[nodeid]`）：事件不跨测试泄漏、
-订阅独立、pytest-xdist 并行安全。bus 由 `create_default_event_bus()`
-创建，默认观察者不漏挂（防退化机检保证）。
+当前主路径共享会话总线，按操作时的执行 scope 过滤订阅；`test_runtime` 是资源借用视图。
+pytest protocol 与阶段 hook 绑定 nodeid 和 setup/call/teardown，线程委托复制上下文。
+显式隔离总线仍可用 `create_default_event_bus(settings)` 创建。
 
 ### 观测的"自动"边界
 
@@ -237,3 +237,11 @@ Allure 记录、失败取证、脱敏、事件隔离、drain 全部自动——
 - [事件总线指南](../guides/event_bus_guide.md)
 - [数据清理](../guides/test_data_cleanup.md)
 - [配置指南](../guides/config_guide.md)
+
+
+### 资源与可选证据的关闭边界
+
+session 异步 fixture 在所属循环退出前通过 Provider 释放并清空缓存；unconfigure 关闭
+其余 Runtime 自有资源。借用视图和声明共享的派生 Provider 不拥有最终关闭权。
+输出异常由观测边界隔离并记录安全诊断，不替换业务返回值或原始断言。
+具体契约与回归入口见 [四项实施记录](../development/priority-four-completion.md)。

df_test_framework-4.10.4/docs/architecture/framework-capability-assessment.md

@@ -0,0 +1,202 @@
+# 框架能力评估：理想能力模型与现状对照
+
+> **状态**：讨论记录 / 非规范
+>
+> 记录 2026-11-05 的一轮框架评估：先抛开现有实现独立推导"测试框架应具备的能力与设计原则"，
+> 再逐项对照真实实现，最后经 Codex 评审修正、收敛为推进方向。本文不直接约束实现，也不替代
+> [DESIGN_STANDARDS](./DESIGN_STANDARDS.md)；落地事项以 `docs/development/` 下的问题说明与方案为准。
+>
+> 对照基线：v4.10.3 + 当日 Unreleased 修复（`d93b3e3`）。后续状态更新见第 5 节。
+
+## 1. 测试框架的定位
+
+一次测试是**对系统的某个预期给出可信结论**。运行器（pytest）负责发现、调度与汇总；协议库
+（httpx、Playwright、SQL 驱动）负责与系统对话；测试框架处理两者都不管、但每个测试团队都会
+反复遇到的问题。衡量标准只有两个：
+
+1. 写出一个可信测试的成本有多低；
+2. 测试失败后弄清原因的成本有多低。
+
+每个新增概念都要为这两点服务，否则就是负担。
+
+## 2. 理想能力模型
+
+### 2.1 要解决的问题
+
+| # | 问题 | 不解决的后果 |
+|---|---|---|
+| 1 | 结论不可信：假通过、偶发失败、异步结果判早了 | 团队不再相信红灯 |
+| 2 | 环境与安全：用例跑在不同环境；破坏性操作误伤共享/生产环境 | 配置散落或事故 |
+| 3 | 状态与隔离：互相踩数据、残留累积 | 偶发失败、环境污染 |
+| 4 | 身份与访问：多角色、多系统、多种认证 | 每个用例自己拼登录 |
+| 5 | 依赖不可控：下游不稳或无测试环境 | 被测系统没问题测试先挂 |
+| 6 | 失败难诊断：只有一行断言错误 | 靠重跑和猜 |
+| 7 | 维护成本：被测系统一改，几百个用例跟着改 | 测试比业务代码难维护 |
+| 8 | 反馈太慢：全量太久、不知道该跑哪些 | 测试被移出主流程 |
+| 9 | 不稳定没人管：偶发失败被重试掩盖 | 可信度悄悄下降 |
+| 10 | 结果难被机器消费 | 无法自动处理失败 |
+
+1、3、6 决定框架有无价值；2、4、7 是基础要求；5、8、9、10 按团队规模和成熟度逐步提供。
+
+### 2.2 能力分档
+
+**核心（没有就不该叫测试框架）**
+
+- **判定**：区分失败 / 错误 / 跳过 / 预期失败，未完成验证不得算通过；等待分"立即成立 / 最终成立 /
+  持续成立"三种语义（持续成立只证明采样点）；失败输出预期、实际与差异，最终成立类带最后一次观察；
+  轮询默认只重复观察，重复动作须显式声明。
+- **测试数据生命周期**：归属可追溯到运行与用例；登记时绑定"由谁、如何撤销"，结果被记录，允许保留现场；
+  按归属认领崩溃残留（受环境安全等级约束）；前置状态可幂等补齐或只检查；随机数据可复现。
+- **证据**：每次交互结构化记录、按用例/步骤归属、入库前统一脱敏；附件存引用；测试结果是事实源，
+  报告与遥测是派生输出，派生失败不改变结论。
+- **环境**：一次加载、类型化；带安全等级，破坏性能力由框架统一拦截；密钥不进证据。
+
+**基础**
+
+- **交互**：每种协议独立可用的客户端，保留协议语义（重放安全、事务、消息确认、浏览器会话）；
+  认证、签名、业务成功判定作为策略；重试由协议声明安全条件，只共享退避算法。
+- **身份**：身份（代表谁）、认证策略（如何获得授权）、会话（令牌/Cookie/浏览器状态）三者分离，
+  会话按"服务 + 身份 + 租户/范围"区分。
+- **组织与复用**：推荐分层（用例 → Flow → API/页面对象 → 客户端）但不强制；数据驱动，参数化有可读身份。
+
+**进阶（按需）**
+
+依赖替身（含替身与真实服务一致性校验）、并行隔离与用例选择、稳定性治理（重试结果如实记录、
+偶发统计、隔离区）、机器可消费结果（错误码、修复建议、能力清单）、工程化工具（脚手架、
+规格驱动生成、体检、清扫）。
+
+**明确不做**：重新实现运行器 / 依赖注入容器 / 插件系统 / 协议库；业务流程与对账算法；
+承诺所有操作可撤销；用通用 `execute(kind, ...)` 抹平协议差异。
+
+### 2.3 设计原则
+
+1. 薄在标准工具之上，每一层都保留直接使用底层工具的出口。
+2. 显式胜过魔法：依赖靠传入，不靠全局状态；自动装配只作可选便利。
+3. 一个资源只有一个所有者：谁创建谁关闭，借用方不关，所有权转移显式表达。
+4. 故障隔离：报告、日志、指标出错不影响被测操作与结论。
+5. 结论如实：清理失败、证据缺失、重试通过与断言结论分开保留。
+6. 概念少、语义精：普通使用者只需理解环境、客户端、数据、断言。
+
+## 3. 现状对照
+
+结论类别：✅ 已做到　⚠️ 部分 / 有缺口　❌ 缺失。依据为对照当日的代码核实。
+
+### 3.1 核心能力
+
+| 能力 | 结论 | 依据 |
+|---|---|---|
+| 判定：四种结论 | ✅ | pytest 原生 + YAML 用例 `xfail {reason, strict}` |
+| 判定：业务成功 | ✅ | `http.response_contract` 配置驱动，`BaseAPI` 自动生效；`expect_business_error` |
+| 判定：等待语义 | ✅ | `wait_until` 超时带最后值；`assert_consistently` 观察全窗口并注明只证明采样点 |
+| 判定：轮询不重复副作用 | ⚠️ | 靠约定，框架不区分观察与动作 |
+| 数据：归属 | ✅ | NamingRegistry、命名规范、KeyPatternRegistry |
+| 数据：清理/补偿 | ⚠️ | 多客户端归属已于 `c119140` 修复；三个清理管理器；清理结果不进报告（BACKLOG 暂缓） |
+| 数据：兜底清扫 | ✅ | `df-test cleanup`，默认 dry-run，拒绝 prod |
+| 数据：前置状态 | ✅ | BaselinePool、`df-test baseline check/ensure` |
+| 数据：可复现 | ⚠️ | 数据管线支持 `seed` / `--seed`；数据生成器是否共用种子未核实 |
+| 证据：交互记录 | ✅ | HTTP/DB/Redis/MQ/UI 事件；失败注入 HTTP 现场；UI trace.zip 与截图 |
+| 证据：统一脱敏 | ⚠️ | 对照时脱敏读全局配置、URL 查询串未脱敏（已修复，见第 5 节） |
+| 证据：结果是事实源 | ⚠️ | 已有事件 schema、附件和运行器结果；缺断言、清理、证据完整性、重试尝试之间稳定可查询的关联与独立状态 |
+| 证据：输出故障隔离 | ⚠️ | EventBus 订阅者异常已隔离；脱敏失败会打断请求，缺整体验证（优先落实第 4 项） |
+| 环境：类型化描述 | ✅ | Pydantic 配置、分层 YAML、显式本机覆盖、环境身份 |
+| 环境：安全等级统一拦截 | ⚠️ | `_PROTECTED_ENVS` 在 cleanup / baseline 各写一份，无框架统一执行点 |
+| 环境：密钥不进证据 | ✅ | `SecretStr` + 脱敏（缺口同统一脱敏一项） |
+
+### 3.2 基础能力
+
+| 能力 | 结论 | 依据 |
+|---|---|---|
+| 交互：独立客户端 | ✅ | HTTP/gRPC/GraphQL/DB/Redis/Kafka/RabbitMQ/存储/浏览器，双轨 |
+| 交互：协议语义 | ✅ | 事务与 savepoint、MQ 专属执行器、SQL 方言编译 |
+| 交互：认证/签名策略 | ✅ | 中间件体系、国密签名 |
+| 交互：重试安全条件 | ⚠️ | v4.10.3 统一重试并支持单请求 `retries=0`；"可安全重放"仍由使用者判断 |
+| 身份：三者分离 | ⚠️ | 无统一身份概念；多角色靠 `with_overrides`，验证码登录由项目自建 Provider，UI 有 `auth_state` |
+| 组织与复用 | ✅ | 推荐分层已有；装饰器与加载函数的学习成本见 3.4 |
+| 数据驱动 | ✅ | `CaseContext[T]`、`case_dataset`，按阶段/标签筛选 |
+
+### 3.3 进阶能力
+
+| 能力 | 结论 | 依据 |
+|---|---|---|
+| 依赖替身 | ⚠️ | HTTP/页面/DB/Redis/时间 Mock，页面 Mock 支持轮换与延迟；无录制回放与替身一致性校验 |
+| 并行隔离 | ⚠️ | 已有局部保护：认证缓存跨 worker 文件锁与原子写（`testing/fixtures/auth.py`）、命名随机唯一标识（`fresh_uid`）；未形成覆盖数据、会话、资源、清理的整体验证 |
+| 用例选择 | ⚠️ | 标签、环境闸门、数据管线筛选；无按影响面选择 |
+| 稳定性治理 | ❌ | 仅 `retry_times` 配置依赖 pytest-rerunfailures；无偶发统计与隔离区 |
+| 机器可消费 | ❌ | 无结构化结果输出、错误码与能力清单；事件 schema 稳定化是开端 |
+| 工程化 | ✅ | Jinja2 脚手架、OpenAPI 生成、doctor、cleanup、baseline、CI 模板 |
+
+### 3.4 设计原则对照
+
+| 原则 | 结论 | 说明 |
+|---|---|---|
+| 薄在标准工具之上 | ⚠️ | 能力层基本做到；组合层的 Runtime/Provider 与 fixture 存在生命周期责任重叠 |
+| 显式胜过魔法 | ⚠️ | 装饰器自动生成 fixture；对照时存在全局配置读取与全局脱敏（后者已修复） |
+| 资源唯一所有者 | ⚠️ | Runtime、Provider、fixture 都可能关闭同一资源；本轮组合缺陷多出于此 |
+| 故障隔离 | ⚠️ | 设计意图明确，缺整体验证 |
+| 结论如实 | ⚠️ | 断言与清理结果不分层；重试通过记为通过 |
+| 概念少、语义精 | ⚠️ | 需按学习成本评估，见下 |
+
+**使用面的衡量方式**：导出数量（227）、fixture 数量（106）只能提示需要整理，不能直接证明概念过多；
+装饰器与对应加载函数也不能相加计为"9 种声明方式"。应以学习和使用成本衡量：普通使用者完成一件事
+是否有清楚的推荐路径；相近接口的差异能否解释清楚；文档、生成器与项目是否使用同一套写法；
+高级能力是否妨碍理解基础用法。
+
+## 4. 结论与推进方向
+
+**总体判断**：保留现有能力，不整体重写。框架的主要资产已经成立——响应契约、等待语义、数据管线、
+命名与清理、环境配置、协议能力、失败取证、脚手架与机检；它们让项目复用的不只是代码，还有经过
+验证的工程规则。负担与缺口集中在组合与生命周期、结果表达和使用体验。
+
+评审中对初版结论的修正（均已采纳）：
+
+- **组合层**：不预设"重做组合层"或删除哪些类。Runtime、Provider、fixture 并存本身不等于冲突，
+  也可能分别承担环境组合、资源构造、作用域管理；先统一资源所有权、配置来源和上下文传播，
+  对无法清楚表达这些契约的部分再重构。
+- **结果模型**：目标是补齐结果契约（断言、清理、证据完整性、重试尝试的关联与独立状态），
+  先验证扩展现有链路是否足够，再决定是否新建模型。
+- **身份**：身份、认证、会话的边界值得明确，统一 Actor API 是否必要取决于能减少多少真实重复，
+  作为专项设计，不与资源正确性修复绑定。
+- **并行隔离**：由"完全缺失"修正为"有局部保护、未整体验证"，先补场景验证再设计机制。
+- **使用面**：按学习与使用成本衡量，不按数量。
+
+### 推进层次
+
+| 层次 | 内容 |
+|---|---|
+| 优先落实 | 资源所有权、配置与脱敏一致性、执行上下文传播、输出故障隔离的组合验证 |
+| 按实际缺口补强 | 结果契约、身份与会话管理、并行隔离、重试结果保留 |
+| 持续改善 | 推荐使用路径、命名一致性、文档与脚手架、重复实现整理 |
+
+此前暂缓的事项（对账原语、执行记录、清理结果可见、MaxCompute 上收等，见 [BACKLOG](../development/BACKLOG.md)）
+维持原结论，不因本次评估重新列为必做项。每项落地前先写清"当前具体问题、目标行为、验收场景"，
+再选择最小完整改动。
+
+## 5. 状态（持续更新）
+
+| 事项 | 状态 | 文档 |
+|---|---|---|
+| 优先落实四项问题说明 | 已整理 | [priority-issues-2026-11](../development/priority-issues-2026-11.md) |
+| 第 2 项 配置与脱敏一致性 | **已实施**（v4.10.4，`e840379` / `baaccc4`） | [config-ownership-plan](../development/config-ownership-plan.md) |
+| 第 1 项 资源所有权 | 已实施并通过离线验收（v4.10.4） | [实施与验收](../development/priority-four-completion.md) |
+| 第 3 项 执行上下文传播 | 已实施并通过离线验收，含 race 线程传播补漏（v4.10.4） | [实施与验收](../development/priority-four-completion.md) |
+| 第 4 项 输出故障隔离 | 已实施并通过离线验收（v4.10.4） | [实施与验收](../development/priority-four-completion.md) |
+
+## 6. 讨论过但未作为目标的方向
+
+同日讨论中还出现过若干更彻底的重设计方向。它们不是当前目标，记录取舍以免重复讨论；
+若要启用，须先做对应验证。
+
+| 方向 | 价值 | 主要顾虑 / 需验证 |
+|---|---|---|
+| 统一 Scope 栈管理资源与数据撤销 | 生命周期一种机制 | 资源释放与数据补偿语义不同（数据可能需保留、只能补偿、需记录结果），可共享调度但不能视为同一件事；执行嵌套不等于资源所有权 |
+| Runtime 环境化、资源全部交给 fixture | 消除双重生命周期 | 框架 CLI（cleanup / baseline）与 FSC 双库 fixture 等非 pytest 入口也需复用构造与关闭规则 |
+| OTel 作为唯一证据底座 | 调用关联与跨系统追踪 | 有采样、队列满可丢 span，缺测试结论 / 阶段 / 重跑语义；应保留自有结果契约再与 OTel 关联 |
+| 单一异步实现 + 同步 portal 桥接 | 消除双轨重复 | 线程边界、事件循环归属、取消传播；Playwright 同步 API 基于 greenlet 而非线程 portal；需 spike 验证 |
+| 服务声明式配置统一 5 类装饰器 | 降低概念数 | 证据不足；不同装饰器可能对应不同职责，可先统一注册机制 |
+
+## 相关文档
+
+- [定位梳理记录](./framework-positioning-notes.md)
+- [DESIGN_STANDARDS](./DESIGN_STANDARDS.md)
+- [可观测架构](./observability-architecture.md)
+- [框架候选事项清单](../development/BACKLOG.md)

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/docs/architecture/observability-architecture.md

@@ -30,8 +30,8 @@ test id / correlation_id / trace_id / artifact reference 关联。
    ▼
 EventBus（纯路由器，不绑定任何输出策略）
    │  组合根（pytest_configure / 测试隔离 bus）用
-   │  create_default_event_bus() 工厂挂默认观察者
-   ├──▶ ObservabilityLogObserver   → 实时结构化日志（全局开关 is_observability_enabled）
+   │  create_default_event_bus(settings) 工厂按本次运行配置挂默认观察者
+   ├──▶ ObservabilityLogObserver   → 实时结构化日志（开关与脱敏在构造时绑定）
    ├──▶ AllureObserver             → 报告 step/attachment
    ├──▶ HttpRequestRecorder        → 失败时注入完整 HTTP 现场（数据型取证）
    ├──▶ MetricsObserver            → Prometheus 指标
@@ -56,17 +56,26 @@ OTel tracing（独立机制，不经 EventBus）
 ### EventBus（infrastructure/events/bus.py）
 
 - **纯路由器**：构造时不挂任何订阅者；作用域（scope）过滤订阅。
-- **组合根工厂** `create_default_event_bus()`：挂 `ObservabilityLogObserver`，
-  框架 pytest 路径与库模式使用者从这里创建；防退化由机检测试保证。
+- **组合根工厂** `create_default_event_bus(settings)`：按本次运行配置挂 `ObservabilityLogObserver`
+  （`observability.enabled=False` 时不挂）。`Bootstrap.run()` 默认用它创建总线并注入 Runtime，
+  pytest 会话复用这条总线；输出策略属于总线，共享总线的派生 Runtime 共享该策略。
 - **publish_sync 语义**：同步上下文完整等待；异步上下文入队即返、任务被跟踪，
   在确定性关键点 `await bus.drain()`（框架已在每个测试 teardown 的
   autouse fixture 中自动 drain）。
 - 事件发布失败不影响主流程，但记 debug 日志（R8.5，禁止静默吞）。
 
-### 无 Runtime 的裸实例（库模式/手动调试）
+### 配置显式归属
 
-能力客户端未注入 runtime 时，事件直投 `get_fallback_observer()`——
-实时日志不丢；两条投递路径共用同一份格式化实现。
+观测相关的配置与策略都在构造/装配时确定，不在处理事件时查找：事件在源头按所属配置脱敏
+（客户端/中间件构造时经 `resolve_sanitizer()`：显式 `sanitizer` → `runtime.settings.sanitize`
+→ 纯默认 `SanitizeConfig()`）；观察者的开关由创建它的组合根决定；进程级 structlog 管道的脱敏在
+`configure_logging(logging_config, sanitize)` 时绑定。因此工作线程中处理事件与主线程一致。
+详见 [配置显式归属方案](../development/config-ownership-plan.md)。
+
+### 无事件总线的裸实例（库模式/手动调试）
+
+能力客户端未注入 runtime / event_bus 时不产生观测输出（无隐藏的回退路径）；需要实时日志时
+传入 `create_default_event_bus(settings)` 创建的总线。
 
 ### 实时日志（ObservabilityLogObserver）
 

{df_test_framework-4.10.3 → df_test_framework-4.10.4}/docs/development/BACKLOG.md

@@ -52,6 +52,28 @@
 | 15 | [HTTP 接口支持面设计](http-client-interface-plan.md) | 中 | 后续讨论草案，不扩大 v4.10.3 收尾范围。多值查询参数被压成 `?a=2` 的缺陷已于 v4.10.3 修复；后续按 extensions、认证策略与 auth、Cookie 管理、流式接口及其余参数表达能力推进；客户端默认跟随重定向保持不变。详细边界、待定项和验收要求见方案，排期另定 |
 | 16 | 消费项目迁移至 4.10.3 | 高（发布后） | Master/FSC：`max_retries`→`retries`（属性读取、构造参数、`model_copy` 键、测试桩、YAML、`HTTP__MAX_RETRIES` 文档），写接口改按请求声明 `retries=0`；切换前以本地源码跑单元、`--collect-only` 与代表性 API 用例，确认无未知参数 TypeError |
 
+## 暂缓决策与重新评估条件
+
+2026-11-05 按维护者补充的既有讨论结论整理。以下是当前保留的投入边界，不是本轮实施清单；
+达到重新评估条件只表示可以讨论，不自动转为开发任务或发布承诺。消费者范围按当时讨论记录，
+重新评估时再核对实际需求。
+
+| 事项 | 保留结论与原因 | 什么时候再看 |
+|---|---|---|
+| 对账原语 | 暂不上收框架。比较循环主要集中在 FSC，尚只有一个明确消费者，不为单项目循环预建通用抽象 | FSC 认为手写循环难维护时，先在项目内提取纯函数；第二个项目出现同类需求后，再评估框架抽取 |
+| 执行记录（可恢复的运行清单） | Master 与 FSC 已有共性，值得设计；抽取目标是输入指纹、原子落盘、续查等机制，不只是统一 JSON 格式 | 原前置为重试控制落地。HTTP 重试统一已随 [v4.10.3](../releases/v4.10.3.md) 落地，现可重新评估，尚未排期；设计时仍需区分请求重试与业务执行恢复 |
+| 清理结果可见 | 降级并暂缓。此前认为命名规范与残留认领已提供兜底，暂不增加统一清理结果汇总或报告能力 | 暂不处理；后续是否恢复由维护者另行决定 |
+| MaxCompute 引擎上收 | 继续由数仓项目承载；维护者确认此前已有记录。框架 `capabilities/engines/` 仍为预留骨架，不因目录存在而提前实现 | 出现第二个使用 MaxCompute 的项目时，重新核对可复用机制及业务边界 |
+| 版本与发布核验（锁定版本与实际安装版本） | P2，暂不排期；关注依赖锁定结果与实际运行解释器所加载版本的一致性 | 在后续版本治理评估中安排，不因本次记录立即启动 |
+| 运行前体检 | 在已有 doctor 与 baseline 上扩展，先列清具体缺项；不另建一套平行体检入口 | 后续有具体检查缺口时再评估，当前不急 |
+
+### 与本轮代码评估的边界
+
+“清理结果可见”暂缓的是汇总与报告增强，不表示接受清理对象归属错误。2026-11-05 独立评估
+在假客户端上复现：同一 `SimpleCleanupManager` 先后为 A、B 两个 HTTP 客户端登记清理项，
+两项最终均交给 B 执行。这属于多客户端清理的正确性问题，应单独跟踪修复，不能被上述暂缓决策覆盖。
+该复现不表示已在真实环境发生误清理；本次只记录区别，不启动实现。
+
 ## 已决策记录
 
 - **版本号（2026-08-20 决策）**：v4.9.21 发布。维护者判定：当前全部消费项目