# 工作流引擎功能开发文档

## 已实现功能

### 1. 核心功能
- [x] 工作流定义管理
  - 工作流定义的CRUD操作
  - 工作流状态管理（草稿、发布、禁用）
  - 工作流版本控制

- [x] 工作流实例管理
  - 工作流实例的创建和执行
  - 实例状态管理（运行、暂停、完成、失败、取消）
  - 实例执行历史记录

- [x] 节点实例管理
  - 节点实例的创建和执行
  - 节点状态管理（等待、运行、完成、失败、取消）
  - 节点执行历史记录

### 2. 节点类型
- [x] Shell节点
  - 支持Windows/Unix跨平台
  - 工作目录配置
  - 环境变量支持
  - 超时处理
  - 输出流日志记录

### 3. 日志管理
- [x] 日志记录
  - 工作流级别日志
  - 节点级别日志
  - 系统级别日志
  - 变量更新日志

- [x] 日志查询
  - 工作流日志查询
  - 节点日志查询
  - 支持分页和条件过滤

## 待实现功能

### 1. 节点类型扩展
#### 1.1 Jenkins节点
```java
// 实现思路：
1. 添加Jenkins客户端依赖
```xml
<dependency>
    <groupId>com.offbytwo.jenkins</groupId>
    <artifactId>jenkins-client</artifactId>
    <version>0.3.8</version>
</dependency>
```

2. 实现Jenkins节点执行器
```java
@Component
public class JenkinsNodeExecutor extends AbstractNodeExecutor {
    @Override
    protected boolean doExecute(NodeInstance nodeInstance, WorkflowContext context, NodeConfig config) {
        JenkinsNodeConfig jenkinsConfig = (JenkinsNodeConfig) config;
        // 1. 连接Jenkins服务器
        // 2. 触发构建任务
        // 3. 等待构建完成
        // 4. 获取构建结果
        // 5. 处理构建产物
    }
}
```

3. 添加构建结果处理
- 支持构建状态判断
- 支持测试结果解析
- 支持构建产物下载
```

#### 1.2 Git节点
```java
// 实现思路：
1. 添加JGit依赖
```xml
<dependency>
    <groupId>org.eclipse.jgit</groupId>
    <artifactId>org.eclipse.jgit</artifactId>
    <version>6.5.0.202303070854-r</version>
</dependency>
```

2. 实现Git节点执行器
```java
@Component
public class GitNodeExecutor extends AbstractNodeExecutor {
    @Override
    protected boolean doExecute(NodeInstance nodeInstance, WorkflowContext context, NodeConfig config) {
        GitNodeConfig gitConfig = (GitNodeConfig) config;
        // 1. 克隆/拉取代码
        // 2. 切换分支/标签
        // 3. 执行Git操作
        // 4. 提交更改
        // 5. 推送远程
    }
}
```

3. 添加Git操作支持
- 分支管理
- 标签管理
- 代码合并
- 冲突处理
```

### 2. 日志管理增强

#### 2.1 日志导出功能
```java
// 实现思路：
1. 添加Excel导出依赖
```xml
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.3</version>
</dependency>
```

2. 实现日志导出服务
```java
@Service
public class WorkflowLogExportService {
    public void exportToExcel(Long workflowInstanceId, OutputStream output) {
        // 1. 查询日志数据
        // 2. 创建Excel工作簿
        // 3. 写入日志数据
        // 4. 格式化和样式设置
        // 5. 输出文件
    }
    
    public void exportToCsv(Long workflowInstanceId, Writer writer) {
        // 1. 查询日志数据
        // 2. 写入CSV头
        // 3. 写入日志数据
        // 4. 刷新输出
    }
}
```

3. 添加导出接口
```java
@RestController
@RequestMapping("/api/v1/workflow")
public class WorkflowLogController {
    @GetMapping("/{instanceId}/logs/export")
    public void exportLogs(@PathVariable Long instanceId,
                          @RequestParam String format,
                          HttpServletResponse response) {
        // 1. 设置响应头
        // 2. 获取输出流
        // 3. 调用导出服务
        // 4. 处理异常
    }
}
```

#### 2.2 日志清理功能
```java
// 实现思路：
1. 添加定时任务配置
```java
@Configuration
@EnableScheduling
public class WorkflowLogCleanupConfig {
    @Scheduled(cron = "${workflow.log.cleanup.cron}")
    public void cleanupLogs() {
        // 1. 获取清理策略
        // 2. 查询过期日志
        // 3. 批量删除日志
        // 4. 记录清理结果
    }
}
```

