接入数据库

2026-01-26 21:34:17 +08:00
parent c14f67cfc8
commit 3fbd9a2b3d
26 changed files with 3559 additions and 427 deletions
--- a/pages/mall/analytics/test/TEST_DATA_INSERT_GUIDE.md
+++ b/pages/mall/analytics/test/TEST_DATA_INSERT_GUIDE.md
@@ -0,0 +1,209 @@
+# 测试数据插入指南
+
+> 本文档说明如何在启用 RLS（行级安全策略）的情况下插入测试数据。
+
+## 📋 前置条件
+
+1. **已执行表结构创建脚本**
+   - `01_create_tables.sql` - 创建表结构和 RLS 策略
+   - `ANALYTICS_DB_SCHEMA.sql` - 创建 analytics_* 表（可选）
+
+2. **确认 Supabase 连接**
+   - 已配置 Supabase 项目
+   - 可以访问 Supabase Dashboard 的 SQL Editor
+
+## 🚀 插入测试数据的三种方式
+
+### 方式一：使用 Supabase Dashboard（推荐）
+
+**优点**：最简单，无需处理 RLS 权限问题  
+**适用场景**：开发测试、快速验证
+
+**步骤**：
+
+1. 打开 Supabase Dashboard
+2. 进入 **SQL Editor**
+3. 复制 `02_insert_test_data.sql` 的全部内容
+4. 粘贴到 SQL Editor 中
+5. 点击 **Run** 执行
+
+**说明**：Supabase Dashboard 的 SQL Editor 默认使用 `service_role` 权限，可以绕过 RLS 策略，直接插入数据。
+
+---                        
+
+### 方式二：临时禁用 RLS（适用于命令行）
+
+**优点**：可以在命令行或脚本中执行  
+**适用场景**：自动化脚本、CI/CD
+
+**步骤**（不推荐，除非你明确理解风险）：
+
+1. 编辑 `02_insert_test_data.sql`
+2. 取消文件开头关于禁用 RLS 的注释（第 12-19 行）
+3. 取消文件末尾关于重新启用 RLS 的注释（第 137-144 行）
+4. 执行脚本
+
+**示例**：
+
+```sql
+-- 在脚本开头添加
+BEGIN;
+ALTER TABLE orders DISABLE ROW LEVEL SECURITY;
+ALTER TABLE user_sessions DISABLE ROW LEVEL SECURITY;
+-- ... 其他表
+
+-- 插入数据...
+
+-- 在脚本末尾添加
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE user_sessions ENABLE ROW LEVEL SECURITY;
+-- ... 其他表
+COMMIT;
+```
+
+**⚠️ 注意**：执行完成后务必重新启用 RLS，否则数据将不受保护！
+
+---
+
+### 方式三：使用 SECURITY DEFINER 函数（高级）
+
+**优点**：更安全，不需要禁用 RLS  
+**适用场景**：生产环境、需要定期插入测试数据
+
+**步骤**：
+
+1. 创建一个 SECURITY DEFINER 函数来插入测试数据
+2. 调用该函数执行插入
+
+**示例函数**：
+
+```sql
+CREATE OR REPLACE FUNCTION insert_test_data()
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  -- 插入测试用户
+  INSERT INTO users (id, phone, email, nickname, last_login_at) VALUES
+    ('11111111-1111-1111-1111-111111111111', '13800000001', 'user1@test.com', '测试用户1', NOW() - INTERVAL '2 minutes')
+  ON CONFLICT (id) DO NOTHING;
+  
+  -- 插入其他测试数据...
+END;
+$$;
+
+-- 执行函数
+SELECT insert_test_data();
+```
+
+---
+
+## ✅ 验证数据插入
+
+执行以下查询验证数据是否插入成功：
+
+```sql
+-- 检查用户数量
+SELECT COUNT(*) FROM users;
+-- 预期：8
+
+-- 检查订单数量
+SELECT COUNT(*) FROM orders;
+-- 预期：25（15个今日订单 + 10个昨日订单）
+
+-- 检查用户会话数量
+SELECT COUNT(*) FROM user_sessions;
+-- 预期：10
+
+-- 检查访问日志数量
+SELECT COUNT(*) FROM page_views;
+-- 预期：15
+
+-- 检查商家数量
+SELECT COUNT(*) FROM merchants;
+-- 预期：2
+
+-- 检查商品数量
+SELECT COUNT(*) FROM products;
+-- 预期：3
+```
+
+---
+
+## 🔍 常见问题
+
+### Q1: 执行 INSERT 时提示 "new row violates row-level security policy"
+
+**原因**：RLS 策略阻止了插入操作。
+
+**解决方案**：
+- 使用方式一（Supabase Dashboard）
+- 或使用方式二（临时禁用 RLS）
+- 或使用方式三（SECURITY DEFINER 函数）
+
+### Q2: 插入数据后，前端查询不到数据
+
+**原因**：RLS 策略限制了查询权限。
+
+**解决方案**：
+1. 确认前端已正确登录（`auth.uid()` 不为 NULL）
+2. 检查 RLS 策略是否正确配置
+3. 确认测试数据的 `user_id` 与登录用户的 `auth.uid()` 匹配
+
+### Q3: 如何清空测试数据重新插入？
+
+为避免在默认文档里包含破坏性 SQL，本项目将“清理/删除”动作放在独立清理脚本中（如 `04_cleanup.sql`）。
+
+如你需要重新生成测试数据：
+- 先执行清理脚本
+- 再重新执行 seed 脚本
+
+---
+
+## 📝 测试数据说明
+
+### 用户数据
+- **数量**：8 个测试用户
+- **UUID 范围**：`11111111-...` 到 `88888888-...`
+- **用途**：用于订单、会话、访问日志等关联数据
+
+### 订单数据
+- **今日订单**：15 笔（status = 2，已支付）
+- **昨日订单**：10 笔（用于增长率对比）
+- **总 GMV**：约 3,500 元（今日）
+
+### 在线用户
+- **最近 5 分钟活跃**：5 个用户
+- **用于**：实时大屏的"在线用户"统计
+
+### 访问日志
+- **数量**：15 条
+- **来源分布**：direct/search/social/ad
+- **用于**：转化率计算、流量来源分析
+
+---
+
+## 🔗 相关文件
+
+- `01_create_tables.sql` - 表结构创建脚本
+- `02_insert_test_data.sql` - 测试数据插入脚本
+- `03_test_queries.sql` - 数据验证查询脚本
+- `ANALYTICS_DB_SCHEMA.sql` - Analytics 表结构（可选）
+
+---
+
+## 📚 下一步
+
+插入测试数据后，可以：
+
+1. **验证前端页面**
+   - 访问 `/pages/mall/analytics/index` 查看实时大屏
+   - 检查 KPI 数据是否正确显示
+
+2. **执行验证查询**
+   - 运行 `03_test_queries.sql` 验证数据计算逻辑
+
+3. **测试 RPC 函数**
+   - 调用 `rpc_analytics_realtime_kpis` 验证实时 KPI 计算