huangzhenbao/medical-mall

Fork 0

Files

comlibmb c14f67cfc8 数据分析页面骨架

2026-01-23 16:33:11 +08:00

7.5 KiB

Raw Blame History

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

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

📁 文件位置

所有 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步）

方式一：使用完整脚本（推荐）

执行 Schema

-- 在 Supabase SQL Editor 中执行
-- 复制粘贴 pages/mall/analytics/test/ANALYTICS_DB_SCHEMA.sql 的内容

插入测试数据

-- 复制粘贴 pages/mall/analytics/test/ANALYTICS_TEST_SEED.sql 的内容

验证

SELECT COUNT(*) FROM analytics_reports;
-- 应该返回 3

方式二：使用分步脚本

创建表结构

\i pages/mall/analytics/test/01_create_tables.sql

插入测试数据

\i pages/mall/analytics/test/02_insert_test_data.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表示全站）

返回：

gmv, gmv_growth, orders, order_growth, online_users, conversion_rate, conversion_growth

前端调用示例：

<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（可选）

返回：

date, gmv, orders, users

📝 测试数据说明

执行 ANALYTICS_TEST_SEED.sql 后会创建：

2个测试分析师用户
2个测试商家
3个测试商品
过去30天的测试订单（每天5-15个订单）
3个示例报表（销售报表、用户分析报表、商家销售报表）
报表核心指标（GMV、订单量、转化率、客单价）
7天趋势数据（为第一个报表）
3条数据洞察
2个报表收藏
3个导出任务记录
过去30天的统计数据（daily_statistics 表）

🎯 前端使用示例

查询报表列表

<supadb
  collection="analytics_reports"
  :filter="{ owner_user_id: currentUserId }"
  orderby="created_at desc"
  :pageSize="10"
/>

查询报表详情

<supadb
  collection="analytics_reports"
  :filter="{ id: reportId }"
  getone
/>

查询报表指标

<supadb
  collection="analytics_report_metrics"
  :filter="{ report_id: reportId }"
/>

查询趋势数据

<supadb
  collection="analytics_report_rows"
  :filter="{ report_id: reportId }"
  orderby="row_date asc"
/>

调用 RPC 获取实时 KPI

<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
/>

⚠️ 注意事项

执行顺序：必须先执行 Schema，再执行 Seed
基础表依赖：确保基础业务表（users、merchants、orders 等）已存在
时间依赖：测试数据使用 NOW()，每次执行时间戳会不同
数据冲突：脚本使用 ON CONFLICT DO NOTHING，可重复执行
权限：确保使用有足够权限的用户执行（如 postgres）

🔍 验证部署

执行以下查询验证部署是否成功：

-- 检查表是否创建
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节）

🆘 问题排查

如果遇到问题，请检查：

连接问题：确认 Supabase 服务运行正常
权限问题：确认使用 postgres 用户或有足够权限
表冲突：如果表已存在，脚本不会报错（使用 IF NOT EXISTS）
数据验证：执行 03_test_queries.sql 验证数据

更多帮助请参考：pages/mall/analytics/test/SQL_USAGE_GUIDE.md

7.5 KiB Raw Blame History Unescape Escape