Initial commit of akmon project

2026-01-20 08:04:15 +08:00
commit 77a2bab985
1309 changed files with 343305 additions and 0 deletions
--- a/supabase_deployment_checklist.md
+++ b/supabase_deployment_checklist.md
@@ -0,0 +1,462 @@
+# Supabase 消息系统部署清单
+
+本清单确保您在Supabase中正确配置消息系统的权限策略和功能。
+
+## 🎯 部署选项
+
+### 选项1：一键部署（推荐新手）
+
+```sql
+-- 在Supabase SQL编辑器中执行
+\i deploy_one_click.sql
+```
+
+**优点：**
+- ✅ 自动化程度高，一步完成
+- ✅ 包含环境检测和配置验证
+- ✅ 自动创建便捷开发函数
+- ✅ 生成详细的部署报告
+
+**包含内容：**
+- 数据库扩展检查与创建
+- 基础表结构创建
+- 开发权限模式部署
+- 基础消息类型数据
+- 便捷开发函数
+- 部署结果验证
+
+### 选项2：权限管理器模式
+
+```sql
+-- 1. 部署权限管理器
+\i permission_manager.sql
+
+-- 2. 查看当前状态
+SELECT * FROM public.permission_dashboard;
+
+-- 3. 智能切换权限模式
+SELECT public.switch_to_dev_mode();    -- 开发模式
+SELECT public.switch_to_prod_mode();   -- 生产模式
+
+-- 4. 健康检查
+SELECT * FROM public.check_permission_health();
+```
+
+**优点：**
+- 🎛️ 提供完整的权限管理界面
+- 🔄 支持权限模式智能切换
+- 📊 实时权限状态监控
+- 🔍 权限健康检查和诊断
+
+### 选项3：手动分步部署
+
+```sql
+-- 1. 基础表结构
+\i message_system.sql
+
+-- 2. 用户角色系统（生产环境）
+\i supabase_auth_complete_setup.sql
+
+-- 3. 权限策略
+-- 开发环境
+\i dev_open_permissions.sql
+-- 或生产环境
+\i message_permissions_complete.sql
+
+-- 4. 测试数据
+\i insert_test_message_data.sql
+```
+
+**优点：**
+- 🎯 精确控制每个部署步骤
+- 🛠️ 便于调试和故障排除
+- 📝 适合学习和理解系统架构
+- 🔧 支持自定义配置
+
+## 🔄 权限模式管理
+
+### 权限模式脚本列表
+
+| 脚本文件 | 用途 | 适用环境 |
+|----------|------|----------|
+| `open_all_message_permissions.sql` | 完整开放权限脚本 | 开发/测试 |
+| `dev_open_permissions.sql` | 快速开发权限脚本 | 开发/测试 |
+| `restore_normal_permissions.sql` | 恢复正常权限脚本 | 生产环境 |
+| `permission_manager.sql` | 权限管理器 | 所有环境 |
+
+### 开发模式设置
+
+**快速开启开发模式：**
+```sql
+-- 方法1：使用完整脚本
+\i open_all_message_permissions.sql
+
+-- 方法2：使用快速脚本
+\i dev_open_permissions.sql
+
+-- 方法3：使用管理函数
+SELECT public.switch_to_dev_mode();
+```
+
+**开发模式特点：**
+- ✅ 所有authenticated用户拥有完全权限
+- ✅ 提供便捷开发函数
+- ✅ 适合快速原型开发和测试
+- ⚠️ **严禁在生产环境使用**
+
+### 生产模式设置
+
+**恢复生产模式：**
+```sql
+-- 方法1：使用恢复脚本
+\i restore_normal_permissions.sql
+
+-- 方法2：使用管理函数（仅清理）
+SELECT public.switch_to_prod_mode();
+-- 然后手动运行完整的生产权限脚本
+
+-- 方法3：重新部署完整权限
+\i message_permissions_complete.sql
+```
+
+**生产模式特点：**
+- 🔒 基于角色的严格权限控制
+- 🎯 最小权限原则
+- 🛡️ 数据安全保护
+- ✅ 适合生产环境
+
+### 权限状态检查
+
+**查看当前权限模式：**
+```sql
+-- 查看权限模式
+SELECT * FROM public.get_permission_mode();
+
+-- 查看权限仪表板
+SELECT * FROM public.permission_dashboard;
+
+-- 详细策略列表
+SELECT * FROM public.list_message_policies();
+
+-- 权限健康检查
+SELECT * FROM public.check_permission_health();
+```
+
+**常用检查命令：**
+```sql
+-- 快速状态检查
+SELECT 
+    mode,
+    CASE 
+        WHEN dev_policies > 0 THEN '⚠️ 开发环境'
+        WHEN normal_policies > 0 THEN '✅ 生产环境'
+        ELSE '❌ 未配置'
+    END as status
+FROM public.get_permission_mode();
+```
+
+## 🏗️ 数据库架构部署
+
+### 1. 创建表结构
+```sql
+-- 首先执行主数据库架构
+\i message_system.sql
+
+-- 然后执行权限策略
+\i supabase_message_permissions.sql
+
+-- 最后插入测试数据
+\i insert_test_message_data.sql
+```
+
+### 2. 启用必要的扩展
+```sql
+-- 在 Supabase SQL Editor 中执行
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pg_trgm";  -- 用于文本搜索
+```
+
+## 🔐 认证和权限配置
+
+### 1. JWT 配置
+确保您的 Supabase JWT 包含用户角色信息：
+
+```json
+{
+  "aud": "authenticated",
+  "exp": 1234567890,
+  "sub": "user-uuid-here",
+  "email": "user@example.com",
+  "role": "authenticated",
+  "user_role": "teacher",  // 重要：自定义角色字段
+  "app_metadata": {
+    "provider": "email",
+    "providers": ["email"]
+  },
+  "user_metadata": {
+    "user_role": "teacher"   // 备用角色字段
+  }
+}
+```
+
+### 2. 用户表配置
+确保用户表包含角色信息：
+
+```sql
+-- 检查用户表结构
+SELECT column_name, data_type, is_nullable 
+FROM information_schema.columns 
+WHERE table_name = 'ak_users' AND table_schema = 'public';
+
+-- 添加角色列到用户表（如果还没有）
+ALTER TABLE public.ak_users 
+ADD COLUMN IF NOT EXISTS role VARCHAR(20) DEFAULT 'student',
+ADD COLUMN IF NOT EXISTS user_type VARCHAR(20) DEFAULT 'student',
+ADD COLUMN IF NOT EXISTS class_id UUID;  -- 用于班级关联
+
+-- 更新测试用户角色
+UPDATE public.ak_users 
+SET role = 'teacher', user_type = 'teacher'
+WHERE id = '7bf7378e-a027-473e-97ac-3460ed3f170a';
+
+UPDATE public.ak_users 
+SET role = 'student', user_type = 'student'
+WHERE id = 'eed3824b-bba1-4309-8048-19d17367c084';
+
+-- 如果需要，可以创建班级表和师生关系
+-- CREATE TABLE IF NOT EXISTS public.ak_classes (
+--     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+--     name VARCHAR(100) NOT NULL,
+--     description TEXT,
+--     teacher_id UUID REFERENCES public.ak_users(id),
+--     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+-- );
+```
+
+## 📊 实时订阅配置
+
+### 1. 在 Supabase 控制台中启用实时功能
+
+**Database → Replication**
+- 选择需要实时订阅的表：
+  - ✅ `ak_messages`
+  - ✅ `ak_message_recipients`
+  - ✅ `ak_message_groups`
+  - ✅ `ak_message_group_members`
+
+### 2. 实时策略配置
+```sql
+-- 允许用户订阅自己的消息更新
+ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_messages;
+ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_message_recipients;
+ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_message_groups;
+ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_message_group_members;
+```
+
+## 🔧 客户端环境变量
+
+创建 `.env.local` 文件：
+```env
+NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key  # 仅服务端使用
+```
+
+## 🧪 权限策略测试
+
+### 1. 基本权限测试
+
+在 Supabase SQL Editor 中执行：
+
+```sql
+-- 测试用户只能查看自己的消息
+SET LOCAL role = 'authenticated';
+SET LOCAL "request.jwt.claims" = '{"sub": "eed3824b-bba1-4309-8048-19d17367c084", "user_role": "student"}';
+
+-- 应该只返回学生相关的消息
+SELECT COUNT(*) FROM ak_messages;
+SELECT COUNT(*) FROM ak_message_recipients WHERE recipient_id = 'eed3824b-bba1-4309-8048-19d17367c084'::uuid;
+
+-- 重置
+RESET role;
+```
+
+### 2. 教师权限测试
+
+```sql
+-- 设置教师身份
+SET LOCAL role = 'authenticated';
+SET LOCAL "request.jwt.claims" = '{"sub": "7bf7378e-a027-473e-97ac-3460ed3f170a", "user_role": "teacher"}';
+
+-- 测试教师可以发送系统消息
+INSERT INTO ak_messages (
+    message_type_id,
+    sender_type,
+    sender_id,
+    receiver_type,
+    receiver_id,
+    title,
+    content
+) VALUES (
+    (SELECT id FROM ak_message_types WHERE code = 'assignment'),
+    'user',
+    '7bf7378e-a027-473e-97ac-3460ed3f170a',
+    'user',
+    'eed3824b-bba1-4309-8048-19d17367c084',
+    '权限测试消息',
+    '这是一条测试教师权限的消息'
+);
+
+-- 重置
+RESET role;
+```
+
+### 3. 群组权限测试
+
+```sql
+-- 测试群组成员权限
+SET LOCAL role = 'authenticated';
+SET LOCAL "request.jwt.claims" = '{"sub": "eed3824b-bba1-4309-8048-19d17367c084", "user_role": "student"}';
+
+-- 学生应该能看到自己参与的群组
+SELECT * FROM ak_message_groups;
+
+-- 重置
+RESET role;
+```
+
+## 📱 前端集成检查清单
+
+### 1. 认证流程
+- [ ] 用户登录后正确设置角色信息
+- [ ] JWT 包含 `user_role` 字段
+- [ ] 角色信息在用户会话中持久化
+
+### 2. 消息功能
+- [ ] 用户只能看到自己有权限的消息
+- [ ] 教师可以向学生发送消息
+- [ ] 学生可以标记消息为已读
+- [ ] 群组消息正常工作
+
+### 3. 实时功能
+- [ ] 新消息实时推送给正确的用户
+- [ ] 消息状态变化实时同步
+- [ ] 订阅自动受权限策略保护
+
+### 4. 错误处理
+- [ ] 权限不足时显示友好错误信息
+- [ ] 网络错误重试机制
+- [ ] 操作失败回滚机制
+
+## 🚀 生产环境部署
+
+### 1. 性能优化
+
+```sql
+-- 创建必要的索引
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_messages_recipient_user 
+ON ak_message_recipients (recipient_id, recipient_type) 
+WHERE recipient_type = 'user';
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_messages_sender_user 
+ON ak_messages (sender_id, sender_type) 
+WHERE sender_type = 'user';
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_messages_created_at_desc 
+ON ak_messages (created_at DESC);
+
+-- 分析表统计信息
+ANALYZE ak_messages;
+ANALYZE ak_message_recipients;
+ANALYZE ak_message_groups;
+```
+
+### 2. 监控和日志
+
+在 Supabase 控制台中：
+- **Logs** → 查看数据库日志
+- **API** → 监控 API 使用情况
+- **Auth** → 监控认证失败
+
+### 3. 备份策略
+
+```sql
+-- 定期备份重要数据
+pg_dump -h your-db-host -U postgres -d your-db-name \
+  --table=ak_messages \
+  --table=ak_message_recipients \
+  --table=ak_message_groups \
+  --table=ak_user_message_preferences \
+  > message_system_backup.sql
+```
+
+## 🔒 安全检查清单
+
+### 1. 权限策略审查
+- [ ] 所有表都启用了 RLS
+- [ ] 用户只能访问自己的数据
+- [ ] 敏感操作需要适当权限
+- [ ] 没有权限泄露或越权访问
+
+### 2. 数据验证
+- [ ] 输入数据经过验证和清理
+- [ ] 防止 SQL 注入攻击
+- [ ] 文件上传安全检查
+- [ ] 敏感信息加密存储
+
+### 3. 网络安全
+- [ ] 启用 HTTPS
+- [ ] 配置 CORS 策略
+- [ ] API 速率限制
+- [ ] 防止暴力破解
+
+## 📞 故障排查
+
+### 常见问题和解决方案
+
+**问题1：权限被拒绝错误**
+```
+解决方案：
+1. 检查用户是否已认证
+2. 验证 JWT 中的角色信息
+3. 确认 RLS 策略配置正确
+4. 检查表权限设置
+```
+
+**问题2：实时订阅不工作**
+```
+解决方案：
+1. 确认表已添加到实时发布
+2. 检查 RLS 策略是否阻止订阅
+3. 验证客户端连接状态
+4. 查看浏览器开发者工具错误
+```
+
+**问题3：消息发送失败**
+```
+解决方案：
+1. 检查消息类型是否存在
+2. 验证接收者ID有效性
+3. 确认发送者有权限发送该类型消息
+4. 检查函数参数类型匹配
+```
+
+## 📈 性能监控
+
+### 关键指标
+- 消息发送延迟
+- 数据库查询时间
+- 实时连接数量
+- 错误率统计
+
+### 优化建议
+1. 定期分析慢查询
+2. 监控索引使用情况
+3. 优化复杂权限策略
+4. 考虑数据分区策略
+
+---
+
+**完成部署后，使用提供的测试用户 ID 进行功能验证：**
+- 教师：`7bf7378e-a027-473e-97ac-3460ed3f170a`
+- 学生：`eed3824b-bba1-4309-8048-19d17367c084`