# RMDC 项目权限设计方案

## 1. 概述

本文档描述RMDC平台统一权限系统的设计方案，涵盖：
- 权限系统架构设计
- 模块依赖关系
- 接口抽象层设计
- 权限校验流程

---

## 2. 模块依赖关系

### 2.1 设计原则

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

### 2.2 依赖关系图

```mermaid
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 接口

```go
// 位置: 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 接口

```go
// 位置: 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 校验流程图

```mermaid
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 权限检查算法

```mermaid
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 权限分配规则

```mermaid
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 统一权限表

```sql
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 权限树缓存表

```sql
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 | 初始版本 |