ProjectAGiPrompt/8-CMII-RMDC/2-rmdc-jenkins-dac/5-RMDC项目权限设计方案.md

RMDC 项目权限设计方案

1. 概述

本文档描述RMDC平台统一权限系统的设计方案，涵盖：

• 权限系统架构设计
• 模块依赖关系
• 接口抽象层设计
• 权限校验流程

---

2. 模块依赖关系

2.1 设计原则

• 单向依赖：业务模块不依赖权限模块，权限模块通过接口访问业务数据
• 接口抽象：公共接口定义在 rmdc-common，各模块实现具体接口
• 依赖注入：rmdc-core 负责注入所有依赖

2.2 依赖关系图

graph TB
    subgraph "公共层"
        Common[rmdc-common<br/>公共接口定义]
    end
    
    subgraph "权限层"
        UserAuth[rmdc-user-auth<br/>权限中心<br/>实现PermissionChecker]
    end
    
    subgraph "业务层"
        Jenkins[rmdc-jenkins-branch-dac<br/>实现ResourceProvider]
        Watchdog[rmdc-watchdog-center<br/>实现ResourceProvider]
        Monitor[rmdc-monitor-center<br/>实现ResourceProvider]
        Delivery[rmdc-delivery-update<br/>实现ResourceProvider]
    end
    
    subgraph "核心层"
        Core[rmdc-core<br/>网关 + 依赖注入]
    end
    
    UserAuth --> Common
    Jenkins --> Common
    Watchdog --> Common
    Monitor --> Common
    Delivery --> Common
    
    Core --> UserAuth
    Core --> Jenkins
    Core --> Watchdog
    Core --> Monitor
    Core --> Delivery
    
    style Common fill:#4ecdc4,stroke:#087f5b
    style Core fill:#ffd43b,stroke:#f08c00
    style UserAuth fill:#ff6b6b,stroke:#c92a2a

2.3 依赖关系表

模块	依赖	实现接口
rmdc-common	无	定义接口
rmdc-user-auth	rmdc-common	PermissionChecker
rmdc-jenkins-branch-dac	rmdc-common	ResourceProvider
rmdc-watchdog-center	rmdc-common	ResourceProvider
rmdc-core	所有上述模块	-

---

3. 权限接口抽象层

3.1 PermissionChecker 接口

// 位置: rmdc-common/pkg/permission/interface.go
package permission

import "context"

// PermissionChecker 统一权限检查接口
type PermissionChecker interface {
    // CheckPermission 检查用户对资源的权限
    // @param userID 用户ID
    // @param resourceType 资源类型: "jenkins_branch", "watchdog_project", "watchdog_host"
    // @param resource 资源路径: "org/repo/branch" 或 "project_id"
    // @param action 操作类型: "view", "build", "exec", "manage"
    CheckPermission(ctx context.Context, userID int64, resourceType, resource, action string) (bool, error)
    
    // IsSuperAdmin 检查是否为超级管理员
    IsSuperAdmin(ctx context.Context, userID int64) (bool, error)
    
    // GetUserRole 获取用户角色
    GetUserRole(ctx context.Context, userID int64) (string, error)
}

3.2 ResourceProvider 接口

// 位置: rmdc-common/pkg/resource/interface.go
package resource

import "context"

// ResourceProvider 资源提供者接口（各业务模块实现）
type ResourceProvider interface {
    // GetResourceType 返回资源类型标识
    GetResourceType() string
    
    // ListResources 列出所有资源（用于权限分配UI）
    ListResources(ctx context.Context) ([]Resource, error)
    
    // ListResourcesForUser 列出用户有权限的资源
    ListResourcesForUser(ctx context.Context, userID int64) ([]Resource, error)
    
    // ValidateResource 验证资源是否存在
    ValidateResource(ctx context.Context, resourcePath string) (bool, error)
}

// Resource 资源结构
type Resource struct {
    Type     string     `json:"type"`     // 资源类型
    Name     string     `json:"name"`     // 资源名称
    Path     string     `json:"path"`     // 完整路径
    Children []Resource `json:"children,omitempty"`
}

---

4. 统一权限校验流程

4.1 校验流程图

flowchart TB
    subgraph "请求入口"
        Request[API请求<br/>携带JWT Token]
    end
    
    subgraph "rmdc-core 网关层"
        Router[Gin Router]
        AuthMW[AuthMiddleware<br/>1. JWT解析<br/>2. 提取user_id/role]
        PermMW[PermissionMiddleware<br/>1. SuperAdmin跳过<br/>2. 权限检查]
    end
    
    subgraph "rmdc-user-auth 权限中心"
        PermService[PermissionService]
        
        subgraph "模块权限检查器"
            JenkinsChecker[JenkinsPermissionChecker<br/>Jenkins分支权限]
            WatchdogChecker[WatchdogPermissionChecker<br/>项目/主机权限]
        end
        
        subgraph "缓存层"
            L1[L1: 内存缓存<br/>sync.Map]
            L2[L2: 数据库缓存<br/>user_permission_trees]
        end
    end
    
    subgraph "业务模块"
        JenkinsHandler[JenkinsHandler<br/>无权限检查逻辑]
        WatchdogHandler[WatchdogHandler<br/>无权限检查逻辑]
    end
    
    subgraph "数据库"
        PermDB[(user_permissions)]
    end

    Request --> Router --> AuthMW --> PermMW
    PermMW -->|SuperAdmin| JenkinsHandler
    PermMW -->|SuperAdmin| WatchdogHandler
    PermMW -->|其他角色| PermService
    
    PermService --> L1
    L1 -->|未命中| L2
    L2 -->|未命中| PermDB
    
    PermService -->|有权限| JenkinsHandler
    PermService -->|有权限| WatchdogHandler
    PermService -->|无权限| Request
    
    style PermMW fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
    style PermService fill:#ffd43b,stroke:#f08c00,stroke-width:2px

