# rmdc-jenkins-branch-dac 详细设计说明书（DDS）

**模块名称**: rmdc-jenkins-branch-dac  
**版本**: v1.0  
**编制日期**: 2026-01-06  

---

## 1. 模块概述

### 1.1 模块定位

rmdc-jenkins-branch-dac 是 RMDC 平台的**Jenkins分支级权限控制与构建管理模块**，负责：

1. **分支级权限控制(DAC)**：基于自主访问控制模型，实现Organization→Repository→Branch三级资源权限管理
2. **Jenkins集成**：封装Jenkins REST API，提供统一的构建触发、状态查询、日志获取等能力
3. **构建产物管理**：管理Docker镜像的下载、压缩、上传(DCU)流程，集成MinIO对象存储
4. **构建状态追踪**：实时追踪构建进度，提供状态同步和超时检测机制

### 1.2 核心用户角色

| 角色 | 权限说明 |
|------|----------|
| **SuperAdmin** | 全量访问，可管理所有Organization/Repository/Branch |
| **Admin** | 拥有分配的权限，可将自有权限分配给Normal/Third用户 |
| **Normal** | 拥有分配的权限，只能查看和触发被授权的分支构建 |
| **Third** | 第三方人员，权限最受限，仅能查看被授权内容 |

### 1.3 技术栈

- **后端**: Go + Gin + GORM
- **数据库**: PostgreSQL (主库) + SQLite (DCU模块独立库)
- **外部服务**: Jenkins REST API, MinIO对象存储

---

## 2. 系统架构

### 2.1 模块架构图

```mermaid
graph TB
    subgraph "rmdc-core 网关层"
        Router[Gin Router]
        AuthMW[AuthMiddleware]
        PermMW[PermissionMiddleware]
    end
    
    subgraph "rmdc-jenkins-branch-dac 模块"
        subgraph "Handler层"
            OrgH[OrgHandler]
            RepoH[RepoHandler]
            BranchH[BranchHandler]
            BuildH[BuildHandler]
            DCUH[DCUHandler]
        end
        
        subgraph "Service层"
            JenkinsS[JenkinsService]
            BuildS[BuildService]
            SyncS[SyncService]
            DCUS[DCUService]
            TrackerS[BuildTracker]
        end
        
        subgraph "DAO层"
            OrgDAO[OrganizationDAO]
            RepoDAO[RepositoryDAO]
            BranchDAO[BranchDAO]
            BuildDAO[BuildDAO]
        end
        
        JenkinsC[JenkinsClient]
        MinioC[MinioClient]
    end
    
    subgraph "外部服务"
        Jenkins[(Jenkins Server)]
        MinIO[(MinIO Storage)]
    end
    
    Router --> AuthMW --> PermMW
    PermMW --> OrgH & RepoH & BranchH & BuildH & DCUH
    
    BuildH --> BuildS --> JenkinsS --> JenkinsC --> Jenkins
    DCUH --> DCUS --> MinioC --> MinIO
    
    JenkinsS --> OrgDAO & RepoDAO & BranchDAO & BuildDAO
```

### 2.2 Jenkins层级结构

```
Organization Folder（组织）
  └── Repository/Project（仓库）
        └── Branch（分支）
              └── Build（构建）
```

**URL路径模式**：
```
/job/{ORG}                               # 组织
/job/{ORG}/job/{REPO}                    # 仓库
/job/{ORG}/job/{REPO}/job/{BRANCH}       # 分支
/job/{ORG}/job/{REPO}/job/{BRANCH}/{NUM} # 构建
```

---

## 3. 数据模型设计

### 3.1 核心实体

```mermaid
erDiagram
    jenkins_organizations ||--o{ jenkins_repositories : contains
    jenkins_repositories ||--o{ jenkins_branches : contains
    jenkins_branches ||--o{ jenkins_builds : contains
    
    jenkins_organizations {
        int64 id PK
        string name UK
        string display_name
        string url
        datetime last_sync_at
    }
    
    jenkins_repositories {
        int64 id PK
        int64 organization_id FK
        string name
        string url
    }
    
    jenkins_branches {
        int64 id PK
        int64 repository_id FK
        string name
        int last_build_number
        string last_build_result
    }
    
    jenkins_builds {
        int64 id PK
        int64 branch_id FK
        int build_number
        string result
        int64 timestamp
        int64 duration
        int64 estimated_duration
        bool is_building
        string artifact_docker_image
    }
```

---

## 4. API接口规范

> **设计原则**: 使用RESTful风格，优先使用POST + RequestBody，避免PathVariables和RequestParams

### 4.1 组织管理接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/jenkins/organizations/list` | POST | 获取组织列表 |
| `/api/jenkins/organizations/detail` | POST | 获取组织详情 |
| `/api/jenkins/organizations/sync` | POST | 同步Jenkins组织数据 |

