接入数据库

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/ANALYTICS_DATA_QUICK_START.md
+++ b/pages/mall/analytics/test/ANALYTICS_DATA_QUICK_START.md
@@ -0,0 +1,66 @@
+# Analytics 测试数据快速开始（更新版）
+
+> 本文档基于 **2026-01 修订后的数据库脚本**（含 RLS 安全、中文注释、幂等执行）
+>
+> 请务必按下述 **执行顺序** 依次运行 SQL，否则会出现外键或 RLS 限制导致的插入失败。
+
+---
+
+## 🗂️ SQL 执行顺序（只创建，不删除）
+
+| 步骤 | 作用                                                                          | 文件                                    | 需要权限                                              |
+| ---- | ----------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------- |
+| 1    | 创建基础业务表（orders/users/user_sessions/products/merchants/page_views 等） | `01_create_tables.sql`                  | 任意（不清空数据，可重复执行）                        |
+| 2    | 创建用户资料表（ak_users）+ RLS + 用户资料函数                                | `../../user/test/USER_AUTH_SCHEMA.sql`  | 任意（不清空数据，可重复执行）                        |
+| 3    | 创建 auth.users → ak_users 触发器                                             | `../../user/test/USER_AUTH_TRIGGER.sql` | **需要访问 auth schema（建议 Dashboard SQL Editor）** |
+| 4    | 创建 analytics_* 表 + RLS + RPC                                               | `ANALYTICS_DB_SCHEMA.sql`               | 任意（不清空数据，可重复执行）                        |
+| 5    | 插入业务侧测试数据                                                            | `02_insert_test_data.sql`               | **service_role**¹                                     |
+| 6    | 插入 analytics_* 测试数据                                                     | `ANALYTICS_TEST_SEED.sql`               | **service_role**¹                                     |
+| 7    | (可选) 查询验证                                                               | `03_test_queries.sql`                   | 登录用户                                              |
+
+¹ *原因：两份 seed 脚本要写入带 RLS 的表，直接用 anon / authenticated 会被策略拦截。Dashboard SQL Editor 默认具备等价于 postgres/service_role 的权限，可直接执行；CLI 请使用 `psql … -U postgres`（或你的 DB 管理员账号）执行。*
+
+---
+
+## 🚀 执行步骤（以 Supabase Dashboard 为例）
+
+1. 打开 **SQL Editor** → 依次新建 Query 运行 *步骤1–4*。
+2. 登出 / 使用普通账号登录，再运行 *步骤5* 查询验证。
+
+---
+
+## ⚠️ 常见问题
+
+1. **RLS 阻挡插入**  
+   请确认 seed 在 Dashboard 执行，或先 `SET ROLE service_role;`。  
+   不建议在 seed 中禁用 RLS。
+
+2. **重复执行报错**  
+   脚本为“只创建，不删除”模式：表/索引使用 `IF NOT EXISTS`，触发器/策略使用系统表判断后再创建，可重复执行。若仍报错，请先 `ROLLBACK;` 再重试。
+
+3. **前端查不到 seed 数据**  
+   登陆用户的 `auth.uid()`必须与 seed 中 `orders.user_id` 等字段匹配；否则受 RLS 影响会看不到。测试时可在 seed 中把某条 `user_id` 改成你自己的 UID。
+
+---
+
+## 🔐 权限矩阵（简版）
+
+| 表 / 功能                              | anon              | authenticated       | service_role |
+| -------------------------------------- | ----------------- | ------------------- | ------------ |
+| `orders / order_items / user_sessions` | Insert❌ / Select❌ | ✅(仅本人)           | ✅(全部)      |
+| `products / merchants`                 | Select✅           | CRUD⚠️ (受策略)      | ✅            |
+| `page_views`                           | Insert✅ / Select❌ | Select✅(本人)       | ✅            |
+| `analytics_*` 表                       | ❌                 | ✅ (按 owner/shared) | ✅            |
+| RPC (analytics)                        | ❌                 | ✅                   | ✅            |
+
+> 详细策略请见各 SQL 文件内注释。
+
+---
+
+## 🧹 清理
+
+执行 `04_cleanup.sql` 可按时间 / 用户删除测试数据，脚本已更新为幂等。
+
+---
+
+最后更新：2026-01-26
--- a/pages/mall/analytics/test/README.md
+++ b/pages/mall/analytics/test/README.md
@@ -39,22 +39,14 @@

 ### 方式 1: 通过 Supabase Dashboard（推荐）

