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

摘要

为 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