2. 实现日志清理服务
```java
@Service
public class WorkflowLogCleanupService {
    public void cleanupByTime(LocalDateTime before) {
        // 1. 分批查询日志
        // 2. 物理删除日志
        // 3. 记录清理统计
    }
    
    public void cleanupByInstance(Long workflowInstanceId) {
        // 1. 查询实例日志
        // 2. 物理删除日志
        // 3. 记录清理结果
    }
}
```

### 3. 工作流监控

#### 3.1 执行监控
```java
// 实现思路：
1. 添加监控指标收集
```java
@Component
public class WorkflowMetricsCollector {
    private final MeterRegistry registry;
    
    public void recordExecutionTime(String workflowName, long timeMs) {
        // 记录执行时长
    }
    
    public void recordNodeExecutionTime(String nodeName, long timeMs) {
        // 记录节点执行时长
    }
    
    public void incrementExecutionCounter(String workflowName, String status) {
        // 增加执行计数
    }
}
```

2. 实现监控数据存储
```java
@Entity
@Table(name = "wf_workflow_metrics")
public class WorkflowMetrics {
    // 执行时长
    private Long executionTime;
    // 成功率
    private Double successRate;
    // 失败次数
    private Integer failureCount;
    // 平均节点执行时长
    private Long avgNodeExecutionTime;
}
```

3. 添加监控接口
```java
@RestController
@RequestMapping("/api/v1/workflow/metrics")
public class WorkflowMetricsController {
    @GetMapping("/overview")
    public WorkflowMetricsOverview getOverview() {
        // 返回整体监控数据
    }
    
    @GetMapping("/{workflowId}")
    public WorkflowMetricsDetail getDetail(@PathVariable Long workflowId) {
        // 返回具体工作流监控数据
    }
}
```

#### 3.2 告警通知
```java
// 实现思路：
1. 定义告警规则
```java
@Entity
@Table(name = "wf_alert_rule")
public class AlertRule {
    // 告警类型
    private AlertType type;
    // 告警阈值
    private String threshold;
    // 告警级别
    private AlertLevel level;
    // 通知方式
    private List<NotifyChannel> channels;
}
```

2. 实现告警服务
```java
@Service
public class WorkflowAlertService {
    public void checkAndAlert(WorkflowInstance instance) {
        // 1. 获取告警规则
        // 2. 检查是否触发
        // 3. 生成告警信息
        // 4. 发送通知
    }
    
    public void sendAlert(Alert alert) {
        // 1. 获取通知渠道
        // 2. 发送通知
        // 3. 记录通知结果
    }
}
```

### 4. 工作流调度

#### 4.1 定时调度
```java
// 实现思路：
1. 添加调度配置
```java
@Entity
@Table(name = "wf_workflow_schedule")
public class WorkflowSchedule {
    // 调度类型
    private ScheduleType type;
    // Cron表达式
    private String cronExpression;
    // 生效时间
    private LocalDateTime effectiveTime;
    // 失效时间
    private LocalDateTime expireTime;
}
```

2. 实现调度服务
```java
@Service
public class WorkflowScheduleService {
    public void schedule(WorkflowSchedule schedule) {
        // 1. 验证调度配置
        // 2. 创建调度任务
        // 3. 注册到调度器
        // 4. 记录调度状态
    }
    
    public void executeScheduledWorkflow(Long scheduleId) {
        // 1. 获取调度配置
        // 2. 创建工作流实例
        // 3. 执行工作流
        // 4. 记录执行结果
    }
}
```

#### 4.2 依赖调度
```java
// 实现思路：
1. 添加依赖配置
```java
@Entity
@Table(name = "wf_workflow_dependency")
public class WorkflowDependency {
    // 上游工作流
    private Long upstreamWorkflowId;
    // 依赖类型
    private DependencyType type;
    // 触发条件
    private String condition;
}
```