4.2 权限检查算法

flowchart TD
    Start[开始权限检查] --> GetRole[获取用户角色]
    GetRole --> IsSuperAdmin{superadmin?}
    
    IsSuperAdmin -->|是| Allow[✅ 允许访问]
    IsSuperAdmin -->|否| CheckL1[检查L1内存缓存]
    
    CheckL1 --> L1Hit{缓存命中?}
    L1Hit -->|是| CheckPerm[检查权限树]
    L1Hit -->|否| CheckL2[检查L2数据库缓存]
    
    CheckL2 --> L2Hit{缓存命中?}
    L2Hit -->|是| UpdateL1[更新L1缓存]
    L2Hit -->|否| BuildTree[从权限表构建权限树]
    
    UpdateL1 --> CheckPerm
    BuildTree --> SaveL2[保存到L2缓存]
    SaveL2 --> UpdateL1
    
    CheckPerm --> HasPerm{有权限?}
    HasPerm -->|是| Allow
    HasPerm -->|否| Deny[❌ 拒绝访问]

---

5. 角色权限模型

5.1 角色定义

角色	常量	说明
超级管理员	superadmin	拥有全部权限，可管理所有用户和资源
管理员	admin	拥有分配的权限，可将自有权限分配给normal/third
普通人员	normal	拥有分配的权限，无分配能力
三方人员	third	拥有分配的权限，无分配能力，权限受限最严格

5.2 模块级权限

Jenkins分支权限

资源类型	权限类型	说明
Organization	can_view, can_build	组织级权限，自动继承到子仓库/分支
Repository	can_view, can_build	仓库级权限，自动继承到子分支
Branch	can_view, can_build	分支级权限，最细粒度

Watchdog项目权限

资源类型	权限类型	说明
Project	can_view, can_manage	项目级权限
Host	can_view, can_exec	主机操作权限
Namespace	can_view, can_deploy	K8s命名空间权限

5.3 权限分配规则

flowchart LR
    SuperAdmin[SuperAdmin] -->|可分配| Admin
    SuperAdmin -->|可分配| Normal
    SuperAdmin -->|可分配| Third
    
    Admin -->|可分配自有权限| Normal
    Admin -->|可分配自有权限| Third
    
    style SuperAdmin fill:#ff6b6b
    style Admin fill:#ffd43b
    style Normal fill:#4ecdc4
    style Third fill:#a9e34b

---

6. 数据库设计

6.1 统一权限表

CREATE TABLE user_permissions (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL,
    resource_type VARCHAR(50) NOT NULL,   -- 'jenkins_branch', 'watchdog_project'
    resource_path VARCHAR(255) NOT NULL,  -- 'org/repo/branch' or 'project_id'
    permission_level VARCHAR(20),          -- 'org', 'repo', 'branch', 'project'
    can_view BOOLEAN DEFAULT FALSE,
    can_build BOOLEAN DEFAULT FALSE,       -- Jenkins特有
    can_exec BOOLEAN DEFAULT FALSE,        -- Watchdog特有
    can_manage BOOLEAN DEFAULT FALSE,
    granted_by BIGINT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    
    UNIQUE(user_id, resource_type, resource_path),
    INDEX idx_user_resource (user_id, resource_type)
);

6.2 权限树缓存表

CREATE TABLE user_permission_trees (
    user_id BIGINT PRIMARY KEY,
    tree JSON NOT NULL,                    -- 完整权限树JSON
    version BIGINT DEFAULT 0,              -- 版本号
    updated_at TIMESTAMP DEFAULT NOW()
);

---

7. API设计

7.1 用户权限查询API

接口	方法	说明
/api/permissions/my-tree/organizations	GET	获取当前用户的组织列表
/api/permissions/my-tree/repositories	POST	获取当前用户的仓库列表
/api/permissions/my-tree/branches	POST	获取当前用户的分支列表
/api/permissions/my-tree/full	GET	获取完整权限树

7.2 权限管理API (Admin)

接口	方法	说明
/api/permissions/tree	GET	获取系统权限树
/api/permissions/:userId	GET	获取用户权限详情
/api/permissions/assign	POST	分配权限
/api/permissions/copy	POST	复制权限

---

8. 文档版本

版本	日期	修改内容
v1.0	2025-12-10	初始版本