df-test-framework 4.7.5__tar.gz → 4.8.0__tar.gz

{df_test_framework-4.7.5 → df_test_framework-4.8.0}/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.4
-- **更新时间**: 2026-06-29
+- **版本**: v4.8.0
+- **更新时间**: 2026-08-10
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.5 → df_test_framework-4.8.0}/CHANGELOG.md

@@ -7,6 +7,46 @@
 
 ## [Unreleased]
 
+## [4.8.0] - 2026-08-10
+
+### ✨ 新增
+
+- **`compute_sign` 支持固定字段顺序与带键名的密钥**：新增 `field_order` 与 `secret_key_name` 两个参数。
+  - `field_order`：按给定顺序拼接，`params` 里缺失的字段按空串占位（顺序型协议要求占位而非跳过，跳过会让分隔符错位）。不传时仍按 key 字母序，行为不变。
+  - `secret_key_name`：密钥拼成 `"{name}={secret}"` 并用 `separator` 连接，形如 `…&key=xxx`。不传时密钥直接贴住拼接串，与历史一致。
+  - 背景：此前 `concat_mode` / `separator` / `secret_position` 三个维度可配，唯独排序写死 `sorted(params.keys())`，因为该函数抽取自「字母序 + 只拼 value」这一种规则。回调类协议常按业务语义排字段（事件→主体→时间→追踪），字母序拼不出来，只能在项目侧另写一份签名实现。
+  - 兼容性：两个参数均默认 `None`，不传时签名结果与既有版本逐字节一致，存量调用方无需改动。
+
+- **签名模块拆成拼接层与摘要层**：新增 `build_sign_source`（参数 → 签名源）与 `digest_sign`（签名源 → 签名）两个公开函数，`compute_sign` 成为两者串联的便捷入口，签名与行为完全不变。
+  - 动机：真实协议的规则几乎两两不同（字母序/倒序/固定序、空值占位/跳过、`k=v`/`kv`/只拼值、密钥在首/尾/**中间**、大小写输出）。继续往 `compute_sign` 加关键字参数追不上，且有些规则根本表达不了——例如平安的 `join.toUpperCase() + key + timestamp`，密钥后面还接 timestamp，任何 `secret_position` 组合都拼不出。
+  - 现在这类协议自己拼签名源再调 `digest_sign` 即可，不必等框架加参数。
+  - 同批新增的拼接维度：`skip_empty`（跳过空值）、`trailing_separator`（每项后带分隔符）、`key_value_joiner`（键值连接符，支持 `kv` 无等号）、`field_order` 增加 `"sorted_desc"` / `"as_given"`、`output_case`（大写 hex 输出）。
+  - `params` 值不再要求是字符串：内部统一 `str()`，`None` 视作空串，省去每个调用方自己转。
+  - 测试以六个真实协议为样本（虚拟充值对外 API、NNK 券状态回调、供应链 SDK、平安、移动、上海移动），验证的是"真实规则拼不拼得出来"，而非单个参数是否生效。
+
+- **国密 SM2/SM3/SM4**：`sm3()`、`sm2_encrypt/sm2_decrypt`、`sm4_encrypt/sm4_decrypt`，需 `gm` 可选依赖（`pip install df-test-framework[gm]`）。
+  - SM3 也接进 `digest_sign(..., algorithm="sm3")`，用于以 SM3 替代 MD5/SHA-256 的接口签名。
+  - SM4 默认 ECB + PKCS7 填充（国密接口文档普遍规定 `SM4/ECB/PKCS5Padding`，16 字节分组下 PKCS5 与 PKCS7 等价），另支持 CBC。
+  - SM2 输出 `C1C3C2` 且 C1 带 `04` 未压缩点前缀 —— 与 Java BouncyCastle `SM2Engine` 直接互通。解密侧对不带 `04` 的密文自动补齐，兼容其他库的产出。
+  - 测试用 GM/T 0004-2012（SM3）与 GB/T 32907-2016（SM4）标准向量，并跑通一条完整的信封加密协议（SM4 加业务参数 → SM2 加 SM4 密钥 → SM3 签名），验证三个原语能直接拼出协议报文。
+
+  **依赖选型 —— 为什么是 `gmalg` 而不是更常见的 `gmssl`**：国密官方只发标准、不出参考实现，Python 生态因此质量参差，选型硬指标是能否与 Java 后端（BouncyCastle）互通。
+  - `gmalg` 1.1.1（2026-01）：纯 Python 零依赖，SM2 密文默认就是带 `04` 的 `C1C3C2`，实测密文结构 `65+32+16=113` 字节与对接文档逐字对应；306 star / 2 open issues。
+  - `gmssl`（py-gmssl）3.2.2：PyPI 停在 2022-06、48 个 open issue。密文不带 `04`（[#101](https://github.com/duanhongyi/gmssl/issues/101)）；`lstrip("04")` 按字符集而非前缀剥离会破坏以 `0`/`4` 开头的公钥（[#96](https://github.com/duanhongyi/gmssl/issues/96)，实测约 1/8 公钥受影响）；**解密不校验 C3，密文出错时静默返回垃圾数据**——对测试代码是最坏的失败模式；另有 10-20% 随机解密失败（[#102](https://github.com/duanhongyi/gmssl/issues/102)）。
+  - 官方 `gmssl-python` 是 GmSSL C 库的 ctypes 绑定，需先编译 C 库；`tongsuopy` 发布版无 SM2 加解密 API；`fastgm` 已停更。均不适合测试执行机。
+
+- **`sha1()`**：用于仍在使用 SHA-1 的遗留签名协议，`digest_sign` 同步支持 `algorithm="sha1"`。
+
+### ⚠️ 行为变更
+
+- **`compute_sign` 的 HMAC 密钥不再进消息体**：`algorithm="hmac-sha256"` 时密钥此前既被拼进签名源、又作 HMAC 密钥，等于用了两次。HMAC 的设计前提就是密钥不进消息体，拼进去既不增强安全性，也和标准 HMAC 协议（AWS SigV4、GitHub webhook）对不上。修复后 HMAC 下 `secret_position` / `secret_key_name` 一并失效。
+  - **影响面**：`hmac-sha256` 的签名输出会变；非 HMAC 算法逐字节不变 —— 已用 1296 组参数/算法/密钥组合验证，972 组非 HMAC 全部一致，324 组差异全部落在 `hmac-sha256`。
+  - 确有协议要求密钥同时出现在消息体里时，用 `build_sign_source` + `digest_sign` 自行组合。
+
+### 🔧 改进
+
+- **`SignatureMiddleware` 的签名规则委托给 `compute_sign`**：此前中间件另有一份签名实现，与 `compute_sign` 在 HMAC 语义上不一致（中间件是对的）。收敛为一处后两者不会再漂移，收敛前后逐组比对 72 种组合，签名结果完全一致。附带：算法取值非法时的报错文案从英文 `Unknown algorithm` 变为框架统一的中文 `不支持的算法`。
+
 ## [4.7.5] - 2026-06-29
 
 ### ✨ 新增

{df_test_framework-4.7.5 → df_test_framework-4.8.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.7.4
-- **更新时间**: 2026-06-29
+- **版本**: v4.8.0
+- **更新时间**: 2026-08-10
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.5 → df_test_framework-4.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.7.5
+Version: 4.8.0
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework
@@ -78,6 +78,8 @@ Requires-Dist: asyncpg>=0.29.0; extra == 'database-async'
 Provides-Extra: database-mssql
 Requires-Dist: aioodbc>=0.5.0; extra == 'database-mssql'
 Requires-Dist: pyodbc>=5.1.0; extra == 'database-mssql'
+Provides-Extra: gm
+Requires-Dist: gmalg>=1.1.1; extra == 'gm'
 Provides-Extra: kafka
 Requires-Dist: confluent-kafka>=2.12.0; extra == 'kafka'
 Provides-Extra: mq

{df_test_framework-4.7.5 → df_test_framework-4.8.0}/README.md

@@ -1,7 +1,7 @@
 # DF Test Framework
 
-> **版本**: v4.7.4
-> **更新时间**: 2026-06-29
+> **版本**: v4.8.0
+> **更新时间**: 2026-08-10
 > 简单、强大、可扩展的现代化 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.5 → df_test_framework-4.8.0}/docs/ESSENTIAL_DOCS.md

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

{df_test_framework-4.7.5 → df_test_framework-4.8.0}/docs/README.md

@@ -1,6 +1,6 @@
 # DF Test Framework 文档中心
 
-> 版本：v4.7.4 · 最近更新：2026-06-29
+> 版本：v4.8.0 · 最近更新：2026-08-10
 > 现代化 Python 测试自动化框架的官方知识库。
 
 ---
@@ -97,7 +97,7 @@
 | [插件 Hook 扩展指南](guides/plugin_hooks_guide.md) ⭐ | 注册插件、注入全局中间件、挂接测试/会话生命周期 |
 | [插件系统指南](guides/plugins_guide.md) | Pluggy Hooks，自定义插件 |
 | [扩展点指南](guides/extensions.md) | Hook 接入自定义能力（历史参考） |
-| [工具函数指南](guides/helpers_guide.md) | 加解密、哈希、签名、公网 IP |
+| [工具函数指南](guides/helpers_guide.md) | 哈希、API 签名、AES / 国密 SM2·SM3·SM4 加解密、公网 IP |
 
 ---
 

df_test_framework-4.8.0/docs/guides/helpers_guide.md

@@ -0,0 +1,464 @@
+# 工具函数使用指南
+
+> **最后更新**: 2026-08-08
+> **引入版本**: v4.2.0（签名两层拆分与国密支持见 CHANGELOG [Unreleased]）
+
+## 概述
+
+`infrastructure/helpers` 模块提供测试中常用的工具函数，包括哈希计算、AES / 国密加解密、API 签名和公网 IP 探测。
+
+**设计原则**：
+- 哈希/签名/网络工具基于 stdlib，**零额外依赖**
+- AES 加解密需安装 `crypto` 可选依赖组（`pycryptodome`）
+- 国密 SM2/SM3/SM4 需安装 `gm` 可选依赖组（`gmalg`）
+- 所有函数均为纯函数，无���态，线程安全
+
+---
+
+## 快速开始
+
+```python
+from df_test_framework import md5, sha1, sha256, hmac_sha256, compute_sign, get_public_ip
+
+# 哈希
+md5("hello")           # '5d41402abc4b2a76b9719d911017c592'
+sha256("hello")        # '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+hmac_sha256("hello", secret="my_secret")
+
+# API 签名
+params = {"userId": "123", "productCode": "P001"}
+sign = compute_sign(params, secret="my_api_key")
+
+# 协议拼法特殊时，拆成两层自己组合
+from df_test_framework import build_sign_source, digest_sign
+source = build_sign_source(params, concat_mode="key_value", separator="&")
+sign = digest_sign(source + api_key, algorithm="sha256")
+
+# 国密（需 gm 可选依赖）
+from df_test_framework import sm3, sm4_encrypt, sm2_encrypt
+sm3("abc")
+
+# 公网 IP
+ip = get_public_ip()   # e.g., "113.57.21.67"
+```
+
+---
+
+## 哈希函数
+
+基于 Python stdlib `hashlib`，无额外依赖。
+
+### md5
+
+```python
+from df_test_framework import md5
+
+md5("hello")
+# '5d41402abc4b2a76b9719d911017c592'
+```
+
+返回 32 位小写 hex 字符串。
+
+### sha256
+
+```python
+from df_test_framework import sha256
+
+sha256("hello")
+# '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+```
+
+返回 64 位小写 hex 字符串。
+
+### hmac_sha256
+
+```python
+from df_test_framework import hmac_sha256
+
+hmac_sha256("hello", secret="my_secret")
+```
+
+返回 64 位小写 hex HMAC-SHA256 签名。
+
+---
+
+## API 参数签名
+
+签名协议千差万别，但都由两步组成：**把参数拼成签名源**，再**对签名源做摘要**。
+模块按这两步拆开，各自可单独使用：
+
+| 函数 | 职责 |
+|------|------|
+| `build_sign_source` | 参数 → 签名源（排序、拼接、密钥位置） |
+| `digest_sign` | 签名源 → 签名（算法、输出大小写） |
+| `compute_sign` | 两步串联的便捷入口，覆盖绝大多数协议 |
+
+### 基本用法
+
+```python
+from df_test_framework import compute_sign
+
+params = {"euserId": "123", "productCode": "P001", "buyNum": "1"}
+sign = compute_sign(params, secret="my_api_key")
+# 排序: buyNum, euserId, productCode → "1" + "123" + "P001" + "my_api_key" → MD5
+```
+
+### 参数说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `params` | `dict[str, Any]` | 必填 | 参与签名的参数。值统一 `str()` 转换，`None` 视作空串 |
+| `secret` | `str` | 必填 | 签名密钥 |
+| `algorithm` | `str` | `"md5"` | `"md5"` / `"sha1"` / `"sha256"` / `"sm3"` / `"hmac-sha256"` |
+| `concat_mode` | `str` | `"values_only"` | `"values_only"` 只拼值；`"key_value"` 拼键值对 |
+| `separator` | `str` | `""` | 各项之间的分隔符 |
+| `key_value_joiner` | `str` | `"="` | 键值连接符。部分协议直接 `keyvalue` 相连，传空串 |
+| `field_order` | `str \| Sequence[str]` | `"sorted"` | `"sorted"` / `"sorted_desc"` / `"as_given"` 或显式字段序列 |
+| `skip_empty` | `bool` | `False` | 跳过空值（`None` 与空串） |
+| `trailing_separator` | `bool` | `False` | 参数段末尾补一个分隔符 |
+| `secret_position` | `str` | `"append"` | 密钥拼在首还是尾 |
+| `secret_key_name` | `str \| None` | `None` | 密钥的键名，拼成 `&key=xxx` 形式 |
+| `output_case` | `str` | `"lower"` | 输出大小写。部分协议要求大写 hex |
+
+### 字段顺序
+
+默认按 key 字母升序。**回调类协议常按业务语义排字段**（事件→主体→时间→追踪），
+这时传显式序列：
+
+```python
+compute_sign(
+    payload, api_key,
+    concat_mode="key_value", separator="&",
+    field_order=("eventType", "cardPwd", "cardNo", "occurTime"),
+    secret_key_name="key",
+)
+# → "eventType=USED&cardPwd=P1&cardNo=&occurTime=...&key=api_key" → MD5
+```
+
+给了 `field_order` 时，`params` 里**缺失的字段按空串占位**——顺序型协议要占位
+而非跳过，跳过会让分隔符错位。需要丢掉空字段时用 `skip_empty=True`。
+
+### HMAC 类算法的密钥语义
+
+`hmac-*` 下密钥**不会**被拼进签名源，只作 HMAC 密钥（`secret_position` /
+`secret_key_name` 随之失效）。HMAC 的设计前提就是密钥不进消息体，拼进去既不
+增强安全性，也和标准 HMAC 协议（AWS SigV4、GitHub webhook）对不上。
+
+```python
+compute_sign({"a": "1", "b": "2"}, "k", algorithm="hmac-sha256")
+# 签名源是 "12"（不含 k），k 作 HMAC 密钥
+```
+
+### 拼不出来的协议：自己拼签名源
+
+不要等框架加参数。穷举参数追不上真实世界的协议差异，而这条路对任何规则都成立：
+
+```python
+from df_test_framework import build_sign_source, digest_sign
+
+# 某协议：参数拼完整体转大写，密钥后面还要接 timestamp
+# 密钥不在两端而在中间，任何 secret_position 组合都表达不了
+body = build_sign_source(
+    params, concat_mode="key_value", key_value_joiner="", skip_empty=True
+)
+sign = digest_sign(body.upper() + api_key + timestamp, algorithm="sha256")
+```
+
+### 真实协议样例
+
+框架测试里以六个真实协议为样本（`tests/infrastructure/test_helpers.py`
+的 `TestRealWorldProtocols`），可直接照抄：
+
+| 协议特征 | 写法 |
+|---------|------|
+| 字母序 + 只拼值 + 末尾裸接密钥 | `compute_sign(params, key)` |
+| 固定序 + `k=v&` + 末尾 `key=密钥` | `field_order=(...), concat_mode="key_value", separator="&", secret_key_name="key"` |
+| 跳过空值 + 每项后带 `&` + 大写输出 | `skip_empty=True, trailing_separator=True, output_case="upper"` |
+| key 倒序 | `field_order="sorted_desc"` |
+| 密钥在中间 | 用 `build_sign_source` + `digest_sign` |
+
+---
+
+## AES 加解密
+
+需要安装 `crypto` 可选依赖：
+
+```bash
+pip install df-test-framework[crypto]
+# 或
+pip install pycryptodome
+```
+
+### 基本用法
+
+```python
+from df_test_framework import aes_encrypt, aes_decrypt
+
+# AES-CBC 加密（hex 输出）
+ciphertext = aes_encrypt("hello", key="0123456789abcdef", iv="abcdef0123456789")
+
+# AES-CBC 解密
+plaintext = aes_decrypt(ciphertext, key="0123456789abcdef", iv="abcdef0123456789")
+assert plaintext == "hello"
+```
+
+### 参数说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `plaintext`/`ciphertext` | `str` | 必填 | 明文/密文 |
+| `key` | `str \| bytes` | 必填 | 密钥（16/24/32 字节 → AES-128/192/256） |
+| `iv` | `str \| bytes \| None` | `None` | 初始向量（CBC 模式必填，16 字节） |
+| `mode` | `str` | `"CBC"` | AES 模式：`"CBC"` / `"ECB"` |
+| `encoding` | `str` | `"hex"` | 编码格式：`"hex"` / `"base64"` |
+
+### AES-ECB 模式
+
+```python
+# ECB 模式不需要 IV
+ciphertext = aes_encrypt("hello", key="0123456789abcdef", mode="ECB")
+plaintext = aes_decrypt(ciphertext, key="0123456789abcdef", mode="ECB")
+```
+
+### Base64 编码
+
+```python
+ciphertext = aes_encrypt(
+    "hello",
+    key="0123456789abcdef",
+    iv="abcdef0123456789",
+    encoding="base64",
+)
+plaintext = aes_decrypt(
+    ciphertext,
+    key="0123456789abcdef",
+    iv="abcdef0123456789",
+    encoding="base64",
+)
+```
+
+### 未安装依赖时的行为
+
+如果未安装 `pycryptodome`，导入 `aes_encrypt`/`aes_decrypt` 时会静默跳过（不报错）。调用时会抛出 `ImportError` 并提示安装方式。
+
+---
+
+## 国密 SM2/SM3/SM4
+
+需要安装 `gm` 可选依赖：
+
+```bash
+pip install df-test-framework[gm]
+# 或
+pip install gmalg
+```
+
+### 基本用法
+
+```python
+from df_test_framework import sm2_decrypt, sm2_encrypt, sm3, sm4_decrypt, sm4_encrypt
+
+# SM3 杂凑
+sm3("abc")   # '66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0'
+
+# 也可作签名算法
+compute_sign(params, api_key, algorithm="sm3")
+
+# SM4（默认 ECB + PKCS7，国密接口文档普遍规定 SM4/ECB/PKCS5Padding）
+ciphertext = sm4_encrypt("hello", key="0123456789abcdef")
+plaintext = sm4_decrypt(ciphertext, key="0123456789abcdef")
+
+# SM2（输出 C1C3C2，C1 带 04 前缀，与 Java BouncyCastle 直接互通）
+ciphertext = sm2_encrypt(b"sm4-key-16bytes!", public_key=server_pk)
+sm4_key = sm2_decrypt(ciphertext, private_key=client_sk)   # 返回 bytes
+```
+
+### 参数说明
+
+| 函数 | 关键参数 | 说明 |
+|------|---------|------|
+| `sm4_encrypt/decrypt` | `key` | 必须 16 字节；`str` 按 UTF-8 处理 |
+| | `mode` | `"ECB"`（默认）/ `"CBC"`；CBC 需 `iv` |
+| | `encoding` | `"base64"`（默认）/ `"hex"` |
+| `sm2_encrypt` | `public_key` | 裸点 65/64 字节，或 X.509 DER（91 字节）；hex、Base64 或 bytes |
+| `sm2_decrypt` | `private_key` | 裸值 32 字节或 PKCS#8 DER（150 字节）；**返回 `bytes`** 而非 `str` |
+
+`sm2_decrypt` 返回 `bytes` 是因为信封加密里这一步解出的通常是 SM4 密钥
+（16 字节二进制），强行 decode 会抛异常。文本明文自行 `.decode("utf-8")`。
+
+### 与 Java 后端互通：`04` 前缀是硬要求
+
+Java 侧用 BouncyCastle `SM2Engine`，C1 用未压缩点编码，**带 `04` 前缀**：
+
+```
+04 ‖ X(32) ‖ Y(32) ‖ C3(32) ‖ C2(n)
+```
+
+后端切分密文的依据就是这个（`c1Len = fieldSize/8*2 + 1 = 65`，那个 `+1` 就是 `04`）。
+少了它，后端会把 X 的首字节当成前缀，整个切错位。
+
+`sm2_encrypt` 默认输出的正是这个格式，**不需要手工补前缀**。
+`sm2_decrypt` 反过来对不带 `04` 的密文自动补齐，兼容其他库的产出。
+
+### 依赖选型：为什么是 `gmalg` 而不是 `gmssl`
+
+> 调研于 2026-08。国密官方（国家密码管理局/密标委）**只发标准、不出参考实现**，
+> 也不提供官方 SDK——只有标准文本 + 商用密码产品检测认证。
+> 没有权威参考实现来消解编码分歧，Python 生态因此质量参差，选型必须自己验。
+
+| 库 | 最新版 | 维护 | 依赖 | `04` 前缀 | 结论 |
+|----|--------|------|------|----------|------|
+| **gmalg** | 1.1.1 / 2026-01 | 306★，2 open issues | **纯 Python 零依赖** | 原生带 | **采用** |
+| gmssl (py-gmssl) | 3.2.2 / **2022-06** | 559★，**48 open** | 纯 Python | 不带 | 排除 |
+| gmssl-python（官方绑定） | 2.2.2 / 2023-10 | ctypes | **需装 libgmssl** | DER | 部署代价大 |
+| gmssl_pyx | 2.0.1 / 2026-04 | 活跃 | C 扩展 | DER，需转换 | 备选 |
+| tongsuopy（蚂蚁） | 1.0.1 / 2023-02 | — | cffi | — | **发布版无 SM2 加解密 API** |
+| fastgm | 0.4.1 / 2022-02 | 停更 | 需编译 | 不带 | 排除 |
+
+**star 数最高的 `gmssl` 恰恰不能用**，三个已验证的问题：
+
+1. **密文不带 `04`**（[#101](https://github.com/duanhongyi/gmssl/issues/101)）——
+   与 BouncyCastle 不互通，必须手工补/剥
+2. **解密不校验 C3**——密文出错时**静默返回垃圾数据而不报错**。
+   对测试代码这是最坏的失败模式：用例会"通过"但数据是错的
+3. `lstrip("04")` 按**字符集**而非前缀剥离（[#96](https://github.com/duanhongyi/gmssl/issues/96)），
+   会破坏以 `0`/`4` 开头的公钥——实测约 1/8 的随机公钥受影响
+
+另有 10-20% 随机解密失败的报告（[#102](https://github.com/duanhongyi/gmssl/issues/102)，2026-03 仍 open）。
+
+**两库算法本身是一致的**：`gmalg` 密文剥掉 `04` 后 `gmssl` 能解，反之补上也能解。
+差别只在 C1 的点编码约定——`gmssl` 不是算错，是选了与 Java 生态相反的那种。
+
+### 验证依据
+
+框架测试的期望值全部来自外部权威，不是拿底层库跟自己比
+（自比测试在换实现或底层算错时一样是绿的）：
+
+| 来源 | 覆盖 |
+|------|------|
+| GM/T 0004-2012 附录 A | SM3 标准向量 |
+| GB/T 32907-2016 | SM4 标准向量 |
+| 后端 `SM2Utils` 切分逻辑 | 密文布局 `04‖X‖Y‖C3‖C2` |
+| 对接文档「重要说明」 | 完整信封加密协议（见 `tests/infrastructure/test_gmcrypto.py`） |
+
+### 完整信封加密示例
+
+国密接口常见的三段式（SM4 加业务数据 → SM2 加 SM4 密钥 → SM3 签名）：
+
+```python
+import json, secrets
+
+sm4_key = secrets.token_bytes(16)                          # 1. 随机 SM4 密钥
+req_param = sm4_encrypt(json.dumps(business), sm4_key)     # 2. SM4 加业务参数
+req_key = sm2_encrypt(sm4_key, server_public_key)          # 3. SM2 加 SM4 密钥
+sign = sm3(req_param + api_key)                            # 4. SM3 签名
+
+payload = {"reqParam": req_param, "reqKey": req_key, "sign": sign, ...}
+```
+
+### 未安装依赖时的行为
+
+与 AES 一致：未安装 `gmalg` 时导入静默跳过，调用抛 `ImportError` 并提示安装方式。
+
+---
+
+## 公网 IP 探测
+
+```python
+from df_test_framework import get_public_ip
+
+ip = get_public_ip()
+print(ip)  # e.g., "113.57.21.67"
+```
+
+### 工作原理
+
+依次尝试以下公共服务，任一成功即返回：
+1. `httpbin.org/ip`
+2. `api.ipify.org`
+3. `ifconfig.me/ip`
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `timeout` | `int` | `10` | 每个服务的超时时间（秒） |
+
+### 使用场景
+
+- IP 白名单测试：测试前获取当前出口 IP，确认已加入白名单
+- 网络环境验证：确认测试机器的网络出口
+
+### 异常处理
+
+所有服务均不可用时抛出 `RuntimeError`：
+
+```python
+try:
+    ip = get_public_ip(timeout=5)
+except RuntimeError as e:
+    print(f"无法获取公网 IP: {e}")
+```
+
+---
+
+## 实际场景示例
+
+### 场景1：虚拟充值接口签名
+
+```python
+from df_test_framework import compute_sign
+
+def test_recharge(api_service_client):
+    params = {
+        "euserId": "U001",
+        "productCode": "PHONE_50",
+        "buyNum": "1",
+        "orderNo": "ORD20260402001",
+    }
+    sign = compute_sign(params, secret="my_api_key")
+    params["sign"] = sign
+
+    result = api_service_client.recharge(**params)
+    assert result["retCode"] == "0"
+```
+
+### 场景2：加密敏感参数
+
+```python
+from df_test_framework import aes_encrypt
+
+def test_create_order_with_encrypted_phone(order_api):
+    encrypted_phone = aes_encrypt(
+        "13800138000",
+        key="0123456789abcdef",
+        iv="abcdef0123456789",
+    )
+    response = order_api.create_order(phone=encrypted_phone)
+    assert response["success"] is True
+```
+
+### 场景3：IP 白名单验证
+
+```python
+from df_test_framework import get_public_ip
+
+def test_api_ip_whitelist(api_client):
+    ip = get_public_ip()
+    print(f"当前出口 IP: {ip}")
+    # 确认 IP 在白名单中，否则请求会被拒绝
+    response = api_client.get("/protected/data")
+    assert response.status_code != 403, f"IP {ip} 不在白名单中"
+```
+
+---
+
+## 相关文档
+
+- [装饰器使用指南](decorators_guide.md) - @api_class、@actions_class、@service_client
+- [HTTP 客户端指南](http_client_guide.md) - HTTP 客户端和中间件
+- [v4.2.0 发布说明](../releases/v4.2.0.md) - 完整变更日志
+
+---
+
+**完成时间**: 2026-04-02

{df_test_framework-4.7.5 → df_test_framework-4.8.0}/docs/releases/README.md

@@ -1,16 +1,23 @@
 # Release Notes 发布说明索引
 
-> 当前版本：**v4.7.4** · 最近更新：2026-06-29
+> 当前版本：**v4.8.0** · 最近更新：2026-08-10
 
 完整变更摘要见 [CHANGELOG.md](../../CHANGELOG.md)。
 
 ---
 
-## v4.7.x（当前系列）
+## v4.8.x（当前系列）
 
 | 版本 | 发布日期 | 核心特性 |
 |------|----------|----------|
-| **[v4.7.4](v4.7.4.md)** ⭐ 当前 | 2026-06-29 | `OmsReporterPlugin` 嵌入式 scope 路由：一次 Bootstrap 多次执行复用，`bind_execution` / `unbind_execution` |
+| **[v4.8.0](v4.8.0.md)** ⭐ 当前 | 2026-08-10 | 国密 SM2/SM3/SM4 + 签名模块两层拆分（`build_sign_source` / `digest_sign`）|
+
+## v4.7.x
+
+| 版本 | 发布日期 | 核心特性 |
+|------|----------|----------|
+| **[v4.7.5](v4.7.5.md)** | 2026-06-29 | 插件扩展 Hook 接线 + 可观测性实例级注入 |
+| **[v4.7.4](v4.7.4.md)** | 2026-06-29 | `OmsReporterPlugin` 嵌入式 scope 路由：一次 Bootstrap 多次执行复用，`bind_execution` / `unbind_execution` |
 | **[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 重复记录 |