# 摘要

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