-1. **访问 Dashboard**
-   ```
-   http://192.168.1.63:8000
-   或
-   http://192.168.1.63:3000  (Studio 默认端口)
-   ```
+1. **打开 Supabase Studio / Dashboard**
+   - 请使用你自己的部署地址访问（不要在仓库文档里硬编码地址/账号/密码）。

-2. **登录**
-   - 用户名：`supabase`
-   - 密码：`D4ce5p8YBpfYzEoDGZ_7MzehZcWrdCNyDEj_VSUBmOw`
-
-3. **打开 SQL Editor**
+2. **打开 SQL Editor**
   - 在左侧菜单找到 "SQL Editor"
   - 点击 "New Query"

-4. **执行脚本**
+3. **执行脚本**
   - 复制 `01_create_tables.sql` 的内容，粘贴并执行
   - 复制 `02_insert_test_data.sql` 的内容，粘贴并执行
   - （可选）复制 `03_test_queries.sql` 的内容，验证数据
@@ -62,10 +54,8 @@
 ### 方式 2: 使用命令行（PostgreSQL）

 ```bash
-# 连接到内网 Supabase 数据库
-psql -h 192.168.1.63 -p 5432 -U postgres -d postgres
-
-# 输入密码：yxyHINygZMLSq9jLddrZQBB-CoyGHSF5DwlwWmbrYXc
+# 连接到 Supabase Postgres（参数请按你的环境填写）
+psql -h <DB_HOST> -p <DB_PORT> -U postgres -d postgres

 # 执行 SQL 文件（需要完整路径）
 \i D:/datas/hfkj/mall/pages/mall/analytics/test/01_create_tables.sql
@@ -76,17 +66,20 @@ psql -h 192.168.1.63 -p 5432 -U postgres -d postgres
 ### 方式 3: 使用图形工具（DBeaver / pgAdmin）

 1. **创建连接**
-   - 主机：`192.168.1.63`
-   - 端口：`5432`
+   - 主机：`<DB_HOST>`
+   - 端口：`<DB_PORT>`
   - 数据库：`postgres`
-   - 用户名：`postgres`
-   - 密码：`yxyHINygZMLSq9jLddrZQBB-CoyGHSF5DwlwWmbrYXc`
+   - 用户名：`postgres`（或你的管理员账号）
+   - 密码：`<DB_PASSWORD>`

 2. **执行 SQL**
   - 打开 SQL 编辑器
   - 复制 SQL 文件内容并执行

-**详细说明请查看：`SQL_USAGE_GUIDE.md`**
+**详细说明请查看：**
+- **`ANALYTICS_DATA_QUICK_START.md`** - ⭐ **SQL 文件执行顺序指南（必读！）**
+- `SQL_USAGE_GUIDE.md` - SQL 脚本执行详细指南
+- `TEST_DATA_INSERT_GUIDE.md` - 测试数据插入指南（包含 RLS 处理说明）

 ## 测试数据说明

@@ -111,6 +104,20 @@ psql -h 192.168.1.63 -p 5432 -U postgres -d postgres
 - **今日下单用户数：** 约 8个（从 orders 表去重统计）
 - **预期转化率：** 约 53-80%（根据实际数据计算）

+## ⚠️ 重要：RLS（行级安全策略）说明
+
+**所有表已启用 RLS**，插入测试数据时需要注意：
+
+1. **推荐方式**：使用 Supabase Dashboard 的 SQL Editor 执行脚本
+   - Dashboard 默认使用 `service_role` 权限，可以绕过 RLS
+   - 无需额外配置，直接执行即可
+
+2. **命令行方式**：如果使用命令行或脚本执行
+   - 需要临时禁用 RLS（见 `02_insert_test_data.sql` 中的注释说明）
+   - 或使用 `SECURITY DEFINER` 函数（见 `TEST_DATA_INSERT_GUIDE.md`）
+
+3. **详细说明**：请查看 `TEST_DATA_INSERT_GUIDE.md` 获取完整的插入指南
+
 ## 注意事项

 1. **时间依赖**
@@ -131,24 +138,14 @@ psql -h 192.168.1.63 -p 5432 -U postgres -d postgres
   - 所有 ID 使用 UUID 格式
   - 测试数据使用了固定的 UUID 便于识别

+5. **RLS 权限**
+   - 插入数据后，前端查询需要用户已登录
+   - 测试数据的 `user_id` 需要与登录用户的 `auth.uid()` 匹配才能查询到
+   - 或者使用公开数据（如 `products`、`merchants` 表）
+
 ## 清理测试数据

-如果需要清理测试数据，可以执行：
-
-```sql
-- 谨慎操作：清空测试数据
-TRUNCATE TABLE orders, user_sessions, users, order_items, page_views CASCADE;
-```
-
-或者删除特定时间范围的数据：
-
-```sql
-- 删除今日的测试订单
-DELETE FROM orders WHERE created_at >= DATE_TRUNC('day', NOW());
-
-- 删除测试用户会话
-DELETE FROM user_sessions WHERE created_at >= DATE_TRUNC('day', NOW());
-```
+如需清理测试数据，请使用独立的清理脚本（例如 `04_cleanup.sql`）。

 ## 验证实时大屏功能

--- a/pages/mall/analytics/test/SQL_EXECUTION_ORDER.md
+++ b/pages/mall/analytics/test/SQL_EXECUTION_ORDER.md
@@ -0,0 +1,15 @@
+# SQL 文件执行顺序指南（已弃用）
+
+> 本文件已停止维护，避免与新脚本冲突。
+>
+> ✅ **请以 `ANALYTICS_DATA_QUICK_START.md` 为唯一权威执行顺序与权限说明文档。**
+
+## 当前推荐执行顺序（摘要）
+
+1. `01_create_tables.sql`（基础业务表 + RLS + 中文注释，Drop-first）
+2. `../../user/test/USER_AUTH_SCHEMA.sql`（`ak_users` + RLS + 资料函数，Drop-first）
+3. `../../user/test/USER_AUTH_TRIGGER.sql`（auth.users → ak_users 触发器）
+4. `ANALYTICS_DB_SCHEMA.sql`（analytics_* 表 + RLS + RPC，Drop-first）
+5. `02_insert_test_data.sql`（基础表测试数据，需 service_role/postgres）
+6. `ANALYTICS_TEST_SEED.sql`（analytics_* 测试数据，需 service_role/postgres）
+7. `03_test_queries.sql`（可选：验证查询）
--- a/pages/mall/analytics/test/SQL_USAGE_GUIDE.md
+++ b/pages/mall/analytics/test/SQL_USAGE_GUIDE.md
@@ -19,18 +19,10 @@ pages/mall/analytics/test/

 如果您的内网 Supabase 有 Dashboard 界面：

-1. **访问 Dashboard**
-   ```
-   http://192.168.1.63:8000
-   或
-   http://192.168.1.63:3000  (Studio 默认端口)
-   ```
+1. **打开 Supabase Studio / Dashboard**
+   - 使用你自己的部署地址访问（不要在仓库文档里硬编码地址/账号/密码）。

-2. **登录**
-   - 用户名：`supabase`（根据您的配置）
-   - 密码：`D4ce5p8YBpfYzEoDGZ_7MzehZcWrdCNyDEj_VSUBmOw`
-
-3. **打开 SQL Editor**
+2. **打开 SQL Editor**
   - 在左侧菜单找到 "SQL Editor" 或 "SQL"
   - 点击 "New Query"

@@ -51,10 +43,9 @@ pages/mall/analytics/test/
 1. **连接数据库**
   ```bash
   # 使用 psql 连接
