feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
224
backend/团队看板功能验证指南.md
Normal file
224
backend/团队看板功能验证指南.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 团队看板功能验证指南
|
||||
|
||||
## 功能概述
|
||||
|
||||
团队看板功能已完成真实数据库对接，包括：
|
||||
- ✅ 团队概览统计（成员数、学习进度、考试成绩、课程完成率）
|
||||
- ✅ 学习进度图表（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错误
|
||||
- ✅ 权限控制实现
|
||||
- ✅ 导出按钮已移除
|
||||
- ⏳ 待数据验证
|
||||
|
||||
Reference in New Issue
Block a user