998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
225 lines
5.6 KiB
Markdown
225 lines
5.6 KiB
Markdown
# 团队看板功能验证指南
|
||
|
||
## 功能概述
|
||
|
||
团队看板功能已完成真实数据库对接，包括：
|
||
- ✅ 团队概览统计（成员数、学习进度、考试成绩、课程完成率）
|
||
- ✅ 学习进度图表（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错误
|
||
- ✅ 权限控制实现
|
||
- ✅ 导出按钮已移除
|
||
- ⏳ 待数据验证
|
||
|