# 埋点测试用例生成详解

---

## ⚠️ 生成测试用例前必读

**🚨 强制要求：生成任何测试用例前，必须先执行**

```bash
Read: testcase_output/高级房限时任务.md  # 读取格式标准
```

**格式要求**：
- ✅ 严格遵循标准案例的格式和风格
- ✅ 列表格式（`-` 开头），每个用例2-3行
- ✅ 简洁明了，无重复说明
- ❌ 禁止表格格式（`|` 分隔）
- ❌ 禁止冗长描述和多余解释

---

## 功能概述

从埋点文档自动生成标准化测试用例（Markdown + XMind）

**核心价值**：
- 自动提取字段、时机、次数信息
- 输出符合团队规范的格式
- 三维验证：字段完整性、触发时机、上报次数

**工作流程**：
```
飞书文档/Markdown → 分析 → 生成用例 → MD + XMind
```

---

## 输入要求

### 支持的格式

**1. 飞书文档链接**
```
https://wepie.feishu.cn/wiki/xxxxx
```

**2. Markdown 文档**
- 事件名称
- 埋点场景
- 事件属性（字段列表）

### 飞书文档处理流程

**🚨 强制执行顺序**：
```bash
1. echo "" > docs/feishu_doc.md        # 清空临时文件（防止读取旧内容）
2. 调用 feishu2md 转换飞书链接（见下方工具路径）
3. Read: docs/feishu_doc.md            # 读取转换后内容
4. 生成测试用例
```

**🚨 feishu2md 工具使用（必须遵守）**：
```bash
# 工具路径（相对于 ai-platform 根目录）：
python3 skills/common/feishu2md/scripts/feishu2md.py '<飞书链接>' <输出文件路径>

# 示例：
python3 skills/common/feishu2md/scripts/feishu2md.py \
  'https://wepie.feishu.cn/wiki/xxx' \
  skills/testing/data_testing/testcase_generation/docs/feishu_doc.md
```

**❌ 严禁行为**：
- 禁止跳过 feishu2md 直接使用本地 `docs/feishu_doc.md` 旧文件
- 禁止因 WebFetch 无法访问飞书就放弃转换，直接使用本地已有内容
- `docs/feishu_doc.md` 是临时文件，每次必须先清空再通过 feishu2md 重新生成，不可复用旧内容

---

## 输出内容

### 输出文件

1. **Markdown**：`testcase_output/{活动名称}.md`
   - 人类可读的测试用例文档
   - 可直接用于评审和执行

2. **XMind**：`testcase_output/{活动名称}.xmind`
   - 结构化思维导图
   - 可视化展示
   - ⚠️ 只生成单个 .xmind 文件，禁止生成同名文件夹包裹

### 用例结构（三维验证）

**1. 字段完整性验证**
- 必需字段存在
- 字段类型正确
- 枚举值合法

**2. 触发时机验证**
- 正确场景触发
- 错误场景不触发
- 特殊条件验证

**3. 上报次数验证**
- 次数符合预期
- 去重逻辑验证
- 批量操作验证

---

## AI 执行指令

### 强制性要求

**生成任何测试用例前必须做**：

1. **读取标准案例**
   ```bash
   Read: testcase_output/高级房限时任务.md
   ```
   - 这是唯一的格式标准
   - 用例长度、风格都要一致
   - 禁止自己发挥

2. **格式检查清单**
   - [ ] 列表格式（`-` 开头），不用表格
   - [ ] 每个用例2-3行
   - [ ] 标题只用业务名称（不加技术事件名）
   - [ ] 用例描述：`字段名 = 值（说明）`
   - [ ] 无重复说明

3. **禁止事项**
   - ❌ 冗长描述（不超过3行/用例）
   - ❌ 重复信息（不重复写"上报XXX事件"）
   - ❌ 多余解释（只写验证点）
   - ❌ 表格格式
   - ❌ 自己发挥
   - ❌ 创造数据：上报端、字段类型等信息必须来自埋点文档，文档未提供则写"文档未明确"，禁止自行编造

### 核心执行步骤

**步骤1：准备文档**
```bash
# 飞书链接（必须使用 feishu2md 工具，禁止直接读取本地旧文件）
1. echo "" > docs/feishu_doc.md                    # 清空临时文件
2. python3 skills/common/feishu2md/scripts/feishu2md.py '<飞书链接>' docs/feishu_doc.md  # 转换
3. Read: docs/feishu_doc.md                        # 读取转换后的新内容

# 本地文件
Read: <用户指定文件>
```

