012-kaopeilian/backend/团队看板功能验证指南.md

团队看板功能验证指南

功能概述

团队看板功能已完成真实数据库对接，包括：

• ✅ 团队概览统计（成员数、学习进度、考试成绩、课程完成率）
• ✅ 学习进度图表（Top 5成员8周进度趋势）
• ✅ 课程完成分布饼图（已完成/进行中/未开始）
• ✅ 能力短板雷达图（6个能力维度）
• ✅ 排行榜（学习时长Top 5、成绩Top 5）
• ✅ 团队动态（最近20条活动记录）

权限控制

• 管理员/经理（admin/manager）：查看所有团队数据
• 普通用户（trainee）：只查看自己所在团队数据

快速验证

1. 启动服务

# 确保数据库和后端服务运行
cd kaopeilian-backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 启动前端服务
cd kaopeilian-frontend
npm run dev

2. 前端验证

访问：http://localhost:3001/manager/team-dashboard

检查项：

• 概览卡片显示真实数据（不是硬编码的32、78.5%等）
• 学习进度图表正确渲染（显示真实成员名称）
• 课程完成分布饼图显示真实数据
• 能力短板雷达图显示真实能力维度
• 两个排行榜显示真实成员数据
• 团队动态显示最近活动记录
• 导出按钮已移除
• 页面无控制台错误

3. 后端API验证

方式一：使用测试脚本

cd kaopeilian-backend

# 修改test_team_dashboard.py中的TOKEN
# 然后运行
python test_team_dashboard.py

方式二：使用curl

# 替换YOUR_TOKEN为实际token
TOKEN="YOUR_TOKEN"

# 1. 测试团队概览
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/team/dashboard/overview

# 2. 测试学习进度
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/team/dashboard/progress

# 3. 测试课程分布
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/team/dashboard/course-distribution

# 4. 测试能力分析
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/team/dashboard/ability-analysis

# 5. 测试排行榜
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/team/dashboard/rankings

# 6. 测试团队动态
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/team/dashboard/activities

4. 权限验证

测试管理员权限

1. 使用admin账号登录
2. 访问团队看板
3. 应该能看到所有团队的数据

测试普通用户权限

1. 使用trainee账号登录
2. 访问团队看板
3. 应该只看到自己所在团队的数据

数据说明

概览统计

• 团队成员数：从user_teams表统计
• 平均学习进度：基于考试完成情况计算
• 平均考试成绩：使用exams表的round1_score字段
• 课程完成率：已完成课程数 / 总课程数

学习进度图表

• 显示学习时长Top 5成员
• 8周进度趋势（基于考试完成时间）

课程完成分布

• 已完成：有及格成绩（≥60分）的课程
• 进行中：有考试记录但未及格的课程
• 未开始：总课程数 - 已完成 - 进行中

能力分析

• 从practice_reports表的ability_dimensions JSON字段聚合
• 平均分<80的能力作为短板

排行榜

• 学习时长：从practice_sessions聚合duration_seconds
• 成绩排行：从exams聚合round1_score平均值
• 只显示Top 5

团队动态

• 最近的考试记录（来自exams表）
• 最近的陪练记录（来自practice_sessions表）
• 按时间倒序，最多20条

空数据处理

如果数据库中没有足够的数据：

• 概览统计会显示0值
• 图表会显示空状态
• 排行榜会显示空列表
• 动态会显示空列表

这是正常的，前端会友好地展示空状态。

常见问题

Q1: 页面显示"加载失败"

原因：

• 后端服务未启动
• 数据库连接失败
• Token已过期

解决：

1. 检查后端服务是否运行：curl http://localhost:8000/health
2. 检查数据库连接
3. 重新登录获取新token

Q2: 数据全是0

原因：

• 数据库中没有相关数据
• 用户不属于任何团队

解决：

1. 确认数据库中有teams、user_teams数据
2. 确认有exams、practice_sessions数据
3. 使用admin账号登录（可以看到所有团队）

Q3: 图表不显示

原因：

• 浏览器控制台有错误
• echarts初始化失败

解决：

1. 打开浏览器控制台查看错误
2. 刷新页面
3. 检查网络请求是否成功

Q4: 排行榜为空

原因：

• 团队成员没有陪练或考试记录

解决：

• 这是正常的，等待用户完成陪练和考试后会自动显示

技术实现

后端文件

• kaopeilian-backend/app/api/v1/team_dashboard.py - API接口
• 使用SQLAlchemy聚合函数（AVG、SUM、COUNT）
• 支持权限控制（admin/manager查看全部，trainee查看自己团队）

前端文件

• kaopeilian-frontend/src/api/teamDashboard.ts - API封装
• kaopeilian-frontend/src/views/manager/team-dashboard.vue - 页面组件
• 使用echarts渲染图表
• 使用request.ts发起API请求

后续优化建议

1. 日期范围筛选：实现dateRange参数的实际功能
2. 趋势计算：实现真实的趋势对比（对比上周/上月）
3. 缓存优化：使用Redis缓存统计数据
4. 实时刷新：添加WebSocket实时更新
5. 数据导出：实现Excel/PDF导出功能

联调记录

完成时间：2025-10-XX

• ✅ 后端6个API接口全部完成
• ✅ 前端API封装完成
• ✅ 前端页面改造完成
• ✅ 无linter错误
• ✅ 权限控制实现
• ✅ 导出按钮已移除
• ⏳ 待数据验证