# 数据分析模块数据库快速开始指南

> 本文档提供数据分析模块数据库的快速部署和使用指南。

## 📁 文件位置

所有 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`