# 权限、物流及系统基础设施全量集成报告

## 摘要
本次对 Admin 侧进行了基础设施补齐与核心管理模块重构，完成以下闭环：
- 新增系统统一 KV 配置表 `ml_system_configs`，并提供管理端 RPC 读写；
- 建立 RBAC 权限体系（角色/权限/关联表），并以管理端 RPC 提供 CRUD；
- 新增物流资源表（配送员、提货点），并以管理端 RPC 提供 CRUD；
- 将 Admin 侧相关页面从 Mock/静态数据切换为真实 RPC 数据流。

## 动机
商城核心业务（商品、订单等）已基本闭环，但系统底座模块（权限控制、系统开关、物流资源）仍长期处于 Mock/静态模拟阶段，无法满足生产环境可审计、可配置、可授权的要求，因此需要补齐数据库资产（Schema/RLS/RPC）与前端服务层。

## 影响范围
- **数据库**：新增表、启用 RLS、增加 `SECURITY DEFINER` RPC，影响 admin/analytics 权限闭环。
- **管理端页面**：权限管理（管理员/角色/菜单权限）、物流设置（配送员/提货点）、系统配置、统计概览、系统信息页面。
- **服务层**：新增 `services/admin/*Service.uts`，统一数据访问出口（页面不再直连底层 client）。

## 变更清单
> 以提交 `5d00e3d` 为准（`feat(admin): complete integration of auth, delivery, and system infrastructure modules`）。

### 新增文件
#### 数据库（权威入库：`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`

#### 前端服务层（`services/admin/`）
- `services/admin/systemConfigService.uts`
- `services/admin/authService.uts`
- `services/admin/deliveryService.uts`
- `services/admin/maintainService.uts`

### 修改文件
#### 数据库
- `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`

### 删除文件
- 无

## 兼容性与风险
- **权限口径依赖**：本项目角色字段权威为 `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 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. **系统配置**：进入“系统设置”修改任意字段（如网站名称）-> 保存 -> 刷新确认持久化。
2. **权限管理**：
   - 角色管理：新增角色 -> 列表可见；
   - 菜单权限：新增权限项 -> 列表可见；
   - 管理员列表：能拉取 `rpc_admin_get_admin_list` 并显示角色标签。
3. **物流设置**：新增配送员/提货点 -> 列表可见；切换启用/显示状态后刷新保持一致。
4. **统计概览**：进入数据概览页，确认 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/` 作为权威口径。