埋点分析系统 API 测试报告

测试日期: 2026-07-30 测试环境: http://127.0.0.1:5000 登录凭据: admin / clklog 测试日期范围: 2026-07-24 ~ 2026-07-30

一、测试概览

统计项	数值
测试API总数	20
成功 (HTTP 200)	18
失败 (HTTP 401)	2
包含data字段	17
存在数据问题	4

二、逐个API测试结果

1. POST /api/auth/login （登录）

项目	结果
HTTP状态码	200
是否成功	是
返回数据	data对象包含token字段
数据摘要	成功获取Bearer Token

结论: 正常。

2. GET /api/overview/kpi （概览KPI）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	activeusers, avgsessionduration, pv, totalevents
数据结构	每个字段为 {trend, value} 对象
异常	无

数据示例:

{
  "active_users": {"trend": -0.3, "value": 16339},
  "avg_session_duration": {"trend": ..., "value": ...},
  "pv": {"trend": ..., "value": ...},
  "total_events": {"trend": ..., "value": ...}
}

结论: 正常，无null值，无负数异常。

3. GET /api/events/distribution （事件分布）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	data (嵌套对象), labels
数据量	labels: 10条, data: 10条
异常	无

结论: 正常。注意data返回的是嵌套对象而非数组，分页参数在distribution中的含义需确认。

4. GET /api/events/list （事件列表）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	list, page, page_size, total
分页信息	page=1, page_size=10, total=166
列表记录数	10条
单条字段	avgperuser, event, eventtype, screenname, trend, triggercount, usercount

结论: 分页正确，total=166，返回10条记录，无null字段。

5. GET /api/users/kpi （用户KPI）重点关注

项目	结果
HTTP状态码	200
是否成功	是
返回字段	activeusers, newusers, retentionrate, totalusers
数据格式	每个字段为 {trend, value}

完整数据:

{
  "active_users":    {"trend": -0.3,  "value": 16339},
  "new_users":       {"trend": 214.7, "value": 107},
  "retention_rate":  {"trend": null,  "value": 50.0},
  "total_users":     {"trend": 3.4,   "value": 29026}
}

留存率分析:

retention_rate.value = 50.0 (类型: Decimal，数值合理，表示50%)
retention_rate.trend = null --- 问题确认

结论: 留存率数值本身（50.0%）看起来合理，但 trend 字段为 null，这是之前提到的bug。其他字段正常。

6. GET /api/users/trend （用户趋势）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	labels, newusers, totalusers
数据量	labels: 7, newusers: 7, totalusers: 7

结论: 7天数据完整，数组长度一致，无异常。

7. GET /api/screens/flow （页面流转）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	data, labels
数据量	labels: 10, data: 10

结论: 正常。

8. GET /api/elements/kpi （元素KPI）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	totalclicks, uniqueelements, uniquescreens, uniqueusers

结论: 正常，无null字段。

9. GET /api/detail/events （事件明细）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	list, page, page_size, total
分页信息	page=1, page_size=20, total=255891
列表记录数	20条
单条字段	city, clientip, devicemodel, distinctid, elementcontent, elementname, elementtype, event, eventtype, logtime, networktype, osfull, province, screen_name

结论: 分页正确，total=255891，返回20条记录，字段完整。

10. GET /api/detail/filters （过滤器列表）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	devices, events, os_list, provinces

结论: 正常，返回了所有可用的筛选选项。

11. GET /api/flow/overview （流程概览）

项目	结果
HTTP状态码	200
是否成功	是
返回字段	current, previous, samePeriod

完整数据:

{
  "current":    {"avgPv": 0.0, "avgVisitTime": 0, "bounceRate": 0.0, "ipCount": 0, "pv": 0, "uv": 0, "visitCount": 0},
  "previous":   {"avgPv": 0.0, "avgVisitTime": 0, "bounceRate": 0.0, "ipCount": 0, "pv": 0, "uv": 0, "visitCount": 0},
  "samePeriod": {"avgPv": 0.0, "avgVisitTime": 0, "bounceRate": 0.0, "ipCount": 0, "pv": 0, "uv": 0, "visitCount": 0}
}

问题: 三个时间段的数据全部为0。这可能表示流程数据未采集、数据表结构不匹配、或该功能模块依赖的数据源未启用。需要进一步排查。

结论: 返回结构正确，但数据全为0属于异常，建议排查数据源。

12. GET /api/health （健康检查）

项目	结果
HTTP状态码	200
是否成功	是
返回内容	{"code":0,"data":null,"message":"ok"}
data字段	null

结论: 服务运行正常（HTTP 200），但data字段为null。这可能是有意设计（health检查不需要返回数据），但与其他API的返回格式不一致。

13. GET /api/projects （项目列表）

项目	结果
HTTP状态码	200
是否成功	是
返回格式	数组
数据量	1个项目

数据:

{
  "event_count": 2918345,
  "project_name": "qianlongapp",
  "project_token": "5388ed7459ba4c4cad0c8693fb85630a",
  "user_count": 29026
}

