ai-engineering-init 1.12.1 → 1.13.0

package/.cursor/skills/auto-test/SKILL.md

@@ -0,0 +1,453 @@
+---
+name: auto-test
+description: |
+  API 自动化测试技能。基于 Apifox MCP 读取接口文档，使用 Hurl 生成并执行真实 HTTP 测试，
+  支持单接口测试、单业务组合（CRUD 生命周期）、跨业务串联（多模块流程），生成 HTML/JSON 测试报告。
+  测试失败时自动调用 fix-bug 技能走标准修复流程。
+
+  触发场景：
+  - 需要对 API 接口进行自动化测试
+  - 需要验证接口是否符合文档定义
+  - 需要组合多个接口形成业务流程测试
+  - 需要生成接口测试报告
+  - 开发完成后需要回归测试验证
+
+  触发词：自动测试、auto-test、接口测试、API测试、Hurl、测试报告、回归测试
+---
+
+# API 自动化测试（Hurl + Apifox MCP）
+
+## 概述
+
+通过 Apifox MCP 读取接口文档 → AI 生成 Hurl 测试文件 → 执行真实 HTTP 请求 → 生成测试报告 → 失败项**自动调用 `/fix-bug` 走标准修复流程**。
+
+**前置依赖**：
+- Hurl CLI（`brew install hurl` / `winget install hurl` / `apt install hurl`）
+- Apifox MCP Server（已配置项目 ID 和 Access Token）
+- 后端服务运行中
+
+## 测试粒度
+
+| 粒度 | 说明 | 文件命名 | 示例 |
+|------|------|---------|------|
+| **单接口** | 一个 API 端点的正常+异常场景 | `{接口名}.hurl` | `create-order.hurl` |
+| **单业务组合** | 一个模块的 CRUD 生命周期 | `{模块}-lifecycle.hurl` | `order-lifecycle.hurl` |
+| **跨业务串联** | 多模块联动的完整业务流程 | `{流程名}-flow.hurl` | `menu-order-payment-flow.hurl` |
+
+## 文件结构
+
+```
+tests/hurl/
+├── env/
+│   ├── dev.env              # 开发环境变量
+│   ├── test.env             # 测试环境
+│   └── prod.env             # 生产环境（只读接口）
+├── {模块名}/                 # 按业务模块组织
+│   ├── {接口名}.hurl         # 单接口测试
+│   └── {模块}-lifecycle.hurl # 单业务组合
+├── flows/                   # 跨业务串联
+│   └── {流程名}-flow.hurl
+└── reports/                 # 测试报告（gitignore）
+    ├── index.html
+    └── report.json
+```
+
+## 系统接口请求响应规范
+
+> 详细参考：`references/api-conventions.md`（首次生成测试时必须读取）
+
+### 核心契约速查
+
+| 项目 | 规范 |
+|------|------|
+| 请求封装 | `{"content": { ... }}` （LeRequest） |
+| 成功码 | `code == 10000` |
+| 认证头 | `X-Token` + `merchant-id` + `Merchant-Id` |
+| 未授权 | 不带 X-Token → HTTP 401 |
+
+### 返回类型 → data 结构映射
+
+| Controller 返回类型 | data 结构 | 断言关键路径 |
+|---------------------|----------|-------------|
+| `Long`（save） | 雪花 ID | `$.data` isInteger |
+| `void`（delete/submit/export） | null | 仅验证 `$.code == 10000` |
+| `XxxVO`（detail） | 对象 | `$.data.id` exists |
+| `PageVO<T>`（设置类 page） | `$.data.records[]` | `$.data.records` isCollection |
+| `ReportBaseTotalVO<T>`（报表 page） | `$.data.resultPage.records[]` + `$.data.totalLine` | 分页 + 合计行 |
+
+### content 传值类型（最易出错）
+
+| 场景 | content 类型 | 示例 |
+|------|-------------|------|
+| 分页查询 | 对象 | `{"page":{"current":1,"size":10},"keyword":"xxx"}` |
+| 新增/编辑 | 对象 | `{"name":"xxx","entries":[...]}` |
+| 详情/删除/提交 | **裸 Long** | `{{id}}`（不是 `{"id":{{id}}}`） |
+
+> **关键区别**：detail/delete/submit 的 content 是**直接传 ID 值**，不需要包装成对象。
+
+## Hurl 语法速查
+
+### 请求头规范（必须遵守）
+
+每个需要认证的请求必须携带以下 Header：
+
+| Header | 来源 | 用途 |
+|--------|------|------|
+| `X-Token` | 环境变量 `{{x_token}}`（配置文件提供） | 认证令牌 |
+| `merchant-id` | 环境变量 `{{merchant_id}}` | 商户路由（数据源切换） |
+| `Merchant-Id` | 环境变量 `{{merchant_id_auth}}` | 商户权限校验 |
+
+### 基础请求 + 断言
+
+```hurl
+# 请求
+POST {{base_url}}/api/v2/web/order/add
+Content-Type: application/json
+X-Token: {{x_token}}
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{
+  "content": {
+    "menuId": 1001,
+    "quantity": 2
+  }
+}
+
+# 响应断言
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.msg" == "操作成功"
+jsonpath "$.data" isInteger
+```
+
+### 变量捕获（请求间传递数据）
+
+```hurl
+# 如果需要动态获取 Token，可以通过登录接口捕获
+POST {{base_url}}/api/v2/web/auth/login
+Content-Type: application/json
+{
+  "username": "{{username}}",
+  "password": "{{password}}"
+}
+
+HTTP 200
+[Captures]
+x_token: jsonpath "$.data.token"
+```
+
+> 注意：X-Token 优先使用 env 文件中预配置的值，避免每次都调登录接口。
+> 仅在测试登录流程本身或 Token 过期场景时，才通过登录接口动态获取。
+
+### 常用断言
+
+```hurl
+[Asserts]
+# 状态码
+status == 200
+
+# JSON 路径
+jsonpath "$.code" == 10000
+jsonpath "$.data" exists
+jsonpath "$.data" isCollection
+jsonpath "$.data.id" isInteger
+jsonpath "$.data.name" isString
+jsonpath "$.data.list" count > 0
+
+# 类型检查
+jsonpath "$.data.price" isFloat
+
+# 包含
+jsonpath "$.msg" contains "成功"
+
+# 正则
+jsonpath "$.data.phone" matches "^1[3-9]\\d{9}$"
+```
+
+### 环境变量文件格式
+
+```properties
+# env/dev.env
+base_url=http://192.168.97.235:58300
+
+# 认证 Token（X-Token 请求头，配置后所有请求自动携带）
+x_token=你的Token值
+
+# 商户路由（merchant-id 请求头，用于数据源切换）
+merchant_id=你的商户ID
+
+# 商户权限（Merchant-Id 请求头，用于权限校验）
+merchant_id_auth=你的商户ID
+```
+
+## 执行命令
+
+```bash
+# 运行单个测试
+hurl --test --variables-file tests/hurl/env/dev.env tests/hurl/order/create-order.hurl
+
+# 运行模块所有测试
+hurl --test --variables-file tests/hurl/env/dev.env tests/hurl/order/*.hurl
+
+# 运行全部测试 + 生成报告
+hurl --test \
+  --variables-file tests/hurl/env/dev.env \
+  --report-html tests/hurl/reports \
+  --report-json tests/hurl/reports/report.json \
+  tests/hurl/**/*.hurl
+
+# 传递动态变量（如时间戳避免唯一键冲突）
+TS=$(date +%s) && hurl --test \
+  --variables-file tests/hurl/env/dev.env \
+  --variable "voucher_type_ts=$TS" \
+  --variable "voucher_word_ts=$TS" \
+  tests/hurl/finance/*.hurl
+
+# 指定超时（毫秒）
+hurl --test --connect-timeout 5000 --max-time 30000 ...
+
+# 失败时继续执行（不中断）
+hurl --test --continue-on-error ...
+```
+
+## 生成测试的流程
+
+### 第一步：读取接口文档
+
+通过 Apifox MCP 读取指定模块的接口列表：
+- 接口路径、HTTP 方法
+- 请求参数（Header、Body、Query）
+- 响应结构（字段名、类型、示例值）
+
+### 第二步：读取 Param/VO 源码（关键！）
+
+**必须读取后端源码**以确保测试完整性：
+
+1. **Param 类**：提取所有查询条件字段，确保每个字段都有对应测试用例
+2. **VO 类**：提取所有响应字段，在断言中验证字段存在性和类型
+3. **Mapper XML**：理解 SQL 逻辑、JOIN 关系、动态条件
+
+```
+示例：SubjectDetailParam 有 startDate、endDate、areaId、canteenId、keyword
+→ 测试用例必须覆盖：
+  - 基础分页查询（startDate + endDate）
+  - keyword 搜索（科目编码/名称）
+  - 区域+食堂筛选（areaId + canteenId）
+  - 单日查询（startDate == endDate）
+  - 空结果区间（验证空数组返回）
+  - 分页第二页
+  - 导出接口
+  - 未授权测试
+```
+
+### 第三步：准备测试数据（先查后用，禁止硬编码）
+
+**核心原则：测试数据必须从真实环境动态获取，不能硬编码不存在的 ID 或编码。**
+
+```hurl
+# ✅ 正确：先查询获取真实数据，再用于后续请求
+# 0a. 获取真实食堂 ID
+POST {{base_url}}/api/v2/alloc/canteen/page-canteen
+...
+[Captures]
+canteen_id: jsonpath "$.data.records[0].canteenId"
+area_id: jsonpath "$.data.records[0].areaId"
+
+# 0b. 获取关联表的真实记录
+POST {{base_url}}/report/finance/setting/voucher-type/page
+...
+[Captures]
+voucher_type_id: jsonpath "$.data.records[0].id"
+```
+
+```hurl
+# ❌ 错误：硬编码不存在的引用数据
+{
+  "content": {
+    "costNo": "9999",        # 可能不存在
+    "voucherTypeId": 1       # 可能不存在
+  }
+}
+```
+
+**测试数据准备检查清单**：
+- [ ] 外键引用的 ID 通过查询接口动态获取
+- [ ] 业务编码（如 costNo）使用数据库中已存在的真实记录
+- [ ] 唯一键字段使用时间戳变量避免冲突（`{{xxx_ts}}`）
+- [ ] 创建的测试数据标记 summary 含 `auto-test` 便于识别清理
+- [ ] 测试结束后有清理步骤（删除测试数据）
+
+### 第四步：生成 .hurl 文件
+
+**查询条件完整覆盖**（每个 Param 字段都要有测试用例）：
+
+```
+单接口测试场景清单：
+1. 基础分页查询 — 必填参数，预期 code=10000，验证分页结构+VO 所有字段
+2. 合计行验证 — 如有 totalLine，验证所有合计字段存在
+3. 逐个查询条件 — 每个 Param 字段单独或组合测试
+4. 空结果验证 — 故意使用不匹配的条件，验证 records count == 0
+5. 分页翻页 — current=2 验证翻页正确
+6. 导出接口 — 验证 code=10000（异步导出返回 void）
+7. 未授权测试 — 不带 X-Token，预期 HTTP 401
+8. 数据清理 — 删除测试创建的数据
+```
+
+**数据正确性验证**（不只是结构存在，还要验证值合理）：
+
+```hurl
+# ✅ 结构验证 + 数据正确性
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.data.resultPage.records" isCollection
+jsonpath "$.data.resultPage.records" count > 0
+# VO 字段存在性
+jsonpath "$.data.resultPage.records[0].costNo" isString
+jsonpath "$.data.resultPage.records[0].costTypeName" isString    # 关联字段不能为 null
+jsonpath "$.data.resultPage.records[0].debitAmount" exists
+# 合计行数据合理性
+jsonpath "$.data.totalLine.debitAmount" exists
+jsonpath "$.data.totalLine.creditAmount" exists
+```
+
+### 第五步：执行并生成报告
+
+```bash
+hurl --test \
+  --variables-file tests/hurl/env/dev.env \
+  --report-html tests/hurl/reports \
+  --report-json tests/hurl/reports/report.json \
+  --continue-on-error \
+  tests/hurl/{模块}/*.hurl
+```
+
+### 第六步：解析报告
+
+读取 `report.json`，输出摘要：
+
+```markdown
+## 测试报告摘要
+
+| 状态 | 数量 | 占比 |
+|------|------|------|
+| PASS | 15   | 75%  |
+| FAIL | 3    | 15%  |
+| ERROR| 2    | 10%  |
+
+### 失败详情
+
+| 文件 | 接口 | 失败原因 |
+|------|------|---------|
+| order/create-order.hurl | POST /api/v2/web/order/add | 预期 code=10000，实际 code=40001 |
+| menu/query-menu.hurl | GET /api/v2/web/menu/get/1 | 预期 HTTP 200，实际 HTTP 500 |
+```
+
+### 第七步：失败项自动触发 fix-bug 流程
+
+**当测试存在失败项时，必须自动调用 `/fix-bug` 走标准修复流程：**
+
+```
+测试失败 → 分析失败原因 → 分类处理：
+
+1. 测试数据问题（非代码 Bug）：
+   - 引用数据不存在 → 修正测试用例中的数据
+   - 唯一键冲突 → 添加时间戳变量
+   - 权限/状态限制 → 调整测试前置条件
+
+2. 后端代码 Bug：
+   → 自动调用 Skill(fix-bug) 走标准修复流程
+   → 包含：排查报告 → 用户确认 → 修复代码 → 重跑测试验证
+
+3. 接口文档与实现不一致：
+   → 输出差异报告，等待用户确认以哪个为准
+```
+
+**fix-bug 自动触发条件**：
+- HTTP 状态码非预期（如 500）
+- 业务码非预期（如 code != 10000）
+- 响应字段缺失或类型不匹配
+- 关联字段为 null（如 costTypeName 为 null 说明 JOIN 失败）
+- 导出数据异常（原始字段暴露、金额未转换等）
+
+**Bug 报告格式**（传递给 fix-bug）：
+
+```
+Bug 信息：
+- 接口：{METHOD} {URL}
+- 请求参数：{request body}
+- 预期响应：{expected}
+- 实际响应：{actual}
+- Hurl 文件：{file path}
+- 失败断言：{assertion detail}
+- 关联源码：{Controller/Service/Mapper 文件路径}
+```
+
+## LeRequest 适配
+
+leniu 项目的 POST 请求体使用 `LeRequest<T>` 封装：
+
+```hurl
+# ✅ 正确：使用 content 包装 + 三个必要 Header
+POST {{base_url}}/api/v2/web/order/add
+Content-Type: application/json
+X-Token: {{x_token}}
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{
+  "content": {
+    "menuId": 1001,
+    "quantity": 2
+  }
+}
+
+# ❌ 错误：直接传业务字段 / 缺少 Header
+POST {{base_url}}/api/v2/web/order/add
+{
+  "menuId": 1001,
+  "quantity": 2
+}
+```
+
+## 已知陷阱（Lessons Learned）
+
+### 1. del_flag 约定不统一
+leniu 主表用 `2=正常, 1=删除`，但某些设置表（如 `finance_voucher_type`, `finance_voucher_word`）使用 `@TableLogic` 默认值 `0=正常, 1=删除`。**不要盲目统一，要检查每张表的实际约定。**
+
+### 2. 测试数据必须使用真实存在的引用数据
+关联查询（JOIN）依赖引用数据存在且状态正确。例如：
+- `cost_type` 表的 `state = 1` 才是有效记录
+- `costNo` 必须在 `cost_type` 中存在且 `state = 1`
+- 否则 LEFT JOIN 后关联字段（如 `costTypeName`）为 null
+
+### 3. 导出验证要点
+导出接口是异步的（返回 void → code=10000），需要额外关注：
+- VO 的 `@ExcelIgnore` 是否正确标记了内部字段
+- `@ExcelProperty(order=N)` 的顺序是否符合产品要求
+- 金额字段是否配置了 `converter = CustomNumberConverter.class`（分→元）
+- 枚举字段是否有对应的描述字段（如 submitStatus → submitStatusDesc）
+
+### 4. 唯一键冲突
+CRUD 生命周期测试中，新增记录的唯一键字段（如 typeCode）需要加时间戳变量：
+```hurl
+"typeCode": "AT_HURL_{{voucher_type_ts}}"
+```
+执行时通过 `--variable "voucher_type_ts=$(date +%s)"` 传入。
+
+### 5. 后端未重启
+修改后端代码后必须重启服务才能生效。如果测试结果不符合预期，先确认后端是否已重启。
+
+## .gitignore 配置
+
+```gitignore
+# Hurl 测试报告
+tests/hurl/reports/
+```
+
+## 注意
+
+- 测试文件（`.hurl`）需要 Git 管理，报告目录不需要
+- `env/*.env` 中的密码/Token 建议用环境变量替代，不要提交敏感信息
+- 如果是 leniu 项目的 POST 接口，请求体必须用 `{"content": {...}}` 包装
+- 生成测试前确保 Hurl CLI 已安装（`hurl --version`）
+- 与 `test-development` 技能的区别：本技能是真实 HTTP 请求的集成测试，`test-development` 是 JUnit5 单元测试/MockMvc 测试

