df-test-framework 4.7.2__tar.gz → 4.7.3__tar.gz

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/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.7.2
-- **更新时间**: 2026-05-26
+- **版本**: v4.7.3
+- **更新时间**: 2026-05-27
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/CHANGELOG.md

@@ -7,6 +7,25 @@
 
 ## [Unreleased]
 
+## [4.7.3] - 2026-05-27
+
+### 💥 破坏性变更
+
+- **`LoggingConfig.use_utc` 已移除**：替换为 `timestamp: Literal["utc", "local"]`（默认 `"local"`）。
+  迁移：`use_utc: true` → `timestamp: utc`，`use_utc: false` 或未配置 → 无需操作（新默认即 local）；
+  环境变量：`LOGGING__USE_UTC=true` → `LOGGING__TIMESTAMP=utc`
+
+### ✨ 新增
+
+- **`LoggingConfig.timestamp`**：时区策略字段，`"local"`（默认）输出 `2026-05-27T16:30:45.123+08:00`，`"utc"` 输出 `2026-05-27T08:30:45.123Z`
+
+### 🔧 改进
+
+- **日志时间戳统一 RFC 3339 毫秒格式**：所有 handler（控制台 / 文件）共享同一 processor 链，时间戳全局一致；自定义 `_make_timestamper` 替代 structlog 内置 `TimeStamper`，精确控制毫秒精度与时区格式
+- **`ExtraAdder` 并入共享 processor 链**：原先仅在 `foreign_pre_chain` 中，现在 structlog 和第三方日志使用同一套处理器，消除 `foreign_pre_chain` 独立维护
+
+**详细内容**: 查看完整发布说明 [v4.7.3](docs/releases/v4.7.3.md)
+
 ## [4.7.2] - 2026-05-26
 
 ### ✨ 新增

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/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.7.2
-- **更新时间**: 2026-05-26
+- **版本**: v4.7.3
+- **更新时间**: 2026-05-27
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.7.2
+Version: 4.7.3
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/README.md

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

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/docs/ESSENTIAL_DOCS.md

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

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/docs/README.md

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

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/docs/api-reference/infrastructure.md

@@ -683,19 +683,25 @@ APP_TEST__DEFAULT_TIMEOUT=600
 | 字段 | 类型 | 默认值 | 说明 |
 |-----|------|--------|------|
 | `level` | `Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]` | `"INFO"` | 日志级别 |
-| `format` | `Literal["text", "json"]` | `"text"` | 日志格式 |
-| `file` | `Optional[str]` | `None` | 日志文件路径 |
-| `rotation` | `str` | `"100 MB"` | 日志轮转策略 |
-| `retention` | `str` | `"7 days"` | 日志保留策略 |
+| `format` | `Literal["text", "json", "logfmt"]` | `"text"` | 输出格式：text（开发）/ json（生产）/ logfmt（Loki/Prometheus） |
+| `timestamp` | `Literal["utc", "local"]` | `"local"` | 时区策略：local 输出 `2026-05-27T16:30:45.123+08:00`，utc 输出 `2026-05-27T08:30:45.123Z` |
+| `file` | `str \| None` | `None` | 日志文件路径，启用后文件强制使用 JSON 格式 |
+| `rotation` | `str` | `"100 MB"` | 日志轮转大小（如 `"500 MB"`、`"1 GB"`） |
+| `retention` | `str` | `"7 days"` | 日志保留策略（如 `"30 days"`） |
 | `enable_console` | `bool` | `True` | 启用控制台输出 |
-| `sanitize` | `bool` | `True` | 自动脱敏敏感字段 |
+| `use_orjson` | `bool` | `True` | 使用 orjson 高性能 JSON 序列化（已安装时生效） |
+| `add_callsite` | `bool` | `False` | 添加调用位置信息（文件名、行号、限定函数名） |
+| `third_party_level` | `Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]` | `"WARNING"` | 第三方库日志级别（httpx、faker 等），默认抑制噪音 |
 
 **环境变量**:
 ```bash
-APP_LOGGING__LEVEL=DEBUG
-APP_LOGGING__FORMAT=json
-APP_LOGGING__FILE=logs/test.log
-APP_LOGGING__ENABLE_CONSOLE=true
+LOGGING__LEVEL=DEBUG
+LOGGING__FORMAT=json
+LOGGING__TIMESTAMP=local      # local（默认）/ utc
+LOGGING__FILE=logs/test.log
+LOGGING__ENABLE_CONSOLE=true
+LOGGING__ADD_CALLSITE=false
+LOGGING__THIRD_PARTY_LEVEL=WARNING
 ```
 
 ---

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/docs/guides/logging_guide.md

