# Deploy Ease Platform

Deploy Ease Platform 是一个基于Spring Boot 3.x和Flowable 7.x的现代化部署管理平台，提供工作流驱动的自动化部署解决方案。

## 技术栈

### 后端
- **Java 21** + **Spring Boot 3.2.0**
- **Spring Security 6.2.0** + JWT认证
- **Spring Data JPA** + Hibernate
- **Flowable 7.2.0** - 工作流引擎
- **MySQL 8.0+** + Flyway数据库版本控制
- **MapStruct 1.5.5** - 对象映射
- **QueryDSL 5.0.0** - 类型安全查询
- **OpenAPI/Swagger** - API文档
- **Lombok** - 代码简化
- **Hutool** - 工具类库

### 构建工具
- **Maven 3.8+**

## 核心功能模块

### ✅ 1. 系统管理（已完成）

#### 1.1 用户管理
- [x] 用户注册和登录
- [x] JWT Token认证
- [x] 密码重置
- [x] 用户信息维护
- [x] 用户状态管理（启用/禁用）
- [x] 部门分配
- [x] 基础CRUD操作（分页查询、创建、更新、删除）

**主要接口：**
```
POST   /api/v1/user/login           - 用户登录
GET    /api/v1/user/current         - 获取当前用户信息
POST   /api/v1/user/{id}/reset-password  - 重置密码
PUT    /api/v1/user/{id}/department - 分配部门
```

#### 1.2 角色管理
- [x] 角色创建与维护
- [x] 角色标签管理
- [x] 角色权限分配
- [x] 用户角色分配
- [x] 角色权限查询

**主要接口：**
```
POST   /api/v1/role                 - 创建角色
POST   /api/v1/role/{id}/tags       - 分配标签
POST   /api/v1/role/{userId}/assignRoles  - 分配角色
GET    /api/v1/role/{id}/permissions      - 获取角色权限
POST   /api/v1/role/{id}/permissions      - 分配权限
```

#### 1.3 权限管理
- [x] 权限创建与维护
- [x] 权限分类管理（菜单权限、按钮权限）
- [x] 权限与菜单关联
- [x] 基于权限的访问控制

#### 1.4 菜单管理
- [x] 菜单树维护
- [x] 菜单排序
- [x] 菜单显示控制
- [x] 动态菜单加载
- [x] 菜单权限配置
- [x] 权限树查询

**主要接口：**
```
GET    /api/v1/menu/current         - 获取当前用户菜单
GET    /api/v1/menu/tree            - 获取菜单树
GET    /api/v1/menu/permission-tree - 获取权限树
```

#### 1.5 部门管理
- [x] 部门树形结构维护
- [x] 部门编码管理
- [x] 部门负责人设置
- [x] 部门人员管理
- [x] 部门排序

#### 1.6 租户管理
- [x] 多租户支持
- [x] 租户信息管理
- [x] 租户状态控制

**实体统计：** 9个核心实体
- User（用户）
- Role（角色）
- RoleTag（角色标签）
- Permission（权限）
- PermissionTemplate（权限模板）
- Menu（菜单）
- Department（部门）
- Tenant（租户）
- SysParam（系统参数）

---

### ✅ 2. 外部系统集成（已完成）

#### 2.1 外部系统管理
- [x] 外部系统统一管理（Jenkins、Git等）
- [x] 多种认证方式支持
  - 用户名密码认证
  - Token认证
  - SSH密钥认证
- [x] 连接测试
- [x] 同步状态追踪

**主要接口：**
```
POST   /api/v1/external-system       - 创建外部系统
GET    /api/v1/external-system/{id}/test-connection - 测试连接
POST   /api/v1/external-system/{id}/sync - 同步数据
GET    /api/v1/external-system/{id}/status - 获取同步状态
```

#### 2.2 Jenkins集成
- [x] Jenkins实例管理
- [x] 视图(View)同步
- [x] 任务(Job)同步
- [x] 构建(Build)信息同步
- [x] 构建历史记录
- [x] 同步历史追踪

