akmon/README_SUPABASE_DEPLOYMENT.md

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项目

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

2. 配置环境变量

   const supabaseUrl = 'https://your-project.supabase.co'
   const supabaseKey = 'your-anon-key'
   

第二步：部署数据库结构

1. 执行主数据库结构

   -- 在Supabase SQL编辑器中执行
   -- 文件：message_system.sql
   

2. 部署角色管理系统

   -- 在Supabase SQL编辑器中执行
   -- 文件：supabase_auth_complete_setup.sql
   

3. 配置权限策略

   -- 在Supabase SQL编辑器中执行
   -- 文件：message_permissions_complete.sql
   

4. 插入测试数据

   -- 在Supabase SQL编辑器中执行
   -- 文件：insert_test_message_data.sql
   

第三步：配置Supabase Auth

1. 启用邮箱确认

   -- 在Supabase Dashboard > Authentication > Settings
   -- 启用 "Enable email confirmations"
   

2. 配置邮箱模板

   <!-- 自定义确认邮件模板 -->
   <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: 学生，基础消息权限

自动角色分配规则

-- 基于邮箱域名自动分配角色
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
查看所有消息	✅	❌	❌
发送消息	✅	✅	✅
创建群组	✅	✅	需权限
发送广播	✅	需权限	❌
管理角色	✅	❌	❌
审核消息	✅	需权限	❌

💻 前端集成

安装依赖

npm install @supabase/supabase-js

初始化客户端

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. 发送消息

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. 获取消息列表

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

3. 权限检查

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

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

4. 群组管理

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

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

5. 角色管理（管理员）

// 更新用户角色
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. 数据库功能测试

-- 测试角色系统
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. 前端功能测试

// 权限测试
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. 权限检查

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

3. 输入验证

// 验证消息内容
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. 性能监控查询

-- 查看消息发送统计
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. 数据清理

-- 清理过期消息（可选）
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. 权限策略错误

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

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

2. 角色同步问题

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

3. 前端认证问题

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

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

📈 扩展功能

1. 添加新角色

-- 修改角色检查约束
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. 添加班级系统

-- 创建班级表
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. 消息模板系统

-- 已在主系统中实现
-- 可通过前端界面管理消息模板
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组件库
• 📊 数据分析仪表板

---

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