medical-mall/pages/mall/analytics/docs/ANALYTICS_DB_DESIGN.md

数据分析模块数据库设计（Supabase / Postgres）

本文档面向 数据分析端（Analytics Dashboard），为页面 pages/mall/analytics/* 提供可落地的表结构、字段字典、以及用于联调的模拟数据方案。

参考输入（仅作为需求与既有模型依据）：pages/mall/mall.md（订单/用户/商品/配送/优惠券/统计）、pages/mall/analytics/docs/ANALYTICS_PAGES_ANALYSIS.md（页面与指标清单）、以及前端页面当前使用的字段名（如 realTime.gmv、report.title 等）。

文档位置：pages/mall/analytics/docs/ANALYTICS_DB_DESIGN.md

---

1. 设计目标与范围

1.1 目标

• 支持已实现页面的数据落库：index（实时 KPI + 趋势）、profile（报表列表/偏好/导出）、report-detail（报表详情 + 指标 + 明细表格 + 洞察）。
• 支持后续页面扩展：sales-report、user-analysis、product-insights、delivery-analysis、coupon-analysis、market-trends、custom-report。
• 与 components/supadb 兼容：优先提供可 select 的表/视图；复杂统计使用 RPC（Postgres function），在前端通过 supadb.uvue 的 rpc 能力调用。

1.2 范围说明

• 本文档不替代业务核心表（如 orders、order_items、products、users、delivery_tasks、coupon_*）。这些以 pages/mall/mall.md 为准。
• 本文档新增的是 Analytics 侧“报表/洞察/导出/偏好/预警”等应用数据表，以及可选的聚合视图/RPC。

---

2. 现有基础表（业务域）与分析端关系

数据分析端统计大多来源于以下基础表（来自 mall.md 的模型）：

• 订单域：orders、order_items
• 用户域：users
• 商家/商品域：merchants、products、categories
• 配送域：delivery_tasks、delivery_drivers、delivery_tracks
• 营销域：coupon_templates、user_coupons、coupon_usage_logs
• 统计域（已在需求中出现）：daily_statistics（按天、可按 merchant_id 聚合）

分析端新增的表会通过外键关联这些基础表（尤其是 users、merchants、orders）。

---

3. Analytics 新增表：数据字典（推荐最小集）

命名约定：以 analytics_ 为前缀，避免与业务表冲突。

3.1 analytics_user_preferences（分析师偏好）

用途：profile 页偏好设置、默认周期、默认看板等。

字段	类型	约束	说明
id	uuid	PK	主键
user_id	uuid	FK → users(id), UNIQUE	偏好所属用户
default_period	text	NOT NULL, default '7d'	7d/30d/90d/1y 等
timezone	text	default 'Asia/Shanghai'	时区
currency	text	default 'CNY'	展示币种
kpi_cards	jsonb	default '[]'	KPI 卡片配置（顺序/开关）
created_at	timestamptz	default now()	创建时间
updated_at	timestamptz	default now()	更新时间

索引建议：(user_id) 唯一索引即可。

---

3.2 analytics_reports（报表定义/实例）

用途：report-detail 的 report 主体、profile 最近报表列表、custom-report 报表定义。

字段	类型	约束	说明
id	uuid	PK	报表 ID
owner_user_id	uuid	FK → users(id)	报表创建者/所属分析师
merchant_id	uuid	FK → merchants(id), nullable	可选：报表限定商家
title	text	NOT NULL	报表标题（report.title）
description	text	default ''	描述（列表展示）
type	text	NOT NULL	sales/users/orders/conversion/coupon/delivery/market/custom 等
period	text	NOT NULL	7d/30d/90d/1y 或自定义
date_start	date	nullable	自定义范围起始
date_end	date	nullable	自定义范围结束
status	text	NOT NULL, default 'ready'	pending/ready/failed/scheduled/shared
generated_at	timestamptz	nullable	生成时间（report.generated_at）
created_at	timestamptz	default now()	创建时间
updated_at	timestamptz	default now()	更新时间

索引建议：

• (owner_user_id, created_at desc)
• (type, generated_at desc)
• (status)

---

3.3 analytics_report_metrics（报表核心指标）

用途：report-detail 页“核心指标”网格（coreMetrics）。

字段	类型	约束	说明
id	uuid	PK	主键
report_id	uuid	FK → analytics_reports(id)	所属报表
metric_key	text	NOT NULL	gmv/orders/conversion_rate/avg_order_amount 等
metric_label	text	NOT NULL	展示名称
metric_value_num	numeric	nullable	数值
metric_value_text	text	nullable	文本（如百分比已格式化）
format	text	NOT NULL, default 'number'	number/currency/percent
change_pct	numeric	default 0	环比/同比变化（页面用 metric.change）
icon	text	default ''	UI 图标（可选）
color	text	default '#3b82f6'	UI 颜色（可选）
created_at	timestamptz	default now()	创建时间

索引建议：(report_id, metric_key) 唯一或普通索引（按需求）。

---

3.4 analytics_report_rows（报表明细表格/趋势表）

用途：report-detail 页“详细数据”表格与趋势（tableData、图表）。

字段	类型	约束	说明
id	uuid	PK	主键
report_id	uuid	FK → analytics_reports(id)	所属报表
row_date	date	NOT NULL	统计日期（或维度日期）
gmv	numeric	default 0	GMV（元）
orders	integer	default 0	订单数
users	integer	default 0	用户数（可选）
conversion	numeric	default 0	转化率（0-100）或（0-1）需统一约定
avg_order_amount	numeric	default 0	客单价
extra	jsonb	default '{}'	扩展字段（用于自定义报表列）
created_at	timestamptz	default now()	创建时间

索引建议：

• (report_id, row_date)

---

3.5 analytics_insights（洞察/建议）

用途：profile 今日洞察、report-detail 洞察列表、insight-detail 详情页。

字段	类型	约束	说明
id	uuid	PK	洞察 ID
report_id	uuid	FK → analytics_reports(id), nullable	关联报表（可空：全局洞察）
owner_user_id	uuid	FK → users(id), nullable	关联分析师（可空：系统生成）
type	text	NOT NULL	positive/warning/negative/info 等
impact	text	NOT NULL, default 'medium'	high/medium/low
title	text	NOT NULL	洞察标题
content	text	NOT NULL	洞察内容
tags	text[]	default '{}'	标签（可选）
created_at	timestamptz	default now()	创建时间

索引建议：

• (created_at desc)
• (report_id, created_at desc)

---

3.6 analytics_report_favorites（收藏/快捷入口）

用途：profile 报表收藏管理。

字段	类型	约束	说明
id	uuid	PK	主键
user_id	uuid	FK → users(id)	用户
report_id	uuid	FK → analytics_reports(id)	报表
created_at	timestamptz	default now()	创建时间

唯一约束：UNIQUE(user_id, report_id)

---

3.7 analytics_export_jobs（导出任务/历史）

用途：profile 导出历史、report-detail 导出按钮触发。

字段	类型	约束	说明
id	uuid	PK	导出任务 ID
user_id	uuid	FK → users(id)	发起用户
report_id	uuid	FK → analytics_reports(id)	关联报表
format	text	NOT NULL	csv/xlsx/pdf/json
status	text	NOT NULL, default 'queued'	queued/running/done/failed
file_path	text	nullable	Storage 路径（私有桶）
error_message	text	default ''	失败原因
created_at	timestamptz	default now()	创建时间
finished_at	timestamptz	nullable	完成时间

索引建议：(user_id, created_at desc)、(status)

---

4. 可选：视图与 RPC（推荐）

4.1 视图：v_analytics_daily_overview

用途：复用 daily_statistics，快速给首页 KPI 与趋势提供数据源。

• 粒度：按 stat_date + merchant_id（或全站 merchant_id 为空/特殊值）

是否需要全站维度：建议 用 merchant_id 为空表示全站 或单独建全站行。

4.2 RPC：rpc_analytics_realtime_kpis

用途：首页实时 KPI（对比昨日同刻）。 输入建议：

• p_start timestamptz：今日起始
• p_end timestamptz：今日结束（当前时间）
• p_compare_start timestamptz：昨日对应起始
• p_compare_end timestamptz：昨日对应结束
• p_merchant_id uuid（可选）

输出建议（单行）：

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

前端当前 index.uvue 直接从 orders 表计算 KPI；后续可以改为 RPC 提升性能与一致性。

---

5. RLS（权限矩阵建议）

核心原则：前端只用 anon key，所有访问靠 RLS。

5.1 表访问建议

• analytics_user_preferences：用户只能读写自己的 user_id = auth.uid()
• analytics_reports：
  • 普通分析师：owner_user_id = auth.uid() 的报表可读写
  • 共享报表：status = 'shared' 可读（可加 share 表细化）
• analytics_report_metrics / analytics_report_rows / analytics_insights / analytics_export_jobs：通过关联 report_id 或 user_id 做同权限继承

---

6. 模拟数据（联调）策略

目标：让下列页面在无真实业务数据时也能跑通：

• index：订单与用户有数据 → KPI 与趋势能算出来
• profile：有“最近报表/洞察/导出任务”列表
• report-detail：存在 analytics_reports + metrics + rows + insights

6.1 推荐做法

• 插入少量 users/merchants/products/orders/order_items（过去 30 天）
• 同时插入 2-3 份 analytics_reports（不同 type/period）
• 每份报表插入 4-6 个核心指标 + 15-30 行 analytics_report_rows
• 插入 3-8 条 analytics_insights
• 插入 2-3 条 analytics_export_jobs

对应 SQL 脚本（位于 pages/mall/analytics/test/ 目录）：

• Schema（表结构/索引/RLS/RPC）：pages/mall/analytics/test/ANALYTICS_DB_SCHEMA.sql
• 测试数据（Seed）：pages/mall/analytics/test/ANALYTICS_TEST_SEED.sql
• 分步执行脚本：
  • 01_create_tables.sql - 创建表结构
  • 02_insert_test_data.sql - 插入测试数据
  • 03_test_queries.sql - 测试查询示例
  • 04_cleanup.sql - 清理测试数据
• 使用指南：pages/mall/analytics/test/README.md 和 SQL_USAGE_GUIDE.md

---

7. 使用说明

7.1 部署步骤

1. 执行 Schema（创建表、索引、RLS、RPC）：

   -- 在 Supabase SQL Editor 中执行
   -- 方式一：直接复制粘贴 ANALYTICS_DB_SCHEMA.sql 内容
   -- 方式二：使用分步脚本（推荐）
   \i pages/mall/analytics/test/01_create_tables.sql
   

2. 插入测试数据：

   -- 方式一：直接复制粘贴 ANALYTICS_TEST_SEED.sql 内容
   -- 方式二：使用分步脚本（推荐）
   \i pages/mall/analytics/test/02_insert_test_data.sql
   

3. 验证查询（可选）：

   \i pages/mall/analytics/test/03_test_queries.sql
   

4. 验证：

   • 检查表是否创建：SELECT * FROM analytics_reports LIMIT 1;
   • 检查 RPC 是否可用：SELECT * FROM rpc_analytics_realtime_kpis(...);

7.2 前端调用示例（使用 components/supadb）

查询报表列表：

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

调用 RPC 获取实时 KPI：

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

---

8. 反抄袭自证

8.1 仅参考资料（只含规范/文档/API）

• pages/mall/mall.md（项目需求与数据模型）
• pages/mall/analytics/docs/ANALYTICS_PAGES_ANALYSIS.md（页面与指标清单）
• pages/mall/analytics/docs/ANALYTICS_UI_DESIGN.md（页面与交互约定）
• Supabase/Postgres 官方文档（表/索引/RLS/RPC 概念）

8.2 未参考任何实现代码的声明

本文档的表结构与字段设计为基于可观察页面字段与需求规格独立推导的原创设计，未复制/改写任何第三方或原项目实现源码。