@@ -15,7 +15,7 @@ v3.38.2 版本将日志系统从 **loguru** 迁移到 **structlog**：
 |------|-----------------|---------------------|
 | 日志库 | loguru | structlog |
 | pytest 集成 | 需要桥接 | 原生支持（stdlib logging） |
-| 时间格式 | `{time:YYYY-MM-DD HH:mm:ss}` | `%Y-%m-%d %H:%M:%S.%f` |
+| 时间格式 | `{time:YYYY-MM-DD HH:mm:ss}` | RFC 3339 毫秒 + 显式时区 (`2026-05-27T08:30:45.123Z`) |
 | 配置方式 | `setup_logger()` | `configure_logging()` |
 | 导入方式 | `from loguru import logger` | `get_logger(__name__)` |
 
@@ -25,7 +25,7 @@ v3.38.2 版本将日志系统从 **loguru** 迁移到 **structlog**：
 - ✅ **全局配置控制过滤** - YAML `logging.level` 统一控制显示级别（v3.38.7）
 - ✅ **pytest 无缝集成** - ProcessorFormatter 统一格式，无重复输出（v3.38.5）
 - ✅ **两阶段初始化** - 模块加载时即完成 structlog 早期配置（v3.38.6）
-- ✅ **时间格式统一** - structlog 和 pytest 使用相同的 strftime 格式
+- ✅ **时间格式统一** - RFC 3339 毫秒 + 显式时区，全局一致（`timestamp: utc/local`）
 - ✅ **结构化日志** - JSON/logfmt 输出，便于日志聚合
 - ✅ **上下文传播** - 自动传播 request_id、user_id 等
 - ✅ **第三方库支持** - PositionalArgumentsFormatter + ExtraAdder（v3.38.5）
@@ -53,14 +53,14 @@ def test_example():
 ### 配置日志系统
 
 ```python
+from df_test_framework.infrastructure.config import LoggingConfig
 from df_test_framework.infrastructure.logging import configure_logging
 
-configure_logging(
-    env="dev",           # 环境: dev/test/staging/prod
-    level="INFO",        # 级别: DEBUG/INFO/WARNING/ERROR/CRITICAL
-    json_output=None,    # JSON 输出: None=自动, True=强制, False=禁用
-    enable_sanitize=True # 敏感信息脱敏
-)
+configure_logging(LoggingConfig(
+    level="INFO",
+    format="text",       # text / json / logfmt
+    # timestamp 默认 local，多时区场景可改为 utc
+))
 ```
 
 ### 在 pytest 中使用
@@ -100,7 +100,7 @@ def test_with_logging():
 │     ├─ PositionalArgumentsFormatter (% 格式化) ← v3.38.5  │
 │     ├─ ExtraAdder (extra 参数) ← v3.38.5                  │
 │     ├─ sanitize_sensitive_data (脱敏)                      │
-│     ├─ TimeStamper (时间戳)                                │
+│     ├─ _make_timestamper (RFC 3339 毫秒时间戳)             │
 │     ├─ CallsiteParameterAdder (调用位置，可选)            │
 │     ├─ _add_trace_info (OpenTelemetry)                    │
 │     └─ wrap_for_formatter                                  │
@@ -214,33 +214,34 @@ logging:
 ### 开发环境配置
 
 ```python
+from df_test_framework.infrastructure.config import LoggingConfig
 from df_test_framework.infrastructure.logging import configure_logging
 
-configure_logging(
-    env="dev",
+configure_logging(LoggingConfig(
     level="DEBUG",
-    json_output=False,
-)
+    format="text",
+    timestamp="local",   # 本地调试时显示本地时区，带偏移
+))
 ```
 
 输出示例：
 ```
-2025-12-25 11:35:07.590123 [info     ] 用户登录          user_id=123 username=alice
+2026-05-27T16:30:45.123+08:00 [info     ] 用户登录          user_id=123 username=alice
 ```
 
 ### 生产环境配置
 
 ```python
-configure_logging(
-    env="prod",
+configure_logging(LoggingConfig(
     level="INFO",
-    json_output=True,
-)
+    format="json",
+    # timestamp 默认 local，可省略
+))
 ```
 
 输出示例：
 ```json
-{"event": "用户登录", "user_id": 123, "username": "alice", "timestamp": "2025-12-25 11:35:07.590123", "level": "info"}
+{"timestamp": "2026-05-27T16:30:45.123+08:00", "level": "info", "event": "用户登录", "user_id": 123, "username": "alice"}
 ```
 
 ---
