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

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`