2. 实现依赖服务
```java
@Service
public class WorkflowDependencyService {
    public void handleWorkflowComplete(Long workflowInstanceId) {
        // 1. 查询依赖配置
        // 2. 检查触发条件
        // 3. 触发下游工作流
        // 4. 记录依赖执行
    }
}
```

### 5. 工作流权限管理

#### 5.1 权限模型
```java
// 实现思路：
1. 定义权限模型
```java
@Entity
@Table(name = "wf_permission")
public class WorkflowPermission {
    // 权限类型
    private PermissionType type;
    // 权限范围
    private PermissionScope scope;
    // 权限值
    private String value;
}
```

2. 实现权限服务
```java
@Service
public class WorkflowPermissionService {
    public boolean hasPermission(Long userId, Long workflowId, PermissionType type) {
        // 1. 查询用户权限
        // 2. 检查继承权限
        // 3. 验证权限范围
        // 4. 返回结果
    }
    
    public void grantPermission(PermissionGrant grant) {
        // 1. 验证授权者权限
        // 2. 创建权限记录
        // 3. 记录授权日志
    }
}
```

### 6. 工作流版本管理

#### 6.1 版本控制
```java
// 实现思路：
1. 添加版本模型
```java
@Entity
@Table(name = "wf_workflow_version")
public class WorkflowVersion {
    // 版本号
    private String version;
    // 变更内容
    private String changelog;
    // 工作流定义
    private String definition;
}
```

2. 实现版本服务
```java
@Service
public class WorkflowVersionService {
    public void createVersion(Long workflowId) {
        // 1. 生成版本号
        // 2. 保存当前定义
        // 3. 记录变更日志
    }
    
    public void rollback(Long workflowId, String version) {
        // 1. 验证版本有效性
        // 2. 恢复历史版本
        // 3. 记录回滚操作
    }
}
```

### 7. 工作流测试

#### 7.1 模拟执行
```java
// 实现思路：
1. 实现测试环境
```java
@Component
public class WorkflowTestEnvironment {
    public WorkflowContext createTestContext() {
        // 1. 创建测试上下文
        // 2. 初始化测试数据
        // 3. 配置测试参数
    }
}
```

2. 实现测试服务
```java
@Service
public class WorkflowTestService {
    public TestResult simulateExecution(Long workflowId) {
        // 1. 准备测试环境
        // 2. 执行工作流
        // 3. 收集测试结果
        // 4. 生成测试报告
    }
}
```

### 8. 工作流模板

#### 8.1 模板管理
```java
// 实现思路：
1. 添加模板模型
```java
@Entity
@Table(name = "wf_workflow_template")
public class WorkflowTemplate {
    // 模板名称
    private String name;
    // 模板描述
    private String description;
    // 模板定义
    private String definition;
    // 参数定义
    private List<TemplateParameter> parameters;
}
```

2. 实现模板服务
```java
@Service
public class WorkflowTemplateService {
    public Long createFromTemplate(Long templateId, Map<String, Object> parameters) {
        // 1. 加载模板定义
        // 2. 替换模板参数
        // 3. 创建工作流定义
        // 4. 返回工作流ID
    }
    
    public void saveAsTemplate(Long workflowId) {
        // 1. 提取工作流定义
        // 2. 提取参数定义
        // 3. 保存为模板
    }
}
```

## 下一步开发计划

1. 优先实现日志管理增强功能
   - 日志导出功能
   - 日志清理功能
   - 日志查询性能优化

2. 实现工作流监控功能
   - 执行监控
   - 告警通知
   - 监控大屏

3. 实现剩余节点类型
   - Jenkins节点
   - Git节点
   - HTTP节点
   - 通知节点

4. 实现工作流调度功能
   - 定时调度
   - 依赖调度
   - 调度监控

## 技术栈

- 后端框架：Spring Boot 3.x
- 数据库：MySQL 8.x
- ORM框架：Spring Data JPA
- 任务调度：Quartz
- 监控：Micrometer + Prometheus
- 日志：Logback
- 工具库：
  - Apache Commons
  - Guava
  - MapStruct
  - Jackson