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

docs/ops/2026-02-18__admin__auth-delivery-infrastructure-integration.md

@@ -1,59 +1,274 @@
 # 权限、物流及系统基础设施全量集成报告
 
 ## 摘要
-本次对 Admin 侧进行了大规模的基础设施补齐与核心管理模块重构。完成了权限管理（Auth/RBAC）、物流设置（Delivery Staff/Stations）、系统通用配置（ml_system_configs）以及数据概览（Statistic）与系统维护（Maintain）模块的端到端数据库接入。彻底解决了这些模块此前长期存在的 Mock 问题。
+本次对 Admin 侧进行了基础设施补齐与核心管理模块重构，完成以下闭环：
+- 新增系统统一 KV 配置表 `ml_system_configs`，并提供管理端 RPC 读写；
+- 建立 RBAC 权限体系（角色/权限/关联表），并以管理端 RPC 提供 CRUD；
+- 新增物流资源表（配送员、提货点），并以管理端 RPC 提供 CRUD；
+- 将 Admin 侧相关页面从 Mock/静态数据切换为真实 RPC 数据流。
 
 ## 动机
-虽然商城的业务模块（商品、订单等）已基本闭环，但支撑系统运行的“底座”模块（权限控制、系统开关、物流资源等）仍处于静态模拟阶段。为了实现生产级的管理后台，必须建立统一的配置存储体系、完善的权限分配机制以及真实的物流资源管理。
+商城核心业务（商品、订单等）已基本闭环，但系统底座模块（权限控制、系统开关、物流资源）仍长期处于 Mock/静态模拟阶段，无法满足生产环境可审计、可配置、可授权的要求，因此需要补齐数据库资产（Schema/RLS/RPC）与前端服务层。
 
 ## 影响范围
-- **核心底座**：系统配置读写、全站聚合统计。
-- **权限安全**：角色管理、菜单权限树配置、管理员分配。
-- **物流资源**：配送员库、提货点/核销点管理。
-- **应用配置**：公众号、小程序、APP 及 PC 端参数持久化。
+- **数据库**：新增表、启用 RLS、增加 `SECURITY DEFINER` RPC，影响 admin/analytics 权限闭环。
+- **管理端页面**：权限管理（管理员/角色/菜单权限）、物流设置（配送员/提货点）、系统配置、统计概览、系统信息页面。
+- **服务层**：新增 `services/admin/*Service.uts`，统一数据访问出口（页面不再直连底层 client）。
 
 ## 变更清单
+> 以提交 `5d00e3d` 为准（`feat(admin): complete integration of auth, delivery, and system infrastructure modules`）。
 
