akmon/doc_zhipao/ANALYTICS_RPC_DEPLOYMENT_GUIDE.md

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 文件

# 在 Supabase SQL Editor 中执行
# 或通过 psql 命令行执行
psql -h [your-host] -U [your-user] -d [your-database] -f analytics_rpc_functions.sql

2. 验证函数创建

-- 检查函数是否创建成功
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. 测试函数调用

-- 测试教师统计数据
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 页面调用

<!-- 统计数据 -->
<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" 
/>

参数示例

// 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. 权限错误 - 确保函数权限正确授予

调试技巧

-- 检查用户角色
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 页面应该能够正常加载和显示数据分析功能。