medical-mall/pages/mall/admin/user/docs/USER_STATISTICS_DB.md

Admin / 用户统计 - 数据库接入说明

本页面（pages/mall/admin/user/Statistic.uvue）复用 analytics 模块的 RPC 统计口径，不在 admin 模块重复定义。

依赖 RPC

• public.rpc_analytics_user_kpis(p_start_date DATE, p_end_date DATE)
• public.rpc_analytics_user_growth_trend(p_start_date DATE, p_end_date DATE)
• （可选扩展）
  • public.rpc_analytics_user_segments(p_start_date DATE, p_end_date DATE)
  • public.rpc_analytics_traffic_sources(p_start_date DATE, p_end_date DATE)

RPC 定义参考（权威）：

• docs/sql/30_rpc/auth/get_current_user_role_v1.sql（RPC 入口鉴权依赖）
• docs/sql/30_rpc/analytics/rpc_analytics_user_gender_distribution_v1.sql（性别比例）

历史/迁移参考（非权威引用口径）：

• mall_sql/migrations/ml_analytics_rpcs.sql
• pages/mall/analytics/test/01_ml_analytics_rpcs_user.sql

依赖数据表（口径来源）

• public.ak_users
• public.ml_orders
• public.ml_browse_history

KPI 映射（页面展示 → RPC 返回字段）

页面 KPI（现 UI）建议映射如下：

• 累计用户 → total_users
• 新增用户数 → new_users
• 成交用户数 → paid_users 或 ordering_users
  • 如果你希望“成交”严格等于“支付成功用户”，用 paid_users
  • 如果你希望“成交”口径为“下单用户”，用 ordering_users

注意：当前 admin 页 UI 里存在“访客数/浏览量/付费会员数”等字段，但现有 rpc_analytics_user_kpis 并不直接返回：

• 访客数、浏览量：需要基于埋点/访问日志表口径定义（可后续新增 RPC）
• 付费会员数：需要会员/订阅表口径（如 ml_user_subscriptions）或会员字段

因此第一阶段接入会优先保证：

• KPI：累计用户、新增用户、活跃用户、下单用户、支付用户、复购率等
• 趋势：新增用户、活跃用户（与 analytics 对齐）

SQL 验证文件

验证与调用样例：

• pages/mall/admin/user/test/01_ml_admin_user_statistics_verify.sql

前端接入方式

建议使用与 analytics 同样的 Supabase RPC 调用方式：

• 使用 ensureSupabaseReady() 初始化
• supa.rpc('rpc_analytics_user_kpis', params) 获取 KPI
• supa.rpc('rpc_analytics_user_growth_trend', params) 获取趋势

params 示例：

• p_start_date: YYYY-MM-DD
• p_end_date: YYYY-MM-DD