数据分析页面骨架
This commit is contained in:
comlibmb
276
pages/mall/analytics/docs/ANALYTICS_DB_QUICK_START.md
Normal file
276
pages/mall/analytics/docs/ANALYTICS_DB_QUICK_START.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 数据分析模块数据库快速开始指南
|
||||
|
||||
> 本文档提供数据分析模块数据库的快速部署和使用指南。
|
||||
|
||||
## 📁 文件位置
|
||||
|
||||
所有 SQL 脚本和测试文件位于：`pages/mall/analytics/test/`
|
||||
|
||||
### 核心文件
|
||||
|
||||
| 文件 | 用途 | 执行顺序 |
|
||||
| ------------------------- | -------------------------------- | ----------- |
|
||||
| `ANALYTICS_DB_SCHEMA.sql` | 完整的表结构、索引、RLS、RPC | 1️⃣ |
|
||||
| `ANALYTICS_TEST_SEED.sql` | 完整的测试数据（包含基础业务表） | 2️⃣ |
|
||||
| `01_create_tables.sql` | 分步：创建表结构 | 1️⃣ |
|
||||
| `02_insert_test_data.sql` | 分步：插入测试数据 | 2️⃣ |
|
||||
| `03_test_queries.sql` | 验证查询示例 | 3️⃣（可选） |
|
||||
| `04_cleanup.sql` | 清理测试数据 | ⚠️（需要时） |
|
||||
|
||||
### 文档文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------- | ---------------------------------- |
|
||||
| `test/README.md` | 测试数据说明和使用方法 |
|
||||
| `test/SQL_USAGE_GUIDE.md` | SQL 脚本执行详细指南 |
|
||||
| `docs/ANALYTICS_DB_DESIGN.md` | 数据库设计文档（表结构、字段说明） |
|
||||
| `docs/ANALYTICS_DB_QUICK_START.md` | 快速开始指南（本文档） |
|
||||
|
||||
## 🚀 快速部署（3步）
|
||||
|
||||
### 方式一：使用完整脚本（推荐）
|
||||
|
||||
1. **执行 Schema**
|
||||
```sql
|
||||
-- 在 Supabase SQL Editor 中执行
|
||||
-- 复制粘贴 pages/mall/analytics/test/ANALYTICS_DB_SCHEMA.sql 的内容
|
||||
```
|
||||
|
||||
2. **插入测试数据**
|
||||
```sql
|
||||
-- 复制粘贴 pages/mall/analytics/test/ANALYTICS_TEST_SEED.sql 的内容
|
||||
```
|
||||
|
||||
3. **验证**
|
||||
```sql
|
||||
SELECT COUNT(*) FROM analytics_reports;
|
||||
-- 应该返回 3
|
||||
```
|
||||
|
||||
### 方式二：使用分步脚本
|
||||
|
||||
1. **创建表结构**
|
||||
```sql
|
||||
\i pages/mall/analytics/test/01_create_tables.sql
|
||||
```
|
||||
|
||||
2. **插入测试数据**
|
||||
```sql
|
||||
\i pages/mall/analytics/test/02_insert_test_data.sql
|
||||
```
|
||||
|
||||
3. **验证数据（可选）**
|
||||
```sql
|
||||
\i pages/mall/analytics/test/03_test_queries.sql
|
||||
```
|
||||
|
||||
## 📊 创建的表
|
||||
|
||||
### Analytics 专用表
|
||||
|
||||
- `analytics_user_preferences` - 分析师偏好设置
|
||||
- `analytics_reports` - 报表定义
|
||||
- `analytics_report_metrics` - 报表核心指标
|
||||
- `analytics_report_rows` - 报表明细行（趋势数据）
|
||||
- `analytics_insights` - 数据洞察
|
||||
- `analytics_report_favorites` - 报表收藏
|
||||
- `analytics_export_jobs` - 导出任务
|
||||
|
||||
### 基础业务表（如果不存在）
|
||||
|
||||
- `users` - 用户表
|
||||
- `merchants` - 商家表
|
||||
- `products` - 商品表
|
||||
- `orders` - 订单表
|
||||
- `order_items` - 订单商品表
|
||||
- `daily_statistics` - 日常统计表
|
||||
|
||||
## 🔐 RLS（权限）策略
|
||||
|
||||
所有 `analytics_*` 表已启用 RLS，策略如下：
|
||||
|
||||
- **用户偏好**：用户只能访问自己的偏好设置
|
||||
- **报表**：用户可访问自己创建的报表和共享报表（`status = 'shared'`）
|
||||
- **报表数据**：通过 `report_id` 关联，继承报表的访问权限
|
||||
- **导出任务**：用户只能访问自己的导出任务
|
||||
|
||||
## 🔧 RPC 函数
|
||||
|
||||
### `rpc_analytics_realtime_kpis`
|
||||
|
||||
计算实时 KPI（GMV、订单数、在线用户、转化率）及增长率。
|
||||
|
||||
**参数：**
|
||||
- `p_start` - 今日起始时间
|
||||
- `p_end` - 今日结束时间（当前时间）
|
||||
- `p_compare_start` - 昨日对应起始时间
|
||||
- `p_compare_end` - 昨日对应结束时间
|
||||
- `p_merchant_id` - 商家ID（可选，NULL表示全站）
|
||||
|
||||
**返回：**
|
||||
```sql
|
||||
gmv, gmv_growth, orders, order_growth, online_users, conversion_rate, conversion_growth
|
||||
```
|
||||
|
||||
**前端调用示例：**
|
||||
```vue
|
||||
<supadb
|
||||
rpc="rpc_analytics_realtime_kpis"
|
||||
:params="{
|
||||
p_start: todayStart,
|
||||
p_end: now,
|
||||
p_compare_start: yesterdayStart,
|
||||
p_compare_end: yesterdaySameTime,
|
||||
p_merchant_id: null
|
||||
}"
|
||||
getone
|
||||
/>
|
||||
```
|
||||
|
||||
### `rpc_analytics_trend_data`
|
||||
|
||||
按日期聚合趋势数据（GMV、订单数、用户数）。
|
||||
|
||||
**参数：**
|
||||
- `p_start_date` - 起始日期
|
||||
- `p_end_date` - 结束日期
|
||||
- `p_merchant_id` - 商家ID（可选）
|
||||
|
||||
**返回：**
|
||||
```sql
|
||||
date, gmv, orders, users
|
||||
```
|
||||
|
||||
## 📝 测试数据说明
|
||||
|
||||
执行 `ANALYTICS_TEST_SEED.sql` 后会创建：
|
||||
|
||||
- **2个测试分析师用户**
|
||||
- **2个测试商家**
|
||||
- **3个测试商品**
|
||||
- **过去30天的测试订单**（每天5-15个订单）
|
||||
- **3个示例报表**（销售报表、用户分析报表、商家销售报表）
|
||||
- **报表核心指标**（GMV、订单量、转化率、客单价）
|
||||
- **7天趋势数据**（为第一个报表）
|
||||
- **3条数据洞察**
|
||||
- **2个报表收藏**
|
||||
- **3个导出任务记录**
|
||||
- **过去30天的统计数据**（`daily_statistics` 表）
|
||||
|
||||
## 🎯 前端使用示例
|
||||
|
||||
### 查询报表列表
|
||||
|
||||
```vue
|
||||
<supadb
|
||||
collection="analytics_reports"
|
||||
:filter="{ owner_user_id: currentUserId }"
|
||||
orderby="created_at desc"
|
||||
:pageSize="10"
|
||||
/>
|
||||
```
|
||||
|
||||
### 查询报表详情
|
||||
|
||||
```vue
|
||||
<supadb
|
||||
collection="analytics_reports"
|
||||
:filter="{ id: reportId }"
|
||||
getone
|
||||
/>
|
||||
```
|
||||
|
||||
### 查询报表指标
|
||||
|
||||
```vue
|
||||
<supadb
|
||||
collection="analytics_report_metrics"
|
||||
:filter="{ report_id: reportId }"
|
||||
/>
|
||||
```
|
||||
|
||||
### 查询趋势数据
|
||||
|
||||
```vue
|
||||
<supadb
|
||||
collection="analytics_report_rows"
|
||||
:filter="{ report_id: reportId }"
|
||||
orderby="row_date asc"
|
||||
/>
|
||||
```
|
||||
|
||||
### 调用 RPC 获取实时 KPI
|
||||
|
||||
```vue
|
||||
<supadb
|
||||
rpc="rpc_analytics_realtime_kpis"
|
||||
:params="{
|
||||
p_start: todayStart.toISOString(),
|
||||
p_end: now.toISOString(),
|
||||
p_compare_start: yesterdayStart.toISOString(),
|
||||
p_compare_end: yesterdaySameTime.toISOString(),
|
||||
p_merchant_id: null
|
||||
}"
|
||||
getone
|
||||
/>
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **执行顺序**：必须先执行 Schema，再执行 Seed
|
||||
2. **基础表依赖**：确保基础业务表（`users`、`merchants`、`orders` 等）已存在
|
||||
3. **时间依赖**：测试数据使用 `NOW()`，每次执行时间戳会不同
|
||||
4. **数据冲突**：脚本使用 `ON CONFLICT DO NOTHING`，可重复执行
|
||||
5. **权限**：确保使用有足够权限的用户执行（如 `postgres`）
|
||||
|
||||
## 🔍 验证部署
|
||||
|
||||
执行以下查询验证部署是否成功：
|
||||
|
||||
```sql
|
||||
-- 检查表是否创建
|
||||
SELECT table_name
|
||||
FROM information_schema.tables
|
||||
WHERE table_schema = 'public'
|
||||
AND table_name LIKE 'analytics_%'
|
||||
ORDER BY table_name;
|
||||
|
||||
-- 检查报表数量
|
||||
SELECT COUNT(*) FROM analytics_reports;
|
||||
-- 应该返回 3
|
||||
|
||||
-- 检查 RPC 函数是否存在
|
||||
SELECT routine_name
|
||||
FROM information_schema.routines
|
||||
WHERE routine_schema = 'public'
|
||||
AND routine_name LIKE 'rpc_analytics_%';
|
||||
-- 应该看到 rpc_analytics_realtime_kpis 和 rpc_analytics_trend_data
|
||||
|
||||
-- 测试 RPC 函数
|
||||
SELECT * FROM rpc_analytics_realtime_kpis(
|
||||
DATE_TRUNC('day', NOW()),
|
||||
NOW(),
|
||||
DATE_TRUNC('day', NOW() - INTERVAL '1 day'),
|
||||
NOW() - INTERVAL '1 day',
|
||||
NULL
|
||||
);
|
||||
```
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- **数据库设计文档**：`pages/mall/analytics/docs/ANALYTICS_DB_DESIGN.md`
|
||||
- **快速开始指南**：`pages/mall/analytics/docs/ANALYTICS_DB_QUICK_START.md`（本文档）
|
||||
- **测试数据说明**：`pages/mall/analytics/test/README.md`
|
||||
- **SQL 使用指南**：`pages/mall/analytics/test/SQL_USAGE_GUIDE.md`
|
||||
- **项目需求文档**：`pages/mall/mall.md`（第2.6节、第10节）
|
||||
|
||||
## 🆘 问题排查
|
||||
|
||||
如果遇到问题，请检查：
|
||||
|
||||
1. **连接问题**：确认 Supabase 服务运行正常
|
||||
2. **权限问题**：确认使用 `postgres` 用户或有足够权限
|
||||
3. **表冲突**：如果表已存在，脚本不会报错（使用 `IF NOT EXISTS`）
|
||||
4. **数据验证**：执行 `03_test_queries.sql` 验证数据
|
||||
|
||||
更多帮助请参考：`pages/mall/analytics/test/SQL_USAGE_GUIDE.md`
|
||||
Reference in New Issue
Block a user