-### 1. 数据库资产 (SQL)
-- **Schema (10_schema)**:
-  - `admin/ml_system_configs_v1.sql`: 统一配置表。
-  - `user/ak_auth_system_v1.sql`: 角色、权限、关联表 (RBAC)。
-  - `delivery/ak_delivery_system_v1.sql`: 配送员、提货点表。
-- **RLS (20_rls)**:
-  - `admin/ml_system_configs_rls_v1.sql`
-  - `auth/ak_auth_rls_v1.sql`
-  - `delivery/ak_delivery_rls_v1.sql`
-- **RPC (30_rpc)**:
-  - **Admin**: `rpc_admin_system_config_get/save`, `rpc_admin_get_overall_stats`, `rpc_admin_get_system_info`。
-  - **Auth**: `rpc_admin_get_admin_list`, `rpc_admin_get_role_list/save/delete`, `rpc_admin_get_permission_list/save/delete`。
-  - **Delivery**: 配送员管理 (list/save/delete)、提货点管理 (list/save/delete)。
+### 新增文件
+#### 数据库（权威入库：`docs/sql/`）
+- Schema（`docs/sql/10_schema/`）
+  - `docs/sql/10_schema/admin/ml_system_configs_v1.sql`
+  - `docs/sql/10_schema/user/ak_auth_system_v1.sql`
+  - `docs/sql/10_schema/delivery/ak_delivery_system_v1.sql`
+- RLS（`docs/sql/20_rls/`）
+  - `docs/sql/20_rls/admin/ml_system_configs_rls_v1.sql`
+  - `docs/sql/20_rls/auth/ak_auth_rls_v1.sql`
+  - `docs/sql/20_rls/delivery/ak_delivery_rls_v1.sql`
+- RPC（`docs/sql/30_rpc/`）
+  - Admin
+    - `docs/sql/30_rpc/admin/rpc_admin_get_overall_stats_v1.sql`
+    - `docs/sql/30_rpc/admin/rpc_admin_get_system_info_v1.sql`
+    - `docs/sql/30_rpc/admin/rpc_admin_system_config_get_v1.sql`
+  - Auth
+    - `docs/sql/30_rpc/auth/rpc_admin_get_admin_list_v1.sql`
+    - `docs/sql/30_rpc/auth/rpc_admin_get_role_list_v1.sql`
+    - `docs/sql/30_rpc/auth/rpc_admin_save_role_v1.sql`
+    - `docs/sql/30_rpc/auth/rpc_admin_delete_role_v1.sql`
+    - `docs/sql/30_rpc/auth/rpc_admin_get_permission_list_v1.sql`
+    - `docs/sql/30_rpc/auth/rpc_admin_save_permission_v1.sql`
+    - `docs/sql/30_rpc/auth/rpc_admin_delete_permission_v1.sql`
+  - Delivery
+    - `docs/sql/30_rpc/delivery/rpc_admin_get_delivery_staff_list_v1.sql`
+    - `docs/sql/30_rpc/delivery/rpc_admin_save_delivery_staff_v1.sql`
+    - `docs/sql/30_rpc/delivery/rpc_admin_delete_delivery_staff_v1.sql`
+    - `docs/sql/30_rpc/delivery/rpc_admin_get_delivery_station_list_v1.sql`
+    - `docs/sql/30_rpc/delivery/rpc_admin_save_delivery_station_v1.sql`
+    - `docs/sql/30_rpc/delivery/rpc_admin_delete_delivery_station_v1.sql`
 
-### 2. 前端服务层 (UTS)
-- `services/admin/systemConfigService.uts` (新增)
-- `services/admin/authService.uts` (新增)
-- `services/admin/deliveryService.uts` (新增)
-- `services/admin/maintainService.uts` (新增)
+#### 前端服务层（`services/admin/`）
+- `services/admin/systemConfigService.uts`
+- `services/admin/authService.uts`
+- `services/admin/deliveryService.uts`
+- `services/admin/maintainService.uts`
 
-### 3. UI 页面重构 (去 Mock)
-- **权限类**: `auth/admin.uvue`, `auth/role.uvue`, `auth/permission.uvue`。
-- **物流类**: `delivery/staff.uvue`, `delivery/station.uvue`。
-- **配置类**: `setting/system/config.uvue`, `app/wechat/config.uvue`, `app/routine/config.uvue`, `app/mobile/config.uvue`, `app/pc/config.uvue`。
-- **综合类**: `statistic/index.uvue`, `maintain/sys/info.uvue`。
+### 修改文件
+#### 数据库
+- `docs/sql/30_rpc/admin/rpc_admin_system_config_save_v1.sql`
+
+#### 页面（`pages/`）
+- `pages/mall/admin/setting/auth/admin.uvue`
+- `pages/mall/admin/setting/auth/role.uvue`
+- `pages/mall/admin/setting/auth/permission.uvue`
+- `pages/mall/admin/setting/delivery/staff.uvue`
+- `pages/mall/admin/setting/delivery/station.uvue`
+- `pages/mall/admin/setting/system/config.uvue`
+- `pages/mall/admin/statistic/index.uvue`
+- `pages/mall/admin/maintain/sys/info.uvue`
+- `pages/mall/admin/app/mobile/config.uvue`
+- `pages/mall/admin/app/pc/config.uvue`
+
+### 删除文件
+- 无
 
 ## 兼容性与风险
