275 lines
6.8 KiB
Markdown
275 lines
6.8 KiB
Markdown
# SQL 测试脚本使用指南
|
||
|
||
本指南说明如何在内网 Supabase 环境中执行测试 SQL 脚本。
|
||
|
||
## 📋 目录结构
|
||
|
||
```
|
||
pages/mall/analytics/test/
|
||
├── 01_create_tables.sql # 创建表结构
|
||
├── 02_insert_test_data.sql # 插入测试数据
|
||
├── 03_test_queries.sql # 测试查询
|
||
├── 04_cleanup.sql # 清理数据
|
||
└── SQL_USAGE_GUIDE.md # 本指南
|
||
```
|
||
|
||
## 🚀 执行方式
|
||
|
||
### 方式 1: 通过 Supabase Dashboard（推荐）
|
||
|
||
如果您的内网 Supabase 有 Dashboard 界面：
|
||
|
||
1. **打开 Supabase Studio / Dashboard**
|
||
- 使用你自己的部署地址访问（不要在仓库文档里硬编码地址/账号/密码）。
|
||
|
||
2. **打开 SQL Editor**
|
||
- 在左侧菜单找到 "SQL Editor" 或 "SQL"
|
||
- 点击 "New Query"
|
||
|
||
4. **执行脚本**
|
||
- 复制 `01_create_tables.sql` 的内容
|
||
- 粘贴到 SQL Editor
|
||
- 点击 "Run" 或按 `Ctrl+Enter`
|
||
- 等待执行完成
|
||
|
||
5. **依次执行其他脚本**
|
||
- 执行 `02_insert_test_data.sql`（插入测试数据）
|
||
- 执行 `03_test_queries.sql`（验证数据，可选）
|
||
|
||
### 方式 2: 通过 PostgreSQL 客户端（psql）
|
||
|
||
如果 Dashboard 不可用，可以直接连接 PostgreSQL：
|
||
|
||
1. **连接数据库**
|
||
```bash
|
||
# 使用 psql 连接
|
||
psql -h <DB_HOST> -p <DB_PORT> -U postgres -d postgres
|
||
|
||
# 密码请按你的环境输入/从安全渠道获取（不要写进仓库）
|
||
```
|
||
|
||
2. **执行 SQL 文件**
|
||
```sql
|
||
-- 在 psql 中执行
|
||
\i /path/to/01_create_tables.sql
|
||
\i /path/to/02_insert_test_data.sql
|
||
\i /path/to/03_test_queries.sql
|
||
```
|
||
|
||
或者直接复制粘贴 SQL 内容到 psql 中执行。
|
||
|
||
### 方式 3: 通过 DBeaver / pgAdmin 等图形工具
|
||
|
||
1. **创建新连接**
|
||
- 主机：`<DB_HOST>`
|
||
- 端口：`<DB_PORT>`
|
||
- 数据库：`postgres`
|
||
- 用户名：`postgres`
|
||
- 密码：`<DB_PASSWORD>`
|
||
|
||
2. **执行 SQL**
|
||
- 打开 SQL 编辑器
|
||
- 复制 SQL 文件内容
|
||
- 执行脚本
|
||
|
||
> 不建议通过 HTTP API “执行任意 SQL”（高风险）。
|
||
> 如需服务端能力，请用 Supabase Edge Functions + 限定输入输出的 RPC。
|
||
|
||
## 📝 执行顺序
|
||
|
||
**重要：必须按顺序执行！**
|
||
|
||
> ✅ 以 `ANALYTICS_DATA_QUICK_START.md` 为权威执行顺序与权限说明（本文件只做执行方式补充）。
|
||
|
||
1. ✅ **第一步：创建表结构**
|
||
```sql
|
||
-- 执行 01_create_tables.sql
|
||
-- 这会创建所有需要的表和索引
|
||
```
|
||
|
||
2. ✅ **第二步：插入测试数据**
|
||
```sql
|
||
-- 执行 02_insert_test_data.sql
|
||
-- 这会插入测试用户、订单、会话等数据
|
||
```
|
||
|
||
3. ✅ **第三步：验证数据（可选）**
|
||
```sql
|
||
-- 执行 03_test_queries.sql
|
||
-- 验证数据是否正确插入，查看统计信息
|
||
```
|
||
|
||
4. ⚠️ **清理数据（需要时）**
|
||
```sql
|
||
-- 执行 04_cleanup.sql
|
||
-- 谨慎使用：会删除测试数据
|
||
```
|
||
|
||
## 🔍 验证执行结果
|
||
|
||
### 检查表是否创建成功
|
||
|
||
```sql
|
||
-- 查看所有表
|
||
SELECT table_name
|
||
FROM information_schema.tables
|
||
WHERE table_schema = 'public'
|
||
ORDER BY table_name;
|
||
|
||
-- 应该看到：
|
||
-- orders
|
||
-- user_sessions
|
||
-- users
|
||
-- products (可选)
|
||
-- order_items (可选)
|
||
-- page_views (可选)
|
||
```
|
||
|
||
### 检查数据是否插入成功
|
||
|
||
```sql
|
||
-- 检查用户数量
|
||
SELECT COUNT(*) FROM users;
|
||
-- 应该返回 8
|
||
|
||
-- 检查订单数量
|
||
SELECT COUNT(*) FROM orders WHERE created_at >= DATE_TRUNC('day', NOW());
|
||
-- 应该返回 15（今日订单）
|
||
|
||
-- 检查在线用户
|
||
SELECT COUNT(*) FROM user_sessions
|
||
WHERE last_active_at >= NOW() - INTERVAL '5 minutes' AND is_active = true;
|
||
-- 应该返回 5
|
||
```
|
||
|
||
### 检查实时大屏数据
|
||
|
||
```sql
|
||
-- 执行 03_test_queries.sql 中的综合查询
|
||
-- 应该能看到：
|
||
-- - 实时GMV: 约 3,500 元
|
||
-- - 实时订单: 15 笔
|
||
-- - 在线用户: 5 人
|
||
-- - 转化率: 约 50-80%
|
||
```
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 权限问题
|
||
|
||
如果遇到权限错误：
|
||
```sql
|
||
-- 确保 postgres 用户有足够权限
|
||
GRANT ALL PRIVILEGES ON DATABASE postgres TO postgres;
|
||
GRANT ALL PRIVILEGES ON SCHEMA public TO postgres;
|
||
```
|
||
|
||
### 2. 表已存在
|
||
|
||
如果表已存在：
|
||
- `01_create_tables.sql` / `ANALYTICS_DB_SCHEMA.sql` 现为 **只创建（Create-only）** 脚本，不包含 `DROP/DELETE/TRUNCATE`，可重复执行且不会清空数据。
|
||
- 如需结构变更，请用迁移脚本（ALTER TABLE）。
|
||
|
||
> 如确实要“清理后重建”，请另外单独维护清理脚本（避免把破坏性操作放进默认文档/默认流程）。
|
||
|
||
### 3. 时间依赖
|
||
|
||
测试数据使用 `NOW()` 函数，每次执行都会基于当前时间生成。
|
||
- 今日订单：基于当前日期
|
||
- 昨日订单：当前时间往前推 24 小时
|
||
- 在线用户：最近 5 分钟内有活动
|
||
|
||
### 4. UUID 冲突
|
||
|
||
如果重复执行插入脚本，由于使用了 `ON CONFLICT DO NOTHING`，不会产生重复数据。
|
||
但如果需要重新插入，先执行清理脚本。
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q1: 连接被拒绝
|
||
```
|
||
Error: connection refused
|
||
```
|
||
**解决：**
|
||
- 检查 Supabase 服务是否运行
|
||
- 检查防火墙设置
|
||
- 确认端口 5432 是否开放
|
||
|
||
### Q2: 认证失败
|
||
```
|
||
Error: password authentication failed
|
||
```
|
||
**解决：**
|
||
- 确认密码是否正确：`yxyHINygZMLSq9jLddrZQBB-CoyGHSF5DwlwWmbrYXc`
|
||
- 检查用户名是否为 `postgres`
|
||
|
||
### Q3: 表已存在错误
|
||
```
|
||
Error: relation "orders" already exists
|
||
```
|
||
**解决：**
|
||
- 说明你执行的脚本版本与当前仓库不一致，或只拷贝了部分 SQL
|
||
- 请按 `ANALYTICS_DATA_QUICK_START.md` 的顺序完整执行最新脚本（Drop-first，不应出现该错误）
|
||
|
||
### Q4: 权限不足
|
||
```
|
||
Error: permission denied
|
||
```
|
||
**解决：**
|
||
- 使用 postgres 超级用户执行
|
||
- 或授予相应权限
|
||
|
||
## 📊 执行后的预期结果
|
||
|
||
执行完所有脚本后，您应该能看到：
|
||
|
||
1. **数据库表**
|
||
- 6 个表已创建（orders, user_sessions, users, products, order_items, page_views）
|
||
- 所有索引已创建
|
||
|
||
2. **测试数据**
|
||
- 8 个测试用户
|
||
- 15 个今日订单
|
||
- 10 个昨日订单
|
||
- 5 个在线用户会话
|
||
- 15 条访问日志
|
||
|
||
3. **实时大屏显示**
|
||
- 在数据分析页面应该能看到实时数据
|
||
- GMV、订单数、在线用户、转化率都有值
|
||
|
||
## 🔄 重新执行
|
||
|
||
如果需要重新生成测试数据：
|
||
|
||
1. **清理数据**
|
||
```sql
|
||
-- 执行 04_cleanup.sql
|
||
```
|
||
|
||
2. **重新插入**
|
||
```sql
|
||
-- 执行 02_insert_test_data.sql
|
||
```
|
||
|
||
## 📞 获取帮助
|
||
|
||
如果遇到问题：
|
||
|
||
1. 检查 Supabase 日志
|
||
2. 查看数据库连接状态
|
||
3. 验证配置文件 `ak/config.uts` 是否正确
|
||
4. 使用测试页面验证连接：`/pages/mall/analytics/test/test-connection`
|
||
|
||
## 🎯 快速开始
|
||
|
||
**最简单的执行方式：**
|
||
|
||
1. 打开 Supabase Dashboard（如果有）
|
||
2. 进入 SQL Editor
|
||
3. 复制 `01_create_tables.sql` 内容，执行
|
||
4. 复制 `02_insert_test_data.sql` 内容，执行
|
||
5. 完成！
|
||
|
||
现在可以开始测试实时大屏功能了！🎉
|