# 团队看板功能验证指南

## 功能概述

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

## 权限控制

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

## 快速验证

### 1. 启动服务

```bash
# 确保数据库和后端服务运行
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验证

#### 方式一：使用测试脚本

```bash
cd kaopeilian-backend

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

#### 方式二：使用curl

```bash
# 替换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错误
- ✅ 权限控制实现
- ✅ 导出按钮已移除
- ⏳ 待数据验证