**主要接口：**
```
POST   /api/v1/jenkins-manager/{externalSystemId}/sync-all    - 同步所有数据
POST   /api/v1/jenkins-manager/{externalSystemId}/sync-views  - 同步视图
POST   /api/v1/jenkins-manager/{externalSystemId}/sync-jobs   - 同步任务
POST   /api/v1/jenkins-manager/{externalSystemId}/sync-builds - 同步构建
GET    /api/v1/jenkins-manager/{externalSystemId}/instance    - 获取实例信息
```

**相关实体：**
- JenkinsView（Jenkins视图）
- JenkinsJob（Jenkins任务）
- JenkinsBuild（Jenkins构建）
- JenkinsSyncHistory（同步历史）

#### 2.3 Git仓库集成
- [x] Git仓库组(Group)管理
- [x] Git项目(Project)管理
- [x] Git分支(Branch)管理
- [x] 多级同步（组 → 项目 → 分支）
- [x] 同步历史记录

**主要接口：**
```
POST   /api/v1/repository-manager/{externalSystemId}/sync-groups    - 同步仓库组
POST   /api/v1/repository-manager/{externalSystemId}/groups/sync-projects  - 同步项目
POST   /api/v1/repository-manager/{externalSystemId}/projects/sync-branches - 同步分支
GET    /api/v1/repository-manager/{externalSystemId}/instance       - 获取实例信息
```

**相关实体：**
- RepositoryGroup（仓库组）
- RepositoryProject（仓库项目）
- RepositoryBranch（仓库分支）
- RepositorySyncHistory（同步历史）

---

### ✅ 3. 部署管理（已完成）

#### 3.1 应用管理
- [x] 应用创建与维护
- [x] 应用编码管理
- [x] 开发语言类型支持（Java、Python、Node.js等）
- [x] 应用与仓库关联
- [x] 应用分组管理

**主要接口：**
```
POST   /api/v1/applications          - 创建应用
GET    /api/v1/applications/development-languages - 获取开发语言列表
```

**相关实体：**
- Application（应用）
- ProjectGroup（项目组）

#### 3.2 环境管理
- [x] 环境配置管理（开发、测试、生产等）
- [x] 环境编码管理
- [x] 构建类型配置（Jenkins、GitLab Runner、GitHub Action）
- [x] 部署方式配置（K8S、Docker、VM）
- [x] 项目组与环境关联

**相关实体：**
- Environment（环境）

#### 3.3 部署配置
- [x] 应用部署配置管理
- [x] 构建配置Schema定义
- [x] 部署操作
- [x] 部署日志记录

**主要接口：**
```
POST   /api/v1/deploy-app-config     - 创建部署配置
GET    /api/v1/deploy-app-config/defined  - 获取构建类型Schema
POST   /api/v1/deploy-app-config/deploy   - 执行部署
```

**相关实体：**
- DeployAppConfig（部署配置）
- DeployLog（部署日志）

---

### ✅ 4. 工作流引擎（已完成，基于Flowable）

#### 4.1 工作流定义
- [x] 工作流设计和保存
- [x] 工作流发布管理
- [x] 工作流启用/禁用
- [x] 工作流状态管理（草稿、已发布、已禁用）
- [x] 图形化配置（GraphJSON）
- [x] BPMN XML自动生成
- [x] 工作流分类管理

**主要接口：**
```
POST   /api/v1/workflow/definition/design            - 保存工作流设计
GET    /api/v1/workflow/definition/published         - 查询已发布工作流
POST   /api/v1/workflow/definition/{id}/published    - 发布工作流
POST   /api/v1/workflow/definition/{id}/disable      - 禁用工作流
POST   /api/v1/workflow/definition/{id}/enable       - 启用工作流
GET    /api/v1/workflow/definition/categories        - 获取工作流分类
```

#### 4.2 工作流实例
- [x] 工作流实例启动
- [x] 工作流实例挂起
- [x] 工作流实例恢复
- [x] 工作流执行状态查询
- [x] 历史实例查询
- [x] 实例与模板关联查询