-- **数据迁移**：启用 RLS 后，需确保管理员用户在 `ak_users` 中的 `role` 字段准确设置为 `admin`，否则将无法调用管理端 RPC。
-- **逻辑依赖**：配送员和提货点管理依赖于 `ml_orders` 等核心表已存在。
+- **权限口径依赖**：本项目角色字段权威为 `public.ak_users.role`。RPC 入口鉴权依赖该字段（至少 `admin` / `analytics`），若数据不一致会导致管理端接口不可用。
+- **RLS 与 RPC 闭环**：Auth/Delivery 等表启用 RLS 后，若绕开 RPC 进行直接表访问会被拒绝；需确保前端全部走 service -> RPC。
+- **配置键名约束**：`ml_system_configs` 使用 `config_key` 唯一约束；变更 key 会造成读取不到旧配置。
+- **配送员/提货点数据影响**：提货点对 `anon/authenticated` 开放 `SELECT`（受 `status=1` 限制），属于预期的消费者端只读能力。
 
 ## 回滚方案
-1. 数据库：依次 DROP 刚才创建的 20 余个 RPC 函数及 5 张核心业务表。
-2. 代码：通过 `git checkout` 恢复重构的 10 余个页面文件及 Service 目录。
+- **数据库回滚**：
+  1. 依次 `DROP FUNCTION IF EXISTS ...` 移除本次新增 RPC（按 `docs/sql/30_rpc/{admin,auth,delivery}/` 列表）。
+  2. `ALTER TABLE ... DISABLE ROW LEVEL SECURITY` 或移除新增 policy（对应 `docs/sql/20_rls/`）。
+  3. `DROP TABLE IF EXISTS` 移除新增表（谨慎，需确认无业务数据依赖）。
+- **代码回滚**：
+  - `git revert 5d00e3d`（推荐）或 `git checkout <old_commit> -- <paths>` 恢复页面与 service 变更。
 
 ## 验证方式
-1. **统计验证**：进入“数据概览”，确认销售额、用户数等指标非 0 且与数据库一致。
-2. **配置验证**：在“系统设置”修改网站名称并提交，刷新页面确认数据持久化。
-3. **权限验证**：在“角色管理”添加新身份，确认能在“管理员管理”中进行分配。
-4. **物流验证**：添加配送员后，确认列表分页展示正确且支持实时状态切换。
+1. **系统配置**：进入“系统设置”修改任意字段（如网站名称）-> 保存 -> 刷新确认持久化。
+2. **权限管理**：
+   - 角色管理：新增角色 -> 列表可见；
+   - 菜单权限：新增权限项 -> 列表可见；
+   - 管理员列表：能拉取 `rpc_admin_get_admin_list` 并显示角色标签。
+3. **物流设置**：新增配送员/提货点 -> 列表可见；切换启用/显示状态后刷新保持一致。
+4. **统计概览**：进入数据概览页，确认 RPC 返回聚合指标且页面可渲染。
 