@@ -286,30 +287,30 @@ log_date_format = "%Y-%m-%d %H:%M:%S"
 
 ### 日志输出效果
 
-**开发环境 (format: text)**：
+**开发环境 (format: text, timestamp: local)**：
 
 ```
 -------------------------- live log sessionstart --------------------------
-2025-12-25 10:27:55.139176 [info] 环境信息已添加到Allure报告 [allure.helper]
+2026-05-27T10:27:55.139+08:00 [info] 环境信息已添加到Allure报告 [allure.helper]
 
 tests/api/test_example.py::TestExample::test_uow_pattern
 ----------------------------- live log setup ------------------------------
-2025-12-25 10:27:55.451533 [info] 数据库连接已建立 [databases.database]
+2026-05-27T10:27:55.451+08:00 [info] 数据库连接已建立 [databases.database]
 PASSED
 ---------------------------- live log teardown ----------------------------
-2025-12-25 10:27:55.479190 [info] UnitOfWork: 数据已回滚 [databases.uow]
+2026-05-27T10:27:55.479+08:00 [info] UnitOfWork: 数据已回滚 [databases.uow]
 ```
 
-**生产环境 (format: json)**：
+**生产环境 (format: json, timestamp: local)**：
 
 ```json
-{"timestamp": "2025-12-25T10:27:55.139176Z", "level": "info", "event": "环境信息已添加到Allure报告", "logger": "allure.helper"}
+{"timestamp": "2026-05-27T10:27:55.139+08:00", "level": "info", "event": "环境信息已添加到Allure报告", "logger": "allure.helper"}
 ```
 
-**Loki/Prometheus (format: logfmt)**：
+**Loki/Prometheus (format: logfmt, timestamp: local)**：
 
 ```
-timestamp=2025-12-25T10:27:55.139176Z level=info logger=allure.helper event="环境信息已添加到Allure报告"
+timestamp=2026-05-27T10:27:55.139+08:00 level=info logger=allure.helper event="环境信息已添加到Allure报告"
 ```
 
 ---
@@ -403,7 +404,7 @@ log_cli_date_format = "%Y-%m-%d %H:%M:%S"
 
 **生产环境**：
 ```python
-configure_logging(env="prod", level="INFO")
+configure_logging(LoggingConfig(level="INFO", format="json"))
 ```
 
 ### 3. 结构化日志

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/docs/releases/README.md

@@ -1,6 +1,6 @@
 # Release Notes 发布说明索引
 
-> 当前版本：**v4.7.2** · 最近更新：2026-05-26
+> 当前版本：**v4.7.3** · 最近更新：2026-05-27
 
 完整变更摘要见 [CHANGELOG.md](../../CHANGELOG.md)。
 
@@ -10,7 +10,8 @@
 
 | 版本 | 发布日期 | 核心特性 |
 |------|----------|----------|
-| **[v4.7.2](v4.7.2.md)** ⭐ 当前 | 2026-05-26 | 脚手架 `flows/` 目录 + 文档结构补强 + pytest addopts 收敛 |
+| **[v4.7.3](v4.7.3.md)** ⭐ 当前 | 2026-05-27 | 日志时间戳标准化：RFC 3339 毫秒 + 显式时区，`use_utc` → `timestamp` |
+| **[v4.7.2](v4.7.2.md)** | 2026-05-26 | 脚手架 `flows/` 目录 + 文档结构补强 + pytest addopts 收敛 |
 | **[v4.7.1](v4.7.1.md)** | 2026-05-22 | 修复 `_auto_allure_observer` 未取消订阅导致 Allure 重复记录 |
 | **[v4.7.0](v4.7.0.md)** | 2026-05-19 | `RuntimeContext.metadata` + 命名 AsyncDatabase 多数据库注册 |
 