**步骤2：理解需求**
- 提取所有埋点事件
- 识别字段及类型
- 理解触发场景

**步骤3：设计用例**
- 参照标准案例格式
- 覆盖字段、时机、次数
- 考虑正常和异常场景

**步骤4：生成输出**
- 生成 Markdown（列表格式）
- 调用脚本生成 XMind
- 保存到 `testcase_output/`

---

## 输出格式标准

### Markdown 格式

**文档结构**：
```markdown
# {活动名称}

## 验收标准
[7条标准检查项，含"上报用户与埋点文档设计用户保持一致"]

---

## {事件显示名}

### 1. 埋点信息概览
- 事件名称、埋点场景、上报端
- ⚠️ 上报端：仅从埋点文档中提取，文档未明确则写"文档未提供"，禁止自行推断或编造

### 2. 字段列表
- 字段1、字段2...

### 3. 测试用例

#### 3.1 基础用例
验证基础字段和上报逻辑

- 事件名称：XXX
- 上报时机：...
- 上报次数：...
- 字段1 = 值（说明，类型：TYPE）
- 字段2 = 值（说明，类型：TYPE）

#### 3.2 枚举用例

##### 用例1：枚举场景1
- 字段 = 枚举值1（说明）

##### 用例2：枚举场景2
- 字段 = 枚举值2（说明）

#### 3.3 场景用例

##### 用例3：业务场景1
- 操作步骤
- 验证结果
- 字段值正确

#### 3.4 异常用例

##### 用例4：边界场景
- 边界条件
- 验证逻辑
```

### 格式关键点

**✅ 正确格式（列表）**：
```markdown
##### 用例1：首页加载icon曝光
- 进入首页，icon显示
- 上报IconView事件
- 所有字段值正确
```

**❌ 错误格式（表格）**：
```markdown
| TC-01-01 | 正常上报 | 包含 id 字段 | ✅ 存在 | P0 |
```

**为什么用列表？**
- XMind 脚本只解析列表格式
- 表格行会被跳过
- 列表更适合思维导图层级

---

## 生成 XMind

### 调用脚本

```python
import sys
sys.path.insert(0, 'scripts')
from generate_xmind import generate_xmind_from_markdown

generate_xmind_from_markdown(
    'testcase_output/活动名称.md',
    'testcase_output/活动名称.xmind'
)
```

### 脚本功能

1. 解析 Markdown 标题层级（#、##、###）
2. 构建思维导图结构
3. 生成 XMind 文件

**节点层级**：
```
根节点：活动名称
├── 事件1
│   ├── 字段完整性验证
│   │   └── 具体用例
│   ├── 触发时机验证
│   └── 上报次数验证
└── 事件2
    └── ...
```

### XMind 生成失败处理

**常见原因1：格式不兼容（最常见）**
- ❌ 使用了表格格式
- ⚠️ XMind 文件很小（<2KB）或内容为空
- ✅ 改为列表格式

**常见原因2：依赖缺失**
```bash
pip3 install xmind
```

**常见原因3：Markdown 格式错误**
- 标题层级不正确（必须用 ##、###、####）
- 列表格式不规范（必须用 `-` + 空格）

**降级方案**：
- 仅提供 Markdown 文档
- 提示用户手动创建 XMind
- 参考 `testcase_output/高级房限时任务.xmind`

---

## 示例：家族资金变更

### 输入文档摘录

```markdown
## 家族资金变更（服务器）

事件名称：FamilyCoin
埋点场景：家族资金变更时打点，打在变更的用户身上

事件属性：
- family_id = 家族ID (STRING)
- coin = 变更金币数量，获得为正，消耗为负 (NUMBER)
- source = 获得来源：家族捐献、家族任务、家族偷取
          消耗来源：家族扭蛋、家族派对房间
```

### 输出用例摘录

