sql数据流，amdin业务逻辑接入

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

@@ -0,0 +1,62 @@
+# 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`

pages/mall/admin/user/docs/ops/2026-02-04__admin-user__user-statistics-db-and-gender-rpc.md

@@ -0,0 +1,78 @@
+# 摘要
+
+为 `pages/mall/admin/user/Statistic.uvue` 的“用户统计”页面接入数据库（复用 analytics RPC），并补齐“用户性别比例”模块的数据库接入。按项目规范新增模块内 `test/` 与 `docs/`，并将满足权威准入要求的性别比例 RPC 归档到 `docs/sql/30_rpc/analytics/`。
+
+# 动机
+
+- 现有 admin 用户统计页 KPI/趋势/性别比例均为静态数据，无法反映真实业务数据。
+- 按 `docs/AGENT_PROJECT_SPEC.md` 的两阶段 SQL 工作流：模块内测试 `test/` 先验证，满足安全准入后才进入 `docs/sql/` 权威目录。
+
+# 影响范围
+
+- **页面**：`pages/mall/admin/user/Statistic.uvue`
+- **组件**：`components/analytics/AnalyticsUserGenderSection.uvue`
+- **SQL（模块测试）**：`pages/mall/admin/user/test/*.sql`
+- **SQL（权威入库）**：`docs/sql/30_rpc/analytics/rpc_analytics_user_gender_distribution_v1.sql`
+
+# 变更清单
+
+## 新增文件
+
+- `pages/mall/admin/user/test/01_ml_admin_user_statistics_verify.sql`
+- `pages/mall/admin/user/test/99_ml_admin_user_statistics_verify.sql`
+- `pages/mall/admin/user/test/02_ml_admin_user_gender_rpc.sql`（测试/验证脚本）
+- `pages/mall/admin/user/docs/USER_STATISTICS_DB.md`
+- `docs/sql/00_meta/README.md`
+- `docs/sql/10_schema/README.md`
+- `docs/sql/20_rls/README.md`
+- `docs/sql/30_rpc/README.md`
+- `docs/sql/40_grants/README.md`
+- `docs/sql/90_archive/README.md`
+- `docs/sql/30_rpc/analytics/rpc_analytics_user_gender_distribution_v1.sql`
+- `pages/mall/admin/user/docs/ops/2026-02-04__admin-user__user-statistics-db-and-gender-rpc.md`（本文件）
+
+## 修改文件
+
+- `pages/mall/admin/user/Statistic.uvue`
+  - KPI/趋势改为 RPC 动态加载
+  - 月份范围筛选（当前月默认）
+  - 将 `startDate/endDate` 透传给性别比例组件
+- `components/analytics/AnalyticsUserGenderSection.uvue`
+  - 静态数据改为 RPC 动态加载
+- `pages/mall/admin/user/docs/USER_STATISTICS_DB.md`
+  - 更新权威 RPC 引用路径
+
+## 删除文件
+
+- 无
+
+# 兼容性与风险
+
+- **RPC 权限风险**：权威 RPC 使用 `SECURITY DEFINER` 绕过 RLS，必须依赖 `public.get_current_user_role()` 做入口鉴权。
+- **数据口径风险**：当前 `ak_users.gender` 取值为 `male/other/NULL`，映射为 `男/未知`（并兼容 future `female`）。
+- **部署风险**：需确保数据库已执行权威 SQL（或在迁移流程中纳入）。
+
+# 回滚方案
+
+- 前端回滚：
+  - 回滚 `pages/mall/admin/user/Statistic.uvue` 与 `components/analytics/AnalyticsUserGenderSection.uvue` 到改动前版本。
+- 数据库回滚：
+  - 执行 `DROP FUNCTION IF EXISTS public.rpc_analytics_user_gender_distribution(DATE, DATE);`
+  - 或将权威 RPC 文件从迁移/部署流程移除。
+
+# 验证方式
+
+1. **数据库验证**（管理员/analytics 身份）：
+   - 执行 `docs/sql/30_rpc/analytics/rpc_analytics_user_gender_distribution_v1.sql`
+   - 调用：
+     - `SELECT * FROM public.rpc_analytics_user_gender_distribution('2026-01-01','2026-01-31');`
+   - 确认返回 `未知/男/女` 分布。
+
+2. **前端验证**：
+   - 打开 admin 用户统计页：KPI 与趋势显示为动态数据。
+   - 选择月份后：KPI、趋势与“用户性别比例”同步刷新。
+
+# 关联文档
+
+- `docs/AGENT_PROJECT_SPEC.md`
+- `docs/sql/11_roles_and_permissions_strategy.md`