df_test_framework-4.7.3/docs/releases/v4.7.3.md

@@ -0,0 +1,83 @@
+# v4.7.3 - 日志时间戳标准化
+
+**发布日期**: 2026-05-27
+
+## 概述
+
+本版本对日志时间戳格式做了一次彻底标准化：统一使用 RFC 3339 毫秒精度 + 显式时区，移除了语义不清晰的 `use_utc` 布尔字段，所有 handler 的时间戳策略全局一致。
+
+---
+
+## 破坏性变更
+
+### `LoggingConfig.use_utc` 已移除
+
+| | 旧版（≤ v4.7.2） | 新版（v4.7.3+） |
+|---|---|---|
+| **YAML** | `use_utc: true` | `timestamp: utc` |
+| **YAML** | `use_utc: false` | `timestamp: local` |
+| **环境变量** | `LOGGING__USE_UTC=true` | `LOGGING__TIMESTAMP=utc` |
+| **Python** | `LoggingConfig(use_utc=True)` | `LoggingConfig(timestamp="utc")` |
+
+**迁移方式**：全局搜索 `use_utc` 替换为 `timestamp`，将布尔值改为字符串字面量。
+
+---
+
+## 新增
+
+### `LoggingConfig.timestamp`
+
+```yaml
+logging:
+  timestamp: local    # 默认，输出 2026-05-27T16:30:45.123+08:00
+  # timestamp: utc    # 多时区团队 / 容器时区未配置时
+```
+
+| 值 | 输出示例 | 适用场景 |
+|----|---------|---------|
+| `local`（默认） | `2026-05-27T16:30:45.123+08:00` | 时区统一的团队，日志直接可读 |
+| `utc` | `2026-05-27T08:30:45.123Z` | 多时区团队、容器时区未配置时 |
+
+两种模式均严格符合 RFC 3339：带时区、毫秒精度、ISO 8601 分隔符。日志聚合系统（Loki/ES/CloudWatch）对两种格式均能正确解析。
+
+---
+
+## 改进
+
+### 时间戳格式统一
+
+**之前**：`format: json` 隐式强制 UTC，`format: text` 输出本地时间但**不含时区偏移**（`2025-12-25 11:35:07.590123`），是数据损坏。
+
+**现在**：`timestamp` 与 `format` 完全正交，任意组合均输出带时区的 RFC 3339 毫秒时间戳。
+
+```
+format: text + timestamp: utc   → 2026-05-27T08:30:45.123Z [info] ...
+format: json + timestamp: local → {"timestamp": "2026-05-27T16:30:45.123+08:00", ...}
+```
+
+### 共享 processor 链
+
+**之前**：`ExtraAdder` 仅在 `foreign_pre_chain` 中，structlog 和第三方日志维护两套 processor 链。
+
+**现在**：统一共享链，所有 handler（控制台 / 文件 / pytest）使用同一套 processor，时间戳策略全局一致，不存在同一次运行中不同 handler 时间格式不同的问题。
+
+---
+
+## 配置参考
+
+```yaml
+# 时区统一团队（默认 local，无需显式配置）
+logging:
+  level: INFO
+  format: json
+  # timestamp: local  # 默认值，可省略
+
+# 多时区团队 / 容器时区未配置时
+logging:
+  timestamp: utc
+```
+
+```bash
+# 环境变量
+LOGGING__TIMESTAMP=local   # 默认；多时区场景改为 utc
+```

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "df-test-framework"
-version = "4.7.2"
+version = "4.7.3"
 description = "基于交互模式的现代化测试自动化框架，支持多种测试场景"
 authors = [{name = "DF QA Team", email = "qa@example.com"}]
 readme = "README_PYPI.md"

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/src/df_test_framework/__init__.py