-## 关联规范
-- 遵循 `AGENT_PROJECT_SPEC.md` 规范。
-- 对齐项目统一的角色鉴权与 RPC 分层口径。
+## 关联文档
+- `docs/project_spec/AGENT_PROJECT_SPEC.md`（操作文档规范与 SQL 入库规范）
+
+> 注意：规范要求对照 `docs/sql/11_roles_and_permissions_strategy.md`，但仓库当前未找到该文件。此处已按规范第 5/7 节口径执行（角色字段 `ak_users.role`、RLS 默认收口、全局访问走 SECURITY DEFINER RPC）。建议后续补齐该策略文档或确认其真实路径，并在此处更新引用。
+
+---
+
+## SQL 安全评审报告（逐文件）
+> 评审结论枚举：Reject / High / OK。评审标准：AGENT_PROJECT_SPEC.md 第 7 节。
+
+### Schema
+#### SQL 安全评审报告
+- **对象**：`docs/sql/10_schema/admin/ml_system_configs_v1.sql`
+- **目标**：提供统一 KV 配置表用于管理端持久化系统/接口配置。
+- **结论**：OK
+- **涉及对象**：表 `ml_system_configs`（DDL）；无 grants。
+- **RLS**：由对应 RLS 文件启用。
+- **风险点**：低（仅 DDL）。
+- **整改建议**：无。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/10_schema/user/ak_auth_system_v1.sql`
+- **目标**：建立 RBAC（角色/权限/关联）基础表。
+- **结论**：OK
+- **涉及对象**：`ak_roles`, `ak_permissions`, `ak_admin_roles`, `ak_role_permissions`。
+- **风险点**：低（仅 DDL）；注意外键引用 `ak_users`。
+- **整改建议**：可选：为 `ak_roles.updated_at` 增加触发器自动更新（非必须）。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/10_schema/delivery/ak_delivery_system_v1.sql`
+- **目标**：新增配送员与提货点基础表。
+- **结论**：OK
+- **涉及对象**：`ml_delivery_staff`, `ml_delivery_stations`。
+- **风险点**：低（仅 DDL）。
+- **整改建议**：可选：对 phone 增加格式校验（应用层）。
+- **准入建议**：允许进入 `docs/sql/`。
+
+### RLS
+#### SQL 安全评审报告
+- **对象**：`docs/sql/20_rls/admin/ml_system_configs_rls_v1.sql`
+- **目标**：启用系统配置表 RLS，限制直接表访问。
+- **结论**：OK
+- **RLS**：启用；策略以 RPC 为主。
+- **风险点**：低。
+- **整改建议**：如需管理员直连查询，可增加更严格 policy（建议仍走 RPC）。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/20_rls/auth/ak_auth_rls_v1.sql`
+- **目标**：启用 RBAC 表 RLS，默认不开放直接访问。
+- **结论**：OK
+- **风险点**：低；默认闭网符合规范。
+- **整改建议**：无。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/20_rls/delivery/ak_delivery_rls_v1.sql`
+- **目标**：启用物流表 RLS；提货点开放消费者端只读（`status=1`）。
+- **结论**：OK
+- **风险点**：中（对 `anon/authenticated` 开放 select）；但 `USING (status=1)` 有约束，符合业务需求。
+- **整改建议**：若需进一步限制字段暴露，可改走 RPC 只返回必要字段。
+- **准入建议**：允许进入 `docs/sql/`。
+
+### RPC
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/admin/rpc_admin_system_config_save_v1.sql`
+- **目标**：保存系统配置（upsert）。
+- **结论**：OK
+- **SECURITY DEFINER**：是；`search_path` 固定：是；入口鉴权：是（`role IN ('admin','analytics')`）。
+- **风险点**：低。
+- **整改建议**：可选：对 `p_key` 增加白名单约束（按业务需要）。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/admin/rpc_admin_system_config_get_v1.sql`
+- **目标**：读取系统配置。
+- **结论**：OK
+- **SECURITY DEFINER**：是；`search_path` 固定：是；入口鉴权：是。
+- **风险点**：低。
+- **整改建议**：无。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/admin/rpc_admin_get_overall_stats_v1.sql`
+- **目标**：返回聚合统计指标（概览页）。
+- **结论**：OK
+- **风险点**：低（聚合返回）。
+- **整改建议**：确保有合理的索引与时间过滤（如后续扩展）。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/admin/rpc_admin_get_system_info_v1.sql`
+- **目标**：返回系统信息（用于维护页）。
+- **结论**：OK
+- **风险点**：中（可能暴露服务器信息）；需确保返回字段不包含密钥。
+- **整改建议**：后续如需增加字段，必须最小化并脱敏。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/auth/rpc_admin_get_admin_list_v1.sql`
+- **目标**：分页获取管理员列表（关联角色名）。
+- **结论**：OK
+- **风险点**：中（涉及用户表字段）；当前仅返回必要字段，未返回敏感信息。
+- **整改建议**：如扩展字段，避免返回手机号/财务信息等。
+- **准入建议**：允许进入 `docs/sql/`。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/auth/rpc_admin_get_role_list_v1.sql`
+- **目标**：分页获取角色列表。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/auth/rpc_admin_save_role_v1.sql`
+- **目标**：新增/更新角色。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/auth/rpc_admin_delete_role_v1.sql`
+- **目标**：删除角色。
+- **结论**：OK
+- **风险点**：中（物理删除）；需注意被引用时的级联行为。
+- **整改建议**：如需审计/恢复，考虑改为软删除。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/auth/rpc_admin_get_permission_list_v1.sql`
+- **目标**：获取全量权限/菜单列表。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/auth/rpc_admin_save_permission_v1.sql`
+- **目标**：新增/更新权限/菜单。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/auth/rpc_admin_delete_permission_v1.sql`
+- **目标**：删除权限/菜单。
+- **结论**：OK
+- **风险点**：中（物理删除 + 级联）。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/delivery/rpc_admin_get_delivery_staff_list_v1.sql`
+- **目标**：分页获取配送员列表。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/delivery/rpc_admin_save_delivery_staff_v1.sql`
+- **目标**：新增/更新配送员。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/delivery/rpc_admin_delete_delivery_staff_v1.sql`
+- **目标**：删除配送员。
+- **结论**：OK
+- **风险点**：中（物理删除）。
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/delivery/rpc_admin_get_delivery_station_list_v1.sql`
+- **目标**：分页获取提货点列表。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/delivery/rpc_admin_save_delivery_station_v1.sql`
+- **目标**：新增/更新提货点。
+- **结论**：OK
+
+#### SQL 安全评审报告
+- **对象**：`docs/sql/30_rpc/delivery/rpc_admin_delete_delivery_station_v1.sql`
+- **目标**：删除提货点。
+- **结论**：OK
+- **风险点**：中（物理删除）。
+
+## 准入结论
+- 本次新增/修改 SQL 未出现硬阻断项（裸放权、破坏性操作、无鉴权 SECURITY DEFINER），评审结论整体为 **OK**，允许进入 `docs/sql/` 作为权威口径。

