# Supabase Auth 角色管理与消息系统部署指南

## 📋 概述

本指南提供了完整的Supabase Auth角色管理和消息系统的部署、配置和使用说明。系统支持教师/学生角色管理，包含完整的权限控制、消息发送、群组管理等功能。

## 🗂️ 文件结构

```
h:\blews\akmon\
├── message_system.sql                      # 主数据库结构
├── supabase_auth_complete_setup.sql       # 完整角色管理系统
├── message_permissions_complete.sql       # 完整权限策略
├── open_all_message_permissions.sql       # 开放权限脚本（开发/测试）
├── dev_open_permissions.sql               # 快速开发权限脚本
├── restore_normal_permissions.sql         # 恢复正常权限脚本
├── permission_manager.sql                 # 权限管理器
├── deploy_one_click.sql                   # 一站式部署脚本
├── supabase_message_client_complete.js    # 前端客户端代码
├── insert_test_message_data.sql           # 测试数据
└── README_SUPABASE_DEPLOYMENT.md          # 本指南
```

## 🚀 部署步骤

### 第一步：准备Supabase项目

1. **创建Supabase项目**
   ```bash
   # 访问 https://supabase.com
   # 创建新项目并获取URL和密钥
   ```

2. **配置环境变量**
   ```javascript
   const supabaseUrl = 'https://your-project.supabase.co'
   const supabaseKey = 'your-anon-key'
   ```

### 第二步：部署数据库结构

1. **执行主数据库结构**
   ```sql
   -- 在Supabase SQL编辑器中执行
   -- 文件：message_system.sql
   ```

2. **部署角色管理系统**
   ```sql
   -- 在Supabase SQL编辑器中执行
   -- 文件：supabase_auth_complete_setup.sql
   ```

3. **配置权限策略**
   ```sql
   -- 在Supabase SQL编辑器中执行
   -- 文件：message_permissions_complete.sql
   ```

4. **插入测试数据**
   ```sql
   -- 在Supabase SQL编辑器中执行
   -- 文件：insert_test_message_data.sql
   ```

### 第三步：配置Supabase Auth

1. **启用邮箱确认**
   ```sql
   -- 在Supabase Dashboard > Authentication > Settings
   -- 启用 "Enable email confirmations"
   ```

2. **配置邮箱模板**
   ```html
   <!-- 自定义确认邮件模板 -->
   <h2>欢迎加入消息系统</h2>
   <p>点击下面的链接确认您的邮箱：</p>
   <a href="{{ .ConfirmationURL }}">确认邮箱</a>
   ```

3. **设置回调URL**
   ```
   # 在Authentication > URL Configuration
   Site URL: http://localhost:3000
   Additional URLs: https://yourdomain.com
   ```

## 🔧 配置说明

### 角色系统配置

系统支持三种角色：
- **admin**: 管理员，拥有所有权限
- **teacher**: 教师，可以发送消息、创建群组、查看学生消息
- **student**: 学生，基础消息权限

### 自动角色分配规则

```sql
-- 基于邮箱域名自动分配角色
CASE 
    WHEN user_domain IN ('teacher.edu', 'faculty.edu', 'staff.edu') THEN 'teacher'
    WHEN user_domain IN ('admin.edu', 'management.edu') THEN 'admin'
    WHEN user_email LIKE '%admin%' OR user_email LIKE '%manager%' THEN 'admin'
    WHEN user_email LIKE '%teacher%' OR user_email LIKE '%faculty%' THEN 'teacher'
    ELSE 'student'
END
```

### 权限系统

每个角色的默认权限：

| 权限 | Admin | Teacher | Student |
|------|-------|---------|---------|
| 查看所有消息 | ✅ | ❌ | ❌ |
| 发送消息 | ✅ | ✅ | ✅ |
| 创建群组 | ✅ | ✅ | 需权限 |
| 发送广播 | ✅ | 需权限 | ❌ |
| 管理角色 | ✅ | ❌ | ❌ |
| 审核消息 | ✅ | 需权限 | ❌ |

## 💻 前端集成

### 安装依赖

```bash
npm install @supabase/supabase-js
```

### 初始化客户端

```javascript
import { messageApp } from './supabase_message_client_complete.js'

// 初始化应用
await messageApp.initialize()

// 用户登录
await messageApp.signIn('teacher@example.com', 'password123')

// 检查用户信息
const userInfo = messageApp.getCurrentUserInfo()
console.log('当前用户:', userInfo)
```

### 常用操作示例

#### 1. 发送消息

```javascript
const messageId = await messageApp.messages.sendSecureMessage({
    messageTypeId: 'announcement-type-id',
    receiverType: 'user',
    receiverId: 'student-user-id',
    title: '作业通知',
    content: '请完成本周的数学作业',
    metadata: { 
        priority: 'high',
        dueDate: '2024-01-15'
    }
})
```

#### 2. 获取消息列表

```javascript
const messages = await messageApp.messages.getAccessibleMessages({
    limit: 20,
    unreadOnly: true,
    messageType: 'announcement'
})
```

#### 3. 权限检查

```javascript
// 检查是否可以发送广播
const canBroadcast = await messageApp.roles.hasPermission('can_send_broadcasts')

// 检查是否可以访问特定消息
const canAccess = await messageApp.roles.canAccessResource('message', messageId, 'read')
```

#### 4. 群组管理

```javascript
// 加入群组
const joinResult = await messageApp.messages.joinMessageGroup('group-id', '申请加入')

// 获取用户群组
const groups = await messageApp.messages.getAccessibleGroups()
```

#### 5. 角色管理（管理员）

