medical-mall/docs/ops/2026-02-10__admin__user-level-db-design.md

用户等级数据库设计与 RPC（v1）

摘要

为“用户等级”功能新增数据库表 public.ak_user_levels（支持逻辑删除），并提供 admin 侧管理 RPC（分页列表/保存/删除/状态切换/展示切换）。同时启用 RLS：消费者端仅可读取“启用且展示且未删除”的等级。

动机

• 当前 admin 用户等级页面存在硬编码 mock 数据，需要接入数据库。
• 统一等级数据口径，为消费者端展示等级提供可靠数据源。

影响范围

• 数据库：新增表、索引；启用 RLS 并新增 select policy；新增 5 个 admin RPC。
• 前端：后续可通过 services/ 接入新 RPC，移除 pages/mall/admin/user/level.uvue 中 mock。

变更清单

• 新增文件：
  • docs/sql/10_schema/user/ak_user_levels_v1.sql
  • docs/sql/20_rls/user/ak_user_levels_rls_v1.sql
  • docs/sql/30_rpc/user/rpc_admin_user_level_list_v1.sql
  • docs/sql/30_rpc/user/rpc_admin_user_level_save_v1.sql
  • docs/sql/30_rpc/user/rpc_admin_user_level_delete_v1.sql
  • docs/sql/30_rpc/user/rpc_admin_user_level_set_visible_v1.sql
  • docs/sql/30_rpc/user/rpc_admin_user_level_set_status_v1.sql

兼容性与风险

• consumer 端读取：RLS 仅开放 anon/authenticated 对可见/启用/未删除等级的 SELECT；不会暴露删除或禁用的数据。
• admin 端管理：通过 SECURITY DEFINER RPC 并进行角色鉴权，避免直通表的全局权限。
• 逻辑删除：通过 deleted_at 字段实现，避免历史引用破坏。

回滚方案

• 回滚 schema：删除表 ak_user_levels（需人工确认，不在本次脚本中提供）。
• 回滚 rpc：删除对应函数（需人工确认，不在本次脚本中提供）。
• 回滚 rls：移除 policy 并禁用 RLS（需人工确认）。

验证方式

• 在 SQL 控制台依次执行：schema -> rls -> rpc。
• 使用 admin 账号调用：
  • rpc_admin_user_level_save 创建数据
  • rpc_admin_user_level_list 验证分页返回
  • rpc_admin_user_level_set_visible/status 验证更新
  • rpc_admin_user_level_delete 验证逻辑删除
• 使用普通账号/匿名访问验证仅能看到启用且展示的数据。

关联文档

• docs/project_spec/AGENT_PROJECT_SPEC.md
• docs/sql/30_rpc/auth/get_current_user_role_v1.sql
• docs/sql/11_roles_and_permissions_strategy.md