214 lines
5.7 KiB
Markdown
214 lines
5.7 KiB
Markdown
# Analytics RPC 函数部署指南
|
||
|
||
## 概述
|
||
为 Analytics 页面创建了4个主要的 RPC 函数，提供教师数据分析功能。
|
||
|
||
## 创建的 RPC 函数
|
||
|
||
### 1. `get_teacher_analytics` - 教师统计数据
|
||
**功能**: 获取教师的核心统计指标
|
||
**参数**:
|
||
- `p_teacher_id` (uuid, 可选) - 教师ID，默认当前用户
|
||
- `p_start_date` (date, 可选) - 开始日期，默认30天前
|
||
- `p_end_date` (date, 可选) - 结束日期，默认今天
|
||
|
||
**返回字段**:
|
||
- `total_students` - 学生总数
|
||
- `total_assignments` - 作业总数
|
||
- `completion_rate` - 完成率(%)
|
||
- `average_score` - 平均分
|
||
- `active_classes` - 活跃班级数
|
||
- `total_submissions` - 总提交数
|
||
- `pending_reviews` - 待评分数
|
||
- `graded_submissions` - 已评分数
|
||
|
||
### 2. `get_top_performers` - 优秀学员排行
|
||
**功能**: 获取表现优秀的学员排行榜
|
||
**参数**:
|
||
- `p_teacher_id` (uuid, 可选) - 教师ID
|
||
- `p_start_date` (date, 可选) - 开始日期
|
||
- `p_end_date` (date, 可选) - 结束日期
|
||
- `p_limit` (integer, 可选) - 返回数量，默认10
|
||
|
||
**返回字段**:
|
||
- `student_id` - 学生ID
|
||
- `name` - 学生姓名
|
||
- `username` - 用户名
|
||
- `avatar_url` - 头像地址
|
||
- `score` - 平均分
|
||
- `submission_count` - 提交数量
|
||
- `completion_rate` - 完成率
|
||
- `class_name` - 班级名称
|
||
- `rank_position` - 排名位置
|
||
|
||
### 3. `get_chart_data` - 图表数据
|
||
**功能**: 获取各种图表数据
|
||
**参数**:
|
||
- `p_teacher_id` (uuid, 可选) - 教师ID
|
||
- `p_start_date` (date, 可选) - 开始日期
|
||
- `p_end_date` (date, 可选) - 结束日期
|
||
- `p_type` (text, 可选) - 图表类型，默认'completion_rate'
|
||
|
||
**支持的图表类型**:
|
||
- `completion_rate` - 完成率趋势
|
||
- `score_distribution` - 成绩分布
|
||
- `submission_trend` - 提交趋势
|
||
|
||
**返回字段**:
|
||
- `date_key` - 日期键
|
||
- `value` - 数值
|
||
- `label` - 标签
|
||
- `count` - 计数
|
||
|
||
### 4. `get_recent_activities` - 近期活动
|
||
**功能**: 获取近期活动记录
|
||
**参数**:
|
||
- `p_teacher_id` (uuid, 可选) - 教师ID
|
||
- `p_limit` (integer, 可选) - 返回数量，默认20
|
||
|
||
**返回字段**:
|
||
- `activity_id` - 活动ID
|
||
- `activity_type` - 活动类型
|
||
- `title` - 标题
|
||
- `description` - 描述
|
||
- `student_name` - 学生姓名
|
||
- `assignment_title` - 作业标题
|
||
- `activity_time` - 活动时间
|
||
- `time_ago` - 相对时间
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 执行 SQL 文件
|
||
```bash
|
||
# 在 Supabase SQL Editor 中执行
|
||
# 或通过 psql 命令行执行
|
||
psql -h [your-host] -U [your-user] -d [your-database] -f analytics_rpc_functions.sql
|
||
```
|
||
|
||
### 2. 验证函数创建
|
||
```sql
|
||
-- 检查函数是否创建成功
|
||
SELECT routine_name, routine_type
|
||
FROM information_schema.routines
|
||
WHERE routine_schema = 'public'
|
||
AND routine_name LIKE 'get_%analytics%'
|
||
OR routine_name LIKE 'get_top_performers'
|
||
OR routine_name LIKE 'get_chart_data'
|
||
OR routine_name LIKE 'get_recent_activities';
|
||
```
|
||
|
||
### 3. 测试函数调用
|
||
```sql
|
||
-- 测试教师统计数据
|
||
SELECT * FROM public.get_teacher_analytics();
|
||
|
||
-- 测试优秀学员排行
|
||
SELECT * FROM public.get_top_performers(limit => 5);
|
||
|
||
-- 测试图表数据
|
||
SELECT * FROM public.get_chart_data(p_type => 'completion_rate');
|
||
|
||
-- 测试近期活动
|
||
SELECT * FROM public.get_recent_activities(p_limit => 10);
|
||
```
|
||
|
||
## 前端使用示例
|
||
|
||
### Analytics 页面调用
|
||
```vue
|
||
<!-- 统计数据 -->
|
||
<supadb
|
||
rpc="get_teacher_analytics"
|
||
:params="analyticsParams"
|
||
@process-data="processStatisticsData"
|
||
/>
|
||
|
||
<!-- 优秀学员 -->
|
||
<supadb
|
||
rpc="get_top_performers"
|
||
:params="performersParams"
|
||
@process-data="processPerformersData"
|
||
/>
|
||
|
||
<!-- 图表数据 -->
|
||
<supadb
|
||
rpc="get_chart_data"
|
||
:params="chartParams"
|
||
@process-data="processChartData"
|
||
/>
|
||
```
|
||
|
||
### 参数示例
|
||
```typescript
|
||
// Analytics 参数
|
||
const analyticsParams = ref({
|
||
teacher_id: 'current_teacher_id', // 可选，默认当前用户
|
||
start_date: '2024-01-01',
|
||
end_date: '2024-12-31'
|
||
})
|
||
|
||
// 优秀学员参数
|
||
const performersParams = ref({
|
||
teacher_id: 'current_teacher_id',
|
||
limit: 10,
|
||
start_date: '2024-01-01',
|
||
end_date: '2024-12-31'
|
||
})
|
||
|
||
// 图表数据参数
|
||
const chartParams = ref({
|
||
teacher_id: 'current_teacher_id',
|
||
type: 'completion_rate', // 或 'score_distribution', 'submission_trend'
|
||
start_date: '2024-01-01',
|
||
end_date: '2024-12-31'
|
||
})
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### 创建的索引
|
||
- `idx_assignments_teacher_date` - 优化按教师和日期查询
|
||
- `idx_assignments_class_due` - 优化按班级和截止日期查询
|
||
- `idx_submissions_assignment_date` - 优化按作业和提交时间查询
|
||
- `idx_submissions_student_score` - 优化按学生和分数查询
|
||
- `idx_user_classes_role` - 优化用户班级角色查询
|
||
|
||
## 安全特性
|
||
|
||
### 权限控制
|
||
- 所有函数都验证调用者是否为教师
|
||
- 只能查看自己教授班级的数据
|
||
- 使用 `SECURITY DEFINER` 确保权限一致性
|
||
|
||
### RLS 策略
|
||
- 为作业表添加了行级安全策略
|
||
- 确保教师只能访问自己的数据
|
||
|
||
## 注意事项
|
||
|
||
1. **数据完整性**: 确保 `ak_user_classes` 表正确维护了师生关系
|
||
2. **时区处理**: 函数使用 `TIMESTAMP WITH TIME ZONE` 处理时间
|
||
3. **空值处理**: 所有计算都考虑了空值情况
|
||
4. **性能监控**: 建议监控函数执行时间，必要时进一步优化
|
||
|
||
## 故障排除
|
||
|
||
### 常见错误
|
||
1. **"用户不是教师或不存在"** - 检查用户角色和ID
|
||
2. **数据为空** - 检查师生关系配置和时间范围
|
||
3. **权限错误** - 确保函数权限正确授予
|
||
|
||
### 调试技巧
|
||
```sql
|
||
-- 检查用户角色
|
||
SELECT id, username, role FROM public.ak_users WHERE id = auth.uid();
|
||
|
||
-- 检查师生关系
|
||
SELECT * FROM public.ak_user_classes WHERE user_id = auth.uid();
|
||
|
||
-- 检查作业数据
|
||
SELECT COUNT(*) FROM public.ak_assignments WHERE teacher_id = auth.uid();
|
||
```
|
||
|
||
部署完成后，Analytics 页面应该能够正常加载和显示数据分析功能。
|