### 4.2 仓库管理接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/jenkins/repositories/list` | POST | 获取仓库列表 |
| `/api/jenkins/repositories/detail` | POST | 获取仓库详情 |
| `/api/jenkins/repositories/sync` | POST | 同步仓库数据 |
| `/api/jenkins/repositories/scan` | POST | 触发仓库扫描 |

### 4.3 分支管理接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/jenkins/branches/list` | POST | 获取分支列表 |
| `/api/jenkins/branches/detail` | POST | 获取分支详情 |
| `/api/jenkins/branches/sync` | POST | 同步分支数据 |

### 4.4 构建管理接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/jenkins/builds/list` | POST | 获取构建列表 |
| `/api/jenkins/builds/detail` | POST | 获取构建详情 |
| `/api/jenkins/builds/trigger` | POST | 触发构建 |
| `/api/jenkins/builds/console` | POST | 获取构建日志 |
| `/api/jenkins/builds/sync` | POST | 同步构建数据 |

### 4.5 DCU接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/dcu/start` | POST | 启动DCU任务 |
| `/api/dcu/status` | POST | 查询任务状态 |
| `/api/dcu/list` | POST | 查询任务列表 |

---

## 5. 分支权限(DAC)设计

### 5.1 权限模型

DAC采用**资源-用户-权限**三元组模型，支持三级权限继承：

| 授权层级 | 继承规则 |
|----------|----------|
| Organization级 | 自动继承到该组织下所有Repository和Branch |
| Repository级 | 自动继承到该仓库下所有Branch |
| Branch级 | 最细粒度，不继承 |

### 5.2 权限类型

| 权限 | 说明 |
|------|------|
| `can_view` | 查看权限 |
| `can_build` | 构建权限 |

---

## 6. 构建状态追踪

### 6.1 BuildTracker设计

BuildTracker负责追踪正在进行中的构建，提供超时检测和状态同步：

```mermaid
sequenceDiagram
    participant User as 用户
    participant Handler as BuildHandler
    participant Service as BuildService
    participant Tracker as BuildTracker
    participant Jenkins as Jenkins API
    
    User->>Handler: POST /builds/trigger
    Handler->>Service: TriggerBuild()
    Service->>Jenkins: 触发构建
    Service->>Tracker: TrackBuild(buildId, timeout)
    Service-->>User: 返回构建号
    
    loop 后台超时检测(每10秒)
        Tracker->>Tracker: checkTimeouts()
        alt 超时
            Tracker->>Jenkins: 查询最新状态
            Tracker->>Tracker: 更新数据库
        end
    end
```

---

## 7. DCU(Download-Compress-Upload)流程

### 7.1 状态机

```mermaid
stateDiagram-v2
    [*] --> idle: 创建任务
    idle --> downloading: StartTask()
    downloading --> compressing: Pull成功
    compressing --> uploading: 压缩成功
    uploading --> completed: 上传成功
    
    downloading --> failed: Pull失败
    compressing --> failed: 压缩失败
    uploading --> failed: 上传失败
```

### 7.2 流程说明

1. **Download**: 从Docker Registry拉取镜像
2. **Compress**: 使用gzip压缩镜像tar包
3. **Upload**: 上传到MinIO对象存储

---

## 8. 错误码定义

| 错误码 | 说明 |
|--------|------|
| `JENKINS-001` | Jenkins服务不可用 |
| `JENKINS-002` | Jenkins认证失败 |
| `JENKINS-003` | Jenkins资源不存在 |
| `JENKINS-004` | 构建触发失败 |
| `JENKINS-005` | 构建超时 |
| `DCU-001` | Docker Pull失败 |
| `DCU-002` | 压缩失败 |
| `DCU-003` | MinIO上传失败 |
| `PERM-001` | 无权限访问该资源 |
| `PERM-002` | 无权限执行该操作 |

---

## 9. 相关文档

| 文档 | 内容 |
|------|------|
| [5-RMDC项目权限设计方案.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/2-Jenkins模块/5-RMDC项目权限设计方案.md) | 权限设计 |
| [8-jenkins项目层级.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/2-Jenkins模块/8-jenkins项目层级.md) | Jenkins层级结构 |
| [9-JenkinsBuild-流程图.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/2-Jenkins模块/9-JenkinsBuild-流程图.md) | 构建流程图 |
| [9-rmdc-dcu模块设计方案.md](file:///c:/Users/wddsh/Documents/IdeaProjects/ProjectAGiPrompt/8-CMII-RMDC/2-Jenkins模块/9-rmdc-dcu模块设计方案.md) | DCU模块设计 |