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/README_SUPABASE_DEPLOYMENT.md
+++ b/README_SUPABASE_DEPLOYMENT.md
@@ -0,0 +1,424 @@
+# 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组件库
+- 📊 数据分析仪表板
+
+---
+
+**部署完成后，请运行测试用例确保所有功能正常工作。**