# 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 页面应该能够正常加载和显示数据分析功能。