junhong_cmp_fiber/docs/004-rbac-data-permission/架构说明.md

架构说明：RBAC 表结构与 GORM 数据权限过滤

概述

本功能实现了完整的 RBAC（基于角色的访问控制）权限系统，以及基于 owner_id + shop_id 的自动数据权限过滤机制。

架构分层

本系统遵循 Handler → Service → Store → Model 四层架构：

┌─────────────────────────────────────────────────────────┐
│                   Handler Layer                          │
│  (HTTP 请求/响应处理，参数验证，调用 Service)            │
├─────────────────────────────────────────────────────────┤
│                   Service Layer                          │
│  (业务逻辑，事务管理，缓存清理，跨模块调用)              │
├─────────────────────────────────────────────────────────┤
│                   Store Layer                            │
│  (数据访问，GORM 操作，数据权限过滤 Scopes)             │
├─────────────────────────────────────────────────────────┤
│                   Model Layer                            │
│  (数据模型定义，DTO 结构)                                │
└─────────────────────────────────────────────────────────┘

核心组件

1. 数据模型

RBAC 表结构

表名	说明	关键字段
tb_account	账号表	parent_id（层级关系）, shop_id（店铺隔离）, user_type
tb_role	角色表	role_type（角色类型）
tb_permission	权限表	perm_code（唯一权限码）, parent_id（树形结构）
tb_account_role	账号-角色关联表	account_id, role_id
tb_role_permission	角色-权限关联表	role_id, perm_id

设计原则

• 无外键约束：表之间通过 ID 字段关联，不使用数据库外键约束
• 软删除支持：所有表都有 deleted_at 字段，支持 GORM 软删除
• 唯一约束带条件：用户名、手机号、权限码的唯一约束仅在未删除记录中生效

2. 数据权限过滤

核心流程

用户请求 → 认证中间件 → 设置用户上下文 → 业务查询 → DataPermissionScope → 返回数据

DataPermissionScope 工作原理

1. 从 Context 提取用户 ID、用户类型、店铺 ID
2. 检查是否为 root 用户（跳过过滤）
3. 递归查询当前用户的所有下级 ID（含自己）
4. 应用 WHERE 条件：owner_id IN (...) AND shop_id = ?

递归查询优化

使用 PostgreSQL 的 WITH RECURSIVE 进行递归查询：

WITH RECURSIVE subordinates AS (
    SELECT id FROM tb_account WHERE id = ?
    UNION ALL
    SELECT a.id FROM tb_account a
    INNER JOIN subordinates s ON a.parent_id = s.id
)
SELECT id FROM subordinates

3. Redis 缓存策略

缓存设计

• 缓存键格式：account:subordinates:{account_id}
• 过期时间：30 分钟
• 缓存内容：用户及其所有下级的 ID 列表

缓存失效策略

• 创建子账号时：清除父账号及所有上级的缓存
• 删除账号时：清除父账号及所有上级的缓存
• 缓存自动过期后：下次查询重新生成

4. Context 上下文传递

上下文键

const (
    UserIDKey   = "user_id"
    UserTypeKey = "user_type"
    ShopIDKey   = "shop_id"
)

辅助函数

• SetUserContext(ctx, userID, userType, shopID) - 设置用户上下文
• GetUserIDFromContext(ctx) - 获取用户 ID
• GetShopIDFromContext(ctx) - 获取店铺 ID
• IsRootUser(ctx) - 检查是否为 root 用户

路由模块化

目录结构

internal/routes/
├── routes.go      # 主入口，Services 容器
├── account.go     # 账号路由
├── role.go        # 角色路由
├── permission.go  # 权限路由
├── health.go      # 健康检查路由
└── task.go        # 任务路由

Services 容器

type Services struct {
    AccountHandler    *handler.AccountHandler
    RoleHandler       *handler.RoleHandler
    PermissionHandler *handler.PermissionHandler
}

主函数重构

编排模式

main 函数仅做编排，不包含具体实现：

func main() {
    cfg := initConfig()           // 加载配置
    logger := initLogger(cfg)     // 初始化日志
    db := initDatabase(cfg)       // 初始化数据库
    redis := initRedis(cfg)       // 初始化 Redis
    queue := initQueue(redis)     // 初始化队列
    services := initServices(db, redis) // 初始化服务
    app := createFiberApp(cfg)    // 创建应用
    initMiddleware(app, cfg)      // 注册中间件
    initRoutes(app, services)     // 注册路由
    startServer(app, cfg)         // 启动服务器
}

初始化函数职责

函数	职责
initConfig	加载配置文件
initLogger	初始化 Zap 日志
initDatabase	连接 PostgreSQL
initRedis	连接 Redis
initQueue	初始化 Asynq 客户端
initServices	创建所有 Service 实例
initMiddleware	注册全局中间件
initRoutes	注册所有路由
startServer	启动 HTTP 服务器

性能考量

关键性能指标

• API 响应时间 P95 < 200ms
• 递归查询下级 ID P95 < 50ms（含 Redis 缓存）
• 数据库查询 P95 < 50ms

优化措施

1. Redis 缓存：缓存递归查询结果，避免重复数据库查询
2. 索引优化：关键字段都建立索引（parent_id、shop_id、owner_id）
3. 批量操作：账号-角色、角色-权限支持批量创建
4. 连接池：数据库和 Redis 配置合理的连接池

安全考量

数据隔离

• 店铺隔离：通过 shop_id 实现多租户数据隔离
• 层级权限：用户只能访问自己及下级创建的数据
• root 用户：跳过数据权限过滤，可访问所有数据

密码安全

• 密码字段使用 json:"-" 标签，不返回给客户端
• 密码使用 bcrypt 加密存储

错误处理

• 查询下级 ID 失败时，降级为只返回自己的数据
• 所有错误通过统一错误处理机制返回

扩展指南

添加新业务表的数据权限

1. 在业务表中添加 owner_id 和 shop_id 字段
2. 在 Store 方法中应用 DataPermissionScope
3. 确保创建记录时设置正确的 owner_id 和 shop_id

示例：

func (s *OrderStore) List(ctx context.Context) ([]*model.Order, error) {
    var orders []*model.Order
    err := s.db.WithContext(ctx).
        Scopes(postgres.DataPermissionScope(ctx, s.accountStore)).
        Find(&orders).Error
    return orders, err
}

添加新的 RBAC 实体

1. 创建 Model 和 DTO
2. 创建 Store（CRUD 方法）
3. 创建 Service（业务逻辑）
4. 创建 Handler（HTTP 接口）
5. 添加路由文件
6. 更新 Services 容器

测试策略

单元测试

• 递归查询测试
• 缓存读写测试
• 数据权限 Scope 测试
• 软删除测试

集成测试

• 数据库迁移测试
• 层级数据权限过滤测试
• 跨店铺数据隔离测试
• API 端点测试

技术决策记录

为什么不使用外键？

1. 灵活性：业务逻辑完全在代码中控制
2. 性能：无外键约束检查开销
3. 分布式友好：便于未来拆分微服务

为什么使用 WITH RECURSIVE？

1. 原生支持：PostgreSQL 内置支持
2. 性能优异：单次查询获取所有下级
3. 深度无限：支持任意层级的递归

为什么缓存过期时间是 30 分钟？

1. 平衡性：在实时性和性能之间取得平衡
2. 业务特点：账号层级变化不频繁
3. 可配置：可根据业务需求调整