**主要接口：**
```
POST   /api/v1/workflow/instance/start               - 启动工作流
GET    /api/v1/workflow/instance/templates-with-instances - 查询模板及实例
GET    /api/v1/workflow/instance/historical-instances - 查询历史实例
POST   /api/v1/workflow/definition/{processInstanceId}/suspend - 挂起实例
POST   /api/v1/workflow/definition/{processInstanceId}/resume  - 恢复实例
```

#### 4.3 节点定义与执行
- [x] 节点类型管理
- [x] 节点配置Schema
- [x] 节点实例状态追踪
- [x] 节点重试机制
- [x] 节点跳过机制

**主要接口：**
```
POST   /api/v1/workflow/node-instance/{id}/retry     - 重试节点
POST   /api/v1/workflow/node-instance/{id}/skip      - 跳过节点
```

#### 4.4 节点类型实现（Delegate）
- [x] **ShellNodeDelegate** - Shell脚本执行
- [x] **DeployNodeDelegate** - 部署节点执行
- [x] **ApprovalNodeDelegate** - 审批节点
- [x] **NotificationNodeDelegate** - 通知节点
- [x] **BaseNodeDelegate** - 基础节点抽象

#### 4.5 工作流日志
- [x] 实时日志记录
- [x] 节点级日志
- [x] 日志查询

**相关实体：**
- WorkflowDefinition（工作流定义）
- WorkflowNodeDefinition（节点定义）
- WorkflowInstance（工作流实例）
- WorkflowNodeInstance（节点实例）
- WorkflowLog（工作流日志）

---

### ✅ 5. 基础框架（已完成）

#### 5.1 通用CRUD框架
- [x] BaseController - 统一REST控制器
- [x] BaseServiceImpl - 通用服务实现
- [x] IBaseRepository - 通用数据访问接口
- [x] BaseConverter - 对象转换抽象
- [x] 统一响应格式（Response<T>）
- [x] 统一分页格式（Page<T>）

**标准CRUD接口（所有Controller继承）：**
```
POST   /{resource}           - 创建
PUT    /{resource}/{id}      - 更新
DELETE /{resource}/{id}      - 删除
GET    /{resource}/{id}      - 查询详情
GET    /{resource}           - 查询列表
GET    /{resource}/page      - 分页查询
GET    /{resource}/list      - 条件查询
POST   /{resource}/batch     - 批量处理
GET    /{resource}/export    - 导出数据
```

#### 5.2 查询框架
- [x] 基于QueryDSL的类型安全查询
- [x] 动态查询条件构建
- [x] @QueryField注解支持
- [x] 多种查询类型（EQUAL、LIKE、BETWEEN、IN等）
- [x] 软删除查询支持

#### 5.3 安全框架
- [x] Spring Security集成
- [x] JWT Token认证
- [x] 权限拦截器
- [x] 自定义认证入口点
- [x] JWT过滤器

#### 5.4 审计框架
- [x] 审计注解（@Audited）
- [x] 自动记录创建人/创建时间
- [x] 自动记录更新人/更新时间
- [x] 乐观锁版本控制
- [x] 审计事件监听

#### 5.5 异常处理
- [x] 统一异常处理（GlobalExceptionHandler）
- [x] 业务异常（BusinessException）
- [x] 系统异常（SystemException）
- [x] 唯一约束异常（UniqueConstraintException）
- [x] 实体未找到异常（EntityNotFoundException）
- [x] 国际化错误消息

#### 5.6 数据库版本控制
- [x] Flyway集成
- [x] 表结构版本管理（V1.0.0__init_schema.sql）
- [x] 初始数据管理（V1.0.1__init_data.sql）
- [x] 28个数据库表

#### 5.7 其他框架功能
- [x] 国际化支持（i18n）
- [x] JSON序列化配置
- [x] 租户过滤器
- [x] 逻辑删除支持（@LogicDelete）
- [x] 依赖注入后处理器
- [x] Formily Schema生成（用于前端表单）

---

## 数据库表结构（28张表）

### 系统管理表（7张）
1. `sys_tenant` - 租户表
2. `sys_department` - 部门表
3. `sys_user` - 用户表
4. `sys_param` - 系统参数表
5. `sys_role` - 角色表
6. `sys_role_tag` - 角色标签表
7. `sys_menu` - 菜单表