结论: 正常，返回1个项目，数据完整。

14. GET /api/env/list （环境列表）

项目	结果
HTTP状态码	200
是否成功	是
返回格式	数组
数据量	2个环境

数据:

"生产环境" (production) - host: 114.80.38.24:9000
"测试环境" (test) - host: 192.168.20.147:9000

结论: 正常。

15. GET /api/env/current （当前环境）

项目	结果
HTTP状态码	200
是否成功	是
当前环境	production (114.80.38.24)

结论: 正常，当前连接生产环境。

三、错误情况测试

3.1 不带Token访问受保护API

测试端点	预期	实际	结果
GET /api/overview/kpi	401	401	通过

返回401状态码，但响应Body为空，没有返回JSON格式的错误信息（如 {"code":401,"message":"未授权"}）

3.2 无效Token访问

测试端点	预期	实际	结果
GET /api/overview/kpi (Bearer invalidtoken12345)	401	401	通过

返回401状态码，同样响应Body为空。

3.3 缺少必要参数

测试端点	缺失参数	预期	实际	结果
/api/overview/kpi?end_date=2026-07-30	start_date	400	200	不通过
/api/overview/kpi?start_date=2026-07-24	end_date	400	200	不通过
/api/overview/kpi?startdate=abc&enddate=xyz	无效日期	400	200	不通过

问题: 缺少必要参数和无效日期格式时，API返回200而非400，只是返回了空数据。建议后端增加参数校验，返回明确的错误信息。

四、数据质量评估

4.1 数值合理性

API	字段	值	评估
users/kpi	active_users.value	16339	合理
users/kpi	new_users.value	107	合理
users/kpi	total_users.value	29026	合理
users/kpi	retention_rate.value	50.0	合理（50%留存率）
projects	event_count	2918345	合理（约292万事件）
projects	user_count	29026	与users/kpi一致
detail/events	total	255891	合理
events/list	total	166	合理（事件类型数）

4.2 Null值检测

API	字段	值	是否问题
users/kpi	retention_rate.trend	null	是 - Bug
health	data	null	可能是有意设计

4.3 全零数据

API	字段	值	是否问题
flow/overview	current.*	全部为0	是 - 需排查
flow/overview	previous.*	全部为0	是 - 需排查
flow/overview	samePeriod.*	全部为0	是 - 需排查

4.4 分页正确性

API	total	page	page_size	实际返回	一致性
events/list	166	1	10	10条	正确
detail/events	255891	1	20	20条	正确

五、问题汇总

严重问题（2个）

#	问题	影响API	描述
1	留存率趋势为null	/api/users/kpi	retention_rate.trend = null，前端可能因此显示异常
2	流程概览数据全为0	/api/flow/overview	current/previous/samePeriod 三个时段所有指标均为0

中等问题（1个）

#	问题	影响API	描述
3	缺少参数校验	/api/overview/kpi 等	缺少startdate/enddate/无效日期格式时返回200而非400

轻微问题（2个）

#	问题	影响API	描述
4	401响应Body为空	所有需认证API	未认证时返回空Body，建议返回JSON格式错误信息
5	health接口data为null	/api/health	与其他API返回格式不一致

六、结论

核心功能正常: 15个API端点中，14个认证API均返回200，认证拦截机制正常工作（401）。
留存率Bug确认存在: retention_rate.trend 为 null，前端可能因此无法正确显示趋势箭头或百分比变化。
流程概览数据缺失: flow/overview 三个时段数据全为0，建议检查数据采集管道或ClickHouse查询逻辑。
参数校验缺失: 缺少日期参数时不返回400错误，前端无法有效提示用户。
数据一致性良好: projects中的usercount与users/kpi中的totalusers一致（均为29026），说明数据源一致。

埋点分析系统 API 测试报告

一、测试概览

二、逐个API测试结果

1. POST /api/auth/login （登录）

2. GET /api/overview/kpi （概览KPI）

3. GET /api/events/distribution （事件分布）

4. GET /api/events/list （事件列表）

5. GET /api/users/kpi （用户KPI）重点关注

6. GET /api/users/trend （用户趋势）

7. GET /api/screens/flow （页面流转）

8. GET /api/elements/kpi （元素KPI）

9. GET /api/detail/events （事件明细）

10. GET /api/detail/filters （过滤器列表）

11. GET /api/flow/overview （流程概览）

12. GET /api/health （健康检查）

13. GET /api/projects （项目列表）

14. GET /api/env/list （环境列表）

15. GET /api/env/current （当前环境）

三、错误情况测试

3.1 不带Token访问受保护API

3.2 无效Token访问

3.3 缺少必要参数

四、数据质量评估

4.1 数值合理性

4.2 Null值检测

4.3 全零数据

4.4 分页正确性

五、问题汇总

严重问题（2个）

中等问题（1个）

轻微问题（2个）

六、结论

📎 相关文章

📊 股票代码总索引

科技股下半年机会

社交数据 - 社交数据