# Jenkins Build Flow - 构建流程图

此文档描述了完整的Jenkins构建触发、状态轮询、数据库持久化以及前端状态展示流程。

## 构建任务完整流程

```mermaid
sequenceDiagram
    participant FE as Frontend
    participant BE as Backend (Handler)
    participant SVC as Service
    participant DB as Database
    participant JK as Jenkins
    participant BT as BuildTracker
    
    Note over FE,BT: 1. 触发构建
    FE->>BE: POST /build/trigger
    BE->>SVC: TriggerBuild()
    SVC->>JK: TriggerBuildInOrg()
    JK-->>SVC: Success
    SVC->>JK: GetBranchBuildsInOrg() (get build number)
    SVC->>DB: SaveBuild (is_building=true)
    SVC->>BT: TrackBuild(estimatedDuration + 20s)
    SVC-->>FE: Build Number
    
    Note over FE,BT: 2. 跳转构建详情页
    FE->>FE: 显示JenkinsBuildStatusCard
    FE->>BE: GET /builds/details
    BE->>SVC: GetBuildDetails()
    SVC->>DB: GetBuildByNumber()
    SVC->>JK: GetBuildDetailsInOrg()
    SVC->>BT: UpdateQueryTime()
    alt 构建已完成/失败
        SVC->>JK: GetBuildArtifactDockerImage() (仅SUCCESS)
        BT->>DB: UpdateBuild (async)
        BT->>BT: RemoveTask
    end
    SVC-->>FE: Build Details
    
    Note over FE,BT: 3. 前端等待轮询
    FE->>FE: 计算 waitTime = estimatedDuration - elapsed - 20s
    FE->>FE: JenkinsBuildStatusCard显示倒计时
    
    Note over FE,BT: 4. 开始轮询
    loop 每3秒 (直到超时或完成)
        FE->>FE: 检查超时 (elapsed > estimated + 30s?)
        alt 超时
            FE->>FE: 停止轮询
        else 未超时
            FE->>BE: GET /builds/details
            BE->>SVC: GetBuildDetails()
            alt 构建完成/失败
                SVC->>DB: Update (async)
                SVC->>BT: Remove from tracker
                SVC-->>FE: result != ""
                FE->>FE: 停止轮询，更新UI
            else 仍在构建
                SVC-->>FE: is_building=true
                FE->>FE: 更新燃尽进度条
            end
        end
    end
    
    Note over FE,BT: 5. 后台超时检查
    BT->>BT: checkBuildTimeouts() (每10秒)
    alt 超时 (estimatedDuration + 20s)
        BT->>JK: GetBuildDetailsInOrg()
        BT->>DB: UpdateBuild
        BT->>BT: RemoveTask
    end
```

## 关键流程说明

### 1. 触发构建 (TriggerBuild)

1. 前端调用 `POST /build/trigger` 触发构建
2. 后端调用 Jenkins API 触发构建
3. 等待1秒后查询最新构建号
4. 将构建初始信息保存到 `jenkins_builds` 表 (is_building=true)
5. 启动 BuildTracker 追踪此构建任务

### 2. 构建详情查询 (GetBuildDetails)

1. 前端调用 `GET /builds/details` 获取构建详情
2. 后端优先从数据库获取已有信息(DCU相关)
3. 调用 Jenkins API 获取最新状态
4. **仅当构建成功时**才查询 ArtifactDockerImage（避免不必要的日志解析）
5. 通知 BuildTracker 更新查询时间
6. 如果构建已完成，异步更新数据库并从Tracker移除

### 3. 前端轮询策略

**等待时间算法**: 
```
waitTime = max(0, estimatedDuration - (currentTime - buildStartTime) - 20000ms)
```

- 考虑用户刷新页面的情况，使用已经过的时间计算剩余等待时间
- 提前20秒开始轮询，确保及时获取最终状态

**超时停止**:
```
if (currentTime - buildStartTime > estimatedDuration + 30000ms) {
    停止轮询
}
```

### 4. 后端超时保障

- BuildTracker 每10秒检查一次超时任务
- 超时时间 = estimatedDuration + 20秒
- 超时后主动查询Jenkins并更新数据库
- 确保即使前端未轮询，构建状态也能被正确记录

---

## JenkinsBuildStatusCard 组件

### 功能说明

位于 `BuildDetails.vue` 中，产物信息卡片和DCU状态卡片之间，用于展示Jenkins构建进度。

### 显示状态

| 状态 | 说明 |
|------|------|
| 等待查询 | 构建刚启动，显示轮询倒计时 |
| 构建中 | 显示燃尽进度条和实时duration |
| 超时运行中 | 构建时间已超过预估 |
| 成功/失败 | 构建完成，显示最终状态 |

### 燃尽进度条算法

```mermaid
flowchart TD
    A[开始] --> B{duration >= estimatedDuration?}
    B -->|No| C{duration >= estimatedDuration - 20s?}
    B -->|Yes| D{duration >= estimatedDuration + 20s?}
    
    C -->|No| E[绿色进度条 = 0%<br/>显示'等待中...']
    C -->|Yes| F[绿色燃尽<br/>显示'预计完成 Xs']
    
    D -->|No| G[红色增长<br/>显示'已超时 Xs']
    D -->|Yes| H[红色 100%<br/>停止增长]
```

**进度条计算公式:**

1. **等待阶段** (`duration < estimated - 20s`):
   - 颜色: 绿色
   - 进度: 0%
   - 文本: "等待中..."

2. **燃尽阶段** (`estimated - 20s <= duration < estimated`):
   - 颜色: 绿色
   - 进度: `100 - (estimated - duration) / 20s * 100`
   - 文本: "预计完成 Xs"

3. **超时阶段** (`estimated <= duration < estimated + 20s`):
   - 颜色: 红色
   - 进度: `(duration - estimated) / 20s * 100`
   - 文本: "已超时 Xs"

4. **停止阶段** (`duration >= estimated + 20s`):
   - 颜色: 红色
   - 进度: 100%
   - 持续更新duration显示

### Duration 实时计算

> **注意**: Jenkins在构建进行中时返回 `duration: 0`，只有构建完成后才返回真实duration。

**解决方案**: 在组件中实时计算:
```typescript
realTimeDuration = Date.now() - new Date(build.timestamp).getTime()
```

使用 `setInterval` 每秒更新 `now` 值，驱动 `realTimeDuration` 计算属性更新。

---

## 相关文件

| 文件 | 作用 |
|------|------|
| `build_tracker.go` | 后端构建状态追踪，超时检测 |
| `jenkins_service.go` | GetBuildDetails，异步DB更新 |
| `UserDashboard.vue` | 用户端轮询逻辑 |
| `ProjectsManagement.vue` | 管理端轮询逻辑 |
| `BuildDetails.vue` | 构建详情页，集成状态卡片 |
| `JenkinsBuildStatusCard.vue` | 构建状态展示组件 |