### 权限管理表（5张）
8. `sys_role_tag_relation` - 角色标签关系表
9. `sys_user_role` - 用户角色关系表
10. `sys_role_menu` - 角色菜单关系表
11. `sys_permission_template` - 权限模板表
12. `sys_template_menu` - 模板菜单关系表
13. `sys_permission` - 权限表

### 外部系统表（1张）
14. `sys_external_system` - 外部系统表

### Git仓库表（3张）
15. `deploy_repo_group` - 仓库组表
16. `deploy_repo_project` - 仓库项目表
17. `deploy_repo_branch` - 仓库分支表

### Jenkins表（4张）
18. Jenkins相关表（通过代码推断，未在SQL中完整展示）

### 工作流表（5张）
19. `workflow_definition` - 工作流定义表
20. `workflow_node_definition` - 节点定义表
21. `workflow_instance` - 工作流实例表
22. `workflow_node_instance` - 节点实例表
23. `workflow_log` - 工作流日志表

### 部署管理表（6张）
24. `deploy_project_group` - 项目组表
25. `deploy_application` - 应用表
26. `deploy_environment` - 环境表
27. `deploy_project_group_environment` - 项目组环境关系表
28. `deploy_log` - 部署日志表
29. `deploy_app_config` - 应用部署配置表

---

## API接口统计

### Controller统计（26个）
**系统管理（7个）：**
- UserApiController
- RoleApiController
- RoleTagApiController
- PermissionApiController
- MenuApiController
- DepartmentApiController
- TenantApiController

**部署管理（8个）：**
- ApplicationApiController
- ProjectGroupApiController
- EnvironmentApiController
- DeployAppConfigApiController
- DeployLogApiController
- ExternalSystemApiController
- RepositoryManagerApiController
- RepositoryProjectApiController
- RepositoryGroupApiController
- RepositoryBranchApiController

**Jenkins管理（5个）：**
- JenkinsManagerApiController
- JenkinsViewApiController
- JenkinsJobApiController
- JenkinsBuildApiController
- JenkinsSyncHistoryApiController

**工作流管理（4个）：**
- WorkflowDefinitionApiController
- WorkflowNodeDefinitionApiController
- WorkflowInstanceApiController
- WorkflowNodeInstanceApiController

**接口方法统计：**
- 约49个自定义@Operation接口方法
- 每个Controller继承BaseController，获得9个标准CRUD方法
- **总计约280+个API接口**

---

## 🚧 待完善功能

### 1. 测试覆盖
- [ ] Service层单元测试
- [ ] Controller层集成测试
- [ ] Repository层数据访问测试
- [ ] 工作流引擎测试
- **当前测试覆盖率：约1%（仅1个测试类）**

### 2. 缓存机制
- [ ] Redis集成
- [ ] 工作流定义缓存
- [ ] 权限数据缓存
- [ ] 菜单数据缓存
- **当前状态：已引入Caffeine依赖，但未使用**

### 3. 监控和运维
- [ ] 健康检查端点完善
- [ ] 性能监控（APM）集成
- [ ] 日志聚合（ELK）
- [ ] 告警机制
- [ ] 链路追踪

### 4. 部署和DevOps
- [ ] Docker镜像构建
- [ ] Kubernetes部署配置
- [ ] CI/CD Pipeline
- [ ] 环境配置分离（dev/test/prod）
- **当前配置：application.yml包含硬编码数据库密码和JWT密钥**

### 5. 文档完善
- [ ] API文档完善（Swagger注释）
- [ ] 架构图和流程图
- [ ] 部署手册
- [ ] 运维手册
- [ ] 最佳实践指南

### 6. 代码质量
- [ ] 代码质量检查工具集成（Checkstyle、PMD、SonarQube）
- [ ] TODO注释处理（14处待处理）
- [ ] System.out.println清理（14处）
- [ ] 泛化异常处理优化（95处catch Exception）

### 7. 安全加固
- [ ] 敏感配置外部化
- [ ] JWT密钥加密存储
- [ ] 数据库连接加密
- [ ] API访问频率限制
- [ ] SQL注入防护验证
- [ ] XSS攻击防护