```markdown
# 家族资金变更

## 验收标准
- ✅ 事件名与设计文档保持一致
- ✅ 字段名与设计文档完全一致
- ...

---

## 家族资金变更

### 1. 埋点信息概览
- **事件名称**：FamilyCoin
- **埋点场景**：家族资金变更时打点
- **上报端**：服务器

### 2. 字段列表
- **family_id**：家族ID（STRING）
- **coin**：变更金币数量（NUMBER，正数=获得，负数=消耗）
- **source**：获得/消耗来源（STRING）

### 3. 测试用例

#### 3.1 基础用例
验证基础字段和上报逻辑

- 事件名称：FamilyCoin
- 上报时机：家族资金变更时立即上报
- 上报次数：资金变更1次上报1次
- family_id = 家族ID（正确，类型：STRING）
- coin = 变更金币数量（正确，类型：NUMBER）
- source = 获得/消耗来源（正确，类型：STRING）

#### 3.2 枚举用例

##### 用例1：获得来源 - 家族捐献
- source = "家族捐献"（枚举值正确）
- coin > 0（正数）

##### 用例2：消耗来源 - 家族扭蛋
- source = "家族扭蛋"（枚举值正确）
- coin < 0（负数）

#### 3.3 场景用例

##### 用例3：普通成员捐献资金
- 普通成员捐献资金给家族
- source = "家族捐献"，coin > 0
- 上报给捐献的成员

##### 用例4：抽取家族扭蛋
- 成员抽取家族扭蛋消耗资金
- source = "家族扭蛋"，coin < 0
- 上报给抽扭蛋的成员

#### 3.4 异常用例

##### 用例5：资金累计验证
- total_coin = 上次 total_coin + 本次 coin
- 验证累计资金计算正确

##### 用例6：正负数验证
- 获得资金：coin > 0
- 消耗资金：coin < 0
```

---

## 验收标准

生成的测试用例需满足：

### 完整性
- ✅ 覆盖所有埋点事件
- ✅ 每个事件都有三类用例
- ✅ 所有字段都有验证

### 准确性
- ✅ 用例ID不重复
- ✅ 字段类型正确
- ✅ 触发场景清晰
- ✅ 预期结果明确

### 可执行性
- ✅ 测试场景具体可操作
- ✅ 验证点明确可判断
- ✅ 预期结果可验证

### 格式规范
- ✅ Markdown 格式正确
- ✅ 用例编号连续
- ✅ XMind 文件可正常打开

### 文件输出
- ✅ Markdown 文件保存到 `testcase_output/`
- ✅ XMind 文件保存到 `testcase_output/`
- ✅ 文件名符合命名规范

---

## 注意事项

### 文档解析

**飞书文档特殊情况**：
- 包含图片：只提取文本
- 包含表格：提取为字段列表
- 包含代码块：识别为字段定义

**Markdown 要求**：
- 使用标准 Markdown 语法
- 避免复杂嵌套结构

### 字段类型处理

**🚨 强制要求：字段类型必须来自埋点文档，禁止自行推断或编造**

- 文档明确标注了类型（如 NUMBER、STRING、BOOL）→ 直接使用
- 文档未标注类型 → 写"文档未明确"，禁止根据字段名猜测

### 枚举值处理

- **完整枚举**：文档列出所有值 → 每个值都生成用例
- **不完整枚举**：只给部分示例 → 添加"其他合法值"用例
- **动态枚举**：由配置生成 → 描述为"配置中的合法值"

### 边界场景

**必须覆盖**：
- 空值（如果允许）
- 最大/最小值（数字字段）
- 特殊字符（字符串字段）
- 并发操作（次数验证）

### 用例编号管理

**编号规则**：
- 格式：用例{序号}：{场景名称}
- 序号：从1开始递增
- 同一事件内连续编号

### 文件命名

**推荐格式**：
- `{活动名称}_埋点测试用例.md`
- `{活动名称}_埋点测试用例.xmind`

**避免**：
- 特殊字符：`/`、`\`、`:`、`*`、`?`、`"`、`<`、`>`、`|`
- 过长文件名（< 50字符）
- 空格（使用下划线）

### 测试用例维护

**文档变更时**：
- 标注版本号
- 记录变更历史
- 更新受影响用例

**用例执行后**：
- 记录实际结果
- 标注通过/失败状态
- 关联缺陷（如有）

### 与产品对齐

**生成前**：
- 确认埋点需求准确性
- 与产品确认特殊场景
- 与开发确认实现细节

**生成后**：
- 评审用例覆盖度
- 补充遗漏场景
- 调整优先级

---

## 快速参考

**标准案例位置**：
```
testcase_output/高级房限时任务.md
```

**生成XMind命令**：
```bash
python3 scripts/generate_xmind.py \
  --input testcase_output/xxx.md \
  --output testcase_output/xxx.xmind
```

**检查文件大小**：
```bash
ls -lh testcase_output/xxx.xmind
# 正常大小：> 3KB
# 异常大小：< 2KB（可能内容为空）
```

**问题排查**：
- XMind 内容为空 → 检查是否用了表格格式
- 生成失败 → 检查 Markdown 标题层级
- 依赖缺失 → pip3 install xmind