feat(tests): 增强测试框架的 SQL 日志记录与覆盖率报告

- 在 ApiCase 中添加 SQL 日志记录功能，失败时输出日志以便于调试
- 更新 TestApp 以支持测试模式下的 SQL 日志缓冲，成功与失败的测试均可记录日志
- 改进 PrintCoverage 方法，优化覆盖率报告的输出逻辑，支持部分运行的接口显示
- 增加 Note 备注功能，提升测试用例的可读性与文档化效果
- 更新相关文档，详细说明新功能的使用场景与示例

docs/Testing_API测试框架.md

@@ -109,6 +109,7 @@ var OrderTest = CtrTest{
 
         // ======== 第三步：正确请求 + Verify 统一校验 ========
         a.WithSession(Map{"user_id": int64(1)}).
+            Note("quantity=3 用于校验总价: 29.9*3=89.7; 新订单 state=0(待付款)").
             JSON(Map{"goods_id": goodsId, "quantity": 3, "address": "XX路1号"}).
             Verify(func(a *Api) error {
                 // 响应值断言
@@ -234,6 +235,7 @@ Verify 统一校验（响应值断言 + 数据库状态校验，集中在一个
 |------|------|------|
 | 错误用例 | **必须** | 覆盖权限、参数、业务逻辑等异常路径 |
 | 测试数据准备 | 按需 | 接口依赖的前置数据用 `a.DB()` 插入 |
+| Note 备注 | 按需 | 用 `.Note(...)` 补充参数含义、枚举值说明、算法描述等上下文 |
 | 响应结构校验 | **必须** | 正确请求必须用第三参数校验 result 的类型和结构 |
 | Verify 校验 | **必须** | 在 Verify 内用 `a.Resp()` 断言响应值 + 用 `a.DB()` 校验数据库状态 |
 
@@ -394,6 +396,55 @@ a.WithSession(Map{"user_id": int64(1)}).
 | 删除类（Delete） | 响应值断言 + 校验记录已删除/软删除 |
 | 纯查询（Select） | 响应值断言（无需 DB 校验） |
 
+### 5. Note 备注
+
+`Note` 用于为测试用例附加说明文字，备注会显示在 API 调试控制台的用例详情中，也会写入 `api-spec.json`。Note 不影响测试逻辑，只提升可读性。
+
+**典型使用场景：**
+
+```go
+// 场景一：枚举值/状态码说明 — 当参数或校验涉及枚举值时，备注各值含义
+a.WithSession(Map{"user_id": int64(1)}).
+    Note("status: 0=待付款, 1=已付款, 2=已发货, 3=已完成, 4=已取消").
+    Query(Map{"status": "1"}).
+    Get("按状态查询订单", 0, Map{"total": int64(1), "data": Slice{Map{"id": int64(1)}}})
+
+// 场景二：算法/签名说明 — 接口涉及加密或计算逻辑时，简述算法
+a.Note("sign = MD5(smsProxyKey + timestamp), 有效期5分钟").
+    Form(Map{"phone": "13800138000", "sign": "abc123", "timestamp": "1700000000"}).
+    Post("发送验证码", 0, Map{"expire": int64(1)})
+
+// 场景三：参数值含义 — 说明测试数据的选取理由或计算依据
+a.WithSession(Map{"user_id": int64(1)}).
+    Note("quantity=3, 单价29.9, 预期总价: 29.9*3=89.7").
+    JSON(Map{"goods_id": goodsId, "quantity": 3}).
+    Post("创建订单", 0, Map{"id": int64(1), "total_price": float64(1.0)})
+
+// 场景四：前置依赖/调用顺序说明
+a.WithSession(Map{"user_id": int64(1)}).
+    Note("需先调用 /api/cart/add 加入购物车, cart_id 来自上一步返回").
+    JSON(Map{"cart_id": cartId}).
+    Post("购物车结算", 0, Map{"order_id": int64(1)})
+
+// 场景五：接口特殊行为说明
+a.WithSession(Map{"admin_id": int64(1)}).
+    Note("批量操作，单次最多100条; 部分失败不回滚，返回逐条结果").
+    JSON(Map{"ids": Slice{int64(1), int64(2), int64(3)}}).
+    Post("批量审核", 0, Map{"success": int64(1), "fail": int64(1)})
+```
+
+**建议使用 Note 的场景：**
+
+| 场景 | 示例 |
+|------|------|
+| 参数含枚举值（status/type/state 等） | `Note("type: 1=个人, 2=企业")` |
+| 涉及签名、加密、哈希等算法 | `Note("sign = MD5(appKey+timestamp+nonce)")` |
+| 测试数据有特定计算依据 | `Note("quantity=3, price=29.9, 预期 total=89.7")` |
+| 接口有调用顺序或前置依赖 | `Note("需先调用 /api/order/create 创建订单")` |
+| 接口有特殊行为（批量/异步/幂等等） | `Note("幂等接口，重复调用返回相同结果")` |
+
+> Note 是可选的，但在涉及枚举值、算法、前置依赖等场景时建议使用。好的备注能让其他开发者快速理解用例意图，也让调试控制台成为自文档化的 API 手册。
+
 ### 简写支持说明
 
 框架也支持以下简写用法：