### 8. 性能优化
- [ ] 数据库索引优化
- [ ] N+1查询问题排查
- [ ] 连接池配置优化（当前仅10个）
- [ ] 大数据量分页优化
- [ ] 异步任务处理

---

## 快速开始

### 环境要求
- JDK 21+
- Maven 3.8+
- MySQL 8.0+
- Node.js 16+（前端）

### 1. 数据库准备
```sql
CREATE DATABASE `deploy-ease-platform` 
  DEFAULT CHARACTER SET utf8mb4 
  COLLATE utf8mb4_unicode_ci;
```

### 2. 配置修改
编辑 `src/main/resources/application.yml`：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/deploy-ease-platform?...
    username: your_username
    password: your_password
    
jwt:
  secret: 'your_secret_key'  # 建议使用环境变量
```

⚠️ **安全提示：** 生产环境请使用环境变量或配置中心管理敏感信息！

### 3. 启动项目
```bash
# 编译项目
mvn clean package -DskipTests

# 启动服务
mvn spring-boot:run

# 或直接运行
java -jar target/deploy-cd-1.0-SNAPSHOT.jar
```

### 4. 访问服务
- **API文档：** http://localhost:8080/swagger-ui.html
- **健康检查：** http://localhost:8080/actuator/health

### 5. 默认用户（需通过初始化SQL配置）
```
用户名：admin
密码：（请查看V1.0.1__init_data.sql）
```

---

## 项目规范

### 代码规范
详见项目根目录下的规范文件：
- `.cursor/rules/project.mdc` - 完整开发规范
- `frontend.rules` - 前端开发规范

### 核心规范要点

#### 包结构
```
com.qqchen.deploy.backend
├── framework/          # 框架核心
│   ├── annotation/     # 注解定义
│   ├── controller/     # 基础控制器
│   ├── service/        # 基础服务
│   ├── repository/     # 基础仓库
│   └── ...
├── system/            # 系统模块
│   ├── api/           # REST接口
│   ├── entity/        # 实体类
│   ├── service/       # 业务服务
│   └── ...
├── deploy/            # 部署模块
└── workflow/          # 工作流模块
```

#### 命名规范
- **Entity：** 名词，如User、Role
- **DTO：** 实体名+DTO，如UserDTO
- **Service接口：** I+实体名+Service，如IUserService
- **Service实现：** 实体名+ServiceImpl，如UserServiceImpl
- **Controller：** 实体名+ApiController，如UserApiController
- **Repository：** I+实体名+Repository，如IUserRepository

#### 注解使用
- **@ServiceType(DATABASE)** - 数据库服务
- **@ServiceType(INTEGRATION)** - 集成服务（禁用数据库操作）
- **@LogicDelete** - 启用逻辑删除
- **@Audited** - 启用审计
- **@QueryField** - 查询字段映射

---

## 贡献指南

### 提交规范
```
feat: 新功能
fix: Bug修复
docs: 文档更新
style: 代码格式调整
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具变动
```

### 分支管理
- `master` - 生产环境分支
- `develop` - 开发分支
- `feature/*` - 功能分支
- `bugfix/*` - Bug修复分支
- `hotfix/*` - 热修复分支

---

## 许可证
MIT License

---

## 联系方式
项目维护者：Deploy Ease Team

---

## 更新日志

### v1.0.0（当前版本）
- ✅ 完成系统管理核心功能
- ✅ 完成Jenkins和Git集成
- ✅ 完成工作流引擎基础功能
- ✅ 完成部署管理框架
- ✅ 完成28张数据库表设计
- ✅ 完成280+个API接口
- ⚠️ 测试覆盖率待提升
- ⚠️ 缓存机制待实现
- ⚠️ 生产环境配置待优化

---

**注意事项：**
1. 本项目处于开发阶段，部分功能仍在完善中
2. 生产环境使用前请务必完成安全加固
3. 建议补充完整的单元测试和集成测试
4. 数据库配置和JWT密钥需要外部化管理
5. 建议集成专业的日志分析和监控方案