package/.cursor/skills/auto-test/references/api-conventions.md

@@ -0,0 +1,260 @@
+# 系统接口请求响应规范（详细参考）
+
+> 本文件定义了 leniu 系统的标准接口契约。生成测试用例时**必须严格匹配**这些模式。
+> 安装框架后可直接使用，无需额外学习。
+
+## 统一请求格式
+
+所有 POST 接口使用 `LeRequest<T>` 封装，业务参数放在 `content` 字段内：
+
+```json
+{
+  "content": { /* 业务参数 */ }
+}
+```
+
+## 统一响应格式
+
+```json
+{
+  "code": 10000,       // 业务码：10000=成功，其他=失败
+  "msg": "操作成功",    // 提示信息
+  "data": ...          // 业务数据（类型取决于接口）
+}
+```
+
+## 接口类型与响应模式速查
+
+根据 Controller 方法返回值类型，确定 data 的结构和对应断言：
+
+| Controller 返回类型 | data 类型 | 示例 | Hurl 断言模板 |
+|---------------------|----------|------|--------------|
+| `Long` | 雪花 ID | `$.data` = 1234567890 | `jsonpath "$.data" isInteger` |
+| `void` | null | `$.data` = null | `jsonpath "$.code" == 10000` |
+| `XxxVO` | 对象 | `$.data.id`, `$.data.name` | `jsonpath "$.data.id" exists` |
+| `PageVO<XxxVO>` | 分页对象 | `$.data.records[0]` | 见「标准分页」 |
+| `ReportBaseTotalVO<XxxVO>` | 分页+合计 | `$.data.resultPage` + `$.data.totalLine` | 见「报表分页」 |
+
+## 标准分页响应（PageVO）
+
+**适用于**：设置类 CRUD 分页查询（如凭证类型、凭证字）
+
+```json
+{
+  "code": 10000,
+  "data": {
+    "records": [ { "id": 1, "name": "..." }, ... ],
+    "current": 1,
+    "size": 10,
+    "total": 25
+  }
+}
+```
+
+**Hurl 断言模板**：
+
+```hurl
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.data.records" isCollection
+jsonpath "$.data.current" exists
+jsonpath "$.data.size" exists
+jsonpath "$.data.total" exists
+# VO 字段逐一验证
+jsonpath "$.data.records[0].id" exists
+jsonpath "$.data.records[0].typeName" isString
+```
+
+## 报表分页响应（ReportBaseTotalVO）
+
+**适用于**：报表类分页查询（凭证列表、科目明细、科目汇总），响应包含 `resultPage`（分页数据）+ `totalLine`（合计行）
+
+```json
+{
+  "code": 10000,
+  "data": {
+    "resultPage": {
+      "records": [ { ... }, ... ],
+      "current": 1,
+      "size": 10,
+      "total": 25
+    },
+    "totalLine": {
+      "debitAmount": 1285100,
+      "creditAmount": 1285000
+    }
+  }
+}
+```
+
+**Hurl 断言模板**：
+
+```hurl
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+# 分页结构
+jsonpath "$.data.resultPage" exists
+jsonpath "$.data.resultPage.records" isCollection
+jsonpath "$.data.resultPage.current" exists
+jsonpath "$.data.resultPage.size" exists
+jsonpath "$.data.resultPage.total" exists
+# VO 字段逐一验证（首条记录）
+jsonpath "$.data.resultPage.records[0].voucherDate" isString
+jsonpath "$.data.resultPage.records[0].areaName" isString
+jsonpath "$.data.resultPage.records[0].costTypeName" isString  # 关联字段不能为 null
+# 合计行（只有数值字段和方向字段，其余为 null 占位）
+jsonpath "$.data.totalLine" exists
+jsonpath "$.data.totalLine.debitAmount" exists
+jsonpath "$.data.totalLine.creditAmount" exists
+```
+
+## 各操作类型的请求与响应模式
+
+### 1. 新增（save）→ 返回 Long ID
+
+```hurl
+# Controller: Long save(LeRequest<XxxSaveParam>)
+POST {{base_url}}/report/finance/voucher/save
+Content-Type: application/json
+X-Token: {{x_token}}
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{
+  "content": {
+    "areaId": {{area_id}},
+    "name": "auto-test数据，可删除",
+    "entries": [ ... ]
+  }
+}
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+[Captures]
+created_id: jsonpath "$.data"    # 捕获返回的 ID 供后续使用
+```
+
+### 2. 编辑（save 带 id / update）→ 返回 void
+
+```hurl
+# 方式一：save 带 id（delete-insert 模式，常用于主子表）
+POST {{base_url}}/report/finance/voucher/save
+{ "content": { "id": {{created_id}}, "name": "修改后", ... } }
+
+# 方式二：独立 update 接口
+POST {{base_url}}/report/finance/setting/voucher-type/update
+{ "content": { "id": {{type_id}}, "typeName": "修改后" } }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 3. 查详情（detail）→ 返回 XxxVO 对象
+
+```hurl
+# Controller: XxxDetailVO detail(LeRequest<Long>)
+# 注意：content 直接传 ID 值（Long），不需要包装对象
+POST {{base_url}}/report/finance/voucher/detail
+{ "content": {{created_id}} }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+jsonpath "$.data.id" exists
+jsonpath "$.data.areaName" isString
+jsonpath "$.data.entries" isCollection      # 子表数据
+jsonpath "$.data.entries" count == 2
+jsonpath "$.data.entries[0].id" exists
+```
+
+### 4. 删除（delete）→ 返回 void
+
+```hurl
+# Controller: void delete(LeRequest<Long>)
+# 注意：content 直接传 ID 值（Long）
+POST {{base_url}}/report/finance/voucher/delete
+{ "content": {{created_id}} }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 5. 提交/审批等状态变更 → 返回 void
+
+```hurl
+# Controller: void submit(LeRequest<Long>)
+POST {{base_url}}/report/finance/voucher/submit
+{ "content": {{created_id}} }
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 6. 分页查询（page）→ 返回 PageVO 或 ReportBaseTotalVO
+
+```hurl
+# 标准分页（设置类）
+POST {{base_url}}/report/finance/setting/voucher-type/page
+{
+  "content": {
+    "page": { "current": 1, "size": 10 }
+  }
+}
+
+# 报表分页（含合计行）
+POST {{base_url}}/report/finance/voucher/page
+{
+  "content": {
+    "page": { "current": 1, "size": 10 },
+    "startDate": "2026-03-01",
+    "endDate": "2026-03-31"
+  }
+}
+```
+
+### 7. 导出（export）→ 返回 void（异步）
+
+```hurl
+# Controller: void export(LeRequest<XxxPageParam>)
+# 异步导出，仅验证接口不报错
+POST {{base_url}}/report/finance/voucher/export
+{
+  "content": {
+    "page": { "current": 1, "size": 10 },
+    "startDate": "2026-03-01",
+    "endDate": "2026-03-31"
+  }
+}
+
+HTTP 200
+[Asserts]
+jsonpath "$.code" == 10000
+```
+
+### 8. 未授权测试 → 预期 HTTP 401
+
+```hurl
+# 去掉 X-Token 请求头
+POST {{base_url}}/report/finance/voucher/page
+Content-Type: application/json
+merchant-id: {{merchant_id}}
+Merchant-Id: {{merchant_id_auth}}
+{ "content": { "page": { "current": 1, "size": 10 } } }
+
+HTTP 401
+```
+
+## content 传值类型总结
+
+| 场景 | content 类型 | 示例 |
+|------|-------------|------|
+| 分页查询 | 对象（含 page + 查询条件） | `{"page":{"current":1,"size":10},"keyword":"xxx"}` |
+| 新增/编辑 | 对象（业务字段） | `{"name":"xxx","entries":[...]}` |
+| 查详情/删除/提交 | **裸 Long** | `{{id}}` （不是 `{"id": {{id}}}`） |
+
+> **关键区别**：detail/delete/submit 的 content 是**直接传 ID 值**，不需要包装成对象。这是最常见的错误。