medical-mall/docs/sql/00_meta/11_roles_and_permissions_strategy.md

角色与权限策略（权威口径）

本文档为 docs/sql/ 权威 SQL 入库与评审的安全口径说明。任何涉及 RLS / RPC / GRANT 的变更，必须对照本文档与 docs/project_spec/AGENT_PROJECT_SPEC.md。

1. 权威身份字段

• 后台/分析端角色字段唯一权威：public.ak_users.role
• 推荐值：admin / analytics / user（以及业务需要的扩展值）

2. 权限访问基本原则

2.1 最小权限原则

• 默认不对 anon / authenticated 开放管理侧敏感表的直接访问。
• 管理侧的“全局读写”必须通过 RPC（函数）进行封装。

2.2 RLS 先行

• 所有业务表必须开启 RLS（除非明确说明原因）。
• 对消费者端可公开读取的数据（如提货点），允许创建只读 SELECT policy，并限制条件（例如 status = 1）。

3. RPC 安全口径（强制）

3.1 SECURITY DEFINER

所有管理端 RPC 必须：

• SECURITY DEFINER
• SET search_path = public
• 入口鉴权：必须校验当前用户为后台管理员

推荐的入口鉴权形式：

• 通过 public.ak_users 校验：
  • WHERE auth_id = auth.uid() AND role = 'admin'

注：如未来引入统一函数 get_current_user_role()，则可改为 get_current_user_role() IN ('admin','analytics')。

3.2 返回字段最小化

• 仅返回前端所需字段。
• 禁止返回敏感字段（如密钥、token、完整手机号/身份证号等），除非有明确业务需求与脱敏方案。

3.3 分页与限制

• 列表类 RPC 必须支持分页（LIMIT/OFFSET）或带 LIMIT。

4. GRANT/REVOKE 口径

• 默认：REVOKE ALL ... FROM PUBLIC。
• 仅对需要调用 RPC 的角色授予 EXECUTE（通常为 authenticated）。
• 禁止对 anon/authenticated 大范围 GRANT 直接表权限。

5. 入库评审要点（与 AGENT_PROJECT_SPEC.md 对齐）

评审必须覆盖：

• 是否开启 RLS；policy 是否过宽。
• 是否存在不安全的 SECURITY DEFINER（无鉴权/未固定 search_path）。
• 是否有破坏性语句（DROP/TRUNCATE/无 WHERE 的 UPDATE/DELETE）。

---

6. 关联文档

• docs/project_spec/AGENT_PROJECT_SPEC.md
• docs/sql/00_meta/README.md