Initial commit of akmon project
This commit is contained in:
213
doc_zhipao/ANALYTICS_RPC_DEPLOYMENT_GUIDE.md
Normal file
213
doc_zhipao/ANALYTICS_RPC_DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# 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 页面应该能够正常加载和显示数据分析功能。
|
||||
Reference in New Issue
Block a user