admin的数据库文件补全，修复uvue中的数据库接入bug

2026-02-25 10:02:50 +08:00
parent 5d00e3d74e
commit dc8f899610
40 changed files with 1629 additions and 625 deletions
--- a/docs/sql/00_meta/11_roles_and_permissions_strategy.md
+++ b/docs/sql/00_meta/11_roles_and_permissions_strategy.md
@@ -0,0 +1,67 @@
+# 角色与权限策略（权威口径）
+
+> 本文档为 `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`
--- a/docs/sql/00_meta/12_soft_delete_standard.md
+++ b/docs/sql/00_meta/12_soft_delete_standard.md
@@ -0,0 +1,75 @@
+# 数据库软删除 (Soft Delete) 统一标准规范
+
+## 1. 核心目标
+- **数据保留**：防止误操作导致的数据永久丢失，支持操作审计。
+- **级联安全**：通过逻辑链路同步软删关联数据，避免孤儿数据。
+- **透明过滤**：利用 RLS（行级安全策略）或统一过滤口径，使业务层查询默认排除已标记删除的记录。
+
+## 2. 字段规范
+所有需要支持软删除的业务表必须统一包含以下字段：
+
+| 字段名        | 类型          | 说明                                    | 索引建议         |
+| :------------ | :------------ | :-------------------------------------- | :--------------- |
+| `deleted_at`  | `TIMESTAMPTZ` | 删除时间戳。非 NULL 表示已删除。        | **必须建立索引** |
+| `deleted_by`  | `UUID`        | 执行删除操作的用户 ID (`ak_users.id`)。 | 建议索引         |
+| `restored_at` | `TIMESTAMPTZ` | (可选) 最近一次恢复的时间戳。           | -                |
+| `restored_by` | `UUID`        | (可选) 最近一次恢复的操作人。           | -                |
+
+## 3. RLS 自动过滤口径
+为了确保查询透明性，必须在 `20_rls/` 策略中统一加入过滤条件：
+
+```sql
+-- 示例策略：仅允许查询未删除的记录
+CREATE POLICY select_active_records ON public.your_table
+  FOR SELECT
+  TO authenticated
+  USING (deleted_at IS NULL);
+```
+
+## 4. RPC 重构准则
+删除接口必须从 `DELETE FROM ...` 改为 `UPDATE ... SET deleted_at = now()`：
+
+### 4.1 基础删除模板
+```sql
+CREATE OR REPLACE FUNCTION public.rpc_admin_soft_delete_item(p_id UUID)
+RETURNS BOOLEAN SECURITY DEFINER SET search_path = public AS $$
+BEGIN
+    -- 1. 鉴权 (示例)
+    IF NOT EXISTS (
+        SELECT 1 FROM public.ak_users 
+        WHERE auth_id = auth.uid() AND role = 'admin'
+    ) THEN
+        RAISE EXCEPTION 'Permission denied';
+    END IF;
+    
+    -- 2. 执行软删
+    UPDATE public.your_table
+    SET deleted_at = now(), deleted_by = auth.uid()
+    WHERE id = p_id AND deleted_at IS NULL;
+    
+    RETURN FOUND;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### 4.2 级联软删除规范
+若存在级联依赖（如：软删“商品分类”时需同步软删其下的“商品”），必须在 RPC 内部通过事务或同步 UPDATE 处理：
+
+```sql
+-- 级联链路示例
+UPDATE public.ml_products
+SET deleted_at = now(), deleted_by = auth.uid()
+WHERE category_id = p_category_id AND deleted_at IS NULL;
+```
+
+## 5. UI 交互适配
+- **默认视图**：列表页面默认仅展示 `deleted_at IS NULL` 的数据。
+- **回收站 (可选)**：若业务需要，可提供“回收站”视图（过滤 `deleted_at IS NOT NULL`）及“恢复”功能。
+- **二次确认**：点击“删除”按钮时，必须弹出提示明确告知数据将进入逻辑删除状态。
+
+---
+
+## 6. 改造优先级
+1. **第一梯队**：基础资产（商品、分类、文章、分销商）。
+2. **第二梯队**：配置类（运费模板、通知模板、DIY 页面）。
+3. **第三梯队**：日志/交互类（评论、收藏、地址）。