# 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`