# 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`