docs/ops/2026-02-25__admin__soft-delete-standard-refactor.md

@@ -0,0 +1,90 @@
+# 软删除标准化改造（RPC + RLS）操作文档
+
+## 摘要
+本次对管理端涉及的“删除”相关数据库逻辑进行标准化改造：
+- 将各模块 RPC 删除行为由物理删除统一切换为软删除（`UPDATE ... SET deleted_at = now(), deleted_by = ...`）；
+- 对存在依赖关系的对象补齐级联软删除（如：删除客服话术分类时同步软删其下话术等）；
+- 对各模块 RLS 策略补齐 `deleted_at IS NULL` 过滤条件，使业务侧默认不可见已软删数据；
+- 提供执行顺序建议，确保先补齐字段/索引，再应用 RLS/RPC 逻辑。
+
+## 动机
+- 统一删除语义，避免误操作导致数据不可恢复。
+- 支持审计追溯（删除时间、删除人）。
+- 通过 RLS 形成“默认过滤”，降低前端/服务层遗漏过滤导致的数据暴露风险。
+
+## 影响范围
+- **数据库**：涉及多个域（admin/cms/decoration/delivery/distribution/finance/kefu/user/auth）的 RLS 与 RPC 文件；新增/补齐软删除字段与索引（迁移脚本）。
+- **管理端功能**：所有调用相关 `rpc_admin_*_delete*` 的管理页面，其删除行为从“物理删除”变更为“逻辑删除”。
+- **数据可见性**：RLS 在 SELECT 场景默认排除 `deleted_at IS NOT NULL` 的记录，前端列表/查询将不再返回已软删数据。
+
+## 变更清单
+> 本次变更以 `docs/sql/00_meta/12_soft_delete_standard.md` 作为软删除标准口径。
+
+### 新增文件
+- `docs/sql/00_meta/11_roles_and_permissions_strategy.md`
+- `docs/sql/00_meta/12_soft_delete_standard.md`
+- `docs/sql/10_schema/99_soft_delete_migration_v1.sql`
+
+### 修改文件
+#### RLS（补齐 `deleted_at IS NULL`）
+- `docs/sql/20_rls/admin/ml_system_configs_rls_v1.sql`
+- `docs/sql/20_rls/cms/ml_cms_rls_v1.sql`
+- `docs/sql/20_rls/decoration/ml_decoration_rls_v1.sql`
+- `docs/sql/20_rls/delivery/ak_delivery_rls_v1.sql`
+- `docs/sql/20_rls/distribution/ml_distribution_rls_v1.sql`
+- `docs/sql/20_rls/finance/ml_extract_rls_v1.sql`
+- `docs/sql/20_rls/finance/ml_invoices_rls_v1.sql`
+- `docs/sql/20_rls/finance/ml_user_bill_rls_v1.sql`
+- `docs/sql/20_rls/finance/ml_user_recharge_rls_v1.sql`
+
+#### RPC（删除改为软删除 + deleted_by 审计 + 必要时级联）
+- `docs/sql/30_rpc/auth/rpc_admin_delete_permission_v1.sql`
+- `docs/sql/30_rpc/auth/rpc_admin_delete_role_v1.sql`
+- `docs/sql/30_rpc/cms/rpc_admin_article_category_delete_v1.sql`
+- `docs/sql/30_rpc/cms/rpc_admin_article_delete_v1.sql`
+- `docs/sql/30_rpc/decoration/rpc_admin_delete_diy_page_v1.sql`
+- `docs/sql/30_rpc/delivery/rpc_admin_delete_delivery_staff_v1.sql`
+- `docs/sql/30_rpc/delivery/rpc_admin_delete_delivery_station_v1.sql`
+- `docs/sql/30_rpc/distribution/rpc_admin_delete_agent_v1.sql`
+- `docs/sql/30_rpc/distribution/rpc_admin_delete_division_v1.sql`
+- `docs/sql/30_rpc/kefu/rpc_admin_kefu_account_delete_v1.sql`
+- `docs/sql/30_rpc/kefu/rpc_admin_kefu_auto_reply_delete_v1.sql`
+- `docs/sql/30_rpc/kefu/rpc_admin_kefu_word_category_delete_v1.sql`
+- `docs/sql/30_rpc/kefu/rpc_admin_kefu_word_delete_v1.sql`
+- `docs/sql/30_rpc/product/rpc_admin_category_delete_v1.sql`
+- `docs/sql/30_rpc/user/rpc_admin_user_group_delete_v1.sql`
+- `docs/sql/30_rpc/user/rpc_admin_user_label_delete_v1.sql`
+- `docs/sql/30_rpc/user/rpc_admin_user_level_delete_v1.sql`
+
+#### 前端（与删除相关页面适配/受影响）
+- `pages/mall/admin/setting/delivery/station.uvue`
+- `pages/mall/admin/setting/interface/storage.uvue`
+
+### 删除文件
+- 无
+
+## 兼容性与风险
+- **数据不可再“物理删除”释放唯一约束**：软删除后记录仍在表中，若存在唯一索引且未做“partial unique（仅对未删除记录生效）”，可能导致“删除后无法新建同名/同 key”问题，需要按业务决定是否改索引策略。
+- **RLS 策略一致性要求更高**：补齐 `deleted_at IS NULL` 后，任何期望访问回收站数据的场景都需要新增专用策略或通过管理端特权 RPC 实现。
+- **级联链路需覆盖完整**：部分对象存在多级依赖（分类 -> 子项 -> 关联），若漏掉级联，会出现“父对象不可见但子对象仍可见/仍占用数据”的不一致。
+
+## 回滚方案
+- **仅回滚删除语义（不建议长期保持）**：
+  - 将相关 `rpc_admin_*_delete*` 还原为物理删除（`DELETE FROM ...`）并移除 `deleted_at/deleted_by` 写入逻辑。
+- **回滚 RLS 过滤**：
+  - 在对应 `docs/sql/20_rls/**` 中移除 `AND deleted_at IS NULL`（或恢复到改造前版本）。
+- **回滚 schema 迁移**：
+  - 不建议回滚 `deleted_*` 字段（会丢失审计数据）；如必须回滚，应先评估依赖与历史数据。
+
+## 验证方式
+- **字段与索引**：执行 `docs/sql/10_schema/99_soft_delete_migration_v1.sql` 后，确认涉及表存在 `deleted_at/deleted_by` 字段，以及 `idx_<table>_soft_delete` 索引。
+- **RLS 过滤生效**：对任一涉及表执行查询（按当前角色权限），确认已软删的数据默认不返回。
+- **RPC 删除行为**：调用任一删除 RPC 后：
+  - 记录未被物理删除；
+  - `deleted_at` 被写入当前时间；
+  - `deleted_by` 被写入执行删除的管理员用户 ID；
+  - 对需要级联的对象，子表记录同步被标记软删。
+
+## 关联文档
+- `docs/project_spec/AGENT_PROJECT_SPEC.md`
+- `docs/sql/00_meta/12_soft_delete_standard.md`