```javascript
// 更新用户角色
await messageApp.roles.updateUserRole('user-id', 'teacher', {
    department: 'Mathematics',
    class_id: 'class-123',
    permissions: { can_send_broadcasts: true }
})

// 批量更新角色
const updates = [
    { user_id: 'user1', role: 'teacher', department: 'Science' },
    { user_id: 'user2', role: 'student', class_id: 'class-456' }
]
const results = await messageApp.roles.batchUpdateUserRoles(updates)
```

## 🧪 测试和验证

### 1. 数据库功能测试

```sql
-- 测试角色系统
SELECT * FROM public.test_message_permissions('7bf7378e-a027-473e-97ac-3460ed3f170a');

-- 查看用户角色详情
SELECT * FROM public.user_roles_detailed ORDER BY created_at DESC;

-- 检查权限策略
SELECT schemaname, tablename, policyname, permissive 
FROM pg_policies 
WHERE schemaname = 'public' AND tablename LIKE 'ak_%';
```

### 2. 前端功能测试

```javascript
// 权限测试
await messageApp.roles.testPermissions()

// 消息统计
const stats = await messageApp.messages.getMessageStats()
console.log('消息统计:', stats)

// 角色同步检查
const users = await messageApp.roles.getUsersWithRoles()
const unsyncedUsers = users.filter(u => !u.role_synced)
console.log('角色未同步的用户:', unsyncedUsers)
```

## 🔒 安全最佳实践

### 1. 行级安全策略（RLS）

- ✅ 所有消息相关表都启用了RLS
- ✅ 用户只能访问自己相关的数据
- ✅ 教师可以访问学生消息（基于班级）
- ✅ 管理员拥有完全访问权限

### 2. 权限检查

```javascript
// 始终进行权限检查
if (await messageApp.roles.hasPermission('send_message')) {
    // 执行发送消息操作
} else {
    throw new Error('没有发送消息的权限')
}
```

### 3. 输入验证

```javascript
// 验证消息内容
function validateMessage(title, content) {
    if (!title || title.length < 1 || title.length > 200) {
        throw new Error('标题长度必须在1-200字符之间')
    }
    if (!content || content.length < 1 || content.length > 5000) {
        throw new Error('内容长度必须在1-5000字符之间')
    }
}
```

## 📊 监控和维护

### 1. 性能监控查询

```sql
-- 查看消息发送统计
SELECT 
    DATE(created_at) as date,
    COUNT(*) as message_count,
    COUNT(DISTINCT sender_id) as active_senders
FROM public.ak_messages 
WHERE created_at >= NOW() - INTERVAL '7 days'
GROUP BY DATE(created_at)
ORDER BY date DESC;

-- 查看权限策略性能
SELECT 
    schemaname, tablename, policyname,
    (SELECT COUNT(*) FROM pg_stat_user_tables WHERE relname = tablename) as table_size
FROM pg_policies 
WHERE schemaname = 'public';
```

### 2. 数据清理

```sql
-- 清理过期消息（可选）
DELETE FROM public.ak_messages 
WHERE created_at < NOW() - INTERVAL '1 year'
AND message_type_id IN (
    SELECT id FROM public.ak_message_types 
    WHERE type_name IN ('notification', 'reminder')
);

-- 清理无效角色记录
DELETE FROM public.user_roles 
WHERE user_id NOT IN (SELECT id FROM auth.users);
```

## 🚨 故障排除

### 常见问题及解决方案

#### 1. 权限策略错误

```sql
-- 检查策略冲突
SELECT tablename, COUNT(*) as policy_count
FROM pg_policies 
WHERE schemaname = 'public'
GROUP BY tablename
HAVING COUNT(*) > 10;

-- 重建权限策略
-- 执行 message_permissions_complete.sql
```

#### 2. 角色同步问题

```sql
-- 强制同步所有用户角色
SELECT user_id, public.sync_user_role_metadata(user_id) as synced
FROM public.user_roles WHERE is_active = true;
```

#### 3. 前端认证问题

```javascript
// 检查认证状态
const { data: { session } } = await supabase.auth.getSession()
if (!session) {
    console.log('用户未登录')
    // 重定向到登录页面
}

// 刷新token
await supabase.auth.refreshSession()
```

## 📈 扩展功能

### 1. 添加新角色

```sql
-- 修改角色检查约束
ALTER TABLE public.user_roles 
DROP CONSTRAINT user_roles_role_check;

ALTER TABLE public.user_roles 
ADD CONSTRAINT user_roles_role_check 
CHECK (role IN ('admin', 'teacher', 'student', 'parent', 'supervisor'));
```

### 2. 添加班级系统

```sql
-- 创建班级表
CREATE TABLE public.classes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    grade TEXT,
    school_id UUID,
    teacher_id UUID REFERENCES auth.users(id),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 更新用户角色表
-- class_id 字段已存在，可直接使用
```

### 3. 消息模板系统

```sql
-- 已在主系统中实现
-- 可通过前端界面管理消息模板
SELECT * FROM public.ak_message_templates WHERE is_public = true;
```

## 📞 支持和联系

如果在部署过程中遇到问题，请检查：

1. **Supabase项目配置**：确认URL和密钥正确
2. **数据库权限**：确认有足够的数据库权限
3. **网络连接**：确认可以连接到Supabase
4. **浏览器控制台**：查看详细错误信息

## 📝 更新日志

### v1.0.0 (2024-01-10)
- ✅ 完整的角色管理系统
- ✅ 权限控制和RLS策略
- ✅ 前端客户端库
- ✅ 测试数据和文档

### 未来计划
- 🔄 实时消息推送
- 📱 移动端适配
- 🎨 UI组件库
- 📊 数据分析仪表板

---

**部署完成后，请运行测试用例确保所有功能正常工作。**