-   psql -h 192.168.1.63 -p 5432 -U postgres -d postgres
+   psql -h <DB_HOST> -p <DB_PORT> -U postgres -d postgres
   
-   # 输入密码（根据您的配置）
-   # POSTGRES_PASSWORD=yxyHINygZMLSq9jLddrZQBB-CoyGHSF5DwlwWmbrYXc
+   # 密码请按你的环境输入/从安全渠道获取（不要写进仓库）
   ```

 2. **执行 SQL 文件**
@@ -70,41 +61,26 @@ pages/mall/analytics/test/
 ### 方式 3: 通过 DBeaver / pgAdmin 等图形工具

 1. **创建新连接**
-   - 主机：`192.168.1.63`
-   - 端口：`5432`
+   - 主机：`<DB_HOST>`
+   - 端口：`<DB_PORT>`
   - 数据库：`postgres`
   - 用户名：`postgres`
-   - 密码：`yxyHINygZMLSq9jLddrZQBB-CoyGHSF5DwlwWmbrYXc`
+   - 密码：`<DB_PASSWORD>`

 2. **执行 SQL**
   - 打开 SQL 编辑器
   - 复制 SQL 文件内容
   - 执行脚本

-### 方式 4: 通过 HTTP API（程序化执行）
-
-使用 Supabase REST API 执行 SQL（需要 service_role key）：
-
-```javascript
-// 注意：这种方式需要 Supabase 的 SQL 执行功能
-// 通常不推荐，因为安全风险较高
-const response = await fetch('http://192.168.1.63:8000/rest/v1/rpc/exec_sql', {
-  method: 'POST',
-  headers: {
-    'apikey': 'YOUR_SERVICE_ROLE_KEY',
-    'Authorization': 'Bearer YOUR_SERVICE_ROLE_KEY',
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    sql: 'SELECT * FROM users LIMIT 1;'
-  })
-})
-```
+> 不建议通过 HTTP API “执行任意 SQL”（高风险）。
+> 如需服务端能力，请用 Supabase Edge Functions + 限定输入输出的 RPC。

 ## 📝 执行顺序

 **重要：必须按顺序执行！**

+> ✅ 以 `ANALYTICS_DATA_QUICK_START.md` 为权威执行顺序与权限说明（本文件只做执行方式补充）。
+
 1. ✅ **第一步：创建表结构**
   ```sql
   -- 执行 01_create_tables.sql