@@ -7,7 +7,7 @@ DF 测试自动化框架
 变更历史见 CHANGELOG.md，发布说明见 docs/releases/。
 """
 
-__version__ = "4.7.2"
+__version__ = "4.7.3"
 __author__ = "DF QA Team"
 
 # ==============================================================================

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/src/df_test_framework/cli/templates/generators/env_files.py

@@ -174,7 +174,7 @@ observability:
 logging:
   level: INFO
   format: text          # text（开发）或 json（生产）
-  # use_utc: false      # 生产环境建议启用 UTC 时间戳
+  # timestamp: utc      # 需要 UTC 时可显式配置，默认 local
   # add_callsite: false # 调试时启用，添加文件名/函数名/行号
 
 # ============================================================
@@ -269,7 +269,7 @@ observability:
 logging:
   level: INFO
   format: text          # text（开发）或 json（生产）
-  # use_utc: false      # 生产环境建议启用 UTC 时间戳
+  # timestamp: utc      # 需要 UTC 时可显式配置，默认 local
   # add_callsite: false # 调试时启用，添加文件名/函数名/行号
 
 # ============================================================
@@ -452,7 +452,7 @@ observability:
 logging:
   level: INFO
   format: text          # text（开发）或 json（生产）
-  # use_utc: false      # 生产环境建议启用 UTC 时间戳
+  # timestamp: utc      # 需要 UTC 时可显式配置，默认 local
   # add_callsite: false # 调试时启用，添加文件名/函数名/行号
 
 # ============================================================
@@ -610,7 +610,7 @@ http:
 logging:
   level: INFO
   format: json          # 预发布环境使用 JSON 格式
-  use_utc: true         # 使用 UTC 时间戳
+  timestamp: local      # 需要 UTC 时显式配置，默认 local
   # 脱敏默认启用，无需配置
 
 observability:
@@ -653,7 +653,7 @@ http:
 logging:
   level: WARNING        # 生产环境只记录警告及以上
   format: json          # 生产环境使用 JSON 格式
-  use_utc: true         # 使用 UTC 时间戳（ISO 8601）
+  timestamp: local      # 需要 UTC 时显式配置，默认 local
   file: logs/test.log   # 日志文件
   rotation: "500 MB"    # 日志轮转
   retention: "30 days"  # 日志保留
@@ -846,7 +846,7 @@ OBSERVABILITY__ALLURE_RECORDING=true
 # ============================================================
 LOGGING__LEVEL=INFO
 LOGGING__FORMAT=text
-# LOGGING__USE_UTC=false       # 生产环境建议启用 UTC 时间戳
+LOGGING__TIMESTAMP=local      # 需要 UTC 时改为 utc，默认 local
 # LOGGING__ADD_CALLSITE=false  # 调试时启用，添加文件名/函数名/行号
 # LOGGING__FILE=logs/app.log   # 日志文件路径
 
@@ -949,7 +949,7 @@ HTTP__TIMEOUT=30
 
 LOGGING__LEVEL=WARNING
 LOGGING__FORMAT=json
-LOGGING__USE_UTC=true
+LOGGING__TIMESTAMP=local      # 需要 UTC 时改为 utc，默认 local
 LOGGING__FILE=logs/test.log
 OBSERVABILITY__DEBUG_OUTPUT=false
 # 脱敏默认启用，无需配置

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/src/df_test_framework/cli/templates/generators/settings_enhanced.py

@@ -212,9 +212,9 @@ class {ProjectName}Settings(FrameworkSettings):
     logging: LoggingConfig = Field(
         default_factory=lambda: LoggingConfig(
             level="INFO",
-            format="text",        # text（开发）或 json（生产）
-            # use_utc=False,      # 生产环境建议启用
-            # add_callsite=False, # 调试时启用
+            format="text",          # text（开发）或 json（生产）
+            # timestamp="utc",      # 需要 UTC 时可显式配置，默认 local
+            # add_callsite=False,   # 调试时启用
         ),
         description="日志配置"
     )

{df_test_framework-4.7.2 → df_test_framework-4.7.3}/src/df_test_framework/infrastructure/config/schema.py

@@ -693,9 +693,9 @@ class LoggingConfig(BaseModel):
     )
     enable_console: bool = Field(default=True, description="Enable console logging")
 
-    use_utc: bool = Field(
-        default=False,
-        description="使用 UTC 时间戳（ISO 8601 格式），生产环境推荐启用",
+    timestamp: Literal["utc", "local"] = Field(
+        default="local",
+        description="时间戳时区策略: local(RFC 3339 + 本地偏移，默认) / utc(RFC 3339 + Z)",
     )
     use_orjson: bool = Field(
         default=True,