# WesPy 架构和常见问题

WesPy-HTTP-Go 活动埋点的架构说明和测试中常见问题的排查方法。

---

## 🏗️ WesPy架构说明

### 埋点定义层

```go
// acttrack/sale.go 或 acttrack/acttrack.go
func TrackXXX(actId, uid, ...) {
    safego.SafeGo(func() {  // 异步上报
        properties := commonacttrack.MergeActivityTrack(map[string]interface{}{
            "activity_type": "temporary_event",
            "action":        "xxx_action",  // 唯一标识
            "act_id":        actId,
            // ... 业务字段
        })
        sensorsdata.SensorTrack(int64(uid), "ActivityTotal", properties, ...)
    })
}
```

**关键点**:
- 使用 `safego.SafeGo` 异步上报
- 调用 `MergeActivityTrack` 自动补充公共字段
- 事件名固定为 `"ActivityTotal"`
- action 区分不同埋点

---

### 公共字段自动补充

```go
// MergeActivityTrack 自动添加：
// - activity: 活动页名称（从配置中心查询）
// - activity_name: 活动名称
// - activity_version: 活动版本号
```

**注意**: `activity` 和 `activity_name` 无需手动传递。

---

### 调用层

```go
// hook/send_gift.go 等业务逻辑文件
acttrack.TrackHuntLottery(actId, members[0], flagUserCoin, round, "个人维度", 0, 0)
```

---

## 🔍 常见测试问题

### 问题1: 埋点没有上报 🔴

**症状**:
- 触发了操作，但抓包看不到埋点请求
- 数数平台查询不到数据

**可能原因**:
1. 服务未启动或重启失败
2. 代码逻辑判断不通过（如：金币不足）
3. 埋点代码被注释或删除
4. 网络问题导致请求失败

**排查方法**:
```bash
# 1. 检查服务状态
ps aux | grep activity

# 2. 查看服务日志
tail -f wespy-http-go/app/activity/logs/activity.log

# 3. 搜索埋点函数调用
grep -rn "TrackFamilyCompleteTask" wespy-http-go/app/activity/
```

---

### 问题2: 字段值错误 🔴

**症状**:
- 抓包看到埋点，但字段值不对（如：reward_num=2026）
- 所有数据的字段值都一样

**可能原因**:
1. 字段值硬编码（如：`"reward_num": 2026`）
2. 参数传递错误
3. 配置错误

**排查方法**:
```bash
# 1. 搜索硬编码值
grep -rn "2026" acttrack/*.go

# 2. 查看埋点函数定义
# 检查参数是否正确使用
```

**测试验证**:
```sql
-- 数数平台查询，检查字段值的多样性
SELECT
    reward_num,
    COUNT(*) as cnt
FROM ActivityTotal
WHERE act_id = 6420
    AND action = 'level_reward'
GROUP BY reward_num;

-- 如果只有一个值（如：2026），则说明硬编码
```

---

### 问题3: 字段缺失 🔴

**症状**:
- 抓包看到埋点，但某些字段不存在或为null

**可能原因**:
1. 代码中未实现该字段
2. 参数未传递
3. 条件判断导致字段未添加

**排查方法**:
```bash
# 搜索字段名
grep -rn "num" acttrack/*.go | grep -i "reward"

# 检查埋点函数参数列表
```

---

### 问题4: 上报次数错误 ⚠️

**症状**:
- 触发一次操作，数数平台查到多条记录
- 或者应该上报2次，但只上报了1次

**可能原因**:
1. 业务设计就是多次上报（如：房主+top用户）
2. 代码中有多个调用点
3. 循环中调用埋点函数

**排查方法**:
```sql
-- 数数平台查询单次操作的上报次数
SELECT
    DATE_FORMAT(time, '%H:%i:%s') as trigger_time,
    COUNT(*) as report_count,
    GROUP_CONCAT(distinct_id) as user_ids
FROM ActivityTotal
WHERE act_id = 6362
    AND action = 'hunt_room_win'
    AND date >= CURRENT_DATE
GROUP BY trigger_time
ORDER BY trigger_time DESC;
```

---

### 问题5: 延迟太久 ⚠️

**症状**:
- 抓包看到上报，但数数平台10分钟后还查不到

**可能原因**:
1. 数数平台数据延迟（正常5-10分钟）
2. 数据格式错误，数数平台解析失败
3. 环境配置错误（上报到错误的数数项目）

**排查方法**:
1. 等待15分钟后再查询
2. 检查抓包的数据格式是否正确
3. 确认数数平台的项目ID

---

## ✅ 测试清单（7步流程）

### 第一步：获取测试用例信息
- [ ] 读取测试用例文档
- [ ] 提取所有埋点字段列表
- [ ] 过滤服务器埋点（只测试 ActivityTotal）
- [ ] 剔除客户端埋点（AppClick、AppViewScreen、ShowH5）
- [ ] 生成测试清单表格

### 第二步：查询活动配置
- [ ] 使用 get_key_api.py 查询活动配置
- [ ] 确认活动ID、活动名称
- [ ] 记录 Widget 配置（哪些启用、哪些未启用）
- [ ] 记录任务配置（任务ID、阶段数）
- [ ] 记录奖励配置（奖池类型、道具ID）
- [ ] 记录枚举值（box_type、lottery_type 等）

### 第三步：定位埋点代码
- [ ] 查找活动目录
- [ ] 定位活动 acttrack 目录
- [ ] 定位 Widget acttrack 目录
- [ ] 检查 action 唯一性（活动+Widget）
- [ ] 创建埋点代码映射表

### 第四步：执行每条测试用例
- [ ] 代码审查：对照字段完整性
- [ ] 代码审查：检查硬编码、字段缺失
- [ ] 代码审查：查找调用点
- [ ] 实际触发：按照测试步骤操作
- [ ] 抓包验证：验证埋点上报
- [ ] 抓包验证：验证字段完整性和值正确性
- [ ] 数数平台：查询数据存在性
- [ ] 数数平台：验证字段值多样性（防止硬编码）
- [ ] 数数平台：验证上报次数
- [ ] 记录测试结论（通过/失败）

### 第五步：多场景测试
- [ ] 边界场景（最小值、最大值、临界值）
- [ ] 枚举值完整性（逐一测试每个枚举值）
- [ ] 不同维度（个人维度、房间维度）
- [ ] 多用户场景（排名、top5、批量上报）
- [ ] 异常场景（金币不足、权限不足、活动未开始/已结束）

### 第六步：记录测试结果
- [ ] 为每条用例记录详细结果
- [ ] 包含：代码审查结果
- [ ] 包含：实际测试结果
- [ ] 包含：抓包截图
- [ ] 包含：数数平台查询SQL和结果
- [ ] 包含：多场景测试结果
- [ ] 包含：测试结论（通过/失败）
- [ ] 包含：发现问题清单（如有）

### 第七步：输出测试报告
- [ ] 按照标准模板编写报告
- [ ] 包含：测试概述
- [ ] 包含：活动配置信息
- [ ] 包含：埋点代码映射
- [ ] 包含：所有测试用例执行结果
- [ ] 包含：测试汇总统计
- [ ] 包含：问题汇总（Critical/Warning/Info）
- [ ] 包含：修复验证计划
- [ ] 包含：测试结论和建议
- [ ] 包含：附录（截图、SQL、清单）
- [ ] 输出 Markdown 文件
- [ ] （可选）输出 PDF 文件

---

[← 返回主文档](../SKILL.md)