@@ -190,17 +166,11 @@ GRANT ALL PRIVILEGES ON SCHEMA public TO postgres;

 ### 2. 表已存在

-如果表已存在，脚本会使用 `CREATE TABLE IF NOT EXISTS`，不会报错。
-但如果需要重新创建：
-```sql
-- 先删除表（谨慎操作）
-DROP TABLE IF EXISTS order_items CASCADE;
-DROP TABLE IF EXISTS page_views CASCADE;
-DROP TABLE IF EXISTS user_sessions CASCADE;
-DROP TABLE IF EXISTS orders CASCADE;
-DROP TABLE IF EXISTS users CASCADE;
-DROP TABLE IF EXISTS products CASCADE;
-```
+如果表已存在：
+- `01_create_tables.sql` / `ANALYTICS_DB_SCHEMA.sql` 现为 **只创建（Create-only）** 脚本，不包含 `DROP/DELETE/TRUNCATE`，可重复执行且不会清空数据。
+- 如需结构变更，请用迁移脚本（ALTER TABLE）。
+
+> 如确实要“清理后重建”，请另外单独维护清理脚本（避免把破坏性操作放进默认文档/默认流程）。

 ### 3. 时间依赖

@@ -238,8 +208,8 @@ Error: password authentication failed
 Error: relation "orders" already exists
 ```
 **解决：**
- 脚本已使用 `IF NOT EXISTS`，通常不会报错
- 如需重新创建，先删除表
+- 说明你执行的脚本版本与当前仓库不一致，或只拷贝了部分 SQL
+- 请按 `ANALYTICS_DATA_QUICK_START.md` 的顺序完整执行最新脚本（Drop-first，不应出现该错误）

 ### Q4: 权限不足
 ```
--- 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 计算